Core function

Specify storage, data type, length, and storage location for a parameter marker.

EDSSetParam(HSTMT_IV, PARMNUM_IV, ETYPE_IV, DBTYPE_IV, LENGTH_IV, SCALE_IV, VALUE_SV |VALUE_IV |VALUE_FV, OPTION_IV)

•HSTMT_IV An input integer value that indicates the statement handle associated with the SQL statement.

•PARMNUM_IV An input integer value containing the parameter number. Numbers indicate position of the parameter within the SQL statement, starting with 1 and increasing from left to right.

•ETYPE_IV An input integer value indicating the data type of the VALUE argument as stored in your application. ETYPE_IV must be either EDS_STRING, EDS_INT, or EDS_FLOAT. EDS_SQL_DEFAULT specifies that the parameter value be transferred from the default ESL data type for the SQL type specified by DBTYPE_IV.

•DBTYPE_IV An input integer value indicating the data type of the column as defined by the data source.

•LENGTH_IV An input integer value indicating the length of the data to be inserted into the column in the database. This is only necessary if ETYPE_IV is EDS_STRING. Otherwise, LENGTH_IV can be set to 0.

•SCALE_IV An input integer value indicating the total number of digits to the right of the decimal point in the referenced column. This argument is valid only when SQLTYPE_IV is numeric. This value is returned from the call to EDSDescribeCol.

•VALUE_SV|VALUE_IV|VALUE_FV An input value that contains the actual data for the parameter marker. The data must be in the form specified by the ETYPE_IV argument.

If OPTION_IV is EDS_DATA_AT_EXEC, then the VALUE argument is an application-defined value that is associated with the parameter. It is returned to your application through EDSParamData. (See "Description," below, for additional information.)

To send multiple values for a parameter, your application can set the VALUE argument to an array of parameter values. (See "Description" for additional information.)

•OPTION_IV An input integer value indicating optional usage of EDSSetParam. To specify a null parameter value, your application can set OPTION_IV to EDS_NULL_DATA. If the data for the parameter is to be sent at statement execution time, your application should set OPTION_IV to EDS_DATA_AT_EXEC. (See "Description," for more information.) Otherwise, this argument is ignored.

Description

To pass parameter data, your application does the following:

1.Calls EDSSetParam for each parameter to specify its data type. For EDS_DATA_AT_EXEC parameters, it also associates an application-defined value with the parameter. For all other parameters, it binds the value and length of the parameter to an ESL variable. EDS_DATA_AT_EXEC parameters can be mixed with other parameters.

2.Sets the values for parameters that are bound to variables.

3.Calls EDSExecute or EDSExecDirect to initiate execution of the SQL statement. If there are any EDS_DATA_AT_EXEC parameters, the function returns EDS_NEED_DATA.

4.Performs the following steps to process any EDS_DATA_AT_EXEC parameters:

a.Calls EDSParamData. The application-defined value for the first EDS_DATA_AT_EXEC parameter is returned.

b.Calls EDSPutData one or more times to send data for the parameter.  (More than one call will be needed if the data value is larger than the buffer.)

c.Calls EDSParamData again to signal that all data has been sent for the parameter and to return the application-defined value for the next EDS_DATA_AT_EXEC parameter (if there is one).

d.Repeats steps b and c for the remaining EDS_DATA_AT_EXEC parameters.

EDSParamData returns EDS_NEED_DATA if there are EDS_DATA_AT_EXEC parameters for which data has not been sent. It returns EDS_SUCCESS when data has been sent for all parameters and the statement has been executed successfully. It returns EDS_ERROR if any errors occur. Note that it can return any SQLSTATE that can be returned by the function called to execute the statement (EDSExecute or EDSExecDirect).

Note that when EDSExecDirect or EDSExecute return EDS_NEED_DATA, there are only three functions that can be called until EDSParamData returns EDS_SUCCESS; EDSParamData, EDSPutData, and EDSCancel. Any other function call will return EDS_ERROR and the processing of parameters will not be affected.

Parameter values remain in effect until your application calls EDSSetParam again or calls EDSFreeStmt with the DROP or RESET_PARAMS option.

Where a literal quote character ( ' ) appears in a character string for a parameter, the driver ensures that each literal quote is translated into the form required by the data source. For example, if the data source required that embedded literal quotes be doubled, the driver would replace each quote character ( ' ) with two quote characters ( ' ' )

You can mix parameters for which data is to be sent at statement execution time with other parameters. To specify a parameter for which to send data at execution time, set OPTION_IV to EDS_DATA_AT_EXEC.

This feature is considered extended functionality and can be used to send long data values in portions (for example, parameters of the EDS_SQL_LONGVARBINARY or EDS_SQL_LONGVARCHAR types).

If your application calls EDSParamOptions to specify multiple values for a set of parameters, your application must use the VALUE argument to indicate an array of parameter values. These values are processed with a single SQL statement. (This is considered extended functionality and is not supported by all drivers.)

The data source–specific data types that map to EDS_SQL_LONGVARCHAR and EDS_SQL_LONGVARBINARY are typically unbounded data types; that is, when a column is defined with one of these data types, no length is defined. There is only the data source maximum length for the data type.

For parameters for long data types, LENGTH_IV must be set to the total length of data that will be sent to the data source.

Return Value

EDSSetParam returns EDS_SUCCESS, EDS_INVALID_HANDLE, or EDS_ERROR.

When EDSSetParam returns EDS_ERROR, you can obtain an associated SQLSTATE value with more specific information by calling EDSError. The following table lists each typical SQLSTATE value and explains each one in the context of the command EDSSetParam.

The following table lists possible SQLSTATE values:

See Also

EDSExecute and EDSExecDirect execute a statement.

EDSNumParams retrieves the number of parameters in a SQL statement.

EDSFetch retrieves result rows.

EDSPutData and EDSParamData send large data values to a server.

EDSParamOptions specifies multiple values for a parameter.