Initiates a language request or remote procedure call (RPC).
CS_RETCODE (command, type, buffer, buf_len, option); CS_COMMAND *command; CS_INT type; CS_BYTE *buffer; CS_INT buf_len; CS_INT option;
(I) Handle for this client/server operation. This handle is defined in the associated ct_cmd_alloc call. The command handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
(I) Type of request to initiate. The following symbolic values are legal for type:
When type Is |
ct_command Initiates |
Buffer contains |
|---|---|---|
CS_LANG_CMD (148) |
A language request. |
The text of the language request. |
CS_RPC_CMD (149) |
A remote procedure call. |
The name of the remote procedure. |
(I) Variable (buffer) that contains the language request or RPC name.
This argument is typically one of the following datatypes:
int buffer[n]; char buffer[n];
(I) Length, in bytes, of the buffer.
If the value in the buffer is a fixed-length or symbolic value, assign buf_len a value of CS_UNUSED.
Option associated with this request, if any.
Currently, only RPCs take options. For language requests, assign option a value of CS_UNUSED.
The following symbolic values are legal for option when type is CS_RPC_CMD:
Value |
Meaning |
|---|---|
CS_RECOMPILE (188) |
Recompile the stored procedure before executing it. |
CS_NORECOMPILE (189) |
Do not recompile the stored procedure before executing it. |
CS_UNUSED (-99999) |
No options are assigned. |
ct_command returns one of the following values:
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_FAIL (-2) |
The routine failed. |
TDS_CONNECTION_TERMINATED (-4997) |
The connection is not active. |
TDS_INVALID_PARAMETER (-4) |
A parameter contains an illegal value. |
TDS_WRONG_STATE (-6) |
Program is in the wrong communication state to issue this call. |
The following code fragment demonstrates the use of ct_command. It is taken from the sample program SYCTSAA6 in Appendix A, “Sample Language Application.”
/*-----------------------------------------------------------------*/
/* Open connection to the server or CICS region */
/*-----------------------------------------------------------------*/
rc = ct_connect (connection, servname, server_size);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CONNECT failed", msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Invokes SEND_COMMAND routine */
/*------------------------------------------------------------*/
if (no_errors_sw)
send_command ();
/*------------------------------------------------------------*/
/* Process the results of the command */
/*------------------------------------------------------------*/
if (no_errors_sw)
{
while (no_more_results == FALSE)
proces_results ();
}
} /* end proces_input */
/********************************************************************/
/* */
/* Subroutine to allocate, send, and process commands */
/* */
/********************************************************************/
void send_command ()
{
CS_INT rc;
CS_INT *outlen;
CS_INT buf_len;
CS_CHAR sql_cmd[45];
/*------------------------------------------------------------*/
/* Find out what the maximum number of connections is */
/*------------------------------------------------------------*/
rc = ct_config (context, CS_GET, CS_MAX_CONNECT,
&maxconnect, CS_FALSE, outlen);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CONFIG failed", msg_size);
strncpy (msgtext2, "Please press return to
continue!",text_size);
error_out(rc);
/* reset program flags to move on with the task */
print_once = TRUE;
diag_msgs_initialized = TRUE;
strncpy(msgtext2, "Press Clear To Exit", text_size);
}
/*------------------------------------------------------------*/
/* Allocate a command handle */
/*------------------------------------------------------------*/
rc = ct_cmd_alloc (connection, &cmd);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CMDALLOC failed", msg_size);
no_errors_sw = FALSE ;
error_out(rc);
}
/*------------------------------------------------------------*/
/* Prepare the language request */
/*------------------------------------------------------------*/
strcpy(sql_cmd,
"SELECT FIRSTNME, EDUCLVL FROM SYBASE.SAMPLETB");
buf_len = sizeof(sql_cmd);
rc = ct_command(cmd, (long) CS_LANG_CMD, sql_cmd,
buf_len, (long) CS_UNUSED);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_COMMAND failed", msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Send the language request */
/*------------------------------------------------------------*/
rc = ct_send (cmd);
if (rc != CS_SUCCEED)
{
strcpy (msgstr, "CT_SEND failed", msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
} /* end send_command */
ct_command initiates a language request or RPC. Initiating a request is the first step in sending it to a server.
Sending a request to a server is a three step process. To send a request to a server, an application must:
Call ct_command to initiate the request. ct_command sets up internal structures that are used in developing a request stream to send to the server.
Call ct_param to pass parameters for the request. An application must call ct_param once for each parameter in the request.
Call ct_send to send the request to the server.
Language requests contain character strings that represent requests in a server’s own language. For example, language requests to Adaptive Server Enterprise can include any legal Transact-SQL command.
A language request can be in any language, as long as the server to which it is directed can understand it. For example, Adaptive Server Enterprise understands Transact-SQL, but requests to DB2 must use the DB2 version of SQL.
If the language request string contains variables, an application can pass values for these variables by calling ct_param once for each variable that the language string contains. A language request can have up to 255 parameters.
Transact-SQL request variables must begin with a colon (:).
An RPC instructs a server to execute a stored procedure or transaction on either itself or a remote server.
If an application is using an RPC to execute a stored procedure or transaction that requires parameters, the application calls ct_param once for each parameter the stored procedure or transaction requires.
After sending an RPC with ct_send, an application can process the stored procedure or transaction results with ct_results and ct_fetch. The functions ct_results and ct_fetch are used to process both the result rows generated by the stored procedure or transaction and the return parameters and status, if any.
Related functions
Related topics
