srv_descfmt

Description

Describe or retrieve the description of a column or parameter going to or coming from a client.

Syntax

CS_RETCODE srv_descfmt(spp, cmd, type, item,

               clfmtp)

SRV_PROC        *spp;
CS_INT               cmd;
CS_INT               type;
CS_INT               item;
CS_DATAFMT     *clfmtp;

Parameters

spp: A pointer to an internal thread control structure.

cmd

Indicates whether srv_descfmt describes data being sent to the client or retrieves a description of data received from the client. Table 3-36 describes the legal values for cmd:

**Table 3-36: Values for cmd (srv_descfmt)**
Value	Description
CS_SET	srv_descfmt describes the format the data will be in when the client receives it.
CS_GET	srv_descfmt retrieves the format the data was in when the client sent it.

type

If cmd is CS_SET, the type of data being described. If cmd is CS_GET, the type of data being retrieved. Table 3-37 describes the valid types and their appropriate context:

**Table 3-37: Values for type (srv_descfmt)**
Type	Permissible settings for cmd	Description
SRV_RPCDATA	CS_SET or CS_GET	RPC or stored procedure parameters
SRV_ROWDATA	CS_SET only	Row data
SRV_CURDATA	CS_GET only	Cursor parameters
SRV_UPCOLDATA	CS_GET only	Cursor update columns
SRV_KEYDATA	CS_GET only	Cursor key data
SRV_ERRORDATA	CS_SET only	Extended error data
SRV_DYNDATA	CS_SET or CS_GET	Dynamic SQL data
SRV_NEGDATA	CS_SET or CS_GET	Negotiated login data
SRV_MSGDATA	CS_SET or CS_GET	MSG parameters
SRV_LANGDATA	CS_GET only	Language parameters

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

clfmtp: A pointer to a CS_DATAFMT structure containing a description of the data.

Returns

**Table 3-38: Return values (srv_descfmt)**
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_descfmt PROTOTYPE((

SRV_PROC        *spp,

CS_INT          item,

CS_DATAFMT      *dp

));

/*

** EX_SRV_DESCFMT

**

**     Example routine used to get an RPC parameter description.

**

** Arguments:

**

**     spp          A pointer to an internal thread control

                     structure.

**     item         The parameter number we’re looking for.

**     dp           The address of a CS_DATAFMT to be filled with

 **                  the parameter’s description.

**

** Returns:

**          CS_SUCCEED if the description was obtained, or

 **          CS_FAIL if an error was detected.

*/

CS_RETCODE      ex_srv_descfmt(sp, item, dp)

SRV_PROC        *sp;

CS_INT          item;

CS_DATAFMT      *dp;

/*

     ** Call srv_descfmt to get the RPC parameter description.

*/

     if( srv_descfmt(sp, CS_GET, SRV_RPCDATA, item, dp) ==

           CS_FAIL )

/*

          ** An error was al&ready raised.

*/

          return CS_FAIL;

/*

     ** All done.

*/

     return CS_SUCCEED;

Usage

srv_descfmt describes the format of a variety of kinds of columns and parameter. See “CS_DATAFMT structure” for details.
When sending rows or parameters to the client (CS_SET), you must call srv_descfmt to describe how the data will look to the client. When receiving parameters from the client (CS_GET), call srv_descfmt to retrieve a description of the format the data was in when the client sent it. A gateway application may want to save this client format information to pass it on to the remote server.

The srv_descfmt 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_descfmt. (Note that “clfmtp” is a pointer to the structure.

**Table 3-39: CS_DATAFMT fields used (srv_descfmt)**
Field	CS_SET	CS_GET
clfmtp→ namelen	Length of name	Length of name
clfmtp→ status	Parameter/column status	Parameter status
clfmtp→ name	Parameter/column name	Parameter name
clfmtp→datatype	Remote datatype set here	Remote datatype retrieved from here
clfmtp→maxlength	Maximum length of remote datatype set here	Maximum length of remote datatype retrieved from here
clfmtp→format	Remote datatype format	Remote datatype formats

If the format described in the CS_DATAFMT structure (clfmtp) differs from the format described in the subsequent call to srv_bind (osfmtp), Open Server automatically converts to the client format (clfmtp) when cmd is CS_SET or the application format (osfmtp) when cmd is CS_GET.

Once each column or parameter in the datastream has been described and bound, call srv_xferdata to send the data in the program variable to the client or update the program variable with data from the client.

SRV_NEGDATA parameters can be sent or received as part of a negotiated login operation, after srv_negotiate has returned successfully.

Key column numbers correspond to their number in the row.