Documentation de référence de l'API Mainframe Connector

Le tableau suivant répertorie les API BigQuery, Cloud Storage et Commandes Google Cloud que vous pouvez utiliser avec Mainframe Connector.

Produit Commande Description Compatible avec le transcodage à distance
Commandes BigQuery Utilisez cette commande pour créer un fichier binaire. La commande accepte un COPYBOOK DD comme entrée.

La commande bq export est compatible avec certains réglages de performances des fonctionnalités. Pour en savoir plus, consultez la section Améliorations des performances pour la commande bq export.

Remarque : La commande bq export échoue pour les requêtes d'exportation de grandes tables Bigtable. Pour éviter les erreurs, ajoutez la méthode l'indicateur -allowLargeResults à bq export. lorsque vous voulez exporter de grandes tables.		 Oui
Utilisez cette commande pour charger des données dans une table. Pour en savoir plus, consultez bq load. Non
Utilisez cette commande pour créer des ressources BigQuery, telles que des tables intégrées ou externes, qui nécessitent un partitionnement et un clustering de configuration. Pour en savoir plus, consultez la page bq mk.

Vous pouvez également utiliser la commande bq mk pour générer table BigQuery directement à partir de l'analyse des cahiers COBOL. Pour en savoir plus, consultez Créer une table BigQuery à partir d'un cahier de copie. 		Non
Utilisez cette commande pour créer un job de requête qui exécute la requête SQL spécifiée. La commande lit la requête SQL à partir de l'option --sql ou à partir de QUERY DD. Si les deux sont fournis, la requête dans l'indicateur --sql est prioritaire.

Utilisez l'indicateur --follow=true pour générer un rapport qui affiche les résultats d'une requête select. Pour écrire ce rapport dans un fichier du mainframe, définissez une instruction DD AUDITL qui pointe vers le fichier qui doit contenir le rapport sur les journaux d'audit. N'utilisez pas l'indicateur --follow si vous souhaitez un comportement de journalisation normal.

Certains résultats de requête peuvent renvoyer un grand nombre de lignes, parfois en millions. Pour que le résultat reste lisible, le nombre de lignes affichée est plafonnée. Pour contrôler le nombre de lignes affichées, utilisez l'indicateur --report_row_limit. Par exemple, utilisez --report_row_limit 10 pour limiter les résultats à 10 lignes. Par défaut, le nombre de lignes affichées est limité à 30.

Pour utiliser le paramétrage bq query, consultez la page Paramétrer une requête bq.

Pour en savoir plus, consultez la section bq query. 		Oui
Utilisez cette commande pour supprimer définitivement une ressource BigQuery. En tant que cette commande supprime définitivement une ressource, nous vous recommandons de l'utiliser avec prudence. Pour en savoir plus, consultez bq rm. Non
Commandes Cloud Storage Utilisez cette commande pour copier des données textuelles ou binaires vers Cloud Storage. Vous pouvez utiliser le mode de copie binaire simple pour copier un ensemble de données d'IBM z/OS vers Cloud Storage sans le modifier dans le cadre d'un pipeline de données. Vous pouvez également convertir l'encodage de caractères de l'EBCDIC (Extended Binary Coded Decimal Interchange Code) en ASCII UTF-8, et ajouter des sauts de ligne.

Vous pouvez également utiliser cette commande pour copier le code source de l'application défini dans le langage de contrôle des tâches (JCL). 		Non
Utilitaire gsutil Utiliser cette commande pour transcoder un ensemble de données et l'écrire dans Cloud Storage dans la colonne Optimized Row Columnar (ORC) . La commande lit les données à partir de INFILE DD et la disposition des enregistrements à partir du Fichier COPYBOOK. Si vous souhaitez que la commande lise les données à partir d’un fichier de nom de source de données (DSN), utilisez les options suivantes:
  • --inDsn: DSN de l'ensemble de données d'entrée. Si cet indicateur est fourni, remplace INFILE DD.
  • --cobDsn: DSN du recueil d'e-mails. Si cet indicateur est fourni, remplace COPYBOOK DD.
La commande ouvre ensuite un nombre configurable de connexions parallèles à l'API Cloud Storage et transcode l'ensemble de données COBOL au format de fichier ORC en colonnes et compressé GZIP. Vous pouvez vous attendre à un taux de compression d'environ 35 %.

Vous pouvez éventuellement utiliser cette commande pour interagir avec Service gRPC du connecteur de mainframe qui s'exécute sur une VM sur le mainframe. Pour ce faire, définissez SRVHOST et SRVPORT, ou indiquez le nom d'hôte et à l'aide des options de ligne de commande. Lorsque le service gRPC est utilisé, l'ensemble de données d'entrée est d'abord copié dans Cloud Storage par Mainframe Connector, puis un appel de procédure à distance (RPC) est effectué pour demander au service gRPC de transcoder le fichier.

