在主機上安裝 Mainframe Connector

Mainframe Connector 會在 MVS 批次作業的環境中，以 Java 虛擬機器 (JVM) 程序的形式啟動。通常，Mainframe Connector 會使用 JAR 檔案部署，其中包含 JVM 隨附的 IBM 程式庫以外的一些必要依附元件。以下各節將詳細說明 Mainframe Connector 安裝程序。

事前準備

• 完成 Mainframe Connector 的初始設定。初始設定包括授予服務帳戶必要角色、設定資產安全性，以及設定大型主機與 Google Cloud之間的網路連線。
• 設定 Java 8 或 Java 17。
• 安裝 JZOS Batch Launcher 和 Toolkit (Java 8 或 Java 17)。

安裝 Mainframe Connector

如要安裝 Mainframe Connector，請按照下列步驟操作：

1. 將預先建構的 Mainframe Connector JAR 檔案下載至使用者帳戶具有寫入權限的目錄。

   重要事項

   請注意，Mainframe Connector 會使用 Google Analytics 收集使用資料。這有助於我們改善軟體，提供更優質的使用體驗。Google Analytics 預設為啟用。 不過，您可以在執行 Mainframe Connector 時設定環境變數，選擇不使用這項功能。
   
   使用 Google Analytics 時，請務必遵守《Google Analytics 服務條款和隱私權政策》。 下載 Mainframe Connector 即表示您已詳閱、瞭解並接受條款及細則。

   下載 取消

2. 將 mainframe-connector-shadow-VERSION-all.jar 檔案複製到 BQSH job control language (JCL) 程序中「Java Classpath」部分指定的路徑 (如步驟 8 所示)。VERSION 是 Mainframe Connector 的版本。

3. 如要從大型主機存取 Google Cloud 服務，您必須建立並下載服務帳戶金鑰 (JSON 金鑰檔案)。如要進一步瞭解如何建立 JSON 金鑰檔案，請參閱「建立服務帳戶金鑰」。

4. 使用二進位傳輸模式的檔案傳輸通訊協定 (FTP)，將 JSON 金鑰檔複製到 Unix 檔案系統。請務必將未修改的 JSON 金鑰檔案儲存在檔案系統中，並保留原始的 UTF-8 編碼。

   IBM z/OS Unix 檔案系統沒有儲存 JSON 金鑰檔案的預設路徑。您必須選擇只有具備服務帳戶存取權的使用者才能讀取的路徑。如果 JSON 金鑰檔案已正確轉移，就無法從 UNIX 系統服務 (USS) 讀取。

5. 使用二進位模式的 FTP，將步驟 1 中下載的 JAR 檔案上傳至大型主機上的下列位置。

    /opt/google/mainframe-connector/VERSION/
   

   將 Version 改為 JAR 檔案版本。

   請注意，這是部署 JAR 檔案的建議路徑。您也可以使用網站管理員選擇的任何路徑。

6. 執行下列指令，驗證 JAR 檔案是否已正確轉移。請注意，-t 選項會列出 JAR 檔案的內容。

    jar -tvf JAR_FILE_NAME
   

   請將 JAR_FILE_NAME 改成 JAR 檔案的名稱。

7. 複製下列 BQSH JCL 程序，並替換下列變數。

   在 BQSH JCL 程序中，BQSH_ROOT_LOGGER=DEBUG 表示已啟用偵錯記錄。如要停用偵錯記錄，請註解排除該行，或將變數設為 DEBUG 以外的值。

   如要將 Mainframe Connector 設定為將記錄資訊寫入 Cloud Logging，請設定 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
   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. 如要設定 Mainframe Connector，以便與 TLS 攔截 Proxy 搭配使用，請在 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"
    ```
   

9. 如果您使用預設信任儲存區密碼 changeit，則不必設定 trustStorePassword 系統屬性。Proxy 功能由「Apache HttpComponents HttpClient」提供。

   您必須使用 Mainframe Connector 支援的憑證信任存放區格式。憑證信任儲存庫可儲存為下列格式：

   • PKCS12 (.p12)：可能包含多個憑證，且需要密碼
   • JKS (.jks)：可能包含多個憑證，且需要密碼
   • PEM (.pem)：可能包含多個以 base64 編碼的憑證
   • 二進位 (.der)：每個檔案包含一個憑證

   如果 trustStore 系統屬性是目錄的路徑，系統會掃描該目錄，並將目錄中所有 .pem 和 .der 格式的憑證新增為信任的憑證。您必須手動載入 PKCS12 或 JKS 憑證。

如需隨時變更 BQSH JCL 程序，您可以在較低環境的程序庫 (PROCLIB) 中暫存較新版本。這個程式庫會新增至系統程式庫 SYSP.PROCLIB 之前，因此在更新 SYSP.PROCLIB 中的程序之前，可以先在較低的環境中審查變更。這樣一來，您在測試期間就不必更新 JCL 程序，指向新的更新程序。

BQSH JCL 程序範例

以下是 BQSH JCL 程序範例。在本程序中，ENV 符號用於指向 Java 標準環境陳述式，且專屬於 Google Cloud 環境。這樣一來，您就不必為每個環境執行多個 BQSH 程序。如要變更特定環境的設定，只要在系統 PARMLIB 程式庫的Google Cloud 環境中更新該特定成員即可。舉例來說，您可以建立新的 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
//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

以下是 DEV PARMLIB 成員的範例，說明如何參照 JSON 金鑰檔案和 Mainframe Connector 軟體 JAR 檔案。

# 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

後續步驟

• 將本機轉碼的大型主機資料移至 Google Cloud
• 在 Google Cloud上遠端轉碼大型主機資料
• 使用虛擬磁帶庫，轉碼移至 Google Cloud 的大型主機資料