ct_param

Description

Defines a command parameter.

Syntax

CS_RETCODE ct_param (command, datafmt, data, datalen,
                      indicator);
CS_COMMAND      *command;
CS_DATAFMT      *datafmt;
CS_BYTE         *data;
CS_INT          datalen;
CS_SMALLINT     indicator;

Parameters

command: (I) Handle for this client/server operation. This handle is defined in the associated ct_cmd_alloc call.

DATAFMT

(I) A structure that contains a description of the parameter. This structure is also used by ct_bind, ct_describe and cs_convert and is explained in “DATAFMT structure”.

Table 3-10 lists the fields in the DATAFMT structure, indicates whether or when they are used by ct_param, and contains general information about the fields.

Table 3-10 contains specific information on how to set these fields when defining a parameter for a particular kind of command.

The programmer is responsible for adhering to these rules. Client-Library does not enforce them.

Table 3-10: Fields in the DATAFMT structure for **ct_param**
When this field	Is used in this condition	Set the field to
name	When defining parameters for all supported commands.	The name of the parameter being defined. If 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 to an Adaptive Server Enterprise, name must begin with the “@” symbol, which prefixes all Adaptive Server Enterprise stored procedure parameter names. 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.
namelen	When defining parameters for all supported commands.	The length, in bytes, of name. If namelen is 0, the parameter is considered to be unnamed.
datatype	When defining parameters for all supported commands.	The datatype of the parameter value. All datatypes listed under “Datatypes” are valid.
format	Not used (CS_FMT_UNUSED).	Not applicable.
maxlength	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, maxlength 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, maxlength does not include the length of the “LL” length specification. For Sybase-decimal and Sybase-numeric, set maxlength to 35. If the parameter is non-return, if datatype is fixed-length, or if the application does not need to restrict the length of return parameters, set maxlength to CS_UNUSED.
scale	Used for packed decimal, Sybase-numeric, and Sybase-decimal datatypes.	The number of digits after the decimal point.
precision	Used for packed decimal, Sybase-numeric, and Sybase-decimal datatypes.	The total number of digits before and after the decimal point.
status	When defining parameters for all types of commands except message commands.	The type of parameter being defined. One of the following values: CS_INPUTVALUE - The parameter is an input parameter value for a non-return RPC parameter or a language request parameter. CS_RETURN - The parameter is a return parameter.
count	Not used (CS_FMT_UNUSED).	Not applicable.
usertype	Only when defining a parameter that has an Adaptive Server Enterprise user-defined datatype; otherwise CS-UNUSED.	The user-defined datatype of the parameter, if any. usertype is set in addition to (not instead of) datatype. This field is used for datatypes defined at the server, not for Open Client user-defined datatypes.
locale	Not used (CS_FMT_UNUSED).	Zeroes.

data: 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.

data_len: The length, in bytes, of the parameter data. For Sybase-numeric and Sybase-decimal, set data_len to 35.

indicator: 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.

Returns

ct_param returns one of the following values:

Value	Meaning
CS_SUCCEED (-1)	The routine completed successfully.
CS_FAIL (-2)	The routine failed.

Examples

Example 1