Vous pouvez également utiliser la commande gsutil cp pour effectuer les opérations suivantes: 		Oui
Utilisez cette commande pour supprimer des buckets ou des objets dans un bucket. Pour plus plus d'informations, consultez la section rm – Supprimer des objets. Non
Utilitaire gszutil L'utilitaire gszutil s'exécute à l'aide du SDK Java IBM JZOS et fournit un émulateur de shell. compatible avec gsutil et la ligne de commande BigQuery à l'aide de JCL.

La commande gszutil étend les fonctionnalités de la commande gsutil en acceptant un schéma sous la forme d'un COPYBOOK DD, qu'elle utilise pour transcoder directement les ensembles de données COBOL en ORC avant de les importer dans Cloud Storage. L'utilitaire gszutil vous permet également d'exécuter BigQuery query et load à l'aide de JCL

L'utilitaire gszutil fonctionne avec le serveur gRPC, ce qui vous permet de réduire la consommation de millions d'instructions par seconde (MIPS). Nous vous recommandons d'utiliser l'utilitaire gszutil dans votre de production pour convertir les fichiers binaires de Cloud Storage Format ORC. 		Non
Autres commandes Utilisez cette commande pour envoyer un message à un sujet Pub/Sub. Vous pouvez fournir le message à l’aide de la ligne de commande ou d’un jeu de données. Non
Utilisez cette commande pour déclencher l'exécution d'un modèle Dataflow flex. La commande exécute une tâche à partir du chemin d'accès au modèle Flex spécifié. Pour Pour en savoir plus, consultez la page sur gcloud dataflow flex-template run. Non
Utilisez cette commande pour envoyer une requête HTTP à un service Web ou à des API REST. Non
Utilisez cette commande pour imprimer les données système nécessaires sur le fichier sortie (stdout). Cela permet à l'équipe d'assistance Mainframe Connector de recueillir les informations nécessaires pour diagnostiquer un problème sans avoir besoin une interaction approfondie avec les clients.
En fonction de l'option utilisée, la commande systemreport affiche l'élément les données système suivantes:
  • --supported_ciphers: algorithmes de chiffrement compatibles
  • --available_security_providers: fournisseurs de solutions de sécurité disponibles
 Non

Configuration du réglage des performances pour la commande bq export

Le connecteur de mainframe est compatible avec les réglages de performances suivants : pour la commande bq export:

  • exporter_thread_count (facultatif) : définit le nombre de nœuds de calcul les threads. La valeur par défaut est 4.
  • max_read_streams (facultatif) : définit le nombre maximal de flux de lecture. La la valeur par défaut est identique à celle définie pour exporter_thread_count
  • order_response (facultatif) : si vous définissez cette option sur "true", l'exportateur conserve l'ordre des résultats de la requête. Cet indicateur affecte les performances d'exportation. La valeur par défaut est false.
  • max_read_queue (facultatif) : définit le nombre maximal d'enregistrements lus. les files d'attente. La valeur par défaut est le double du nombre de threads.
  • transcoding_buffer (facultatif) : définissez la taille de la mémoire tampon de transcodage par thread en Mo. La valeur par défaut est de 20 Mo.

Notez que vous pouvez également essayer d'augmenter la taille de la fenêtre de transport en définissant OVERRIDE_GRPC_WINDOW_MB variable d'environnement pour améliorer les performances. La taille de fenêtre par défaut est de 4 Mo.

Créer une table BigQuery à partir d'un cahier

Vous pouvez utiliser la commande bq mk pour générer une table BigQuery directement à partir de l'analyse des livres de copie COBOL. L'analyseur de livre de copie natif extrait les valeurs par défaut de la clause VALUE dans un livre de copie et les attribue aux colonnes correspondantes d'une table BigQuery nouvellement créée.

Pour vous aider à tester cette fonctionnalité, la commande bq mk fournit également un mode simulation. Ce mode vous permet de prévisualiser les CREATE TABLE SQL sans créer la table dans dans BigQuery.

La commande bq mk fournit les options de configuration suivantes pour prennent en charge cette fonctionnalité:

  • --schema_from_copybook : spécifie le carnet de copie à utiliser pour créer la table.
  • --dry_run (facultatif) : si cette option est activée, la commande n'affiche que le la commande CREATE TABLE SQL générée sans l'exécuter. Cette option est définie sur "false" par défaut.
  • --tablespec "[PROJECT_ID]:[DATASET].[TABLE]": spécifie le ID du projet BigQuery, ensemble de données et nom de la table cible.
  • --encoding: spécifie l'encodage utilisé pour lire le recueil. . La valeur par défaut est CP037.

Les clauses VALUE suivantes sont acceptées :

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

Les clauses HIGH-VALUE et LOW-VALUE sont compatibles avec variables alphanumériques uniquement.

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>

Paramétrage bq query

Mainframe Connector vous permet d'utiliser des requêtes paramétrées bq query

Voici un exemple d'utilisation d'une règle Requête bq query:

Fichier de requête

SELECT * FROM `bigquery-public-data.samples.wikipedia` WHERE title = @xtitle

Voici un exemple avec plusieurs paramètres.

Fichier de requête

SELECT * FROM bigquery-public-data.samples.wikipedia WHERE title = @mytitle AND num_characters > @min_chars;

Exemple d'exécution

bq query \
--project_id=mainframe-connector-dev \
--location="US" \
--parameters=mytitle::Hippocrates,min_chars:INT64:42600

Copier un fichier de Cloud Storage vers votre mainframe

Vous pouvez utiliser la commande gsutil cp pour copier un fichier depuis Cloud Storage vers un ensemble de données mainframe. Notez que vous ne pouvez pas copier des ensembles de données partitionnés.

Pour copier un fichier de Cloud Storage vers un ensemble de données Mainframe, spécifiez le DSN et l'espace requis pour le fichier que vous souhaitez télécharger sur le mainframe dans JCL, comme illustré dans l'exemple suivant:

//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 *

Spécifiez la commande gsutil cp au format suivant. Si le fichier existe déjà sur votre mainframe, veillez à ajouter le --replace à la commande.

gsutil cp GCS_URI DSN --recfm=RECFM --lrecl=LRECL --blksize=BLKSIZE --noseek

Remplacez les éléments suivants :

  • GCS_URI : URI (identifiant de ressource uniforme) Cloud Storage du fichier Cloud Storage. Exemple :gs://bucket/sample.mainframe.dsn
  • DSN : emplacement de destination du DSN sur le mainframe.
  • RECFM : format d'enregistrement (RECFM) du fichier mainframe. Les valeurs valides sont F, FB et U. Notez que ces valeurs ne sont pas sensibles à la casse.
  • LRECL : (facultatif) Longueur d'enregistrement (LRECL) du fichier. La valeur doit être un entier >= 0. Si LRECL n'est pas spécifié, le fichier est considéré comme au format d'enregistrement de longueur indéterminée (U).
  • BLKSIZE : (facultatif) Taille de bloc du fichier. Si la valeur est définie sur 0, déterminera la taille de bloc optimale. La valeur doit être un entier >= 0. Si vous ne spécifiez pas de valeur, le fichier est traité comme un fichier débloqué.
  • noseek : (facultatif) Incluez ce paramètre si vous souhaitez améliorer les performances de téléchargement. Cet indicateur est défini sur "false" par défaut, c'est-à-dire que sont activées.

Exemple d'exécution

gsutil cp gs://sample-bucket/MAINFRAME.DSN.FILE MAINFRAME.DSN.FILE \
--lrecl=16 --blksize=0 --recfm=fb

Configuration du réglage des performances pour la commande gsutil cp

Le connecteur de mainframe est compatible avec les réglages de performances suivants : la configuration de la commande gsutil cp.

  • Utilisez l'option --parallelism pour définir le nombre de threads. La la valeur par défaut est 1 (thread unique).
  • Utilisez l'argument --maxChunkSize pour définir la taille maximale de chaque bloc. Chaque segment aura son propre fichier ORC (Optimized Row Columnar). Augmentez cette valeur pour réduire le nombre de segments créés, mais au détriment des besoins en mémoire plus importants pendant le processus de transcodage. Pour en savoir plus, consultez la section Analyser l'argument maxChunkSize. La valeur par défaut est de 128 Mio.
  • Utilisez l'argument --preload_chunk_count pour définir la quantité de données est préchargé en mémoire pendant que tous les nœuds de calcul sont occupés. Cet argument peut améliorer au détriment de la mémoire. La valeur par défaut est "2".

Exemple d'exécution

gsutil cp \
  --replace \
  --parser_type=copybook \
  --parallelism=8 \
  --maxChunkSize=256MiB \
  gs://$BUCKET/test.orc

Dans cet exemple, nous avons considéré un fichier volumineux et avons donc utilisé huit threads à partir desquels le débit de ligne est atteint. Si vous avez suffisamment de mémoire, nous vous recommandons la taille des fragments à 256 Mio, voire 512 Mio, pour éviter de créer et la finalisation des objets Cloud Storage. Pour les petits fichiers, utiliser moins de threads et des segments plus petits peut produire de meilleurs résultats.

Analyser l'argument maxChunkSize

L'indicateur maxChunkSize accepte des valeurs sous la forme d'une quantité et d'une unité de mesure, par exemple 5 Mo. Vous pouvez utiliser un espace entre la quantité et l'intensité.

Vous pouvez indiquer la valeur dans les formats suivants:

  • Format Java:b/k/m/g/t, pour octet, kibioctet, mébioctet, gibioctet et tébioctet respectivement
  • Format international : KiB/MiB/GiB/TiB, pour kibioctet, mébioctet, gibioctet et tébioctet, respectivement
  • Format métrique : b/ko/Mo/Go/To, pour kilo-octet, mégaoctet, gigaoctet et téraoctet, respectivement

L'analyse de la taille des données n'est pas sensible à la casse. Notez que vous ne pouvez pas spécifier montants. Par exemple, utilisez 716 Ko au lieu de 0,7 Mo.