語言環境介面參考手冊

語言環境介面函數

在您撰寫語言環境時,您必須決定要提供哪些介面。 而您的決定必須視您想要語言環境從事哪些作業而定。 例如,若語言環境要存取資料庫資料,或是要編寫語言, 則兩者所使用的選項會有所不同。

Net.Data 對每一種語言環境使用四個介面函數。

  1. dtw_initialize()
  2. dtw_execute()
  3. dtw_getNextRow()
  4. dtw_cleanup()

您可提供這些函數的其中一個或數個函數。其中有三種函數是選用性的,但是每一個語言環境都必須要有 dtw_execute() 介面函數。 如果 Net.Data 巨集參照沒有 dtw_execute() 介面函數的語言環境, Net.Data 將傳回錯誤訊息同時停止處理 Net.Data 巨集。

欲呼叫語言環境,您可在 Net.Data 巨集的 FUNCTION 區塊中參照它。 如果語言環境有定義下列函數,則您可以呼叫語言環境介面函數:

當 Net.Data 呼叫一個使用語言環境的函數時,它會用下列步驟來呼叫該語言環境:

  1. 如果 Net.Data 已定義給這個語言環境,且如果它是第一個語言環境函數呼叫, 則 Net.Data 會呼叫 dtw_initialize()。此函數會執行語言環境所要求的任何起始設定作業, 例如連接至資料庫,或是配置變數。
  2. Net.Data 呼叫 dtw_execute() 以處理巨集 FUNCTION 區塊,該區塊含有語言環境必須處理的陳述式或指令。
  3. 在成功的回覆中,如果 dtw_execute() 指示應呼叫 dtw_getNextRow(), Net.Data 就會呼叫 dtw_getNextRow()。
  4. 當 Net.Data 巨集處理程序完成時,如果已將 dtw_cleanup() 函數定義在語言環境, 而且之後有傳回 Web 伺服器的話,Net.Data 就會呼叫 dtw_cleanup(), 以清除環境 (例如,切斷與資料庫的連線,或釋放資源)。

下列各節將為您說明介面函數:

dtw_initialize()

格式:
int dtw_initialize(dtw_lei_t *);

dtw_initialize() 介面函數會執行語言環境所要求的任何特殊起始設定, 例如連接資料庫或配置資源。這個介面函數是選用性的。

就每一個巨集而言,Net.Data 只呼叫一次某語言環境的 dtw_initialize() 介面函數, 也就是當 Net.Data 第一次呼叫該語言環境的 FUNCTION 區塊。後續的語言環境呼叫會略過 dtw_initialize() 介面函數的呼叫。

這個介面函數不會影響訊息區塊處理。正值或零的回覆碼表示繼續處理; 負值回覆碼表示不繼續處理。如果回覆碼為非零值, 而且 dtw_lei_t 結構中的 default_error_message 欄位內已定義預設的訊息, 則 Net.Data 會發出預設訊息;如果預設訊息不存在,則 Net.Data 會發出錯誤訊息。

dtw_execute()

格式:
dtw_execute(dtw_lei_t *);

dtw_execute() 介面函數會處理每一個函數呼叫中的 FUNCTION 區塊。 FUNCTION 區塊可以包含將在 dtw_execute() 函數中處理的陳述式或指令。

每當 Net.Data 巨集呼叫函數時 (該函數參照語言環境),都會呼叫 dtw_execute() 介面函數。 當 dtw_execute() 介面函數完成時,Net.Data 會檢查回覆碼及 dtw_lei_t 結構的旗號欄位。如果回覆碼為 0,則 Net.Data 會加以檢查,以確定 DTW_LE_CONTINUE 是否設定在旗號欄位中。 如果是的話,則 Net.Data 將會呼叫 dtw_getNextRow() 介面函數 (請參閱dtw_getNextRow())。如果回覆碼非零,則 Net.Data 將檢查廣域及本端的 MESSAGE 區塊,以決定下一個動作的方向。如果 MESSAGE 區塊不存在,或者 Net.Data 無法在任一個 MESSAGE 區塊中找到符合回覆碼的項目,則 Net.Data 將在回覆碼為正值時繼續處理,否則的話它將在回覆碼為負值時結束巨集處理。

