Initializes the TDS environment for a connection.
%INCLUDE SYGWPLI;
01 RETCODE FIXED BIN(31), 01 IHANDLE PTR; For CICS: CALL TDINIT (DFHEIBLK, RETCODE, IHANDLE); For IMS TM: CALL TDINIT (IO_PCB, RETCODE, IHANDLE); For MVS: CALL TDINIT (DUMMY, GWL_RC, GWL_INIT_HANDLE);
MVS applications should pass a null pointer to TDINIT.
DUMMY should be declared as: DCL
DUMMY PTR;
(O) Variable where the result of function execution is returned. Its value is one of the codes listed in Table 3-22.
(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.
The RETCODE argument can contain any of the return values listed in Table 3-22.
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. |
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 in Appendix B, “Sample RPC Application for CICS.”
/*------------------------------------------------------------------*/
INITIALIZE_PROGRAM:
/*------------------------------------------------------------------*/
/* ------------------------------------------------------------*/
/* reset db2 error handlers */
/* ------------------------------------------------------------*/
EXEC SQL WHENEVER SQLWARNING CONTINUE;
EXEC SQL WHENEVER SQLERROR CONTINUE;
EXEC SQL WHENEVER NOT FOUND CONTINUE;
/* ------------------------------------------------------------*/
/* establish gateway environment */
/* ------------------------------------------------------------*/
CALL TDINIT (DFHEIBLK, GWL_RC, GWL_INIT_HANDLE);
/* ------------------------------------------------------------*/
/* accept client request */
/* ------------------------------------------------------------*/
CALL TDACCEPT (GWL_PROC, GWL_RC, GWL_INIT_HANDLE,
SNA_CONNECTION_NAME,
SNA_SUBC);
/*------------------------------------------------------------------*/
/* (BODY OF PROGRAM) */
/*------------------------------------------------------------------*/
GO TO END_PROGRAM;
/*------------------------------------------------------------------*/
END_PROGRAM:
/*------------------------------------------------------------------*/
IF SEND_DONE = SEND_DONE_OK THEN
WRK_DONE_STATUS = TDS_DONE_COUNT;
ELSE
DO;
WRK_DONE_STATUS = TDS_DONE_ERROR;
PARM_RETURN_ROWS = 0;
END;
CALL TDSNDDON (GWL_PROC, GWL_RC,
WRK_DONE_STATUS,
PARM_RETURN_ROWS,
TDS_ZERO,
TDS_ENDRPC);
CALL TDFREE (GWL_PROC, GWL_RC);
EXEC CICS RETURN;
END SYSAMP1;
The following code fragment illustrates the use of TDINIT, TDSETPT, and TDACCEPT at the beginning of a Gateway-Library program. This example is taken from the sample program in Appendix D, “Sample RPC Application for IMS TM (Explicit).”
/* -------------------------------------------------------------*/
/* establish gateway environment */
/* ------------------------------------------------------------*/
CALL TDINIT (P_PCBTERM, GWL_RC, GWL_INIT_HANDLE);
[check return code]
/* ------------------------------------------------------------*/
/* 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 client request */
/* ------------------------------------------------------------*/
CALL TDACCEPT (GWL_PROC, GWL_RC, GWL_INIT_HANDLE,
SNA_CONNECTION_NAME,
SNA_SUBC);
[check return code]
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.
This function 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: This is the EXEC Interface Block (EIB). You must code “DFHEIBLK” exactly as shown in the first call in the Syntax example.
Under IMS TM: This is the I/O Program Communications Block. You must code “IO_PCB” exactly as shown in the second call in the Syntax example.
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.
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.
Related functions
Related topics
