srv_alt_bind

Description

Describe and bind the source data for a compute row column.

Syntax

   CS_RETCODE srv_alt_bind(spp, altid, item, osfmtp,
           varaddr, varlenp, indp) 
 
 SRV_PROC         *spp;
 CS_INT               altid;
 CS_INT               item;
 CS_DATAFMT    *osfmtp;
 CS_BYTE           *varaddrp;
 CS_INT               *varlenp;
 CS_SMALLINT    *indp;

Parameters

spp: A pointer to an internal thread control structure.

altid: The unique identifier for the compute row in which this compute column is contained. The altid is defined using srv_alt_header.

item: The column’s column number in the compute row. Compute row column numbers start at 1.

osfmtp: A pointer to a CS_DATAFMT structure. This structure describes the format of the compute row column data that the application program variable contains.

varaddrp: A pointer to the program variable to which the outgoing data is bound.

varlenp: A pointer to the program variable containing *varaddrp’s length.

indp

A pointer to the buffer containing the null value indicator. The following table summarizes the values *indp can contain:

**Table 3-2: Values for indp (srv_alt_bind)**
Value	Indicates
CS_NULLDATA	Column data is null.
CS_GOODDATA	Column data is not null.

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

Returns

**Table 3-3: Return values (srv_alt_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_alt_bind PROTOTYPE((

 SRV_PROC               *spp,

 CS_INT                 altid,

 CS_VOID                *sump

));

/*

 ** EX_SRV_ALT_BIND

**

 **    Example routine to describe and bind the source data for

 **    a compute row column. This example binds a value which

 **    is the sum of the first column of row data.

**

 ** Arguments:

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

 **             The thread must be an active client thread that

 **             can handle row data.

**

 **    altid    -     The id for this compute row.

**

 **    sump    -    A pointer to the variable which will contain

 **                 the sum of the first column of row data.

**

 ** Returns:

 **     CS_SUCCEED - Compute row column was successfully bound.

 **     CS_FAIL    - An error was detected.

**

*/

 CS_RETCODE          ex_srv_alt_bind(spp, altid, sump)

 SRV_PROC            *spp;

 CS_INT              altid;

 CS_VOID             *sump;

    CS_DATAFMT compute_colfmt;

/*

      **Format for this compute column.

*/

      CS_INT         namelen;

/*

      **Length of compute column name

*/

    CS_INT        compute_colnum;

/*

     **    The column number for this compute column.

*/

   CS_SMALLINT     indicator;

/*

     **    Null indicator.

*/

     CS_INT            sumlen;

/*

     **    Length of the compute value

*/

     CS_RETCODE        result;

/*

     **Return value from srv_alt_bind.

*/

/*

     ** Initialize the compute column’s data format. This compute

     ** column represents a sum of the first column of data.

*/

     namelen = 3;

     srv_bmove(“sum”, compute_colfmt.name, namelen);

   compute_colfmt.namelen = namelen;

     compute_colfmt.datatype = CS_INT_TYPE;

     compute_colfmt.format = CS_FMT_UNUSED;

     compute_colfmt.maxlength = sizeof(CS_INT);

     compute_colfmt.scale = 0;

   compute_colfmt.precision = CS_DEF_PREC;

     compute_colfmt.status = 0;

     compute_colfmt.count = 0;

     compute_colfmt.usertype = 0;

     compute_colfmt.locale = (CS_LOCALE *)NULL;

/*

     ** Perform the bind

*/

     compute_colnum = 1;

     indicator = CS_GOODDATA;

     sumlen = sizeof(CS_INT);

   result = srv_alt_bind(spp, altid, compute_colnum,

            &compute_colfmt, sump, &sumlen, &indicator);

    return (result);

Usage

Only applications that mimic Adaptive Server’s feature of returning compute row information will need to call srv_alt_bind. srv_alt_bind is most useful to applications acting as a gateway to an Adaptive Server.

srv_alt_bind describes the format of the application program variable in which a compute row column’s data is stored. An application must call it once for each column in a compute row.

The srv_alt_bind routine reads from (CS_GET) or sets (CS_SET) the CS_DATAFMT fields listed in the table below. All other fields are undefined for srv_alt_bind. (Note that “osfmtp” is a pointer to the structure.

**Table 3-4: CS_DATAFMT fields used (srv_alt_bind)**
Field	CS_SET	CS_GET
osfmtp→datatype	Datatype of application program variable	Datatype of application program variable
osfmtp→maxlength	Unused	Maximum length of program variable
osfmtp→count	0 or 1	0 or 1

If the format described by osfmtp differs from the client format set with srv_alt_descfmt (clfmtp), Open Server automatically converts the data to the client format.

A compute result set contains only one row. However, an application can return multiple result sets, each with a distinct altid.

To process compute row data, an Open Server application must:

Call srv_alt_header to define a compute row identifier.
Call srv_alt_descfmt for each column to describe the format the column data is in when the client receives it.
Call srv_alt_bind for each column to bind the data to a local program variable.
Call srv_alt_xferdata to send the row to the client, once each column in the compute row has been described and its data bound to a program variable.

The contents of the buffers to which varaddrp, lenp, and indp point need not be valid until srv_xferdata is called.