srv_options

Description

Send option information to a client or receive option information from a client.

Syntax

CS_RETCODE srv_options(spp, cmd, optcmdp, optionp,

    bufp, bufsize, outlenp)

SRV_PROC    *spp;
CS_INT           cmd;
CS_INT           *optcmdp;
CS_INT           *optionp;
CS_CHAR       *bufp;
CS_INT           bufsize;
CS_INT          *outlenp;

Parameters

spp: A pointer to an internal thread control structure.

cmd

Indicates whether the application is calling srv_options to send or receive option information. Table 3-74 describes the legal values for cmd:

**Table 3-74: Values for cmd (srv_options)**
Value	Description
CS_SET	The Open Server application is sending an option command to a client.
CS_GET	The Open Server application is receiving an option command from a client.

optcmdp

A pointer either to the program variable that will contain a client’s option command (CS_GET) or to the program variable that contains the Open Server application’s option command (CS_SET). Table 3-75 summarizes the legal values for *optcmdp:

**Table 3-75: Values for optcmdp (srv_options)**
Value	Description	Cmd
SRV_SETOPTION	The client is requesting that the option be set. The value associated with optionp is returned in bufp. Open Server will set bufsize* to the size, in bytes, of the data returned. If bufp is not large enough to hold the data, the function will return CS_FAIL, the actual size of the option value, in bytes, is returned in outlenp, and the values of optionp and bufp will remain undefined.	CS_GET
SRV_CLEAROPTION	The client is requesting that optionp be set to its default value. The bufp and optionp values will remain undefined.	CS_GET
SRV_GETOPTION	A client is requesting information on the current value in optionp. The bufp* and optionp values will remain undefined.	CS_GET
SRV_SENDOPTION	The application is sending the current option value to the client in response to a SRV_GETOPTION command. bufp points to the argument associated with the option, and bufsize holds the size, in bytes, of the data in *bufp.	CS_SET

optionp: A pointer either to the client’s requested option (CS_GET) or to the option with which the Open Server application is responding (CS_SET).

bufp: A pointer to a buffer that will contain either the value associated with the option (CS_GET) or the value of the option to be sent to the requestor (CS_SET). The *optionp contains the option in question and *bufp contains its value (on a CS_SET). For a complete list of options and their legal values, see below.

bufsize: The length of the *bufp buffer. When sending an option that takes a character string option value, if the value in bufp is null terminated, pass bufsize as CS_NULLTERM.

outlenp: A pointer to a program variable which is set to the size, in bytes, of the option value returned in *bufp. This parameter is only used when cmd is set to CS_GET, and is optional.

Returns

**Table 3-76: Return values (srv_options)**
Returns	To indicate
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.

Examples

Example 1

#include  <ospublic.h>

/*

** Local Prototype

*/

CS_RETCODE    ex_srv_options PROTOTYPE((

SRV_PROC      *spp,

CS_INT        *rowcount

));

/*

** EX_SRV_OPTIONS

**

**    Example routine to recieve option information for the

 **    maximum number of regular rows to return (CS_OPT_ROWCOUNT)

 **    from a client.

**

** Arguments:

**   spp       A pointer to an internal thread control structure.

**   rowcount  Return pointer for the number of rows to return.

**

** Returns:

**

**    CS_SUCCEED   Successfully retrieved option.

**    CS_FAIL      An error was detected.

*/

CS_RETCODE       ex_srv_options(spp, rowcount)

SRV_PROC         *spp;

CS_INT           *rowcount;

    CS_INT       optcmdp;    /* The client’s option command. */

    CS_INT       optionp;    /* The client’s option request. */

    /* Initialization. */

    optcmdp = SRV_GETOPTION;

    optionp = CS_OPT_ROWCOUNT;

