转码器配置

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

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

配置

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

JSON 表示法
{ "defaults": object (DefaultsSection), "field_overrides": object (FieldOverride), "field_suffixes": object (FieldSuffix), "header_records_to_skip": long, "record_filter_condition": string, "schema_validation_mode": enum (SchemaValidationMode), "transformations": object (Transformation) }

字段
defaults	object (DefaultsSection) 为 Cobol 原型指定默认字段修饰符。
field_overrides	object (FieldOverride) 指定字段覆盖设置。
field_suffixes	object (FieldSuffix) 指定字段后缀。
header_records_to_skip	long 指定要跳过的前几条记录的数量。
record_filter_condition	string 为记录指定过滤条件。 过滤条件基于通用表达式语言 (CEL) 的子集，并支持以下内容： 字段访问：字段可以按名称引用。对于嵌套字段，请使用点表示法（例如 PARENT.CHILD）。 比较运算符： `==`, `!=`, `<`, `<=`, `>`, `>=`. 逻辑运算符：`&&` (AND), `||` (OR), `!` (NOT). 列表包含： `in`（检查列表中是否存在某个值）。 算术运算符： `+`, `-`, `*`, `/`, `%`. 字符串和列表函数： size()：返回字符串或列表的长度。 contains(substring)：检查字符串是否包含指定的子字符串。 startsWith(prefix)：检查字符串是否以指定前缀开头。 endsWith(suffix)：检查字符串是否以指定的后缀结尾。 日期和时间戳常量： date(string)：解析 ISO 格式 (YYYY-MM-DD) 的日期。例如，date('2025-01-12')。 date(string, format)：使用自定义格式解析日期。例如，date('12/01/2025', 'dd/MM/yyyy')。 timestamp(string)：解析 ISO 格式的时间戳。例如，timestamp('1999-05-03T02:34:00Z')。 比较和运算必须在相同或兼容数据类型的变量或常量之间进行（例如，比较浮点数，或对日期/时间戳字段使用日期/时间戳常量）。 示例： "record_filter_condition": "(ACCOUNT-GRP.DATE > date('2025-01-12') ) && ((SCORE_A + SCORE_B) > 134) && FLD-STR.startsWith('HE')"
schema_validation_mode	enum (SchemaValidationMode) 指定架构验证模式。
transformations	object (Transformation) 指定字段转换。

DefaultsSection

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

JSON 表示法
{ "alpha_numeric_display": object (FieldModifier), "binary": object (FieldModifier), "dbcs": object (FieldModifier), "hexadecimal_floating_point": object (FieldModifier), "national": object (FieldModifier), "numeric_display": object (FieldModifier), "packed_decimal": object (FieldModifier), "utf8": object (FieldModifier) }

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

FieldModifier

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

JSON 表示法

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

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

二进制

忽略任何先前的修饰符，并将此字段视为二进制数。

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

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

字节

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

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

JSON 表示法
{ }

DecodeAsNull

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

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

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

EncodeNullAs

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

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

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

填充程序

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

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

JSON 表示法
{ }

FormatDate

使用一种受支持的格式将字符串或数字字段设置为日期格式。 您只能将此修饰符应用于有大小限制的字段。 对于数字字段，系统会在设置格式之前将其动态转换为字符串表示形式（不包括任何符号标记）。系统假定日期值为正数；不支持负数日期，且无法解析。 在解码过程中，系统会按顺序测试这些格式，直到其中一种格式与字符串匹配。 在编码过程中，系统会使用第一种格式，并忽略其余格式。

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

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

DateTimeFormat

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

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

字段
pattern	string 指定日期格式化程序模式。 如需详细了解有效的格式化程序模式，请参阅 DateTimeFormatter 类。 注意：两位数年份 (yy) 会映射到 2000-2099 范围。例如，对于模式 MM/dd/yy，值 05/03/99 会解码为 2099-05-03。
size	int 指定此模式适用的字段的大小。

FormatTimestamp

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

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

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

HFP

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

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

JSON 表示法
{ }

ModifierChain

指定修饰符链，以串联方式应用多个修饰符。 修饰符会按照其指定顺序应用。

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

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

NullIf

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

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

示例：Null 指示符

如需创建 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 指示器。

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

