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

Le tableau suivant répertorie les commandes BigQuery, Cloud Storage et d'autres commandes Google Cloud que vous pouvez utiliser avec le connecteur Mainframe.

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 prend en charge certaines fonctionnalités de réglage des performances. Pour en savoir plus, consultez la section Améliorations des performances pour la commande bq export.

Vous pouvez utiliser des jeux de caractères personnalisés avec la commande bq export. Pour en savoir plus, consultez la section Utiliser des jeux de caractères personnalisés.

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

Vous pouvez également utiliser la commande bq mk pour générer une table BigQuery directement à partir de l'analyse des livres de copie COBOL. Pour en savoir plus, consultez Créer une table BigQuery à partir d'un cahier de copie. 		Non
Utilisez cette commande pour créer une tâche de requête qui exécute la requête SQL spécifiée. La commande lit la requête SQL à partir de l'indicateur --sql ou 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 des millions. Pour que la sortie reste lisible par l'humain, le nombre de lignes affichées est limité. 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 la paramétrisation bq query, consultez la section Paramétrisation des requêtes bq.

Pour en savoir plus, consultez Requête bq. 		Oui
Utilisez cette commande pour supprimer définitivement une ressource BigQuery. Étant donné que cette commande supprime définitivement une ressource, nous vous recommandons de l'utiliser avec précaution. 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 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 Utilisez cette commande pour transcoder un ensemble de données et l'écrire dans Cloud Storage au format de fichier ORC (Optimized Row Columnar). La commande lit les données du DD INFILE et la mise en page des enregistrements 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 indicateurs suivants :
  • --inDsn: DSN de l'ensemble de données d'entrée. Si elle est fournie, cette option remplace INFILE DD.
  • --cobDsn: DSN du carnet de copie S'il est fourni, cet indicateur remplace COPYBOOK DD.


La commande ouvre ensuite un nombre configurable de connexions parallèles à l'API Cloud Storage et convertit 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 également utiliser cette commande pour interagir avec le service gRPC du connecteur mainframe exécuté sur une VM sur le mainframe. Pour ce faire, définissez les variables d'environnement SRVHOST et SRVPORT, ou fournissez le nom d'hôte et le numéro de port à l'aide d'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 le connecteur mainframe, puis un appel de procédure à distance (RPC) est effectué pour demander au service gRPC de transcoder le fichier.

Vous pouvez également effectuer les tâches suivantes avec la commande gsutil cp : 		Oui
Utilisez cette commande pour supprimer des buckets ou des objets dans un bucket. Pour en savoir plus, consultez rm : supprimer des objets. Non
Utilitaire gszutil L'utilitaire gszutil s'exécute à l'aide du SDK Java JZOS d'IBM et fournit un émulateur de shell qui accepte les invocations de ligne de commande gsutil et 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 query et load BigQuery à 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 environnement de production pour convertir les fichiers binaires dans Cloud Storage au 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 ensemble 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 en savoir plus, consultez 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 la sortie standard (stdout). Cela permet à l'équipe d'assistance du connecteur Mainframe de rassembler les informations nécessaires pour diagnostiquer un problème sans avoir à interagir beaucoup avec le client.
En fonction de l'indicateur que vous utilisez, la commande systemreport affiche les données système suivantes :
  • --supported_ciphers: algorithmes de chiffrement compatibles
  • --available_security_providers: fournisseurs de solutions de sécurité disponibles
 Non

Utiliser des jeux de caractères personnalisés

Le connecteur Mainframe est compatible avec différents jeux de caractères qui décodent des octets en chaînes BigQuery, et inversement. Mainframe Connector vous permet de configurer votre propre jeu de caractères personnalisé. Vous pouvez configurer un jeu de caractères personnalisé en créant un fichier de mappage de caractères Unicode (UCM). Le connecteur Mainframe est compatible avec le sous-ensemble suivant du format UCM:

<code_set_name>               "<name>"
<uconv_class>                 "SBCS"
<subchar>                     \x1A #Example

CHARMAP
#_______ _________
<U0000> \x00 |0       #For the third column, only 0 is supported.
<U0001> \x01 |0
#etc
END CHARMAP

Si vous souhaitez utiliser un jeu de caractères personnalisé, définissez un fichier de configuration au format UCM. Vous pouvez utiliser ce jeu de caractères personnalisé avec les commandes gsutil cp ou bq export en définissant l'indicateur --encoding=charset.

Lorsque vous créez un jeu de caractères personnalisé, assurez-vous que:

  • Lorsque vous définissez un fichier UCM, tenez compte des points suivants :
    • Le connecteur Mainframe n'est compatible qu'avec les jeux de caractères personnalisés utilisant un jeu de caractères à octet unique (SBCS).
    • Le connecteur Mainframe n'est compatible qu'avec l'indicateur de précision UCM |0.
    • Assurez-vous que les fichiers UCM se trouvent dans les services système Unix (USS) z/OS et non sur un ensemble de données partitionné par stockage virtuel multiple (MVS PDS).
    • Assurez-vous que les fichiers UCM sont enregistrés au format ASCII (American Standard Code for Information Interchange) et non au format EBCDIC (Extended Binary Coded Decimal Interchange Code).
  • Fournissez un mappage explicite pour chaque valeur d'octet unique possible sur un caractère Unicode. Si vous ne savez pas à quel caractère Unicode vous souhaitez mapper un octet, nous vous recommandons de le mapper sur U+FFFD. Vous pouvez mapper différentes séquences d'octets sur le même caractère Unicode. Toutefois, dans ces cas, la mise en correspondance n'est pas bidirectionnelle. Autrement dit, lorsque vous chargez des données dans BigQuery et les exportez ensuite vers un fichier binaire, la sortie peut différer de l'entrée d'origine.
  • Assurez-vous que les séquences d'octets de la deuxième colonne sont uniques. Si plusieurs séquences d'octets sont mappées sur le même caractère Unicode, ce caractère Unicode est décodé en séquence d'octets du dernier mappage défini dans le fichier UCM.
  • Assurez-vous que le connecteur Mainframe peut trouver le fichier UCM en définissant la variable d'environnement BQSH_FEATURE_CUSTOM_CHARSET sur le chemin d'accès du fichier UCM. Si vous souhaitez utiliser plusieurs jeux de caractères, vous pouvez fournir les chemins d'accès à plusieurs jeux de caractères séparés par un délimiteur point-virgule. Par exemple, BQSH_FEATURE_CUSTOM_CHARSET=path1;path2. path peut pointer vers un fichier local ou un fichier stocké dans Cloud Storage. Si vous exécutez les commandes gsutil cp ou bq export avec l'indicateur --remote pour effectuer un transcodage à distance, le connecteur Mainframe utilise la valeur locale définie pour la variable d'environnement BQSH_FEATURE_CUSTOM_CHARSET. Il en va de même lorsque vous exécutez Mainframe Connector en mode autonome. Si l'indicateur --encoding fait référence à un jeu de caractères personnalisé qui ne correspond pas à la valeur que vous avez définie pour BQSH_FEATURE_CUSTOM_CHARSET (ou si vous n'avez pas défini BQSH_FEATURE_CUSTOM_CHARSET du tout), la commande s'arrête avec un message d'erreur.

Configuration d'optimisation des performances pour la commande bq export

Mainframe Connector est compatible avec la configuration de réglage des performances suivante pour la commande bq export:

  • exporter_thread_count (facultatif) : définit le nombre de threads de travail. La valeur par défaut est 4.
  • max_read_streams (facultatif) : définit le nombre maximal de flux de lecture. 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 de files d'attente d'enregistrements de lecture. 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 la variable d'environnement OVERRIDE_GRPC_WINDOW_MB pour améliorer les performances. La taille de la 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 d'afficher un aperçu de la commande CREATE TABLE SQL générée sans créer réellement la table dans BigQuery.

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

  • --schema_from_copybook: spécifie le carnet de copie à utiliser pour créer la table.
  • --dry_run (facultatif) : lorsque cette option est activée, la commande n'affiche que la commande CREATE TABLE SQL générée sans l'exécuter. Par défaut, cette option est définie sur "false".
  • --tablespec "[PROJECT_ID]:[DATASET].[TABLE]": spécifie l'ID du projet BigQuery, l'ensemble de données et le nom de la table pour la table cible.
  • --encoding: spécifie l'encodage utilisé pour lire le fichier de modèle. 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 ne sont acceptées que pour les variables alphanumériques.

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 avec bq query.

Voici un exemple d'utilisation d'une requête bq query paramétrée:

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

Effectuer une simulation de la commande gsutil cp

La commande gsutil cp décode un fichier QSAM (Queued Sequential Access Method) à l'aide d'un livre de copie COBOL et génère un fichier ORC dans Cloud Storage. Vous pouvez effectuer une simulation de la commande gsutil cp à l'aide de l'indicateur dry_run et tester les étapes suivantes:

  • Analysez un fichier de données ou un manuel COBOL, puis vérifiez s'il est compatible avec Mainframe Connector.
  • Décoder un fichier QSAM sans l'écrire dans Cloud Storage

Utilisez la commande suivante pour effectuer une simulation:

gsutil cp \
--dry_run \
gs://result-dir

Si toutes les étapes sont exécutées correctement, la commande se termine avec le code de retour 0. En cas de problème, un message d'erreur s'affiche.

Lorsque vous utilisez l'indicateur dry_run, toutes les statistiques telles que le nombre total d'octets lus, le nombre d'enregistrements écrits et le nombre total d'erreurs sont enregistrées.

Si vous utilisez l'indicateur dry_run et que la source de données n'existe pas, la commande ne renvoie pas d'erreur. Il ne vérifie que l'analyseur de livre de copie, puis termine l'exécution.

Copier un fichier de Cloud Storage vers votre mainframe

Vous pouvez utiliser la commande gsutil cp pour copier un fichier de 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 de mainframe, spécifiez le DSN et les exigences d'espace du 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 l'option --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 supposé être au format d'enregistrement à longueur non définie (U).
  • BLKSIZE: (facultatif) Taille de bloc du fichier. Si cette valeur est définie sur 0, le système 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 non bloqué.
  • noseek: (facultatif) Incluez ce paramètre si vous souhaitez améliorer les performances de téléchargement. Cette option est définie sur "false" par défaut, ce qui signifie que les opérations de recherche 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 d'optimisation des performances pour la commande gsutil cp

Le connecteur Mainframe est compatible avec la configuration de réglage des performances suivante pour la commande gsutil cp.

  • Utilisez l'option --parallelism pour définir le nombre de threads. 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. Augmentez cette valeur pour réduire le nombre de segments créés, mais cela augmentera les besoins en mémoire pendant le processus de transcodage. Pour en savoir plus, consultez Analyser l'argument maxChunkSize. La valeur par défaut est de 128 Mo.
  • Utilisez l'argument --preload_chunk_count pour définir la quantité de données à précharger en mémoire lorsque tous les nœuds de calcul sont occupés. Cet argument peut améliorer les performances au prix 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 disposez de suffisamment de mémoire, nous vous recommandons d'augmenter la taille des fragments à 256 Mio ou même à 512 Mio, car cela réduit les coûts de création et de 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 fournir 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 de montants partiels. Par exemple, utilisez 716 Ko au lieu de 0,7 Mo.