Mainframe Connector をインストールする

Mainframe Connector は、MVS バッチジョブのコンテキスト内で Java 仮想マシン(JVM)プロセスとして起動されます。Mainframe Connector は通常、JVM に付属の IBM ライブラリ以外の必要な依存関係を含む JAR ファイルを使用してデプロイされます。 以降のセクションでは、Mainframe Connector のインストール プロセスについて詳しく説明します。

始める前に

  • Mainframe Connector の初期設定を完了します。 初期設定には、サービス アカウントに必要なロールの付与、アセットのセキュリティの設定、メインフレームと Google Cloud 間のネットワーク接続の設定が含まれます。
  • Java V8 を構成します。
  • JZOS Batch Launcher と Toolkit をインストールします。

Mainframe Connector をインストールする

Mainframe Connector をインストールする手順は次のとおりです。

  1. ビルド済みの JAR ファイルをダウンロードします。ステップ 7 に示す BQSH ジョブ制御言語(JCL)プロシージャの Java Classpath セクションで指定されるパスに、mainframe-connector-shadow-VERSION-all.jar ファイルをコピーします。 VERSION は、Mainframe Connector のバージョンです。

  2. メインフレームから Google Cloud サービスにアクセスするには、サービス アカウント キーを JSON キーファイルとして作成してダウンロードする必要があります。JSON キーファイルの作成の詳細については、サービス アカウント キーを作成するをご覧ください。

  3. バイナリ転送モードでファイル転送プロトコル(FTP)を使用して、JSON キーファイルを Unix ファイル システムにコピーします。変更されていない JSON キーファイルを、元の UTF-8 エンコードでファイル システムに保存してください。

    IBM z/OS Unix ファイル システムに JSON キーファイルを格納するためのデフォルトのパスはありません。サービス アカウントにアクセスする権限を持つユーザーのみが読み取り可能なパスを選択する必要があります。JSON キーファイルが正しく転送されると、UNIX System Services(USS)から読み取ることはできません。

  4. バイナリモードで FTP を使用して、手順 1 でダウンロードした JAR ファイルをメインフレームの次の場所にアップロードします。

     /opt/google/mainframe-connector/VERSION/
    

    Version は、JAR ファイルのバージョンに置き換えます。

    これは、JAR ファイルをデプロイするための推奨パスです。サイト管理者が選択したパスを使用することもできます。

  5. 次のコマンドを実行して、JAR ファイルが正しく転送されたことを確認します。-t オプションを使用すると、JAR ファイルの内容が一覧表示されます。

     jar -tvf JAR_FILE_NAME
    

    JAR_FILE_NAME は、JAR ファイルの名前に置き換えます。

  6. 次の BQSH JCL プロシージャのコピーを作成し、以下の変数を置き換えます。

    BQSH JCL プロシージャで BQSH_ROOT_LOGGER=DEBUG は、デバッグ ロギングが有効であることを示します。デバッグ ロギングを無効にするには、行をコメントアウトするか、変数を DEBUG 以外に設定します。

    ロギング情報を Cloud Logging に書き込むように Mainframe Connector を構成するには、次の例に示すように LOG_PROJECT 環境変数と LOG_ID 環境変数を設定します。

    Mainframe Connector でサポートされている環境変数の一覧については、環境変数をご覧ください。

    • GKEY_FILE_PATH は、手順 3 で説明する JSON キーファイルへのパスに置き換えます。
    • JAR_FILE_PATH は、JAR ファイルを含むディレクトリへのパスに置き換えます。
    • PROJECT_NAME は、Cloud Logging でログが作成されるプロジェクトに置き換えます
    • LOG_ID_NAME は、ログの名前に置き換えます。
    //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. TLS インターセプト プロキシと連携するように Mainframe Connector を構成するには、BQSH JCL プロシージャで次の Java システム プロパティを設定します。

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

    IBM_JAVA_OPTIONS の Java システム プロパティを追加する前の BQSH JCL プロシージャは次のとおりです。

    # 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. デフォルトのトラストストア パスワード changeit を使用している場合は、trustStorePassword システム プロパティを設定する必要はありません。 プロキシ機能は Apache HttpComponents HttpClient によって提供されます。

    Mainframe Connector でサポートされている証明書トラストストア形式を使用する必要があります。証明書トラストストアは、次の形式で保存できます。

    • PKCS12(.p12): 多くの証明書が含まれている可能性があり、パスワードが必要です
    • JKS(.jks): 多くの証明書が含まれる可能性があり、パスワードが必要です
    • PEM(.pem): base64 としてエンコードされた証明書が多数含まれている可能性があります。
    • バイナリ(.der): ファイルごとに 1 つの証明書が含まれます。

    trustStore システム プロパティがディレクトリへのパスである場合は、ディレクトリがスキャンされ、ディレクトリ内で検出される .pem および .pem 形式のすべての証明書が信頼できる証明書として追加されます。 PKCS12 証明書または JKS 証明書は手動で読み込む必要があります。

BQSH JCL プロシージャを変更する必要がある場合は、下位環境のプロシージャ ライブラリ(PROCLIB)に新しいバージョンをステージングできます。このライブラリはシステム ライブラリ SYSP.PROCLIB の前に追加されるため、SYSP.PROCLIB のプロシージャを更新する前に、下位環境に対して変更を検査できます。これにより、テスト中に新しい更新されたプロシージャを指すように JCL プロシージャを更新するのを回避できます。

BQSH JCL サンプル プロシージャ

以下に、BQSH JCL のサンプル プロシージャを示します。このプロシージャでは、ENV シンボリックを使用して Java スタンダード環境ステートメントを指定します。これは Google Cloud 環境に固有のものです。この場合、環境ごとに複数の BQSH プロシージャは必要ありません。特定の環境に変更を加える場合は、Google Cloud 環境のシステム PARMLIB ライブラリでそのメンバーを更新するだけです。たとえば、新しい JAR ファイルの作成、別の IBM Java バージョンの使用、環境ステートメントを使用して JSON キーファイルの変更を行います。

#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

次に、JSON キーファイルと Mainframe Connector ソフトウェアの JAR ファイルを参照する方法を示す DEV PARMLIB メンバーの例を示します。

# 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

次のステップ