SQLCA (área de comunicaciones SQL)

Una SQLCA es un conjunto de variables que se actualiza al final de la ejecución de cada sentencia de SQL.

Un programa que contiene sentencias de SQL ejecutables y se precompila con la opción LANGLEVEL SAA1 (el valor por omisión) o MIA debe proporcionar exactamente una SQLCA, aunque es posible que exista más de una SQLCA por paso en una aplicación de múltiples pasos.

Cuando se precompila un programa con la opción LANGLEVEL SQL92E, puede declararse una variable SQLCODE o SQLSTATE en la sección de declaración SQL o se puede declarar una variable SQLCODE en algún otro lugar del programa.

No se debe proporcionar ninguna SQLCA cuando se utiliza LANGLEVEL SQL92E. La sentencia de SQL INCLUDE puede utilizarse para proporcionar la declaración de la SQLCA en todos los lenguajes excepto en REXX. La SQLCA se proporciona automáticamente en REXX.

Para visualizar la SQLCA después de cada mandato ejecutado mediante el procesador de línea de mandatos, emita el mandato db2 -a. La SQLCA se proporciona como parte de la salida para los mandatos posteriores. La SQLCA también se vuelca en el archivo de anotaciones cronológicas db2diag.

Descripciones de los campos de la SQLCA

Tabla 1. Campos de la SQLCA. Los nombres de los campos que se muestran son aquellos presentes en una SQLCA obtenida mediante una sentencia INCLUDE.
Nombre Tipo de datos Valores de campos
sqlcaid CHAR(8) Una indicación visual para los vuelcos de almacenamiento que contienen la SQLCA. El sexto byte es L si se devuelve información de número de línea del análisis de una rutina de SQL, activador de SQL o sentencia de SQL compuesto dinámico. El sexto byte es M si se devuelve información de número de línea y del ID de objeto de la ejecución de una rutina SQL compilada, un activador de SQL compilado o una sentencia de SQL compuesto dinámico (compilado).
sqlcabc INTEGER Contiene la longitud de la SQLCA, 136.
sqlcode INTEGER Contiene el código de retorno SQL:
0
Ejecución satisfactoria (aunque pueden haberse establecido uno o varios indicadores SQLWARN).
positivo
Ejecución satisfactoria, pero con una condición de aviso.
negativo
Condición de error.
sqlerrml SMALLINT Indicador de longitud para sqlerrmc, en el rango de 0 a 70. 0 significa que el valor de sqlerrmc no es relevante.
sqlerrmc VARCHAR (70) Contiene uno o más tokens, separados por X'FF', que se sustituyen por variables en las descripciones de condiciones de errores.

Este campo también se utiliza cuando se establece una conexión satisfactoria.

Cuando se emite una sentencia de SQL compuesto NOT ATOMIC, ésta puede contener información acerca de siete o menos errores.

El último token puede ir seguido de X'FF'. El valor sqlerrml incluirá cualquier X'FF' de cola.
sqlerrp CHAR(8) A partir de V11.1, el formato del campo SQLERRP se cambia a SQLvvrrmm, donde:
  • vv representa el número de versión
  • rr representa el número de release
  • m representa el valor de modificación

El ejemplo siguiente muestra la relación entre la firma del producto y la nueva señal en el campo SQLERRP. Todos los fixpacks posteriores para un determinado paquete de modificación devuelven el mismo valor de SQLERRP.

Product           SQLERRP
signature         token
Db2 10.5.0.7      SQL10057
Db2 11.0.0.0      SQL11010
Db2 11.1.1.1      SQL11011
Db2 11.1.2.0      SQL11012
sqlerrd ARRAY Seis variables INTEGER que proporcionan información de diagnóstico. Generalmente, estos valores están vacíos si no hay errores, excepto sqlerrd(6) de una base de datos particionada.
sqlerrd(1) INTEGER Si se invoca la conexión y es satisfactoria, contiene la diferencia máxima esperada en la longitud de los datos de caracteres mixtos (tipos de datos CHAR) cuando se convierten a la página de códigos de la base de datos de la página de códigos de la aplicación. Un valor de 0 ó 1 indica sin expansión; un valor mayor que 1 indica una posible expansión en longitud; un valor negativo indica una posible contracción.

Cuando un procedimiento SQL termina satisfactoriamente su ejecución, este campo contiene el valor del estado de devolución del procedimiento SQL.
sqlerrd(2) INTEGER

Si se invoca la conexión y es satisfactoria, contiene la diferencia máxima esperada en la longitud de datos de caracteres mixtos (tipos de datos CHAR) cuando se convierten a la página de códigos de la aplicación de la página de códigos de la base de datos. Un valor de 0 ó 1 indica sin expansión; un valor mayor que 1 indica una posible expansión en longitud; un valor negativo indica una posible contracción. Si la SQLCA es el resultado de una sentencia de SQL compuesto NOT ATOMIC que ha encontrado uno o varios errores, el valor se establece en el número de sentencias que han fallado.
sqlerrd(3) INTEGER Si se invoca PREPARE y la operación es satisfactoria, contiene una estimación del número de filas que se devolverán. Después de INSERT, UPDATE, DELETE o MERGE, contiene el número real de filas que estaban cualificadas para la operación. Para una sentencia TRUNCATE, el valor será -1. Si se invoca SQL compuesto, contiene una acumulación de todas las filas de subsentencia. Si se invoca CONNECT, contiene 1 si la base de datos se puede actualizar, o 2 si la base de datos es de sólo lectura.

Si se invoca la sentencia OPEN y el cursor contiene sentencias de cambio de datos de SQL, este campo contiene la suma del número de filas cualificadas para las operaciones incorporadas de inserción, actualización, supresión o fusión.

Si se detecta un error durante la compilación de una rutina de SQL, activador o sentencia de SQL compuesto dinámico (en línea o compilado), sqlerrd(3) contiene el número de línea en el que se ha detectado el error. El sexto byte de sqlcaid debe ser L para que esta entrada sea un número de línea válido.

Si se detecta un error durante la ejecución de una rutina de SQL compilado, activador o sentencia de SQL dinámico (compilado), sqlerrd(3) contiene el número de línea en el que se ha generado el error. El sexto byte de sqlcaid debe ser M para que esto sea un número de línea válido.
sqlerrd(4) INTEGER

Si se invoca PREPARE y es satisfactoria, contiene una estimación del coste relativo de los recursos necesarios para procesar la sentencia. Si se invoca SQL compuesto, contiene una cuenta del número de subsentencias satisfactorias. Si se invoca CONNECT, contiene 0 para una confirmación en una fase de un cliente que no se encuentra en el último nivel; 1 para una confirmación de una fase; 2 para una confirmación de sólo lectura de una fase; y 3 para una confirmación de dos fases.

Si se detecta un error durante la ejecución de una rutina de SQL compilado o activador, sqlerrd(4) contiene un número entero que identifica de forma exclusiva a la rutina o activador dentro del que se ha generado el error. El sexto byte de sqlcaid debe ser M para que esta entrada sea un número de línea válido
sqlerrd(5) INTEGER
Contiene el número total de filas suprimidas, insertadas o actualizadas como resultado de:
  • La imposición de las restricciones después de una operación de supresión satisfactoria
  • El proceso de sentencias de SQL activadas por activadores en línea activados.
Si se invoca SQL compuesto, contiene una acumulación del número de dichas filas para todas las subsentencias. En algunos casos cuando se encuentra un error, este campo contiene un valor negativo que es un puntero de un error interno. Si se invoca CONNECT, contiene un valor de tipo de autenticación:
  • 0 para autenticación de servidor
  • 1 para autenticación de cliente
  • 4 para la autenticación SERVER_ENCRYPT
  • 7 para autenticación KERBEROS
  • 9 para autenticación GSSPLUGIN
  • 11 para autenticación DATA_ENCRYPT
  • 255 para autenticación sin especificar.
sqlerrd(6) INTEGER Para una base de datos particionada, contiene el número de partición de la partición de base de datos que ha encontrado el error o aviso. Si no se han encontrado errores ni avisos, este campo contiene el número de partición coordinadora. El número de este campo es igual al especificado para la partición de base de datos del archivo db2nodes.cfg.
sqlwarn Matriz Un conjunto de indicadores de aviso, que contiene cada uno un blanco o W. Si se invoca SQL compuesto, contiene una acumulación de indicadores de aviso establecidos para todas las subsentencias.
sqlwarn0 CHAR(1) Espacio en blanco si todos los demás indicadores están en blanco; contiene una W si como mínimo otro indicador no está en blanco.
sqlwarn1 CHAR(1) Contiene una W si el valor de una columna de serie se ha truncado cuando se ha asignado a una variable host. Contiene una N el terminador nulo se ha truncado. Contiene A si la operación CONNECT o ATTACH se realiza satisfactoriamente y el nombre de autorización de la conexión tiene más de 8 bytes. Contiene P si la estimación de coste relativo de la sentencia PREPARE almacenada en sqlerrd(4) supera el valor que se puede almacenar en un INTEGER o era menor de 1, y el registro especial CURRENT EXPLAIN MODE o CURRENT EXPLAIN SNAPSHOT se establece en un valor distinto de NO.
sqlwarn2 CHAR(1) Contiene W si los valores nulos se eliminaron del argumento de una función de agregación. a

