ct_param

Description

Supplies values for a server command’s input parameters.

Syntax

CS_RETCODE ct_param(cmd, datafmt, data, datalen, indicator);
 
 CS_COMMAND        *cmd;
 CS_DATAFMT          *datafmt;
 CS_VOID                  *data;
 CS_INT                     datalen;
 CS_SMALLINT          indicator;

Parameters

cmd

A pointer to the CS_COMMAND structure managing a client/server operation.

datafmt

A pointer to a CS_DATAFMT structure that describes the parameter.

For information about how to set these fields for specific uses of ct_param, see “Usage” on page 476.

data

The address of the parameter data.

There are two ways to indicate a parameter with a null value:

  • Pass indicator as -1. In this case, data and datalen are ignored.

  • Pass data as NULL and datalen as 0 or CS_UNUSED.

datalen

The length, in bytes, of the parameter data.

If datafmt−>datatype indicates that the parameter is a fixed-length type, datalen is ignored. CS_VARBINARY and CS_VARCHAR are considered to be fixed-length types.

indicator

An integer variable used to indicate a parameter with a null value. To indicate a parameter with a null value, pass indicator as -1. If indicator is -1, data and datalen are ignored.

Returns

ct_param returns the following values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

CS_BUSY

An asynchronous operation is already pending for this connection. See “Asynchronous programming”.

Examples

Example 1

