Call Level Interface Guide and Reference

Allocating and Freeing Descriptors

Descriptors are allocated in one of two ways:

Implicitly Allocated Descriptors

When a statement handle is allocated, a set of four descriptors are implicitly allocated. When the statement handle is freed, all implicitly allocated descriptors on that handle are freed as well.

To obtain handles to these implicitly allocated descriptors an application can call SQLGetStmtAttr(), passing the statement handle and an Attribute value of:

• SQL_ATTR_APP_PARAM_DESC (APD)
• SQL_ATTR_APP_ROW_DESC (ARD)
• SQL_ATTR_IMP_PARAM_DESC (IPD)
• SQL_ATTR_IMP_ROW_DESC (IRD)

Explicitly Allocated Descriptors

An application can explicitly allocate application descriptors. It is not possible, however, to allocate implementation descriptors.

An application descriptor on a connection can be explicitly allocated at any time it is connected to the database. This is done by calling SQLSetStmtAttr(), passing the statement handle and an Attribute value of:

• SQL_ATTR_APP_PARAM_DESC (APD)
• SQL_ATTR_APP_ROW_DESC (ARD)

In this case the explicitly specified allocated descriptor will be used rather than the implicitly allocated descriptor.

An explicitly allocated descriptor can be associated with more than one statement.

Initialization of Fields

When an application row descriptor is allocated, its fields receive the initial values indicated in the Initialization of Descriptor Fields section of SQLSetDescField(). The SQL_DESC_TYPE field is set to SQL_DEFAULT which provides for a standard treatment of database data for presentation to the application. The application may specify different treatment of the data by setting fields of the descriptor record.

The initial value of the SQL_DESC_ARRAY_SIZE header field is 1. To enable multirow fetch, the application can set this value in an ARD to specify the number of rows in a rowset. See "Scrollable Cursors" for information about rowsets in a scrollable cursor.

There are no default values for the fields of an IRD. The fields are set when there is a prepared or executed statement.

The following fields in an IPD are undefined until they have been automatically populated by a call to SQLPrepare():

• SQL_DESC_CASE_SENSITIVE
• SQL_DESC_FIXED_PREC_SCALE
• SQL_DESC_TYPE_NAME
• SQL_DESC_DESC_UNSIGNED
• SQL_DESC_LOCAL_TYPE_NAME

Automatic Population of the IPD

There are times when the application will need to discover information about the parameters of a prepared SQL statement. A good example is when an ad-hoc query is prepared; the application will not know anything about the parameters in advance. If the application enables automatic population of the IPD, by setting the SQL_ATTR_ENABLE_AUTO_IPD statement attribute to SQL_TRUE (using SQLSetStmtAttr()), then the fields of the IPD are automatically populated to describe the parameter. This includes the data type, precision, scale, and so on (the same information that SQLDescribeParam() returns). The application can use this information to determine if data conversion is required, and which application buffer is the most appropriate to bind the parameter to.

Automatic population of the IPD involves some overhead. If it is not necessary for this information to be automatically gathered by the CLI driver then the SQL_ATTR_ENABLE_AUTO_IPD statement attribute should be set to SQL_FALSE. This is the default setting, and the application should return it to this value when it is no longer needed.

When automatic population of the IPD is active, each call to SQLPrepare() causes the fields of the IPD to be updated. The resulting descriptor information can be retrieved by calling the following functions:

• SQLGetDescField()
• SQLGetDescRec()
• SQLDescribeParam()

Freeing Descriptors

Explicitly Allocated Descriptors

When an explicitly allocated descriptor is freed, all statement handles to which the freed descriptor applied automatically revert to the original descriptors implicitly allocated for them.

Explicitly allocated descriptors can be freed in one of two ways:

• by calling SQLFreeHandle()with a HandleType of SQL_HANDLE_DESC
• by freeing the connection handle that the descriptor is associated with

Implicitly Allocated Descriptors

An implicitly allocated descriptor can be freed in one of the following ways:

• by calling SQLDisconnect() which drops any statements or descriptors open on the connection
• by calling SQLFreeHandle() with a HandleType of SQL_HANDLE_STMT to free the statement handle and all of the implicitly allocated descriptors associated with the statement

An implicitly allocated descriptor cannot be freed by calling SQLFreeHandle() with a HandleType of SQL_HANDLE_DESC.

[ DB2 List of Books | Search the DB2 Books ]