Sends a results completion indication to the client.
% INCLUDE SYGWPLI;
01 TDPROC PTR, 01 RETCODE FIXED BIN(31), 01 STATUS FIXED BIN(31), 01 ROW_COUNT FIXED BIN(31), 01 RETURN_STATUS_NUMBER FIXED BIN(31), 01 CONN_OPTIONS FIXED BIN(31);
CALL TDSNDDON (TDPROC, RETCODE, STATUS,ROW_COUNT,
RETURN_STATUS_NUMBER, CONN_OPTIONS);
(I) Handle for this client/server connection. This must be the same value specified in the associated TDACCEPT call. The TDPROC handle corresponds to the connection and command handles in Open Client Client-Library.
(O) Variable where the result of function execution is returned. Its value is one of the codes listed in Table 3-39.
(I) The result of the operation. Assign this argument one of the following values:
TDS_DONE_FINAL (0x0000) |
The set of results currently being sent is the final set of results. If STATUS is TDS_DONE_FINAL, CONN_OPTIONS must be TDS_ENDREPLY or TDS_ENDRPC. Note: TDS_ENDREPLY is not supported for the IMS TM implicit API. |
TDS_DONE_CONTINUE (0x0001) |
More results follow. This option tells the receiving program to continue retrieving results until this argument specifies TDS_DONE_FINAL or TDS_DONE_ERROR. If STATUS is TDS_DONE_CONTINUE, CONN_OPTIONS must be TDS_FLUSH. |
TDS_DONE_ERROR (0x0002) |
The last request received from the client resulted in an error. |
TDS_DONE_COUNT (0x0010) |
The ROW_COUNT argument contains a valid count value. |
(I) Number of rows selected or modified by the request. If this argument contains a valid number (a positive integer or zero), the STATUS argument should indicate TDS_DONE_COUNT. If the client request did not affect any rows (for example, it created or dropped a table), this argument does not contain a valid number, and TDS_DONE_COUNT should not be returned in the STATUS argument.
(I) Completion code used only with RPCs. An integer that is passed back to the client return status field to indicate normal completion, an error, or other condition. Sybase Adaptive Servers have predefined return status values for the numbers 0 and -1 to -14, listed in Table 3-38. Values -15 to -99 are reserved for future use. To avoid conflict with Adaptive Server codes, use positive numbers for user-defined return status values.
The predefined Sybase return status values are listed in Table 3-38. These values cannot be null.
Value |
Meaning |
|---|---|
0 |
Procedure executed without error. |
-1 |
Missing object. |
-2 |
Datatype error. |
-3 |
Process was chosen as deadlock victim. |
-4 |
Permission error. |
-5 |
Syntax error. |
-6 |
Miscellaneous user error. |
-7 |
Resource error, such as out of space. |
-8 |
Non-fatal internal problem. |
-9 |
System limit was reached. |
-10 |
Fatal internal inconsistency. |
-11 |
Fatal internal inconsistency. |
-12 |
Table or index is corrupt. |
-13 |
Database is corrupt. |
-14 |
Hardware error. |
(I) Connection open or closed indicator. Specifies whether the connection between the client and server should remain open or be closed.
Assign CONN_OPTIONS one of the following values:
TDS_ENDREPLY (1) |
Indicates that the reply data stream ended. The communication state is changed from SEND to RECEIVE, and the transaction awaits the next request. When you use this value, STATUS must be TDS_DONE_FINAL. For IMS TM transactions, the TDSETPT PROG_TYPE argument must be EXPL.
|
TDS_ENDRPC (3) |
Indicates that the data stream ended. This option ends the current conversation with the client and nullifies the handle specified in TDPROC. If a subsequent Gateway-Library function attempts to use that connection or handle, it results in an error or abend. When you use this value, STATUS must be TDS_DONE_FINAL. |
TDS_FLUSH (7) |
Indicates the end of a result set, but that another may follow. This option does not end the conversation, but it leaves the connection open. If CONN_OPTIONS is TDS_FLUSH, STATUS must be TDS_DONE_CONTINUE. |
The RETCODE argument can contain any of the return values listed in Table 3-39.
Return value |
Meaning |
|---|---|
TDS_OK (0) |
Function completed successfully. |
TDS_CANCEL_RECEIVED (-12) |
Operation canceled. The remote partner issued a cancel. The current operation failed. |
TDS_CONNECTION_FAILED (-4998) |
Connection abended. The client/server connection abnormally ended (for example, the LU 6.2 session crashed or the remote transaction abended). |
TDS_CONNECTION_TERMINATED (-4997) |
Connection closed. The remote partner closed (deallocated) the client/server connection. |
TDS_ILLEGAL_REQUEST (-5) |
Illegal function. The operation failed. This code can indicate that a client application is trying to use a Gateway-Library function that is not supported for clients (for example, TDSNDROW). |
TDS_INVALID_PARAMETER (-4) |
Invalid parameter value. The value assigned to one or more of the arguments supplied in the call is not valid. The operation failed. |
TDS_INVALID_STATUS (-174) |
Invalid status value. The value entered in the STATUS field is invalid. |
TDS_INVALID_TDPROC (-18) |
Error in specifying a value for the TDPROC argument. |
TDS_WRONG_STATE (-6) |
This function cannot be used in the current communication state. For example, your program tried to send a reply before it read in all of the client parameters. The application was still in RECEIVE state and could not send. The operation failed. |
The following code fragment illustrates the use of TDINIT, TDACCEPT, TDSNDDON, and TDFREE at the beginning and end of a Gateway-Library program. This example is taken from the sample program in Appendix B, “Sample RPC Application for CICS.”
/*------------------------------------------------------------------*/
INITIALIZE_PROGRAM:
/*------------------------------------------------------------------*/
/* ------------------------------------------------------------*/
/* reset db2 error handlers */
/* ------------------------------------------------------------*/
EXEC SQL WHENEVER SQLWARNING CONTINUE;
EXEC SQL WHENEVER SQLERROR CONTINUE;
EXEC SQL WHENEVER NOT FOUND CONTINUE;
/* ------------------------------------------------------------*/
/* establish gateway environment */
/* ------------------------------------------------------------*/
CALL TDINIT (DFHEIBLK, GWL_RC, GWL_INIT_HANDLE);
/* ------------------------------------------------------------*/
/* accept client request */
/* ------------------------------------------------------------*/
CALL TDACCEPT (GWL_PROC, GWL_RC, GWL_INIT_HANDLE,
SNA_CONNECTION_NAME,
SNA_SUBC);
/*------------------------------------------------------------------*/
/* (BODY OF PROGRAM) */
/*------------------------------------------------------------------*/
GO TO END_PROGRAM;
/*------------------------------------------------------------------*/
END_PROGRAM:
/*------------------------------------------------------------------*/
IF SEND_DONE = SEND_DONE_OK THEN
WRK_DONE_STATUS = TDS_DONE_COUNT;
ELSE
DO;
WRK_DONE_STATUS = TDS_DONE_ERROR;
PARM_RETURN_ROWS = 0;
END;
CALL TDSNDDON (GWL_PROC, GWL_RC,
WRK_DONE_STATUS,
PARM_RETURN_ROWS,
TDS_ZERO,
TDS_ENDRPC);
CALL TDFREE (GWL_PROC, GWL_RC);
EXEC CICS RETURN;
END SYSAMP1;
The following code fragment illustrates the use of TDGETREQ in a program that uses the IMS TM implicit API. This example is taken from the sample program SYIPSAM1, listed in Appendix E, “Sample RPC Application for IMS TM (Implicit).”
/*------------------------------------------------------------------*/
/* WORK AREAS */
/*------------------------------------------------------------------*/
DCL
01 GW_LIB_MISC_FIELDS,
05 GWL_SPA_PTR PTR,
05 GWL_PROC PTR,
05 GWL_INIT_HANDLE PTR,
05 GWL_RC FIXED BIN(31),
05 GWL_WAIT_OPTION FIXED BIN(31),
05 GWL_REQ_TYPE FIXED BIN(31),
05 GWL_PROG_TYPE CHAR(04) INIT(‘MPP ‘),
05 GWL_RPC_NAME CHAR(30);
[rest of work areas]
/* ------------------------------------------------------------*/
/* set program type to MPP */
/* ------------------------------------------------------------*/
CALL TDSETPT (GWL_INIT_HANDLE, GWL_RC, GWL_PROG_TYPE,
GWL_SPA_PTR, TDS_NULL, TDS_NULL);
.
. [check return code]
.
/* ------------------------------------------------------------*/
/* accept first client request */
/* ------------------------------------------------------------*/
CALL TDACCEPT (GWL_PROC, GWL_RC, GWL_INIT_HANDLE,
SNA_CONNECTION_NAME, SNA_SUBC);
.
. [check return code; process request]
.
DO WHILE(MORE_MSGS);
.
. [prepare to send results; send reply rows]
.
/*------------------------------------------------------------------*/
SEND_DONE:
/*------------------------------------------------------------------*/
CALL TDSNDDON (GWL_PROC, GWL_RC, TDS_DONE_COUNT,
CTR_ROWS, TDS_ZERO, TDS_ENDRPC);
.
. [check return code]
.
IF PARM_NR_ROWS = 0 THEN
MORE_MSGS = FALSE;
ELSE
DO;
GWL_WAIT_OPTION = TDS_TRUE;
GWL_REQ_TYPE = 0;
GWL_RPC_NAME = ‘ ‘;
CALL TDGETREQ (GWL_PROC, GWL_RC,
GWL_WAIT_OPTION,
GWL_REQ_TYPE,
GWL_TRAN_NAME);
SELECT (GWL_RC);
WHEN(TDS_OK);
WHEN(TDS_CONNECTION_TERMINATED)
MORE_MSGS = FALSE;
WHEN(TDS_RESULTS_COMPLETE)
MORE_MSGS = FALSE;
OTHERWISE
DO;
MORE_MSGS = FALSE;
CALL_NAME = ‘TDGETREQ’;
CALL DISP_ERROR;
END;
END; /* SELECT */
END; /* END ELSE */
END; /* DO WHILE MORE_MSGS = TRUE */
The following code fragment illustrates the use of TDSNDDON and TDGETREQ in a program that uses the IMS TM explicit API. This example is taken from the sample program SYIXSAM1, listed in Appendix D, “Sample RPC Application for IMS TM (Explicit).”
/*------------------------------------------------------------------*/
/* WORK AREAS */
/*------------------------------------------------------------------*/
DCL
01 GW_LIB_MISC_FIELDS,
05 GWL_SPA_PTR PTR,
05 GWL_PROC PTR,
05 GWL_INIT_HANDLE PTR,
05 GWL_RC FIXED BIN(31),
05 GWL_WAIT_OPTION FIXED BIN(31),
05 GWL_REQ_TYPE FIXED BIN(31),
05 GWL_PROG_TYPE CHAR(04) INIT(‘MPP ‘),
05 GWL_TRAN_NAME CHAR(30);
.
. [rest of work areas]
.
/* ------------------------------------------------------------*/
/* set program type to EXPL */
/* ------------------------------------------------------------*/
GWL_PROG_TYPE = ‘EXPL’;
CALL TDSETPT (GWL_INIT_HANDLE, GWL_RC, GWL_PROG_TYPE,
GWL_SPA_PTR, TDS_NULL, TDS_NULL);
.
. [check return code]
.
/* ------------------------------------------------------------*/
/* accept first client request */
/* ------------------------------------------------------------*/
CALL TDACCEPT (GWL_PROC, GWL_RC, GWL_INIT_HANDLE,
SNA_CONNECTION_NAME, SNA_SUBC);
.
. [check return code; process request]
.
DO WHILE(MORE_MSGS);
.
. [prepare to send results; send reply rows]
/*------------------------------------------------------------------*/
SEND_DONE:
/*------------------------------------------------------------------*/
IF PARM_NR_ROWS = 0 THEN
DO;
MORE_MSGS = FALSE;
GWL_SEND_DONE = TDS_ENDRPC;
END;
ELSE
GWL_SEND_DONE = TDS_ENDREPLY;
CALL TDSNDDON (GWL_PROC, GWL_RC, TDS_DONE_COUNT,
CTR_ROWS, TDS_ZERO, GWL_SEND_DONE);
. [check return code]
IF PARM_NR_ROWS = 0 THEN
DO;
GWL_WAIT_OPTION = TDS_TRUE;
GWL_REQ_TYPE = 0;
GWL_RPC_NAME = ‘ ‘;
CALL TDGETREQ (GWL_PROC, GWL_RC,
GWL_WAIT_OPTION,
GWL_REQ_TYPE,
GWL_TRAN_NAME);
SELECT (GWL_RC);
WHEN(TDS_OK);
WHEN(TDS_CONNECTION_TERMINATED)
DO;
MORE_MSGS = FALSE;
CALL FREE_STORAGE;
END;
WHEN(TDS_RESULTS_COMPLETE)
DO;
MORE_MSGS = FALSE;
CALL FREE_STORAGE;
END;
OTHERWISE
DO;
MORE_MSGS = FALSE;
CALL_NAME = ‘TDGETREQ’;
CALL DISP_ERROR;
END;
END; /* SELECT */
END; /* IF */
END; /* DO WHILE MORE_MSGS = TRUE */
A server application uses this function to tell a client that it finished sending results and there is no additional data to be returned, or that an error or abnormal situation was detected by the server application. TDSNDDON also indicates whether the client/server connection should remain open or be closed.
When STATUS is TDS_DONE_FINAL, TDSNDDON sends return parameter information back to the client. The return parameter value must be previously set by TDSETPRM.
When the connection remains open, this function puts the server application into RECEIVE state to await another request. In this case, that application should call TDRESULT next, to determine the client response.
The application must be in SEND state for this function to execute successfully. If it is not in SEND state, TDSNDDON returns TDS_WRONG_STATE. Call TDRESULT to put your application in SEND state.
See the discussion of RETURN in the Adaptive Server Enterprise Reference Manual for more information about return status values.
This call controls whether the connection between a client and a server should remain open or whether it should be closed.
To prepare to accept additional client requests after all results are returned, set STATUS to TDS_DONE_FINAL and CONN_OPTIONS to TDS_ENDREPLY. Then, call TDGETREQ to accept the next client request.
A return code of TDS_CANCEL_RECEIVED indicates that the client sent an ATTENTION. Once it receives an ATTENTION, Open ServerConnect does not forward any results to the client.
All Open ServerConnect application programs should check for TDS_CANCEL_RECEIVED frequently, and send a TDSNDDON as soon as possible after one is received.
If a client ATTENTION is received after all
results are sent by the Gateway-Library transaction, Open ServerConnect may
forward results to the client before it is aware that the client
canceled the request.
The transaction stays active and processes new requests as they are sent.
IMS TM users: Long-running transactions are only supported
for the explicit API (the TDSETPT PROG_TYPE parameter
is set to EXPL).
A transaction ends after it sends results to the client.
The JCM converts the data in the return parameter from mainframe to workstation before sending it back to the client.
Related functions
Related documents
Mainframe Connect Server Option Installation and Administration Guide
Adaptive Server Enterprise Reference Manual (for a discussion of return status values)
