ct_cmd_alloc

Allocate a CS_COMMAND structure.

CS_RETCODE ct_cmd_alloc(connection, cmd_pointer)
 
 CS_CONNECTION     *connection;
 CS_COMMAND          **cmd_pointer;

connection: A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.

cmd_pointer: The address of a pointer variable. ct_cmd_alloc sets *cmd_pointer to the address of a newly allocated CS_COMMAND structure.

ct_cmd_alloc returns the following values:

Return value	Meaning
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.
CS_BUSY	An asynchronous operation is already pending for this connection. See “Asynchronous programming”.

The most common reason for a ct_cmd_alloc failure is a lack of memory.

          /* Allocate a command handle to send the text with */

           if ((retcode = ct_cmd_alloc(connection, &cmd)) !=

                CS_SUCCEED)

                ex_error("UpdateTextData: ct_cmd_alloc() failed");

                return retcode;

This code excerpt is from the getsend.c example program.

A CS_COMMAND structure, also called a command structure, is a control structure that a Client-Library application uses to send commands to a server and process the results of those commands.
An application must call ct_con_alloc to allocate a connection structure before calling ct_cmd_alloc to allocate command structures for the connection.

However, it is not necessary that the connection structure represent an open connection. (An application opens a connection by calling ct_connect to connect to a server.)