Referencia del analizador de copybooks

Mainframe Connector usa un analizador basado en ANTLR4 que admite copybooks de COBOL estándar.

En este documento, se enumeran las tareas de procesamiento previo que realiza el analizador de copybooks, los tipos de datos admitidos y las restricciones de uso, y cómo configurar los modificadores de campos con la configuración del transcodificador con los comandos qsam decode y qsam encode.

Procesamiento previo:

Antes de analizar un copybook, el analizador de copybooks preprocesa los datos y realiza los siguientes pasos:

  • Quita las líneas de comentarios (* en la columna 7 o comentarios intercalados *> y *>CE).
  • Resuelve la continuación de línea (- en la columna 7 seguida de un literal entre comillas).
  • Borra las áreas de números de secuencia (columnas 1 a 6) y la columna 73 y posteriores. El código debe comenzar en la columna 8 o una posterior.
  • Conserva las declaraciones específicas del preprocesador, como EJECT, SKIP1, SKIP2, SKIP3 y TITLE. Estas declaraciones se analizan, pero se ignoran. El analizador de copybooks no admite los copybooks que contienen parámetros de preprocesador que puede usar COPY REPLACING. En estos copybooks, los identificadores están rodeados por dos puntos (:).

Tipos de datos admitidos y restricciones

Los siguientes son los tipos de datos que admite el analizador de copybooks y las restricciones para su uso:

  • Solo se permite un único registro 01 de nivel superior en un copybook, y el registro 01 no puede tener una cláusula OCCURS.
  • No se admiten los campos de nivel 66 (RENAMES o alias) ni de nivel 77 (independiente). El nivel 88 (nombres de condiciones) se analiza y se ignora.
  • Todos los campos elementales (que no son de grupo) deben tener una cláusula PICTURE, excepto los campos de punto flotante hexadecimales (COMP-1 y COMP-2). Se admiten los siguientes campos PICTURE:
    • Alfabético (PIC A), alfanumérico (PIC X) y alfanumérico editado (A, X, 9, B, 0, /).
    • PIC G (DBCS; requiere USAGE DISPLAY-1).
    • PIC N (nacional o DBCS) y editado nacional (N, B, 0, /).
    • PIC U (UTF-8), incluido PIC U BYTE-LENGTH n.
    • Numérico (9, S, V) y editado numérico ($, B, /, V, Z, 0, 9, ,, ., *, +, -, CR, DB). Ten en cuenta que no se admite PIC P (posición de escalamiento).
    • Los campos decimales con zona y decimales empaquetados con precisión de hasta 18 se decodifican en tipos de 64 bits (LONG o DECIMAL64), y los campos de mayor precisión se decodifican en tipos de precisión arbitraria (BIG_INTEGER o BIG_DECIMAL). Cuando schema_validation_mode se establece en BIG_QUERY, la precisión máxima admitida es 76 (BIGNUMERIC) y la escala máxima es 38 (para POSTGRES, la precisión máxima es 147,455 y la escala máxima es 16,383; para MYSQL, la precisión máxima es 65 y la escala máxima es 30).
  • El punto flotante hexadecimal (HFP) de IBM se admite con COMP-1/COMPUTATIONAL-1 (precisión simple, 4 bytes) y COMP-2/COMPUTATIONAL-2 (precisión doble, 8 bytes), o aplicando el modificador de campo hfp en la configuración del transcodificador.
  • Las cláusulas REDEFINES se admiten en campos de tamaño estático cuando todas las variantes redefinidas tienen el mismo tamaño de bytes. No se puede hacer referencia a los campos redefinidos como el campo de longitud de una cláusula OCCURS DEPENDING ON ni como el target_field de un modificador null_if.
  • Las cláusulas OCCURS son compatibles con los arrays de longitud fija (OCCURS n TIMES), los arrays de longitud dinámica (OCCURS min TO max TIMES DEPENDING ON field) y los arrays de longitud dinámica empaquetados (OCCURS UNBOUNDED DEPENDING ON field). Las frases ASCENDING/DESCENDING KEY y INDEXED BY en una cláusula OCCURS no son compatibles, y DEPENDING ON debe hacer referencia a un nombre de campo en el alcance.
  • Solo se admiten las siguientes cláusulas USAGE:
    • DISPLAY (predeterminado para campos alfanuméricos y decimales con zona)
    • DISPLAY-1 (DBCS)
    • NATIONAL (predeterminado para los campos PIC N; codificado como UTF-16BE)
    • UTF-8 (predeterminado para los campos 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 y TIMESTAMP se admiten con la configuración del transcodificador.
  • Los indicadores nulos se admiten con la configuración del transcodificador.
  • Se admiten los campos PIC G y PIC N del conjunto de grupo de caracteres de doble byte (DBCS). De forma predeterminada, a los campos PIC N sin una cláusula USAGE se les asigna USAGE NATIONAL (UTF-16BE). Para usar un campo PIC N como DBCS, especifica USAGE DISPLAY-1 en el copybook o anula su codificación de caracteres en la configuración del transcodificador.
  • Las cadenas de caracteres de longitud variable se admiten con la configuración del transcodificador.
  • Se admite la cláusula SIGN (LEADING, TRAILING, SEPARATE CHARACTER).
  • Se admiten comentarios.

Compatibilidad con campos de fecha y marca de tiempo

Mainframe Connector admite la decodificación y codificación de campos de fecha y marca de tiempo con los modificadores de campo format_date y format_timestamp en la configuración del transcodificador (--transcode-configuration). Puedes aplicar estos modificadores en los campos coincidentes con field_suffixes o en campos específicos con field_overrides:

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

En la siguiente lista, se describen las propiedades de configuración con más detalle:

  • suffix: Coincide con cualquier campo de copybook cuyo nombre termine con -SUFFIX_STRING o _SUFFIX_STRING (no distingue mayúsculas de minúsculas). Asegúrate de que suffix no contenga un guion ni un guion bajo iniciales. Como alternativa, usa field_overrides con "field": "FIELD_NAME" para orientar un campo individual.
  • format_date / format_timestamp: Define el modificador que se usa para analizar o dar formato al campo:
    • format_date se puede aplicar a campos de cadena con tamaño (PIC X) o campos numéricos enteros (como PIC 9(n), COMP o COMP-3 con escala 0 y precisión de hasta 18, que se convierten de forma dinámica en su representación de cadena sin firma antes de darles formato).
    • format_timestamp se puede aplicar a campos de cadena con tamaño (PIC X). Las marcas de tiempo se interpretan en UTC, a menos que se incluya una zona horaria o un desplazamiento en el patrón.
  • formats: Es una lista de objetos DateTimeFormat, cada uno de los cuales especifica lo siguiente:
    • size: Es el tamaño del campo al que se aplica el patrón (longitud en bytes para los campos de cadena o precisión para los campos numéricos).
    • pattern: Es un patrón de fecha o marca de tiempo. Durante la decodificación (qsam decode), los formatos que coinciden con el tamaño del campo se evalúan en orden hasta que uno coincida. Durante la codificación (qsam encode), solo se usa el primer formato coincidente para el tamaño del campo. Para obtener más información sobre los formatos válidos, consulta Formatos de fecha y marca de tiempo compatibles.
  • Quita sufijos (opcional): Para quitar -SUFFIX_STRING o _SUFFIX_STRING del nombre del campo de salida, agrega una transformación rename al array transformations en la configuración del transcodificador.

Ejemplos

  • Para dar formato a los campos de 8 bytes que terminan con -DT8 o _DT8 como DATE con el patrón yyyyMMdd, y los campos de 10 bytes que terminan con -DT o _DT con MM-dd-yyyy o MM/dd/yyyy, haz lo siguiente:

    {
  "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"
            }
          ]
        }
      }
    }
  ]
}

  • Para dar formato a los campos de 26 bytes que terminan con -TIMESTAMP, _TIMESTAMP, -TS o _TS como TIMESTAMP con el patrón yyyy-MM-dd HH.mm.ss.SSSSSS y quitar el sufijo de los nombres de las columnas de salida, haz lo siguiente:

    {
  "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"
      }
    }
  ]
}

