Sentencia CREATE

La sentencia CREATE crea un nuevo campo de mensaje.

Notas:
  1. No utilice la CláusulaDomain ni la CláusulaParse con el calificador FIELD. Cada subcláusula de CláusulaParse sólo puede aparecer una vez.
  2. Utilice la CláusulaRepeat sólo con los calificadores PREVIOUSSIBLING y NEXTSIBLING

El nuevo campo de mensajes se coloca en una ubicación determinada (CREATE FIELD) o relativa a una ubicación ya existente (CREATE ... OF...). Los nuevos campos sólo se pueden crear cuando la referencia de campo de destino apunta a un mensaje modificable, por ejemplo, Environment, InputLocalEnvironment, OutputLocalEnvironment, OutputRoot u OutputExceptionList.

Si incluye una cláusula FIELD, se navega al campo especificado por el destino (creando los campos si es necesario) y se ejecuta cualquier cláusula values o from existente. Este formato de sentencia CREATE no crea necesariamente ningún campo; sólo asegura que existan los campos dados.

Si se utilizan índices de matriz en la referencia de campo de destino, sólo se puede crear una instancia de un campo determinado. Por consiguiente, si escribe una sentencia SET que empieza por:
 SET OutputRoot.XML.Message.Structure[2].Field = ...  

debe existir al menos una instancia de Estructura en el mensaje. Es decir, los únicos campos del árbol que se crean son los que están en una vía de acceso directa desde la raíz al campo identificado por la referencia de campo.

Si incluye una cláusula PREVIOUSSIBLING, NEXTSIBLING, FIRSTCHILD o LASTCHILD, se navega al campo especificado por el destino (creando los campos si es necesario) exactamente de la misma manera que para la cláusula FIELD. A continuación, se crea un campo nuevo y se une en la posición especificada (por ejemplo, como PREVIOUSSIBLING o FIRSTCHILD). Este formato de sentencia CREATE siempre crea un campo nuevo y lo coloca en la posición especificada.

Si utiliza dos sentencias CREATE FIRSTCHILD OF destino, la segunda sentencia crea un campo nuevo como primer elemento dependiente del destino y desplaza el primer elemento dependiente creado anteriormente a la derecha del árbol de mensajes (de forma que ya no es el primer elemento dependiente). De manera similar, CREATE LASTCHILD OF destino navega al campo de destino y añade un campo nuevo como su elemento dependiente más a la derecha, desplazando el último elemento dependiente anterior a la izquierda.

CREATE PREVIOUSSIBLING OF destino crea un campo inmediatamente a la izquierda del campo especificado por el destino (por lo que no se modifica la profundidad del árbol); de manera similar, CREATE NEXTSIBLING OF destino crea un campo inmediatamente a la derecha del campo especificado por el destino. Al crear PREVIOUSSIBLING o NEXTSIBLING, puede utilizar la palabra clave REPEAT para copiar el tipo y el nombre del nuevo campo desde el campo actual.

Si está presente, la cláusula AS mueve la variable de referencia con nombre para apuntar al campo recién creado. Esto es útil porque probablemente desea involucrar el campo nuevo en un proceso adicional.

Si está presente, la cláusula DOMAIN asocia el campo nuevo con un analizador nuevo del tipo especificado. Esta cláusula espera un nombre de campo de raíz (por ejemplo, XML o MQRFH2). Si la cláusula DOMAIN está presente, pero el valor suministrado es una serie de caracteres de longitud cero, se crea un analizador nuevo del mismo tipo que el analizador es propietario del campo especificado por el destino. Se emite una excepción si el nombre de dominio suministrado no es del tipo de datos CHARACTER o su valor es NULL. No especifique la cláusula DOMAIN con la cláusula FIELD; no es seguro que se cree un campo nuevo.

Utilice la cláusula REPEAT para copiar el tipo y nombre del campo nuevo desde el campo de destino. De forma alternativa, el tipo, nombre y valor del campo nuevo puede ser: En el caso de las cláusulas FROM y PARSE, también puede crear elementos dependientes del nuevo campo.

Para la cláusula VALUES, el tipo, nombre y valor (o cualquier subconjunto de ellos) se pueden especificar mediante cualquier expresión que devuelva un tipo de datos adecuado (INTEGER para el tipo, CHARACTER para el nombre y cualquier tipo escalar para el valor). Se emite una excepción si el valor suministrado para un tipo o nombre es NULL.

