Instala Mainframe Connector en tu unidad central

El conector de Mainframe se inicia como un proceso de máquina virtual de Java (JVM) dentro del contexto de un trabajo por lotes de MVS. Por lo general, el conector de Mainframe se implementa con un archivo JAR que contiene algunas dependencias requeridas, además de 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 V8.
• Instala el iniciador y el kit de herramientas de lotes de JZO.

Instala Mainframe Connector

Para instalar Mainframe Connector, sigue estos pasos:

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

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

3. Copia el archivo de clave 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 modificaciones 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 Unix de IBM z/OS. 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.

4. 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 que elija un administrador del sitio.

5. 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.

6. Haz una copia del siguiente procedimiento de JCL de BQSH y reemplaza 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, marca como comentario la línea o configura la variable en un valor que no sea 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 como se muestra en el siguiente ejemplo.

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

   • GKEY_FILE_PATH con la ruta de acceso al archivo de claves JSON que se describe en el paso 3.
   • JAR_FILE_PATH por la ruta de acceso al directorio que contiene el archivo JAR
   • PROJECT_NAME por el proyecto para el que se crea el registro en Cloud Logging
   • LOG_ID_NAME por 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
   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. Para configurar Mainframe Connector para que funcione con un proxy de intercepción de TLS, establece 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 de 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"
    ```
   

8. Si usas la contraseña predeterminada del almacén de confianza changeit, no es necesario que configures la propiedad del sistema trustStorePassword. Apache HttpComponents HttpClient proporciona las funciones de proxy.

   Debes usar un formato de almacén de confianza de certificados compatible con el conector de Mainframe. 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 todos los certificados con el formato .pem y .der que se encuentran en él se agregan 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 activar una versión más reciente en la biblioteca de procedimientos (PROCLIB) del entorno inferior. Esta biblioteca se agrega 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 manera, puedes evitar actualizar los procedimientos de JCL para que apunten a un nuevo procedimiento actualizado durante las pruebas.

Ejemplo de procedimiento JCL de BQSH

El siguiente es un procedimiento de JCL de BQSH de muestra. En este procedimiento, se usa el símbolo ENV para apuntar a las sentencias del entorno estándar de Java y es específico del entorno de Google Cloud. De esta manera, no necesitas varios procedimientos de BQSH para cada entorno. Si quieres realizar cambios en un entorno en particular, solo debes actualizar ese miembro específico en el entorno de Google Cloud 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 clave JSON y al archivo JAR del software del conector de Mainframe.

# 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?

• Cómo mover datos de mainframe transcodificados de forma local a Google Cloud
• Transcodifica datos de mainframe de forma remota en Google Cloud
• Transcodifica los datos de mainframe que se transfirieron a Google Cloud con una biblioteca de cintas virtual