Configuración del transcodificador

Puedes configurar el transcodificador de Mainframe Connector agregando la configuración requerida en un archivo JSON. Este archivo se conoce como el archivo de configuración del transcodificador. Debes definir la configuración como se especifica en la sección Configuración. Los comandos qsam encode y qsam decode usan el archivo de configuración del transcodificador para realizar la transcodificación de datos.

En esta página, se describen las distintas formas en que puedes configurar el transcodificador de Mainframe Connector.

Configuración

El objeto Configuration es la raíz de la configuración del transcodificador. Contiene todas las opciones de configuración del transcodificador.

Representación JSON 
{
    "defaults": object (DefaultsSection),
    "field_suffixes": object (FieldSuffix),
    "field_overrides": object (FieldOverride),
    "transformations": object (Transformation),
    "schema_validation_mode": enum (SchemaValidationMode),
    "header_records_to_skip": long,
    "record_filter_condition": string
}
Campos
defaults

object (DefaultsSection)

Especifica modificadores de campo predeterminados para arquetipos de Cobol.
field_suffixes

object (FieldSuffix)

Especifica los sufijos de los campos.
field_overrides

object (FieldOverride)

Especifica las anulaciones de campos.
transformations

object (Transformation)

Especifica las transformaciones de campo.
schema_validation_mode

enum (SchemaValidationMode)

Especifica el modo de validación del esquema.
header_records_to_skip

long

Especifica la cantidad de primeros registros que se omitirán.
record_filter_condition

string

Especifica una condición de filtro para los registros.

El filtro admite los siguientes operadores:

  • Operadores de comparación: `==`, `!=`, `<`, `<=`, `>`, `>=`.
  • Operadores lógicos: `&&` (AND), `||` (OR).
  • Contención de listas: `in` (para verificar si un valor está presente en una variable de lista).
  • Operadores aritméticos: `+`, `-`, `*`, `/`, `%`.
  • Funciones de cadena y lista:
    • size(): Devuelve la longitud de una cadena o lista.
    • contains(substring): Comprueba si una cadena contiene una subcadena especificada.
Las comparaciones y las operaciones se deben realizar entre variables o constantes del mismo tipo de datos.

Ejemplo:

"record_filter_condition": "(DATE > '2025-01-12' ) && ((SCORE_A + SCORE_B) > 134)

DefaultsSection

El objeto DefaultsSection se puede usar para especificar modificaciones predeterminadas por tipos de Cobol. Estos se aplican antes de cualquier modificación de sufijo o anulación.

Representación JSON 
{
    "alpha_numeric_display": object (FieldModifier),
    "numeric_display": object (FieldModifier),
    "binary": object (FieldModifier),
    "packed_decimal": object (FieldModifier),
    "national": object (FieldModifier),
    "utf8": object (FieldModifier),
    "dbcs": object (FieldModifier),
    "hexadecimal_floating_point": object (FieldModifier)
}
Campos
alpha_numeric_display

object (FieldModifier)

Especifica valores predeterminados para los campos alfanuméricos (PIC X).
numeric_display

object (FieldModifier)

Especifica los valores predeterminados para los campos de visualización numérica (decimales zonificados).
binary

object (FieldModifier)

Especifica valores predeterminados para los campos de número binario (COMP).
packed_decimal

object (FieldModifier)

Especifica valores predeterminados para los campos decimales empaquetados (COMP-3).
national

object (FieldModifier)

Especifica valores predeterminados para los campos nacionales (PIC N).
utf8

object (FieldModifier)

Especifica valores predeterminados para los campos UTF-8 (PIC U).
dbcs

object (FieldModifier)

Es el valor predeterminado para los campos de DBCS (DISPLAY-1).
hexadecimal_floating_point

object (FieldModifier)

Es el valor predeterminado para los campos de punto flotante hexadecimal (COMP-1, COMP-2).

FieldSuffix

Los sufijos de campo se aplican a todos los campos que tienen un sufijo.

Los campos coinciden si terminan con un guion (-) o un guion bajo (_) seguido del sufijo.

