cs_locator()

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.