Referensi parser copybook

Mainframe Connector menggunakan parser berbasis ANTLR4 yang mendukung copybook COBOL standar.

Dokumen ini mencantumkan tugas pra-pemrosesan yang dilakukan oleh parser copybook, jenis data yang didukung dan batasan penggunaan, serta cara mengonfigurasi pengubah kolom menggunakan konfigurasi transcoder dengan perintah qsam decode dan qsam encode.

Prapemrosesan

Sebelum mengurai copybook, parser copybook melakukan pra-pemrosesan data dan melakukan langkah-langkah berikut:

  • Menghapus baris komentar (* di kolom 7, atau komentar *> dan *>CE inline).
  • Menyelesaikan kelanjutan baris (- di kolom 7 diikuti dengan literal yang dikutip).
  • Mengosongkan area nomor urut (kolom 1–6) dan kolom 73 dan seterusnya. Kode harus dimulai di kolom 8 atau yang lebih baru.
  • Mempertahankan pernyataan khusus pra-pemroses seperti EJECT, SKIP1, SKIP2, SKIP3, dan TITLE. Pernyataan ini diurai, tetapi diabaikan. Copybook yang berisi parameter preprocessor yang dapat digunakan oleh COPY REPLACING tidak didukung oleh parser copybook. Dalam copybook ini, ID diapit oleh titik dua (:).

Jenis data dan batasan yang didukung

