轉碼器設定

您可以在 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

欄位後置字元適用於所有含有後置字元的欄位。

如果欄位結尾為連字號 (-) 或底線 (_)，後面接著後置字元，系統就會進行比對。

後置字串不區分大小寫。

系統會在 FieldOverride 修飾符「之後」套用 FieldSuffix 修飾符。

舉例來說，為後置字串 NID 定義的修飾符會套用至名為 FLD-NID 的欄位，但不會套用至欄位 FUNID。

JSON 表示法 
{
    "suffix": string,
    "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)

指定要套用至相符欄位的修飾符。

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} 會釋出未巢狀結構的欄位名稱。

對於未巢狀結構體，${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_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 表示法 
{
    "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 的資料類型相容。

ZonedDecimalEncoding

指定解碼或編碼區域化小數欄位時要使用的編碼。

列舉
UNSPECIFIED 保留輔助鍵鏈結中指定的編碼。如果未指定修飾符，系統會使用 EBCDIC。
EBCDIC 使用 EBCDIC 編碼。
ASCII 使用 ASCII 編碼。

DecimalLogicalType

用於小數欄位的邏輯類型。

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