Retrieves the last status information received from a remote procedure call (RPC) or SQL command string.
COPY SYGWCOB.
01 TDPROC PIC S9(9) USAGE COMP SYNC. 01 RETCODE PIC S9(9) USAGE COMP SYNC. 01 RETURN-STATUS-NUMBER PIC S9(9) USAGE COMP SYNC. 01 DONE-STATUS PIC S9(9) USAGE COMP SYNC. 01 DONE-COUNT PIC S9(9) USAGE COMP SYNC. 01 COMM–STATE PIC S9(9) USAGE COMP SYNC. 01 COMM-RETCODE PIC S9(9) USAGE COMP SYNC. 01 COMM-ERROR-SUBCODE PIC S9(9) USAGE COMP SYNC.
CALL 'TDSTATUS' USING TDPROC, RETCODE, RETURN-STATUS-NUMBER, DONE-STATUS, DONE-COUNT, COMM–STATE, COMM-RETCODE, COMM-ERROR-SUBCODE.
(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-43.
(O) Variable where the completion code for this request is stored. This code is an integer that indicates normal completion, an error, or other condition. Negative numbers (-1 to -99) and zero are Sybase-defined return status numbers. Positive numbers are user-defined values. For a list of Sybase-defined return status numbers, see the discussion of TDSNDDON.
(O) Variable where the result of the operation is stored. This value indicates whether the operation completed normally or returned an error, and whether any rows were affected. DONE-STATUS returns one of the following values:
TDS-DONE-FINAL (0x0000) |
The set of results currently being sent is the final set of results. |
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. |
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. |
(O) Variable where the row count for the operation is stored. If the DONE-STATUS indicates that a valid number of rows was affected by the operation, this value indicates how many rows were affected.
(O) Variable where the current communication state of the mainframe server is stored. COMM-STATE returns one of the following values:
TDS-RESET (0) |
Client/server conversation for this transaction ended. If the current transaction is running under CICS or uses the IMS TM explicit API, the transaction should exit as soon as possible. If the current transaction is a WFI transaction using the IMS TM implicit API, the transaction can accept another client request by calling TDGETREQ. |
TDS-SEND (1) |
Transaction is in SEND state. |
TDS-RECEIVE (2) |
Transaction is in RECEIVE state. |
TDINFRPC also returns this information.
See “Communication states” for an explanation of communication states.
(O) Variable where the TDPROC current communication I/O return code is stored. This value is in SAA format.
(O) Detailed error information. Provides additional information about the cause of failure when TDSTATUS returns a return code other than TDS-OK.
A list of these codes is in the Mainframe Connect Client Option and Server Option Messages and Codes.
The RETCODE argument can contain any of the return values listed in Table 3-43.
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-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-TDPROC (-18) |
Error in specifying a value for the TDPROC argument. |
TDS-STATUS-NOT-RECEIVED (-11) |
No status returned from client. No RETURN-STATUS-NUMBER is available because the server did not yet send the status back to the client. |
The following code fragment shows how a program uses TDSTATUS to determine the communication state before sending an error message to a client. This example is taken from the sample program, SYCCSAR2, in Appendix B, “Sample RPC Application for CICS.”
*-----------------------------------------------------------------
SEND-SQL-ERROR.
*-----------------------------------------------------------------
MOVE SQLCODE TO MSG-SQL-ERROR-C.
MOVE SQLERRMC TO MSG-SQL-ERROR-K.
* -------------------------------------------------------------
* ensure possible non-printables translated to spaces
* -------------------------------------------------------------
PERFORM VARYING MSG-SQL-ERROR-SS FROM 1 BY 1
UNTIL MSG-SQL-ERROR-SS > SQLERRML
IF MSG-SQL-ERROR-K-CHARS(MSG-SQL-ERROR-SS) < SPACE
OR MSG-SQL-ERROR-K-CHARS(MSG-SQL-ERROR-SS) > '9' THEN
MOVE SPACE TO MSG-SQL-ERROR-K-CHARS(MSG-SQL-ERROR-SS)
END-IF
END-PERFORM.
MOVE MSG-SQL-ERROR TO MSG-TEXT.
MOVE LENGTH OF MSG-SQL-ERROR TO MSG-TEXT-L.
PERFORM SEND-ERROR-MESSAGE.
*-----------------------------------------------------------------
SEND-ERROR-MESSAGE.
*-----------------------------------------------------------------
MOVE 'N' TO SEND-DONE-SW.
MOVE MSG-SEVERITY-ERROR TO MSG-SEVERITY.
MOVE MSG-NR-ERROR TO MSG-NR.
MOVE TDS-ERROR-MSG TO MSG-TYPE.
PERFORM SEND-MESSAGE.
*-----------------------------------------------------------------
SEND-MESSAGE.
*-----------------------------------------------------------------
MOVE LENGTH OF MSG-RPC TO MSG-RPC-L.
* Ensure we're in right state to send a message
CALL 'TDSTATUS' USING GWL-PROC, GWL-RC, GWL-STATUS-NR,
GWL-STATUS-DONE, GWL-STATUS-COUNT,
GWL-STATUS-COMM,
GWL-STATUS-RETURN-CODE,
GWL-STATUS-SUBCODE.
IF (GWL-RC = TDS-OK AND
GWL-STATUS-COMM = TDS-RECEIVE) THEN
CALL 'TDSNDMSG' USING GWL-PROC, GWL-RC, MSG-TYPE,
MSG-NR, MSG-SEVERITY, TDS-ZERO,
TDS-ZERO, MSG-RPC, MSG-RPC-L,
MSG-TEXT, MSG-TEXT-L
END-IF.
The following code fragment illustrates the use of TDSTATUS and TDSNDMSG 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-ERROR-MESSAGE.
*-----------------------------------------------------------------
MOVE 'N' TO SEND-DONE-SW.
MOVE TDS-ERROR-MSG TO MSG-TYPE.
MOVE LENGTH OF MSG-RPC TO MSG-RPC-L.
* Ensure we're in right state to send a message
CALL 'TDSTATUS' USING GWL-PROC, GWL-RC,
GWL-STATUS-NR,
GWL-STATUS-DONE,
GWL-STATUS-COUNT,
GWL-STATUS-COMM,
GWL-STATUS-RETURN-CODE,
GWL-STATUS-SUBCODE.
IF (GWL-RC = TDS-OK AND
GWL-STATUS-COMM = TDS-RECEIVE) THEN
CALL 'TDSNDMSG' USING GWL-PROC, GWL-RC,
MSG-TYPE, MSG-NR,
MSG-SEVERITY,
TDS-ZERO,
TDS-ZERO,
MSG-RPC, MSG-RPC-L,
MSG-TEXT, MSG-TEXT-L
END-IF.
TDSTATUS returns the TDS status number, status flags, count, and communication state associated with the current RPC or SQL command batch execution.
TDSTATUS returns standard communication subcodes.
Related functions
Related topics
Related documents
Mainframe Connect Client Option and Server Option Messages and Codes
