Referenz zum Copybook-Parser

Der Mainframe-Connector unterstützt zwei Versionen des Copybook-Parsers:

  • Nativer Copybook-Parser: Der native Copybook-Parser implementiert einen ANTLR4-basierten Parser, unterstützt COBOL-Copybooks und ist die empfohlene Version des Parsers.
  • Alte Copybook-Datei-Parser: Der alte Copybook-Datei-Parser ist eine ältere Version des Parsers, die nur sehr wenige Copybook-Formate unterstützt.

Sie können anhand Ihres Copybooks festlegen, welchen Parser Sie verwenden möchten. Weitere Informationen zum Definieren des zu verwendenden Parsers finden Sie unter Copybook-Parser definieren.

Nativer Copybook-Parser

Der native Copybook-Parser ist die neueste Version des Parsers und wird standardmäßig verwendet. Der native Copybook-Parser implementiert einen ANTLR4-basierten Parser und unterstützt COBOL-Copybooks.

In diesem Abschnitt sind die Aufgaben aufgeführt, die vom Parser für das native Copybook ausgeführt werden. Außerdem werden die Datentypen beschrieben, die vom Parser für native Copybooks unterstützt werden, sowie die Einschränkungen für die Verwendung.

Vorverarbeitung

Bevor ein Copybook geparst wird, werden die Daten vom Native Copybook-Parser vorab verarbeitet und die folgenden Aufgaben ausgeführt:

  • Entfernt Kommentarzeilen.
  • Behebt die Zeilenfortsetzung.
  • Die Bereiche für die Zeilennummern und Spalte 73 werden ausgeblendet.
  • Behält preprocessorspezifische Anweisungen wie EJECT, SPACE und TITLE bei. Diese Felder werden geparst, aber ignoriert. Copybooks mit Preprozessorparametern, die von COPY REPLACING verwendet werden können, werden vom nativen Copybook-Parser nicht unterstützt. In diesen Musterbüchern sind Kennungen von einem Doppelpunkt (:) umgeben.

Unterstützte Datentypen und Einschränkungen

Im Folgenden finden Sie die Datentypen, die vom Parser für native Copybooks unterstützt werden, sowie die Einschränkungen für die Verwendung:

  • Die Ebenen 66 (ALIAS) und 77 (STANDALONE) werden nicht unterstützt.
  • Verwenden Sie nur PICTURE-Felder. Die folgenden PICTURE-Felder werden unterstützt:
    • Pic A, Pic B, Pic G (DBCS), Pic N (national oder DBCS), Pic U (UTF8), Pic X und zoned decimal (maximale Genauigkeit 38, maximale Skala 38)
  • IBM Hexadecimal Floating Point (HFP) wird unterstützt.
  • REDEFINES werden nicht unterstützt.
  • Verwenden Sie nur die folgenden COMP-Felder. ALIGN und OCCURS werden nicht unterstützt.
    • COMP
    • COMP4
    • BINARY
    • COMP3
    • PACKED-DECIMAL
  • DATE und TIMESTAMP werden unterstützt.
  • Null-Indikatoren werden unterstützt.
  • Die Felder „Pic G“ und „Pic N“ für Double-Byte-Zeichensätze (DBCS) werden unterstützt und sollten anstelle von „Pic T“ verwendet werden, das jetzt eingestellt wurde. Wenn Sie das Pic N-Feld als DBCS verwenden möchten, ohne USAGE DISPLAY-1 anzugeben, müssen Sie die Umgebungsvariable NSYMBOL auf DBCS festlegen. Standardmäßig ist NSYMBOL auf NATIONAL festgelegt, wodurch USAGE NATIONAL auf Pic N-Felder gesetzt wird, die keine USAGE-Klausel haben. NSYMBOL kann nur auf NATIONAL oder DBCS gesetzt werden.
  • Zeichenstrings mit variabler Länge werden unterstützt.
  • Die SIGN-Klausel wird unterstützt.
  • Alle Felder müssen ausgerichtet sein und es darf nur eine einzige Einzugebene verwendet werden.
  • Kommentare werden unterstützt.

Unterstützung für Datums- und Zeitstempelfelder

Der Mainframe-Connector unterstützt das Verschieben von Datums- und Zeitstempeldaten zwischen BigQuery und anderen Systemen. Dazu müssen Sie Umgebungsvariablen definieren, die mit dem Wort SUFFIX beginnen und das folgende Format haben:

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

