Función SQLGetEnvAttr
Conformidad
Versión introducida: Cumplimiento de estándares ODBC 3.0: ISO 92
Resumen
SQLGetEnvAttr devuelve la configuración actual de un atributo de entorno.
Sintaxis
SQLRETURN SQLGetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Argumentos
EnvironmentHandle
[Entrada] Identificador de entorno.
Atributo
[Entrada] Atributo que se va a recuperar.
ValuePtr
[Salida] Puntero a un búfer en el que se va a devolver el valor actual del atributo especificado por Attribute.
Si ValuePtr es NULL, StringLengthPtr seguirá devolviendo el número total de bytes (excepto el carácter de terminación NULL para los datos de caracteres) disponible para devolver en el búfer al que apunta ValuePtr.
BufferLength
[Entrada] Si ValuePtr apunta a una cadena de caracteres, este argumento debe ser la longitud de *ValuePtr. Si *ValuePtr es un entero, se omite BufferLength . Si *ValuePtr es una cadena Unicode (al llamar a SQLGetEnvAttrW), el argumento BufferLength debe ser un número par. Si el valor del atributo no es una cadena de caracteres, BufferLength no se usa.
StringLengthPtr
[Salida] Puntero a un búfer en el que se va a devolver el número total de bytes (excepto el carácter de terminación NULL) disponible para devolver en *ValuePtr. Si el valor del atributo es una cadena de caracteres y el número de bytes disponibles para devolver es mayor o igual que BufferLength, los datos de *ValuePtr se truncan a BufferLength menos la longitud de un carácter de terminación NULL y el controlador termina en null.
Devoluciones
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnóstico
Cuando SQLGetEnvAttr 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 SQLGetEnvAttr 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.
| SQLSTATE | Error | Descripción |
|---|---|---|
| 01000 | Advertencia general | Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 01004 | Datos de cadena, truncados a la derecha | Los datos devueltos en *ValuePtr se truncaron para ser BufferLength menos el carácter de terminación null. La longitud del valor de cadena notruncado se devuelve en *StringLengthPtr. (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. |
| HY010 | Error de secuencia de función | (DM) SQL_ATTR_ODBC_VERSION aún no se ha establecido a través de SQLSetEnvAttr. 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 tener acceso a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja. |
| HY092 | Identificador de atributo o opción no válido | 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 al 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. |
| IM001 | El controlador no admite esta función | (DM) El controlador correspondiente a EnvironmentHandle no admite la función . |
Comentarios
Para obtener una lista de atributos, vea SQLSetEnvAttr. No hay atributos de entorno específicos del controlador. Si Attribute especifica un atributo que devuelve una cadena, ValuePtr debe ser un puntero a un búfer en el que devolver la cadena. La longitud máxima de la cadena, incluido el byte de terminación NULL, será BufferLength bytes.
Se puede llamar a SQLGetEnvAttr en cualquier momento entre la asignación y la liberación de un identificador de entorno. Todos los atributos de entorno establecidos correctamente por la aplicación para el entorno se conservan hasta que se llama a SQLFreeHandle en EnvironmentHandle con un HandleType de SQL_HANDLE_ENV. Se puede asignar simultáneamente más de un identificador de entorno en ODBC 3*.x*. Un atributo de entorno en un entorno no se ve afectado cuando se ha asignado otro entorno.
Nota
El atributo de entorno SQL_ATTR_OUTPUT_NTS es compatible con las aplicaciones compatibles con estándares. Cuando se llama a SQLGetEnvAttr , el Administrador de controladores ODBC 3*.x* siempre devuelve SQL_TRUE para este atributo. SQL_ATTR_OUTPUT_NTS solo se puede establecer en SQL_TRUE mediante una llamada a SQLSetEnvAttr.
Funciones relacionadas
| Para información acerca de | Vea |
|---|---|
| Devolver la configuración de un atributo de conexión | Función SQLGetConnectAttr |
| Devolver la configuración de un atributo de instrucción | Función SQLGetStmtAttr |
| Establecimiento de un atributo de conexión | Función SQLSetConnectAttr |
| Establecimiento de un atributo de entorno | Función SQLSetEnvAttr |
| Establecimiento de un atributo de instrucción | Función SQLSetStmtAttr |