SQLSetStmtAttr--Establecer opciones referentes a una sentencia

Finalidad

Especificación:

CLI de DB2 2.1

ODBC 1.0

ISO CLI

SQLSetStmtAttr() define opciones relacionadas con una sentencia.

Sintaxis

SQLRETURN   SQLSetStmtAttr   (SQLHSTMT          StatementHandle,   
                              SQLINTEGER        Attribute,         
                              SQLPOINTER        ValuePtr,          
                              SQLINTEGER        StringLength);

Argumentos de la función

Tabla 82. Argumentos de SQLSetStmtAttr

Tipo de datos	Argumento	Uso	Descripción
SQLHSTMT	`StatementHandle`	entrada	Descriptor de contexto de sentencia.
SQLINTEGER	`Attribute`	entrada	Opción para definir.
SQLPOINTER	`ValuePtr`	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, no se tiene en cuenta `StringLength`. Si `Attribute` es un atributo de CLI de DB2, la aplicación indica la naturaleza del atributo estableciendo el argumento `StringLength`. `StringLength` puede tener los valores siguientes: Si `ValuePtr` es un puntero que apunta a una serie de caracteres, `StringLength` es la longitud de la serie o SQL_NTS. Si `ValuePtr` es un puntero que apunta a un almacenamiento intermedio binario, la aplicación coloca el resultado de la macro SQL_LEN_BINARY_ATTR(length) en `StringLength`. Esto coloca un valor negativo en `StringLength`. Si `ValuePtr` es un puntero que apunta a un valor distinto de una serie de caracteres o serie binaria, el valor de `StringLength` debe ser SQL_IS_POINTER. Si `ValuePtr` contiene un valor de longitud fija, `StringLength` es SQL_IS_INTEGER o SQL_IS_UINTEGER.
SQLINTEGER	`StringLength`	entrada	Si `ValuePtr` apunta a una serie de caracteres o almacenamiento intermedio binario, este argumento debe ser igual a la longitud de `ValuePtr`. Si `ValuePtr` es un puntero pero no apunta a una serie de caracteres o almacenamiento intermedio binario, `StringLength` debe tener el valor SQL_IS_POINTER. Si `ValuePtr` no es un puntero, `StringLength` debe ser SQL_IS_NOT_POINTER.

Uso

Los atributos de una sentencia permanecen vigentes hasta que son modificados por otra llamada a SQLSetStmtAttr() o hasta que la sentencia se descarta mediante una llamada a SQLFreeHandle(). Invocar SQLFreeStmt() con las opciones SQL_CLOSE, SQL_UNBIND o SQL_RESET_PARAMS no restaura los atributos de una sentencia.

Algunos atributos de sentencia dan soporte a la sustitución de un valor similar si la fuente de datos no da soporte al valor especificado en ValuePtr. En tales casos, CLI de DB2 devuelve SQL_SUCCESS_WITH_INFO y SQLSTATE 01S02 (Valor de opción cambiado). Por ejemplo, si Attribute es SQL_ATTR_CONCURRENCY, ValuePtr es SQL_CONCUR_ROWVER, y la fuente de datos no da soporte a este valor, CLI de DB2 sustituye SQL_CONCUR_VALUES y devuelve SQL_SUCCESS_WITH_INFO. Para determinar el valor sustituido, la aplicación invoca SQLGetStmtAttr(). El formato de la información establecida con ValuePtr depende del valor especificado para Attribute.

SQLSetStmtAttr() acepta información sobre atributos en uno de dos formatos diferentes: una serie de caracteres terminada en nulo o un valor entero de 32 bits. El formato del atributo está indicado en la descripción del atributo. Este formato es aplicable a la información devuelta para cada atributo en SQLGetStmtAttr(). Las series de caracteres a las que apunta el argumento ValuePtr de SQLSetStmtAttr() tienen una longitud igual a StringLength.

El bit de modificación

DB2 Everyplace utiliza un bit de modificación para hacer un seguimiento de los cambios efectuados en un registro. El comportamiento del bit de modificación está determinado por los atributos de sentencia SQL_ATTR_DELETE_MODE, SQL_ATTR_READ_MODE y SQL_ATTR_DIRTYBIT_SET_MODE. La tabla siguiente muestra los estados del bit de modificación después de que se realicen ciertas operaciones de base de datos en un registro. La tabla asume que el parámetro SQL_ATTR_DIRTYBIT_SET_MODE se establece en SQL_DIRTYBIT_SET_BY_SYSTEM con el bit de modificación mantenido por el sistema.

