Sentencia CREATE VARIABLE

La sentencia CREATE VARIABLE define una variable global de sesión.

Invocación

Esta sentencia puede incorporarse en un programa de aplicación o emitirse de forma interactiva. Es una sentencia ejecutable que puede prepararse de forma dinámica sólo si el comportamiento de ejecución de DYNAMICRULES está en vigor para el paquete (SQLSTATE 42509).

Autorización

Los privilegios que posee el ID de autorización de la sentencia debe tener al menos una de las autorizaciones siguientes:

Autorización IMPLICIT_SCHEMA en la base de datos, si el nombre de esquema implícito o explícito de la variable no existe
Privilegio CREATEIN para el esquema, si el nombre de esquema de la variable hace referencia a un esquema existente
Autorización SCHEMAADM en el esquema, si el nombre de esquema de la variable hace referencia a un esquema existente
Autorización DBADM

y cualesquiera privilegios que sean necesarios para ejecutar la expresión por omisión.

Para ejecutar esta sentencia con un constructor-valor-cursor que utiliza una sentencia-select, los privilegios del ID de autorización de la sentencia deben incluir los privilegios necesarios para ejecutar la sentencia-select. Consulte la sección Autorización en Consultas de SQL.

Los privilegios de grupo no se tienen en cuenta a la hora de comprobar la autorización para los objetos a los que se hace referencia en la sentencia.

Para sustituir una variable existente, el ID de autorización de la sentencia debe ser el propietario de la variable existente (SQLSTATE 42501).

Sintaxis

tipo-datos1

tipo-incorporado

tipo-datos-variable-anclados

constructor-valor-cursor

declaración-parámetro

tipo-datos-2

tipo-datos-parámetro-anclado

posibilidad de mantenimiento

Notas:

¹ Si tipo-datos1 especifica un tipo incorporado CURSOR o un nombre-tipo-cursor, solamente pueden especificarse NULL o constructor-valor-cursor. Únicamente se puede especificar DEFAULT NULL explícitamente para el nombre-tipo-matriz o nombre-tipo-fila.
² La cláusula FOR BIT DATA se puede especificar en cualquier orden con las restricciones de columna siguientes. La cláusula FOR BIT DATA no se puede especificar con unidades de serie CODEUNITS32 (SQLSTATE 42613).

Descripción

OR REPLACE

Especifica que se debe sustituir la definición de la variable si existe una en el servidor actual. La definición existente se descarta de forma efectiva antes de que la nueva definición se sustituya en el catálogo, con la excepción de que los privilegios que se han otorgado sobre la variable no se ven afectados por ello. Esta opción se ignora si no existe una definición para la variable en el servidor actual. Esta opción sólo puede especificarla el propietario del objeto.

nombre-variable

Da nombre a la variable global. El nombre, incluyendo un calificador implícito o explícito, no debe identificar una variable global que ya exista en el servidor actual (SQLSTATE 42710). Si no se especifica el calificador, se asigna el esquema actual de forma implícita. Si el nombre de variable global se califica explícitamente con un nombre de esquema, el nombre de esquema no puede empezar con los caracteres SYS (SQLSTATE 42939).

tipo1-datos

Especifica el tipo de datos de la variable global. No puede especificarse un tipo estructurado (SQLSTATE 42611).

tipo-incorporado

Especifica un tipo de datos incorporado. BOOLEAN y CURSOR no pueden especificarse para una tabla. Para obtener una descripción más completa de cada tipo de datos incorporado, consulte CREATE TABLE.

Se puede especificar FOR BIT DATA como parte de los tipos de datos de serie de caracteres.

BOOLEAN: Para un booleano.
CURSOR: Para una referencia a un cursor subyacente.

tipo-datos-variable-anclados

Identifica otro objeto que se utiliza para determinar el tipo de datos de la variable global. El tipo de datos del objeto de anclaje tiene las mismas limitaciones que se aplican a la especificación del tipo de datos directamente o, en el caso de una fila, a la creación de un tipo de fila.

ANCHOR DATA TYPE TO

Indica que se utiliza un tipo de datos anclados para especificar el tipo de datos.

nombre2-variable

Identifica una variable global. El tipo de datos de la variable a la que se hace referencia se utiliza como tipo de datos para la variable global.

nombre-tabla.nombre-columna

Identifica un nombre de columna de una tabla o vista existente. El tipo de datos de la columna se utiliza como tipo de datos para la variable global.

ROW OF nombre-tabla o nombre-vista

