Level 1 function
Set options that govern connections.
EDSSetConnectOption(HDBC_IV, OPTION_IV, VALUE_IV |VALUE_SV)
•HDBC_IV An input integer value indicating the database connection handle.
•OPTION_IV An input integer value indicating the option to set. Refer to "Description," below.
VALUE_IV | VALUE_SV An input pointer to the value of the option (passed by reference).
Description
The driver can return EDS_SUCCESS_WITH_INFO to provide information about the result of setting an option. For example, setting EDS_AUTOCOMMIT during a transaction might cause the transaction to be committed. The driver could use EDS_SUCCESS_WITH_INFO and information returned with EDSError to inform your application of the commit action.
The currently defined options are shown in the table on the next page; it is expected that more will be defined to take advantage of different data sources. Option numbers 1–999 are reserved by ODBC; driver writers can reserve values greater than 999 for driver-specific uses.
An application can call EDSSetConnectOption and include a statement option. The driver sets the statement option for any HSTMTs associated with the specified connection handle and establishes the statement option as a default for any HSTMTs later allocated for that connection handle. For a list of statement options, refer to EDSSetStmtOption.
All connection and statement options set for the connection handle persist until EDSFreeConnect is called on the connection handle.
The type of information set via the VALUE parameter depends on the specified OPTION_IV. EDSSetConnectOption will accept option information in one of two different formats: a string or an integer value. The format of each is noted in the option’s description. This format applies to the information returned for each option in SQLGetConnectOption. Character strings returned by SetConnectOption have a maximum length of 256 bytes (excluding the null termination byte).
OPTION_IV |
Contents |
EDS_ACCESS_MODE |
An integer value. EDS_MODE_READ_ONLY is used by the driver or data source as an indicator that the connection is not required to support SQL statements that cause updates to occur. This mode can be used to optimize locking strategies, transaction management, or other areas as appropriate to the driver or data source. The driver is not required to prevent such statements from being submitted to the data source. The behavior of the driver and data source when asked to process SQL statements that are not read-only during a read-only connection is implementation-defined. EDS_MODE_READ_WRITE is the default. |
EDS_AUTOCOMMIT |
An integer value. If VALUE_IV equals 1, each statement is implicitly committed: 0 = Off 1 = On (the default) |
EDS_LOGIN_TIMEOUT |
An integer value corresponding to the number of seconds to wait for a login request to complete before returning to your application. The default is 15. If VALUE_IV is 0, the timeout is disabled and a connection attempt will wait indefinitely. |
EDS_OPT_TRACE |
An integer value telling the Driver Manager whether to perform tracing: 0 = Tracing off (the default) 1 = Tracing on |
EDS_OPT_TRACEFILE |
A string containing the name of the trace file. If tracing is enabled, the Driver Manager writes to this file each time your application calls a function. If no trace filename is specified, the Driver Manager writes to the SQL.LOG. |
EDS_TXN_ISOLATION |
An integer value that sets the transaction isolation level for the current connection handle. The valid values for VALUE_IV can be determined by calling EDSGetInfo with INFOTYPE_IV = EDS_TXN_ISOLATION_OPTIONS. VALUE_IV must be one of the following values: EDS_TXN_READ_UNCOMMITTED = Changes are immediately perceived by all transactions (dirty read, non repeatable read, and phantoms are possible). EDS_TXN_READ_COMMITTED = Row read by transaction 1 can be altered and committed by transaction 2 (non repeatable read and phantoms are possible). EDS_TXN_REPEATABLE_READ = A transaction can add or remove rows matching the search condition or a pending transaction (repeatable read, but phantoms are possible). EDS_TXN_SERIALIZABLE = Data affected by pending transaction is not available to other transactions (repeatable read, but phantoms are not possible). EDS_TXN_VERSIONING = Data affected by pending transaction is not available to other transactions, but higher concurrency is possible than with isolation level 3. Typically, level 3 is attained by using locking protocols that reduce concurrency; level 4 is typically attained by a non-locking protocol such as “record versioning.” For example, Oracle’s™ Read Consistency isolation level is level 4. |
Return Value
EDSSetConnectOption returns EDS_SUCCESS, EDS_SUCCESS_WITH_INFO, EDS_INVALID_HANDLE, or EDS_ERROR.
When EDSSetConnectOption 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 EDSSetConnectOption.
The following table lists possible SQLSTATE values:
SQL STATE |
Error |
Description |
08003 |
Connection not open |
An OPTION_IV value was specified that required an open connection, but the connection handle was not in a connected state. |
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 associated with the connection 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 VALUE argument. |
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 settings of connection options.
EDSSetStmtOption sets statement options