Tabla 83. Estados del bit de modificación de DB2 Everyplace

Acciones en un registro	Estado del bit de modificación
Estado limpio (0) y a continuación INSERTAR	INSERTAR
Estado limpio (0) y a continuación SUPRIMIR	SUPRIMIR
Estado limpio (0) y a continuación ACTUALIZAR	ACTUALIZAR
SUPRIMIR y a continuación INSERTAR	ACTUALIZAR
SUPRIMIR y a continuación SUPRIMIR	No aplicable
SUPRIMIR y a continuación ACTUALIZAR	No aplicable
INSERTAR y a continuación INSERTAR	No aplicable
INSERTAR y a continuación SUPRIMIR	Eliminación física de registro
INSERTAR y a continuación ACTUALIZAR	INSERTAR
ACTUALIZAR y a continuación INSERTAR	No aplicable
ACTUALIZAR y a continuación SUPRIMIR	DELETE
ACTUALIZAR y a continuación ACTUALIZAR	ACTUALIZAR

El valor del bit de modificación se puede obtener realizando una consulta a la columna $dirty de una tabla. Por ejemplo, la sentencia siguiente devuelve el bit de modificación y la columna NAME de la tabla PHONEBOOK:

SELECT $dirty, NAME from PHONEBOOK

El bit de modificación puede tener los valores siguientes.

Tabla 84. Valores del bit de modificación de DB2 Everyplace

Descripción	Valor del bit de modificación
Registro no cambiado (LIMPIO)	0
Registro suprimido (SUPRIMIR)	1
Registro insertado (INSERTAR)	2
Registro actualizado (ACTUALIZAR)	3

Atributos de sentencia

A continuación se muestran los atributos definidos actualmente.

SQL_ATTR_CURSOR_SCROLLABLE (CLI de DB2)

Entero de 32 bits que especifica el nivel de soporte que la aplicación requiere. El establecimiento de este atributo afecta a llamadas posteriores a SQLExecDirect() y SQLExecute(). Los valores soportados son:

SQL_NONSCROLLABLE
No se requieren cursores desplazables en el descriptor de contexto de sentencia. Si la aplicación llama a SQLFetchScroll() en este descriptor de contexto, el único valor válido para FetchOrientation() es SQL_FETCH_NEXT. Es el valor por omisión.
SQL_SCROLLABLE
Se requieren cursores desplazables en el descriptor de contexto de sentencia. Cuando se llama a SQLFetchScroll(), la aplicación puede especificar cualquier valor válido para FetchOrientation, por lo que el cursor se puede posicionar en modalidades distintas de la secuencial.

SQL_ATTR_CURSOR_SENSITIVITY (CLI de DB2)

Valor entero de 32 bits que especifica si un cursor es sensible a la actividad de grabación de otro cursor. Los valores soportados son:

SQL_UNSPECIFIED
La actividad de grabación de otros cursores tiene un impacto indefinido sobre el cursor actual. Es el valor por omisión.
SQL_INSENSITIVE
La actividad de grabación de otros cursores no tiene ningún impacto sobre el cursor actual.
Nota:
Utilice este valor de atributo con moderación porque puede afectar al rendimiento.

SQL_ATTR_CURSOR_TYPE (CLI de DB2)

Valor entero de 32 bits que especifica el tipo de cursor. Los valores soportados son:

SQL_CURSOR_FORWARD_ONLY = El cursor sólo se desplaza hacia adelante. Es el valor por omisión.
SQL_CURSOR_STATIC = Los datos del conjunto resultante son estáticos.

Esta opción no se puede especificar para un cursor abierto.

SQL_ATTR_ROW_ARRAY_SIZE (CLI de DB2)

Valor entero de 32 bits que especifica el número de filas del conjunto de filas. Es el número de filas devueltas por cada llamada a SQLFetch() o SQLFetchScroll(). El valor por omisión es 1. Si el tamaño de conjunto de filas especificado excede el tamaño máximo de conjunto de filas soportado por la fuente de datos, CLI de DB2 sustituye ese valor y devuelve SQLSTATE 01S02 (Valor de opción cambiado). Esta opción se puede especificar para un cursor abierto.

SQL_ATTR_ROW_BIND_TYPE (CLI de DB2)

Valor entero de 32 bits que define la orientación del enlace que se debe utilizar cuando se invoca SQLFetch() o SQLFetchScroll() para la sentencia asociada. El enlace basado en columnas se selecciona proporcionando la constante definida SQL_BIND_BY_COLUMN en ValuePtr. La longitud especificada en ValuePtr debe incluir espacio para todas las columnas enlazadas y el espacio de relleno necesario de la estructura o almacenamiento intermedio para asegurar que, cuando la dirección de una columna enlazada se incremente con la longitud especificada, el resultado apuntará al comienzo de la misma columna en la fila siguiente. Cuando se utiliza el operador sizeof con estructuras o uniones en C de ANSI, este comportamiento está asegurado. El enlace basado en columnas es la orientación predefinida del enlace para SQLFetchScroll().

SQL_ATTR_ROW_NUMBER (CLI de DB2)

Valor entero de 32 bits que es el número de la fila actual en el conjunto resultante entero. Si no se puede determinar el número de la fila actual o si no existe ninguna fila actual, CLI de DB2 devuelve 0. Este atributo se puede recuperar mediante una llamada a SQLGetStmtAttr(), pero no se puede establecer mediante una llamada a SQLSetStmtAttr().

SQL_ATTR_ROW_STATUS_PTR (CLI de DB2)

Valor entero de 16 bits, sin signo, que apunta a una matriz de valores UWORD que contiene valores de estado de filas después de una llamada a SQLFetch() o SQLFetchScroll(). La matriz tiene tantos elementos como filas hay en el conjunto de filas. Este atributo de sentencia se puede definir como puntero nulo, en cuyo caso CLI de DB2 no devuelve valores de estado para filas. Este atributo se puede definir en cualquier momento, pero el nuevo valor no se utiliza hasta la siguiente llamada a SQLFetch() o SQLFetchScroll().

SQL_ATTR_ROWS_FETCHED_PTR (CLI de DB2)

Valor entero de 32 bits, sin signo, que apunta a un almacenamiento intermedio en el que devolver el número de filas recuperadas después de una llamada a SQLFetch() o SQLFetchScroll().

SQL_ATTR_DELETE_MODE (DB2 Everyplace)

Los valores soportados son:

SQL_DELETE_MARK_ONLY
Este es el valor por omisión del sistema. Cuando se ejecute una sentencia de SQL de supresión, los registros sólo están señalados como "delete" (suprimir). Su contenido sigue pudiéndose leer en el caso de que se establezca SQL_READ_INCLUDE_MARKED_DELETE.
SQL_DELETE_PHYSICAL_REMOVE
Una sentencia de supresión de SQL elimina físicamente los registros que satisfagan la condición de la cláusula WHERE, sin tener en cuenta su bit de modificación.

Por ejemplo, utilice la sintaxis siguiente para eliminar físicamente algunos registros ignorando el estado de los bits de parada:

SQLSetStmtAttr (stmt, SQL_ATTR_DELETE_MODE,
SQL_DELETE_PHYSICAL_REMOVE, 0)

A continuación, ejecute la sentencia de SQL siguiente para suprimir todos los registros de la tabla T donde X no sea igual a 0:

DELETE T WHERE X<>0

SQL_ATTR_DIRTYBIT_SET_MODE (DB2 Everyplace)

Valor entero de 32 bits que especifica el tipo de cursor. Los valores soportados son:

