ct_dyndesc

Description

Perform operations on a dynamic SQL descriptor area.

Syntax

CS_RETCODE ct_dyndesc(cmd, descriptor, desclen,
              operation, index, datafmt, buffer,
              buflen, copied, indicator)
 
CS_COMMAND    *cmd;
CS_CHAR            *descriptor;
CS_INT                 desclen;
CS_INT                 operation;
CS_INT                 index;
CS_DATAFMT      *datafmt;
CS_VOID              *buffer;
CS_INT                 buflen;
CS_INT                 *copied;
CS_SMALLINT      *indicator;

Parameters

cmd: A pointer to a CS_COMMAND structure. Any CS_COMMAND in the same context in which a descriptor is allocated can be used to operate on the descriptor.

descriptor: A pointer to the name of the descriptor. Descriptor names must be unique within a context.

desclen: The length, in bytes, of *descriptor. If *descriptor is null-terminated, pass desclen as CS_NULLTERM.

operation

The descriptor operation to initiate. The following table lists the values for operation:

**Table 3-25: Values for ct_dyndesc operation parameter**
Value of operation	Result
CS_ALLOC	Allocates a descriptor.
CS_DEALLOC	Deallocates a descriptor.
CS_GETATTR	Retrieves a parameter or result item’s attributes.
CS_GETCNT	Retrieves the number of parameters or columns.
CS_SETATTR	Sets a parameter’s attributes.
CS_SETCNT	Sets the number of parameters or columns.
CS_USE_DESC	Associates a descriptor with a statement or a command structure.

index

When used, an integer variable.

Depending on the value of operation, index can be either the 1-based index of a descriptor item or the number of items associated with a descriptor.

datafmt: When used, a pointer to a CS_DATAFMT structure.

buffer: When used, a pointer to data space.

buflen: When used, buflen is the length, in bytes, of the *buffer data.

copied: When used, a pointer to an integer variable. ct_dyndesc sets *copied to the length, in bytes, of the data placed in *buffer.

indicator

When used, a pointer to an indicator variable.

**Table 3-26: Values for ct_dyndesc indicator parameter**
Value of operation	Value of *indicator	Meaning
CS_GETATTR	-1	Truncation of a server value by Client-Library.
	0	No truncation.
	integer value	Truncation of an application value by the server.
CS_SETATTR	-1	The parameter has a null value.

Returns

ct_dyndesc returns the following values:

Return value	Meaning
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.
CS_ROW_FAIL	A recoverable error occurred. Recoverable errors include conversion errors that occur while copying values to program variables as well as memory allocation failures.
CS_BUSY	An asynchronous operation is already pending for this connection. See “Asynchronous programming”.

Usage

A dynamic SQL descriptor area contains information about the input parameters to a dynamic SQL statement or the result data items generated by the execution of a dynamic SQL statement.
Although ct_dyndesc takes a CS_COMMAND structure as a parameter, the scope of a dynamic SQL descriptor area is a Client-Library context; that is:
- Descriptor names must be unique within a context.
- An application can use any command structure within a context to reference the context’s descriptor areas. For example, a descriptor area allocated through one command structure can be deallocated by another command structure within the same context.
For more information about dynamic SQL, see Chapter 8, “Using Dynamic SQL Commands,” in the Open Client Client-Library/C Programmer’s Guide.

Allocating a descriptor

To allocate a descriptor, an application calls ct_dyndesc with operation as CS_ALLOC.

Table 3-27 lists parameter values for CS_ALLOC operations:

**Table 3-27: Parameter values for ct_dyndesc(CS_ALLOC) operations**
descriptor, desclen	index	datafmt	buffer, buflen	copied	indicator
The name of the descriptor to allocate, the length of the name or CS_NULLTERM.	The maximum number of items that the descriptor will accommodate.	NULL	NULL, CS_UNUSED	NULL	NULL

Deallocating a descriptor

To deallocate a descriptor, an application calls ct_dyndesc with operation as CS_DEALLOC.

Table 3-28 lists parameter values for CS_DEALLOC operations:

**Table 3-28: Parameter values for ct_dyndesc(CS_DEALLOC) operations**
descriptor, desclen	index	datafmt	buffer, buflen	copied	indicator
The name of the descriptor to deallocate, the length of the name or CS_NULLTERM.	CS_UNUSED	NULL	NULL, CS_UNUSED	NULL	NULL

Retrieving a parameter or result item’s attributes

To retrieve the attributes of a parameter or a result data item, an application calls ct_dyndesc with operation as CS_GETATTR.

Table 3-29 lists parameter values for CS_GETATTR operations:

**Table 3-29: Parameter values for ct_dyndesc(CS_GETATTR) operations**
descriptor, desclen	index	datafmt	buffer, buflen	copied	indicator
The name of the descriptor of interest, the length of the name or CS_NULLTERM.	The number of the item whose description is being requested. Index numbers start with 1.	As an input parameter, datafmt describes buffer. ct_dyndesc overwrites *datafmt with a description of the item.	If supplied, buffer is set to the value of the item. If buffer* is NULL, only a description of the item is returned. buflen must be CS_UNUSED. datafmt->maxlength describes *buffer’s length.	If supplied, copied is set to the number of bytes placed in buffer. Can be NULL.	If supplied, *indicator is set to the value of the item’s indicator. Can be NULL.

