srv_props

Description

Define and retrieve Open Server properties.

Syntax

CS_RETCODE srv_props(cp, cmd, property, bufp, buflen,
                 outlenp)

CS_CONTEXT       *cp;
CS_INT           cmd;
CS_INT           property;
CS_VOID          *bufp;
CS_INT           buflen;
CS_INT           *outlenp;

Parameters

scp: A pointer to a CS_CONTEXT structure previously allocated using cs_ctx_alloc.

cmd

The action to take. Table 3-84 summarizes the legal values for cmd:

**Table 3-84: Values for cmd (srv_props)**
Value	Meaning
CS_SET	The Open Server application is setting the property. In this case, bufp should contain the value the property is to be set to, and buflen should specify the size, in bytes, of that value.
CS_GET	The Open Server application is retrieving the property. In this case, bufp should point to the buffer where the property value is placed, and buflen should be the size, in bytes, of the buffer.
CS_CLEAR	The Open Server application is resetting the property to its default value. In this case, bufp, buflen, and outlenp are ignored.

property: The property being set, retrieved or cleared. See below for a list of this argument’s legal values.

bufp: A pointer to the Open Server application data buffer where property value information is placed (CS_SET) or property value information is retrieved (CS_GET).

buflen: The length, in bytes, of the buffer.

outlenp: A pointer to a CS_INT variable, which Open Server will set to the size, in bytes, of the property value retrieved. This argument is only used when cmd is CS_GET, and is optional.

Returns

**Table 3-85: Return values (srv_props)**
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_set_propPROTOTYPE((

CS_CONTEXT *cp,

CS_INT     property,

CS_VOID    *bufp,

CS_INT     buflen

));

/*

** EX_SRV_SET_PROP

**

**    Example routine to set a property using srv_props.

**

** Arguments:

**

**    *cp       Pointer to a CS_CONTEXT structure previously

**              allocated by cs_ctx_alloc.

**    property  The property being set.

**    *bufp     Pointer to the value the property is to be

**              set to.

**    buflen    The length of the value.

**

** Returns

**

**   CS_SUCCEED   Arguments were valid and srv_props was called.

**   CS_FAIL      An error was detected.

**

*/

CS_RETCODE      ex_srv_set_prop(cp, property, bufp, buflen)

CS_CONTEXT      *cp;

CS_INT          property;

CS_VOID         *bufp;

CS_INT          buflen;

      /* Check arguments. */

      if(cp == (CS_CONTEXT *)NULL)

            return(CS_FAIL);

      if(buflen < 1)

            return(CS_FAIL);
return(srv_props(cp,(CS_INT)CS_SET,property,bufp,buflen,

  (CS_INT *)0));

Usage

srv_props is called to define and retrieve server-wide configuration parameters and properties.

srv_version must be called before srv_props can be called.
All properties to be set by srv_props (except SRV_S_TRACEFLAG, SRV_S_LOGFILE, and SRV_S_TRUNCATELOG) must be set before srv_init is called.
After srv_init is called, setting the SRV_S_LOGFILE property with bufp set to an empty string ("") and buflen set to zero will close the log file.
Use the SRV_S_TCP_RCVBUF and SRV_S_TCP_SNDBUF server properties for setting TCP socket input and output buffer sizes. Open Server applications use these property settings to set buffer sizes with the operating system setsockopt command. Because setsockopt must be invoked before the TCP connect and accept commands, set these properties before attempting to create a connection.

Set the properties as appropriate for your application. For example, if the server is expected to be receiving a large amount of data from the client, set SRV_S_TCP_RCVBUF to a large value to increase the corresponding buffer size.

Use the CS_TCP_RCVBUF and CS_TCP_SNDBUF context/connection properties to set TCP socket input and output buffer sizes on the client side. See the Open Client Client-Library/C Reference Manual.

A server example:
```
srv_props(cp, CS_SET, SRV_S_TCP_SNDBUF, bufp, CS_SIZEOF(CS_INT), (CS_INT *)NULL);
```

Table 3-86 summarizes the server properties, whether they can be set or retrieved, and the datatype of each property value:

