Instala Mainframe Connector en tu unidad central

Mainframe Connector se inicia como un proceso de máquina virtual de Java (JVM) en el contexto de un trabajo por lotes de MVS. Por lo general, Mainframe Connector se implementa con un archivo JAR que contiene algunas dependencias obligatorias que no son las bibliotecas de IBM incluidas con la JVM. En las siguientes secciones, se describe el proceso de instalación de Mainframe Connector en detalle.

Antes de comenzar

  • Completa la configuración inicial de Mainframe Connector. La configuración inicial incluye otorgar los roles necesarios a tu cuenta de servicio , configurar la seguridad de tus recursos y configurar la conectividad de red entre tu mainframe y Google Cloud.
  • Configura Java 8 o Java 17.
  • Instala el iniciador y el kit de herramientas por lotes de JZOS (Java 8 o Java 17).

Instala Mainframe Connector

Para instalar Mainframe Connector, sigue estos pasos:

  1. Descarga el archivo JAR de Mainframe Connector compilado previamente en un directorio en el que tu cuenta de usuario tenga permisos de escritura.

    Importante

    Ten en cuenta que Mainframe Connector usa Google Analytics para recopilar datos de uso. Esto nos ayuda a mejorar el software y brindar una mejor experiencia del usuario. De forma predeterminada, Google Analytics está habilitado. Sin embargo, puedes inhabilitarlo si configuras una variable de entorno cuando ejecutas Mainframe Connector.

    El uso de Google Analytics está sujeto a las Condiciones del Servicio y a la Política de Privacidad de Google Analytics. Cuando descargas Mainframe Connector, reconoces que leíste, comprendiste y aceptaste los términos y condiciones.

    Descargar Cancelar

  2. Copia el archivo mainframe-connector-shadow-VERSION-all.jar a la ruta de acceso especificada en la sección Java Classpath del procedimiento del lenguaje de control de trabajos (JCL) de BQSH (JCL) que se muestra en el paso 8. VERSION es la versión de Mainframe Connector.

  3. Para acceder a los servicios desde tu mainframe, debes crear y descargar una clave de cuenta de servicio como un archivo de claves JSON. Google Cloud Para obtener más información sobre cómo crear un archivo de claves JSON, consulta Crea una clave de cuenta de servicio.

  4. Copia el archivo de claves JSON en el sistema de archivos de Unix con el protocolo de transferencia de archivos (FTP) en modo de transferencia binaria. Asegúrate de almacenar el archivo de claves JSON sin modificar en el sistema de archivos, con su codificación UTF-8 original.

    No hay una ruta de acceso predeterminada para almacenar el archivo de claves JSON en el sistema de archivos de IBM z/OS Unix. Debes elegir una ruta de acceso que solo puedan leer los usuarios con permisos para acceder a la cuenta de servicio. El archivo de claves JSON no se podrá leer desde los Servicios del sistema UNIX (USS) si se transfirió correctamente.

  5. Usa FTP en modo binario para subir el archivo JAR que descargaste en el paso 1 a la siguiente ubicación en tu mainframe.

     /opt/google/mainframe-connector/VERSION/

    Reemplaza Version por la versión del archivo JAR.

    Ten en cuenta que esta es la ruta de acceso recomendada para implementar el archivo JAR. También puedes usar cualquier ruta de acceso elegida por un administrador del sitio.

  6. Ejecuta el siguiente comando para validar que el archivo JAR se transfirió correctamente. Ten en cuenta que la opción -t muestra el contenido del archivo JAR.

     jar -tvf JAR_FILE_NAME

    Reemplaza JAR_FILE_NAME por el nombre del archivo JAR.

  7. Haz una copia del siguiente procedimiento JCL de BQSH.

    /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
export GOOGLE_DIR="JAR_FILE_PATH"
export 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
export JAVA_HOME="/usr/lpp/java/J8.0_64"
export PATH="/bin:$JAVA_HOME/bin"

# Log Level
export BQSH_ROOT_LOGGER=DEBUG

# Cloud Logging
export LOG_PROJECT="PROJECT_NAME"
export LOG_ID="LOG_ID_NAME"

# Google Analytics
# Uncomment the following line to disable Google Analytics
#export DISABLE_ANALYTICS=True