If necessary, ct_dyndesc converts the column’s source data to the format described by *datafmt and places the result in *buffer. If pointers are supplied for *indicator and *copied, they are set accordingly.

An application needs to set the *datafmt fields for a CS_GETATTR operation exactly as they would be set for a ct_bind call, except that datafmt−>count must be 0 or 1 (only one column value at a time can be retrieved). Table 3-30 lists the CS_DATAFMT fields that are used:

**Table 3-30: CS_DATAFMT settings for ct_dyndesc(CS_GETATTR) operations**
Field name	Set field to
datatype	The datatype of the buffer variable.
format	A bitmask of format symbols.
maxlength	The length of the buffer data space.
scale	If buffer is a numeric or decimal variable, the maximum number of digits that can be represented to the right of the decimal point; scale is ignored for all other datatypes.
precision	If buffer is a numeric or decimal variable, the maximum number of decimal digits that can be represented; precision is ignored for all other datatypes.
count	0 or 1.
locale	A pointer to a valid CS_LOCALE structure or NULL.
All other fields are ignored.

ct_dyndesc(CS_GETATTR) sets the *datafmt fields exactly as ct_describe would set them. Table 3-31 lists the fields in *datafmt that ct_dyndesc sets:

**Table 3-31: CS_DATAFMT fields set by ct_dyndesc(CS_GETATTR) operations**
Field name	ct_dyndesc sets field to
name	The null-terminated name of the data item, if any. A NULL name is indicated by a namelen of 0.
namelen	The actual length of the name, not including the null terminator. 0 to indicate a NULL name.
datatype	The datatype of the item. All datatypes listed in “Types” are valid, with the exceptions of CS_VARCHAR and CS_VARBINARY.
maxlength	The maximum possible length of the data for the column or parameter.
scale	The maximum number of digits to the right of the decimal point in the result data item.
precision	The maximum number of decimal digits that can be represented in the result data item.
status	A bitmask of the following values: CS_CANBENULL to indicate that the column can contain NULL values. CS_HIDDEN to indicate that the column is a “hidden” column that has been exposed. For information on hidden columns, see “Hidden keys”. CS_IDENTITY to indicate that the column is an identity column. CS_KEY to indicate the column column is part of the key for a table. CS_VERSION_KEY to indicate the column is part of the version key for the row. CS_TIMESTAMP to indicate the column is a timestamp column. CS_UPDATABLE to indicate that the column is an updatable cursor column. CS_UPDATECOL to indicate that the column is in the update clause of a cursor declare command. CS_RETURN to indicate that the column is a return parameter of an RPC command.
count	ct_dyndesc sets count to 1.
usertype	The Adaptive Server user-defined datatype of the column or parameter, if any. usertype is set in addition to (not instead of) datatype.
locale	A pointer to a CS_LOCALE structure that contains locale information for the data. This pointer can be NULL.

Retrieving the number of parameters or columns

To retrieve the number of parameters or result items a descriptor can describe, an application calls ct_dyndesc with operation as CS_GETCNT.
ct_dyndesc sets *buffer to the number of dynamic parameter specifications or the number of columns in the dynamic SQL statement’s select list, depending on whether input parameters or output columns are being described.

The following table lists parameter values for CS_GETCNT operations:

**Table 3-32: Parameter values for ct_dyndesc(CS_GETCNT) operations**
descriptor, desclen	index	datafmt	buffer, buflen	copied	indicator
The name of the descriptor of interest, the length of the name or CS_NULLTERM.	CS_UNUSED	NULL	A pointer to a CS_INT, CS_UNUSED.	If supplied, copied is set to the number of bytes placed in buffer. Can be NULL.	NULL

Setting a parameter’s attributes

To set a parameter’s attributes, an application calls ct_dyndesc with operation as CS_SETATTR.

Table 3-33 lists parameter values for CS_SETATTR operations:

**Table 3-33: Parameter values for ct_dyndesc(CS_SETATTR) operations**
descriptor, desclen	index	datafmt	buffer, buflen	copied	indicator
The name of the descriptor of interest, the length of the name or CS_NULLTERM.	The number of the item whose description is being set. Index numbers start with 1.	*datafmt contains a description of the item.	A pointer to the value of the item, the length of the value. Pass buflen as CS_UNUSED if buffer points to a fixed-length type.	NULL	If supplied, indicator is the value of the item’s indicator. If indicator is -1, then buffer is ignored and the value of the item is set to NULL. indicator can be NULL.

An application needs to set the *datafmt fields for a CS_SETATTR operation exactly as they would be set for a ct_param call. Table 3-34 lists the fields that are used:

