Net.Data 參考手冊

Net.Data 語言環境變數

使用這些變數可幫助您使用語言環境自行設定 FUNCTION 區塊的處理方式。在參照這些變數之前，您可能必須先定義它們。

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

DATABASE

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X
X X X X

目的

呼叫資料庫函數時，指定存取的資料庫或 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 值

值說明
dbname Net.Data 所連接的資料庫名稱。

值	說明
`dbname`	Net.Data 所連接的資料庫名稱。

範例

範例 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

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

目的

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

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

值

DB_CASE="UPPER"|"LOWER"

表 8. DB_CASE 值

值說明
UPPER 將所有 SQL 指令字元轉換成大寫字體。
LOWER 將所有 SQL 指令字元轉換成小寫字體。

值	說明
UPPER	將所有 SQL 指令字元轉換成大寫字體。
LOWER	將所有 SQL 指令字元轉換成小寫字體。

範例

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

%DEFINE DB_CASE="UPPER"

DB2PLAN

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT

X

目的

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

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

必要條件： 在 Net.Data 起始設定檔案中的 DTW_SQL ENVIRONMENT 陳述式上，必需設有這個變數，但在巨集檔中則為選用性地設定。如果這個變數沒有被指定在 OS/390 起始設定檔案內或只在巨集內而不在起始設定檔案中時，一旦當巨集嘗試執行 SQL 函數，就會發生錯誤。

值

DB2PLAN="plan_name"

表 9. DB2PLAN 值

值說明
plan_name DB2 規劃的名稱。這個名稱可以是 8 個以下的字元。

值	說明
`plan_name`	DB2 規劃的名稱。這個名稱可以是 8 個以下的字元。

範例

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

%DEFINE DB2PLAN="DTWGAV21"

DB2SSID

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT

X

目的

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

必要條件： 這個變數必要在 Net.Data 起始設定檔案中被指定，或在巨集檔中選用性地被指定。如果這個變數沒有在 Net.Data for OS/390 起始設定檔案中指定，也沒有在巨集中定義，這時候，若巨集想要執行 SQL 函數就會發生錯誤。

值

DB2PLAN="subsytem_id"

表 10. DB2SSID 值

值說明
subsystem_id DB2 子系統的名稱。這個名稱可以是 8 個以下的字元。

值	說明
`subsystem_id`	DB2 子系統的名稱。這個名稱可以是 8 個以下的字元。

範例

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

%DEFINE DB2SSID="DBNC"

DTW_APPLET_ALTTEXT

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X
X X X

目的

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

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

值

DTW_APPLET_ALTTEXT="HTML_text_and_tags"

表 11. DTW_APPLET_ALTTEXT 值

值說明
HTML_text_and_tags HTML 標籤及文字，讓不認得 APPLET 標籤的瀏覽器使用。

值	說明
`HTML_text_and_tags`	HTML 標籤及文字，讓不認得 APPLET 標籤的瀏覽器使用。

範例

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

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

DTW_EDIT_CODES

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT

X

目的

將 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 值

值說明
edit_code 指定一個字串，對應 SQL 語言環境所建置表格的結果直欄。

值	說明
`edit_code`	指定一個字串，對應 SQL 語言環境所建置表格的結果直欄。

範例

範例 1：

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

DTW_MBMODE

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X
X X X

目的

提供多位元字集支援給預設語言環境所使用的字串及字組函數。您可以在起始設定檔案中設定這個變數，但也可以在巨集檔中使用它來設定或置換現行的設定。

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

OS/400 的使用者請注意： Net.Data for OS/400 會自動啟用 MBCS 支援的函數，所以不需要這個變數。Net.Data for OS/400 不處理被移轉到 OS/400 作業系統的巨集檔內所含的此變數。

值

DTW_MBMODE="YES"|"NO"

表 13. DTW_MBMODE 值

值說明
YES 指定 MBCS 支援給字串及字組函數
NO 指定字串及字組函數不要有 MBCS 支援。 NO 是預設值。

值	說明
YES	指定 MBCS 支援給字串及字組函數
NO	指定字串及字組函數不要有 MBCS 支援。 NO 是預設值。

範例

範例 1： 置換 INI 檔案中的值

INI 檔：

DTW_MBMODE "NO"
...
ENVIRONMENT (DTW_DEFAULT) [dll] (IN DTW_MBMODE, OUT
RETURN_CODE )

巨集檔：

 %DEFINE DTW_MBMODE = "YES"

DTW_SAVE_TABLE_IN

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

目的

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

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

值

DTW_SAVE_TABLE_IN="table_name_var"

表 14. DTW_SAVE_TABLE_IN 值

值說明
table_name_var SQL 語言環境用來存放來自查詢之表格資料的表格名稱。