Compatibilidad con indicadores nulos

Mainframe Connector admite indicadores nulos a través del modificador de campo null_if en la configuración del transcodificador (--transcode-configuration).

Para configurar un indicador nulo basado en sufijos (en el que un campo como COL1-NID actúa como el indicador nulo para COL1 en el mismo registro), define una entrada en field_suffixes con "is_inverse": true y "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"
        }
      }
    }
  ]
}

En la siguiente lista, se describen los parámetros que puedes usar para configurar los indicadores nulos:

  • suffix: Corresponde a los sufijos -NULL_INDICATORNAME o NULL_INDICATOR_NAME que identifican un campo de indicador nulo en un copybook.
  • is_inverse: Cuando se establece en true en un FieldSuffix, el modificador se aplica al campo hermano cuyo nombre coincide con el campo indicador sin el sufijo (por ejemplo, COL1 cuando el indicador es COL1-NID1), y "$self" se refiere al campo indicador en sí. También puedes aplicar null_if directamente en un campo específico con field_overrides y establecer target_field en el nombre del campo indicador.
  • null_value o null_values: Especifica el valor único (null_value) o la lista de valores (null_values) en target_field que indican que el campo al que se hace referencia es null.
  • non_null_value o non_null_values: (Opcional) Especifica el valor único (non_null_value) o la lista de valores (non_null_values) en target_field para indicar que el campo al que se hace referencia no es null. Si se omite, cualquier valor que no sea null_value o null_values se trata como no nulo. Se debe especificar al menos uno de los valores null_value(s) o non_null_value(s).
  • Excluye o conserva el campo de indicador nulo: De forma predeterminada, el campo de indicador nulo se conserva como una columna en el esquema de salida. Para omitir el campo de indicador nulo de la tabla de salida mientras se usa durante la transcodificación, agrega una transformación exclude para el campo de indicador en el array transformations (no apliques el modificador filler a un campo de indicador nulo, ya que filler omite la decodificación del campo por completo).
  • Anula el tipo de campo de indicador: (Opcional) Para forzar que un campo de indicador nulo se decodifique como bytes o binary, agrega una regla field_suffixes (o field_overrides) no inversa para el campo de indicador con "modifier": { "bytes": {} } o "modifier": { "binary": {} }. Para bytes, expresa null_value y non_null_value como cadenas hexadecimales (por ejemplo, "FF" o "00").

