add

La sentencia EGL add coloca un registro en un archivo, una cola de mensajes o una base de datos; o coloca un conjunto de registros en una base de datos.


Diagrama de sintaxis para la sentencia add
nombre de registro
Nombre del objeto de E/S que debe añadirse; un DLISegment, un registro indexado, MQ, relativo, serie o SQL
usingPCB nombrePCB
Opción que permite especificar el nombre de un PCB, según lo definido en el registro PSB, para utilizarlo en lugar del PCB por omisión.
with #dli{ sentencia DLI }
Opción que permite una llamada explícita DL/I ISRT, como se describe en la sección Soporte DL/I. No deje espacios entre #dli y el corchete de apertura.
with #sql{ sentencia SQL }
Opción que permite una sentencia SQL INSERT explícita. No deje espacios después de #sql.
nombre de matriz dinámica SQL
El nombre de una matriz dinámica de registros SQL. Los elementos se insertan en la base de datos, cada uno en la posición especificada por los valores de clave específicos del elemento. La operación se detiene cuando se produce el primer error o cuando se insertan todos los elementos.

A continuación se ofrece un ejemplo:

if (userRequest == "A")
		try 
add record1;
		onException
myErrorHandler(12);
		end
	end

El comportamiento de la sentencia add depende del tipo de registro. Para obtener detalles acerca del proceso DL/I, consulte el tema Registro DLISegment. Para obtener detalles acerca del proceso SQL, consulte el tema Registro SQL.

Registro DLISegment

La sentencia add genera una sentencia DL/I ISRT. En DL/I, esta inserción tiene lugar en la posición actual en la base de datos, sea cual sea. Puede controlar este posicionamiento, por ejemplo, estableciendo explícitamente las claves en el programa EGL (como se muestra en el ejemplo que figura más abajo), utilizando una sentencia set record position, utilizando una sentencia get o creando SSA calificados mediante la directiva #dli.

El ejemplo siguiente añade un pedido a la base de datos de clientes:
	//crear
instancias de los registros
	myCustomer CustomerRecord;
	myLocation LocationRecord;
	myOrder    OrderRecord;

	//crear un argumento de búsqueda de segmento
	myCustomer.customerNo = "005001";
	myLocation.locationNo = "000022";

	//rellenar los campos del registro de pedido
	fillOrder(myOrder);
	
	//añadir el registro de pedido nuevo
	try
		add myOrder;
		onException
			myErrorHandler(2);
	end
Esta sentencia add generará el siguiente código pseudo-DL/I:
ISRT STSCCST (STQCCNO = :myCustomer.customerNo) 
     STSCLOC (STQCLNO = :myLocation.locationNo) 
     STPCORD
Los argumentos de búsqueda de segmento (SSA) calificados para el cliente y la ubicación identifican los segmentos padre del nuevo segmento de pedido. DL/I añadirá el nuevo segmento de pedido en una posición determinada por el campo keyItem de ese segmento, orderDateNo (STQCODN).
Para capturar errores "leves" de E/S, como por ejemplo "noRecordFound", utilice un bloque de establecimiento de valores al crear el programa para establecer la propiedad de programa throwNrfEofExceptions en yes. En la función de manejo de errores, compruebe los errores con los operadores "is" o "not":
	if (myOrder is unique)
		...
	end
Los posibles errores de tiempo de ejecución son los siguientes:
  • unique si ya existe un segmento de pedido con la clave especificada (no se permiten duplicaciones)
  • duplicate si existe un segmento de pedido con la misma clave, pero se permiten las duplicaciones
DL/I también da soporte al uso de llamadas de vía de acceso en sentencias add. Esto significa que puede añadir segmentos padre para todos los niveles de segmento entre el segmento de nivel más bajo que esté añadiendo y el segmento raíz. En el ejemplo siguiente, DL/I añadirá un cliente y una ubicación nuevos al mismo tiempo que añade un pedido nuevo:
add myCustomer, myLocation, myOrder;
EGL generará el siguiente código pseudo-DL/I a partir de esta sentencia:
ISRT STSCCST*D (STQCCNO = :myCust.customerNo) 
     STSCLOC (STQCLNO = :myLocation.locationNo) 
     STPCORD

Registro indexado

Si añade un registro indexado, la clave del registro determina la posición lógica del registro en el archivo. La adición de un registro a una posición de archivo que ya se esté utilizando provoca un error grave de E/S UNIQUE o (si se permiten duplicaciones) el error leve de E/S DUPLICATE.

