Mainframe Connector API-Referenz

In der folgenden Tabelle sind die BigQuery-, Cloud Storage- und andere Google Cloud-Befehle aufgeführt, die Sie mit dem Mainframe-Connector verwenden können.

Produkt Befehl Beschreibung Unterstützt die Remote-Transcodierung
BigQuery-Befehle Mit diesem Befehl können Sie eine Binärdatei erstellen. Der Befehl akzeptiert ein COPYBOOK DD als Eingabe.

Der Befehl bq export unterstützt einige Funktionen zur Leistungsoptimierung. Weitere Informationen finden Sie unter Leistungsverbesserungen für den Befehl bq export.

Mit dem Befehl bq export können Sie benutzerdefinierte Zeichensätze verwenden. Weitere Informationen finden Sie unter Benutzerdefinierte Zeichensätze verwenden.

Hinweis:Mit dem Befehl bq export können keine großen Bigtable-Tabellen exportiert werden. Wenn Sie große Tabellen exportieren möchten, fügen Sie dem Befehl bq export das Flag -allowLargeResults hinzu, um Fehler zu vermeiden.		 Ja
Verwenden Sie diesen Befehl, um Daten in eine Tabelle zu laden. Weitere Informationen finden Sie unter bq load. Nein
Mit diesem Befehl können Sie BigQuery-Ressourcen wie integrierte Tabellen oder externe Tabellen erstellen, für die Partitionierung und Clustering erforderlich sind. Weitere Informationen finden Sie unter bq mk.

Mit dem Befehl bq mk können Sie auch direkt aus dem Parsen von COBOL-Copybooks eine BigQuery-Tabelle generieren. Weitere Informationen finden Sie unter BigQuery-Tabelle aus einem Copybook erstellen. 		Nein
Mit diesem Befehl können Sie einen Abfragejob erstellen, der die angegebene SQL-Abfrage ausführt. Der Befehl liest die SQL-Abfrage entweder aus dem Flag --sql oder aus QUERY DD. Wenn beide angegeben sind, hat die Abfrage im --sql-Flag Vorrang.

Mit dem Flag --follow=true können Sie einen Bericht generieren, der die Ergebnisse einer Auswahlabfrage enthält. Um diesen Bericht in eine Datei auf dem Mainframe zu schreiben, definieren Sie eine DD-Anweisung AUDITL, die auf die Datei verweist, die den Bericht zu den Audit-Logs enthalten soll. Verwenden Sie das Flag --follow nicht, wenn Sie das normale Logging-Verhalten wünschen.

Einige Abfrageergebnisse können eine große Anzahl von Zeilen zurückgeben, manchmal Millionen. Damit die Ausgabe für Menschen lesbar bleibt, ist die Anzahl der angezeigten Zeilen begrenzt. Mit dem Flag --report_row_limit können Sie die Anzahl der angezeigten Zeilen steuern. Verwenden Sie beispielsweise --report_row_limit 10, um die Ergebnisse auf 10 Zeilen zu begrenzen. Standardmäßig ist die Anzahl der angezeigten Linien auf 30 beschränkt.

Informationen zur Verwendung der bq query-Parametrisierung finden Sie unter Parametrisierung von bq-Abfragen.

Weitere Informationen finden Sie unter bq query. 		Ja
Mit diesem Befehl können Sie eine BigQuery-Ressource endgültig löschen. Da mit diesem Befehl eine Ressource endgültig gelöscht wird, sollten Sie ihn mit Vorsicht verwenden. Weitere Informationen finden Sie unter bq rm. Nein
Cloud Storage-Befehle Mit diesem Befehl können Sie Text- oder Binärdaten in Cloud Storage kopieren. Mit dem einfachen Binärkopiemodus können Sie einen Datensatz im Rahmen einer Datenpipeline unverändert von IBM z/OS nach Cloud Storage kopieren. Optional können Sie die Zeichencodierung von EBCDIC (Extended Binary Coded Decimal Interchange Code) in ASCII UTF-8 konvertieren und Zeilenschaltungen hinzufügen.

