Comandos da API Mainframe Connector

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

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 Mainframe Connector 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). 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 um único byte (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 para o 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.
• Verifique se o Mainframe Connector pode encontrar o arquivo UCM definindo a variável de ambiente BQSH_FEATURE_CUSTOM_CHARSET como o caminho do 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 se aplica quando você executa o Conector de mainframe no modo autônomo. 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 você a testar esse recurso, o comando bq mk também oferece um modo de simulação. 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 copybook. 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 QSAM 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 seguintes etapas:

• 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 gravá-lo 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 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 formato a seguir. 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 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 fragmento. 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.