Execute o Mainframe Connector no modo autónomo

Esta página aborda a forma como pode instalar o Mainframe Connector no Cloud Run, transcodificar dados, guardá-los no BigQuery e exportá-los do BigQuery.

A versão 5.13.0 e posteriores do Mainframe Connector suportam a execução do Mainframe Connector como uma tarefa autónoma no Google Cloud. Esta funcionalidade permite-lhe executar o Mainframe Connector como uma tarefa em lote contentorizada, por exemplo, como uma tarefa do Cloud Run, uma tarefa do Google Kubernetes Engine ou num contentor Docker. Esta opção ajuda a evitar a instalação do conetor do mainframe localmente no mainframe e facilita a integração da análise de ficheiros do método de acesso sequencial em fila (QSAM) do mainframe nos fluxos de trabalho de extração, transformação e carregamento (ETL) existentes.

Quando usa a versão autónoma do Mainframe Connector, tem de configurar o fluxo de trabalho de ETL que carrega o ficheiro QSAM para o Google Cloud .

Antes de começar

• Implemente o Mainframe Connector no Cloud Run.
• Crie uma conta de serviço ou identifique uma conta de serviço existente para usar com o Mainframe Connector. Esta conta de serviço tem de ter autorizações para aceder a contentores do Cloud Storage, conjuntos de dados do BigQuery e qualquer outro Google Cloud recurso que queira usar.
• Certifique-se de que à conta de serviço que criou está atribuída a função de invocador do Cloud Run.
• Certifique-se de que os dados do mainframe já estão disponíveis Google Cloud como um ficheiro QSAM.

Transcodifique dados através do Mainframe Connector no modo autónomo no Cloud Run

O conetor de mainframe oferece duas formas de executar o conetor de mainframe como uma tarefa autónoma no Google Cloud:

• Usar comandos qsam (versão 5.16.0 e posteriores)
• Usar o comando gsutil cp

Vantagens dos comandos qsam

Os comandos qsam oferecem as seguintes vantagens:

• Suporta tipos de dados compostos, incluindo a cláusula OCCURS (listas), a cláusula REDEFINES e registos aninhados. Para mais informações sobre estes tipos de dados, consulte a qsam referência de transcodificação.
• Suporta a configuração do processo de transcodificação através de um ficheiro de configuração do transcodificador. Esta capacidade oferece mais flexibilidade ao descodificar dados para Google Cloud, e codificar os dados novamente para o mainframe.
• Suporta a criação de um conjunto de dados de transbordo, que é uma tabela de erros de transcodificação que pode ser usada para inspeção de erros.
• Suporta vários formatos de entrada e saída. Esta capacidade permite-lhe carregar os seus dados para e a partir de vários armazéns de dados.

Execute o Mainframe Connector no modo autónomo através de comandos qsam

Para transcodificar os seus dados através do Mainframe Connector no modo autónomo com comandos qsam, siga estes passos:

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

   • Leia o seu conjunto de dados
   • Transcodifique-o para um formato suportado
   • Carregue-o para o Cloud Storage

   O conjunto de dados de entrada tem de ser um ficheiro QSAM com um comprimento de registo fixo ou variável. Pode usar o seguinte ficheiro YAML de exemplo para ler o seu conjunto de dados, transcodificá-lo para o formato ORC e carregá-lo para o Cloud Storage.

   No exemplo seguinte, 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 o seguinte:

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

   Segue-se um exemplo de um ficheiro 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"
   

   Nota

   • As variáveis com o sufixo FILLER são ignoradas durante o processo de importação.
   • A partir da versão 5.12.0, o Mainframe Connector substitui os hífenes ("-") por sublinhados ("_") nos nomes das variáveis. Se quiser manter os hífens nos nomes das variáveis, desative esta conversão automática definindo a variável da base de dados BQSH_FEATURE_CONVERT_UNDERSCORE_IN_FIELDS_NAME como false.

2. Crie um ficheiro 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 o seguinte:

   • JOB: o nome da sua tarefa do Cloud Run. Os nomes das tarefas têm de ter 49 carateres ou menos e têm de ser exclusivos por região e projeto.
   • IMAGE: o URL da imagem do contentor de tarefas, por exemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
   • LOCATION_OF_THE_COMMAND_YAML_FILE: a localização do ficheiro YAML que criou no passo anterior.

3. Implemente a nova tarefa através do seguinte comando:

   gcloud run jobs replace job.yaml
   

4. Execute a tarefa através do seguinte comando:

   gcloud run jobs execute JOB_NAME

   Substitua JOB_NAME pelo nome da tarefa.

Para mais informações sobre como criar e executar uma tarefa do Cloud Run, consulte os artigos Crie uma nova tarefa e Execute uma tarefa.

Execute o Mainframe Connector no modo autónomo através do comando gsutil cp

Para transcodificar os seus dados através do Mainframe Connector no modo autónomo com o comando gsutil cp, siga estes passos:

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

   • Leia o seu conjunto de dados
   • Transcodifique-o para ORC
   • Carregue-o para o Cloud Storage

   O conjunto de dados de entrada tem de ser um ficheiro QSAM com um comprimento de registo fixo ou variável. Pode usar o seguinte ficheiro YAML de exemplo para ler o seu conjunto de dados, transcodificá-lo para o formato ORC e carregá-lo para o Cloud Storage.

   No exemplo seguinte, leia os dados do conjunto de dados INFILE e o esquema de registo 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 o seguinte:

   • INFILE: o nome do ficheiro de entrada.
   • INFILE_DSN: o nome do ficheiro de nome da origem de dados (DSN) de entrada.
   • INFILE_DSN_FILEPATH: o caminho para o ficheiro DSN de entrada.
   • COPYBOOK_FILEPATH: o caminho para o livro de registo DD.
   • LOG_PROJECT: o nome do projeto de registo.

   Segue-se um exemplo de um ficheiro 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
   

   Nota

   • As variáveis com o sufixo FILLER são ignoradas durante o processo de importação.
   • A partir da versão 5.12.0, o Mainframe Connector substitui os hífenes ("-") por sublinhados ("_") nos nomes das variáveis. Se quiser manter os hífens nos nomes das variáveis, desative esta conversão automática definindo a variável da base de dados BQSH_FEATURE_CONVERT_UNDERSCORE_IN_FIELDS_NAME como false.

   Para ver a lista completa de variáveis de ambiente suportadas pelo Mainframe Connector, consulte o artigo Variáveis de ambiente.

   Se quiser registar os comandos executados durante este processo, pode ativar as estatísticas de carregamento.

2. Crie um ficheiro 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 o seguinte:

   • JOB: o nome da sua tarefa do Cloud Run. Os nomes das tarefas têm de ter 49 carateres ou menos e têm de ser exclusivos por região e projeto.
   • IMAGE: o URL da imagem do contentor de tarefas, por exemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
   • LOCATION_OF_THE_COMMAND_YAML_FILE: a localização do ficheiro YAML que criou no passo anterior.

3. Implemente a nova tarefa através do seguinte comando:

   gcloud run jobs replace job.yaml
   

4. Execute a tarefa através do seguinte comando:

   gcloud run jobs execute JOB_NAME

   Substitua JOB_NAME pelo nome da tarefa.

Para mais informações sobre como criar e executar uma tarefa do Cloud Run, consulte os artigos Crie uma nova tarefa e Execute uma tarefa.

Exporte a tabela do BigQuery para o conjunto de dados do mainframe

Pode exportar uma tabela do BigQuery para um conjunto de dados do mainframe criando um ficheiro YAML que executa uma leitura SQL a partir do ficheiro DD QUERY e exporta o conjunto de dados resultante para o Cloud Storage como um ficheiro binário, da seguinte forma.

Os passos para criar e executar a tarefa do Cloud Run são os mesmos que mencionados na secção Transcodifique dados através do Mainframe Connector no modo autónomo no Cloud Run. A única diferença são as instruções mencionadas no ficheiro YAML. O conetor de mainframe oferece duas formas de exportar a tabela do BigQuery:

• Usar comandos qsam (versão 5.16.0 e posteriores)

• Usar o comando bq export

Use 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 o seguinte:

• QUERY_PATH: a consulta SQL a executar. O resultado da consulta é codificado num ficheiro binário.
• OUTFILE: o contentor do Cloud Storage que vai conter o ficheiro binário de saída.
• COPYBOOK_PATH: o caminho para o livro de registo DD.
• TRANSCODE_CONFIGURATION_PATH: o caminho para o ficheiro de configuração do transcodificador.
• LOG_PROJECT: o nome do projeto de registo.
• PROJECT_ID: o ID do projeto no qual quer executar a consulta.
• LOCATION: a região ou a multirregião onde a consulta vai ser executada. Recomendamos que execute a consulta numa localização próxima dos dados. O valor predefinido é US.

Segue-se um exemplo de um ficheiro 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}

Use 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 o seguinte:

• COPYBOOK_FILEPATH: o caminho para o livro de registo DD.
• LOG_PROJECT: o nome do projeto de registo.
• PROJECT_NAME: o nome do projeto no qual quer executar a consulta.
• LOCATION: a localização onde a consulta vai ser executada. Recomendamos que execute a consulta numa localização próxima dos dados.
• BUCKET: O URI do Cloud Storage que vai conter o ficheiro binário de saída.

Segue-se um exemplo de um ficheiro 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"