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.

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:

Return value	Meaning
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed. If ct_options returns CS_FAIL, *param remains untouched.
CS_CANCELED	The operation was canceled.
CS_PENDING	Asynchronous network I/O is in effect. See “Asynchronous programming”.
CS_BUSY	An asynchronous operation is already pending for this connection. See “Asynchronous programming”.

Usage

**Table 3-45: Summary of ct_options parameters**
Value of option	Value of *param	Legal Values for *param	Default
CS_OPT_ANSINULL	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_ANSIPERM	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_ARITHABORT	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_ARITHIGNORE	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_AUTHOFF	A string value representing an authority level.	A string value. Possible values include “sa”, “sso”, and “oper.”	Not applicable
CS_OPT_AUTHON	A string value representing an authority level.	A string value. Possible values include “sa”, “sso”, and “oper.”	Not applicable
CS_OPT_CHAINXACTS	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_CHARSET	The name of a language that is supported and found on the locale.dat file. Used to set the language or character set on an open connection.	A value representing a language, for your platform, on the locales.dat file.	NULL
CS_OPT_CURCLOSEONXACT	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_DATEFIRST	A symbolic value representing the day to use as the first day of the week.	CS_OPT_SUNDAY, CS_OPT_MONDAY, CS_OPT_TUESDAY, CS_OPT_WEDNESDAY, CS_OPT_THURSDAY, CS_OPT_FRIDAY, CS_OPT_SATURDAY	For us_english, the default is CS_OPT_ SUNDAY.
CS_OPT_DATEFORMAT	A symbolic value representing the order of year, month, and day to be used in datetime values.	CS_OPT_FMTMDY, CS_OPT_FMTDMY, CS_OPT_FMTYMD, CS_OPT_FMTYDM, CS_OPT_FMTMYD, CS_OPT_FMTDYM	For us_english, the default is CS_OPT_ FMTMDY.
CS_OPT_FIPSFLAG	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_FORCEPLAN	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_FORMATONLY	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_GETDATA	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_HIDE_VCC	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_IDENTITYOFF	A string value representing a table name.	A string value.	NULL
CS_OPT_IDENTITYON	A string value representing a table name.	A string value.	NULL
CS_OPT_IDENTITYUPD_OFF	Disable the identity update option.	A string value.	NULL
CS_OPT_IDENTITYUPD_ON	Enable the identity update option.	A string value.	NULL
CS_OPT_ISOLATION	A symbolic value representing the transaction isolation level.	CS_OPT_LEVEL1, CS_OPT_LEVEL0, CS_OPT_LEVEL3 CS_OPT_LEVEL0 requires Adaptive Server version 11.0 or later.	CS_OPT_ LEVEL1
CS_OPT_NATLANG	The name of a language that is supported and found on the locale.dat file. Used to set the language or character set on an open connection.	A value representing a language, for your platform, on the locales.dat file.	NULL
CS_OPT_NOCOUNT	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_NOEXEC	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_PARSEONLY	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_QUOTED_ IDENT	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_RESTREES	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_ROWCOUNT	The maximum number of rows that can be affected by a query. Limits the number of regular rows returned by a select or the number of rows changed by an update or delete.	An integer value. 0 means there is no limit.	0, no limit
CS_OPT_SHOW_FI	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_SHOWPLAN	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_STATS_IO	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_STATS_TIME	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_STR_RTRUNC	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE
CS_OPT_TEXTSIZE	The length, in bytes, of the longest text or image value the server should return.	An integer value.	32,768 bytes
CS_OPT_TRUNCIGNORE	A Boolean value.	CS_TRUE, CS_FALSE	CS_FALSE

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