Referensi Mainframe Connector API

Tabel berikut mencantumkan perintah BigQuery, Cloud Storage, dan Google Cloud lainnya yang dapat Anda gunakan dengan Mainframe Connector.

Produk Perintah Deskripsi Mendukung transcoding jarak jauh
Perintah BigQuery Gunakan perintah ini untuk membuat file biner. Perintah ini menerima COPYBOOK DD sebagai input.

Perintah bq export mendukung beberapa kemampuan penyesuaian performa. Untuk informasi selengkapnya, lihat Peningkatan performa untuk perintah bq export.

Anda dapat menggunakan kumpulan karakter yang disesuaikan dengan perintah bq export. Untuk informasi selengkapnya, lihat Menggunakan set karakter yang disesuaikan.

Catatan: Perintah bq export akan menolak permintaan untuk mengekspor tabel Bigtable yang besar. Untuk menghindari error, tambahkan flag -allowLargeResults ke perintah bq export saat Anda ingin mengekspor tabel berukuran besar.		 Ya
Gunakan perintah ini untuk memuat data ke dalam tabel. Untuk mengetahui informasi selengkapnya, lihat bq load. Tidak
Gunakan perintah ini untuk membuat resource BigQuery, seperti tabel bawaan atau tabel eksternal, yang memerlukan penyiapan partisi dan pengelompokan. Untuk informasi selengkapnya, lihat bq mk.

Anda juga dapat menggunakan perintah bq mk untuk membuat tabel BigQuery langsung dari mengurai copybook COBOL. Untuk mengetahui informasi selengkapnya, lihat Membuat tabel BigQuery dari buku salinan. 		Tidak
Gunakan perintah ini untuk membuat tugas kueri yang menjalankan kueri SQL yang ditentukan. Perintah ini membaca kueri SQL dari flag --sql atau dari QUERY DD. Jika keduanya disediakan, kueri dalam tanda --sql akan diprioritaskan.

Gunakan tanda --follow=true untuk membuat laporan yang menampilkan hasil kueri tertentu. Untuk menulis laporan ini ke file di mainframe, tentukan pernyataan DD AUDITL yang mengarah ke file yang akan berisi laporan log audit. Jangan gunakan flag --follow jika Anda menginginkan perilaku logging normal.

Beberapa hasil kueri dapat menampilkan banyak baris, terkadang jutaan. Agar output tetap dapat dibaca manusia, jumlah baris yang ditampilkan dibatasi. Untuk mengontrol jumlah baris yang ditampilkan, gunakan flag --report_row_limit. Misalnya, gunakan --report_row_limit 10 untuk membatasi hasil hingga 10 baris. Secara default, jumlah baris yang ditampilkan dibatasi hingga 30.

Untuk menggunakan parameterisasi bq query, lihat parameterisasi kueri bq.

Untuk mengetahui informasi selengkapnya, lihat kueri bq. 		Ya
Gunakan perintah ini untuk menghapus resource BigQuery secara permanen. Karena perintah ini menghapus resource secara permanen, sebaiknya gunakan perintah ini dengan hati-hati. Untuk informasi selengkapnya, lihat bq rm. Tidak
Perintah Cloud Storage Gunakan perintah ini untuk menyalin data teks atau biner ke Cloud Storage. Anda dapat menggunakan mode salinan biner sederhana untuk menyalin set data dari IBM z/OS ke Cloud Storage yang tidak dimodifikasi sebagai bagian dari pipeline data. Atau, Anda dapat mengonversi encoding karakter dari kode pertukaran desimal kode biner yang diperluas (EBCDIC) ke ASCII UTF-8, dan menambahkan baris baru.

Anda juga dapat menggunakan perintah ini untuk menyalin kode sumber aplikasi yang ditentukan dalam job control language (JCL). 		Tidak
Utilitas gsutil Gunakan perintah ini untuk mentranskode set data dan menulisnya ke Cloud Storage dalam format file Optimized Row Columnar (ORC). Perintah ini membaca data dari INFILE DD, dan tata letak data dari file COPYBOOK. Jika Anda ingin perintah membaca data dari file Nama Sumber Data (DSN), gunakan flag berikut:
  • --inDsn: DSN set data input. Jika diberikan, flag ini akan mengganti INFILE DD.
  • --cobDsn: DSN buku salinan. Jika diberikan, tanda ini akan mengganti COPYBOOK DD.


Kemudian, perintah ini akan membuka sejumlah koneksi paralel yang dapat dikonfigurasi ke Cloud Storage API dan mentranskode set data COBOL ke format file ORC yang dikompresi GZIP dan kolom. Anda dapat mengharapkan rasio kompresi sekitar 35%.