Los sufijos no distinguen mayúsculas de minúsculas.

El modificador FieldSuffix se aplica después del modificador FieldOverride.

Por ejemplo, el modificador definido para el sufijo NID se aplicará al campo llamado FLD-NID, pero no al campo FUNID.

Representación JSON 
{
    "suffix": string,
    "is_inverse": boolean,
    "modifier": object (FieldModifier)
}
Campos
suffix

string

El campo con este sufijo tendrá el modificador aplicado.
is_inverse

boolean

Especifica si el modificador es un modificador de campo inverso o no. Un modificador de campo inverso aplica el modificador en otro campo que tiene el mismo nombre que el campo con el modificador, pero sin el modificador. Por ejemplo, si los campos FLD-NID y FLD existen en el mismo registro, el modificador se aplicará a FLD.

Cuando se usa un modificador de campo inverso, se puede usar el identificador especial $self siempre que se pueda usar tradicionalmente un nombre de campo para hacer referencia al campo con el sufijo.

Por ejemplo, para crear un campo indicador de nulos, puedes usar el modificador de campo null_if con is_inverse establecido en true. Consulta NullIf para obtener más información.
modifier

object (FieldModifier)

Especifica el modificador que se aplicará a los campos coincidentes.

FieldOverride

Anula o modifica la cadena de codificación y decodificación para el campo especificado.

Representación JSON 
{
    "field": string,
    "modifier": object (FieldModifier)
}
Campos
field

string

Especifica el nombre del campo al que se aplicará el modificador.
modifier

object (FieldModifier)

Especifica el modificador que se aplicará al campo coincidente.

Transformación

Las transformaciones de vista se usan para modificar la relación entre la tabla y el archivo QSAM. Las transformaciones siempre se expresan desde el punto de vista de los datos. El concepto es similar al de las tablas de vistas en BigQuery.

Representación JSON 
{
    "exclude": object (Exclude),
    "unnest": object (Unnest),
    "move": object (Move),
    "rename": object (Rename)
}
Campos
exclude

object (Exclude)
unnest

object (Unnest)
move

object (Move)
rename

object (Rename)

FieldModifier

Un modificador de campo te permite modificar la codificación o decodificación de un campo específico. Ten en cuenta que no todos los modificadores se pueden aplicar a todos los campos. Consulta la documentación de los modificadores específicos para obtener más información.

Representación JSON 
{
    "filler": object (Filler),
    "null_if": object (NullIf),
    "format_date": object (FormatDate),
    "chain": object (ModifierChain),
    "zoned_decimal": object (ZonedDecimal),
    "binary": object (Binary),
    "packed_decimal": object (PackedDecimal),
    "null_if_invalid": object (NullIfInvalid),
    "bytes": object (Bytes),
    "varlen": object (VarLen),
    "string": object (String),
    "null_if_empty": object (NullIfEmpty),
    "format_timestamp": object (FormatTimestamp),
    "hfp": object (HFP),
    "decode_as_null": object (DecodeAsNull),
    "encode_null_as": object (EncodeNullAs)
}
Campos
filler

object (Filler)

Excluye el campo del procesamiento y la salida.
null_if

object (NullIf)

Establece el campo como nulo de forma condicional según el valor de otro campo.
format_date

object (FormatDate)

Da formato a un campo de cadena como una fecha.
chain

object (ModifierChain)

Encadena varios modificadores para que se apliquen de forma secuencial.
zoned_decimal

object (ZonedDecimal)

Anula la configuración predeterminada para los campos decimales zonificados.
binary

object (Binary)

Anula la configuración predeterminada para los campos numéricos binarios.
packed_decimal

object (PackedDecimal)

Anula la configuración predeterminada para los campos decimales empaquetados.
null_if_invalid

object (NullIfInvalid)

Establece el campo como nulo si se produce un error de transcodificación, lo que evita el desbordamiento de registros.
bytes

object (Bytes)

Trata el campo como una secuencia sin procesar de bytes, ignorando la información de tipo anterior.
varlen