Especifica que la variable global es una fila de campos con nombres y tipos de datos que se basan en los nombres de columna y los tipos de datos de columna de la tabla identificada por nombre-tabla o la vista identificada por nombre-vista. El tipo de datos de la variable global es un tipo de fila sin nombre.

ROW OF nombre-variable-cursor

Especifica una fila de campos con nombres y tipos de datos que se basan en los nombres de campo y los tipos de datos de campos de la variable de cursor identificada por nombre-variable-cursor. La variable de cursor especificada debe ser uno de los elementos siguientes (SQLSTATE 428HS):

Una variable global con un tipo de datos de cursor con tipo firme.
Una variable global con un tipo de datos de cursor con tipo no firme que se creó o declaró con una cláusula CONSTANT especificando una sentencia-select en la que todas las columnas de resultados tienen nombre.

Si el tipo de cursor de la variable global no es de un tipo firme que utiliza un tipo de fila con nombre, el tipo de datos de la variable global es un tipo de fila sin nombre.

nombre-tipo-matriz

Especifica el nombre de un tipo de matriz definido por el usuario. Si se especifica el nombre-tipo-matriz sin un nombre de esquema, el tipo de matriz se resuelve buscando en los esquemas de la vía de acceso de SQL.

nombre-tipo-cursor

Especifica el nombre de un tipo de cursor. Si se especifica el nombre-tipo-cursor sin un nombre de esquema, el tipo de cursor se resuelve buscando en los esquemas de la vía de acceso de SQL.

nombre-tipo-diferenciado

Especifica el nombre de un tipo diferenciado. La longitud, la precisión y la escala de la variable declarada son, respectivamente, la longitud, la precisión y la escala del tipo fuente del tipo diferenciado. Si se especifica el nombre-tipo-diferenciado sin un nombre de esquema, el tipo diferenciado se resuelve buscando en los esquemas de la vía de acceso de SQL.

REF (nombre-tipo)

Especifica un tipo de referencia. Si se especifica un nombre de tipo sin un nombre de esquema, el nombre-tipo se resuelve buscando los esquemas en la vía de acceso de SQL.

nombre-tipo-fila

Especifica el nombre de un tipo de fila definido por el usuario. Los campos de la variable son los campos del tipo de fila. Si se especifica el nombre-tipo-fila sin un nombre de esquema, el tipo de fila se resuelve buscando en los esquemas de la vía de acceso de SQL.

DEFAULT o CONSTANT

Especifica un valor para la variable global cuando se hace referencia a ella por primera vez en la sesión. El valor de la cláusula DEFAULT o CONSTANT se determina en esta primera referencia. Si no se especifica ninguna, el valor por omisión para la variable global es el valor nulo. Sólo puede especificarse de forma explícita DEFAULT NULL si está especificado nombre-tipo-matriz o nombre-tipo-fila.

DEFAULT

Define el valor por omisión de la variable global. El valor por omisión debe ser una asignación compatible con el tipo de datos de la variable.

CONSTANT

Especifica que la variable global tiene un valor fijo que no se puede cambiar. Una variable global que se defina mediante CONSTANT no puede utilizarse como destino de una operación de asignación. El valor fijo debe ser compatible con la asignación al tipo de datos de la variable.

NULL

Especifica NULL como valor por omisión para la variable global. Si se especifica el nombre-tipo-fila, el valor de la variable global es una fila donde cada campo tiene el valor nulo.

constante

Especifica el valor de una constante como valor por omisión para la variable global. Si tipo-datos1 especifica un tipo incorporado CURSOR o un nombre-tipo-cursor, no puede especificarse la constante (SQLSTATE 42601).

registro-especial

Especifica el valor de un registro especial como valor por omisión para la variable global. Si tipo1-datos especifica un tipo incorporado CURSOR o un nombre-tipo-cursor, no se puede especificar el registro-especial (SQLSTATE 42601).

variable-global

Especifica el valor de una variable global como valor por omisión para la variable global. Si tipo1-datos especifica un tipo incorporado CURSOR o un nombre-tipo-cursor, no se puede especificar la variable-global (SQLSTATE 42601).

constructor-valor-cursor

Un constructor-valor-cursor especifica la sentencia-select asociada con la variable global. La asignación de un constructor-valor-cursor a una variable de cursor define el cursor subyacente de esa variable de cursor.

ASENSITIVE o INSENSITIVE

Especifica si el cursor es sensible o insensible a los cambios. Consulte DECLARE CURSOR para obtener más información. El valor por omisión es ASENSITIVE.