La cláusula NAMESPACE acepta cualquier expresión que devuelva un valor no nulo de tipo carácter. El significado depende de la presencia de las cláusulas NAME y NAMESPACE como se indica a continuación:
NAMESPACE NAME Elemento denominado de la manera siguiente
No No El elemento carece de nombre (el distintivo de nombre no se establece automáticamente)
No Se proporciona al elemento el nombre de un espacio de nombres seleccionado de la vía de acceso
No Se proporciona al elemento el nombre vacío en el espacio de nombres dado
Se proporciona al elemento el nombre dado en el espacio de nombres dado

La cláusula IDENTITY toma un único elemento de vía de acceso en lugar de las cláusulas TYPE y NAME y sigue todas las normas descritas en el tema de referencias de campo (consulte el apartado Referencias de campo ESQL).

Para la cláusula FROM, el tipo, nombre y valor del campo nuevo se toman del campo al que apunta SourceFieldReference. Se separa cualquier campo dependiente existente (el campo podría existir ya, en el caso de una cláusula FIELD), y al campo nuevo se le proporcionan copias de elemento dependientes y de niveles inferiores del campo de origen.

Si una cláusula PARSE está presente, se construye un subárbol bajo el campo recién creado desde la corriente de bits suministrada. El algoritmo para realizar esta operación varía de un analizador a otro y según las opciones especificadas. Todos los analizadores dan soporte a la modalidad RootBitStream, en que el algoritmo de creación de árbol es el mismo que el utilizado por un nodo de entrada.

Algunos analizadores también dan soporte a una segunda modalidad, FolderBitStream, que genera un subárbol desde una corriente de bits creada por la función ASBITSTREAM (consulte el apartado Función ASBITSTREAM) utilizando esta modalidad.

Cuando se procesa la sentencia, se evalúan las expresiones de cláusulas PARSE. Se emitirá una excepción si alguna de las expresiones siguientes no da como resultado un valor no nulo del tipo adecuado:

Cláusula Tipo Valor por omisión
Options entero RootBitStream & ValidateNone
Encoding entero 0
Ccsid entero 0
Message set carácter Serie de longitud cero
Message type carácter Serie de longitud cero
Message format carácter Serie de longitud cero

Aunque la cláusula OPTIONS acepta cualquier expresión que devuelva un valor de tipo entero, sólo tiene sentido generar valores de opciones de la lista de constantes suministradas, utilizando la función BITOR si se necesita más de una opción.

Una vez generado, el valor se convierte en un entero y se puede guardar en una variable o pasar como parámetro a una función, así como utilizarlo directamente con una llamada CREATE. La lista de constantes definidas globalmente es: Inicio del cambio
        Opciones de modalidad de analizador...
        FolderBitStream
        RootBitStream

        Validar opciones maestras...
        ValidateValue		  -- Se puede utilizar con ValidateContent
        ValidateContent		-- Se puede utilizar con ValidateValue
        ValidateNone

       Validar opciones de acción ante anomalía...
        ValidateException
        ValidateLocalError
        ValidateUserTrace

        Validar opciones de temporización...
        ValidateComplete
        ValidateImmediate
        ValidateDeferred 

       Validar opciones de limitación de valor...
        ValidateFullConstraints
        ValidateBasicConstraints

        Validar opciones de arreglo...
        ValidateFullFixUp
        ValidateNoFixUp
Fin del cambio

Sólo se puede especificar una opción de cada grupo, a excepción de ValidateValue y ValidateContent, que se pueden utilizar juntas para obtener la validación de contenido y valores. Si no especifica una opción en un grupo, se utilizará la opción que aparece en negrita.

La cláusula ENCODING acepta cualquier expresión que devuelva un valor de tipo entero. No obstante, sólo tiene sentido generar valores de opción de la lista de constantes suministradas:
       MQENC_INTEGER_NORMAL
       MQENC_INTEGER_REVERSED
       MQENC_DECIMAL_NORMAL
       MQENC_DECIMAL_REVERSED
       MQENC_FLOAT_IEEE_NORMAL
       MQENC_FLOAT_IEEE_REVERSED
       MQENC_FLOAT_S390

Los valores utilizados para la cláusula CCSID siguen el sistema de numeración normal. Por ejemplo, 1200 = UCS-2, 1208 = UTF-8.

