Riferimento per l'analizzatore sintattico Copybook

Mainframe Connector utilizza un parser basato su ANTLR4 che supporta i copybook COBOL standard.

Questo documento elenca le attività di pre-elaborazione eseguite dall'analizzatore sintattico del copybook, i tipi di dati supportati e le limitazioni di utilizzo, nonché come configurare i modificatori di campo utilizzando la configurazione del transcoder con i comandi qsam decode e qsam encode.

Pre-elaborazione

Prima di analizzare un copybook, il parser del copybook pre-elabora i dati ed esegue i seguenti passaggi:

  • Rimuove le righe di commento (* nella colonna 7 o commenti *> e *>CE incorporati).
  • Risolve la continuazione della riga (- nella colonna 7 seguita da un valore letterale tra virgolette).
  • Cancella le aree dei numeri di sequenza (colonne 1-6) e la colonna 73 e successive. Il codice deve iniziare alla colonna 8 o successiva.
  • Conserva le istruzioni specifiche del preprocessore come EJECT, SKIP1, SKIP2, SKIP3 e TITLE. Queste istruzioni vengono analizzate, ma ignorate. I copybook contenenti parametri del preprocessore che possono essere utilizzati da COPY REPLACING non sono supportati dall'analizzatore sintattico dei copybook. In questi copybook, gli identificatori sono racchiusi tra due punti (:).

Tipi di dati supportati e limitazioni

Di seguito sono riportati i tipi di dati supportati dal parser del copybook e le limitazioni per il loro utilizzo:

  • In un copybook è consentito un solo record 01 di primo livello e il record 01 non può avere una clausola OCCURS.
  • I campi di livello 66 (RENAMES/alias) e di livello 77 (autonomo) non sono supportati. Il livello 88 (nomi delle condizioni) viene analizzato e ignorato.
  • Tutti i campi elementari (non di gruppo) devono avere una clausola PICTURE, ad eccezione dei campi con rappresentazione in virgola mobile esadecimali (COMP-1 e COMP-2). Sono supportati i seguenti campi PICTURE:
    • Alfabetico (PIC A), alfanumerico (PIC X) e alfanumerico modificato (A, X, 9, B, 0, /).
    • PIC G (DBCS; richiede USAGE DISPLAY-1).
    • PIC N (nazionale o DBCS) e modificato a livello nazionale (N, B, 0, /).
    • PIC U (UTF-8), incluso PIC U BYTE-LENGTH n.
    • Numerico (9, S, V) e numerico modificato ($, B, /, V, Z, 0, 9, ,, ., *, +, -, CR, DB). Tieni presente che PIC P (posizione di scalabilità) non è supportato.
    • I campi decimali a zone e decimali compressi con precisione fino a 18 vengono decodificati in tipi a 64 bit (LONG o DECIMAL64) e i campi con precisione superiore vengono decodificati in tipi con precisione arbitraria (BIG_INTEGER o BIG_DECIMAL). Quando schema_validation_mode è impostato su BIG_QUERY, la precisione massima supportata è 76 (BIGNUMERIC) e la scalabilità massima è 38 (per POSTGRES, la precisione massima è 147.455 e la scalabilità massima è 16.383; per MYSQL, la precisione massima è 65 e la scalabilità massima è 30).
  • La rappresentazione in virgola mobile esadecimale (HFP) di IBM è supportata utilizzando COMP-1/COMPUTATIONAL-1 (precisione singola, 4 byte) e COMP-2/COMPUTATIONAL-2 (precisione doppia, 8 byte) o applicando il modificatore di campo hfp nella configurazione del transcodificatore.
  • Le clausole REDEFINES sono supportate nei campi di dimensioni statiche quando tutte le varianti ridefinite hanno le stesse dimensioni in byte. I campi ridefiniti non possono essere indicati come campo di lunghezza di una clausola OCCURS DEPENDING ON o come target_field di un modificatore null_if.
  • Le clausole OCCURS sono supportate per gli array di lunghezza fissa (OCCURS n TIMES), gli array di lunghezza dinamica (OCCURS min TO max TIMES DEPENDING ON field) e gli array di lunghezza dinamica compressi (OCCURS UNBOUNDED DEPENDING ON field). Le frasi ASCENDING/DESCENDING KEY e INDEXED BY in una clausola OCCURS non sono supportate e DEPENDING ON deve fare riferimento a un nome di campo nell'ambito.
  • Sono supportate solo le seguenti clausole USAGE:
    • DISPLAY (valore predefinito per i campi alfanumerici e decimali con zona)
    • DISPLAY-1 (DBCS)
    • NATIONAL (valore predefinito per i campi PIC N; codificato come UTF-16BE)
    • UTF-8 (valore predefinito per i campi 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 sono supportati utilizzando la configurazione del transcoder.
  • Gli indicatori null sono supportati utilizzando la configurazione del transcodificatore.
  • Sono supportati i campi PIC G e PIC N del set di caratteri a doppio byte (DBCS). Per impostazione predefinita, ai campi PIC N senza una clausola USAGE viene assegnato USAGE NATIONAL (UTF-16BE). Per utilizzare un campo PIC N come DBCS, specifica USAGE DISPLAY-1 nel copybook o esegui l'override della codifica dei caratteri nella configurazione del transcoder.
  • Le stringhe di caratteri di lunghezza variabile sono supportate utilizzando la configurazione del transcoder.
  • La clausola SIGN (LEADING, TRAILING, SEPARATE CHARACTER) è supportata.
  • I commenti sono supportati.

Supporto per i campi di data e timestamp

Mainframe Connector supporta la decodifica e la codifica dei campi di data e timestamp utilizzando i modificatori di campo format_date e format_timestamp nella configurazione del transcodificatore (--transcode-configuration). Puoi applicare questi modificatori ai campi corrispondenti utilizzando field_suffixes o a campi specifici utilizzando field_overrides:

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

Il seguente elenco descrive in modo più dettagliato le proprietà di configurazione:

  • suffix: corrisponde a qualsiasi campo del copybook il cui nome termina con -SUFFIX_STRING o _SUFFIX_STRING (senza distinzione tra maiuscole e minuscole). Assicurati che suffix non contenga un trattino o un trattino basso iniziale. In alternativa, utilizza field_overrides con "field": "FIELD_NAME" per scegliere come target un singolo campo.
  • format_date/format_timestamp: definisce il modificatore utilizzato per analizzare o formattare il campo:
    • format_date può essere applicato a campi di stringhe con dimensioni (PIC X) o campi numerici interi (come PIC 9(n), COMP o COMP-3 con scala 0 e precisione fino a 18, che vengono convertiti dinamicamente nella loro rappresentazione di stringa non firmata prima della formattazione).
    • format_timestamp può essere applicato ai campi stringa con dimensioni (PIC X). I timestamp vengono interpretati in UTC, a meno che nel pattern non sia incluso un fuso orario o un offset.
  • formats: un elenco di oggetti DateTimeFormat, ognuno dei quali specifica:
    • size: le dimensioni del campo a cui si applica il pattern (lunghezza in byte per i campi stringa o precisione per i campi numerici).
    • pattern: un pattern di data o timestamp. Durante la decodifica (qsam decode), i formati corrispondenti alle dimensioni del campo vengono valutati in ordine fino a quando non ne viene trovato uno corrispondente. Durante la codifica (qsam encode), viene utilizzato solo il primo formato corrispondente per le dimensioni del campo. Per saperne di più sui formati validi, consulta Formati di data e timestamp supportati.
  • Rimozione dei suffissi (facoltativo): per rimuovere -SUFFIX_STRING o _SUFFIX_STRING dal nome del campo di output, aggiungi una trasformazione rename all'array transformations nella configurazione del transcodificatore.

Esempi

  • Per formattare i campi di 8 byte che terminano con -DT8 o _DT8 come DATE con il pattern yyyyMMdd e i campi di 10 byte che terminano con -DT o _DT con MM-dd-yyyy o 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"
            }
          ]
        }
      }
    }
  ]
}

  • Per formattare i campi di 26 byte che terminano con -TIMESTAMP, _TIMESTAMP, -TS o _TS come TIMESTAMP con il pattern yyyy-MM-dd HH.mm.ss.SSSSSS e rimuovere il suffisso dai nomi delle colonne di output:

    {
  "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"
      }
    }
  ]
}

Supporto per gli indicatori null

Mainframe Connector supporta gli indicatori null tramite il modificatore di campo null_if nella configurazione del transcodificatore (--transcode-configuration).

Per configurare un indicatore null basato su suffisso (dove un campo come COL1-NID funge da indicatore null per COL1 nello stesso record), definisci una voce in field_suffixes con "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"
        }
      }
    }
  ]
}

Il seguente elenco descrive i parametri che puoi utilizzare per configurare gli indicatori null:

  • suffix: corrisponde ai suffissi -NULL_INDICATORNAME o NULL_INDICATOR_NAME che identificano un campo indicatore null in un copybook.
  • is_inverse: se impostato su true in un FieldSuffix, il modificatore viene applicato al campo di pari livello il cui nome corrisponde al campo indicatore senza il suffisso (ad esempio, COL1 quando l'indicatore è COL1-NID1) e "$self" si riferisce al campo indicatore stesso. Puoi anche applicare null_if direttamente a un campo specifico utilizzando field_overrides e impostare target_field sul nome del campo indicatore.
  • null_value o null_values: specifica il singolo valore (null_value) o l'elenco di valori (null_values) in target_field che indicano che il campo di riferimento è null.
  • non_null_value o non_null_values: (facoltativo) specifica il singolo valore (non_null_value) o l'elenco di valori (non_null_values) in target_field per segnalare che il campo di riferimento non è null. Se omesso, qualsiasi valore diverso da null_value o null_values viene considerato non nullo. È necessario specificare almeno un valore per null_value(s) o non_null_value(s).
  • Esclusione o conservazione del campo dell'indicatore null: per impostazione predefinita, il campo dell'indicatore null viene mantenuto come colonna nello schema di output. Per omettere il campo dell'indicatore null dalla tabella di output, ma utilizzarlo comunque durante la transcodifica, aggiungi una trasformazione exclude per il campo dell'indicatore nell'array transformations (non applicare il modificatore filler a un campo dell'indicatore null, poiché filler salta completamente la decodifica del campo).
  • Override del tipo di campo indicatore: (facoltativo) per forzare la decodifica di un campo indicatore null come bytes o binary, aggiungi una regola field_suffixes (o field_overrides) non inversa per il campo indicatore con "modifier": { "bytes": {} } o "modifier": { "binary": {} }. Per bytes, esprimi null_value e non_null_value come stringhe esadecimali (ad esempio, "FF" o "00").

Esempi

Negli esempi seguenti, COL1-NID1 e FIELD-NID2 vengono esclusi dalla tabella di output dopo essere stati valutati come indicatori null, mentre COL2-NULL viene mantenuto nello schema di output.

Snippet di 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).

Configurazione del transcodificatore (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"
      }
    }
  ]
}

Supporto per i campi DBCS

Quando utilizzi i campi DBCS (PIC G o PIC N con USAGE DISPLAY-1), assicurati di quanto segue:

  • I campi PIC G devono specificare esplicitamente USAGE DISPLAY-1.
  • I campi PIC N senza una clausola USAGE hanno come valore predefinito USAGE NATIONAL (UTF-16BE). Per trattare un campo PIC N come un campo DBCS, specifica USAGE DISPLAY-1 nel copybook (o esegui l'override della codifica nella configurazione del transcodificatore).
  • Per impostazione predefinita, i campi USAGE DISPLAY-1 vengono decodificati e codificati utilizzando il set di caratteri DBCS cp300 (x-IBM300), che prevede byte DBCS non elaborati senza caratteri di controllo shift-out (0x0E) e shift-in (0x0F).
  • Per utilizzare un set di caratteri DBCS diverso (ad esempio Cp834) o un set di caratteri multi-byte (MBCS) che utilizza byte shift-out (0x0E) e shift-in (0x0F) (ad esempio 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 o x-IBM1364), configura il modificatore di campo string nella configurazione del transcoder (--transcode-configuration).

Puoi impostare la codifica DBCS a livello globale per tutti i campi USAGE DISPLAY-1 utilizzando defaults.dbcs o per campi specifici utilizzando field_overrides o field_suffixes:

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

Supporto per stringhe di caratteri di lunghezza variabile

Il parser del copybook supporta i campi di gruppo di stringhe di caratteri di lunghezza variabile utilizzando il modificatore di campo varlen nella configurazione del transcoder:

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

Quando utilizzi il modificatore di campo varlen, assicurati di quanto segue:

  • Applica il modificatore varlen all'elemento del gruppo (ad esempio VAR-GRP) utilizzando field_overrides o field_suffixes nella configurazione del transcodificatore:

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

  • L'elemento del gruppo deve contenere esattamente due sottocampi:

    1. Il primo sottocampo deve essere decodificato in un numero intero a 64 bit (LONG, ad esempio un campo intero binario COMP o decimale a zone) che specifica la lunghezza in byte dei dati della stringa.
    2. Il secondo sottocampo deve essere un campo stringa non modificato (ad esempio PIC X(n), PIC N(n) o PIC U(n)).

  • Non sono richiesti suffissi di sottocampi specifici (come -LEN o -TEXT) e la colonna risultante nello schema di output utilizza il nome dell'elemento del gruppo (VAR-GRP).

Campi e costrutti non supportati

Le sezioni seguenti descrivono i campi e i costrutti non supportati dal parser del copybook.

Costrutti COBOL non supportati

Il parser del copybook può analizzare i seguenti costrutti COBOL, anche se non sono supportati. Se utilizzi questi costrutti nel copybook, Mainframe Connector mostra un errore:

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

Tipi di dati non supportati

I seguenti tipi di USAGE possono essere analizzati dalla grammatica, ma non sono supportati dal compilatore del copybook:

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