參考手冊

Net.Data 語言環境變數

使用這些變數可幫助您使用語言環境自行設定 FUNCTION 區塊的處理方式。每個變數都有一個預設值。您可以將新的值指定給變數，置換預設值。

• DATABASE
• DB_CASE
• DB2PLAN
• DB2SSID
• DTW_APPLET_ALTTEXT
• DTW_EDIT_CODES
• DTW_PAD_PGM_PARMS
• DTW_SAVE_TABLE_IN
• DTW_SET_TOTAL_ROWS
• LOCATION
• LOGIN
• NULL_RPT_FIELD
• PASSWORD
• SHOWSQL
• SQL_STATE
• TRANSACTION_SCOPE

DATABASE

目的

呼叫資料庫函數時，指定存取的資料庫或 ODBC 資料來源。 在巨集中可以多次變更這個變數，以存取多重的資料庫或 ODBC 資料來源。

在 OS/400 作業系統上： 這個變數是可選用的。 根據預設值，Net.Data 會指定 DATABASE="*LOCAL"； DTW_SQL 語言環境是使用區域關聯式資料庫目錄登錄。

在 Windows NT、OS/2 及 UNIX 作業系統上： 除了當使用 DTW_ORA (Oracle) 語言環境以外，請在呼叫任何資料庫函數前， 定義這個變數。此外，當自同一個 HTML 區塊或經由相同的語言環境存取多重資料庫時， 您必需使用「現場連線」。

使用 DEFINE 陳述式或 以 @DTW_ASSIGN() 函數來設定這個變數值。

值

DATABASE="dbname"

表 7. DATABASE 值

範例

範例 1：指定任何 SQL 作業均連接 CELDIAL 資料庫

%DEFINE DATABASE="CELDIAL"
 
%FUNCTION (DTW_SQL) getRpt() {
SELECT * FROM customer
%}
 
%HTML(report){
%INCLUDE "rpthead.htm"
@getRpt()
%INCLUDE "rptfoot.htm"
%}

當函數 getRpt 被呼叫時，即可存取資料庫 CELDIAL。

範例 2：使用 DTW_ASSIGN 置換先前的 DATABASE 定義

%DEFINE DATABASE="DB2C1"
...
%HTML(monthRpt){
@DTW_ASSIGN(DATABASE, "DB2D1")
%INCLUDE "rpthead.htm"
@getRpt()
%INCLUDE "rptfoot.htm"
%}

不管 DATABASE 之前的值是什麼， HTML 區塊都會查詢資料庫 DB2D1。

DB_CASE

目的

指定 SQL 指令所用的字體，並將所有字元轉換成大寫或小寫字體。如果沒有定義這個變數， 則預設動作是不轉換 SQL 指令字元。

使用 DEFINE 陳述式或 以 @DTW_ASSIGN() 函數來設定這個變數值。

值

DB_CASE="UPPER"|"LOWER"

表 8. DB_CASE 值

範例

範例 1：指定所有 SQL 指令皆使用大寫字體

%DEFINE DB_CASE="UPPER"

DB2PLAN

目的

配置一個連接區域 DB2 子系統的規劃。這個變數會在 Net.Data 將存取的區域 DB2 子系統上為 Net.Data SQL 語言環境指定一個規劃名稱。

使用 DEFINE 陳述式或 以 @DTW_ASSIGN() 函數來設定這個變數值。

需求： 為了讓巨集中此變數的值生效， 變數必須列示在 SQL 語言環境的 ENVIRONMENT 陳述式中。

值

DB2PLAN="plan_name"

表 9. DB2PLAN 值

範例

範例 1：在 DEFINE 陳述式中指定規劃

手%DEFINE DB2PLAN="DTWGAV22"

DB2SSID

目的

建立一個到區域 DB2 子系統的連線。此變數會指定 Net.Data 所要存取的區域 DB2 子系統的子系統 ID。每一個巨集只能有一個區域資料庫連線。

需求： 為了讓巨集中此變數的值生效， 變數必須列示在 SQL 語言環境的 ENVIRONMENT 陳述式中。

值

DB2PLAN="subsytem_id"

表 10. DB2SSID 值

範例

範例 1：在 DEFINE 陳述式中指定一個子系統 ID

%DEFINE DB2SSID="DBNC"

DTW_APPLET_ALTTEXT

目的

將 HTML 標籤及文字顯示給不認得 APPLET 標籤的瀏覽器，且與 Applet 語言環境共同使用。

使用 DEFINE 陳述式或 以 @DTW_ASSIGN() 函數來設定這個變數值。

