ct_cmd_props

Description

Set or retrieve command structure properties. For use by applications that resend commands.

Syntax

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;

Parameters

cmd: A pointer to the CS_COMMAND structure managing a client/server operation.

action

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.

property: 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.

buffer

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.

buflen

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.

outlen

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.

Returns

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”.

Examples

Example 1

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 example program. For another example using ct_cmd_props, see the rpc.c example 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    updateability[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(updateability, "read only");

     else if ((cur_status & CS_CURSTAT_UPDATABLE)

              == CS_CURSTAT_UPDATABLE)

       strcpy(updateability, "updatable");

     else

       updateability[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, updateability, status_str);

   return CS_SUCCEED;

 } /* cursor_status */

Usage

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:

**Table 3-7: Command structure properties**
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 or not 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.