Secara opsional, Anda dapat menggunakan perintah ini untuk berinteraksi dengan layanan gRPC Mainframe Connector yang berjalan di VM di mainframe. Untuk melakukannya, tetapkan variabel lingkungan SRVHOST dan SRVPORT, atau berikan nama host dan nomor port menggunakan opsi command line. Saat layanan gRPC digunakan, set data input pertama kali disalin ke Cloud Storage oleh Mainframe Connector, lalu panggilan prosedur jarak jauh (RPC) dilakukan untuk menginstruksikan layanan gRPC untuk mentranskode file.

Anda juga dapat melakukan tugas berikut dengan perintah gsutil cp: 		Ya
Gunakan perintah ini untuk menghapus bucket atau objek dalam bucket. Untuk mengetahui informasi selengkapnya, lihat rm - Menghapus objek. Tidak
Utilitas gszutil Utilitas gszutil berjalan menggunakan IBM JZOS Java SDK dan menyediakan emulator shell yang menerima pemanggilan command line gsutil dan BigQuery menggunakan JCL.

Utilitas gszutil memperluas fungsi utilitas gsutil dengan menerima skema dalam bentuk COPYBOOK DD, menggunakannya untuk mentranskode set data COBOL langsung ke ORC sebelum mengupload ke Cloud Storage. Utilitas gszutil juga memungkinkan Anda menjalankan BigQuery query dan load menggunakan JCL.

Utilitas gszutil berfungsi dengan server gRPC, yang membantu Anda mengurangi konsumsi satu juta petunjuk per detik (MIPS). Sebaiknya gunakan utilitas gszutil di lingkungan produksi untuk mengonversi file biner di Cloud Storage ke format ORC. 		Tidak
Perintah Lainnya Gunakan perintah ini untuk mengirim pesan ke topik Pub/Sub. Anda dapat memberikan pesan menggunakan command line, atau menggunakan set data. Tidak
Gunakan perintah ini untuk memicu eksekusi template flex Dataflow. Perintah ini menjalankan tugas dari jalur template fleksibel yang ditentukan. Untuk mengetahui informasi selengkapnya, lihat gcloud dataflow flex-template run. Tidak
Gunakan perintah ini untuk membuat permintaan HTTP ke layanan web atau REST API. Tidak
Gunakan perintah ini untuk mencetak data sistem yang diperlukan ke output standar (stdout). Hal ini memungkinkan tim dukungan Mainframe Connector mengumpulkan informasi yang diperlukan untuk mendiagnosis masalah tanpa memerlukan interaksi pelanggan yang ekstensif.
Berdasarkan flag yang Anda gunakan, perintah systemreport akan mencetak data sistem berikut:
  • --supported_ciphers: Cipher yang didukung
  • --available_security_providers: Penyedia keamanan yang tersedia
 Tidak

Menggunakan kumpulan karakter yang disesuaikan

Konektor Mainframe mendukung berbagai set karakter yang mendekode byte menjadi string BigQuery, dan sebaliknya. Konektor Mainframe memungkinkan Anda mengonfigurasi set karakter kustom Anda sendiri. Anda dapat mengonfigurasi kumpulan karakter kustom dengan mem-build file Unicode Character Mapping (UCM). Konektor Mainframe mendukung subset format UCM berikut:

<code_set_name>               "<name>"
<uconv_class>                 "SBCS"
<subchar>                     \x1A #Example

CHARMAP
#_______ _________
<U0000> \x00 |0       #For the third column, only 0 is supported.
<U0001> \x01 |0
#etc
END CHARMAP

Jika Anda ingin menggunakan kumpulan karakter yang disesuaikan, tentukan file konfigurasi dalam format UCM. Anda dapat menggunakan kumpulan karakter yang disesuaikan ini dengan perintah gsutil cp atau bq export dengan menetapkan tanda --encoding=charset.

Saat membuat kumpulan karakter yang disesuaikan, pastikan hal berikut:

  • Saat menentukan file UCM, perhatikan hal berikut:
    • Konektor Mainframe hanya mendukung himpunan karakter yang disesuaikan menggunakan himpunan karakter byte tunggal (SBCS).
    • Konektor Mainframe hanya mendukung indikator presisi UCM |0.
    • Pastikan file UCM berada di z/OS Unix System Services (USS) dan bukan di beberapa set data partisi penyimpanan virtual (MVS PDS).
    • Pastikan file UCM disimpan dalam format American Standard Code for Information Interchange (ASCII), bukan dalam format Extended Binary Coded Decimal Interchange Code (EBCDIC).
  • Berikan pemetaan eksplisit untuk setiap kemungkinan nilai byte tunggal ke karakter Unicode. Jika Anda tidak yakin karakter Unicode mana yang ingin Anda petakan ke byte, sebaiknya petakan ke U+FFFD. Anda dapat memetakan urutan byte yang berbeda ke karakter Unicode yang sama. Namun, dalam kasus ini, pemetaan tidak bersifat dua arah, yaitu, saat Anda memuat data ke BigQuery, lalu mengekspornya kembali ke file biner, output-nya mungkin berbeda dari input asli.
  • Pastikan urutan byte di kolom kedua bersifat unik. Jika beberapa urutan byte dipetakan ke karakter Unicode yang sama, karakter Unicode ini akan didekode ke urutan byte dari pemetaan terakhir yang ditentukan dalam file UCM.
  • Pastikan Konektor Mainframe dapat menemukan file UCM dengan menetapkan variabel lingkungan BQSH_FEATURE_CUSTOM_CHARSET ke jalur file UCM. Jika ingin menggunakan beberapa kumpulan karakter, Anda dapat memberikan jalur ke beberapa kumpulan karakter yang dipisahkan oleh pemisah titik koma. Misalnya, BQSH_FEATURE_CUSTOM_CHARSET=path1;path2. path dapat mengarah ke file lokal atau file yang disimpan di Cloud Storage. Jika Anda menjalankan perintah gsutil cp atau bq export dengan tanda --remote untuk melakukan transcoding jarak jauh, Mainframe Connector akan menggunakan nilai lokal yang ditetapkan untuk variabel lingkungan BQSH_FEATURE_CUSTOM_CHARSET. Hal yang sama berlaku saat Anda menjalankan Mainframe Connector dalam mode mandiri. Jika tanda --encoding merujuk pada kumpulan karakter kustom yang tidak sesuai dengan nilai yang Anda tetapkan untuk BQSH_FEATURE_CUSTOM_CHARSET (atau jika Anda belum menetapkan BQSH_FEATURE_CUSTOM_CHARSET sama sekali), perintah akan keluar dengan pesan error.

Konfigurasi penyesuaian performa untuk perintah bq export

Mainframe Connector mendukung konfigurasi penyesuaian performa berikut untuk perintah bq export:

  • exporter_thread_count: (Opsional) Menetapkan jumlah thread pekerja. Nilai defaultnya adalah 4.
  • max_read_streams: (Opsional) Menetapkan aliran baca maksimum. Nilai defaultnya sama dengan nilai yang ditetapkan untuk exporter_thread_count.
  • order_response: (Opsional) Jika Anda menetapkan tanda ini ke benar, eksportir akan mempertahankan urutan hasil kueri. Flag ini memengaruhi performa ekspor. Nilai defaultnya adalah false.
  • max_read_queue: (Opsional) Tetapkan jumlah maksimum antrean data baca. Nilai defaultnya adalah dua kali jumlah thread.
  • transcoding_buffer: (Opsional) Tetapkan ukuran buffering transcoding per thread dalam MB. Nilai defaultnya adalah 20 MB.

Perhatikan bahwa Anda juga dapat mencoba meningkatkan ukuran jendela transpor dengan menetapkan variabel lingkungan OVERRIDE_GRPC_WINDOW_MB untuk meningkatkan performa. Ukuran jendela default adalah 4 MB.

Membuat tabel BigQuery dari buku salinan

Anda dapat menggunakan perintah bq mk untuk membuat tabel BigQuery langsung dari mengurai copybook COBOL. Parser buku salinan native mengekstrak nilai default dari klausa VALUE dalam buku salinan, dan menetapkannya ke kolom yang sesuai dalam tabel BigQuery yang baru dibuat.

Untuk membantu Anda menguji fitur ini, perintah bq mk juga menyediakan mode uji coba. Mode ini memungkinkan Anda melihat pratinjau perintah CREATE TABLE SQL yang dihasilkan tanpa benar-benar membuat tabel di BigQuery.

Perintah bq mk menyediakan opsi konfigurasi berikut untuk mendukung fitur ini:

  • --schema_from_copybook: Menentukan buku salinan yang akan digunakan untuk membuat tabel.
  • --dry_run: (Opsional) Jika diaktifkan, perintah hanya akan mencetak perintah CREATE TABLE SQL yang dihasilkan tanpa mengeksekusinya. Flag ini ditetapkan ke salah (false) secara default.
  • --tablespec "[PROJECT_ID]:[DATASET].[TABLE]": Menentukan ID project, set data, dan nama tabel BigQuery untuk tabel target.
  • --encoding: Menentukan encoding yang digunakan untuk membaca file copybook. Nilai defaultnya adalah CP037.

