Mainframe Connector auf Ihrem Mainframe installieren

Mainframe Connector wird als JVM-Prozess (Java Virtual Machine) gestartet im Kontext eines MVS-Batchjobs. Mainframe Connector wird in der Regel mit einer JAR-Datei bereitgestellt, die einige erforderliche Abhängigkeiten enthält, die nicht in den IBM-Bibliotheken enthalten sind, die in der JVM enthalten sind. In den folgenden Abschnitten wird die Installation von Mainframe Connector im Detail beschrieben.

Hinweis

  • Schließen Sie die Ersteinrichtung für Mainframe Connector ab. Die Ersteinrichtung umfasst das Zuweisen der erforderlichen Rollen zu Ihrem Dienst konto, das Einrichten der Sicherheit für Ihre Assets und das Einrichten der Netzwerk verbindung zwischen Ihrem Mainframe und Google Cloud.
  • Konfigurieren Sie Java 8 oder Java 17.
  • Installieren Sie den JZOS Batch Launcher and Toolkit (Java 8 oder Java 17).

Mainframe Connector installieren

So installieren Sie Mainframe Connector:

  1. Laden Sie die vorkompilierte JAR-Datei für Mainframe Connector in ein Verzeichnis herunter, für das Ihr Nutzerkonto Schreibberechtigungen hat.

    Wichtig

    Mainframe Connector erhebt Nutzungsdaten mit Google Analytics. So können wir die Software verbessern und eine bessere Nutzererfahrung bieten. Google Analytics ist standardmäßig aktiviert. Sie können die Erhebung jedoch deaktivieren, indem Sie beim Ausführen von Mainframe Connector eine Umgebungsvariable konfigurieren.

    Die Verwendung von Google Analytics unterliegt den Google Analytics Nutzungsbedingungen und der Datenschutzerklärung. Durch das Herunterladen von Mainframe Connector bestätigen Sie, dass Sie die Nutzungsbedingungen gelesen und verstanden haben und ihnen zustimmen.

    Herunterladen Abbrechen

  2. Kopieren Sie die Datei mainframe-connector-shadow-VERSION-all.jar in den Pfad, der im Abschnitt Java Classpath der BQSH JCL-Prozedur (Job Control Language) angegeben ist, die in Schritt 8 gezeigt wird. VERSION ist die Version von Mainframe Connector.

  3. Wenn Sie auf Google Cloud Dienste von Ihrem Mainframe aus zugreifen möchten, müssen Sie einen Dienstkontoschlüssel erstellen und als JSON-Schlüsseldatei herunterladen. Weitere Informationen zum Erstellen einer JSON-Schlüsseldatei finden Sie unter Dienstkontoschlüssel erstellen.

  4. Kopieren Sie die JSON-Schlüsseldatei im binären Übertragungsmodus mit dem File Transfer Protocol (FTP) in das Unix-Dateisystem. Speichern Sie die unveränderte JSON-Schlüsseldatei mit der ursprünglichen UTF-8-Codierung im Dateisystem.

    Es gibt keinen Standardpfad zum Speichern der JSON-Schlüsseldatei im IBM z/OS Unix-Dateisystem. Sie müssen einen Pfad auswählen, der nur von Nutzern mit Berechtigungen für den Zugriff auf das Dienstkonto gelesen werden kann. Die JSON-Schlüsseldatei kann nicht von UNIX System Services (USS) gelesen werden, wenn sie korrekt übertragen wurde.

  5. Laden Sie die in Schritt 1 heruntergeladene JAR-Datei im binären Modus mit FTP an den folgenden Speicherort auf Ihrem Mainframe hoch.

     /opt/google/mainframe-connector/VERSION/

    Ersetzen Sie Version durch die Version der JAR-Datei.

    Dies ist der empfohlene Pfad zum Bereitstellen der JAR-Datei. Sie können auch einen beliebigen Pfad verwenden, der von einem Websiteadministrator ausgewählt wurde.

  6. Führen Sie den folgenden Befehl aus, um zu prüfen, ob die JAR-Datei korrekt übertragen wurde. Die Option -t listet den Inhalt der JAR-Datei auf.

     jar -tvf JAR_FILE_NAME

    Ersetzen Sie JAR_FILE_NAME durch den Namen der JAR-Datei.

  7. Erstellen Sie eine Kopie der folgenden BQSH-JCL-Prozedur.

    /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

    Ersetzen Sie Folgendes:

    • GKEY_FILE_PATH: der Pfad zur JSON-Schlüsseldatei, die in Schritt 3 beschrieben wird.
    • JAR_FILE_PATH: der Pfad zum Verzeichnis, das die JAR Datei enthält.
    • PROJECT_NAME: das Projekt, für das das Log in Cloud Logging erstellt wird.
    • LOG_ID_NAME: der Name des Logs.
    • Wenn Sie die Debug-Protokollierung deaktivieren möchten, kommentieren Sie die Zeile BQSH_ROOT_LOGGER=DEBUG aus.
    • Wenn Sie Mainframe Connector so konfigurieren möchten, dass Protokollierungsinformationen in Cloud Logging geschrieben werden, legen Sie die Umgebungsvariablen LOG_PROJECT und LOG_ID fest.
    • Wenn Sie Google Analytics deaktivieren möchten, setzen Sie die Umgebungsvariable DISABLE_ANALYTICS auf True.
    • Legen Sie die Property bqsh.dataset.encoding fest, um die Standardzeichencodierung anzugeben, die für Mainframe-Dataset-Vorgänge (DSN und DD) verwendet wird. Wenn die Property unter z/OS nicht festgelegt ist, versucht Mainframe Connector, die Codierung dynamisch mit den Systemeigenschaften native.encoding oder sun.jnu.encoding zu erkennen und verwendet andernfalls IBM-1047. In Nicht-Mainframe-Umgebungen wird standardmäßig der JVM-Zeichensatz verwendet.

    Eine vollständige Liste der von Mainframe Connector unterstützten Umgebungsvariablen finden Sie unter Umgebungsvariablen.

  8. Wenn Sie Mainframe Connector so konfigurieren möchten, dass er mit einem TLS-Proxy funktioniert, legen Sie die folgenden Java-Systemeigenschaften in der BQSH-JCL-Prozedur fest.

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

    Die BQSH-JCL-Prozedur vor dem Hinzufügen der Java-Systemeigenschaften für IBM_JAVA_OPTIONS sieht so aus:

    # 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. Wenn Sie das Standardpasswort für den Trust Store changeit verwenden, dann müssen Sie die Systemeigenschaft trustStorePassword nicht festlegen. Die Proxyfunktionen werden von Apache HttpComponents HttpClient bereitgestellt.

    Sie müssen ein Zertifikat-Truststore-Format verwenden, das von Mainframe Connector unterstützt wird. Der Zertifikat-Truststore kann in den folgenden Formaten gespeichert werden:

    • PKCS12 (.p12) : Kann viele Zertifikate enthalten und erfordert ein Passwort.
    • JKS (.jks) : Kann viele Zertifikate enthalten und erfordert ein Passwort.
    • PEM (.pem) : Kann viele Zertifikate enthalten, die als base64 codiert sind.
    • Binär (.der) : Enthält ein Zertifikat pro Datei.

    Wenn die Systemeigenschaft trustStore der Pfad zu einem Verzeichnis ist, wird das Verzeichnis gescannt und alle Zertifikate im Format .pem und .der im Verzeichnis werden als vertrauenswürdige Zertifikate hinzugefügt. Sie müssen PKCS12- oder JKS-Zertifikate manuell laden.

