Appendix B.1 Organization and contents of the SQL Descriptor Area

This appendix explains the organization and contents of the areas that are described in the information on I/O variables, determined dynamically at the time of UAP execution.

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

(1) Organization of the SQL Descriptor Area

Figure B-1 shows how the SQL Descriptor Area is organized.

Figure B-1 Organization of the SQL Descriptor Area

[Figure]

Notes

  1. Numbers in parentheses indicate length (in bytes).
  2. n indicates the number of SQLVARs specified in SQLN.
  3. Square brackets ([ ]) enclose the length for 64-bit mode. For 64-bit mode Windows, SQLDA is 16 + 24n bytes.
  4. In 64-bit mode, the length of SQLDABC is the size of the long type for each platform.
* If BLOB- or BINARY-type data is used, the area name is SQLVAR_LOB, which consists of SQLDIM(1), SQLCOD(1), SQLXDIM(2), SQLLOBLEN(4), SQLDATA(4 [8]), and SQLLOBIND(4 [8]).
Define the SQLVAR_LOB area in the SQLVAR area, and use it by overwriting the SQLVAR area during the input/output of BLOB-type data. For the contents of SQLVAR_LOB, see Table B-3 Contents of SQLVAR_LOB.

(2) Contents of the SQL Descriptor Area

Table B-1 shows the contents of the SQL Descriptor Area; for details about SQL data, see Table B-2 Data codes and data lengths set in the SQL Descriptor Area.

Table B-1 Contents of the SQL Descriptor Area

Level number1Data Area nameData typeLength (bytes)Source of valueDescription
1SQLDA[Figure]16+16n
[24+24n]
[Figure]Denotes the overall SQL Descriptor Area.
2SQLDAIDchar8HiRDBContains the SQLDA ID (SQLDA[Figure][Figure][Figure]), indicating the SQLDA. This parameter is set when the DESCRIBE or DESCRIBE TYPE statement is issued.
2SQLDABClong4 [8]6HiRDBContains the length of SQLDA. This parameter is set when the DESCRIBE or DESCRIBE TYPE statement is issued.
2SQLN2short2UAPWhen an SQLDA area is allocated or SQLDA is used, this parameter specifies the number of SQLVARs (1 to 4000) for the allocated SQLDA area.
HiRDBBinary 0 is set in this area if there is not enough SQLDA area (SQLN < SQLD) when the DESCRIBE or DESCRIBE TYPE statement is issued.
2SQLDshort2UAPWhen the OPEN or EXECUTE statement is issued, specifies the number of input ? parameters in SQLD of the SQL Descriptor Area that is specified in the USING clause.
When the EXECUTE statement is issued, specifies the number of output ? parameters in SQLDA of the SQL Descriptor Area that is specified in the INTO clause.
When the FETCH statement is issued, specifies the number of retrieval items (1-4000).
HiRDBBinary 0, the number of retrieval items, or the number of output ? parameters is set when the DESCRIBE [OUTPUT] statement is issued:
0:
The SQL statement that was preprocessed was a statement other than the SELECT statement and was not a CALL statement containing an output ? parameter
Number of retrieval items:
The SQL statement that was preprocessed was the SELECT statement
Number of output ? parameters:
The SQL statement that was preprocessed was the CALL statement
The number of input ? parameters is set when the DESCRIBE INPUT statement is issued.
The total number of user-defined type configuration elements that the system tried to receive and high-order user-defined type configuration elements being inherited is set when the DESCRIBE TYPE statement is issued. However, if the number of configuration elements exceeds 30,000, 30001 is set.
2SQLVAR[Figure]16n
[24n]
[Figure]Area composed of the SQLDIM, SQLCOD, SQLXDIM, SQLLEN, SQLSYS, SQLDATA, and SQLIND areas. This set of areas should be defined at least as many times as the value specified in the SQLN area.
3SQLDIMunsigned char1[Figure]Not used.
3SQLCODunsigned char1UAPA data code3 is specified in this area when an EXECUTE, OPEN, or FETCH statement is issued.
HiRDBA data code3 is set in this area after a DESCRIBE or DESCRIBE TYPE statement is issued.
3SQLXDIMshort2UAPOne of the following values is specified, depending on the structure type of the area for the variable specified by SQLDA when the EXECUTE, OPEN, or FETCH statement is issued.
Simple structure: 1
Repetition structure: 2 to 30000 (integer indicating maximum number of elements in the area)
For details about data area structures, see E. SQL Data Types and Data Descriptions.
HiRDBOne of the following values is set depending on the structure type of the retrieval item or ? parameter when the DESCRIBE or DESCRIBE TYPE statement is issued.
Simple structure: 1
Repetition structure: 2 to 30000 (integer indicating maximum number of members in the area)
3SQLLEN3, 4short2UAPA data length3 is set in this area when an EXECUTE, OPEN, or FETCH statement is issued.
HiRDBA data length3 is set in this area after a DESCRIBE or DESCRIBE TYPE statement is issued.
3SQLSYSshort2UAPThe following value is specified when the EXECUTE, OPEN, or FETCH statement is issued:
  • Length of the area for one element that includes a gap when a variable-length character string type (VARCHAR, NVARCHAR, MVARCHAR) of a repetition structure or array structure is specified.
  • 0 for all other cases
