Menjalankan Mainframe Connector dalam mode mandiri

Halaman ini membahas cara menginstal Mainframe Connector di Cloud Run, mentranskode data, menyimpannya ke BigQuery, dan mengekspornya dari BigQuery.

Mainframe Connector versi 5.13.0 dan yang lebih baru mendukung menjalankan Mainframe Connector sebagai tugas mandiri di Google Cloud. Fitur ini memungkinkan Anda menjalankan Mainframe Connector sebagai tugas batch dalam container, misalnya, sebagai tugas Cloud Run, tugas Google Kubernetes Engine, atau dalam container Docker. Opsi ini membantu Anda menghindari penginstalan Mainframe Connector secara lokal di mainframe, dan mempermudah Anda mengintegrasikan penguraian file metode akses berurutan (QSAM) yang diantrekan mainframe ke alur kerja ekstrak, transformasi, dan muat (ETL) yang ada.

Saat menggunakan Mainframe Connector versi mandiri, Anda harus menyiapkan alur kerja ETL yang memuat file QSAM ke Google Cloud sendiri.

Sebelum memulai

  • Deploy Mainframe Connector di Cloud Run.
  • Buat akun layanan atau identifikasi akun layanan yang ada untuk digunakan dengan Mainframe Connector. Akun layanan ini harus memiliki izin untuk mengakses bucket Cloud Storage, set data BigQuery, dan resource Google Cloud lain yang ingin Anda gunakan.
  • Pastikan akun layanan yang Anda buat diberi peran Cloud Run Invoker.
  • Pastikan data mainframe sudah tersedia di Google Cloud sebagai file QSAM.

Mentranskode data menggunakan Mainframe Connector dalam mode mandiri di Cloud Run

Mainframe Connector menyediakan dua cara untuk menjalankan Mainframe Connector sebagai tugas mandiri di Google Cloud:

Keuntungan perintah qsam

Perintah qsam memberikan keuntungan berikut:

  • Mendukung jenis data gabungan, termasuk klausa OCCURS (daftar), klausa REDEFINES, dan kumpulan data bertingkat. Untuk mengetahui informasi selengkapnya tentang jenis data ini, lihat referensi transcoding qsam.
  • Mendukung konfigurasi proses transcoding melalui file konfigurasi transcoder. Kemampuan ini menawarkan fleksibilitas yang lebih besar saat mendekode data ke Google Cloud, dan mengenkode data kembali ke mainframe.
  • Mendukung pembuatan set data pelimpahan, yang merupakan tabel error transkode yang dapat digunakan untuk pemeriksaan error.
  • Mendukung beberapa format input dan output. Dengan kemampuan ini, Anda dapat memuat data ke dan dari berbagai gudang data.

Menjalankan Mainframe Connector dalam mode mandiri menggunakan perintah qsam

Untuk mentranskode data menggunakan Mainframe Connector dalam mode mandiri menggunakan perintah qsam, ikuti langkah-langkah berikut:

  1. Buat file YAML dengan perintah untuk melakukan hal berikut:

    Set data input harus berupa file QSAM dengan panjang rekaman tetap atau variabel. Anda dapat menggunakan contoh file YAML berikut untuk membaca set data, mentranskode ke format ORC, dan menguploadnya ke Cloud Storage.

    Dalam contoh berikut, kita menggunakan DataPath Cloud Storage untuk INFILE, OUTFILE, COPYBOOK, dan TRANSCODE_CONFIGURATION.

    environmentVariables:
- name: "INFILE"
  value: "INFILE"
- name: "OUTFILE"
  value: "OUTFILE"
- name: "COPYBOOK"
  value: "COPYBOOK"
- name: "TRANSCODE_CONFIGURATION"
  value: "TRANSCODE_CONFIGURATION"
- name: "LOG_PROJECT"
  value: "LOG_PROJECT"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"

command:
  qsam decode $INFILE $OUTFILE
  --copybook $COPYBOOK
  --transcode-configuration ${TRANSCODE_CONFIGURATION}
  --output-format orc
  --parallelism 8
  --chunk-size "512Mib"

    Ganti kode berikut:

    • INFILE: Nama file input.
    • OUTFILE: Nama file output.
    • COPYBOOK_PATH: Jalur ke DD copybook.
    • TRANSCODE_CONFIGURATION_PATH: Jalur ke file konfigurasi transkode.
    • LOG_PROJECT: Nama project log.

    Berikut adalah contoh file YAML:

    environmentVariables:
- name: "INFILE"
  value: "gs://my_bucket/my/input.dat"
- name: "OUTFILE"
  value: "gs://my_bucket/my/output.orc"
- name: "COPYBOOK"
  value: "gs://my_bucket/my/copybook.cpy"
- name: "TRANSCODE_CONFIGURATION"
  value: "gs://my_bucket/my/transcode-configuration-file.json"
- name: "LOG_PROJECT"
  value: "the log project"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