您可以令 dtw_execute() 介面函數執行所有產生報表區塊程序之輸入所需的處理程序, 以使執行效能最佳化。 例如,dtw_execute() 介面函數可產生要在報表區塊階段處理的整個表格。

dtw_getNextRow()

格式:
int dtw_getNextRow(dtw_lei_t *);

dtw_getNextRow() 介面函數會取回輸入,以進行一次一列的 Net.Data REPORT 區塊處理。只要 DTW_LE_CONTINUE 旗號設定為需要為該表格處理其他列的資料,就會呼叫這個介面函數。 此介面函數是可選用的。

限制:只有 Net.Data 在 OS/400 或 OS/390 作業系統上執行的情況下, 才會呼叫這個介面函數。

發生下列狀況時,Net.Data 會呼叫 dtw_getNextRow():

當 dtw_execute() 函數將 DTW_LE_CONTINUE 旗號設定為 on 且回覆碼為 0 時,Net.Data 會執行下列步驟︰

  1. 處理 REPORT 區塊標頭。
  2. 呼叫語言環境的 dtw_getNextRow() 介面函數以擷取橫列。
  3. 為 dtw_getNextRow() 介面函數的回覆值處理訊息區塊。
  4. 處理 ROW 區塊。
  5. 判定 dtw_getNextRow() 是否有啟動 DTW_LE_CONTINUE 旗號:

呼叫 dtw_getNextRow() 後,會設定 dtw_lei_t 結構中的橫列欄位以指向橫列物件。 欲處理橫列物件,請使用 Net.Data 公用程式函數 dtw_row_SetCols() 及 dtw_row_SetV()。 Net.Data 會假設在第一次呼叫 dtw_getNextRow() 介面函數後, 橫列物件會包含該表格的直欄標題。 後續的呼叫包含實際的表格資料。

只要 DTW_LE_CONTINUE 設定在旗號欄位中且回覆碼為 0,則會繼續呼叫 dtw_getNextRow() 函數。 如果回覆碼非零,則 Net.Data 會檢查廣域及本端的 MESSAGE 區塊,以決定下一個動作的方向。 如果 MESSAGE 區塊不存在,或者 Net.Data 無法在任一個 MESSAGE 區塊中到符合的項目,則 Net.Data 將在回覆碼為正值時繼續處理,否則的話它將在回覆碼為負值時結束巨集處理。

dtw_cleanup()

格式:
int dtw_cleanup(dtw_lei_t *);

使用 dtw_cleanup() 介面函數以清除語言環境。 如果您使用 dtw_initialize() 來配置資源,請考慮使用此介面函數。針對切斷資料庫的連線或釋放資源等作業使用此函數。 這個介面函數是選用性的。

處理 Net.Data 要求時,Net.Data 會在巨集處理正常或不正常結束時, 呼叫語言環境的 dtw_cleanup() 介面函數。如果沒有製作任何的語言環境呼叫函數,則不呼叫此介面。

如果巨集異常終止的話,則 Net.Data 會在 dtw_lei_t 結構中的旗號欄位內設定 DTW_END_ABNORMAL。 下面列示出 Net.Data 將異常終止的條件:

如果語言環境的介面函數使用要在介面函數之間傳遞的參數來設定 le_opaque_data 欄位, 請在處理程序結束時,用 dtw_cleanup() 來釋放與欄位相關的資源。

這個介面函數不會影響訊息區塊處理。如果回覆值不是 0,就會發出預設的訊息; 如果沒有預設訊息的存在,則 Net.Data 會發出警告訊息。


[ 頁面頂端 | 前一頁 | 下一頁 | 目錄 | 索引 ]