Wenn Sie jederzeit Änderungen an der BQSH-JCL-Prozedur vornehmen müssen, können Sie eine neuere Version in der unteren Umgebung Prozedur-Bibliothek (PROCLIB) bereitstellen. Diese Bibliothek wird vor der Systembibliothek SYSP.PROCLIB hinzugefügt, sodass die Änderungen in der unteren Umgebung geprüft werden können, bevor die Prozedur in SYSP.PROCLIB aktualisiert wird. So können Sie vermeiden, dass JCL-Prozeduren während des Tests auf eine neue aktualisierte Prozedur verweisen.

Beispiel für eine BQSH-JCL-Prozedur

Im Folgenden finden Sie ein Beispiel für eine BQSH-JCL-Prozedur. In dieser Prozedur wird das ENV Symbol verwendet, um auf die Anweisungen für die Java-Standardumgebung zu verweisen, und ist spezifisch für die Google Cloud Umgebung. So benötigen Sie nicht mehrere BQSH-Prozeduren für jede Umgebung. Wenn Sie Änderungen für eine bestimmte Umgebung vornehmen möchten, müssen Sie nur dieses Mitglied in der Google Cloud Umgebung in der Systembibliothek PARMLIB aktualisieren. Sie können beispielsweise eine neue JAR-Datei erstellen, eine andere IBM Java-Version verwenden oder die JSON-Schlüsseldatei mit Umgebungsvariablen ändern.

#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

Im Folgenden sehen Sie ein Beispiel für das DEV PARMLIB-Mitglied, in dem gezeigt wird, wie auf die JSON-Schlüsseldatei und die JAR-Datei der Mainframe Connector-Software verwiesen wird.

# 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

Nächste Schritte