Level 1 subroutine
Set options related to a statement handle.
call EDSSetStmtOption(HSTMT_IV, OPTION_IV, VALUE_IV)
•HSTMT_IV An input integer value that indicates the statement handle.
•OPTION_IV An input integer value indicating the option to set, listed under "Description".
•VALUE_IV An input integer value indicating the value of the option.
Description
To set an option for all statements associated with a specific connection handle, your application can call EDSSetConnectOption.
Statement options for a statement handle remain in effect until they are changed by another call to EDSSetStmtOption or the statement handle is dropped by calling EDSFreeStmt with the EDS_DROP option. Calling EDSFreeStmt with the EDS_CLOSE, EDS_UNBIND, or EDS_RESET_PARAMS options does not reset statement options.
The format of information set via VALUE_IV depends on the specified OPTION_IV. EDSSetStmtOption will accept option information in one of two different formats: string or integer. The format of each is noted in the option's description. This format applies to the information returned for each option in EDSGetStmtOption. Strings returned by EDSGetStmtOption have a maximum length of 256 bytes.
The following functions can be run asynchronously:
The currently-defined options are shown in the following table; it is expected that more will be defined to take advantage of different data sources. OPTION_IV numbers 1-999 are reserved by ODBC; driver writers can reserve values greater than 999 for driver-specific uses.
OPTION_IV |
Contents |
EDS_ASYNC_ENABLE |
Once a function has been called asynchronously, no other functions can be called on the associated statement handle (or connection handle associated with the statement handle) except for EDSCancel, the original function, or EDSGetFunctions, until the original function returns other than EDS_STILL_EXECUTING. Any other function will return EDS_ERROR with a SQLSTATE of S1010 (function sequence error). If VALUE_IV equals 1, the driver enables asynchronous behavior for function calls associated with the specified statement handle: 0=Off (the default) 1=On |
EDS_BIND_TYPE |
Sets the binding orientation to be used when EDSExtendedFetch is called on the associated statement handle. Column-wise binding is selected by supplying the defined constant EDS_BIND_BY_COLUMN for the argument VALUE_IV. Column-wise binding is the default binding orientation for EDSExtendedFetch. The length specified in VALUE_IV must include space for all of the bound columns and any padding of the structure or buffer to ensure that when the address of a bound column is incremented with the specified length, the result will point to the beginning of the same column in the next row. |
EDS_MAX_LENGTH |
Maximum amount of data that can be retrieved from a single column with a LONGVARCHAR or LONGVARBINARY data type. If data is truncated because the value specified for EDS_MAX_LENGTH is less than the amount of data available, EDSGetData or EDSFetch will return EDS_SUCCESS instead of returning EDS_SUCCESS_WITH_INFO and SQLSTATE 01004 (data truncated). If VALUE_IV equals 0 (the default), the driver attempts to return all available data for long variable length columns. |
EDS_NOSCAN |
If EDS_TRUE, the driver does not scan SQL strings for escape clauses. Instead, the driver sends the statement directly to the data source. If EDS_FALSE (the default), the driver scans for escape clauses. |
EDS_QUERY_TIMEOUT |
Number of seconds to wait for a SQL statement to execute before returning to your application. If VALUE_IV equals 0 (the default), then there is no time out. Note that your application need not call EDSFreeStmt with the EDS_CLOSE option to reuse the statement handle if a SELECT statement timed out. |
EDS_MAX_ROWS |
Maximum number of rows to return to your application for a SELECT statement. If VALUE_IV equals 0 (the default), then the driver returns all rows. |
Return Value
EDSSetStmtOption returns EDS_SUCCESS, EDS_INVALID_HANDLE, or EDS_ERROR.
When EDSSetStmtOption 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 EDSSetStmtOption.
The following table lists possible SQLSTATE values:
SQL STATE |
Error |
Description |
08S01 |
Communication link failure |
The communication link between the driver and the data source to which the driver was connected failed before the function completed processing. |
IM001 |
Driver does not support this function |
The driver corresponding to the statement handle does not support the function. |
S1000 |
General error |
An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by EDSError in the argument ERRORTEXT describes the error and its cause. |
S1001 |
Memory allocation failure |
The driver was unable to allocate the memory required to support execution or completion of the function. |
S1009 |
Invalid argument value |
Given the specified OPTION_IV value, an invalid value was specified for the argument VALUE_IV. |
S1010 |
Function sequence error |
An asynchronously executing function (not this one) was called for the statement handle and was still executing when this function was called. |
S1092 |
Option type out of range |
An invalid OPTION_IV value was specified. |
S1C00 |
Driver not capable |
The driver or data source does not support the specified OPTION_IV. |
See Also
EDSGetConnectOption retrieves the current setting of a connection option.
EDSSetConnectOption sets connection options or setting statement options for all statements associated with a specific connection.
EDSGetStmtOption retrieves the setting of a statement option.
