Perintah Mainframe Connector API

Tabel berikut mencantumkan perintah BigQuery, Cloud Storage, danGoogle 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.

Catatan: Sebaiknya gunakan perintah qsam decode dan qsam encode untuk melakukan tugas ini. Untuk mengetahui informasi tentang keuntungan menggunakan perintah qsam, lihat Keuntungan perintah qsam.

Perintah bq export mendukung beberapa kemampuan pengoptimalan performa. Untuk mengetahui informasi selengkapnya, lihat Peningkatan performa untuk perintah bq export. Anda dapat menggunakan set karakter yang disesuaikan dengan perintah bq export. Untuk mengetahui informasi selengkapnya, lihat Menggunakan set karakter yang disesuaikan.

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

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

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

Beberapa hasil kueri dapat menampilkan sejumlah besar baris, terkadang hingga 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. 		Ya
Gunakan perintah ini untuk menghapus resource BigQuery secara permanen. Karena perintah ini menghapus resource secara permanen, sebaiknya Anda menggunakannya dengan hati-hati. Tidak
Perintah Cloud Run Gunakan perintah ini untuk memicu tugas Cloud Run dari Mainframe Anda. Tidak
Gunakan perintah ini untuk melihat log eksekusi tugas Cloud Run tertentu. Tidak
Gunakan perintah ini untuk membatalkan tugas Cloud Run. 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 tanpa diubah sebagai bagian dari pipeline data. Secara opsional, Anda dapat mengonversi encoding karakter dari extended binary coded decimal interchange code (EBCDIC) ke ASCII UTF-8, dan menambahkan jeda baris.

Catatan: Sebaiknya gunakan perintah copy text untuk melakukan tugas ini karena perintah tersebut memberikan kemampuan yang lebih baik.

Anda juga dapat menggunakan perintah ini untuk menyalin kode sumber aplikasi yang ditentukan dalam bahasa kontrol tugas (JCL). 		Tidak
Utilitas gsutil Gunakan perintah ini untuk mentranskode set data dan menuliskannya ke Cloud Storage dalam format file Optimized Row Columnar (ORC). Perintah membaca data dari INFILE DD, dan tata letak rekaman dari file COPYBOOK.

Catatan: Sebaiknya gunakan perintah qsam decode dan qsam encode untuk melakukan tugas ini. Untuk mengetahui informasi tentang keuntungan menggunakan perintah qsam, lihat Keuntungan perintah qsam.

Jika Anda ingin perintah membaca data dari file Nama Sumber Data (DSN), gunakan tanda berikut:
  • --inDsn: DSN set data input. Jika diberikan, flag ini akan menggantikan DD INFILE.
  • --cobDsn: DSN copybook. Jika diberikan, tanda ini akan menggantikan COPYBOOK DD.
Kemudian, perintah akan membuka sejumlah koneksi paralel yang dapat dikonfigurasi ke Cloud Storage API dan mentranskode set data COBOL ke format file ORC kolom yang dikompresi GZIP. 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 akan disalin terlebih dahulu ke Cloud Storage oleh Mainframe Connector, lalu panggilan prosedur jarak jauh (RPC) dilakukan untuk menginstruksikan layanan gRPC agar mentranskode file.

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

Catatan: Sebaiknya gunakan perintah qsam decode dan qsam encode untuk melakukan tugas ini. Untuk mengetahui informasi tentang keuntungan menggunakan perintah qsam, lihat Keuntungan perintah qsam.

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

Utilitas gszutil berfungsi dengan server gRPC, yang membantu Anda mengurangi konsumsi juta instruksi per detik (MIPS). Sebaiknya gunakan utilitas gszutil di lingkungan produksi Anda untuk mengonversi file biner di Cloud Storage ke format ORC. 		Tidak
Perintah qsam dan vsam Gunakan perintah ini untuk mentranskode rekaman file QSAM ke format yang Anda inginkan menggunakan argumen --output-format. File QSAM asli dibagi menjadi beberapa bagian berdasarkan nilai yang Anda tentukan dengan argumen --max-chunk-size. Output yang ditranskode disimpan di jalur target sebagai file yang diurutkan secara leksikografis. Tidak
Gunakan perintah ini untuk mengonversi data dari sumber eksternal ke file QSAM. Input ditentukan oleh nilai yang Anda tentukan menggunakan argumen --input-format. Tidak
Gunakan perintah ini untuk mentranskode rekaman file Virtual Storage Access Method (VSAM) ke format yang Anda inginkan menggunakan argumen --output-format. File VSAM asli dibagi menjadi beberapa bagian berdasarkan nilai yang Anda tentukan dengan argumen --max-chunk-size. Output yang ditranskode disimpan di jalur target sebagai file yang diurutkan secara leksikografis. Tidak
Perintah Pub/Sub Gunakan perintah ini untuk memublikasikan pesan ke topik Pub/Sub. Tidak
Perintah lainnya Gunakan perintah ini untuk menyalin set data biner dari jalur sumber ke jalur tujuan. Tidak
copy text
 Gunakan perintah ini untuk menyalin file ke lokasi penyimpanan pilihan Anda, seperti Cloud Storage, dan sebaliknya. Tidak
Gunakan perintah ini untuk membuat permintaan HTTP ke layanan web atau REST API. Tidak
Gunakan perintah ini untuk memicu eksekusi template flex Dataflow. Perintah ini menjalankan tugas dari jalur template flex yang ditentukan. Untuk informasi selengkapnya, lihat gcloud dataflow flex-template run. 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 tanda yang Anda gunakan, perintah systemreport mencetak data sistem berikut:
  • --supported_ciphers: Cipher yang didukung
  • --available_security_providers: Penyedia keamanan yang tersedia
 Tidak

