

AWS Mainframe Modernization Service （受管執行期環境體驗） 不再向新客戶開放。對於與 AWS Mainframe Modernization Service （受管執行期環境體驗） 類似的功能，探索 AWS Mainframe Modernization Service （自我管理體驗）。現有客戶可以繼續正常使用該服務。如需詳細資訊，請參閱[AWS 大型主機現代化可用性變更](https://docs.aws.amazon.com/m2/latest/userguide/mainframe-modernization-availability-change.html)。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# AWS 大型主機 Blusam 的轉換
<a name="ba-shared-blusam"></a>

在大型主機系統上 （在下列主題中稱為「舊版」)，商業資料通常會使用 VSAM （虛擬儲存存取方法） 儲存。資料存放在屬於「資料集」的「記錄」（位元組陣列）中。

有四個資料集組織：
+ **KSDS**：金鑰序列資料集 - 記錄會依主索引鍵 （不允許重複的索引鍵） 編製索引，並可選擇使用額外的「備用」索引鍵。所有索引鍵值都是記錄位元組陣列的子集，每個索引鍵由以下項目定義：
  + 位移 （以 0 為基礎，0 是記錄位元組陣列內容的開頭，以位元組為單位）
  + a length （以位元組表示）
  + 是否容忍重複的值
+ **ESDS**：輸入序列資料集 - 記錄主要是循序存取 （根據其在資料集中的插入順序），但可以使用其他備用金鑰存取；
+ **RRDS**：相對記錄資料集 - 使用「跳躍」存取記錄，使用相對記錄編號；跳躍可以向前或向後完成；
+ **LDS**：線性資料集 - 在那裡沒有記錄，只是以頁面整理的位元組串流。主要用於舊版平台上的內部用途。

使用 AWS Transform 進行大型主機重構方法現代化舊版應用程式時，現代化應用程式不再旨在存取 VSAM 儲存的資料，同時保留資料存取邏輯。Blusam 元件是答案：它允許從舊版 VSAM 資料集匯出匯入資料，為現代化應用程式提供 API，以搭配專用的管理 Web 應用程式操作它們。請參閱 [AWS 大型主機Blusam管理主控台的轉換](ba-shared-bac-userguide.md)。

**注意**  
Blusam 僅支援 KSDS、ETS 和 RRDS。

Blusam API 可讓您保留資料存取邏輯 （循序、隨機和相對讀取；插入、更新和刪除記錄），而依賴快取策略和 RDBMS 型儲存的元件架構則允許具有有限資源的高輸送量 I/O 操作。

## Blusam 基礎設施
<a name="ba-shared-blusam-infrastructure"></a>

Blusam 依賴 PostgreSQL RDBMS 儲存資料集，包括原始記錄資料和金鑰索引 （如適用）。最愛的選項是使用 Amazon Aurora PostgreSQL 相容引擎。本主題中的範例和圖例是以此引擎為基礎。

**注意**  
在伺服器啟動時，Blusam執行時間會檢查是否存在某些強制性技術資料表，並在找不到它們時建立它們。因此，在組態中用來存取Blusam資料庫的角色必須獲得建立、更新和刪除資料庫資料表 （資料列和資料表定義本身） 的權限。如需如何停用 的詳細資訊Blusam，請參閱 [Blusam 組態](#ba-shared-blusam-configuration)。

### 快取
<a name="ba-shared-blusam-caching"></a>

除了儲存體本身之外， 會在與快取實作結合時更快速Blusam地運作。

目前支援兩個快取引擎：EhCache 和 Redis，每個引擎都有自己的使用案例：
+ EhCache：獨立內嵌揮發性本機快取 
  + **不符合** AWS 大型主機現代化受管環境部署的資格。
  + 通常在單一節點，例如單一 Apache Tomcat 伺服器，用於執行現代化應用程式時使用。例如，節點可能專用於託管批次任務。
  + **揮發性**：EhCache 快取執行個體是揮發性；其內容會在伺服器關閉時遺失。
  + **內嵌**：EhCache 和伺服器共用相同的 JVM 記憶體空間 （定義託管機器的規格時要考量）。
+ Redis：共用持久性快取 
  + 符合 AWS 大型主機現代化受管環境部署的資格。
  + 通常用於多節點情況，特別是當多個伺服器落後於負載平衡器時。快取內容在所有節點之間共用。
  + Redis 是持久性的，不繫結至節點生命週期。它正在自己的專用機器或服務上執行 （例如，Amazon ElastiCache)。快取位於所有節點的遠端。

### 鎖定
<a name="ba-shared-blusam-locking"></a>

為了處理資料集和記錄的並行存取， Blusam依賴可設定的鎖定系統。鎖定可套用至兩個層級：資料集和記錄：
+ 鎖定用於寫入目的的資料集，可防止所有其他用戶端在任何層級 （資料集或記錄） 對其執行寫入操作。
+ 在記錄層級鎖定以進行寫入，將阻止其他用戶端僅對指定記錄執行寫入操作。

