Menginstal Mainframe Connector di mainframe Anda

Mainframe Connector diluncurkan sebagai proses Java virtual machine (JVM) dalam konteks tugas batch MVS. Mainframe Connector biasanya di-deploy menggunakan file JAR yang berisi beberapa dependensi yang diperlukan selain library IBM yang disertakan dengan JVM. Bagian berikut menjelaskan proses penginstalan Mainframe Connector secara mendetail.

Sebelum memulai

  • Selesaikan penyiapan awal untuk Mainframe Connector. Penyiapan awal mencakup pemberian peran yang diperlukan ke akun layanan Anda, menyiapkan keamanan untuk aset Anda, dan menyiapkan konektivitas jaringan antara mainframe dan Google Cloud.
  • Konfigurasi Java 8 atau Java 17.
  • Instal JZOS Batch Launcher and Toolkit (Java 8 atau Java 17).

Menginstal Mainframe Connector

Untuk menginstal Mainframe Connector, gunakan langkah-langkah berikut:

  1. Download file JAR Mainframe Connector yang telah dibuat sebelumnya ke direktori yang memiliki izin tulis untuk akun pengguna Anda.

    Penting

    Perlu diketahui bahwa Mainframe Connector menggunakan Google Analytics untuk mengumpulkan data penggunaan. Hal ini membantu kami meningkatkan kualitas software dan memberikan pengalaman pengguna yang lebih baik. Secara default, Google Analytics diaktifkan. Namun, Anda dapat memilih untuk tidak ikut serta dengan mengonfigurasi variabel lingkungan saat menjalankan Mainframe Connector.

    Penggunaan Google Analytics tunduk pada Google Analytics Persyaratan Layanan dan Kebijakan Privasi. Dengan mendownload Mainframe Connector, Anda mengakui bahwa Anda telah membaca, memahami, dan menyetujui persyaratan dan ketentuan.

    Download Batal

  2. Salin file mainframe-connector-shadow-VERSION-all.jar ke jalur yang ditentukan di bagian Java Classpath dari prosedur bahasa kontrol tugas (JCL) BQSH yang ditampilkan di langkah 8. VERSION adalah versi Mainframe Connector.

  3. Untuk mengakses Google Cloud layanan dari mainframe, Anda harus membuat dan mendownload kunci akun layanan sebagai file kunci JSON. Untuk mengetahui informasi selengkapnya tentang cara membuat file kunci JSON, lihat Membuat kunci akun layanan.

  4. Salin file kunci JSON ke sistem file Unix menggunakan protokol transfer file (FTP) dalam mode transfer biner. Pastikan Anda menyimpan file kunci JSON yang tidak diubah pada sistem file, dengan encoding UTF-8 aslinya.

    Tidak ada jalur default untuk menyimpan file kunci JSON di sistem file IBM z/OS Unix. Anda harus memilih jalur yang hanya dapat dibaca oleh pengguna yang memiliki izin untuk mengakses akun layanan. File kunci JSON tidak akan dapat dibaca dari UNIX System Services (USS) jika ditransfer dengan benar.

  5. Gunakan FTP dalam mode biner untuk mengupload file JAR yang Anda download di langkah 1 ke lokasi berikut di mainframe Anda.

     /opt/google/mainframe-connector/VERSION/

    Ganti Version dengan versi file JAR.

    Perhatikan bahwa ini adalah jalur yang direkomendasikan untuk men-deploy file JAR. Anda juga dapat menggunakan jalur apa pun yang dipilih oleh administrator situs.

  6. Jalankan perintah berikut untuk memvalidasi bahwa file JAR telah ditransfer dengan benar. Perhatikan bahwa opsi -t mencantumkan konten file JAR.

     jar -tvf JAR_FILE_NAME

    Ganti JAR_FILE_NAME dengan nama file JAR.

  7. Buat salinan prosedur JCL BQSH berikut.

    /BQSH PROC
//*******************************************************************
//*
//* Copyright 2022 Google LLC All Rights Reserved
//*
//* Licensed under the Apache License, Version 2.0 (the "License");
//* you may not use this file except in compliance with the License.
//* You may obtain a copy of the License at
//*
//*     http://www.apache.org/licenses/LICENSE-2.0
//*
//* Unless required by applicable law or agreed to in writing, software
//* distributed under the License is distributed on an "AS IS" BASIS,
//* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//* See the License for the specific language governing permissions and
//* limitations under the License.
//*
//*******************************************************************
//BQSH EXEC PGM=JVMLDM86,REGION=0M,
//  PARM='/+I com.google.cloud.bqsh.Bqsh'
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//STDOUT   DD SYSOUT=*
//STDERR   DD SYSOUT=*
//CEEDUMP  DD SYSOUT=*
//ABNLIGNR DD DUMMY
//STDIN    DD DUMMY
//QUERY    DD DUMMY
//INFILE   DD DUMMY
//COPYBOOK DD DUMMY
//KEYFILE  DD DUMMY
//STDENV   DD *,SYMBOLS=EXECSYS

