ct_dynsqlda

Description

Operate on a SQLDA structure.

Syntax

CS_RETCODE ct_dynsqlda(cmd, sqlda_type, dap, operation)
 
 CS_COMMAND    *cmd;
 CS_INT                 sqlda_type;
 SQLDA                  *dap;
 CS_INT                 operation;

Parameters

cmd: A pointer to a CS_COMMAND structure.

sqlda_type: Symbolic constant describing the type of SQLDA structure pointed at by dap. In this version, sqlda_type must be CS_SQLDA_SYBASE to indicate a Sybase-style SQLDA structure.

dap: The address of a SQLDA structure. The SQLDA structure is defined in the Sybase sqlda.h header file. See “Sybase-style SQLDA structure” for the definition of this structure.

operation

The operation to perform. Table 3-37 summarizes the use of ct_dynsqlda:

**Table 3-37: Values for ct_dynsqlda operation parameter**
Value of operation	Function
CS_GET_IN	Fills *dap with a description of the input parameters for a prepared dynamic SQL statement.
CS_GET_OUT	Fills *dap with a description of the columns returned by a prepared dynamic SQL statement.
CS_SQLDA_ PARAM	Uses a SQLDA structure to supply input parameters for the execution of a prepared statement. When executing a prepared dynamic SQL statement, this operation applies the contents of *dap as input parameters.
CS_SQLDA_ BIND	Uses a SQLDA structure to process results from the execution of a prepared statement. When processing the results returned by the execution of a prepared dynamic SQL statement, this operation binds the contents of *dap to the result columns.

Returns

ct_dynsqlda returns the following values:

Return value	Meaning
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.
CS_BUSY	An asynchronous operation is pending for this connection. See “Asynchronous programming”.

Usage

A SQLDA structure is used with prepared dynamic SQL statements. It contains format descriptions and (optionally) values for command input parameters or result columns.
For more information about dynamic SQL, see Chapter 8, “Using Dynamic SQL Commands,” in the Open Client Client-Library/C Programmer’s Guide.
ct_dynsqlda manages a SQLDA structure. A SQLDA structure contains data areas for the descriptions and values of a command’s input parameters or result values.

Sybase-style SQLDA structure

The Sybase-style SQLDA is a self-describing, variable-length structure, declared as follows:

typedef struct _sqlda

     CS_SMALLINT sd_sqln; /* Actual length of column array    */

     CS_SMALLINT sd_sqld; /* Current number of columns        */

/*

     ** The following array is treated as if it were the length

     ** indicated by sd_sqln.

*/

     struct _sd_column

         CS_DATAFMT sd_datafmt; /* Format of column i.       */

         CS_VOID *sd_sqldata;   /* Value buffer for column i. */

         CS_INT sd_sqllen;      /* Length of current value.   */

         CS_SMALLINT sd_sqlind; /* Indicator for column i.    */

         CS_VOID *sd_sqlmore;   /* Reserved for future use.   */

     } sd_column[1];

 } sqlda;

 #define SYB_SQLDA_SIZE(n) (sizeof(sqlda) \

         - sizeof(struct _sd_column) \

                 + (n) * sizeof(struct _sd_column))

Allocating SQLDA structures

The application is responsible for correctly allocating and initializing the structure pointed to by dap. The actual size of the structure depends on the number of columns that the structure is to describe. An application can use the SYB_SQLDA_SIZE macro to allocate a SQLDA buffer of the appropriate size. On a system that uses malloc to allocate memory, this can be done as follows:

#define MAX_COLUMNS 16

 SQLDA *dap;

 dap = (SQLDA *) malloc(

                  SYB_SQLDA_SIZE(MAX_COLUMNS) );

 if (dap == (SQLDA *) NULL)

   ... out of memory ...

 memset((void *)dap, 0,

        SYB_SQLDA_SIZE(MAX_COLUMNS));

 dap->sd_sqln = MAX_COLUMNS;

An application can invoke the SQLDA_DECL macro to declare a static SQLDA structure. The invocation:

SQLDA_DECL(name, size);

Is equivalent to the declaration:

struct {

         CS_SMALLINT sd_sqln;

         CS_SMALLINT sd_sqld;

         struct {

                 CS_DATAFMT sd_datafmt;