/*

    ** Get the maximum number of rows to return.

*/

    if (srv_options(spp, CS_GET, &optcmdp, &optionp, (CS_VOID

         *)rowcount, CS_SIZEOF(CS_INT), (CS_INT *)NULL) !=

         CS_SUCCEED)

        return(CS_FAIL);

    return(CS_SUCCEED);

Usage

srv_options allows an Open Server application to read option information from a client or send option information to a client.

Table 3-77 summarizes the valid options, their legal values, and the datatype of the optionp parameter:

**Table 3-77: Description of options (srv_options)**
Option	Legal value	bufp points to
CS_OPT_ANSINULL	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_ANSIPERM	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_ARITHABORT	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_ARITHIGNORE	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_AUTHOFF	CS_OPT_SA, CS_OPT_SSO, CS_OPT_OPER	A character string
CS_OPT_AUTHON	CS_OPT_SA, CS_OPT_SSO, CS_OPT_OPER	A character string
CS_OPT_CHAINXACTS	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_CURCLOSEONXACT	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_CURREAD	Read label (string)	A character string
CS_OPT_CURWRITE	Write label (string)	A character string
CS_OPT_DATEFIRST	CS_OPT_SUNDAY CS_OPT_MONDAY CS_OPT_TUESDAY CS_OPT_WEDNESDAY CS_OPT_THURSDAY CS_OPT_FRIDAY CS_OPT_SATURDAY	A symbolic value representing the day to use as the first day of the week
CS_OPT_DATEFORMAT	CS_OPT_FMTMDY CS_OPT_FMTDMY CS_OPT_FMTYMD CS_OPT_FMTYDM CS_OPT_FMTMYD CS_OPT_FMTDYM	A symbolic value representing the order of year, month and day to be used in datetime values
CS_OPT_FIPSFLAG	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_FORCEPLAN	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_FORMATONLY	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_GETDATA	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_IDENTITYOFF	A string value representing a table name	A character string
CS_OPT_IDENTITYON	A string value representing a table name	A character string
CS_OPT_ISOLATION	CS_OPT_LEVEL1 CS_OPT_LEVEL3	A symbolic value representing the isolation level
CS_OPT_NOCOUNT	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_NOEXEC	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_PARSEONLY	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_QUOTED_IDENT	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_RESTREES	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_ROWCOUNT	The maximum number of regular rows to return	A CS_INT 0 means all rows are returned
CS_OPT_SHOWPLAN	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_STATS_IO	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_STATS_TIME	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_STR_RTRUNC	CS_TRUE, CS_FALSE	A CS_BOOL
CS_OPT_TEXTSIZE	The length, in bytes, of the longest text or image value the server should return	A CS_INT
CS_OPT_TRUNCIGNORE	CS_TRUE, CS_FALSE	A CS_BOOL

“Options” describes each option and lists its default value.

Open Server raises a SRV_OPTION event for each option command received from a client. Inside its SRV_OPTION event handler, the application can then call srv_options with cmd set to CS_GET to retrieve the option information. When srv_options returns, optcmdp, optionp, and *bufp will contain all of the option information received from the client. It is an error to call srv_options in any event handler other than a SRV_OPTION event handler.
In response to SRV_SETOPTION and SRV_CLEAROPTION, the application must call srv_senddone with an argument of SRV_DONE_FINAL. If option processing is unsuccessful, the application must call srv_senddone with an argument of SRV_DONE_FINAL | SRV_DONE_ERROR.
The application must respond to every SRV_GETOPTION command it receives with a call to srv_options, with optcmdp set to SRV_SENDOPTION and bufp pointing to the current value of the option.
It is the application’s responsibility to ensure that the *bufp buffer is large enough to receive arguments sent by a client with a SRV_SETOPTION command. If the buffer is not large enough, srv_options will return CS_FAIL and outlenp will be set to the required size.
Open Server has no notion of what particular options mean. It is the Open Server application’s responsibility to save the client’s option commands and perform any actions that they require. If there is no SRV_OPTION event handler installed, option commands received from clients will be rejected with an error.