Documentation de référence sur l'analyseur de cahier

Mainframe Connector est compatible avec deux versions de l'analyseur de cahiers des charges:

  • Analyseur de cahier natif: l'analyseur de cahier des charges natif. implémente un analyseur basé sur ANTLR4, prend en charge les recueils COBOL et constitue version recommandée de l'analyseur.
  • Analyseur de cahiers des charges: cet analyseur est une ancienne version de l'analyseur compatible des cahiers des charges.

Vous pouvez définir l'analyseur que vous souhaitez utiliser en fonction de votre modèle. Pour en savoir plus sur la définition de l'analyseur que vous souhaitez utiliser, consultez la section Définir l'analyseur de livre de copie.

Analyseur de cahiers natifs

L'analyseur de cahiers natifs est la dernière version de l'analyseur et est utilisé par défaut. L'analyseur de livrets de codes natif implémente un analyseur basé sur ANTLR4 et est compatible avec les livrests de codes COBOL.

Cette section liste les tâches de prétraitement effectuées par les types de données compatibles avec l'analyseur de livret de copie natif, ainsi que les restrictions d'utilisation.

Preprocessing

Avant d'analyser un livre de copie, l'analyseur de livre de copie natif prétraite les données et effectue les tâches suivantes :

  • Supprime les lignes de commentaire.
  • Résout la continuation de ligne.
  • Efface les zones de numéros de ligne et les zones de la colonne 73.
  • Conserve les instructions spécifiques au préprocesseur telles que EJECT, SPACE et TITLE. Ces champs sont analysés, mais sont ignorées. Les manuels contenant des paramètres de préprocesseur pouvant être utilisés par COPY REPLACING ne sont pas compatibles avec l'analyseur de manuels natif. Dans ces cahiers, les identifiants sont entourés d'un deux-points (:).

Types de données compatibles et restrictions

Vous trouverez ci-dessous les types de données compatibles avec l'analyseur de livre de copie natif et les restrictions d'utilisation :

  • Les niveaux 66 (ALIAS) ou 77 (STANDALONE) ne sont pas acceptés.
  • N'utilisez que des champs PICTURE. Les champs PICTURE suivants sont acceptés:
    • Pic A, Pic, B, Pic G (DBCS), Pic N (national ou DBCS), Pic U (UTF8), Pic X, et décimales par zone (précision maximale de 38, échelle maximale de 38)
  • La norme IBM Hexadecimal virgule flottante (HFP) est acceptée.
  • Les REDEFINES ne sont pas acceptés.
  • N'utilisez que les champs COMP suivants. ALIGN et OCCURS ne sont pas pris en charge.
    • COMP
    • COMP4
    • BINARY
    • COMP3
    • PACKED-DECIMAL
  • DATE et TIMESTAMP sont acceptés.
  • Les indicateurs nuls sont acceptés.
  • Les champs Pic G et Pic N du jeu de caractères à deux octets (DBCS) sont compatibles et doivent être utilisés à la place de Pic T, qui est désormais obsolète. À utiliser le champ Pic N comme DBCS sans spécifier USAGE DISPLAY-1 ; vous devez définir la variable d'environnement NSYMBOL sur DBCS Par défaut, NSYMBOL est défini sur NATIONAL, ce qui définit USAGE NATIONAL sur les champs Pic N qui ne comportent pas de clause USAGE. Notez que NSYMBOL ne peut être défini que sur NATIONAL ou DBCS.
  • Les chaînes de caractères de longueur variable sont acceptées.
  • La clause SIGN est acceptée.
  • Vous devez justifier tous les champs et utiliser un seul niveau de retrait.
  • Les commentaires sont acceptés.

Prise en charge des champs de date et d'horodatage

Mainframe Connector prend en charge le transfert des données de date et d'horodatage vers et depuis de BigQuery. Pour ce faire, vous devez définir des variables d'environnement qui commencent par le mot SUFFIX au format suivant:

SUFFIX_SUFFIX_STRING="command --format FORMAT --timezone TIMEZONE"

La liste suivante décrit le format plus en détail :

  • SUFFIX_SUFFIX_STRING: variable d'environnement qui que vous pouvez utiliser pour définir des données de date et d'horodatage. SUFFIX_STRING nom correspond aux suffixes -SUFFIX_STRING ou _SUFFIX_STRING, qui doit être interprété comme une date ou code temporel lorsqu'il est utilisé comme suffixe d'un nom de champ dans un recueil. Assurez-vous que SUFFIX_STRING ne contient pas de trait d'union ni de trait de soulignement.
  • command: définit le décodeur à utiliser pour analyser le . Les commandes acceptées sont date-converter et timestamp-converter.
  • --format : paramètre qui définit le format de la date ou de l'horodatage. Vous pouvez indiquer au maximum cinq formats différents séparés par une virgule. Si plusieurs formats peuvent correspondre à une entrée donnée, le premier format correspondant est utilisé pour le chargement dans BigQuery. Si plusieurs formats sont spécifiés pour , seul le premier format est utilisé. Pour en savoir plus sur les formats valides, consultez la section Formats de date et d'horodatage acceptés.
  • --timezone: paramètre facultatif pour le type TIMESTAMP. Par défaut, le fuseau horaire est UTC. Pour en savoir plus sur les fuseaux horaires acceptés consultez la page Formats de fuseau horaire acceptés.
  • --omitsuffix (facultatif) : si ce paramètre est spécifié, -SUFFIX_STRING ou _SUFFIX_STRING est supprimé du nom du champ qui s'affiche dans BigQuery.

