Matrices de variables de host en C y C++

En los programas C y C++, puede especificar matrices de variables de host de tipo numérico, carácter, gráfico, binario, LOB, XML y ROWID. También puede especificar localizadores LOB y variables de referencia de archivos LOB y XML.

Solo se puede hacer referencia a las matrices de variables de lenguaje principal como una referencia simple en los contextos siguientes. En los diagramas de sintaxis, host-variable-array designa una referencia a una matriz de variables de host.

En una sentencia FETCH para una captación de varias filas. Ver declaración FETCH.
En la forma FOR n ROWS de la sentencia INSERT con una matriz de variables de host para los datos de origen. Ver declaración INSERT.
En una sentencia MERGE con varias filas de datos de origen. Véase la declaración MERGE.
En una sentencia EXECUTE para proporcionar un valor para un marcador de parámetro en una forma dinámica FOR n ROWS de la sentencia INSERT o una sentencia MERGE. Ver la instrucción EXECUTE.

Inicio del cambio Si una aplicación hace referencia a una matriz de variables de host en otros contextos no admitidos, Db2 devuelve el error SQLCODE -312. fin del cambio

Restricciones:

Solo algunas de las declaraciones C válidas son declaraciones de matriz de variables de host válidas. Si la declaración de una matriz variable no es válida, cualquier instrucción SQL que haga referencia a la matriz variable podría dar lugar al mensaje UNDECLARED HOST VARIABLE ARRAY.
Tanto para C como para C++, no se puede especificar el atributo _packed en las declaraciones de estructura para las siguientes matrices que se utilizan en sentencias INSERT, FETCH y MERGE de varias filas:
- matrices de caracteres de longitud variable
- matrices gráficas de longitud variable
- Matrices LOB
Además, la directiva #pragma pack(1) no puede estar en vigor si planea utilizar estas matrices en sentencias de varias filas.

Matrices de variables de host numéricas

El siguiente diagrama muestra la sintaxis para declarar matrices de variables de host numéricas.

Notas:

¹ dimensión debe ser una constante entera en el rango 1-32767.

Ejemplo

El siguiente ejemplo muestra una declaración de una matriz numérica de variables de host:

EXEC SQL BEGIN DECLARE SECTION;
    /* declaration of numeric host-variable array */
    long serial_num[10];
    ...
EXEC SQL END DECLARE SECTION;

Matrices de variables de host de caracteres

Puede especificar las siguientes formas de matrices de variables de host de caracteres:

Formulario de caracteres terminados en NUL
Formulario estructurado VARCHAR
CLOB

Los siguientes diagramas muestran la sintaxis para formularios distintos de CLOB.

El siguiente diagrama muestra la sintaxis para declarar matrices de variables de host de caracteres terminadas en NUL.

Notas:

¹ dimensión debe ser una constante entera en el rango 1-32767.
² Cualquier cadena que se asigne a esta variable debe terminar en NUL. Cualquier cadena que se recupere de esta variable terminará en NUL.
³ Las cadenas de un array de variables de host de caracteres terminados en NUL se asignan a cadenas de caracteres de longitud variable (excepto para el NUL).

El siguiente diagrama muestra la sintaxis para declarar matrices de variables de host de caracteres de longitud variable que utilizan la forma estructurada VARCHAR.

Notas:

¹ Puede utilizar la etiqueta struct para definir otras variables, pero no puede utilizarlas como matrices de variables de host en SQL.
² var-1 debe ser una variable numérica escalar.
³ var-2 debe ser una variable de matriz escalar CHAR.
la dimensión ⁴ debe ser una constante entera en el rango 1-32767.

Ejemplo

El siguiente ejemplo muestra declaraciones válidas e inválidas de matrices de variables de host VARCHAR.

EXEC SQL BEGIN DECLARE SECTION;
    /* valid declaration of VARCHAR host-variable array */
    struct VARCHAR {
      short len;
      char s[18];
      } name[10];

/* invalid declaration of VARCHAR host-variable array */
   struct VARCHAR name[10];

Matrices binarias de variables de host

El siguiente diagrama muestra la sintaxis para declarar matrices de variables de host binarias.

Notas:

¹ dimensión debe ser una constante entera en el rango 1-32767.

Matrices gráficas de variables de host

Puede especificar las siguientes formas de matrices de variables de host gráficas:

Forma gráfica terminada en NUL
Formulario estructurado VARGRAPHIC.

Recomendación : En lugar de utilizar el tipo de datos C wchar_t para definir matrices de variables de host gráficas y vargráficas, utilice una de las siguientes técnicas:

Defina el tipo de datos sqldbchar utilizando la siguiente declaración typedef:
```
typedef unsigned short sqldbchar;
```
Utilice el tipo de datos sqldbchar que se define en la instrucción typedef en los archivos de cabecera que suministra Db2.
Utiliza el tipo de datos C sin signo corto.

El siguiente diagrama muestra la sintaxis para declarar matrices de variables de host gráficas terminadas en NUL.

Notas:

¹ dimensión debe ser una constante entera en el rango 1-32767.
² length debe ser una constante entera decimal mayor que 1 y no mayor que 16352.
³ Cualquier cadena que se asigne a esta variable debe terminar en NUL. Cualquier cadena que se recupere de esta variable terminará en NUL.
⁴ No asignar caracteres de un solo byte en una matriz de variables de host gráficas terminada en NUL

El siguiente diagrama muestra la sintaxis para declarar matrices de variables de host gráficas que utilizan la forma estructurada VARGRAPHIC.

Notas:

¹ Puede utilizar la etiqueta struct para definir otras variables, pero no puede utilizarlas como matrices de variables de host en SQL.
² var-1 debe ser una variable numérica escalar.
³ var-2 debe ser una variable de matriz de caracteres escalar.
⁴ length debe ser una constante entera decimal mayor que 1 y no mayor que 16352.
la dimensión ⁵ debe ser una constante entera en el rango de 1 a 32767.

Ejemplo

El siguiente ejemplo muestra declaraciones válidas e inválidas de matrices de variables de host gráficas que utilizan la forma estructurada VARGRAPHIC.

EXEC SQL BEGIN DECLARE SECTION;
   /* valid declaration of host-variable array vgraph */
   struct VARGRAPH {
      short len;
      sqldbchar d[10];
      } vgraph[20];
 
   /* invalid declaration of host-variable array vgraph */
   struct VARGRAPH vgraph[20];

LOB, localizador y matrices de variables de referencia de archivos

El siguiente diagrama muestra la sintaxis para declarar matrices de variables de host BLOB, CLOB y DBCLOB, localizadores y variables de referencia de archivos.

Notas:

¹ dimensión debe ser una constante entera en el rango 1-32767.

Variables de matriz de referencia de archivos y host XML

El siguiente diagrama muestra la sintaxis para declarar matrices de variables de host BLOB, CLOB y DBCLOB y matrices de variables de referencia de archivos para tipos de datos XML.

Notas:

¹ dimensión debe ser una constante entera en el rango 1-32767.

Matrices de variables ROWID

El siguiente diagrama muestra la sintaxis para declarar matrices de variables ROWID.

Notas:

¹ dimensión debe ser una constante entera en el rango 1-32767.