Istruzione XML PARSE

I due programmi di analisi XML ad alta velocità sono:

• Il parser dei servizi di sistema XML z/OS® , per funzioni di analisi avanzate. Questo parser viene selezionato dall'opzione del compilatore XMLPARSE (XMLSS).
• Il parser XML fornito nel runtime COBOL, per la compatibilità con Enterprise COBOL for z/OS Versione 3. Il parser compatibile viene selezionato dall'opzione del compilatore XMLPARSE (COMPAT).

L'istruzione XML PARSE analizza un documento XML nelle singole parti e trasmette ciascuna parte, una alla volta, a una procedura di elaborazione scritta dall'utente.

Formato

identifier-1

identifier-1 deve essere un elemento di dati elementari della categoria nazionale, un gruppo nazionale, un elemento di dati elementari della categoria alfanumerico o un elemento di gruppo alfanumerico. identifier-1 non può essere un identificativo di funzione. identifier-1 contiene il flusso di caratteri del documento XML.

Se identifier-1 è un elemento del gruppo nazionale, identifier-1 viene elaborato come elemento di dati elementari di categoria nazionale.

Se identifier-1 è di categoria nazionale, il suo contenuto deve essere codificato utilizzando Unicode UTF-16BE (CCSID 1200). Se l'opzione del compilatore XMLPARSE (COMPAT) è attiva, identifier-1 non deve contenere entità di caratteri rappresentate utilizzando più unità di codifica. Utilizzare un riferimento di caratteri per rappresentare tali caratteri, ad esempio:

• "񧘃" o
• "𐠓"

La lettera x deve essere minuscola.

l'identifier-1 non deve essere un elemento di gruppo di lunghezza dinamica o un elemento elementare di lunghezza dinamica.

Se identifier-1 è di categoria alfanumerica, il suo contenuto deve essere codificato utilizzando una delle serie di caratteri elencate in Serie di caratteri codificati per i documenti XML in Enterprise COBOL Programming Guide. Se l'opzione del compilatore XMLPARSE (COMPAT) è attiva e identifier-1 è alfanumerico e contiene un documento XML che non specifica una dichiarazione di codifica, il documento XML viene analizzato con la codepage specificata dall'opzione del compilatore CODEPAGE.

Se l'opzione del compilatore XMLPARSE (XMLSS) è attiva, il documento XML viene analizzato con la codepage specificata nella frase ENCODING; se la frase ENCODING non viene utilizzata, il documento viene analizzato con la codepage specificata dall'opzione del compilatore CODEPAGE. Qualsiasi dichiarazione di codifica nel documento XML viene ignorata.

Frase RETURNING NATIONAL

La frase RETURNING NATIONAL può essere specificata solo quando è attiva l'opzione del compilatore XMLPARSE (XMLSS).

Quando identifier-1 fa riferimento a un elemento di dati di categoria alfanumerica e viene specificata la frase RETURNING NATIONAL, i frammenti di documento XML vengono convertiti automaticamente in rappresentazione Unicode UTF-16 e restituiti alla procedura di elaborazione nei registri speciali nazionali XML - NTEXT, XML - NNAMESPACE e XML - NNAMESPACE - PREFIX.

Quando la frase RETURNING NATIONAL non viene specificata e identifier-1 fa riferimento a un elemento dati di categoria alfanumerico, i frammenti di documento XML vengono restituiti alla procedura di elaborazione nei registri speciali alfanumerici XML - TEXT, XML - NAMESPACE e XML - NAMESPACE - PREFIX tranne che quando XMLPARSE (COMPAT) è attivo, il testo per gli eventi ATTRIBUTE - NATIONAL - CHARACTER e CONTENT - NATIONAL - CHARACTER XML viene sempre restituito nel registro speciale XML - NTEXT.

Quando identifier-1 fa riferimento ad un elemento dati nazionale, i frammenti di documenti XML vengono sempre restituiti in rappresentazione Unicode UTF-16 nei registri speciali nazionali XML - NTEXT, XML - NNAMESPACE e XML - NNAMESPACE - PREFIX.

Frase VALIDATING

La frase VALIDATING specifica che il parser deve convalidare il documento XML rispetto ad uno schema XML durante l'analisi. In Enterprise COBOL, lo schema utilizzato per la convalida XML è in un formato preelaborato noto come Optimized Schema Representation o OSR. La frase VALIDATING può essere specificata solo quando è attiva l'opzione del compilatore XMLPARSE (XMLSS).

Consultare Parsing XML documents with validation in Enterprise COBOL Programming Guide per dettagli.

l'identifier-2 non deve essere un elemento di gruppo di lunghezza dinamica o un elemento elementare di lunghezza dinamica.

