Installare il connettore mainframe sul mainframe

Il connettore mainframe viene avviato come processo di 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 il connettore mainframe

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 del documento BQSH Procedura del linguaggio di controllo del job (JCL) mostrata nel passaggio 7. VERSION è la versione del connettore mainframe.

  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 dei file (FTP) in modalità di trasferimento binario. Assicurati di archiviare la chiave JSON non modificata sul file system, con la codifica originale UTF-8.

    Non esiste un percorso predefinito per l'archiviazione del file di chiave JSON in IBM z/OS Unix file system in-app. Devi scegliere un percorso che sia leggibile solo dagli utenti con le autorizzazioni di accesso all'account di servizio. Il file della chiave JSON non verrà leggibili da UNIX System Services (USS) se sono state trasferite correttamente.

  4. Utilizza l'FTP in modalità binaria per caricare il file JAR scaricato nel passaggio 1 in la seguente posizione sul tuo 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 dall'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 BQSH JCL e sostituisci il codice come la codifica one-hot delle variabili categoriche.

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

    Per configurare il connettore mainframe per la scrittura delle informazioni di logging in Cloud Logging, imposta LOG_PROJECT e LOG_ID come mostrato nell'esempio seguente.

    Per l'elenco completo delle variabili di ambiente supportate da Connettore mainframe, vedi 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 BQSH JCL prima di aggiungere le proprietà di sistema Java per IBM_JAVA_OPTIONS è il 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 di archivio attendibilità dei certificati supportato da Connettore mainframe. 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 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 file .pem Il formato .der trovato nella directory viene aggiunto come certificato attendibile. Devi caricare manualmente i certificati PKCS12 o JKS.

Se devi apportare modifiche alla procedura JCL BQSH in qualsiasi momento, puoi una versione più recente nell'ambiente inferiore libreria di procedure (PROCLIB). Questa libreria viene aggiunta prima della libreria di sistema, SYSP.PROCLIB, quindi le modifiche possono essere verificate nell'ambiente inferiore prima di aggiornare 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 Procedure BQSH per ogni ambiente. Se vuoi apportare modifiche a un ambiente specifico, devi solo aggiornare quel membro specifico 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 del membro DEV PARMLIB che mostra come Il file di chiave JSON e il file JAR del software del connettore mainframe sono a cui viene fatto riferimento.

# 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