Installa Mainframe Connector sul mainframe

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

  • Completa la configurazione iniziale di Mainframe Connector. La configurazione iniziale include la concessione dei ruoli richiesti al tuo service account, 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).

Installa Mainframe Connector

Per installare Mainframe Connector:

  1. Scarica il file JAR di Mainframe Connector precompilato in una directory per 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 un'esperienza utente migliore. Per impostazione predefinita, Google Analytics è attivato. Tuttavia, puoi disattivare questa opzione configurando una variabile di ambiente quando esegui 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 condizioni.

    Scarica Annulla

  2. 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 8. VERSION è la versione di Mainframe Connector.

  3. Per accedere ai Google Cloud servizi 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, vedi Creare una chiave dell'account di servizio.

  4. Copia il file di 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 nel file system, con la codifica UTF-8 originale.

    Non esiste un percorso predefinito per l'archiviazione del file chiave JSON nel file system IBM z/OS Unix. Devi scegliere un percorso leggibile solo dagli utenti con autorizzazioni per accedere alaccount di serviziot. 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 del 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.

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

  7. 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 è attivato. Per disattivare la registrazione 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
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. 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 predefinita dell'archivio attendibile changeit, non devi impostare la proprietà di sistema trustStorePassword. Le funzionalità proxy sono fornite da Apache HttpComponents HttpClient.

    Devi utilizzare un formato di archivio attendibilità certificati supportato da Mainframe Connector. L'archivio di 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 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 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 (PROCLIB) dell'ambiente inferiore. 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 è riportata una procedura JCL BQSH di esempio. In questa procedura, il simbolo ENV viene utilizzato per indicare le istruzioni dell'ambiente standard Java ed è specifico dell'ambiente Google Cloud . In questo modo, non hai bisogno di più procedure BQSH per ogni ambiente. Se vuoi apportare modifiche per un ambiente specifico, devi solo aggiornare il membro specifico nell'ambienteGoogle Cloud nella libreria PARMLIB del sistema. 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 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