應根據快取組態相應地設定Blusam鎖定系統：
+ 如果選擇 EhCache 做為快取實作，則不需要進一步鎖定組態，因為應該使用預設的記憶體內鎖定系統。
+ 如果選擇 Redis 做為快取實作，則需要 Redis 型鎖定組態，以允許從多個節點同時存取。用於鎖定的 Redis 快取不必與用於資料集的 Redis 快取相同。如需設定 Redis 型鎖定系統的相關資訊，請參閱 [Blusam 組態](#ba-shared-blusam-configuration)。

## Blusam 內部和資料從舊版遷移
<a name="ba-shared-blusam-intrinsics"></a>



### 儲存資料集：記錄和索引
<a name="ba-shared-blusam-storage"></a>

匯入 時，每個舊版資料集Blusam都會儲存到專用資料表；資料表的每一列都代表記錄，使用兩個資料欄：
+ 數值 ID 欄，大整數類型，即資料表主索引鍵，用於存放記錄的相對位元組地址 (RBA)。RBA 代表從資料集開始的位元組位移，從 0 開始。
+ 位元組陣列記錄欄，用於存放原始記錄的內容。

例如，請參閱 CardDemo 應用程式中使用的 KSDS 資料集內容：

![查詢結果顯示值為 0 到 3600 的 ID 資料欄，以及包含二進位資料的記錄資料欄。](http://docs.aws.amazon.com/zh_tw/m2/latest/userguide/images/sample_dataset_storage.png)

+ 此特定資料集具有固定長度記錄，長度為 300 位元組 （因此 ID 的集合為 300 的倍數）。
+ 根據預設，用於查詢 PostgreSQL 資料庫的 pgAdmin 工具不會顯示位元組陣列資料欄內容，而是列印 【二進位資料】 標籤。
+ 原始記錄內容符合從舊版匯出的原始資料集，無需任何轉換。特別是，不會發生字元集轉換；這表示記錄的英數字元部分必須由使用舊版字元集的現代化應用程式解碼，很可能是 EBCDIC 變體。

關於資料集中繼資料和索引鍵：每個資料集都與名為 的資料表中的兩列相關聯`metadata`。這是預設的命名慣例。若要了解如何自訂，請參閱 [Blusam 組態](#ba-shared-blusam-configuration)。

![表格顯示兩個資料列，其中包含 VSAM KSDS 資料集項目的名稱和中繼資料資料欄。](http://docs.aws.amazon.com/zh_tw/m2/latest/userguide/images/sample_dataset_metadata_rows.png)

+ 第一列具有資料集名稱做為*名稱*資料欄的值。*中繼資料*資料欄是二進位資料欄，其中包含指定資料集之一般中繼資料的二進位序列化。如需詳細資訊，請參閱[一般資料集中繼資料屬性](#ba-shared-blusam-metadata)。
+ 第二列具有資料集名稱，其尾碼`__internal'`為*名稱*資料欄的值。*中繼資料*資料欄二進位內容取決於資料集的「權重」。
  + 對於小型/中型資料集，內容是以下項目的壓縮序列化：
    + 資料集所使用的金鑰定義；主金鑰定義 （適用於 KSDS) 和替代金鑰定義，如適用 （適用於 KSDS / ESDS)
    + 如果適用，索引鍵索引 （具有備用索引鍵定義的 KSDS / ESDS)：用於記錄的索引瀏覽；索引鍵索引會將索引鍵值映射至記錄的 RBA；
    + 記錄長度映射：用於記錄的循序/相對瀏覽；
  + 對於大型/非常大型資料集，內容是壓縮序列化：
    + 資料集所使用的金鑰定義；主金鑰定義 （適用於 KSDS) 和替代金鑰定義，如適用 （適用於 KSDS / ESDS)

此外，大型/非常大型的資料集索引 （如果適用） 會使用分頁機制存放；索引頁面二進位序列化會以專用資料表的資料列存放 （每個資料集索引鍵一個資料表）。索引的每個頁面都會儲存在資料列中，並具有下列資料欄：
+ ID：索引頁面的技術識別符 （數字主索引鍵）；
+ firstkey：存放在索引頁面中第一個 （最低） 索引鍵值的二進位值；
+ lastkey：存放在索引頁面中最後一個 （最高） 索引鍵值的二進位值；
+ 中繼資料：索引頁面的二進位壓縮序列化 （將索引鍵值映射至記錄 RBAs)。

