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

Le connecteur Mainframe utilise un analyseur basé sur ANTLR4 qui accepte les copybooks COBOL standards.

Ce document liste les tâches de prétraitement effectuées par l'analyseur de copybook, les types de données compatibles et les restrictions d'utilisation, ainsi que la manière de configurer les modificateurs de champ à l'aide de la configuration du transcodeur avec les commandes qsam decode et qsam encode.

Preprocessing

Avant d'analyser un copybook, l'analyseur de copybook prétraite les données et effectue les étapes suivantes :

  • Supprime les lignes de commentaire (* dans la colonne 7, ou les commentaires intégrés *> et *>CE).
  • Résout la continuation de ligne (- dans la colonne 7 suivi d'un littéral entre guillemets).
  • Efface les zones de numéro de séquence (colonnes 1 à 6) et la colonne 73 et au-delà. Le code doit commencer à la colonne 8 ou ultérieure.
  • Conserve les instructions spécifiques au préprocesseur telles que EJECT, SKIP1, SKIP2, SKIP3 et TITLE. Ces instructions sont analysées, mais ignorées. Les copybooks contenant des paramètres de préprocesseur pouvant être utilisés par COPY REPLACING ne sont pas compatibles avec l'analyseur de copybooks. Dans ces copybooks, les identifiants sont entourés de deux-points (:).

Types de données compatibles et restrictions

Voici les types de données compatibles avec l'analyseur de copybook et les restrictions d'utilisation :

  • Un seul enregistrement 01 de premier niveau est autorisé dans un copybook, et l'enregistrement 01 ne peut pas comporter de clause OCCURS.
  • Les champs de niveau 66 (RENAMES/alias) et de niveau 77 (autonome) ne sont pas acceptés. Le niveau 88 (noms des conditions) est analysé et ignoré.
  • Tous les champs élémentaires (hors groupe) doivent comporter une clause PICTURE, à l'exception des champs à virgule flottante hexadécimaux (COMP-1 et COMP-2). Les champs PICTURE suivants sont acceptés :
    • Alphabétique (PIC A), alphanumérique (PIC X) et alphanumérique modifié (A, X, 9, B, 0, /).
    • PIC G (DBCS ; nécessite USAGE DISPLAY-1).
    • PIC N (national ou DBCS) et national-edited (N, B, 0, /).
    • PIC U (UTF-8), y compris PIC U BYTE-LENGTH n.
    • Numérique (9, S, V) et numérique modifié ($, B, /, V, Z, 0, 9, ,, ., *, +, -, CR, DB). Notez que PIC P (position de mise à l'échelle) n'est pas compatible.
    • Les champs décimaux zonés et décimaux condensés avec une précision allant jusqu'à 18 sont décodés en types 64 bits (LONG ou DECIMAL64), et les champs de précision supérieure sont décodés en types de précision arbitraire (BIG_INTEGER ou BIG_DECIMAL). Lorsque schema_validation_mode est défini sur BIG_QUERY, la précision maximale acceptée est de 76 (BIGNUMERIC) et l'échelle maximale est de 38 (pour POSTGRES, la précision maximale est de 147 455 et l'échelle maximale est de 16 383 ; pour MYSQL, la précision maximale est de 65 et l'échelle maximale est de 30).
  • Le format IBM Hexadecimal Floating-Point (HFP) est compatible avec COMP-1 / COMPUTATIONAL-1 (simple précision, 4 octets) et COMP-2 / COMPUTATIONAL-2 (double précision, 8 octets), ou en appliquant le modificateur de champ hfp dans la configuration du transcodeur.
  • Les clauses REDEFINES sont acceptées sur les champs de taille statique lorsque toutes les variantes redéfinies ont la même taille en octets. Les champs redéfinis ne peuvent pas être référencés en tant que champ de longueur d'une clause OCCURS DEPENDING ON ou en tant que target_field d'un modificateur null_if.
  • Les clauses OCCURS sont compatibles avec les tableaux de longueur fixe (OCCURS n TIMES), les tableaux de longueur dynamique (OCCURS min TO max TIMES DEPENDING ON field) et les tableaux de longueur dynamique compressés (OCCURS UNBOUNDED DEPENDING ON field). Les expressions ASCENDING/DESCENDING KEY et INDEXED BY d'une clause OCCURS ne sont pas acceptées, et DEPENDING ON doit faire référence à un nom de champ dans le champ d'application.
  • Seules les clauses USAGE suivantes sont acceptées :
    • DISPLAY (par défaut pour les champs alphanumériques et décimaux zonés)
    • DISPLAY-1 (DBCS)
    • NATIONAL (par défaut pour les champs PIC N ; encodé en tant que UTF-16BE)
    • UTF-8 (par défaut pour les champs PIC U)
    • BINARY, COMP, COMPUTATIONAL, COMP-4, COMPUTATIONAL-4, COMP-5, COMPUTATIONAL-5
    • COMP-3, COMPUTATIONAL-3, PACKED-DECIMAL
    • COMP-1, COMPUTATIONAL-1, COMP-2, COMPUTATIONAL-2
  • DATE et TIMESTAMP sont compatibles avec la configuration du transcodeur.
  • Les indicateurs de valeur nulle sont acceptés à l'aide de la configuration du transcodeur.
  • Les champs PIC G et PIC N du jeu de caractères codés sur deux octets (DBCS) sont acceptés. Par défaut, les champs PIC N sans clause USAGE se voient attribuer USAGE NATIONAL (UTF-16BE). Pour utiliser un champ PIC N en tant que DBCS, spécifiez USAGE DISPLAY-1 dans le copybook ou remplacez son encodage de caractères dans la configuration du transcodeur.
  • Les chaînes de caractères de longueur variable sont acceptées à l'aide de la configuration du transcodeur.
  • La clause SIGN (LEADING, TRAILING, SEPARATE CHARACTER) est acceptée.
  • Les commentaires sont acceptés.

Compatibilité avec les champs de date et de code temporel

Le connecteur Mainframe permet de décoder et d'encoder les champs de date et d'horodatage à l'aide des modificateurs de champ format_date et format_timestamp dans la configuration du transcodeur (--transcode-configuration). Vous pouvez appliquer ces modificateurs aux champs correspondants à l'aide de field_suffixes ou à des champs spécifiques à l'aide de field_overrides :

{
  "field_suffixes": [
    {
      "suffix": "SUFFIX_STRING",
      "modifier": {
        "format_date": {
          "formats": [
            {
              "size": FIELD_SIZE,
              "pattern": "FORMAT_PATTERN"
            }
          ]
        }
      }
    }
  ]
}

La liste suivante décrit plus en détail les propriétés de configuration :

  • suffix : correspond à tout champ de copybook dont le nom se termine par -SUFFIX_STRING ou _SUFFIX_STRING (non sensible à la casse). Assurez-vous que suffix ne commence pas par un trait d'union ou un trait de soulignement. Vous pouvez également utiliser field_overrides avec "field": "FIELD_NAME" pour cibler un champ individuel.
  • format_date / format_timestamp : définit le modificateur utilisé pour analyser ou formater le champ :
    • format_date peut être appliqué aux champs de chaîne dimensionnés (PIC X) ou aux champs numériques entiers (tels que PIC 9(n), COMP ou COMP-3 avec une échelle de 0 et une précision allant jusqu'à 18, qui sont convertis de manière dynamique en leur représentation de chaîne non signée avant le formatage).
    • format_timestamp peut être appliqué aux champs de chaîne dimensionnés (PIC X). Les codes temporels sont interprétés au format UTC, sauf si un fuseau horaire ou un décalage est inclus dans le modèle.
  • formats : liste d'objets DateTimeFormat, chacun spécifiant :
    • size : taille du champ auquel le modèle s'applique (longueur en octets pour les champs de chaîne ou précision pour les champs numériques).
    • pattern : un format de date ou d'horodatage. Lors du décodage (qsam decode), les formats correspondant à la taille du champ sont évalués dans l'ordre jusqu'à ce qu'un format corresponde. Lors de l'encodage (qsam encode), seul le premier format correspondant à la taille du champ est utilisé. Pour en savoir plus sur les formats valides, consultez Formats de date et d'horodatage acceptés.
  • Supprimer les suffixes (facultatif) : pour supprimer -SUFFIX_STRING ou _SUFFIX_STRING du nom du champ de sortie, ajoutez une transformation rename au tableau transformations dans votre configuration de transcodeur.

Exemples

  • Pour formater des champs de 8 octets se terminant par -DT8 ou _DT8 en tant que DATE avec le modèle yyyyMMdd, et des champs de 10 octets se terminant par -DT ou _DT avec MM-dd-yyyy ou MM/dd/yyyy :

    {
  "field_suffixes": [
    {
      "suffix": "DT8",
      "modifier": {
        "format_date": {
          "formats": [
            {
              "size": 8,
              "pattern": "yyyyMMdd"
            }
          ]
        }
      }
    },
    {
      "suffix": "DT",
      "modifier": {
        "format_date": {
          "formats": [
            {
              "size": 10,
              "pattern": "MM-dd-yyyy"
            },
            {
              "size": 10,
              "pattern": "MM/dd/yyyy"
            }
          ]
        }
      }
    }
  ]
}

  • Pour formater les champs de 26 octets se terminant par -TIMESTAMP, _TIMESTAMP, -TS ou _TS en tant que TIMESTAMP avec le format yyyy-MM-dd HH.mm.ss.SSSSSS et supprimer le suffixe des noms de colonnes de sortie :

    {
  "field_suffixes": [
    {
      "suffix": "TIMESTAMP",
      "modifier": {
        "format_timestamp": {
          "formats": [
            {
              "size": 26,
              "pattern": "yyyy-MM-dd HH.mm.ss.SSSSSS"
            }
          ]
        }
      }
    },
    {
      "suffix": "TS",
      "modifier": {
        "format_timestamp": {
          "formats": [
            {
              "size": 26,
              "pattern": "yyyy-MM-dd HH.mm.ss.SSSSSS"
            }
          ]
        }
      }
    }
  ],
  "transformations": [
    {
      "rename": {
        "find": "^(.*)[-_](TIMESTAMP|TS)$",
        "replace": "$1"
      }
    }
  ]
}

Compatibilité avec les indicateurs nuls

Mainframe Connector accepte les indicateurs de valeur nulle via le modificateur de champ null_if dans la configuration du transcodeur (--transcode-configuration).

Pour configurer un indicateur de valeur nulle basé sur un suffixe (où un champ tel que COL1-NID sert d'indicateur de valeur nulle pour COL1 dans le même enregistrement), définissez une entrée dans field_suffixes avec "is_inverse": true et "target_field": "$self" :

{
  "field_suffixes": [
    {
      "suffix": "NULL_INDICATOR_NAME",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "NULL_VALUE",
          "non_null_value": "NOT_NULL_VALUE"
        }
      }
    }
  ]
}

La liste suivante décrit les paramètres que vous pouvez utiliser pour configurer les indicateurs de valeur nulle :

  • suffix : correspond aux suffixes -NULL_INDICATORNAME ou NULL_INDICATOR_NAME qui identifient un champ d'indicateur de valeur nulle dans un copybook.
  • is_inverse : lorsqu'il est défini sur true sur un FieldSuffix, le modificateur est appliqué au champ frère dont le nom correspond au champ d'indicateur sans le suffixe (par exemple, COL1 lorsque l'indicateur est COL1-NID1), et "$self" fait référence au champ d'indicateur lui-même. Vous pouvez également appliquer null_if directement à un champ spécifique à l'aide de field_overrides et définir target_field sur le nom du champ d'indicateur.
  • null_value ou null_values : spécifie la valeur unique (null_value) ou la liste de valeurs (null_values) dans target_field qui indiquent que le champ référencé est null.
  • non_null_value ou non_null_values : (facultatif) spécifie la valeur unique (non_null_value) ou la liste de valeurs (non_null_values) dans target_field pour signaler que le champ référencé n'est pas null. Si ce paramètre est omis, toute valeur autre que null_value ou null_values est traitée comme non nulle. Vous devez spécifier au moins null_value(s) ou non_null_value(s).
  • Exclure ou conserver le champ d'indicateur de valeur nulle : par défaut, le champ d'indicateur de valeur nulle est conservé en tant que colonne dans le schéma de sortie. Pour omettre le champ d'indicateur de valeur nulle de la table de sortie tout en l'utilisant pendant le transcodage, ajoutez une transformation exclude pour le champ d'indicateur dans le tableau transformations (n'appliquez pas le modificateur filler à un champ d'indicateur de valeur nulle, car filler ignore complètement le décodage du champ).
  • Remplacer le type de champ d'indicateur : (facultatif) Pour forcer le décodage d'un champ d'indicateur de valeur nulle en tant que bytes ou binary, ajoutez une règle field_suffixes (ou field_overrides) non inverse pour le champ d'indicateur avec "modifier": { "bytes": {} } ou "modifier": { "binary": {} }. Pour bytes, exprimez les valeurs null_value et non_null_value sous forme de chaînes hexadécimales (par exemple, "FF" ou "00").

Exemples

Dans les exemples suivants, COL1-NID1 et FIELD-NID2 sont exclus de la table de sortie après avoir été évalués comme des indicateurs de valeur nulle, tandis que COL2-NULL est conservé dans le schéma de sortie.

Extrait de copybook :

01 REC.
   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).

Configuration du transcodeur (transcode-configuration.json) :

{
  "field_suffixes": [
    {
      "suffix": "NID1",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "-1",
          "non_null_value": "0"
        }
      }
    },
    {
      "suffix": "NID2",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "?"
        }
      }
    },
    {
      "suffix": "NULL",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "?"
        }
      }
    }
  ],
  "transformations": [
    {
      "exclude": {
        "field": "COL1-NID1"
      }
    },
    {
      "exclude": {
        "field": "FIELD-NID2"
      }
    }
  ]
}

