Deallocates a command handle.
%INCLUDE CTPUBLIC;
DCL 01 COMMAND FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31) INIT(0); CALL CTBCMDDR (COMMAND, RETCODE);
(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.
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.
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. |
The following code fragment demonstrates how CTBCMDDROP is used with other routines at the end of a program after results have been processed. It is taken from the sample program SYCTSAA4 in Appendix A, “Sample Language Application.”
/*------------------------------------------------------------------*/
/* */
/* Subroutine to perform drop command handler, close server */
/* connection, and deallocate Connection Handler. */
/* */
/*------------------------------------------------------------------*/
CLOSE_CONNECTION: PROC ;
/*------------------------------------------------------------------*/
/* drop the command handle */
/*------------------------------------------------------------------*/
CALL CTBCMDDR( CSL_CMD_HANDLE,
CSL_RC ) ;
IF CSL_RC = CS_FAIL THEN
DO ;
MSGSTR = 'CTBCMDDROP failed' ;
CALL ERROR_OUT ;
END ;
/*------------------------------------------------------------------*/
/* close the server connection */
/*------------------------------------------------------------------*/
CALL CTBCLOSE( CSL_CON_HANDLE,
CSL_RC,
CS_UNUSED ) ;
IF CSL_RC = CS_FAIL THEN
DO ;
MSGSTR = 'CTBCLOSE failed' ;
CALL ERROR_OUT ;
END ;
/*------------------------------------------------------------------*/
/* DE_ALLOCATE THE CONNECTION HANDLE */
/*------------------------------------------------------------------*/
CALL CTBCONDR( CSL_CON_HANDLE,
CSL_RC ) ;
IF CSL_RC = CS_FAIL THEN
DO ;
MSGSTR = 'CTBCONDROP failed' ;
CALL ERROR_OUT ;
END ;
END CLOSE_CONNECTION ;
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.
Related functions:
