Función SQLGetConnectAttr
Conformidad
Versión introducida: Cumplimiento de estándares ODBC 3.0: ISO 92
Resumen
SQLGetConnectAttr devuelve la configuración actual de un atributo de conexión.
Nota
Para obtener más información sobre lo que el Administrador de controladores asigna a esta función cuando una aplicación ODBC 3*.x* está trabajando con un controlador ODBC 2*.x*, vea Mapping Replacement Functions for Backward Compatibility of Applications.
Sintaxis
SQLRETURN SQLGetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Argumentos
ConnectionHandle
[Entrada] Identificador de conexión.
Atributo
[Entrada] Atributo que se va a recuperar.
ValuePtr
[Salida] Puntero a la memoria en la que se va a devolver el valor actual del atributo especificado por Attribute. En el caso de los atributos de tipo entero, algunos controladores solo pueden escribir los 32 o 16 bits inferiores de un búfer y dejar sin cambios el bit de orden superior. Por lo tanto, las aplicaciones deben usar un búfer de SQLULEN e inicializar el valor en 0 antes de llamar a esta función.
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 Attribute es un atributo definido por ODBC y ValuePtr apunta a una cadena de caracteres o a un búfer binario, este argumento debe ser la longitud de *ValuePtr. Si Attribute es un atributo definido por ODBC y *ValuePtr es un entero, bufferLength se omite. Si el valor de *ValuePtr es una cadena Unicode (al llamar a SQLGetConnectAttrW), el argumento BufferLength debe ser un número par.
Si Attribute es un atributo definido por el controlador, la aplicación indica la naturaleza del atributo en el Administrador de controladores estableciendo el argumento BufferLength . BufferLength puede tener los siguientes valores:
Si *ValuePtr es un puntero a una cadena de caracteres, BufferLength es la longitud de la cadena.
Si *ValuePtr es un puntero a un búfer binario, la aplicación coloca el resultado de la macro SQL_LEN_BINARY_ATTR(length) en BufferLength. Esto coloca un valor negativo en BufferLength.
Si *ValuePtr es un puntero a un valor distinto de una cadena de caracteres o una cadena binaria, BufferLength debe tener el valor SQL_IS_POINTER.
Si *ValuePtr contiene un tipo de datos de longitud fija, BufferLength es SQL_IS_INTEGER o SQL_IS_UINTEGER, según corresponda.
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 que BufferLength menos la longitud del carácter de terminación null, los datos de *ValuePtr se truncan a BufferLength menos la longitud del 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 SQLGetConnectAttr devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado de la estructura de datos de diagnóstico mediante una llamada a SQLGetDiagRec con un HandleType de SQL_HANDLE_DBC y un identificador de ConnectionHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLGetConnectAttr 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 la longitud de un carácter de terminación NULL. La longitud del valor de cadena notruncado se devuelve en *StringLengthPtr. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 08003 | Conexión no abierta | (DM) Se especificó un valor de atributo que requería una conexión abierta. |
| 08S01 | Error de vínculo de comunicación | Se produjo un error en el vínculo de comunicación entre el controlador y el origen de datos al que se conectó el controlador antes de que la función completara el procesamiento. |
| 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 la estructura de datos de diagnóstico por el argumento MessageText en SQLGetDiagField 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 | Se llamó a SQLBrowseConnect (DM) para ConnectionHandle y devolvió SQL_NEED_DATA. Se llamó a esta función antes de que SQLBrowseConnect devolva SQL_SUCCESS_WITH_INFO o SQL_SUCCESS. (DM) SQLExecute, SQLExecDirect o SQLMoreResults se llamó a para ConnectionHandle y devolvió SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos. |
| 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. |
| HY090 | Longitud de búfer o cadena no válida | (DM) *ValuePtr es una cadena de caracteres y BufferLength era menor que cero, pero no igual que SQL_NTS. |
| 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. |
| HY114 | El controlador no admite la ejecución de funciones asincrónicas de nivel de conexión | (DM) Una aplicación intentó habilitar la ejecución de funciones asincrónicas con SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE para un controlador que no admite operaciones de conexión asincrónicas. |
| 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 conexión ODBC válido para la versión de ODBC compatible con el controlador, pero no era compatible con el controlador. |
| HYT01 | Se ha agotado el tiempo de espera de la conexión. | El período de tiempo de espera de conexión expiró antes de que el origen de datos responda a la solicitud. El período de tiempo de espera de conexión se establece a través de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | El controlador no admite esta función | (DM) El controlador que corresponde a ConnectionHandle no admite la función . |
Comentarios
Para obtener información general sobre los atributos de conexión, consulte Atributos de conexión.
Para obtener una lista de atributos que se pueden establecer, vea SQLSetConnectAttr. Observe que si Attribute especifica un atributo que devuelve una cadena, ValuePtr debe ser un puntero a un búfer para la cadena. La longitud máxima de la cadena devuelta, incluido el carácter de terminación NULL, será BufferLength bytes.
Según el atributo , una aplicación no tiene que establecer una conexión antes de llamar a SQLGetConnectAttr. Sin embargo, si se llama a SQLGetConnectAttr y el atributo especificado no tiene un valor predeterminado y no se ha establecido mediante una llamada anterior a SQLSetConnectAttr, SQLGetConnectAttr devolverá SQL_NO_DATA.
Si Attribute es SQL_ATTR_ TRACE o SQL_ATTR_ TRACEFILE, ConnectionHandle no tiene que ser válido y SQLGetConnectAttr no devolverá SQL_ERROR ni SQL_INVALID_HANDLE si ConnectionHandle no es válido. Estos atributos se aplican a todas las conexiones. SQLGetConnectAttr devolverá SQL_ERROR o SQL_INVALID_HANDLE si otro argumento no es válido.
Aunque una aplicación puede establecer atributos de instrucción mediante SQLSetConnectAttr, una aplicación no puede usar SQLGetConnectAttr para recuperar valores de atributo de instrucción; debe llamar a SQLGetStmtAttr para recuperar la configuración de los atributos de instrucción.
Tanto SQL_ATTR_AUTO_IPD como SQL_ATTR_CONNECTION_DEAD atributos de conexión se pueden devolver mediante una llamada a SQLGetConnectAttr , pero no se puede establecer mediante una llamada a SQLSetConnectAttr.
Nota
No hay compatibilidad asincrónica con SQLGetConnectAttr. Al implementar SQLGetConnectAttr, un controlador puede mejorar el rendimiento minimizando el número de veces que se envía o solicita información desde el servidor.
Funciones relacionadas
| Para información acerca de | Vea |
|---|---|
| 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 |