參考手冊

一般函數

一般函數可協助您使用 Net.Data 來開發網頁，且不適用於其它的種類。下列函數都是一般目的函數：

DTW_ADDQUOTE
DTW_CACHE_PAGE
DTW_DATE
DTW_EXIT
DTW_GETCOOKIE
DTW_GETENV
DTW_GETINIDATA
DTW_HTMLENCODE
DTW_QHTMLENCODE
DTW_SENDMAIL
DTW_SETCOOKIE
DTW_SETENV
DTW_TIME
DTW_URLESCSEQ

DTW_ADDQUOTE

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

目的

將在輸入字串中的單引號置換為兩個單引號。

格式

@DTW_ADDQUOTE(stringIn, stringOut)

@DTW_rADDQUOTE(stringIn)

@DTW_mADDQUOTE(stringMult, stringMult2, ..., stringMultn)

參數

表 27. DTW_ADDQUOTE 參數

資料類型	參數	使用	說明
字串	`stringIn`	IN	一個變數或文字字串。 DTW_mADDQUOTE 可以有多個輸入字串。
字串	`stringOut`	OUT	包含 `stringIn` 已修改格式的變數。
字串	`stringMult`	INOUT	在輸入上：包含字串的變數。在輸出上：包含輸入字串的一個變數，該字串的每一個單引號（'）字元都被兩個單引號字元所置換。

回覆碼

表 28. DTW_ADDQUOTE 回覆碼

回覆碼	說明
-1001	伺服器無法處理 Net.Data 的配置記憶體要求。
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。
1005	函數呼叫上傳遞的參數必須是字串變數，但卻是不同的變數類型。
1006	文字字串傳遞給函數呼叫中的參數，但此參數必須是輸出參數。

用法注意事項

對於從 Web 瀏覽器取得輸入的所有 SQL INPUT 陳述式使用這個函數。例如，如果您如下列範例一般，將 O'Brien 輸入為姓氏，則單引號將會造成錯誤：

