OS/400 版管理及程式設計指南

變數類型

您可以在巨集中使用下列類型的變數。

• "條件式變數"
• "環境變數"
• "執行變數"
• "隱藏變數"
• "列示變數"
• "表格變數"
• "雜項變數"
• "表格處理程序變數"
• "報告變數"
• "語言環境變數"

如果您將字串指定給 Net.Data 以某種方式 (如 ENVVAR、LIST、條件列示變數) 定義的變數， 變數將不再以定義的方式運作。換言之，變數將變成含有字串的簡單變數。

請參閱 Net.Data 參考手冊，取得每一變數的語法及範例。

條件式變數

透過類似於 IF THEN 結構的方法，條件式變數可讓您為變數定義一個條件值。 定義條件式變數時，您可以設定兩個可能的變數值。 若所參照的第一個變數存在，則條件式變數會取得第一個值， 否則，條件式變數取得第二個值。 條件變數的語法為：

varA = varB ? "value_1" : "value_2"

若 varB 已定義，則 varA="value_1"， 否則為 varA="value_2"。 這與使用 IF 區塊是相同的，如下列範例所示：

%IF ($(varB))
    varA = "value_1"
%ELSE
    varA = "value_2"
%ENDIF
 

關於使用條件式變數與列示變數，請參閱 "列示變數" 中的範例。

環境變數

一旦 Web 伺服器使環境變數可供正在處理您的 Net.Data 要求的處理或緒使用後， 您便可以參照這些環境變數。 當參照 ENVVAR 變數時，Net.Data 會以相同名稱傳回環境變數的現行值。

定義環境變數的語法如下：

%DEFINE var=%ENVVAR

其中 var 是將定義的環境變數的名稱。

例如，變數 SERVER_NAME 可定義為環境變數：

%DEFINE SERVER_NAME=%ENVVAR

然後被參考到：

伺服器是 $(SERVER_NAME)

其輸出結果如下：

伺服器是 www.software.ibm.com

請參閱 Net.Data 參考手冊，取得 ENVVAR 陳述式的詳細資訊。

執行變數

透過執行變數，可讓您從一個變數參照呼叫其他程式。

使用 DEFINE 區塊中的 EXEC 語言結構，在 Net.Data 巨集中定義執行變數。 有關 EXEC 語言元素的詳細資訊， 請參閱 Net.Data 參考手冊中有關語言結構這一章。 在下列範例中，變數 runit 被定義來執行可執行的程式 testProg：

%DEFINE runit=%EXEC "testProg"

runit 變成執行變數。

Net.Data 在 Net.Data 巨集中發現有效變數參照時，會執行可執行程式。 例如，若 Net.Data 巨集中對變數 runit 有一個有效變數參照， 則會執行 testProg 程式。

最簡單的方法是從另一個變數定義中來參照執行變數。 下列範例示範這個方法。變數 date 將定義為可執行的變數， 且 dateRpt 含有可執行變數的參照。

%DEFINE date=%EXEC "date"
%DEFINE dateRpt="Today is $(date)"

不論 $(dateRpt) 位於 Net.Data 巨集中的何處， Net.Data 會搜尋可執行程式 date，一旦發現，即傳回：

今天是 Tue 11-07-1999

若 Net.Data 在巨集中發現執行變數，則會使用下列方法來尋找被參考到的可執行程式：

1. 它會搜尋 Net.Data 起始設定檔案中的 EXEC_PATH 所設定的目錄。 有關詳細資料，請參閱"EXEC_PATH"。
2. 如果 Net.Data 找不到程式，則系統會搜尋系統 PATH 環境變數或檔案庫列示中所定義的目錄。若找到可執行的程式，則 Net.Data 會執行該程式。

限制：請勿將執行變數設定為其呼叫之可執行程式輸出的值。 在前一個範例中，變數 date 的值是 NULL (空值)。 若您在 DTW_ASSIGN 函數呼叫中使用此變數，來指定其值給另一個變數， 則指定後新變數的值也會是 NULL (空值)。執行變數的唯一目的，是呼叫其定義的程式。

您也可以藉由在變數定義中指定參數及程式名稱，然後將參數傳給要執行的程式。 在本範例中，distance 和 time 的值被傳遞給程式 calcMPH。

