Transcoder 配置

您可以在 JSON 文件中添加所需配置，以配置 Mainframe Connector 转码器。 此文件称为转码器配置文件。您必须按照配置部分中的规定定义配置。qsam encode 和 qsam decode 命令使用转码器配置文件执行数据转码。

本页介绍了配置 Mainframe Connector 转码器的各种方法。

配置

Configuration 对象是转码器配置的根。 它包含转码器的所有配置选项。

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 }

字段
defaults	object (DefaultsSection) 为 Cobol 原型指定默认字段修饰符。
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 为记录指定过滤条件。 该过滤条件支持以下运算符： 比较运算符： `==`, `!=`, `<`, `<=`, `>`, `>=`. 逻辑运算符： `&&` (AND), `||` (OR). 列表包含： `in`（用于检查某个值是否出现在列表变量中）。 算术运算符： `+`, `-`, `*`, `/`, `%`. 字符串和列表函数： size()：返回字符串或列表的长度。 contains(substring)：检查字符串是否包含指定的子字符串。 比较和运算必须在相同数据类型的变量或常量之间进行。 示例： "record_filter_condition": "(DATE > '2025-01-12' ) && ((SCORE_A + SCORE_B) > 134)

DefaultsSection

DefaultsSection 对象可用于按 COBOL 类型指定默认修改。 这些设置会在任何后缀或替换修改之前应用。

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

字段
alpha_numeric_display	object (FieldModifier) 为字母数字 (PIC X) 字段指定默认值。
numeric_display	object (FieldModifier) 为数字显示（分区十进制）字段指定默认值。
binary	object (FieldModifier) 为二进制数 (COMP) 字段指定默认值。
packed_decimal	object (FieldModifier) 为压缩十进制 (COMP-3) 字段指定默认值。
national	object (FieldModifier) 为国家 (PIC N) 字段指定默认值。
utf8	object (FieldModifier) 为 UTF-8 (PIC U) 字段指定默认值。
dbcs	object (FieldModifier) dbcs（显示屏 1）字段的默认值。
hexadecimal_floating_point	object (FieldModifier) 十六进制浮点 (COMP-1、COMP-2) 字段的默认值。

FieldSuffix

字段后缀适用于所有带有后缀的字段。

如果字段以连字符 (-) 或下划线 (_) 结尾，后跟后缀，则匹配。

后缀不区分大小写。

FieldSuffix 修饰符是在 FieldOverride 修饰符之后应用的。

例如，为后缀 NID 定义的修饰符将应用于名为 FLD-NID 的字段，但不会应用于字段 FUNID。

JSON 表示法
{ "suffix": string, "is_inverse": boolean, "modifier": object (FieldModifier) }

字段
suffix	string 带有此后缀的字段将应用相应修饰符。
is_inverse	boolean 指定修饰符是否为反向字段修饰符。 逆字段修饰符会将修饰符应用于另一个字段，该字段的名称与带有修饰符的字段的名称相同，但没有修饰符。例如，如果同一记录中同时存在 FLD-NID 和 FLD 字段，则修饰符将应用于 FLD。 使用反向字段修饰符时，只要传统上可以使用字段名称来引用带有后缀的字段，就可以使用特殊标识符 $self。 例如，如需创建 null 指示器字段，您可以使用 null_if 字段修饰符，并将 is_inverse 设置为 true。如需了解详情，请参阅 NullIf。
modifier	object (FieldModifier) 指定要应用于匹配字段的修饰符。

FieldOverride

替换或修改指定字段的解码和编码链。

JSON 表示法
{ "field": string, "modifier": object (FieldModifier) }

字段
field	string 指定要应用修饰符的字段的名称。
modifier	object (FieldModifier) 指定要应用于匹配字段的修饰符。

转换

视图转换用于修改表与 QSAM 文件之间的关系。 转换始终从数据的角度进行表述。 此概念类似于 BigQuery 中的视图表。

JSON 表示法
{ "exclude": object (Exclude), "unnest": object (Unnest), "move": object (Move), "rename": object (Rename) }

字段
exclude	object (Exclude)
unnest	object (Unnest)
move	object (Move)
rename	object (Rename)

FieldModifier

借助字段修饰符，您可以修改特定字段的编码或解码。 请注意，并非所有修饰符都可应用于所有字段。 如需了解详情，请参阅有关特定修饰符的文档。

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

