blk_describe

Retrieves a description of a database column.

CS_RETCODE blk_describe(blkdesc, colnum, datafmt)
 
 CS_BLKDESC        *blkdesc;
 CS_INT                   colnum;
 CS_DATAFMT        *datafmt;

blkdesc: A pointer to the CS_BLKDESC that is serving as a control block for the bulk-copy operation. blk_alloc allocates a CS_BLKDESC structure.

colnum: The number of the column of interest. The first column in a table is column number 1, the second is number 2, and so forth.

A pointer to a CS_DATAFMT structure. blk_describe fills *datafmt with a description of the database column referenced by colnum.

During a bulk-copy-in operation, blk_describe fills in the following fields in the CS_DATAFMT:

**Table 4-4: CS_DATAFMT fields, as set by blk_describe for bulk-copy-in**
Field name	blk_describe sets the field to
name	The null-terminated name of the column, 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 indicates a NULL name.
datatype	A type constant representing the datatype of the column. All type constants listed on the “Types” topics page are valid, with the exception of CS_VARCHAR_TYPE and CS_VARBINARY_TYPE.
maxlength	The maximum possible length of the data for the column.
scale	The scale of the column.
precision	The precision of the column.

During a bulk-copy-out operation, blk_describe fills in the following fields in the CS_DATAFMT:

**Table 4-5: CS_DATAFMT fields, as set by blk_describe for bulk-copy-out**
Field name	blk_describe sets the field to
name	The null-terminated name of the column, 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 indicates a NULL name.
datatype	The datatype of the column. All datatypes listed on the “Types” topics page in the Open Client Client-Library/C Reference Manual are valid.
maxlength	The maximum possible length of the data for the column.
scale	The scale of the column.
precision	The precision of the column.
status	A bit mask of the following symbols, combined with a bitwise, OR: CS_CANBENULL to indicate that the column can contain NULL values. CS_HIDDEN to indicate that this column is a hidden column that has been exposed. Hidden columns are exposed when the CS_HIDDEN_KEYS property is set for the bulk descriptor’s parent connection. CS_IDENTITY to indicate that the column is an identity column. CS_KEY to indicate the 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.
usertype	The Adaptive Server user-defined datatype of the column, 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.

blk_describe returns:

Returns	Indicates
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.

blk_describe returns CS_FAIL if colnum does not represent a valid result column.

blk_describe is a client-side routine.

blk_describe describes the format of a database column. The application can use this information to:

Determine the datatype and size requirements for allocating storage for retrieving rows (for bulk copy out of the database).

Determine compatibility between program variable datatypes and the database columns (by calling cs_will_convert to determine whether the conversion is supported and, if necessary, by checking the data lengths).

Perform error checking. For example, the debug version of a bulk-copy application might call blk_describe to confirm assumptions about the format of table columns.
An application typically uses a column description while determining compatible program variable types and sizes.
See the “CS_DATAFMT Structure” topics page in the Open Client Client-Library/C Reference Manual for a complete description of the CS_DATAFMT structure.