Mit diesem Befehl können Sie auch den in Job Control Language (JCL) definierten Anwendungsquellcode kopieren. 		Nein
gsutil-Dienstprogramm Mit diesem Befehl können Sie einen Datensatz transkodieren und im Dateiformat Optimized Row Columnar (ORC) in Cloud Storage schreiben. Der Befehl liest die Daten aus dem INFILE-DD und das Datensatzlayout aus der COPYBOOK-Datei. Wenn der Befehl die Daten aus einer DSN-Datei (Datenquellenname) lesen soll, verwenden Sie die folgenden Flags:
  • --inDsn: das DSN des Eingabedatensatzes. Wenn dieses Flag angegeben ist, wird INFILE DD überschrieben.
  • --cobDsn: den DSN des Copybooks. Wenn angegeben, überschreibt dieses Flag COPYBOOK DD.


Der Befehl öffnet dann eine konfigurierbare Anzahl paralleler Verbindungen zur Cloud Storage API und transkodiert den COBOL-Datensatz in das spaltenorientierte und GZIP-komprimierte ORC-Dateiformat. Sie können mit einem Komprimierungsverhältnis von etwa 35% rechnen.

Mit diesem Befehl können Sie optional mit dem gRPC-Dienst des Mainframe-Connectors interagieren, der auf einer VM auf dem Mainframe ausgeführt wird. Legen Sie dazu die Umgebungsvariablen SRVHOST und SRVPORT fest oder geben Sie den Hostnamen und die Portnummer mithilfe von Befehlszeilenoptionen an. Wenn der gRPC-Dienst verwendet wird, wird der Eingabedatensatz zuerst vom Mainframe Connector in Cloud Storage kopiert. Anschließend wird ein Remote Procedure Call (RPC) ausgeführt, um den gRPC-Dienst zum Transcodieren der Datei aufzufordern.

Mit dem Befehl gsutil cp können Sie auch die folgenden Aufgaben ausführen: 		Ja
Mit diesem Befehl können Sie Buckets oder Objekte in einem Bucket löschen. Weitere Informationen finden Sie unter rm – Objekte entfernen. Nein
gszutil-Dienstprogramm Das gszutil-Dienstprogramm wird mit dem IBM JZOS Java SDK ausgeführt und bietet einen Shell-Emulator, der gsutil- und BigQuery-Befehlszeilenaufrufe mit JCL akzeptiert.

Das Dienstprogramm gszutil erweitert die Funktionalität des Dienstprogramms gsutil, indem es ein Schema in Form eines COPYBOOK DD akzeptiert und damit COBOL-Datasets direkt in ORC transkodiert, bevor sie in Cloud Storage hochgeladen werden. Mit dem Dienstprogramm gszutil können Sie auch BigQuery query und load mit JCL ausführen.

Das Dienstprogramm gszutil funktioniert mit dem gRPC-Server, wodurch Sie den MIPS-Verbrauch (Millionen von Anweisungen pro Sekunde) reduzieren können. Wir empfehlen, in Produktionsumgebungen das Dienstprogramm gszutil zu verwenden, um Binärdateien in Cloud Storage in das ORC-Format zu konvertieren. 		Nein
Weitere Befehle Mit diesem Befehl können Sie eine Nachricht an ein Pub/Sub-Thema senden. Sie können die Nachricht über die Befehlszeile oder über einen Datensatz angeben. Nein
Mit diesem Befehl können Sie die Ausführung einer Dataflow-Flex-Vorlage auslösen. Mit dem Befehl wird ein Job über den angegebenen Pfad der Flex-Vorlage ausgeführt. Weitere Informationen finden Sie unter gcloud dataflow flex-template run. Nein
Mit diesem Befehl können Sie eine HTTP-Anfrage an einen Webservice oder REST APIs senden. Nein
Mit diesem Befehl werden die erforderlichen Systemdaten in der Standardausgabe (stdout) ausgegeben. So kann das Mainframe Connector-Supportteam die erforderlichen Informationen zur Diagnose eines Problems erfassen, ohne dass umfangreiche Kundeninteraktionen erforderlich sind.
Je nach verwendetem Flag werden mit dem Befehl systemreport die folgenden Systemdaten ausgegeben:
  • --supported_ciphers: Unterstützte Chiffren
  • --available_security_providers: Verfügbare Sicherheitsanbieter
 Nein

Benutzerdefinierte Zeichensätze verwenden