%DEFINE mph=%EXEC "calcMPH $(distance) $(time)" 

下一範例會傳回系統日期作為報告的一部份：

%DEFINE database="celdial"
 %DEFINE tstamp=%EXEC "date"
 
%FUNCTION(DTW_SQL) myQuery() {
SELECT CUSTNO, CUSTNAME from dist1.customer
%REPORT{
%ROW{
<A HREF="/cgi-bin/db2www/exmp.d2w/report?value1=$(V1)&value2=$(V2)">
$(V1) $(V2) </A> <BR>
%}
%}
%}
 
%HTML(report){
<H1>報告製作於： $(tstamp) </H1>
@myQuery()
%}

每一個報告都有日期，以便於追蹤。本範例中， 亦會替另一個 Net.Data 巨集，在鏈結中加入客戶號碼和名稱。 在報告中按一下任何客戶，即呼叫 exmp.d2w Net.Data 巨集， 並將編號和名稱傳給 Net.Data 巨集。

隱藏變數

您可以使用隱藏變數，來隱藏變數的實際名稱， 讓使用 Web 瀏覽器來顯示網頁原始碼的應用程式使用者無法看見。若要定義隱藏變數：

1. 在 HTML 區塊中最後一次參照變數的後面，為您想要隱藏的每一個字串定義一個變數。變數在 HTML 區塊中使用之後，永遠都是以 DEFINE 語言結構來定義， 如下列範例所示。 $$(variable) 會被參考到，然後被定義。
2. 在變數被參照的 HTML 區塊中，使用兩個貨幣符號 (而不是一個) 來參照變數。 例如，採用 $$(X) 而不是 $(X)。

   %HTML(INPUT) {
   <FORM ...>
   <P>選取您要檢視的欄位：
   shanghai<SELECT NAME="欄位">
   <OPTION VALUE="$$(name)"> 姓名
   <OPTION VALUE="$$(addr)"> 地址
   </FORM>
   %}
    
   %DEFINE {
   name="customer.name"
   addr="customer.address"
   %}
    
   %FUNCTION(DTW_SQL) mySelect(){
     SELECT $(Field) FROM customer
   %}
    
   

   當 Web 瀏覽器顯示 HTML 套表時， $$(name) 和 $$(addr) 會分別置換成 $(name) 和 $(addr)， 因此，實際的表格和直欄名稱永遠不會出現在 HTML 套表上。 應用程式使用者無從得知真正變數名稱已隱藏。 當使用者提出該套表時，會呼叫 HTML(REPORT) 區塊。 當 @mySelect() 呼叫 FUNCTION 區塊時， SQL 陳述式中的 $(Field)， 會置換成 SQL 查詢中的 customer.name 或 customer.addr。

列示變數

使用列示變數可讓您建置一串以分隔符號區隔的值。 這特別有助於您建立多項目的 SQL 查詢 (例如，常見於某些 WHERE 或 HAVING 子句中)。 列示變數語法如下：

%LIST " value_separator " variable_name

建議值：空白是有意義的。在大部份的情況下， 請在值分隔字元的前後各插入一個空格。 大部份的查詢在值區隔符號上， 會使用布林或算術運算子 (例如，AND、OR 或 >)。 下列範例舉例說明如何使用條件、隱藏、以及列示變數：

%HTML(INPUT) {
<FORM METHOD="POST" ACTION="/cgi-bin/db2www/example2.d2w/report">
<H2>選取一個過更多個都市：</H2>
<INPUT TYPE="checkbox" NAME="conditions" VALUE="$$(cond1)">Sao Paolo<BR>
<INPUT TYPE="checkbox" NAME="conditions" VALUE="$$(cond2)">Seattle<BR>
<INPUT TYPE="checkbox" NAME="conditions" VALUE="$$(cond3)">Shanghai<BR>
<INPUT TYPE="submit" VALUE="Submit Query">
</FORM>
%}
 
%DEFINE{
DATABASE="custcity"
 %LIST " OR " conditions
cond1="cond1='Sao Paolo'"
cond2="cond2='Seattle'"
cond3="cond3='Shanghai'"
whereClause= ? "WHERE $(conditions)" : ""
%}
 
