Mainframe Connector API-Referenz

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

Produkt Befehl Beschreibung Unterstützt 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 Leistungsabstimmungen Funktionen. Weitere Informationen finden Sie unter Leistungsverbesserungen für die bq export-Befehl

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
Verwenden Sie diesen Befehl, um BigQuery-Ressourcen zu erstellen, z. B. integrierte Tabellen oder externe Tabellen, die Partitionierung und Clustering benötigen, einrichten können. Weitere Informationen finden Sie unter bq mk.

Sie können auch den Befehl bq mk verwenden, um ein BigQuery-Tabelle direkt aus dem Parsen von COBOL-Copybooks. Weitere Informationen 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 im 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 nicht die Das Flag --follow, wenn Sie ein normales Logging-Verhalten wünschen.

Bei einigen Abfrageergebnissen wird möglicherweise eine große Anzahl von Zeilen zurückgegeben, manchmal in Millionen. Damit die Ausgabe für Menschen lesbar bleibt, muss die Anzahl der Zeilen ist begrenzt. Um die Anzahl der angezeigten Zeilen zu steuern, verwenden Sie die Flag --report_row_limit. Verwenden Sie beispielsweise --report_row_limit 10, um die Ergebnisse auf 10 Zeilen zu begrenzen. Von ist die Anzahl der angezeigten Zeilen auf 30 begrenzt.

Informationen zur Verwendung der bq query-Parameterisierung finden Sie unter bq-Abfrageparameter.

Weitere Informationen finden Sie unter bq query. 		Ja
Mit diesem Befehl können Sie eine BigQuery-Ressource endgültig löschen. Als Mit diesem Befehl wird eine Ressource endgültig gelöscht. Wir empfehlen, sie zu verwenden. mit Vorsicht. Weitere Informationen finden Sie unter bq rm. Nein
Cloud Storage-Befehle Verwenden Sie diesen Befehl, um Text oder Binärdaten in Cloud Storage zu 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 Anwendungsquellencode 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 Eingabe-Dataset, DSN. Dieses Flag (falls angegeben) überschreibt INFILE DD.
  • --cobDsn: den DSN des Copybooks. Dieses Flag (falls angegeben) überschreibt 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.

Optional können Sie diesen Befehl verwenden, um mit dem gRPC-Dienst für Mainframe-Connector die auf einer VM im Mainframe ausgeführt werden. Legen Sie dazu SRVHOST fest. und SRVPORT Umgebungsvariablen oder geben Sie den Hostnamen und mithilfe von Befehlszeilenoptionen. 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 Folgendes tun: 		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 gsutil durch Akzeptieren eines Schemas in Form eines COPYBOOK DD, zur Transcodierung von COBOL-Datensätzen direkt in ORC, bevor sie in Cloud Storage 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 mithilfe eines Datasets bereitstellen. 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. Für Weitere Informationen finden Sie unter gcloud dataflow flex-template run. Nein
Verwenden Sie diesen Befehl, um eine HTTP-Anfrage an einen Webdienst oder REST APIs zu senden. Nein
Verwenden Sie diesen Befehl, um die erforderlichen Systemdaten Ausgabe (stdout). So kann das Mainframe Connector-Supportteam die erforderlichen Informationen zur Diagnose eines Problems erfassen, ohne dass eine umfangreiche Kundeninteraktion erforderlich ist.
Je nach verwendetem Flag gibt der Befehl systemreport Folgendes aus: folgenden Systemdaten:
  • --supported_ciphers: unterstützte Chiffren
  • --available_security_providers: Verfügbare Sicherheitsanbieter
 Nein

Konfiguration zur Leistungsoptimierung für den Befehl bq export

Der Mainframe-Connector unterstützt die folgende Leistungsoptimierung Konfiguration 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 „true“ setzen, Exporter behält 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 die doppelte Anzahl von Threads.
  • transcoding_buffer (optional): Legen Sie die Größe der Transcodierung fest. Zwischenspeicher pro Thread in MB. Der Standardwert ist 20 MB.

Sie können auch versuchen, das Transportfenster zu vergrößern, indem Sie die OVERRIDE_GRPC_WINDOW_MB 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 durch 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 eine Vorschau der generierten CREATE TABLE SQL, ohne die Tabelle tatsächlich in BigQuery

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 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  "     "

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

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 finden Sie ein Beispiel mit mehreren Parametern.

Abfragedatei

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

Ausführungsbeispiel

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

Datei aus Cloud Storage in Ihren Mainframe kopieren

Mit dem Befehl gsutil cp können Sie eine Datei aus Cloud Storage in ein Mainframe-Dataset umwandeln. Partitionierte Daten können nicht Datasets (PDS).

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 im Mainframe vorhanden ist, achten Sie darauf, das --replace-Element an den Befehl an.

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 Aufnahmeformat (RECFM) der Mainframe-Datei. Das gültige 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 dieser Wert auf 0 gesetzt ist, die optimale Blockgröße. Der Wert muss eine Ganzzahl größer als 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.

Ausführungsbeispiel

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.

  • Verwenden Sie das Flag --parallelism, um die Anzahl der Threads festzulegen. Der Standardwert ist 1 (einzelner Thread).
  • Verwenden Sie das Argument --maxChunkSize, um die maximale Größe der einzelnen Elemente festzulegen. Chunk. Jeder Block hat eine eigene ORC-Datei (Optimized Row Columnar). Erhöhen Sie diesen Wert, um die Anzahl der erstellten Chunks zu reduzieren. Dies führt jedoch zu einem höheren Speicherbedarf während des Transcodierungsvorgangs. Weitere Informationen finden Sie unter maxChunkSize-Argument analysieren. Der Standardwert ist 128 MiB.
  • Verwenden Sie das Argument --preload_chunk_count, um die Datenmenge auf Vorab in den Arbeitsspeicher laden, während alle Worker ausgelastet sind. Dieses Argument kann zulasten des Arbeitsspeichers. 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 genügend Arbeitsspeicher vorhanden ist, sollten Sie die Blockgröße auf 256 MiB oder sogar auf 512 MiB erhöhen, da dadurch und die Fertigstellung von Cloud Storage-Objekten. Bei kleinen Dateien können Sie mit weniger Threads und kleineren Chunks möglicherweise bessere Ergebnisse erzielen.

maxChunkSize-Argument parsen

Für das Flag maxChunkSize sind Werte in Form eines Betrags und eines Maßeinheit, 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. Sie können keine Teilbeträge angeben. Verwenden Sie beispielsweise 716 KiB anstelle von 0,7 MiB.