Initiate a language, package, RPC, message, or send-data command.
CS_RETCODE ct_command(cmd, type, buffer, buflen,
option)
CS_COMMAND *cmd;
CS_INT type;
CS_VOID *buffer;
CS_INT buflen;
CS_INT option;
A pointer to the CS_COMMAND structure managing a client/server operation.
The type of command to initiate. Table 3-9 lists the symbolic values for type.
A pointer to data space. Table 3-9 lists the datatypes and meanings for *buffer values.
The length, in bytes, of the *buffer data, or CS_UNUSED if *buffer represents a fixed-length or symbolic value.
The option associated with this command.
Language, RPC (remote procedure call), send-data, and send-bulk-data commands take options. For all other types of commands, pass option as CS_UNUSED.
The following table lists the symbolic values for option:
type is |
Value of option |
Meaning |
|---|---|---|
CS_LANG_CMD |
CS_MORE |
The text in buffer is only part of the language command to be executed. |
CS_END |
The text in buffer is the last part of the language command to be executed. |
|
CS_UNUSED |
Equivalent to CS_END. |
|
CS_RPC_CMD |
CS_RECOMPILE |
Recompile the stored procedure before executing it. |
CS_NO_RECOMPILE |
Do not recompile the stored procedure before executing it. |
|
CS_UNUSED |
Equivalent to CS_NO_RECOMPILE. |
|
CS_SEND_DATA_CMD |
CS_COLUMN_DATA |
The data will be used for a text or image column update. |
CS_BULK_DATA |
For internal Sybase use only. The data will be used for a bulk copy operation. |
|
CS_SEND_BULK_CMD |
CS_BULK_INIT |
For internal Sybase use only. Initialize a bulk copy operation. |
CS_BULK_CONT |
For internal Sybase use only. Continue a bulk copy operation. |
ct_command returns the following values:
Returns |
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”. |
/*
** ex_execute_cmd()
**
** Type of function:
** example program utility api
**
** Purpose:
** Sends a language command to the server.
*/
CS_RETCODE CS_PUBLIC
ex_execute_cmd(connection, cmdbuf)
CS_CONNECTION *connection;
CS_CHAR *cmdbuf;
{
CS_RETCODE retcode;
CS_INT restype;
CS_COMMAND *cmd;
CS_RETCODE query_code;
/*
** Get a command structure,store the command string in it,
** and send it to the server.
*/
if ((retcode = ct_cmd_alloc(connection, &cmd)) !=
CS_SUCCEED)
{
ex_error("ex_execute_cmd: ct_cmd_alloc() failed");
return retcode;
}
if ((retcode = ct_command(cmd, CS_LANG_CMD, cmdbuf,
CS_NULLTERM, CS_UNUSED)) != CS_SUCCEED)
{
ex_error("ex_execute_cmd: ct_command() failed");
(void)ct_cmd_drop(cmd);
return retcode;
}
/* Now send the command and process the results */
... ct_send, ct_results, and so forth deleted ...
return CS_SUCCEED;
}
This code excerpt is from the exutils.c example program.
Table 3-9 summarizes ct_command usage.
Value of type |
Command initiated |
buffer is |
buflen is |
|---|---|---|---|
CS_LANG_CMD |
A language command |
A pointer to a CS_CHAR array that contains all or part of the language command text. Use the CS_MORE and CS_END options to build the command text in pieces. See Table 3-8 for details. |
The length of the *buffer data or CS_NULLTERM. |
CS_MSG_CMD |
A message command |
A pointer to a CS_INT variable that contains the message ID. |
CS_UNUSED |
CS_PACKAGE_CMD |
A package command |
A pointer to a CS_CHAR array that contains the name of the package. |
The length of the *buffer data or CS_NULLTERM. |
CS_RPC_CMD |
A remote procedure call command |
A pointer to a CS_CHAR array that contains the name of the remote procedure. |
The length of the *buffer data or CS_NULLTERM. |
CS_SEND_DATA_CMD |
A send-data command |
NULL. |
CS_UNUSED. |
CS_SEND_BULK_CMD |
A Sybase internal send-bulk-data command |
A pointer to a CS_CHAR array that contains the database table name. |
The length of the *buffer data or CS_NULLTERM. |
ct_command initiates several types of server commands.
For an overview of Client-Library command types, see Chapter 5, “Choosing Command Types,” in the Open Client Client-Library/C Programmer’s Guide.
Initiating a command is the first step in sending it to a server. For a client application to execute a server command, Client-Library must convert the command to a symbolic command stream that can be sent to the server. The command stream contains information about the type of the command and the data needed for execution. For example, an RPC command requires a procedure name, the number of parameters, and (if needed) parameter values.
The steps for executing a server command with ct_command are as follows:
Initiate the command by calling ct_command. This step sets up internal structures that are used in building a command stream to send to the server.
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.
Send the command to the server by calling ct_send. ct_send writes the symbolic command stream onto the command structure’s parent connection.
Handle the results of the command by calling ct_results repeatedly until it no longer returns CS_SUCCEED. See Chapter 6, “Writing Results-Handling Code,” in the Open Client Client-Library/C Programmer’s Guide for a discussion of processing results.
ct_command command types other than send-data commands or send-bulk commands can be resent by calling ct_send immediately after the application has processed the results of the previous execution. Client-Library saves the initiated command information in the command structure until the application initiates a new command with ct_command, ct_cursor, ct_dynamic, or ct_sendpassthru. If parameter source variables for the command were specified with ct_setparam, then the application can change the parameter values without calling ct_setparam again. See “Resending commands” for more information on this feature.
An application can call ct_cancel with type as CS_CANCEL_ALL to clear a command that has been initiated but not yet sent.
The following rules apply to the use of ct_command:
When a command structure is initiated, an application must either send the initiated command or clear it before a new command can be initiated with ct_command, ct_cursor, ct_dynamic, or ct_sendpassthru.
After sending a command, an application must completely process or cancel all results returned by the command’s execution before initiating a new command on the same command structure.
An application cannot call ct_command to initiate a command on a command structure that is managing a cursor. The application must deallocate the cursor first (or use a different command structure).
Each section below contains information about one of the types of commands that ct_command can initiate.
A language command contains a character string that represents one or more command in a server’s own language. For example, the following language command contains a Transact-SQL command:
ct_command(cmd, CS_LANG_CMD,
"select * from pubs2..authors",
CS_NULLTERM,
CS_UNUSED);
ct_command’s CS_MORE and CS_END option values allow the application to append text to the language buffer. Language command text can be assembled in pieces with consecutive calls.
The language buffer can represent more than one server commands. For example, the following sequence builds a language command containing three Transact-SQL statements:
ct_command(cmd, CS_LANG_CMD,
“select * from pubs2..titles ”,
CS_NULLTERM, CS_MORE);
ct_command(cmd, CS_LANG_CMD,
“select * from pubs2..authors ”,
CS_NULLTERM, CS_MORE);
ct_command(cmd, CS_LANG_CMD,
“select * from pubs2..publishers ”,
CS_NULLTERM, CS_END);
ct_command does not add white space when appending to the command buffer and the space must therefore be specified by the user.
When the CS_UNUSED option is specified, Client-Library requires the application to pass the entire language text in one call to ct_command.
A language command can be in any language, as long as the server to which it is directed can understand it. Adaptive Server understands Transact-SQL, but an Open Server application constructed with Server-Library can be written to understand any language.
If the language command string contains host variables, an application can pass values for these variable by calling ct_param or ctsetparam once for each variable that the language string contains. Use ct_setparam if the command will be sent to the server more than once. See “Resending commands” for more information.
Transact-SQL variables must begin with an @ sign.
An Adaptive Server language cursor generates a regular row result set when an application calls ct_command to execute a fetch language command against the cursor. The Transact-SQL fetch command generates regular row results containing a number of rows equal to the current “cursor rows” setting for the language cursor.
Message commands and results provide a way for clients and servers to communicate specialized information to one another. A message command is similar to an RPC command, but the command is identified by a number (called the message ID) rather than by an RPC name.
A message command has an ID, which an application provides in a CS_INT variable. The application passes the address of the CS_INT as ct_command’s buffer parameter.
A custom Open Server application can be programmed with an event handler that responds to user-defined messages. IDs for user-defined messages must be greater than or equal to CS_USER_MSGID and less than or equal to CS_USER_MAX_MSGID.
If a message requires parameters, the application calls ct_param or ct_setparam once for each parameter that the message requires. Use ct_setparam if the RPC command will be sent to the server more than once. See “Resending commands” for more information.
A package command instructs an IBM DB/2 database server to execute a package. A package is similar to a remote procedure. It contains precompiled SQL statements that are executed as a unit when the package is invoked.
If the package requires parameters, the application calls ct_param or ct_setparam once for each parameter that the package requires. Use ct_setparam if the package command will be sent to the server more than once. See “Resending commands” for more information.
An RPC (remote procedure call) command instructs a server to execute a stored procedure either on this server or a remote server.
An application initiates an RPC command by calling ct_command with *buffer as the name of the stored procedure to execute.
If an application is using an RPC command to execute a stored procedure that requires parameters, the application must call ct_param or ct_setparam once for each parameter required by the stored procedure. Use ct_setparam if the RPC command will be sent to the server more than once. See “Resending commands” for more information.
After sending an RPC command with ct_send, an application processes the stored procedure’s results with ct_results and ct_fetch. ct_results and ct_fetch are used to process both the result rows generated by the stored procedure and the return parameters and status from the procedure, if any.
An alternative way to call a stored procedure is by executing a language command containing a Transact-SQL execute statement. When a stored procedure is executed through a language command, parameter values may be converted to character format (if necessary) and passed as part of the language command text, or they may be included in the command as host variables. With an RPC command, parameters can be passed in their declared datatypes with ct_param or ct_setparam.
An application uses a send-data command to write large amounts of text or image data to a server.
An application typically calls:
ct_command to initiate the send-data command.
ct_data_info to set the I/O descriptor for the operation.
ct_send_data to write the value, in chunks, to the data stream.
ct_send to send the command to the server.
Send-data commands cannot be re-sent.
For more information about writing text or image values, see “text and image data handling”.
Internally, Sybase uses send-bulk-data commands as part of its implementation of the Bulk-Library routines.
Send-bulk-data commands cannot be re-sent.
ct_cmd_alloc, ct_cursor, ct_dynamic, ct_param, ct_send, ct_setparam
