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;
A pointer to a CS_CONTEXT structure.
Specifies whether to set or retrieve information. Currently, the only action allowed is CS_GET.
Pointer to the locator variable.
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. |
A pointer to the variable in which to store. Character data is NULL terminated.
*buffer length, in bytes.
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, cs_locator() returns the required buffer size in *outlen.
Return value |
Meaning |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_TRUNCATED |
The result has been truncated because the buffer is too small. |
CS_FAIL |
The routine failed. |
Retrieves the LOB locator for a text value that needs to be truncated. See the Open Client Client-Library/C Reference Manual for more code examples.
CS_LOCATOR *lobloc;
CS_INT prefetchsize;
CS_BOOL boolval;
CS_INT start, length;
CS_INT outlen;
CS_CHAR charbuf[1024];
CS_BIGINT totallen;
...
/*
** Turn on option CS_LOBLOCATOR first and set the prefetchsize to 100.
*/boolval = CS_TRUE;
ct_options(conn, CS_SET, CS_OPT_LOBLOCATOR, &boolval, CS_UNUSED, NULL);
prefetchsize = 100;
ct_options(conn, CS_SET, CS_OPT_LOBPREFETCHSIZE, \
&prefetchsize, CS_UNUSED, NULL);
/*
** Allocate memory for the CS_LOCATOR.
*/
cs_locator_alloc(ctx, &lobloc);
/*
** Open a transaction and get the locator. The locator is only valid within a
** transaction.
*/
sprintf(cmdbuf, "begin transaction \
select au_id, copy from pubs2..blurbs where au_id \
like ‘486-29-%’");
ct_command(cmd, CS_LANG_CMD, cmdbuf , CS_NULLTERM, CS_UNUSED);
ct_send(cmd);
/*
** Process results.
*/
while ((results_ret = ct_results(...)) == CS_SUCCEED)
{
...}
/*
** Bind the locator and fetch it.
*/
strcpy(prmfmt.name, "@locatorparam");
prmfmt.namelen = CS_NULLTERM;
prmfmt.datatype = CS_TEXTLOCATOR_TYPE;
prmfmt.maxlength = CS_UNUSED;
...
ct_bind(cmd, 1, &fmt, lobloc, NULL, &indicator);
ct_fetch(cmd, CS_UNUSED, CS_UNUSED, CS_UNUSED, &count);
}
/*
** Use the cs_locator() routine to retrieve data from the fetched locator.
** Get the prefetch length and the prefetch data.
*/
cs_locator(ctx, CS_GET, lobloc, CS_LCTR_PREFETCHLEN, \
(CS_VOID *)&prefetchsize, sizeof(CS_INT), &outlen);
cs_locator(ctx, CS_GET, lobloc, CS_LCTR_PREFETCHDATA, \
(CS_VOID *)charbuf, sizeof(charbuf), &outlen);
/*
** Retrieve the total length of the LOB data in the server for this
** locator.
*/
cs_locator(ctx, CS_GET, lobloc, CS_LCTR_LOBLEN, \
(CS_VOID *)&totallen,
sizeof(totallen), &outlen);
/*
** Use the retrieved locator to perform an action to the LOB, pointed to by
** this locator in the server.
**
** Get a substring from the text in the server, using a parameterized
** language command.
*/
start = 10;
length = 20;
sprintf(cmdbuf, "select return_lob(text, substring(@locatorparam, \
start, length))");
ct_command(cmd, CS_LANG_CMD, cmdbuf, CS_NULLTERM, CS_UNUSED);
/*
** Set the format structure and call ct_param()
*/
strcpy(prmfmt.name, "@locatorparam");
prmfmt.namelen = CS_NULLTERM;
prmfmt.datatype = CS_TEXTLOCATOR_TYPE;
prmfmt.format = CS_FMT_UNUSED;
prmfmt.maxlength = CS_UNUSED;
prmfmt.status = CS_INPUTVALUE;
indicator = 0;
ct_param(cmd, &prmfmt, (CS_VOID *)lobloc, CS_UNUSED, indicator);
/*
** Send the locator commands to the server.
*/
ct_send(cmd);
/*
** Process results.
*/
while ((results_ret = ct_results(...)) == CS_SUCCEED)
{
...
}
/*
** Truncate the text to 20 bytes and commit the transaction.
*/
sprintf(cmdbuf, "truncate lob @locatorparam (length) \
commit transaction");
ct_command(cmd, CS_LANG_CMD, cmdbuf, CS_NULLTERM, CS_UNUSED);
ct_param(cmd, &prmfmt, (CS_VOID *)lobloc, CS_UNUSED, indicator);
ct_send(cmd);
/*
** Process results.
*/
while ((results_ret = ct_results(...)) == CS_SUCCEED)
{
...
}
/*
** The transaction is closed, deallocate the locator.
*/
cs_locator_drop(ctx, lobloc);
