An application can call SQLSetEnvAttr only if no connection handle is allocated on the environment. All environment attributes successfully set by the application for the environment persist until SQLFreeHandle is called on the environment. More than one environment handle can be allocated simultaneously in ODBC 3.x.
The format of information set through ValuePtr depends on the specified Attribute. SQLSetEnvAttr will accept attribute information in one of two different formats: a null-terminated character string or a 32-bit integer value. The format of each is noted in the attribute's description.
There are no driver-specific environment attributes.
Connection attributes cannot be set by a call to SQLSetEnvAttr. Trying to do this will return SQLSTATE HY092 (Invalid attribute/option identifier).
| Attribute | ValuePtr contents
|
| SQL_ATTR_CONNECTION_POOLING (ODBC 3.0) | A 32-bit SQLUINTEGER value that enables or disables connection pooling at the environment level. The following values are used: SQL_CP_OFF = Connection pooling is turned off. This is the default. SQL_CP_ONE_PER_DRIVER = A single connection pool is supported for each driver. Every connection in a pool is associated with one driver. SQL_CP_ONE_PER_HENV = A single connection pool is supported for each environment. Every connection in a pool is associated with one environment. Connection pooling is enabled by calling SQLSetEnvAttr to set the SQL_ATTR_CONNECTION_POOLING attribute to SQL_CP_ONE_PER_DRIVER or SQL_CP_ONE_PER_HENV. This call must be made before the application allocates the shared environment for which connection pooling is to be enabled. The environment handle in the call to SQLSetEnvAttr is set to null, which makes SQL_ATTR_CONNECTION_POOLING a process-level attribute. After connection pooling is enabled, the application then allocates an implicit shared environment by calling SQLAllocHandle with the InputHandle argument set to SQL_HANDLE_ENV. -
After connection pooling has been enabled and a shared environment has been selected for an application, SQL_ATTR_CONNECTION_POOLING cannot be reset for that environment, because SQLSetEnvAttr is called with a null environment handle when setting this attribute. If this attribute is set while connection pooling is already enabled on a shared environment, the attribute affects only shared environments that are allocated subsequently.
For more information, see ODBC Connection Pooling. |
| SQL_ATTR_CP_MATCH (ODBC 3.0) | A 32-bit SQLUINTEGER value that determines how a connection is chosen from a connection pool. When SQLConnect or SQLDriverConnect is called, the Driver Manager determines which connection is reused from the pool. The Driver Manager tries to match the connection options in the call and the connection attributes set by the application to the keywords and connection attributes of the connections in the pool. The value of this attribute determines the level of precision of the matching criteria. The following values are used to set the value of this attribute: SQL_CP_STRICT_MATCH = Only connections that exactly match the connection options in the call and the connection attributes set by the application are reused. This is the default. SQL_CP_RELAXED_MATCH = Connections with matching connection string keywords can be used. Keywords must match, but not all connection attributes must match. For more information about how the Driver Manager performs the match in connecting to a pooled connection, see SQLConnect. For more information about connection pooling, see ODBC Connection Pooling. |
| SQL_ATTR_ODBC_VERSION (ODBC 3.0) | A 32-bit integer that determines whether certain functionality exhibits ODBC 2.x behavior or ODBC 3.x behavior. The following values are used to set the value of this attribute: SQL_OV_ODBC3 = The Driver Manager and driver exhibit the following ODBC 3.x behavior: -
The driver returns and expects ODBC 3.x codes for date, time, and timestamp. -
The driver returns ODBC 3.x SQLSTATE codes when SQLError, SQLGetDiagField, or SQLGetDiagRec is called. -
The CatalogName argument in a call to SQLTables accepts a search pattern. -
The Driver Manager does not support C data type extensibility.
SQL_OV_ODBC2 = The Driver Manager and driver exhibit the following ODBC 2.x behavior. This is especially useful for an ODBC 2.x application working with an ODBC 3.x driver. -
The driver returns and expects ODBC 2.x codes for date, time, and timestamp. -
The driver returns ODBC 2.x SQLSTATE codes when SQLError, SQLGetDiagField, or SQLGetDiagRec is called. -
The CatalogName argument in a call to SQLTables does not accept a search pattern. -
The Driver Manager does not support C data type extensibility.
An application must set this environment attribute before it calls any function that has an SQLHENV argument, or the call will return SQLSTATE HY010 (Function sequence error). It is driver-specific whether additional behavior exists for these environmental flags. |
| SQL_ATTR_OUTPUT_NTS (ODBC 3.0) | A 32-bit integer that determines how the driver returns string data. If SQL_TRUE, the driver returns string data null-terminated. If SQL_FALSE, the driver does not return string data null-terminated. This attribute defaults to SQL_TRUE. A call to SQLSetEnvAttr to set it to SQL_TRUE returns SQL_SUCCESS. A call to SQLSetEnvAttr to set it to SQL_FALSE returns SQL_ERROR and SQLSTATE HYC00 (Optional feature not implemented). |