轉碼器設定

您可以在 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) 定義空值的解碼方式。
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 指定日期格式化程式模式。 如要進一步瞭解有效的格式化工具模式，請參閱「Class DateTimeFormatter」。
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，或同時指定兩者。

如要建立空值指標欄位，可以使用含有 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 表示法
{ "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。 使用反向欄位修飾符時，只要傳統上可使用欄位名稱參照帶有後置字元的欄位，即可使用特殊識別碼 $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 指定相符欄位的新名稱。 您可以在 replace 字串中使用反向參照 (例如 $1、$2)，擷取 find 規則運算式中的群組。這樣一來，您就能根據原始欄位名稱的部分內容，進行更複雜的轉換。 範例： "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

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

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

ZonedDecimalEncoding

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

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