DESCRIBE (E-SQL)

The DESCRIBE statement populates the SQLDA data structure.

Syntax

DESCRIBE prepared_stmt_name INTO :sqlda_struct

Arguments
prepared_stmt_name
Is a prepared SQL statement. For more information, see PREPARE.
sqlda_struct
Is the output SQLDA data structure to be populated.
Remarks

The DESCRIBE statement processes prepared, dynamic SQL statements. This statement populates the specified SQLDA data structure with the data type, the length, and the column name of each column returned by the specified prepared statement. (Prepared statements are created by using the PREPARE statement. Note that the DESCRIBE statement cannot be used in the FROM clause of a PREPARE statement.) The DESCRIBE statement works like a PREPARE statement with an INTO clause.

Before using DESCRIBE, the sqln and sqlabc fields of the SQLDA data structure that are allocated by the application should be set to appropriate values. The sqln field must be set to the maximum number of column descriptor entries that can be held. The sqlabc field must be set to the length, in bytes, of the SQLDA data structure. The length is computed by using the SQLDASIZE macro as follows:

SQLDASIZE(mysqlda->sqln)

  

When the DESCRIBE statement is executed, it sets the sqld field of the SQLDA data structure to the number of column descriptors used by the prepared statement. If a nonSELECT statement was prepared, sqld is set to 0.

If the application does not know the maximum number of column descriptors required for the prepared statement, it can set sqln to 0 before using the DESCRIBE statement. Then DESCRIBE will set sqld to the maximum number of column descriptors required without actually constructing any column descriptors.

After the DESCRIBE statement has populated the SQLDA data structure, and before it has used the FETCH statement, the application must insert the address of each output variable into the sqldata field (part of the sqlvar field) of the SQLDA data structure.

Examples

#define NUM_RETURN_COLS 2

struct sqlda *mysqlda;

EXEC SQL BEGIN DECLARE SECTION;

char statement[] = "SELECT au_fname, au_lname FROM authors";

EXEC SQL END DECLARE SECTION;

  

mysqlda = malloc(SQLDASIZE(NUM_RETURN_COLS));

if (mysqlda == NULL)

{

    return;

}

mysqlda->sqln = NUM_RETURN_COLS;

mysqlda->sqldabc = SQLDASIZE(NUM_RETURN_COLS);

  

EXEC SQL DECLARE c1 CURSOR FOR stmt1;

EXEC SQL PREPARE stmt1 FROM :statement;

EXEC SQL DESCRIBE stmt1 INTO :mysqlda;

// SQLDA now contains a description of the dynamic SQL statement //

EXEC SQL OPEN c1;

EXEC SQL FETCH c1 USING DESCRIPTOR :mysqlda;

  

See Also
PREPARE Advanced Programming

  


(c) 1988-98 Microsoft Corporation. All Rights Reserved.