Pour ajouter un alias à un SUFFIX_SUFFIX_STRING, vous pouvez définir une variable d'environnement SUFFIX_SUFFIX_ALIAS=$SUFFIX_SUFFIX_STRING.

Exemples :

  • Si vous définissez une variable d'environnement sur SUFFIX_DT8="date-converter --format yyyyMMdd", un champ avec le suffixe -DT8 ou _DT8 sera un champ de type DATE dans BigQuery, et son format sera yyyyMMdd.
  • Si vous définissez une variable d'environnement sur SUFFIX_DT10="date-converter --format MM-dd-yyyy", un champ avec le suffixe -DT10 ou _DT10 sera un champ de type DATE dans BigQuery, et son format sera MM-dd-yyyy.
  • Si vous définissez une variable d'environnement en tant que SUFFIX_DT="date-converter --format 'MM-dd-yyyy,MM/dd/yyyy'", un le champ comportant le suffixe -DT ou _DT sera une DATE dans BigQuery, son format sera MM-dd-yyyy ou MM/dd/yyyy.
  • Si vous définissez deux variables d'environnement sur SUFFIX_TIMESTAMP="timestamp-converter --format yyyy-MM-dd SUFFIX_TIMESTAMP=timestamp-converter --format 'yyyy-MM-dd HH.mm.ss.SSSSSS' --timezone America/New_York" et SUFFIX_TS=$SUFFIX_TIMESTAMP, un champ avec l'un des suffixes suivants : -TIMESTAMP, _TIMESTAMP, -TS ou _TS sera un champ de type TIMESTAMP dans BigQuery, et son format sera yyyy-MM-dd HH:mm:ss.SSSSSS avec le fuseau horaire America/New_York.

Prise en charge des indicateurs de valeur nulle

Mainframe Connector prend en charge les indicateurs nuls à partir de la version 5.13.0. Pour utiliser des indicateurs nuls, vous devez définir des variables d'environnement commençant par le mot SUFFIX au format suivant :

SUFFIX_NULL_INDICATOR_NAME="command --null-value NULL_VALUE --not-null-value NOT_NULL_VALUE"

NULL_INDICATOR_NAME correspond aux suffixes -NULL_INDICATOR_NAME ou _NULL_INDICATOR_NAME qui sont interprétés comme un indicateur nul lorsqu'ils sont utilisés comme suffixe d'un nom de champ dans un cahier.

La liste suivante décrit les paramètres que vous pouvez utiliser avec ces environnements variables:

  • command : la valeur doit être null-indicator.
  • –null-value: la valeur null indicator indique que le champ référencé est nul. La valeur de --null-value doit être soit une chaîne, soit un nombre décimal.
  • –not-null-value (facultatif) : si spécifié, la valeur null indicator indique que le champ référencé n'est pas nul. Si ce paramètre n'est pas défini, toute valeur autre que –value-null est acceptée. La valeur de –not-null-value doit être une chaîne ou un nombre décimal.
  • –keep : (facultatif) Lorsque spécifié, le champ null-indicator est conservé en tant que colonne dans le format de fichier ORC (Optimized Row Columnar). Par par défaut, ce champ n'est pas conservé au format ORC.

Si null-indicator ne comporte pas de champ référencé, Mainframe Connector affiche un message d'erreur et arrête de traiter les fichiers.

Exemples :

Extrait du recueil

10 COL1-NID1            PIC S9(4) USAGE COMP.
10 COL1                 PIC S9(6) USAGE COMP.

10 FIELD       PIC        X(10).
10 FIELD-NID2  PIC        X(1).

10 COL2       PIC        X(10).
10 COL2-NULL  PIC        X(1).

Définition des variables d'environnement

SUFFIX_NID1="null-indicator --null-value -1 --not-null-value 0"
# Copybook fields with NID1 suffix null indicator configuration.
SUFFIX_NID2="null-indicator --null-value '?'"
# Copybook fields with NID2 suffix null indicator configuration.
SUFFIX_NULL="null-indicator --null-value '?' --keep"
# Copybook fields with NULL suffix null indicator configuration.

Compatibilité avec les champs DBCS

