Referencia del analizador de libros de copia

Mainframe Connector admite dos versiones del analizador de libros de copia:

• Analizador de libros de copia nativos: El analizador de libros de copia nativos implementa un analizador basado en ANTLR4, admite libros de copia de COBOL y es la versión recomendada del analizador.
• Analizador de libros de copia heredados: Es una versión anterior del analizador que admite formatos de libros de copia muy limitados.

Nota: El analizador heredado dejará de estar disponible. Te recomendamos que cambies al analizador de libros de copia nativos.

Puedes definir qué analizador deseas usar en función de tu modelo de texto. Para obtener más información sobre cómo definir el analizador que deseas usar, consulta Define el analizador de libro de copia.

Analizador de libro de copia nativo

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

En esta sección, se enumeran las tareas de preprocesamiento que realiza el analizador de libros de texto nativos. También se describen los tipos de datos que admite el analizador de libros de copia nativos y las restricciones para su uso.

Procesamiento previo:

Antes de analizar un libro de copia, el analizador de libros de copia nativo preprocesa los datos y realiza las siguientes tareas:

• Quita las líneas de comentarios.
• Resuelve la continuación de línea.
• Deja en blanco las áreas de los números de línea y las áreas de la columna 73.
• Conserva instrucciones específicas del preprocesador, como EJECT, SPACE y TITLE. Estos campos se analizan, pero se ignoran. El analizador de libros de copia nativos no admite los libros de copia que contienen parámetros del preprocesador que puede usar COPY REPLACING. En estos libros de texto, los identificadores están rodeados de dos puntos (:).

Tipos de datos admitidos y restricciones

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

• No se admiten los niveles 66 (ALIAS) ni 77 (STANDALONE).
• Usa solo campos de IMAGEN. 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 con zona (precisión máxima 38, escala máxima 38)
• Se admite el punto flotante hexadecimal (HFP) de IBM.
• No se admiten REDEFINES.
• Usa solo los siguientes campos COMP. ALIGN y OCCURS no son compatibles.
  • COMP
  • COMP4
  • BINARY
  • COMP3
  • PACKED-DECIMAL
• Se admiten DATE y TIMESTAMP.
• Se admiten indicadores nulos.
• Los campos Pic G y Pic N del conjunto de grupo de caracteres de doble byte (DBCS) son compatibles y se deben usar en lugar de Pic T, que ahora dejó de estar disponible. Para usar el campo Pic N como DBCS sin especificar USAGE DISPLAY-1, debes configurar la variable de entorno NSYMBOL como DBCS. De forma predeterminada, NSYMBOL se establece en NATIONAL, que establece USAGE NATIONAL en campos Pic N que no tienen una cláusula USAGE. Ten en cuenta que NSYMBOL solo se puede establecer en NATIONAL o DBCS.
• Se admiten cadenas de caracteres de longitud variable.
• Se admite la cláusula SIGN.
• Debes justificar todos los campos y usar un solo nivel de sangría.
• Se admiten comentarios.

Compatibilidad con campos de fecha y marca de tiempo

Mainframe Connector admite el traslado de datos de fecha y marca de tiempo dentro y fuera de BigQuery. Para ello, debes definir variables de entorno que comiencen con la palabra SUFFIX en 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: Es la 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 se deben interpretar como una fecha o una marca de tiempo cuando se usan como sufijo de un nombre de campo en un libro de copia. Asegúrate de que SUFFIX_STRING no contenga un guion ni 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: Es un parámetro que define el formato de la fecha o la marca de tiempo. Puedes especificar hasta cinco formatos diferentes separados por comas. Si varios formatos pueden coincidir con una entrada determinada, se usa el primero que coincida para cargarlo en BigQuery. Si se especifican varios formatos para la exportación, solo se usa el primero. Para obtener más información sobre los formatos válidos, consulta Formatos de fecha y marca de tiempo compatibles.
• --timezone: Es un parámetro opcional para el tipo TIMESTAMP. De forma predeterminada, la zona horaria es UTC. Para obtener más información sobre los formatos de zona horaria compatibles, consulta Formatos de zona horaria compatibles.
• --omitsuffix (opcional): Si se especifica este parámetro, se quita -SUFFIX_STRING o _SUFFIX_STRING del nombre del campo que aparece en BigQuery.

