Installa Mainframe Connector sul tuo mainframe

Mainframe Connector viene avviato come processo della macchina virtuale Java (JVM) nel contesto di un job batch MVS. In genere, Mainframe Connector viene eseguito il deployment 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

  • Completa la configurazione iniziale di Mainframe Connector. La configurazione iniziale include la concessione dei ruoli richiesti al tuo account di servizio , la configurazione della sicurezza per gli asset e la configurazione della connettività di rete tra il mainframe e Google Cloud.
  • Configura Java 8 o Java 17.
  • Installa JZOS Batch Launcher and Toolkit (Java 8 o Java 17).

Installare Mainframe Connector

Per installare Mainframe Connector, segui questi passaggi:

  1. Scarica il file JAR di Mainframe Connector precompilato in una directory in cui il tuo account utente dispone delle autorizzazioni di scrittura.

    Importante

    Tieni presente che Mainframe Connector utilizza Google Analytics per raccogliere i dati di utilizzo. Questo ci aiuta a migliorare il software e a fornire una migliore esperienza utente. Per impostazione predefinita, Google Analytics è abilitato. Tuttavia, puoi disattivarlo configurando una variabile di ambiente durante l'esecuzione di Mainframe Connector.

    L'utilizzo di Google Analytics è soggetto ai Termini di servizio e alle Norme sulla privacy di Google Analytics. Scaricando Mainframe Connector, confermi di aver letto, compreso e accettato i termini e le condizioni.

    Scarica Annulla

  2. Copia il file mainframe-connector-shadow-VERSION-all.jar nel percorso specificato nella sezione Java Classpath della procedura del linguaggio di controllo dei job (JCL) BQSH mostrata nel passaggio 8. VERSION è la versione di Mainframe Connector.

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

  4. Copia il file di chiave JSON nel file system Unix utilizzando il protocollo FTP (File Transfer Protocol) in modalità di trasferimento binario. Assicurati di archiviare il file di chiave JSON non modificato nel file system, con la codifica UTF-8 originale.

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

  5. 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 eseguire il deployment del file JAR. Puoi anche utilizzare qualsiasi percorso scelto da un amministratore del sito.

  6. Esegui il comando seguente 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.

  7. Crea una copia della seguente procedura JCL 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"
export IBM_JAVA_OPTIONS="$IJO"
export JZOS_MAIN_ARGS=""
/*
// PEND

    Sostituisci quanto segue:

    • GKEY_FILE_PATH: il percorso del file di chiave JSON descritto nel passaggio 3.
    • JAR_FILE_PATH: il percorso della directory contenente il file JAR.
    • PROJECT_NAME: il progetto per il quale viene creato il log in Cloud Logging.
    • LOG_ID_NAME: il nome del log.
    • Per disattivare la registrazione di debug, commenta la riga BQSH_ROOT_LOGGER=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.
    • Per disattivare Google Analytics, imposta la variabile di ambiente DISABLE_ANALYTICS su True.

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

  8. Per configurare Mainframe Connector 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"
 ```

  9. Se utilizzi la password dell'archivio di attendibilità predefinita changeit, allora non devi impostare la proprietà di sistema trustStorePassword. Le funzionalità proxy sono fornite da Apache HttpComponents HttpClient.

    Devi utilizzare un formato di archivio di attendibilità di certificati supportato da Mainframe Connector. Il truststore di 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 come 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 lo staging di una versione più recente nella libreria delle procedure dell'ambiente inferiore (PROCLIB). Questa libreria viene aggiunta prima della libreria di sistema, SYSP.PROCLIB, in modo che le modifiche possano essere verificate rispetto all'ambiente inferiore prima di aggiornare la procedura in SYSP.PROCLIB. In questo modo, puoi evitare di aggiornare le procedure JCL in modo che puntino a una nuova procedura aggiornata durante i test.

Esempio di procedura JCL BQSH

Di seguito è riportato un esempio di procedura JCL BQSH. In questa procedura, il simbolo ENV viene utilizzato per puntare alle istruzioni dell'ambiente standard Java ed è specifico per l' Google Cloud ambiente. In questo modo, non sono necessarie più procedure BQSH per ogni ambiente. Se vuoi apportare modifiche a un ambiente specifico, devi solo aggiornare il membro specifico nell' Google Cloud ambiente nella libreria PARMLIB di sistema. Ad esempio, crea un nuovo file JAR, utilizza una versione Java IBM diversa o modifica il file di chiave JSON utilizzando le istruzioni dell'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 del membro DEV PARMLIB che mostra come viene fatto 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