Compatibilité avec les champs DBCS

Lorsque vous utilisez des champs DBCS (PIC G ou PIC N avec USAGE DISPLAY-1), assurez-vous de respecter les points suivants :

  • Les champs PIC G doivent spécifier explicitement USAGE DISPLAY-1.
  • Les champs PIC N sans clause USAGE sont définis par défaut sur USAGE NATIONAL (UTF-16BE). Pour traiter un champ PIC N en tant que champ DBCS, spécifiez USAGE DISPLAY-1 dans le copybook (ou remplacez son encodage dans la configuration du transcodeur).
  • Par défaut, les champs USAGE DISPLAY-1 sont décodés et encodés à l'aide du jeu de caractères DBCS cp300 (x-IBM300), qui attend des octets DBCS bruts sans caractères de contrôle de décalage (0x0E) et de décalage (0x0F).
  • Pour utiliser un autre jeu de caractères DBCS (tel que Cp834) ou un jeu de caractères multi-octets (MBCS) qui utilise des octets de décalage (0x0E) et de décalage (0x0F) (tels que x-IBM930, x-IBM933, x-IBM935, x-IBM937, x-IBM939, x-IBM942, x-IBM942C, x-IBM943, x-IBM943C, x-IBM949, x-IBM949C, x-IBM950, x-IBM964, x-IBM970 ou x-IBM1364), configurez le modificateur de champ string dans la configuration du transcodeur (--transcode-configuration).

