Using SQL descriptor areas in REXX applications
There are two types of SQL descriptor areas. One is defined with the ALLOCATE DESCRIPTOR statement. The other is defined using the SQL descriptor area (SQLDA) structure. Only the SQLDA form is discussed here. Allocated descriptors are not supported in REXX.
The following statements can use an SQLDA:
- EXECUTE...USING DESCRIPTOR descriptor-name
- FETCH...USING DESCRIPTOR descriptor-name
- OPEN...USING DESCRIPTOR descriptor-name
- CALL...USING DESCRIPTOR descriptor-name
- DESCRIBE statement-name INTO descriptor-name
- DESCRIBE TABLE host-variable INTO descriptor-name
Unlike the SQLCA, more than one SQLDA can be in a procedure, and an SQLDA can have any valid name.
Each SQLDA consists of a set of REXX variables with a common stem, where the name of the stem is the descriptor-name from the appropriate SQL statements. This must be a simple stem; that is, the stem itself must not contain any periods. The SQL/REXX interface automatically provides the fields of the SQLDA for each unique descriptor name. An INCLUDE SQLDA statement is not required and is not allowed.
The SQL/REXX interface uses the SQLDA in a manner consistent with the typical SQL usage. However, the SQL/REXX interface maintains the fields of the SQLDA in separate variables rather than in a contiguous data area.
The following variables are returned to the application after a DESCRIBE, a DESCRIBE TABLE, or a PREPARE INTO statement:
- stem.n.SQLNAME
- The name of the nth column in the result table.
The following variables must be provided by the application before an EXECUTE...USING DESCRIPTOR, an OPEN...USING DESCRIPTOR, a CALL...USING DESCRIPTOR, or a FETCH...USING DESCRIPTOR statement. They are returned to the application after a DESCRIBE, a DESCRIBE TABLE, or a PREPARE INTO statement:
- stem.SQLD
- Number of variable elements that the SQLDA actually contains.
- stem.n.SQLTYPE
- An integer representing the data type of the nth element (for
example, the first element is in stem.1.SQLTYPE).
The following data types are not allowed:
- 400®/401
- NUL-terminated graphic string
- 404/405
- BLOB host variable
- 408/409
- CLOB host variable
- 412/413
- DBCLOB host variable
- 460/461
- NUL-terminated character string
- 476/477
- PASCAL L-string
- 496/497
- Large integer (where scale is greater than 0)
- 500/501
- Small integer (where scale is greater than 0)
- 504/505
- DISPLAY SIGN LEADING SEPARATE
- 904/905
- ROWID
- 908/909
- VARBINARY host variable
- 912/913
- BINARY host variable
- 916/917
- BLOB file reference variable
- 920/921
- CLOB file reference variable
- 924/925
- DBCLOB file reference variable
- 960/961
- BLOB locator
- 964/965
- CLOB locator
- 968/969
- DBCLOB locator
- 972
- Result set locator
- 988/989
- XML host variable
- 996/997
- Decimal floating point host variable
- 2452/2453
- XML locator
- stem.n.SQLLEN
- If SQLTYPE does not indicate a DECIMAL or NUMERIC data type, the maximum length of the data contained in stem.n.SQLDATA.
- stem.n.SQLLEN.SQLPRECISION
- If the data type is DECIMAL or NUMERIC, this contains the precision of the number.
- stem.n.SQLLEN.SQLSCALE
- If the type is DECIMAL or NUMERIC, this contains the scale of the number.
- stem.n.SQLCCSID
- The CCSID of the nth column of the data.
The following variables must be provided by the application before an EXECUTE...USING DESCRIPTOR or an OPEN...USING DESCRIPTOR statement, and they are returned to the application after a FETCH...USING DESCRIPTOR statement. They are not used after a DESCRIBE, a DESCRIBE TABLE, or a PREPARE INTO statement:
- stem.n.SQLDATA
- This contains the input value supplied by the application, or
the output value fetched by SQL.
This value is converted to the attributes specified in SQLTYPE, SQLLEN, SQLPRECISION, and SQLSCALE.
- stem.n.SQLIND
- If the input or output value is null, this is a negative number.