Menggunakan set karakter yang disesuaikan

Mainframe Connector mendukung berbagai himpunan karakter yang mendekode byte menjadi string BigQuery, dan sebaliknya. Mainframe Connector memungkinkan Anda mengonfigurasi charset kustom Anda sendiri. Anda dapat mengonfigurasi set karakter yang disesuaikan dengan membuat file Pemetaan Karakter Unicode (UCM). Mainframe Connector 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 set karakter yang disesuaikan, tentukan file konfigurasi dalam format UCM. Anda dapat menggunakan set karakter yang disesuaikan ini dengan perintah gsutil cp atau bq export dengan menyetel tanda --encoding=charset.

Saat membuat set karakter yang disesuaikan, verifikasi hal berikut:

  • Saat menentukan file UCM, perhatikan hal berikut:
    • Mainframe Connector hanya mendukung set karakter yang disesuaikan menggunakan set karakter byte tunggal (SBCS).
    • Mainframe Connector hanya mendukung indikator presisi UCM |0.
    • Pastikan file UCM berada di z/OS Unix System Services (USS), bukan di set data yang dipartisi multiple virtual storage (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).
  • Menyediakan pemetaan eksplisit untuk setiap kemungkinan nilai byte tunggal ke karakter Unicode. Jika Anda tidak yakin karakter Unicode mana yang ingin dipetakan 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 dua arah, yaitu, saat Anda memuat data ke BigQuery dan kemudian mengekspornya kembali ke file biner, outputnya mungkin berbeda dari input aslinya.
  • Pastikan urutan byte di kolom kedua bersifat unik. Jika beberapa urutan byte dipetakan ke karakter Unicode yang sama, karakter Unicode ini didekode ke urutan byte dari pemetaan terakhir yang ditentukan dalam file UCM.
  • Pastikan Mainframe Connector dapat menemukan file UCM dengan menetapkan variabel lingkungan BQSH_FEATURE_CUSTOM_CHARSET ke jalur file UCM. Jika Anda ingin menggunakan beberapa set karakter, Anda dapat memberikan jalur ke beberapa set karakter yang dipisahkan oleh pemisah titik koma. Misalnya, BQSH_FEATURE_CUSTOM_CHARSET=path1;path2. path dapat mengarah ke file lokal atau ke 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 set karakter yang disesuaikan 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) Tetapkan aliran baca maksimum. Nilai defaultnya sama dengan nilai yang ditetapkan untuk exporter_thread_count.
  • order_response: (Opsional) Jika Anda menyetel tanda ini ke benar (true), pengekspor akan mempertahankan urutan hasil kueri. Flag ini memengaruhi performa pengeksporan. Nilai defaultnya adalah false.
  • max_read_queue: (Opsional) Tetapkan jumlah maksimum antrean rekaman baca. Nilai defaultnya adalah dua kali jumlah thread.
  • transcoding_buffer: (Opsional) Tetapkan ukuran buffer transkode per thread dalam MB. Nilai defaultnya adalah 20 MB.

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

Membuat tabel BigQuery dari copybook

Anda dapat menggunakan perintah bq mk untuk membuat tabel BigQuery langsung dari parsing copybook COBOL. Parser copybook native mengekstrak nilai default dari klausa VALUE dalam copybook, 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 copybook yang akan digunakan untuk membuat tabel.
  • --dry_run: (Opsional) Jika diaktifkan, perintah hanya mencetak perintah CREATE TABLE SQL yang dihasilkan tanpa mengeksekusinya. Flag ini ditetapkan ke 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.

Klausul 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  "     "

Klausul 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

Lakukan uji coba perintah gsutil cp

Perintah gsutil cp mendekode file QSAM menggunakan copybook 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 copybook atau file data COBOL dan memeriksa apakah 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 kembalian 0. Jika ada masalah, pesan error akan ditampilkan.

Saat Anda menggunakan tanda dry_run, semua statistik seperti total byte yang dibaca, jumlah rekaman yang ditulis, total error, akan dicatat.

Jika Anda menggunakan tanda dry_run dan sumber data tidak ada, perintah tidak akan menampilkan error. Sebagai gantinya, hanya memeriksa parser copybook dan kemudian 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 tanda --replace ke perintah.

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

Ganti kode berikut:

  • GCS_URI: URI (uniform resource identifier) Cloud Storage dari file Cloud Storage. Contoh, gs://bucket/sample.mainframe.dsn.
  • DSN: Lokasi tujuan DSN di Mainframe.
  • RECFM: Format rekaman (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 dianggap dalam format rekaman panjang tidak ditentukan (U).
  • BLKSIZE: (Opsional) Ukuran blok file. Jika disetel 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 disetel 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 penyetelan performa berikut untuk perintah gsutil cp.

  • Gunakan tanda --parallelism untuk menetapkan jumlah thread. Nilai defaultnya adalah 1 (berulir tunggal).
  • Gunakan argumen --maxChunkSize untuk menetapkan ukuran maksimum setiap chunk. Setiap bagian akan memiliki file ORC-nya sendiri. Tingkatkan nilai ini untuk mengurangi jumlah potongan yang dibuat dengan biaya persyaratan memori yang lebih besar selama proses transcoding. Untuk mengetahui detailnya, lihat Mengurai 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 sedang 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 besar dan menggunakan 8 thread saat kecepatan saluran 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 penyelesaian objek Cloud Storage. Untuk file kecil, penggunaan lebih sedikit thread dan potongan yang lebih kecil dapat menghasilkan hasil yang lebih baik.

Mengurai argumen maxChunkSize

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

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