轉碼器設定

您可以在 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), "split": object (Split) }

欄位
exclude	object (Exclude)
unnest	object (Unnest)
move	object (Move)
rename	object (Rename)
split	object (Split)

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 指定要排除的欄位。

拆分

取消巢狀結構欄位。

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

欄位
field	string 指定要分割的欄位。
primary_key	string 指定要當做主鍵的欄位名稱。
foreign_key	string 指定要新增至新結構定義的欄位名稱，主鍵值會儲存在這個欄位中。 如未指定，系統會使用主鍵名稱。

填補

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

提供空白的 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。

BinarySignedness

用於十進位欄位的邏輯類型。

列舉
UNSPECIFIED	根據比例和精確度，使用最合適的型別。
SIGNED	使用 64 位元儲存值。 這個修飾符僅適用於精確度小於或等於 18，且比例為 0 的數字。
UNSIGNED	使用 64 位元儲存值。 這個修飾符僅適用於精確度小於或等於 18 的數字。

SchemaValidationMode

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

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

DecimalLogicalType

用於十進位欄位的邏輯類型。

列舉
AUTO	根據比例和精確度，使用最合適的型別。
LONG	使用 64 位元儲存值。 這個修飾符僅適用於精確度小於或等於 18，且比例為 0 的數字。
DECIMAL64	使用 64 位元儲存值。 這個修飾符僅適用於精確度小於或等於 18 的數字。
BIG_DECIMAL	將值儲存為無界限的小數值。這是最慢的選項，但支援任何精確度的任何十進位數。
BIG_INTEGER	將值儲存為無界整數值。這是最慢的選項，但支援任何精確度的整數。

ZonedDecimalEncoding

指定解碼或編碼分區十進位欄位時要使用的編碼。

列舉
UNSPECIFIED	保留修飾符鏈中指定的編碼方式。 如未指定修飾符，則會使用 EBCDIC。
EBCDIC	使用 EBCDIC 編碼。
ASCII	使用 ASCII 編碼。