Referensi parser buku salinan

Mainframe Connector mendukung dua versi parser copybook:

  • Parser copybook native: Parser copybook native menerapkan parser berbasis ANTLR4, mendukung copybook COBOL, dan merupakan versi parser yang direkomendasikan.
  • Parser buku salinan lama: Parser buku salinan lama adalah parser versi lama yang memiliki dukungan untuk format buku salinan yang sangat terbatas.

Anda dapat menentukan parser yang ingin digunakan berdasarkan copybook. Untuk informasi selengkapnya tentang cara menentukan parser yang ingin Anda gunakan, lihat Menentukan parser copybook.

Parser buku salinan native

Parser buku salinan Native adalah versi terbaru parser dan digunakan secara default. Parser copybook native mengimplementasikan parser berbasis ANTLR4 dan mendukung copybook COBOL.

Bagian ini mencantumkan tugas pra-pemrosesan yang dilakukan oleh parser buku salinan Native. Panduan ini juga menguraikan jenis data yang didukung oleh parser copybook Native dan batasan penggunaannya.

Prapemrosesan

Sebelum mengurai buku salinan, parser buku salinan Native akan memproses data terlebih dahulu dan melakukan tugas berikut:

  • Menghapus baris komentar.
  • Menyelesaikan kelanjutan baris.
  • Menghapus area nomor baris dan area kolom 73.
  • Mempertahankan pernyataan khusus preprocessor seperti EJECT, SPACE, dan TITLE. Kolom ini diuraikan, tetapi diabaikan. Buku salinan yang berisi parameter preprocessor yang dapat digunakan oleh COPY REPLACING tidak didukung oleh parser buku salinan Native. Dalam buku salinan ini, ID diapit oleh titik dua (:).

Jenis data dan batasan yang didukung

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

  • Tingkat 66 (ALIAS) atau 77 (STANDALONE) tidak didukung.
  • Hanya gunakan kolom GAMBAR. Kolom PICTURE berikut didukung:
    • Pic A, Pic, B, Pic G (DBCS), Pic N (nasional atau DBCS), Pic U (UTF8), Pic X, dan desimal zona (presisi maksimum 38, skala maksimum 38)
  • IBM Hexadecimal floating point (HFP) didukung.
  • REDEFINES tidak didukung.
  • Hanya gunakan kolom COMP berikut. ALIGN dan OCCURS tidak didukung.
    • COMP
    • COMP4
    • BINARY
    • COMP3
    • PACKED-DECIMAL
  • DATE dan TIMESTAMP didukung.
  • Indikator null didukung.
  • Kolom Set karakter dua byte (DBCS) Pic G dan Pic N didukung dan harus digunakan, bukan Pic T, yang sekarang tidak digunakan lagi. Untuk menggunakan kolom Pic N sebagai DBCS tanpa menentukan USAGE DISPLAY-1, Anda harus menetapkan variabel lingkungan NSYMBOL ke DBCS. Secara default, NSYMBOL ditetapkan ke NATIONAL yang menetapkan USAGE NATIONAL ke kolom Pic N yang tidak memiliki klausa USAGE. Perhatikan bahwa NSYMBOL hanya dapat ditetapkan ke NATIONAL atau DBCS.
  • String karakter dengan panjang variabel didukung.
  • Klausa SIGN didukung.
  • Anda harus meratakan semua kolom dan menggunakan satu tingkat indentasi.
  • Komentar didukung.

Dukungan untuk kolom tanggal dan stempel waktu

Mainframe Connector mendukung pemindahan data tanggal dan stempel waktu masuk dan keluar dari BigQuery. Untuk melakukannya, Anda harus menentukan variabel lingkungan yang dimulai dengan kata SUFFIX dalam format berikut:

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