In der folgenden Liste wird das Format genauer beschrieben:

  • SUFFIX_SUFFIX_STRING: Die Umgebungsvariable, mit der Sie Datums- und Zeitstempeldaten definieren können. Der SUFFIX_STRING-Name entspricht den Suffixen -SUFFIX_STRING oder _SUFFIX_STRING, die als Datum oder Zeitstempel interpretiert werden sollten, wenn sie als Suffix eines Feldnamens in einem Copybook verwendet werden. SUFFIX_STRING darf keinen Bindestrich oder Unterstrich enthalten.
  • command: Definiert den Decoder, der zum Parsen des Felds verwendet werden soll. Die unterstützten Befehle sind date-converter und timestamp-converter.
  • --format: Ein Parameter, der das Format des Datums oder Zeitstempels definiert. Sie können bis zu fünf verschiedene Formate angeben, die durch Kommas getrennt werden. Wenn mehrere Formate mit einer bestimmten Eingabe übereinstimmen, wird das erste übereinstimmende Format zum Laden in BigQuery verwendet. Wenn für den Export mehrere Formate angegeben werden, wird nur das erste Format verwendet. Weitere Informationen zu gültigen Formaten finden Sie unter Unterstützte Datums- und Zeitstempelformate.
  • --timezone: Ein optionaler Parameter vom Typ TIMESTAMP. Standardmäßig ist die Zeitzone UTC. Weitere Informationen zu unterstützten Zeitzonenformaten finden Sie unter Unterstützte Zeitzonenformate.
  • --omitsuffix (optional): Wenn dieser Parameter angegeben ist, wird -SUFFIX_STRING oder _SUFFIX_STRING aus dem Feldnamen entfernt, der in BigQuery angezeigt wird.

Wenn Sie einen Alias für ein SUFFIX_SUFFIX_STRING hinzufügen möchten, können Sie die Umgebungsvariable SUFFIX_SUFFIX_ALIAS=$SUFFIX_SUFFIX_STRING festlegen.

Beispiele:

  • Wenn Sie eine Umgebungsvariable als SUFFIX_DT8="date-converter --format yyyyMMdd" definieren, ist ein Feld mit dem Suffix -DT8 oder _DT8 in BigQuery ein Feld vom Typ DATE und sein Muster ist yyyyMMdd.
  • Wenn Sie eine Umgebungsvariable als SUFFIX_DT10="date-converter --format MM-dd-yyyy" definieren, ist ein Feld mit dem Suffix -DT10 oder _DT10 in BigQuery ein Feld vom Typ DATE und sein Muster ist MM-dd-yyyy.
  • Wenn Sie eine Umgebungsvariable als SUFFIX_DT="date-converter --format 'MM-dd-yyyy,MM/dd/yyyy'" definieren, ist ein Feld mit dem Suffix -DT oder _DT in BigQuery ein Feld vom Typ DATE und sein Muster ist entweder MM-dd-yyyy oder MM/dd/yyyy.
  • Wenn Sie zwei Umgebungsvariablen als SUFFIX_TIMESTAMP="timestamp-converter --format yyyy-MM-dd SUFFIX_TIMESTAMP=timestamp-converter --format 'yyyy-MM-dd HH.mm.ss.SSSSSS' --timezone America/New_York" und SUFFIX_TS=$SUFFIX_TIMESTAMP definieren, ist ein Feld mit einem der folgenden Suffixe – -TIMESTAMP, _TIMESTAMP, -TS oder _TS – in BigQuery ein Feld vom Typ TIMESTAMP und sein Muster ist yyyy-MM-dd HH:mm:ss.SSSSSS mit Zeitzone America/New_York.

Unterstützung für Null-Indikatoren

Der Mainframe-Connector unterstützt Null-Indikatoren ab Version 5.13.0. Wenn Sie Nullindikatoren verwenden möchten, müssen Sie Umgebungsvariablen definieren, die mit dem Wort SUFFIX im folgenden Format beginnen:

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

NULL_INDICATOR_NAME entspricht den Suffixen -NULL_INDICATOR_NAME oder _NULL_INDICATOR_NAME, die als Nullindikator interpretiert werden, wenn sie als Suffix eines Feldnamens in einem Copybook verwendet werden.

In der folgenden Liste werden die Parameter beschrieben, die Sie mit diesen Umgebungsvariablen verwenden können:

  • command: Der Wert muss null-indicator sein.
  • –null-value: Der Wert null indicator gibt an, dass das referenzierte Feld null ist. Der Wert von --null-value muss entweder ein String oder eine Dezimalzahl sein.
  • –not-null-value: (Optional) Wenn angegeben, gibt der Wert null indicator an, dass das referenzierte Feld nicht null ist. Wenn dieser Parameter nicht festgelegt ist, wird jeder Wert akzeptiert, der nicht –value-null ist. Der Wert von –not-null-value muss entweder ein String oder eine Dezimalzahl sein.
  • –keep: Optional. Wenn diese Option angegeben ist, wird das Feld null-indicator als Spalte im ORC-Dateiformat (Optimized Row Columnar) beibehalten. Dieses Feld wird standardmäßig nicht im ORC-Format beibehalten.
  • -force-type: (Optional) Unterstützt zwei Optionen: bytes und binary, mit denen ein Feld jeweils als Bytes oder Binärdaten decodiert werden kann. Bei Bytes werden die Werte für null und not-null als HEX ausgedrückt (z. B. FA3AB5). Es sind Konstanten vom Typ HIGH und LOW verfügbar, die allen FF oder allen 00 entsprechen. Bei Binärwerten handelt es sich um Ganzzahlen.

