Open Client Client-Library/C Reference Manual

Home

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Commands

In the client/server model, a server accepts commands from multiple clients and responds by returning data and other information to the clients. Open Client applications use Client-Library routines to communicate commands to servers.

Table 2-18 summarizes the Client-Library command types:

Command types
Command type	Initiated by	Summary
Language	ct_command	Defines the text of a query that the server will parse, interpret, and execute.
RPC, Package	ct_command	Specifies the name of a server procedure (Adaptive Server stored procedure or Open Server registered procedure) to be executed by the server. The procedure must already exist on the server. Package commands are only supported by mainframe Open Server servers. They are otherwise identical to RPC commands.
Cursor	ct_cursor	Initiates one of several commands to manage a Client-Library cursor.
Dynamic SQL	ct_dynamic	Initiates a command to execute a literal SQL statement (with restrictions on statement content) or to manage a prepared dynamic SQL statement.
Message	ct_command	Initiates a message command and specifies the message-command ID number.
Send-Data	ct_command	Initiates a command to upload a large text/image column value to the server.

Sending commands

All commands are defined and sent in three steps:

Initiate the command. This identifies the command type and what it executes.
Define parameter values, if necessary.
Send the command. ct_send writes the command symbols and data to the network. The server then reads the command, interprets it, and executes it.

Initiating a command

An application sends several types of commands to a server:

An application calls ct_command to initiate a language, message, package, remote procedure call (RPC), or send-data command.
An application calls ct_cursor to initiate a cursor command.
An application calls ct_dynamic to initiate a dynamic SQL command.

Defining parameters for a command

The following types of commands take parameters:

A language command, when the command text contains variables
An RPC command, when the stored procedure takes parameters
A cursor declare command, when the body of the cursor contains host variables or when some of the cursor's columns are for update
A cursor open command, when the body of the cursor contains host language parameters
A cursor update command if the text of the update statement contains variables
A message command
A dynamic SQL execute command

An application calls ct_param or ct_setparam once for each parameter a command requires. These routines perform the same function, except that ct_param copies a parameter value, while ct_setparam copies the address of a variable that contains the value. If ct_setparam is used, Client-Library reads the parameter value when the command is sent. This allows the application to change the parameter values that were specified with ct_setparam before resending the command.

Sending a command

After a command has been initiated and its parameters have been defined, an application calls ct_send to send the command to the server. The server then interprets the command, executes it, and returns the results to the client application.

Resending a command

For most command types, Client-Library allows an application to resend the command after the results of previous execution have been processed. Enhancements to ct_send, ct_cursor, and ct_bind, and the addition of ct_setparam routine in version 11.1 allow batch-processing applications to resend commands and reuse binds when repeatedly executing the same server command. This feature can eliminate redundant calls to ct_bind, ct_command, ct_cursor, and ct_param.

The application resends commands as follows:

If necessary, the application changes values in parameter source variables.
If the command requires parameters, the application should define parameter source variables with ct_setparam instead of passing values with ct_param. Input parameter values passed with ct_param can not be changed when a command is resent.
The application calls ct_send to resend the command after the results of the previous command execution have been processed and before a new command is initiated on the command structure.

An application can resend all types of commands except:

Send-data commands initiated by ct_command(CS_SEND_DATA_CMD)
Send-bulk commands initiated by ct_command(CS_SEND_BULK_CMD)
ct_cursor cursor commands other than cursor-update or cursor-delete
ct_dynamic commands other than execute-immediate commands or a command to execute a prepared statement

Deciding which type of command to use

See Chapter 5, "Choosing Command Types," in the Open Client Client-Library/C Programmer's Guide for guidance on which command type is right for your application.


	Expand Search