Executar o Mainframe Connector no modo independente

Nesta página, explicamos como instalar o conector de mainframe no Cloud Run, transcodificar dados, salvá-los no BigQuery e exportá-los do BigQuery.

O Mainframe Connector versão 5.13.0 e mais recentes oferecem suporte à execução do Mainframe Connector como um job independente no Google Cloud. Com esse recurso, é possível executar o Mainframe Connector como um job em lote conteinerizado, por exemplo, como um job do Cloud Run, do Google Kubernetes Engine ou em um contêiner do Docker. Essa opção ajuda a evitar a instalação do Mainframe Connector localmente no mainframe e facilita a integração da análise de arquivos do método de acesso sequencial enfileirado (QSAM) do mainframe aos fluxos de trabalho de extração, transformação e carregamento (ETL) atuais.

Ao usar a versão independente do Mainframe Connector, você precisa configurar o fluxo de trabalho de ETL que carrega o arquivo QSAM para Google Cloud por conta própria.

Antes de começar

  • Implante o Conector de mainframe no Cloud Run.
  • Crie uma conta de serviço ou identifique uma conta de serviço atual para usar com o Mainframe Connector. Essa conta de serviço precisa ter permissões para acessar buckets do Cloud Storage, conjuntos de dados do BigQuery e qualquer outro recurso do Google Cloud que você queira usar.
  • Verifique se a conta de serviço criada tem o papel de invocador do Cloud Run atribuído.
  • Verifique se os dados do mainframe já estão disponíveis em Google Cloud como um arquivo QSAM.

Transcodificar dados usando o conector de mainframe no modo independente no Cloud Run

O Mainframe Connector oferece duas maneiras de executar o Mainframe Connector como um job independente no Google Cloud:

Vantagens dos comandos qsam

Os comandos qsam oferecem as seguintes vantagens:

  • Compatível com tipos de dados compostos, incluindo a cláusula OCCURS (listas), a cláusula REDEFINES e registros aninhados. Para mais informações sobre esses tipos de dados, consulte a referência de transcodificação qsam.
  • Oferece suporte à configuração do processo de transcodificação por um arquivo de configuração do transcoder. Esse recurso oferece mais flexibilidade ao decodificar dados para Google Cloud e codificar os dados de volta para o mainframe.
  • Permite a criação de um conjunto de dados de transbordamento, que é uma tabela de erros de transcodificação que pode ser usada para inspeção de erros.
  • Compatível com vários formatos de entrada e saída. Com esse recurso, é possível carregar dados de e para vários data warehouses.

Executar o Conector de mainframe no modo independente usando comandos qsam

Para transcodificar seus dados usando o Mainframe Connector no modo independente com comandos qsam, siga estas etapas:

  1. Crie um arquivo YAML com comandos para fazer o seguinte:

    • Ler o conjunto de dados
    • Transcodifique para um formato compatível
    • Faça upload para o Cloud Storage.

    O conjunto de dados de entrada precisa ser um arquivo QSAM com comprimento de registro fixo ou variável. Use o exemplo de arquivo YAML a seguir para ler seu conjunto de dados, transcodificá-lo para o formato ORC e fazer upload dele para o Cloud Storage.

    No exemplo a seguir, usamos o DataPath do Cloud Storage para INFILE, OUTFILE, COPYBOOK e TRANSCODE_CONFIGURATION.

    environmentVariables:
- name: "INFILE"
  value: "INFILE"
- name: "OUTFILE"
  value: "OUTFILE"
- name: "COPYBOOK"
  value: "COPYBOOK"
- name: "TRANSCODE_CONFIGURATION"
  value: "TRANSCODE_CONFIGURATION"
- name: "LOG_PROJECT"
  value: "LOG_PROJECT"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"

command:
  qsam decode $INFILE $OUTFILE
  --copybook $COPYBOOK
  --transcode-configuration ${TRANSCODE_CONFIGURATION}
  --output-format orc
  --parallelism 8
  --chunk-size "512Mib"

    Substitua:

    • INFILE: o nome do arquivo de entrada.
    • OUTFILE: o nome do arquivo de saída.
    • COPYBOOK_PATH: o caminho para o DD de copybook.
    • TRANSCODE_CONFIGURATION_PATH: o caminho para o arquivo de configuração de transcodificação.
    • LOG_PROJECT: o nome do projeto de registro.

    Confira um exemplo de arquivo YAML:

    environmentVariables:
- name: "INFILE"
  value: "gs://my_bucket/my/input.dat"
- name: "OUTFILE"
  value: "gs://my_bucket/my/output.orc"
- name: "COPYBOOK"
  value: "gs://my_bucket/my/copybook.cpy"
- name: "TRANSCODE_CONFIGURATION"
  value: "gs://my_bucket/my/transcode-configuration-file.json"
- name: "LOG_PROJECT"
  value: "the log project"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
command:
  qsam decode $INFILE $OUTFILE
  --copybook $COPYBOOK
  --transcode-configuration ${TRANSCODE_CONFIGURATION}
  --output-format orc
  --parallelism 8
  --chunk-size "512Mib"

  2. Crie um arquivo job.yaml com o seguinte comando.

    kind: Job
metadata:
  name: JOB
spec:
  template:
    spec:
      template:
        spec:
          containers:
          - image: IMAGE
            command:
            - bash
            - /opt/mainframe-connector/standalone.sh
            - --argsFrom
            - LOCATION_OF_THE_COMMAND_YAML_FILE

    Substitua:

    • JOB: o nome do seu job do Cloud Run; Os nomes dos jobs precisam ter 49 caracteres ou menos e ser exclusivos por região e projeto.
    • IMAGE: o URL da imagem do contêiner do job. Por exemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
    • LOCATION_OF_THE_COMMAND_YAML_FILE: o local do arquivo YAML que você criou na etapa anterior.

  3. Implante o novo job usando este comando:

    gcloud run jobs replace job.yaml

  4. Execute o job usando o seguinte comando:

    gcloud run jobs execute JOB_NAME

    Substitua JOB_NAME pelo nome do job.

Para mais informações sobre como criar e executar um job do Cloud Run, consulte Criar um job e Executar um job.

Execute o Mainframe Connector no modo independente usando o comando gsutil cp

Para transcodificar seus dados usando o Mainframe Connector no modo independente com o comando gsutil cp, siga estas etapas:

  1. Crie um arquivo YAML com comandos para fazer o seguinte:

    • Ler o conjunto de dados
    • Transcodificar para ORC
    • Faça upload para o Cloud Storage.

    O conjunto de dados de entrada precisa ser um arquivo QSAM com comprimento de registro fixo ou variável. Use o exemplo de arquivo YAML a seguir para ler seu conjunto de dados, transcodificá-lo para o formato ORC e fazer upload dele para o Cloud Storage.

    No exemplo a seguir, leia os dados do conjunto de dados INFILE e o layout do registro do COPYBOOK DD.

    environmentVariables:
- name: "INFILE"
  value: "INFILE"
- name: "INFILE_DSN"
  value: "INFILE_DSN"
- name: "GCSDSNURI"
  value: "INFILE_DSN_FILEPATH"
- name: "COPYBOOK"
  value: "COPYBOOK_FILEPATH"
- name: "LOG_PROJECT"
  value: "LOG_PROJECT"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
command:
  gsutil cp gs://outputbucket/output
  --parallelism 8
  --maxChunkSize "512Mib"
  --parser_type=copybook

    Substitua:

    • INFILE: o nome do arquivo de entrada.
    • INFILE_DSN: o nome do arquivo de nome da fonte de dados (DSN) de entrada.
    • INFILE_DSN_FILEPATH: o caminho para o arquivo DSN de entrada.
    • COPYBOOK_FILEPATH: o caminho para o DD de copybook.
    • LOG_PROJECT: o nome do projeto de registro.

    Confira um exemplo de arquivo YAML:

      environmentVariables:
  - name: "INFILE"
    value: "input.dat"
  - name: "INFILE_DSN"
    value: "input.dat"
  - name: "GCSDSNURI"
    value: "gs://inputbucket/inputfolder"
  - name: "COPYBOOK"
    value: "gs://inputbucket/copybook.cpy"
  - name: "LOG_PROJECT"
    value: "the log project"
  - name: "IBM_JAVA_OPTIONS"
    value: "-XX:+UseContainerSupport"
  command:
    gsutil cp gs://outputbucket/output
    --parallelism 8
    --maxChunkSize "512Mib"
    --parser_type=copybook

    Para conferir a lista completa de variáveis de ambiente compatíveis com o Mainframe Connector, consulte Variáveis de ambiente.

    Se quiser registrar os comandos executados durante esse processo, ative as estatísticas de carga.

  2. Crie um arquivo job.yaml com o seguinte comando.

    kind: Job
metadata:
  name: JOB
spec:
  template:
    spec:
      template:
        spec:
          containers:
          - image: IMAGE
            command:
            - bash
            - /opt/mainframe-connector/standalone.sh
            - --argsFrom
            - LOCATION_OF_THE_COMMAND_YAML_FILE

    Substitua:

    • JOB: o nome do seu job do Cloud Run; Os nomes dos jobs precisam ter 49 caracteres ou menos e ser exclusivos por região e projeto.
    • IMAGE: o URL da imagem do contêiner do job. Por exemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
    • LOCATION_OF_THE_COMMAND_YAML_FILE: o local do arquivo YAML que você criou na etapa anterior.

  3. Implante o novo job usando este comando:

    gcloud run jobs replace job.yaml

  4. Execute o job usando o seguinte comando:

    gcloud run jobs execute JOB_NAME

    Substitua JOB_NAME pelo nome do job.

Para mais informações sobre como criar e executar um job do Cloud Run, consulte Criar um job e Executar um job.

Exportar tabela do BigQuery para um conjunto de dados do mainframe

É possível exportar uma tabela do BigQuery para um conjunto de dados de mainframe criando um arquivo YAML que executa uma leitura SQL do arquivo QUERY DD e exporta o conjunto de dados resultante para o Cloud Storage como um arquivo binário, da seguinte maneira.

As etapas para criar e executar o job do Cloud Run são as mesmas mencionadas na seção Transcodificar dados usando o Mainframe Connector no modo independente no Cloud Run. A única diferença são as instruções mencionadas no arquivo YAML. O Mainframe Connector oferece duas maneiras de exportar tabela do BigQuery:

  • Usando comandos qsam (versão 5.16.0 e mais recentes)

  • Como usar o comando bq export

Usar comandos qsam 

environmentVariables:
  - name: "QUERY"
    value: "QUERY_PATH"
  - name: "OUTFILE"
    value: "OUTFILE"
  - name: "COPYBOOK"
    value: "COPYBOOK_PATH"
  - name: "TRANSCODE_CONFIGURATION"
    value: "TRANSCODE_CONFIGURATION_PATH"
  - name: "PROJECT_ID"
    value: "PROJECT_ID"
  - name: "LOCATION"
    value: "LOCATION"
  - name: "LOG_PROJECT"
    value: "LOG_PROJECT"
  - name: "IBM_JAVA_OPTIONS"
    value: "-XX:+UseContainerSupport"
command:
qsam encode \
  $QUERY
  $OUTFILE
  --copybook ${COPYBOOK_PATH}
  --transcode-configuration ${TRANSCODE_CONFIGURATION_PATH}
  --input-format=BIGQUERY \
  --input-parameter project_id=${PROJECT_ID} \
  --input-parameter location=${LOCATION}

Substitua:

  • QUERY_PATH: a consulta SQL a ser executada. O resultado da consulta será codificado em um arquivo binário.
  • OUTFILE: o bucket do Cloud Storage que vai conter o arquivo binário de saída.
  • COPYBOOK_PATH: o caminho para o DD de copybook.
  • TRANSCODE_CONFIGURATION_PATH: o caminho para o arquivo de configuração do transcoder.
  • LOG_PROJECT: o nome do projeto de registro.
  • PROJECT_ID: o ID do projeto em que você quer executar a consulta.
  • LOCATION: a região ou multirregião em que a consulta será executada. Recomendamos que você execute a consulta em um local próximo aos dados. O valor padrão é "US".

Confira um exemplo de arquivo YAML:

environmentVariables:
- name: "QUERY"
  value: "gs://my_bucket/my/input.sql"
- name: "OUTFILE"
  value: "gs://my_bucket/my/output.orc"
- name: "COPYBOOK"
  value: "gs://my_bucket/my/copybook.cpy"
- name: "TRANSCODE_CONFIGURATION"
  value: "gs://my_bucket/my/transcode-configuration-file.json"
- name: "PROJECT_ID"
  value: "my-project"
- name: "LOCATION"
  value: "US"
- name: "LOG_PROJECT"
  value: "my-log-project"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
  command:
  qsam encode \
    $QUERY
    $OUTFILE
    --copybook ${COPYBOOK_PATH}
    --transcode-configuration ${TRANSCODE_CONFIGURATION_PATH}
    --input-format=BIGQUERY \
    --input-parameter project_id=${PROJECT_ID} \
    --input-parameter location=${LOCATION}

Usar o comando bq export 

environmentVariables:
- name: "COPYBOOK"
  value: "COPYBOOK_FILEPATH"
- name: "LOG_PROJECT"
  value: "LOG_PROJECT"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
command:
  bq export --project_id="PROJECT_NAME" --location="LOCATION" --sql="select * from project.dataset.table" --bucket="BUCKET"

Substitua:

  • COPYBOOK_FILEPATH: o caminho para o DD de copybook.
  • LOG_PROJECT: o nome do projeto de registro.
  • PROJECT_NAME: o nome do projeto em que você quer executar a consulta.
  • LOCATION: o local onde a consulta será executada. Recomendamos que você execute a consulta em um local próximo aos dados.
  • BUCKET: o URI do Cloud Storage que vai conter o arquivo binário de saída.

Confira um exemplo de arquivo YAML:

environmentVariables:
- name: "COPYBOOK"
  value: "gs://inputbucket/copybook.cpy"
- name: "LOG_PROJECT"
  value: "my-log-project"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
command:
  bq export --project_id="my-project" --run_mode="gcsoutput" --location=US --sql="select * from project.dataset.table" --bucket="gs://outputbucket/data.dat"