在您撰寫語言環境時,您必須決定要提供哪些介面。 而您的決定必須視您想要語言環境從事哪些作業而定。 例如,若語言環境要存取資料庫資料,或是要編寫語言, 則兩者所使用的選項會有所不同。
Net.Data 對每一種語言環境使用四個介面函數。
您可提供這些函數的其中一個或數個函數。其中有三種函數是選用性的,但是每一個語言環境都必須要有 dtw_execute() 介面函數。 如果 Net.Data 巨集參照沒有 dtw_execute() 介面函數的語言環境, Net.Data 將傳回錯誤訊息同時停止處理 Net.Data 巨集。
欲呼叫語言環境,您可在 Net.Data 巨集的 FUNCTION 區塊中參照它。 如果語言環境有定義下列函數,則您可以呼叫語言環境介面函數:
當 Net.Data 呼叫一個使用語言環境的函數時,它會用下列步驟來呼叫該語言環境:
下列各節將為您說明介面函數:
dtw_initialize() 介面函數會執行語言環境所要求的任何特殊起始設定, 例如連接資料庫或配置資源。這個介面函數是選用性的。
就每一個巨集而言,Net.Data 只呼叫一次某語言環境的 dtw_initialize() 介面函數, 也就是當 Net.Data 第一次呼叫該語言環境的 FUNCTION 區塊。後續的語言環境呼叫會略過 dtw_initialize() 介面函數的呼叫。
這個介面函數不會影響訊息區塊處理。正值或零的回覆碼表示繼續處理; 負值回覆碼表示不繼續處理。如果回覆碼為非零值, 而且 dtw_lei_t 結構中的 default_error_message 欄位內已定義預設的訊息, 則 Net.Data 會發出預設訊息;如果預設訊息不存在,則 Net.Data 會發出錯誤訊息。
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() 介面函數會取回輸入,以進行一次一列的 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 會執行下列步驟︰
呼叫 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() 介面函數以清除語言環境。 如果您使用 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 會發出警告訊息。