字段
non_null_value	string 如果指定了此值，且 target_field 不等于此值，则不会对该字段进行解码或编码，并且该值会设置为 null。
non_null_values	string 指定后，如果 target_field 不等于这些值中的任何一个，则该字段不会被解码或编码，并且值会设置为 null。
null_value	string 指定后，如果 target_field 等于此值，则该字段不会解码或编码，并且该值会设置为 null。
null_values	string 指定后，如果 target_field 等于其中任何值，则该字段不会被解码或编码，并且值会设置为 null。
target_field	string 指定要检查其值的字段。该字段必须在范围内。如需访问嵌套字段，您可以使用点表示法（例如“GROUP.FIELD”）。

NullIfEmpty

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

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

JSON 表示法
{ }

NullIfInvalid

如果转码失败，则将该值视为 null。 您只能将此修饰符应用于有大小限制的字段。 默认情况下，如果某个字段无法解码，则整条记录都会移至溢出（错误）数据集，并从输出中排除，而其余加载操作会使用有效记录完成。 设置 null_if_invalid 修饰符后，Mainframe Connector 会保留无效记录，并将此字段设置为 null。 仅当您想保留此类具有 null 值的行时，才使用此选项，而不仅仅是为了使加载成功，因为默认情况下系统已经跳过了错误记录。 系统会忽略该错误，并且不会将其记录在溢出数据集中。 在解码过程中，此记录的此字段值将为 null。 在编码过程中，如果无法写入数据，则整个字段将填充 null 字节。

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

JSON 表示法
{ }

PackedDecimal

将此字段设置为 PackedDecimal。

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

字段
logical_type	enum (DecimalLogicalType) 替换逻辑类型。 默认情况下，Mainframe Connector 会根据精度和比例使用最佳逻辑类型。
negative_sign_nibble	enum (PackedDecimalNegativeNibble) 指定要用于负号的半字节。 虽然 x'B' 和 x'D' 都是有效的负号，但某些大型主机系统或应用可能有要求使用其中一个的惯例。

字符串

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

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

字段
encoding	string 对字段进行编码所采用的编码。
pad_char	string 设置后，系统会使用 pad_char 填充导出的字符串。 如果设置了 pad_char，则其长度必须为 1。 pad_char 仅影响编码，解码会忽略 pad_char。
trim_suffix	boolean 如果设置为 true，则字符串末尾的所有空格都将被剪裁。trim_suffix 仅影响解码，编码会忽略 trim_suffix。请注意，仅包含空格的字符串将变为空字符串。

VarLen

表示长度可变的字段。

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

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

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

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

JSON 表示法
{ }

ZonedDecimal

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

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

字段
encoding	enum (ZonedDecimalEncoding) 对字段进行编码所采用的编码。
logical_type	enum (DecimalLogicalType) 指定在解码或编码字段时要使用的逻辑类型。

FieldOverride

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

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

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

FieldSuffix

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

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

后缀不区分大小写。

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

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

JSON 表示法
{ "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) 指定要应用于匹配字段的修饰符。
suffix	string 带有此后缀的字段将应用该修饰符。

转换

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

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

字段
exclude	object (Exclude)
move	object (Move)
rename	object (Rename)
split	object (Split)
target_table	string 可选。指定要应用转换的目标表（视图）名称。 默认情况下，转换会应用于主表 (_main) 或全局（如果适用）。 如果您有拆分视图（由 split 转换创建），则可以按名称定位到特定的拆分表。 注意：拆分转换本身无法定位，如果设置了 target_table，则会出错。
unnest	object (Unnest)

排除

从生成的表中排除某个字段，但仍进行解码或编码。 当字段不需要传输到表但需要进行转码时，此功能非常有用。 例如，可以从表中省略 null 指示符或长度字段。

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

JSON 表示法
{ "field": string }

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

移动

移动记录中的字段。

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 表示法
{ "field": string, "foreign_key": string, "primary_key": string }

字段
field	string 指定要拆分的字段。
foreign_key	string 为将添加到新架构中的字段指定名称，该字段将用于存储主键值。 如果未指定，则使用主键名称。
primary_key	string 指定将用作主键的字段名称。

Unnest

对该字段执行非嵌套化操作。

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

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

枚举

BinarySignedness

枚举
SIGNED	二进制数有符号。
UNSIGNED	二进制数不带符号。
UNSPECIFIED	尝试从现有链中推断符号。

DecimalLogicalType

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

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

PackedDecimalNegativeNibble

枚举
NIBBLE_B	默认使用 x'B'。
NIBBLE_D	使用 x'D' 表示负号半字节。

SchemaValidationMode

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

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

ZonedDecimalEncoding

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

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