Der Mainframe-Connector unterstützt verschiedene Zeichensätze, die Bytes in BigQuery-Strings und umgekehrt decodieren. Mit dem Mainframe-Connector können Sie einen benutzerdefinierten Zeichensatz konfigurieren. Sie können einen benutzerdefinierten Zeichensatz konfigurieren, indem Sie eine Unicode Character Mapping-Datei (UCM) erstellen. Der Mainframe-Connector unterstützt die folgende Teilmenge des UCM-Formats:

<code_set_name>               "<name>"
<uconv_class>                 "SBCS"
<subchar>                     \x1A #Example

CHARMAP
#_______ _________
<U0000> \x00 |0       #For the third column, only 0 is supported.
<U0001> \x01 |0
#etc
END CHARMAP

Wenn Sie einen benutzerdefinierten Zeichensatz verwenden möchten, definieren Sie eine Konfigurationsdatei im UCM-Format. Sie können diesen benutzerdefinierten Zeichensatz mit den Befehlen gsutil cp oder bq export verwenden, indem Sie das Flag --encoding=charset festlegen.

Beachten Sie beim Erstellen eines benutzerdefinierten Zeichensatzes Folgendes:

  • Beachten Sie beim Definieren einer UCM-Datei Folgendes:
    • Der Mainframe-Connector unterstützt nur benutzerdefinierte Zeichensätze mit einem Ein-Byte-Zeichensatz (Single Byte Character Set, SBCS).
    • Der Mainframe-Connector unterstützt nur den UCM-Genauigkeitsindikator |0.
    • Die UCM-Dateien müssen sich in den z/OS Unix System Services (USS) und nicht auf einem Dataset mit mehreren virtuellen Speicherpartitionen (MVS PDS) befinden.
    • Die UCM-Dateien müssen im ASCII-Format (American Standard Code for Information Interchange) und nicht im EBCDIC-Format (Extended Binary Coded Decimal Interchange Code) gespeichert sein.
  • Geben Sie eine explizite Zuordnung für jeden möglichen einzelnen Bytewert zu einem Unicode-Zeichen an. Wenn Sie sich nicht sicher sind, welchem Unicode-Zeichen Sie ein Byte zuordnen möchten, empfehlen wir, U+FFFD zu verwenden. Sie können demselben Unicode-Zeichen unterschiedliche Bytefolgen zuordnen. In diesen Fällen ist die Zuordnung jedoch nicht bidirektional. Wenn Sie also Daten in BigQuery laden und später wieder in eine Binärdatei exportieren, kann sich die Ausgabe von der ursprünglichen Eingabe unterscheiden.
  • Die Bytefolgen in der zweiten Spalte müssen eindeutig sein. Wenn mehrere Bytefolgen demselben Unicode-Zeichen zugeordnet sind, wird dieses Unicode-Zeichen in eine Bytefolge der zuletzt definierten Zuordnung in der UCM-Datei decodiert.
  • Achten Sie darauf, dass der Mainframe-Connector die UCM-Datei finden kann, indem Sie die Umgebungsvariable BQSH_FEATURE_CUSTOM_CHARSET auf den Pfad der UCM-Datei festlegen. Wenn Sie mehrere Zeichensätze verwenden möchten, können Sie die Pfade zu den Zeichensätzen durch ein Semikolon als Trennzeichen trennen. Beispiel: BQSH_FEATURE_CUSTOM_CHARSET=path1;path2 path kann entweder auf eine lokale Datei oder auf eine in Cloud Storage gespeicherte Datei verweisen. Wenn du die Befehle gsutil cp oder bq export mit dem Flag --remote ausführst, um eine Remote-Transcodierung durchzuführen, verwendet Mainframe Connector den lokalen Wert, der für die Umgebungsvariable BQSH_FEATURE_CUSTOM_CHARSET festgelegt ist. Das gilt auch, wenn Sie Mainframe Connector im Standalone-Modus ausführen. Wenn sich das --encoding-Flag auf einen benutzerdefinierten Zeichensatz bezieht, der nicht dem Wert entspricht, den Sie für BQSH_FEATURE_CUSTOM_CHARSET festgelegt haben, oder wenn Sie BQSH_FEATURE_CUSTOM_CHARSET nicht festgelegt haben, wird der Befehl mit einer Fehlermeldung beendet.

