L'istruzione CREATE crea un nuovo campo di messaggio.
Il nuovo campo di messaggi è posizionato in un'ubicazione fornita (CREATE FIELD) oppure in relazione a un'ubicazione esistente (CREATE ... OF...). I nuovi campo possono essere creati solo quando il riferimento di campo di destinazione punta ad un messaggio modificabile, ad esempio Environment, InputLocalEnvironment, OutputLocalEnvironment, OutputRoot o OutputExceptionList.
Se si include una clausola FIELD, si passa al campo specificato dalla destinazione (creando i campi, se necessario) e viene eseguita la clausola values o from. Questo formato dell'istruzione CREATE non crea necessariamente i campi, ma assicura solo che i campi forniti esistano.
SET OutputRoot.XML.Message.Structure[2].Field = ...
almeno una istanza di Structure deve già esistere nel messaggio. Quindi, gli unici campi nella struttura ad albero che vengono creati sono quelli su un percorso diretto dalla root al campo identificato dal riferimento di campo.
Se si include una clausola PREVIOUSSIBLING, NEXTSIBLING, FIRSTCHILD o LASTCHILD, si passa al campo specificato dalla destinazione (creando i campi, se necessario) esattamente nello stesso modo utilizzato per la clausola FIELD. Un nuovo campo viene creato e collegato nella posizione specificata (ad esempio, come PREVIOUSSIBLING o FIRSTCHILD). Questo formato dell'istruzione CREATE crea sempre un nuovo campo e lo posiziona nella posizione specificata.
Se si utilizzano due istruzioni di destinazione CREATE FIRSTCHILD OF che specificano la stessa destinazione, la seconda istruzione crea un nuovo campo come primo child della destinazione e sposta il primo child precedentemente creato alla destra nella struttura ad albero del messaggio (quindi, esso non è più il primo child). Allo stesso modo, la destinazione CREATE LASTCHILD OF passa al campo di destinazione ed aggiunge un nuovo campo come relativo child all'estrema destra, spostando a sinistra l'ultimo child precedente.
La destinazione CREATE PREVIOUSSIBLING OF crea un campo all'immediata sinistra del campo specificato dalla destinazione (la profondità della struttura ad albero non viene modificata); allo stesso modo, la destinazione CREATE NEXTSIBLING OF crea un campo all'immediata destra del campo specificato dalla destinazione. Quando si crea PREVIOUSSIBLING o NEXTSIBLING, è possibile utilizzare la parola chiave REPEAT per copiare il tipo ed il nome del nuovo campo dal campo corrente.
Clausola AS:
Se presente, la clausola AS sposta la variabile di riferimento denominata in modo da puntare al campo appena creato. Ciò è utile perché probabilmente si desidera coinvolgere il nuovo campo in elaborazioni successive.
Clausola DOMAIN:
Se presente, la clausola DOMAIN associa il nuovo campo ad un nuovo programma di analisi del tipo specificato. Tale clausola prevede un nome di campo root (ad esempio, XML o MQRFH2). Se la clausola DOMAIN è presente, ma il valore fornito è una stringa di caratteri di lunghezza zero, viene creato un nuovo programma di analisi dello stesso tipo del programma di analisi proprietario del campo specificato dalla destinazione. Viene generata un'eccezione se il nome del dominio fornito non è un tipo di dati CHARACTER oppure se il relativo valore è NULL. Non specificare la clausola DOMAIN con la clausola FIELD; non è sicuro che venga creato un nuovo campo.
Clausola REPEAT:
Clausola VALUES:
Per la clausola VALUES, il tipo, il nome ed il valore (o qualsiasi relativo insieme secondario) possono essere specificati da qualsiasi espressione che restituisce un tipo di dati adatto (INTEGER per il tipo, CHARACTER per il nome e qualsiasi tipo scalare per il valore). Viene generata un'eccezione se il valore fornito per un tipo o per un nome è NULL.
Clausola NAMES:
NAMESPACE | NAME | Elemento denominato nel modo seguente |
---|---|---|
No | No | L'elemento è senza nome (indicatore name non impostato automaticamente) |
No | Sì | All'elemento viene assegnato il nome nello spazio dei nomi predefinito |
Sì | No | All'elemento viene assegnato il nome vuoto nello spazio dei nomi fornito |
Sì | Sì | All'elemento viene assegnato il nome fornito nello spazio dei nomi fornito |
L'operando IDENTITY accetta un elemento del percorso singolo al posto delle clausole TYPE e NAME, laddove un elemento del percorso contenga (al massimo) un tipo, uno spazio dei nomi, un nome e un indice. In questo modo vengono specificati il tipo, lo spazio dei nomi, il nome e l'indice dell'elemento da creare e vengono seguite tutte le regole descritte nella sezione per i riferimenti di campo (consultare Riferimenti di campo ESQL). Ad esempio:
IDENTITY (XML.attribute)Space1:Name1[42]
Consultare la sezione Esempi in basso per le modalità di utilizzo dell'operando IDENTITY.
Clausola FROM:
Per la clausola FROM, il tipo, il nome ed il valore del nuovo campo vengono presi dal campo puntato da SourceFieldReference. Tutti i campi child esistenti della destinazione vengono scollegati (il campo potrebbe già esistere nel caso di una clausola FIELD) ed al nuovo campo vengono assegnate copie dei child, dei child secondari e così via del campo origine.
Clausola PARSE:
Se è presente una clausola PARSE, viene creata una struttura ad albero secondaria al di sotto del campo appena creato dal flusso di bit fornito. L'algoritmo per questa operazione varia in base al programma di analisi ed alle opzioni specificate. Tutti i programmi di analisi supportano la modalità RootBitStream, in cui l'algoritmo di creazione della struttura ad albero è uguale a quello utilizzato da un nodo di input.
Alcuni programmi di analisi supportano anche una seconda modalità, FolderBitStream, che genera una struttura ad albero secondaria da un flusso di bit creato dalla funzione ASBITSTREAM (consultare Funzione ASBITSTREAM) che utilizza tale modalità.
Quando l'istruzione viene elaborata, vengono valutate tutte le espressioni della clausola PARSE. Viene generata un'eccezione se una delle seguenti espressioni non risulta in un valore non null del tipo appropriato:
Clausola | Tipo | Valore predefinito |
---|---|---|
Opzioni | integer | RootBitStream & ValidateNone |
Codifica | integer | 0 |
Ccsid | integer | 0 |
Serie di messaggi | character | Stringa di lunghezza zero |
Tipo di messaggio | character | Stringa di lunghezza zero |
Formato del messaggio | character | Stringa di lunghezza zero |
Sebbene la clausola OPTIONS accetti qualsiasi espressione che restituisce un valore di tipo integer, è utile creare valori dell'opzione dall'elenco delle costanti fornite, utilizzando la funzione BITOR, solo se è richiesta più di un'opzione.
Validate master options... ValidateContentAndValue ValidateValue -- Can be used with ValidateContent ValidateContent -- Can be used with ValidateValue ValidateNone Validate failure action options... ValidateException ValidateExceptionList ValidateLocalError ValidateUserTrace Validate value constraints options... ValidateFullConstraints ValidateBasicConstraints Validate fix up options... ValidateFullFixUp ValidateNoFixUp Parse timing options... ParseComplete ParseImmediate ParseOnDemand
E' possibile specificare solo una opzione da ciascun gruppo, con l'eccezione di ValidateValue e ValidateContent, che possono essere utilizzate insieme per ottenere il contenuto e la convalida del valore. Se non si specifica un'opzione all'interno di un gruppo, viene utilizzata l'opzione in grassetto.
MQENC_INTEGER_NORMAL MQENC_INTEGER_REVERSED MQENC_DECIMAL_NORMAL MQENC_DECIMAL_REVERSED MQENC_FLOAT_IEEE_NORMAL MQENC_FLOAT_IEEE_REVERSED MQENC_FLOAT_S390
I valori utilizzati per la clausola CCSID seguono il normale sistema di numerazione. Ad esempio, 1200 = UCS-2, 1208 = UTF-8.
Per le clausole assenti, vengono utilizzati i valori predefiniti forniti. Utilizzare i valori predefiniti di codifica e CCSID perché essi utilizzano i valori delle impostazioni CCSID e di codifica del gestore code.
Allo stesso modo, è utile utilizzare i valori predefiniti per ciascuna delle opzioni relative al formato, al tipo ed alla serie di messaggi, perché molti programmi di analisi non richiedono le informazioni relative al formato, al tipo ed alla serie di messaggi, per cui è sufficiente qualsiasi valore valido.
ENCODING -> CCSID -> SET -> TYPE -> FORMAT -> OPTIONS
L'elenco può essere troncato in qualsiasi punto ed è possibile utilizzare un'espressione completamente vuota per le clausole in cui non viene fornito un valore.
CREATE FIELD OutputRoot.XML.Data;
CREATE FIRSTCHILD OF ref1;
CREATE NEXTSIBLING OF ref1 TYPE NameValue NAME 'Price' VALUE 92.3;
CREATE PREVIOUSSIBLING OF ref1 TYPE Name NAME 'Quantity';
CREATE FIRSTCHILD OF targetCursor AS targetCursor NAME 'Component';L'esempio riportato di seguito crea un nuovo campo come sibling di destra del campo puntato dalla variabile di riferimento targetCursor con lo stesso tipo e nome di quel campo. L'istruzione quindi sposta targetCursor in modo da puntare al nuovo campo:
CREATE NEXTSIBLING OF targetCursor AS targetCursor REPEAT;
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);
Questo esempio può essere esteso in modo da visualizzare la serializzazione e l'analisi di un campo o di una cartella:
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);
CREATE FIELD OutputRoot.XMLNS.TestCase.Root IDENTITY (XML.ParserRoot)Root; CREATE FIELD OutputRoot.XMLNS.TestCase.Root.Attribute IDENTITY (XML.Attribute)NSpace1:Attribute VALUE 'Attrib Value'; CREATE LASTCHILD OF OutputRoot.XMLNS.TestCase.Root IDENTITY (XML.Element)NSpace1:Element1[1] VALUE 'Element 1 Value'; CREATE LASTCHILD OF OutputRoot.XMLNS.TestCase.Root IDENTITY (XML.Element)NSpace1:Element1[2] VALUE 'Element 2 Value';
Questa sequenza di istruzioni produce il seguente messaggio di output:
<TestCase> <Root xmlns:NS1="NSpace1" NS1:Attribute="Attrib Value"> <NS1:Element1>Element 1 Value</NS1:Element1> <NS1:Element1>Element 2 Value</NS1:Element1> </Root> </TestCase>
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);
Questo esempio fornisce un codice ESQL di esempio ed un messaggio di input che generano il messaggio di output alla fine dell'esempio.
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;