                 CS_VOID *sd_sqldata;

                 CS_SMALLINT sd_sqlind;

                 CS_INT sd_sqllen;

                 CS_VOID *sd_sqlmore;

         } sd_column[(size)];

 } name;

If the structure will be used to pass input parameters or retrieve results, the (using ct_dynsqlda’s CS_SQLDA_PARAM or CS_SQLDA_BIND operations), then the application must also allocate buffers for item values and set the buffer lengths in the structure.
The use of the Sybase-style SQLDA is explained in the following sections.

Sybase SQLDA: Retrieving input formats

ct_dynsqlda(cmd, CS_SQLDA_SYBASE, &sqlda, CS_GET_IN) fills the fields of sqlda with a description of the input parameters required to execute a prepared statement.
A prepared dynamic SQL statement can contain parameter markers for values to be supplied at execution time.
A dynamic SQL statement can contain parameter markers for parameters to be supplied at execution time. After a dynamic SQL statement is prepared, the application can request a description of the format of the statement’s parameter. The procedure is:
1. Build and send a ct_dynamic(CS_DESCRIBE_INPUT) command to the server.
2. Handle the results of the command with ct_reults. When ct_results returns a result_type value of CS_DESCRIBE_RESULT, the parameter formats are available.
3. If necessary, call ct_res_info(CS_NUMDATA) to find out how many parameters the statement requires. The SQLDA structure contains an array of column descriptors. The array must contain at least one entry for each required parameter.
4. Call ct_dynsqlda to retrieve the parameter formats.

The application is responsible for allocating the SQLDA structure and the memory pointed to by its constituent pointers. The field settings for a CS_GET_IN operation are as follows:

**Table 3-38: SQLDA fields for ct_dynsqlda(CS_GET_IN) calls**
Field	Description
sqlda-> sd_sqln	On input, the number of elements in the array that starts at sqlda->sd_column. The SQLDA must be sufficiently large. See “Allocating SQLDA structures”.
sqlda-> sd_sqld	On output, the actual number of items.
sqlda-> sd_column[i]. sd_sqldata	Unused (ignored).
sqlda-> sd_column[i]. sd_sqllen	Unused (ignored).
sqlda-> sd_column[i]. sd_datafmt	On output, the CS_DATAFMT fields for each parameter are set exactly as ct_describe would set them (see Table 3-18).
sqlda-> sd_column[i]. sd_sqlind	Unused (ignored).

Sybase SQLDA: Retrieving output formats

ct_dynsqlda(cmd, CS_SQLDA_SYBASE, &sqlda, CS_GET_OUT) fills the fields of sqlda with a description of the results returned by the execution of a prepared statement.
A dynamic SQL statement can contain a server select command. After a dynamic SQL statement is prepared, the application can request a description of the format of the row data returned by the statement. The procedure is:
1. Build and send a ct_dynamic(CS_DESCRIBE_OUTPUT) command to the server.
2. Handle the results of the command with ct_results. When ct_results returns a result_type value of CS_DESCRIBE_RESULT, the output formats are available to the application.
3. If necessary, call ct_res_info(CS_NUMDATA) to find out how many columns the statement returns. The SQLDA structure contains the address of an array of column descriptors. This array must contain at least one entry per column.
4. Call ct_dynsqlda to retrieve the column formats.

The application is responsible for allocating the SQLDA structure and the memory pointed to by its constituent pointers. The field settings for a CS_GET_OUT operation are as follows:

**Table 3-39: SQLDA fields for ct_dynsqlda(CS_GET_OUT) calls**
Field	Description
sqlda-> sd_sqln	On input, the number of elements in the array that starts at sqlda->sd_column. The SQLDA must be sufficiently large. See “Allocating SQLDA structures”.
sqlda-> sd_sqld	On output, the actual number of items.
sqlda-> sd_column[i]. sd_sqldata	Unused (ignored).
sqlda-> sd_column[i]. sd_sqllen	Unused (ignored).
sqlda-> sd_column[i]. sd_datafmt	On output, the CS_DATAFMT fields for each column are set exactly as ct_describe would set them (see Table 3-18).
sqlda-> sd_column[i]. sd_sqlind	Unused (ignored).

Sybase SQLDA: Passing command input parameters