Konfiguration zur Leistungsoptimierung für den Befehl bq export

Der Mainframe-Connector unterstützt die folgende Konfiguration zur Leistungsoptimierung für den Befehl bq export:

  • exporter_thread_count: (Optional) Legen Sie die Anzahl der Worker-Threads fest. Der Standardwert ist 4.
  • max_read_streams: (Optional) Legen Sie die maximale Anzahl von Lesestreams fest. Der Standardwert entspricht dem für exporter_thread_count festgelegten Wert.
  • order_response: (Optional) Wenn Sie dieses Flag auf „wahr“ setzen, behält der Exporter die Reihenfolge der Abfrageergebnisse bei. Dieses Flag wirkt sich auf die Exportleistung aus. Der Standardwert ist „false“.
  • max_read_queue: (Optional) Legen Sie die maximale Anzahl der Lesedatensätze fest. Der Standardwert ist das Doppelte der Anzahl der Threads.
  • transcoding_buffer: (Optional) Größe des Transcodierungspuffers pro Thread in MB festlegen. Der Standardwert ist 20 MB.

Sie können auch versuchen, die Größe des Transportfensters zu erhöhen, indem Sie die Umgebungsvariable OVERRIDE_GRPC_WINDOW_MB festlegen, um die Leistung zu verbessern. Die Standardfenstergröße beträgt 4 MB.

BigQuery-Tabelle aus einem Arbeitsbuch erstellen

Mit dem Befehl bq mk können Sie eine BigQuery-Tabelle direkt aus dem Parsen von COBOL-Copybooks generieren. Der native Copybook-Parser extrahiert Standardwerte aus der VALUE-Klausel in einem Copybook und weist sie den entsprechenden Spalten in einer neu erstellten BigQuery-Tabelle zu.

Zum Testen dieser Funktion bietet der Befehl bq mk auch einen Testlauf. In diesem Modus können Sie sich eine Vorschau des generierten CREATE TABLE SQL-Befehls ansehen, ohne die Tabelle tatsächlich in BigQuery zu erstellen.

Der Befehl bq mk bietet die folgenden Konfigurationsoptionen zur Unterstützung dieser Funktion:

  • --schema_from_copybook: Gibt das Copybook an, das zum Erstellen der Tabelle verwendet werden soll.
  • --dry_run: (Optional) Wenn diese Option aktiviert ist, wird nur der generierte CREATE TABLE SQL-Befehl ausgegeben, ohne dass er ausgeführt wird. Dieses Flag ist standardmäßig auf „false“ gesetzt.
  • --tablespec "[PROJECT_ID]:[DATASET].[TABLE]": Gibt die BigQuery-Projekt-ID, das Dataset und den Tabellennamen für die Zieltabelle an.
  • --encoding: Gibt die Codierung an, die zum Lesen der Copybook-Datei verwendet wird. Der Standardwert ist CP037.

Die folgenden VALUE-Klauseln werden unterstützt:

VAR1   PIC 9(5) VALUE 55.
*-- Set VAR1 to 55
VAR1   PIC X(5) VALUE aaaa. Set VAR1 to aaaa
VAR1   PIC 9(3) COMP VALUE 3. Set VAR1 to 3 (binary)
VAR1   PIC [9(5), X(5)] VALUE <literal>. Set VAR1 to <literal>
VAR1   PIC [9(5), X(5)] VALUE ZERO. Set VAR1 to 0 or "0"
VAR1   PIC [9(5), X(5)] VALUE ZEROS. Set VAR1 to 0 or "00000"
VAR1   PIC [9(5), X(5)] VALUE ZEROES. Set VAR1 to 0 or "00000"
VAR1   PIC X(5) VALUE SPACE. Set VAR1 to  " "
VAR1   PIC X(5) VALUE SPACES. Set VAR1 to  "     "

HIGH-VALUE- und LOW-VALUE-Klauseln werden nur für alphanumerische Variablen unterstützt.

