A CS_IODESC structure, or I/O descriptor structure, describes text or image data.
An application calls ct_data_info to retrieve a CS_IODESC structure after retrieving a text or image value that it plans to update at a later time. After it has a valid CS_IODESC, a typical application changes only the values of the locale, total_txtlen, and log_on_update fields before using the CS_IODESC to update the text or image value.
An application calls ct_data_info to define a CS_IODESC structure after calling ct_command to initiate a send-data operation to update a text or image value.
A CS_IODESC is defined as follows:
typedef struct _cs_iodesc
{
CS_INT iotype; /* CS_IODATA. */
CS_INT datatype; /* Text or image. */
CS_LOCALE *locale; /* Locale information. */
CS_INT usertype; /* User-defined type. */
CS_INT total_txtlen; /* Total data length. */
CS_INT offset; /* Reserved. */
CS_BOOL log_on_update /* Log the insert? */
CS_CHAR name[CS_OBJ_NAME]; /* Name of data object.*/
CS_INT namelen /* Length of name. */
CS_BYTE timestamp[CS_TS_SIZE]; /* Adaptive Server id. */
CS_INT timestamplen; /* Length of timestamp.*/
CS_BYTE textptr[CS_TP_SIZE]; /* Adaptive Server ptr.*/
CS_INT textptrlen; /* Length of textptr. */
CS_INT delete_length; /* Number of bytes to */
/* delete/overwrite for*/
/* partial updates. */
} CS_IODESC;
where:
iotype indicates the type of I/O to perform. For text and image operations, iotype can have the value CS_IODATA or CS_IOPARTIAL. The CS_IOPARTIAL setting specifies that a partial update is to be performed on the text or image column.
datatype is the datatype of the data object. The values for datatype are CS_TEXT_TYPE and CS_IMAGE_TYPE.
locale is a pointer to a CS_LOCALE structure containing localization information for the text or image value. Set locale to NULL if localization information is not required.
Before using a CS_IODESC structure, make sure that locale is valid by setting it either to NULL or to the address of a valid CS_LOCALE structure.
usertype is the Adaptive Server user-defined datatype of the data object, if any. On send-data operations, usertype is ignored. On get-data operations, Client-Library sets usertype in addition to (not instead of) datatype.
total_txtlen is the total length, in bytes, of the text or image value.
Unicode and partial updates
If your client application performs partial updates on 2-byte Unicode datatypes,
the application must make sure that it sends an even number of bytes
to avoid a character split. You can use the buflen parameter
of ct_send_data() and
the total_txtlen field
of CS_IODESC to
specify the length, in bytes, of the Unicode data.
For partial updates to Unitext data, the offset and delete_length values
must be specified as a character count while total_txtlen must
be specified in bytes.
offset indicates the first byte in the column that is affected by a partial update.
log_on_update describes whether the server should log the update to this text or image value.
name is the name of the text or image column. name is a null-terminated string of the form table.column.
namelen is the length, in bytes, of name (not including the null terminator). When filling in a CS_IODESC, an application sets namelen to CS_NULLTERM to indicate a null-terminated name.
timestamp is the text timestamp of the column. A text timestamp marks the time of a text or image column’s last modification.
timestamplen is the length, in bytes, of timestamp.
textptr is the text pointer for the column. A text pointer is an internal server pointer that points to the data for a text or image column. textptr identifies the target column in a send-data operation.
textptrlen is the length, in bytes, of textptr.
delete_length indicates the number of bytes that are to be overwritten or deleted from column a text or image column for which a partial update has been specified.