Vous pouvez définir l'encodage DBCS de manière globale pour tous les champs USAGE DISPLAY-1 à l'aide de defaults.dbcs, ou pour des champs spécifiques à l'aide de field_overrides ou field_suffixes :

{
  "defaults": {
    "dbcs": {
      "string": {
        "encoding": "x-IBM930"
      }
    }
  }
}

Prise en charge des chaînes de caractères de longueur variable

L'analyseur de copybook accepte les champs de groupe de chaînes de caractères de longueur variable à l'aide du modificateur de champ varlen dans la configuration du transcodeur :

10 VAR-GRP.
   15 VAR-LEN  PIC 9(4) USAGE COMP.
   15 VAR-TEXT PIC X(50).

Lorsque vous utilisez le modificateur de champ varlen, assurez-vous de respecter les points suivants :

  • Appliquez le modificateur varlen à l'élément de groupe (par exemple, VAR-GRP) à l'aide de field_overrides ou field_suffixes dans la configuration du transcodeur :

    {
  "field_overrides": [
    {
      "field": "VAR-GRP",
      "modifier": {
        "varlen": {}
      }
    }
  ]
}

  • L'élément de groupe doit contenir exactement deux sous-champs :

    1. Le premier sous-champ doit être décodé en un entier de 64 bits (LONG, tel qu'un champ d'entier décimal binaire COMP ou zoné) qui spécifie la longueur en octets des données de chaîne.
    2. Le deuxième sous-champ doit être un champ de chaîne non modifié (tel que PIC X(n), PIC N(n) ou PIC U(n)).

  • Aucun suffixe de sous-champ spécifique (tel que -LEN ou -TEXT) n'est requis, et la colonne obtenue dans le schéma de sortie utilise le nom de l'élément de groupe (VAR-GRP).

