ALTER EXTRACT

為下列用途使用 ALTER EXTRACT：

• 若要變更使用 ADD EXTRACT 命令建立的 Extract 群組屬性。

• 將歷程檔遞增至序列中的下一個檔案。

• 升級成整合式擷取組態。

• 從整合式擷取組態降級。

• 將任何指定的 Db2 for i 日記帳定位在特定的日記帳序號。

使用此命令之前，請先使用 STOP EXTRACT group_name 命令停止 Extract。

語法

ALTER EXTRACT group-name
         [, BEGIN {NOW | yyyy-mm-dd[ hh:mi:[ss[.cccccc]]]} |
|            [, EXTRBA archive-offset-number]
|            [, ADD_EXTRACT_attribute  | SCN value]
|            [, LSN
|            [, EOL
|            [, DESC
|            [ CRITICAL    [ YES | NO ]     ]
|            [ ENCRYPTIONPROFILE     encryption-profile-name]
|            [ PROFILE
|                [ AUTOSTART   [ YES | NO ]
|                  [ DELAY     delay-number   ] ]
|                  [ AUTORESTART [ YES | NO ]
|                       [ RETRIES          retries-number ]
|                       [ WAITSECONDS      wait-number    ]
|                       [ RESETSECONDS     reset-number   ]
|                       [ DISABLEONFAILURE [ YES | NO ] ] ] ]
|             [ LOGNUM lognum]
|             [ LOGPOS logpos

Db2 支援下列 ALTER EXTRACT 選項，可供 i 定位指定日誌的 Extract：

ALTER EXTRACT {BEGIN {NOW | yyyy-mm-ddT[ hh:mi:[ss[.cccccc]]Z]}
[JOURNAL journal_library/journal_name [JRNRCV receiver_library/
  receiver_name]] |
, EOL [JOURNAL journal_library/journal_name
  [JRNRCV receiver_library/receiver_name]] |
, SEQNO sequence_number [JOURNAL journal_library/journal_name
  [JRNRCV receiver_library/receiver_name]]}

BEGIN {NOW | yyyy-mm-ddT[ hh:mi:[ss[.cccccc]]]Z} [JOURNAL journal_library/journal_name [JRNRCV receiver_library/ receiver_name]] | , EOL [JOURNAL journal_library/journal_name [JRNRCV receiver_library/receiver_name]] | , SEQNO sequence_number [JOURNAL journal_library/journal_name [JRNRCV receiver_library/receiver_name]]

這些 IBM for i 選項允許在全域起點使用 ADD EXTRACT 發出之後，進行日誌特定 Extract 定位。具有 ALTER EXTRACT 的特定日記帳位置集不會影響先前以 ADD EXTRACT 或 ALTER EXTRACT 設定的任何全域位置；不過全域位置集若使用 ALTER EXTRACT，則會覆寫先前在相同 Extract 組態中設定的任何特定日記帳位置。

備註：SEQNO，與 `ALTER 中的日記帳搭配使用時

          EXTRACT`, is the journal sequence number that is relative to that specific journal, not the system sequence number that is global across journals.
          {: .infoboxnote}

group-name

要更改之 Extract 群組的名稱。

{BEGIN {NOW

Tyyyy-mm-dd[ hh:mi:[ss[.cccccc]]]Z}

NOW

對於 Db2 LUW 以外的所有資料庫，NOW 會指定 ALTER EXTRACT 命令的發行時間。

NOW 指定 ALTER EXTRACT 命令的發行時間。

若為 Db2 LUW，只有確認及結束異動記錄包含時戳，因此只能計算出與這些時戳相對的 Extract 開始位置。這是 Oracle GoldenGate 所使用的 API 限制。請注意，依時戳定位並不準確，而且耗費的時間可能也很長。建議儘可能使用 LRI 或 EOL 選項。

YYYY-MM-DDThh:mm:ssZ

以指定格式表示的日期與時間 (時戳)。例如，2017-07-14T14:54:45Z。

yyyy-mm-dd[ hh:mi:[ss[.cccccc]]]

以指定格式表示的日期與時間 (時戳)。針對整合式模式的 Oracle Extract，此時戳值必須大於向資料庫註冊 Extract 的時戳。

在 SQL Server 異動日誌中依時戳定位受下列 SQL Server 特性影響：

• SQL Server 異動日誌中記錄的時戳時間粒度為 3.3333 微秒 (ms)。兩個異動若同樣都以 3.3333 微秒時間間隔開始，此程度的時間粒度可能就不允許在兩個異動之間依時間定位。

• 並非每筆 SQL Server 日誌記錄都會記錄時戳，只有開始並確認異動的記錄，以及其他不包含資料的記錄才會記錄時戳。

• SQL Server 時戳不是來自系統時鐘，而是來自使用中的個別處理器特定的內部時鐘。這個時鐘一秒會更新數次，但在更新過程中可能會與系統時鐘不同步。因此會降低依時間定位的精確度。

• 日誌備份檔案記錄的時戳可能不會準確對應至備份中記錄的時間 (不過相差不到一秒)。

精確定位至 LSN。

在 PostgreSQL 中依時戳定位包括下列情況：

• 案例 1

  如果 track_commit_timestamp 是 off，則不論使用何種定位方法，當 Extract 處理作業啟動時，將會顯示下列輸出：

  2020-04-29 02:15:54 INFO OGG-01517 Position of first record processed LSN: 0/2222C20, Jan 1, 1970 12:00:00 PM.

• 案例 2

  如果在註冊 Extract 之前啟用 track_commit_timestamp，則在來源資料庫中植入記錄後，將會顯示正確的時間戳記，如下列範例所述：

  2020-04-29 02:19:07 INFO OGG-01515 Positioning to begin time Apr 29,2020 2:18:38 AM.

• 案例 3

  如果在註冊 Extract 之後啟用 track_commit_timestamp，則可能會有較舊的記錄存在於日誌中，而日誌中未使用關聯的 transaction ID 建立確認時戳。在此情況下，如果 Extract 未取得時戳，則會改用情況 1 中提及的預設時戳。輸出與下列類似：

  020-04-29 01:55:07 INFO OGG-01517 Position of first record processed LSN: 0/221D028, Jan 1, 1970 12:00:00 PM.

• 如果複製插槽已移到別處，則無法指定過去時戳。

START

適用於 PostgreSQL。

新增 Extract，而不使用 BEGIN NOW 或 LSN。Extract 將會從複製插槽重新啟動位置自動啟動。

ADD_EXTRACT_attribute

您可以變更任何使用 ALTER EXTRACT 命令指定的屬性，但下列除外：

• 更改以 EXTTRAILSOURCE 選項指定的 Extract。

• 更改以 THREADS 選項指定的 RAC 繫線數目。

針對這些例外，刪除 Extract 群組，然後再新增一次。

若使用 BEGIN 選項，請勿結合陳述式中的其他選項。發出個別敘述句，例如：

ALTER EXTRACT exte, BEGIN 2019-01-01
ALTER EXTRACT exte, ETROLLOVER
ALTER EXTRACT exte, SCN 789000

如果對「整合式擷取」使用 SCN 或 BEGIN 選項，則需要 DBLOGIN，且指定的 SCN 或時戳值不可低於外送伺服器的第一個 SCN 或時戳。若要尋找外送伺服器的第一個 SCN，請發出下列命令：

INFO EXTRACT group_name, SHOWCH DETAIL

下列範例中列出第一個 SCN 值：

Integrated Extract outbound server first scn: 0.665884 (665884)

EXTRBA offset_number

適用於 Db2 z/OS。

指定異動日誌內用來開始擷取資料的相對位元組位址。

必要格式為 0Xnnn，其中 nnn 是 1 到 20 位數 (第一個字元是數字零，第二個字元可以是大寫或小寫的字母 x) 結束。

EOL

適用於 Db2 for i、Db2 LUW、MySQL、PostgreSQL 及 SQL Server。

將處理設定為從將寫入下一筆記錄的日誌檔 (或日記帳) 結尾開始。將不會擷取任何作用中的異動。

對於 Db2 LUW，它會設定處理從日誌檔中的作用中 LRI 值開始。作用中的 LRI 是將寫入下一筆記錄之日誌檔結尾的位置。將不會擷取任何作用中的異動。

對於 PostgreSQL，EOL 需有 DBLOGIN 才能定位。

若為 MySQL，它會尋找與檔案結尾相對應的位置，然後從那裡開始讀取異動。若持續將資料寫入二進位日誌，EOL 位置就會不精確。

TRANLOG LRI LRI_number

(Db2 LUW) 您可以對 Db2 LUW 系統使用此選項，來指定檢查點異動日誌的 LRI 記錄值。

對於 PostgreSQL，EOL 需有 DBLOGIN 才能定位。

REPORT file_name

指定 Extract 報表檔案在 Oracle GoldenGate 目錄內預設為 dirrpt 之外的位置的完整路徑名稱。

SCN value

適用於 Oracle。

在重做日誌中具有指定 Oracle 系統變更編號 (SCN) 的異動啟動 Extract。針對 Extract，此 SCN 值必須大於向資料庫註冊 Extract 的 SCN。對於 SCN 或 BEGIN 選項，則需要 DBLOGIN，且指定的 SCN 或時戳值不能低於外送伺服器的第一個 SCN 或時戳。

LSN value

適用於 Db2 z/OS、PostgreSQL 及 SQL Server。

指定開始擷取資料的交易 LSN。此選項的別名為 EXTLSN。

對於 Db2 z/OS，LSN 值可以是一系列十六進位數字或一系列十進位數字。如果是十六進位格式，則前面必須加上 0X 或 0x，後面接著 1 到 20 個十六進位數字：0-9、a-g 或 A-G。如果是十進位格式，則沒有前置碼，並且使用 1-25 位十進位數字：0-9。

PostgreSQL 的 LSN 值可以是 hi 或 lo。將日誌檔進入點的值設為 hi。Lo 是日誌檔中的位移。LSN 位置應該位於複製插槽重新啟動位置與寫入日誌目前位置之間。如果指定的位置本身就在所提及的範圍內，則 Extract 將會發出錯誤。

若為 SQL Server，LSN 會指定開始擷取資料的交易 LSN。此選項的別名為 EXTLSN。

指定的 LSN 應存在為在 cdc.lsn_time_mapping 系統表格中找到的有效 tran_begin_lsn，否則 Extract 將嘗試定位在提供的 LSN 的值之後。

SQL Server 的有效 LSN 規格包含下列項目：

• 以冒號區隔的十六進位字串 (8:8:4)，使用前置零與 0X前置碼填補，例如 0X00000d7e:0000036b:0001

• 以冒號區隔的十六進位字串，使用 0X 前置碼但不使用前置零，例如 0Xd7e:36b:1

您可以查詢下列範例以尋找可用的最小 LSN：

SELECT min([tran_begin_lsn]) FROM [cdc].[lsn_time_mapping] with (nolock) where tran_id <> 0x00

下列範例顯示 Db2 z/OS LSN 值的用法：

範例 1：

ALTER EXTRACT extn TRANLOG, LSN 0xDEE40E4F27A3245400

範例 2：

ALTER EXTRACT extn TRANLOG, LSN 22216433159121980904448

下列範例顯示 SQL Server 的 LSN 值：

ALTER EXTRACT extn TRANLOG, LSN 0X00000d7e:0000036b:0001

LOGNUM

適用於 MySQL。

這是日誌檔編號。例如，如果必要的記錄檔名稱為 test.000034，則 LOGNUM 值為 34。Extract 將會搜尋此日誌檔。注意：在 Microservices Architecture 中，如果 LOGNUM 值在值前面包含零，ALTER EXTRACT 就會失敗。例如，ALTER EXTRACT ext1, TRANLOG, LOGNUM 000001, LOGPOS 0 會失敗。相反地，將此範例設為 LOGNUM 為 1 以便成功。

LOGPOS

適用於 MySQL。

這是日誌檔中的事件偏移值，用於識別特定的異動記錄。事件偏移值儲存在日誌記錄的標頭區段中。若要在 binlog 檔案的開頭定位，請將 LOGPOS 設為 0。

ETROLLOVER

用於需要重新定位主要 Extract 並重新產生其歷程檔的手動復原情況，以及用於從舊版的 Oracle GoldenGate 升級。

讓 Extract 在重新啟動時建立新的歷程檔拷貝，並遞增至歷程檔序列中的下一個檔案，這需要將讀取器 (汲取或 Replicat) 手動重新定位至新的歷程檔序號。

有了 ETROLLOVER，「擷取」會在指定的 SCN 之後擷取所有記錄，不論是否已擷取並寫入歷程檔，都會開始 Extract。若無 ETROLLOVER，Extract 將可略過擷取任何已擷取並寫入歷程檔的記錄。

從 19c 開始，在分送服務的處理過程中：

• 如果來源部署上的主要 Extract 使用目標歷程檔 ETROLLOVER 升級，則 theDistribution Service 會自動偵測來源歷程檔 ETROLLOVER，並開始從下一個輸入歷程檔讀取。這與資料汲取 ALTER EXTRACT groupname EXTSEQNO seqno+1 EXTRBA 0 的命令相同。

• 升級「分佈服務」之後，會在重新啟動時自動對輸出歷程檔執行 ETROLLOVER，並正確寫入下一個歷程檔。這與資料汲取 ALTER EXTRACT groupname ETROLLOVER 相同。

DESC ‘description’

指定群組的說明，例如 'Extracts account_tab on Serv1'。以單引號括住描述。您可以使用簡寫關鍵字 DESC 或完整字 DESCRIPTION。

ENCRYPTIONPROFILE

指定 Extract 的加密設定檔名稱。此名稱有大小寫之別，因此您必須使用以 ADD EXTRACT 輸入的確切名稱。

GTIDSET gtidset

適用於 MySQL。

使用 MySQL GTID 式擷取之 GTID 集選項的 positiob 定位類型，指定 Extract 的起始定位。GTID 集支援的 MySQL 來源為 MySQL Server 8.0、MySQL Server 5.7、MySQL Database Service (MDS)。支援的 GTID 集大小上限為 64 KB。

語法：

ALTER EXTRACT extract_name, TRANLOG, GTIDSET gtidset

下列範例包括 GTID 集有效格式的所有組合。

範例 1：

ALTER EXTRACT exte, TRANLOG, GTIDSET "E11FA47-71CA-11E1-9E33-C80AA9429562:4"

範例 2：

ALTER EXTRACT exts, TRANLOG, GTIDSET "3E11FA47-71CA-11E1-9E33-C80AA9429562:1-10"

範例 3：

ALTER EXTRACT extn, TRANLOG, GTIDSET "3E11FA47-71CA-11E1-9E33-C80AA9429562:1-3:11:47-49"

範例 4：

ALTER EXTRACT extw, TRANLOG, GTIDSET "2174B383-5441-11E8-B90A-C80AA9429562:1-3,24DA167-0C0C-11E8-8442-00059A3C7B00:1-19"

備註：如範例 4 所示，當 GTID 集包含多個 UUID 時，為了形成 REST API 要求，此 GTID 集會使用逗號分隔符號細分為多個 GTID 集。

CRITICAL

指示處理作業對於部署是否至關重要。

PROFILE

自動啟動設定檔的名稱。此名稱有大小寫之別，因此您必須使用以 ALTER EXTRACT 輸入的確切名稱。

AUTOSTART

指定受管理的處理作業是否要在管理服務啟動時自動啟動。預設值為 YES。

RETRIES

作業取消重試前應重新啟動的次數上限。這是選擇性選項。

WAITSECONDS

計算重試次數的持續時間 (秒)。

RESETSECONDS

重設計算重試次數的持續時間。

DISABLEONFAILURE

如果設為 TRUE，則重試次數用完時會停用工作。

INFO EXTRACT group-name, SHOWCH DETAIL

下列範例中列出第一個 SCN 值：

Integrated Extract outbound server first scn: 0.665884 (665884)

範例

---

下列範例將 Extract 更改為從 2019 年 1 月 1 日起開始處理資料。

ALTER EXTRACT exte, BEGIN 2019-01-01

---

下列範例將 Extract 更改為在歷程檔中的特定位置開始處理資料。

ALTER EXTRACT exte, EXTSEQNO 26, EXTRBA 338

---

下列範例將 SQL Server 環境中的 Extract 更改為在特定 LSN 啟動。

ALTER EXTRACT exte, LSN 0Xd7e:36b:1

---

下列範例將 Extract 更改為遞增至歷程檔序列中的下一個檔案。

ALTER EXTRACT exte, ETROLLOVER

---

下列範例將 Extract 更改為升級成整合式擷取。

ALTER EXTRACT exte, UPGRADE INTEGRATED TRANLOG

---

下列命令使用 ETROLLOVER 來避免使用反向 SCN 778899 來篩選重複的記錄。

ALTER EXTRACT exte, SCN 778899
ALTER EXTRACT exte ETROLLOVER
START EXTRACT exte

如果您未使用 ETROLLOVER，則如果您將 Extract 變更為先前的 SCN 值，它將不會處理重複的記錄。更改 Extract 以篩選重複記錄的命令如下：

ALTER EXTRACT exte, SCN 778899
START EXTRACT exte

---

以下顯示 IBM for i 日誌開始點的 ALTER EXTRACT。

ALTER EXTRACT exte, SEQNO 1234  JOURNAL accts/acctsjrn

---

以下顯示 IBM for i 日誌與接收者起點的 ALTER EXTRACT。

ALTER EXTRACT exte, SEQNO 1234 JOURNAL accts/acctsjrn JRNRCV accts/jrnrcv0005

---

下列範例更改 Db2 LUW 系統上的 Extract。

ALTER EXTRACT exte, TRANLOG LRI 8066.322711

---

以下範例顯示搭配 PostgreSQL 使用的 ALTER EXTRACT 選項：

ALTER EXTRACT exte, EOL
ALTER EXTRACT POSTEXT, LSN 0/156784
ALTER EXTRACT POSTEXT, BEGIN 2022-02-18T14:50:43.4230Z