Riferimento all'API Mainframe Connector

La tabella seguente elenca i comandi BigQuery, Cloud Storage e altri Google Cloud che puoi utilizzare con Mainframe Connector.

Prodotto Comando Descrizione Supporta la transcodifica da remoto
Comandi BigQuery Utilizza questo comando per creare un file binario. Il comando accetta un COPYBOOK DD come input.

Il comando bq export supporta alcune funzionalità di ottimizzazione del rendimento. Per ulteriori informazioni, consulta Miglioramenti del rendimento per il comando bq export.

Puoi utilizzare set di caratteri personalizzati con il comando bq export. Per ulteriori informazioni, consulta Utilizzare set di caratteri personalizzati.

Nota: il comando bq export non riesce a esportare tabelle Bigtable di grandi dimensioni. Per evitare errori, aggiungi il flag -allowLargeResults al comando bq export quando vuoi esportare tabelle di grandi dimensioni.		 Sì
Utilizza questo comando per caricare i dati in una tabella. Per ulteriori informazioni, consulta bq load. No
Utilizza questo comando per creare risorse BigQuery, come tabelle integrate o esterne, che richiedono la configurazione di partizionamento e clustering. Per ulteriori informazioni, consulta bq mk.

Puoi anche utilizzare il comando bq mk per generare una tabella BigQuery direttamente dall'analisi dei copybook COBOL. Per ulteriori informazioni, consulta Creare una tabella BigQuery da un archivio. 		No
Utilizza questo comando per creare un job di query che esegue la query SQL specificata. Il comando legge la query SQL dal flag --sql o da QUERY DD. Se vengono forniti entrambi, la query nel flag --sql ha la precedenza.

Utilizza il flag --follow=true per generare un report che mostri i risultati di una query selezionata. Per scrivere questo report in un file nel mainframe, definisci un'istruzione DD AUDITL che indichi il file che deve contenere il report sugli audit log. Non utilizzare il --follow flag se vuoi un normale comportamento di registrazione.

Alcuni risultati di query possono restituire un numero elevato di righe, a volte milioni. Affinché l'output rimanga leggibile, il numero di righe visualizzate è limitato. Per controllare il numero di righe visualizzate, utilizza il flag --report_row_limit. Ad esempio, utilizza --report_row_limit 10 per limitare i risultati a 10 righe. Per impostazione predefinita, il numero di righe visualizzate è limitato a 30.

Per utilizzare la parametrizzazione bq query, consulta la sezione Parametrizzazioni delle query bq.

Per ulteriori informazioni, consulta query bq. 		Sì
Utilizza questo comando per eliminare definitivamente una risorsa BigQuery. Poiché questo comando elimina definitivamente una risorsa, ti consigliamo di utilizzarlo con cautela. Per ulteriori informazioni, consulta bq rm. No
Comandi Cloud Storage Utilizza questo comando per copiare dati di testo o binari in Cloud Storage. Puoi utilizzare la modalità di copia binaria semplice per copiare un set di dati da IBM z/OS a Cloud Storage non modificato all'interno di una pipeline di dati. Facoltativamente, puoi convertire la codifica dei caratteri dal codice di interscambio decimale codificato in binario (EBCDIC) in ASCII UTF-8 e aggiungere interruzioni di riga.

Puoi utilizzare questo comando anche per copiare il codice sorgente dell'applicazione definito in JCL (Job Control Language). 		No
Utilità gsutil Utilizza questo comando per transcodificare un set di dati e scriverlo in Cloud Storage nel formato file ORC (Optimized Row Columnar). Il comando legge i dati dal DD INFILE e il layout dei record dal file COPYBOOK. Se vuoi che il comando legga i dati da un file DSN (Data Source Name), utilizza i seguenti flag:
  • --inDsn: il DSN del set di dati di input. Se specificato, questo flag sostituisce INFILE DD.
  • --cobDsn: il DSN del libro mastro. Se specificato, questo flag sostituisce COPYBOOK DD.


Il comando apre quindi un numero configurabile di connessioni parallele all'API Cloud Storage e transcodifica il set di dati COBOL nel formato file ORC compresso GZIP e colonnare. Puoi aspettarti un rapporto di compressione di circa il 35%.

Se vuoi, puoi utilizzare questo comando per interagire con il servizio gRPC di Mainframe Connector in esecuzione su una VM sul mainframe. A tale scopo, imposta le variabili di ambiente SRVHOST e SRVPORT oppure fornisci il nome host e il numero di porta utilizzando le opzioni della riga di comando. Quando viene utilizzato il servizio gRPC, il set di dati di input viene prima copiato in Cloud Storage da Mainframe Connector, quindi viene eseguita una chiamata di procedura remota (RPC) per indicare al servizio gRPC di transcodificare il file.

