The following sections describe manipulating descriptors using descriptor handles. The final section, "Accessing Descriptors without using a Handle" describes how to manipulate descriptor values by calling CLI functions that do not use descriptor handles.
The handle of an explicitly allocated descriptor is returned in the OutputHandlePtr argument when the application calls SQLAllocHandle() to allocate the descriptor.
The handle of an implicitly allocated descriptor is obtained by calling SQLGetStmtAttr() with either SQL_ATTR_IMP_PARAM_DESC or SQL_ATTR_IMP_ROW_DESC.
See SQLGetDescField - Get Single Field Settings of Descriptor Record for information on how to obtain a single field of a descriptor record.
See SQLGetDescRec - Get Multiple Field Settings of Descriptor Record for information on how to obtain the settings of multiple descriptor fields that affect the data type and storage of column or parameter data.
This section deals with how to set the values of descriptor fields using descriptor handles. You can also set many of these fields without using descriptor handles; see "Accessing Descriptors without using a Handle" for more information.
Two methods can be used to set descriptor fields, one field at a time or multiple fields at a time:
Some fields of a descriptor are read-only, but the others can be set using the function SQLSetDescField(). See the following sections for specific details on each field that can be set:
Record and header fields are set differently using SQLSetDescField():
The application must follow the steps defined in Sequence of Setting Descriptor Fields when setting individual fields of a descriptor. Setting some fields will cause DB2 CLI to automatically set other fields. A consistency check will take place after the application follows the defined steps. This will ensure that the values in the descriptor fields are consistent. See "Consistency Check" for more information.
If a function call that would set a descriptor fails, the contents of the descriptor fields are undefined after the failed function call.
A predefined set of descriptor fields can be set with one call rather than setting individual fields one at a time. SQLSetDescRec() sets the following fields for a single column or parameter:
(SQL_DESC_DATETIME_INTERVAL_CODE is also defined by ODBC but is not supported by DB2 CLI.)
See SQLSetDescRec - Set Multiple Descriptor Fields for a Column or Parameter Data for more information.
One benefit of descriptors is the fact that a single descriptor can be used for multiple purposes. For instance, an ARD on one statement handle can be used as an APD on another statement handle.
There will be other instances, however, where the application will want to make a copy of the original descriptor, then modify certain fields. In this case SQLCopyDesc() is used to overwrite the fields of an existing descriptor with the values from another descriptor. Only fields that are defined for both the source and target descriptors are copied (with the exception of the SQL_DESC_ALLOC_TYPE field which cannot be changed).
Fields can be copied from any type of descriptor, but can only be copied to an application descriptor (APD or ARD) or an IPD. Fields cannot be copied to an IRD. The descriptor's allocation type will not be changed by the copy procedure (again, the SQL_DESC_ALLOC_TYPE field cannot be changed).
See SQLCopyDesc - Copy Descriptor Information Between Handles for complete details on copying descriptors.
As was mentioned at the beginning of this section on descriptors, many CLI functions make use of descriptors, but the application itself does not need to manipulate them directly. Instead, the application can use a different function which will set or retrieve one or more fields of a descriptor as well as perform other functions. This category of CLI functions are called concise functions. SQLBindCol() is an example of a concise function that manipulates descriptor fields.
In addition to manipulating multiple fields, concise functions are called without explicitly specifying the descriptor handle. The application does not even need to retrieve the descriptor handle to use a concise function.
The following types of concise functions exist::
If required, an application can also use the descriptor calls directly to modify individual details of a binding. In this case the descriptor handle must be retrieved, and the functions SQLSetDescField() or SQLSetDescRec() called to modify the binding.