Referência da API Mainframe Connector

A tabela a seguir lista os comandos do BigQuery, do Cloud Storage e outros comandos do Google Cloud que podem ser usados com o Mainframe Connector.

Produto Comando Descrição Suporte à transcodificação remota
Comandos do BigQuery Use este comando para criar um arquivo binário. O comando aceita um COPYBOOK DD como entrada.

O comando bq export oferece suporte a alguns recursos de ajuste de desempenho. Para mais informações, consulte Melhorias de desempenho para o comando bq export.

É possível usar conjuntos de caracteres personalizados com o comando bq export. Para mais informações, consulte Usar conjuntos de caracteres personalizados.

Observação:o comando bq export falha em solicitações para exportar tabelas grandes do Bigtable. Para evitar erros, adicione a flag -allowLargeResults ao comando bq export quando quiser exportar tabelas grandes.		 Sim
Use este comando para carregar dados em uma tabela. Para mais informações, consulte bq load. Não
Use esse comando para criar recursos do BigQuery, como tabelas integradas ou externas, que precisam de particionamento e agrupamento para serem configurados. Para mais informações, consulte bq mk.

Também é possível usar o comando bq mk para gerar uma tabela do BigQuery diretamente da análise de cópias de COBOL. Para mais informações, consulte Criar uma tabela do BigQuery com base em um livro de cópias. 		Não
Use este comando para criar um job de consulta que execute a consulta SQL especificada. O comando lê a consulta SQL da flag --sql ou de QUERY DD. Se ambos forem fornecidos, a consulta na flag --sql terá precedência.

Use a flag --follow=true para gerar um relatório que mostre os resultados de uma consulta de seleção. Para gravar esse relatório em um arquivo no mainframe, defina uma instrução DD AUDITL que aponte para o arquivo que deve conter o relatório de registros de auditoria. Não use a sinalização --follow se quiser o comportamento de registro normal.

Alguns resultados de consulta podem retornar um grande número de linhas, às vezes milhões. Para que a saída continue legível para humanos, o número de linhas exibidas é limitado. Para controlar o número de linhas exibidas, use a flag --report_row_limit. Por exemplo, use --report_row_limit 10 para limitar os resultados a 10 linhas. Por padrão, o número de linhas exibidas é limitado a 30.

Para usar a parametrização bq query, consulte Parametrização de consulta bq.

Para mais informações, consulte Consulta bq. 		Sim
Use este comando para excluir permanentemente um recurso do BigQuery. Como esse comando exclui um recurso permanentemente, recomendamos que você o use com cuidado. Para mais informações, consulte bq rm. Não
Comandos do Cloud Storage Use este comando para copiar dados de texto ou binários para o Cloud Storage. Você 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, você pode converter a codificação de caracteres de código binário decimal de troca estendido (EBCDIC) para ASCII UTF-8 e adicionar quebras de linha.

Você também pode usar esse comando para copiar o código-fonte do aplicativo definido em linguagem de controle de tarefas (JCL). 		Não
Utilitário gsutil Use esse comando para transcodificar um conjunto de dados e gravá-lo no Cloud Storage no formato de arquivo ORC (Optimized Row Columnar). O comando lê os dados do INFILE DD e o layout de registro do arquivo COPYBOOK. Se você quiser que o comando leia os dados de um arquivo de nome da fonte de dados (DSN, na sigla em inglês), use as seguintes flags:
  • --inDsn: o DSN do conjunto de dados de entrada. Se for fornecida, essa flag vai substituir o INFILE DD.
  • --cobDsn: o DSN do livro de cópia. Se for fornecido, essa flag vai substituir o COPYBOOK DD.


Em seguida, o comando abre um número configurável de conexões paralelas para a API Cloud Storage e transcodifica o conjunto de dados COBOL para o formato de arquivo ORC com colunas e com compactação GZIP. Espere uma taxa de compactação de cerca de 35%.