Puoi anche eseguire le seguenti attività con il comando gsutil cp: 		Sì
Utilizza questo comando per eliminare bucket o oggetti all'interno di un bucket. Per ulteriori informazioni, consulta rm - Rimuovere oggetti. No
Utilità gszutil L'utilità gszutil viene eseguita utilizzando l'SDK Java JZOS di IBM e fornisce un emulatore di shell che accetta invocazioni della riga di comando gsutil e BigQuery utilizzando JCL.

L'utilità gszutil estende la funzionalità dell'utilità gsutil accettando uno schema sotto forma di COPYBOOK DD, che viene utilizzato per transcodificare i set di dati COBOL direttamente in ORC prima del caricamento su Cloud Storage. L'utilità gszutil consente inoltre di eseguire BigQuery query e load utilizzando JCL.

L'utilità gszutil funziona con il server gRPC, che ti aiuta a ridurre il consumo di milioni di istruzioni al secondo (MIPS). Ti consigliamo di utilizzare l'utilità gszutil nel tuo ambiente di produzione per convertire i file binari in Cloud Storage in formato ORC. 		No
Altri comandi Utilizza questo comando per inviare un messaggio a un argomento Pub/Sub. Puoi fornire il messaggio utilizzando la riga di comando o un set di dati. No
Utilizza questo comando per attivare l'esecuzione di un Modello flessibile Dataflow. Il comando esegue un job dal percorso del modello flessibile specificato. Per maggiori informazioni, consulta gcloud dataflow flex-template run. No
Utilizza questo comando per effettuare una richiesta HTTP a un servizio web o ad API REST. No
Utilizza questo comando per stampare i dati di sistema necessari nell'output standard (stdout). In questo modo, il team di assistenza di Mainframe Connector può raccogliere le informazioni necessarie per diagnosticare un problema senza richiedere un'interazione approfondita con il cliente.
A seconda del flag utilizzato, il comando systemreport stampa i seguenti dati di sistema:
  • --supported_ciphers: crittografi supportati
  • --available_security_providers: fornitori di servizi di sicurezza disponibili
 No

Utilizzare set di caratteri personalizzati

Il connettore mainframe supporta diversi set di caratteri che decodificano i byte in stringhe BigQuery e viceversa. Mainframe Connector consente di configurare il tuo set di caratteri personalizzato. Puoi configurare un set di caratteri personalizzato creando un file Unicode Character Mapping (UCM). Mainframe Connector supporta il seguente sottoinsieme del formato UCM:

<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

Se vuoi utilizzare un set di caratteri personalizzato, definisci un file di configurazione nel formato UCM. Puoi utilizzare questo set di caratteri personalizzato con i comandi gsutil cp o bq export impostando il flag --encoding=charset.

Quando crei un set di caratteri personalizzato, assicurati di quanto segue:

  • Quando definisci un file UCM, tieni presente quanto segue:
    • Il connettore Mainframe supporta solo set di caratteri personalizzati che utilizzano un set di caratteri a byte singolo (SBCS).
    • Il connettore mainframe supporta solo l'indicatore di precisione UCM |0.
    • Assicurati che i file UCM si trovino in USS (Unix System Services) di z/OS e non in un set di dati partizionato con archiviazione virtuale multipla (PDS MVS).
    • Assicurati che i file UCM siano salvati nel formato ASCII (American Standard Code for Information Interchange) e non nel formato EBCDIC (Extended Binary Coded Decimal Interchange Code).
  • Fornisci una mappatura esplicita per ogni possibile valore di singolo byte a un carattere Unicode. Se non sai a quale carattere Unicode mappare un byte, ti consigliamo di mapparlo a U+FFFD. Puoi mappare diverse sequenze di byte allo stesso carattere Unicode. Tuttavia, in questi casi la mappatura non è bidirezionale, ovvero quando carichi i dati in BigQuery e poi li esporti di nuovo in un file binario, l'output potrebbe essere diverso dall'input originale.
  • Assicurati che le sequenze di byte nella seconda colonna siano univoche. Se più sequenze di byte sono mappate allo stesso carattere Unicode, questo carattere Unicode viene decodificato in una sequenza di byte dell'ultima mappatura definita nel file UCM.
  • Assicurati che il connettore mainframe possa trovare il file UCM impostando la variabile di ambiente BQSH_FEATURE_CUSTOM_CHARSET sul percorso del file UCM. Se vuoi utilizzare più set di caratteri, puoi fornire i percorsi di più set di caratteri separati dal delimitatore punto e virgola. Ad esempio: BQSH_FEATURE_CUSTOM_CHARSET=path1;path2. path può puntare a un file locale o a un file archiviato su Cloud Storage. Se esegui i comandi gsutil cp o bq export con il flag --remote per eseguire la transcodifica remota, Mainframe Connector utilizza il valore locale impostato per la variabile di ambiente BQSH_FEATURE_CUSTOM_CHARSET. Lo stesso vale quando esegui Mainframe Connector in modalità autonoma. Se il flag --encoding fa riferimento a un insieme di caratteri personalizzato che non corrisponde al valore impostato per BQSH_FEATURE_CUSTOM_CHARSET (o se non hai impostato BQSH_FEATURE_CUSTOM_CHARSET), il comando esce con un messaggio di errore.