command:
  qsam decode $INFILE $OUTFILE
  --copybook $COPYBOOK
  --transcode-configuration ${TRANSCODE_CONFIGURATION}
  --output-format orc
  --parallelism 8
  --chunk-size "512Mib"

  2. Buat file job.yaml dengan perintah berikut.

    kind: Job
metadata:
  name: JOB
spec:
  template:
    spec:
      template:
        spec:
          containers:
          - image: IMAGE
            command:
            - bash
            - /opt/mainframe-connector/standalone.sh
            - --argsFrom
            - LOCATION_OF_THE_COMMAND_YAML_FILE

    Ganti kode berikut:

    • JOB: nama tugas Cloud Run Anda. Nama tugas harus terdiri dari 49 karakter atau kurang dan harus unik per region dan project.
    • IMAGE: URL image container tugas, misalnya, us-docker.pkg.dev/cloudrun/container/job:latest.
    • LOCATION_OF_THE_COMMAND_YAML_FILE: lokasi file YAML yang Anda buat pada langkah sebelumnya.

  3. Deploy tugas baru menggunakan perintah berikut:

    gcloud run jobs replace job.yaml

  4. Jalankan tugas menggunakan perintah berikut:

    gcloud run jobs execute JOB_NAME

    Ganti JOB_NAME dengan nama tugas.

Untuk mengetahui informasi selengkapnya tentang cara membuat dan menjalankan tugas Cloud Run, lihat Membuat tugas baru dan Menjalankan tugas.

Menjalankan Mainframe Connector dalam mode mandiri menggunakan perintah gsutil cp

Untuk mentranskode data menggunakan Mainframe Connector dalam mode mandiri menggunakan perintah gsutil cp, ikuti langkah-langkah berikut:

  1. Buat file YAML dengan perintah untuk melakukan hal berikut:

    • Membaca set data
    • Transkode ke ORC
    • Menguploadnya ke Cloud Storage

    Set data input harus berupa file QSAM dengan panjang rekaman tetap atau variabel. Anda dapat menggunakan contoh file YAML berikut untuk membaca set data, mentranskode ke format ORC, dan menguploadnya ke Cloud Storage.

    Dalam contoh berikut, baca data dari set data INFILE, dan tata letak data dari COPYBOOK DD.

    environmentVariables:
- name: "INFILE"
  value: "INFILE"
- name: "INFILE_DSN"
  value: "INFILE_DSN"
- name: "GCSDSNURI"
  value: "INFILE_DSN_FILEPATH"
- name: "COPYBOOK"
  value: "COPYBOOK_FILEPATH"
- name: "LOG_PROJECT"
  value: "LOG_PROJECT"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
command:
  gsutil cp gs://outputbucket/output
  --parallelism 8
  --maxChunkSize "512Mib"
  --parser_type=copybook

    Ganti kode berikut:

    • INFILE: Nama file input.
    • INFILE_DSN: Nama file Input Data Source Name (DSN).
    • INFILE_DSN_FILEPATH: Jalur ke file DSN input.
    • COPYBOOK_FILEPATH: Jalur ke DD copybook.
    • LOG_PROJECT: Nama project log.

    Berikut adalah contoh file YAML:

      environmentVariables:
  - name: "INFILE"
    value: "input.dat"
  - name: "INFILE_DSN"
    value: "input.dat"
  - name: "GCSDSNURI"
    value: "gs://inputbucket/inputfolder"
  - name: "COPYBOOK"
    value: "gs://inputbucket/copybook.cpy"
  - name: "LOG_PROJECT"
    value: "the log project"
  - name: "IBM_JAVA_OPTIONS"
    value: "-XX:+UseContainerSupport"
  command:
    gsutil cp gs://outputbucket/output
    --parallelism 8
    --maxChunkSize "512Mib"
    --parser_type=copybook

    Untuk mengetahui daftar lengkap variabel lingkungan yang didukung oleh Mainframe Connector, lihat Variabel lingkungan.

    Jika ingin mencatat perintah yang dijalankan selama proses ini, Anda dapat mengaktifkan statistik pemuatan.

  2. Buat file job.yaml dengan perintah berikut.

    kind: Job
metadata:
  name: JOB
spec:
  template:
    spec:
      template:
        spec:
          containers:
          - image: IMAGE
            command:
            - bash
            - /opt/mainframe-connector/standalone.sh
            - --argsFrom
            - LOCATION_OF_THE_COMMAND_YAML_FILE

    Ganti kode berikut:

    • JOB: nama tugas Cloud Run Anda. Nama tugas harus terdiri dari 49 karakter atau kurang dan harus unik per region dan project.
    • IMAGE: URL image container tugas, misalnya, us-docker.pkg.dev/cloudrun/container/job:latest.
    • LOCATION_OF_THE_COMMAND_YAML_FILE: lokasi file YAML yang Anda buat pada langkah sebelumnya.

  3. Deploy tugas baru menggunakan perintah berikut:

    gcloud run jobs replace job.yaml

  4. Jalankan tugas menggunakan perintah berikut:

    gcloud run jobs execute JOB_NAME

    Ganti JOB_NAME dengan nama tugas.

