GET DESCRIPTOR statement

Use the GET DESCRIPTOR statement to read from a system descriptor area.

Syntax


>>-GET DESCRIPTOR--+-descriptor_var-+--------------------------->
                   '-'descriptor '--'   

>--+-total_items_var-- = -COUNT----------------------------------+-><
   |                          .-,------------------------------. |   
   |                          V                                | |   
   '-VALUE--+-item_num_var-+----| Described Item Information |-+-'   
            '-item_num-----'                                         

Described Item Information

|--field_var-- = -+-+-DATA------+---------------+---------------|
                  | +-IDATA-----+               |   
                  | +-ILENGTH---+               |   
                  | +-INDICATOR-+               |   
                  | +-ITYPE-----+               |   
                  | +-LENGTH----+               |   
                  | +-NAME------+               |   
                  | +-NULLABLE--+               |   
                  | +-PRECISION-+               |   
                  | +-SCALE-----+               |   
                  | '-TYPE------'               |   
                  |  (1)                        |   
                  '-------+-EXTYPEID----------+-'   
                          +-EXTYPELENGTH------+     
                          +-EXTYPENAME--------+     
                          +-EXTYPEOWNERLENGTH-+     
                          +-EXTYPEOWNERNAME---+     
                          +-SOURCEID----------+     
                          '-SOURCETYPE--------'

Notes:

Informix® extension

Element	Description	Restrictions	Syntax
descriptor	Quoted string that identifies a system-descriptor area (SDA)	System-descriptor area must already have been allocated	Quoted String
descriptor_var	Variable that stores descriptor value	Same restrictions as descriptor	Language specific
field_var	Host variable to receive the contents of a field from an SDA	Must be of type that can receive value of a specified SDA field	Language specific
item_num	Unsigned ordinal number of an item described in the SDA	0 ≤ item_num ≤ (number of item descriptors in the SDA)	Literal Number
item_num_ var	Host variable storing item_num	Must be an integer data type	Language specific
total_items_var	Host variable storing the number of items described in the SDA	Must be an integer data type	Language specific

Usage

Use this statement with Informix ESQL/C.

Use the GET DESCRIPTOR statement to accomplish any of the following tasks:

Determine how many items are described in a system-descriptor area.
Determine the characteristics of each column or expression that is described in the system-descriptor area.
Copy a value from the system-descriptor area into a host variable after a FETCH statement.

You can use GET DESCRIPTOR after you describe EXECUTE FUNCTION, INSERT, SELECT, or UPDATE statements with the DESCRIBE . . . USING SQL DESCRIPTOR statement.

The host variables that you reference in the GET DESCRIPTOR statement must be declared in the BEGIN DECLARE SECTION of a program.

If an error occurs during the assignment of a value to any specified host variable, the contents of the host variable are undefined.

Examples

The following ESQL/C example shows how to use a GET DESCRIPTOR statement with a host variable to determine how many items are described in the system-descriptor area called desc1: GET DESCRIPTOR

main() 
{ 
	EXEC SQL BEGIN DECLARE SECTION; 
		int h_count; 
	EXEC SQL END DECLARE SECTION; 

	EXEC SQL allocate descriptor 'desc1' with max 20; 
	
	/* This section of program would prepare a SELECT or INSERT 
	* statement into the s_id statement id. 
	*/ 

	EXEC SQL describe s_id using sql descriptor 'desc1'; 
	EXEC SQL get descriptor 'desc1' :h_count = count;

The following ESQL/C example uses GET DESCRIPTOR to obtain data type information from the demodesc system-descriptor area:

EXEC SQL get descriptor 'demodesc' value 
	:index :type = TYPE, 
	:len = LENGTH, 
	:name = NAME; 
printf("Column %d: type = %d, len = %d, name = %s\n", 
	index, type, len, name);

The following ESQL/C example shows how you can copy data from the DATA field into a host variable (result) after a fetch. For this example, it is predetermined that all returned values are the same data type:

EXEC SQL get descriptor 'demodesc' :desc_count = count; 
.. . 
EXEC SQL fetch democursor using sql descriptor 'demodesc'; 
for (i = 1; i <= desc_count; i++) 
	{ 
	if (sqlca.sqlcode != 0) break; 
	EXEC SQL get descriptor 'demodesc' value :i :result = DATA; 
	printf("%s ", result); 
} 
printf("\n");