object (VarLen)

Establece el registro como un campo de longitud variable.
string

object (String)

Anula la configuración predeterminada para los campos de cadena.
null_if_empty

object (NullIfEmpty)

Establece el campo como nulo si su contenido se considera vacío.
format_timestamp

object (FormatTimestamp)

Da formato a un campo de cadena como una marca de tiempo.
hfp

object (HFP)

Interpreta el campo como un número hexadecimal de punto flotante (HFP).
decode_as_null

object (DecodeAsNull)

Define cómo se deben decodificar los valores nulos.
encode_null_as

object (EncodeNullAs)

Define cómo se deben codificar los valores nulos.

Excluir

Excluye un campo de la tabla resultante, pero aún se somete a la decodificación o codificación. Esto es útil cuando el campo no necesita transferirse a la tabla, pero es obligatorio para la transcodificación. Por ejemplo, se pueden omitir de la tabla los indicadores de nulos o los campos de longitud.

Para omitir la transcodificación por completo, aplica el modificador de relleno.

Representación JSON 
{
    "field": string
}
Campos
field

string

Especifica el campo que se excluirá.

Unnest

Desanida el campo.

Representación JSON 
{
    "field": string,
    "format": string
}
Campos
field

string

Especifica el campo que se anulará
format

string

Especifica el nuevo formato del campo.

El ${parent} se lanzará con el nombre del campo que se anula.

En el caso de los structs no anidados, ${field} se reemplaza por el nombre del campo de structs.

En el caso de los arrays y las listas sin anidar, ${index} se reemplaza por los índices del array.

Mover

Mueve un campo en el registro.

Representación JSON 
{
    "field": string,
    "offset": int
}
Campos
field

string

Especifica el campo que se moverá.
offset

int

Especifica la cantidad de posiciones, hacia adelante o hacia atrás, a las que se debe mover el campo.

Cambiar nombre

Cambia el nombre de uno o más campos según una coincidencia de expresión regular.

Por ejemplo, para reemplazar todos los guiones por guiones bajos, usa el siguiente formato JSON: {"find": "\\-", "replace":"_"}.

Representación JSON 
{
    "find": string,
    "replace": string
}
Campos
find

string

Especifica un patrón de expresión regular de Java para identificar los campos a los que se les cambiará el nombre.

El patrón coincide con el nombre completo del campo. Si el patrón coincide con alguna parte del nombre del campo, se considera que el campo coincide.

Ejemplos:

  • "\\-" (coincide con cualquier campo que contenga un guion)
  • "^field_name$" (coincide con los campos que tienen el nombre exacto field_name)
  • "^field_(.*)$" (coincide con cualquier campo que comience con field_ y captura el resto)
  • "part_of_name" (coincide con cualquier campo que contenga part_of_name)
replace

string

Especifica el nuevo nombre para los campos coincidentes.

Los grupos de captura de la expresión regular find se pueden usar en la cadena replace con referencias inversas como $1 y $2. Esto permite transformaciones más complejas basadas en partes del nombre del campo original.

Ejemplos:

  • "new_field_name" (reemplaza el campo por un nombre fijo)
  • "new_$1" (usa el primer grupo de captura de find)
  • "${1}_new" (sintaxis alternativa para grupos de captura)
  • "prefix_$1_suffix" (usa un grupo de captura y agrega prefijos o sufijos)

Relleno

Especifica que se ignorará un campo durante el procesamiento. El campo no se decodificará desde la entrada ni se codificará hacia la salida, y se excluirá del esquema y la tabla de datos resultantes durante la decodificación. Puedes aplicar este modificador a cualquier campo que tenga un tamaño conocido estático.

Proporciona un objeto JSON vacío de la siguiente manera:

Representación JSON 
{
}

NullIf

Establece un campo como nulo si se cumple una condición. Debes especificar null_value o non_null_value, o ambos.

Para crear un campo indicador de nulos, puedes usar un FieldSuffix con un modificador de campo null_if y establecer is_inverse en true, como se muestra en los siguientes ejemplos:

Ejemplo: Indicador de nulos

Para crear un campo indicador de nulos, podemos usar el modificador de campo null_if de la siguiente manera. 

 {
  "field_suffixes": [
   {
     "suffix": "NID",
     "is_inverse": true,
     "modifier": {
     "null_if": {
       "null_value": "?",
       "target_field": "$self"
     }
    }
   }
  ]
 }

Esto permite que todos los campos con el sufijo NID sean indicadores nulos efectivos, como se muestra en el siguiente fragmento de copybook: 

 01 REC.
   02 FIELD     PIC X(10).
   02 FIELD-NID PIC X(1).

Ejemplo: Indicador nulo binario

Para crear un campo indicador de nulos binary, podemos usar los modificadores de campo binary y null_if de la siguiente manera. 

 {
  "field_suffixes": [
   {
     "suffix": "NID",
     "modifier": {
       "binary": {}
     }
   },
   {
     "suffix": "NID",
     "is_inverse": true,
     "modifier": {
     "null_if": {
       "null_value": "15",
       "target_field": "$self"
     }
    }
   }
  ]
 }

Esto permite que todos los campos con el sufijo NID sean indicadores nulos binary de manera efectiva con el mismo libro de copias del ejemplo anterior.

Ejemplo: Indicador de nulos de bytes

Para crear un campo indicador de nulos bytes, podemos usar los modificadores de campo bytes y null_if de la siguiente manera. Los valores para nulo y no nulo se expresan como HEX. 

 {
  "field_suffixes": [
   {
     "suffix": "NID",
     "modifier": {
       "bytes": {}
     }
   },
   {
     "suffix": "NID",
     "is_inverse": true,
     "modifier": {
     "null_if": {
       "null_value": "FF",
       "target_field": "$self"
     }
    }
   }
  ]
 }

Esto permite que todos los campos con el sufijo NID sean efectivamente un indicador de nulo bytes con el mismo libro de copias del ejemplo anterior.

Representación JSON 
{
    "target_field": string,
    "null_value": string,
    "null_values": string,
    "non_null_value": string,
    "non_null_values": string
}
Campos
target_field

string

Especifica el campo cuyo valor deseas verificar. El campo debe estar dentro del alcance.
null_value

string

Cuando se especifica, si target_field es igual a este valor, el campo no se decodifica ni codifica, y el valor se establece como nulo.
null_values

string

Cuando se especifica, si target_field es igual a cualquiera de estos valores, el campo no se decodifica ni codifica, y el valor se establece como nulo.
non_null_value

string

Cuando se especifica, si target_field no es igual a este valor, el campo no se decodifica ni codifica, y el valor se establece como nulo.
non_null_values

string

Cuando se especifica, si target_field no es igual a ninguno de estos valores, el campo no se decodifica ni codifica, y el valor se establece como nulo.

FormatDate

Da formato a una cadena como fecha con uno de los formatos admitidos. Solo puedes aplicar este modificador a los campos con tamaño. Durante el proceso de decodificación, los formatos se prueban en orden hasta que uno de ellos coincide con la cadena. Durante el proceso de codificación, se usa el primer formato y se ignoran los demás.

Representación JSON 
{
    "formats": object (DateTimeFormat)
}
Campos
formats

object (DateTimeFormat)

Es la lista de formatos de fecha.

ModifierChain

Especifica una cadena de modificadores para aplicar varios modificadores en serie. Los modificadores se aplican en el orden en que se especifican.

Representación JSON 
{
    "modifiers": object (FieldModifier)
}
Campos
modifiers

object (FieldModifier)

Especifica la lista de modificadores que se aplicarán.

ZonedDecimal

Establece varias opciones relacionadas con la codificación y decodificación de números decimales zonificados. Solo puedes aplicar este modificador en un campo decimal.

Representación JSON 
{
    "logical_type": enum (DecimalLogicalType),
    "encoding": enum (ZonedDecimalEncoding)
}
Campos
logical_type

enum (DecimalLogicalType)

Especifica el tipo lógico que se usará cuando se decodifique o codifique el campo.
encoding