Klausa VALUE berikut didukung:

VAR1   PIC 9(5) VALUE 55.
*-- Set VAR1 to 55
VAR1   PIC X(5) VALUE aaaa. Set VAR1 to aaaa
VAR1   PIC 9(3) COMP VALUE 3. Set VAR1 to 3 (binary)
VAR1   PIC [9(5), X(5)] VALUE <literal>. Set VAR1 to <literal>
VAR1   PIC [9(5), X(5)] VALUE ZERO. Set VAR1 to 0 or "0"
VAR1   PIC [9(5), X(5)] VALUE ZEROS. Set VAR1 to 0 or "00000"
VAR1   PIC [9(5), X(5)] VALUE ZEROES. Set VAR1 to 0 or "00000"
VAR1   PIC X(5) VALUE SPACE. Set VAR1 to  " "
VAR1   PIC X(5) VALUE SPACES. Set VAR1 to  "     "

Klausa HIGH-VALUE dan LOW-VALUE hanya didukung untuk variabel alfanumerik.

VAR1   PIC X(5) VALUE HIGH-VALUE. Set VAR1 to `X"FF "
VAR1   PIC X(5) VALUE HIGH-VALUES. Set VAR1 to 0 or `X"FFFFFFFFFF"
VAR1   PIC X(5) VALUE LOW-VALUE. Set VAR1 to `X"00" (NULL)
VAR1   PIC X(5) VALUE LOW-VALUES. Set VAR1 to `X"0000000000" (NULL)
VAR1   PIC X(5) VALUE QUOTE. Set VAR1 to `"`
VAR1   PIC X(5) VALUE `QUOTES`. Set VAR1 to 0 or `""""`
VAR1   PIC [9(5), X(5)] VALUE NULL. Not defined and won't be supported
VAR1   PIC [9(5), X(5)] VALUE ALL <literal>. Set all fields with the value ALL to <literal>

Parameterisasi bq query

Mainframe Connector memungkinkan Anda menggunakan kueri berparameter dengan bq query.

Berikut adalah contoh cara menggunakan kueri bq query berparameter:

File kueri

SELECT * FROM `bigquery-public-data.samples.wikipedia` WHERE title = @xtitle

Berikut adalah contoh dengan beberapa parameter.

File kueri

SELECT * FROM bigquery-public-data.samples.wikipedia WHERE title = @mytitle AND num_characters > @min_chars;

Contoh eksekusi

bq query \
--project_id=mainframe-connector-dev \
--location="US" \
--parameters=mytitle::Hippocrates,min_chars:INT64:42600

Melakukan uji coba perintah gsutil cp

Perintah gsutil cp mendekode file Metode Akses Serial Antrean (QSAM) menggunakan buku salinan COBOL, dan membuat file ORC di Cloud Storage. Anda dapat melakukan uji coba perintah gsutil cp menggunakan tanda dry_run dan menguji langkah-langkah berikut:

  • Mengurai file data atau copybook COBOL dan memeriksa apakah file tersebut kompatibel dengan Mainframe Connector.
  • Mendekode file QSAM tanpa menulisnya ke Cloud Storage.

Gunakan perintah berikut untuk melakukan uji coba:

gsutil cp \
--dry_run \
gs://result-dir

Jika semua langkah berhasil dieksekusi, perintah akan keluar dengan kode return 0. Jika terjadi masalah, pesan error akan ditampilkan.

Saat Anda menggunakan flag dry_run, semua statistik seperti total byte yang dibaca, jumlah data yang ditulis, total error, akan dicatat ke dalam log.

Jika Anda menggunakan tanda dry_run dan sumber data tidak ada, perintah tidak akan menampilkan error. Sebagai gantinya, hanya memeriksa parser copybook, lalu menyelesaikan eksekusi.

Menyalin file dari Cloud Storage ke Mainframe

Anda dapat menggunakan perintah gsutil cp untuk menyalin file dari Cloud Storage ke set data Mainframe. Perhatikan bahwa Anda tidak dapat menyalin set data yang dipartisi (PDS).

Untuk menyalin file dari Cloud Storage ke set data Mainframe, tentukan DSN dan persyaratan ruang file yang ingin Anda download ke Mainframe di JCL, seperti yang ditunjukkan dalam contoh berikut:

//OUTFILE  DD DSN=MAINFRAME.DSN.FILE,DISP=(,CATLG),
//            RECFM=FB,DSORG=PS,
//            SPACE=(10,(2,1),RLSE),
//            AVGREC=M,
//            UNIT=SYSDA
//SYSPRINT DD SYSOUT=*
//SYSDUMP  DD SYSOUT=*
//STDIN DD *

Tentukan perintah gsutil cp dalam format berikut. Jika file sudah ada di Mainframe, pastikan Anda menambahkan flag --replace ke perintah.

gsutil cp GCS_URI DSN --recfm=RECFM --lrecl=LRECL --blksize=BLKSIZE --noseek

Ganti kode berikut:

  • GCS_URI: ID resource (URI) seragam Cloud Storage dari file Cloud Storage. Contoh, gs://bucket/sample.mainframe.dsn.
  • DSN: Lokasi tujuan DSN di Mainframe.
  • RECFM: Format data (RECFM) file Mainframe. Nilai yang valid adalah F, FB, dan U. Perhatikan bahwa nilai ini tidak peka huruf besar/kecil.
  • LRECL: (Opsional) Panjang data (LRECL) file. Nilainya harus berupa bilangan bulat >= 0. Jika LRECL tidak ditentukan, file diasumsikan berada dalam format data dengan panjang tidak ditentukan (U).
  • BLKSIZE: (Opsional) Ukuran blok file. Jika ditetapkan ke 0, sistem akan menentukan ukuran blok yang optimal. Nilai harus berupa bilangan bulat >= 0. Jika Anda tidak menentukan nilai, file akan diperlakukan sebagai file yang tidak diblokir.
  • noseek: (Opsional) Sertakan parameter ini jika Anda ingin meningkatkan performa download. Flag ini ditetapkan ke salah (false) secara default, yaitu operasi pencarian diaktifkan.

Contoh eksekusi

gsutil cp gs://sample-bucket/MAINFRAME.DSN.FILE MAINFRAME.DSN.FILE \
--lrecl=16 --blksize=0 --recfm=fb

Konfigurasi penyesuaian performa untuk perintah gsutil cp

Mainframe Connector mendukung konfigurasi penyesuaian performa berikut untuk perintah gsutil cp.

  • Gunakan flag --parallelism untuk menetapkan jumlah thread. Nilai defaultnya adalah 1 (single threaded).
  • Gunakan argumen --maxChunkSize untuk menetapkan ukuran maksimum setiap bagian. Setiap bagian akan memiliki file ORC-nya sendiri. Tingkatkan nilai ini untuk mengurangi jumlah potongan yang dibuat dengan mengorbankan persyaratan memori yang lebih besar selama proses transcoding. Untuk mengetahui detailnya, lihat Menguraikan argumen maxChunkSize. Nilai defaultnya adalah 128 MiB.
  • Gunakan argumen --preload_chunk_count untuk menetapkan jumlah data yang akan dimuat sebelumnya ke memori saat semua pekerja sibuk. Argumen ini dapat meningkatkan performa dengan mengorbankan memori. Nilai defaultnya adalah 2.

Contoh eksekusi

gsutil cp \
  --replace \
  --parser_type=copybook \
  --parallelism=8 \
  --maxChunkSize=256MiB \
  gs://$BUCKET/test.orc

Dalam contoh ini, kita telah mempertimbangkan file berukuran besar sehingga telah menggunakan 8 thread saat kecepatan baris tercapai. Jika Anda memiliki memori yang cukup, sebaiknya tingkatkan ukuran potongan menjadi 256 MiB atau bahkan 512 MiB karena hal ini akan mengurangi overhead pembuatan dan menyelesaikan objek Cloud Storage. Untuk file kecil, menggunakan lebih sedikit thread dan bagian yang lebih kecil dapat menghasilkan hasil yang lebih baik.

Mengurai argumen maxChunkSize

Flag maxChunkSize menerima nilai dalam bentuk jumlah dan unit pengukuran, misalnya 5 MiB. Anda dapat menggunakan spasi kosong di antara jumlah dan magnitudo.

Anda dapat memberikan nilai dalam format berikut:

  • Format Java: b/k/m/g/t, masing-masing untuk byte, kibibyte, mebibyte, gibibyte, dan tebibyte
  • Format internasional: KiB/MiB/GiB/TiB, masing-masing untuk kibibyte, mebibyte, gibibyte, dan tebibyte
  • Format metrik: b/kb/mb/gb/tb, masing-masing untuk kilobyte, megabyte, gigabyte, dan terabyte

Penguraian ukuran data tidak peka huruf besar/kecil. Perhatikan bahwa Anda tidak dapat menentukan jumlah sebagian. Misalnya, gunakan 716 KiB, bukan 0,7 MiB.