Menginstal Mainframe Connector di mainframe

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, ikuti langkah-langkah berikut:

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

    Penting

    Perhatikan 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 dengan mengonfigurasi variabel lingkungan saat menjalankan Mainframe Connector.

    Penggunaan Google Analytics tunduk pada Persyaratan Layanan dan Kebijakan Privasi Google Analytics. Dengan mendownload Mainframe Connector, Anda menyatakan 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 layanan Google Cloud 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 dimodifikasi di 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 dengan 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 pada 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 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 BQSH JCL berikut dan ganti variabel berikut.

    Dalam prosedur JCL BQSH, BQSH_ROOT_LOGGER=DEBUG menunjukkan bahwa logging debug diaktifkan. Untuk menonaktifkan logging debug, jadikan baris sebagai komentar atau setel variabel ke nilai selain DEBUG.

    Untuk mengonfigurasi Mainframe Connector agar menulis informasi logging ke Cloud Logging, tetapkan variabel lingkungan LOG_PROJECT dan LOG_ID seperti yang ditunjukkan dalam contoh berikut.

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

    • GKEY_FILE_PATH dengan jalur ke file kunci JSON yang dijelaskan di langkah 3.
    • JAR_FILE_PATH dengan jalur ke direktori yang berisi file JAR.
    • PROJECT_NAME dengan project yang lognya dibuat di Cloud Logging
    • LOG_ID_NAME dengan nama log
    //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
GOOGLE_DIR="JAR_FILE_PATH"
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
JH="/usr/lpp/java/J8.0_64"
export JAVA_HOME="$JH"
export PATH="/bin:$JH/bin"

# Log Level
export BQSH_ROOT_LOGGER=DEBUG

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

# Binary Data Sets
# Uncomment the line below 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
JL="$JH/lib"
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

  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 BQSH JCL 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 penyimpanan tepercaya default changeit, maka Anda tidak perlu menyetel properti sistem trustStorePassword. Kemampuan proxy disediakan oleh Apache HttpComponents HttpClient.

    Anda harus menggunakan format penyimpanan tepercaya 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 dipindai dan semua sertifikat dengan format .pem dan .der yang ditemukan di direktori ditambahkan sebagai sertifikat tepercaya. Anda harus memuat sertifikat PKCS12 atau JKS secara manual.

Jika perlu membuat perubahan pada prosedur JCL BQSH kapan saja, Anda dapat menyiapkan versi yang lebih baru di library prosedur (PROCLIB) lingkungan yang lebih rendah. 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 telah diupdate selama pengujian.

Contoh prosedur JCL BQSH

Berikut adalah contoh prosedur BQSH JCL. Dalam prosedur ini, simbol ENV digunakan untuk menunjuk ke pernyataan lingkungan standar Java dan khusus untuk lingkungan Google Cloud . Dengan cara ini, Anda tidak memerlukan beberapa prosedur BQSH untuk setiap lingkungan. Jika Anda ingin membuat perubahan untuk lingkungan tertentu, Anda hanya perlu memperbarui anggota tertentu di library PARMLIB lingkunganGoogle Cloud dalam sistem. Misalnya, buat file JAR baru, gunakan versi IBM Java yang berbeda, atau ubah 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