Defines a command parameter.
%INCLUDE CTPUBLIC; DCL 01 COMMAND FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31) INIT(0); 01 DATAFMT, 05 FMT_NAME CHAR(132), 05 FMT_NAMELEN FIXED BIN(31), 05 FMT_TYPE FIXED BIN(31), 05 FMT_FORMAT FIXED BIN(31), 05 FMT_MAXLEN FIXED BIN(31), 05 FMT_SCALE FIXED BIN(31), 05 FMT_PRECIS FIXED BIN(31), 05 FMT_STATUS FIXED BIN(31), 05 FMT_COUNT FIXED BIN(31), 05 FMT_UTYPE FIXED BIN(31), 05 FMT_LOCALE FIXED BIN(31); 01 DATA type; 01 DATALEN FIXED BIN(31); 01 INDICATOR FIXED BIN(15) INIT(0); CALL CTBBIND (COMMAND, RETCODE, DATAFMT, DATA, DATALEN, INDICATOR);
(I) Handle for this client/server operation. This handle is defined in the associated CTBCMDALLOC call.
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.
(I) A structure that contains a description of the parameter. This structure is also used by CTBBIND, CTBDESCRIBE and CSBCONVERT and is explained in “DATAFMT structure”.
Table 3-13 lists the fields in the DATAFMT structure, indicates whether or when they are used by CTBPARAM, and contains general information about the fields.
The programmer is responsible for adhering to these
rules. Client-Library does not enforce them.
When this field |
Is used in this condition |
Set the field to |
|---|---|---|
FMT_NAME |
When defining parameters for all supported commands. |
The name of the parameter being defined. If FMT_NAMELEN is 0, the parameter is considered to be unnamed. Unnamed parameters are interpreted positionally. It is an error to mix named and unnamed parameters in a single command.
When sending parameters with language requests, this must be the variable name as it appears in the language string. Transact-SQL names begin with the colon (:) symbol. |
FMT_NAMELEN |
When defining parameters for all supported commands. |
The length, in bytes, of FMT_NAME. If FMT_NAMELEN is 0, the parameter is considered to be unnamed. |
FMT_TYPE |
When defining parameters for all supported commands. |
The datatype of the parameter value. All datatypes listed under “Datatypes” are valid. |
FMT_FORMAT |
Not used (CS_FMT_UNUSED). |
Not applicable. |
FMT_MAXLEN |
When defining non-fixed-length return parameters for RPCs; otherwise CS_UNUSED. |
The maximum length, in bytes, of the data returned in this parameter. For character or binary data, FMT_MAXLEN must represent the total length of the return parameter, including any space required for special terminating bytes, with this exception: when the parameter is a VARYCHAR datatype such as the DB2 VARCHAR, FMT_MAXLEN does not include the length of the “LL” length specification. For Sybase-decimal and Sybase-numeric, set FMT_MAXLEN to 35. If the parameter is non-return, if FMT_TYPE is fixed-length, or if the application does not need to restrict the length of return parameters, set FMT_MAXLEN to CS_UNUSED. |
FMT_SCALE |
Used for packed decimal, Sybase-decimal, and Sybase-numeric datatypes. |
The number of digits after the decimal point. |
FMT_PRECIS |
Used for packed decimal, Sybase-decimal, and Sybase-numeric datatypes. |
The total number of digits before and after the decimal point. |
FMT_STATUS |
When defining parameters for all types of commands except message commands. |
The type of parameter being defined. One of the following values:
|
FMT_COUNT |
Not used (CS_FMT_UNUSED). |
Not applicable. |
FMT_UTYPE |
Only when defining a parameter that has an Adaptive Server user-defined datatype; otherwise CS_UNUSED. |
The user-defined datatype of the parameter, if any. FMT_UTYPE is set in addition to (not instead of) DATATYPE.
|
FMT_LOCALE |
Not used (CS_FMT_UNUSED). |
Zeroes. |
Variable that contains the parameter data.
To indicate a null parameter (zeroes), assign INDICATOR a value of -1.
If INDICATOR is -1, DATA and DATA_LEN are ignored. For example, an application might pass empty parameters to a stored procedure or transaction that assigns default values to empty input parameters.
The length, in bytes, of the parameter data. For Sybase-numeric and Sybase-decimal, set DATA_LEN to 35.
An integer variable used to indicate an empty parameter. To indicate that a parameter is empty, assign INDICATOR a value of -1. If INDICATOR is -1, DATA and DATA_LEN are ignored.
CTBPARAM returns one of the following values:
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_FAIL (-2) |
The routine failed. |
The following code fragment illustrates the use of CTBPARAM. It is taken from the sample program SYCTSAR4 in Appendix B, “Sample RPC Application.”
/*------------------------------------------------------------*/
/* prepare the command (an RPC request) */
/*------------------------------------------------------------*/
PF_STRLEN = STG(CF_CMD);
CALL CTBCOMMA( CSL_CMD_HANDLE,
CSL_RC,
CS_RPC_CMD,
CF_CMD,
PF_STRLEN,
CS_UNUSED );
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
NO_ERRORS_SW = FALSE ;
MSGSTR = 'CTBCOMMAND failed' ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* */
/* setup a return parameter for NUM_OF_ROWS */
/* */
/* describe the first parameter (NUM_OF_ROWS) */
/* */
/*------------------------------------------------------------*/
DF_NAME = '@parm1';
DF_NAMELEN = 6;
DF_DATATYPE = CS_INT_TYPE;
DF_FORMAT = CS_FMT_UNUSED;
DF_MAXLENGTH = CS_UNUSED;
DF_STATUS = CS_RETURN;
DF_USERTYPE = CS_UNUSED;
PM_LEN = STG(PM_PARAM1);
PM_PARAM1 = 0; /* NUM_OF_ROWS */
PM_NULLIND = 0;
CALL CTBPARAM( CSL_CMD_HANDLE,
CSL_RC,
DATAFMT,
PM_PARAM1,
PM_LEN,
PM_NULLIND );
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
NO_ERRORS_SW = FALSE ;
MSGSTR =
'CTBPARAM CS_INT_TYPE parm1 failed' ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* */
/* describe the second parameter (DEPTNO) */
/* */
/*------------------------------------------------------------*/
DF_NAME = '@parm2';
DF_NAMELEN = 6;
DF_DATATYPE = CS_VARCHAR_TYPE;
DF_FORMAT = CS_FMT_UNUSED;
DF_MAXLENGTH = CS_UNUSED;
DF_STATUS = CS_INPUTVALUE;
DF_USERTYPE = CS_UNUSED;
PM_PARAM2 = PF_DEPT; /* DEPTNO */
PM_LEN = PF_DEPT_SIZE ;
PM_NULLIND = 0;
CALL CTBPARAM( CSL_CMD_HANDLE,
CSL_RC,
DATAFMT,
PM_PARAM2,
PM_LEN,
PM_NULLIND );
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
NO_ERRORS_SW = FALSE ;
MSGSTR =
'CTBPARAM CS_VARCHAR_TYPE parm2 failed' ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* send the command */
/*------------------------------------------------------------*/
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_PARAM ;
An application calls CTBCOMMAND to initiate a language request, RPC or message command.
An application calls CTBPARAM once for each parameter that is sent with the current RPC. It describes each parameter. That description is forwarded to the procedure or transaction called.
CTBPARAM defines parameters for the following types of commands:
Language requests
RPCs
A language request requires input parameter values when the text of the language request contains host variables.
Parameters must be described by CTBPARAM in the same order in which they are sent to the server. The first CTBPARAM call describes the first parameter, the second CTBPARAM call describes the second parameter, and so on, until all parameters are described and sent.
An application calls CTBPARAM with FMT_STATUS as CS_INPUTVALUE to define a parameter value for a language request containing variables.
A language request can have up to 255 parameters.
Table 3-14 lists the fields in the DATAFMT structure that take special values when describing a parameter for a language request.
Field |
Value |
|---|---|
NAME |
The variable name as it appears in the language string. Transact-SQL names begin with the colon (:) character. |
FMT_STATUS |
CS_INPUTVALUE |
All other fields |
Standard CTBPARAM values. |
An application calls CTBPARAM with FMT_STATUS as CS_RETURN to define a return parameter for an RPC, and calls CTBPARAM with FMT_STATUS as CS_INPUTVALUE to define a non-return parameter.
An application can call a stored procedure or transaction in two ways: (1) by sending a language request or (2) by issuing an RPC. See “Remote procedure calls (RPCs)” for a discussion of the differences between these techniques.
To send an RPC, a Client-Library application:
Calls CTBCOMMAND to initiate the request.
Calls CTBPARAM once for each parameter that is being passed to the remote procedure.
Calls CTBSEND to send the request to the server. One CTBSEND forwards the RPC with all defined parameters; the application does not call CTBSEND separately for each parameter.
An RPC can have up to 255 parameters.
The following fields in the DATAFMT structure listed in Table 3-15 take special values when describing an RPC parameter.
Field |
Value |
|---|---|
FMT_NAME |
When sending parameters to an Adaptive Server, FMT_NAME must begin with the “@” symbol, which prefixes all Adaptive Server stored procedure parameter names. |
FMT_MAXLEN |
The maximum length of data to be returned by the server. Set to CS_UNUSED if the parameter is non-return, if FMT_TYPE is fixed-length, or if the application does not need to restrict the length of return parameters. |
FMT_STATUS |
CS_RETURN to indicate that the parameter is a return parameter. CS_INPUTVALUE to indicate that the parameter is not a return parameter. |
All other fields |
Standard CTBPARAM values. |
Table 3-16 lists a summary of CTBPARAM arguments.
Command |
FMT_STATUS value |
DATA, DATA_LEN value |
|---|---|---|
Language request |
CS_INPUTVALUE |
The parameter value and length. |
RPC (return parameters) |
CS_RETURN |
The parameter value and length. |
RPC (non-return parameters) |
CS_INPUTVALUE |
The parameter value and length. |
Related functions:
Related topics:
