Initiates a language request or remote procedure call (RPC).
%INCLUDE CTPUBLIC;
DCL 01 COMMAND FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31) INIT(0); 01 REQTYPE FIXED BIN(31) INIT(0); 01 BUFFER type; 01 BUFFER_LEN FIXED BIN(31); 01 OPTION FIXED BIN(31); CALL CTBCOMMA (COMMAND, RETCODE, REQTYPE, BUFFER, BUFFER_LEN, OPTION);
(I) Handle for this client/server operation. This handle is defined in the associated CTBCMDALLOC call. The command handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.
(I) Type of request to initiate. The following symbolic values are legal for REQTYPE:
When REQTYPE is |
CTBCOMMAND 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:
01 BUFFER FIXED BIN(n); 01 BUFFER CHAR(n);
(I) Length, in bytes, of the buffer.
If the value in the buffer is a fixed-length or symbolic value, assign BUFFER_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 REQTYPE is CS_RPC_CMD:
Value |
Meaning |
|---|---|
CS_RECOMPILE (188) |
Recompile the stored procedure before executing. |
CS_NORECOMPILE (189) |
Do not recompile the stored procedure before executing. |
CS_UNUSED (-99999) |
No options are assigned. |
CTBCOMMAND returns one of the following values listed in Table 3-6.
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 CTBCOMMAND. It is taken from the sample program SYCTSAA4 in Appendix A, “Sample Language Application.”
/*------------------------------------------------------------*/
/* allocate a command handle */
/*------------------------------------------------------------*/
CALL CTBCMDAL( CSL_CON_HANDLE,
CSL_RC,
CSL_CMD_HANDLE ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCMDALLOC failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* prepare the language request */
/*------------------------------------------------------------*/
PF_STRLEN = STG(CF_LANG2 ) ;
CALL CTBCOMMA( CSL_CMD_HANDLE,
CSL_RC,
CS_LANG_CMD,
CF_LANG2,
PF_STRLEN,
CS_UNUSED ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCOMMAND failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* send the language request */
/*------------------------------------------------------------*/
CALL CTBSEND( CSL_CMD_HANDLE,
CSL_RC ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBSEND failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
END SEND_COMMAND ;
CTBCOMMAND 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 CTBCOMMAND to initiate the request. CTBCOMMAND sets up internal structures that are used in developing a request stream to send to the server.
Call CTBPARAM to pass parameters for the request. An application must call CTBPARAM once for each parameter in the request.
Call CTBSEND 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 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 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 CTBPARAM 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 uses an RPC to execute a stored procedure or transaction that requires parameters, the application calls CTBPARAM once for each parameter the stored procedure or transaction requires.
After sending an RPC with CTBSEND, an application can process the stored procedure or transaction results with CTBRESULTS and CTBFETCH. The functions CTBRESULTS and CTBFETCH 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:
