Función SQLSetEnvAttr

  • Artículo

Conformidad
Versión introducida: Cumplimiento de estándares odbc 3.0: ISO 92

Resumen
SQLSetEnvAttr establece atributos que rigen aspectos de los entornos.

Sintaxis

  
SQLRETURN SQLSetEnvAttr(  
     SQLHENV      EnvironmentHandle,  
     SQLINTEGER   Attribute,  
     SQLPOINTER   ValuePtr,  
     SQLINTEGER   StringLength);

Argumentos

EnvironmentHandle
[Entrada] Identificador del entorno.

Atributo
[Entrada] Atributo que se va a establecer, que aparece en "Comentarios".

ValuePtr
[Entrada] Puntero al valor que se va a asociar a Attribute. Según el valor de Attribute, ValuePtr será un valor entero de 32 bits o apuntará a una cadena de caracteres terminada en null.

StringLength
[Entrada] Si ValuePtr apunta a una cadena de caracteres o a un búfer binario, este argumento debe ser la longitud de *ValuePtr. Para los datos de cadena de caracteres, este argumento debe contener el número de bytes de la cadena.

Si ValuePtr es un entero, stringLength se omite.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnóstico

Cuando SQLSetEnvAttr devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_ENV y un identificador de EnvironmentHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLSetEnvAttr y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario. Si un controlador no admite un atributo de entorno, el error solo se puede devolver durante el tiempo de conexión.

SQLSTATE Error Descripción
01000 Advertencia general Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO).
01S02 Valor de opción cambiado El controlador no admitía el valor especificado en ValuePtr y sustituyó un valor similar. (Function devuelve SQL_SUCCESS_WITH_INFO).
HY000 Error general Se produjo un error para el que no había ningún SQLSTATE específico y para el que no se definió SQLSTATE específico de la implementación. El mensaje de error devuelto por SQLGetDiagRec en el búfer *MessageText describe el error y su causa.
HY001 Error de asignación de memoria El controlador no pudo asignar memoria necesaria para admitir la ejecución o finalización de la función.
HY009 Uso no válido del puntero nulo El argumento Attribute identificó un atributo de entorno que requería un valor de cadena y el argumento ValuePtr era un puntero nulo.
HY010 Error de secuencia de función (DM) Se ha asignado un identificador de conexión en EnvironmentHandle.

