srv_bind

Description

Describe and bind a program variable for a column or parameter.

Syntax

CS_RETCODE srv_bind(spp, cmd, type, item, os&fmtp,

                 varaddrp, varlenp, indp)

SRV_PROC          *spp;
CS_INT                 cmd;
CS_INT                 type;
CS_INT                 item;
CS_DATA&fmt      *os&fmtp;
CS_BYTE             *varaddrp;
CS_INT                *varlenp;
CS_SMALLINT     *indp;

Parameters

spp: A pointer to an internal thread control structure.

cmd

cmd indicates whether the program variable stores data going out to a client or coming in from a client. The following table describes the legal values for cmd:

**Table 3-10: Values for cmd (srv_bind)**
Value	Description
CS_SET	Data in the varaddrp is sent to a client when srv_xferdata* is called.
CS_GET	varaddrp is initialized with data from a client after a call to srv_xferdata*.

type

The type of data stored into or read from the program variable. The following table describes the legal values for type:

**Table 3-11: Values for type (srv_bind)**
Type	Valid cmd	Description of data
SRV_RPCDATA	CS_SET or CS_GET	RPC or stored procedure parameter
SRV_ROWDATA	CS_SET only	Result row column
SRV_CURDATA	CS_GET only	Cursor parameter
SRV_KEYDATA	CS_GET only	Cursor key column
SRV_ERRORDATA	CS_SET only	Error message parameter
SRV_DYNAMICDATA	CS_SET or CS_GET	Dynamic SQL parameter
SRV_NEGDATA	CS_SET or CS_GET	Negotiated login parameter
SRV_MSGDATA	CS_SET or CS_GET	Message parameter
SRV_LANGDATA	CS_GET only	Language parameter

item: The column or parameter number. Column and parameter numbers start at 1.

os&fmtp: A pointer to a CS_DATA&fmt structure. This structure describes the format of the data stored in *varaddrp.

varaddrp: A pointer to the program variable to which the column or parameter data is bound.

varlenp

A pointer to the length of varaddrp. Its precise meaning and characteristics differ depending on the value of cmd. The following table summarizes the legal values for varlenp:

**Table 3-12: Values for varlenp (srv_bind)**
If cmd is	Then varlenp
CS_SET (data going out to client)	Cannot be NULL Points to the actual length of the data in *varaddrp Need not be valid until srv_xferdata is called
CS_GET (data coming in from client)	Can be NULL (indicating that the Open Server application al&ready knows the length of the data) Is a pointer to the program variable in which Open Server places the actual length of the data Is filled in after a call to srv_xferdata

When retrieving data, *varlenp is empty until the application calls srv_xferdata. Open Server then fills the buffer with the length of the newly received value. When sending data, an application fills in *varlenp points before calling srv_xferdata to send the data.

indp

A pointer to a buffer containing a null value indicator. The following table lists the legal values for *indp:

**Table 3-13: Values for indp (srv_bind)**
Value	Indicates
CS_NULLDATA	Column or parameter data is null.
CS_GOODDATA	Column or parameter data is not null.

If indp is NULL, the column data is assumed to be valid; that is, not null.

Returns

**Table 3-14: Return values (srv_bind)**
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_bind PROTOTYPE((

SRV_PROC               *spp,

CS_INT                 *nump,

CS_BYTE                *namep,

CS_INT                 *lenp

));

/*

 ** EX_SRV_BIND

**

**     Example routine using srv_bind to describe and bind two

 **     program.

**     variables to receive client RPC parameters. For this

 **     example, the

**     RPC is passed an employee number, and last name. A third

 **     program.

**     variable will be bound to receive the length of the

 **     employee’s name.

**     This routine is called prior to srv_xferdata, which will

 **     actually transfer the data into the program variables.

**

** Arguments:

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

**     nump    A Pointer to the integer to receive the employee

 **             number.

**     namep   A Pointer to the memory area to receive the

 **             employee name.

**    lenp     A Pointer to the integer to receive the length of

 **             the employee’s name. (On input, points to the

 **             maximum length of the memory area available.)

**

** Returns:

**    CS_SUCCEED    Program variables were successfully bound.

**    CS_FAIL       An error was detected.

*/

