轉碼器設定

您可以在 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 (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_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) 根據另一個欄位的值，有條件地將欄位設為空值。
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) 將欄位解讀為十六進位浮點數 (HFP)。
decode_as_null	object (DecodeAsNull) 定義空值的解碼方式。
encode_null_as	object (EncodeNullAs) 定義空值的編碼方式。

排除

從產生的表格中排除欄位，但仍會進行解碼或編碼。 如果欄位不需要轉移至表格，但轉碼時必須使用，這項功能就非常實用。 舉例來說，您可以從表格中省略空值指標或長度欄位。

如要完全略過轉碼程序，請套用填補修飾符。

JSON 表示法
{ "field": string }

欄位
field	string 指定要排除的欄位。

Unnest

取消巢狀結構欄位。

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

欄位
field	string 指定要取消巢狀結構的欄位
format	string 指定新的欄位格式。 ${parent} 將會發布，並取消巢狀結構的欄位名稱。 如為未巢狀結構的 struct，${field} 會替換為 struct 欄位的名稱。 對於未巢狀化的陣列和清單，${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 指定相符欄位的新名稱。 您可以在 replace 字串中使用 find 規則運算式的擷取群組，方法是使用 $1、$2 等反向參照。這樣一來，您就能根據原始欄位名稱的部分內容，進行更複雜的轉換。 範例： "new_field_name" (將欄位替換為固定名稱) "new_$1" (使用 find 的第一個擷取群組) "${1}_new" (擷取群組的替代語法) "prefix_$1_suffix" (使用擷取群組並新增前置字串/後置字串)

補白廣告

指定在處理期間要忽略的欄位。 系統不會從輸入內容解碼或編碼至輸出內容，且在解碼期間，會從產生的結構定義和資料表排除這個欄位。 您可以將這個修飾符套用至任何具有靜態已知大小的欄位。

提供空白的 JSON 物件，如下所示：

JSON 表示法
{ }

NullIf

如果符合條件，請將欄位設為空值。您必須指定 null_value 或 non_null_value，或同時指定兩者。

如要建立空值指標欄位，可以使用含有 null_if 欄位修飾符的 FieldSuffix，並將 is_inverse 設為 true，如下列範例所示：

範例：空值指標

如要建立空值指標欄位，可以使用 null_if 欄位修飾符，如下所示：

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

這樣一來，所有帶有 NID 後置字元的欄位，都會成為有效的空值指標，如下列副本程式碼片段所示：

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

範例：二進位空值指標

如要建立 binary 空值指標欄位，可以使用 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 空值指標。

示例：位元組空值指標

如要建立 bytes 空值指標欄位，可以使用 bytes 和 null_if 欄位修飾符，如下所示。空值和非空值會以 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_values	string 指定後，如果 target_field 等於其中任何一個值，系統就不會解碼或編碼該欄位，並將值設為空值。
non_null_value	string 指定時，如果 target_field 不等於這個值，系統就不會解碼或編碼該欄位，並將值設為空值。
non_null_values	string 指定時，如果 target_field 不等於任何這些值，則不會解碼或編碼該欄位，且值會設為空值。

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

如果轉碼失敗，請將值視為空值。 您只能將這個修飾符套用至大小欄位。 系統會忽略這項錯誤，且不會記錄在溢位資料集中。 在解碼過程中，這項記錄的欄位值會是空值。 在編碼過程中，如果無法寫入資料，整個欄位都會填入空位元組。

提供空白的 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，則欄位應設為空值。

提供空白的 JSON 物件，如下所示：

JSON 表示法
{ }

FormatTimestamp

使用其中一種提供的格式，將字串格式化為時間戳記。 這項功能只能套用至已調整大小的欄位。 解碼期間，系統會依序測試格式，直到其中一種格式與字串相符為止。 編碼時，系統會使用第一個格式，並忽略其餘格式。

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

欄位
formats	object (DateTimeFormat) 時間戳記格式清單。

HFP

將這個欄位設為十六進位浮點數。

提供空白的 JSON 物件，如下所示：

JSON 表示法
{ }

DecodeAsNull

定義解碼程序期間如何解讀空值。 由於 COBOL 本身不支援空值，這個參數會指定必須視為空值的值。

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

欄位
values	string 字串表示法清單。將欄位初步解碼為字串形式後，如果欄位內容符合任何這些值，系統就會將其視為空值。
hex_bytes	string 單一位元組的十六進位表示法清單。如果欄位包含任何重複的位元組，系統會將其視為空值。 舉例來說，使用 FF 代表所有高點，並使用 00 代表所有低點 (空白)。

EncodeNullAs

定義編碼程序期間的空值表示方式。

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

欄位
value	string 如果來源值為空值，請編碼這個特定值。 確認字串是否符合欄位類型。
hex_byte	string 如果來源值為空值，請編碼這個特定位元組序列 (以十六進位字串表示)。舉例來說，雙位元組欄位的高值為 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

指定要在副本編譯期間使用的結構定義驗證模式。這個模式會驗證是否與特定目標資料格式相容。

列舉
DEFAULT	預設結構定義驗證模式。 這個模式會驗證副本中是否有不重複的欄位名稱。
BIG_QUERY	BigQuery 相容性的結構定義驗證模式。 這個模式會擴充預設驗證，確認副本的結構定義與 BigQuery 的資料類型相容。
POSTGRES	PostgreSQL 相容性的結構定義驗證模式。 這個模式會擴充預設驗證，確認副本的結構定義與 PostgreSQL 資料類型相容。
MYSQL	MySQL 相容性的結構定義驗證模式。 這個模式會擴充預設驗證，確認副本的結構定義與 MySQL 資料類型相容。