**Table 3-86: Server properties and their datatypes (srv_props)**
Property	SET/ CLEAR	GET	bufp when cmd is CS_SET	bufp when cmd is CS_GET
SRV_S_ALLOCFUNC	Yes	Yes	A function pointer	The address of a function pointer
SRV_S_APICHK	Yes	Yes	A CS_BOOL	A CS_BOOL
SRV_S_ATTNREASON	No	Yes	Not applicable	A CS_INT
SRV_S_CERT_AUTH	Yes	Yes	char*	char*
SRV_S_CURTHREAD	No	Yes	Not applicable	The address of a thread pointer
SRV_S_DISCONNECT	Yes	Yes	A CS_BOOL	A CS_BOOL
SRV_S_DEFQUEUESIZE	Yes	Yes	A CS_INT	A CS_INT
SRV_S_DS_PROVIDER	Yes	Yes	A pointer to a character string	A pointer to a character string
SRV_S_DS_REGISTER	Yes	Yes	A CS_BOOL	A CS_BOOL
SRV_S_ERRHANDLE	Yes	Yes	A function pointer	The address of a function pointer
SRV_S_FREEFUNC	Yes	Yes	A function pointer	The address of a function pointer
SRV_S_IFILE	Yes	Yes	A character string	A character string
SRV_S_LOGFILE	Yes	Yes	A character string	A character string
SRV_S_LOGSIZE	Yes	Yes	A CS_INT	A CS_INT
SRV_S_MAXLISTENERS	Yes	Yes	A CS_INT	A CS_INT
SRV_S_MSGPOOL	Yes	Yes	A CS_INT	A CS_INT
SRV_S_NETBUFSIZE	Yes	Yes	A CS_INT	A CS_INT
SRV_S_NETTRACEFILE	Yes	Yes	A character string	A character string
SRV_S_NUMCONNECTIONS	Yes	Yes	A CS_INT	A CS_INT
SRV_S_NUMLISTENERS	No	Yes	A CS_INT	A CS_INT
SRV_S_NUMMSGQUEUES	Yes	Yes	A CS_INT	A CS_INT
SRV_S_NUMMUTEXES	Yes	Yes	A CS_INT	A CS_INT
SRV_S_NUMREMBUF	Yes	Yes	A CS_INT	A CS_INT
SRV_S_NUMREMSITES	Yes	Yes	A CS_INT	A CS_INT
SRV_S_NUMTHREADS	Yes	Yes	A CS_INT	A CS_INT
SRV_S_NUMUSEREVENTS	Yes	Yes	A CS_INT	A CS_INT
SRV_S_PREEMPT	Yes	Yes	A CS_BOOL	A CS_BOOL
SRV_S_REALLOCFUNC	Yes	Yes	A function pointer	The address of a function pointer
SRV_S_RETPARMS	Yes	Yes	A CS_BOOL	A CS BOOL
SRV_S_REQUESTCAP	Yes	Yes	A CS_CAP_TYPE structure	A CS_CAP_TYPE structure
SRV_S_RESPONSECAP	Yes	Yes	A CS_CAP_TYPE structure	A CS_CAP_TYPE structure
SRV_S_SEC_KEYTAB	Yes	Yes	A pointer to a character string	A pointer to a character string
SRV_S_SEC_PRINCIPAL	Yes	Yes	A pointer to a character string	A pointer to a character string
SRV_S_SERVERNAME	No	Yes	A character string	A character string
SRV_S_SSL_CIPHER	Yes	No	char*
SRV_S_SSL_LOCAL_ID	Yes	Yes	struct	char*
SRV_S_SSL_VERSION	Yes	No	CS_INT
SRV_S_STACKSIZE	Yes	Yes	A CS_INT	A CS_INT
SRV_S_TCP_RCVBUF	Yes	Yes	A CS_INT	A CS_INT
SRV_S_TCP_SNDBUF	Yes	Yes	A CS_INT	A CS_INT
SRV_S_TDSVERSION	Yes	Yes	A CS_INT	A CS_INT
SRV_S_TIMESLICE	Yes	Yes	A CS_INT	A CS_INT
SRV_S_TRACEFLAG	Yes	Yes	A CS_INT (bit mask)	A CS_INT (bit mask)
SRV_S_TRUNCATELOG	Yes	Yes	A CS_BOOL	A CS_BOOL
SRV_S_USESRVLANG	Yes	Yes	A CS_BOOL	A CS_BOOL
SRV_S_VERSION	No	Yes	Not applicable	A character string
SRV_S_VIRTCLKRATE	Yes	Yes	A CS_INT	A CS_INT
SRV_S_VIRTTIMER	Yes	Yes	A CS_BOOL	A CS_BOOL

