Set or retrieve command structure properties. For use by applications that resend commands.
CS_RETCODE ct_cmd_props(cmd, action, property, buffer,
buflen, outlen)
CS_COMMAND *cmd;
CS_INT action;
CS_INT property;
CS_VOID *buffer;
CS_INT buflen;
CS_INT *outlen;
A pointer to the CS_COMMAND structure managing a client/server operation.
One of the following symbolic values:
Value of action |
Meaning |
|---|---|
CS_SET |
Sets the value of the property. |
CS_GET |
Retrieves the value of the property. |
CS_CLEAR |
Clears the value of the property by resetting it to its Client-Library default value. |
The symbolic name of the property whose value is being set or retrieved. The Properties lists all Client-Library properties. For a summary of the properties that are legal with ct_cmd_props, see Table 3-7.
If a property value is being set, buffer points to the value to use in setting the property.
If a property value is being retrieved, buffer points to the space in which ct_cmd_props will place the requested information.
Generally, buflen is the length, in bytes, of *buffer.
If a property value is being set and the value in *buffer is a null-terminated string, pass buflen as CS_NULLTERM.
If *buffer is a fixed-length or symbolic value, pass buflen as CS_UNUSED.
A pointer to an integer variable.
If a property value is being set, outlen is not used and should be passed as NULL.
If a property value is being retrieved and outlen is supplied, ct_cmd_props sets *outlen to the length, in bytes, of the requested information.
If the information is larger than buflen bytes, the call will fail. The application can use the value of *outlen to determine how many bytes are needed to hold the information.
ct_cmd_props returns the following values:
Return value |
Meaning |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
CS_BUSY |
An asynchronous operation is already pending for this connection. See “Asynchronous programming”. |
Example for Command-Level User Data
The following code fragment retrieves the CS_USERDATA property value. This code excerpt is from the ex_alib.c sample program. For another example using ct_cmd_props, see the rpc.c sample program.
/*
** Extract the user area out of the command handle.
*/
retstat = ct_cmd_props(cmd, CS_GET, CS_USERDATA,
&ex_async, CS_SIZEOF(ex_async), NULL);
if (retstat != CS_SUCCEED)
{
return retstat;
}
Example for Cursor Status
This code fragment shows a function cursor_status that calls ct_cmd_props to retrieve status information about a Client-Library cursor.
#define RETURN_IF(a,b) if (a != CS_SUCCEED)\
{ fprintf(stderr, "Error in: %s line %d\n", \
b, __LINE__); return a ;}
/*
** cursor_status() -- Print status information about the
** Client-Library cursor (if any) declared on a CS_COMMAND
** structure.
**
** PARAMETERS:
** cmd -- an allocated CS_COMMAND structure.
**
**
** RETURNS
** CS_FAIL if an error occurred.
** CS_SUCCEED if everything went ok.
*/
CS_RETCODE
cursor_status(cmd)
CS_COMMAND *cmd;
{
CS_RETCODE ret;
CS_INT cur_status;
CS_INT cur_id;
CS_CHAR cur_name[CS_MAX_NAME];
CS_CHAR updatability[CS_MAX_NAME];
CS_CHAR status_str[CS_MAX_NAME];
CS_INT outlen;
/*
** Get the cursor status property.
*/
ret = ct_cmd_props(cmd, CS_GET, CS_CUR_STATUS, &cur_status,
CS_UNUSED, (CS_INT *) NULL);
RETURN_IF(ret, "cursor_status: ct_cmd_props(CUR_STATUS)");
/*
** Is there a cursor?
** Note that CS_CURSTAT_NONE is not a bitmask, but the
** other values are.
*/
if (cur_status == CS_CURSTAT_NONE)
fprintf(stdout,
"cursor_status: no cursor on this command structure\n");
else
{
/*
** A cursor exists, so check its state. Is it
** declared, opened, or closed?
*/
if ((cur_status & CS_CURSTAT_DECLARED)
== CS_CURSTAT_DECLARED)
strcpy(status_str, "declared");
if ((cur_status & CS_CURSTAT_OPEN) == CS_CURSTAT_OPEN)
strcpy(status_str, "open");
if ((cur_status & CS_CURSTAT_CLOSED) == CS_CURSTAT_CLOSED)
strcpy(status_str, "closed");
/*
** Is the cursor updatable or read only?
*/
if ((cur_status & CS_CURSTAT_RDONLY) == CS_CURSTAT_RDONLY)
strcpy(updatability, "read only");
else if ((cur_status & CS_CURSTAT_UPDATABLE)
== CS_CURSTAT_UPDATABLE)
strcpy(updatability, "updatable");
else
updatability[0] = '\0';
/*
** Get the cursor id.
*/
ret = ct_cmd_props(cmd, CS_GET, CS_CUR_ID, &cur_id,
CS_UNUSED, (CS_INT *) NULL);
RETURN_IF(ret, "cursor_status: ct_cmd_props(CUR_ID)");
/*
** Get the cursor name.
*/
ret = ct_cmd_props(cmd, CS_GET, CS_CUR_NAME, cur_name,
CS_MAX_NAME, &outlen);
RETURN_IF(ret, "cursor_status: ct_cmd_props(CUR_NAME)");
/*
** Null terminate the name.
*/
if (outlen < CS_MAX_NAME)
cur_name[outlen] = '\0';
else
RETURN_IF(CS_FAIL, "cursor_status: name too long");
/* Print it all out */
fprintf(stdout, "Cursor '%s' (id %d) is %s and %s.\n",
cur_name, cur_id, updatability, status_str);
}
return CS_SUCCEED;
} /* cursor_status */
Example for Scrollable Cursor Status
The code fragment for scrollable cursors is identical to the previous example, with the exception of the following extract:
/*
** Is the cursor scrollable or read-only?
*/
if (( cur_status & CS_CURSTAT_SCROLLABLE == CS_CURSTAT_SCROLLABLE )
strcpy(updatability, "scrollable")
else if ((cur_status & CS_CURSTAT_RDONLY) == CS_CURSTAT_RDONLY)
strcpy(updatability, "read-only")
else
updatability[0] = '\0';
For information about action, buffer, buflen, and outlen, see Chapter 2, “Understanding Structures, Constants, and Conventions,” in the Open Client Client-Library/C Programmer's Guide.
Command structure properties affect the behavior of an application at the command structure level.
All command structures allocated for a connection pick up default property values from the parent connection. An application can override these default values by calling ct_cmd_props.
If an application changes connection property values after allocating command structures for the connection, the existing command structures will not pick up the new property values. New command structures allocated for the connection will use the new property values as defaults.
See “Properties” for more information about properties.
An application can use ct_cmd_props to set or retrieve the properties listed in Table 3-7:
Property |
Meaning |
*buffer value |
Level |
Notes |
|---|---|---|---|---|
CS_CUR_ID |
The cursor’s identification number. |
Set to an integer value. |
Command. |
Retrieve only, after CS_CUR_STATUS indicates an existing cursor. |
CS_CUR_NAME |
The cursor’s name, as defined in an application’s ct_cursor(CS_CUR SOR_DECLARE) call. |
Set to a null-terminated character string. |
Command. |
Retrieve only, after ct_cursor(CS_CURSOR_DECLARE) returns CS_SUCCEED. |
CS_CUR_ ROWCOUNT |
The current value of cursor rows. Cursor rows is the number of rows returned to Client-Library per internal fetch request. |
Set to an integer value. |
Command. |
Retrieve only, after CS_CUR_STATUS indicates an existing cursor. |
CS_CUR_STATUS |
The cursor’s status. |
A CS_INT value. See “Cursor status” for possible values. |
Command. |
Retrieve only. |
CS_HAVE_BINDS |
Whether any saved result bindings are present for the current result set. |
CS_TRUE or CS_FALSE. A default is not applicable. |
Command. |
Retrieve only. |
CS_HAVE_CMD |
Whether a resendable command exists for the command structure. |
CS_TRUE or CS_FALSE |
Command. |
Retrieve only. |
CS_HAVE_ CUROPEN |
Whether or not a restorable cursor-open command exists for the command structure. |
CS_TRUE or CS_FALSE |
Command. |
Retrieve only. |
CS_HIDDEN_KEYS |
Whether or not to expose hidden keys. |
CS_TRUE or CS_FALSE. The default is CS_FALSE. |
Context, connection, or command. |
Cannot be set at the command level if results are pending or a cursor is open. |
CS_PARENT_ HANDLE |
The address of the command structure’s parent connection. |
Set to an address. |
Connection or command. |
Retrieve only. |
CS_STICKY_BINDS |
Whether or not bindings between result items and program variables persist when a command is executed repeatedly. |
CS_TRUE or CS_FALSE. The default is CS_FALSE. |
Command. |
|
CS_USERDATA |
User-allocated data. |
User-allocated data. |
Connection or command. To set CS_ USERDATA at the context level, call cs_config. |
None. |
