Exécuter Mainframe Connector en mode autonome

Mainframe Connector version 5.13.0 et ultérieure est compatible avec l'exécution de Mainframe Connector en tant que job autonome sur Google Cloud. Cette fonctionnalité vous permet d'exécuter Mainframe Connector en tant que job par lot conteneurisé, par exemple en tant que job Cloud Run, job Google Kubernetes Engine ou dans un conteneur Docker. Cette option vous permet d'éviter d'installer Mainframe Connector localement sur votre mainframe et facilite l'intégration de l'analyse de vos fichiers QSAM (Queued Sequential Access Method) à vos workflows ETL (Extract, Transform, and Load) existants.

Lorsque vous utilisez la version autonome de Mainframe Connector, vous devez configurer vous-même le workflow ETL qui charge le fichier QSAM dans Google Cloud par vous-même.

Avant de commencer

• Déployez Mainframe Connector sur Cloud Run.
• Créez un compte de service ou identifiez-en un existant à utiliser avec Mainframe Connector. Ce compte de service doit disposer des autorisations nécessaires pour accéder aux buckets Cloud Storage, aux ensembles de données BigQuery et à toute autre Google Cloud ressource que vous souhaitez utiliser.
• Assurez-vous que le rôle Demandeur Cloud Run est attribué au compte de service que vous avez créé.
• Assurez-vous que les données du mainframe sont déjà disponibles sur Google Cloud sous forme de fichier QSAM.

Transcoder des données à l'aide de Mainframe Connector en mode autonome sur Cloud Run

Mainframe Connector vous permet d'exécuter Mainframe Connector en tant que job autonome sur Google Cloudde deux manières :

• À l'aide des commandes qsam (version 5.16.0 et ultérieure)
• À l'aide de la commande gsutil cp

Avantages des commandes qsam

Les commandes qsam offrent les avantages suivants :

• Prise en charge des types de données composés, y compris la clause OCCURS (listes), la clause REDEFINES et les enregistrements imbriqués. Pour en savoir plus sur ces types de données, consultez la documentation de référence sur le transcodage qsam et vsam.
• Prise en charge de la configuration du processus de transcodage via un fichier de configuration du transcodeur. Cette fonctionnalité offre plus de flexibilité lors du décodage des données dans Google Cloud, et de l'encodage des données dans le mainframe.
• Prise en charge de la création d'un ensemble de données de débordement, qui est une table d'erreurs de transcodage pouvant être utilisée pour l'inspection des erreurs.
• Prise en charge de plusieurs formats d'entrée et de sortie. Cette fonctionnalité vous permet de charger vos données dans et depuis différents entrepôts de données.

Exécuter Mainframe Connector en mode autonome à l'aide des commandes qsam

Pour transcoder vos données à l'aide de Mainframe Connector en mode autonome à l'aide des commandes qsam, procédez comme suit :

1. Créez un fichier YAML avec des commandes pour effectuer les opérations suivantes :

   • Lire votre ensemble de données
   • Le transcoder dans un format compatible
   • L'importer dans Cloud Storage

   L'ensemble de données d'entrée doit être un fichier QSAM avec une longueur d'enregistrement fixe ou variable. Vous pouvez utiliser l'exemple de fichier YAML suivant pour lire votre ensemble de données, le transcoder au format ORC et l'importer dans Cloud Storage.

   Dans l'exemple suivant, nous utilisons le Cloud Storage DataPath pour INFILE, OUTFILE, COPYBOOK, et 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"
   

   Remplacez les éléments suivants :

   • INFILE : nom du fichier d'entrée.
   • OUTFILE : nom du fichier de sortie.
   • COPYBOOK_PATH : chemin d'accès au DD du copybook.
   • TRANSCODE_CONFIGURATION_PATH: chemin d'accès au fichier de configuration du transcodage.
   • LOG_PROJECT : nom du projet de journalisation.

   Voici un exemple de fichier 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"
   

   Remarque

   • Les variables avec le suffixe FILLER sont ignorées lors du processus d'importation.
   • À partir de la version 5.12.0, Mainframe Connector remplace les traits d'union ("-") par des traits de soulignement ("_") dans les noms de variables. Si vous souhaitez conserver les traits d'union dans vos noms de variables, désactivez cette conversion automatique en définissant la variable de base de données BQSH_FEATURE_CONVERT_UNDERSCORE_IN_FIELDS_NAME sur false.

2. Créez un fichier job.yaml avec la commande suivante.

   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
   

   Remplacez les éléments suivants :

   • JOB : nom de votre job Cloud Run. Les noms de tâche doivent comporter un maximum de 49 caractères et être uniques par région et par projet.
   • IMAGE : URL de l'image de conteneur du job, par exemple us-docker.pkg.dev/cloudrun/container/job:latest.
   • LOCATION_OF_THE_COMMAND_YAML_FILE : emplacement du fichier YAML que vous avez créé à l'étape précédente.

3. Déployez la nouvelle tâche à l'aide de la commande suivante :

   gcloud run jobs replace job.yaml
   

4. Exécutez la tâche à l'aide de la commande suivante :

   gcloud run jobs execute JOB_NAME

   Remplacez JOB_NAME par le nom de la tâche.

Pour en savoir plus sur la création et l'exécution d'un job Cloud Run, consultez Créer un job et Exécuter un job.

Exécuter Mainframe Connector en mode autonome à l'aide de la commande gsutil cp

Pour transcoder vos données à l'aide de Mainframe Connector en mode autonome à l'aide de la commande gsutil cp, procédez comme suit :

1. Créez un fichier YAML avec des commandes pour effectuer les opérations suivantes :

   • Lire votre ensemble de données
   • Le transcoder au format ORC
   • L'importer dans Cloud Storage

   L'ensemble de données d'entrée doit être un fichier QSAM avec une longueur d'enregistrement fixe ou variable. Vous pouvez utiliser l'exemple de fichier YAML suivant pour lire votre ensemble de données, le transcoder au format ORC et l'importer dans Cloud Storage.

   Dans l'exemple suivant, lisez les données de l'ensemble de données INFILE et la mise en page de l'enregistrement à partir du 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
   

   Remplacez les éléments suivants :

   • INFILE : nom du fichier d'entrée.
   • INFILE_DSN: nom du fichier DSN (Data Source Name) d'entrée.
   • INFILE_DSN_FILEPATH : chemin d'accès au fichier DSN d'entrée.
   • COPYBOOK_FILEPATH : chemin d'accès au DD du copybook.
   • LOG_PROJECT : nom du projet de journalisation.

   Voici un exemple de fichier 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
   

   Remarque

   • Les variables avec le suffixe FILLER sont ignorées lors du processus d'importation.
   • À partir de la version 5.12.0, Mainframe Connector remplace les traits d'union ("-") par des traits de soulignement ("_") dans les noms de variables. Si vous souhaitez conserver les traits d'union dans vos noms de variables, désactivez cette conversion automatique en définissant la variable de base de données BQSH_FEATURE_CONVERT_UNDERSCORE_IN_FIELDS_NAME sur false.

   Pour obtenir la liste complète des variables d'environnement compatibles avec Mainframe Connector, consultez Variables d'environnement.

   Si vous souhaitez enregistrer les commandes exécutées lors de ce processus, vous pouvez activer les statistiques de chargement.

2. Créez un fichier job.yaml avec la commande suivante.

   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
   

   Remplacez les éléments suivants :

   • JOB : nom de votre job Cloud Run. Les noms de tâche doivent comporter un maximum de 49 caractères et être uniques par région et par projet.
   • IMAGE : URL de l'image de conteneur du job, par exemple us-docker.pkg.dev/cloudrun/container/job:latest.
   • LOCATION_OF_THE_COMMAND_YAML_FILE : emplacement du fichier YAML que vous avez créé à l'étape précédente.

3. Déployez la nouvelle tâche à l'aide de la commande suivante :

   gcloud run jobs replace job.yaml
   

4. Exécutez la tâche à l'aide de la commande suivante :

   gcloud run jobs execute JOB_NAME

   Remplacez JOB_NAME par le nom de la tâche.

Pour en savoir plus sur la création et l'exécution d'un job Cloud Run, consultez Créer un job et Exécuter un job.

Exporter une table BigQuery dans un ensemble de données de mainframe

Vous pouvez exporter une table BigQuery dans un ensemble de données de mainframe en créant un fichier YAML qui exécute une lecture SQL à partir du fichier QUERY DD, et exporte l'ensemble de données résultant vers Cloud Storage en tant que fichier binaire, comme suit.

Les étapes de création et d'exécution du job Cloud Run sont les mêmes que celles mentionnées dans la section Transcoder des données à l'aide de Mainframe Connector en mode autonome sur Cloud Run. La seule différence réside dans les instructions mentionnées dans le fichier YAML. Mainframe Connector vous permet d'exporter une table BigQuery de deux manières :

• À l'aide des commandes qsam (version 5.16.0 et ultérieure)

• À l'aide de la commande bq export

Utiliser les commandes 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}

Remplacez les éléments suivants :

• QUERY_PATH : requête SQL à exécuter. Le résultat de la requête sera encodé dans un fichier binaire.
• OUTFILE: bucket Cloud Storage qui contiendra le fichier binaire de sortie.
• COPYBOOK_PATH : chemin d'accès au DD du copybook.
• TRANSCODE_CONFIGURATION_PATH: chemin d'accès au fichier de configuration du transcodeur.
• LOG_PROJECT : nom du projet de journalisation.
• PROJECT_ID: ID du projet dans lequel vous souhaitez exécuter la requête.
• LOCATION: région ou emplacement multirégional où la requête sera exécutée. Nous vous recommandons d'exécuter la requête dans un emplacement proche des données. La valeur par défaut est "US".

Voici un exemple de fichier 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}

Utiliser la commande 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"

Remplacez les éléments suivants :

• COPYBOOK_FILEPATH : chemin d'accès au DD du copybook.
• LOG_PROJECT : nom du projet de journalisation.
• PROJECT_NAME: nom du projet dans lequel vous souhaitez exécuter la requête.
• LOCATION: emplacement où la requête sera exécutée. Nous vous recommandons d'exécuter la requête dans un emplacement proche des données.
• BUCKET: URI Cloud Storage qui contiendra le fichier binaire de sortie.

Voici un exemple de fichier 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"