Sends a results completion indication to the client.
COPY SYGWCOB.
01 TDPROC PIC S9(9) USAGE COMP SYNC. 01 RETCODE PIC S9(9) USAGE COMP SYNC. 01 STATUS PIC S9(9) USAGE COMP SYNC. 01 ROW-COUNT PIC S9(9) USAGE COMP SYNC. 01 RETURN-STATUS-NUMBER PIC S9(9) USAGE COMP SYNC. 01 CONN-OPTIONS PIC S9(9) USAGE COMP SYNC.
CALL 'TDSNDDON' USING 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’s 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.
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. |
This value cannot be NULL.
(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 parameter 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, SYCCSAR2, in Appendix B, “Sample RPC Application for CICS.”
* Establish gateway environment
CALL 'TDINIT' USING DFHEIBLK, GWL-RC, GWL-INIT-HANDLE.
* Accept client request
CALL 'TDACCEPT' USING GWL-PROC, GWL-RC, GWL-INIT-HANDLE,
SNA-CONNECTION-NAME, SNA-SUBC.
* TDRESULT to make sure we were started via RPC request
CALL 'TDRESULT' USING GWL-PROC, GWL-RC.
IF GWL-RC NOT = TDS-PARM-PRESENT THEN
PERFORM TDRESULT-ERROR
GO TO END-PROGRAM
END-IF.
* ------------------------------------------------------------- * body of program * ------------------------------------------------------------- *-----------------------------------------------------------------
END-PROGRAM.
*-----------------------------------------------------------------
IF SEND-DONE-OK
MOVE TDS-DONE-COUNT TO WRK-DONE-STATUS
ELSE
MOVE TDS-DONE-ERROR TO WRK-DONE-STATUS
MOVE ZERO TO PARM-RETURN-ROWS
END-IF.
CALL 'TDSNDDON' USING GWL-PROC, GWL-RC, WRK-DONE-STATUS,
PARM-RETURN-ROWS, TDS-ZERO,
TDS-ENDRPC.
CALL 'TDFREE' USING GWL-PROC, GWL-RC.
EXEC CICS RETURN END-EXEC.
The following code fragment illustrates the use of TDSNDDON and TDGETREQ in a Gateway-Library transaction using the IMS TM implicit API. This example is taken from the sample program in Appendix D, “Sample RPC Application for IMS TM (Implicit).”
*---------------------------------------------------------------- SEND-ROWS. *----------------------------------------------------------------
PERFORM FETCH-AND-SEND-ROWS
UNTIL ALL-DONE.
FINISH-REPLY.
.
CALL ‘TDSNDDON’ USING GWL-PROC, GWL-RC,
WRK-DONE-STATUS,
CTR-ROWS,
TDS-ZERO,
TDS-ENDRPC.
. [check return code]
.
* Get next client request
MOVE TDS-TRUE TO GWL-WAIT-OPTION.
MOVE ZEROES TO GWL-REQ-TYPE.
MOVE SPACES TO GWL-RPC-NAME.
CALL ‘TDGETREQ’ USING GWL-PROC, GWL-RC, GWL-WAIT-OPTION,
GWL-REQ-TYPE, GWL-RPC-NAME.
EVALUATE GWL-RC
WHEN ZEROES
GO TO READ-IN-USER-PARM
WHEN TDS-RESULTS-COMPLETE
PERFORM FREE-ALL-STORAGE
WHEN TDS-CONNECTION-TERMINATED
PERFORM FREE-ALL-STORAGE
WHEN OTHER
MOVE ‘TDGETREQ’ TO CALL-ERROR
PERFORM DISPLAY-CALL-ERROR
END-EVALUATE.
GOBACK.
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.
IMS TM Users: Long-running transactions are only supported
for the explicit API (the TDSETPT PROG-TYPE parameter
is set to EXPL).
With short transactions, a transaction ends after it sends results to the client; in long-running transactions, it stays active and processes new requests as they are sent.
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.
Therefore, 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 Open ServerConnect transaction, Open ServerConnect
may forward results to the client before it is aware that the client
canceled the request.
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)
| Copyright © 2005. Sybase Inc. All rights reserved. |
|
|
