GET DESCRIPTOR statement

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

Syntax

^{(explicit id getd002)
getd002} GET DESCRIPTOR { descriptor_var | 'descriptor ' } { total_items_var = COUNT | VALUE { item_num_var | item_num } <Described Item Information> }

Described Item Information

field_var =

{ { DATA | IDATA | ILENGTH | INDICATOR | ITYPE | LENGTH | NAME | NULLABLE | PRECISION | SCALE | TYPE } | ^[] { EXTYPEID | EXTYPELENGTH | EXTYPENAME | EXTYPEOWNERLENGTH | EXTYPEOWNERNAME | SOURCEID | SOURCETYPE } }


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");

¹ Informix® extension