Comandos da API Mainframe Connector

A tabela seguinte apresenta os comandos do BigQuery, Cloud Storage e outros Google Cloud que pode usar com o conetor do mainframe.

Nota: para os comandos que suportam a execução remota, pode usar a opção remoteUrl em vez de remoteHost e remotePort. A opção remoteUrl tem de conter o esquema, o anfitrião e a porta. Se o esquema for https, e não for fornecida nenhuma trust store como opção trustCertCollectionFilePath ou variável de ambiente TRUST_CERT_COLLECTION_FILE_PATH, é usada a trust store predefinida do sistema.

Produto	Comando	Descrição	Suporta transcodificação remota
Comandos do BigQuery	bq export	Use este comando para criar um ficheiro binário. O comando aceita um COPYBOOK DD como entrada. Nota: recomendamos que use os comandos qsam decode e qsam encode para realizar esta tarefa. Para ver informações sobre as vantagens de usar os comandos qsam, consulte o artigo Vantagens dos comandos qsam. O comando bq export suporta algumas capacidades de otimização do desempenho. Para mais informações, consulte o artigo Melhorias de desempenho para o comando bq export. Pode usar conjuntos de carateres personalizados com o comando bq export. Para mais informações, consulte o artigo Use conjuntos de carateres personalizados. Nota: o comando bq export falha os pedidos para exportar tabelas grandes do Bigtable. Para evitar erros, adicione a flag -allowLargeResults ao comando bq export quando quiser exportar tabelas grandes.	Sim
	bq load	Use este comando para carregar dados para uma tabela.	Não
	bq mk	Use este comando para criar recursos do BigQuery, como tabelas integradas ou tabelas externas, que precisam de partição e agrupamento para serem configurados. Também pode usar o comando bq mk para gerar uma tabela do BigQuery diretamente a partir da análise de livros de cópias COBOL. Para mais informações, consulte o artigo Crie uma tabela do BigQuery a partir de um copybook.	Não
	bq query	Use este comando para criar uma tarefa de consulta que execute a consulta SQL especificada. O comando lê a consulta SQL a partir do indicador --sql ou de QUERY DD. Se ambos forem fornecidos, a consulta na flag --sql tem prioridade. Use a flag --follow=true para gerar um relatório que apresente os resultados de uma consulta selecionada. Para escrever este relatório num ficheiro no mainframe, defina uma declaração DD AUDITL que aponte para o ficheiro que deve conter o relatório de registos de auditoria. Não use a flag --follow se quiser um comportamento de registo normal. Alguns resultados de consultas podem devolver um grande número de linhas, por vezes, na ordem dos milhões. Para que o resultado permaneça legível, o número de linhas apresentadas está limitado. Para controlar o número de linhas apresentadas, use a flag --report_row_limit. Por exemplo, use --report_row_limit 10 para limitar os resultados a 10 linhas. Por predefinição, o número de linhas apresentadas está limitado a 30. Para usar a parametrização bq query, consulte o artigo Parametrização de consultas do bq.	Sim
	bq rm	Use este comando para eliminar permanentemente um recurso do BigQuery. Como este comando elimina permanentemente um recurso, recomendamos que o use com precaução.	Não
Comandos do Cloud Run	cloud run job execute	Use este comando para acionar uma tarefa do Cloud Run a partir do seu mainframe.	Não
	cloud run job logs	Use este comando para ver os registos de uma execução de tarefa específica do Cloud Run.	Não
	cloud run job cancel	Use este comando para cancelar uma tarefa do Cloud Run.	Não