Configurazione dell'ottimizzazione delle prestazioni per il comando bq export

Mainframe Connector supporta la seguente configurazione di ottimizzazione delle prestazioni per il comando bq export:

  • exporter_thread_count: (Facoltativo) Imposta il numero di thread worker. Il valore predefinito è 4.
  • max_read_streams: (Facoltativo) imposta gli stream di lettura massimi. Il valore predefinito è uguale a quello impostato per exporter_thread_count.
  • order_response: (Facoltativo) se imposti questo flag su true, l'esportatore mantiene l'ordine dei risultati della query. Questo flag influisce sul rendimento dell'esportazione. Il valore predefinito è false.
  • max_read_queue: (Facoltativo) Imposta il numero massimo di code di record di lettura. Il valore predefinito è il doppio del numero di thread.
  • transcoding_buffer: (Facoltativo) Imposta le dimensioni del buffer di transcodifica per thread in MB. Il valore predefinito è 20 MB.

Tieni presente che puoi anche provare ad aumentare le dimensioni della finestra di trasporto impostando la variabile di ambiente OVERRIDE_GRPC_WINDOW_MB per migliorare le prestazioni. La dimensione predefinita della finestra è 4 MB.

Creare una tabella BigQuery da un copybook

Puoi utilizzare il comando bq mk per generare una tabella BigQuery direttamente dall'analisi dei copybook COBOL. L'analizzatore di file di copia nativo estrae i valori predefiniti dalla clausola VALUE all'interno di un file di copia e li assegna alle colonne corrispondenti in una tabella BigQuery appena creata.

Per aiutarti a testare questa funzionalità, il comando bq mk fornisce anche una modalità di simulazione. Questa modalità ti consente di visualizzare l'anteprima del comando CREATE TABLE SQL generato senza creare effettivamente la tabella in BigQuery.

Il comando bq mk fornisce le seguenti opzioni di configurazione per supportare questa funzionalità:

  • --schema_from_copybook: specifica il modello da utilizzare per creare la tabella.
  • --dry_run: (Facoltativo) Se abilitato, il comando stampa solo il comando CREATE TABLE SQL generato senza eseguirlo. Questo indicatore è impostato su false per impostazione predefinita.
  • --tablespec "[PROJECT_ID]:[DATASET].[TABLE]": specifica l'ID progetto, il set di dati e il nome della tabella BigQuery per la tabella di destinazione.
  • --encoding: specifica la codifica utilizzata per leggere il file del libro mastro. Il valore predefinito è CP037.

Sono supportate le seguenti clausole VALUE:

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

Le clausole HIGH-VALUE e LOW-VALUE sono supportate solo per le variabili alfanumeriche.

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>

Parametrizzazione bq query

Mainframe Connector ti consente di utilizzare query con parametri con bq query.

Di seguito è riportato un esempio di come utilizzare una query bq query parametroizzata:

File di query

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

Di seguito è riportato un esempio con più parametri.

File di query

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

Esempio di esecuzione

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

Esegui una prova del comando gsutil cp

Il comando gsutil cp decodifica un file QSAM (Queued Sequential Access Method) utilizzando un copybook COBOL e genera un file ORC su Cloud Storage. Puoi eseguire una prova dry run del comando gsutil cp utilizzando il dry_run flag e testare i seguenti passaggi:

  • Analizza un file di dati o un copybook COBOL e controlla se è compatibile con Mainframe Connector.
  • Decodifica un file QSAM senza scriverlo in Cloud Storage.

Utilizza il seguente comando per eseguire una simulazione:

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

Se tutti i passaggi vengono eseguiti correttamente, il comando esce con il codice di ritorno 0. Se si verificano problemi, viene visualizzato un messaggio di errore.

