srv_setcontrol

Describe user control or format information for columns.

CS_RETCODE srv_setcontrol(spp, colnum, ctrlinfop,
                 ctrllen)

SRV_PROC         *spp;
CS_INT                colnum;
CS_BYTE            *ctrlinfop;
CS_INT              ctrllen;

colnum: The number of the column to which the control information applies. The first column in a row is column number 1.

ctrlinfop: A pointer to the control data. Its length is given by the ctrllen parameter.

ctrllen: The length, in bytes, of the control data. There are, at most, SRV_MAXCHAR bytes of control information per column.

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

#include    <ospublic.h>

/*

** Local Prototype.

*/

CS_RETCODE     ex_srv_setcontrol PROTOTYPE((

SRV_PROC      *spp

));

/*

** Constants.

#define MAXROWDATA        20

#define COLCONTROL        “Emp name: %s”

/*

** EX_SRV_SETCONTROL

**

**    Example routine to describe format information for a column

 **    using srv_setcontrol. In this example, a simple character

 **    column contains an employee name.

**

** Arguments:

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

**

** Returns:

**    CS_SUCCEED      Control information successfully defined.

**    CS_FAIL    An error was detected.

*/

CS_RETCODE       ex_srv_setcontrol(spp)

SRV_PROC         *spp;

      CS_DATAFMT fmt;

      /* Describe the format of the row data for the column. */

      srv_bzero((CS_VOID *)&fmt, (CS_INT)sizeof(fmt));

      fmt.datatype = CS_CHAR_TYPE;

      fmt.maxlength = MAXROWDATA;

      if (srv_descfmt(spp, (CS_INT)CS_SET, (CS_INT)SRV_ROWDATA,

            (CS_INT)1, &fmt) != CS_SUCCEED)

            return(CS_FAIL);

      /* Define the control information for the column. */

      if (srv_setcontrol(spp, (CS_INT)1, (CS_BYTE *)COLCONTROL,

            (CS_INT)strlen(COLCONTROL)) != CS_SUCCEED)

            return(CS_FAIL);

      return(CS_SUCCEED);

An Open Server application uses srv_setcontrol to tell a client about any user-defined format information pertinent to a particular column. For example, a client may want to send a particular string along with a particular column.
srv_setcontrol must be called after a call to srv_descfmt and before calls to srv_xferdata. If called from any other context, it will return CS_FAIL.
Control information can be associated with columns in any order. The only requirement is that the column must first be defined with srv_descfmt.
It is not necessary to call srv_setcontrol for every column in a row. If an Open Server application does not set control information for a column, a null control string is returned for the column.
An application should not return control information unless the client has specifically requested such information, through the client option toggle, CS_OPT_CONTROL.