SQL_DIRTYBIT_SET_BY_SYSTEM
Este es el valor por omisión del sistema. Todo registro que se inserte, actualice o suprima tendrá un bit de modificación establecido, respectivamente, en INSERT, UPDATE o DELETE. No se permite ninguna operación UPDATE sobre la columna $dirty cuando esté establecido SQL_DIRTYBIT_SET_BY_SYSTEM.
SQL_DIRTYBIT_SET_BY_APPLICATION
La aplicación es responsable de establecer el bit de modificación al insertar, actualizar o eliminar registros. La semántica de cada una de las operaciones es como sigue:
UPDATE
El sistema establece el bit de modificación exactamente como lo ha especificado la aplicación. Por ejemplo, si una aplicación ejecuta la sentencia siguiente, todos los registros de la tabla se restablecen a 0 (CLEAN):
```
UPDATE T SET $dirty=0 WHERE $dirty>0
```
INSERT
El bit de modificación del registro que recién insertado se establece en CLEAN.
DELETE
Si se establece SQL_DELETE_PHYSICAL_REMOVE, una operación DELETE elimina físicamente registros de la base de datos. De lo contrario, los valores de la columna $dirty se establecen en DELETE y los registros permanecen en la base de datos.

Por ejemplo, para limpiar el bit de modificación de un registro utilice la sentencia siguiente:

SQLSetStmtAttr (stmt, SQL_ATTR_DIRTYBIT_SET_MODE,
SQL_DIRTYBIT_SET_BY_APPLICATION, 0)

A continuación ejecute la sentencia de SQL siguiente:

UPDATE T SET $DIRTY=0 WHERE $DIRTY>0

En general, las aplicaciones pueden establecer SQL_DIRTYBIT_SET_BY_APPLICATION cuando los bits de parada no se necesitan para hacer el seguimiento de las actualizaciones de base de datos mediante usuarios finales.

SQL_ATTR_READ_MODE (DB2 Everyplace)

Valor entero de 32 bits que especifica el tipo de cursor. Los valores soportados son:

SQL_READ_EXCLUDE_MARKED_DELETE
Este es el valor por omisión del sistema. Todos los registros con bit de modificación establecidos en "delete" (suprimir) se ocultan de SQL.
SQL_READ_INCLUDE_MARKED_DELETE
Una vez establecidos, los registros con el bit de modificación establecido en DELETE (suprimir) se pueden ver desde sentencias SELECT de SQL. Las aplicaciones pueden distinguir los registros suprimidos de otros registros buscando un registro en el bit de modificación.

Por ejemplo, utilice la sentencia siguiente para leer todos los registros que tengan el bit de modificación establecido, incluyendo aquellos que tengan un bit de modificación marcado como DELETE:

SQLSetStmtAttr
(stmt, SQL_ATTR_READ_MODE, SQL_READ_INCLUDE_MARKED_DELETE, 0)

A continuación ejecute la sentencia de SQL siguiente para recuperar todos los registros:

SELECT * FROM T WHERE $dirty<>0

SQL_ATTR_REORG_MODE (DB2 Everyplace)

Valor entero de 32 bits que especifica si se realiza una reorganización automática de la base de datos en tablas creadas por el usuario y si se permiten sentencias explícitas REORG de SQL. Los valores soportados son:

SQL_REORG_ENABLED - Es el valor por omisión del sistema. La base de datos puede ser reorganizada por DB2 Everyplace o explícitamente por el usuario mediante una sentencia REORG de SQL.
SQL_REORG_DISABLED - Las sentencias REORG de SQL están restringidas y la reorganización automática de tablas creadas por el usuario está inhabilitada.

Esta opción no se puede especificar para un cursor abierto.

Códigos de retorno

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnósticos

Tabla 85. SQLSTATE de SQLSetStmtAttr

SQLSTATE	Descripción	Explicación
24000	Estado no válido del cursor.	Ya hay un cursor abierto para el descriptor de contexto de sentencia.
HY001	Error de asignación de memoria.	CLI de DB2 no puede asignar la memoria necesaria para ejecutar o finalizar la función.
HY010	Error de secuencia de función.	Se llama a la función mientras se produce una operación de datos en ejecución (`SQLPrepare()` o `SQLExecDirect()`). Se llamó a la función mientras estaba en curso una operación BEGIN COMPOUND y END COMPOUND de SQL.
HY014	No hay más descriptores de contexto.	CLI de DB2 no puede asignar un descriptor de contexto debido a recursos internos.
HY090	Longitud no válida de la serie de caracteres o del almacenamiento intermedio.	El valor de uno de los argumentos de longitud de nombre es menor que 0, pero no igual a SQL_NTS.

Restricciones

Ninguna.

Consulta relacionada