在大型机上安装 Mainframe Connector

Mainframe Connector 在 MVS 批处理作业的上下文中作为 Java 虚拟机 (JVM) 进程启动。Mainframe Connector 通常使用 JAR 文件进行部署，该文件包含一些必需的依赖项（JVM 随附的 IBM 库除外）。以下部分详细介绍了 Mainframe Connector 安装流程。

准备工作

• 完成 Mainframe Connector 的初始设置。 初始设置包括向服务账号授予所需角色、为资产设置安全性，以及在大型机与 Google Cloud之间设置网络连接。
• 配置 Java 8 或 Java 17。
• 安装 JZOS 批处理启动器和工具包（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 文件复制到第 8 步中显示的 BQSH 作业控制语言 (JCL) 过程的 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 拦截代理，请在 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 系统属性。代理功能由 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 的大型机数据进行转码