Table 3-87 lists the default value for each server property:

**Table 3-87: Legal properties and their default values (srv_props)**
Property	Default
SRV_S_ALLOCFUNC	malloc()
SRV_S_APICHK	CS_TRUE
SRV_S_ATTNREASON	No default
SRV_S_CURTHREAD	N/A.
SRV_S_DEFQUEUESIZE	SRV_DEF_DEFQUEUESIZE
SRV_S_DISCONNECT	CS_FALSE
SRV_S_DS_PROVIDER	Platform dependent. Refer to the Open Client and Open Server Configuration Guide for your platform.
SRV_S_DS_REGISTER	CS_TRUE, Server-Library registers itself with a directory on start-up.
SRV_S_ERRHANDLE	No error handler
SRV_S_FREEFUNC	free()
SRV_S_IFILE	$SYBASE/interfaces
SRV_S_LOGFILE	srv.log
SRV_S_LOGSIZE	Max integer value
SRV_S_MAXLISTENERS	CS_MAX_NOMAX
SRV_S_MSGPOOL	SRV_DEF_MSGPOOL
SRV_S_NETBUFSIZE	SRV_DEF_NETBUFSIZE
SRV_S_NETTRACEFILE	sybnet.dbg
SRV_S_NUMCONNECTIONS	SRV_DEF_NUMCONNECTIONS
SRV_S_NUMLISTENERS	N/A.
SRV_S_NUMMSGQUEUES	SRV_DEF_NUMMSGQUEUES
SRV_S_NUMMUTEXES	SRV_DEF_NUMMUTEXES
SRV_S_NUMREMBUF	SRV_DEF_NUMREMBUF
SRV_S_NUMREMSITES	SRV_DEF_NUMREMSITES
SRV_S_NUMTHREADS	SRV_DEF_NUMTHREADS
SRV_S_NUMUSEREVENTS	SRV_DEF_NUMUSEREVENTS
SRV_S_PREEMPT	CS_FALSE
SRV_S_REALLOCFUNC	realloc()
SRV_S_REQUESTCAP	See “Capabilities”
SRV_S_RESPONSECAP	See “Capabilities”
SRV_S_RETPARMS	No default
SRV_S_SEC_KEYTAB	No default
SRV_S_SEC_PRINCIPAL	Security mechanism dependent
SRV_S_SERVERNAME	DSLISTEN environment variable
SRV_S_STACKSIZE	SRV_DEF_STACKSIZE
SRV_S_TCP_RCVBUF	Platform dependent.
SRV_S_TCP_SNDBUF	Platform dependent.
SRV_S_TDSVERSION	SRV_TDS_5_0
SRV_S_TIMESLICE	SRV_DEF_TIMESLICE
SRV_S_TRACEFLAG	0
SRV_S_TRUNCATELOG	CS_FALSE
SRV_S_USESRVLANG	CS_TRUE
SRV_S_VERSION	Compile-time version string
SRV_S_VIRTCLKRATE	SRV_DEF_VIRTCLKRATE
SRV_S_VIRTTIMER	CS_FALSE

All server properties that have a default and are settable can be reset back to the default value by calling srv_props with cmd set to CS_CLEAR.

All server properties can be retrieved at any time by calling srv_props with cmd set to CS_GET. If the Open Server application has not defined a value for a property, the default value is returned.

For a description of properties, see the Properties topic page.

When a property is being retrieved, if buflen indicates that the user buffer is not big enough to hold the property value, Open Server will place the number of bytes required in *outlenp, and the user buffer will not be modified.

The default stacksize (default value for SRV_S_STACKSIZE) depends on the platform used.

For native-threaded versions of Open Server, the default stacksize of underlying threads is used. This value can be changed by setting the stacksize with the SRV_S_STACKSIZE property.

Note that when setting the stacksize, stack overflow errors may occur if the specified stacksize is too small.