Comandos do Cloud Storage	scp	Use este comando para copiar texto ou dados binários para o Cloud Storage. Pode usar o modo de cópia binária simples para: Copiar um conjunto de dados do IBM z/OS para o Cloud Storage sem modificações como parte de um pipeline de dados. Opcionalmente, pode converter a codificação de carateres do código de intercâmbio decimal codificado em binário alargado (EBCDIC) para ASCII UTF-8 e adicionar quebras de linha. Nota: recomendamos que use os comandos copy text para realizar esta tarefa, uma vez que oferecem melhores capacidades. Também pode usar este comando para copiar o código fonte da aplicação definido em linguagem de controlo de tarefas (JCL).	Não
gsutil utilitário	gsutil cp	Use este comando para transcodificar um conjunto de dados e escrevê-lo no Cloud Storage no formato de ficheiro Optimized Row Columnar (ORC). O comando lê os dados do INFILE DD e o esquema de registo do ficheiro COPYBOOK. Nota: recomendamos que use os comandos qsam decode e qsam encode para realizar esta tarefa. Para ver informações sobre as vantagens de usar os comandos qsam, consulte o artigo Vantagens dos comandos qsam. Se quiser que o comando leia os dados de um ficheiro de nome da origem de dados (DSN), use as seguintes flags: --inDsn: o DSN do conjunto de dados de entrada. Se for fornecida, esta flag substitui o DD INFILE. --cobDsn: o DSN do livro de cópias. Se for fornecida, esta flag substitui o DD COPYBOOK. Em seguida, o comando abre um número configurável de ligações paralelas à API Cloud Storage e transcodifica o conjunto de dados COBOL para o formato de ficheiro ORC colunar e comprimido com GZIP. Pode esperar uma taxa de compressão de cerca de 35%. Opcionalmente, pode usar este comando para interagir com o serviço Mainframe Connector gRPC em execução numa VM no mainframe. Para o fazer, defina as variáveis de ambiente SRVHOST e SRVPORT ou faculte o nome do anfitrião e o número da porta através das opções da linha de comandos. Quando o serviço gRPC é usado, o conjunto de dados de entrada é primeiro copiado para o Cloud Storage pelo Mainframe Connector e, em seguida, é feita uma chamada de procedimento remoto (RPC) para instruir o serviço gRPC a transcodificar o ficheiro. Também pode realizar as seguintes tarefas com o comando gsutil cp : Faça uma execução de ensaio do comando gsutil cp Copie um ficheiro do Cloud Storage para o seu mainframe Otimize o desempenho do comando gsutil cp Use conjuntos de carateres personalizados com o gsutil cp.	Sim
	gsutil rm	Use este comando para eliminar contentores ou objetos num contentor.	Não
gszutil utilitário	gszutil	O utilitário gszutil é executado através do IBM JZOS Java SDK e fornece um emulador de shell que aceita gsutil e invocações da linha de comandos do BigQuery através de JCL. Nota: recomendamos que use os comandos qsam decode e qsam encode para realizar esta tarefa. Para ver informações sobre as vantagens de usar os comandos qsam, consulte o artigo Vantagens dos comandos qsam. O utilitário gszutil expande a funcionalidade do utilitário gsutil aceitando um esquema sob a forma de um COPYBOOK DD, usando-o para transcodificar conjuntos de dados COBOL diretamente para ORC antes de carregar para o Cloud Storage. O utilitário gszutil também lhe permite executar o BigQuery query e o load através do JCL. O utilitário gszutil funciona com o servidor gRPC, que ajuda a reduzir o consumo de milhões de instruções por segundo (MIPS). Recomendamos que use o utilitário gszutil no seu ambiente de produção para converter ficheiros binários no Cloud Storage para o formato ORC.	Não
Comandos qsam	qsam decode	Use este comando para transcodificar registos de ficheiros QSAM para o formato pretendido usando o argumento --output-format. O ficheiro QSAM original é dividido em blocos com base no valor especificado com o argumento --max-chunk-size. O resultado transcodificado é guardado no caminho de destino como ficheiros ordenados lexicograficamente.	Não
	qsam encode	Use este comando para converter dados de uma origem externa num ficheiro QSAM. A entrada é definida pelo valor especificado através do argumento --input-format.	Não