Para las cláusulas ausentes, se utilizan los valores por omisión proporcionados. Se recomienda que utilice los valores por omisión de CCSID y codificación, porque toman sus valores de los valores de CCSID y codificación del gestor de colas.

De manera similar, es práctico utilizar los valores por omisión para cada opción de conjunto de mensajes, tipo y formato, porque muchos analizadores no necesitan información de conjunto de mensajes, tipo o formato, por lo que cualquier valor válido es suficiente.

Cuando se han evaluado las expresiones, se genera una corriente de bits utilizando los resultados de las expresiones.
Nota: Dado que esta función tiene un gran número de cláusulas, se da soporte a una sintaxis alternativa en que se suministran los parámetros como una lista separada por comas en lugar de cláusulas con nombre. En este caso, las expresiones deben estar en el orden siguiente:
ENCODING -> CCSID -> SET -> TYPE -> FORMAT -> OPTIONS

La lista se puede truncar en cualquier punto y puede utilizar una expresión totalmente vacía para las cláusulas para las que no suministre un valor.

Ejemplos de uso de la sentencia CREATE

El ejemplo siguiente crea el campo especificado:
CREATE FIELD OutputRoot.XML.Data;
El ejemplo siguiente crea un campo sin nombre, tipo ni valor como primer elemento dependiente de ref1:
CREATE FIRSTCHILD OF ref1;
El ejemplo siguiente crea un campo utilizando el tipo, nombre y valor especificados:
CREATE NEXTSIBLING OF ref1 TYPE NameValue NAME 'Price' VALUE 92.3;
El ejemplo siguiente crea un campo con un tipo y nombre, pero sin valor; el campo se añade antes del igual indicado por la referencia dinámica (ref1):
CREATE PREVIOUSSIBLING OF ref1 TYPE Name NAME 'Quantity';
El ejemplo siguiente crea un campo de nombre Component y mueve la variable de referencia targetCursor para apuntar a él:
CREATE FIRSTCHILD OF targetCursor AS targetCursor NAME 'Component';
El ejemplo siguiente crea un campo nuevo como igual derecho del campo al que apunta la variable de referencia targetCursor que tiene el mismo tipo y nombre que ese campo. A continuación, la sentencia muev targetCursor para que apunte al nuevo campo:
CREATE NEXTSIBLING OF targetCursor AS targetCursor REPEAT;

El ejemplo siguiente muestra cómo utilizar la cláusula PARSE:

DECLARE bodyBlob BLOB;

SET bodyBlob = BITSTREAM( InputRoot.XML );
DECLARE creationPtr REFERENCE TO OutputRoot.XML;
CREATE FIRSTCHILD OF creationPtr PARSE(bodyBlob,InputProperties.Encoding,437) ;

Ejemplo de sentencia de creación

Este ejemplo proporciona un ESQL de ejemplo y un mensaje de entrada, que producen el mensaje de salida al final del ejemplo.

ESQL:

/* copy headers */
DECLARE i INTEGER;
DECLARE numHeaders INT;
SET i = 1;
SET numHeaders = CARDINALITY(InputRoot.*[]);
WHILE i < numHeaders DO
    SET OutputRoot.*[i] = InputRoot.*[i]; 
    SET i = i + 1; 
END WHILE;

CREATE FIELD OutputRoot.XML.TestCase.description TYPE NameValue VALUE 'This is my TestCase' ;
CREATE FIRSTCHILD OF OutputRoot.XML.TestCase Domain('XML') NAME 'Identifier' VALUE InputRoot.XML.TestCase.Identifier;
CREATE LASTCHILD OF OutputRoot.XML.TestCase Domain('XML') NAME 'Sport' VALUE InputRoot.XML.TestCase.Sport;
 CREATE LASTCHILD OF OutputRoot.XML.TestCase Domain('XML') NAME 'Date' VALUE InputRoot.XML.TestCase.Date;
 CREATE LASTCHILD OF OutputRoot.XML.TestCase Domain('XML') NAME 'Type' VALUE InputRoot.XML.TestCase.Type;
 CREATE FIELD OutputRoot.XML.TestCase.Division[1].Number TYPE NameValue VALUE 'Premiership';
 CREATE FIELD OutputRoot.XML.TestCase.Division[1].Result[1].Number TYPE NameValue VALUE  '1' ;
 CREATE FIELD OutputRoot.XML.TestCase.Division[1].Result[1].Home TYPE Name;
 CREATE LASTCHILD OF OutputRoot.XML.TestCase.Division[1].Result[1].Home NAME 'Team' VALUE 'Liverpool' ;
 CREATE LASTCHILD OF OutputRoot.XML.TestCase.Division[1].Result[1].Home NAME 'Score' VALUE '4';
 CREATE FIELD OutputRoot.XML.TestCase.Division[1].Result[1].Away TYPE Name;
 CREATE LASTCHILD OF OutputRoot.XML.TestCase.Division[1].Result[1].Away NAME 'Team' VALUE 'Everton';