值

DTW_APPLET_ALTTEXT="HTML_text_and_tags"

表 11. DTW_APPLET_ALTTEXT 值

範例

範例 1：指示 Web 瀏覽器限制的替代文字

%DEFINE DTW_APPLET_ALTTEXT="<P>對不起，您的瀏覽器不支援 java。"

DTW_EDIT_CODES

目的

將 SQL 作業結果所傳回的 NUMERIC、DECIMAL、INTEGER 及 SMALLINT 資料類型轉換成適用於 DTW_SQL 語言環境。變數 DTW_EDIT_CODES 是一串字元，對應 DTW_SQL LE 所建置的 表格直欄結果；例如，DTW_EDIT_CODES 中的第五個字元 將被引用在結果組的第五個欄位，但該欄位必需是受支援型類之一。 這個單一字元可以是定義在 Data 資料說明規格參考手冊中任何一個已支援系統所提供的編輯碼。

例如，DECIMAL(6,0) 欄位在正常狀況下會顯示出 字串 '112698'。若指定變數 DTW_EDIT_CODES 中的直欄為一個編輯碼 'Y'時， 該欄位會顯示出結果表格中之相對應直欄的字串，代表日期 '11/26/98'。

要訣： 引用一個使用者自定的編輯碼給一個直欄，而造成字串含有非數值字元 (如逗點或貨幣符號) 時， 如果該字串被送回伺服器在 Net.Data 中進行後續處理， 則會導致語法錯誤。 例如，非數值的欄位值可能被用於後續 DTW_SQL 函數呼叫中的數字比較， 因而造成語法錯誤。

使用 DEFINE 陳述式或 以 @DTW_ASSIGN() 函數來設定這個變數值。

值

DTW_EDIT_CODES="edit_code"

表 12. DTW_EDIT_CODES 值

範例

範例 1：

@DTW_ASSIGN(DTW_EDIT_CODES "JJLJJ*******Y")

DTW_PAD_PGM_PARMS

目的

指示語言環境將字元參數（CHAR 或 CHARACTER 的資料類型）傳遞至程式或儲存程序時，是否要填補空格。

就 IN 或 INOUT 參數而言，若參數值長度小於指定的精確度， 空格將插入參數值的右側，直到參數值與精確度兩者的長度相同為止。

就 OUT 參數而言，參數值設為精確度的空格。

呼叫程式或儲存程序之後，從 OUT 和 INOUT 參數值中除去所有的尾端空格。

在起始設定檔案中設定這個變數， 指定一個值給您所有的巨集。您可以在巨集中定義這個值，將它置換。 若巨集中未定義 DTW_PAD_PGM_PARMS，則會使用 Net.Data 起始設定檔的值。

Direct Call 及 SQL 語言環境支援 DTW_PAD_PGM_PARMS。

值

DTW_PAD_PGM_PARMS="YES"|"NO"

表 13. DTW_PAD_PGM_PARMS 值

範例

範例 1： 參數填補空格

DTW_PAD_PGM_PARMS="YES"

DTW_SAVE_TABLE_IN

目的

識別 SQL 語言環境用來存放來自查詢之表格資料的表格變數。 此表可以稍後再用， 例如，用於分析表格資料的 REXX 程式。

使用 DEFINE 陳述式或 以 @DTW_ASSIGN() 函數來設定這個變數值。

值

DTW_SAVE_TABLE_IN="table_name_var"

表 14. DTW_SAVE_TABLE_IN 值

範例

範例 1： 用於 REXX 呼叫且先前已定義的表格變數

%DEFINE theTable = %TABLE(2)
%DEFINE DTW_SAVE_TABLE_IN = "theTable"
 
%FUNCTION(DTW_SQL) doQuery() {
SELECT MODNO, COST, DESCRIP FROM EQPTABLE
WHERE TYPE='MONITOR'
%}
 
%FUNCTION(DTW_REXX) analyze_table(myTable) {
  %EXEC{ anzTbl.cmd %}
%}
 
%HTML(doTable) {
@doQuery()
@analyze_table(theTable)
%}

REXX FUNCTION 區塊會呼叫 REXX 程式 anzTbl.cmd, 該程式是使用表格變數 theTable 來分析表格中的資料。 變數 theTable 是由之前一個 SQL 函數呼叫所傳回。

DTW_SET_TOTAL_ROWS

目的

指定資料庫語言環境中查詢結果組的總列數必需被指定給 TOTAL_ROWS。