Daftar berikut menjelaskan format secara lebih mendetail:

  • SUFFIX_SUFFIX_STRING: Variabel lingkungan yang dapat Anda gunakan untuk menentukan data tanggal dan stempel waktu. Nama SUFFIX_STRING sesuai dengan akhiran -SUFFIX_STRING atau _SUFFIX_STRING yang harus ditafsirkan sebagai tanggal atau stempel waktu saat digunakan sebagai akhiran nama kolom dalam buku salinan. Pastikan SUFFIX_STRING tidak berisi tanda hubung atau garis bawah.
  • command: Menentukan dekoder yang harus digunakan untuk mengurai kolom. Perintah yang didukung adalah date-converter dan timestamp-converter.
  • --format: Parameter yang menentukan format tanggal atau stempel waktu. Anda dapat menentukan maksimal lima format berbeda yang dipisahkan dengan koma. Jika beberapa format dapat cocok dengan input tertentu, format pertama yang cocok akan digunakan untuk dimuat ke BigQuery. Jika beberapa format ditentukan untuk ekspor, hanya format pertama yang akan digunakan. Untuk mengetahui informasi selengkapnya tentang format yang valid, lihat Format tanggal dan stempel waktu yang didukung.
  • --timezone: Parameter opsional untuk jenis TIMESTAMP. Secara default, zona waktunya adalah UTC. Untuk mengetahui informasi selengkapnya tentang format zona waktu yang didukung, lihat Format zona waktu yang didukung.
  • --omitsuffix (Opsional): Jika parameter ini ditentukan, -SUFFIX_STRING atau _SUFFIX_STRING akan dihapus dari nama kolom yang muncul di BigQuery.

Untuk menambahkan alias untuk SUFFIX_SUFFIX_STRING, Anda dapat menetapkan variabel lingkungan SUFFIX_SUFFIX_ALIAS=$SUFFIX_SUFFIX_STRING.

Contoh:

  • Jika Anda menentukan variabel lingkungan sebagai SUFFIX_DT8="date-converter --format yyyyMMdd", kolom dengan akhiran -DT8 atau _DT8 akan menjadi kolom jenis DATE di BigQuery, dan polanya akan menjadi yyyyMMdd.
  • Jika Anda menentukan variabel lingkungan sebagai SUFFIX_DT10="date-converter --format MM-dd-yyyy", kolom dengan akhiran -DT10 atau _DT10 akan menjadi kolom jenis DATE di BigQuery, dan polanya akan menjadi MM-dd-yyyy.
  • Jika Anda menentukan variabel lingkungan sebagai SUFFIX_DT="date-converter --format 'MM-dd-yyyy,MM/dd/yyyy'", kolom dengan akhiran -DT atau _DT akan menjadi kolom jenis DATE di BigQuery, dan polanya akan berupa MM-dd-yyyy atau MM/dd/yyyy.
  • Jika Anda menentukan dua variabel lingkungan sebagai SUFFIX_TIMESTAMP="timestamp-converter --format yyyy-MM-dd SUFFIX_TIMESTAMP=timestamp-converter --format 'yyyy-MM-dd HH.mm.ss.SSSSSS' --timezone America/New_York" dan SUFFIX_TS=$SUFFIX_TIMESTAMP, kolom dengan salah satu akhiran berikut: -TIMESTAMP, _TIMESTAMP, -TS, atau _TS akan menjadi kolom jenis TIMESTAMP di BigQuery, dan polanya akan yyyy-MM-dd HH:mm:ss.SSSSSS dengan zona waktu America/New_York.

Dukungan untuk indikator null

Mainframe Connector mendukung indikator null mulai dari versi 5.13.0. Untuk menggunakan indikator null, Anda harus menentukan variabel lingkungan yang dimulai dengan kata SUFFIX dalam format berikut:

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

NULL_INDICATOR_NAME sesuai dengan akhiran -NULL_INDICATOR_NAME atau _NULL_INDICATOR_NAME yang ditafsirkan sebagai indikator null saat digunakan sebagai akhiran nama kolom dalam buku salinan.

Daftar berikut menjelaskan parameter yang dapat Anda gunakan dengan variabel lingkungan ini:

  • command: Nilainya harus null-indicator.
  • –null-value: Nilai null indicator menandakan bahwa kolom yang dirujuk adalah null. Nilai --null-value harus berupa string atau angka desimal.
  • –not-null-value: (Opsional) Jika ditentukan, nilai null indicator akan menandakan bahwa kolom yang dirujuk bukan null. Jika parameter ini tidak ditetapkan, nilai apa pun yang bukan –value-null akan diterima. Nilai –not-null-value harus berupa string atau angka desimal.
  • –keep: (Opsional) Jika ditentukan, kolom null-indicator akan disimpan sebagai kolom dalam format file Optimized Row Columnar (ORC). Secara default, kolom ini tidak disimpan dalam format ORC.
  • -force-type: (Opsional) Mendukung dua opsi -- bytes dan binary yang memaksa kolom didekode sebagai byte atau biner. Untuk byte, nilai untuk null dan not-null dinyatakan sebagai HEX (misalnya, FA3AB5). Konstanta HIGH dan LOW tersedia yang setara dengan semua FF atau semua 00. Untuk biner, nilainya adalah bilangan bulat reguler.