![資料庫資料表顯示 ID、firstkey bytea、 lastkey bytea 和中繼資料 oid 的資料列。](http://docs.aws.amazon.com/zh_tw/m2/latest/userguide/images/sample_index_pages.png)


資料表名稱是資料集名稱和金鑰內部名稱的串連，其中包含金鑰的相關資訊，例如金鑰偏移、金鑰是否接受重複 （設定為 true 以允許重複），以及金鑰長度。例如，假設名為 "AWS\_LARGE\_KSDS" 的資料集具有下列兩個定義金鑰：
+ 主索引鍵 【偏移：0，重複：false， length：18】
+ 備用索引鍵 【offset： 3， duplicates： true， length： 6】

在此情況下，下表會存放與兩個索引鍵相關的索引。

![標記為 aws_large_ksds_0f18 和 aws_large_ksds_3f6 的兩個摺疊資料表項目。](http://docs.aws.amazon.com/zh_tw/m2/latest/userguide/images/sample_large_dataset_indexes_tables.png)


### 使用寫入落後機制最佳化 I/O 輸送量
<a name="ba-shared-blusam-write-behind"></a>

為了最佳化插入/更新/刪除操作效能，Blusam引擎依賴可設定的寫入落後機制。此機制建置在專用執行緒集區上，該集區使用大量更新查詢來處理持久性操作，以最大化Blusam儲存的 I/O 輸送量。

Blusam 引擎會收集應用程式對記錄執行的所有更新操作，並建置要分派給專用執行緒進行處理的記錄批次。然後，使用大量更新查詢將批次保留到Blusam儲存體，避免使用原子持久性操作，確保盡可能使用最佳的網路頻寬。

機制使用可設定的延遲 （預設為一秒） 和可設定的批次大小 （預設為 10000 筆記錄）。一旦符合下列兩個條件中的第一個，就會執行建置持久性查詢：
+ 已超過設定的延遲，且批次不是空的
+ 批次中要處理的記錄數目達到設定的限制

若要了解如何設定幕後寫入機制，請參閱 [可選屬性](#ba-shared-blusam-configuration-engine-optional-properties)。

### 挑選適當的儲存方案
<a name="ba-shared-blusam-storage-scheme"></a>

如上一節所示，資料集的儲存方式取決於其「權重」。但是，對於資料集，什麼被視為小型、中型或大型？ 何時選擇分頁儲存策略，而不是一般儲存策略？

該問題的答案取決於下列各項。
+ 託管將使用這些資料集之現代化應用程式的每部伺服器上可用的記憶體數量。
+ 快取基礎設施上的可用記憶體數量 （如果有的話）。

使用非分頁索引儲存方案時，每個資料集的完整索引和記錄大小集合會在資料集開啟時間載入伺服器記憶體。此外，如果涉及快取，則所有資料集記錄可能會使用一般方法預先載入快取，這可能會導致快取基礎設施端的記憶體資源耗盡。

根據定義的金鑰數量、金鑰值的長度、記錄數量和同時開啟的資料集數量，可針對指定的已知使用案例大致評估耗用記憶體數量。

如需詳細資訊，請參閱 [估計指定資料集的記憶體使用量](#ba-shared-blusam-memory)。

### Blusam 遷移
<a name="ba-shared-blusam-migration"></a>

為指定的資料集選取適當的儲存體方案後，必須透過遷移舊版資料集來填入Blusam儲存體。

若要達成此目的，使用者必須使用舊版資料集的**原始二進位匯出**，而不需在匯出程序期間使用任何字元集轉換。從舊版系統傳輸資料集匯出時，請務必不要損毀二進位格式。例如，使用 FTP 時強制執行二進位模式。

**原始二進位匯出**僅包含記錄。匯入機制不需要匯出索引鍵/索引，因為匯入機制正在即時重新計算所有索引鍵/索引。

資料集二進位匯出可用後，有幾個選項可將其遷移至Blusam存在：

在 AWS 大型主機現代化受管環境上：
+ 使用專用功能匯入資料集。請參閱 [匯入 AWS Mainframe Modernization 應用程式的資料集](applications-m2-dataset.md)。

或
+ 使用資料集大量匯入設施。請參閱 [AWS Mainframe Modernization 資料集定義參考](datasets-m2-definition.md) 和 [VSAM 的資料集請求格式範例](datasets-m2-definition.md#datasets-m2-definition-vsam)。

或
+ 使用 groovy 指令碼，使用專用載入服務匯入資料集。

**注意**  
目前只能在大型主機現代化受管環境中使用 groovy 指令碼匯入 LargeKSDS 和 LargeESDS。

Amazon EC2 上大型主機執行期的 AWS 轉換上：
+ 使用 匯入資料集[AWS 大型主機Blusam管理主控台的轉換](ba-shared-bac-userguide.md)。

或
+ 使用 groovy 指令碼，使用專用載入服務匯入資料集。

#### 使用 Groovy 指令碼匯入資料集
<a name="ba-shared-blusam-migration-groovy"></a>

本節將協助您撰寫 groovy 指令碼，將舊版資料集匯入 Blusam。

它從一些強制性匯入開始：

```
import com.netfective.bluage.gapwalk.bluesam.BluesamManager
import com.netfective.bluage.gapwalk.bluesam.metadata.Key;
import com.netfective.bluage.gapwalk.rt.provider.ServiceRegistry
import java.util.ArrayList; //used for alternate keys if any
```

之後，針對要匯入的每個資料集，程式碼會建置在指定的模式上：

1. 建立或清除映射物件

1. 使用所需的屬性填入映射 （這隨資料集類型而異 -- 如需詳細資訊，請參閱下文）

1. 在服務登錄檔中擷取要用於資料集類型的適當載入服務

1. 使用映射做為引數來執行服務

您可以使用下列識別符，從服務登錄檔擷取 5 個服務實作：
+ `"BluesamKSDSFileLoader"`：適用於小型/中型 KSDS
+ `"BluesamESDSFileLoader"` 適用於中小型 ESDS
+ `"BluesamRRDSFileLoader"`：適用於 RRDS
+ `"BluesamLargeKSDSFileLoader"`：適用於大型 KSDS
+ `"BluesamLargeESDSFileLoader"`：適用於大型 ESDS

是否選擇 KSDS/ESDS 的一般版本和大型版本服務，取決於資料集的大小，以及您想要套用的儲存策略。若要了解如何選擇適當的儲存策略，請參閱 [挑選適當的儲存方案](#ba-shared-blusam-storage-scheme)。

若要能夠成功將資料集匯入 Blusam，必須將適當的屬性提供給載入服務。

常見屬性：
+ 強制性 （適用於所有類型的資料集）
  + "bluesamManager"：預期值為 `applicationContext.getBean(BluesamManager.class)`
  + "datasetName"：資料集的名稱，做為字串
  + "inFilePath"：舊版資料集匯出的路徑，做為字串
  + "recordLength"：固定記錄長度或變數記錄長度資料集為 0，以整數表示
+ 選用
  + **不支援大型資料集：**
    + "isAppend" ：布林值旗標，表示匯入正在附加模式中發生 （將記錄附加至現有Blusam資料集）。
    + 「useCompression」：布林值旗標，表示將使用壓縮來存放中繼資料。
  + **僅適用於大型資料集：**
    + 「indexingPageSizeInMb」：每個索引頁面的大小，針對資料集的每個索引鍵，以絕對正整數表示

資料集類型相依屬性：
+ KSDS/大型 KSDS：
  + mandatory 
    + "primaryKey" ：主索引鍵定義，使用`com.netfective.bluage.gapwalk.bluesam.metadata.Key`建構函數呼叫。
  + 選用：
    + "alternateKeys" ：使用建構函數呼叫建置的備用金鑰定義的清單 `com.netfective.bluage.gapwalk.bluesam.metadata.Key` ( `java.util.List`)。
+ ESDS/大型 ESDS：
  + 選用：
    + "alternateKeys" ：使用建構函數呼叫建置的備用金鑰定義的清單 `com.netfective.bluage.gapwalk.bluesam.metadata.Key` ( `java.util.List`)。
+ RRDS：
  + 無。

金鑰建構函數呼叫：
+ `new Key(int offset, int length)`： 會使用指定的金鑰屬性 （偏移和長度） 建立金鑰物件，且不允許重複。此變體應該用來定義主索引鍵。
+ `new Key(boolean allowDuplicates, int offset, int length)`： 會使用指定的金鑰屬性 （偏移和長度） 和允許標記的重複項目來建立金鑰物件。

下列 Groovy 範例說明各種載入案例。

使用兩個備用金鑰載入大型 KSDS：

```
import com.netfective.bluage.gapwalk.bluesam.BluesamManager
import com.netfective.bluage.gapwalk.bluesam.metadata.Key;
import com.netfective.bluage.gapwalk.rt.provider.ServiceRegistry
import java.util.ArrayList;

// Loading a large KSDS into Blusam
def map = [:]
map.put("bluesamManager", applicationContext.getBean(BluesamManager.class));
map.put("datasetName", "largeKsdsSample");
map.put("inFilePath", "/work/samples/largeKsdsSampleExport");
map.put("recordLength", 49);
map.put("primaryKey", new Key(0, 18));
ArrayList altKeys = [new Key(true, 10, 8), new Key(false, 0, 9)]
map.put("alternateKeys", altKeys);
map.put("indexingPageSizeInMb", 25);
def service = ServiceRegistry.getService("BluesamLargeKSDSFileLoader");
service.runService(map);
```

載入不含備用索引鍵的可變記錄長度 ESDS：

```
import com.netfective.bluage.gapwalk.bluesam.BluesamManager
import com.netfective.bluage.gapwalk.bluesam.metadata.Key;
import com.netfective.bluage.gapwalk.rt.provider.ServiceRegistry

// Loading an ESDS into Blusam
def map = [:]
map.put("bluesamManager", applicationContext.getBean(BluesamManager.class));
map.put("datasetName", "esdsSample");
map.put("inFilePath", "/work/samples/esdsSampleExport");
map.put("recordLength", 0);
def service = ServiceRegistry.getService("BluesamESDSFileLoader");
service.runService(map);
```

可變記錄長度資料集匯出將包含強制性的 Record Decriptor Word (RDW) 資訊，以允許在讀取時分割記錄。

載入固定記錄長度 RRDS：

```
import com.netfective.bluage.gapwalk.bluesam.BluesamManager
import com.netfective.bluage.gapwalk.bluesam.metadata.Key;
import com.netfective.bluage.gapwalk.rt.provider.ServiceRegistry

// Loading a RRDS into Blusam
def map = [:]
map.put("bluesamManager", applicationContext.getBean(BluesamManager.class));
map.put("datasetName", "rrdsSample");
map.put("inFilePath", "/work/samples/rrdsSampleExport");
map.put("recordLength", 180);
def service = ServiceRegistry.getService("BluesamRRDSFileLoader");
service.runService(map);
```

在**多結構描述模式中**載入資料集：

**多結構描述模式**：在某些舊版系統中，VSAM 檔案會組織成檔案集，允許程式存取和修改指定分割區內的資料。現代系統會將每個檔案集視為結構描述，啟用類似的資料分割和存取控制。

 若要在 `application-main.yml` 檔案中啟用**多結構描述模式**，請參閱 [Blusam 組態](#ba-shared-blusam-configuration)。在此模式中，資料集可以使用共用內容載入至特定結構描述，該內容是執行時間資訊的記憶體內登錄檔。若要將資料集載入特定結構描述，請在資料集名稱前加上相關結構描述名稱。

將 KSDS 檔案載入**至多結構描述模式的特定結構描述**：

```
import com.netfective.bluage.gapwalk.bluesam.BluesamManager
import com.netfective.bluage.gapwalk.bluesam.metadata.Key;
import com.netfective.bluage.gapwalk.rt.provider.ServiceRegistry
import java.util.ArrayList;
import com.netfective.bluage.gapwalk.rt.shared.SharedContext;

// Loading a KSDS into Blusam
def map = [:]
String schema = "schema1";
String datasetName = schema+"|"+"ksdsSample";
SharedContext.get().setCurrentBlusamSchema(schema);
schema = SharedContext.get().getCurrentBlusamSchema();
map.put("bluesamManager", applicationContext.getBean(BluesamManager.class));
map.put("datasetName", datasetName);
map.put("inFilePath", "/work/samples/ksdsSampleExport");
map.put("recordLength", 49);
map.put("primaryKey", new Key(0, 18));
map.put("indexingPageSizeInMb", 25);
def service = ServiceRegistry.getService("BluesamKSDSFileLoader");
service.runService(map);
```

將大型 KSDS 檔案載入**至多結構描述模式的特定結構描述**：

```
import com.netfective.bluage.gapwalk.bluesam.BluesamManager
import com.netfective.bluage.gapwalk.bluesam.metadata.Key;
import com.netfective.bluage.gapwalk.rt.provider.ServiceRegistry
import java.util.ArrayList;
import com.netfective.bluage.gapwalk.rt.shared.SharedContext;

// Loading a Large KSDS into Blusam
def map = [:]
String schema = "schema1";
String datasetName = schema+"|"+"largeKsdsSample";
SharedContext.get().setCurrentBlusamSchema(schema);
schema = SharedContext.get().getCurrentBlusamSchema();
map.put("bluesamManager", applicationContext.getBean(BluesamManager.class));
map.put("datasetName", datasetName);
map.put("inFilePath", "/work/samples/LargeKsdsSampleExport");
map.put("recordLength", 49);
map.put("primaryKey", new Key(0, 18));
map.put("indexingPageSizeInMb", 25);
def service = ServiceRegistry.getService("BluesamLargeKSDSFileLoader");
service.runService(map);
```

此外，組態項目 （要在`application-main.yml`組態檔案中設定） 可用來微調匯入程序：
+ `bluesam.fileLoading.commitInterval`：嚴格正整數，定義一般 ESDS/KSDS/RRDS 匯入機制的遞交間隔。**不適用於大型資料集匯入。**預設為 100000。

## Blusam 組態
<a name="ba-shared-blusam-configuration"></a>

設定 Blusam 發生在`application-main.yml`組態檔案中 （或在Blusam管理主控台 -- BAC -- 應用程式獨立部署的`application-bac.yml`組態檔案中）。

Blusam 必須在兩個方面設定：
+ Blusam 儲存和快取存取組態
+ Blusam 引擎組態

### Blusam 儲存和快取存取組態
<a name="ba-shared-blusam-configuration-storage"></a>

如需有關如何使用秘密管理員或資料來源設定Blusam儲存和快取存取權的資訊，請參閱 [為大型主機執行期的 AWS 轉換設定組態](ba-runtime-config.md)。

**注意**  
關於Blusam儲存體的存取，使用的登入資料將指向具有相應權限的連線角色。若要讓Blusam引擎能夠如預期般運作，連線角色必須具有下列權限：
+ 連線至資料庫
+ 建立/刪除/更改/截斷資料表和檢視
+ 選取/插入/刪除/更新資料表和檢視中的資料列
+ 執行函數或程序

### Blusam 引擎組態
<a name="ba-shared-blusam-configuration-engine"></a>



#### 停用 Blusam 支援
<a name="ba-shared-blusam-configuration-disabling"></a>

首先，讓我們提到，透過將 `bluesam.disabled` 屬性設定為 ，可以完全停用Blusam支援`true`。應用程式啟動時，伺服器日誌中會顯示一則資訊訊息，提醒Blusam停用：

```
BLUESAM is disabled. No operations allowed.
```

在這種情況下Blusam，不需要進一步設定 ，任何使用Blusam相關功能的嘗試 （以程式設計方式或透過 REST 呼叫） 都會在 Java 程式碼執行`UnsupportedOperationException`中引發 ，並提供有關Blusam停用的相關說明訊息。

#### Blusam 引擎屬性
<a name="ba-shared-blusam-configuration-engine-properties"></a>

Blusam 引擎組態屬性會在 bluesam 金鑰字首下重新分組：

##### 強制性屬性
<a name="ba-shared-blusam-configuration-engine-mandatory-properties"></a>


+ `cache`：使用所選的快取實作進行評價。有效的值如下：
  + `ehcache`：適用於本機內嵌 ehcache 用量。請參閱上述相關的使用案例限制。
  + `redis`：用於共用遠端 redis 快取用量。這是 AWS Mainframe Modernization 受管使用案例的偏好選項。
  + `none`：停用儲存快取
+ `persistence`：以 pgsql 評價 (PostgreSQL 引擎：最低版本 10.0 – 建議版本 >=14.0
+ 資料來源參考： `<persistence engine>.dataSource` 會指向 Blusam 儲存體連線的 dataSource 定義，此定義在組態檔案中的其他位置。通常命名為 `bluesamDs` 。

**注意**  
每當 Redis 用作快取機制時，無論是用於資料或鎖定 （請參閱下文），都必須設定對 Redis 執行個體的存取。如需詳細資訊，請參閱[大型主機執行期 AWS 轉換中可用的 Redis 快取屬性](ba-runtime-redis-configuration.md)。

##### 可選屬性
<a name="ba-shared-blusam-configuration-engine-optional-properties"></a>

Blusam 鎖定：屬性的字首為 `locks`
+ `cache`：只有可用值為 `redis` ，以指定將使用以 redis 為基礎的鎖定機制 （也會在以 redis 為基礎的Blusam儲存快取時使用）。如果 屬性遺失或未設定為 `redis` ，則會改用預設記憶體內鎖定機制。
+ `lockTimeOut`：正長整數值，在嘗試鎖定已鎖定的元素標記為失敗之前，以毫秒表示的逾時。預設為 `500`。
+ `locksDeadTime`：正長整數值，代表以毫秒為單位的最長時間，應用程式可以保留鎖定。鎖定會自動標記為過期，並在經過時間之後釋放。預設為 `1000` ；
+ `locksCheck`：字串，用於定義目前鎖定管理員使用的Blusam鎖定檢查策略，關於過期的鎖定移除。在以下值中挑選：
  + `off`：不執行檢查。不鼓勵，因為可能會發生死鎖。
  + `reboot`：檢查會在重新啟動或應用程式啟動時執行。此時會釋出所有過期的鎖定。這是預設值。
  + `timeout`：檢查會在重新啟動或應用程式開始時間執行，或在嘗試鎖定資料集期間逾時過期時執行。過期的鎖定會立即釋放。

寫入落後機制：屬性的字首為`write-behind`索引鍵：
+ `enabled`： `true` （預設和建議值） 或 `false` ，以啟用或停用寫入落後機制。停用機制將大幅影響寫入效能，而且不建議這麼做。
+ `maxDelay`：要觸發執行緒的最大持續時間。預設為 `"1s"`（一秒）。保留預設值通常是個好主意，除非特定條件需要調校此值。在任何情況下，該值都應保持低 (3 秒內）。延遲字串的格式為： `<time unit>`要在下列值中挑選`<integer value><optional whitespace><time unit>`：
  + `"ns"`：奈秒
  + `"µs"`：微秒
  + `"ms"`：毫秒
  + `"s"`： 秒
+ `threads`：專用寫入落後執行緒的數量。預設為 `5` 。您需要根據執行Blusam引擎之主機的運算能力來調整此值。這與使用更高的值無關，希望提高效能，因為限制因素將成為儲存 RDBMS 處理許多並行批次查詢的能力。建議值通常在 4-8 的範圍內。
+ `batchSize`：正整數，代表批次中要大量處理到執行緒的記錄數目上限。其值必須介於 1 到 32767 之間。預設為 `10000`。使用 `1`做為值會破壞機制的目的，以避免使用原子更新查詢；使用的適當最小值約為 `1000` 。

內嵌 EhCache 微調：屬性的字首為`ehcache`索引鍵：
+ `resource-pool`: 
  + `size`：內嵌快取的配置記憶體大小，以字串表示。預設為 `"1024MB"`(1 GB)。針對託管Blusam引擎之機器的可用記憶體，以及應用程式正在使用的資料集大小進行調整。大小字串的格式為： `<memory-unit>`要在下列值中挑選`<integer value><optional whitespace><memory unit>`：
    + `B`：位元組
    + `KB`：KB
    + `MB`：MB
    +  `GB`： GB
    + `TB`：TB
  + `heap`： `true`或 `false` ，指出快取是否會耗用 JVM 堆積記憶體。預設為 `true`（快取效能的最快選項，但快取儲存會耗用 JVM 堆積上 RAM 記憶體的記憶體）。將此屬性設定為 `false`會切換到離區記憶體，這會較慢，因為需要與 JVM 堆積交換。
+ `timeToLiveMillis`：快取項目在被視為過期和移除之前保留在快取中的持續時間 （以毫秒為單位）。如果未指定此屬性，快取項目預設不會自動過期。

##### 大型資料集的選用屬性：
<a name="ba-shared-blusam-optional-properties-large-data-sets"></a>

分頁索引的本機化記憶體內快取：
+ `indexesPrefetchWindowSize`：此屬性適用於使用 Redis 快取啟用操作的 Blusam 大型資料集。它指定可用於儲存分頁索引的記憶體內快取大小上限 （以 MB 為單位）。預設值為 0。此值可能會根據可用的系統記憶體和處理中的資料集大小進行調整。

範例組態程式碼片段：

```
dataSource:
  bluesamDs:
    driver-class-name: org.postgresql.Driver
    ...
    ...
bluesam:
  locks:
    lockTimeOut: 700
  cache: ehcache
  persistence: pgsql
  ehcache:
    resource-pool:
      size: 8GB
  write-behind:
    enabled: true
    threads: 8
    batchsize: 5000
    indexesPrefetchWindowSize: 25  
  pgsql:
    dataSource : bluesamDs
```

##### 多結構描述組態屬性
<a name="ba-shared-blusam-configuration-multi-schema"></a>
+ `multiSchema`：false （預設值） 或 true，以停用或啟用適用於 的多結構描述模式 Blusam - 可用的 4.4.0 版。
+ `pgsql`: 
  + `schemas`：應用程式將在多結構描述模式中用於 的結構描述名稱清單Blusam。
  + `fallbackSchema`：用於多結構描述模式的備用結構描述名稱。如果在目前的結構描述內容中找不到資料集，此結構描述將用於該資料集上的 Blusam相關操作。

範例組態程式碼片段 （針對 啟用多結構描述模式Blusam)：

```
dataSource:
  bluesamDs:
    driver-class-name: org.postgresql.Driver
    ...
    ...
bluesam:
  locks:
    lockTimeOut: 700
  cache: ehcache
  persistence: pgsql
  ehcache:
    resource-pool:
      size: 8GB
  write-behind:
    enabled: true
    threads: 8
    batchsize: 5000 
  multiSchema: true 
  pgsql:
    dataSource : bluesamDs
    schemas: 
      - "schema1"
      - "schema2" 
      - "schema3"
    fallbackSchema: schema3
```

**注意**  
Blusam 中繼資料結構描述，包括多結構描述模式 `application-main.yml` 檔案中列出的結構描述，如果不存在且使用者具有足夠的權限，則會在Blusam資料庫中建立結構描述。

## Blusam DD 檔案組態
<a name="ba-shared-blusam-dd-file-configuration"></a>

這些選項可用於 groovy 中的Blusam檔案組態 (JCL 中的資料定義）：
+ `largeKSDS()`：表示大型 KSDS 性質。使用時，如果指定的檔案是遺失的檔案，而且應該建立該檔案 （取決於 OPEN 模式和選用的檔案選項），則會建立大型 KSDS 檔案及其索引表。

  ```
  .bluesam("TESTFILE").dataset("TESTFILE").largeKSDS().build()
  ```
+ `indexPageSize(Integer param)`：指定要建立之索引資料表的頁面大小 （以 mb 為單位）。適用於具有 `largeKSDS()`選項的檔案。的值`param`應嚴格為正值。預設值 15 將用於無效的`param`值。

  ```
  .bluesam("TESTFILE").dataset("TESTFILE").largeKSDS().indexPageSize(15).build()
  ```

 您可以在位於 `entities/src/main/resources/ds-config.yml`（或組態檔案的其他位置） 的 `ds-config.yml` 檔案中設定預設檔案組態。當未將特定檔案組態提供給執行單位時，這些設定可做為備用組態。中支援所有 Bluesam 檔案組態選項`ds-config.yml`。

```
TESTFILE:
 provider: Bluesam
 dataset: TESTFILE
 largeKSDS: true
 indexPageSize: 15
```

## Blusam 管理主控台
<a name="ba-shared-blusam-administration-console"></a>

Blusam 管理主控台 (BAC) 是一種 Web 應用程式，用於管理Blusam儲存體。如需 BAC 的詳細資訊，請參閱 [AWS 大型主機Blusam管理主控台的轉換](ba-shared-bac-userguide.md)。

## 附錄
<a name="ba-shared-blusam-appendix"></a>



### 一般資料集中繼資料屬性
<a name="ba-shared-blusam-metadata"></a>

一般資料集中繼資料序列化屬性清單：
+ 名稱 （資料集的）
+ 類型 (KSDS、 LargeKSDS、ESDS、 LargeESDS 或 RRDS)
+ 快取暖機旗標 （是否應在伺服器啟動時預先載入快取中的資料集）
+ 壓縮用量旗標 （以壓縮或原始格式存放記錄）
+ 建立日期
+ 上次修改日期
+ 固定長度記錄旗標 （資料集記錄的長度是否相同）
+ 記錄長度 -- 僅適用於固定記錄長度
+ 頁面大小 （用於自訂用於在需要時預先載入快取的分頁 sql 查詢）
+ 大小 （資料集的大小 - 記錄的累積長度）
+ 上次偏移 （偏移，即新增至資料集之最新記錄的 RBA)
+ next offset （用於將新記錄新增至資料集的下一個可用位移）
+ 如果有意義的，定義資料集所使用的金鑰；每個金鑰都由其類型 （備用金鑰集合的主要或部分） 和三個屬性定義：
  + 位移：索引鍵值開始位元組記錄中的位置；
  + length ：金鑰值的位元組長度。因此，索引鍵值是位元組陣列，這是記錄的子集，從位置 開始`key offset`到結束`key offset + length - 1`；
  + 允許的重複旗標：金鑰是否接受重複 （設定為 true 以允許重複）。

### 估計指定資料集的記憶體使用量
<a name="ba-shared-blusam-memory"></a>

對於中小型資料集，中繼資料 （各種金鑰的大小和索引） 將完全載入記憶體。為託管用於執行現代化應用程式的伺服器之機器配置適當的資源，需要找出Blusam資料集產生的記憶體消耗量，特別是中繼資料。本節提供相關運算子的實際答案。

指定的公式僅適用於中Blusam小型資料集，而不是使用「大型」儲存策略。

#### Blusam 資料集中繼資料
<a name="ba-shared-blusam-metadata-parts"></a>

對於Blusam資料集，中繼資料分為兩個部分：
+ 核心中繼資料：保留有關資料集的全域資訊。相較於內部中繼資料，此項目的記憶體使用量可視為可忽略。
+ 內部中繼資料： 保留記錄大小和金鑰索引的相關資訊；當資料集不是空的時，這是載入託管現代化應用程式的應用程式伺服器時耗用記憶體的原因。以下各節詳細說明耗用記憶體如何隨著記錄數量而成長。

#### 計算內部中繼資料足跡
<a name="ba-shared-blusam-footprint-calculation"></a>



##### 記錄大小映射
<a name="ba-shared-blusam-footprint-sizesmap"></a>

首先，內部中繼資料會儲存映射，以保留每個記錄的大小 （以整數形式），並指定其 RBA （相對位元組地址，以長數字形式存放）。

該資料結構的記憶體使用量，以位元組為單位： `80 * number of records`

這適用於所有資料集類型。

##### 索引
<a name="ba-shared-blusam-footprint-indexes"></a>

關於 KSDS 的主索引鍵或 ESDS 和 KSDS 上的備用索引鍵，用量的計算取決於兩個因素：
+ 資料集中的記錄數目；
+ 金鑰的大小，以位元組為單位。

下圖顯示根據金鑰大小 (x 軸），每個記錄的金鑰索引大小 (y 軸）。

![顯示每個記錄索引大小的折線圖，隨著索引鍵大小從 0 增加到 80，從 83 增加到 157。](http://docs.aws.amazon.com/zh_tw/m2/latest/userguide/images/indexes_size_per_record.png)


用於評估資料集之指定索引鍵的佔用量的對應公式為：

```
index footprint = number of records * ( 83 + 8 (key length / 8))
```

其中 ' / ' 代表整數分割。

範例：
+ 資料集 1：
  + 記錄數目 = 459 996
  + 因此，金鑰長度 = 15 （金鑰長度 / 8) = 1
  + 索引足跡 = 459 996 \* (83 \+ (8\*1)) = 41 859 636 位元組 (= 約 39 MB)
+ 資料集 2：
  + 記錄數目 = 13 095 783
  + 金鑰長度 = 18，因此 （金鑰長度 / 8) = 2
  + 索引足跡 = 13 095 783 \* (83 \+ (8\*2)) = 1 296 482 517 位元組 ( = 大約 1.2 GB)

指定資料集的總佔用空間是所有索引鍵的所有佔用空間和記錄大小映射的佔用空間總和。

例如，以只有單一金鑰的範例資料集 2 為例，全域足跡為：
+ 記錄大小映射：13 095 783 \* 80 = 1 047 662 640 位元組
+ 索引鍵：1 296 482 517 位元組 （請參閱上述）
+ 總使用量 = 2 344 145 157 位元組 ( = 2.18 GB 大約）