CREATE LASTCHILD OF OutputRoot.XML.TestCase.Division[1].Result[1].Away NAME 'Score' VALUE '0';
 CREATE FIELD OutputRoot.XML.TestCase.Division[1].Result[2].Number TYPE NameValue VALUE  '2';
 CREATE FIELD OutputRoot.XML.TestCase.Division[1].Result[2].Home TYPE Name;
 CREATE LASTCHILD OF OutputRoot.XML.TestCase.Division[1].Result[2].Home NAME 'Team' VALUE 'Manchester United';
 CREATE LASTCHILD OF OutputRoot.XML.TestCase.Division[1].Result[2].Home NAME 'Score' VALUE '2';
 CREATE FIELD OutputRoot.XML.TestCase.Division[1].Result[2].Away TYPE Name;
 CREATE LASTCHILD OF OutputRoot.XML.TestCase.Division[1].Result[2].Away NAME 'Team' VALUE 'Arsenal';
 CREATE LASTCHILD OF OutputRoot.XML.TestCase.Division[1].Result[2].Away NAME 'Score' VALUE '3';
 CREATE FIELD OutputRoot.XML.TestCase.Division[2].Number TYPE NameValue  VALUE '2';
 CREATE FIELD OutputRoot.XML.TestCase.Division[2].Result[1].Number TYPE NameValue  VALUE  '1';
 CREATE FIELD OutputRoot.XML.TestCase.Division[2].Result[1].Home TYPE Name;
 CREATE LASTCHILD OF OutputRoot.XML.TestCase.Division[2].Result[1].Home NAME 'Team' VALUE 'Port Vale';
 CREATE LASTCHILD OF OutputRoot.XML.TestCase.Division[2].Result[1].Home NAME 'Score' VALUE '9' ;
 CREATE FIELD OutputRoot.XML.TestCase.Division[2].Result[1].Away TYPE Name;
 CREATE LASTCHILD OF OutputRoot.XML.TestCase.Division[2].Result[1].Away NAME 'Team' VALUE 'Brentford';
 CREATE LASTCHILD OF OutputRoot.XML.TestCase.Division[2].Result[1].Away NAME 'Score' VALUE '5';
Input Message:

<TestCase description="This is my TestCase">
  <Identifier>ES03B305_T1</Identifier>
  <Sport>Football</Sport>
  <Date>01/02/2000</Date>
  <Type>LEAGUE</Type>
</TestCase>

Mensaje de salida:

<TestCase description="This is my TestCase">
  <Identifier>ES03B305_T1</Identifier>
  <Sport>Football</Sport>
  <Date>01/02/2000</Date>
  <Type>LEAGUE</Type>
  <Division Number="Premiership">
    <Result Number="1">
      <Home>
        <Team>Liverpool</Team>
        <Score>4</Score>
      </Home>
      <Away>
        <Team>Everton</Team>
        <Score>0</Score>      
      </Away>
    </Result>
    <Result Number="2">
      <Home>
        <Team>Manchester United</Team>
        <Score>2</Score>
      </Home>
      <Away>
        <Team>Arsenal</Team>
        <Score>3</Score>      
      </Away>
    </Result>
  </Division>
  <Division Number="2">
    <Result Number="1">
      <Home>
        <Team>Port Vale</Team>
        <Score>9</Score>
      </Home>
      <Away>
        <Team>Brentford</Team>
        <Score>5</Score>      
      </Away>
    </Result>
    <Result Number="2">
      <Home>
        <Team>Reading</Team>
        <Score>6</Score>
      </Home>
      <Away>
        <Team>Stoke City</Team>
        <Score>7</Score>      
      </Away>
    </Result>
  </Division>
</TestCase>

Conceptos relacionados
ESQL

Tareas relacionadas
Desarrollo de ESQL
Trabajo con mensajes XML y corrientes de bits

Referencia relacionada
Preferencia de sintaxis
Sentencias ESQL
Función ASBITSTREAM