Sentencia CREATE

La sentencia CREATE crea un nuevo campo de mensaje.

SINTAXIS

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

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

Si incluye una cláusula FIELD, se recorre el campo especificado por el destino (creando los campos, si es necesario) y se ejecutan las cláusulas value o la cláusula from existentes. Esta forma de sentencia CREATE no crea necesariamente ningún campo, simplemente se asegura de que los campos concretos existan.

Si utiliza índices de matriz en la referencia del campo de destino, solamente se puede crear una instancia de un campo determinado. De este modo, si escribe una sentencia SET que comience por:
 SET OutputRoot.XML.Message.Structure[2].Field = ...  

al menos debe haber una instancia de Structure en el mensaje. Esto es, los únicos campos del árbol que se crearán son los que están en una vía de acceso directa desde la raíz al campo identificado mediante la referencia de campo.

Si incluye una cláusula PREVIOUSSIBLING, NEXTSIBLING, FIRSTCHILD o LASTCHILD, se recorre el campo especificado por el destino (creando los campos, si es necesario) exactamente del mismo modo que para la cláusula FIELD. A continuación, se crea un campo nuevo y se asocia a la posición especificada (por ejemplo, como en PREVIOUSSIBLING o FIRSTCHILD). Esta forma de sentencia CREATE siempre crea un campo nuevo y lo coloca en la posición especificada.

Si utiliza dos sentencias CREATE FIRSTCHILD OF de destino que especifican el mismo destino, la segunda sentencia crea un campo nuevo como el primer hijo del destino y desplaza el primer hijo creado anteriormente a la derecha del árbol de mensaje (por lo tanto, ya no es el primer hijo). Del mismo modo, la sentencia CREATE LASTCHILD OF de destino va hasta el campo de destino y añade un campo nuevo como su hijo en la posición más a la derecha, desplazando el último hijo anterior a la izquierda.

La sentencia CREATE PREVIOUSSIBLING OF de destino crea un campo en la posición izquierda más inmediata del campo especificado por el destino (por lo tanto, el árbol no se modifica). Del mismo modo, la sentencia CREATE NEXTSIBLING OF de destino crea un campo en la posición derecha más inmediata al campo especificado por el destino. Cuando cree PREVIOUSSIBLING o NEXTSIBLING, puede utilizar la palabra clave REPEAT para copiar el tipo y el nombre del campo nuevo del campo actual.

Cláusula AS:

Si está presente, la cláusula AS desplaza la variable de referencia nombrada de modo que apunte al campo recién creado. Esto resulta útil porque probablemente desee que el campo nuevo participe en algún proceso adicional.

Cláusula DOMAIN:

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 raíz (por ejemplo, XML o MQRFH2). Si está presente la cláusula DOMAIN, pero el valor proporcionado es una serie de caracteres de longitud cero, se crea un nuevo analizador del mismo tipo que el analizador propietario del campo especificado por el destino. Se genera una excepción si el nombre de dominio suministrado no tiene el tipo de datos de CHARACTER o si su valor es NULL. No especifique la cláusula DOMAIN con la cláusula FIELD. No es seguro que se crea un campo nuevo.

Cláusula REPEAT:

Utilice la cláusula REPEAT para copiar el nuevo tipo del campo y el nombre del campo de destino. De forma alternativa, el tipo, nombre y valor del campo nuevo se pueden:
  • Copiar de un campo existente (utilizando la cláusula FROM)
  • Especificar de forma explícita (utilizando la cláusula VALUES)
  • Definir analizando una corriente de bits (utilizando la cláusula PARSE)
En el caso de las cláusulas FROM y PARSE, también puede crear niños del campo nuevo.

Cláusula VALUES:

En la cláusula VALUES, el tipo, nombre y valor (o cualquier subconjunto de los mismos) 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 genera una excepción si el valor proporcionado para un tipo o nombre es NULL.

Cláusula NAMES:

La cláusula NAMES toma cualquier expresión que devuelve 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 con nombre como se indica a continuación
No No El elemento no tiene nombre (no se establece automáticamente el indicador name)
No Al elemento se le asigna el nombre del espacio de nombres por omisión
No Al elemento se le asigna el nombre vacío del espacio de nombres dado
Al elemento se le asigna el nombre proporcionado del espacio de nombres dado

El operando IDENTITY toma un solo elemento de vía de acceso en lugar de las cláusulas TYPE y NAME, en las que un elemento de vía de acceso contiene (como máximo) un tipo, un espacio de nombres, un nombre y un índice. Éstos especifican el tipo, el espacio de nombres, el nombre y el índice del elemento a crear y siguen todas las normas descritas en el tema para referencias de campo (consulte Referencias de campo ESQL). Por ejemplo:

IDENTITY (XML.attribute)Space1:Name1[42]

Consulte la sección Ejemplos más abajo para ver cómo se utiliza el operando IDENTITY.

