Deallocates a command handle.
CS_RETCODE ct_cmd_drop(command); CS_COMMAND *command;
(I) Handle for this client/server operation. This handle is defined in the associated ct_cmd_alloc call. The connection handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
ct_cmd_drop returns one of the following values:
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_FAIL (-2) |
The routine failed. ct_cmd_drop 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 ct_cmd_drop is used with other routines at the end of a program after results have been processed. It is taken from the sample program SYCTSAA6 in Appendix A, “Sample Language Application.”
/***********************************************************************/
/* */
/* Subroutine to perform drop command handler, close server */
/* connection, and deallocate Connection Handler. */
/* */
/***********************************************************************/
void close_connection ()
{
CS_INT rc;
/*---------------------------------------------------------------------*/
/* drop the command handle */
/*---------------------------------------------------------------------*/
rc = ct_cmd_drop (cmd);
if (rc == CS_FAIL)
{
strncpy (msgstr, "CT_CMD_DROP failed", msg_size);
error_out (rc) ;
}
/*------------------------------------------------------------------*/
/* close the server connection */
/*-------------------------------------------------------------------*/
rc = ct_close (connection, (long) CS_UNUSED);
if (rc == CS_FAIL)
{
strncpy (msgstr, "CT_CLOSE failed", msg_size);
error_out (rc) ;
}
/*--------------------------------------------------------------------*/
/* De_allocate the connection handle */
/*--------------------------------------------------------------------*/
rc = ct_con_drop (connection);
if (rc == CS_FAIL)
{
strncpy (msgstr, "CT_CON_DROP failed", msg_size);
error_out (rc) ;
}
} /* end close_connection */
ct_cmd_drop deallocates a command handle.
If ct_cmd_drop is called while a command is pending (which means all results have not been returned), it fails. Before deallocating a command structure, an application should process or cancel any pending results.
Once a command handle has been deallocated, it cannot be reused. To allocate a new command handle, an application calls ct_cmd_alloc.
Related functions