Untuk mengetahui informasi selengkapnya tentang cara membuat dan mengeksekusi tugas Cloud Run, lihat Membuat tugas baru dan Mengeksekusi tugas.

Mengekspor tabel BigQuery ke set data Mainframe

Anda dapat mengekspor tabel BigQuery ke set data mainframe dengan membuat file YAML yang menjalankan pembacaan SQL dari file QUERY DD, dan mengekspor set data yang dihasilkan ke Cloud Storage sebagai file biner, sebagai berikut.

Langkah-langkah untuk membuat dan menjalankan tugas Cloud Run sama seperti yang disebutkan di bagian Mentranskode data menggunakan Mainframe Connector dalam mode mandiri di Cloud Run. Satu-satunya perbedaan adalah petunjuk yang disebutkan dalam file YAML. Mainframe Connector menyediakan dua cara untuk mengekspor tabel BigQuery:

  • Menggunakan perintah qsam (rilis 5.16.0 dan yang lebih baru)

  • Menggunakan perintah bq export

Menggunakan perintah qsam 

environmentVariables:
  - name: "QUERY"
    value: "QUERY_PATH"
  - name: "OUTFILE"
    value: "OUTFILE"
  - name: "COPYBOOK"
    value: "COPYBOOK_PATH"
  - name: "TRANSCODE_CONFIGURATION"
    value: "TRANSCODE_CONFIGURATION_PATH"
  - name: "PROJECT_ID"
    value: "PROJECT_ID"
  - name: "LOCATION"
    value: "LOCATION"
  - name: "LOG_PROJECT"
    value: "LOG_PROJECT"
  - name: "IBM_JAVA_OPTIONS"
    value: "-XX:+UseContainerSupport"
command:
qsam encode \
  $QUERY
  $OUTFILE
  --copybook ${COPYBOOK_PATH}
  --transcode-configuration ${TRANSCODE_CONFIGURATION_PATH}
  --input-format=BIGQUERY \
  --input-parameter project_id=${PROJECT_ID} \
  --input-parameter location=${LOCATION}

Ganti kode berikut:

  • QUERY_PATH: Kueri SQL yang akan dijalankan. Hasil kueri akan dienkode ke dalam file biner.
  • OUTFILE: Bucket Cloud Storage yang akan berisi file biner output.
  • COPYBOOK_PATH: Jalur ke DD copybook.
  • TRANSCODE_CONFIGURATION_PATH: Jalur ke file konfigurasi transkoder.
  • LOG_PROJECT: Nama project log.
  • PROJECT_ID: Project ID tempat Anda ingin menjalankan kueri.
  • LOCATION: Region atau multi-region tempat kueri akan dieksekusi. Sebaiknya jalankan kueri di lokasi yang dekat dengan data. Nilai defaultnya adalah AS.

Berikut adalah contoh file YAML:

environmentVariables:
- name: "QUERY"
  value: "gs://my_bucket/my/input.sql"
- name: "OUTFILE"
  value: "gs://my_bucket/my/output.orc"
- name: "COPYBOOK"
  value: "gs://my_bucket/my/copybook.cpy"
- name: "TRANSCODE_CONFIGURATION"
  value: "gs://my_bucket/my/transcode-configuration-file.json"
- name: "PROJECT_ID"
  value: "my-project"
- name: "LOCATION"
  value: "US"
- name: "LOG_PROJECT"
  value: "my-log-project"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
  command:
  qsam encode \
    $QUERY
    $OUTFILE
    --copybook ${COPYBOOK_PATH}
    --transcode-configuration ${TRANSCODE_CONFIGURATION_PATH}
    --input-format=BIGQUERY \
    --input-parameter project_id=${PROJECT_ID} \
    --input-parameter location=${LOCATION}

Menggunakan perintah bq export 

environmentVariables:
- name: "COPYBOOK"
  value: "COPYBOOK_FILEPATH"
- name: "LOG_PROJECT"
  value: "LOG_PROJECT"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
command:
  bq export --project_id="PROJECT_NAME" --location="LOCATION" --sql="select * from project.dataset.table" --bucket="BUCKET"

Ganti kode berikut:

  • COPYBOOK_FILEPATH: Jalur ke DD copybook.
  • LOG_PROJECT: Nama project log.
  • PROJECT_NAME: Nama project tempat Anda ingin menjalankan kueri.
  • LOCATION: Lokasi tempat kueri akan dieksekusi. Sebaiknya jalankan kueri di lokasi yang dekat dengan data.
  • BUCKET: URI Cloud Storage yang akan berisi file biner output.

Berikut adalah contoh file YAML:

environmentVariables:
- name: "COPYBOOK"
  value: "gs://inputbucket/copybook.cpy"
- name: "LOG_PROJECT"
  value: "my-log-project"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
command:
  bq export --project_id="my-project" --run_mode="gcsoutput" --location=US --sql="select * from project.dataset.table" --bucket="gs://outputbucket/data.dat"