Using the DESCRIBE Statement

The sqlda structure is a dynamic-management structure that contains information about columns in dynamic SQL statements. The DESCRIBE...INTO statement uses the sqlda structure to return information about the columns in the select list of the Projection clause of a SELECT statement. It sets the sqlvar field of an sqlda structure to point to a sequence of partially filled sqlvar_struct structures. Each structure describes a single select-list column.

Each sqlvar_struct structure contains character data for the column name and the column data. When the ESQL/C client application fills this structure, the column name and the column data are in the client code set. When the database server fills this structure and executes a DESCRIBE...INTO statement, this character data is in the database code set.

When the client application performs code-set conversion between the client and database code sets, the number of bytes that is required to store the column name and column data in the client code set might not equal the number that is required to store this same information in the database code set. Therefore, the size of the character data in sqlvar_struct might increase or decrease during code-set conversion. To handle this possible difference in size, the client application must ensure that it correctly handles the character data in the sqlvar_struct structure.

The sqldata Field

To hold the column data, the client application must allocate a buffer and set sqldata to point to this buffer. If your client application might perform code-set conversion, it must allocate sufficient storage to handle the increase in the size of the column data that might occur.

When the DESCRIBE ... INTO statement sets the sqllen field, the sqllen value indicates the length of the column data in the database code set. Therefore, if you use the value of sqllen that the DESCRIBE ... INTO statement retrieves, you might not allocate a buffer that is sufficiently large for the data values when they are in the client code set.

For example, the following code fragment allocates an sqldata buffer with the malloc( ) system call:

EXEC SQL include sqlda;
...
struct sqlda *q_desc;
...
EXEC SQL describe sqlstmt_id into q_desc;
...
q_desc->sqlvar[0].sqldata = 
   (char *)malloc(q_desc->sqlvar[0].sqllen);

In the preceding code fragment, the client application might truncate characters that it converts because the client application uses the sqllen value to determine the buffer size. Instead, increase the buffer to four times its original size when you allocate a buffer, as the following code fragment shows:

EXEC SQL include sqlda;
EXEC SQL define BUFSIZE_FACT 4;
...

struct sqlda *q_desc;
...

q_desc->sqlvar[0].sqllen = 
   q_desc->sqlvar[0].sqllen * BUFSIZE_FACT + 1;
q_desc->sqlvar[0].sqldata = 
   (char *)malloc(q_desc->sqlvar[0].sqllen);

A buffer-size factor (BUFSIZE_FACT) of 4 is suggested because a multibyte character has a maximum size of 4 bytes.

The sqlname Field

The sqlname field contains the name of the column. When the client application performs code-set conversion, this column name might also undergo expansion when the application converts it from the database code set to the client code set. Because the ESQL/C application stores the buffer for sqlname data in its internal work area, your ESQL/C source code does not have to handle possible buffer-size increases. Your code processes the contents of sqlname in the client code set.