在大型主机上安装大型主机连接器

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

准备工作

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

安装大型主机连接器

要安装大型主机连接器，请按以下步骤操作：

1. 下载预构建的 JAR 文件。复制 mainframe-connector-shadow-VERSION-all.jar 文件添加到 BQSH 的 Java 类路径部分中指定的路径 作业控制语言 (JCL) 程序，如第 7 步中所示。 VERSION 是 Mainframe Connector 的版本。

2. 如需从大型机访问 Google Cloud 服务，您必须创建服务账号密钥并将其下载为 JSON 密钥文件。如需详细了解如何创建 JSON 密钥文件，请参阅创建服务账号密钥。

3. 使用文件传输协议将 JSON 密钥文件复制到 Unix 文件系统 (FTP)（采用二进制传输模式）。确保您将未修改的 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 替换为上述 JSON 密钥文件的路径 第 3 步。
   • 将 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 拦截 代理，请在 BQSH JCL 过程中设置以下 Java 系统属性。

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

   为以下对象添加 Java 系统属性之前的 BQSH JCL 过程 IBM_JAVA_OPTIONS 如下所示。

   # 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 提供。

   您使用的证书受信任证书存储区格式必须是 大型主机连接器。证书信任存储区可存储在 以下格式：

   • 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 的主机数据