Mainframe Connector auf dem Mainframe installieren

Der Mainframe-Connector wird als JVM-Prozess (Java Virtual Machine) im Kontext eines MVS-Batchjobs gestartet. Der Mainframe-Connector wird in der Regel mit einer JAR-Datei bereitgestellt, die einige erforderliche Abhängigkeiten enthält, die nicht zu den in der JVM enthaltenen IBM-Bibliotheken gehören. In den folgenden Abschnitten wird die Installation des Mainframe Connectors ausführlich beschrieben.

Hinweise

Mainframe Connector installieren

So installieren Sie Mainframe Connector:

  1. Laden Sie die vorkonfigurierte JAR-Datei herunter. Kopieren Sie die Datei mainframe-connector-shadow-VERSION-all.jar in den Pfad, der im Abschnitt Java Classpath der BQSH-Job Control Language (JCL)-Prozedur in Schritt 7 angegeben ist. VERSION ist die Version von Mainframe Connector.

  2. Wenn Sie von Ihrem Mainframe auf Google Cloud-Dienste 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.

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

    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 gelesen werden kann, die Berechtigungen für den Zugriff auf das Dienstkonto haben. Die JSON-Schlüsseldatei kann von UNIX System Services (USS) nicht gelesen werden, wenn sie richtig übertragen wurde.

  4. Verwenden Sie FTP im Binärmodus, um die in Schritt 1 heruntergeladene JAR-Datei an den folgenden Speicherort auf Ihrem Mainframe hochzuladen.

     /opt/google/mainframe-connector/VERSION/

    Ersetzen Sie Version durch die Version der JAR-Datei.

    Dies ist der empfohlene Pfad für die Bereitstellung der JAR-Datei. Sie können auch einen Pfad verwenden, den ein Websiteadministrator ausgewählt hat.

  5. Führen Sie den folgenden Befehl aus, um zu prüfen, ob die JAR-Datei richtig übertragen wurde. Beachten Sie, dass die Option -t den Inhalt der JAR-Datei auflistet.

     jar -tvf JAR_FILE_NAME

    Ersetzen Sie JAR_FILE_NAME durch den Namen der JAR-Datei.

  6. Erstellen Sie eine Kopie der folgenden BQSH-JCL-Prozedur und ersetzen Sie die folgenden Variablen.

    In der BQSH-JCL-Prozedur gibt BQSH_ROOT_LOGGER=DEBUG an, dass das Debug-Logging aktiviert ist. Wenn Sie das Debug-Logging deaktivieren möchten, kommentieren Sie die Zeile aus oder geben Sie für die Variable einen anderen Wert als DEBUG an.

    Wenn Sie Mainframe Connector so konfigurieren möchten, dass Protokollinformationen in Cloud Logging geschrieben werden, legen Sie die Umgebungsvariablen LOG_PROJECT und LOG_ID wie im folgenden Beispiel gezeigt fest.

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

    • GKEY_FILE_PATH mit dem Pfad zur JSON-Schlüsseldatei aus Schritt 3.
    • JAR_FILE_PATH durch den Pfad zum Verzeichnis mit der JAR-Datei.
    • PROJECT_NAME durch das Projekt, für das das Protokoll in Cloud Logging erstellt wird
    • LOG_ID_NAME durch den Namen des Logs
    //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. Wenn Sie den Mainframe-Connector für die Verwendung mit einem TLS-Abfang-Proxy konfigurieren möchten, 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

    So fügen Sie die Java-Systemeigenschaften für IBM_JAVA_OPTIONS in der BQSH-JCL hinzu:

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

    Sie müssen ein Zertifikats-Trust-Store-Format verwenden, das vom Mainframe Connector unterstützt wird. Der Zertifikats-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, die sich darin befinden, werden als vertrauenswürdige Zertifikate hinzugefügt. PKCS12- oder JKS-Zertifikate müssen manuell geladen werden.

Wenn Sie jederzeit Änderungen an der BQSH-JCL-Prozedur vornehmen müssen, können Sie eine neuere Version in der unteren Umgebung in der Procedure Library (PROCLIB) bereitstellen. Diese Bibliothek wird vor der Systembibliothek SYSP.PROCLIB hinzugefügt, damit die Änderungen an der niedrigeren Umgebung geprüft werden können, bevor das Verfahren in SYSP.PROCLIB aktualisiert wird. So müssen Sie die JCL-Prozeduren nicht aktualisieren, damit sie 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. Bei diesem Verfahren wird das Symbol ENV verwendet, um auf die Java-Standardumgebungsausdrücke zu verweisen. Es ist spezifisch für die Google Cloud-Umgebung. So sind nicht mehrere BQSH-Vorgänge für jede Umgebung erforderlich. 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 mithilfe von Umgebungsanweisungen ä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 Beispiel für das Mitglied DEV PARMLIB wird gezeigt, 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