Cláusula FROM:

Para la cláusula FROM, el tipo, nombre y valor del campo nuevo se toman del campo al que apunta ReferenciaCampoOrigen. Los campos hijo del destino existentes se separan (el campo puede existir ya en el caso de una cláusula FIELD) y al nuevo campo se le proporcionan copias de los elementos hijo, nieto, etc. del campo de origen.

Cláusula PARSE:

Si existe una cláusula PARSE, se crea un subárbol bajo el campo recién creado a partir de la corriente de bits suministrada. El algoritmo para llevarlo a cabo varía según el analizador y en función de las opciones especificadas. Todos los analizadores dan soporte a la modalidad RootBitStream, en la que el algoritmo de creación de árbol es el mismo que utiliza un nodo de entrada.

Algunos analizadores soportan además una segunda modalidad, FolderBitStream, que genera un subárbol a partir de una corriente de bits creada por la función ASBITSTREAM (consulte la Función ASBITSTREAM) utilizando esa modalidad.

Cuando se procesa la sentencia, se evalúa cualquier expresión de la cláusula PARSE. Se genera una excepción si cualquiera de las expresiones siguientes no dan como resultado un valor no nulo del tipo adecuado:

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

Aunque la cláusula OPTIONS acepta cualquier expresión que devuelve un valor de tipo entero, solo tiene sentido generar valores de opciones a partir 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 puede guardarlo en una variable o pasarlo como un parámetro a una función, al igual que utilizarlo directamente con una sentencia CREATE. La lista de constantes definidas globalmente es:
        Opciones de validación maestras...
        ValidateContentAndValue
        ValidateValue		-- Se puede utilizar con ValidateContent
        ValidateContent		-- Se puede utilizar con ValidateValue
        ValidateNone

       Opciones de validación de acciones de error...
        ValidateException
        ValidateExceptionList
        ValidateLocalError
        ValidateUserTrace

       Opciones de validación de limitaciones de valores...
        ValidateFullConstraints
        ValidateBasicConstraints

       Opciones de validación de arreglos...
        ValidateFullFixUp
       ValidateNoFixUp

       sequence contents ..
        ParseComplete
        ParseImmediate
       ParseOnDemand
Notas:
  1. La opción validateFullFixUp se ha reservado para uso futuro. Al seleccionar validateFullFixUp, el comportamiento será el mismo que con validateNoFixUp.
  2. La opción validateFullConstraints se ha reservado para uso futuro. Al seleccionar validateFullConstraints, el comportamiento será el mismo que con validateBasicConstraints.
  3. Para obtener detalles completos sobre las opciones de validación, consulte Propiedades de validación para mensajes del dominio MRM.
  4. Las Opciones de validación de temporización se corresponden con las Opciones de temporización del análisis y, concretamente, se llama a la Validación diferida A petición.

Puede especificar solamente una opción de cada grupo, con la excepción ValidateValue y ValidateContent, que se pueden utilizar conjuntamente para obtener la validación de contenido y valor. Si no especifica una opción en un grupo, se utiliza la opción que está en negrita.

La cláusula ENCODING acepta cualquier expresión que devuelve un valor de tipo entero. No obstante, solo tiene sentido generar valores de opciones de la lista de constantes proporcionada:
       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.

Si faltan cláusulas, se utilizan los valores predeterminados dados. Utilice los valores por omisión de codificación y CCSID debido a que toman sus valores de los valores de codificación del gestor de colas y de CCSID.

Del mismo modo, resulta práctico utilizar los valores por omisión para cada una de las opciones de tipo y formato y conjunto de mensajes porque muchos analizadores no necesitan información acerca del tipo, formato o del conjunto de mensajes, por lo que cualquier valor es suficiente.

Cuando se evalúan las expresiones, se analiza una corriente de bits utilizando los resultados de las expresiones.
Nota: Debido a que esta función tiene un gran número de cláusulas, se da soporte a una sintaxis alternativa en la que los parámetros se proporcionan en una lista separados por comas en lugar de mediante cláusulas con nombres. En este caso, las expresiones deben tener este orden:
ENCODING -> CCSID -> SET -> TYPE -> FORMAT -> OPTIONS

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

