Ejecuta Mainframe Connector en modo independiente

En esta página, se explica cómo instalar Mainframe Connector en Cloud Run, transcodificar datos, guardarlos en BigQuery y exportarlos desde BigQuery.

La versión 5.13.0 y versiones posteriores de Mainframe Connector admiten la ejecución de Mainframe Connector como un trabajo independiente en Google Cloud. Esta función te permite ejecutar Mainframe Connector como un trabajo por lotes en contenedores, por ejemplo, como un trabajo de Cloud Run, un trabajo de Google Kubernetes Engine o dentro de un contenedor de Docker. Esta opción te ayuda a evitar la instalación local de Mainframe Connector en tu mainframe y facilita la integración del análisis de archivos del método de acceso secuencial en cola (QSAM) de tu mainframe a los flujos de trabajo existentes de extracción, transformación y carga (ETL).

Cuando usas la versión independiente de Mainframe Connector, debes configurar el flujo de trabajo de ETL que carga el archivo QSAM en Google Cloud por tu cuenta.

Antes de comenzar

  • Implementa Mainframe Connector en Cloud Run.
  • Crea una cuenta de servicio o identifica una cuenta de servicio existente para usarla con Mainframe Connector. Esta cuenta de servicio debe tener permisos para acceder a los buckets de Cloud Storage, los conjuntos de datos de BigQuery y cualquier otro recurso de Google Cloud que desees usar.
  • Asegúrate de que la cuenta de servicio que creaste tenga asignado el rol de invocador de Cloud Run.
  • Asegúrate de que los datos de la unidad central ya estén disponibles en Google Cloud como un archivo QSAM.

Transcodifica datos con Mainframe Connector en modo independiente en Cloud Run

Mainframe Connector proporciona dos formas de ejecutar Mainframe Connector como un trabajo independiente en Google Cloud:

Ventajas de los comandos qsam

Los comandos qsam proporcionan las siguientes ventajas:

  • Admite tipos de datos compuestos, incluidas las cláusulas OCCURS (listas), REDEFINES y registros anidados. Para obtener más información sobre estos tipos de datos, consulta la referencia de transcodificación de qsam.
  • Admite la configuración del proceso de transcodificación a través de un archivo de configuración del transcodificador. Esta capacidad ofrece más flexibilidad cuando se decodifican datos para Google Cloudy cuando se vuelven a codificar los datos en el mainframe.
  • Admite la creación de un conjunto de datos de desbordamiento, que es una tabla de errores de transcodificación que se puede usar para la inspección de errores.
  • Admite varios formatos de entrada y salida. Esta capacidad te permite cargar tus datos en varios almacenes de datos y desde ellos.

Ejecuta Mainframe Connector en modo independiente con comandos qsam

Para transcodificar tus datos con Mainframe Connector en modo independiente con comandos de qsam, sigue estos pasos:

  1. Crea un archivo YAML con comandos para hacer lo siguiente:

    • Lee tu conjunto de datos
    • Transcodifícalo a un formato compatible
    • Súbelo a Cloud Storage

    El conjunto de datos de entrada debe ser un archivo QSAM con una longitud de registro fija o variable. Puedes usar el siguiente archivo YAML de muestra para leer tu conjunto de datos, transcodificarlo al formato ORC y subirlo a Cloud Storage.

    En el siguiente ejemplo, usamos DataPath de Cloud Storage para INFILE, OUTFILE, COPYBOOK y 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"

    Reemplaza lo siguiente:

    • INFILE: Es el nombre del archivo de entrada.
    • OUTFILE: Es el nombre del archivo de salida.
    • COPYBOOK_PATH: Es la ruta de acceso al DD de copybook.
    • TRANSCODE_CONFIGURATION_PATH: Es la ruta de acceso al archivo de configuración de transcodificación.
    • LOG_PROJECT: Es el nombre del proyecto de registro.

    El siguiente es un ejemplo de un archivo 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. Crea un archivo job.yaml con el siguiente 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

    Reemplaza lo siguiente:

    • JOB por el nombre del trabajo de Cloud Run. Los nombres de trabajos deben tener 49 caracteres o menos, y deben ser únicos por región y proyecto.
    • IMAGE: Es la URL de la imagen de contenedor del trabajo, por ejemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
    • LOCATION_OF_THE_COMMAND_YAML_FILE: Es la ubicación del archivo YAML que creaste en el paso anterior.

  3. Implementa el servicio nuevo mediante el siguiente comando:

    gcloud run jobs replace job.yaml

  4. Ejecuta el trabajo con el siguiente comando:

    gcloud run jobs execute JOB_NAME

    Reemplaza JOB_NAME por el nombre del trabajo.

Para obtener más información sobre cómo crear y ejecutar un trabajo de Cloud Run, consulta Crea un trabajo nuevo y Ejecuta un trabajo.

Ejecuta Mainframe Connector en modo independiente con el comando gsutil cp.

Para transcodificar tus datos con Mainframe Connector en modo independiente con el comando gsutil cp, sigue estos pasos:

  1. Crea un archivo YAML con comandos para hacer lo siguiente:

    • Lee tu conjunto de datos
    • Transcodifícalo a ORC
    • Súbelo a Cloud Storage

    El conjunto de datos de entrada debe ser un archivo QSAM con una longitud de registro fija o variable. Puedes usar el siguiente archivo YAML de muestra para leer tu conjunto de datos, transcodificarlo al formato ORC y subirlo a Cloud Storage.

    En el siguiente ejemplo, se leen los datos del conjunto de datos INFILE y el diseño de registros del DD COPYBOOK.

    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

    Reemplaza lo siguiente:

    • INFILE: Es el nombre del archivo de entrada.
    • INFILE_DSN: Es el nombre del archivo de nombre de la fuente de datos (DSN) de entrada.
    • INFILE_DSN_FILEPATH: Es la ruta de acceso al archivo DSN de entrada.
    • COPYBOOK_FILEPATH: Es la ruta de acceso al DD de copybook.
    • LOG_PROJECT: Es el nombre del proyecto de registro.

    El siguiente es un ejemplo de un archivo 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 obtener la lista completa de las variables de entorno compatibles con Mainframe Connector, consulta Variables de entorno.

    Si quieres registrar los comandos que se ejecutan durante este proceso, puedes habilitar las estadísticas de carga.

  2. Crea un archivo job.yaml con el siguiente 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

    Reemplaza lo siguiente:

    • JOB por el nombre del trabajo de Cloud Run. Los nombres de trabajos deben tener 49 caracteres o menos, y deben ser únicos por región y proyecto.
    • IMAGE: Es la URL de la imagen de contenedor del trabajo, por ejemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
    • LOCATION_OF_THE_COMMAND_YAML_FILE: Es la ubicación del archivo YAML que creaste en el paso anterior.

  3. Implementa el servicio nuevo mediante el siguiente comando:

    gcloud run jobs replace job.yaml

  4. Ejecuta el trabajo con el siguiente comando:

    gcloud run jobs execute JOB_NAME

    Reemplaza JOB_NAME por el nombre del trabajo.

Para obtener más información sobre cómo crear y ejecutar un trabajo de Cloud Run, consulta Crea un trabajo nuevo y Ejecuta un trabajo.

Exporta la tabla de BigQuery al conjunto de datos de Mainframe

Para exportar una tabla de BigQuery a un conjunto de datos de la unidad central, crea un archivo YAML que ejecute una lectura de SQL desde el archivo DD de QUERY y exporte el conjunto de datos resultante a Cloud Storage como un archivo binario, de la siguiente manera.

Los pasos para crear y ejecutar el trabajo de Cloud Run son los mismos que se mencionan en la sección Transcodifica datos con Mainframe Connector en modo independiente en Cloud Run. La única diferencia son las instrucciones que se mencionan en el archivo YAML. El conector de Mainframe proporciona dos formas de exportar tablas de BigQuery:

  • Usa los comandos de qsam (versión 5.16.0 y posteriores)

  • Usa el comando bq export

Usa los comandos de 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}

Reemplaza lo siguiente:

  • QUERY_PATH: Es la consulta en SQL que se ejecutará. El resultado de la búsqueda se codificará en un archivo binario.
  • OUTFILE: Es el bucket de Cloud Storage que contendrá el archivo binario de salida.
  • COPYBOOK_PATH: Es la ruta de acceso al DD de copybook.
  • TRANSCODE_CONFIGURATION_PATH: Es la ruta de acceso al archivo de configuración del transcodificador.
  • LOG_PROJECT: Es el nombre del proyecto de registro.
  • PROJECT_ID: Es el ID del proyecto en el que deseas ejecutar la consulta.
  • LOCATION: Es la región o multirregión en la que se ejecutará la búsqueda. Te recomendamos que ejecutes la consulta en una ubicación cercana a los datos. El valor predeterminado es US.

El siguiente es un ejemplo de un archivo 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}

Usa el 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"

Reemplaza lo siguiente:

  • COPYBOOK_FILEPATH: Es la ruta de acceso al DD de copybook.
  • LOG_PROJECT: Es el nombre del proyecto de registro.
  • PROJECT_NAME: Es el nombre del proyecto en el que deseas ejecutar la consulta.
  • LOCATION: Es la ubicación en la que se ejecutará la consulta. Te recomendamos que ejecutes la consulta en una ubicación cercana a los datos.
  • BUCKET: Es el URI de Cloud Storage que contendrá el archivo binario de salida.

El siguiente es un ejemplo de un archivo 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"