Referencia del analizador de copybooks

Mainframe Connector admite dos versiones del analizador de copybooks:

Puedes definir el analizador que quieras usar en función de tu copybook. Para obtener más información sobre cómo definir el analizador que quieras usar, consulta Definir el analizador de copybook.

Analizador de copybooks nativo

El analizador de copybooks nativo es la versión más reciente del analizador y se usa de forma predeterminada. El analizador nativo de copybooks implementa un analizador basado en ANTLR4 y admite copybooks de COBOL.

En esta sección se enumeran las tareas de preprocesamiento que realiza el analizador de copybooks nativo. También se indican los tipos de datos que admite el analizador de copybooks nativo y las restricciones de uso.

Preprocesamiento

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

  • Elimina las líneas de comentarios.
  • Resuelve la continuación de líneas.
  • Oscurece las áreas de los números de línea y las áreas de la columna 73.
  • Conserva las instrucciones específicas del preprocesador, como EJECT, SPACE y TITLE. Estos campos se analizan, pero se ignoran. El analizador de copybooks nativo 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

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

  • No se admiten los niveles 66 (ALIAS) ni 77 (STANDALONE).
  • Usa solo campos PICTURE. Se admiten los siguientes campos PICTURE:
    • Pic A, Pic, B, Pic G (DBCS), Pic N (nacional o DBCS), Pic U (UTF8), Pic X, y decimal zonificado (precisión máxima 38, escala máxima 38)
  • Se admite el formato de coma flotante hexadecimal de IBM (HFP).
  • No se admiten las REDEFINES.
  • Usa solo los siguientes campos COMP. No se admiten ALIGN ni OCCURS.
    • COMP
    • COMP4
    • BINARIO
    • COMP3
    • PACKED-DECIMAL
  • Se admiten DATE y TIMESTAMP.
  • Se admiten indicadores nulos.
  • Los campos juego de caracteres de doble byte (DBCS) Pic G y Pic N se admiten y deben usarse en lugar de Pic T, que ahora está obsoleto. Para usar el campo Pic N como DBCS sin especificar USAGE DISPLAY-1, debes asignar el valor DBCS a la variable de entorno NSYMBOL. De forma predeterminada, NSYMBOL se define como NATIONAL, lo que asigna a USAGE NATIONAL los campos Pic N que no tienen una cláusula USAGE. Ten en cuenta que NSYMBOL solo puede tener el valor NATIONAL o DBCS.
  • Se admiten cadenas de caracteres de longitud variable.
  • Se admite la cláusula SIGN.
  • Debe justificar todos los campos y usar un solo nivel de sangría.
  • Se admiten comentarios.

Compatibilidad con campos de fecha y hora

Mainframe Connector permite transferir datos de fecha y de marca de tiempo a BigQuery y desde BigQuery. Para ello, debes definir variables de entorno que empiecen por la palabra SUFFIX con el siguiente formato:

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

En la siguiente lista se describe el formato con más detalle:

  • SUFFIX_SUFFIX_STRING: variable de entorno que puedes usar para definir datos de fecha y marca de tiempo. El nombre SUFFIX_STRING corresponde a los sufijos -SUFFIX_STRING o _SUFFIX_STRING, que deben interpretarse como una fecha o una marca de tiempo cuando se usan como sufijo de un nombre de campo en un copybook. Asegúrate de que SUFFIX_STRING no contenga un guion o un guion bajo.
  • command: define el decodificador que se debe usar para analizar el campo. Los comandos admitidos son date-converter y timestamp-converter.
  • --format: parámetro que define el formato de la fecha o la marca de tiempo. Puedes especificar un máximo de cinco formatos diferentes separados por comas. Si varios formatos coinciden con una entrada determinada, se usará el primero que coincida para cargar los datos en BigQuery. Si se especifican varios formatos para la exportación, solo se usará el primero. Para obtener más información sobre los formatos válidos, consulta Formatos de fecha y de marca de tiempo admitidos.
  • --timezone: parámetro opcional del tipo TIMESTAMP. De forma predeterminada, la zona horaria es UTC. Para obtener más información sobre los formatos de zona horaria admitidos, consulta Formatos de zona horaria admitidos.
  • --omitsuffix (Opcional): Si se especifica este parámetro, se elimina -SUFFIX_STRING o _SUFFIX_STRING del nombre del campo que aparece en BigQuery.

