Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 3 Routines

ct_send

Usage

Usage

• ct_send sends a command over the network for the server to execute.

• Before calling ct_send, the application must specify the type of command and the data needed for its execution. Once this step is done, the command structure is said to be initiated. The routines ct_command, ct_cursor, or ct_dynamic initiate a command.

  See Chapter 5, "Choosing Command Types," in the Open Client-Client Library/C Programmer's Guide for a description of the server commands available to a Client-Library application.

• For most command types, ct_send can be called to resend a previously executed command after all the results from the previous execution have been handled. Exceptions are noted under "Resending commands".

• Sending a command to a server for first-time execution is a multi-step process:

  1. Initiate the command by calling ct_command, ct_cursor, or ct_dynamic. These routines set up internal structures that are used in building a symbolic command stream to send to the server.

  2. Pass parameters for the command (if required) by calling ct_param or ct_setparam once for each parameter that the command requires.

     Not all commands require parameters. For example, a remote procedure call command may or may not require parameters, depending on the stored procedure being called.

  3. Send the command to the server by calling ct_send. ct_send writes the symbolic command stream onto the command structure's parent connection.

  4. Handle the results of command execution by calling ct_results repeatedly until it no longer returns CS_SUCCEED. See "Results" for a discussion of processing results.

• An application can call ct_cancel(CS_CANCEL_ALL) to cancel a command that has been initiated but not yet sent. But after an application has sent a command, it must call ct_results before calling ct_cancel to cancel the results of command execution.

• ct_send uses an asynchronous write and does not wait for a response from the server. An application must call ct_results to verify the success of the command and to set up the command results for processing.

• Most types of commands can be resent immediately after all the results of the previous command have been handled. The exceptions are:

  • Send-data commands initiated by ct_command(CS_SEND_DATA_CMD).

  • Send-bulk commands initiated by ct_command(CS_SEND_BULK_CMD)

  For all other types of commands, the application can resend the command with ct_send immediately after the application has processed all the results of the previous execution. Client-Library does not discard the initiated command information until the application initiates a new command with ct_command, ct_cursor, ct_dynamic, or ct_sendpassthru.

• In general, applications that resend commands should supply command parameters with ct_setparam rather than ct_param.

  • ct_setparam allows the application to change parameter values before resending the command. ct_setparam accepts pointers to program variables that contain parameter values. The variables' contents are read by subsequent calls to ct_send. The binding between command parameters and program variables persists until the application initiates a new command with ct_command, ct_cursor, ct_dynamic, or ct_sendpassthru.

  • ct_param copies data from program variables before it returns. If ct_param is called to supply command parameters, the parameter values cannot be changed when the command is resent.

  If a parameter is effectively a literal value (that is, it will not change), then it is appropriate for the application to define the parameter with ct_param even if the command will be resent.

• An application can check the CS_HAVE_CMD property to see if a resendable command exists for the command structure. See "Have resendable command" for a description of this property.

• Applications which resend commands may be able to use the CS_STICKY_BINDS property to eliminate redundant ct_bind calls. See "Persistent result bindings " for a description of this property.