Initiates a language request or remote procedure call (RPC).
COPY CTPUBLIC.
01 COMMAND PIC S9(9) COMP SYNC. 01 RETCODE PIC S9(9) COMP SYNC. 01 REQTYPE PIC S9(9) COMP SYNC. 01 BUFFER type. 01 BUFFER-LEN PIC S9(9) COMP SYNC. 01 OPTION PIC S9(9) COMP SYNC.
CALL 'CTBCOMMA' USING 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 “Return value,” 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 PIC S9(9) COMP SYNC. 01 BUFFER PIC X(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 it. |
CS-NORECOMPILE (189) |
Do not recompile the stored procedure before executing it. |
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 SYCTSAA5 in Appendix A, “Sample Language Requests.”
*--------------------------------------------------------------
* allocate a command handle
*--------------------------------------------------------------
CALL 'CTBCMDAL' USING CSL-CON-HANDLE,
CSL-RC,
CSL-CMD-HANDLE.
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCMDAL failed' DELIMITED BY SIZE
INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF.
*-------------------------------------------------------------
* prepare the language request
*-------------------------------------------------------------
MOVE CF-LANG2-SIZE TO PF-STRLEN.
CALL 'CTBCOMMA' USING CSL-CMD-HANDLE,
CSL-RC,
CS-LANG-CMD,
CF-LANG2,
PF-STRLEN,
CS-UNUSED.
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCOMMA CS-LANG-CMD failed' DELIMITED BY SIZE
INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF.
*-------------------------------------------------------------
* send the language request
*-------------------------------------------------------------
CALL 'CTBSEND' USING CSL-CMD-HANDLE,
CSL-RC.
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBSEND failed' DELIMITED BY SIZE
INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF.
SEND-COMMAND-EXIT.
EXIT.
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 (:).
RPCs instruct 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
