Send a results completion message or flush results to a client.
CS_RETCODE srv_senddone(spp, status, transtate, count)
SRV_PROC *spp; CS_INT status; CS_INT transtate; CS_INT count;
A pointer to an internal thread control structure.
A 2-byte bit mask composed of one or more flags OR’d together. The following table describes each flag:
Status |
Description |
|---|---|
SRV_DONE_FINAL |
The current set of results is the final set of results. |
SRV_DONE_MORE |
The current set of results is not the final set of results. |
SRV_DONE_COUNT |
The count parameter contains a valid count. |
SRV_DONE_ERROR |
The current client command got an error. |
SRV_DONE_FLUSH |
The current result set will be sent to the client without waiting for a full packet. |
The current state of the transaction. The following table describes the legal values for transtate:
Transaction State |
Description |
|---|---|
CS_TRAN_UNDEFINED |
Not currently in a transaction. |
CS_TRAN_COMPLETED |
The current transaction completed successfully. |
CS_TRAN_FAIL |
The current transaction failed. |
CS_TRAN_IN_PROGRESS |
Currently in a transaction. |
CS_TRAN_STMT_FAIL |
The current transaction statement failed. |
A 4-byte field containing a count for the current set of results. The count is valid if the SRV_DONE_COUNT flag is set in the status field.
Returns |
To indicate |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
#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_DATA&fmt &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_desc&fmt(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);
}
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.
The transtate argument replaces
the info argument in the Open Server 2.0 version
of srv_senddone.This change will cause
runtime errors in existing applications if the value of info in
the existing application is not 0.