字段
filler	object (Filler) 从处理和输出中排除相应字段。
null_if	object (NullIf) 根据另一个字段的值有条件地将该字段设置为 null。
format_date	object (FormatDate) 将字符串字段的格式设置为日期。
chain	object (ModifierChain) 链接多个修饰符，以便按顺序应用。
zoned_decimal	object (ZonedDecimal) 替换分区十进制字段的默认配置。
binary	object (Binary) 替换二进制数字字段的默认配置。
packed_decimal	object (PackedDecimal) 替换打包十进制字段的默认配置。
null_if_invalid	object (NullIfInvalid) 如果发生转码错误，则将相应字段设置为 null，以防止记录溢出。
bytes	object (Bytes) 将相应字段视为原始字节序列，忽略之前的类型信息。
varlen	object (VarLen) 将记录设置为可变长度字段。
string	object (String) 替换字符串字段的默认配置。
null_if_empty	object (NullIfEmpty) 如果字段的内容被视为空，则将该字段设置为 null。
format_timestamp	object (FormatTimestamp) 将字符串字段格式化为时间戳。
hfp	object (HFP) 将相应字段解读为十六进制浮点数 (HFP)。
decode_as_null	object (DecodeAsNull) 定义了必须如何解码 null 值。
encode_null_as	object (EncodeNullAs) 定义了必须如何对 null 值进行编码。

排除

从结果表中排除某个字段，但仍会进行解码或编码。 如果字段不需要转移到表中，但转码需要该字段，则此属性非常有用。例如，可以从表中省略 null 指示器或长度字段。

如需完全绕过转码，请应用填充修饰符。

JSON 表示法
{ "field": string }

字段
field	string 指定要排除的字段。

Unnest

取消嵌套相应字段。

JSON 表示法
{ "field": string, "format": string }

字段
field	string 指定要取消嵌套的字段
format	string 指定新字段格式。 系统将发布 ${parent}，其中包含要取消嵌套的字段的名称。 对于非嵌套结构体，${field} 会替换为结构体字段的名称。 对于非嵌套数组和列表，${index} 会替换为数组的索引。

移动

移动记录中的字段。

JSON 表示法
{ "field": string, "offset": int }

字段
field	string 指定要移动的字段。
offset	int 指定字段需要向前或向后移动的位数。

重命名

根据正则表达式匹配结果重命名一个或多个字段。

例如，如需将所有连字符替换为下划线，请使用以下 JSON 格式： {"find": "\\-", "replace":"_"}。

JSON 表示法
{ "find": string, "replace": string }

字段
find	string 指定用于标识要重命名的字段的 Java 正则表达式模式。 系统会根据完整字段名称匹配模式。如果该模式与字段名称的任何部分匹配，则该字段将被视为匹配。 示例： "\\-"（匹配包含连字符的任何字段） "^field_name$"（匹配名称完全为 field_name 的字段） "^field_(.*)$"（匹配以 field_ 开头的任何字段并捕获其余部分） "part_of_name"（匹配包含 part_of_name 的任何字段）
replace	string 指定匹配字段的新名称。 find 正则表达式中的捕获组可通过 $1、$2 等反向引用在 replace 字符串中使用。这样，您就可以根据原始字段名称的一部分进行更复杂的转换。 示例： "new_field_name"（将字段替换为固定名称） "new_$1"（使用 find 中的第一个捕获组） "${1}_new"（捕获组的替代语法） "prefix_$1_suffix"（使用捕获组并添加前缀/后缀）

填充程序

指定在处理期间忽略某个字段。 该字段不会从输入中解码或编码到输出中，并且在解码期间会从生成的架构和数据表中排除。 您可以将此修饰符应用于任何具有静态已知大小的字段。

提供一个空的 JSON 对象，如下所示：

JSON 表示法
{ }

NullIf

如果满足条件，则将字段设置为 null。您必须指定 null_value 和/或 non_null_value。

如需创建 null 指示器字段，您可以使用带有 null_if 字段修饰符的 FieldSuffix，并将 is_inverse 设置为 true，如以下示例所示：

示例：空值指示器

如需创建 null 指示器字段，我们可以使用 null_if 字段修饰符，如下所示。

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

这样一来，带有后缀 NID 的所有字段都可以有效地作为 null 指标，如以下 copybook 代码段所示：

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

示例：二进制 null 指示器

如需创建 binary null 指示器字段，我们可以使用 binary 和 null_if 字段修饰符，如下所示。

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