Berikut adalah jenis data yang didukung oleh parser copybook dan batasan penggunaannya:

  • Hanya satu data 01 tingkat teratas yang diizinkan dalam copybook, dan data 01 tidak boleh memiliki klausa OCCURS.
  • Kolom level 66 (RENAMES/alias) dan level 77 (mandiri) tidak didukung. Level 88 (nama kondisi) diuraikan dan diabaikan.
  • Semua kolom dasar (non-grup) harus memiliki klausa PICTURE, kecuali untuk kolom floating point heksadesimal (COMP-1 dan COMP-2). Kolom PICTURE berikut didukung:
    • Alfabet (PIC A), alfanumerik (PIC X), dan alfanumerik yang diedit (A, X, 9, B, 0, /).
    • PIC G (DBCS; memerlukan USAGE DISPLAY-1).
    • PIC N (nasional atau DBCS) dan diedit secara nasional (N, B, 0, /).
    • PIC U (UTF-8), termasuk PIC U BYTE-LENGTH n.
    • Numerik (9, S, V) dan numerik yang diedit ($, B, /, V, Z, 0, 9, ,, ., *, +, -, CR, DB). Perhatikan bahwa PIC P (posisi penskalaan) tidak didukung.
    • Kolom desimal berzona dan desimal yang dipadatkan dengan presisi hingga 18 didekode menjadi jenis 64-bit (LONG atau DECIMAL64), dan kolom presisi yang lebih tinggi didekode menjadi jenis presisi arbitrer (BIG_INTEGER atau BIG_DECIMAL). Jika schema_validation_mode ditetapkan ke BIG_QUERY, presisi maksimum yang didukung adalah 76 (BIGNUMERIC) dan skala maksimumnya adalah 38 (untuk POSTGRES, presisi maksimumnya adalah 147.455 dan skala maksimumnya adalah 16.383; untuk MYSQL, presisi maksimumnya adalah 65 dan skala maksimumnya adalah 30).
  • IBM Hexadecimal Floating-Point (HFP) didukung menggunakan COMP-1 / COMPUTATIONAL-1 (presisi tunggal, 4 byte) dan COMP-2 / COMPUTATIONAL-2 (presisi ganda, 8 byte), atau dengan menerapkan pengubah kolom hfp dalam konfigurasi transcoder.
  • Klausa REDEFINES didukung pada kolom berukuran statis jika semua varian yang didefinisikan ulang memiliki ukuran byte yang sama. Kolom yang didefinisikan ulang tidak dapat direferensikan sebagai kolom panjang klausa OCCURS DEPENDING ON atau sebagai target_field pengubah null_if.
  • Klausa OCCURS didukung untuk array panjang tetap (OCCURS n TIMES), array panjang dinamis (OCCURS min TO max TIMES DEPENDING ON field), dan array panjang dinamis yang dipaketkan (OCCURS UNBOUNDED DEPENDING ON field). Frasa ASCENDING/DESCENDING KEY dan INDEXED BY dalam klausa OCCURS tidak didukung, dan DEPENDING ON harus merujuk ke nama kolom dalam cakupan.
  • Hanya klausa USAGE berikut yang didukung:
    • DISPLAY (default untuk kolom alfanumerik dan desimal berzona)
    • DISPLAY-1 (DBCS)
    • NATIONAL (default untuk kolom PIC N; dienkode sebagai UTF-16BE)
    • UTF-8 (default untuk kolom 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 dan TIMESTAMP didukung menggunakan konfigurasi transcoder.
  • Indikator null didukung menggunakan konfigurasi transcoder.
  • Kolom himpunan karakter double-byte (DBCS) PIC G dan PIC N didukung. Secara default, kolom PIC N tanpa klausa USAGE akan diberi USAGE NATIONAL (UTF-16BE). Untuk menggunakan kolom PIC N sebagai DBCS, tentukan USAGE DISPLAY-1 di copybook atau ganti encoding karakternya dalam konfigurasi transcoder.
  • String karakter dengan panjang variabel didukung menggunakan konfigurasi transcoder.
  • Klausa SIGN (LEADING, TRAILING, SEPARATE CHARACTER) didukung.
  • Komentar didukung.

Dukungan untuk kolom tanggal dan stempel waktu

Mainframe Connector mendukung decoding dan encoding kolom tanggal dan stempel waktu menggunakan pengubah kolom format_date dan format_timestamp dalam konfigurasi transcoder (--transcode-configuration). Anda dapat menerapkan pengubah ini di seluruh kolom yang cocok menggunakan field_suffixes atau ke kolom tertentu menggunakan field_overrides:

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

Daftar berikut menjelaskan properti konfigurasi secara lebih mendetail:

  • suffix: Mencocokkan kolom copybook apa pun yang namanya diakhiri dengan -SUFFIX_STRING atau _SUFFIX_STRING (tidak peka huruf besar/kecil). Pastikan suffix tidak berisi tanda hubung atau garis bawah di awal. Atau, gunakan field_overrides dengan "field": "FIELD_NAME" untuk menargetkan masing-masing kolom.
  • format_date / format_timestamp: Menentukan pengubah yang digunakan untuk mengurai atau memformat kolom:
    • format_date dapat diterapkan ke kolom string berukuran (PIC X) atau kolom numerik bilangan bulat (seperti PIC 9(n), COMP, atau COMP-3 dengan skala 0 dan presisi hingga 18, yang dikonversi secara dinamis ke representasi string tanpa tanda sebelum pemformatan).
    • format_timestamp dapat diterapkan ke kolom string berukuran (PIC X). Stempel waktu ditafsirkan dalam UTC kecuali jika zona waktu atau offset disertakan dalam pola.
  • formats: Daftar objek DateTimeFormat, yang masing-masing menentukan:
    • size: Ukuran kolom yang menerapkan pola (panjang byte untuk kolom string, atau presisi untuk kolom numerik).
    • pattern: Pola tanggal atau stempel waktu. Selama decoding (qsam decode), format yang cocok dengan ukuran kolom dievaluasi secara berurutan hingga ada yang cocok. Selama encoding (qsam encode), hanya format pencocokan pertama untuk ukuran kolom yang digunakan. Untuk mengetahui informasi selengkapnya tentang format yang valid, lihat Format tanggal dan stempel waktu yang didukung.
  • Menghapus akhiran (Opsional): Untuk menghapus -SUFFIX_STRING atau _SUFFIX_STRING dari nama kolom output, tambahkan transformasi rename ke array transformations dalam konfigurasi transcoder Anda.

Contoh

  • Untuk memformat kolom 8 byte yang diakhiri dengan -DT8 atau _DT8 sebagai DATE dengan pola yyyyMMdd, dan kolom 10 byte yang diakhiri dengan -DT atau _DT dengan MM-dd-yyyy atau 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"
            }
          ]
        }
      }
    }
  ]
}

  • Untuk memformat kolom 26 byte yang diakhiri dengan -TIMESTAMP, _TIMESTAMP, -TS, atau _TS sebagai TIMESTAMP dengan pola yyyy-MM-dd HH.mm.ss.SSSSSS dan menghapus akhiran dari nama kolom 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"
      }
    }
  ]
}

Dukungan untuk indikator null

Mainframe Connector mendukung indikator null melalui pengubah kolom null_if dalam konfigurasi transcoder (--transcode-configuration).

Untuk mengonfigurasi indikator null berbasis akhiran (dengan kolom seperti COL1-NID bertindak sebagai indikator null untuk COL1 dalam data yang sama), tentukan entri di field_suffixes dengan "is_inverse": true dan "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"
        }
      }
    }
  ]
}