HiRDB0 is set when the DESCRIBE or DESCRIBE TYPE statement is issued.
3SQLDATA5unsigned char4 [8]UAPSpecifies the address of the data area that stores the value of the ? parameter when either an EXECUTE or an OPEN statement is issued.5
When a FETCH statement is issued, this area specifies the address of the data area that receives the data.
3SQLIND5short4 [8]UAPSpecifies the address of the area for receiving the value of the indicator variable only if a data code with an indicator variable is set in SQLCODE when an EXECUTE, OPEN, or FETCH statement is issued. The area for receiving the value of the indicator variable is 2 bytes. For details about indicator variable specification, see Table B-2 Data codes and data lengths set in the SQL Descriptor Area.
Legend:
[Figure]: One blank.
[Figure]: Not applicable.
Note
Square brackets ([ ]) enclose the length for 64-bit mode. For 64-bit mode Windows, SQLCA is 16 + 24n bytes.
1 Level numbers indicate the set inclusion relationships of the SQL Descriptor Area. For example, the level 1 data area is composed of level 2 data areas.
2 The number of SQLVARs set by a UAP in the SQLN area should be either the number of ? parameters set in the SQLD area or a value greater than the number of retrieval items. If the number of SQLVARs is less than the number of ? parameters or less than the number of retrieval items, HiRDB posts this fact by returning binary 0 to the SQLN area.
3 For details about the data codes and data lengths, see Table B-2 Data codes and data lengths set in the SQL Descriptor Area.
4 For a packed decimal number (DECIMAL, INTERVAL YEAR TO DAY, or INTERVAL HOUR TO SECOND), the SQLLEN area is composed of the following areas:
Data area nameData typeLength (bytes)Description
SQLPRCSNB1Precision (p)
SQLSCALEB1Decimal scaling position (s)
5 Because the SQLDATA and SQLIND areas are cleared when a DESCRIBE statement is executed, a value must be reset after the DESCRIBE statement has executed. For repetition columns, use the following structure to set a value:
[Figure]
6 In 64-bit mode, the length is the size of the long type for each platform.

Table B-2 Data codes and data lengths set in the SQL Descriptor Area

Decimal data codeHexadecimal data codeIndicator variableData typeData lengthUnit
000[Figure]Data type not available in HiRDB10Bytes
4830NoC VARCHAR(n)41 [Figure] n[Figure] 320002
4931Yes
6844NoROWRow length L in table to be operated on:
1 [Figure] L[Figure] 30,000
6945Yes
10064NoINTERVAL YEAR TO DAYPrecision 8
Decimal scaling factor 0
Digits
10165Yes
1106ENoINTERVAL HOUR TO SECONDPrecision 6
Decimal scaling factor 0
1116FYes
11270NoDATE4Bytes
11371Yes
12078NoTIME3
12179Yes
1247CNoTIMESTAMP[(p)]7 [Figure][Figure] p[Figure] 2 [Figure]
p = 0, 2, 4, or 6
1257DYes
13183[Figure]Abstract data type3[Figure][Figure]
14490NoBINARY(n)1 [Figure] n[Figure] 2147483647​2Bytes
14591Yes
14692NoBLOB[(n)]1 [Figure] n[Figure] 2147483647​
14793Yes
1549ANoBINARY locator4
1559BYes
1589ENoBLOB locator4
1599FYes
160A0NoMVARCHAR(n)1 [Figure] n[Figure] 320002
161A1Yes
164A4NoMCHAR[(n)]1 [Figure] n[Figure] 30000
165A5Yes
176B0NoNVARCHAR(n)1 [Figure] n[Figure] 160002Characters
177B1Yes
180B4NoNCHAR(n) or NATIONAL CHAR[ACTER](n)1 [Figure] n[Figure] 15,000
181B5Yes
192C0NoVARCHAR(n)1 [Figure] n[Figure] 32,0002Bytes
193C1Yes
196C4NoCHAR[ACTER](n)1 [Figure] n[Figure] 30,000
197C5Yes
224E0NoFLOAT or DOUBLE PRECISION8
225E1Yes
226E2NoSMALLFLT or REAL4
227E3Yes
228E4No[LARGE]DEC[IMAL]
[(p [, s])]
Precision p
Decimal scaling factor s
1 [Figure] p[Figure] 29, 0 [Figure] s[Figure] p
Digits
229E5Yes
234EANoDISPLAY SIGN LEADING SEPARATE5Precision p
Decimal scaling factor s
1 [Figure] p[Figure] 29, 0 [Figure] s[Figure] p
235EBYes
240F0NoINT[EGER]4Bytes
241F1Yes
244F4NoSMALLINT2
245F5Yes
Legend:
[Figure]: Not applicable.
Note
During a remote database access to a distributed server other than HiRDB, the DESCRIBE statement converts the data types for the distributed server to the corresponding HiRDB data types. For details about data type conversion by the DESCRIBE statement, see 11.4 Available data types.
1 When a DESCRIBE statement that accesses remotely a DBMS other than HiRDB is executed, and there is no HiRDB data type corresponding to the data type at the server, data code 0 is set. Remote database access cannot access the data in a column for which this data code is set. You cannot set data code 0 in a UAP for SQL statements other than the DESCRIBE statement. Also, the HiRDB dictionary table does not include data code 0. For details about the association between a distributed server and the data type when remote database access is performed using the distributed client facility, see 11.4 Available data types.

