Client-Library changes

The CS_LOCATOR datatype supports LOB locator. The cs_locator_alloc() and cs_locator_drop() APIs allocate and deallocate memory for CS_LOCATOR variables. cs_locator() has been added to retrieve information from a CS_LOCATOR variable.

Client-Library routines cs_convert() and ct_bind() have been enhanced to handle CS_LOCATOR variables.

CS_LOCATOR is an opaque datatype that stores locator values and optional prefetched data. Use cs_locator_alloc() to allocate memory for a CS_LOCATOR variable before binding the incoming locator to the variable, otherwise, an error occurs. When the variable is no longer needed, use cs_locator_drop() to free its memory.

CS_LOCATOR variables can be reused, however, the current locator value in Adaptive Server is valid only until the transaction ends.

The type constants for CS_LOCATOR are:

• CS_TEXTLOCATOR_TYPE – for text LOBs.

• CS_IMAGELOCATOR_TYPE – for image LOBs.

• CS_UNITEXTLOCATOR_TYPE – for unitext LOBs.

Use cs_convert() to retrieve the locator’s prefetched data and the character representation of the locator value from the CS_LOCATOR variable. Converting CS_LOCATOR to a CS_CHAR returns the locator’s hexadecimal value as a string. Converting the locator to CS_TEXT_TYPE, CS_IMAGE_TYPE, or CS_UNITEXT_TYPE returns the locator’s prefetched data.

When working with locator datatypes:

• ct_bind() ignores the maxlength value of CS_DATAFMT because Client-Library considers the length of locator datatypes as fixed. Memory required for any optional prefetched data that is sent with the locator is allocated internally for its entire length. The maxlength value does not influence the length of the prefetched data.

• You can bind an incoming LOB locator to CS_CHAR_TYPE. You cannot, however, directly bind a locator to CS_TEXT_TYPE, CS_IMAGE_TYPE, or CS_UNITEXT_TYPE.

Retrieves information from a CS_LOCATOR variable, such as prefetched data, the total length of the LOB in the server, or the character representation of the locator pointer.

CS_RETCODE cs_locator(ctx, action, locator, type, buffer, buflen,
   outlen)

CS_CONTEXT        *ctx;
CS_INT                    action;
CS_LOCATOR        *locator;
CS_INT                    type;
CS_VOID                *buffer;
CS_INT                   buflen;
CS_INT                     *outlen;

• ctx – a pointer to a CS_CONTEXT structure.

• action – specifies whether to set or retrieve information. Currently, the only action allowed is CS_GET.

• locator – a pointer to the locator variable.

• type – type of information to retrieve or set. Symbolic values:

  Value	Action	*buffer points to	Description
  CS_LCTR_LOBLEN	CS_GET	CS_BIGINT	Retrieves the total length of the LOB data in the server.
  CS_LCTR_LOCATOR	CS_GET	CS_CHAR	Retrieves the locator value as a character string.
  CS_LCTR_PREFETCHLEN	CS_GET	CS_INT	Retrieves the length of the prefetched LOB data contained in the locator variable.
  CS_LCTR_PREFETCHDATA	CS_GET	CS_CHAR	Retrieves the prefetched LOB data contained in the locator variable.
  CS_LCTR_DATATYPE	CS_GET	CS_INT	Retrieves the locator type. Valid return types are CS_TEXTLOCATOR_TYPE, CS_IMAGELOCATOR_TYPE, and CS_UNITEXTLOCATOR_TYPE.

• buffer – a pointer to the variable to store data to. Character data is NULL terminated.

• buflen – *buffer length, in bytes.

• outlen – a pointer to a CS_INT variable. If outlen is not NULL, cs_locator() sets *outlen to the length, in bytes, of the data placed in *buffer. If the data returned is a character data (for example, a prefetched data or locator string), the length returned in *outlen includes the NULL terminator. If cs_locator() returns CS_TRUNCATED and outlen is not NULL, then cs_locator() returns the required buffer size in *outlen.

Allocates a CS_LOCATOR datatype structure.

CS_RETCODE cs_locator_alloc(ctx, locator)

CS_CONTEXT *ctx;
CS_LOCATOR **locator;

• ctx – a pointer to a CS_CONTEXT structure.

• locator – the address of a locator variable to be allocated. Sets *locator to the address of a newly allocated CS_LOCATOR structure.

Deallocates a CS_LOCATOR datatype structure.

CS_RETCODE cs_locator_drop(ctx, locator)

CS_CONTEXT *ctx;
CS_LOCATOR *locator;

• ctx – a pointer to a CS_CONTEXT structure.

• locator – a pointer to the locator variable to be deallocated.

isql displays the LOB locator value in its hexadecimal character form. Prefetched data stored in CS_LOCATOR does not appear.

1> set send_locator on
2> go

1> select * from testable
2> go

charcol         textcol
--------------- --------------------------------------------------
Hello           0x48656c6c6f20576f726c642e2048657265204920616d2e2e