Si se invoca CONNECT y se ejecuta satisfactoriamente, contiene una D si la base de datos se encuentra inmovilizada o I si la instancia se encuentra inmovilizada.
sqlwarn3 CHAR(1) Contiene W si el número de columnas no es igual al número de variables host. Contiene Z si el número de ubicadores del conjunto de resultado especificado en la sentencia ASSOCIATE LOCATORS es menor que el número de conjuntos de resultados devueltos por un procedimiento.
sqlwarn4 CHAR(1) Contiene W si una sentencia UPDATE o DELETE preparada no incluye una cláusula WHERE.
sqlwarn5 CHAR(1) Contiene E si se ha tolerado un error durante la ejecución de la sentencia SQL.
sqlwarn6 CHAR(1) Contiene W si se ha ajustado el resultado del cálculo de una fecha para evitar una fecha imposible.
sqlwarn7 CHAR(1) Si se invoca CONNECT y se ejecuta satisfactoriamente, contiene una B si el servidor es BigSQL.
sqlwarn8 CHAR(1) Contiene W si el carácter que no se ha podido convertir se ha sustituido por un carácter de sustitución. Contiene Y si ha habido un intento no satisfactorio de establecer una conexión fiable.
sqlwarn9 CHAR(1) Contiene W si se han ignorado expresiones aritméticas con errores durante el proceso de la función de agregación.
sqlwarn10 CHAR(1) Contiene W si ha habido un error de conversión al convertir un valor de datos de caracteres de uno de los campos de la SQLCA.
sqlstate CHAR(5) Un código de retorno que indica el resultado de la sentencia de SQL ejecutada más recientemente.

a Es posible que algunas funciones no establezcan SQLWARN2 en W aunque se hayan eliminado los valores nulos, porque el resultado no dependía de la eliminación de dichos valores.

Informe de errores

El orden en que notifican los errores es el siguiente:

  1. Las condiciones de error graves siempre se informan. Cuando se informa de un error grave, no hay ninguna adición a la SQLCA.
  2. Si no se produce ningún error grave, un error de punto muerto tiene prioridad sobre los demás errores.
  3. En el resto de errores, se devuelve la SQLCA para el primer código SQL negativo.
  4. Si no se detecta ningún código SQL negativo, se devuelve la SQLCA para el primer aviso (es decir, código SQL positivo).

    En un sistema de base de datos particionada, se produce una excepción a esta norma si se invoca una operación de manipulación de datos en una tabla que está vacía en una partición de base de datos, pero que tiene datos en otras particiones de base de datos. Sólo se devuelve SQLCODE +100 a la aplicación si los agentes de todas las particiones devuelven SQL0100W, porque la tabla está vacía en todas las particiones de base de datos o porque no hay más filas que cumplan la cláusula WHERE de una sentencia UPDATE.

Utilización de SQLCA en sistemas de bases de datos particionadas

En sistemas de bases de datos particionadas, una sentencia de SQL pueden ejecutarla varios agentes de distintas particiones de base de datos y cada agente puede devolver una SQLCA distinta para diferentes errores o avisos. El agente coordinador también tiene su propia SQLCA.

Para proporcionar una vista coherente para las aplicaciones, todos los valores de SQLCA se fusionan en una estructura y los campos de SQLCA indican cuentas globales como, por ejemplo:
  • Para todos los errores y avisos, el campo sqlwarn contiene los distintivos de aviso recibidos de todos los agentes.
  • Los valores de los campos sqlerrd que indican cuentas de fila son acumulaciones de todos los agentes.
Nota: Es posible que no se devuelva SQLSTATE 09000 cada vez que se produzca un error durante el proceso de una sentencia SQL desencadenada.