Función SQLGetStmtAttr

  • Artículo

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

Resumen
SQLGetStmtAttr devuelve la configuración actual de un atributo de instrucción.

Nota

Para obtener más información sobre lo que el Administrador de controladores asigna esta función a cuando odbc 3. La aplicación x funciona con ODBC 2. x driver, consulte Mapping Replacement Functions for Backward Compatibility of Applications.

Sintaxis

  
SQLRETURN SQLGetStmtAttr(  
     SQLHSTMT        StatementHandle,  
     SQLINTEGER      Attribute,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);

Argumentos

StatementHandle
[Entrada] Identificador de instrucción.

Atributo
[Entrada] Atributo que se va a recuperar.

ValuePtr
[Salida] Puntero a un búfer en el que se va a devolver el valor del atributo especificado en 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 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 devuelto en *ValuePtr es una cadena Unicode (al llamar a SQLGetStmtAttrW), 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 o SQL_NTS.

  • 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 se 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 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_ERROR o SQL_INVALID_HANDLE.

Diagnóstico

Cuando SQLGetStmtAttr devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_STMT y un identificador de StatementHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLGetStmtAttr 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).
24000 Estado de cursor no válido El argumento Attribute se SQL_ATTR_ROW_NUMBER y el cursor no estaba abierto, o el cursor se colocaba antes del inicio del conjunto de resultados o después del final del conjunto de resultados.
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 argumento 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) Se llamó a una función de ejecución asincrónica para el identificador de conexión asociado a StatementHandle. Esta función asincrónica todavía se estaba ejecutando cuando se llamó a la función SQLGetStmtAttr .

(DM) Se llamó a una función de ejecución asincrónica para StatementHandle y todavía se estaba ejecutando cuando se llamó a esta función.

(DM) se llamó a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos para statementHandle y devolvió SQL_NEED_DATA. Se llamó a esta función antes de enviar datos para todos los parámetros o columnas de datos en ejecución.
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.
HY109 Posición del cursor no válida El argumento Attribute se SQL_ATTR_ROW_NUMBER y la fila se había eliminado o no se pudo capturar.
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 instrucció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 correspondiente a StatementHandle no admite la función .

Comentarios

Para obtener información general sobre los atributos de instrucción, vea Atributos de instrucción.

Una llamada a SQLGetStmtAttr devuelve en *ValuePtr el valor del atributo de instrucción especificado en Attribute. Ese valor puede ser un valor SQLULEN o una cadena de caracteres terminada en NULL. Si el valor es un valor SQLULEN, 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. Además, no se usan los argumentos BufferLength y StringLengthPtr . Si el valor es una cadena terminada en null, la aplicación especifica la longitud máxima de esa cadena en el argumento BufferLength y el controlador devuelve la longitud de esa cadena en el búfer *StringLengthPtr .

Para permitir que las aplicaciones que llaman a SQLGetStmtAttr funcionen con ODBC 2. Los controladores x , una llamada a SQLGetStmtAttr se asigna en el Administrador de controladores a SQLGetStmtOption.

Los atributos de instrucción siguientes son de solo lectura, por lo que SQLGetStmtAttr puede recuperarlos, pero no establecidos por SQLSetStmtAttr:

  • SQL_ATTR_IMP_PARAM_DESC

  • SQL_ATTR_IMP_ROW_DESC

  • SQL_ATTR_ROW_NUMBER

Para obtener una lista de atributos que se pueden establecer y recuperar, vea SQLSetStmtAttr.

Para información acerca de Vea
Devolver la configuración de un atributo de conexión Función SQLGetConnectAttr
Establecimiento de un atributo de conexión Función SQLSetConnectAttr
Establecimiento de un atributo de instrucción Función SQLSetStmtAttr

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC