Copybook-Parser-Referenz

Mainframe Connector verwendet einen ANTLR4-basierten Parser, der Standard-COBOL-Copybooks unterstützt.

In diesem Dokument werden die vom Copybook-Parser ausgeführten Vorverarbeitungsaufgaben, die unterstützten Datentypen und Nutzungseinschränkungen sowie die Konfiguration von Feldmodifikatoren mithilfe der Transcoder-Konfiguration mit den Befehlen qsam decode und qsam encode beschrieben.

Vorverarbeitung

Vor dem Parsen eines Copybooks verarbeitet der Copybook-Parser die Daten vor und führt die folgenden Schritte aus:

  • Entfernt Kommentarzeilen (* in Spalte 7 oder Inline-Kommentare mit *> und *>CE).
  • Löst die Zeilenfortsetzung auf (- in Spalte 7, gefolgt von einem Literal in Anführungszeichen).
  • Sequenznummernbereiche (Spalten 1–6) und Spalte 73 und höher werden ausgeblendet. Der Code muss in Spalte 8 oder höher beginnen.
  • Behält präprozessorspezifische Anweisungen wie EJECT, SKIP1, SKIP2, SKIP3 und TITLE bei. Diese Anweisungen werden geparst, aber ignoriert. Copybooks, die Präprozessorparameter enthalten, die von COPY REPLACING verwendet werden können, werden vom Copybook-Parser nicht unterstützt. In diesen Copybooks sind Kennungen von Doppelpunkten (:) umgeben.

Unterstützte Datentypen und Einschränkungen

Im Folgenden finden Sie die vom Copybook-Parser unterstützten Datentypen und die Einschränkungen für ihre Verwendung:

  • In einem Copybook ist nur ein einziger 01-Eintrag auf oberster Ebene zulässig. Der 01-Eintrag darf keine OCCURS-Klausel enthalten.
  • Felder der Ebene 66 (RENAMES/Alias) und der Ebene 77 (eigenständig) werden nicht unterstützt. Ebene 88 (Bedingungsnamen) wird geparst und ignoriert.
  • Alle elementaren Felder (Nicht-Gruppenfelder) müssen eine PICTURE-Klausel haben, mit Ausnahme von hexadezimalen Gleitkommafeldern (COMP-1 und COMP-2). Die folgenden PICTURE-Felder werden unterstützt:
    • Alphabetisch (PIC A), alphanumerisch (PIC X) und alphanumerisch bearbeitet (A, X, 9, B, 0, /).
    • PIC G (DBCS; erfordert USAGE DISPLAY-1).
    • PIC N (national oder DBCS) und national-edited (N, B, 0, /).
    • PIC U (UTF-8), einschließlich PIC U BYTE-LENGTH n.
    • Numerisch (9, S, V) und numerisch bearbeitet ($, B, /, V, Z, 0, 9, ,, ., *, +, -, CR, DB). Beachten Sie, dass PIC P (Skalierungsposition) nicht unterstützt wird.
    • Zonen- und gepackte Dezimalfelder mit einer Genauigkeit von bis zu 18 werden in 64-Bit-Typen (LONG oder DECIMAL64) decodiert. Felder mit höherer Genauigkeit werden in Typen mit beliebiger Genauigkeit (BIG_INTEGER oder BIG_DECIMAL) decodiert. Wenn schema_validation_mode auf BIG_QUERY gesetzt ist, beträgt die maximal unterstützte Genauigkeit 76 (BIGNUMERIC) und die maximale Skalierung 38 (für POSTGRES beträgt die maximale Genauigkeit 147.455 und die maximale Skalierung 16.383; für MYSQL beträgt die maximale Genauigkeit 65 und die maximale Skalierung 30).
  • IBM Hexadecimal Floating-Point (HFP) wird mit COMP-1 / COMPUTATIONAL-1 (einfache Genauigkeit, 4 Byte) und COMP-2 / COMPUTATIONAL-2 (doppelte Genauigkeit, 8 Byte) oder durch Anwendung des Feldmodifikators hfp in der Transcoder-Konfiguration unterstützt.
  • REDEFINES-Klauseln werden für Felder mit statischer Größe unterstützt, wenn alle neu definierten Varianten dieselbe Bytegröße haben. Neu definierte Felder können nicht als Längenfeld einer OCCURS DEPENDING ON-Klausel oder als target_field eines null_if-Modifikators referenziert werden.
  • OCCURS-Klauseln werden für Arrays mit fester Länge (OCCURS n TIMES), Arrays mit dynamischer Länge (OCCURS min TO max TIMES DEPENDING ON field) und gepackte Arrays mit dynamischer Länge (OCCURS UNBOUNDED DEPENDING ON field) unterstützt. Die Ausdrücke ASCENDING/DESCENDING KEY und INDEXED BY in einer OCCURS-Klausel werden nicht unterstützt und DEPENDING ON muss auf einen Feldnamen im Bereich verweisen.
  • Nur die folgenden USAGE-Anweisungen werden unterstützt:
    • DISPLAY (Standard für alphanumerische und gezonte Dezimalfelder)
    • DISPLAY-1 (DBCS)
    • NATIONAL (Standard für PIC N-Felder; codiert als UTF-16BE)
    • UTF-8 (Standard für PIC U-Felder)
    • 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 und TIMESTAMP werden mit der Transcoder-Konfiguration unterstützt.
  • Null-Indikatoren werden über die Transcoder-Konfiguration unterstützt.
  • Die DBCS-Felder (Double-Byte Character Set) PIC G und PIC N werden unterstützt. Standardmäßig wird PIC N-Feldern ohne USAGE-Klausel USAGE NATIONAL (UTF-16BE) zugewiesen. Wenn Sie ein PIC N-Feld als DBCS verwenden möchten, geben Sie entweder USAGE DISPLAY-1 im Copybook an oder überschreiben Sie die Zeichencodierung in der Transcoder-Konfiguration.
  • Zeichenfolgen mit variabler Länge werden über die Transcoder-Konfiguration unterstützt.
  • Die SIGN-Klausel (LEADING, TRAILING, SEPARATE CHARACTER) wird unterstützt.
  • Kommentare werden unterstützt.

Unterstützung für Datums- und Zeitstempelfelder

Mainframe Connector unterstützt das Decodieren und Codieren von Datums- und Zeitstempelfeldern mit den Feldmodifikatoren format_date und format_timestamp in der Transcoder-Konfiguration (--transcode-configuration). Sie können diese Modifikatoren mit field_suffixes auf übereinstimmende Felder oder mit field_overrides auf bestimmte Felder anwenden:

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

In der folgenden Liste werden die Konfigurationsattribute ausführlicher beschrieben:

  • suffix: Stimmt mit jedem Copybook-Feld überein, dessen Name mit -SUFFIX_STRING oder _SUFFIX_STRING endet (Groß-/Kleinschreibung wird nicht berücksichtigt). Achten Sie darauf, dass suffix keinen führenden Bindestrich oder Unterstrich enthält. Alternativ können Sie field_overrides mit "field": "FIELD_NAME" verwenden, um ein einzelnes Feld anzugeben.
  • format_date / format_timestamp: Definiert den Modifikator, der zum Parsen oder Formatieren des Felds verwendet wird:
    • format_date kann auf Stringfelder mit Größenangabe (PIC X) oder ganzzahlige numerische Felder (z. B. PIC 9(n), COMP oder COMP-3 mit Skalierung 0 und Genauigkeit bis zu 18, die vor der Formatierung dynamisch in ihre vorzeichenlose Stringdarstellung konvertiert werden) angewendet werden.
    • format_timestamp kann auf Stringfelder mit Größenangabe (PIC X) angewendet werden. Zeitstempel werden in UTC interpretiert, sofern im Muster keine Zeitzone oder kein Versatz enthalten ist.
  • formats: Eine Liste von DateTimeFormat-Objekten, die jeweils Folgendes angeben:
    • size: Die Größe des Felds, auf das das Muster angewendet wird (Bytelänge für Stringfelder oder Genauigkeit für numerische Felder).
    • pattern: Ein Datums- oder Zeitstempelmuster. Beim Decodieren (qsam decode) werden Formate, die der Größe des Felds entsprechen, der Reihe nach ausgewertet, bis eines übereinstimmt. Während der Codierung (qsam encode) wird nur das erste übereinstimmende Format für die Größe des Felds verwendet. Weitere Informationen zu gültigen Formaten finden Sie unter Unterstützte Datums- und Zeitstempelformate.
  • Suffixe entfernen (optional): Wenn Sie -SUFFIX_STRING oder _SUFFIX_STRING aus dem Namen des Ausgabefelds entfernen möchten, fügen Sie dem Array transformations in Ihrer Transcoder-Konfiguration eine rename-Transformation hinzu.