2 When a variable-length character string of 0 length is set in the UAP, 1 must be set in the SQLLEN area.

3 When the DESCRIBE statement is executed, a data type is returned from the server. The UAP can reference data types. Data type setup and data length setup and referencing are disabled.

4 This data type can be set in C.
5 This data type can be set in COBOL.

Table B-3 Contents of SQLVAR_LOB

Level number1Data Area nameData typeLength (bytes)Source of valueDescription
2SQLVAR_LOB[Figure]16n
[24n]
[Figure]Area that consists of SQLDIM, SQLCOD, SQLXDIM, SQLLOBLEN, SQLDATA, SQLDATA, and SQLLOBIND. Define this area in the SQLVAR area, and use it by overwriting the SQLVAR area during the input/out of BLOB- and BINARY-type data.
3SQLDIMunsigned char1[Figure]Not used.
3SQLCODunsigned char1UAPSpecifies a data code2 when the EXECUTE, OPEN, or FETCH statement is issued.
HiRDBContains a data code2 after the DESCRIBE or DESCRIBE TYPE statement has been issued.
3SQLXDIMshort2UAPSpecifies 1 when the EXECUTE, OPEN, or FETCH statement is issued. For details about the data area structures, see E. SQL Data Types and Data Descriptions.
HiRDBContains the value 1 after the DESCRIBE or DESCRIBE TYPE statement has been issued.
3SQLLOBLEN2long [int]4UAPSpecifies the data length2 when the EXECUTE, OPEN, or FETCH statement is issued.
HiRDBContains the data length2 after the DESCRIBE or DESCRIBE TYPE statement is issued.
3SQLDATA3unsigned char *4 [8]UAPWhen the EXECUTE or OPEN statement is issued, specifies the address of the data area in which a ? parameter value is stored.
When the FETCH statement is issued, specifies the address of the data area that receives the data.
3SQLLOBIND3long *
[int *]
4 [8]UAPSpecifies the address of the area for receiving the value of the indicator variable only if a data code with an indicator variable is set in SQLCODE when an EXECUTE, OPEN, or FETCH statement is issued. The area for receiving the value of the indicator variable is 4 bytes. For details about indicator variable specification, see Table B-2 Data codes and data lengths set in the SQL Descriptor Area.

[Figure]: Not applicable.

Note
The square brackets in the data type and length columns indicate the data type and length in the 64-bit mode.
1 Level numbers indicate the set inclusion relationships of the SQL Descriptor Area. For example, the level 2 data area is composed of the level 3 data areas.
2 For details on data length and data codes, see Table B-2 Data codes and data lengths set in the SQL Descriptor Area.
3 The SQLDATA and SQLLOBIND data areas are cleared when a DESCRIBE statement is executed. Therefore, if you use a DESCRIBE statement, reset the values for these data areas after executing the DESCRIBE statement. For the structure for setting a value in a repetition column, see footnote #5 in Table B-1 Contents of the SQL Descriptor Area.