Comandi dell'API Mainframe Connector

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

Utilizzare set di caratteri personalizzati

Mainframe Connector supporta diversi set di caratteri che decodificano i byte in stringhe BigQuery e viceversa. Mainframe Connector ti consente di configurare il tuo set di caratteri personalizzato. Puoi configurare un set di caratteri personalizzato creando un file di mappatura dei caratteri Unicode (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 in 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, verifica quanto segue:

• Quando definisci un file UCM, tieni presente quanto segue:
  • Mainframe Connector supporta solo set di caratteri personalizzati utilizzando un set di caratteri a byte singolo (SBCS).
  • Mainframe Connector supporta solo l'indicatore di precisione UCM |0.
  • Verifica che i file UCM si trovino in z/OS Unix System Services (USS) e non in un set di dati partizionato di archiviazione virtuale multipla (MVS PDS).
  • Verifica che i file UCM siano salvati in formato American Standard Code for Information Interchange (ASCII) e non in formato Extended Binary Coded Decimal Interchange Code (EBCDIC).
• Fornisci una mappatura esplicita per ogni possibile valore a byte singolo a un carattere Unicode. Se non sai con certezza a quale carattere Unicode vuoi mappare un byte, ti consigliamo di mapparlo a U+FFFD. Puoi mappare sequenze di byte diverse allo stesso carattere Unicode. Tuttavia, in questi casi la mappatura non è bidirezionale, ovvero quando carichi i dati in BigQuery e li esporti di nuovo in un file binario, l'output potrebbe differire dall'input originale.
• Verifica che le sequenze di byte nella seconda colonna siano univoche. Se più sequenze di byte vengono mappate allo stesso carattere Unicode, questo carattere Unicode viene decodificato in una sequenza di byte dell'ultima mappatura definita nel file UCM.
• Verifica che Mainframe Connector 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 a 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 si riferisce a un set 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 di lavoro. Il valore predefinito è 4.
• max_read_streams: (facoltativo) imposta il numero massimo di flussi di lettura. Il valore predefinito è uguale a quello impostato per exporter_thread_count.
• order_response: (Facoltativo) Se imposti questo flag su true, lo strumento di esportazione mantiene l'ordine dei risultati della query. Questo flag influisce sulle prestazioni 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 la dimensione della finestra di trasporto impostando la variabile di ambiente OVERRIDE_GRPC_WINDOW_MB per migliorare le prestazioni. La dimensione predefinita della finestra è 4 MB.

Crea una tabella BigQuery da un copybook

Puoi utilizzare il comando bq mk per generare una tabella BigQuery direttamente dall'analisi dei copybook COBOL. Il parser nativo di copybook estrae i valori predefiniti dalla clausola VALUE all'interno di un copybook 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 copybook da utilizzare per creare la tabella.
• --dry_run: (facoltativo) se attivato, il comando stampa solo il comando CREATE TABLE SQL generato senza eseguirlo. Questo flag è impostato su false per impostazione predefinita.
• --tablespec "[PROJECT_ID]:[DATASET].[TABLE]": specifica l'ID progetto BigQuery, il set di dati e il nome della tabella di destinazione.
• --encoding: specifica la codifica utilizzata per leggere il file copybook. 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 con parametri:

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 utilizzando un copybook COBOL e genera un file ORC su Cloud Storage. Puoi eseguire una prova dry run del comando gsutil cp utilizzando il flag dry_run e testare i seguenti passaggi:

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

Utilizza il comando seguente per eseguire una prova generale:

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

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

Quando utilizzi il flag dry_run, vengono registrate tutte le statistiche, ad esempio il totale dei byte letti, il numero di record scritti e il totale degli errori.

Se utilizzi il flag dry_run e l'origine dati non esiste, il comando non restituisce un errore. Controlla solo il parser copybook e completa l'esecuzione.

Copia un file da Cloud Storage al tuo 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 partizionati (PDS).

Per copiare un file da Cloud Storage a un set di dati mainframe, specifica i requisiti di spazio e DSN 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à sul mainframe, verifica 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) 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 >= 0. Se LRECL non è specificato, si presume che il file sia nel formato di record a lunghezza indefinita (U).
• BLKSIZE: (Facoltativo) le dimensioni del blocco del file. Se impostato su 0, il sistema determinerà la dimensione del blocco ottimale. Il valore deve essere un numero intero maggiore o uguale a 0. Se non specifichi un valore, il file viene considerato non bloccato.
• noseek: (Facoltativo) Includi questo parametro se vuoi migliorare il rendimento dei download. Questo flag è impostato su false per impostazione predefinita, ovvero le operazioni di ricerca sono attive.

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 blocco avrà il proprio file ORC. Aumenta questo valore per ridurre il numero di chunk creati a scapito di requisiti di memoria più elevati durante il processo di transcodifica. Per maggiori dettagli, vedi Analizzare l'argomento maxChunkSize. Il valore predefinito è 128 MiB.
• Utilizza l'argomento --preload_chunk_count per impostare la quantità di dati da precaricare nella memoria mentre 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 quindi abbiamo utilizzato 8 thread in corrispondenza della velocità di linea raggiunta. Se hai memoria sufficiente, ti consigliamo di aumentare le dimensioni del chunk a 256 MiB o anche 512 MiB, in quanto riduce la creazione dell'overhead e la finalizzazione degli oggetti Cloud Storage. Per i file di piccole dimensioni, l'utilizzo di meno thread e blocchi più piccoli potrebbe produrre risultati migliori.

Analizzare l'argomento maxChunkSize

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

Puoi fornire il valore nei seguenti formati:

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

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