srv_alt_bind

Description

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

Syntax

   CS_RETCODE srv_alt_bind(spp, altid, item, os&fmtp,
           varaddr, varlenp, indp) 
 
 SRV_PROC         *spp;
 CS_INT               altid;
 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.

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.

os&fmtp: A pointer to a CS_DATA&fmt 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_DATA&fmt      compute_col&fmt;

/*

      **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_col&fmt.name, namelen);

   compute_col&fmt.namelen = namelen;

     compute_col&fmt.datatype = CS_INT_TYPE;

     compute_col&fmt.format = CS_&fmt_UNUSED;

     compute_col&fmt.maxlength = sizeof(CS_INT);

     compute_col&fmt.scale = 0;

   compute_col&fmt.precision = CS_DEF_PREC;

     compute_col&fmt.status = 0;

     compute_col&fmt.count = 0;

     compute_col&fmt.usertype = 0;

     compute_col&fmt.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_col&fmt, 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_DATA&fmt fields listed in the table below. All other fields are undefined for srv_alt_bind. (Note that “os&fmtp” is a pointer to the structure.

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

If the format described by os&fmtp differs from the client format set with srv_alt_desc&fmt (cl&fmtp), 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:
1. Call srv_alt_header to define a compute row identifier.
2. Call srv_alt_desc&fmt for each column to describe the format the column data is in when the client receives it.
3. Call srv_alt_bind for each column to bind the data to a local program variable.
4. 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.