Para agregar un alias para un SUFFIX_SUFFIX_STRING, puedes configurar 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, debes definir variables de entorno que comiencen con la palabra SUFFIX en 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 libro de copia.

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

• command: El valor debe ser null-indicator.
• –null-value: El valor null indicator indica que el campo al que se hace 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 establece este parámetro, se acepta cualquier valor que no sea –value-null. El valor de –not-null-value debe ser una cadena o un número decimal.
• –keep: Opcional. Cuando se especifica, el campo null-indicator se mantiene como una columna en el formato de archivo Optimized Row Columnar (ORC). De forma predeterminada, este campo no se mantiene en el formato ORC.
• -force-type: (Opcional) Admite dos opciones: bytes y binary, que obligan a que un campo se decodifique 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). Hay constantes HIGH y LOW disponibles que son equivalentes a todas las FF o todas las 00. Para el formato binario, los valores son números enteros normales.

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

Ejemplos:

Fragmento de libro de texto

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 las 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 de DBCS

Asegúrate de lo siguiente cuando uses campos de DBCS:

• Cuando usas campos de DBCS de PIC G o Pic N, debes proporcionar una de las siguientes codificaciones válidas de grupo de caracteres de varios bytes (MBCS) en la opción encoding o en la variable de entorno ENCODING cuando usas 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 libro de copia solo contiene bytes de DBCS, pero estos bytes no están rodeados de desplazamiento hacia la izquierda (0x0E) y desplazamiento hacia la derecha (0x0F), debes agregar el sufijo _DBCS al nombre del campo para asegurarte de que estos bytes se decodifiquen como bytes de DBCS.

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

Compatibilidad con cadenas de caracteres de longitud variable

El analizador de libros de copia nativos admite los siguientes campos struct:

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

El primer campo en el campo struct es la longitud del segundo campo, el campo de cadena. Es posible que debas agregar padding al final del registro según su longitud, como se muestra en la siguiente figura.

Figura 1. Se agregó padding a las cadenas de caracteres de longitud variable.

El conector de unidades centrales quita 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 campos struct, establece la variable de entorno BQSH_FEATURE_VARIABLE_LENGTH_ENABLED en yes o true.

Cuando uses campos struct, asegúrate de lo siguiente:

• El sufijo del primer parámetro en struct es -LEN. Si deseas usar un sufijo diferente, debes configurar la variable de entorno BQSH_FEATURE_VARIABLE_LENGTH_LEN_SUFFIX en el sufijo que deseas usar.
• El sufijo del segundo parámetro en struct es -TEXT. Si deseas usar un sufijo diferente, debes configurar la variable de entorno BQSH_FEATURE_VARIABLE_LENGTH_LEN_SUFFIX con el sufijo que deseas usar.

Campos y construcciones no admitidos

En las siguientes secciones, se describen los campos y las construcciones que no son compatibles con

• Construidas de COBOL
• Tipos de datos

Construye COBOL

Construye COBOL, aunque estas construcciones no sean compatibles. Si usas estas construcciones en tu libro de copia, el conector de Mainframe muestra 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 libros de copia heredados

El analizador de libros de copia heredados es una versión anterior del analizador que admite funciones que no son de COBOL. Si usas un libro de copia basado en DSL, es posible que el analizador heredado sea más adecuado, ya que el analizador de libros de copia nativos podría causar errores.

Nota: El analizador heredado dejará de estar disponible. Te recomendamos que cambies al analizador de libros de copia nativos.

Puedes usar el DD de libro de copia con las siguientes restricciones:

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