Comandos do Pub/Sub	pubsub topics publish	Use este comando para publicar uma mensagem num tópico do Pub/Sub.	Não
Outros comandos	copy text	Use este comando para copiar um ficheiro para uma localização de armazenamento à sua escolha, como o Cloud Storage, e vice-versa.	Não
	curl	Use este comando para fazer um pedido HTTP a um serviço Web ou APIs REST.	Não
	gcloud dataflow flex-template run	Use este comando para acionar a execução de um modelo flexível do Dataflow. O comando executa uma tarefa a partir do caminho do modelo flexível especificado. Para mais informações, consulte o artigo gcloud dataflow flex-template run.	Não
	systemreport	Use este comando para imprimir os dados do sistema necessários na saída padrão (stdout). Isto permite que a equipa de apoio técnico do Mainframe Connector recolha as informações necessárias para diagnosticar um problema sem a necessidade de uma interação extensiva com o cliente. Com base na flag que usa, o comando systemreport imprime os seguintes dados do sistema: --supported_ciphers: Cifras suportadas --available_security_providers: fornecedores de segurança disponíveis	Não

Use conjuntos de carateres personalizados

O Mainframe Connector suporta diferentes conjuntos de carateres que descodificam bytes em strings do BigQuery e vice-versa. O Mainframe Connector permite-lhe configurar o seu próprio conjunto de carateres personalizado. Pode configurar um conjunto de carateres personalizado criando um ficheiro de mapeamento de carateres Unicode (UCM). O conetor de mainframe suporta o seguinte subconjunto do 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 quiser usar um conjunto de carateres personalizado, defina um ficheiro de configuração no formato UCM. Pode usar este conjunto de carateres personalizado com os comandos gsutil cp ou bq export definindo a flag --encoding=charset.

Quando cria um conjunto de carateres personalizado, verifique o seguinte:

• Ao definir um ficheiro UCM, tenha em atenção o seguinte:
  • O conetor de mainframe só suporta conjuntos de carateres personalizados com um conjunto de carateres de byte único (SBCS).
  • O conetor de mainframe só suporta o indicador de precisão UCM |0.
  • Verifique se os ficheiros UCM estão localizados nos serviços do sistema Unix z/OS (USS) e não num conjunto de dados particionado de armazenamento virtual múltiplo (MVS PDS).
  • Verifique se os ficheiros UCM estão guardados no formato American Standard Code for Information Interchange (ASCII) e não no formato Extended Binary Coded Decimal Interchange Code (EBCDIC).
• Forneça um mapeamento explícito para cada valor de byte único possível para um caráter Unicode. Se não tiver a certeza sobre que caráter Unicode quer mapear um byte, recomendamos que o mapeie para U+FFFD. Pode mapear diferentes sequências de bytes para o mesmo caráter Unicode. No entanto, nestes casos, o mapeamento não é bidirecional, ou seja, quando carrega dados para o BigQuery e, posteriormente, os exporta novamente para um ficheiro binário, a saída pode ser diferente da entrada original.
• Verifique se as sequências de bytes na segunda coluna são únicas. Se várias sequências de bytes forem mapeadas para o mesmo caráter Unicode, este caráter Unicode é descodificado para uma sequência de bytes do último mapeamento definido no ficheiro UCM.
• Verifique se o Mainframe Connector consegue encontrar o ficheiro UCM ao definir a variável de ambiente BQSH_FEATURE_CUSTOM_CHARSET para o caminho do ficheiro UCM. Se quiser usar vários conjuntos de carateres, pode indicar os caminhos para vários conjuntos de carateres separados pelo delimitador de ponto e vírgula. Por exemplo, BQSH_FEATURE_CUSTOM_CHARSET=path1;path2. path pode apontar para um ficheiro local ou para um ficheiro armazenado no Cloud Storage. Se executar os comandos gsutil cp ou bq export com a flag --remote para realizar a transcodificação remota, o Mainframe Connector usa o valor local definido para a variável de ambiente BQSH_FEATURE_CUSTOM_CHARSET. O mesmo se aplica quando executa o Mainframe Connector no modo autónomo. Se a flag --encoding se referir a um conjunto de carateres personalizado que não corresponde ao valor que definiu para BQSH_FEATURE_CUSTOM_CHARSET (ou se não tiver definido BQSH_FEATURE_CUSTOM_CHARSET), o comando é terminado com uma mensagem de erro.

