A instrução XML PARSE é a interface da linguagem COBOL para um dos dois analisadores XML de alta velocidade, dependendo da configuração da opção do compilador
XMLPARSE.
A instrução XML PARSE analisa um documento XML em suas partes individuais e passa cada parte, uma de cada vez, para um procedimento de processamento escrito
pelo usuário.
- identifier-1
- O identifier-1 deve ser um item de dados elementar da categoria nacional, um grupo nacional, um item de dados elementar da categoria alfanumérica ou um item de
grupo alfanumérico.
identifier-1 não pode ser um identificador de função.
identifier-1 contém o fluxo de caracteres do documento XML.
Se o identifier-1 for um item de grupo nacional, o identifier-1 será processado como um item de dados elementar da categoria nacional.
Se o identifier-1 for da categoria nacional, seu conteúdo deverá ser codificado usando o Unicode UTF-16BE (CCSID 1200). identifier
Se a opção do compilador XMLPARSE (COMPAT) estiver em vigor, o identifier-1 não deverá conter nenhuma entidade de caractere representada usando várias unidades
de codificação.
Use uma referência de caracter para representar esses caracteres, por exemplo:
- "񧘃" ou
- "𐠓"
letra x deve estar em minúscula.
O identifier-1 não deve ser um item de grupo de comprimento dinâmico ou um item elementar de comprimento dinâmico.
Se o identifier-1 for da categoria alfanumérica, seu conteúdo deverá ser codificado usando um dos conjuntos de caracteres listados no
Coded character sets for XML documents
Enterprise COBOL Programming Guide.
Se a opção do compilador XMLPARSE (COMPAT) estiver em vigor e o identifier-1 for alfanumérico e contiver um documento XML que não especifica uma declaração de
codificação, o documento XML será analisado com a página de código especificada pela opção do compilador CODEPAGE.
Se a opção do compilador XMLPARSE (XMLSS) estiver em vigor, o documento XML será analisado com a página de código especificada na frase ENCODING; se a frase
ENCODING não for usada, o documento será analisado com a página de código especificada pela opção do compilador CODEPAGE.
Qualquer declaração de codificação no documento XML é ignorada.
- RETURNING NATIONAL phrase
- A frase RETURNING NATIONAL pode ser especificada apenas quando a opção do compilador XMLPARSE (XMLSS) estiver em vigor.
Quando o identifier-1 faz referência a um item de dados da categoria alfanumérica e a frase RETURNING NATIONAL é especificada, os fragmentos de documento XML
são convertidos automaticamente na representação Unicode UTF-16 e retornados ao procedimento de processamento nos registros especiais nacionais XML-NTEXT,
XML-NNAMESPACE, e XML-NNAMESPACE-PREFIX.
Quando a frase RETURNING NATIONAL não é especificada e o identifier-1 faz referência a um item de dados da categoria alfanumérica, os fragmentos de documento
XML são retornados ao procedimento de processamento nos registros alfanuméricos especiais XML-TEXT, XML-NAMESPACE e XML-NAMESPACE-PREFIX, exceto que, quando
XMLPARSE (COMPAT) estiver em vigor, o texto para os eventos XML ATTRIBUTE-NATIONAL-CHARACTER e CONTENT-NATIONAL-CHARACTER será sempre retornado no registro
especial XML-NTEXT.
Quando o identifier-1 faz referência a um item de dados nacional, os fragmentos de documento XML sempre são retornados na representação Unicode UTF-16 nos
registros especiais nacionais XML-NTEXT, XML-NNAMESPACE e XML-NNAMESPACE-PREFIX.
- VALIDATING phrase
- A frase VALIDATING especifica que o analisador deve validar o documento XML em relação a um esquema XML enquanto o analisa.
No Enterprise COBOL, o esquema usado para validação de XML está em um formato pré-processado conhecido como Representação de Esquema Otimizada ou OSR.
A frase VALIDATING pode ser especificada apenas quando a opção do compilador XMLPARSE (XMLSS) estiver em vigor.
Consulte Parsing XML documents with validation
no Enterprise COBOL Programming Guide para obter detalhes.
O identifier-2 pode não ser um item de grupo de comprimento dinâmico ou um item elementar de comprimento dinâmico.
Se a palavra-chave FILE não for especificada, o identifier-2 deverá fazer referência a um item de dados que contenha o esquema XML otimizado.
O identifier-2 deve ser da categoria alfanumérica e não pode ser um identificador de função.
Se a palavra-chave FILE for especificada, xml-schema-name-1 identifica um arquivo z/OS UNIX existente ou um conjunto de dados MVS que contém o esquema XML
otimizado.
xml-schema-name-1 deve estar associado ao nome do arquivo externo do esquema usando a cláusula XML-SCHEMA.
Para obter mais informações sobre a cláusula XML-SCHEMA, consulte o parágrafo
SPECIAL-NAMES paragraph.
Restrição: A validação XML usando a palavra-chave FILE não é suportada no CICS®.
Durante a análise com validação, os eventos XML normais são retornados como para análise sem validação até que ocorra uma exceção devido a um erro de validação
ou outro erro no documento.
Quando um documento XML não é válido, o analisador sinaliza uma exceção XML e passa o controle para o procedimento de processamento com o registro especial
XML-EVENT contendo 'EXCEPTION' e o registro especial XML-CODE contendo o código de retorno 24 na meia-ordem de alta ordem e um código de razão na meia palavra
de ordem baixa.
Para obter informações sobre o código de retorno e o código de razão para exceções que podem ocorrer ao analisar documentos XML com validação, consulte
XML PARSE exceptions with XMLPARSE(XMLSS) in
effect no Enterprise COBOL Programming Guide.
- ENCODING phrase
- A frase ENCODING pode ser especificada apenas quando a opção do compilador XMLPARSE (XMLSS) estiver em vigor.
A frase ENCODING especifica uma codificação que é assumida para o documento XML de origem no identifier-1.
codepage deve ser um item de dados inteiro não assinado ou um literal inteiro não assinado que represente um identificador de conjunto de caracteres codificado
válido (CCSID).
A especificação da frase ENCODING substitui a codificação especificada pela opção do compilador CODEPAGE.
A codificação especificada em qualquer declaração XML é sempre ignorada.
Se o identifier-1 referenciar um item de dados da categoria nacional, a codepage deverá especificar o CCSID 1200, para Unicode UTF-16.
Se o identifier-1 referenciar um item de dados da categoria alfanumérica, a codepage deverá especificar o CCSID 1208 para UTF-8 ou um CCSID para uma página de
código EBCDIC ou ASCII suportada.
Consulte Coded character sets for XML documents no
Enterprise COBOL Programming Guide for details.
- PROCESSING PROCEDURE phrase
- Especifica o nome de um procedimento para manipular os vários eventos que o analisador XML gera.
- procedure-name-1, procedure-name-2
- Deve nomear uma seção ou parágrafo na PROCEDURE DIVISION.
Quando o procedure-name-1 e o procedure-name-2 são especificados, se um é um nome de procedimento em um procedimento declarativo, ambos devem ser nomes de
procedimento no mesmo procedimento declarativo.
- procedure-name-1
- Especifica a primeira (ou única) seção ou parágrafo no procedimento de processamento.
- procedure-name-2
- Especifica a última seção ou parágrafo no procedimento de processamento.
Para cada evento XML, o analisador transfere o controle para a primeira instrução do procedimento denominada procedure-name-1.
O controle é sempre retornado do procedimento de processamento para o analisador XML.
O ponto a partir do qual o controle é retornado é determinado da seguinte maneira:
- Se procedure-name-1 for um nome de parágrafo e procedure-name-2 não for especificado, o retorno será feito após a execução da última instrução do parágrafo
procedure-name-1.
- Se procedure-name-1 for um nome de seção e procedure-name-2 não for especificado, o retorno será feito após a execução da última instrução do último parágrafo
na seção procedure-name-1.
- Se procedure-name-2 for especificado e for um nome de parágrafo, o retorno será feito após a execução da última instrução do procedure-name-2 paragraph.
- Se procedure-name-2 for especificado e for um nome de seção, o retorno será feito após a execução da última instrução do último parágrafo na seção
procedure-name-2.
O único relacionamento necessário entre procedure-name-1 e procedure-name-2 é que eles definem uma sequência consecutiva de operações a serem executadas,
começando no procedimento nomeado por procedure-name-1 e terminando com a execução do procedimento nomeado pelo procedure-name-2.
Se houver dois ou mais caminhos lógicos para o ponto de retorno, o procedure-name-2 poderá nomear um parágrafo que consista apenas em uma instrução EXIT;
todos os caminhos para o ponto de retorno devem levar a este parágrafo.
O procedimento de processamento consiste em todas as instruções nas quais os eventos XML são manipulados.
O intervalo do procedimento de processamento inclui todas as instruções executadas pelas instruções CALL, EXIT, GO TO, GOBACK, INVOKE, MERGE, PERFORM e SORT
que estão no intervalo do procedimento de processamento, bem como todas as instruções nos procedimentos declarativos executados como resultado da execução de
instruções no intervalo do procedimento de processamento.
O intervalo do procedimento de processamento não deve causar a execução de nenhuma instrução GOBACK ou EXIT PROGRAM, exceto para retornar o controle de um
método ou programa para o qual o controle foi passado por uma instrução INVOKE ou CALL, respectivamente, executada no intervalo da procedimento de processamento.
O intervalo do procedimento de processamento não deve causar a execução de uma instrução XML PARSE, a menos que a instrução XML PARSE seja executada em um
método ou programa externo para o qual o controle foi passado por uma instrução INVOKE ou CALL executada no intervalo do processamento procedimento.
Um programa em execução em vários encadeamentos pode executar a mesma instrução XML ou diferentes instruções XML simultaneamente.
O procedimento de processamento pode finalizar a unidade de execução com uma instrução STOP RUN.
Para mais detalhes sobre o procedimento de processamento, consulte Control flow.
- ON EXCEPTION
- A frase ON EXCEPTION especifica instruções imperativas que são executadas quando a instrução XML PARSE gera uma condição de exceção.
Existe uma condição de exceção quando o analisador XML detecta um erro no processamento do documento XML.
O analisador primeiro sinaliza uma exceção XML passando o controle para o procedimento de processamento com o registro especial XML-EVENT contendo 'EXCEPTION'.
O analisador também fornece um código de erro numérico no registro especial XML-CODE, conforme detalhado em
Handling XML PARSE exceptions no Enterprise COBOL Programming
Guide.
Uma condição de exceção também existe se o procedimento de processamento definir XML-CODE para -1 antes de retornar ao analisador para qualquer evento XML normal.
Nesse caso, o analisador não sinaliza um evento XML EXCEPTION e a análise é finalizada.
Se a frase ON EXCEPTION for especificada, o analisador transferirá o controle para imperative-statement-1.
Se a frase ON EXCEPTION não for especificada, a frase NOT ON EXCEPTION, se houver, será ignorada e o controle será transferido para o final da instrução XML PARSE.
O registro especial XML-CODE contém o código de erro numérico da exceção XML ou -1 após a execução da instrução XML PARSE.
Se o procedimento de processamento manipular o evento de exceção XML e definir XML-CODE como zero antes de retornar o controle ao analisador, a condição de
exceção não existirá mais.
Se nenhuma outra exceção não tratada ocorrer antes do término do analisador, o controle será transferido para a imperative-statement-2 da frase NOT ON EXCEPTION,
se especificado.
- NOT ON EXCEPTION
- A frase NOT ON EXCEPTION especifica instruções imperativas que são executadas quando nenhuma condição de exceção existe no final do processamento do XML PARSE.
Se uma condição de exceção não existir na finalização do processamento do XML PARSE, o controle será transferido para a imperative-statement-2 da frase NOT ON
EXCEPTION, se especificado.
Se a frase NOT ON EXCEPTION não for especificada, o controle será transferido para o final da instrução XML PARSE.
A frase ON EXCEPTION, se especificada, é ignorada.
O registro especial XML-CODE contém zero após a execução da instrução XML PARSE.
- END-XML phrase
- Esse terminador de escopo explícito delimita o escopo das instruções XML GENERATE ou XML PARSE.
END-XML permite que uma instrução XML GENERATE ou XML PARSE condicional (ou seja, uma instrução XML GENERATE ou XML PARSE que especifique a frase ON EXCEPTION
ou NOT ON EXCEPTION) seja aninhada em outra instrução condicional.
O escopo de uma instrução XML GENERATE ou XML PARSE condicional pode ser encerrado por:
- Uma frase END-XML no mesmo nível de aninhamento
- Um período separador
END-XML também pode ser usado com uma instrução XML GENERATE ou XML PARSE que não especifica a frase ON EXCEPTION ou NOT ON EXCEPTION.
Para obter mais informações sobre terminadores de escopo explícitos, consulte
Delimited scope statements.
