在主機上安裝 Mainframe Connector

主機連接器會在 MVS 批次作業的背景中，以 Java 虛擬機器 (JVM) 程序的形式啟動。主機介面通常會使用 JAR 檔案部署，其中包含 JVM 所附帶的 IBM 程式庫以外的部分必要依附元件。以下各節將詳細說明主機介面連接器的安裝程序。

事前準備

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

安裝 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 工作控制語言 (JCL) 程序 (如步驟 8 所示) 的 Java 路徑集部分中指定的路徑。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 金鑰檔案和主機介面連接器軟體 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