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)
}
字段
defaults

object (DefaultsSection)

为 Cobol 原型指定默认字段修饰符。
field_suffixes

object (FieldSuffix)

指定字段后缀。
field_overrides

object (FieldOverride)

指定字段替换项。
transformations

object (Transformation)

指定字段转换。
schema_validation_mode

enum (SchemaValidationMode)

指定架构验证模式。

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（DISPLAY-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

指定要排除的字段。

展开

展开该字段。

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

指定匹配字段的新名称。

您可以使用 $1、$2 等反向引用，在 replace 字符串中使用 find 正则表达式的捕获组。这样一来，您就可以根据原始字段名称的部分内容进行更复杂的转换。

示例：

  • "new_field_name"（将字段替换为固定名称）
  • "new_$1"（使用 find 中的第一个捕获组）
  • "${1}_new"（捕获组的替代语法）
  • "prefix_$1_suffix"（使用捕获组并添加前缀/后缀）

填充程序

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

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

JSON 表示法 
{
}

NullIf

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

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

示例：null 指示器

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

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

这样一来，所有带有后缀 NID 的字段实际上都成为 null 指示器，如以下副本簿代码段所示： 

 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 指示器

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

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 连接器会根据精度和小数位数使用最佳逻辑类型。

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 类。

BinarySignedness

要为十进制字段使用的逻辑类型。

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

SchemaValidationMode

指定在编译副本簿时要使用的架构验证模式。此模式用于验证与特定目标数据格式的兼容性。

枚举
DEFAULT 默认架构验证模式。 此模式用于验证副本集中是否包含唯一的字段名称。
BIG_QUERY 用于 BigQuery 兼容性的架构验证模式。 此模式会扩展默认验证，以验证副本簿的架构是否与 BigQuery 的数据类型兼容。

ZonedDecimalEncoding

指定在解码或编码时区数值字段时要使用的编码。

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

DecimalLogicalType

要为十进制字段使用的逻辑类型。

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