enum (ZonedDecimalEncoding)

Es la codificación con la que se codifica el campo.

Objeto binario

Ignora los modificadores anteriores y trata este campo como un número binario.

Representación JSON 
{
    "signedness": enum (BinarySignedness)
}
Campos
signedness

enum (BinarySignedness)

Indica si el número es con signo o sin signo.

PackedDecimal

Establece este campo en un PackedDecimal.

Representación JSON 
{
    "logical_type": enum (DecimalLogicalType)
}
Campos
logical_type

enum (DecimalLogicalType)

Anula el tipo lógico. De forma predeterminada, Mainframe Connector usa el tipo lógico óptimo según la precisión y la escala.

NullIfInvalid

Trata el valor como nulo si falla la transcodificación. Solo puedes aplicar este modificador a los campos con tamaño. El error se ignora y no se registra en el conjunto de datos de desbordamiento. Durante el proceso de decodificación, el valor de este campo será nulo para este registro. Durante el proceso de codificación, si no se pueden escribir los datos, todo el campo se completará con bytes nulos.

Proporciona un objeto JSON vacío de la siguiente manera:

Representación JSON 
{
}

Bytes

Trata el campo como una secuencia de bytes sin procesar. Este modificador anula cualquier información de tipo anterior, lo que hace que los datos de bytes sin procesar del campo se conserven tal como están, sin una codificación de caracteres específica ni una interpretación numérica. Puedes aplicar este modificador a cualquier campo, independientemente de su tipo o tamaño original.

Proporciona un objeto JSON vacío de la siguiente manera:

Representación JSON 
{
}

VarLen

Representa un campo de longitud variable.

Un campo de longitud variable contiene tres partes:

  1. Es un elemento de grupo que contiene dos subcampos.
  2. Es un campo dentro del elemento del grupo que contiene la longitud de los datos de la transacción.
  3. Es un campo dentro del elemento del grupo que contiene los datos.

El nombre del campo de longitud variable será el nombre del grupo.

Proporciona un objeto JSON vacío de la siguiente manera:

Representación JSON 
{
}

String

Establece las distintas opciones relacionadas con la codificación y decodificación de cadenas. Solo se puede aplicar a un campo de cadena.

Representación JSON 
{
    "encoding": string,
    "trim_suffix": boolean,
    "pad_char": string
}
Campos
encoding

string

Es la codificación con la que se codifica el campo.
trim_suffix

boolean

Cuando se establece como verdadero, se quita cualquier espacio en blanco al final de la cadena. trim_suffix solo afecta la decodificación, la codificación ignora trim_suffix. Ten en cuenta que las cadenas que solo constan de espacios en blanco se convertirán en cadenas vacías.
pad_char

string

Cuando se establecen cadenas de exportación de relleno con pad_char. Si se establece, la longitud de pad_char debe ser 1. pad_char solo afecta la codificación, la decodificación ignora pad_char.

NullIfEmpty

El campo debe establecerse como nulo si todos los bytes de ese campo son 0.

Proporciona un objeto JSON vacío de la siguiente manera:

Representación JSON 
{
}

FormatTimestamp

Da formato a una cadena como marca de tiempo con uno de los formatos proporcionados. Esto solo se puede aplicar a los campos dimensionados. Durante la decodificación, los formatos se prueban en orden hasta que uno de ellos coincide con la cadena. Durante la codificación, se usará el primer formato y se ignorará el resto.

Representación JSON 
{
    "formats": object (DateTimeFormat)
}
Campos
formats

object (DateTimeFormat)

Es una lista de formatos de marcas de tiempo.

HFP

Establece este campo como Hexadecimal Floating-Point.

Proporciona un objeto JSON vacío de la siguiente manera:

Representación JSON 
{
}

DecodeAsNull

Define cómo se interpretan los valores nulos durante el proceso de decodificación. Como COBOL no admite valores nulos de forma nativa, este parámetro especifica qué valores se deben tratar como nulos.

Representación JSON 
{
    "values": string,
    "hex_bytes": string
}
Campos
values