Ejemplos

En los siguientes ejemplos, COL1-NID1 y FIELD-NID2 se excluyen de la tabla de salida después de evaluarse como indicadores nulos, mientras que COL2-NULL se conserva en el esquema de salida.

Fragmento 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).

Configuración del transcodificador (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"
      }
    }
  ]
}

Compatibilidad con campos de DBCS

Cuando uses campos DBCS (PIC G o PIC N con USAGE DISPLAY-1), asegúrate de lo siguiente:

  • Los campos PIC G deben especificar USAGE DISPLAY-1 de forma explícita.
  • Los campos PIC N sin una cláusula USAGE se establecen de forma predeterminada en USAGE NATIONAL (UTF-16BE). Para tratar un campo PIC N como un campo DBCS, especifica USAGE DISPLAY-1 en el copybook (o anula su codificación en la configuración del transcodificador).
  • De forma predeterminada, los campos USAGE DISPLAY-1 se decodifican y codifican con el grupo de caracteres DBCS cp300 (x-IBM300), que espera bytes DBCS sin procesar sin caracteres de control de salida (0x0E) y de entrada (0x0F).
  • Para usar un grupo de caracteres DBCS diferente (como Cp834) o un grupo de caracteres de varios bytes (MBCS) que use bytes de salida (0x0E) y de entrada (0x0F) (como 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 o x-IBM1364), configura el modificador de campo string en la configuración del transcodificador (--transcode-configuration).

Puedes establecer la codificación DBCS de forma global para todos los campos USAGE DISPLAY-1 con defaults.dbcs o para campos específicos con field_overrides o field_suffixes:

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

Compatibilidad con cadenas de caracteres de longitud variable

El analizador de copybook admite campos de grupo de cadenas de caracteres de longitud variable con el modificador de campo varlen en la configuración del transcodificador:

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

Cuando uses el modificador de campo varlen, asegúrate de lo siguiente:

  • Aplica el modificador varlen al elemento del grupo (por ejemplo, VAR-GRP) con field_overrides o field_suffixes en la configuración del Transcoder:

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

  • El elemento de grupo debe contener exactamente dos subcampos:

    1. El primer subcampo debe decodificarse en un número entero de 64 bits (LONG, como un campo de número entero decimal con zona o COMP binario) que especifique la longitud en bytes de los datos de la cadena.
    2. El segundo subcampo debe ser un campo de cadena sin modificar (como PIC X(n), PIC N(n) o PIC U(n)).

  • No se requieren sufijos de subcampo específicos (como -LEN o -TEXT), y la columna resultante en el esquema de salida usa el nombre del elemento del grupo (VAR-GRP).

Campos y construcciones no compatibles

En las siguientes secciones, se describen los campos y las construcciones que no admite el analizador de copybooks.

Construcciones de COBOL no compatibles

El analizador de copybooks puede analizar las siguientes construcciones de COBOL, aunque no se admiten. Si usas estas construcciones en tu copybook, Mainframe Connector muestra un error:

  • ALIGNED
  • BLANK WHEN ZERO
  • COMMON, OWN, LOCAL
  • DYNAMIC LENGTH (como PIC X DYNAMIC LENGTH o PIC U DYNAMIC LENGTH LIMIT n)
  • INTEGER, STRING
  • JUSTIFIED
  • ASCENDING/DESCENDING KEY en OCCURS
  • INDEXED BY en OCCURS
  • RECEIVED BY
  • RECORD AREA
  • RENAMES
  • SYNCHRONIZED/SYNC
  • THREAD-LOCAL
  • TYPE IS ...
  • TYPEDEF
  • USING LANGUAGE/CONVENTION

Tipos de datos no admitidos

La gramática puede analizar los siguientes tipos de USAGE, pero el compilador de copybook no los admite:

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