在大型机上安装 Mainframe Connector

大型机连接器会作为 Java 虚拟机 (JVM) 进程在 MVS 批处理作业上下文中启动。通常，Mainframe 连接器是使用包含 JVM 中包含的 IBM 库以外的一些必需依赖项的 JAR 文件进行部署的。以下部分详细介绍了大型机连接器的安装过程。

准备工作

• 完成大型机连接器的初始设置。 初始设置包括向您的服务账号授予所需角色、为您的资产设置安全性，以及在您的大型机与 Google Cloud之间设置网络连接。
• 配置 Java V8。
• 安装 JZOS 批处理启动器和工具包。

安装 Mainframe Connector

如需安装 Mainframe Connector，请按以下步骤操作：

1. 下载预构建的 JAR 文件。将 mainframe-connector-shadow-VERSION-all.jar 文件复制到第 7 步中所示 BQSH 作业控制语言 (JCL) 过程的 Java 类路径部分中指定的路径。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 以外的任何值。

   如需配置 Mainframe Connector 将日志记录信息写入 Cloud Logging，请设置 LOG_PROJECT 和 LOG_ID 环境变量，如以下示例所示。

   如需查看 Mainframe 连接器支持的环境变量的完整列表，请参阅环境变量。

   • 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. 如需将 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"
    ```
   

8. 如果您使用的是默认信任库密码 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 的主机数据