| Specification: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLCopyDesc() copies descriptor information from one descriptor handle to another.
Syntax
SQLRETURN SQLCopyDesc (SQLHDESC SourceDescHandle,
SQLHDESC TargetDescHandle);
Function Arguments
Table 42. SQLCopyDesc Arguments
| Data Type | Argument | Use | Description |
|---|---|---|---|
| SQLHDESC | SourceDescHandle | input | Source descriptor handle. |
| SQLHDESC | TargetDescHandle | input | Target descriptor handle. TargetDescHandle can be a handle to an application descriptor or an IPD. SQLCopyDesc() will return SQLSTATE HY016 (Cannot modify an implementation descriptor) if TargetDescHandle is a handle to an IRD. |
Usage
A call to SQLCopyDesc() copies the fields of the source descriptor handle to the target descriptor handle. Fields can only be copied to an application descriptor or an IPD, but not to an IRD. Fields can be copied from either an application or an implementation descriptor.
All fields of the descriptor, except SQL_DESC_ALLOC_TYPE (which specifies whether the descriptor handle was automatically or explicitly allocated), are copied, whether or not the field is defined for the destination descriptor. Copied fields overwrite the existing fields.
All descriptor fields are copied, even if SourceDescHandle and TargetDescHandle are are on two different connections or environments.
The call to SQLCopyDesc() is immediately aborted if an error occurs.
When the SQL_DESC_DATA_PTR field is copied, a consistency check is performed. If the consistency check fails, SQLSTATE HY021 (Inconsistent descriptor information.) is returned and the call to SQLCopyDesc() is immediately aborted. For more information, see "Consistency Checks" in "SQLSetDescField()."
| Note: | Descriptor handles can be copied across connections or environments.
An application may, however, be able to associate an explicitly allocated
descriptor handle with a StatementHandle, rather than calling
SQLCopyDesc() to copy fields from one descriptor to another.
An explicitly allocated descriptor can be associated with another
StatementHandle on the same ConnectionHandle by setting the
SQL_ATTR_APP_ROW_DESC or SQL_ATTR_APP_PARAM_DESC statement attribute to the
handle of the explicitly allocated descriptor. When this is done,
SQLCopyDesc() does not have to be called to copy descriptor field
values from one descriptor to another.
A descriptor handle cannot be associated with a StatementHandle on another ConnectionHandle, however; to use the same descriptor field values on StatementHandles on different ConnectionHandles, SQLCopyDesc() has to be called. |
For a description of the fields in a descriptor header or record, see SQLSetDescField - Set a Single Field of a Descriptor Record. For more information on descriptors, see Using Descriptors.
Copying Rows between Tables
An ARD on one statement handle can serve as the APD on another statement handle. This allows an application to copy rows between tables without copying data at the application level. To do this, an application calls SQLCopyDesc() to copy the fields of an ARD that describes a fetched row of a table, to the APD for a parameter in an INSERT statement on another statement handle. The SQL_ACTIVE_STATEMENTS InfoType returned by the driver for a call to SQLGetInfo() must be greater than 1 for this operation to succeed.
Return Codes
Diagnostics
When SQLCopyDesc() returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLGetDiagRec() with a HandleType of SQL_HANDLE_DESC and a Handle of TargetDescHandle. If an invalid SourceDescHandle was passed in the call, SQL_INVALID_HANDLE will be returned, but no SQLSTATE will be returned.
When an error is returned, the call to SQLCopyDesc() is
immediately aborted, and the contents of the fields in the
TargetDescHandle descriptor are undefined.
Table 43. SQLCopyDesc SQLSTATEs
| SQLSTATE | Description | Explanation |
|---|---|---|
| 01000 | Warning. | Informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Communication link failure. | The communication link between DB2 CLI and the data source to which it was trying to connect failed before the function completed processing. |
| HY000 | General error. | An error occurred for which there was no specific SQLSTATE. The error message returned by SQLGetDiagRec() in the *MessageText buffer describes the error and its cause. |
| HY001 | Memory allocation failure. | DB2 CLI was unable to allocate the memory required to support execution or completion of the function. |
| HY007 | Associated statement is not prepared. | SourceDescHandle was associated with an IRD, and the associated statement handle was not in the prepared or executed state. |
| HY010 | Function sequence error. |
The function was called while in a data-at-execute (SQLParamData(), SQLPutData()) operation. The function was called while within a BEGIN COMPOUND and END COMPOUND SQL operation. An asynchronously executing function (not this one) was called for the
StatementHandle and was still executing when this function was
called.
|
| HY016 | Cannot modify an implementation row descriptor. | TargetDescHandle was associated with an IRD. |
| HY021 | Inconsistent descriptor information. | The descriptor information checked during a consistency check was not consistent. For more information, see Consistency Checks in SQLSetDescField(). |
| HY092 | Option type out of range. | The call to SQLCopyDesc() prompted a call to SQLSetDescField(), but *ValuePtr was not valid for the FieldIdentifier argument on TargetDescHandle. |
Restrictions
None.
Example
See the README file in the sqllib\samples\cli (or sqllib/samples/cli) subdirectory for a list of appropriate samples.
References
None.