值	說明
`table_name_var`	SQL 語言環境用來存放來自查詢之表格資料的表格名稱。

範例

範例 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

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X
X X X X

目的

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

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

若要自動傳送變數，可將它作為一個 IN 變數併入資料庫語言環境陳述式中，該陳述式位於 Net.Data 起始設定檔案內。請參閱 Net.Data 管理及程式設計手冊中的架構章節，以取得關於資料庫語言環境陳述式的詳細資料。

值

DTW_SET_TOTAL_ROWS="YES"|"NO"

表 15. DTW_SET_TOTAL_ROWS 值

值說明
YES 指定總列數的值給 TOTAL_ROWS 變數。重要事項： 如果想要參考變數 TOTAL_ROWS 來決定查詢所傳回的列數，則必需設定此值。
NO Net.Data 不會設定 TOTAL_ROWS 變數且 TOTAL_ROWS 無法在巨集檔中被參考。NO 是預設值。

值	說明
YES	指定總列數的值給 TOTAL_ROWS 變數。重要事項：如果想要參考變數 TOTAL_ROWS 來決定查詢所傳回的列數，則必需設定此值。
NO	Net.Data 不會設定 TOTAL_ROWS 變數且 TOTAL_ROWS 無法在巨集檔中被參考。NO 是預設值。

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

範例

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

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

LOCATION

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT

X

目的

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

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

值

LOCATION="remote_dbase_name"

表 16. LOCATION 值

值說明
remote_dbase_name 定義於 CDB 的 SYSIBM.SYSLOCATIONS 表格中有效遠端資料庫伺服器的名稱。這個名稱可以是 8 個以下的字元。

值	說明
`remote_dbase_name`	定義於 CDB 的 SYSIBM.SYSLOCATIONS 表格中有效遠端資料庫伺服器的名稱。這個名稱可以是 8 個以下的字元。

範例

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

%DEFINE LOCATION="QMFDJ00"

LOGIN

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X
X X X X

目的

傳送使用者 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 值

值說明
database_user_id 有效的資料庫使用者 ID。其預設值是使用啟動 Web 伺服器的使用者 ID。

值	說明
`database_user_id`	有效的資料庫使用者 ID。其預設值是使用啟動 Web 伺服器的使用者 ID。

範例

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

%DEFINE LOGIN="DB2USER"

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

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

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

NULL_RPT_FIELD

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT

X

目的

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

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

值

NULL_RPT_FIELD="null_char"

表 18. NULL_RPT_FIELD 值

值說明
null_char 指定一個字串，來代表 SQL 結果組所傳回的 NULL 值。其預設值是空字串。

值	說明
`null_char`	指定一個字串，來代表 SQL 結果組所傳回的 NULL 值。其預設值是空字串。

範例

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

%DEFINE NULL_RPT_FIELD = "++++"

PASSWORD

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X
X X X X

目的

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

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

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

值

PASSWORD="password"

表 19. PASSWORD 值

值說明
password 指定一個有效密碼，以提供自動對資料庫語言環境的存取權限。

值	說明
`password`	指定一個有效密碼，以提供自動對資料庫語言環境的存取權限。

範例

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

%DEFINE PASSWORD="NETDATA"

範例 2: HTML 套表輸入行

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

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

SHOWSQL

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

目的

隱藏或顯示 Web 瀏覽器所用之查詢的 SQL。在測試時顯示 SQL，特別有助於 Net.Data 巨集的除錯作業。

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

值

SHOWSQL="YES"|"NO"

表 20. SHOW_SQL 值

值說明
YES 顯示送給資料庫之查詢的 SQL。
NO 隱藏送給資料庫之查詢的 SQL。 NO 是預設值。

值	說明
YES	顯示送給資料庫之查詢的 SQL。
NO	隱藏送給資料庫之查詢的 SQL。 NO 是預設值。

範例

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

%DEFINE SHOWSQL="YES"

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

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

SQL_STATE

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

目的

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

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

範例

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

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

TRANSACTION_SCOPE

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

目的

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

使用 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 值

值說明
SINGLE 只要 HTML 區塊中的每一個 SQL 命令順利完成， Net.Data 就會發出 COMMIT。
MULTIPLE Net.Data 只會在 HTML 區塊中所有的 SQL 命令都順利完成之後，才會發出 COMMIT。 MULTIPLE 是預設值。

值	說明
SINGLE	只要 HTML 區塊中的每一個 SQL 命令順利完成， Net.Data 就會發出 COMMIT。
MULTIPLE	Net.Data 只會在 HTML 區塊中所有的 SQL 命令都順利完成之後，才會發出 COMMIT。 MULTIPLE 是預設值。

範例

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

%DEFINE TRANSACTION_SCOPE="SINGLE"

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