srv_msg

Description

Send or receive a message datastream.

Syntax

CS_RETCODE srv_msg(spp, cmd, msgidp, status)

SRV_PROC    *spp;
CS_INT           cmd;
CS_INT           *msgidp;
CS_INT          *statusp;

Parameters

spp: A pointer to an internal thread control structure.

cmd

Indicates whether the application is calling srv_msg to send or retrieve a message. The following table describes the legal values for cmd:

**Table 3-63: Values for cmd (srv_msg)**
Value	Description
CS_SET	srv_msg is setting the values for status and msgid prior to sending the message to the client.
CS_GET	srv_msg is retrieving the status and msgid values for the message being received.

msgidp: A pointer to the message ID of the current message. If the Open Server application is sending a message (CS_SET), it must provide the message ID here. If the application is reading a message (CS_GET), the message ID of the received message is returned here. Values of SRV_MINRESMSG through SRV_MAXRESMSG are reserved for internal Sybase usage. Since the message ID is subsequently sent as a smallint (2 bytes) through TDS, the available range you can use for your own messages is SRV_MAXRESMSG to 65535, if you define message ID as an unsigned CS_SMALLINT.

statusp

A pointer to the status of the current message. If the Open Server application is receiving a message (CS_GET), Open Server will update *statusp with the message status. If the application is sending a message (CS_SET), *statusp must contain the status of the message to be sent. The following table describes the legal values for *statusp:

**Table 3-64: Values for statusp (srv_msg)**
Value	Description
SRV_HASPARAMS	The message has parameters.
SRV_NOPARAMS	The message has no parameters.

Returns

**Table 3-65: Return values (srv_msg)**
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_msg PROTOTYPE((

SRV_PROC      *spp

));

/*

** EX_SRV_MSG
 **

 **    Example routine to receive and send a message datastream.

**

 ** Arguments:

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

**

 ** Returns:

 **  CS_SUCCEED if we were successful in both receiving and

 **  sending a message stream.

**

 **  CS_FAIL if an error was detected.

**

*/

CS_RETCODE    ex_srv_msg(spp)

SRV_CONFIG    *scp;

    CS_RETCODE      result;

    CS_INT          msgid;

    CS_INT          status;

/*

     ** We will first get a message and process any parameters.

*/

    result = srv_msg(spp, CS_GET, &msgid, &status);

    if (result == CS_FAIL)

        return (CS_FAIL);

    if (status == SRV_HASPARAMS)

/*

         ** Process parameters here using srv_bind and

         ** srv_xferdata.

*/

/*

    ** Now, an example of sending a message.

*/

    msgid = 32768;

    status = SRV_NOPARAMS;

    result = srv_msg(spp, CS_SET, &msgid, &status);

    if (result == CS_FAIL)

        return (CS_FAIL);

/*

     ** If the message has parameters, send it across using     ** srv_xferdata

*/

    if (status == SRV_HASPARAMS)

        result = srv_xferdata(spp, CS_SET, SRV_MSGDATA);

    return(result);

Usage

srv_msg is used to send or receive a TDS message data stream.
Each message data stream received from a client raises a SRV_MSG event. A separate event is raised for each message received.
If a message has parameters, *statusp will contain the value CS_HASPARAMS. The application can retrieve and store the parameters using srv_desc&fmt, srv_bind, and srv_xferdata with type set to SRV_MSGDATA.
An application can determine the number of parameters for a message by calling srv_numparams.
The srv_msg routine is used to send the status and ID. The actual parameters of the message, if any, are sent using srv_desc&fmt, srv_bind, and srv_xferdata with a type argument of SRV_MSGDATA.
An application can send or receive multiple message data streams.
srv_xferdata is only needed to retrieve or send message parameters. When using it for these cases, srv_xferdata must be called once for each message being sent or received. If you use srv_xferdata when no parameters exist, Open Server returns an error.
srv_msg can only be called in a SRV_MSG event handler when cmd is CS_GET. It can be called in any event handler when cmd is CS_SET.