Installa Mainframe Connector sul mainframe

Mainframe Connector viene avviato come processo della macchina virtuale Java (JVM) nel contesto di un job batch MVS. In genere, il connettore mainframe viene di solito implementato utilizzando un file JAR contenente alcune dipendenze richieste diverse dalle librerie IBM incluse nella JVM. Le sezioni seguenti descrivono in dettaglio la procedura di installazione di Mainframe Connector.

Prima di iniziare

Installa Mainframe Connector

Per installare il connettore mainframe:

  1. Scarica il file JAR precompilato. Copia il file mainframe-connector-shadow-VERSION-all.jar nel percorso specificato nella sezione Java Classpath della procedura BQSH job control language (JCL) mostrata nel passaggio 7. VERSION è la versione di Mainframe Connector.

  2. Per accedere ai servizi Google Cloud dal mainframe, devi creare e scaricare una chiave dell'account di servizio come file della chiave JSON. Per ulteriori informazioni sulla creazione di un file della chiave JSON, consulta Creare una chiave dell'account di servizio.

  3. Copia il file della chiave JSON nel file system Unix utilizzando il protocollo di trasferimento file (FTP) in modalità di trasferimento binario. Assicurati di archiviare il file della chiave JSON non modificato sul file system con la codifica UTF-8 originale.

    Non esiste un percorso predefinito per l'archiviazione del file della chiave JSON nel file system Unix IBM z/OS. Devi scegliere un percorso leggibile solo dagli utenti con autorizzazioni per accedere all'account di servizio. Il file della chiave JSON non sarà leggebile da UNIX System Services (USS) se è stato trasferito correttamente.

  4. Utilizza FTP in modalità binaria per caricare il file JAR scaricato nel passaggio 1 nella seguente posizione sul mainframe.

     /opt/google/mainframe-connector/VERSION/

    Sostituisci Version con la versione del file JAR.

    Tieni presente che questo è il percorso consigliato per il deployment del file JAR. Puoi anche utilizzare qualsiasi percorso scelto da un amministratore del sito.

  5. Esegui il seguente comando per verificare che il file JAR sia stato trasferito correttamente. Tieni presente che l'opzione -t elenca i contenuti del file JAR.

     jar -tvf JAR_FILE_NAME

    Sostituisci JAR_FILE_NAME con il nome del file JAR.

  6. Crea una copia della seguente procedura JCL BQSH e sostituisci le seguenti variabili.

    Nella procedura JCL BQSH, BQSH_ROOT_LOGGER=DEBUG indica che il logging di debug è abilitato. Per disattivare la registrazione di log di debug, commenta la riga o imposta la variabile su un valore diverso da DEBUG.

    Per configurare Mainframe Connector in modo che scriva le informazioni di logging in Cloud Logging, imposta le variabili di ambiente LOG_PROJECT e LOG_ID come mostrato nell'esempio seguente.

    Per l'elenco completo delle variabili di ambiente supportate da Mainframe Connector, consulta Variabili di ambiente.

    • GKEY_FILE_PATH con il percorso del file della chiave JSON descritto nel passaggio 3.
    • JAR_FILE_PATH con il percorso della directory contenente il file JAR.
    • PROJECT_NAME con il progetto per cui viene creato il log in Cloud Logging
    • LOG_ID_NAME con il nome del log
    //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. Per configurare il connettore Mainframe in modo che funzioni con un proxy di intercettazione TLS, imposta le seguenti proprietà di sistema Java nella procedura JCL BQSH.

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

    La procedura JCL BQSH prima di aggiungere le proprietà di sistema Java per IBM_JAVA_OPTIONS è la seguente.

    # 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. Se utilizzi la password predefinita del magazzino attendibile changeit, non devi impostare la proprietà di sistema trustStorePassword. Le funzionalità proxy sono fornite da Apache HttpComponents HttpClient.

    Devi utilizzare un formato dell'archivio di attendibilità dei certificati supportato da Mainframe Connector. L'archivio attendibilità dei certificati può essere archiviato nei seguenti formati:

    • PKCS12 (.p12): può contenere molti certificati e richiede una password
    • JKS (.jks): può contenere molti certificati e richiede una password
    • PEM (.pem): può contenere molti certificati codificati in base64
    • Binario (.der): contiene un certificato per file

    Se la proprietà di sistema trustStore è il percorso di una directory, la directory viene analizzata e tutti i certificati con il formato .pem e .der trovati nella directory vengono aggiunti come certificati attendibili. Devi caricare manualmente i certificati PKCS12 o JKS.

Se devi apportare modifiche alla procedura JCL BQSH in qualsiasi momento, puoi eseguire il staging di una versione più recente nella libreria di procedure (PROCLIB) dell'ambiente inferiore. Questa libreria viene aggiunta prima della libreria di sistema SYSP.PROCLIB, in modo che le modifiche possano essere controllate rispetto all'ambiente inferiore prima di aggiornare la procedura in SYSP.PROCLIB. In questo modo, puoi evitare di aggiornare le procedure JCL per fare in modo che indirizzino a una nuova procedura aggiornata durante i test.

Procedura JCL BQSH di esempio

Di seguito è riportata una procedura JCL BQSH di esempio. In questa procedura, il valore simbolico ENV viene utilizzato per fare riferimento alle istruzioni di ambiente Java standard ed è specifico per l'ambiente Google Cloud. In questo modo, non sono necessarie più procedure BQSH per ogni ambiente. Se vuoi apportare modifiche per un determinato ambiente, devi solo aggiornare l'elemento specifico nell'ambiente Google Cloud nella libreria di sistema PARMLIB. Ad esempio, crea un nuovo file JAR, utilizza una versione diversa di IBM Java o modifica il file di chiavi JSON utilizzando le istruzioni di ambiente.

#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

Di seguito è riportato un esempio dell'elemento DEV PARMLIB che mostra come vengono fatti riferimento al file di chiave JSON e al file 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

Passaggi successivi