Sentencia FETCH

Invocación

Aunque un recurso SQL interactivo pueda proporcionar una interfaz que dé la apariencia de ejecución interactiva, esta sentencia sólo puede incorporarse dentro de un programa de aplicación. Es una sentencia ejecutable que no se puede preparar dinámicamente. Cuando se invoca utilizan el procesador de línea de mandatos, la sintaxis siguiente nombre-cursor es opcional y diferente de la sintaxis de SQL.

Para obtener más información, consulte Utilización de sentencias SQL y sentencias XQuery de línea de mandatos.

Autorización

Para obtener información acerca de la autorización que se necesita para utilizar un cursor, consulte DECLARE CURSOR.

Sintaxis

destino-asignación

Descripción

nombre-variable-cursor

Identifica el cursor que se va a utilizar en una operación de lectura. El nombre-variable-cursor debe identificar una variable de cursor que esté en el ámbito. Cuando se ejecuta la sentencia FETCH, el cursor subyacente del nombre-variable-cursor debe estar en estado abierto. Una sentencia FETCH que utiliza un nombre-variable-cursor sólo se puede utilizar en una sentencia de SQL compuesto (compilado).

INTO destino-asignación

Identifica uno o varios destinos para la asignación de los valores de salida. El primer valor de la fila del resultado se asigna al primer destino de la lista, el segundo valor al segundo destino, etcétera. Cada asignación que se realiza para un destino-asignación se realiza secuencialmente y siguiendo la lista. Si se produce un error en cualquier asignación, no se asigna el valor al destino y no se asignan más valores a los destinos. Cualquier valor que ya se haya asignado a los destinos continúa asignado.

Cuando el tipo de datos de cada destino-asignación no es un tipo de fila, se asigna el valor 'W' al campo SQLWARN3 del SQLCA si el número de destinos-asignación es menor que el número de valores de la columna de resultados.

Si el tipo de datos de un destino-asignación es un tipo de fila, debe haber exactamente un destino-asignación especificado (SQLSTATE 428HR), el número de columnas debe coincidir con el número de campos en el tipo de fila y los tipos de datos de las columnas de la fila captada deben poder asignarse a los campos correspondientes del tipo de fila (SQLSTATE 42821).

Si el tipo de datos de un destino-asignación es un elemento de matriz, debe haber exactamente un destino-asignación especificado.

nombre-variable-global

Identifica la variable global que es el sujeto de la asignación.

nombre-variable-lenguaje-principal

Identifica la variable del lenguaje principal que es el sujeto de la asignación. Para los valores de salida LOB, el destino puede ser una variable del lenguaje principal normal (si es lo suficientemente grande), una variable de localizador LOB o una variable de referencia a archivos LOB.

nombre-parámetro-SQL

Identifica el parámetro que es el sujeto de la asignación.

nombre-variable-SQL

Identifica la variable de SQL que es el sujeto de la asignación. Las variables de SQL se deben declarar antes de utilizarlas.

nombre-variable-transición

Identifica la columna que se debe actualizar en la fila de transición. Un nombre-variable-transición debe identificar una columna en la tabla sujeto de un activador, calificado opcionalmente por un nombre de correlación que identifica el nuevo valor.

nombre-variable-matriz

Identifica una variable de SQL, un parámetro de SQL o una variable global con tipo de matriz.

[índice-matriz]

Expresión que especifica qué elemento de la matriz será el destino de la asignación. Para una matriz común, la expresión de índice-matriz se debe poder asignar a INTEGER (SQLSTATE 428H1) y no puede ser un valor nulo. Su valor debe estar entre 1 y la cardinalidad máxima definida para la matriz (SQLSTATE 2202E). Para una matriz asociativa, la expresión de índice-matriz se debe poder asignar al tipo de datos de índice de la matriz asociativa (SQLSTATE 428H1) y no puede ser un valor nulo.

referencia-campo

Identifica el campo de un valor de tipo de fila que es el destino de la asignación. La referencia-campo debe especificarse como un nombre-campo calificado donde el calificador identifica el valor de fila donde está definido el campo.

USING DESCRIPTOR nombre-descriptor

Identifica una SQLDA que debe contener una descripción válida de cero o más variables del lenguaje principal.

Antes de procesar la sentencia FETCH, el usuario debe establecer los campos siguientes en la SQLDA:

• SQLN para indicar el número de apariciones de SQLVAR proporcionadas en la SQLDA.
• SQLDABC para indicar el número de bytes de almacenamiento asignado para la SQLDA.
• SQLD para indicar el número de variables utilizadas en SQLDA al procesar la sentencia.
• Las apariciones de SQLVAR, para indicar los atributos de las variables.

SQLDA debe tener suficiente almacenamiento para contener todas las apariciones de SQLVAR. Por lo tanto, el valor de SQLDABC debe ser mayor o igual que 16 + SQLN*(N), donde N es la longitud de una aparición SQLVAR.

Si las columnas resultantes de LOB o de tipo estructurado necesitan acomodarse, debe haber dos entradas SQLVAR para cada elemento de la lista de selección (o columna de la tabla de resultados).

SQLD debe establecerse en un valor mayor o igual que cero y menor o igual que SQLN.

La variable número n descrita en el SQLDA corresponde a la columna número n de la tabla de resultados del cursor. El tipo de datos de cada variable debe ser compatible con su columna correspondiente.

Cada asignación que se realiza para una variable se realiza de acuerdo con normas específicas. Si el número de variables es menor que el número de valores de la fila, el campo SQLWARN3 de la SQLDA se establece en 'W'. Tenga en cuenta que no hay ningún aviso si hay más variables que el número de columnas del resultado. Si se produce un error de asignación, no se asigna el valor a la variable y no se asignan más valores a las variables. Cualquier valor que ya se haya asignado a las variables continúa asignado.

Ejemplos

• Ejemplo 1:  En este ejemplo C, la sentencia FETCH coloca los resultados de la sentencia SELECT en las variables de programa dnum, dname y mnum. Cuando ya no quedan más filas para leer, se devuelve la condición de no encontrado.

     EXEC SQL DECLARE C1 CURSOR FOR
       SELECT DEPTNO, DEPTNAME, MGRNO FROM TDEPT
         WHERE ADMRDEPT = 'A00';
  
     EXEC SQL OPEN C1;
  
     mientras (SQLCODE==0) {
         EXEC SQL FETCH C1 INTO :dnum, :dname, :mnum;
     }
  
     EXEC SQL CLOSE C1;

• Ejemplo 2:  La sentencia FETCH utiliza una SQLDA.

  
     FETCH CURS USING DESCRIPTOR :sqlda3