Appendix A.1 Organization and contents of the SQL Communications Area

The organization and contents of the area that receives SQL execution information are explained as follows.

Organization of this subsection
(1) Organization of the SQL Communications Area
(2) Contents of the SQL Communications Area

(1) Organization of the SQL Communications Area

Figure A-1 shows how the SQL Communications Area is organized.

Figure A-1 Configuration of SQL Communications Area

[Figure]

Note
  1. Numbers in parentheses indicate length (in bytes).
  2. Brackets [ ] in parentheses enclose a value for 64-bit mode. For 64-bit mode Windows, SQLCA is 336 bytes.
  3. In 64-bit mode, the length of SQLCABC, SQLCODE, and SQLERRD becomes the size of the long type for each platform.

(2) Contents of the SQL Communications Area

Table A-1 shows the contents of the SQL Communications Area.

Table A-1 Contents of the SQL Communications Area

Level number1Communications area nameData typeLength (bytes)Description
1SQLCA[Figure]336 [368]Denotes the overall SQL Communications Area.
2SQLCAID[Figure]8Denotes the SQLCAIDC, SQLCAIDS, and SQLCAIDE areas.
3SQLCAIDCchar5Contains a character string (SQLCA) indicating that the area is the SQL Communications Area.
3SQLCAIDSchar2Used by HiRDB.
3SQLCAIDEchar1Used by HiRDB.2
2SQLCABClong4 [8]6Sets the size (336 [368] bytes) of the SQL Communications Area.
2SQLCODElong4 [8]6Receives one of the following return codes from HiRDB after SQL statements have been executed:
Negative: Abnormal termination
0: Normal termination
Positive: Normal termination with a message
For details about the messages associated with return codes, see the manual HiRDB Version 8 Messages. Return codes associated with messages are retrieved as follows:
Return code Associated message ID
-yyy KFPA11yyy
-1yyy KFPA19yyy
-3yyy KFPA18yyy
yyy KFPA12yyy
3yyy KFPA13yyy
Examples:
Return code Message ID
-125 KFPA11125
-1200 KFPA19200
-3200 KFPA18200
100 KFPA12100
3010 KFPA13010
2SQLERRM[Figure]256Denotes the SQLERRML and SQLERRMC areas.
The contents of these areas vary depending on whether the return code returned to the SQLCODE area is positive or negative:
  • If the return code is negative, a character string indicating the location or the cause of the error can be returned
  • If the return code is positive, a character string indicating message information can be returned.
3SQLERRMLshort2Contains the length of the message returned to the SQLERRMC area.
3SQLERRMCchar254Contains the message associated with the return code returned to the SQLCODE area; for the contents of this area, see the manual HiRDB Version 8 Messages.
2SQLERRPchar8Used by HiRDB.
2SQLERRDlong4[Figure]6
[8[Figure]6]6
Contains the internal status of HiRDB. This area is an array of six areas of the long data type:
SQLERRD[0]: Not used
SQLERRD[1]: Not used
SQLERRD[2]: One of the following values.3
  • Number of rows retrieved by the SELECT statement
  • Number of rows updated by the UPDATE statement
  • Number of rows deleted by the DELETE statement
  • Number of rows inserted by the INSERT statement
  • Number of rows fetched by the FETCH statement
  • Number of rows created by the ASSIGN LIST statement
SQLERRD[3]: Not used
SQLERRD[4]: Not used
SQLERRD[5]: Not used
2SQLWARN0char1W is set in this area when a warning flag (W) is set in any of the areas SQLWARN1-SQLWARNF.
2SQLWARN1char1W is set in this area if an embedded variable for receiving data during character data retrieval was shorter than the data, and the truncated value was received.
W is also set if the embedded variable for receiving data during repetition retrieval had a smaller element count than the data and values of the discarded elements that were received; otherwise, this area is blank.
2SQLWARN2char1W is set in this area if the null value was ignored in set function processing; otherwise, this area is blank.
However, in either of the following cases, a blank may be set in this area even if the null value was ignored during set function processing:
  • When a table that defines an index that recognizes a null value as an exception value is retrieved.
  • When the rapid grouping facility is used.
This area is not used in remote database access.
2SQLWARN3char1W is set in this area if the number of columns containing the results of a retrieval did not match the number of embedded variables that received the results of the retrieval; otherwise, this area is blank4.
2SQLWARN4char1W is set in this area if an UPDATE or DELETE statement without a WHERE clause was executed; otherwise, this area is blank. This area is not used in remote database access.
2SQLWARN5char1Spare
2SQLWARN6char1W is set in this area if the transaction was cancelled implicitly; otherwise, this area is blank.
2SQLWARN7char1W is set in this area if a repetition column with subscripts is specified in the SET or DELETE clause of the UPDATE statement, and the update is ignored because there are no elements in the row to be updated; otherwise, this area is blank. This area is not used in remote database access.
2SQLWARN8char1Spare
2SQLWARN9char1Spare
2SQLWARNA5char1W is set in this area if an invalid date occurred as a result of a date operation and HiRDB modified the date automatically to the last day of the affected month; otherwise, this area is blank. This area is not used in remote database access.
2SQLWARNB5char1W is set in this area if either an overflow error or division by zero error occurred in a computation during SQL statements execution and the result of the computation was set as a null value. Otherwise, this area is blank. This area is not used in remote database access.
2SQLWARNC5char1W is set in this area when the value for a day in a date interval is more than two digits after a date operation has been completed; otherwise, this area is blank. This area is not used in remote database access.
2SQLWARNDchar1W is set in this area when a warning that occurs in a foreign server cannot be classified into other types of SQLWARN.
2SQLWARNEchar1Spare
2SQLWARNFchar1Spare
2SQLCASYSchar16Used by HiRDB.
[Figure]: Not Applicable.
Note
Value in brackets [ ] indicates the length for 64-bit mode. For 64-bite mode Windows, SQLCA is 336 bytes.
1 Level numbers indicate the set inclusion relationships of the SQL Communications Area. The level 1 Communications Area is composed of level 2 Communications Areas.
2 This area stores the type of database management system at the server with which remote database access was performed. The following values can be set in the SQLCAIDE area:
ValueServer's database management systemRemote database access protocol
KSQL/KOSI-RDA
OORACLEOSI-RDA
PHiRDBOSI-RDA
RXDM/RDOSI-RDA
1RDB1 E2OSI-RDA
(Blank)Local accessNot applicable
OtherOne of the following:
  • A database management system other than the above
  • Not connected to a server system (database management system not applicable)
OSI-RDA
3 For remote database access, information depends on the distributed server as follows:
Returned valueDBMS at server
HiRDB and XDM/RDOther than HiRDB or XDM/RD
Number of rows fetched by the SELECT statementThese values are set.These values are set when a rows count is returned from the server DBMS; otherwise, 0 is set.
Number of rows updated by the UPDATE statement
Number of rows deleted by the DELETE statement
Number of rows inserted by the INSERT statement
Number of rows fetched by the FETCH statementThese values are set.
Number of rows created by the ASSIGN LIST statementThese values are not usable.These values are not usable.
4 If the server is either HiRDB or XDM/RD, a remote database access operation results in an SQL error.
5 The first FETCH statement returns W when an SQL statement containing sort processing or an SQL statement containing the EXISTS predicate is executed.
In the HiRDB/Parallel Server environment, the row that returns W cannot be determined if a warning is generated at the WHERE clause.
6 In 64-bit mode, the length is the size of the long type for each platform.