SQLGetStmtAttr--Obtener el valor actual de un atributo de sentencia

Finalidad

Especificación:

CLI de DB2 5.0

ODBC 3.0

ISO CLI

SQLGetStmtAttr() devuelve el valor actual de un atributo de una sentencia.

Sintaxis

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

Argumentos de la función

Tabla 70. Argumentos de SQLGetStmtAttr

Tipo de datos	Argumento	Uso	Descripción
SQLHSTMT	`StatementHandle`	entrada	Descriptor de contexto de sentencia.
SQLINTEGER	`Attribute`	entrada	Atributo que se debe recuperar.
SQLPOINTER	`ValuePtr`	salida	Puntero a un almacenamiento intermedio en el que devolver el valor del atributo especificado en `Attribute`.
SQLINTEGER	`BufferLength`	entrada	Si `Attribute` es un atributo definido por ODBC y ValuePtr apunta a una serie de caracteres o almacenamiento intermedio binario, este argumento debe ser igual a la longitud de `ValuePtr`. Si `Attribute` es un atributo definido por ODBC y `ValuePtr` es un entero, se ignora `BufferLength`. Si `Attribute` es un atributo de la CLI de DB2, la aplicación indica la naturaleza del atributo estableciendo el argumento `BufferLength`. `BufferLength` puede tener los valores siguientes: Si `ValuePtr` es un puntero a una serie de caracteres, `BufferLength` es la longitud de la serie o SQL_NTS. Si `ValuePtr` es un puntero a un almacenamiento intermedio binario, la aplicación coloca el resultado de la macro SQL_LEN_BINARY_ATTR(longitud) en `BufferLength`. Si `ValuePtr` es un puntero a un valor distinto de una serie de caracteres o serie 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.
SQLSMALLINT	`*StringLengthPtr`	salida	Puntero a un almacenamiento intermedio en el que se devolverá el número total de bytes (excluyendo el carácter de terminación en nulo) disponibles para devolverlos en `ValuePtr`. Si se trata de un puntero nulo, no se devuelve ninguna longitud. Si el valor del atributo es una serie de caracteres, y si el número de bytes disponibles para devolverlos es mayor o igual que `BufferLength`, los datos `ValuePtr` se truncan hasta `BufferLength` menos la longitud de un carácter de terminación en nulo, y la CLI de DB2 los termina en nulo.

Uso

Una llamada a SQLGetStmtAttr() devuelve en *ValuePtr el valor del atributo de sentencia especificado en Attribute. En DB2 Everyplace, este valor es un valor de 32 bits y no se utilizan los argumentos BufferLength ni StringLengthPtr.

SQLGetStmtAttr() puede recuperar los atributos de sentencia siguientes. Para ver una descripción de los atributos, consulte SQLSetStmtAttr--Establecer opciones referentes a una sentencia.

SQL_ATTR_CURSOR_SCROLLABLE (DB2 CLI/ODBC)
SQL_ATTR_CURSOR_SENSITIVITY (DB2 CLI/ODBC)
SQL_ATTR_CURSOR_TYPE (DB2 CLI/ODBC)
SQL_ATTR_ROW_ARRAY_SIZE (DB2 CLI/ODBC)
SQL_ATTR_ROW_BIND_TYPE (DB2 CLI/ODBC)
SQL_ATTR_ROW_NUMBER (DB2 CLI/ODBC)
SQL_ATTR_DELETE_MODE (DB2 Everyplace)
SQL_ATTR_DIRTYBIT_SET_MODE (DB2 Everyplace)
SQL_ATTR_READ_MODE (DB2 Everyplace)
SQL_ATTR_REORG_MODE (DB2 Everyplace)

Códigos de retorno

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnósticos

Tabla 71. SQLSTATE de SQLGetStmtAttr

SQLSTATE	Descripción	Explicación
01000	Aviso.	Mensaje informativo. (La función devuelve SQL_SUCCESS_WITH_INFO).
01004	Datos truncados.	Los datos devueltos en *`ValuePtr` se truncan hasta `BufferLength` menos la longitud de un carácter de terminación en nulo. La longitud del valor de la serie no truncada se devuelve en `StringLengthPtr`. (La función devuelve SQL_SUCCESS_WITH_INFO).
24000	Estado no válido del cursor.	El argumento `Attribute` es SQL_ATTR_ROW_NUMBER y el cursor no está abierto, o el cursor está posicionado delante del comienzo del conjunto resultante o detrás del final del mismo.
HY000	Error general.	Se ha producido un error para el que no existe ningún SQLSTATE específico. El mensaje de error devuelto por `SQLGetDiagRec()` en el almacenamiento intermedio `*MessageText` describe el error y su causa.
HY001	Error de asignación de memoria.	DB2 CLI no puede asignar la memoria necesaria para ejecutar o finalizar la función.
HY010	Error de secuencia de función.	Se llama a una función de ejecución asíncrona para `StatementHandle` y se sigue ejecutando cuando se llama a esta función. Se llama a `SQLExecute()` o `SQLExecDirect()` para `StatementHandle` y se devuelve SQL_NEED_DATA. Se llama a esta función antes de que se envíen datos para todos los parámetros o columnas de datos en ejecución.
HY013	Error inesperado de gestión de la memoria.	DB2 CLI no puede acceder a la memoria necesaria para ejecutar o finalizar la función.
HY090	Longitud no válida de la serie de caracteres o del almacenamiento intermedio.	El valor especificado para el argumento `BufferLength` es menor que 0.
HY092	Tipo de opción fuera de rango.	El valor especificado para el argumento `Attribute` no es válido para esta versión de la CLI de DB2.
HY109	Posición no válida del cursor.	El argumento `Attribute` es SQL_ATTR_ROW_NUMBER y la fila se había suprimido o no se había podido recuperar.
HYC00	Controlador no apropiado.	El valor especificado para el argumento `Attribute` es un atributo válido para esta versión de la CLI de DB2, pero la fuente de datos no lo soporta.

Restricciones

Ninguna.

Consulta relacionada