Para añadir un alias a un SUFFIX_SUFFIX_STRING, puedes definir una variable de entorno SUFFIX_SUFFIX_ALIAS=$SUFFIX_SUFFIX_STRING.

Ejemplos:

  • Si defines una variable de entorno como SUFFIX_DT8="date-converter --format yyyyMMdd", un campo con el sufijo -DT8 o _DT8 será un campo de tipo DATE en BigQuery y su patrón será yyyyMMdd.
  • Si defines una variable de entorno como SUFFIX_DT10="date-converter --format MM-dd-yyyy", un campo con el sufijo -DT10 o _DT10 será un campo de tipo DATE en BigQuery y su patrón será MM-dd-yyyy.
  • Si defines una variable de entorno como SUFFIX_DT="date-converter --format 'MM-dd-yyyy,MM/dd/yyyy'", un campo con el sufijo -DT o _DT será un campo de tipo DATE en BigQuery y su patrón será MM-dd-yyyy o MM/dd/yyyy.
  • Si defines dos variables de entorno como SUFFIX_TIMESTAMP="timestamp-converter --format yyyy-MM-dd SUFFIX_TIMESTAMP=timestamp-converter --format 'yyyy-MM-dd HH.mm.ss.SSSSSS' --timezone America/New_York" y SUFFIX_TS=$SUFFIX_TIMESTAMP, un campo con uno de los siguientes sufijos: -TIMESTAMP, _TIMESTAMP, -TS o _TS será un campo de tipo TIMESTAMP en BigQuery y su patrón será yyyy-MM-dd HH:mm:ss.SSSSSS con la zona horaria America/New_York.

Compatibilidad con indicadores nulos

Mainframe Connector admite indicadores nulos a partir de la versión 5.13.0. Para usar indicadores nulos, debe definir variables de entorno que empiecen por la palabra SUFFIX con el siguiente formato:

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

NULL_INDICATOR_NAME corresponde a los sufijos -NULL_INDICATOR_NAME o _NULL_INDICATOR_NAME, que se interpretan como un indicador nulo cuando se usan como sufijo de un nombre de campo en un copybook.

En la siguiente lista se describen los parámetros que puede usar con estas variables de entorno:

  • command: el valor debe ser null-indicator.
  • –null-value: el valor null indicator indica que el campo de referencia es nulo. El valor de --null-value debe ser una cadena o un número decimal.
  • –not-null-value: (opcional) Cuando se especifica, el valor null indicator indica que el campo al que se hace referencia no es nulo. Si no se define este parámetro, se aceptará cualquier valor que no sea –value-null. El valor de –not-null-value debe ser una cadena o un número decimal.
  • –keep: (Opcional) Si se especifica, el campo null-indicator se conserva como columna en el formato de archivo ORC (Optimized Row Columnar). De forma predeterminada, este campo no se conserva en el formato ORC.
  • -force-type: (opcional) admite dos opciones: bytes y binary, que obligan a decodificar un campo como bytes o binario, respectivamente. En el caso de los bytes, los valores de null y not-null se expresan como HEX (por ejemplo, FA3AB5). Están disponibles las constantes HIGH y LOW, que equivalen a todos los FF o todos los 00. En el caso de los valores binarios, se trata de números enteros normales.

Si null-indicator no tiene ningún campo de referencia, Mainframe Connector muestra un mensaje de error y deja de procesar los archivos.

Ejemplos:

Fragmento de cuaderno de copias

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

Definición de variables de entorno

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.

Compatibilidad con campos DBCS