**Table 3-34: CS_DATAFMT fields for ct_dyndesc(CS_SETATTR) operations**
Field name	Set field to
name	The name of the parameter.
namelen	The length of the name or CS_NULLTERM.
datatype	The datatype of the item being set.
maxlength	For variable-length return parameters, maxlength is the maximum number of bytes to be returned for this parameter. maxlength is ignored if status is CS_INPUTVALUE or if datatype represents a fixed-length type.
status	CS_INPUTVALUE, CS_UPDATECOL, or CS_RETURN. CS_UPDATECOL indicates an update column for a cursor-declare command. CS_RETURN indicates a return parameter.
locale	A pointer to a valid CS_LOCALE structure or NULL.
All other fields are ignored.

Setting the number of parameters or columns

To set the number of parameters or columns a descriptor can describe, an application calls ct_dyndesc with operation as CS_SETCNT.

Table 3-35 lists parameter values for CS_SETCNT operations:

**Table 3-35: Parameter values for ct_dyndesc(CS_SETCNT) operations**
descriptor, desclen	index	datafmt	buffer, buflen:	copied	indicator
The name of the descriptor of interest, the length of the name or CS_NULLTERM.	The new descriptor count	NULL	NULL, CS_UNUSED	NULL	NULL

Associating a descriptor with a statement or command structure

To associate a descriptor with a prepared statement or command structure, an application calls ct_dyndesc with operation as CS_USE_DESC.

Table 3-36 lists parameter values for CS_USE_DESC operations:

**Table 3-36: Parameter values for ct_dyndesc(CS_USE_DESC) operations**
descriptor, desclen	index	datafmt	buffer, buflen	copied	indicator
The name of the descriptor of interest, the length of the name or CS_NULLTERM.	CS_UNUSED	NULL	NULL, CS_UNUSED	NULL	NULL

Descriptor areas are normally associated with a context structure. When a descriptor area is used to describe input to or output from a cursor, however, it must first be associated with the command structure which opened the cursor.

When using a descriptor to describe cursor input, a typical application’s sequence of calls is:

ct_dyndesc(CS_ALLOC)

 ct_dyndesc(CS_SETCNT)

 for each input value:

     ct_dyndesc(CS_SETATTR)

 end for

 ct_cursor to open the cursor

 ct_dyndesc(CS_USE_DESC)

 ct_send

Getting descriptions of command inputs or outputs with ct_dyndesc

The sequence of calls to retrieve a description of a prepared statement’s input parameters or result columns with ct_dyndesc is described below.
1. Call ct_dyndesc with operation as CS_ALLOC to allocate a descriptor area.
2. Call ct_dynamic to initiate the command to get the description. Pass the ct_dynamic type argument as CS_DESCRIBE_INPUT for input descriptions and as CS_DESCRIBE_OUTPUT for output descriptions.
3. Call ct_send to send the command to the server.
4. Call ct_results as necessary to process the results of the command. A describe command generates a result set of type CS_DESCRIBE_RESULT. This result set contains no fetchable data but does contain descriptive information for each of the input values.
5. Call ct_dyndesc with operation as CS_USE_DESC to associate the prepared statement with the descriptor area allocated in step 1. This assumes that CS_DESCRIBE_RESULT was returned as ct_results’ current result_type value, as do the following two steps.
6. Call ct_dyndesc with operation as CS_GETCNT to get the number of parameters or columns.
7. For each parameter or column, call ct_dyndesc with operation as CS_GETATTR to get the value’s description.

Passing parameter values with ct_dyndesc

When executing a prepared dynamic SQL statement, an application can supply input parameter values with ct_dyndesc. The sequence of calls is as follows:
1. Call ct_dynamic(CS_EXECUTE) to initiate the command.
2. For each required input parameter, call ct_dyndesc with operation as CS_SETATTR to place a parameter value in the descriptor area. If necessary, convert the value with cs_convert first. The CS_SETATTR usage is summarized under “Setting a parameter’s attributes”.
3. Call ct_dyndesc with operation as CS_USE_DESC to apply the parameter values to the command.
4. Call ct_send to send the command to the server.
5. Process the results of the command. See “Results” if you are unfamiliar with Client-Library’s results model.
Client-Library allows applications to resend a dynamic-SQL execute command by calling ct_send immediately after the application has processed the results of the previous execution. However, parameter values are fixed for all executions of the command if ct_dyndesc is used to supply parameter values. Applications that resend commands with different parameter values should use ct_setparam instead. For more information on this feature, see ct_setparam and “Resending commands”.

Retrieving result column values with ct_dyndesc

When processing fetchable results, an application can retrieve result column values with ct_dyndesc and ct_fetch. (Fetchable results are indicated by the value of the ct_results result_type parameter).
The sequence of calls is summarized below. This sequence assumes that ct_results has returned a result_type value that indicates fetchable data:
1. Call ct_dyndesc with operation as CS_USE_DESC to associate the descriptor with the result rows.
2. Call ct_fetch to fetch a result row. If ct_fetch returns CS_END_DATA, then all the rows have been retrieved.
3. For each column in the result set, call ct_dyndesc with operation as CS_GETATTR to get the column’s value. CS_GETATTR usage is summarized under “Retrieving a parameter or result item’s attributes”.
4. Repeat steps 2–4 until ct_fetch returns CS_END_DATA.