# Service Account Keyfile
# Edit the line below to specify a unix filesystem path where
# the service account keyfile is stored.
# The service account should be granted Storage, BigQuery and Logging permissions.
export GKEYFILE="GKEY_FILE_PATH"

# Path to directory containing google jar file
# Edit this to set actual path selected for your site
# it's recommended to have a path with a version identifier
# and create a symlink to the directory of the latest version
export GOOGLE_DIR="JAR_FILE_PATH"
export GOOGLE_CLASSPATH="$GOOGLE_DIR/*"

# Do not modify the 3 lines below
# Collect system symbols from JES
export JOBNAME=&JOBNAME
export JOBDATE=&YYMMDD
export JOBTIME=&HHMMSS

# IBM JZOS JDK Location
export JAVA_HOME="/usr/lpp/java/J8.0_64"
export PATH="/bin:$JAVA_HOME/bin"

# Log Level
export BQSH_ROOT_LOGGER=DEBUG

# Cloud Logging
export LOG_PROJECT="PROJECT_NAME"
export LOG_ID="LOG_ID_NAME"

# Google Analytics
# Uncomment the following line to disable Google Analytics
#export DISABLE_ANALYTICS=True

# Binary Data Sets
# Uncomment the following line to set a default output bucket for scp.
# The DSN of the input file is used as the object name.
# this may greatly reduce effort across many job steps
#export GCSDSNURI="gs://[BUCKET]/[PREFIX]"

# Generational Data Sets
# Uncomment the line below to set a default output bucket for scp GDG datasets.
# The Cloud GDG feature emulates a GDG dataset in a versioned object.
# Cloud Storage objects take precedence over local DSN when this is set.
#export GCSGDGURI="gs://[BUCKET]/[PREFIX]"

# Uncomment the line below to set a default output bucket for the gszutil command.
#export GCSOUTURI="gs://[BUCKET]/[PREFIX]"

# Mainframe Connector gRPC service
# Uncomment and edit the lines below to set the Hostname or IP Address and
# port of the gRPC data set transcoding service.
# The gRPC service converts z/OS datasets to ORC format on VMs running in
# Google Cloud VPC. This is strongly recommended when processing high volumes
# of data.
#export SRVREMOTE=
#export SRVPORT=

# Native Libraries
export JL="$JH/lib"
export LP="/lib:/usr/lib:$JH/bin:$JL/s390x:$JL/s390x/j9vm:$JH/bin/classic"
export LIBPATH="$LP:/usr/lib/java_runtime64"

# Java Classpath
CP="$JL:$JL/ext:/usr/include/java_classes/*"
export CLASSPATH="$CP:$GOOGLE_CLASSPATH"

