DB2 10.5 for Linux, UNIX, and Windows

SQLCopyDesc function (CLI) - Copy descriptor information between handles

Copies descriptor information from one descriptor handle to another.

Specification:

CLI 5.0
ODBC 3.0
ISO CLI

Syntax

SQLRETURN   SQLCopyDesc (
               SQLHDESC       SourceDescHandle,   /* hDescSource */
               SQLHDESC       TargetDescHandle);  /* hDescTarget */

Function arguments

Table 1. 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 in the TargetDescHandle.

All descriptor fields are copied, even if SourceDescHandle and TargetDescHandle 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.

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 StatementHandle on different ConnectionHandle, SQLCopyDesc() has to be called.

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

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

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 2. SQLCopyDesc SQLSTATEs
SQLSTATE	Description	Explanation
01000	Warning.	Informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
08S01	Communication link failure.	The communication link between 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 is unable to allocate memory required to support execution or completion of the function. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
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.
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

  SQLHANDLE hIRD, hARD; /* descriptor handles */
  
  /* ... */

  /* copy descriptor information between handles */
  rc = SQLCopyDesc(hIRD, hARD);