OS/400 版的 Net.Data 管理與程式設計手冊

定義使用者定義的函數

若要在巨集檔案中定義自己的函數，請使用 FUNCTION 區塊或 MACRO_FUNCTION 區塊。

FUNCTION 區塊: 定義可從 Net.Data 巨集來呼叫的次常式，該次常式可由語言環境來處理或呼叫外部程式。
MACRO_FUNCTION 區塊: 定義可從 Net.Data 巨集來呼叫的次常式，該次常式必須由 Net.Data 來處理，而不是語言環境。區塊中的陳述式必須是 Net.Data 巨集語言原始陳述式。

MACRO_FUNCTION 區塊是可以改善執行效能的 FUNCTION 區塊的替代區塊。 MACRO_FUNCTION 區塊僅是由 Net.Data 來處理，且不會呼叫語言環境。關於這兩個結構的詳細資訊在 Net.Data 參考手冊中可找到。

語法：使用下列語法來定義函數：

FUNCTION 區塊：

%FUNCTION(type) function-name(usage parameter, ...) [RETURNS(return-var)] {
  executable-statements
  report-block
  ...
  report-block
 
  message-block
%}

MACRO_ FUNCTION 區塊：

%MACRO_FUNCTION function-name(usage parameter, ...)  {
  executable-statements
  report-block
  ...
  report-block
   %}

其中：

type

指出架構在起始設定檔中之語言環境。語言環境會呼叫某個特定的語言處理器 (處理可執行的陳述式)，並提供 Net.Data 和語言處理器之間的標準介面。

Net.Data 會提供幾個預設的語言環境。

function-name

指定 FUNCTION 或 MACRO_FUNCTION 區塊的名稱。請以巨集檔案其他處的函數呼叫來執行 FUNCTION 區塊或 MACRO_FUNCTION 區塊。函數呼叫以前置的 at (@) 符號來參照 function-name。有關詳細資料，請參閱呼叫函數。

您可以使用相同名稱來定義多重 FUNCTION 或 MACRO_FUNCTION 區塊，以便同時處理。每一個區塊皆必須有相同的參數列示。當 Net.Data 呼叫函數時，相同名稱的所有 FUNCTION 區塊或相同名稱的 MACRO_FUNCTION 區塊，會以定義於 Net.Data 巨集中的次序來執行。

usage

指定參數是輸入 (IN) 參數、輸出 (OUT) 參數、或同時兼具這兩種類型 (INOUT)。此指定表示參數是否在 FUNCTION 區塊、 MACRO_FUNCTION 區塊或兩者上來回傳遞。用法類型適用於參數列示中所有後續的參數，直到被另一個用法類型改變為止。預設類型為 IN。

parameter

區域變數的名稱，可換成指定於函數呼叫中之相對應引數的值。例如，可執行之陳述式或 REPORT 區塊中的參數參照 $(parm1)，可換成參數的實際值。另外，使用該語言的自然語法或當作環境變數使用時，即可將這些參數傳送至語言環境，供可執行的陳述式存取。參數變數參照在 FUNCTION 區塊或 MACRO_FUNCTION 區塊之外即失去效用。

return-var

請在 RETURNS 關鍵字後指定此參數，來識別特殊的 OUT 參數。在 Net.Data 巨集的處理上，指派給函數呼叫之 return 變數的值，可以替代函數呼叫。如果未設定 RETURNS 子句，函數呼叫的值為：

NULL，若從呼叫到語言環境的回覆碼為零的話
回覆碼的值，若回覆碼為非零的話。

executable-statements

在取代變數和處理函數之後，傳送至指定語言環境來處理的一組語言陳述式。 executable-statements 可以含有 Net.Data 變數參照與 Net.Data 函數呼叫。將可執行的陳述式傳遞到語言環境之前，Net.Data 將以實際值置換這些變數參照或函數呼叫。

對於 FUNCTION 區塊，Net.Data 會以變數值來置換所有的變數參照、執行所有的函數呼叫，並在可執行的陳述式傳送至語言環境之前，以結果值來置換函數呼叫。每一個語言環境以不同的方式處理陳述式。有關指定可執行的陳述式或呼叫可執行的程式，請參閱執行變數。

對於 MACRO_FUNCTION 區塊，可執行的陳述式是 HTML 陳述式和 Net.Data 巨集語言結構的組合。此情況下，不會呼叫任何語言環境，因為 Net.Data 扮演語言處理器的角色，且評估和執行可執行的陳述式。

report-block

定義一個或多個 REPORT 區塊，來處理 FUNCTION 區塊的輸出。請參閱報告區塊。

message-block

定義 MESSAGE 區塊，用以處理 FUCNTION 所傳回的任何訊息。請參閱訊息區塊。

請在最外層的 Net.Data 巨集上定義函數，供 Net.Data 巨集呼叫。

在函數中使用特殊字元

當符合 Net.Data 語言結構語法的字元在函數區塊的語言陳述式區段中使用，作為語法有效的內含程式碼 (如 REXX 或 Perl) 的一部份時，它們可能會被誤譯為 Net.Data 語言結構，導致在巨集中發生錯誤或無法預期的結果。

