This section summarizes the SQLDA structure and related information.
As you have learned in the previous sections, the SQLDA can be used in any number of ways. In general, the fields within the SQLDA must be initialized either by using a DESCRIBE statement or by user code. Once they are initialized, the SQLDA can be used for input (in EXECUTE, OPEN, and PUT) or for output (in FETCH).
Figure 69 summarizes the sequence of events needed to initialize the SQLDA for use in processing dynamically defined statements in DB2 Server for VM. In any case, you must always initialize SQLN before the DESCRIBE.
Figure 69. SQLDA Initialization - DB2 Server for VM
Figure 70. SQLDA Initialization DB2 Server for VSE
 |
If you do not use a DESCRIBE to set up the SQLDA, you need only fill in those fields that are actually used by the OPEN, FETCH, PUT, or EXECUTE statements.
For applications that override the defaults for subtypes and CCSIDs, the SQLDA provides output information on subtypes and CCSIDs. The DB2 Server for VSE & VM SQL Reference manual contains a description of the structure of the SQLDA, and an explanation of each field within the SQLDA. The following are some additional guidelines for using the SQLN and SQLD fields.
Always set this value when the structure is allocated. When the USING clause of the DESCRIBE statement is set to NAMES, LABELS, or ANY, specify the maximum number of expected select_list items. When you set the USING clause option to BOTH, specify twice the number of expected select_list items.
If the statement being described is not a select-statement, the database manager returns a zero in SQLD. If the statement is a select-statement, SQLD is set to indicate the number of SQLVAR elements. This number is either the number of select_list elements (when the USING clause of the DESCRIBE statement is set to NAMES, LABELS, or ANY), or twice the number of select_list elements (if the USING clause is set to BOTH).
In the second case (USING clause set to BOTH), your program should reset SQLD to half its value before issuing a subsequent FETCH or PUT. This is because only the first N/2 elements contain information; the rest contains label information only.
If (after a DESCRIBE) SQLD is greater than SQLN, the SQLVAR array is not large enough to contain descriptions for all the select_list items. In this case, you must allocate a larger SQLDA based on the value of SQLD. The value in SQLN is not changed.
If you set the value of SQLD yourself, and you set it to less than SQLN, the excess elements of the SQLVAR array are ignored.