Instalar Mainframe Connector en tu mainframe

Mainframe Connector se inicia como un proceso de máquina virtual Java (JVM) en el contexto de un trabajo por lotes de MVS. Mainframe Connector se suele implementar mediante un archivo JAR que contiene algunas dependencias necesarias distintas de las bibliotecas de IBM incluidas en la JVM. En las siguientes secciones se describe en detalle el proceso de instalación de Mainframe Connector.

Antes de empezar

  • Completa la configuración inicial de Mainframe Connector. La configuración inicial incluye la asignación de los roles necesarios a tu cuenta de servicio, la configuración de la seguridad de tus recursos y la configuración de la conectividad de red entre tu mainframe y Google Cloud.
  • Configura Java 8 o Java 17.
  • Instala JZOS Batch Launcher and Toolkit (Java 8 o Java 17).

Instalar Mainframe Connector

Para instalar Mainframe Connector, sigue estos pasos:

  1. Descarga el archivo JAR del conector de mainframe precompilado 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 recoger datos de uso. Esto nos ayuda a mejorar el software y a ofrecer una mejor experiencia de usuario. Google Analytics está habilitado de forma predeterminada. Sin embargo, puede inhabilitar esta opción configurando una variable de entorno al ejecutar Mainframe Connector.

    El uso de Google Analytics está sujeto a los Términos del Servicio y la Política de Privacidad de Google Analytics. Al descargar Mainframe Connector, confirmas que has leído, comprendido y aceptado los términos y condiciones.

    Descargar Cancelar

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

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

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

    No hay ninguna ruta predeterminada para almacenar el archivo de clave JSON en el sistema de archivos Unix de IBM z/OS. Debes elegir una ruta 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 ha transferido correctamente.

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

     /opt/google/mainframe-connector/VERSION/

    Sustituye Version por la versión del archivo JAR.

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

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

     jar -tvf JAR_FILE_NAME

    Sustituye JAR_FILE_NAME por el nombre del archivo JAR.

  7. Haz una copia del siguiente procedimiento JCL de BQSH y sustituye las siguientes variables.

    En el procedimiento JCL de BQSH, BQSH_ROOT_LOGGER=DEBUG indica que el registro de depuración está habilitado. Para inhabilitar el registro de depuración, comenta la línea o asigna a la variable cualquier valor que no sea DEBUG.

    Para configurar Mainframe Connector de forma que escriba información de registro en Cloud Logging, define las variables de entorno LOG_PROJECT y LOG_ID, tal como se muestra en el siguiente ejemplo.

    Para ver la lista completa de variables de entorno admitidas por Mainframe Connector, consulta Variables de entorno.

    • GKEY_FILE_PATH con la ruta al archivo de clave JSON descrito en el paso 3.
    • JAR_FILE_PATH con la ruta al directorio que contiene el archivo JAR.
    • PROJECT_NAME con el proyecto en el que se está creando el registro en Cloud Logging
    • LOG_ID_NAME con el nombre del registro
    //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. Para configurar Mainframe Connector de forma que funcione con un proxy que intercepte TLS, define las siguientes propiedades del sistema 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 añadir las propiedades del sistema 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, no tienes que definir la propiedad del sistema trustStorePassword. Las funciones de proxy las proporciona Apache HttpComponents HttpClient.

    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 a un directorio, se analiza el directorio y se añaden como certificados de confianza todos los certificados con formato .pem y .der que se encuentren en el directorio. Debes cargar manualmente los certificados PKCS12 o JKS.

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

Ejemplo de procedimiento JCL de BQSH

A continuación, se muestra un ejemplo de procedimiento JCL de BQSH. En este procedimiento, el símbolo ENV se usa para hacer referencia a las instrucciones del entorno estándar de Java y es específico del entorno Google Cloud . De esta forma, no necesitas varios procedimientos de BQSH para cada entorno. Si quieres hacer cambios en un entorno concreto, solo tienes que actualizar ese miembro específico en la bibliotecaGoogle Cloud environment in system PARMLIB. Por ejemplo, puedes crear un archivo JAR, usar una versión diferente de IBM Java o cambiar el archivo de claves JSON mediante 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

A continuación, se muestra un ejemplo del miembro DEV PARMLIB que muestra cómo se hace referencia al archivo de claves JSON y al archivo JAR del software 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

Siguientes pasos