Conformance
Version Introduced: ODBC 3.0
Standards Compliance: ISO 92
Summary
f90SQLSetEnvAttr sets attributes that govern aspects of environments.
Syntax
| f90SQLSetEnvAttr | (EnvironmentHandle, Attribute, Value, iRet) |
| integer(SQLHDBC_KIND),intent(in):: | EnvironmentHandle |
| integer(SQLINTEGER_KIND),intent(in):: | Attribute |
| { | |
| integer(SQLUINTEGER_KIND),intent(in):: | Value | |
| character(len=*),intent(in):: | Value |
| } | |
| integer(SQLRETURN_KIND),intent(out):: | iRet |
Arguments
EnvironmentHandle [Input]
Environment handle.
Attribute [Input]
Attribute to set, listed in "Comments."
Value [Input]
Value to be associated with Attribute. Depending on the value of Attribute, Value will be a 32-bit unsigned integer value or character string.
iRet [Output]
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When f90SQLSetEnvAttr returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling f90SQLGetDiagRec with a HandleType of SQL_HANDLE_ENV and a Handle of EnvironmentHandle. The following table lists the SQLSTATE values commonly returned by f90SQLSetEnvAttr and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise. If a driver does not support an environment attribute, the error can be returned only during connect time.
| SQLSTATE | Error | Description |
| 01000 | General warning | Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Option value changed | The driver did not support the value specified in Value and substituted a similar value. (Function returns SQL_SUCCESS_WITH_INFO.) |
| HY000 | 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 f90SQLGetDiagRec in the MessageText buffer describes the error and its cause. |
| HY001 | Memory allocation error | The driver was unable to allocate memory required to support execution or completion of the function. |
| HY009 | Invalid use of null pointer | The Attribute argument identified an environment attribute that required a string value, and the ValuePtr argument was a null pointer. |
| HY010 | Function sequence error | (DM) A connection handle has been allocated on EnvironmentHandle. |
| HY013 | Memory management error | The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions. |
| HY024 | Invalid attribute value | Given the specified Attribute value, an invalid value was specified in Value. |
| HY090 | Invalid string or buffer length | The Len_trim(Value) argument was less than 0, but was not SQL_NTS. |
| HY092 | Invalid attribute/option identifier | (DM) The value specified for the argument Attribute was not valid for the version of ODBC supported by the driver. |
| HYC00 | Optional feature not implemented | The value specified for the argument Attribute
was a valid ODBC environment attribute for the version of ODBC supported by the driver,
but was not supported by the driver. (DM) The Attribute argument was SQL_ATTR_OUTPUT_NTS, and Value was SQL_FALSE. |
Comments
An application can call f90SQLSetEnvAttr only if no connection handle is allocated on the environment. All environment attributes successfully set by the application for the environment persist until f90SQLFreeHandle is called on the environment. More than one environment handle can be allocated simultaneously in ODBC 3.x.
The format of information set through Value depends on the specified Attribute. f90SQLSetEnvAttr will accept attribute information in one of two different formats: a 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 f90SQLSetEnvAttr. Attempting to do so will return SQLSTATE HY092 (Invalid attribute/option identifier).
| Attribute | Value contents |
| SQL_ATTR_CONNECTION_POOLING (ODBC 3.0) |
A 32-bit SQLUINTEGER_KIND 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 f90SQLSetEnvAttr 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 f90SQLSetEnvAttr 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 f90SQLAllocHandle 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 f90SQLSetEnvAttr 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 only affects shared environments that are allocated subsequently. |
| SQL_ATTR_CP_MATCH (ODBC 3.0) |
A 32-bit SQLUINTEGER_KIND value that
determines how a connection is chosen from a connection pool. When f90SQLConnect or f90SQLDriverConnect
is called, the Driver Manager determines which connection is reused from the pool. The
Driver Manager attempts 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. |
| 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:
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):
An application must set this environment attribute before calling any function that has an SQLHENV_KIND argument, or the call will return SQLSTATE HY010 (Function sequence error). |
| 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 f90SQLSetEnvAttr to set it to SQL_TRUE returns SQL_SUCCESS. A call to f90SQLSetEnvAttr to set it to SQL_FALSE returns SQL_ERROR and SQLSTATE HYC00 (Optional feature not implemented). |
Code Example
See any example in Chapter 5.
Related Subroutines
| For information about | See |
| Allocating a handle | f90SQLAllocHandle |
| Returning the setting of an environment attribute | f90SQLGetEnvAttr |