VAR1   PIC X(5) VALUE HIGH-VALUE. Set VAR1 to `X"FF "
VAR1   PIC X(5) VALUE HIGH-VALUES. Set VAR1 to 0 or `X"FFFFFFFFFF"
VAR1   PIC X(5) VALUE LOW-VALUE. Set VAR1 to `X"00" (NULL)
VAR1   PIC X(5) VALUE LOW-VALUES. Set VAR1 to `X"0000000000" (NULL)
VAR1   PIC X(5) VALUE QUOTE. Set VAR1 to `"`
VAR1   PIC X(5) VALUE `QUOTES`. Set VAR1 to 0 or `""""`
VAR1   PIC [9(5), X(5)] VALUE NULL. Not defined and won't be supported
VAR1   PIC [9(5), X(5)] VALUE ALL <literal>. Set all fields with the value ALL to <literal>

bq query Parametrisierung

Mit dem Mainframe Connector können Sie parametrisierte Abfragen mit bq query verwenden.

Im Folgenden finden Sie ein Beispiel für die Verwendung einer parametrisierten bq query-Abfrage:

Abfragedatei

SELECT * FROM `bigquery-public-data.samples.wikipedia` WHERE title = @xtitle

Im folgenden Beispiel werden mehrere Parameter verwendet.

Abfragedatei

SELECT * FROM bigquery-public-data.samples.wikipedia WHERE title = @mytitle AND num_characters > @min_chars;

Beispiel für die Ausführung

bq query \
--project_id=mainframe-connector-dev \
--location="US" \
--parameters=mytitle::Hippocrates,min_chars:INT64:42600

Probelauf des Befehls gsutil cp ausführen

Mit dem Befehl gsutil cp wird eine QSAM-Datei (Queued Sequential Access Method) mithilfe eines COBOL-Copybooks decodiert und eine ORC-Datei in Cloud Storage generiert. Sie können einen Probelauf des Befehls gsutil cp mit dem Flag dry_run ausführen und die folgenden Schritte testen:

  • COBOL-Copybook oder Datendatei parsen und prüfen, ob sie mit Mainframe Connector kompatibel ist
  • Eine QSAM-Datei decodieren, ohne sie in Cloud Storage zu schreiben.

Verwenden Sie den folgenden Befehl, um einen Probelauf durchzuführen:

gsutil cp \
--dry_run \
gs://result-dir

Wenn alle Schritte erfolgreich ausgeführt wurden, wird der Befehl mit dem Rückgabecode 0 beendet. Falls Probleme auftreten, wird eine Fehlermeldung angezeigt.

Wenn Sie das Flag dry_run verwenden, werden alle Statistiken wie die Gesamtzahl der gelesenen Byte, die Anzahl der geschriebenen Datensätze und die Gesamtzahl der Fehler protokolliert.

Wenn Sie das Flag dry_run verwenden und die Datenquelle nicht vorhanden ist, gibt der Befehl keinen Fehler zurück. Stattdessen wird nur der Copybook-Parser geprüft und die Ausführung abgeschlossen.

Dateien aus Cloud Storage in den Mainframe kopieren

Mit dem Befehl gsutil cp können Sie eine Datei aus Cloud Storage in einen Mainframe-Datensatz kopieren. Partitionierte Datensätze (PDS) können nicht kopiert werden.

Wenn Sie eine Datei aus Cloud Storage in einen Mainframe-Datensatz kopieren möchten, geben Sie in JCL den DSN und die Speicheranforderungen der Datei an, die Sie auf den Mainframe herunterladen möchten, wie im folgenden Beispiel gezeigt:

//OUTFILE  DD DSN=MAINFRAME.DSN.FILE,DISP=(,CATLG),
//            RECFM=FB,DSORG=PS,
//            SPACE=(10,(2,1),RLSE),
//            AVGREC=M,
//            UNIT=SYSDA
//SYSPRINT DD SYSOUT=*
//SYSDUMP  DD SYSOUT=*
//STDIN DD *

Geben Sie den Befehl gsutil cp im folgenden Format an. Wenn die Datei bereits auf Ihrem Mainframe vorhanden ist, fügen Sie dem Befehl das Flag --replace hinzu.

gsutil cp GCS_URI DSN --recfm=RECFM --lrecl=LRECL --blksize=BLKSIZE --noseek