ct_dynsqlda(cmd, CS_SQLDA_SYBASE, &sqlda, CS_SQLDA_PARAM) applies the contents of an SQLDA structure as input parameter values for the execution of a prepared statement.
The procedure for using ct_dynsqlda to pass parameters for the execution of a prepared statement is as follows:
1. (Optional) Get a description of the command inputs as described by “Sybase SQLDA: Retrieving input formats”.
2. Call ct_dynamic(CS_EXECUTE) to initiate the command.
3. Fill in the fields of the SQLDA as described in the table below.
4. Call ct_dynsqlda(CS_SQLDA_PARAM) to apply the SQLDA’s contents as input parameter values.
5. Send the command with ct_send.
6. Handle the results of the command.

The application is responsible for allocating the SQLDA structure and the memory pointed to by its constituent pointers. The field settings for a CS_SQLDA_PARAM operation are as follows:

**Table 3-40: SQLDA fields for ct_dynsqlda(CS_SQLDA_PARAM) calls**
Field	Description
sqlda-> sd_sqln	On input, the number of elements in the array that starts at sqlda->sd_column. The array must have as many entries as the number of items requested by the sd_sqld field. See “Allocating SQLDA structures”.
sqlda-> sd_sqld	On input, the number of items in the sqlda->sd_column array that should be applied as parameter values.
sqlda-> sd_column[i]. sd_sqldata	When executing a command, contains the address of a buffer containing a value for parameter i (with 0 being the first parameter marker in the statement).
sqlda-> sd_column[i]. sd_sqllen	The length, in bytes, of the buffer pointed at by sd_column[i].sd_sqldata.
sqlda-> sd_column[i]. sd_datafmt	The CS_DATAFMT fields for each column must be set exactly as required by ct_param (see Table 3-49).
sqlda-> sd_column[i]-> sd_sqlind	When executing a command, a value of -1 indicates that the value for parameter i is NULL.

Sybase SQLDA: Retrieving results

ct_dynsqlda(cmd, CS_SQLDA_SYBASE, &sqlda, CS_SQLDA_BIND) binds the contents of an SQLDA structure to columns in the results returned by the execution of a prepared statement.
The procedure for using ct_dynsqlda for results processing is as follows:
1. (Optional) Get a description of the command outputs as described in “Sybase SQLDA: Retrieving output formats”.
2. Call ct_dynamic(CS_EXECUTE) to initiate the command.
3. Supply any necessary parameter values for execution.
4. Send the command with ct_send.
5. Handle the results of the command. When ct_results returns a result_type value of CS_ROW_RESULT, the SQLDA structure can be bound to the result rows.
6. Fill in the fields of the SQLDA as described in the table below, then call ct_dynsqlda(CS_SQLDA_BIND) to bind them to the column values in the result rows.
7. Process the rows with ct_fetch. Each call to ct_fetch places values, converted if necessary, into the bound fields of the SQLDA.

The application is responsible for allocating the SQLDA structure and the memory pointed to by its constituent pointers. The field settings for a CS_SQLDA_BIND operation are as follows:

**Table 3-41: SQLDA fields for ct_dynsqlda(CS_SQLDA_BIND) calls**
Field	Description
sqlda-> sd_sqln	On input, the number of elements in the array that starts at sqlda->sd_column. The array must be at least as long as the number of items requested by the sd_sqld field. See “Allocating SQLDA structures”.
sqlda-> sd_sqld	On input, the number of items in the sqlda->sd_column array that should be bound to result columns.
sqlda-> sd_column[i]. sd_sqldata	Contains the address of a buffer where ct_fetch will place values for column i (with 0 being the first column).
sqlda-> sd_column[i]. sd_sqllen	The length, in bytes, of the buffer pointed at by sd_column[i]->sd_sqldata.
sqlda-> sd_column[i]. sd_datafmt	The CS_DATAFMT fields for each column must be set exactly as required by ct_bind (see Table 3-1).
sqlda-> sd_column[i]. sd_sqlind	Subsequent calls to ct_fetch will write indicator values for each column. Indicator values are as follows: -1 indicates the column value is NULL. 0 indicates a successful fetch. Any positive integer indicates truncation. The value is the actual length of the column value before truncation.