Referência do analisador de Copybook

O conetor de mainframe suporta duas versões do analisador de copybook:

  • Analisador de copybook nativo: o analisador de copybook nativo implementa um analisador baseado em ANTLR4, suporta copybooks COBOL e é a versão recomendada do analisador.
  • Analisador de copybook antigo: o analisador de copybook antigo é uma versão mais antiga do analisador que suporta formatos de copybooks muito limitados.

Pode definir o analisador que quer usar com base no seu copybook. Para mais informações sobre como definir o analisador que quer usar, consulte Defina o analisador de copybook.

Analisador de livros de cópias nativos

O analisador Native copybook é a versão mais recente do analisador e é usado por predefinição. O analisador nativo de copybooks implementa um analisador baseado em ANTLR4 e suporta copybooks COBOL.

Esta secção apresenta uma lista das tarefas de pré-processamento realizadas pelo analisador de Native copybook. Também descreve os tipos de dados suportados pelo analisador nativo de livros de registo e as restrições para a respetiva utilização.

Pré-processamento

Antes de analisar um copybook, o analisador de copybook nativo pré-processa os dados e realiza as seguintes tarefas:

  • Remove linhas de comentários.
  • Resolve a continuação de linhas.
  • Esconde as áreas de números de linhas e as áreas da coluna 73.
  • Preserva declarações específicas do pré-processador, como EJECT, SPACE e TITLE. Estes campos são analisados, mas ignorados. Os copybooks que contêm parâmetros de pré-processador que podem ser usados por COPY REPLACING não são suportados pelo analisador de copybooks nativo. Nestes livros de cópias, os identificadores estão rodeados por dois pontos (:).

Tipos de dados suportados e restrições

Seguem-se os tipos de dados suportados pelo analisador nativo de livros de registo e as restrições para a respetiva utilização:

  • Os níveis 66 (ALIAS) ou 77 (STANDALONE) não são suportados.
  • Use apenas campos PICTURE. Os seguintes campos PICTURE são suportados:
    • Pic A, Pic, B, Pic G (DBCS), Pic N (nacional ou DBCS), Pic U (UTF8), Pic X e decimal zonado (precisão máxima de 38, escala máxima de 38)
  • O ponto flutuante hexadecimal (HFP) da IBM é suportado.
  • Os REDEFINES não são suportados.
  • Use apenas os seguintes campos COMP. ALIGN e OCCURS não são suportados.
    • COMP
    • COMP4
    • BINARY
    • COMP3
    • PACKED-DECIMAL
  • DATE e TIMESTAMP são suportados.
  • Os indicadores nulos são suportados.
  • Os campos Pic G e Pic N do conjunto de carateres de dois bytes (DBCS) são suportados e devem ser usados em vez de Pic T, que foi descontinuado. Para usar o campo Pic N como DBCS sem especificar USAGE DISPLAY-1, tem de definir a variável de ambiente NSYMBOL como DBCS. Por predefinição, NSYMBOL está definido como NATIONAL, que define USAGE NATIONAL como campos Pic N que não têm uma cláusula USAGE. Tenha em atenção que NSYMBOL só pode ser definido como NATIONAL ou DBCS.
  • As strings de carateres de comprimento variável são suportadas.
  • A cláusula SIGN é suportada.
  • Tem de justificar todos os campos e usar um único nível de recuo.
  • Os comentários são suportados.

Suporte para campos de data e hora

O conetor de mainframe suporta a movimentação de dados de data e hora de entrada e saída do BigQuery. Para o fazer, tem de definir variáveis de ambiente que comecem pela palavra SUFFIX no seguinte formato:

SUFFIX_SUFFIX_STRING="command --format FORMAT --timezone TIMEZONE"

A lista seguinte descreve o formato mais detalhadamente:

  • SUFFIX_SUFFIX_STRING: a variável de ambiente que pode usar para definir dados de data e hora. O SUFFIX_STRING nome corresponde aos sufixos -SUFFIX_STRING ou _SUFFIX_STRING que devem ser interpretados como uma data ou data/hora quando usados como sufixo de um nome de campo num copybook. Certifique-se de que o elemento SUFFIX_STRING não contém um hífen nem um sublinhado.
  • command: define o descodificador que deve ser usado para analisar o campo. Os comandos suportados são date-converter e timestamp-converter.
  • --format: um parâmetro que define o formato da data ou da data/hora. Pode especificar, no máximo, cinco formatos diferentes separados por vírgulas. Se vários formatos puderem corresponder a uma determinada entrada, o primeiro formato que corresponder é usado para carregar para o BigQuery. Se forem especificados vários formatos para a exportação, apenas é usado o primeiro formato. Para mais informações sobre formatos válidos, consulte o artigo Formatos de data e indicação de tempo compatíveis.
  • --timezone: um parâmetro opcional para o tipo TIMESTAMP. Por predefinição, o fuso horário é UTC. Para mais informações sobre os formatos de fuso horário compatíveis, consulte o artigo Formatos de fuso horário compatíveis.
  • --omitsuffix (Opcional): se este parâmetro for especificado, -SUFFIX_STRING ou _SUFFIX_STRING é removido do nome do campo apresentado no BigQuery.

Para adicionar um alias para um SUFFIX_SUFFIX_STRING, pode definir uma variável de ambiente SUFFIX_SUFFIX_ALIAS=$SUFFIX_SUFFIX_STRING.

Exemplos:

  • Se definir uma variável de ambiente como SUFFIX_DT8="date-converter --format yyyyMMdd", um campo com o sufixo -DT8 ou _DT8 será um campo do tipo DATE no BigQuery, e o respetivo padrão será yyyyMMdd.
  • Se definir uma variável de ambiente como SUFFIX_DT10="date-converter --format MM-dd-yyyy", um campo com o sufixo -DT10 ou _DT10 será um campo do tipo DATE no BigQuery, e o respetivo padrão será MM-dd-yyyy.
  • Se definir uma variável de ambiente como SUFFIX_DT="date-converter --format 'MM-dd-yyyy,MM/dd/yyyy'", um campo com o sufixo -DT ou _DT vai ser um campo do tipo DATE no BigQuery, e o respetivo padrão vai ser MM-dd-yyyy ou MM/dd/yyyy.
  • Se definir duas variáveis de ambiente como SUFFIX_TIMESTAMP="timestamp-converter --format yyyy-MM-dd SUFFIX_TIMESTAMP=timestamp-converter --format 'yyyy-MM-dd HH.mm.ss.SSSSSS' --timezone America/New_York" e SUFFIX_TS=$SUFFIX_TIMESTAMP, um campo com um dos seguintes sufixos: -TIMESTAMP, _TIMESTAMP, -TS ou _TS será um campo do tipo TIMESTAMP no BigQuery, e o respetivo padrão será yyyy-MM-dd HH:mm:ss.SSSSSS com o fuso horário America/New_York.

Suporte para indicadores nulos

O conetor de mainframe suporta indicadores nulos a partir da versão 5.13.0. Para usar indicadores nulos, tem de definir variáveis de ambiente que comecem pela palavra SUFFIX no seguinte formato:

SUFFIX_NULL_INDICATOR_NAME="command --null-value NULL_VALUE --not-null-value NOT_NULL_VALUE"

NULL_INDICATOR_NAME corresponde aos sufixos -NULL_INDICATOR_NAME ou _NULL_INDICATOR_NAME que são interpretados como um indicador nulo quando usados como sufixo de um nome de campo num copybook.

A lista seguinte descreve os parâmetros que pode usar com estas variáveis de ambiente:

  • command: o valor tem de ser null-indicator.
  • –null-value: O valor null indicator indica que o campo referenciado é nulo. O valor de --null-value tem de ser uma string ou um número decimal.
  • –not-null-value: (Opcional) Quando especificado, o valor null indicator indica que o campo referenciado não é nulo. Se este parâmetro não estiver definido, é aceite qualquer valor que não seja –value-null. O valor de –not-null-value tem de ser uma string ou um número decimal.
  • –keep: (Opcional) Quando especificado, o campo null-indicator é mantido como uma coluna no formato de ficheiro colunar de linhas otimizado (ORC). Por predefinição, este campo não é mantido no formato ORC.
  • -force-type: (Opcional) Suporta duas opções: bytes e binary, que forçam um campo a ser descodificado como bytes ou binário, respetivamente. Para bytes, os valores de null e not-null são expressos como HEX (por exemplo, FA3AB5). Estão disponíveis constantes HIGH e LOW equivalentes a todos os FF ou todos os 00. Para o tipo binário, os valores são números inteiros normais.

Se o elemento null-indicator não tiver um campo referenciado, o Mainframe Connector apresenta uma mensagem de erro e para de processar os ficheiros.

Exemplos:

Fragmento de livro de cópias

10 COL1-NID1            PIC S9(4) USAGE COMP.
10 COL1                 PIC S9(6) USAGE COMP.

10 FIELD       PIC        X(10).
10 FIELD-NID2  PIC        X(1).

10 COL2       PIC        X(10).
10 COL2-NULL  PIC        X(1).

Definição de variáveis de ambiente

SUFFIX_NID1="null-indicator --null-value -1 --not-null-value 0"
# Copybook fields with NID1 suffix null indicator configuration.
SUFFIX_NID2="null-indicator --null-value '?'"
# Copybook fields with NID2 suffix null indicator configuration.
SUFFIX_NULL="null-indicator --null-value '?' --keep"
# Copybook fields with NULL suffix null indicator configuration.

Suporte para campos DBCS

Certifique-se de que cumpre os seguintes requisitos quando usar campos DBCS:

  • Quando usa campos DBCS PIC G ou Pic N, tem de fornecer uma das seguintes codificações de conjunto de carateres multibyte (MBCS) válidas na encodingopção ou na variável de ambiente ENCODING quando usa os comandos gsutil cp ou bq export:
    • x-IBM930
    • x-IBM933
    • x-IBM935
    • x-IBM937
    • x-IBM939
    • x-IBM942
    • x-IBM942C
    • x-IBM943
    • x-IBM943C
    • x-IBM949
    • x-IBM949C
    • x-IBM950
    • x-IBM964
    • x-IBM970
    • x-IBM1364
  • Quando um campo de copybook contém apenas bytes DBCS, mas estes bytes não estão rodeados por shift-out (0x0E) e shift-in (0x0F), tem de adicionar o sufixo _DBCS ao nome do campo para garantir que estes bytes são descodificados como bytes DBCS.

Por exemplo, se os dados correspondentes ao campo do livro de registo 03 FLD01 PIC N USAGE DISPLAY-1 contiverem bytes 0x43 e 0xC5 na codificação x-IBM930 que não estão rodeados por 0x0E e 0x0F, tem de mudar o nome do campo do livro de registo para 03 FLD01-DBCS PIC N USAGE DISPLAY-1 para descodificar corretamente os dados DBCS.

Suporte para strings de carateres de comprimento variável

O analisador de livros de cópias nativos suporta os seguintes campos struct:

  • 10 var
  • 15 var-LEN PIC 9(4) USAGE COMP
  • 15 var-TEXT PIC X(n)

O primeiro campo no campo struct é o comprimento do segundo campo, o campo de string. Pode ter de adicionar algum preenchimento ao final do registo com base no comprimento do registo, conforme mostrado na figura seguinte.

Preenchimento adicionado a strings de carateres de comprimento variável.
Figura 1. Preenchimento adicionado a strings de carateres de comprimento variável.

O conetor de mainframe remove o sufixo do nome da variável antes de guardar os dados no BigQuery. Neste exemplo, o nome da variável é var.

Para usar campos struct, defina a variável de ambiente BQSH_FEATURE_VARIABLE_LENGTH_ENABLED como yes ou true.

Quando usar campos struct, certifique-se do seguinte:

  • O sufixo do primeiro parâmetro em struct é -LEN. Se quiser usar um sufixo diferente, tem de definir a variável de ambiente BQSH_FEATURE_VARIABLE_LENGTH_LEN_SUFFIX para o sufixo que quer usar.
  • O sufixo do segundo parâmetro em struct é -TEXT. Se quiser usar um sufixo diferente, tem de definir a variável de ambiente BQSH_FEATURE_VARIABLE_LENGTH_DATA_SUFFIX para o sufixo que quer usar.

Campos e construções não suportados

As secções seguintes descrevem os campos e as construções que não são suportados pela

Construções COBOL

Construções COBOL, apesar de estas construções não serem suportadas. Se usar estas construções no seu livro de cópias, o Mainframe Connector apresenta um erro.

  • dataAlignedClause
  • dataBlankWhenZeroClause
  • dataCommonOwnLocalClause
  • dataIntegerStringClause
  • dataJustifiedClause
  • dataOccursClause
  • dataReceivedByClause
  • dataRecordAreaClause
  • dataRenamesClause
  • dataSignClause
  • dataSynchronizedClause
  • dataThreadLocalClause
  • dataTypeClause
  • dataTypeDefClause
  • dataUsingClause

Tipos de dados

Os tipos de dados COBOL, como COMP-1 e COMP-2, são suportados.

Analisador de copybook antigo

O analisador de copybook antigo é uma versão mais antiga do analisador que suporta funcionalidades não COBOL. Se estiver a usar um copybook baseado em DSL, o analisador sintático antigo pode ser mais adequado, uma vez que o analisador sintático de copybook nativo pode causar erros.

Pode usar o LDD de livro de cópias com as seguintes restrições:

  • Os níveis 66 (ALIAS) ou 77 (STANDALONE) não são suportados.
  • Os REDEFINES não são suportados.
  • As linhas de comentários não são suportadas.
  • Os campos de comprimento 10 cujo nome termina com DATE ou DT são datas. A descodificação é diferente para esses campos.
  • Use apenas os seguintes campos COMP. ALIGN e OCCURS não são suportados.
    • COMP
    • COMP4
    • BINARY
    • COMP3
    • PACKED-DECIMAL
  • Use apenas campos PICTURE. Defina campos PICTURE na mesma linha, diretamente após o nome do campo.
  • Tem de justificar todos os campos e usar um único nível. Os comentários não são suportados.
  • Certifique-se de que as colunas 1 a 6 contêm sempre espaços em branco.