Describe or retrieve the description of a column or parameter going to or coming from a client.
CS_RETCODE srv_desc&fmt(spp, cmd, type, item,
cl&fmtp)
SRV_PROC *spp; CS_INT cmd; CS_INT type; CS_INT item; CS_DATA&fmt *cl&fmtp;
A pointer to an internal thread control structure.
Indicates whether srv_desc&fmt describes data being sent to the client or retrieves a description of data received from the client. The following table describes the legal values for cmd:
Value |
Description |
---|---|
CS_SET |
srv_desc&fmt describes the format the data will be in when the client receives it. |
CS_GET |
srv_desc&fmt retrieves the format the data was in when the client sent it. |
If cmd is CS_SET, the type of data being described. If cmd is CS_GET, the type of data being retrieved. The following table describes the valid types and their appropriate context:
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 |
The parameter or column number. Parameter and column numbers start at 1.
A pointer to a CS_DATA&fmt structure containing a description of the data.
Returns |
To indicate |
---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
#include <ospublic.h>
/*
** Local Prototype
*/
CS_RETCODE ex_srv_desc&fmt PROTOTYPE((
SRV_PROC *spp,
CS_INT item,
CS_DATA&fmt *dp
));
/*
** EX_SRV_DESC&fmt
**
** 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_DATA&fmt 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_desc&fmt(sp, item, dp)
SRV_PROC *sp;
CS_INT item;
CS_DATA&fmt *dp;
{
/*
** Call srv_desc&fmt to get the RPC parameter description.
*/
if( srv_desc&fmt(sp, CS_GET, SRV_RPCDATA, item, dp) ==
CS_FAIL )
{
/*
** An error was al&ready raised.
*/
return CS_FAIL;
}
/*
** All done.
*/
return CS_SUCCEED;
}
srv_desc&fmt 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_desc&fmt to describe how the data will look to the client. When receiving parameters from the client (CS_GET), call srv_desc&fmt 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_desc&fmt 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_desc&fmt. (Note that “cl&fmtp” is a pointer to the structure.
Field |
CS_SET |
CS_GET |
---|---|---|
cl&fmtp→ namelen |
Length of name |
Length of name |
cl&fmtp→ status |
Parameter/column status |
Parameter status |
cl&fmtp→ name |
Parameter/column name |
Parameter name |
cl&fmtp→datatype |
Remote datatype set here |
Remote datatype retrieved from here |
cl&fmtp→maxlength |
Maximum length of remote datatype set here |
Maximum length of remote datatype retrieved from here |
cl&fmtp→format |
Remote datatype format |
Remote datatype formats |
If the format described in the CS_DATA&fmt structure (cl&fmtp) differs from the format described in the subsequent call to srv_bind (os&fmtp), Open Server automatically converts to the client format (cl&fmtp) when cmd is CS_SET or the application format (os&fmtp) 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_desc&fmt cannot be called with cmd equal to CS_SET and type equal to SRV_RPCDATA in the SRV_RPC event handler. When in the SRV_RPC event handler, Open Server reads the format information for RPC return parameters from the client.
You can use srv_desc&fmt with cmd set to CS_SET and type to SRV_RPCDATA in other event handlers.
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.
srv_bind, srv_cursor_props,srv_dynamic, srv_msg, srv_negotiate, srv_numparams, srv_sendinfo, srv_xferdata, “CS_DATAFMT structure”