# JVM options
IJO="-Xms512m -Xmx512m -Xcompressedrefs -Djava.net.preferIPv4Stack=true"
export IBM_JAVA_OPTIONS="$IJO"
export JZOS_MAIN_ARGS=""
/*
// PEND

    Ganti kode berikut:

    • GKEY_FILE_PATH: jalur ke file kunci JSON yang dijelaskan di langkah 3.
    • JAR_FILE_PATH: jalur ke direktori yang berisi file JAR.
    • PROJECT_NAME: project tempat log dibuat di Cloud Logging.
    • LOG_ID_NAME: nama log.
    • Untuk menonaktifkan logging debug, beri komentar pada baris BQSH_ROOT_LOGGER=DEBUG.
    • Untuk mengonfigurasi Mainframe Connector agar menulis informasi logging ke Cloud Logging, tetapkan variabel lingkungan LOG_PROJECT dan LOG_ID.
    • Untuk menonaktifkan Google Analytics, tetapkan variabel lingkungan DISABLE_ANALYTICS ke True.

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

  8. Untuk mengonfigurasi Mainframe Connector agar berfungsi dengan proxy yang mencegat TLS, tetapkan properti sistem Java berikut dalam prosedur JCL BQSH.

    • javax.net.ssl.trustStore
    • javax.net.ssl.trustStorePassword
    • https.proxyHost
    • https.proxyUser
    • https.proxyPassword

    Prosedur JCL BQSH sebelum menambahkan properti sistem Java untuk IBM_JAVA_OPTIONS adalah sebagai berikut.

    # JVM options
IJO="-Xms512m -Xmx512m -Xcompressedrefs -Djava.net.preferIPv4Stack=true"
export IBM_JAVA_OPTIONS="$IJO"
 ```

The BQSH JCL procedure after adding the Java system properties for
<code>IBM_JAVA_OPTIONS</code> is as follows.

```none
# JVM options
IJO="-Xms512m -Xmx512m -Xcompressedrefs -Djava.net.preferIPv4Stack=true"
IJO="$IJO -Djavax.net.ssl.trustStore=/path/to/cacerts"
IJO="$IJO -Djavax.net.ssl.trustStorePassword=notasecret"
IJO="$IJO -Dhttp.proxyHost=proxy.example.com"
IJO="$IJO -Dhttp.proxyUser=username"
IJO="$IJO -Dhttp.proxyPassword=password"
export IBM_JAVA_OPTIONS="$IJO"
 ```

  9. Jika Anda menggunakan sandi trust store default changeit, maka Anda tidak perlu menetapkan properti sistem trustStorePassword. Kemampuan proxy disediakan oleh Apache HttpComponents HttpClient.

    Anda harus menggunakan format trust store sertifikat yang didukung oleh Mainframe Connector. Trust store sertifikat dapat disimpan dalam format berikut:

    • PKCS12 (.p12): Dapat berisi banyak sertifikat dan memerlukan sandi
    • JKS (.jks): Dapat berisi banyak sertifikat dan memerlukan sandi
    • PEM (.pem): Dapat berisi banyak sertifikat yang dienkode sebagai base64
    • Biner (.der): Berisi satu sertifikat per file

    Jika properti sistem trustStore adalah jalur ke direktori, direktori akan dipindai dan semua sertifikat dengan format .pem dan .der yang ditemukan di direktori akan ditambahkan sebagai sertifikat tepercaya. Anda harus memuat sertifikat PKCS12 atau JKS secara manual.

Jika Anda perlu melakukan perubahan pada prosedur JCL BQSH kapan saja, Anda dapat menyiapkan versi yang lebih baru di lingkungan yang lebih rendah library prosedur (PROCLIB). Library ini ditambahkan sebelum library sistem, SYSP.PROCLIB, sehingga perubahan dapat diperiksa terhadap lingkungan yang lebih rendah sebelum memperbarui prosedur di SYSP.PROCLIB. Dengan cara ini, Anda dapat menghindari pembaruan prosedur JCL untuk mengarah ke prosedur baru yang diperbarui selama pengujian.

Contoh prosedur JCL BQSH

Berikut adalah contoh prosedur JCL BQSH. Dalam prosedur ini, simbol ENV digunakan untuk mengarah ke pernyataan lingkungan standar Java dan khusus untuk Google Cloud lingkungan. Dengan cara ini, Anda tidak memerlukan beberapa prosedur BQSH untuk setiap lingkungan. Jika ingin melakukan perubahan untuk a lingkungan tertentu, Anda hanya perlu memperbarui anggota tertentu di dalam Google Cloud lingkungan dalam library PARMLIB sistem. Misalnya, membuat file JAR baru, menggunakan versi IBM Java yang berbeda, atau mengubah file kunci JSON menggunakan pernyataan lingkungan.

#BQSH PROC ENV=DEV
//
//******************************************************************
//*
//* Copyright 2022 Google LLC All Rights Reserved
//*
//* Licensed under the Apache License, Version 2.0 (the "License");
//* you may not use this file except in compliance with the License.
//* You may obtain a copy of the License at
//*      http://www.apache.org/licenses/LICENSE-2.0
//* Unless required by applicable law or agreed to in writing , software
//* distributed under the License is distributed on as "AS IS" BASIS,
//* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express of impl.
//* See the license for the specific language governing permissions and
//* limitations under the License.
//*
//******************************************************************
//BQSH EXEC PGM=JVMLDM86,REGION=0M,
//  PARM='/+I com.google.cloud.bqsh.Bqsh'
//SYSPRINT DD SYSOUT = *
//SYSOUT   DD SYSOUT = *
//STDOUT   DD SYSOUT = *
//STDERR   DD SYSOUT = *
//CEEDUMP  DD SYSOUT = *
//ABNLIGNR DD DUMMY
//STDIN    DD DUMMY
//QUERY    DD DUMMY
//INFILE   DD DUMMY
//COPYBOOK DD DUMMY
//KEYFILE  DD DUMMY
//STDENV   DD DISP=SHR,DSN=SYSP.PARMLIB(EDW&ENV)
//         DD *,SYMBOLS=EXECSYS
# Do not modify the 3 lines below
# Collect system symbols from JES
export JOBNAME=&JOBNAME
export JOBDATE=&YYMMDD
export JOBTIME=&HHMMSS

Berikut adalah contoh anggota DEV PARMLIB yang menunjukkan cara file kunci JSON dan file JAR software Mainframe Connector direferensikan.

# Service Account Keyfile
# Edit the line below to specify a unix filesystem path where
# the service account keyfile is stored.
# The service account should be granted Storage, BigQuery and Logging pe
GKPATH= "/opt/google/keyfile"
GKFILE= "prj-ent-edw-dev-landing-2451-f89d99af31e5.json"
export GKEYFILE= "$GKPATH/$GKFILE"

# Path  to directory containing google jar file
# Edit this is set actual path selected for your site
# its recommended to have a path with a version identifier
# and create a symlink to the directory of the latert version
GOOGLE_DIR= "/opt/google/mainframe-connector/5.9.0"
GOOGLE_CLASSPATH= "$GOOGLE_DIR/*"

#IBM JZOS JDK Location
JH= "/usr/lpp/java/J8.0_64"
export JAVA_HOME= "$JH"
export PATH= "/bin:$JH/bin"

# Log Level
export BQSH_ROOT_LOGGER=DEBUG

Langkah berikutnya