Chapter 2: Functions

CTBCMDDROP

Description

Deallocates a command handle.

Syntax

COPY CTPUBLIC.

01 COMMAND     PIC S9(9) COMP SYNC.
01 RETCODE     PIC S9(9) COMP SYNC.

CALL 'CTBCMDDR' USING COMMAND RETCODE.

Parameters

COMMAND: (I) Handle for this client/server operation. This handle is defined in the associated CTBCMDALLOC call. The connection handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.

RETCODE: (O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Return value,” in this section.

Returns

CTBCMDDROP returns one of the following values:

Value	Meaning
CS-SUCCEED (-1)	The routine completed successfully.
CS-FAIL (-2)	The routine failed. CTBCMDDROP returns CS-FAIL if the command handle has any results pending.
TDS-COMMAND-ACTIVE (-7)	A command is in progress.
TDS-RESULTS-STILL-ACTIVE (-50)	Some results are still pending.

Examples

Example 1

The following code fragment demonstrates the use of CTBCMDDROP at the end of a program, after results processed. It is taken from the sample program SYCTSAA5 in Appendix A, “Sample Language Requests.”

	*===========================================================
	*==                                                       ==
	*== Subroutine to perform drop command handler, close     ==
	*== server connection, and deallocate Connection Handler. ==
	*==                                                       ==
	*===========================================================
        CLOSE-CONNECTION.
       ***************************
       * DROP THE COMMAND HANDLE *
       ***************************
            CALL 'CTBCMDDR' USING CSL-CMD-HANDLE
                                  CSL-RC.
            IF CSL-RC = CS-FAIL
              THEN
                MOVE SPACES TO MSGSTR
                STRING 'CTBCMDDR failed' DELIMITED BY
                        SIZE INTO MSGSTR
                PERFORM PRINT-MSG
            END-IF.
       *******************************
       * CLOSE THE SERVER CONNECTION *
       *******************************
            CALL 'CTBCLOSE' USING CSL-CON-HANDLE
                                  CSL-RC
                                  CS-UNUSED.
             IF CSL-RC = CS-FAIL
              THEN
                MOVE SPACES TO MSGSTR
                STRING 'CTBCLOSE failed' DELIMITED BY
                        SIZE INTO MSGSTR
                PERFORM PRINT-MSG
            END-IF.
       *************************************
       * DE-ALLOCATE THE CONNECTION HANDLE *
       *************************************
            CALL 'CTBCONDR' USING CSL-CON-HANDLE
                                  CSL-RC.
            IF CSL-RC = CS-FAIL
              THEN
                MOVE SPACES TO MSGSTR
                STRING 'CTBCONDR failed' DELIMITED BY
                        SIZE INTO MSGSTR
                PERFORM PRINT-MSG
            END-IF.
        CLOSE-CONNECTION-EXIT.
            EXIT.

Usage

CTBCMDDROP deallocates a command handle.
If CTBCMDDROP is called while a command is pending (results have not all been returned), it fails. Before deallocating a command structure, an application should process or cancel any pending results.
Once a command handle is deallocated, it cannot be reused. To allocate a new command handle, an application calls CTBCMDALLOC.