Daftar berikut menjelaskan parameter yang dapat Anda gunakan untuk mengonfigurasi indikator null:

  • suffix: Sesuai dengan akhiran -NULL_INDICATORNAME atau NULL_INDICATOR_NAME yang mengidentifikasi kolom indikator null dalam copybook.
  • is_inverse: Jika ditetapkan ke true pada FieldSuffix, pengubah diterapkan ke kolom yang setara yang namanya cocok dengan kolom indikator tanpa akhiran (misalnya, COL1 jika indikatornya adalah COL1-NID1), dan "$self" mengacu pada kolom indikator itu sendiri. Anda juga dapat menerapkan null_if langsung pada kolom tertentu menggunakan field_overrides dan menetapkan target_field ke nama kolom indikator.
  • null_value atau null_values: Menentukan nilai tunggal (null_value) atau daftar nilai (null_values) di target_field yang menandakan bahwa kolom yang direferensikan adalah null.
  • non_null_value atau non_null_values: (Opsional) Menentukan nilai tunggal (non_null_value) atau daftar nilai (non_null_values) di target_field untuk memberi sinyal bahwa kolom yang direferensikan bukan null. Jika dihilangkan, nilai apa pun selain null_value atau null_values akan diperlakukan sebagai bukan null. Setidaknya salah satu dari null_value(s) atau non_null_value(s) harus ditentukan.
  • Mengecualikan atau mempertahankan kolom indikator null: Secara default, kolom indikator null dipertahankan sebagai kolom dalam skema output. Untuk menghilangkan kolom indikator null dari tabel output saat masih menggunakannya selama transcoding, tambahkan transformasi exclude untuk kolom indikator dalam array transformations (jangan terapkan pengubah filler ke kolom indikator null, karena filler akan melewati dekode kolom sepenuhnya).
  • Mengganti jenis kolom indikator: (Opsional) Untuk memaksa kolom indikator null didekode sebagai bytes atau binary, tambahkan aturan field_suffixes (atau field_overrides) non-inverse untuk kolom indikator dengan "modifier": { "bytes": {} } atau "modifier": { "binary": {} }. Untuk bytes, nyatakan null_value dan non_null_value sebagai string heksadesimal (misalnya, "FF" atau "00").

Contoh

Dalam contoh berikut, COL1-NID1 dan FIELD-NID2 dikecualikan dari tabel output setelah dievaluasi sebagai indikator null, sedangkan COL2-NULL dipertahankan dalam skema output.

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

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

Dukungan untuk kolom DBCS

Saat menggunakan kolom DBCS (PIC G atau PIC N dengan USAGE DISPLAY-1), pastikan hal berikut:

  • Kolom PIC G harus menentukan USAGE DISPLAY-1 secara eksplisit.
  • Kolom PIC N tanpa klausa USAGE ditetapkan secara default ke USAGE NATIONAL (UTF-16BE). Untuk memperlakukan kolom PIC N sebagai kolom DBCS, tentukan USAGE DISPLAY-1 di copybook (atau ganti encoding-nya dalam konfigurasi transcoder).
  • Secara default, kolom USAGE DISPLAY-1 didekode dan dienkode menggunakan himpunan karakter DBCS cp300 (x-IBM300), yang mengharapkan byte DBCS mentah tanpa karakter kontrol shift-out (0x0E) dan shift-in (0x0F).
  • Untuk menggunakan himpunan karakter DBCS yang berbeda (seperti Cp834) atau himpunan karakter multi-byte (MBCS) yang menggunakan byte shift-out (0x0E) dan shift-in (0x0F) (seperti 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, atau x-IBM1364), konfigurasikan pengubah kolom string dalam konfigurasi transcoder (--transcode-configuration).

Anda dapat menetapkan encoding DBCS secara global untuk semua kolom USAGE DISPLAY-1 menggunakan defaults.dbcs, atau untuk kolom tertentu menggunakan field_overrides atau field_suffixes:

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

Dukungan untuk string karakter dengan panjang variabel

Parser copybook mendukung kolom grup string karakter dengan panjang variabel menggunakan pengubah kolom varlen dalam konfigurasi transcoder:

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

Saat menggunakan pengubah kolom varlen, pastikan hal berikut:

  • Terapkan pengubah varlen ke item grup (misalnya, VAR-GRP) menggunakan field_overrides atau field_suffixes dalam konfigurasi transcoder:

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

  • Item grup harus berisi tepat dua subkolom:

    1. Subkolom pertama harus didekode menjadi bilangan bulat 64-bit (LONG, seperti kolom bilangan bulat desimal biner COMP atau zoned) yang menentukan panjang byte data string.
    2. Subkolom kedua harus berupa kolom string yang tidak diubah (seperti PIC X(n), PIC N(n), atau PIC U(n)).

  • Tidak diperlukan akhiran subkolom tertentu (seperti -LEN atau -TEXT), dan kolom yang dihasilkan dalam skema output menggunakan nama item grup (VAR-GRP).

Kolom dan konstruksi yang tidak didukung

Bagian berikut menjelaskan kolom dan konstruksi yang tidak didukung oleh parser copybook.

Konstruksi COBOL yang tidak didukung

Parser copybook dapat mengurai konstruksi COBOL berikut, meskipun konstruksi ini tidak didukung. Jika Anda menggunakan konstruksi ini dalam copybook, Mainframe Connector akan menampilkan error:

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

Jenis data yang tidak didukung

Jenis USAGE berikut dapat diurai oleh tata bahasa, tetapi tidak didukung oleh compiler copybook:

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