Champs et constructions non compatibles

Les sections suivantes décrivent les champs et les constructions qui ne sont pas compatibles avec l'analyseur de copybook.

Constructions COBOL non compatibles

L'analyseur de copybook peut analyser les constructions COBOL suivantes, même si elles ne sont pas compatibles. Si vous utilisez ces constructions dans votre copybook, Mainframe Connector affiche une erreur :

  • ALIGNED
  • BLANK WHEN ZERO
  • COMMON, OWN, LOCAL
  • DYNAMIC LENGTH (par exemple, PIC X DYNAMIC LENGTH ou PIC U DYNAMIC LENGTH LIMIT n)
  • INTEGER, STRING
  • JUSTIFIED
  • ASCENDING/DESCENDING KEY dans la zone géographique OCCURS
  • INDEXED BY dans la zone géographique OCCURS
  • RECEIVED BY
  • RECORD AREA
  • RENAMES
  • SYNCHRONIZED/SYNC
  • THREAD-LOCAL
  • TYPE IS ...
  • TYPEDEF
  • USING LANGUAGE/CONVENTION

Types de données non compatibles

Les types USAGE suivants peuvent être analysés par la grammaire, mais ne sont pas compatibles avec le compilateur de copybook :

  • BIT
  • CONTROL-POINT
  • DATE
  • DOUBLE
  • EVENT
  • FUNCTION-POINTER
  • INDEX
  • KANJI
  • LOCK
  • POINTER
  • PROCEDURE-POINTER
  • REAL
  • SQL
  • TASK