Quando utilizzi il flag dry_run, vengono registrate tutte le statistiche, ad esempio i byte totaliletti, il numero di record scritti, gli errori totali.

Se utilizzi il flag dry_run e l'origine dati non esiste, il comando non restituisce un errore. Controlla solo l'interprete del modello e poi completa l'esecuzione.

Copiare un file da Cloud Storage al mainframe

Puoi utilizzare il comando gsutil cp per copiare un file da Cloud Storage a un set di dati mainframe. Tieni presente che non puoi copiare i set di dati partitioned (PDS).

Per copiare un file da Cloud Storage a un set di dati mainframe, specifica il DSN e i requisiti di spazio del file che vuoi scaricare sul mainframe in JCL, come mostrato nell'esempio seguente:

//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 *

Specifica il comando gsutil cp nel seguente formato. Se il file esiste già sulla tua mainframe, assicurati di aggiungere il flag --replace al comando.

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

Sostituisci quanto segue:

  • GCS_URI: l'URI (Uniform Resource Identifier) di Cloud Storage del file Cloud Storage. Ad esempio, gs://bucket/sample.mainframe.dsn.
  • DSN: la posizione di destinazione del DSN sul mainframe.
  • RECFM: il formato del record (RECFM) del file mainframe. I valori validi sono F, FB e U. Tieni presente che questi valori non fanno distinzione tra maiuscole e minuscole.
  • LRECL: (Facoltativo) La lunghezza del record (LRECL) del file. Il valore deve essere un numero intero maggiore o uguale a 0. Se LRECL non è specificato, si presume che il file sia nel formato di record con lunghezza non definita (U).
  • BLKSIZE: (facoltativo) la dimensione del blocco del file. Se impostato su 0, il sistema determinerà la dimensione ottimale del blocco. Il valore deve essere un numero intero maggiore o uguale a 0. Se non specifichi un valore, il file viene considerato sbloccato.
  • noseek: (Facoltativo) Includi questo parametro se vuoi migliorare il rendimento del download. Questo flag è impostato su false per impostazione predefinita, ovvero le operazioni di ricerca sono attivate.

Esempio di esecuzione

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

Configurazione dell'ottimizzazione delle prestazioni per il comando gsutil cp

Mainframe Connector supporta la seguente configurazione di ottimizzazione delle prestazioni per il comando gsutil cp.

  • Utilizza il flag --parallelism per impostare il numero di thread. Il valore predefinito è 1 (single threaded).
  • Utilizza l'argomento --maxChunkSize per impostare la dimensione massima di ogni blocco. Ogni chunk avrà il proprio file ORC. Aumenta questo valore per ridurre il numero di chunk creati a costo di requisiti di memoria più elevati durante il processo di transcodifica. Per maggiori dettagli, vedi Eseguire l'analisi dell'argomento maxChunkSize. Il valore predefinito è 128 MiB.
  • Utilizza l'argomento --preload_chunk_count per impostare la quantità di dati da precaricare nella memoria quando tutti i worker sono occupati. Questo argomento può migliorare le prestazioni a scapito della memoria. Il valore predefinito è 2.

Esempio di esecuzione

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

In questo esempio, abbiamo considerato un file di grandi dimensioni e abbiamo utilizzato 8 thread con una frequenza di riga raggiunta. Se hai memoria sufficiente, ti consigliamo di aumentare la dimensione del chunk a 256 MB o addirittura 512 MB, poiché riduce il sovraccarico di creazione e la finalizzazione degli oggetti Cloud Storage. Per i file di piccole dimensioni, l'utilizzo di meno thread e chunk più piccoli potrebbe produrre risultati migliori.

Analizza l'argomento maxChunkSize

Il flag maxChunkSize accetta valori sotto forma di importo e unità di misura, ad esempio 5 MiB. Puoi utilizzare spazi tra la quantità e l'intensità.

Puoi fornire il valore nei seguenti formati:

  • Formato Java: b/k/m/g/t, rispettivamente per byte, kibibyte, mebibyte, gibibyte e tebibyte
  • Formato internazionale: KiB/MiB/GiB/TiB, rispettivamente per kibibyte, mebibyte, gibibyte e tebibyte
  • Formato metrico: b/kb/mb/gb/tb, rispettivamente per kilobyte, megabyte, gigabyte e terabyte

L'analisi delle dimensioni dei dati non è sensibile alle maiuscole. Tieni presente che non puoi specificare importi parziali. Ad esempio, utilizza 716 KiB anziché 0,7 MiB.