This code excerpt is from the rpc.c sample program.

          /*
           ** BuildRpcCommand()
           **
           ** Purpose:
           **     Builds an RPC command but does not send it.
           **
           */
          CS_STATIC CS_RETCODE 
           BuildRpcCommand(cmd)
           CS_COMMAND     *cmd;
           {
                CS_CONNECTION   *connection;
                CS_CONTEXT      *context;
                CS_RETCODE      retcode;
                CS_DATAFMT      datafmt;
                CS_DATAFMT      srcfmt;
                CS_DATAFMT      destfmt;
                CS_INT          intvar;
                CS_SMALLINT     smallintvar;
                CS_FLOAT        floatvar;
                CS_MONEY        moneyvar;
                CS_BINARY       binaryvar;
                char            moneystring[10];
                char            rpc_name[15];
                CS_INT           destlen;
               /*
                ** Assign values to the variables used for 
                ** parameter passing.
                */  
                intvar = 2;
                smallintvar = 234;
                floatvar = 0.12;
                binaryvar = (CS_BINARY)0xff;
                strcpy(rpc_name, "sample_rpc");
                strcpy(moneystring, "300.90");
                /*
                ** Clear and setup the CS_DATAFMT structures used 
                ** to convert datatypes.
                */
                memset(&srcfmt, 0, sizeof (CS_DATAFMT));
                srcfmt.datatype = CS_CHAR_TYPE;
                srcfmt.maxlength = strlen(moneystring);
                srcfmt.precision = 5;
                srcfmt.scale = 2;
                srcfmt.locale = NULL;
               memset(&destfmt, 0, sizeof (CS_DATAFMT));
                destfmt.datatype = CS_MONEY_TYPE;
                destfmt.maxlength = sizeof(CS_MONEY);
                destfmt.precision = 5;
                destfmt.scale = 2;
                destfmt.locale = NULL;
               /*
                ** Convert the string representing the money value
                ** to a CS_MONEY variable. Since this routine 
                ** does not have the context handle, we use the 
                ** property functions to get it.
                */
                if ((retcode = ct_cmd_props(cmd, CS_GET,
                     CS_PARENT_HANDLE, &connection, CS_UNUSED,
                     NULL)) != CS_SUCCEED)
                        ...error checking deleted ...
                if ((retcode = ct_con_props(connection, CS_GET,
                     CS_PARENT_HANDLE, &context, CS_UNUSED,
                     NULL)) != CS_SUCCEED)
                       ...error checking deleted ...
               retcode = cs_convert(context, &srcfmt, 
                     (CS_VOID *)moneystring, &destfmt, &moneyvar,
                     &destlen);
                if (retcode != CS_SUCCEED)
                       ...error checking deleted ...
                /*
                ** Initiate the RPC command for our stored
                ** procedure.
                */
                if ((retcode = (cmd, CS_RPC_CMD,
                     rpc_name, CS_NULLTERM, CS_NO_RECOMPILE)) !=
                     CS_SUCCEED)
                         ...error checking deleted ...
               /*
                ** Clear and set up the CS_DATAFMT structure, then 
                ** pass each of the parameters for the RPC.
                */
                memset(&datafmt, 0, sizeof (datafmt));
                strcpy(datafmt.name, "@intparam");
                datafmt.namelen = CS_NULLTERM;
                datafmt.datatype = CS_INT_TYPE;
                datafmt.maxlength = CS_UNUSED;
                datafmt.status = CS_INPUTVALUE;
                datafmt.locale = NULL;
               if ((retcode = ct_param(cmd, &datafmt, 
                     (CS_VOID *)&intvar, sizeof(CS_INT),0))
                    != CS_SUCCEED)
                      ...error checking deleted ...
               strcpy(datafmt.name, "@sintparam");
                datafmt.namelen = CS_NULLTERM;
                datafmt.datatype = CS_SMALLINT_TYPE;
                datafmt.status = CS_RETURN;
                datafmt.locale = NULL;
                if ((retcode = ct_param(cmd, &datafmt, 
                     (CS_VOID *)&smallintvar, 
                     sizeof(CS_SMALLINT), 0)) 
                    != CS_SUCCEED)
                ...error checking deleted ...
               strcpy(datafmt.name, "@floatparam");
                datafmt.namelen = CS_NULLTERM;
                datafmt.datatype = CS_FLOAT_TYPE;
                datafmt.status = CS_RETURN;
                datafmt.locale = NULL;
                if((retcode = ct_param(cmd, &datafmt, 
                     (CS_VOID *)&floatvar,sizeof(CS_FLOAT),0))
                    != CS_SUCCEED)
                       ...error checking deleted ...
               strcpy(datafmt.name, "@moneyparam");
                datafmt.namelen = CS_NULLTERM;
                datafmt.datatype = CS_MONEY_TYPE;
                datafmt.status = CS_RETURN;
                datafmt.locale = NULL;
                if((retcode = ct_param(cmd, &datafmt, 
                     (CS_VOID *)&moneyvar, sizeof(CS_MONEY),0)) 
                    != CS_SUCCEED)
                    ...error checking deleted ...
 
                strcpy(datafmt.name, "@dateparam");
                datafmt.namelen = CS_NULLTERM;
                datafmt.datatype = CS_DATETIME4_TYPE;
                datafmt.status = CS_RETURN;
                datafmt.locale = NULL;
                /*
                ** The datetime variable is filled in by the RPC 
                ** so pass NULL for the data, 0 for data length, 
                ** and -l for the indicator arguments.
                */
                if((retcode = ct_param(cmd, &datafmt, NULL, 0, 
                     -1)) != CS_SUCCEED)
                           ...error checking deleted ...
               strcpy(datafmt.name, "@charparam");
                datafmt.namelen = CS_NULLTERM;
                datafmt.datatype = CS_CHAR_TYPE;
                datafmt.maxlength = EX_MAXSTRINGLEN;
                datafmt.status = CS_RETURN;
                datafmt.locale = NULL;
                /*
                ** The character string variable is filled in by 
                ** the RPC so pass NULL for the data 0 for data 
                ** length, and -l for the indicator arguments.
                */
                if((retcode = ct_param(cmd, &datafmt, NULL, 0, 
                     -1)) != CS_SUCCEED)
                        ...error checking deleted ...
               strcpy(datafmt.name, "@binaryparam");
                datafmt.namelen = CS_NULLTERM;
                datafmt.datatype = CS_BINARY_TYPE;
                datafmt.maxlength = EX_MAXSTRINGLEN;
                datafmt.status = CS_RETURN;
                datafmt.locale = NULL;
                if((retcode = ct_param(cmd, &datafmt, 
                     (CS_VOID *)&binaryvar, 
                     sizeof(CS_BINARY), 0))
                    != CS_SUCCEED)
                      ...error checking deleted ...
               return retcode;
           }

Usage

Table 3-46 summarizes ct_param usage.

Table 3-46: Summary of ct_param parameters

Type of command

Purpose of ct_param call

datafmt->status is

*data, datalen are

Cursor declare

To identify update columns

CS_UPDATECOL

The name of the update column and the name’s length

Cursor declare

To define host variable formats

CS_INPUTVALUE

NULL and CS_UNUSED

Cursor open

To pass parameter values

CS_INPUTVALUE

The parameter value and length

Cursor update

To pass parameter values

CS_INPUTVALUE

The parameter value and length

Dynamic SQL execute

To pass parameter values

CS_INPUTVALUE

The parameter value and length

Language

To pass parameter values

CS_INPUTVALUE

The parameter value and length

Message

To pass parameter values

CS_INPUTVALUE

The parameter value and length

RPC

To pass parameter values

CS_RETURN to pass a return parameter; CS_INPUTVALUE to pass a non-return parameter.

The parameter value and length


Identifying update columns for a cursor declare command


Defining host variable formats


Passing input parameter values

See also

ct_command, ct_cursor, ct_dynamic, ct_send, ct_setparam