Comandos da API Mainframe Connector

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

Usar conjuntos de caracteres personalizados

O Mainframe Connector oferece suporte a diferentes conjuntos de caracteres que decodificam bytes em strings do BigQuery e vice-versa. Com o Mainframe Connector, é possível 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). O Mainframe Connector é compatível com 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 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ó aceita conjuntos de caracteres personalizados usando um conjunto de caracteres de byte único (SBCS, na sigla em inglês).
  • O Mainframe Connector só é compatível com o indicador de precisão 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 particionado de armazenamento virtual múltiplo (MVS PDS).
  • Verifique se os arquivos UCM estão salvos 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 caractere Unicode. Se você não tiver certeza de qual caractere Unicode quer mapear para um byte, recomendamos que o mapeie para U+FFFD. É possível mapear sequências de bytes diferentes para o mesmo caractere Unicode. No entanto, nesses casos, o mapeamento não é bidirecional. Ou seja, quando você carrega dados no BigQuery e depois 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, ele será decodificado para uma sequência de bytes do último mapeamento definido no arquivo UCM.
• Verifique se o Mainframe Connector consegue encontrar o arquivo UCM definindo a variável de ambiente BQSH_FEATURE_CUSTOM_CHARSET como o caminho do arquivo UCM. Se quiser usar vários conjuntos de caracteres, forneça os caminhos para vários conjuntos separados pelo delimitador de ponto e vírgula. Por exemplo, BQSH_FEATURE_CUSTOM_CHARSET=path1;path2. path pode apontar para um arquivo local ou armazenado no Cloud Storage. Se você executar os comandos gsutil cp ou bq export com a flag --remote para realizar uma transcodificação remota, o Mainframe Connector usará o valor local definido para a variável de ambiente BQSH_FEATURE_CUSTOM_CHARSET. O mesmo se aplica 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 definiu 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) defina o número de linhas de execução de trabalho. O valor padrão é 4.
• max_read_streams: (opcional) defina o número máximo de fluxos de leitura. O valor padrão é o mesmo definido para exporter_thread_count.
• order_response: (opcional) se você definir essa flag como "true", 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 registros 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 copybook

É possível usar o comando bq mk para gerar uma tabela do BigQuery diretamente da análise de copybooks COBOL. O analisador nativo de copybook 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 você a testar esse recurso, o comando bq mk também oferece um modo de teste a seco. Esse modo permite visualizar 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 compatibilidade com esse recurso:

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

As seguintes cláusulas VALUE são aceitas:

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 compatíveis apenas com 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

Com o Mainframe Connector, é possível 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 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

Faça uma simulação do comando gsutil cp.

O comando gsutil cp decodifica um arquivo QSAM usando um livro de cópias COBOL e gera um arquivo ORC no Cloud Storage. É possível fazer uma simulação do comando gsutil cp usando a flag dry_run e testar as seguintes etapas:

• Analise um copybook ou arquivo de dados COBOL e verifique se ele é compatível com o Mainframe Connector.
• Decodifica um arquivo QSAM sem gravá-lo no Cloud Storage.

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

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

Se todas as etapas forem executadas com sucesso, o comando vai sair 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 copybook 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).

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 baixar para o mainframe em JCL, conforme mostrado no exemplo a seguir:

//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 arquivo já existir no mainframe, verifique se você adicionou a flag --replace ao comando.

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

Substitua:

• GCS_URI: o identificador uniforme de recursos (URI) 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 do 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 ideal do bloco. O valor precisa ser um número inteiro maior ou igual a zero. Se você não especificar um valor, o arquivo será tratado como desbloqueado.
• noseek: (opcional) inclua esse parâmetro se quiser melhorar o desempenho do download. Por padrão, essa flag é definida como "false", 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 parte. Cada parte terá um arquivo ORC próprio. Aumente esse valor para reduzir o número de partes criadas, mas isso vai aumentar os requisitos de memória durante o processo de transcodificação. Para mais detalhes, consulte Analisar o argumento maxChunkSize. O valor padrão é 128 MiB.
• Use o argumento --preload_chunk_count para definir a quantidade de dados a serem pré-carregados 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 em que a taxa de linha é alcançada. Se você tiver memória suficiente, recomendamos aumentar o tamanho do bloco para 256 MiB ou até mesmo 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 partes menores pode gerar resultados melhores.

Analisar o argumento maxChunkSize

A flag maxChunkSize aceita valores na forma de uma quantidade e uma unidade de medida, por exemplo, 5 MiB. É possível usar espaços em branco entre o valor 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.