%FUNCTION(DTW_SQL) mySelect(){
SELECT name, city FROM citylist
$(whereClause)
%}
 
%HTML(REPORT){
@mySelect()
%}

在 HTML 套表中，若未勾選出任何勾選框，則 conditions 為 NULL (空值)， 因此查詢中的 whereClause 亦為 NULL (空值)。否則， whereClause 有 OR 所分隔的選取值。 例如，若三個都市皆選取，則 SQL 查詢如下：

SELECT name, city FROM citylist
WHERE cond1='Sao Paolo' OR cond2='Seattle' OR cond3='Shanghai'

本範例顯示選取了 Seattle，其產生的 SQL 查詢如下：

SELECT name, city FROM citylist
WHERE cond1='Seattle'

表格變數

表格變數可以定義一套相關資料。它含有一組包括一列直欄表頭的橫列及直欄。 在 Net.Data 巨集中定義表格的方式，如下列陳述式所示：

%DEFINE myTable=%TABLE(30)

位在 %TABLE 後面的數字會限制這個表格變數可含有的列數。 如果您想指定一個沒有列數限制的表格， 您可以如下列範例所示，使用預設值或指定 ALL：

%DEFINE myTable2=%TABLE
%DEFINE myTable3=%TABLE(ALL)

定義表格時，並無橫列與直欄。把值移入表格內的唯一方法，是將它當做 OUT 或 INOUT 參數來傳給函數， 或使用 Net.Data 提供的內建表格函數。 DTW_SQL 語言環境自動地將 SELECT 陳述式的結果放入表格中。

對於非資料庫語言環境，例如 DTW_REXX 或 DTW_PERL， 語言環境也會負責設定表格值。不過，語言環境 script 或 program 會按著一個資料格接著一個資料格， 來定義表格值。 請參閱"使用語言環境"，取得語言環境如何使用表格變數的詳細資訊。

您可以參照表格變數名稱，在函數之間傳遞表格。 在函數的 REPORT 區塊中可以參照表格的個別元素， 或使用 Net.Data 表格函數來參照它們。. 請參閱"表格處理程序變數"，瞭解如何在 REPORT 區塊內， 存取表格中的個別元素，以及參閱"表格函數"， 瞭解如何使用表格函數來存取表格的個別元素。 表格變數通常是在 SQL 函數中移入值，然後當做參數傳遞給 SQL 函數或另一個函數， 以用來當做報告的輸入。 您可以將表格變數當做 IN、OUT 或 INOUT 參數，傳遞給任何非 SQL 函數。 表格只能當作 OUT 參數傳給 SQL 函數。

如果您參照一個表格變數，將依據 DTW_HTML_TABLE 變數的設定， 來顯示表格內容並製作它的格式。 在下列範例中，將顯示 myTable 的內容：

%HTML (output) {
  $(myTable)
}

表格中的直欄名稱和欄位值，是以 1 起始的陣列元素來定址。

雜項變數

這些變數是 Net.Data 定義的變數，用途如下：

• 影響 Net.Data 處理程序
• 找出函數呼叫的狀態
• 取得資料庫查詢之結果集的相關資訊
• 決定有關檔案位置和日期的資訊

雜項變數可以有 Net.Data 決定的預定值，或您所設定的值。 例如，Net.Data 基於目前所處理的檔案，來決定 DTW_CURRENT_FILENAME 變數值， 而您可以設定 Net.Data 是否要除去定位字元和換行字元所造成的額外空白。

預設變數可用來當做巨集內的變數參照，並提供有關檔案現行狀態、日期、 或函數呼叫狀態之資訊。例如，若要取回目前的檔案名稱，您可以使用：

%REPORT {
<p>此檔案為 <i>$(DTW_CURRENT_FILENAME)</i>。</P>
}

可更改的變數值通常是使用 DEFINE 陳述式或 @DTW_ASSIGN() 函數來設定， 且可讓您影響 Net.Data 處理巨集的方式。例如，若要設定是否除去空白，您可以使用下列 DEFINE 陳述式：

%DEFINE DTW_REMOVE_WS="YES"

關於有效雜項變數列示及其語法和範例，請參閱 Net.Data 參考手冊中的變數這一章。

表格處理程序變數