INSERT INTO USER1.CUSTABLE (LNAME, FNAME)
VALUES ('O'Brien', 'Patrick')

使用 DTW_ADDQUOTE 函數會變更 SQL 陳述式並防止錯誤發生：

INSERT INTO USER1.CUSTABLE (LNAME, FNAME)
VALUES ('O''Brien', 'Patrick')

範例

範例 1：在 OUT 參數新增一個額外的單引號

@DTW_ADDQUOTE(string1,string2)

輸入：string1="John's Web page"
傳回：string2="John''s Web page"

範例 2：在函數呼叫的傳回值上新增額外的單引號

@DTW_rADDQUOTE("The title of the article is 'Once upon a time'")

傳回："The title of the article is ''Once upon a time''"

範例 3：在函數呼叫的每一個 INOUT 參數上新增額外的單引號

@DTW_mADDQUOTE(string1,string2)

輸入：string1="Joe's bag", string2="'to be or not to be'"
傳回：string1="Joe''s bag", string2="''to be or not to be''"

範例 4：在插入 DB2 表格的資料中插入額外的單引號

%FUNCTION(DTW_SQL) insertName(){
INSERT INTO USER1.CUSTABLE (LNAME,FNAME)
VALUES ('@DTW_rADDQUOTE(lastname)', '@DTW_rADDQUOTE(firstname)')
%}

輸入：lastname="O'Brien", firstname="Patrick"
傳回："O''Brien", "Patrick"

DTW_CACHE_PAGE

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

目的

快取因巨集處理結果而產生的部份或全部網頁。

格式

@DTW_CACHE_PAGE(cacheid, url, age, status)

參數

表 29. DTW_CACHE_PAGE 參數

參數	使用	說明
`cache_id`	IN	一個字串變數用來識別頁面將被放置的快取記憶體。
`cached_page_ID`	IN	一個包含識別字的字串變數，在後續的 DTW_CACHE_PAGE 快取要求中，用來指定快取頁面的位置。字串可以是一個 URL。
`age`	IN	一個字串變數，包含了以秒為單位的時間長度。這個參數決定一個頁面是否過期。如果頁面已經比 `age` 還要舊時，此頁面就不會被傳送到瀏覽器。如果 `age` 被設定為 -1，且頁面存在快取記憶體中，則不論其經歷時間， Net.Data 會直接從快取記憶體中將它傳送到 Web 瀏覽器。 Net.Data 不會置換快取記憶體中的頁面。
`status`	OUT	顯示快取頁面狀態的字串變數。可能的值是以小寫顯示： ok：當巨集執行終止時，輸出頁面會被送到快取記憶體。 new：頁面不在快取記憶體中。 renew：頁面在快取記憶體中，但已過期。 no_cache：所指定的快取記憶體識別字不存在。必須在快取記憶體架構檔中定義。您的巨集可以繼續執行，無須快取頁面。 inactive：您指定的快取記憶體已被標示為非作用中。您的巨集可以繼續執行，無須快取頁面。 busy：在這次執行中，您的巨集已經曾發出 DTW_CACHE_PAGE 內建函數。您的巨集可以繼續執行。 error：嘗試與快取記憶體通信時發生錯誤。

回覆碼

表 30. DTW_CACHE_PAGE 回覆碼

回覆碼	說明
-1001	伺服器無法處理 Net.Data 的配置記憶體要求。
1001	輸入參數包含 NULL 值。
1002	輸入參數包含的字串有空字元結尾。
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。
1005	函數呼叫上傳遞的參數必須是字串變數，但卻是不同的變數類型。
1006	文字字串傳遞給函數呼叫中的參數，但此參數必須是輸出參數。
1007	參數包含的值無效。

用法注意事項

當 DTW_CACHE_PAGE() 被呼叫時，它會嘗試從快取記憶體取回指定的頁面，並將該頁面傳送到 Web 瀏覽器，就如同它是由巨集所產生的輸出頁面一樣。如果找到頁面且該頁面未過期， Net.Data 會停止巨集的處理、跳出巨集、並將快取的頁面傳送到 Web 瀏覽器。

如果所要求的頁面不在快取記憶體中，或現有的快取頁面已經大於 age 值，Net.Data 會產生新的輸出頁面。當巨集順利的完成後，Net.Data 會將新頁面傳送到瀏覽器，並同時快取頁面。
對於大部份快取應用程式而言，在巨集頂端設定 DTW_CACHE_PAGE()，以便快取執行巨集時產生的所有網頁。這個方法可在更新巨集時更容易維護巨集。例如，當函數位於巨集的中間，一個 HTML 報告區段在較早時加入巨集中，可能會被忽略。 Net.Data 將不會快取新報告輸出。此外，這個方法可以增進執行效能，因為當 Net.Data 決定頁面已快取時，它會停止所有進一步的處理程序。

對於進階快取應用程式而言，當您需要在處理過程中決定快取的特定位置時，您可以將函數放置在巨集的特定位置，而不是巨集開頭。例如，您可能需要基於在查詢或函數呼叫後要傳回多少列數而來作快取的決定。

範例

範例 1：將 DTW_CACHE_PAGE() 函數放置在巨集的開頭，以擷取所有 HTML 輸出

%IF (customer_status == "Classic")
 @DTW_CACHE_PAGE("mymacro.mac", "http://www.mypage.org", "-1", status)
%ENDIF 
 % DEFINE { ...%}
 
...
 
%HTML (OUTPUT) {
 <title>這是頁面標題
 </head>
  <body>
  <center>
 這是主標題
 <p>現在時刻 $(time)。祝您有愉快的一天！
  </body>
  </html>
  
%}

範例 2：將函數放置在 HTML 區塊中，因為快取的決定取決於 HTML 輸出的預期大小

%DEFINE { ...%}
 
...
 
%FUNCTION(DTW_SQL) count_rows(){
  從客戶選取 count(*)
%REPORT{
%ROW{
  @DTW_ASSIGN(ALL_ROWS, V1)
%}
%}
%}
 
%FUNCTION(DTW_SQL) all_customers(){
  select * from customer
%}
 
%HTML (OUTPUT) {
  <html>
 <head>
 <title>這是客戶列表
 </head>
  <body>
 
@count_rows()
 
 %IF ($(ALL_ROWS) > "100")
 @DTW_CACHE_PAGE("mymacro.mac", "http://www.mypage.org", "-1", status)
%ENDIF
 
@all_customers()
 
  </body>
  </html>
%}

在這個範例中，頁面的快取或取回是基於 HTML 輸出的預期大小。只有當資料庫表格內容超過 100 列時，HTML 輸出頁才值得快取。執行巨集後，Net.Data 總是將 OUTPUT 區塊中的文字，這是客戶列表，傳送到瀏覽器；文字從不快取。當 IF 區塊的條件滿足時， @count_rows() 函數呼叫的下幾行，會被快取或取回。兩者一同形成完整的 Net.Data 輸出頁面。

範例 3：動態取回快取記憶體 ID 與快取頁面 ID

%HTML (OUTPUT) {
 %IF (customer == "Joe Smith")
 
@DTW_CACHE_PAGE(@DTW_rGETENV("DTW_MACRO_FILENAME"), @DTW_rGETENV("URL"),"-1", status)
 
%ENDIF
 
...
 
  <html>
 <head>
 <title>這是頁面標題</title>
 </head>
  <body>
  <center>
 <h3>這是主標題</h3>
 <p>今天是 @DTW_rDATE()。祝您有愉快的一天！
  </body>
  </html>
 
%}

DTW_DATE

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

目的

在所指定的格式中傳回現行系統日期。

格式

@DTW_DATE(format, stringOut)

@DTW_DATE(stringOut)

@DTW_rDATE(format)

@DTW_rDATE()

參數

表 31. DTW_DATE 參數

資料類型	參數	使用	說明
字串	`format`	IN	一個指定資料格式的變數或文字字串。有效格式包括： D - 一年中的第幾天 (001-366) E - 歐式日期格式 (dd/mm/yy) N - 一般日期格式 (dd mon yyyy) O - 照順序的日期格式 (yy/mm/dd) S - 標準日期格式 (yyyymmdd) U - 美式日期格式 (mm/dd/yy) 預設值是 N。
字串	`stringOut`	OUT	一個包含具有所指定格式之日期的變數。

回覆碼

表 32. DTW_DATE 回覆碼

回覆碼	說明
-1001	伺服器無法處理 Net.Data 的配置記憶體要求。
1001	輸入參數包含 NULL 值。
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。
1005	函數呼叫上傳遞的參數必須是字串變數，但卻是不同的變數類型。
1006	文字字串傳遞給函數呼叫中的參數，但此參數必須是輸出參數。
1007	參數包含的值無效。

範例

範例 1：一般日期格式

@DTW_DATE(results)

傳回：results = "25 Apr 1997"

範例 2：歐洲日期格式

@DTW_DATE("E", results)

傳回：results="25/04/97"

範例 3：美式日期格式

%HTML(report){
<P>這個報告建立於 @DTW_rDATE("U")。

傳回：04/25/97

DTW_EXIT

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

目的

指定立即離開巨集。Net.Data 會傳送 DTW_EXIT() 被呼叫之前所產生的任何網頁到 Web 瀏覽器。

格式

@DTW_EXIT()

回覆碼

表 33. DTW_EXIT 回覆碼

回覆碼	說明
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。

用法注意事項

使用 DTW_EXIT() 立即停止巨集處理。這個方法可節省 Net.Data 處理整個檔案所花的時間。
確定在新增 DTW_EXIT() 函數之前，整個巨集的語法是正確的。使用 DTW_EXIT() 會使 Net.Data 在遇到此函數的呼叫時停止處理巨集，這可避免您發覺在處理完 DTW_EXIT() 函數之後發生的錯誤。

範例

範例 1：跳出巨集

%HTML(cache_example) {
 
  <html>
 <head>
 <title>這是頁面標題</title>
 </head>
  <body>
  <center>
 <h3>這是主標題</h3>
 <!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!>
 <！Joe Smith 看到一篇非常短的頁面                   ！>
 <!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!>
 %IF (customer == "Joe Smith")
 
@DTW_EXIT()
 
%ENDIF
 
...
 
  </body>
  </html>
 %}

DTW_GETCOOKIE

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

目的

傳回所指定 cookie 的值。

格式

@DTW_GETCOOKIE(IN cookie_name, OUT cookie_value)

@DTW_rGETCOOKIE(IN cookie_name)

參數

表 34. DTW_GETCOOKIE 參數

資料類型	參數	使用	說明
字串	`cookie_name`	IN	指定 cookie 名稱的變數或文字字串。
字串	`cookie_value`	OUT	包含經由函數取回之 cookie 值的變數，例如使用者狀態資訊。 OS/400 與 OS/390 使用者：如果 cookie 值具有 URL 樣式編碼 (例如 "%20")，則 cookie 值會在傳回之前被解碼。工作站使用者：如果 cookie 值具有 URL 樣式編碼 (例如 "%20")，則 cookie 值不會在傳回之前被解碼。

回覆碼

表 35. DTW_GETCOOKIE 回覆碼

回覆碼	說明
-1001	伺服器無法處理 Net.Data 的配置記憶體要求。
1001	輸入參數包含 NULL 值。
1002	輸入參數包含的字串有空字元結尾。
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。
1005	函數呼叫上傳遞的參數必須是字串變數，但卻是不同的變數類型。
1006	文字字串傳遞給函數呼叫中的參數，但此參數必須是輸出參數。
8000	找不到 cookie。

用法注意事項

在兩個不同的 HTTP 要求中定義並取回 cookie。因為 cookie 只能在被傳送到從屬站以後才可看見，如果巨集嘗試去獲得定義於相同 HTTP 要求的 cookie，您可能會接收到不預期的結果。

範例

範例 1：取回包含使用者 ID 和密碼資訊的 cookie

@DTW_GETCOOKIE("mycookie_name_for_userID", userID)
@DTW_GETCOOKIE("mycookie_name_for_password", password)

範例 2：在收集使用者資訊之前，決定使用者 cookie 是否存在

  %MESSAGE {
    8000 : "" : continue
%}
 
%HTML(welcome) {
  <html>
  <body>
  <h1>Net.Data 俱樂部</h1>
  @DTW_GETCOOKIE("NDC_name", name)
  %IF ($(RETURN_CODE) == "8000") %{ 找不到 cookie。%}
  <form method="post" action="remember">
  <p>歡迎蒞臨本會。請輸入您的姓名。<br>
  <input name="name">
  <input type="submit" value="submit"><br>
</form>
%ELSE
  <p>$(name) 您好，歡迎再度光臨。
%ENDIF
  </body>
  </html>
  %}

HTML 歡迎使用區段會檢查 cookie NDC_name 是否存在。如果 cookie 存在，瀏覽器會顯示一個個人化的歡迎。如果 cookie 不存在，套表會要求輸入使用者姓名，並將它置於 HTML remember 區段，如此將使用者名稱設定成如下的 cookie NDC_name：

%HTML(remember) {
  <html>
  <body>
  <H1>Net.Data 俱樂部</H1>
  @DTW_SETCOOKIE("NDC_name", name, "expires=Wednesday, 01-Dec-2010 00:00:00;path=/")
  <p>感謝您。
  <p><a href="welcome">Come back</a>
  </body>
  </html>
  %}

DTW_GETENV

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

目的

將所指定之環境變數的值傳回。

格式

@DTW_GETENV(envVarName, envVarValue)

@DTW_rGETENV(envVarName)

參數

表 36. DTW_GETENV 參數

資料類型	參數	使用	說明
字串	`envVarName`	IN	一個變數或文字字串。
字串	`envVarValue`	OUT	在 envVarName 上所指定的環境變數值。若該值找不到的話將會傳回一個空字串。

回覆碼

表 37. DTW_GETENV 回覆碼

回覆碼	說明
-1001	伺服器無法處理 Net.Data 的配置記憶體要求。
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。
1005	函數呼叫上傳遞的參數必須是字串變數，但卻是不同的變數類型。
1006	文字字串傳遞給函數呼叫中的參數，但此參數必須是輸出參數。

用法注意事項

您亦可使用 ENVVAR 陳述式來參考環境變數的值。有關詳細資訊，請參閱ENVVAR 陳述式。

範例

範例 1：透過 OUT 參數傳回 PATH 陳述式的值

@DTW_GETENV(myEnvVarName, myEnvVarValue)

輸入：myEnvVarName = "PATH"
傳回：myEnvVarValue = "/usr/bin"

範例 2：傳回 PATH 陳述式的值

@DTW_rGETENV(myPath)

輸入：myPath = "PATH"
傳回："/usr/bin"

範例 3：傳回伺服器通信協定的值

伺服器是 @DTW_rGETENV("SERVER_PROTOCOL")。

傳回："HTTP/1.0"

DTW_GETINIDATA

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

目的

傳回所指定之架構變數的值。

格式

@DTW_GETINIDATA(iniVarName, iniVarValue)

@DTW_rGETINIDATA(iniVarName)

參數

表 38. DTW_GETINIDATA 參數

資料類型	參數	使用	說明
字串	`iniVarName`	IN	一個變數或文字字串。
字串	`iniVarValue`	OUT	在 `iniVarName` 中所指定的架構變數值。

回覆碼

表 39. DTW_GETINIDATA 回覆碼

回覆碼	說明
-1001	伺服器無法處理 Net.Data 的配置記憶體要求。
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。
1005	函數呼叫上傳遞的參數必須是字串變數，但卻是不同的變數類型。
1006	文字字串傳遞給函數呼叫中的參數，但此參數必須是輸出參數。

用法注意事項

如果指定的架構變數不是架構檔，則 Net.Data 會傳回空字串。
對於 OS/390、OS/2、Windows NT 及 UNIX 使用者： 架構路徑變數 (MACRO_PATH、EXEC_PATH 和 INCLUDE_PATH)，以及 ENVIRONMENT 陳述式，無法由這個呼叫取回。
對於 OS/400 使用者： ENVIRONMENT 陳述式無法由這個呼叫取回。

範例

範例 1：傳回 Net.Data 路徑變數值

@DTW_GETINIDATA(myEnvVarName, myEnvVarValue)

輸入：myEnvVarName = "FFI_PATH"
傳回：myEnvVarValue = "D:\FFI"

DTW_HTMLENCODE

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

目的

利用 HTML 字元跳出碼來編寫選取的字元。

格式

@DTW_HTMLENCODE(stringIn, stringOut)

@DTW_rHTMLENCODE(stringIn)

參數

表 40. DTW_HTMLENCODE 參數

資料類型	參數	使用	說明
字串	`stringIn`	IN	一個變數或文字字串。
字串	`stringOut`	OUT	一個包含已修改輸入字串的變數，該輸入字串中的某些字元已被 HTML 字元跳出碼所置換。

回覆碼

表 41. DTW_HTMLENCODE 回覆碼

回覆碼	說明
-1001	伺服器無法處理 Net.Data 的配置記憶體要求。
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。
1005	函數呼叫上傳遞的參數必須是字串變數，但卻是不同的變數類型。
1006	文字字串傳遞給函數呼叫中的參數，但此參數必須是輸出參數。

用法注意事項

您可以使用這個函數，來編寫您不希望 Web 瀏覽器解譯為 HTML 的字元資料。例如，藉由使用適當的跳出碼，您可以在網頁內顯示一些字元，例如小於 (<) 及大於 (>) 符號，否則這些字元會被瀏覽器解譯為 HTML 標籤的元件。

表 42 顯示由 DTW_HTMLENCODE 函數所編碼的字元。

表 42. HTML 的字元跳出碼

字元	名稱	程式碼
SPACE	空格
"	雙引號	"
#	號碼記號	#
%	百分比	%
&	＆記號	&
[	左方括弧	(
]	右方括弧	)
+	加	+
\	斜線	/
:	冒號	:
;	分號	;
<	小於	<
=	等於	&#61:
>	大於	&#62:
?	問號	&#63:
@	At 記號	@
/	反斜線	\
^	Carat	^
{	左大括弧	{
\|	直線	\|
}	右大括弧	}
~	波型符號	~

範例

範例 1：對空格字元編碼

@DTW_HTMLENCODE(string1,string2)

輸入：string1 = "Jim's dog"
傳回：string2 = "Jim's dog"

範例 2：對空格、小於符號與等號編碼

@DTW_rHTMLENCODE("X <= 10")

傳回："X <= 10"

DTW_QHTMLENCODE

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

目的

執行與 @DTW_HTMLENCODE 相同的功能，但亦將單引號字元 (') 編寫為 '。表 42 顯示 DTW_QHTMLENCODE 所使用的 HTML 字元跳出碼。

格式

@DTW_QHTMLENCODE(stringIn, stringOut)

@DTW_rQHTMLENCODE(stringIn)

參數

表 43. DTW_QHTMLENCODE 參數

資料類型	參數	使用	說明
字串	`stringIn`	IN	一個變數或文字字串。
字串	`stringOut`	OUT	一個包含已修改格式的 `stringIn` 的變數，其中有某些字元已被 HTML 字元跳出碼所置換。

回覆碼

表 44. DTW_QHTMLENCODE 回覆碼

回覆碼	說明
-1001	伺服器無法處理 Net.Data 的配置記憶體要求。
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。
1005	函數呼叫上傳遞的參數必須是字串變數，但卻是不同的變數類型。
1006	文字字串傳遞給函數呼叫中的參數，但此參數必須是輸出參數。

範例

範例 1：對單引號與空格編碼

@DTW_QHTMLENCODE(string1,string2)

輸入：string1 = "Jim's dog"
傳回：string2 = "Jim's dog"

範例 2：對單引號、空格與＆符號編碼

@DTW_rQHTMLENCODE("John's & Jane's")

傳回："John's & Jane's"

DTW_SENDMAIL

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

目的

動態建立與傳輸電子郵件（e-mail）訊息。

格式

@DTW_SENDMAIL(IN Sender, IN Recipient, IN Message, IN Subject, IN CarbonCopy, IN BlindCarbonCopy, IN ReplyTo, IN Organization)

@DTW_SENDMAIL(IN Sender, IN Recipient, IN Message, IN Subject, IN CarbonCopy, IN BlindCarbonCopy, IN ReplyTo)

@DTW_SENDMAIL(IN Sender, IN Recipient, IN Message, IN Subject, IN CarbonCopy, IN BlindCarbonCopy)

@DTW_SENDMAIL(IN Sender, IN Recipient, IN Message, IN Subject, IN CarbonCopy)

@DTW_SENDMAIL(IN Sender, IN Recipient, IN Message, IN Subject)

@DTW_SENDMAIL(IN Sender, IN Recipient, IN Message)

參數

表 45. DTW_SENDMAIL 參數

資料類型	參數	使用	說明
字串	`sender`	IN	指定作者位址的變數或文字字串。這個參數是必要的。有效的格式為：姓名 <使用者 @ 領域> <使用者 @ 領域> 使用者 @ 領域
字串	`recipient`	IN	指定收件者的電子郵件位址的變數或文字字串。藉由逗點（,）的分隔，這個值可以包含多重收件者。這個參數是必要的。有效的`收件者`格式為：姓名 <使用者 @ 領域> <使用者 @ 領域> 使用者 @ 領域
字串	`message`	IN	包含電子郵件訊息本文的變數或文字字串。這個參數是必要的。
字串	`subject`	IN	包含主旨行文字的變數或文字字串。這是一個可選用的參數。您必須指定一個空字串 ("") 才能指定額外的參數。
字串	`CarbonCopy`	IN	包含額外收件者之電子郵件位址、或姓名與電子郵件位址的變數或文字字串。藉由逗點（,）的分隔，這個值可以包含額外收件者。請參閱 `Recipient` 參數以取得有效的收件者格式。這是一個可選用的參數。您必須指定一個空字串 ("") 才能指定額外的參數。
字串	`BlindCarbonCopy`	IN	包含額外收件者之電子郵件位址、或姓名與電子郵件位址的變數或文字字串，但收件者不會出現在電子郵件表頭。藉由逗點（,）的分隔，這個值可以包含額外收件者。請參閱 `Recipient` 參數以取得有效的收件者格式。這是一個可選用的參數。您必須指定一個空字串 ("") 才能指定額外的參數。
字串	`ReplyTo`	IN	包含回覆此訊息要送往`寄件者`電子郵件的變數或文字字串。這是一個可選用的參數。您必須指定一個空字串 ("") 才能指定額外的參數。有效的`回覆`格式為：姓名 <使用者 @ 領域> <使用者 @ 領域> 使用者 @ 領域
字串	`Organization`	IN	包含`寄件者`組織名稱的變數或文字字串。這是一個可選用的參數。

回覆碼

表 46. DTW_SENDMAIL 回覆碼

回覆碼	說明
-1001	伺服器無法處理 Net.Data 的配置記憶體要求。
1001	輸入參數包含 NULL 值。
1002	輸入參數包含的字串有空字元結尾。
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。
1005	函數呼叫上傳遞的參數必須是字串變數，但卻是不同的變數類型。
7000	Net.Data 無法連接指定的 SMTP 伺服器。
7001	Net.Data 嘗試將電子郵件訊息轉遞至指定的 SMTP 伺服器時，發生 SMTP 錯誤。
7002	指定的 SMTP 伺服器不支援 ESMTP (Extended Simple Mail Transfer Protocol)。

用法注意事項

您可以使用可選用的架構變數 DTW_SMTP_SERVER，指定 SMTP 伺服器來傳輸電子郵件訊息。這個參數值可以是主電腦名稱、IP 位址或節點與名稱。當這個變數沒有被定義， Net.Data 會使用區域主電腦以作為 SMTP 伺服器。若想進一步了解此變數，請參閱您作業系統的 Net.Data 管理和程式設計指南內的架構這一章。
OS/400、OS/2、Windows NT 及 UNIX 使用者： 標準 SMTP (Simple Mail Transfer Protocol) 伺服器只接受 7 位元資料，如 U.S. ASCII 字元。如果您的訊息有 8 位元字元，建議您指定 ESMTP 伺服器， ESMTP 伺服器接受 8 位元字元。 Net.Data 不會將 8 位元資料編碼為 7 位元資料。如果您無法存取 ESMTP 伺服器，從電子郵件訊息中除去所有的 8 位元字元。

Net.Data for OS/390 使用者不必修改電子郵件訊息的 SMTP 伺服器。

字集支援：

OS/400 使用者：您可以使用可選用的架構變數 DTW_SMTP_CHARSET，指定將訊息從 EBCDIC 轉換為 ASCII 時，要使用哪一個 ASCII 字集。如果未指定 DTW_SMTP_CHARSET，則預設字集為 iso-8859-1。有關這個變數及支援的字集之詳細資訊，請參閱 OS/400 版 Net.Data 管理及程式設計指南內的架構這一章。

OS/2、Windows NT 及 UNIX 使用者： 表 47說明所支援的字集：

表 47. Net.Data 支援的字集

語言環境	字集	OS/2 或 UNIX 字碼頁	Windows NT 字碼頁
美國, 西歐	"iso-8859-1"	819	1252
日文	"x-sjis"	943	932
中文 (簡體)	"gb2312"	1381	936
韓文	"euc-kr"	970	949
中文 (繁體)	"big5"	950	950

下列列示說明 Net.Data 不傳送電子郵件訊息的條件：
- 無法聯繫指定的 SMTP 伺服器。
- 指定的 SMTP 伺服器不支援 ESMTP (Extended Simple Mail Transfer Protocol )，但指定的電子郵件卻包含非美式 ASCII 字集。

範例

範例 1：建立並傳送一個簡單電子郵件訊息的函數呼叫

@DTW_SENDMAIL("<ibmuser1@ibm.com>", "<ibmuser2@ibm.com>", "在 9:30 有一個會議。",
"狀態會議")

DTW_SENDMAIL 函數傳送電子郵件訊息時包含下列資訊：

日期：Mon, 3 Apr 1998 09:54:33 PST
收件者：<ibmuser2@ibm.com>
寄件者：<ibmuser1@ibm.com>
主旨：狀態會議
 
在 9:30 有一個會議。

日期的資訊是使用系統日期和時間函數建構而成，並以 SMTP 特定資料格式呈現。

範例 2：建立並傳送多重收件者、副本與密件副本收件者與公司名稱的電子郵件訊息的函數呼叫

@DTW_SENDMAIL("IBM User 1 <ibmuser1@ibm.com>", "IBM User 2 <ibmuser2@ibm.com>, 
IBM User 3 <ibmuser3@ibm.com>, IBM User 4 <ibmuser4@ibm.com>", "There is a meeting at 9:30.", 
"Status meeting", "IBM User 5 <ibmuser5@ibm.com>", "IBM User 6 <ibmuser6@ibm.com", 
"meeting@ibm.com", "IBM")

DTW_SENDMAIL 函數傳送電子郵件訊息時包含下列資訊：

日期：Mon, 3 Apr 1998 09:54:33 PST
收件者：IBM 使用者 2 <ibmuser2@ibm.com>, IBM 使用者 3 <ibmuser3@ibm.com>, IBM 使用者 4 <ibmuser4@ibm.com>
副本：IBM 使用者 5 <ibmuser5@ibm.com>
密件副本：IBM User 6 <ibmuser6@ibm.com>
收件者：IBM 使用者 1 <ibmuser1@ibm.com>
回覆：meeting@ibm.com
組織：IBM
主旨：狀態會議
 
在 9:30 有一個會議。

範例 3：經由 Web 套表介面建立並傳送電子郵件的巨集

  %HTML(start) {
  <html>
  <body>
  <h1>Net.Data 電子郵件範例</h1>
  <form method="post" action="sendemail">
  <p>給：<br><input name="recipient"><p>
  主旨：<br><input name="subject"><p>
  訊息：<br><textarea name=message rows=20 cols=40>
  </textarea><p>
  <input type="submit" value="Send E-mail"><br>
</form>
  </body>
  </html>
  %}
 
  %HTML(sendemail) {
  <html>
  <body>
  <h1>Net.Data 電子郵件範例</h1>
  @DTW_SENDMAIL("Net.Data E-mail Service <netdata@us.ibm.com>", recipient, message, subject)
  <p>電子郵件已送出。
  </body>
  </html>
  %}

這個巨集是經由 Web 套表介面傳送電子郵件。HTML 的啟動區段中顯示一個套表，收件者的電子郵件位址、主旨與訊息都可以鍵入。當使用者按一下傳送電子郵件按鈕，訊息就被傳送到 HTML(sendemail) 區段中指定的收件者。這個區段呼叫 DTW_SENDMAIL，並使用從 Web 套表中獲得的參數來決定電子郵件訊息的內容、與寄件者與收件者。一旦電子郵件訊息傳送出去，便會顯示確認通知。

範例 4：使用 SQL 查詢來決定收件者列示的巨集

%Function(DTW_SQL) mailing_list(IN message) {
  SELECT EMAIL_ADDRESS FROM CUSTOMERS WHERE ZIPCODE='CA'
%REPORT {
      傳送產品資訊給所有住在加州的客戶...<P>
  %ROW {
        @DTW_SENDMAIL("John Doe Corp. <John.Doe@doe.com>", V1, message, "New Product Release")
        E-mail 已送出給客戶 $(V1)。<BR>
      %}
    %}
  %}

經由客戶資料庫的 SQL 查詢結果所決定，這個巨集會自動傳送電子郵件訊息到指定的客戶群組。SQL 查詢也取回客戶的電子郵件位址。電子郵件內容是由 message 值所決定，而且可以是靜態或動態的（例如您可以使用另一個 SQL 查詢來動態指定產品的版本號碼，或各種報價的價格）。

DTW_SETCOOKIE

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

目的

產生可在從屬站系統上設定 cookie 的 JavaScript 程式碼。

格式

@DTW_SETCOOKIE(IN cookie_name, IN cookie_value, IN advanced_options)

@DTW_SETCOOKIE(IN cookie_name, IN cookie_value)

參數

表 48. DTW_SETCOOKIE 參數

資料類型	參數	使用	說明
字串	`cookie_name`	IN	指定 cookie 名稱的變數或文字字串。
字串	`cookie_value`	IN	指定 cookie 值的變數或文字字串。避免在 `cookie_value` 中使用分號 (;)、逗點 (,) 及空格。若需要這些特殊字元時，請先使用 Net.Data 函數 DTW_rURLESCSEQ 來處理包含這些特殊字元的字串，再將字串遞送到 DTW_SETCOOKIE。例如， @DTW_SETCOOKIE("my_cookie_name", @DTW_rURLESCSEQ("my cookie value"))
字串	`advanced_options`	IN	包含可選用屬性的字串，由分號所隔開，可用來定義 cookie。這些屬性可以是： `到期` = `日期` 指定一個定義 cookie 有效生命週期的日期字串。在到期日以後，便不再儲存或取回 cookie。語法： `weekday`, `DD`-`month`-`YYYY HH:MM:SS` GMT 其中： `weekday` 指定工作日的完整名稱。 `DD` 指定某月中的日期。 `month` 指定月份的三字元縮寫。 `YYYY` 指定年份的四字元號碼。 `HH:MM:SS` 以小時、分鐘與秒鐘來指定時間戳記。 `領域` = `領域名稱` 指定 cookie 的領域屬性，使用在領域屬性匹配。 `路徑` = `路徑` 指定 cookie 是有效的領域中 URL 的子集。 `安全` 指定 cookie 只能透過安全的通道傳輸到 HTTPS 伺服器。未指定 `secure` 選項時，cookie 可以透過非安全的通道傳送。安全選項不需要瀏覽器對 cookie加密，也不需要它確保包含 DTW_SETCOOKIE 陳述式的 HTML 頁面要透過 SSL 傳輸。有關進階選項的其餘資訊，請參閱網站 `http://home.netscape.com` 上的 Netscape cookie 規格。

回覆碼

表 49. DTW_SETCOOKIE 回覆碼

回覆碼	說明
-1001	伺服器無法處理 Net.Data 的配置記憶體要求。
1001	輸入參數包含 NULL 值。
1002	輸入參數包含的字串有空字元結尾。
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。
1005	函數呼叫上傳遞的參數必須是字串變數，但卻是不同的變數類型。

用法注意事項

如果從屬站 Web 瀏覽器不支援 Java Script，瀏覽器便不設定 cookie。
因為 DTW_SETCOOKIE 會產生 Java Script，請勿在 <SCRIPT> 或 <NOSCRIPT> HTML 元素中呼叫 DTW_SETCOOKIE。
要取回 cookie，請使用 DTW_GETCOOKIE() 函數。請參閱DTW_GETCOOKIE以學習如何定義 cookie。
在兩個不同的 HTTP 要求中定義並取回 cookie。因為 cookie 只能在被傳送到從屬站以後才可看見，如果巨集嘗試去獲得定義於相同 HTTP 要求的 cookie，您可能會接收到不預期的結果。

範例

範例 1：以「安全」進階選項來定義包含使用者 ID 和密碼資訊

@DTW_SETCOOKIE("mycookie_name_for_userID", "User1")
@DTW_SETCOOKIE("mycookie_name_for_password", "sd3dT", "secure")

範例 2：定義包含到期日進階選項的 cookie

@DTW_SETCOOKIE("mycookie_name_for_userID", "User1",
   "expires=Wednesday 01-Dec-2010 00:00:00")
@DTW_SETCOOKIE("mycookie_name_for_password", "sd3dT", "expires=Wednesday, 01-Dec-2010 00:00:00; secure")

函數呼叫應在同一行；本範例中分成許多行是受限於版面。

範例 3：在收集使用者資訊之前，決定使用者 cookie 是否存在

%HTML(welcome) {
  <html>
  <body>
  <h1>Net.Data 俱樂部</h1>
  @DTW_GETCOOKIE("NDC_name", name)
  %IF ($(RETURN_CODE) == "8000") %{ 找不到 cookie。%}
  <form method="post" action="remember">
  <p>歡迎蒞臨本會。請輸入您的姓名。<br>
  <input name="name">
  <input type="submit" value="submit"><br>
</form>
%ELSE
  <p>$(name) 您好，歡迎再度光臨。
%ENDIF
  </body>
  </html>
  %}

HTML(welcome) 區段會檢查 cookie NDC_name 是否存在。如果 cookie 存在，瀏覽器會顯示一個個人化的歡迎。如果 cookie 不存在，瀏覽器會要求使用者輸入名稱，並將它置於 HTML(remember) 區段。這個區段將使用者名稱記錄到 cookie NDC_name，如下面所顯示：

%HTML(remember) {
  <html>
  <body>
  <H1>Net.Data 俱樂部>
  @DTW_SETCOOKIE("NDC_name", name, "expires=Wednesday, 01-Dec-2010 00:00:00;path=/")
  <p>感謝您。
  <p><a href="welcome">Come back</a>
  </body>
  </html>
  %}

DTW_SETENV

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

目的

指定一個指定值給一環境變數，並傳回上一個值。

格式

@DTW_SETENV(envVarName, envVarValue, prevValue)

@DTW_rSETENV(envVarName, envVarValue)

參數

表 50. DTW_SETENV 參數

資料類型	參數	使用	說明
字串	`envVarName`	IN	一個代表環境變數的變數或文字字串。
字串	`envVarValue`	IN	一個有指定為環境變數數值的變數或文字字串。
字串	`prevValue`	OUT	一個包含環境變數之上一個值的變數。

回覆碼

表 51. DTW_SETENV 回覆碼

回覆碼	說明
-1001	伺服器無法處理 Net.Data 的配置記憶體要求。
1001	輸入參數包含 NULL 值。
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。
1005	函數呼叫上傳遞的參數必須是字串變數，但卻是不同的變數類型。
1006	文字字串傳遞給函數呼叫中的參數，但此參數必須是輸出參數。

用法注意事項

如果找不到先前的環境變數值，則傳回空字串。

範例

範例 1：傳回前路徑的值

@DTW_SETENV("PATH", "myPath", prevValue)

輸入：envVarName = "PATH", envVarValue = "myPath"
傳回：prevValue = "myPreviousPath"

範例 2：傳回前路徑的值，並指定 PATH 的值

@DTW_rSETENV("PATH", "myPath")

輸入：envVarName = "PATH", envVarValue = "myPath"
傳回："myPreviousPath", PATH = "myPath"

DTW_TIME

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

目的

以所指定的格式將現行系統時間傳回。

格式

@DTW_TIME(stringIn, stringOut)

@DTW_TIME(stringOut)

@DTW_rTIME(stringIn)

@DTW_rTIME()

參數

表 52. DTW_TIME 參數

資料類型	參數	使用	說明
字串	`stringIn`	IN	指定時間格式的變數或文字字串。有效的格式為： C - 常用時間 (hh:mmAM/PM 以 12 小時時間顯示） L - 區域時間 (hh:mm:ss) N - 正常時間 (hh:mm:ss 以 24 小時時間顯示）；預設值 X - 擴充時間 (hh:mm:ss.ccc 以 24 小時格式顯示，其中 ccc 是指毫秒數) H - 從午夜 12 點起算的小時數 M - 從午夜 12 點起算的分鐘數 S - 從午夜 12 點起算的秒數
字串	`stringOut`	OUT	一個包含以所指定格式顯示之時間的變數。

回覆碼

表 53. DTW_TIME 回覆碼

回覆碼	說明
-1001	伺服器無法處理 Net.Data 的配置記憶體要求。
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。
1005	函數呼叫上傳遞的參數必須是字串變數，但卻是不同的變數類型。
1006	文字字串傳遞給函數呼叫中的參數，但此參數必須是輸出參數。
1007	參數包含的值無效。

範例

範例 1：24 小時時間格式

@DTW_TIME(results)

傳回：results = "10:30:53"

範例 2：常用時間格式

@DTW_TIME("C", results)

傳回：results = "10:30AM"

範例 3：以函數呼叫傳回從午夜起算的分鐘數

@DTW_rTIME("M")

傳回："630"

範例 4：以函數呼叫傳回時間預設值與資料格式

%REPORT{
<P>這個報告於 @DTW_rTIME()，@DTW_rDATE() 建立的。
%}

傳回：這個報告於 15:04:39，01 May 1997 建立的。

DTW_URLESCSEQ

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

目的

URL 中不容許的已選取字元以其跳出值來置換，即所謂的 URL 編碼。

格式

@DTW_URLESCSEQ(stringIn, stringOut)

@DTW_rURLESCSEQ(stringIn)

參數

表 54. DTW_URLESCSEQ 參數

資料類型	參數	使用	說明
字串	`stringIn`	IN	一個變數或文字字串。
字串	`stringOut`	OUT	一個包含輸入字串的變數，該輸入字串具有 URL 中不允許的字元，會由它們的十六進位跳出值來置換。

回覆碼

表 55. DTW_URLESCSEQ 回覆碼

回覆碼	說明
-1001	伺服器無法處理 Net.Data 的配置記憶體要求。
1003	函數呼叫中傳遞的參數超過容許數目，或少於函數要求的最小數目。
1005	函數呼叫上傳遞的參數必須是字串變數，但卻是不同的變數類型。
1006	文字字串傳遞給函數呼叫中的參數，但此參數必須是輸出參數。

用法注意事項

您可以使用這個函數，將表 56中列示的任何字元傳送到另一個巨集或 HTML 區塊。

表 56. URL 的字元跳出值

字元	名稱	程式碼
SPACE	空格	%20
"	雙引號	%22
#	號碼記號	%23
%	百分比	%25
&	＆記號	%26
+	加	%2B
\	反斜線	%2F
:	冒號	%3A
;	分號	%3B
<	小於	%3C
=	等於	%3D
>	大於	%3E
?	問號	%3F
@	At 記號	%40
[	左方括弧	%5B
/	斜線	%5C
]	右方括弧	%5D
^	Carat	%5E
{	左大括弧	%7B
\|	直線	%7C
}	右大括弧	%7D
~	波型符號	%7E

範例

範例 1：以跳出值置換 string1 中的＆符號與空格，並將結果指定到 string2

@DTW_URLESCSEQ(string1,string2)

輸入：string1 = "Guys & Dolls"
傳回：string2 = "Guys%20%26%20Dolls"

範例 2：以跳出碼置換空格與＆符號。

@DTW_rURLESCSEQ("Guys & Dolls")

傳回："Guys%20%26%20Dolls"

範例 3：在 ROW 區塊中使用 DTW_rURLESCSEQ，並以跳出碼置換空格和 'at' 字元。

%ROW{
<P><a href="fullRpt.mac/input?name=@DTW_rURLESCSEQ(V1)&email=@DTW_rULRESCSEQ(V2)">
$(V1)</a>
%}

輸入：V1="Patrick O'Brien", V2="obrien@ibm.com"

傳回：

<P><a href="fullrpt.mac/input?name=Patrick%20O'Brien&email="obrien%40ibm.com">
Patrick O'Brien</a>

當應用程式使用者按一下名稱 "Patrick O'Brien" 時，指定給名稱和電子郵件位址的值會在 URL 查詢字串中矩陣式排列，這會導致 Net.Data 執行 fullrpt.mac 巨集的輸入區段。

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