Beispiele

  • So formatieren Sie 8-Byte-Felder, die mit -DT8 oder _DT8 enden, als DATE mit dem Muster yyyyMMdd und 10-Byte-Felder, die mit -DT oder _DT enden, mit MM-dd-yyyy oder 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"
            }
          ]
        }
      }
    }
  ]
}

  • So formatieren Sie 26-Byte-Felder, die auf -TIMESTAMP, _TIMESTAMP, -TS oder _TS enden, als TIMESTAMP mit dem Muster yyyy-MM-dd HH.mm.ss.SSSSSS und entfernen das Suffix aus den Namen der Ausgabespalten:

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

Unterstützung für Null-Indikatoren

Mainframe Connector unterstützt Null-Indikatoren über den Feldmodifikator null_if in der Transcoder-Konfiguration (--transcode-configuration).

Wenn Sie einen suffixbasierten Null-Indikator konfigurieren möchten (wobei ein Feld wie COL1-NID als Null-Indikator für COL1 im selben Datensatz fungiert), definieren Sie einen Eintrag in field_suffixes mit "is_inverse": true und "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"
        }
      }
    }
  ]
}

In der folgenden Liste werden die Parameter beschrieben, mit denen Sie Null-Indikatoren konfigurieren können:

  • suffix: Entspricht den Suffixen -NULL_INDICATORNAME oder NULL_INDICATOR_NAME, die ein Null-Indikatorfeld in einem Copybook identifizieren.
  • is_inverse: Wenn für ein FieldSuffix auf true gesetzt, wird der Modifikator auf das gleichgeordnete Feld angewendet, dessen Name mit dem Indikatorfeld ohne das Suffix übereinstimmt (z. B. COL1, wenn der Indikator COL1-NID1 ist). "$self" bezieht sich auf das Indikatorfeld selbst. Sie können null_if auch direkt auf ein bestimmtes Feld anwenden. Verwenden Sie dazu field_overrides und legen Sie für target_field den Namen des Indikatorfelds fest.
  • null_value oder null_values: Gibt den einzelnen Wert (null_value) oder die Liste der Werte (null_values) in target_field an, die signalisieren, dass das referenzierte Feld null ist.
  • non_null_value oder non_null_values: (Optional) Gibt den einzelnen Wert (non_null_value) oder die Liste von Werten (non_null_values) in target_field an, um zu signalisieren, dass das referenzierte Feld nicht null ist. Wenn der Wert weggelassen wird, wird jeder Wert außer null_value oder null_values als nicht null behandelt. Es muss mindestens null_value(s) oder non_null_value(s) angegeben werden.
  • Null-Indikatorfeld ausschließen oder beibehalten: Standardmäßig wird das Null-Indikatorfeld als Spalte im Ausgabeschema beibehalten. Wenn Sie das Null-Indikatorfeld aus der Ausgabetabelle weglassen, es aber während der Transcodierung verwenden möchten, fügen Sie im Array transformations eine exclude-Transformation für das Indikatorfeld hinzu. Wenden Sie den Modifikator filler nicht auf ein Null-Indikatorfeld an, da filler die Decodierung des Felds vollständig überspringt.
  • Feldtyp des Indikators überschreiben: (Optional) Wenn Sie erzwingen möchten, dass ein Null-Indikatorfeld als bytes oder binary decodiert wird, fügen Sie eine nicht inverse field_suffixes-Regel (oder field_overrides-Regel) für das Indikatorfeld mit "modifier": { "bytes": {} } oder "modifier": { "binary": {} } hinzu. Geben Sie für bytes die null_value und non_null_value als hexadezimale Strings an (z. B. "FF" oder "00").

