Installer Mainframe Connector sur votre mainframe

Le connecteur Mainframe est lancé en tant que processus de machine virtuelle Java (JVM) dans le contexte d'une tâche par lot MVS. Le connecteur mainframe est généralement déployé à l'aide d'un fichier JAR contenant certaines dépendances requises autres que les bibliothèques IBM incluses avec la JVM. Les sections suivantes décrivent le processus d'installation de Mainframe Connector en détail.

Avant de commencer

Installer Mainframe Connector

Pour installer Mainframe Connector, procédez comme suit :

  1. Téléchargez le fichier JAR précompilé. Copiez le fichier mainframe-connector-shadow-VERSION-all.jar dans le chemin d'accès spécifié dans la section Java Classpath de la procédure JCL (job control language) BQSH illustrée à l'étape 7. VERSION correspond à la version de Mainframe Connector.

  2. Pour accéder aux services Google Cloud depuis votre mainframe, vous devez créer et télécharger une clé de compte de service sous forme de fichier de clé JSON. Pour en savoir plus sur la création d'un fichier de clé JSON, consultez Créer une clé de compte de service.

  3. Copier le fichier de clé JSON dans le système de fichiers Unix à l'aide du protocole de transfert de fichiers (FTP) en mode de transfert binaire. Veillez à stocker la clé JSON non modifiée. sur le système de fichiers, avec son encodage UTF-8 d'origine.

    Il n'existe pas de chemin d'accès par défaut pour stocker le fichier de clé JSON dans le système d'exploitation Unix IBM z/OS système de fichiers. Vous devez choisir un chemin accessible uniquement par les utilisateurs disposant des autorisations nécessaires pour accéder au compte de service. Le fichier de clé JSON ne sera pas lisible à partir de UNIX System Services (USS) s'il a été transféré correctement.

  4. Utilisez FTP en mode binaire pour importer le fichier JAR que vous avez téléchargé à l'étape 1 à l'emplacement suivant sur votre mainframe.

     /opt/google/mainframe-connector/VERSION/

    Remplacez Version par la version du fichier JAR.

    Notez qu'il s'agit de la méthode recommandée pour déployer le fichier JAR. Vous pouvez également utiliser n'importe quel chemin choisi par un administrateur de site.

  5. Exécutez la commande suivante pour vérifier que le fichier JAR a bien été transféré. Notez que l'option -t répertorie le contenu de la fichier JAR.

     jar -tvf JAR_FILE_NAME

    Remplacez JAR_FILE_NAME par le nom du fichier JAR.

  6. Créez une copie de la procédure JCL BQSH suivante et remplacez-la par variables.

    Dans la procédure JCL BQSH, BQSH_ROOT_LOGGER=DEBUG indique que la journalisation de débogage est activée. Pour désactiver la journalisation de débogage, mettez la ligne en commentaire ou définissez la variable sur une valeur autre que DEBUG.

    Pour configurer le connecteur de mainframe afin d'écrire des informations de journalisation dans Cloud Logging, définissez les paramètres LOG_PROJECT et LOG_ID des variables d'environnement, comme illustré dans l'exemple suivant.

    Pour obtenir la liste complète des variables d'environnement compatibles avec le connecteur Mainframe, consultez la section Variables d'environnement.

    • GKEY_FILE_PATH par le chemin d'accès au fichier de clé JSON décrit dans Étape 3.
    • JAR_FILE_PATH par le chemin d'accès au répertoire contenant le fichier JAR ; .
    • PROJECT_NAME par le projet pour lequel le journal est créé dans Cloud Logging
    • LOG_ID_NAME par le nom du journal
    //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. À configurer le connecteur de mainframe afin qu'il fonctionne avec une interception TLS proxy, définissez les propriétés système Java suivantes dans la procédure JCL BQSH.

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

    La procédure JCL BQSH avant d'ajouter les propriétés système Java pour IBM_JAVA_OPTIONS se présente comme suit.

    # 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 vous utilisez le mot de passe du magasin de confiance par défaut changeit, alors vous n'avez pas besoin de définir la propriété système trustStorePassword. Les fonctionnalités de proxy sont fournies par Apache HttpComponents HttpClient.

    Vous devez utiliser un format de magasin de certificats de confiance compatible avec Mainframe Connector. Le magasin de confiance des certificats peut être stocké dans les formats suivants :

    • PKCS12 (.p12) : peut contenir de nombreux certificats et nécessite un mot de passe
    • JKS (.jks) : peut contenir de nombreux certificats et nécessite un mot de passe
    • PEM (.pem) : peut contenir de nombreux certificats encodés en base64
    • Binaire (.der) : contient un certificat par fichier

    Si la propriété système trustStore est le chemin d'accès à un répertoire, le répertoire est analysé et tous les certificats comportant les fichiers .pem et Les fichiers .der trouvés dans l'annuaire sont ajoutés en tant que certificats de confiance. Vous devez charger manuellement les certificats PKCS12 ou JKS.

Si vous devez apporter des modifications à la procédure JCL BQSH, vous pouvez organiser une version plus récente dans l'environnement inférieur bibliothèque de procédures (PROCLIB). Cette bibliothèque est ajoutée avant la bibliothèque système, SYSP.PROCLIB, afin que les modifications puissent être examinées par rapport à l'environnement inférieur avant la mise à jour de la procédure dans SYSP.PROCLIB. Vous éviterez ainsi de mettre à jour JCL procédures pour indiquer une nouvelle procédure mise à jour lors des tests.

Exemple de procédure JCL BQSH

Voici un exemple de procédure JCL BQSH. Dans cette procédure, la bibliothèque ENV symbolic est utilisé pour pointer vers les instructions de l'environnement standard Java et est propre à l'environnement Google Cloud. De cette façon, vous n'avez pas besoin des procédures BQSH pour chaque environnement. Si vous souhaitez apporter des modifications environnement spécifique, il vous suffit de mettre à jour ce membre spécifique dans Environnement Google Cloud dans la bibliothèque système PARMLIB Par exemple, créez fichier JAR, utilisez une autre version d'IBM Java ou modifiez le fichier de clé JSON à l'aide d'instructions d'environnement.

#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

Voici un exemple du membre DEV PARMLIB montrant comment le fichier de clé JSON et le fichier JAR du logiciel Mainframe Connector sont référencés.

# 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

Étape suivante