Chapter 3: Functions

TDFREE

Description

Frees up a previously allocated TDPROC structure after returning results to a client.

Syntax

COPY SYGWCOB.

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

CALL 'TDFREE' USING TDPROC, RETCODE.

Parameters

TDPROC: (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.

RETCODE

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

**Table 3-8: TDFREE return values**
Return value	Meaning
TDS-OK (0)	Function completed successfully.
TDS-CONNECTION-TERMINATED (-4997)	Connection closed. The remote partner closed (deallocated) the client/server connection.
TDS-INVALID-TDPROC (-18)	Error in specifying a value for the TDPROC argument.

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

This code fragment shows the use of TDFREE and TDTERM in a transaction that uses the IMS TM implicit API. This transaction processes multiple client requests, using TDGETREQ to call each request after the first. This example is taken from the sample program in Appendix D, “Sample RPC Application for IMS TM (Implicit).”

*    ----------------------------------------------------------- 
*	  Get next client request 
*    ----------------------------------------------------------- 
      MOVE TDS-TRUE TO GWL-WAIT-OPTION. 
      MOVE ZEROES TO GWL-REQ-TYPE. 
      MOVE SPACES TO GWL-RPC-NAME. 
      CALL ‘TDGETREQ’ USING GWL-PROC, GWL-RC, GWL-WAIT-OPTION, 
                            GWL-REQ-TYPE, GWL-RPC-NAME.

     EVALUATE GWL-RC 
            WHEN ZEROES 
               GO TO READ-IN-USER-PARM 
            WHEN TDS-RESULTS-COMPLETE 
                 PERFORM FREE-ALL-STORAGE 
            WHEN TDS-CONNECTION-TERMINATED 
               PERFORM FREE-ALL-STORAGE 
            WHEN OTHER 
               MOVE ‘TDGETREQ’ TO CALL-ERROR 
               PERFORM DISPLAY-CALL-ERROR 
      END-EVALUATE.  
      GOBACK.

*--------------------------------------------------------------- 
  FREE-ALL-STORAGE. 
*--------------------------------------------------------------- 
      CALL ‘TDFREE’ USING GWL-PROC, GWL-RC. 
      CALL ‘TDTERM’ USING GWL-INIT-HANDLE, GWL-RC.

Usage

An application calls TDFREE to clean up and deallocate the TDPROC structure defined for this connection in TDACCEPT (For TCP/IP applications, this closes the socket). TDFREE does not free up the IHANDLE.

Under CICS

The IHANDLE is automatically freed when the transaction ends.

Typically, a transaction calls TDFREE either at the end of a transaction, or after TDRESULT returns TDS-CONNECTION-TERMINATED or TDS-CONNECTION-FAILED.

Under IMS TM and MVS

The transaction must call TDTERM to free the IHANDLE.

The last call in an IMS TM program, after it has processed all requests, must be TDTERM, which frees all resources, including the IHANDLE, in preparation for program termination. Sybase strongly recommends ending all programs with a TDTERM call.