Istruzione CREATE

L'istruzione CREATE crea un nuovo campo di messaggio.

SINTASSI

Note:
  1. Non utilizzare DomainClause e ParseClause con il qualificatore FIELD.
  2. Utilizzare RepeatClause solo con i qualificatori PREVIOUSSIBLING e NEXTSIBLING
  3. Ciascuna clausola secondaria all'interno di ParseClause può ricorrere una volta sola.

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.

Se si utilizzano indici di array nel riferimento di campo di destinazione, è possibile creare solo una istanza di un particolare campo. Per questo motivo, se si scrive un'istruzione SET che inizia con:
 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:

Utilizzare la clausola REPEAT per copiare il nome ed il tipo del nuovo campo dal campo di destinazione. In alternativa, il tipo, il nome ed il valore del nuovo campo possono essere:
  • Copiati da qualsiasi campo esistente (utilizzando la clausola FROM)
  • Specificati in modo esplicito (utilizzando la clausola VALUES)
  • Definiti analizzando un flusso di bit (utilizzando la clausola PARSE)
Nel caso delle clausole FROM e PARSE, è anche possibile creare child del nuovo campo.

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:

La clausola NAMES accetta qualsiasi espressione che restituisca un valore non null di tipo carattere. Il significato dipende dalla presenza delle clausole NAME e NAMESPACE, come riportato di seguito:
NAMESPACE NAME Elemento denominato nel modo seguente
No No L'elemento è senza nome (indicatore name non impostato automaticamente)
No All'elemento viene assegnato il nome nello spazio dei nomi predefinito
No All'elemento viene assegnato il nome vuoto nello spazio dei nomi fornito
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.

Una volta creato, il valore diventa un integer ed è possibile salvarlo in una variabile o passarlo come parametro ad una funzione oppure utilizzarlo direttamente con un'istruzione CREATE. L'elenco delle costanti definite globalmente è:
        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
Note:
  1. L'opzione validateFullFixUp è riservata per un utilizzo futuro. La selezione di validateFullFixUp attribuisce un funzionamento identico a validateNoFixUp.
  2. L'opzione validateFullConstraints è riservata per un utilizzo futuro. La selezione di validateFullConstraints attribuisce un funzionamento identico a validateBasicConstraints.
  3. Per informazioni dettagliate relative alle opzioni di convalida, fare riferimento a Proprietà della convalida per i messaggi nel dominio MRM.
  4. Le opzioni Validate timing options corrispondono alle Parse Timing options e, in particolare, Validate Deferred è chiamato On Demand.

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.

La clausola ENCODING accetta qualsiasi espressione che restituisce un valore di tipo integer. Tuttavia, è valido solo creare valori di opzione dall'elenco delle costanti fornite:
       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.

Quando tutte le espressioni sono state valutate, un flusso di bit viene analizzato utilizzando i risultati delle espressioni.
Nota: Poiché questa funzione dispone di un numero elevato di clausole, è supportata una sintassi alternativa in cui i parametri vengono forniti come un elenco separato da virgole e non per clausole denominate. In questo caso, le espressioni devono essere nell'ordine:
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.

Esempi di utilizzo dell'istruzione CREATE

  1. L'esempio riportato di seguito crea il campo specificato:
    CREATE FIELD OutputRoot.XML.Data;
  2. L'esempio riportato di seguito crea un campo senza nome, tipo o valore come primo child di ref1:
    CREATE FIRSTCHILD OF ref1;
  3. L'esempio riportato di seguito crea un campo utilizzando il tipo, il nome ed il valore specificati:
    CREATE NEXTSIBLING OF ref1 TYPE NameValue NAME 'Price' VALUE 92.3;
  4. L'esempio riportato di seguito crea un campo con un tipo ed un nome, ma senza valore; il campo viene aggiunto prima del sibling indicato dal riferimento dinamico (ref1):
    CREATE PREVIOUSSIBLING OF ref1 TYPE Name NAME 'Quantity';
  5. L'esempio riportato di seguito crea un campo denominato Component e sposta la variabile di riferimento targetCursor in modo che punti ad esso:
    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;
  6. L'esempio riportato di seguito illustra come utilizzare la clausola 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);

    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);
  7. L'esempio riportato di seguito mostra come utilizzare l'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 '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>
  8. L'esempio riportato di seguito mostra come è possibile utilizzare la clausola DOMAIN per evitare la perdita di informazioni univoche del programma di analisi XML quando si verifica una copia diversa del programma di analisi:
    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);

Esempio di istruzione CREATE

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;
Concetti correlati
Panoramica di ESQL
Attività correlate
Sviluppo di ESQL
Gestione dei messaggi XML e dei flussi di bit
Riferimenti correlati
Diagrammi di sintassi: tipi disponibili
Istruzioni ESQL
Funzione ASBITSTREAM
Informazioni particolari | Marchi | Download | Libreria | Supporto | Commenti
Copyright IBM Corporation 1999, 2006 Ultimo aggiornamento: ago 17, 2006
ak04950_