CS_RETCODE     ex_srv_bind(spp, nump, namep, lenp)

SRV_PROC        *spp;

CS_INT          *nump;

CS_BYTE         *namep;

CS_INT          *lenp;

     CS_INT               param_no;

     CS_DATA&fmt           var&fmt;

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

/*

     ** First, bind the integer to receive the employee number,

     ** param 1. Here, we know the length of the data, so no

     ** length pointer is required.

*/

     param_no = 1;

     var&fmt.datatype = CS_INT_TYPE;

     var&fmt.maxlength = (CS_INT)sizeof(CS_INT);

     if (srv_bind(spp, (CS_INT)CS_GET, (CS_INT)SRV_RPCDATA,

          param_no, &var&fmt, (CS_BYTE *)nump, (CS_INT *)NULL,

          (CS_SMALLINT *)NULL) != CS_SUCCEED)

          return(CS_FAIL);

/*

      ** Then, bind the character memory to receive the

      ** employee name, param 2.

*/

     param_no = 2;

     var&fmt.datatype = CS_CHAR_TYPE;

     var&fmt.maxlength = *lenp;

     if (srv_bind(spp, (CS_INT)CS_GET, (CS_INT)SRV_RPCDATA,

           param_no,

          &var&fmt, namep, lenp, (CS_SMALLINT *)NULL) !=

           CS_SUCCEED)

          return(CS_FAIL);

     return(CS_SUCCEED);

Usage

srv_bind describes the format of a row column or parameter and associates it with an application program variable.
srv_bind must be called once for each column in a results row or parameter in a parameter stream.
Applications that want to change local program variable addresses (varaddrp, varlenp, or indp) between sending rows must call srv_bind followed by srv_xferdata each time such a change occurs.
A Server-Library application sends data to a client in two stages:

First, it calls srv_bind with cmd equal to CS_SET. The parameters varaddrp, varlenp, and indp contain a pointer to the data being found, a pointer to its length, and a pointer to an indicator variable. At this time, Server-Library records the addresses passed in these pointer parameters.

These values must remain valid until the application calls srv_xferdata, which is when Server-Library reads the values from those memory locations. For example, different buffers must be used when multiple data items are passed in separate calls to srv_bind.
Error data parameters must be described (srv_desc&fmt), bound (srv_bind) and sent to the client (srv_xferdata) immediately after a call to srv_sendinfo and before calling srv_senddone. The type argument of the srv_desc&fmt, srv_bind, and srv_xferdata routines is set to SRV_ERRORDATA.
Message data parameters must be described (srv_desc&fmt), bound (srv_bind), and transferred (srv_xferdata) following a call to the srv_msg routine. The type argument of the srv_desc&fmt, srv_bind, and srv_xferdata routines is set to SRV_MSGDATA.

The srv_bind routine reads from (CS_GET) or sets (CS_SET) the CS_DATA&fmt fields listed in the table below. All other fields are undefined for srv_bind. (Note that “os&fmtp” is a pointer to the structure.

**Table 3-15: CS_DATA&fmt fields used (srv_bind)**
Field	In CS_SET operations, it is:	In CS_GET operations, it is:
os&fmtp→datatype	Datatype of application program variable	Datatype of application program variable
os&fmtp→maxlength	Actual length of program variable	Maximum length of program variable
os&fmtp→count	0 or 1	0 or 1
os&fmtp→status	CS_CANBENULL must be set if you are sending null values.	Unused

To send a null value in a column, the status value of that column’s CS_DATA&fmt structure must have the CS_CANBENULL bit set. Refer to Table 2-9 for possible values of status in the CS_DATA&fmt structure.

If the format described by os&fmtp differs from the format of the data received from the client (cmd set to CS_GET), Open Server automatically converts the data to os&fmtp. If it differs from the format in which the data is sent to the client (cmd set to CS_SET), Open Server automatically converts it to the client format (cl&fmtp).