Beispiele

In den folgenden Beispielen werden COL1-NID1 und FIELD-NID2 aus der Ausgabetabelle ausgeschlossen, nachdem sie als Null-Indikatoren ausgewertet wurden, während COL2-NULL im Ausgabeschema beibehalten wird.

Copybook-Snippet:

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

Transcoder-Konfiguration (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"
      }
    }
  ]
}

Unterstützung für DBCS-Felder

Beachten Sie bei der Verwendung von DBCS-Feldern (PIC G oder PIC N mit USAGE DISPLAY-1) Folgendes:

  • In PIC G-Feldern muss USAGE DISPLAY-1 explizit angegeben werden.
  • PIC N-Felder ohne USAGE-Klausel werden standardmäßig auf USAGE NATIONAL (UTF-16BE) gesetzt. Wenn Sie ein PIC N-Feld als DBCS-Feld behandeln möchten, geben Sie USAGE DISPLAY-1 im Copybook an (oder überschreiben Sie die Codierung in der Transcoder-Konfiguration).
  • Standardmäßig werden USAGE DISPLAY-1-Felder mit dem DBCS-Zeichensatz cp300 (x-IBM300) decodiert und codiert. Dieser erwartet rohe DBCS-Bytes ohne die Steuerzeichen „Shift-Out“ (0x0E) und „Shift-In“ (0x0F).
  • Wenn Sie einen anderen DBCS-Zeichensatz (z. B. Cp834) oder einen Multi-Byte-Zeichensatz (MBCS) verwenden möchten, der Shift-Out- (0x0E) und Shift-In-Bytes (0x0F) verwendet (z. B. 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 oder x-IBM1364), konfigurieren Sie den Feldmodifikator string in der Transcoder-Konfiguration (--transcode-configuration).

Sie können die DBCS-Codierung global für alle USAGE DISPLAY-1-Felder mit defaults.dbcs oder für bestimmte Felder mit field_overrides oder field_suffixes festlegen:

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

Unterstützung für Zeichenfolgen mit variabler Länge

Der Copybook-Parser unterstützt Gruppenfelder für Zeichenstrings mit variabler Länge mithilfe des Feldmodifikators varlen in der Transcoder-Konfiguration:

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

Beachten Sie bei Verwendung des Feldmodifikators varlen Folgendes:

  • Wenden Sie den Modifikator varlen auf das Gruppenelement (z. B. VAR-GRP) an. Verwenden Sie dazu field_overrides oder field_suffixes in der Transcoder-Konfiguration:

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

  • Das Gruppenelement muss genau zwei Unterfelder enthalten:

    1. Das erste Unterfeld muss in eine 64-Bit-Ganzzahl (LONG, z. B. ein binäres COMP- oder ein gezontes dezimales Ganzzahlfeld) decodiert werden, die die Bytelänge der Stringdaten angibt.
    2. Das zweite Unterfeld muss ein unverändertes Stringfeld sein (z. B. PIC X(n), PIC N(n) oder PIC U(n)).

  • Es sind keine spezifischen Suffixe für Unterfelder (wie -LEN oder -TEXT) erforderlich. Die resultierende Spalte im Ausgabeschema verwendet den Namen des Gruppenelements (VAR-GRP).

Nicht unterstützte Felder und Konstrukte

In den folgenden Abschnitten werden die Felder und Konstrukte beschrieben, die vom Copybook-Parser nicht unterstützt werden.

Nicht unterstützte COBOL-Konstrukte

Der Copybook-Parser kann die folgenden COBOL-Konstrukte parsen, obwohl diese Konstrukte nicht unterstützt werden. Wenn Sie diese Konstrukte in Ihrem Copybook verwenden, zeigt Mainframe Connector einen Fehler an:

  • ALIGNED
  • BLANK WHEN ZERO
  • COMMON, OWN, LOCAL
  • DYNAMIC LENGTH (z. B. PIC X DYNAMIC LENGTH oder 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

Nicht unterstützte Datentypen

Die folgenden USAGE-Typen können von der Grammatik geparst werden, werden aber vom Copybook-Compiler nicht unterstützt:

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