Installer Mainframe Connector sur votre mainframe

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

Avant de commencer

  • Effectuez la configuration initiale de Mainframe Connector. La configuration initiale inclut l'attribution des rôles requis à votre compte de service , la configuration de la sécurité de vos actifs et la configuration de la connectivité réseau entre votre mainframe et Google Cloud.
  • Configurez Java 8 ou Java 17.
  • Installez le lanceur et le kit d'outils par lot JZOS (Java 8 ou Java 17).

Installer Mainframe Connector

Pour installer Mainframe Connector, procédez comme suit :

  1. Téléchargez le fichier JAR Mainframe Connector précompilé dans un répertoire pour lequel votre compte utilisateur dispose d'autorisations d'écriture.

    Important

    Sachez que Mainframe Connector utilise Google Analytics pour collecter des données d'utilisation. Cela nous aide à améliorer le logiciel et à offrir une meilleure expérience utilisateur. Par défaut, Google Analytics est activé. Toutefois, vous pouvez le désactiver en configurant une variable d'environnement lors de l' exécution de Mainframe Connector.

    L'utilisation de Google Analytics est soumise aux Conditions d'utilisation et à la Politique de confidentialité de Google Analytics. En téléchargeant Mainframe Connector, vous reconnaissez avoir lu, compris et accepté les conditions générales.

    Télécharger Annuler

  2. 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 de langage de contrôle des tâches (JCL) BQSH présentée à l'étape 8. VERSION correspond à la version de Mainframe Connector.

  3. Pour accéder aux Google Cloud services depuis votre mainframe, vous devez créer et télécharger une clé de compte de service sous la forme d'un 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.

  4. Copiez 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. Assurez-vous de stocker le fichier de clé JSON non modifié dans 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 de fichiers IBM z/OS Unix. Vous devez choisir un chemin d'accès qui ne peut être lu que par les utilisateurs autorisés à accéder au compte de service. Le fichier de clé JSON ne sera pas lisible à partir des services système UNIX (USS) s'il a été transféré correctement.

  5. Utilisez le protocole 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 du chemin d'accès recommandé pour déployer le fichier JAR. Vous pouvez également utiliser n'importe quel chemin d'accès choisi par un administrateur de site.

  6. Exécutez la commande suivante pour vérifier que le fichier JAR a été transféré correctement. Notez que l'option -t liste le contenu du fichier JAR.

     jar -tvf JAR_FILE_NAME

    Remplacez JAR_FILE_NAME par le nom du fichier JAR.

  7. Créez une copie de la procédure JCL BQSH suivante.

    /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"
IJO="$IJO -Dbqsh.dataset.encoding=IBM-1047"
export IBM_JAVA_OPTIONS="$IJO"
export JZOS_MAIN_ARGS=""
/*
// PEND

    Remplacez les éléments suivants :

    • GKEY_FILE_PATH : chemin d'accès au fichier de clé JSON décrit à l'étape 3.
    • JAR_FILE_PATH : chemin d'accès au répertoire contenant le fichier JAR.
    • PROJECT_NAME : projet pour lequel le journal est créé dans Cloud Logging.
    • LOG_ID_NAME : nom du journal.
    • Pour désactiver la journalisation de débogage, mettez en commentaire la ligne BQSH_ROOT_LOGGER=DEBUG.
    • Pour configurer Mainframe Connector afin qu'il écrive les informations de journalisation dans Cloud Logging, définissez les variables d'environnement LOG_PROJECT et LOG_ID.
    • Pour désactiver Google Analytics, définissez la variable d'environnement DISABLE_ANALYTICS sur True.
    • Pour spécifier l'encodage de caractères par défaut utilisé pour les opérations sur les ensembles de données mainframe (DSN et DD), définissez la propriété bqsh.dataset.encoding. Si elle n'est pas définie sur z/OS, Mainframe Connector tente de détecter dynamiquement l'encodage à l'aide des propriétés système native.encoding ou sun.jnu.encoding, en revenant à IBM-1047. Dans les environnements non mainframe, il revient au jeu de caractères par défaut de la JVM.

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

  8. Pour configurer Mainframe Connector afin qu'il fonctionne avec un proxy d'interception TLS, 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 l'ajout des propriétés système Java pour IBM_JAVA_OPTIONS est la suivante.

    # 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. 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 confiance de certificat compatible avec Mainframe Connector. Le magasin de confiance de certificat 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 au format base64
    • Binaire (.der) : contient un certificat par fichier

    Si la propriété système trustStore correspond au chemin d'accès à un répertoire, celui-ci est analysé et tous les certificats au format .pem et .der trouvés dans le répertoire sont ajoutés en tant que certificats approuvés. Vous devez charger manuellement les certificats PKCS12 ou JKS.

Si vous devez apporter des modifications à la procédure JCL BQSH à tout moment, vous pouvez mettre en scène une version plus récente dans la bibliothèque de procédures d'environnement inférieur (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 de mettre à jour la procédure dans SYSP.PROCLIB. Ainsi, vous pouvez éviter de mettre à jour les procédures JCL pour qu'elles pointent vers 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, le ENV symbole est utilisé pour pointer vers les instructions d'environnement standard Java et est spécifique à l' Google Cloud environnement. Ainsi, vous n'avez pas besoin de plusieurs procédures BQSH pour chaque environnement. Si vous souhaitez apporter des modifications à un environnement particulier, il vous suffit de mettre à jour ce membre spécifique dans l' Google Cloud environnement de la bibliothèque système PARMLIB. Par exemple, créez un 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 de 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