这样一来，所有带有后缀 NID 的字段都可以有效地成为 binary null 指标，并且使用与之前示例中相同的 copybook。

示例：字节 null 指示器

如需创建 bytes null 指示器字段，我们可以使用 bytes 和 null_if 字段修饰符，如下所示。null 和非 null 的值表示为 HEX。

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

这样一来，所有带有后缀 NID 的字段都可以有效地成为 bytes null 指示器，并使用之前示例中的相同 copybook。

JSON 表示法
{ "target_field": string, "null_value": string, "null_values": string, "non_null_value": string, "non_null_values": string }

字段
target_field	string 指定要检查其值的字段。相应字段必须在范围内。
null_value	string 如果指定了此值，且 target_field 等于此值，则不会对相应字段进行解码或编码，并且该字段的值会设置为 null。
null_values	string 如果指定了这些值，且 target_field 等于其中任何一个值，则不会对相应字段进行解码或编码，并且该字段的值会设置为 null。
non_null_value	string 如果指定了此值，但 target_field 不等于此值，则不会对相应字段进行解码或编码，并且该字段的值会设置为 null。
non_null_values	string 如果指定了这些值，但 target_field 不等于其中的任何值，则不会对相应字段进行解码或编码，并且该字段的值会设置为 null。

FormatDate

使用支持的格式之一将字符串格式化为日期。 您只能将此修饰符应用于已设置大小的字段。 在解码过程中，系统会按顺序测试格式，直到其中一种格式与字符串匹配。 在编码过程中，系统会使用第一个格式，并忽略其余格式。

JSON 表示法
{ "formats": object (DateTimeFormat) }

字段
formats	object (DateTimeFormat) 日期格式列表。

ModifierChain

指定一个修饰符链，以按顺序应用多个修饰符。 修饰符按指定顺序应用。

JSON 表示法
{ "modifiers": object (FieldModifier) }

字段
modifiers	object (FieldModifier) 指定要应用的修饰符列表。

ZonedDecimal

设置与分区十进制数的编码和解码相关的各种选项。 您只能在十进制字段上应用此修饰符。

JSON 表示法
{ "logical_type": enum (DecimalLogicalType), "encoding": enum (ZonedDecimalEncoding) }

字段
logical_type	enum (DecimalLogicalType) 指定在解码或编码字段时要使用的逻辑类型。
encoding	enum (ZonedDecimalEncoding) 字段的编码方式。

二进制

忽略所有之前的修饰符，并将此字段视为二进制数。

JSON 表示法
{ "signedness": enum (BinarySignedness) }

字段
signedness	enum (BinarySignedness) 数字的符号。

PackedDecimal

将此字段设置为 PackedDecimal。

JSON 表示法
{ "logical_type": enum (DecimalLogicalType) }

字段
logical_type	enum (DecimalLogicalType) 替换逻辑类型。 默认情况下，Mainframe Connector 会根据精度和比例使用最佳逻辑类型。

NullIfInvalid

如果转码失败，则将值视为 null。 您只能将此修饰符应用于已设置大小的字段。 系统会忽略该错误，并且不会在溢出数据集中记录该错误。 在解码过程中，相应记录的此字段的值将为 null。 在编码过程中，如果无法写入数据，整个字段将填充 null 字节。

提供一个空的 JSON 对象，如下所示：

JSON 表示法
{ }

字节

将相应字段视为原始字节序列。 此修饰符会替换任何先前的类型信息，从而使字段的原始字节数据按原样保留，而无需进行特定的字符编码或数值解释。 您可以将此修饰符应用于任何字段，无论其原始类型或大小如何。

提供一个空的 JSON 对象，如下所示：

JSON 表示法
{ }

VarLen

表示可变长度字段。

可变长度字段包含三个部分：

1. 包含两个子字段的组项。
2. 组项中包含交易数据长度的字段。
3. 组项中包含数据的字段。

可变长度字段的名称将是组名称。

提供一个空的 JSON 对象，如下所示：

JSON 表示法
{ }

字符串

设置与字符串解码和编码相关的各种选项。 只能应用于字符串字段。

JSON 表示法
{ "encoding": string, "trim_suffix": boolean, "pad_char": string }

字段
encoding	string 字段的编码方式。
trim_suffix	boolean 如果设置为 true，则会剪掉字符串末尾的所有空格。 trim_suffix 仅影响解码，编码会忽略 trim_suffix。 请注意，仅包含空格的字符串将变成空字符串。
pad_char	string 使用 pad_char 设置填充导出字符串时。 如果设置了 pad_char，则其长度必须为 1。pad_char 仅影响编码，解码会忽略 pad_char。

