Accepts the next request in a long-running transaction.
%INCLUDE SYGWPLI;
01 TDPROC PTR, 01 RETCODE FIXED BIN(31), 01 WAIT_OPTION FIXED BIN(31), 01 REQUEST_TYPE FIXED BIN(31), 01 TRAN_NAME CHAR(n);
CALL TDGETREQ (TDPROC, RETCODE, WAIT_OPTION,
REQUEST_TYPE, TRAN_NAME);
(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-9.
(I) Wait/do not wait indicator. Indicates what the application should do after a TDGETREQ if no request is present: (1) wait for a new request to arrive, or (2) terminate immediately.
Assign this argument one of the following values:
TDS_TRUE (1) |
Wait for input. |
TDS_FALSE (0) |
Do not wait for input. |
Under CICS and MVS: We recommend always coding TDS_FALSE. Coding TDS_FALSE ends the transaction and frees resources if there is nothing left to do. Coding TDS_TRUE causes the transaction to wait.
Under IMS TM: The WAIT_OPTION tells the transaction what to do when the message queue is empty: wait for another request to appear on the queue, or end the transaction.
To use TDGETREQ properly under the
IMS TM implicit API,
the transaction must be a WPI transaction, or the message region
that the transaction runs in must have PWFI=Y (Pseudo-Wait-For-Input)
specified.
(O) Type of request to be accepted. Returns one of the following values:
TDS_LANGUAGE_EVENT (1) |
Current request is a language request. |
TDS_RPC_EVENT (3) |
Current request is an RPC. |
TDS_DYNAMIC_EVENT (4) |
Current request is a dynamic SQL request. |
TDS_CURSOR_EVENT (5) |
Current request is a cursor request. |
TDINFPGM and TDINFRPC also return this information.
These are new values. The old values (TDS_START_SQL and TDS_START_RPC)
still work, but you should use the new values from now on.
(O) Variable where the name of the current CICS, MVS or IMS TM transaction is returned.
The RETCODE argument can contain any of the return values listed in Table 3-9.
Return value |
Meaning |
|---|---|
TDS_OK (0) |
Function completed successfully. |
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_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_SOS (-257) |
Memory shortage. The host subsystem was unable to allocate enough memory for the control block that Gateway-Library tried to create. The operation failed. |
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 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 */
Use this function in long-running transactions to determine whether more requests are arriving. If more requests are arriving, TDGETREQ:
Indicates whether the request is an RPC or a language request (TDGETREQ gets this information from the login packet).
Returns the transaction name.
Accepts the request.
TDACCEPT cannot be used more than once in an application, and it is always used to accept the first client request received. When a long-running transaction or WFI transaction accepts multiple client requests, the transaction uses TDACCEPT to accept the first request and TDGETREQ to accept subsequent requests. Because all requests do not need to be the same type, TDGETREQ also indicates the type of request. For example, one may be an RPC, the next may be a SQL language request.
TDGETREQ is used with WFI and explicit transactions under IMS TM and for CONVERSATIONAL-type transactions under CICS.
TDINFRPC also returns the type of request, as well as the name of the RPC that called the current transaction.
After a TDGETREQ call, continue coding just as you would after TDACCEPT.
TDGETREQ follows TDSNDDON in a long-running or WFI transaction.
To keep the connection open after TDSNDDON returns results for the previous client request in a long-running transaction, the CONN_OPTIONS argument of TDSNDDON must be set to TDS_ENDREPLY. Otherwise, the conversation shuts down and TDGETREQ returns TDS_CONNECTION_TERMINATED.
In a WFI transaction: The CONN_OPTIONS argument of TDSNDDON must be set to TDS_ENDRPC. TDS_ENDREPLY is not supported for IMS TM implicit transactions.
TDGETREQ puts the transaction into RECEIVE state.
For each new request, the transaction reads in a new login packet. The login packet indicates which type of request is being sent.
You can use long-running transactions with both half-duplex and full-duplex connections.
When a request is present, TDGETREQ returns TDS_OK. If no request is present, the TDGETREQ action depends on the value of the WAIT_OPTION:
When the WAIT_OPTION is TDS_FALSE, TDGETREQ returns TDS_CONNECTION_TERMINATED.
When the WAIT_OPTION is TDS_TRUE, TDGETREQ waits for another request; if the transaction stops, TDGETREQ returns TDS_CONNECTION_TERMINATED.
The implicit API:
Does not support true long-running transactions. However, if an implicit IMS TM transaction is defined as WFI, it can accept multiple requests from any number of workstations for the same mainframe transaction.
When used properly with TDGETREQ, must use a WFI transaction, or the message region that the transaction runs in must have PWFI=Y (Pseudo-Wait-For-Input) specified.
The explicit API:
Must use the same Gateway-Library functions and parameters as CICS programs. All comments in this section apply to explicit IMS TM transactions and to CICS transactions.
Related functions
Related topics
