srv_senddone

Description

Send a results completion message or flush results to a client.

Syntax

CS_RETCODE srv_senddone(spp, status, transtate, count)

SRV_PROC         *spp;
CS_INT                status;
CS_INT                transtate;
CS_INT              count;

Parameters

Returns

Examples

Example 1

#include     <ospublic.h>

/*

** Local Prototype.

*/

CS_RETCODE      ex_srv_senddone PROTOTYPE((

SRV_PROC        *spp

));

/*

** Constants and data definitions.

*/

#define    NUMROWS         3  

#define    MAXROWDATA      6

CS_STATIC CS_CHAR  *row_data[NUMROWS] = {

                    “Larry”,

                    “Curly”,

                    “Moe”

                    };

/*

** EX_SRV_SENDDONE

**

**    Example routine illustrating the use of srv_senddone. This

 **    routine will send a set of results to the client

 **    application, and then send the results completion message.

**

** Arguments:

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

**

** Returns:

**    CS_SUCCEED    Results set sent successfully to client.

**    CS_FAIL       An error was detected.

*/

CS_RETCODE      ex_srv_senddone(spp)

SRV_PROC        *spp;

{

      CS_DATAFMT      fmt;

      CS_INT          row_len;

      CS_INT          idx;

      /*

      ** Describe the format of the row data, with the single

       ** dummy column.

      */

      srv_bzero((CS_VOID *)&fmt, (CS_INT)sizeof(fmt));

      fmt.datatype = CS_CHAR_TYPE;

      fmt.maxlength = MAXROWDATA;

      if (srv_descfmt(spp, (CS_INT)CS_SET, (CS_INT)SRV_ROWDATA,

                (CS_INT)1, &fmt) != CS_SUCCEED)

      {

             (CS_VOID)srv_senddone(spp,

                (CS_INT)(SRV_DONE_FINAL | SRV_DONE_ERROR),

                (CS_INT)CS_TRAN_FAIL, (CS_INT)0);

             return(CS_FAIL);

       }

      for (idx = 0; idx < NUMROWS; ++idx)

      {

           /*

           ** Bind the row_data array element. 

           */

           row_len = (CS_INT)strlen(row_data[idx]);

           if (srv_bind(spp, (CS_INT)CS_SET, (CS_INT)SRV_ROWDATA,

               (CS_INT)1, &fmt, (CS_BYTE *)(row_data[idx]),

                &row_len, (CS_SMALLINT *)NULL) != CS_SUCCEED)

           {

                /* Communicate failure, and number of rows sent. */

                (CS_VOID)srv_senddone(spp,

                     (CS_INT)(SRV_DONE_FINAL |

                              SRV_DONE_ERROR | SRV_DONE_COUNT),

                     (CS_INT)CS_TRAN_FAIL, (CS_INT)idx);

                return(CS_FAIL);

           }

           /*

           ** Transfer the row data.

           */

           if (srv_xferdata(spp, (CS_INT)CS_SET, SRV_ROWDATA)

                                 != CS_SUCCEED)

           {

                /* Communicate failure, and number of rows sent. */

                (CS_VOID)srv_senddone(spp,

                    (CS_INT)(SRV_DONE_FINAL |

                        SRV_DONE_ERROR | SRV_DONE_COUNT),

                    (CS_INT)CS_TRAN_FAIL, (CS_INT)idx);

                return(CS_FAIL);

            }

      }

      /* Send a status value. */

      if (srv_sendstatus(spp, (CS_INT)0) != CS_SUCCEED)

      {

            /* Communicate failure, and number of rows sent. */

            (CS_VOID)srv_senddone(spp,

                (CS_INT)(SRV_DONE_FINAL |

                    SRV_DONE_ERROR | SRV_DONE_COUNT),

                (CS_INT)CS_TRAN_FAIL, (CS_INT)NUMROWS);

            return(CS_FAIL);

      }

      /* Send the final DONE message, with the row count. */

      if (srv_senddone(spp, (CS_INT)(SRV_DONE_FINAL | 

             SRV_DONE_COUNT),

                (CS_INT)CS_TRAN_COMPLETED,

                (CS_INT)NUMROWS) != CS_SUCCEED)

      {

            /* Communicate failure, and number of rows sent. */

            (CS_VOID)srv_senddone(spp,

                (CS_INT)(SRV_DONE_FINAL |

                        SRV_DONE_ERROR | SRV_DONE_COUNT),

                (CS_INT)CS_TRAN_FAIL, (CS_INT)NUMROWS);

            return(CS_FAIL);

      }

return(CS_SUCCEED);

}

Usage

• srv_senddone sends a message to the client that the current set of results is complete. A client request can cause the server to execute a number of commands and to return a number of results sets. For each set of results, a completion message must be returned to the client with srv_senddone.

• If the current results are not the last set of results for the client command batch, the Open Server must set the status mask’s SRV_DONE_MORE field. Otherwise, the Open Server application must set the status field to SRV_DONE_FINAL to indicate that there are no more results for the current command batch.

• The count field indicates how many rows were affected by a particular command. If count actually contains a count, the SRV_DONE_COUNT bit should be set in the status field. This enables the client to distinguish between an actual count of 0 and an unused count field.

• If the SRV_CONNECT handler rejects the client login, the Open Server application must call srv_senddone with the status parameter set to the SRV_DONE_ERROR flag. The SRV_CONNECT handler must then send a DONE packet to the client with srv_senddone. In any case, srv_senddone must be called only once before the SRV_CONNECT handler returns and the SRV_DONE_FINAL status flag must be set.

• When a write is in progress and the network buffer fills up, Open Server flushes its contents. Issuing srv_senddone with status set to SRV_DONE_FINAL or SRV_DONE_FLUSH causes a flush of the network buffer, regardless of how full it is. SRV_DONE_FLUSH can be set with or without SRV_DONE_MORE.

• Setting status to SRV_DONE_FLUSH allows an application to flush to a client results that have accumulated over a long period of time.

• An application cannot set the status argument to SRV_DONE_FLUSH inside a SRV_CONNECTION error handler.

• Open Server does not provide any transaction management. It is the responsibility of the Open Server application to use the transtate argument as required to notify a client of the current transaction state.

See also