The following code fragment illustrates the use of ct_param. It is taken from the sample program SYCTSAR6 in Appendix B, “Sample RPC Application.”

  	/*------------------------------------------------------------*/
  	/* Prepare the command (an RPC request)                       */
  	/*------------------------------------------------------------*/
  
         buf_len = 4;
  
         rc = ct_command(cmd, (long) CS_RPC_CMD, rpc_cmd,
                         buf_len, (long) CS_UNUSED);
  
         if (rc != CS_SUCCEED)
         {
            strncpy (msgstr, "CT_COMMAND failed", msg_size);
            no_errors_sw = FALSE ;
            error_out (rc);
         }
  /*------------------------------------------------------------*/
  /*                                                            */
  /* Setup a return parameter for NUM_OF_ROWS                   */
  /*                                                            */
  /* Describe the first parameter (NUM_OF_ROWS)                 */
  /*                                                            */
  /*------------------------------------------------------------*/
  
         strcpy (datafmt.name, "@parm1");
         datafmt.namelen      = 6;
         datafmt.datatype     = CS_INT_TYPE;
         datafmt.format       = CS_FMT_UNUSED;
         datafmt.maxlength    = CS_UNUSED;
         datafmt.status       = CS_RETURN;
         datafmt.usertype     = CS_UNUSED;
  
         buf_len   = sizeof(param1);
         rc = ct_param (cmd, datafmt, param1, buf_len, nullind);
  
         if (rc != CS_SUCCEED)
         {
            strncpy (msgstr, "CT_PARAM CS_INT_TYPE parm1 failed", 
            msg_size) ;
            no_errors_sw = FALSE ;
            error_out (rc);
         }
  /*------------------------------------------------------------*/
  /*                                                            */
  /* Describe the second parameter (DEPTNO)                     */
  /*                                                            */
  /*------------------------------------------------------------*/
  
         strcpy (datafmt.name, "@parm2");
         datafmt.namelen      = 6;
         datafmt.datatype     = CS_VARCHAR_TYPE;
         datafmt.format       = CS_FMT_UNUSED;
         datafmt.maxlength    = CS_UNUSED;
         datafmt.status       = CS_INPUTVALUE;
         datafmt.usertype     = CS_UNUSED;
  
         buf_len   = sizeof(param2);
  
         rc = ct_param (cmd, datafmt, param2, buf_len, nullind);
  
         if (rc != CS_SUCCEED)
         {
            strncpy (msgstr, "CT_PARAM CS_VARCHAR_TYPE parm2 failed",
            msg_size)
 ;
            no_errors_sw = FALSE ;
            error_out (rc);
         }
  /*------------------------------------------------------------*/
  /* Send the command                                           */
  /*------------------------------------------------------------*/
  
         rc = ct_send (cmd);
  
         if (rc != CS_SUCCEED)
         {
            strncpy (msgstr, "CT_SEND failed", msg_size);
            no_errors_sw = FALSE ;
            error_out (rc);
         }
  }   /* end send_command */

Usage

Table 3-11 lists a summary of arguments for ct_parm.

**Table 3-11: Summary of arguments**
Command	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.

An application calls ct_command to initiate a language request, RPC or message command.
An application calls ct_param 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.
ct_param 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 ct_param in the order they are sent to the server. The first ct_param call describes the first parameter, the second ct_param call describes the second parameter, and so on, until all parameters are described and sent.

Defining arguments for language requests

An application calls ct_param with status as CS_INPUTVALUE to define a parameter value for a language request containing variables.

A language request can have up to 255 parameters.

The following fields in the datafmt structure take special values when describing a parameter for a language request. These are listed in Table 3-12.

Table 3-12: Fields in DATAFMT for language request parameters with **ct_param**
Field	Value
name	The variable name as it appears in the language string. Transact-SQL names begin with the colon (:) character.
status	CS_INPUTVALUE
All other fields	Standard ct_param values.

Defining arguments for RPCs

An application calls ct_param with status as CS_RETURN to define a return parameter for an RPC, and calls ct_param with 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 performs the following steps:
1. Calls ct_command to initiate the request.
2. Calls ct_param once for each parameter that is being passed to the remote procedure.
3. Calls ct_send to send the request to the server. One ct_send forwards the RPC with all defined parameters; the application does not issue rc = ct_send separately for each parameter.
An RPC can have up to 255 parameters.

The following fields in the datafmt structure take special values when describing an RPC parameter. These are listed in Table 3-13.

Table 3-13: Fields in *datafmt* for RPC parameters with **ct_param**
Field	Value
name	When sending parameters to an Adaptive Server Enterprise, name must begin with the “@” symbol, which prefixes all Adaptive Server Enterprise stored procedure parameter names.
maxlength	The maximum length of data to be returned by the server. Set to CS_UNUSED if the parameter is non-return, if datatype is fixed-length, or if the application does not need to restrict the length of return parameters.
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 ct_param values.