Referência do analisador de copybook

O conector de mainframe usa um analisador baseado em ANTLR4 que é compatível com copybooks COBOL padrão.

Neste documento, listamos as tarefas de pré-processamento realizadas pelo analisador de copybook, os tipos de dados compatíveis e as restrições de uso, além de como configurar modificadores de campo usando a configuração do transcodificador com os comandos qsam decode e qsam encode.

Pré-processamento

Antes de analisar um copybook, o analisador pré-processa os dados e executa as seguintes etapas:

  • Remove linhas de comentário (* na coluna 7 ou comentários inline *> e *>CE).
  • Resolve a continuação de linha (- na coluna 7 seguido por um literal entre aspas).
  • Apaga as áreas de número de sequência (colunas 1 a 6) e a coluna 73 em diante. O código precisa começar na coluna 8 ou posterior.
  • Preserva instruções específicas do pré-processador, como EJECT, SKIP1, SKIP2, SKIP3 e TITLE. Essas instruções são analisadas, mas ignoradas. Os copybooks que contêm parâmetros de pré-processador que podem ser usados por COPY REPLACING não são compatíveis com o analisador de copybooks. Nesses copybooks, os identificadores são delimitados por dois-pontos (:).

Tipos de dados e restrições aceitos

Confira a seguir os tipos de dados compatíveis com o analisador de copybook e as restrições de uso:

  • Apenas um único registro 01 de nível superior é permitido em um copybook, e o registro 01 não pode ter uma cláusula OCCURS.
  • Os campos de nível 66 (RENAMES / alias) e nível 77 (independente) não são compatíveis. O nível 88 (nomes de condição) é analisado e ignorado.
  • Todos os campos elementares (não de grupo) precisam ter uma cláusula PICTURE, exceto os campos de usar pontos flutuantes hexadecimal (COMP-1 e COMP-2). Os seguintes campos PICTURE são compatíveis:
    • Alfabético (PIC A), alfanumérico (PIC X) e alfanumérico editado (A, X, 9, B, 0, /).
    • PIC G (DBCS; requer USAGE DISPLAY-1).
    • PIC N (nacional ou DBCS) e editado nacionalmente (N, B, 0, /).
    • PIC U (UTF-8), incluindo PIC U BYTE-LENGTH n.
    • Numérico (9, S, V) e editado numericamente ($, B, /, V, Z, 0, 9, ,, ., *, +, -, CR, DB). Observe que PIC P (posição de escalonamento) não é compatível.
    • Os campos decimais zonados e decimais compactados com precisão de até 18 são decodificados em tipos de 64 bits (LONG ou DECIMAL64), e os campos de maior precisão são decodificados em tipos de precisão arbitrária (BIG_INTEGER ou BIG_DECIMAL). Quando schema_validation_mode é definido como BIG_QUERY, a precisão máxima aceita é 76 (BIGNUMERIC) e a escala máxima é 38 (para POSTGRES, a precisão máxima é 147.455 e a escala máxima é 16.383; para MYSQL, a precisão máxima é 65 e a escala máxima é 30).
  • O ponto flutuante hexadecimal (HFP, na sigla em inglês) da IBM é compatível com COMP-1 / COMPUTATIONAL-1 (precisão única, 4 bytes) e COMP-2 / COMPUTATIONAL-2 (precisão dupla, 8 bytes) ou com a aplicação do modificador de campo hfp na configuração do transcodificador.
  • As cláusulas REDEFINES são compatíveis com campos de tamanho estático quando todas as variantes redefinidas têm o mesmo tamanho de byte. Os campos redefinidos não podem ser referenciados como o campo de comprimento de uma cláusula OCCURS DEPENDING ON ou como o target_field de um modificador null_if.
  • As cláusulas OCCURS são compatíveis com matrizes de comprimento fixo (OCCURS n TIMES), matrizes de comprimento dinâmico (OCCURS min TO max TIMES DEPENDING ON field) e matrizes de comprimento dinâmico compactadas (OCCURS UNBOUNDED DEPENDING ON field). As frases ASCENDING/DESCENDING KEY e INDEXED BY em uma cláusula OCCURS não são compatíveis, e DEPENDING ON precisa referenciar um nome de campo no escopo.
  • Somente as seguintes cláusulas USAGE são compatíveis:
    • DISPLAY (padrão para campos alfanuméricos e decimais zonados)
    • DISPLAY-1 (DBCS)
    • NATIONAL (padrão para campos PIC N; codificado como UTF-16BE)
    • UTF-8 (padrão para campos PIC U)
    • BINARY, COMP, COMPUTATIONAL, COMP-4, COMPUTATIONAL-4, COMP-5, COMPUTATIONAL-5
    • COMP-3, COMPUTATIONAL-3, PACKED-DECIMAL
    • COMP-1, COMPUTATIONAL-1, COMP-2, COMPUTATIONAL-2
  • DATE e TIMESTAMP são compatíveis com a configuração do transcodificador.
  • Os indicadores nulos são compatíveis com a configuração do transcodificador.
  • Os campos PIC G e PIC N do conjunto de caracteres de byte duplo (DBCS, na sigla em inglês) são compatíveis. Por padrão, os campos PIC N sem uma cláusula USAGE recebem USAGE NATIONAL (UTF-16BE). Para usar um campo PIC N como DBCS, especifique USAGE DISPLAY-1 no copybook ou substitua a codificação de caracteres na configuração do transcodificador.
  • Strings de caracteres de comprimento variável são compatíveis com a configuração do transcodificador.
  • A cláusula SIGN (LEADING, TRAILING, SEPARATE CHARACTER) é compatível.
  • É possível usar comentários.

Suporte para campos de data e carimbo de data/hora

O Mainframe Connector é compatível com a decodificação e codificação de campos de data e carimbo de data/hora usando os modificadores de campo format_date e format_timestamp na configuração do transcodificador (--transcode-configuration). É possível aplicar esses modificadores em campos correspondentes usando field_suffixes ou em campos específicos usando field_overrides:

{
  "field_suffixes": [
    {
      "suffix": "SUFFIX_STRING",
      "modifier": {
        "format_date": {
          "formats": [
            {
              "size": FIELD_SIZE,
              "pattern": "FORMAT_PATTERN"
            }
          ]
        }
      }
    }
  ]
}

A lista a seguir descreve as propriedades de configuração em mais detalhes:

  • suffix: corresponde a qualquer campo de copybook cujo nome termine com -SUFFIX_STRING ou _SUFFIX_STRING (não diferencia maiúsculas de minúsculas). Verifique se suffix não contém um hífen ou sublinhado no início. Como alternativa, use field_overrides com "field": "FIELD_NAME" para segmentar um campo individual.
  • format_date / format_timestamp: define o modificador usado para analisar ou formatar o campo:
    • format_date pode ser aplicado a campos de string dimensionados (PIC X) ou campos numéricos inteiros (como PIC 9(n), COMP ou COMP-3 com escala 0 e precisão de até 18, que são convertidos dinamicamente para a representação de string sem sinal antes da formatação).
    • format_timestamp pode ser aplicado a campos de string dimensionados (PIC X). Os carimbos de data/hora são interpretados em UTC, a menos que um fuso horário ou deslocamento seja incluído no padrão.
  • formats: uma lista de objetos DateTimeFormat, cada um especificando:
    • size: o tamanho do campo ao qual o padrão se aplica (comprimento de bytes para campos de string ou precisão para campos numéricos).
    • pattern: um padrão de data ou carimbo de data/hora. Durante a decodificação (qsam decode), os formatos que correspondem ao tamanho do campo são avaliados em ordem até que um deles corresponda. Durante a codificação (qsam encode), apenas o primeiro formato correspondente ao tamanho do campo é usado. Para mais informações sobre formatos válidos, consulte Formatos de data e carimbo de data/hora compatíveis.
  • Remover sufixos (opcional): para remover -SUFFIX_STRING ou _SUFFIX_STRING do nome do campo de saída, adicione uma transformação rename à matriz transformations na configuração da transcodificação.

Exemplos

  • Para formatar campos de 8 bytes que terminam com -DT8 ou _DT8 como DATE com o padrão yyyyMMdd e campos de 10 bytes que terminam com -DT ou _DT com MM-dd-yyyy ou MM/dd/yyyy:

    {
  "field_suffixes": [
    {
      "suffix": "DT8",
      "modifier": {
        "format_date": {
          "formats": [
            {
              "size": 8,
              "pattern": "yyyyMMdd"
            }
          ]
        }
      }
    },
    {
      "suffix": "DT",
      "modifier": {
        "format_date": {
          "formats": [
            {
              "size": 10,
              "pattern": "MM-dd-yyyy"
            },
            {
              "size": 10,
              "pattern": "MM/dd/yyyy"
            }
          ]
        }
      }
    }
  ]
}

  • Para formatar campos de 26 bytes que terminam com -TIMESTAMP, _TIMESTAMP, -TS ou _TS como TIMESTAMP com o padrão yyyy-MM-dd HH.mm.ss.SSSSSS e remover o sufixo dos nomes das colunas de saída:

    {
  "field_suffixes": [
    {
      "suffix": "TIMESTAMP",
      "modifier": {
        "format_timestamp": {
          "formats": [
            {
              "size": 26,
              "pattern": "yyyy-MM-dd HH.mm.ss.SSSSSS"
            }
          ]
        }
      }
    },
    {
      "suffix": "TS",
      "modifier": {
        "format_timestamp": {
          "formats": [
            {
              "size": 26,
              "pattern": "yyyy-MM-dd HH.mm.ss.SSSSSS"
            }
          ]
        }
      }
    }
  ],
  "transformations": [
    {
      "rename": {
        "find": "^(.*)[-_](TIMESTAMP|TS)$",
        "replace": "$1"
      }
    }
  ]
}

Suporte para indicadores nulos

O Mainframe Connector é compatível com indicadores nulos usando o modificador de campo null_if na configuração do transcodificador (--transcode-configuration).

Para configurar um indicador nulo baseado em sufixo (em que um campo como COL1-NID atua como o indicador nulo para COL1 no mesmo registro), defina uma entrada em field_suffixes com "is_inverse": true e "target_field": "$self":

{
  "field_suffixes": [
    {
      "suffix": "NULL_INDICATOR_NAME",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "NULL_VALUE",
          "non_null_value": "NOT_NULL_VALUE"
        }
      }
    }
  ]
}

A lista a seguir descreve os parâmetros que podem ser usados para configurar indicadores nulos:

  • suffix: corresponde aos sufixos -NULL_INDICATORNAME ou NULL_INDICATOR_NAME que identificam um campo indicador nulo em um copybook.
  • is_inverse: quando definido como true em um FieldSuffix, o modificador é aplicado ao campo irmão cujo nome corresponde ao campo indicador sem o sufixo (por exemplo, COL1 quando o indicador é COL1-NID1), e "$self" se refere ao próprio campo indicador. Também é possível aplicar null_if diretamente em um campo específico usando field_overrides e definir target_field como o nome do campo indicador.
  • null_value ou null_values: especifica o valor único (null_value) ou a lista de valores (null_values) em target_field que sinalizam que o campo referenciado é null.
  • non_null_value ou non_null_values: (opcional) especifica o valor único (non_null_value) ou a lista de valores (non_null_values) em target_field para sinalizar que o campo referenciado não é null. Se omitido, qualquer valor diferente de null_value ou null_values será tratado como não nulo. É preciso especificar pelo menos null_value(s) ou non_null_value(s).
  • Excluir ou manter o campo indicador de nulo: por padrão, o campo indicador de nulo é mantido como uma coluna no esquema de saída. Para omitir o campo indicador de nulo da tabela de saída enquanto ele ainda é usado durante a transcodificação, adicione uma transformação exclude para o campo indicador na matriz transformations. Não aplique o modificador filler a um campo indicador de nulo, já que filler ignora a decodificação do campo.
  • Substituição do tipo de campo do indicador: (opcional) para forçar um campo de indicador nulo a ser decodificado como bytes ou binary, adicione uma regra field_suffixes (ou field_overrides) não inversa para o campo do indicador com "modifier": { "bytes": {} } ou "modifier": { "binary": {} }. Para bytes, expresse null_value e non_null_value como strings hexadecimais (por exemplo, "FF" ou "00").

Exemplos

Nos exemplos a seguir, COL1-NID1 e FIELD-NID2 são excluídos da tabela de saída após serem avaliados como indicadores nulos, enquanto COL2-NULL é mantido no esquema de saída.

Snippet do copybook:

01 REC.
   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).

Configuração do Transcoder (transcode-configuration.json):

{
  "field_suffixes": [
    {
      "suffix": "NID1",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "-1",
          "non_null_value": "0"
        }
      }
    },
    {
      "suffix": "NID2",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "?"
        }
      }
    },
    {
      "suffix": "NULL",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "?"
        }
      }
    }
  ],
  "transformations": [
    {
      "exclude": {
        "field": "COL1-NID1"
      }
    },
    {
      "exclude": {
        "field": "FIELD-NID2"
      }
    }
  ]
}

Suporte para campos DBCS

Ao usar campos DBCS (PIC G ou PIC N com USAGE DISPLAY-1), verifique o seguinte:

  • Os campos PIC G precisam especificar explicitamente USAGE DISPLAY-1.
  • Os campos PIC N sem uma cláusula USAGE usam USAGE NATIONAL (UTF-16BE) como padrão. Para tratar um campo PIC N como um campo DBCS, especifique USAGE DISPLAY-1 no copybook (ou substitua a codificação dele na configuração do transcodificador).
  • Por padrão, os campos USAGE DISPLAY-1 são decodificados e codificados usando o conjunto de caracteres DBCS cp300 (x-IBM300), que espera bytes DBCS brutos sem caracteres de controle shift-out (0x0E) e shift-in (0x0F).
  • Para usar um conjunto de caracteres DBCS diferente (como Cp834) ou um conjunto de caracteres de vários bytes (MBCS) que usa bytes de deslocamento para fora (0x0E) e de deslocamento para dentro (0x0F) (como 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 ou x-IBM1364), configure o modificador de campo string na configuração do transcodificador (--transcode-configuration).

É possível definir a codificação DBCS globalmente para todos os campos USAGE DISPLAY-1 usando defaults.dbcs ou para campos específicos usando field_overrides ou field_suffixes:

{
  "defaults": {
    "dbcs": {
      "string": {
        "encoding": "x-IBM930"
      }
    }
  }
}

Suporte para strings de caracteres de comprimento variável

O analisador de copybook é compatível com campos de grupo de strings de caracteres de comprimento variável usando o modificador de campo varlen na configuração do transcodificador:

10 VAR-GRP.
   15 VAR-LEN  PIC 9(4) USAGE COMP.
   15 VAR-TEXT PIC X(50).

Ao usar o modificador de campo varlen, verifique se:

  • Aplique o modificador varlen ao item do grupo (por exemplo, VAR-GRP) usando field_overrides ou field_suffixes na configuração da transcodificação:

    {
  "field_overrides": [
    {
      "field": "VAR-GRP",
      "modifier": {
        "varlen": {}
      }
    }
  ]
}

  • O item de grupo precisa conter exatamente dois subcampos:

    1. O primeiro subcampo precisa ser decodificado em um número inteiro de 64 bits (LONG, como um campo de número inteiro decimal COMP binário ou zoneado) que especifica o comprimento em bytes dos dados da string.
    2. O segundo subcampo precisa ser um campo de string não modificado (como PIC X(n), PIC N(n) ou PIC U(n)).

  • Não são necessários sufixos de subcampo específicos (como -LEN ou -TEXT), e a coluna resultante no esquema de saída usa o nome do item do grupo (VAR-GRP).

Campos e construções sem suporte

As seções a seguir descrevem os campos e as construções que não são compatíveis com o analisador de copybook.

Construções COBOL sem suporte

O analisador de copybook pode analisar as seguintes construções COBOL, mesmo que elas não sejam compatíveis. Se você usar essas construções no copybook, o Mainframe Connector vai mostrar um erro:

  • ALIGNED
  • BLANK WHEN ZERO
  • COMMON, OWN, LOCAL
  • DYNAMIC LENGTH (como PIC X DYNAMIC LENGTH ou PIC U DYNAMIC LENGTH LIMIT n)
  • INTEGER, STRING
  • JUSTIFIED
  • ASCENDING/DESCENDING KEY em OCCURS
  • INDEXED BY em OCCURS
  • RECEIVED BY
  • RECORD AREA
  • RENAMES
  • SYNCHRONIZED / SYNC
  • THREAD-LOCAL
  • TYPE IS ...
  • TYPEDEF
  • USING LANGUAGE/CONVENTION

Tipos de dados não compatíveis

Os seguintes tipos de USAGE podem ser analisados pela gramática, mas não são compatíveis com o compilador de copybook:

  • BIT
  • CONTROL-POINT
  • DATE
  • DOUBLE
  • EVENT
  • FUNCTION-POINTER
  • INDEX
  • KANJI
  • LOCK
  • POINTER
  • PROCEDURE-POINTER
  • REAL
  • SQL
  • TASK