使用 DEFINE 陳述式或 以 @DTW_ASSIGN() 函數來設定這個變數值。

OS/400、OS/2、Windows NT 及 UNIX 使用者： 若要將此變數傳遞至語言環境，請在 Net.Data 起始設定檔的資料庫語言環境 ENVIRONMENT 陳述式中， 將此變數設定為 IN 變數。請參閱 Net.Data 管理及程式設計手冊中的架構章節， 以取得關於資料庫語言環境陳述式的詳細資料。

OS/390 使用者： 定義於巨集中的 DTWT_SET_TOTAL_ROWS， 會暗中傳遞至資料庫語言環境

執行效能要訣： 將 DTW_SET_TOTAL_ROWS 設定為 YES 會影響執行效能，因為若要決定總列數，資料庫語言環境需要所有列數都被取回。

值

DTW_SET_TOTAL_ROWS="YES"|"NO"

表 15. DTW_SET_TOTAL_ROWS 值

範例

範例 1： 定義 DTW_SET_TOTAL_ROWS 以便使用 TOTAL_ROWS

%DEFINE DTW_SET_TOTAL_ROWS="YES"
 
...
 
%FUNCTION (DTW_SQL) myfunc() {
select * from MyTable
%report {
...
%row
...
%}
<P>您的查詢僅限於 $(TOTAL_ROWS) 列。此查詢傳回太多列。
%}
%}

LOCATION

目的

建立一個到遠端資料庫伺服器的連線。 此變數會指定區域 DB2 子系統據以識別該遠端伺服器的名稱。 LOCATION 的值， 必須在「通信資料庫」(CDB) 的 SYSIBM.SYSLOCATIONS 表格中加以定義。 如果巨集中沒有定義這個變數，則該巨集所發出的任何 SQL 要求， 都會在區域 DB2 子系統上執行。

需求： 為了讓巨集中此變數的值生效， 變數必須列示在 SQL 語言環境的 ENVIRONMENT 陳述式中。

使用 DEFINE 陳述式或 以 @DTW_ASSIGN() 函數來設定這個變數值。

值

LOCATION="remote_dbase_name"

表 16. LOCATION 值

範例

範例 1: 在 DEFINE 陳述式中定義遠端資料庫位置

%DEFINE LOCATION="QMFDJ00"

LOGIN

目的

傳送使用者 ID 給資料庫語言環境，以提供對受保護的資料的存取權限。 您可以將這個變數與通行碼一起使用，以納入 DB2 的安全演繹法。

OS/400 使用者：如果未定義 DATABASE 變數， 或是如果它設定為值 "*LOCAL"，OS/400 將不處理 LOGIN 與 PASSWORD。 會透過 Net.Data 執行時所用的使用者設定檔，來遞送資料庫存取。

安全要訣： 雖然您可以將這個撰寫在 Net.Data 巨集內， 最好讓應用程式使用者在 HTML 套表上輸入使用者 ID。 另外，使用 Web 伺服器 ID 的預設值所提供的存取層次，可能無法符合您的安全需要。

使用 DEFINE 陳述式或 以 @DTW_ASSIGN() 函數來設定這個變數值。

值

LOGIN="database_user_id"

表 17. LOGIN 值

範例

範例 1：將存取權限制給使用者 ID, DB2USER

%DEFINE LOGIN="DB2USER"

範例 2：使用 HTML 套表輸入行

USERID&#58;  <INPUT TYPE="text" NAME="LOGIN" SIZE=6>

此例所示範的這一行， 可以併入 HTML 套表中，讓應用程式使用者輸入其使用者 ID。

NULL_RPT_FIELD

目的

指定一個字串讓使用者可以提供給 DTW_SQL 語言環境，來代表 SQL 結果組所傳回的 NULL 值。

使用 DEFINE 陳述式或 以 @DTW_ASSIGN() 函數來設定這個變數值。

值

NULL_RPT_FIELD="null_char"

表 18. NULL_RPT_FIELD 值

範例

範例 1：在 SQL 語言環境中指定一個字串來代表 NULL 值

%DEFINE NULL_RPT_FIELD = "++++"

PASSWORD

目的

傳送一個密碼給資料庫語言環境，以提供對受保護的資料的存取權限。 您可以將這個變數與 LOGIN 一起使用，以納入 DB2 的安全演繹法。

OS/400 使用者：如果未定義 DATABASE 變數， 或是如果它設定為值 "*LOCAL"，OS/400 將不處理 LOGIN 與 PASSWORD。 會透過 Net.Data 執行時所用的使用者設定檔，來遞送資料庫存取。