Asegúrate de que se cumplen los siguientes requisitos al usar campos DBCS:

  • Cuando usas los campos PIC G o PIC N DBCS, debes proporcionar una de las siguientes codificaciones válidas de conjunto de caracteres multibyte (MBCS) en la opción encoding o en la variable de entorno ENCODING al usar los comandos gsutil cp o 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-IBM950
    • x-IBM964
    • x-IBM970
    • x-IBM1364
  • Cuando un campo de copybook solo contiene bytes DBCS, pero estos bytes no están rodeados por shift-out (0x0E) y shift-in (0x0F), debe añadir el sufijo _DBCS al nombre del campo para asegurarse de que estos bytes se decodifiquen como bytes DBCS.

Por ejemplo, si los datos correspondientes al campo de copybook 03 FLD01 PIC N USAGE DISPLAY-1 contienen los bytes 0x43 y 0xC5 en la codificación x-IBM930 que no están rodeados por 0x0E y 0x0F, debe cambiar el nombre del campo de copybook a 03 FLD01-DBCS PIC N USAGE DISPLAY-1 para decodificar correctamente los datos DBCS.

Compatibilidad con cadenas de caracteres de longitud variable

El analizador de copybooks nativo admite los siguientes campos struct:

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

El primer campo del campo struct es la longitud del segundo campo, el campo de cadena. Es posible que tengas que añadir un relleno al final del registro en función de su longitud, como se muestra en la siguiente figura.

Se ha añadido relleno a las cadenas de caracteres de longitud variable.
Imagen 1. Se ha añadido relleno a las cadenas de caracteres de longitud variable.

Mainframe Connector elimina el sufijo del nombre de la variable antes de guardar los datos en BigQuery. En este ejemplo, el nombre de la variable será var.

Para usar los campos struct, define la variable de entorno BQSH_FEATURE_VARIABLE_LENGTH_ENABLED como yes o true.

Cuando use los campos struct, asegúrese de que se cumplan los siguientes requisitos:

  • El sufijo del primer parámetro de struct es -LEN. Si quieres usar otro sufijo, debes definir la variable de entorno BQSH_FEATURE_VARIABLE_LENGTH_LEN_SUFFIX con el sufijo que quieras usar.
  • El sufijo del segundo parámetro de struct es -TEXT. Si quieres usar otro sufijo, debes definir la variable de entorno BQSH_FEATURE_VARIABLE_LENGTH_DATA_SUFFIX con el sufijo que quieras usar.

Campos y estructuras no admitidos

En las siguientes secciones se describen los campos y las estructuras que no admite el

Construcciones de COBOL

Construcciones de COBOL, aunque no sean compatibles. Si usas estas construcciones en tu copybook, Mainframe Connector mostrará un error.

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

Tipos de datos

Se admiten tipos de datos de COBOL, como COMP-1 y COMP-2.

Analizador de copybooks antiguo

El analizador de copybooks antiguo es una versión anterior del analizador que admite funciones que no son de COBOL. Si utilizas un libro de copias basado en DSL, puede que el analizador antiguo sea más adecuado, ya que el analizador de libros de copias nativo puede provocar errores.

Puedes usar el DDL de copybook con las siguientes restricciones:

  • No se admiten los niveles 66 (ALIAS) ni 77 (STANDALONE).
  • No se admiten las REDEFINES.
  • No se admiten líneas de comentarios.
  • Los campos de longitud 10 cuyo nombre termina en DATE o DT son fechas. La decodificación es diferente para esos campos.
  • Usa solo los siguientes campos COMP. No se admiten ALIGN ni OCCURS.
    • COMP
    • COMP4
    • BINARIO
    • COMP3
    • PACKED-DECIMAL
  • Usa solo campos PICTURE. Define los campos PICTURE en la misma línea, directamente después del nombre del campo.
  • Debe justificar todos los campos y usar un solo nivel. No se admiten comentarios.
  • Asegúrate de que las columnas de la 1 a la 6 siempre contengan espacios en blanco.