轉碼器設定

如要設定 Mainframe Connector 轉碼器，請在 JSON 檔案中新增必要設定。這個檔案稱為轉碼器設定檔。您必須按照「設定」一節中的說明定義設定。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) 定義空值的解碼方式。
encode_null_as	object (EncodeNullAs) 定義空值的編碼方式。
filler	object (Filler) 從處理和輸出作業中排除欄位。
format_date	object (FormatDate) 將字串欄位格式設為日期。
format_timestamp	object (FormatTimestamp) 將字串欄位格式設為時間戳記。
hfp	object (HFP) 將欄位解讀為十六進位浮點 (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) 覆寫分區十進位欄位的預設設定。

二進位檔

忽略先前的修飾符，並將這個欄位視為二進位數字。

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

欄位
signedness	enum (BinarySignedness) 數字的正負號。

位元組數

將欄位視為原始位元組序列。這個修飾符會覆寫先前的任何類型資訊，因此欄位的原始位元組資料會保持原樣，不會有特定的字元編碼或數字解讀。 無論原始類型或大小為何，您都可以將這個修飾符套用至任何欄位。

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

JSON 表示法
{ }

DecodeAsNull

定義解碼程序如何解讀空值。由於 COBOL 原生不支援空值，因此這個參數會指定哪些值必須視為空值。

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

欄位
hex_bytes	string 單一位元組的十六進位表示法清單。如果欄位包含任何重複的位元組，則會視為空值。例如，所有高音都使用 FF，所有低音都使用 00 (空白)。
values	string 字串表示法清單。欄位初始解碼為字串形式後，如果欄位內容與其中任何值相符，就會視為空值。

EncodeNullAs

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

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

欄位
hex_byte	string 來源值為空值時，對這個特定位元組序列 (以十六進位字串表示) 進行編碼。例如，將雙位元組欄位設為高值的 FF。您可以將此做法套用至任何已知大小的欄位。系統會重複位元組，以符合基礎欄位的大小。
value	string 如果來源值為空值，請對這個特定值進行編碼。確認字串適用於欄位類型。

補白廣告

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

提供空白 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_value 或 non_null_value，或兩者皆指定。

如要建立空值指標欄位，您可以使用 FieldSuffix 搭配 null_if 欄位修飾符，並將 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 表示法
{ "non_null_value": string, "non_null_values": string, "null_value": string, "null_values": string, "target_field": string }

欄位
non_null_value	string 指定後，如果 target_field 不等於這個值，系統就不會解碼或編碼欄位，並將值設為空值。
non_null_values	string 指定後，如果 target_field 不等於上述任何值，系統就不會解碼或編碼欄位，並將值設為空值。
null_value	string 指定後，如果 target_field 等於這個值，系統就不會解碼或編碼欄位，並將值設為空值。
null_values	string 指定後，如果 target_field 等於其中任何值，系統就不會解碼或編碼欄位，並將值設為空值。
target_field	string 指定要檢查值的欄位。欄位必須在範圍內。如要存取巢狀欄位，可以使用點記法 (例如「GROUP.FIELD」)。

NullIfEmpty

如果欄位中的所有位元組都是 0，則應將欄位設為空值。

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

JSON 表示法
{ }

NullIfInvalid

如果轉碼失敗，則將值視為空值。 這個修飾符只能套用至有大小的欄位。 根據預設，如果欄位解碼失敗，整筆記錄會移至溢出 (錯誤) 資料集，並從輸出內容中排除，其餘載入作業則會以有效記錄完成。設定 null_if_invalid 修飾符時，Mainframe Connector 會保留無效記錄，並將這個欄位設為空值。 只有在您想保留這類含有空值的資料列時，才應使用這個選項，而不是只為了讓載入作業成功，因為預設設定已會略過不良記錄。 系統會忽略錯誤，不會記錄在溢出資料集中。 解碼過程中，這筆記錄的這個欄位值會是空值。 在編碼過程中，如果無法寫入資料，整個欄位都會填入空值位元組。

提供空白 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。 使用反向欄位修飾符時，只要欄位名稱傳統上可用於參照具有後置字串的欄位，就可以使用特殊 ID $self。 舉例來說，如要建立空值指標欄位，您可以使用 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)

排除

從結果資料表中排除欄位，但仍進行解碼或編碼。如果欄位不需要轉移至資料表，但轉碼時需要，這項功能就非常實用。例如，表格可以省略空值指標或長度欄位。

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

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 指定要用做主鍵的欄位名稱。

拆分

取消巢狀結構欄位。

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。