# Binary Data Sets
# Uncomment the following line 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
export JL="$JH/lib"
export 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"
IJO="$IJO -Dbqsh.dataset.encoding=IBM-1047"
export IBM_JAVA_OPTIONS="$IJO"
export JZOS_MAIN_ARGS=""
/*
// PEND

    Reemplaza lo siguiente:

    • GKEY_FILE_PATH: la ruta de acceso al archivo de claves JSON que se describe en el paso 3.
    • JAR_FILE_PATH: La ruta de acceso al directorio que contiene el archivo JAR.
    • PROJECT_NAME: El proyecto para el que se crea el registro en Cloud Logging.
    • LOG_ID_NAME: El nombre del registro.
    • Para inhabilitar el registro de depuración, marca como comentario la línea BQSH_ROOT_LOGGER=DEBUG.
    • Para configurar Mainframe Connector para que escriba información de registro en Cloud Logging, establece las variables de entorno LOG_PROJECT y LOG_ID.
    • Para inhabilitar Google Analytics, establece la variable de entorno DISABLE_ANALYTICS en True.
    • Para especificar la codificación de caracteres predeterminada que se usa para las operaciones del conjunto de datos de mainframe (DSN y DD), establece la propiedad bqsh.dataset.encoding. Si no se establece en z/OS, Mainframe Connector intenta detectar de forma dinámica la codificación con las propiedades del sistema native.encoding o sun.jnu.encoding y recurre a IBM-1047. En entornos que no son de mainframe, recurre al conjunto de caracteres predeterminado de la JVM.

    Para obtener la lista completa de las variables de entorno compatibles con Mainframe Connector, consulta Variables de entorno.

  8. Para configurar Mainframe Connector para que funcione con un proxy de intercepción de TLS, establece las siguientes propiedades del sistema de Java en el procedimiento JCL de BQSH.

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

    El procedimiento JCL de BQSH antes de agregar las propiedades del sistema de Java para IBM_JAVA_OPTIONS es el siguiente.

    # 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. Si usas la contraseña predeterminada del almacén de confianza changeit, entonces no tienes que establecer la propiedad del sistema trustStorePassword. Apache HttpComponents HttpClient proporciona las capacidades de proxy.

    Debes usar un formato de almacén de confianza de certificados compatible con Mainframe Connector. El almacén de confianza de certificados se puede almacenar en los siguientes formatos:

    • PKCS12 (.p12): Puede contener muchos certificados y requiere una contraseña.
    • JKS (.jks): Puede contener muchos certificados y requiere una contraseña.
    • PEM (.pem): Puede contener muchos certificados codificados como base64.
    • Binario (.der): Contiene un certificado por archivo.

    Si la propiedad del sistema trustStore es la ruta de acceso a un directorio, se analiza el directorio y se agregan todos los certificados con el formato .pem y .der que se encuentran en el directorio como certificados de confianza. Debes cargar manualmente los certificados PKCS12 o JKS.

Si necesitas realizar cambios en el procedimiento JCL de BQSH en cualquier momento, puedes preparar una versión más reciente en la biblioteca de procedimientos del entorno inferior (PROCLIB). Esta biblioteca se agrega antes de la biblioteca del sistema, SYSP.PROCLIB, de modo que los cambios se puedan verificar en el entorno inferior antes de actualizar el procedimiento en SYSP.PROCLIB. De esta manera, puedes evitar actualizar los procedimientos JCL para que apunten a un nuevo procedimiento actualizado durante las pruebas.

Procedimiento JCL de BQSH de muestra

El siguiente es un procedimiento JCL de BQSH de muestra. En este procedimiento, el ENV símbolo se usa para apuntar a las instrucciones del entorno estándar de Java y es específico del Google Cloud entorno. De esta manera, no necesitas varios procedimientos BQSH para cada entorno. Si deseas realizar cambios en un entorno en particular, solo debes actualizar ese miembro específico en el Google Cloud entorno en la biblioteca PARMLIB del sistema. Por ejemplo, crea un archivo JAR nuevo, usa una versión diferente de IBM Java o cambia el archivo de claves JSON con instrucciones de entorno.

#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

El siguiente es un ejemplo del miembro DEV PARMLIB que muestra cómo se hace referencia al archivo de claves JSON y al archivo JAR de software de Mainframe Connector.

# 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

¿Qué sigue?