ASENSITIVE: Especifica que el cursor debe ser todo lo sensible que sea posible para las operaciones de inserción, actualización o supresión realizadas en las filas subyacentes de la tabla de resultados, en función de cómo se haya optimizado sentencia-select. Esta opción es el valor por omisión.
INSENSITIVE: Especifica que el cursor no debe contar con sensibilidad para las operaciones de inserción, actualización o supresión que se han realizado en las filas subyacentes de la tabla de resultados. Si se especifica INSENSITIVE, el cursor es de sólo lectura y la tabla de resultados se materializa al abrirse el cursor. Como resultado de ello, el tamaño de la tabla de resultados, el orden de las filas y los valores de cada fila no cambian tras abrirse el cursor. La sentencia SELECT no puede contener una cláusula FOR UPDATE, y el cursor no puede utilizarse para las actualizaciones o supresiones posicionadas.

(declaración-parámetro, ...)

Especifica los parámetros de entrada del cursor, incluido el nombre y el tipo de datos de cada parámetro.

nombre-parámetro

Asigna un nombre al parámetro que se debe utilizar como variable de SQL dentro de la sentencia-select. El nombre no puede ser igual que ningún otro nombre de parámetro del cursor. Los nombres deben elegirse también evitando nombres de columna que se puedan utilizar en la sentencia-select, ya que los nombres de columna se resuelven antes que los nombres de parámetro.

tipo2-datos

Especifica el tipo de datos del parámetro de cursor utilizado dentro de una sentencia-select.

tipo-incorporado: Especifica un tipo de datos incorporado. Para obtener una descripción más completa de cada tipo de datos incorporado, consulte CREATE TABLE. Los tipos incorporados BOOLEAN y CURSOR no pueden especificarse (SQLSTATE 429BB).

tipo-datos-parámetro-anclado

Identifica otro objeto que se utiliza para determinar el tipo de datos del parámetro de cursor. El tipo de datos del objeto de anclaje se ve afectado por las mismas limitaciones que se aplican cuando se especifica el tipo de datos directamente.

ANCHOR DATA TYPE TO

Indica que se utiliza un tipo de datos anclados para especificar el tipo de datos.

nombre-variable: Identifica una variable global. El tipo de datos de la variable a la que se hace referencia se utiliza como tipo de datos para el parámetro de cursor.
nombre-tabla.nombre-columna: Identifica un nombre de columna de una tabla o vista existente. El tipo de datos de la columna se utiliza como tipo de datos para el parámetro de cursor.

nombre-tipo-diferenciado: Especifica el nombre de un tipo diferenciado. Si se especifica el nombre-tipo-diferenciado sin un nombre de esquema, el tipo diferenciado se resuelve buscando en los esquemas de la vía de acceso de SQL.

posibilidad de mantenimiento

Especifica si se impedirá que el cursor se cierre como consecuencia de una operación de confirmación. Consulte DECLARE CURSOR para obtener más información. El valor por omisión es WITHOUT HOLD.

WITHOUT HOLD: No impide que el cursor se cierre como consecuencia de una operación de confirmación.
WITH HOLD: Mantiene recursos en varias unidades de trabajo. Impide que el cursor se cierre como consecuencia de una operación de confirmación.

sentencia-select

Especifica la sentencia SELECT del cursor. Consulte sentencia-select para obtener más información.

nombre-sentencia

Especifica la sentencia-select preparada del cursor. Consulte PREPARE para obtener una explicación de las sentencias preparadas. La variable del cursor de destino no debe tener un tipo de datos que sea un tipo de cursor definido por el usuario con tipo firme (SQLSTATE 428HU).

expresión

Especifica el valor de una expresión como valor por omisión para la variable global. La expresión puede ser cualquier expresión del tipo que se describe en el apartado Expresiones. La expresión debe ser compatible con la asignación al tipo de datos de la variable. El tamaño máximo de la expresión es de 64K. La expresión por omisión no debe modificar datos SQL (SQLSTATE 428FL) ni realizar acciones externas (SQLSTATE 42845). Si tipo1-datos especifica un tipo incorporado CURSOR o un nombre-tipo-cursor, no se puede especificar la expresión (SQLSTATE 42601).

Normas

Utilización de tipos de datos anclados: Un tipo de datos anclado no puede hacer referencia a los siguientes objetos (SQLSTATE 428HS): un apodo, una tabla con tipo, una vista con tipo, una vista estadística asociada con un índice basado en la expresión, una tabla temporal declarada, una definición de fila asociada con un cursor de tipo débil, un objeto con una página de códigos o una clasificación que es diferente de la página de códigos de la base de datos o la asignación de base de datos.