Net.Data 定義表格處理變數乃是為了用於 REPORT 及 ROW 區塊。請使用這些變數來參照來自 SQL 查詢和函數呼叫的值。

表格處理變數具有 Net.Data 決定的預設值。 這些變數可讓您根據直欄、橫列或被處理欄位，參照來自 SQL 查詢的結果集合或函數呼叫的值。 您也可以存取有關被處理的橫列數或所有直欄名稱的列表。

例如，當 Net.Data 處理 SQL 查詢的結果集時， 它會針對每一個現行直欄名稱指定變數 Nn 的值，例如指定 N1 給第一直欄、 N2 給第二個直欄，依此類推。 您可以參照網頁輸出的現行直欄名稱。

使用表格處理程序變數，做為巨集內的變數參照。 例如，若要取回被處理之現行直欄的名稱，您可以使用：

%REPORT {
<p>直欄 1 為 <i>$(N1)</i>。</P>
}

表格處理程序變數亦提供有關查詢結果的資訊。 您可以參照巨集中的變數 TOTAL_ROWS，來顯示 SQL 查詢傳回的列數， 如下列範例所示：

所找到的名稱：$(TOTAL_ROWS)

有些表格處理程序變數，會被其他變數或內建式函數所影響。 例如，TOTAL_ROWS 需要啟用 DTW_SET_TOTAL_ROWS SQL 語言環境變數， 以便 Net.Data 在處理 SQL 查詢的結果集或函數呼叫時，能夠指定 TOTAL_ROWS 的值， 如下列範例所示：

%DEFINE DTW_SET_TOTAL_ROWS="YES"
 
所找到的名稱：$(TOTAL_ROWS)

關於有效表格處理程序變數列示及其語法和範例，請參閱 Net.Data 參考手冊中的變數這一章。

報告變數

Net.Data 會以預設報表格式顯示巨集所產生的網頁輸出。預設報表格式會顯示在使用 <PRE> </PRE> 標籤的表格格式中。 您可以經由下列方式置換預設報表：以顯示輸出的指示來定義 REPORT 區塊， 或使用其中一個報表變數來阻止預設報表的產生。

報表變數會協助您自行設定網頁輸出的顯示方式， 以及如何搭配預設報表與 Net.Data 表格一起使用。您必須先使用 DEFINE 陳述式或 @DTW_ASSIGN() 函數來定義這些變數，才能使用它們。

報表變數會設定間隔、置換預設報表格式、設定 HTML 表格輸出對預設表格輸出， 以及設定其他顯示特性。例如，您可以使用 ALIGN 變數，來控制表格處理程序變數的前端和尾端空間。 下列範例使用 ALIGN 變數，對查詢所傳回的列示，以空格來分隔其中每一個直欄名稱。

%DEFINE ALIGN="YES"
<p>您的查詢是針對這些直欄： $(NLIST)

START_ROW_NUM 報告變數可讓您決定從何列開始顯示查詢的結果。 例如，下列變數值指定 Net.Data 從第三列開始顯示查詢的結果。

%DEFINE START_ROW_NUM = "3"

您也可以決定 Net.Data 是否要對預設格式使用 HTML 標籤。 若 DTW_HTML_TABLE 設為 YES，則會產生 HTML 表格， 而不是文字格式的表格。

%DEFINE DTW_HTML_TABLE="YES"
 
%FUNCTION(DTW_SQL){
SELECT NAME, ADDRESS FROM $(qTable)
%}

關於有效報告變數列示及其語法和範例，請參閱 Net.Data 參考手冊中的變數這一章。

語言環境變數

這些變數與語言環境一同使用，並影響語言環境處理要求的方式。

透過這些變數，您可以執行如下的作業：建立資料庫連線、啟用 NLS 支援， 以及決定是否已順利執行 SQL 陳述式。

例如，您可以使用 SQL_STATE 變數，來存取或顯示資料庫傳回的 SQL 狀態值。

%FUNCTION (DTW_SQL) val1() {
 select * from customer
%REPORT {
 ...
  %ROW {
 ...
%}
 SQLSTATE=$(SQL_STATE)
%}

關於有效語言環境變數列示及其語法和範例，請參閱 Net.Data 參考手冊中的變數這一章。