Jika null-indicator tidak memiliki kolom yang dirujuk, Mainframe Connector akan menampilkan pesan error dan berhenti memproses file.

Contoh:

Cuplikan buku catatan

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

Definisi variabel lingkungan

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.

Dukungan untuk kolom DBCS

Pastikan hal berikut saat menggunakan kolom DBCS:

  • Saat menggunakan kolom DBCS PIC G atau Pic N, Anda harus memberikan salah satu enkode set karakter multi-byte (MBCS) yang valid berikut di opsi encoding atau di variabel lingkungan ENCODING saat menggunakan perintah gsutil cp atau bq export:
    • 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
  • Jika kolom copybook hanya berisi byte DBCS, tetapi byte ini tidak dikelilingi oleh shift-out (0x0E) dan shift-in (0x0F), Anda harus menambahkan akhiran _DBCS ke nama kolom untuk memastikan bahwa byte ini didekode sebagai byte DBCS.

Misalnya, jika data Anda yang sesuai dengan kolom salinan 03 FLD01 PIC N USAGE DISPLAY-1 berisi byte 0x43 dan 0xC5 dalam encoding x-IBM930 yang tidak diapit oleh 0x0E dan 0x0F, Anda harus mengganti nama kolom salinan menjadi 03 FLD01-DBCS PIC N USAGE DISPLAY-1 agar dapat mendekode data DBCS dengan benar.

Dukungan untuk string karakter dengan panjang variabel

Parser buku salinan Native mendukung kolom struct berikut:

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

Kolom pertama di kolom struct adalah panjang kolom kedua, yaitu kolom string. Anda mungkin harus menambahkan beberapa padding ke akhir data berdasarkan panjang data seperti yang ditunjukkan pada gambar berikut.

Padding ditambahkan ke string karakter dengan panjang variabel.
Gambar 1. Padding ditambahkan ke string karakter dengan panjang variabel.

Mainframe Connector menghapus akhiran dari nama variabel sebelum menyimpan data di BigQuery. Dalam contoh ini, nama variabelnya adalah var.

Untuk menggunakan kolom struct, tetapkan variabel lingkungan BQSH_FEATURE_VARIABLE_LENGTH_ENABLED ke yes atau true.

Saat menggunakan kolom struct, pastikan hal berikut:

  • Akhiran parameter pertama di struct adalah -LEN. Jika ingin menggunakan akhiran yang berbeda, Anda harus menetapkan variabel lingkungan BQSH_FEATURE_VARIABLE_LENGTH_LEN_SUFFIX ke akhiran yang ingin digunakan.
  • Akhiran parameter kedua di struct adalah -TEXT. Jika ingin menggunakan akhiran yang berbeda, Anda harus menetapkan variabel lingkungan BQSH_FEATURE_VARIABLE_LENGTH_LEN_SUFFIX ke akhiran yang ingin digunakan.

Kolom dan konstruksi yang tidak didukung

Bagian berikut menjelaskan kolom dan konstruksi yang tidak didukung oleh

Konstruksi COBOL

Konstruksi COBOL meskipun konstruksi ini tidak didukung. Jika Anda menggunakan konstruksi ini di buku salinan, Konektor Mainframe akan menampilkan error.

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

Jenis data

Jenis data COBOL seperti COMP-1 dan COMP-2 didukung.

Parser copybook lama

Parser copybook lama adalah parser versi lama yang mendukung fitur non-COBOL. Jika Anda menggunakan buku salinan berbasis DSL, parser lama mungkin lebih cocok karena parser buku salinan Native dapat menyebabkan error.

Anda dapat menggunakan DD buku salinan dengan batasan berikut:

  • Tingkat 66 (ALIAS) atau 77 (STANDALONE) tidak didukung.
  • REDEFINES tidak didukung.
  • Baris komentar tidak didukung.
  • Kolom dengan panjang 10 yang namanya diakhiri dengan DATE atau DT adalah tanggal. Dekode berbeda untuk kolom tersebut.
  • Hanya gunakan kolom COMP berikut. ALIGN dan OCCURS tidak didukung.
    • COMP
    • COMP4
    • BINARY
    • COMP3
    • PACKED-DECIMAL
  • Hanya gunakan kolom GAMBAR. Tentukan kolom PICTURE di baris yang sama, langsung setelah nama kolom.
  • Anda harus meratakan semua kolom dan menggunakan satu tingkat. Komentar tidak didukung.
  • Pastikan kolom 1 hingga 6 selalu berisi spasi kosong.