Configuração de otimização do desempenho para o comando bq export

O conetor de mainframe suporta a seguinte configuração de otimização do desempenho para o comando bq export:

• exporter_thread_count: (Opcional) Defina o número de threads de trabalho. O valor predefinido é 4.
• max_read_streams: (Opcional) Defina o número máximo de streams de leitura. O valor predefinido é o mesmo que o valor definido para exporter_thread_count.
• order_response: (Opcional) Se definir esta flag como verdadeira, o exportador retém a ordem dos resultados da consulta. Este sinalizador afeta o desempenho da exportação. O valor predefinido é false.
• max_read_queue: (Opcional) Defina o número máximo de filas de registos de leitura. O valor predefinido é o dobro do número de threads.
• transcoding_buffer: (Opcional) Defina o tamanho da memória intermédia de transcodificação por thread em MB. O valor predefinido é 20 MB.

Tenha em atenção que também pode tentar aumentar o tamanho da janela de transporte definindo a variável de ambiente OVERRIDE_GRPC_WINDOW_MB para melhorar o desempenho. O tamanho da janela predefinido é de 4 MB.

Crie uma tabela do BigQuery a partir de um copybook

Pode usar o comando bq mk para gerar uma tabela do BigQuery diretamente a partir da análise de livros de cópias COBOL. O analisador nativo de copybook extrai os valores predefinidos da cláusula VALUE num copybook e atribui-os às colunas correspondentes numa tabela do BigQuery recém-criada.

Nota: esta funcionalidade não é suportada pelo analisador antigo.

Para ajudar a testar esta funcionalidade, o comando bq mk também oferece um modo de teste. Este modo permite-lhe pré-visualizar o comando CREATE TABLE SQLgerado sem criar efetivamente a tabela no BigQuery.

O comando bq mk oferece as seguintes opções de configuração para suportar esta funcionalidade:

• --schema_from_copybook: especifica o livro de registo a usar para criar a tabela.
• --dry_run: (Opcional) Quando ativado, o comando apenas imprime o comando CREATE TABLE SQL gerado sem o executar. Esta flag está predefinida como false.
• --tablespec "[PROJECT_ID]:[DATASET].[TABLE]": especifica o ID do projeto, o conjunto de dados e o nome da tabela do BigQuery para a tabela de destino.
• --encoding: especifica a codificação usada para ler o ficheiro de livro de cópias. O valor predefinido é CP037.

As seguintes cláusulas VALUE são suportadas:

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

As cláusulas HIGH-VALUE e LOW-VALUE são suportadas apenas para variáveis alfanuméricas.

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 Parametrização

O Mainframe Connector permite-lhe usar consultas parametrizadas com o bq query.

Segue-se um exemplo de como pode usar uma consulta bq query parametrizada:

Ficheiro de consulta

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

Segue-se um exemplo com vários parâmetros.

Ficheiro de consulta

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

Exemplo de execução

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

Faça uma execução de ensaio do comando gsutil cp

O comando gsutil cp descodifica um ficheiro QSAM através de um COBOL copybook e gera um ficheiro ORC no Cloud Storage. Pode fazer um teste do comando gsutil cp com a sinalização dry_run e testar os seguintes passos:

• Analise um copybook ou um ficheiro de dados COBOL e verifique se é compatível com o Mainframe Connector.
• Descodifique um ficheiro QSAM sem o escrever no Cloud Storage.

Use o seguinte comando para fazer um teste:

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

Se todos os passos forem executados com êxito, o comando é terminado com o código de retorno 0. Se forem encontrados problemas, é apresentada uma mensagem de erro.

Quando usa a flag dry_run, todas as estatísticas, como o total de bytes lidos, o número de registos escritos e o total de erros, são registadas.

Se usar a flag dry_run e a origem de dados não existir, o comando não devolve um erro. Em vez disso, verifica apenas o analisador de livros de cópias e, em seguida, conclui a execução.

Copie um ficheiro do Cloud Storage para o seu mainframe

Pode usar o comando gsutil cp para copiar um ficheiro do Cloud Storage para um conjunto de dados do mainframe. Tenha em atenção que não pode copiar conjuntos de dados particionados (PDS).

Para copiar um ficheiro do Cloud Storage para um conjunto de dados do mainframe, especifique o DSN e os requisitos de espaço do ficheiro que quer transferir para o mainframe no JCL, conforme mostrado no exemplo seguinte:

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

Especifique o comando gsutil cp no seguinte formato. Se o ficheiro já existir no computador central, verifique se adicionou a flag --replace ao comando.

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

Substitua o seguinte:

• GCS_URI: o identificador uniforme de recurso (URI) do Cloud Storage do ficheiro do Cloud Storage. Por exemplo, gs://bucket/sample.mainframe.dsn.
• DSN: a localização de destino do DSN no mainframe.
• RECFM: o formato de registo (RECFM) do ficheiro de mainframe. Os valores válidos são F, FB e U. Tenha em atenção que estes valores não são sensíveis a maiúsculas e minúsculas.
• LRECL: (Opcional) O comprimento do registo (LRECL) do ficheiro. O valor tem de ser um número inteiro >= 0. Se LRECL não for especificado, assume-se que o ficheiro está no formato de registo de comprimento indefinido (U).
• BLKSIZE: (Opcional) O tamanho do bloco do ficheiro. Se for definido como 0, o sistema determina o tamanho do bloco ideal. O valor tem de ser um número inteiro >= 0. Se não especificar um valor, o ficheiro é tratado como um ficheiro desbloqueado.
• noseek: (Opcional) Inclua este parâmetro se quiser melhorar o desempenho das transferências. Esta flag está definida como false por predefinição, ou seja, as operações de procura estão ativadas.

Exemplo de execução

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

Configuração de otimização do desempenho para o comando gsutil cp

O conetor de mainframe suporta a seguinte configuração de otimização do desempenho para o comando gsutil cp.

• Use a flag --parallelism para definir o número de threads. O valor predefinido é 1 (com uma única thread).
• Use o argumento --maxChunkSize para definir o tamanho máximo de cada fragmento. Cada bloco tem o seu próprio ficheiro ORC. Aumente este valor para reduzir o número de blocos criados à custa de requisitos de memória maiores durante o processo de transcodificação. Para ver detalhes, consulte a secção Analise o argumento maxChunkSize. O valor predefinido é 128 MiB.
• Use o argumento --preload_chunk_count para definir a quantidade de dados a pré-carregar na memória enquanto todos os trabalhadores estão ocupados. Este argumento pode melhorar o desempenho à custa da memória. O valor predefinido é 2.

Exemplo de execução

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

Neste exemplo, considerámos um ficheiro grande e, por isso, usámos 8 threads, que é o número em que a taxa de linhas é atingida. Se tiver memória suficiente, recomendamos que aumente o tamanho dos blocos para 256 MiB ou até 512 MiB, uma vez que reduz a criação de sobrecarga e a finalização de objetos do Cloud Storage. Para ficheiros pequenos, usar menos threads e blocos mais pequenos pode produzir melhores resultados.

Analise o argumento maxChunkSize

A flag maxChunkSize aceita valores sob a forma de um valor e uma unidade de medida, por exemplo, 5 MiB. Pode usar espaços entre o valor e a magnitude.

Pode fornecer o valor nos seguintes formatos:

• Formato Java: b/k/m/g/t, para byte, kibibyte, mebibyte, gibibyte e tebibyte, respetivamente
• Formato internacional: KiB/MiB/GiB/TiB, para kibibyte, mebibyte, gibibyte e tebibyte, respetivamente
• Formato métrico: b/kb/mb/gb/tb, para kilobyte, megabyte, gigabyte e terabyte, respetivamente

A análise do tamanho dos dados não é sensível a maiúsculas e minúsculas. Tenha em atenção que não pode especificar valores parciais. Por exemplo, use 716 KiB em vez de 0,7 MiB.