Registro MQ

Al añadir un registro MQ, el registro se coloca al final de la cola. Esta colocación se produce debido a que la sentencia add invoca una o varias llamadas MQSeries:

Registro relativo

Si añade un registro relativo, el elemento de clave especifica la posición del registro en el archivo. Sin embargo, la adición de un registro a una posición de archivo que ya se esté utilizando provoca un error grave de E/S UNIQUE.

El elemento de clave de registro debe estar disponible para cualquier función que utilice el registro y puede ser cualquiera de los siguientes:
  • Un elemento del mismo registro
  • Un elemento de un registro que sea global con respecto al programa o local con respecto a la función que ejecuta la sentencia add
  • Un elemento de datos que sea global con respecto al programa o local con respecto a la función que ejecuta la sentencia add

Registro serie

Al añadir un registro serie, el registro se coloca al final del archivo.

Si el programa generado finaliza un registro serie y luego emite una sentencia get next para el mismo archivo, el programa cierra y vuelve a abrir el archivo antes de ejecutar la sentencia get next. Por tanto, una sentencia get next que sigue a una sentencia add lee el primer registro del archivo. Este comportamiento también se produce cuando las sentencias get next y add se encuentran en programas diferentes, y un programa llama al otro.

Es aconsejable evitar que el mismo archivo esté abierto en más de un programa simultáneamente.

En CICS para z/OS, un solo programa no puede incluir una combinación de las sentencias add y get next para el mismo archivo de spool. Esta restricción también se aplica cuando las sentencias add y get next se encuentran en programas diferentes, y un programa llama al otro. De forma parecida, una sentencia add a continuación de una sentencia get o get next añadirá un registro al principio del archivo.

Para BMP de IMS o z/OS por lotes, si añade un registro serie de longitud variable a un archivo asociado con GSAM y la longitud del registro es superior a la del archivo físico, DL/I devuelve un código de estado en blanco. Los datos se truncan pero no se emite ningún mensaje, ya que la situación no puede detectarse.

Para IMS/VS, debe asociar un registro serie con un PCB alternativo (un PCB TP del PSB). La cabecera del mensaje IMS (longitud, campo ZZ y código de transacción) se añade automáticamente a cada registro escrito en la cola de mensajes. Una sentencia EGL add para un registro serie asignado a una cola de mensajes da como resultado una llamada ISRT a la cola de mensajes. Si se produce un error y el registro se asigna a una cola de mensajes de varios segmentos y se asocia al PCB alterno expreso, los registros ya añadidos se comprometen, aunque no se haya producido una sentencia close explícita. Si es importante que estos registros no se comprometan, incluya un PCB alterno expreso adicional en el PSB y asocie el archivo al PCB alterno expreso adicional.

Registro SQL

A continuación se indican algunas condiciones de error:
  • Se especifica una sentencia SQL de un tipo que no es INSERT
  • Se especifica alguna, pero no todas las cláusulas de una sentencia SQL INSERT
  • Se especifica una sentencia SQL INSERT (o se acepta una sentencia SQL implícita) que tiene alguna de estas características:
    • Está relacionada con más de una tabla SQL
    • Incluye sólo variables de lenguaje principal que ha declarado como de sólo lectura
    • Está asociada con una columna que no existe o que es incompatible con la variable de lenguaje principal relacionada
Al añadir un registro SQL sin especificar una sentencia SQL explícita, el resultado es el siguiente:
  • El formato de la sentencia SQL INSERT generada es como este:
      INSERT INTO nombre Tabla
        (columna01, ... columnaNN)
        values (:elementoRegistro01, ... :elementoRegistroNN)
  • El valor de clave del registro determina la posición lógica de los datos en la tabla. Un registro que no tenga una clave se maneja de acuerdo con la definición de tabla SQL y las normas de la base de datos.
  • Como resultado de la asociación de elementos de registro y columnas de tabla SQL en el componente de registro, el código generado coloca los datos de cada elemento de registro en la columna de tabla SQL relacionada.
  • Si ha declarado un elemento de registro como de sólo lectura, la sentencia SQL INSERT generada no incluye ese elemento de registro, y el sistema de gestión de bases de datos establece el valor de la columna de tabla SQL relacionada en el valor por omisión especificado al definir la columna.
A continuación figura un ejemplo de utilización de una matriz dinámica de registros SQL:
  try
    add employees;
    onException
      sysLib.rollback();
  end
Comentarios
(C) Copyright IBM Corporation 2000, 2005. Reservados todos los derechos.