Se la parola chiave FILE non viene specificata, identifier-2 deve fare riferimento a un elemento dati che contiene lo schema XML ottimizzato. identifier-2 deve essere di categoria alfanumerica e non può essere un identificativo di funzione.

Se viene specificata la parola chiave FILE, xml-schema-name-1 identifica un file UNIX z/OS esistente o un set di dati MVS che contiene lo schema XML ottimizzato. xml-schema-name-1 deve essere associato al nome del file esterno dello schema utilizzando la clausola XML - SCHEMA. Per ulteriori informazioni sulla clausola XML-SCHEMA, vedere il paragrafo NOMI SPECIALI.

Limitazione: la convalida XML che utilizza la parola chiave FILE non è supportata in CICS®.

Durante l'analisi con convalida, vengono restituiti normali eventi XML come per l'analisi non convalidata fino a quando non si verifica un'eccezione dovuta a un errore di convalida o ad un altro errore nel documento.

Quando un documento XML non è valido, il programma di analisi segnala un'eccezione XML e passa il controllo alla procedura di elaborazione con il registro speciale XML - EVENT contenente 'EXCEPTION' e il codice XML - CODE del registro speciale contenente il codice di ritorno 24 nella halfword di ordine superiore e un codice di errore nella halfword di ordine inferiore.

Per informazioni sul codice di ritorno e sul codice motivo per le eccezioni che potrebbero verificarsi durante l'analisi dei documenti XML con convalida, consultare XML PARSE exceptions con XMLPARSE (XMLSS) in vigore in Enterprise COBOL Programming Guide.

Frase ENCODING

La frase ENCODING può essere specificata solo quando è attiva l'opzione del compilatore XMLPARSE (XMLSS).

La frase ENCODING specifica una codifica utilizzata per il documento XML di origine in identifier-1. codepage deve essere un elemento dati intero senza segno o un valore letterale intero senza segno che rappresenta un CCSID (coded character set identifier) valido. La specifica della frase ENCODING sostituisce la codifica specificata dall'opzione del compilatore CODEPAGE. La codifica specificata in qualsiasi dichiarazione XML viene sempre ignorata.

Se identifier-1 fa riferimento a un elemento dati di categoria nazionale, codepage deve specificare CCSID 1200, per Unicode UTF-16.

Se identifier-1 fa riferimento a un elemento dati di categoria alfanumerica, la codepage deve specificare CCSID 1208 per UTF-8 o un CCSID per una codepage EBCDIC o ASCII supportata. Consultare Coded character sets for XML documents in Enterprise COBOL Programming Guide per i dettagli.

Frase PROCESSING PROCEDURE

Specifica il nome di una procedura per gestire i diversi eventi generati dal programma di analisi XML.

procedure-name-1, procedure-name-2

Deve denominare una sezione o un paragrafo nella PROCEDURE DIVISION. Quando vengono specificati procedure-name-1 e procedure-name-2 , se uno dei due è un nome procedura in una procedura dichiarativa, entrambi devono essere nomi procedura nella stessa procedura dichiarativa.

procedure-name-1

Specifica la prima (o unica) sezione o paragrafo nella procedura di elaborazione.

procedure-name-2

Specifica l'ultima sezione o paragrafo nella procedura di elaborazione.

Per ogni evento XML, il programma di analisi trasferisce il controllo alla prima istruzione della procedura denominata procedure-name-1. Il controllo viene sempre restituito dalla procedura di elaborazione al parser XML. Il punto da cui viene restituito il controllo è determinato come segue:

• Se procedure-name-1 è un nome paragrafo e procedure-name-2 non viene specificato, la restituzione viene effettuata dopo l'esecuzione dell'ultima istruzione del paragrafo procedure-name-1 .
• Se procedure-name-1 è un nome sezione e procedure-name-2 non è specificato, la restituzione viene eseguita dopo l'esecuzione dell'ultima istruzione dell'ultimo paragrafo nella sezione procedure-name-1 .
• Se viene specificato procedure-name-2 ed è un nome paragrafo, la restituzione viene effettuata dopo l'esecuzione dell'ultima istruzione del paragrafo procedure-name-2 .
• Se viene specificato procedure-name-2 ed è un nome sezione, la restituzione viene eseguita dopo l'esecuzione dell'ultima istruzione dell'ultimo paragrafo nella sezione procedure-name-2 .

L'unica relazione necessaria tra il procedure-name-1 e il procedure-name-2 è che definiscono una sequenza consecutiva di operazioni da eseguire, a cominciare dalla procedura denominata da procedure-name-1 e terminando con l'esecuzione della procedura denominata da procedure-name-2.

Se esistono due o più percorsi logici al punto di ritorno, procedure-name-2 può denominare un paragrafo che consiste solo in un'istruzione EXIT; tutti i percorsi al punto di ritorno devono quindi portare a questo paragrafo.