安全要訣： 雖然您可以將這個撰寫在 Net.Data 巨集內， 最好讓應用程式使用者在 HTML 套表上輸入密碼。

使用 DEFINE 陳述式或 以 @DTW_ASSIGN() 函數來設定這個變數值。

值

PASSWORD="password"

表 19. PASSWORD 值

範例

範例 1：將存取權限限制給使用密碼 NETDATA 的應用程式使用者

%DEFINE PASSWORD="NETDATA"

範例 2: HTML 套表輸入行

PASSWORD&#58; <INPUT TYPE="password" NAME="PASSWORD" SIZE=8>

此例所示範的這一行， 可以併入 HTML 套表中，讓應用程式使用者輸入其密碼。

SHOWSQL

目的

隱藏或顯示 Web 瀏覽器所用之查詢的 SQL。 在測試時顯示 SQL，特別有助於 Net.Data 巨集的除錯作業。 唯有當 Net.Data 架構檔中的 DTW_SHOWSQL 設為 YES 時，才能使用 SHOWSQL。 有關 DTW_SHOWSQL 架構變數的詳細資訊， 請參閱您作業系統的 Net.Data 管理和程式設計指南中架構這一章。

使用 DEFINE 陳述式或 以 @DTW_ASSIGN() 函數來設定這個變數值。

值

SHOWSQL="YES"|"NO"

表 20. SHOW_SQL 值

範例

範例 1：顯示所有 SQL 查詢。

架構檔：

DTW_SHOWSQL YES

巨集：

%DEFINE SHOWSQL="YES"

範例 2：設定是否使用 HTML 套表輸入來顯示 SQL。

架構檔：

DTW_SHOWSQL YES

巨集：

SHOWSQL: <INPUT TYPE="radio" NAME="SHOWSQL" VALUE="YES"> Yes
         <INPUT TYPE="radio" NAME="SHOWSQL" VALUE="" CHECKED> No

SQL_STATE

目的

存取或顯示資料庫所傳回的 SQL 狀態值。

這是一種預設變數，其數值無法修改。 使用這種變數作為變數參照。

範例

範例 1：在 REPORT 區塊中顯示 SQL 狀態

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

TRANSACTION_SCOPE

目的

指定 SQL 指令的異動範圍，來決定 Net.Data 是在 HTML 區塊中各個 SQL 指令順利完成之後或是所有 SQL 指令順利完成之後 發出 COMMIT。若您設定的是所有 SQL 指令必需在發出確定前順利完成， 只要有一個 SQL 指令沒有順利完成，都會使先前對該區塊 同一資料庫所執行的 SQL 全數回復。

為了讓 TRANSACTION_SCOPE 變數生效，請在 Net.Data 架構檔的 ENVIRONMENT 陳述式中併入此變數。然後，即可使用 DEFINE 陳述式或 @DTW_ASSIGN() 函數， 指定這個變數的值。

一致性注意事項： 在 OS/400 和 OS/390 以外的平台上， 那麼對收到失敗回應之資料庫所作的更新， 可能會被回復，然如果下列條件全部成立的話，同一 HTML 區塊中對其它資料庫所作的更新， 卻可能被確定：

• 指定了 TRANSACTION_SCOPE = "MULTIPLE"

• 在一個 HTML 區塊中存取多個資料庫 (如果您是使用「現場連線」時就有可能)

• SQL 要求傳回失敗回應

如果您是從 OS/400 上的 Net.Data 存取多個資料庫，或是使用 IBM 的 DataJoiner 軟體， 那麼當您從 Net.Data 更新時，即可取得多個資料庫更新協調和一致性。

在 OS/400 和 OS/390 上， 如果 TRANSACTION_SCOPE = "MULTIPLE" ， 則所有從單個 HTML 區塊發出的 IBM 資料庫更新，將一起確定或回復。

在 OS/400 以外的作業系統上， REXX、Perl 和 Java 語言環境在它們自己獨立的作業系統處理作業當中執行。因此， 不管 Net.Data TRANSACTION_SCOPE 值是什麼， 只要是發自這些語言環境的資料庫更新， 其確定或回復都與發自某個 Net.Data 巨集的資料庫更新互不影響。

值

TRANSACTION_SCOPE="SINGLE"|"MULTIPLE"

表 21. TRANSACTION_SCOPE 值

範例

範例 1：指定在每一個異動之後發出 COMMIT

%DEFINE TRANSACTION_SCOPE="SINGLE"