Instal Mainframe Connector

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

Sebelum memulai

Instal Mainframe Connector

Untuk menginstal Mainframe Connector, ikuti langkah-langkah berikut:

  1. Download file JAR bawaan. Salin file mainframe-connector-shadow-VERSION-all.jar ke jalur yang ditentukan di bagian Java Classpath dari 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 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 kunci JSON yang tidak dimodifikasi file di sistem file, dengan encoding UTF-8 aslinya.

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

  4. Gunakan FTP dalam mode biner untuk mengupload file JAR yang Anda download pada langkah 1 untuk di lokasi berikut pada 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 BQSH JCL, BQSH_ROOT_LOGGER=DEBUG menunjukkan bahwa logging debug diaktifkan. Untuk menonaktifkan logging debug, berikan komentar pada baris tersebut atau setel variabel ke apa pun selain DEBUG.

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

    Untuk 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 JAR .
    • PROJECT_NAME dengan project yang lognya sedang dibuat 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 penyadapan TLS , atur properti sistem Java berikut dalam prosedur BQSH JCL.

    • 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 Anda menggunakan changeit sandi trust store default, Anda tidak perlu menetapkan properti sistem trustStorePassword. Kemampuan proxy disediakan oleh Apache HttpComponents HttpClient.

    Anda harus menggunakan format penyimpanan kepercayaan sertifikat yang didukung oleh Konektor Mainframe. {i>Certificate trust store<i} dapat disimpan di dalam format berikut:

    • PKCS12 (.p12): Mungkin berisi banyak sertifikat dan memerlukan sandi
    • JKS (.jks): Mungkin 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 direktori .pem dan Format .der yang ditemukan di direktori 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 memperbarui prosedur di SYSP.PROCLIB. Dengan cara ini, Anda dapat menghindari pembaruan JCL prosedur untuk menunjuk ke prosedur baru yang diperbarui selama pengujian.

Contoh prosedur BQSH JCL

Berikut adalah sampel prosedur BQSH JCL. Dalam prosedur ini, ENV simbolik digunakan untuk menunjuk ke pernyataan lingkungan standar Java dan ini dikhususkan untuk lingkungan Google Cloud. Dengan cara ini, Anda tidak perlu Prosedur BQSH untuk setiap lingkungan. Jika Anda ingin membuat perubahan untuk lingkungan tertentu, Anda hanya perlu memperbarui anggota tertentu itu di Lingkungan Google Cloud di library PARMLIB sistem. Misalnya, buat file JAR baru, gunakan versi Java IBM yang lain, 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
//STIN     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 bagaimana File kunci JSON dan file JAR software Mainframe Connector adalah yang 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