La procedura di elaborazione consiste in tutte le istruzioni in cui vengono gestiti gli eventi XML. L'intervallo della procedura di elaborazione include tutte le istruzioni eseguite da CALL, EXIT, GO TO, GOBACK, INVOKE, MERGE, PERFORM e SORT che sono nell'intervallo della procedura di elaborazione, nonché tutte le istruzioni nelle procedure dichiarative eseguite come risultato dell'esecuzione delle istruzioni nell'intervallo della procedura di elaborazione.

L'intervallo della procedura di elaborazione non deve causare l'esecuzione di alcuna istruzione GOBACK o EXIT PROGRAM, tranne che per restituire il controllo da un metodo o programma a cui il controllo è stato passato da un'istruzione INVOKE o CALL, rispettivamente, eseguita nell'intervallo della procedura di elaborazione.

L'intervallo della procedura di elaborazione non deve causare l'esecuzione di un'istruzione XML PARSE, a meno che l'istruzione XML PARSE non venga eseguita in un metodo o programma più esterno a cui è stato passato il controllo da un'istruzione INVOKE o CALL eseguita nell'intervallo della procedura di elaborazione.

Un programma in esecuzione su più thread può eseguire la stessa istruzione XML o diverse istruzioni XML contemporaneamente.

La procedura di elaborazione può terminare l'unità di esecuzione con un'istruzione STOP RUN.

Per maggiori dettagli sulla procedura di elaborazione, vedere Flusso di controllo.

ATTIVA ECCEZIONE

La frase ON EXCEPTION specifica le istruzioni imperative eseguite quando l'istruzione XML PARSE genera una condizione di eccezione.

Esiste una condizione di eccezione quando il programma di analisi XML rileva un errore nell'elaborazione del documento XML. Il programma di analisi prima segnala un'eccezione XML passando il controllo alla procedura di elaborazione con il registro speciale XML - EVENT contenente 'EXCEPTION'. Il programma di analisi fornisce anche un codice di errore numerico nel registro speciale XML - CODE, come descritto in dettaglio in Gestione delle eccezioni PARSE XML in Enterprise COBOL - Guida alla programmazione.

Esiste anche una condizione di eccezione se 'la procedura di elaborazione imposta XML-CODE a -1 prima di tornare al parser per qualsiasi evento XML normale. In questo caso, il programma di analisi non segnala un evento EXCEPTION XML e l'analisi viene terminata.

Se viene specificata la frase ON EXCEPTION, il programma di analisi trasferisce il controllo a imperative-statement-1. Se la frase ON EXCEPTION non viene specificata, la frase NOT ON EXCEPTION, se presente, viene ignorata e il controllo viene trasferito alla fine dell'istruzione PARSE XML.

Il registro speciale XML-CODE contiene il codice numerico di errore per l'eccezione XML o -1 dopo l'esecuzione dell'istruzione XML PARSE.

Se la procedura di elaborazione gestisce l'evento di eccezione XML e imposta XML - CODE su zero prima di restituire il controllo al programma di analisi, la condizione di eccezione non esiste più. Se non si verificano altre eccezioni non gestite prima della chiusura del programma di analisi, il controllo viene trasferito a imperative-statement-2 della frase NOT ON EXCEPTION, se specificata.

NON SU ECCEZIONE

La frase NOT ON EXCEPTION specifica le istruzioni imperative che vengono eseguite quando non esiste alcuna condizione di eccezione alla fine dell'elaborazione PARSE XML.

Se non esiste una condizione di eccezione al termine dell'elaborazione PARSE XML, il controllo viene trasferito a imperative-statement-2 della frase NOT ON EXCEPTION, se specificata. Se la frase NOT ON EXCEPTION non viene specificata, il controllo viene trasferito alla fine dell'istruzione XML PARSE. La frase ON EXCEPTION, se specificata, viene ignorata.

Il registro speciale XML - CODE contiene zero dopo l'esecuzione dell'istruzione XML PARSE.

Frase END - XML

Questo terminatore dell'ambito esplicito delimita l'ambito delle istruzioni XML GENERATE o XML PARSE. END - XML consente a un'istruzione XML GENERATE o XML PARSE condizionale (ovvero, un'istruzione XML GENERATE o XML PARSE che specifica la frase ON EXCEPTION o NOT ON EXCEPTION) di essere nidificata in un'altra istruzione condizionale.

L'ambito di un'istruzione XML GENERATE o XML PARSE condizionale può essere terminato da:

• Una frase END - XML allo stesso livello di nidificazione
• Un punto di separazione

END - XML può essere utilizzato anche con un'istruzione XML GENERATE o XML PARSE che non specifica la frase ON EXCEPTION o NOT ON EXCEPTION.

Per ulteriori informazioni sui terminatori di ambito espliciti, vedere Dichiarazioni di ambito delimitate.