Ejemplos de utilización de la sentencia CREATE

  1. El ejemplo siguiente crea el campo especificado:
    CREATE FIELD OutputRoot.XML.Data;
  2. El ejemplo siguiente crea un campo sin nombre, tipo o valor como el primer hijo de ref1:
    CREATE FIRSTCHILD OF ref1;
  3. El ejemplo siguiente crea un campo utilizando el tipo, nombre y valor especificados:
    CREATE NEXTSIBLING OF ref1 TYPE NameValue NAME 'Price' VALUE 92.3;
  4. El ejemplo siguiente crea un campo con un tipo y un nombre, pero sin valor. El campo se añade antes del elemento hermano indicado mediante la referencia dinámica (ref1):
    CREATE PREVIOUSSIBLING OF ref1 TYPE Name NAME 'Quantity';
  5. El ejemplo siguiente crea un campo denominado Component y mueve la variable de referencia targetCursor de modo que apunte al mismo:
    CREATE FIRSTCHILD OF targetCursor AS targetCursor NAME 'Component';
    El ejemplo siguiente crea un nuevo campo como hermano de la derecha del campo al que apunta la variable de referencia targetCursor que tiene el mismo tipo y nombre que este campo. A continuación, la sentencia mueve targetCursor para que apunte al nuevo campo:
    CREATE NEXTSIBLING OF targetCursor AS targetCursor REPEAT;
  6. El ejemplo siguiente muestra cómo utilizar la cláusula PARSE:
    DECLARE bodyBlob BLOB ASBITSTREAM(InputRoot.XML, InputProperties.Encoding,
     InputProperties.CodedCharSetId);
    DECLARE creationPtr REFERENCE TO OutputRoot;
    CREATE LASTCHILD OF creationPtr DOMAIN('XML') PARSE(bodyBlob, InputProperties.Encoding,
     InputProperties.CodedCharSetId);

    Este ejemplo puede ampliarse para mostrar la serialización y el análisis de un campo o una carpeta:

    DECLARE bodyBlob BLOB ASBITSTREAM(InputRoot.XML.TestCase.myFolder, InputProperties.Encoding,
    InputProperties.CodedCharSetId,",",",FolderBitStream);
    DECLARE creationPtr REFERENCE TO OutputRoot;
    CREATE LASTCHILD OF creationPtr DOMAIN('XML') PARSE(bodyBlob, InputProperties.Encoding,
    InputProperties.CodedCharSetId,",",",FolderBitStream);
  7. El ejemplo siguiente muestra cómo utilizar el operando IDENTITY:
    CREATE FIELD OutputRoot.XMLNS.TestCase.Root IDENTITY (XML.ParserRoot)Root;
    CREATE FIELD OutputRoot.XMLNS.TestCase.Root.Attribute 
           IDENTITY (XML.Attribute)NSpace1:Attribute VALUE 'Valor atrib';
    CREATE LASTCHILD OF OutputRoot.XMLNS.TestCase.Root 
           IDENTITY (XML.Element)NSpace1:Element1[1] VALUE 'Valor elemento 1';
    CREATE LASTCHILD OF OutputRoot.XMLNS.TestCase.Root 
           IDENTITY (XML.Element)NSpace1:Element1[2] VALUE 'Valor elemento 2';

    Esta secuencia de sentencias genera el siguiente mensaje de salida:

    <TestCase>
     <Root xmlns:NS1="NSpace1" NS1:Attribute="Attrib Value">
      <NS1:Element1>Valor elemento 1</NS1:Element1>
      <NS1:Element1>Valor elemento 2</NS1:Element1>
     </Root>
    </TestCase>
  8. El ejemplo siguiente le muestra cómo puede utilizar la cláusula DOMAIN para evitar la perdida de información exclusiva del analizador XML cuando se produce una copia de analizador distinta:
    DECLARE bodyBlob BLOB ASBITSTREAM(InputRoot.XML, InputProperties.Encoding,
    InputProperties.CodedCharSetId);
    CREATE FIELD Environment.Variables.myXMLTree;
    DECLARE creationPtr REFERENCE TO Environment.Variables.myXMLTree;
    CREATE FIRSTCHILD OF creationPtr DOMAIN('XML') PARSE(bodyBlob, InputProperties.Encoding, 
    InputProperties.CodedCharSetId);

Ejemplo de sentencia CREATE

En este ejemplo se proporciona ESQL de ejemplo y un mensaje de entrada que genera el mensaje de salida al final del ejemplo.

CREATE COMPUTE MODULE CreateStatement_Compute
CREATE FUNCTION Main() RETURNS BOOLEAN
	BEGIN
CALL CopyMessageHeaders();

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

	END;

CREATE PROCEDURE CopyMessageHeaders() BEGIN
DECLARE I      INTEGER 1;
DECLARE J      INTEGER CARDINALITY(InputRoot.*[]);
WHILE I < J DO
SET OutputRoot.*[I] = InputRoot.*[I];
SET I = I + 1;
END WHILE;
	END;

END MODULE;
Conceptos relacionados
Visión general de ESQL
Tareas relacionadas
Desarrollo de ESQL
Trabajar con mensajes y corrientes de bits XML
Referencia relacionada
Diagramas de sintaxis: tipos disponibles
Sentencias ESQL
Función ASBITSTREAM
Avisos | Marcas registradas | Descargas | Biblioteca | Soporte | Su opinión
Copyright IBM Corporation 1999, 2006 Última actualización: 22/08/2006
ak04950_