Wenn die null-indicator kein referenziertes Feld hat, zeigt Mainframe Connector eine Fehlermeldung an und beendet die Verarbeitung der Dateien.

Beispiele:

Snippet für das Musterbuch

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

Definition von Umgebungsvariablen

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.

Unterstützung für DBCS-Felder

Beachten Sie bei der Verwendung von DBCS-Feldern Folgendes:

  • Wenn Sie PIC G- oder PIC N-DBCS-Felder verwenden, müssen Sie bei Verwendung der Befehle gsutil cp oder bq export eine der folgenden gültigen MBCS-Codierungen (Multi-Byte Character Set) in der Option encoding oder in der Umgebungsvariablen ENCODING angeben:
    • 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
  • Wenn ein Copybook-Feld nur DBCS-Byte enthält, diese aber nicht von Shift-Out (0x0E) und Shift-In (0x0F) umgeben sind, müssen Sie dem Feldnamen das Suffix _DBCS hinzufügen, damit diese Bytes als DBCS-Byte decodiert werden.

Wenn die Daten, die dem Copybook-Feld 03 FLD01 PIC N USAGE DISPLAY-1 entsprechen, beispielsweise die Bytes 0x43 und 0xC5 in der Codierung x-IBM930 enthalten, die nicht von 0x0E und 0x0F umgeben sind, müssen Sie den Namen des Copybook-Felds in 03 FLD01-DBCS PIC N USAGE DISPLAY-1 umbenennen, um die DBCS-Daten korrekt zu decodieren.

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

Der native Copybook-Parser unterstützt die folgenden struct-Felder:

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

Das erste Feld im struct-Feld ist die Länge des zweiten Felds, des Stringfelds. Je nach Eintragslänge müssen Sie dem Eintrag möglicherweise ein paar Leerzeichen hinzufügen, wie in der folgenden Abbildung dargestellt.

Zeichenfolgen mit variabler Länge werden zusätzliche Zeichen hinzugefügt.
Abbildung 1. Zeichenfolgen mit variabler Länge werden zusätzliche Zeichen hinzugefügt.

Der Mainframe-Connector entfernt das Suffix aus dem Variablennamen, bevor die Daten in BigQuery gespeichert werden. In diesem Beispiel lautet der Variablenname var.

Wenn Sie struct-Felder verwenden möchten, legen Sie die Umgebungsvariable BQSH_FEATURE_VARIABLE_LENGTH_ENABLED auf yes oder true fest.

Beachten Sie bei der Verwendung von struct-Feldern Folgendes:

  • Das Suffix des ersten Parameters in struct lautet -LEN. Wenn Sie ein anderes Suffix verwenden möchten, müssen Sie die Umgebungsvariable BQSH_FEATURE_VARIABLE_LENGTH_LEN_SUFFIX auf das gewünschte Suffix festlegen.
  • Das Suffix des zweiten Parameters in struct lautet -TEXT. Wenn Sie ein anderes Suffix verwenden möchten, müssen Sie die Umgebungsvariable BQSH_FEATURE_VARIABLE_LENGTH_LEN_SUFFIX auf das gewünschte Suffix festlegen.

Nicht unterstützte Felder und Konstrukte

In den folgenden Abschnitten werden Felder und Konstrukte beschrieben, die vom

COBOL-Konstrukte

COBOL-Konstrukte, auch wenn diese Konstrukte nicht unterstützt werden. Wenn Sie diese Konstrukte in Ihrem Copybook verwenden, zeigt der Mainframe-Connector einen Fehler an.

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

Datentypen

COBOL-Datentypen wie COMP-1 und COMP-2 werden unterstützt.

Legacy-Copybook-Parser

Der alte Copybook-Parser ist eine ältere Version des Parsers, die nicht COBOL-spezifische Funktionen unterstützt. Wenn Sie ein DSL-basiertes Copybook verwenden, ist der alte Parser möglicherweise besser geeignet, da der native Copybook-Parser Fehler verursachen kann.

Sie können Copybook-DD mit den folgenden Einschränkungen verwenden:

  • Die Ebenen 66 (ALIAS) und 77 (STANDALONE) werden nicht unterstützt.
  • REDEFINES werden nicht unterstützt.
  • Kommentarzeilen werden nicht unterstützt.
  • Felder mit einer Länge von 10 Zeichen, deren Name auf DATE oder DT endet, sind Datumsangaben. Die Dekodierung erfolgt für diese Felder anders.
  • Verwenden Sie nur die folgenden COMP-Felder. ALIGN und OCCURS werden nicht unterstützt.
    • COMP
    • COMP4
    • BINARY
    • COMP3
    • PACKED-DECIMAL
  • Verwenden Sie nur PICTURE-Felder. Definieren Sie PICTURE-Felder in derselben Zeile direkt nach dem Feldnamen.
  • Alle Felder müssen ausgerichtet sein und es darf nur eine Ebene geben. Kommentare werden nicht unterstützt.
  • Die Spalten 1 bis 6 müssen immer leer sein.