例如，Perl 函數可以使用 COMMENT 區塊定界字元 (%{)。當巨集執行時，%{ 字元會被解譯為 COMMENT 區塊的開頭。然後， Net.Data 會尋找 COMMENT 區塊的結尾，當它讀到函數區塊的結尾時，會認為找到它。Net.Data 會繼續尋找函數區塊的結尾，當它找不到時，即會發出錯誤。

使用下列其中一種方法，使用 COMMENT 區塊定界字元或任何其他 Net.Data 特殊字元，作為內含程式碼的一部份，不使它們被 Net.Data 解譯為特殊字元：

使用 EXEC 陳述式呼叫程式碼，而不是將程式碼置於行內。
使用變數參照來設定特殊字元。

例如，下列 Perl 函數含有代表 COMMENT 區塊定界字元 %{ 作為 Perl 語言陳述式一部份的字元：

%function(DTW_PERL) func() {
  ...           
  for $num_words (sort bynumber keys %{ $Rtitles{$num} }) {
  &make_links($Rtitles{$num}{$num_words});          
  }            
  ...         
 %}

若要確定 Net.Data 將 %{ 字元解譯為 Perl 原始碼而非 Net.Data COMMENT 區塊定界字元，請以下列任一方式重寫函數：

使用 %EXEC 陳述式：

%function(DTW_PERL) func() { 
  %EXEC{ func.prl %}          
%}

使用變數參照來設定 %{ 字元：

%define percent_openbrace = "%{"           
 
%function(DTW_PERL) func() {             
 ...           
 for $num_words (sort bynumber keys $(percent_openbrace) $Rtitles{$num} }) {                
  &make_links($Rtitles{$num}{$num_words});             
 }            
 ...          
%}

訊息區塊

MESSAGE 區塊可讓您決定在順利完成 (或未順利完成) 函數呼叫後，要如何繼續處理，並且可讓您顯示相關資訊給函數呼叫者。 Net.Data 使用下列訊息區塊處理：

Net.Data 會為呼叫 FUNCTION 區塊的每一個函數，設定一個語言環境變數 RETURN_CODE。對 MACRO_FUNCTION 區塊的函數呼叫，則不設定 RETURN_CODE。
當語言環境將回覆碼傳回 Net.Data 時，Net.Data 會將 RETURN_CODE 的值設為回覆碼值。
當函數呼叫完成後，MESSAGE 區塊會透過 RETURN_CODE 值來判斷該如何繼續處理。

MESSAGE 區塊是由一系列的訊息陳述式所組成，每個陳述式都設有回覆碼值、訊息文字與要執行的動作。有關 MESSAGE 區塊的語法，請參閱 Net.Data 參考手冊中語言結構一章。

MESSAGE 區塊的範圍可以是廣域或區域。若 MESSAGE 區塊是定義在 FUNCTION 區塊中，則對該 FUNCTION 區塊來說其範圍是區域性的。若它是指定在最外層的巨集上，則 MESSAGE 區塊的範圍是廣域的，且可供在 Net.Data 巨集中執行的所有函數呼叫使用。如果您定義多個廣域 MESSAGE 區塊，則會採用最近一次定義的。

Net.Data 會採用下列的規則，來處理從某函數呼叫所傳回的 RETURN_CODE 變數之值：

檢查區域 MESSAGE 區塊是否有完全相符的；然後根據所指定的，看是要跳出或繼續。
如果 RETURN_CODE 不是 0，請檢查區域 MESSAGE 區塊是否為 +default 或 -default；然後根據所指定的，看是要跳出或繼續，不過得視 RETURN_CODE 的符號而定。
若 RETURN_CODE 不為 0，則檢查區域 MESSAGE 區塊是否為預設值，然後根據所指定的，看是要跳出或繼續。
檢查廣域 MESSAGE 區塊是否有完全相符的；然後根據所指定的，看是要跳出或繼續。
若 RETURN_CODE 不為 0，則根據 RETURN_CODE 的符號，檢查廣域 MESSAGE 區塊是否為 +default 或 -default，然後依指定跳出或繼續。
若 RETURN_CODE 不為 0，則檢查廣域 MESSAGE 區塊是否為 default，然後依指示跳出或繼續。
若 RETURN_CODE 不為 0，則發出 Net.Data 內部預設的訊息並跳出。

下列範例顯示一部份 Net.Data 巨集，其中帶有整體 MESSAGE 區塊，與一個函數的 MESSAGE 區塊。

%{ 廣域 message 區塊 %}
  %MESSAGE {
     -100     : "回覆碼 -100 訊息"   : exit
      100     : "回覆碼 100 訊息"    : continue
   +default : {
此為超出一行的長訊息。
您可以在此訊息中使用 HTML 標籤，包括
鏈結與套表。%}   : continue
%}
 
%{ FUNCTION 區塊中的區域 message 區塊 %}
%FUNCTION(DTW_REXX) my_function() {
  %EXEC { my_command.mbr %}
  %MESSAGE {
     -100     : "回覆碼 -100 訊息"   : exit
      100     : "回覆碼 100 訊息"    : continue
     -default : {
此為超出一行的長訊息。
您可以在此訊息中使用 HTML 標籤，包括
鏈結與套表。%}   : exit
  %}

my_function() 傳回一個 RETURN_CODE 值為 50 時， Net.Data 會以下列順序來處理錯誤：

檢查區域 MESSAGE 區塊中是否有完全相符的。
檢查區域 MESSAGE 區塊中是否為 +default。
檢查區域 MESSAGE 區塊中是否為 default。
檢查廣域 MESSAGE 區塊中是否有完全相符的。
檢查廣域 MESSAGE 區塊中是否為 +default。

當 Net.Data 找到相配時，會將訊息文字送給 Web 瀏覽器，並檢查所要求的動作。

當您設定 continue 時， Net.Data 會在印出訊息文字後繼續處理 Net.Data 巨集。例如，若巨集呼叫 my_functions() 5 次，且在處理範例中之 MESSAGE 區塊時發現了錯誤 100，則該程式的輸出如下：

.
.
.
11 May 1997                  $245.45
13 May 1997                  $623.23
19 May 1997                  $ 83.02
回覆碼 100 訊息
22 May 1997                  $ 42.67
 
總計：                       $994.37

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