Chapter 3: Functions

TDINIT

Description

Initializes the TDS environment for a connection.

Syntax

COPY SYGWCOB.

01 RETCODE PIC S9(9)  USAGE COMP SYNC.
01 IHANDLE PIC S9(9)  USAGE COMP SYNC.

For CICS:ThinSpace CALL 'TDINIT' USING DFHEIBLK, RETCODE, IHANDLE.

For IMS TM: CALL 'TDINIT' USING IO-PCB, RETCODE, IHANDLE.

For native MVS: CALL ‘TDINIT’ USING DUMMY, GWL-RC, 
GWL-INIT-HANDLE.

MVS does not need to use anything.

Parameters

RETCODE: (O) Variable where the result of function execution is returned. Its value is one of the codes listed in Table 3-22.

IHANDLE: (I) A transaction-wide structure that contains information used to set up the Gateway-Library environment. All subsequent tracing and accounting functions must specify this same value in their IHANDLE argument. It corresponds to the context structure in Open Client Client-Library.

Returns

The RETCODE argument can contain any of the return values listed in Table 3-22.

**Table 3-22: TDINIT return values**
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-CONTROL-NOTLOADED (-260)	Cannot load the customization module. This module is necessary for Gateway-Library operation.
TDS-GWLIB-BAD-VERSION (-16)	The program version you are using is newer than the version of the Gateway-Library phase in use.
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-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.

Examples

Example 1

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.

Example 2

The following code fragment shows the use of TDINIT, TDSETPT, and TDACCEPT at the beginning of a program that uses the implicit API under IMS TM. 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. 
*-----------------------------------------------------------

Usage

TDINIT initializes the TDS environment for a new client/server connection, preparing the connection for data transfer between the Gateway-Library transaction and the remote client.
TDINIT must be the first Gateway-Library function called in a server program, and can be called only once for a given connection.
TDINIT is also the first function called in a mixed client/server program. See the example in Appendix F, “Sample Mixed-Mode Application.”
The first TDINIT argument is the address of the communication I/O block.

Under CICS: The EXEC Interface Block (EIB). You must code “DFHEIBLK” exactly as shown in the first call under Syntax.

Under IMS TM: The I/O Program Communications Block. You must code “IO-PCB” exactly as shown in the second call under Syntax.

Under MVS: Pass a null pointer. MVS does not use it.

For Open ServerConnect, the conversation is always initiated by the client program. Gateway-Library programs do not initiate conversations.
You customize your Gateway-Library environment when Open ServerConnect is installed. TDINIT loads the customization module. If it cannot load that module, TDINIT returns TDS-CONTROL-NOTLOADED. Without this module, Gateway-Library programs cannot be used.

During customization, the national language and default character sets used at the mainframe are specified. A Gateway-Library program can retrieve customization information with TDGETUSR.

For Japanese users

The Japanese Conversion Module (JCM) processes Japanese requests. The JCM is an option available with Open ServerConnect which must be installed and defined to your mainframe system.
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.
See “Character sets” and “Processing Japanese client requests” for more information about using Gateway-Library with Japanese characters.