string

Es una lista de representaciones de cadenas. Después de la decodificación inicial del campo a su forma de cadena, si el contenido del campo coincide con alguno de estos valores, se tratará como nulo.
hex_bytes

string

Es una lista de representaciones hexadecimales de un solo byte. Cuando un campo contiene repeticiones de cualquiera de estos bytes, se trata como nulo. Por ejemplo, usar FF para todos los máximos y 00 para todos los mínimos (vacío).

EncodeNullAs

Define cómo se representan los valores nulos durante el proceso de codificación.

Representación JSON 
{
    "value": string,
    "hex_byte": string
}
Campos
value

string

Codifica este valor específico cuando el valor de origen es nulo. Verifica que la cadena sea válida para el tipo de campo.
hex_byte

string

Codifica esta secuencia de bytes específica (representada como una cadena hexadecimal) cuando el valor de origen es nulo. Por ejemplo, FF para un campo de dos bytes a valores altos. Puedes aplicar esto a cualquier campo con un tamaño conocido. Los bytes se repiten para que coincidan con el tamaño del campo subyacente.

DateTimeFormat

Tamaño y patrón que se usarán cuando se convierta el campo en una fecha.

Representación JSON 
{
    "size": int,
    "pattern": string
}
Campos
size

int

Especifica el tamaño del campo al que se aplica este patrón.
pattern

string

Especifica el patrón del formateador de fechas. Para obtener más información sobre los patrones de formato válidos, consulta Clase DateTimeFormatter.

ZonedDecimalEncoding

Especifica la codificación que se usará cuando se decodifique o codifique un campo decimal zonificado.

Enums
UNSPECIFIED Conserva la codificación especificada en la cadena de modificadores. Si no se especifica ningún modificador, se usa EBCDIC.
EBCDIC Usa la codificación EBCDIC.
ASCII Usa la codificación ASCII.

BinarySignedness

Es el tipo lógico que se usará para un campo decimal.

Enums
UNSPECIFIED Usa el tipo más óptimo según la escala y la precisión.
SIGNED Usa 64 bits para almacenar el valor. Este modificador solo funciona para números cuya precisión sea menor o igual a 18 y la escala sea 0.
UNSIGNED Usa 64 bits para almacenar el valor. Este modificador solo funciona para números cuya precisión sea menor o igual a 18.

DecimalLogicalType

Es el tipo lógico que se usará para un campo decimal.

Enums
AUTO Usa el tipo más óptimo según la escala y la precisión.
LONG Usa 64 bits para almacenar el valor. Este modificador solo funciona para números cuya precisión sea menor o igual a 18 y la escala sea 0.
DECIMAL64 Usa 64 bits para almacenar el valor. Este modificador solo funciona para números cuya precisión sea menor o igual a 18.
BIG_DECIMAL Almacena el valor como un valor decimal sin límites. Esta es la opción más lenta, pero admite cualquier decimal de cualquier precisión en cualquier escala.
BIG_INTEGER Almacena el valor como un valor entero sin límites. Esta es la opción más lenta, pero admite cualquier número entero con cualquier precisión.

SchemaValidationMode

Especifica el modo de validación del esquema que se usará durante la compilación del copybook. Este modo verifica la compatibilidad con un formato de datos de destino específico.

Enums
DEFAULT Es el modo de validación de esquema predeterminado. Este modo verifica que los nombres de los campos únicos estén en el copybook.
BIG_QUERY Modo de validación de esquema para la compatibilidad con BigQuery. Este modo extiende la validación predeterminada para verificar que el esquema del copybook sea compatible con los tipos de datos de BigQuery.
POSTGRES Modo de validación de esquema para la compatibilidad con PostgreSQL. Este modo extiende la validación predeterminada para verificar que el esquema del copybook sea compatible con los tipos de datos de PostgreSQL.
MYSQL Modo de validación de esquema para la compatibilidad con MySQL. Este modo extiende la validación predeterminada para verificar que el esquema del copybook sea compatible con los tipos de datos de MySQL.