Menginstal Mainframe Connector di mainframe

Konektor Mainframe diluncurkan sebagai proses Java Virtual Machine (JVM) dalam konteks tugas batch MVS. Konektor Mainframe 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 detail.

Sebelum memulai

Menginstal Mainframe Connector

Untuk menginstal Konektor Mainframe, gunakan langkah-langkah berikut:

  1. Download file JAR bawaan. Salin file mainframe-connector-shadow-VERSION-all.jar ke jalur yang ditentukan di bagian Java Classpath dalam prosedur job control language (JCL) BQSH yang ditampilkan di langkah 7. VERSION adalah versi Mainframe Connector.

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

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

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

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

  6. Buat salinan prosedur JCL BQSH berikut dan ganti variabel berikut.

    Dalam prosedur JCL BQSH, BQSH_ROOT_LOGGER=DEBUG menunjukkan bahwa logging debug diaktifkan. Untuk menonaktifkan logging debug, komentari baris atau tetapkan variabel ke 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 tempat log 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
LOG_PROJECT="PROJECT_NAME"
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

  7. Untuk mengonfigurasi Mainframe Connector agar berfungsi dengan proxy yang mengintersepsi 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"
 ```

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

    Anda harus menggunakan format truststore sertifikat yang didukung oleh Mainframe Connector. Truststore 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 perlu melakukan perubahan pada prosedur JCL BQSH kapan saja, Anda dapat melakukan staging 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 mengupdate 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 lingkungan Google Cloud. Dengan cara ini, Anda tidak memerlukan beberapa prosedur BQSH untuk setiap lingkungan. Jika ingin membuat perubahan untuk lingkungan tertentu, Anda hanya perlu memperbarui anggota tertentu tersebut di lingkungan Google Cloud di library PARMLIB 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 selanjutnya