Vérifiez les points suivants lorsque vous utilisez des champs DBCS:

  • Lorsque vous utilisez des champs PIC G ou Pic N DBCS, vous devez fournir l'un des éléments suivants encodages de jeux de caractères multi-octets (MBCS) valides dans le fichier encoding ou dans la variable d'environnement ENCODING lorsque vous utilisez Commandes gsutil cp ou bq export:
    • x-IBM930
    • x-IBM933
    • X-IBM935
    • X-IBM937
    • x-IBM939
    • x-IBM942
    • x-IBM942C
    • X-IBM943
    • X-IBM943C
    • x-IBM949
    • x-IBM949C
    • X-IBM 950
    • x-IBM964
    • x-IBM970
    • x-IBM1364
  • Lorsqu'un champ de livre de copie ne contient que des octets DBCS, mais que ces octets ne sont pas entourés de caractères de décalage de sortie (0x0E) et de décalage de saisie (0x0F), vous devez ajouter le suffixe _DBCS au nom du champ pour vous assurer que ces octets sont décodés en tant qu'octets DBCS.

Par exemple, si vos données correspondant au champ cahier 03 FLD01 PIC N USAGE DISPLAY-1 contient les octets 0x43 et 0xC5 au format x-IBM930 qui ne sont pas entourés de 0x0E et 0x0F, vous devez renommer le champ du cahier comme suit : 03 FLD01-DBCS PIC N USAGE DISPLAY-1 pour décoder correctement les données DBCS.

Compatibilité avec les chaînes de caractères de longueur variable

L'analyseur de livre de copie natif est compatible avec les champs struct suivants :

  • 10 vars
  • 15 var-LEN PIC 9(4) USAGE COMP.
  • 15 var-TEXT PIC X(n)

Le premier champ du champ struct correspond à la durée du second , le champ de chaîne. Vous devrez peut-être ajouter une marge intérieure à la fin en fonction de sa longueur, comme illustré dans la figure suivante.

Marge intérieure ajoutée aux chaînes de caractères de longueur variable.
Figure 1. Marge intérieure ajoutée aux chaînes de caractères de longueur variable.

Mainframe Connector supprime le suffixe du nom de la variable avant d'enregistrer les données dans BigQuery. Dans cet exemple, le nom de la variable sera var.

Pour utiliser des champs struct, définissez la variable d'environnement BQSH_FEATURE_VARIABLE_LENGTH_ENABLED sur yes ou true.

Lorsque vous utilisez des champs struct, assurez-vous de respecter les points suivants :

  • Le suffixe du premier paramètre dans struct est -LEN. Si vous souhaitez utiliser un suffixe différent, vous devez définir la variable d'environnement BQSH_FEATURE_VARIABLE_LENGTH_LEN_SUFFIX sur le suffixe que vous souhaitez utiliser.
  • Le suffixe du deuxième paramètre dans struct est -TEXT. Si vous souhaitez utiliser un autre suffixe, vous devez définir le variable d'environnement BQSH_FEATURE_VARIABLE_LENGTH_LEN_SUFFIX pour le suffixe que vous souhaitez utiliser.

Champs et constructions non compatibles

Les sections suivantes décrivent les champs et les constructions qui ne sont pas compatibles avec le

Constructions COBOL

constructions COBOL, même si elles ne sont pas compatibles. Si vous utilisez ces dans votre cahier des charges, le connecteur mainframe affiche une erreur.

  • dataAlignedClause
  • dataBlankWhenZeroClause
  • dataCommonOwnLocalClause
  • dataIntegerStringClause
  • dataJustifiedClause
  • dataOccursClause
  • dataReceivedByClause
  • dataRecordAreaClause
  • dataRenamesClause
  • dataSignClause
  • dataSynchronizedClause
  • dataThreadLocalClause
  • dataTypeClause
  • dataTypeDefClause
  • dataUsingClause

Types de données

Les types de données COBOL tels que COMP-1 et COMP-2 sont compatibles.

Analyseur de l'ancien carnet

Il s'agit d'une ancienne version de l'analyseur compatible et non-COBOL. Si vous utilisez un carnet de commandes basé sur le DSL, l'ancien analyseur peut être plus adapté, car l'analyseur de carnet de commandes natif peut provoquer des erreurs.

Vous pouvez utiliser le DD de carnet de copie avec les restrictions suivantes :

  • Les niveaux 66 (ALIAS) ou 77 (STANDALONE) ne sont pas acceptés.
  • Les REDEFINES ne sont pas acceptés.
  • Les lignes de commentaires ne sont pas acceptées.
  • Les champs de longueur 10 dont le nom se termine par DATE ou DT sont des dates. Le décodage est différent pour ces champs.
  • N'utilisez que les champs COMP suivants. ALIGN et OCCURS ne sont pas pris en charge.
    • COMP
    • COMP4
    • BINARY
    • COMP3
    • PACKED-DECIMAL
  • N'utilisez que des champs PICTURE. Définissez les champs PICTURE sur la même ligne, directement après le nom du champ.
  • Vous devez justifier tous les champs et utiliser un seul niveau. Les commentaires ne sont pas acceptés.
  • Assurez-vous que les colonnes 1 à 6 contiennent toujours des espaces vides.