Como alternativa, use esse comando para interagir com o serviço gRPC do conector de mainframe em execução em uma VM no mainframe. Para fazer isso, defina as variáveis de ambiente SRVHOST e SRVPORT ou forneça o nome do host e o número da porta usando as opções de linha de comando. Quando o serviço gRPC é usado, o dataset de entrada é copiado para o Cloud Storage pelo Mainframe Connector e, em seguida, uma chamada de procedimento remoto (RPC) é feita para instruir o serviço gRPC a transcodificar o arquivo.

Também é possível realizar as seguintes tarefas com o comando gsutil cp: 		Sim
Use este comando para excluir buckets ou objetos em um bucket. Para mais informações, consulte rm: remover objetos. Não
Utilitário gszutil O utilitário gszutil é executado usando o SDK do Java do IBM JZOS e fornece um emulador de shell que aceita invocações de linha de comando gsutil e BigQuery usando JCL.

O utilitário gszutil estende a funcionalidade do gsutil aceitando um esquema na forma de um COPYBOOK DD, que é usado para transcodificar conjuntos de dados COBOL diretamente para ORC antes do upload para o Cloud Storage. O utilitário gszutil também permite executar query e load do BigQuery usando 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, na sigla em inglês). Recomendamos o uso do utilitário gszutil no seu ambiente de produção para converter arquivos binários no Cloud Storage para o formato ORC. 		Não
Outros comandos Use este comando para enviar uma mensagem a um tópico do Pub/Sub. É possível fornecer a mensagem usando a linha de comando ou um conjunto de dados. Não
Use este comando para acionar a execução de um modelo flex do Dataflow. O comando executa um job do caminho do modelo flexível especificado. Para mais informações, consulte gcloud dataflow flex-template run. Não
Use este comando para fazer uma solicitação HTTP a um serviço da Web ou APIs REST. Não
Use esse comando para imprimir os dados de sistema necessários na saída padrão (stdout). Isso permite que a equipe de suporte do Mainframe Connector colete as informações necessárias para diagnosticar um problema sem a necessidade de muita interação com o cliente.
Com base na flag usada, o comando systemreport imprime os seguintes dados do sistema:
  • --supported_ciphers: Cifras compatíveis
  • --available_security_providers: provedores de segurança disponíveis
 Não

Usar conjuntos de caracteres personalizados

O conector de mainframe oferece suporte a diferentes conjuntos de caracteres que decodificam bytes em strings do BigQuery e vice-versa. O conector de mainframe permite configurar seu próprio conjunto de caracteres personalizado. É possível configurar um conjunto de caracteres personalizado criando um arquivo de mapeamento de caracteres Unicode (UCM, na sigla em inglês). O Mainframe Connector oferece suporte ao 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 você quiser usar um conjunto de caracteres personalizado, defina um arquivo de configuração no formato UCM. É possível usar esse conjunto de caracteres personalizado com os comandos gsutil cp ou bq export definindo a flag --encoding=charset.

Ao criar um conjunto de caracteres personalizado, verifique o seguinte:

  • Ao definir um arquivo UCM, tenha em mente o seguinte:
    • O Mainframe Connector só oferece suporte a conjuntos de caracteres personalizados usando um conjunto de caracteres de byte único (SBCS).
    • O Mainframe Connector só oferece suporte ao indicador de precisão do UCM |0.
    • Verifique se os arquivos UCM estão localizados nos serviços do sistema Unix z/OS (USS), e não em um conjunto de dados particionados de armazenamento virtual (MVS PDS, na sigla em inglês).
    • Verifique se os arquivos UCM são salvos no formato ASCII (American Standard Code for Information Interchange) e não no formato EBCDIC (Extended Binary Coded Decimal Interchange Code).
  • Forneça um mapeamento explícito para cada valor de byte único possível para um caractere Unicode. Se você não tiver certeza de qual caractere Unicode quer mapear um byte, recomendamos que o mapeamento seja feito para U+FFFD. É possível mapear diferentes sequências de bytes para o mesmo caractere Unicode. No entanto, nesses casos, o mapeamento não é bidirecional. Ou seja, quando você carrega dados no BigQuery e os exporta de volta para um arquivo binário, a saída pode ser diferente da entrada original.
  • Verifique se as sequências de bytes na segunda coluna são exclusivas. Se várias sequências de bytes forem mapeadas para o mesmo caractere Unicode, esse caractere Unicode será decodificado para uma sequência de bytes do último mapeamento definido no arquivo UCM.
  • Defina a variável de ambiente BQSH_FEATURE_CUSTOM_CHARSET como o caminho do arquivo UCM para garantir que o Mainframe Connector consiga encontrar o arquivo UCM. Se você quiser usar vários conjuntos de caracteres, forneça os caminhos para vários conjuntos de caracteres separados pelo delimitador ponto e vírgula. Por exemplo, BQSH_FEATURE_CUSTOM_CHARSET=path1;path2. path pode apontar para um arquivo local ou para um arquivo armazenado no Cloud Storage. Se você executar os comandos gsutil cp ou bq export com a flag --remote para realizar a transcodificação remota, o Mainframe Connector vai usar o valor local definido para a variável de ambiente BQSH_FEATURE_CUSTOM_CHARSET. O mesmo acontece quando você executa o Mainframe Connector no modo independente. Se a flag --encoding se referir a um conjunto de caracteres personalizado que não corresponde ao valor definido para BQSH_FEATURE_CUSTOM_CHARSET (ou se você não tiver definido BQSH_FEATURE_CUSTOM_CHARSET), o comando será encerrado com uma mensagem de erro.

Configuração de ajuste de desempenho para o comando bq export

O Mainframe Connector é compatível com a seguinte configuração de ajuste de desempenho para o comando bq export:

  • exporter_thread_count: (opcional) define o número de linhas de execução de trabalhadores. O valor padrão é 4.
  • max_read_streams: (opcional) define os fluxos de leitura máximos. O valor padrão é igual ao valor definido para exporter_thread_count.
  • order_response: (opcional) se você definir essa flag como verdadeira, o exportador vai manter a ordem dos resultados da consulta. Essa flag afeta o desempenho da exportação. O valor padrão é falso.
  • max_read_queue: (opcional) define o número máximo de filas de registro de leitura. O valor padrão é o dobro do número de linhas de execução.
  • transcoding_buffer: (opcional) define o tamanho do buffer de transcodificação por linha de execução em MBs. O valor padrão é 20 MB.

Também é possível aumentar o tamanho da janela de transporte definindo a variável de ambiente OVERRIDE_GRPC_WINDOW_MB para melhorar o desempenho. O tamanho padrão da janela é 4 MB.

Criar uma tabela do BigQuery usando um livro de cópias

É possível usar o comando bq mk para gerar uma tabela do BigQuery diretamente da análise de cópias de COBOL. O analisador de copybook nativo extrai valores padrão da cláusula VALUE em um copybook e os atribui às colunas correspondentes em uma tabela do BigQuery recém-criada.

Para ajudar a testar esse recurso, o comando bq mk também oferece um modo de teste. Esse modo permite que você visualize o comando CREATE TABLE SQL gerado sem criar a tabela no BigQuery.

O comando bq mk oferece as seguintes opções de configuração para oferecer suporte a esse recurso:

  • --schema_from_copybook: especifica o livro de cópia a ser usado para criar a tabela.
  • --dry_run: (opcional) quando ativado, o comando apenas imprime o comando CREATE TABLE SQL gerado sem executá-lo. Essa flag é definida como falsa por padrão.
  • --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 arquivo de cópia. O valor padrão é CP037.

As cláusulas VALUE a seguir são compatíveis:

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 têm suporte 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>

Parametrização bq query

O Mainframe Connector permite usar consultas parametrizadas com bq query.

Confira a seguir um exemplo de como usar uma consulta bq query parametrizada:

Arquivo de consulta

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

Confira abaixo um exemplo com vários parâmetros.

Arquivo 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

Executar uma simulação do comando gsutil cp

O comando gsutil cp decodifica um arquivo de método de acesso sequencial em fila (QSAM, na sigla em inglês) usando um copybook COBOL e gera um arquivo ORC no Cloud Storage. É possível realizar um teste do comando gsutil cp usando a flag dry_run e testar as etapas a seguir:

  • Analise um arquivo de dados ou de cópia COBOL e verifique se ele é compatível com o Mainframe Connector.
  • Decodificar um arquivo QSAM sem gravar no Cloud Storage.

Use o comando a seguir para realizar uma simulação:

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

Se todas as etapas forem executadas com sucesso, o comando será encerrado com o código de retorno 0. Se houver algum problema, uma mensagem de erro será exibida.

Quando você usa a flag dry_run, todas as estatísticas, como o total de bytes lidos, o número de registros gravados e o total de erros, são registradas.

Se você usar a flag dry_run e a fonte de dados não existir, o comando não vai retornar um erro. Em vez disso, ele verifica apenas o analisador de cópia e conclui a execução.

Copiar um arquivo do Cloud Storage para o mainframe

Use o comando gsutil cp para copiar um arquivo do Cloud Storage para um conjunto de dados do Mainframe. Não é possível copiar conjuntos de dados particionados (PDS, na sigla em inglês).

Para copiar um arquivo do Cloud Storage para um conjunto de dados do Mainframe, especifique o DSN e os requisitos de espaço do arquivo que você quer fazer o download para o Mainframe no JCL, conforme mostrado no exemplo abaixo:

//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 formato a seguir. Se o arquivo já existir no mainframe, adicione a flag --replace ao comando.

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

Substitua:

  • GCS_URI: o identificador de recurso uniforme (URI, na sigla em inglês) do Cloud Storage do arquivo do Cloud Storage. Por exemplo, gs://bucket/sample.mainframe.dsn.
  • DSN: o local de destino do DSN no mainframe.
  • RECFM: o formato de registro (RECFM) do arquivo Mainframe. Os valores válidos são F, FB e U. Esses valores não diferenciam maiúsculas de minúsculas.
  • LRECL: (opcional) o comprimento do registro (LRECL) do arquivo. O valor precisa ser um número inteiro maior ou igual a 0. Se LRECL não for especificado, o arquivo será considerado no formato de registro de comprimento indefinido (U).
  • BLKSIZE: (opcional) o tamanho do bloco do arquivo. Se definido como 0, o sistema vai determinar o tamanho de bloco ideal. O valor precisa ser um número inteiro maior ou igual a 0. Se você não especificar um valor, o arquivo será tratado como desbloqueado.
  • noseek: (opcional) inclua esse parâmetro se quiser melhorar a performance do download. Essa flag é definida como falsa por padrão, ou seja, as operações de busca sã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 ajuste de desempenho para o comando gsutil cp

O Mainframe Connector é compatível com a seguinte configuração de ajuste de desempenho para o comando gsutil cp.

  • Use a flag --parallelism para definir o número de linhas de execução. O valor padrão é 1 (uma única linha de execução).
  • Use o argumento --maxChunkSize para definir o tamanho máximo de cada bloco. Cada bloco terá o próprio arquivo ORC. Aumente esse valor para reduzir o número de blocos criados à custa de requisitos de memória maiores durante o processo de transcodificação. Para saber mais, consulte Analisar o argumento maxChunkSize. O valor padrão é 128 MiB.
  • Use o argumento --preload_chunk_count para definir a quantidade de dados a ser pré-carregada na memória enquanto todos os workers estão ocupados. Esse argumento pode melhorar o desempenho ao custo da memória. O valor padrão é 2.

Exemplo de execução

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

Neste exemplo, consideramos um arquivo grande e usamos oito linhas de execução para alcançar a taxa de linha. Se você tiver memória suficiente, recomendamos aumentar o tamanho do bloco para 256 MiB ou até 512 MiB, já que isso reduz a criação de sobrecarga e a finalização de objetos do Cloud Storage. Para arquivos pequenos, usar menos linhas de execução e pedaços menores pode produzir resultados melhores.

Analisar o argumento maxChunkSize

A flag maxChunkSize aceita valores na forma de um valor e uma unidade de medida, por exemplo, 5 MiB. É possível usar espaços em branco entre a quantidade e a magnitude.

É possível fornecer o valor nos seguintes formatos:

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

A análise do tamanho dos dados não diferencia maiúsculas de minúsculas. Não é possível especificar valores parciais. Por exemplo, use 716 KiB em vez de 0,7 MiB.