NullIfEmpty

如果相应字段中的所有字节均为 0，则应将该字段设置为 null。

提供一个空的 JSON 对象，如下所示：

JSON 表示法
{ }

FormatTimestamp

使用提供的格式之一将字符串格式化为时间戳。 此属性只能应用于有大小的字段。 在解码期间，系统会按顺序测试格式，直到其中一种格式与字符串匹配。 在编码期间，系统将使用第一个格式，并忽略其余格式。

JSON 表示法
{ "formats": object (DateTimeFormat) }

字段
formats	object (DateTimeFormat) 时间戳格式列表。

HFP

将此字段设置为十六进制浮点数。

提供一个空的 JSON 对象，如下所示：

JSON 表示法
{ }

DecodeAsNull

定义在解码过程中如何解读 null 值。 由于 COBOL 本身不支持 null，因此此形参用于指定哪些值必须被视为 null。

JSON 表示法
{ "values": string, "hex_bytes": string }

字段
values	string 字符串表示形式的列表。在将字段初步解码为字符串形式后，如果字段的内容与这些值中的任何一个匹配，则该字段将被视为 null。
hex_bytes	string 单个字节的十六进制表示形式的列表。 如果字段包含重复的上述任何字节，则会被视为 null。 例如，使用 FF 表示所有高值，使用 00 表示所有低值（空）。

EncodeNullAs

定义在编码过程中如何表示 null 值。

JSON 表示法
{ "value": string, "hex_byte": string }

字段
value	string 当源值为 null 时，对该特定值进行编码。 验证字符串是否对相应字段类型有效。
hex_byte	string 当源值为 null 时，对该特定字节序列（以十六进制字符串表示）进行编码。例如，将双字节字段的 FF 设置为高值。 您可以将此方法应用于任何具有已知大小的字段。 重复字节以匹配底层字段的大小。

DateTimeFormat

将字段转换为日期时要使用的格式和模式。

JSON 表示法
{ "size": int, "pattern": string }

字段
size	int 指定此模式所适用的字段的大小。
pattern	string 指定日期格式化程序模式。 如需详细了解有效的格式设置器模式，请参阅类 DateTimeFormatter。

ZonedDecimalEncoding

指定在解码或编码分区十进制字段时要使用的编码。

枚举
UNSPECIFIED	保留修饰符链中指定的编码。 如果未指定修饰符，则使用 EBCDIC。
EBCDIC	使用 EBCDIC 编码。
ASCII	使用 ASCII 编码。

BinarySignedness

用于十进制字段的逻辑类型。

枚举
UNSPECIFIED	根据规模和精度使用最合适的类型。
SIGNED	使用 64 位存储值。 此修饰符仅适用于精度小于或等于 18 且标度为 0 的数字。
UNSIGNED	使用 64 位来存储值。 此修饰符仅适用于精度小于或等于 18 的数字。

DecimalLogicalType

用于十进制字段的逻辑类型。

枚举
AUTO	根据规模和精度使用最合适的类型。
LONG	使用 64 位存储值。 此修饰符仅适用于精度小于或等于 18 且标度为 0 的数字。
DECIMAL64	使用 64 位来存储值。 此修饰符仅适用于精度小于或等于 18 的数字。
BIG_DECIMAL	将值存储为无界限的十进制值。这是最慢的选项，但支持任意精度和任意规模的任何十进制数。
BIG_INTEGER	将值存储为无界限的整数值。这是最慢的选项，但支持任意精度的任何整数。

SchemaValidationMode

指定在 copybook 编译期间使用的架构验证模式。此模式用于验证与特定目标数据格式的兼容性。

枚举
DEFAULT	默认架构验证模式。 此模式会验证 copybook 中是否存在唯一的字段名称。
BIG_QUERY	用于 BigQuery 兼容性的架构验证模式。 此模式扩展了默认验证，以验证 copybook 的架构是否与 BigQuery 的数据类型兼容。
POSTGRES	PostgreSQL 兼容性的架构验证模式。 此模式扩展了默认验证，以验证 copybook 的架构是否与 PostgreSQL 数据类型兼容。
MYSQL	MySQL 兼容性的架构验证模式。 此模式会扩展默认验证，以验证 copybook 的架构是否与 MySQL 数据类型兼容。