Ersetzen Sie Folgendes:

  • GCS_URI: Der Cloud Storage-URI (Uniform Resource Identifier) der Cloud Storage-Datei. Beispiel: gs://bucket/sample.mainframe.dsn.
  • DSN: Der DSN-Zielspeicherort auf dem Mainframe.
  • RECFM: Das Datensatzformat (RECFM) der Mainframe-Datei. Gültige Werte sind „F“, „FB“ und „U“. Bei diesen Werten wird die Groß- und Kleinschreibung nicht berücksichtigt.
  • LRECL: (Optional) Die Datensatzlänge (LRECL) der Datei. Der Wert muss eine Ganzzahl >= 0 sein. Wenn LRECL nicht angegeben wird, wird davon ausgegangen, dass die Datei im Datensatzformat mit undefinierter Länge (U) vorliegt.
  • BLKSIZE: (Optional) Die Blockgröße der Datei. Wenn der Wert auf „0“ gesetzt ist, wird die optimale Blockgröße vom System ermittelt. Der Wert muss eine Ganzzahl >= 0 sein. Wenn Sie keinen Wert angeben, wird die Datei als nicht blockierte Datei behandelt.
  • noseek: (Optional) Fügen Sie diesen Parameter hinzu, wenn Sie die Downloadleistung verbessern möchten. Dieses Flag ist standardmäßig auf „false“ (falsch) gesetzt, d. h. Suchvorgänge sind aktiviert.

Beispiel für die Ausführung

gsutil cp gs://sample-bucket/MAINFRAME.DSN.FILE MAINFRAME.DSN.FILE \
--lrecl=16 --blksize=0 --recfm=fb

Konfiguration zur Leistungsoptimierung für den Befehl gsutil cp

Der Mainframe-Connector unterstützt die folgende Konfiguration zur Leistungsoptimierung für den Befehl gsutil cp.

  • Mit dem Flag --parallelism können Sie die Anzahl der Threads festlegen. Der Standardwert ist 1 (einzelner Thread).
  • Mit dem Argument --maxChunkSize können Sie die maximale Größe der einzelnen Chunks festlegen. Jeder Block hat eine eigene ORC-Datei. Erhöhen Sie diesen Wert, um die Anzahl der erstellten Chunks zu reduzieren. Dies führt jedoch zu einem höheren Arbeitsspeicherbedarf während des Transcodierungsvorgangs. Weitere Informationen finden Sie unter maxChunkSize-Argument analysieren. Der Standardwert ist 128 MiB.
  • Mit dem Argument --preload_chunk_count können Sie die Datenmenge festlegen, die in den Arbeitsspeicher geladen werden soll, während alle Worker beschäftigt sind. Mit diesem Argument kann die Leistung verbessert werden, was jedoch zu einer höheren Arbeitsspeicherauslastung führt. Der Standardwert liegt bei 2.

Beispiel für die Ausführung

gsutil cp \
  --replace \
  --parser_type=copybook \
  --parallelism=8 \
  --maxChunkSize=256MiB \
  gs://$BUCKET/test.orc

In diesem Beispiel haben wir eine große Datei verwendet und daher 8 Threads, bei denen die Leitungsrate erreicht wird. Wenn Sie genügend Arbeitsspeicher haben, empfehlen wir, die Blockgröße auf 256 MiB oder sogar 512 MiB zu erhöhen, da dadurch der Overhead beim Erstellen und Fertigstellen von Cloud Storage-Objekten reduziert wird. Bei kleinen Dateien können Sie mit weniger Threads und kleineren Chunks möglicherweise bessere Ergebnisse erzielen.

Argument maxChunkSize parsen

Für das Flag maxChunkSize sind Werte in Form eines Betrags und einer Maßeinheit zulässig, z. B. 5 MiB. Sie können Leerzeichen zwischen Betrag und Größe verwenden.

Sie können den Wert in den folgenden Formaten angeben:

  • Java-Format:b/k/m/g/t für Byte, Kibibyte, Mebibyte, Gibibyte und Tebibyte
  • Internationales Format:KiB/MiB/GiB/TiB für Kibibyte, Mebibyte, Gibibyte und Tebibyte
  • Dezimalformat:b/kb/mb/gb/tb für Kilobyte, Megabyte, Gigabyte und Terabyte

Beim Parsen der Datengröße wird nicht zwischen Groß- und Kleinschreibung unterschieden. Bruchteile von Beträgen können nicht angegeben werden. Verwenden Sie beispielsweise 716 KiB anstelle von 0, 7 MiB.