ct_options

Description

Set, retrieve, or clear the values of server query-processing options.

Syntax

CS_RETCODE ct_options(connection, action, option,
                  param, paramlen, outlen)
 
 CS_CONNECTION    *connection;
 CS_INT                      action;
 CS_INT                      option;
 CS_VOID                   *param;
 CS_INT                      paramlen;
 CS_INT                      *outlen;

Parameters

connection

A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.

connection is the server connection for which the option is set, retrieved, or cleared.

action

One of the following symbolic values:

Value of action	Result
CS_SET	Sets the option.
CS_GET	Retrieves the option.
CS_CLEAR	Clears the option by resetting it to its default value. Default values are determined by the server to which an application is connected.

option

The server option of interest. Table 3-45 lists the symbolic values for option. For more information about these options, see “Options”.

param

All options take parameters.

When setting an option, param can point to a symbolic value, a Boolean value, an integer value, or a character string.

For example:

• The CS_OPT_DATEFIRST option takes a symbolic value as a parameter:

       CS_INT       parmvalue;
  

        parmamvalue = CS_OPT_TUESDAY;
  

        ct_options(conn, CS_SET, CS_OPT_DATEFIRST,
  

             &paramvalue, CS_UNUSED, NULL);
  

• The CS_OPT_CHAINXACTS option takes a Boolean value as a parameter:

       CS_BOOL    parmvalue;
  

        parmamvalue = CS_TRUE;
  

        ct_options(conn, CS_SET, CS_OPT_CHAINXACTS,
  

             &paramvalue, CS_UNUSED, NULL);
  

• The CS_OPT_ROWCOUNT option takes an integer as a parameter:

       CS_INT       parmvalue;
  

        paramvalue = 50;
  

        oc_options(conn, CS_SET, CS_OPT_ROWCOUNT,
  

             &paramvalue, CS_UNUSED, NULL);
  

• The CS_OPT_IDENTITYOFF option takes a character string as a parameter:

       ct_options(conn, CS_SET, CS_OPT_IDENTITYOFF,
  

             "authors", CS_NULLTERM, NULL);
  

  When retrieving an option, param points to the space in which ct_options places the value of the option.

  If paramlen indicates that *param is not large enough to hold the option’s value, ct_option sets *outlen to the length of the value and returns CS_FAIL.

  When clearing an option, param must be NULL.

paramlen

The length, in bytes, of *param.

When setting or retrieving an option that takes a fixed-length parameter, pass paramlen as CS_UNUSED.

When setting an option that takes a character string parameter, if the value in *param is null-terminated, pass paramlen as CS_NULLTERM.

When retrieving an option, if paramlen indicates that *param is not large enough to hold the requested information, ct_options sets *outlen to the length of the requested information and returns CS_FAIL.

When clearing an option, paramlen must be CS_UNUSED.

outlen

A pointer to an integer variable.

If an option is being set or cleared, outlen is not used and must be passed as NULL.

If an option is being retrieved, ct_options sets *outlen to the length, in bytes, of the option’s value. This length includes a null terminator, if applicable.

If the option’s value is larger than paramlen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information.

Returns

ct_options returns the following values:

Usage

• Although query-processing options can be set and cleared through the Transact-SQL set command, it is recommended that Client-Library applications use ct_options instead. This is because ct_options allows an application to check the status of an option, which cannot be done through the set command.

• An application can use ct_options to change server options only for a single connection at a time. The connection must be open and must have no active commands or pending results, but can have an open cursor.

• The routine ct_connect optionally reads a section from the Open Client/Server runtime configuration file to set server options for a newly opened connection. For a description of this feature, see “Using the runtime configuration file”.

See also

ct_capability, ct_con_props, “Options”

---

Copyright © 2003. Sybase Inc. All rights reserved.

View this book as PDF