Función SQLGetEnvAttr

  • Artículo

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.

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

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC