Commandes de l'API Mainframe Connector

Le tableau suivant liste les commandes BigQuery, Cloud Storage et autres commandesGoogle Cloud que vous pouvez utiliser avec Mainframe Connector.

Utiliser des ensembles de caractères personnalisés

Le connecteur Mainframe est compatible avec différents ensembles de caractères qui décodent les 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 UCM (Unicode Character Mapping). Mainframe Connector 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 cet ensemble 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é, vérifiez les points suivants :

• Lorsque vous définissez un fichier UCM, gardez à l'esprit les points suivants :
  • Mainframe Connector n'accepte que les jeux de caractères personnalisés utilisant un jeu de caractères à un octet (SBCS).
  • Le connecteur Mainframe n'accepte que l'indicateur de précision UCM |0.
  • Vérifiez que les fichiers UCM se trouvent dans les services système Unix z/OS (USS) et non dans un ensemble de données partitionné à stockage virtuel multiple (MVS PDS).
  • Vérifiez 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 vers un caractère Unicode. Si vous ne savez pas quel caractère Unicode associer à un octet, nous vous recommandons de l'associer à U+FFFD. Vous pouvez mapper différentes séquences d'octets au même caractère Unicode. Toutefois, dans ces cas, le mappage n'est pas bidirectionnel. Autrement dit, lorsque vous chargez des données dans BigQuery et que vous les exportez ensuite dans un fichier binaire, la sortie peut différer de l'entrée d'origine.
• Vérifiez que les séquences d'octets de la deuxième colonne sont uniques. Si plusieurs séquences d'octets correspondent au même caractère Unicode, ce caractère Unicode est décodé en une séquence d'octets de la dernière mise en correspondance définie dans le fichier UCM.
• Vérifiez que Mainframe Connector 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 ensembles de caractères, vous pouvez fournir les chemins d'accès à plusieurs ensembles de caractères séparés par un point-virgule. Par exemple, BQSH_FEATURE_CUSTOM_CHARSET=path1;path2. path peut pointer vers un fichier local ou vers 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, Mainframe Connector 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 le connecteur Mainframe 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 se ferme avec un message d'erreur.

Configuration de l'optimisation des performances pour la commande bq export

Le connecteur Mainframe est compatible avec la configuration d'optimisation des performances suivante pour la commande bq export :

• exporter_thread_count : (facultatif) définissez le nombre de threads de worker. La valeur par défaut est 4.
• max_read_streams : (facultatif) définissez 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. Cette option affecte les performances d'exportation. La valeur par défaut est "false".
• max_read_queue : (facultatif) Définissez le nombre maximal de files d'attente d'enregistrements en 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 fenêtre par défaut est de 4 Mo.

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

Vous pouvez utiliser la commande bq mk pour générer une table BigQuery directement à partir de l'analyse des copybooks COBOL. L'analyseur de copybook natif extrait les valeurs par défaut de la clause VALUE d'un copybook 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 d'exécution à sec. Ce mode vous permet de prévisualiser 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 copybook à utiliser pour créer la table.
• --dry_run (facultatif) : lorsque cette option est activée, la commande n'imprime que la commande CREATE TABLE SQL générée sans l'exécuter. Par défaut, ce flag est défini 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 cible.
• --encoding : spécifie l'encodage utilisé pour lire le fichier copybook. 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 de 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 à l'aide d'un copybook COBOL et génère un fichier ORC sur 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 copybook ou un fichier de données COBOL, et vérifiez s'il est compatible avec Mainframe Connector.
• Décode un fichier QSAM sans l'écrire dans Cloud Storage.

Exécutez 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 ferme 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 consigné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. Au lieu de cela, il ne vérifie que l'analyseur de copybook, 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 les ensembles de données partitionnés (PDS).

Pour copier un fichier de Cloud Storage vers un ensemble de données de mainframe, spécifiez le nom de l'ensemble de données et les exigences d'espace du fichier que vous souhaitez télécharger sur le mainframe dans JCL, comme indiqué 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 ordinateur central, vérifiez que vous ajoutez l'option --replace à la commande.

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

Remplacez les éléments suivants :

• GCS_URI : identifiant URI (Uniform Resource Identifier) 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 nombre entier supérieur ou égal à 0. Si LRECL n'est pas spécifié, le fichier est considéré comme étant au format d'enregistrement à longueur indéfinie (U).
• BLKSIZE : (facultatif) taille de bloc du fichier. Si la valeur est définie sur 0, le système détermine la taille de bloc optimale. La valeur doit être un entier supérieur ou égal à 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 de l'optimisation des performances pour la commande gsutil cp

Mainframe Connector est compatible avec la configuration d'optimisation 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 (monothread).
• Utilisez l'argument --maxChunkSize pour définir la taille maximale de chaque bloc. Chaque bloc aura son propre fichier ORC. Augmentez cette valeur pour réduire le nombre de blocs créés, au détriment de besoins en mémoire plus importants lors du processus de transcodage. Pour en savoir plus, consultez 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 à 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 pour atteindre le débit de ligne. Si vous disposez de suffisamment de mémoire, nous vous recommandons d'augmenter la taille des blocs à 256 Mio, voire 512 Mio, car cela réduit la surcharge de création et de finalisation des objets Cloud Storage. Pour les petits fichiers, l'utilisation de moins de threads et de blocs plus petits peut donner de meilleurs résultats.

Analyser l'argument maxChunkSize

L'option maxChunkSize accepte les valeurs sous la forme d'un montant et d'une unité de mesure (par exemple, 5 Mio). Vous pouvez utiliser des espaces entre le montant et la magnitude.

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/kb/mb/gb/tb, 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 Kio au lieu de 0,7 Mio.