Accepts a request from a remote client. This function returns the handle for the SNA or TCP/IP conversation in the TDPROC program variable.
COPY SYGWCOB. 01 TDPROC PIC S9(9) USAGE COMP SYNC. 01 RETCODE PIC S9(9 USAGE COMP SYNC. 01 IHANDLE PIC S9(9) USAGE COMP SYNC. 01 ACCEPT-CONNECTION-NAME PIC X(8) VALUE IS SPACES. 01 ERROR-SUBCODE PIC S9(9) USAGE COMP SYNC.
CALL 'TDACCEPT’ USING TDPROC, RETCODE, IHANDLE, ACCEPT-CONNECTION-NAME, ERROR-SUBCODE.
(O) Handle for this client/server connection. All subsequent server functions using this connection must specify this same value in their TDPROC argument. 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-2.
(I) A transaction-wide structure that contains information used to set up the Gateway-Library environment. This must be the same IHANDLE specified in the program’s initial TDINIT call. It corresponds to the context structure in Open Client Client-Library.
(I) Leave blank. CICS and IMS TM get this information elsewhere.
(O) Detailed error information. Provides additional information about the cause of failure when TDACCEPT returns a return code other than TDS-OK. For a list of error subcodes, see Mainframe Connect Client Option and Server Option Messages and Codes.
The RETCODE argument can contain any of the return values listed in Table 3-2.
Return value |
Meaning |
|---|---|
TDS-OK (0) |
Function completed successfully. |
TDS-CHARSET-NOTLOADED (-261) |
Gateway-Library found the DBCS specified by the client, but the corresponding double-byte module was not loaded at the mainframe. This code is retuned to TDACCEPT when a client specifies a DBCS (for example, Shift-JIS) for which the associated translate module was not loaded or defined to the mainframe system. If the TP system is CICS, this can mean that the translate module was not defined in RDO (or to the PPT table), or that it is not present in the LOADLIB. |
TDS-CHARSETSRV-NOT-SBCS (-264) |
The client character set was not found; DBCS specified as default. This code represents two problems:
|
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-DBCS-CHARSET-NOTFOUND (-263) |
Gateway-Library could not find the DBCS specified in the client login packet. This usually indicates that the client request specified an invalid character set in, for example, the -J option in isql or the DBSETLCHARSET value in a DB-Library program. |
TDS-DEFAULT-CHARSET-NOTFOUND (-262) |
The client login packet did not specify a character set or the specified client character set could not be found, and Gateway-Library did not find the default. This code is returned for single-byte character sets only. |
TDS-GWLIB-UNAVAILABLE (-15) |
Could not load SYGWCICS (the Gateway-Library phase). |
TDS-INVALID-IHANDLE (-19) |
Invalid IHANDLE specification. Error in specifying a value for the IHANDLE argument. |
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 was trying to create. The operation failed. |
TDS-USING-DEFAULT-CHARSETSRV (10) |
Gateway-Library using default character set. The client login packet did not specify a character set, or Gateway-Library could not find the specified single-byte character set, so it used the default character set specified during customization. This is an informational message. |
The following code fragment illustrates the use of TDINIT, TDACCEPT, TDRESULT, 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 TDINIT, TDSETPT, and TDACCEPT at the beginning of a Gateway-Library program that uses the IMS implicit API. This example is taken from the sample program in Appendix D, “Sample RPC Application for IMS TM (Implicit).”
* ------------------------------------------------------------------ * establish gateway environment * ------------------------------------------------------------------
CALL ‘TDINIT’ USING IO-PCB, GWL-RC, GWL-INIT-HANDLE.
[check return code]
* ------------------------------------------------------------------
* set program type to MPP
* ------------------------------------------------------------------
CALL ‘TDSETPT’ USING GWL-INIT-HANDLE, GWL-RC, GWL- PROG-TYPE,
GWL-SPA-PTR, TDS-NULL, TDS- NULL.
[check return code]
* ------------------------------------------------------------------
* accept client request
* ------------------------------------------------------------------
CALL ‘TDACCEPT’ USING GWL-PROC, GWL-RC, GWL-INIT-HANDLE,
SNA-CONNECTION-NAME,
SNA-SUBC.
*-----------------------------------------------------------------------
READ-IN-USER-PARM.
*-----------------------------------------------------------------------
A mainframe server application uses TDACCEPT to accept RPCs and language requests from a remote client. It reads in login information and does all necessary translations, including workstation-to-mainframe character set conversions for all supported national languages. This function is required in all Open ServerConnect programs.
TDACCEPT retrieves login information from the login packet sent with the client request. The login packet contains information needed by the mainframe program, including the following:
The client login name and password.
The national language and character set used by the client.
The type of request (language, RPC, cursor or dynamic). If the request is an RPC, the RPC name. If the request is a cursor, the cursor name.
The name of the TRS sending the request (in a three-tier environment), or the name of the Open Server from the interfaces file (in a two-tier environment).
Your program can retrieve information with TDGETUSR.
TDACCEPT returns the handle for the conversation initiated by this client request.
This book uses the term conversation to
refer to active connections for both SNA and TCP/IP.
A successful TDACCEPT puts the server application in RECEIVE state. The server application can then call TDRCVSQL, TDYNAMIC, TDRCVPRM or TDCURPRO to retrieve incoming SQL text, RPC parameters or cursor information. See “Communication states” for a discussion of SEND and RECEIVE states.
TDACCEPT returns standard communication subcodes. These codes are listed in Mainframe Connect Client Option and Server Option Messages and Codes.
Only one TDACCEPT can be in an Open ServerConnect program. If this is a long-running transaction, use TDACCEPT to accept the first client request and TDGETREQ to accept subsequent requests.
After Gateway-Library accepts the client request, it converts the request into a form understood by the mainframe. Roman characters are converted from ASCII to EBCDIC. Japanese characters are converted to IBM-Kanji.
Gateway-Library uses translate tables to do these conversions. Single-byte translate tables can be customized locally. The Japanese Conversion Module has its own set of conversion tables.
The Open ServerConnect environment is customized at the customer site. During customization, you define the type of requests that Gateway-Library will process. Customized items related to international applications include:
The national language used at the mainframe.
The DBCS support flag. This determines whether or not double-byte character sets (DBCS) such as kanji are supported.
The treatment of single-byte character sets, when DBCS are supported. This determines whether they are treated as lowercase roman letters or as Japanese hankaku katakana characters.
The default character set, when the client character set is single-byte.
When TDACCEPT retrieves the client character set from the login packet, it looks up that character set in a table of supported character set names. If it finds a match in that table, it uses the associated translate table or conversion module to convert the request to mainframe characters.
If no character set is specified in the login packet, or if Gateway-Library cannot find a match for the specified client character set, the action taken by TDACCEPT depends on whether or not a double-byte character set was specified during customization.
When the character set is single-byte:
Gateway-Library uses the default character set defined during customization, and TDACCEPT returns TDS-OK.
If Gateway-Library cannot find the default character
set in the character set table, TDACCEPT fails
and returns TDS-DEFAULT-CHARSET-NOTFOUND. If
Gateway-Library finds the default character set, but it is a double-byte
character set, TDACCEPT fails, returning TDS-CHARSETSRV-NOT-SBCS.
When the character set is double-byte:
If the login packet does not specify a character set or specifies one that Gateway-Library cannot match, TDACCEPT fails and returns TDS-DBCS-CHARSET-NOTFOUND.
If Gateway-Library finds the client character set, but the corresponding conversion module (for example, the JCM) was not loaded, TDACCEPT fails and returns TDS-CHARSET-NOTLOADED or TDS-CONTROL-NOT-LOADED.
Japanese requests are processed by the Japanese Conversion Module (JCM), a separate tape that provides Japanese language support for Open ServerConnect. The JCM must be installed and defined to your mainframe system before Gateway-Library can process client requests written in Japanese.
Within a Gateway-Library program, TDINIT loads the JCM. If it cannot load that module, TDINIT does not return an error code. However, when a client request specifies a double-byte character set in the login packet, TDACCEPT returns TDS-CHARSET-NOTLOADED.
If your program uses the JCM, TDACCEPT converts the name of each parameter to the character set used at the mainframe.
Related functions
Related topics
Related documents
Mainframe Connect Client Option and Server Option Messages and Codes