Notas

Las variables globales de sesión tienen un ámbito de sesión. Esto significa que, aunque están disponibles para todas las sesiones activas en la base de datos, su valor es privado para cada una de las sesiones.
Contextos para variables globales de fila, cursor, booleanas y de matriz: las variables globales que son variables de matriz, variables booleanas o variables de fila sólo se pueden utilizar en sentencias de SQL compuesto (compilado) o en sentencias de variable SET. Las variables globales que son variables de cursor solamente se pueden utilizar en sentencias de SQL compuesto (compilado).
Crear con errores: Si un objeto referenciado en la expresión predeterminada no existe o se ha marcado como no válido, o el definidor no tiene temporalmente privilegios para acceder al objeto, y si el parámetro de configuración de base de datos auto_reval está establecido en DISABLED, la variable se seguirá creando correctamente. La variable se marcará como no válida y se volverá a validar la próxima vez que se invoque.
Ámbito de valores de variable global: Los valores de las variables globales se mantienen hasta que se actualizan en la sesión actual, hasta que se descarta o modifica la variable global o hasta que finaliza una sesión de la aplicación. El valor no se ve afectado por las sentencias COMMIT o ROLLBACK. El valor por omisión para una variable global puede ser no determinista y dependiente de cuándo se calcula el valor por omisión para la variable global (por ejemplo, una referencia a la hora del día o una referencia a algunos datos almacenados en una tabla).
Una técnica utilizada habitualmente, sobre todo para cuestiones de rendimiento, es que una aplicación o producto gestione un conjunto de conexiones y direccione transacciones a una conexión arbitraria. En estas situaciones, el valor que no sea por omisión de una variable global o el valor por omisión inicial no determinista para una variable global solamente deberían ser dependientes hasta que finalice la transacción. Algunos ejemplos de dónde puede producirse este tipo de situación incluyen aplicaciones que utilicen protocolos XA, usen la agrupación de conexiones, empleen el concentrador de conexiones y utilicen HADR para lograr la migración tras error.
Privilegios para utilizar una variable global: Todo intento de leer o grabar en una variable global creada mediante esta sentencia requiere que el ID de autorización que intente esta acción detente el privilegio correspondiente sobre la variable global. Al definidor de la variable se le otorgan de modo implícito todos los privilegios sobre la variable.
Establecimiento del valor por omisión: La primera vez que se hace referencia a una variable global creada dentro de un determinado ámbito se crea una instancia de la misma en su valor por omisión. Tenga en cuenta que si se hace referencia a una variable global en una sentencia, se creará una instancia de la misma con independencia del flujo de control para dicha sentencia.
Utilización de una variable global de sesión recién creada: Si se crea una variable global en una sesión, no podrán utilizarla otras sesiones hasta que se haya confirmado la unidad de trabajo. Sin embargo, la variable global nueva puede utilizarse en la sesión que creó la variable antes de la confirmación de la unidad de trabajo.

Ejemplos

Ejemplo 1: Cree una variable global de sesión para indicar la impresora que ha de utilizarse para la sesión.
```
   CREATE VARIABLE MYSCHEMA.MYJOB_PRINTER VARCHAR(30)
     DEFAULT 'Impresora por omisión'
```

Ejemplo 2: Cree una variable global de sesión para indicar el departamento en el que trabaja el empleado.

   CREATE VARIABLE SCHEMA1.GV_DEPTNO INTEGER
     DEFAULT ((SELECT DEPTNO FROM HR.EMPLOYEES
       WHERE EMPUSER = SESSION_USER))

Ejemplo 3: Cree una variable global de sesión para indicar el nivel de seguridad del usuario actual.

   CREATE VARIABLE SCHEMA2.GV_SECURITY_LEVEL INTEGER
     DEFAULT (GET_SECURITY_LEVEL (SESSION_USER))

Ejemplo 4: Cree una variable global de sesión como un cursor en la tabla STAFF que devuelva los nombres de cada empleado para cada tipo de trabajo especificado. Ordene los resultados por número de departamento.
```
   CREATE VARIABLE STAFFJOBS CURSOR
     CONSTANT (CURSOR (WHICHJOB CHAR(5)) 
     FOR SELECT NAME, DEPT FROM STAFF WHERE JOB = WHICHJOB 
       ORDER BY DEPT)
```
Ejemplo 5: Crear una variable global del tipo de datos XML:
```
   CREATE VARIABLE MYSCHEMA.CUSTOMER_HISTORY_VAR XML
```