(DM) SQL_ATTR_ODBC_VERSION no se ha establecido con SQLSetEnvAttr y Attribute no es igual a SQL_ATTR_ODBC_VERSION. No es necesario establecer SQL_ATTR_ODBC_VERSION explícitamente si usa SQLAllocHandleStd.
HY013 Error de administración de memoria No se pudo procesar la llamada de función porque no se pudo acceder a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja.
HY024 Valor de atributo no válido Dado el valor attribute especificado, se especificó un valor no válido en ValuePtr.
HY090 Longitud de búfer o cadena no válida El argumento StringLength era menor que 0, pero no era SQL_NTS.
HY092 Identificador de atributo o opción no válido (DM) El valor especificado para el argumento Attribute no era válido para la versión de ODBC compatible con el controlador.
HY117 La conexión se suspende debido a un estado de transacción desconocido. Solo se permiten funciones de desconexión y de solo lectura. (DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran.
HYC00 Característica opcional no implementada El valor especificado para el argumento Attribute era un atributo de entorno ODBC válido para la versión de ODBC compatible con el controlador, pero no era compatible con el controlador.

(DM) El argumento Attribute se SQL_ATTR_OUTPUT_NTS y ValuePtr se SQL_FALSE.

Comentarios

Una aplicación solo puede llamar a SQLSetEnvAttr si no se asigna ningún identificador de conexión en el entorno. Todos los atributos de entorno establecidos correctamente por la aplicación para el entorno persisten hasta que se llama a SQLFreeHandle en el entorno. Se puede asignar simultáneamente más de un identificador de entorno en ODBC 3.x.

El formato de información establecido a través de ValuePtr depende del atributo especificado. SQLSetEnvAttr aceptará información de atributo en uno de los dos formatos diferentes: una cadena de caracteres terminada en null o un valor entero de 32 bits. El formato de cada uno se indica en la descripción del atributo.

No hay atributos de entorno específicos del controlador.

Los atributos de conexión no se pueden establecer mediante una llamada a SQLSetEnvAttr. Al intentar hacerlo, se devolverá SQLSTATE HY092 (identificador de opción o atributo no válido).

Atributo Contenido de ValuePtr
SQL_ATTR_CONNECTION_POOLING (ODBC 3.8) Valor SQLUINTEGER de 32 bits que habilita o deshabilita la agrupación de conexiones en el nivel de entorno. Se usan los valores siguientes:

SQL_CP_OFF = La agrupación de conexiones está desactivada. Este es el valor predeterminado.

SQL_CP_ONE_PER_DRIVER = Se admite un único grupo de conexiones para cada controlador. Cada conexión de un grupo está asociada a un controlador.

SQL_CP_ONE_PER_HENV = Se admite un único grupo de conexiones para cada entorno. Cada conexión de un grupo está asociada a un entorno.

SQL_CP_DRIVER_AWARE = Use la característica de reconocimiento del grupo de conexiones del controlador, si está disponible. Si el controlador no admite el reconocimiento del grupo de conexiones, se omite SQL_CP_DRIVER_AWARE y se usa SQL_CP_ONE_PER_HENV. Para obtener más información, consulte Agrupación de conexiones compatibles con controladores. En un entorno en el que algunos controladores admiten y algunos controladores no admiten el reconocimiento del grupo de conexiones, SQL_CP_DRIVER_AWARE puede habilitar la característica de reconocimiento del grupo de conexiones en esos controladores auxiliares, pero es equivalente a establecer en SQL_CP_ONE_PER_HENV en los controladores que no admiten la característica de reconocimiento del grupo de conexiones.

La agrupación de conexiones está habilitada mediante una llamada a SQLSetEnvAttr para establecer el atributo SQL_ATTR_CONNECTION_POOLING en SQL_CP_ONE_PER_DRIVER o SQL_CP_ONE_PER_HENV. Esta llamada se debe realizar antes de que la aplicación asigne el entorno compartido para el que se va a habilitar la agrupación de conexiones. El identificador de entorno de la llamada a SQLSetEnvAttr se establece en null, lo que hace que SQL_ATTR_CONNECTION_POOLING un atributo de nivel de proceso. Una vez habilitada la agrupación de conexiones, la aplicación asigna un entorno compartido implícito llamando a SQLAllocHandle con el argumento InputHandle establecido en SQL_HANDLE_ENV.

Una vez habilitada la agrupación de conexiones y se ha seleccionado un entorno compartido para una aplicación, SQL_ATTR_CONNECTION_POOLING no se puede restablecer para ese entorno, ya que se llama a SQLSetEnvAttr con un identificador de entorno NULO al establecer este atributo. Si este atributo se establece mientras la agrupación de conexiones ya está habilitada en un entorno compartido, el atributo afecta solo a los entornos compartidos que se asignan posteriormente.

También es posible habilitar la agrupación de conexiones en un entorno. Tenga en cuenta lo siguiente sobre la agrupación de conexiones de entorno:

- Habilitar la agrupación de conexiones en un identificador NULL es un atributo de nivel de proceso. Posteriormente, los entornos asignados serán un entorno compartido y heredarán la configuración de agrupación de conexiones de nivel de proceso.
- Después de asignar un entorno, una aplicación todavía puede cambiar su configuración del grupo de conexiones.
- Si la agrupación de conexiones de entorno está habilitada y el controlador de la conexión usa la agrupación de controladores, la agrupación de entornos tiene preferencia.

SQL_ATTR_CONNECTION_POOLING se implementa dentro del Administrador de controladores. Un controlador no necesita implementar SQL_ATTR_CONNECTION_POOLING. Las aplicaciones ODBC 2.0 y 3.0 pueden establecer este atributo de entorno.

Para obtener más información, consulte este artículo sobre la agrupación de conexiones ODBC.
SQL_ATTR_CP_MATCH (ODBC 3.0) Valor SQLUINTEGER de 32 bits que determina cómo se elige una conexión de un grupo de conexiones. Cuando se llama a SQLConnect o SQLDriverConnect , el Administrador de controladores determina qué conexión se reutiliza del grupo. El Administrador de controladores intenta coincidir con las opciones de conexión de la llamada y los atributos de conexión establecidos por la aplicación en las palabras clave y los atributos de conexión de las conexiones del grupo. El valor de este atributo determina el nivel de precisión de los criterios coincidentes.

Los valores siguientes se usan para establecer el valor de este atributo:

SQL_CP_STRICT_MATCH = Solo se reutilizan las conexiones que coinciden exactamente con las opciones de conexión de la llamada y los atributos de conexión establecidos por la aplicación. Este es el valor predeterminado.

SQL_CP_RELAXED_MATCH = Se pueden usar conexiones con palabras clave de cadena de conexión coincidentes. Las palabras clave deben coincidir, pero no todos los atributos de conexión deben coincidir.

Para obtener más información sobre cómo el Administrador de controladores realiza la coincidencia en la conexión a una conexión agrupada, consulte SQLConnect. Para obtener más información sobre la agrupación de conexiones, consulte Agrupación de conexiones ODBC.
SQL_ATTR_ODBC_VERSION (ODBC 3.0) Entero de 32 bits que determina si cierta funcionalidad presenta un comportamiento ODBC 2.x o odbc 3.x . Los valores siguientes se usan para establecer el valor de este atributo:

SQL_OV_ODBC3_80 = El administrador de controladores y el controlador muestran el siguiente comportamiento de ODBC 3.8:

: el controlador devuelve y espera códigos ODBC 3.x para la fecha, hora y marca de tiempo.
- El controlador devuelve códigos SQLSTATE ODBC 3.x cuando se llama a SQLError, SQLGetDiagField o SQLGetDiagRec .
: el argumento CatalogName de una llamada a SQLTables acepta un patrón de búsqueda.
- El Administrador de controladores admite la extensibilidad del tipo de datos C. Para obtener más información sobre la extensibilidad de tipos de datos de C, vea Tipos de datos de C en ODBC.

Para obtener más información, vea Novedades de ODBC 3.8.

SQL_OV_ODBC3 = El administrador de controladores y el controlador muestran el siguiente comportamiento de ODBC 3.x :

: el controlador devuelve y espera códigos ODBC 3.x para la fecha, hora y marca de tiempo.
- El controlador devuelve códigos SQLSTATE ODBC 3.x cuando se llama a SQLError, SQLGetDiagField o SQLGetDiagRec .
: el argumento CatalogName de una llamada a SQLTables acepta un patrón de búsqueda.
- El Administrador de controladores no admite la extensibilidad del tipo de datos C.

SQL_OV_ODBC2 = El administrador de controladores y el controlador muestran el siguiente comportamiento de ODBC 2.x . Esto es especialmente útil para una aplicación ODBC 2.x que funciona con un controlador ODBC 3.x .

: el controlador devuelve y espera códigos ODBC 2.x para la fecha, hora y marca de tiempo.
: el controlador devuelve códigos SQLSTATE ODBC 2.x cuando se llama a SQLError, SQLGetDiagField o SQLGetDiagRec .
- El argumento CatalogName de una llamada a SQLTables no acepta un patrón de búsqueda.
- El Administrador de controladores no admite la extensibilidad del tipo de datos C.

Una aplicación debe establecer este atributo de entorno antes de llamar a cualquier función que tenga un argumento SQLHENV o la llamada devolverá SQLSTATE HY010 (error de secuencia de función). Es específico del controlador si existe un comportamiento adicional para estas marcas de entorno.

- Para obtener más información, consulte Declaración de los cambios de comportamiento y versión ODBC de la aplicación.
SQL_ATTR_OUTPUT_NTS (ODBC 3.0) Entero de 32 bits que determina cómo el controlador devuelve datos de cadena. Si SQL_TRUE, el controlador devuelve los datos de cadena terminados en null. Si SQL_FALSE, el controlador no devuelve datos de cadena terminados en null.

Este atributo tiene como valor predeterminado SQL_TRUE. Una llamada a SQLSetEnvAttr para establecerla en SQL_TRUE devuelve SQL_SUCCESS. Una llamada a SQLSetEnvAttr para establecerla en SQL_FALSE devuelve SQL_ERROR y SQLSTATE HYC00 (característica opcional no implementada).
Para información acerca de Vea
Asignar un identificador Función SQLAllocHandle
Devolver la configuración de un atributo de entorno Función SQLGetEnvAttr

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC
Novedades de ODBC 3.8