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 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 diubah sebagai bagian dari pipeline data. Secara opsional, 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:
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 million instructions per second (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:
|
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 perintahgsutil cp
ataubq export
dengan tanda--remote
untuk melakukan transcoding jarak jauh, Mainframe Connector akan menggunakan nilai lokal yang ditetapkan untuk variabel lingkunganBQSH_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 untukBQSH_FEATURE_CUSTOM_CHARSET
(atau jika Anda belum menetapkanBQSH_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 untukexporter_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 perintahCREATE 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 adalahCP037
.
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 dianggap 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 argumenmaxChunkSize
. 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 linier 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.