Reference

General Functions

General functions help you develop Web pages with Net.Data and do not fit in the other categories. The following functions are general-purpose functions:

• 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

Purpose

Replaces single quotes in an input string with two single quotes.

Format

@DTW_ADDQUOTE(stringIn, stringOut)

@DTW_rADDQUOTE(stringIn)

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

Parameters

Table 27. DTW_ADDQUOTE Parameters

Return Codes

Table 28. DTW_ADDQUOTE Return Codes

Usage Notes

Consider using this function for all SQL INPUT statements where input is obtained from a Web browser. For example, if you enter O'Brien as a last name, as in the following example, the single quote might give you an error:

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

Using the DTW_ADDQUOTE function changes the SQL statement and prevents the error:

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

Examples

Example 1: Adds an extra single quote on the OUT parameter

@DTW_ADDQUOTE(string1,string2)

• Input: string1="John's Web page"
• Returns: string2="John''s Web page"

Example 2: Adds an extra single quote on the returned value of the function call

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

• Returns: "The title of the article is ''Once upon a time''"

Example 3: Adds extra single quotation marks on each of the INOUT parameters of the function call

@DTW_mADDQUOTE(string1,string2)

• Input: string1="Joe's bag", string2="'to be or not to be'"
• Returns: string1="Joe''s bag", string2="''to be or not to be''"

Example 4: Inserts extra single quotation marks into data being inserted in a DB2 table

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

• Input: lastname="O'Brien", firstname="Patrick"
• Returns: "O''Brien", "Patrick"

DTW_CACHE_PAGE

Purpose

Caches partial or complete Web pages that are generated as a result of the processing of macros.

Format

@DTW_CACHE_PAGE(cacheid, url, age, status)

Parameters

Table 29. DTW_CACHE_PAGE Parameters

Return Codes

Table 30. DTW_CACHE_PAGE Return Codes

Usage Notes

1. When invoked, DTW_CACHE_PAGE() attempts to retrieve the specified page from the cache and to send it to the Web browser as if it were the output page generated from the macro. If the page is found and it has not expired, Net.Data stops processing the macro, exits from the macro, and sends the cached page to the Web browser.

   If the requested page is not in the cache or the existing cached page is older than the value of age, Net.Data generates a new output page. When the macro successfully completes, Net.Data sends the new page to the browser and caches the page.

2. For most caching applications, specify DTW_CACHE_PAGE() at the top of the macro to cache all of the Web page that is generated when the macro executes. This technique makes it asier to maintain the macro when the macro is updated. For example, when the function is in the middle of the macro, it might not be noticed when a HTML report section is added earlier in the macro. Net.Data would not cache the new report output. Additionally, this method improves performance as Net.Data stops all further processing when it determines that the page is cached.

   For advanced caching applications, you can place the function in specific locations of the macro when you need to make the decision to cache at a specific point during processing, rather than at the beginning of the macro. For example, you might need to make the caching decision based on how many rows are returned from a query or function call.

Examples

Example 1: Places the DTW_CACHE_PAGE() function at the beginning of the macro to capture all HTML output

%IF (customer_status == "Classic")
@DTW_CACHE_PAGE("mymacro.mac", "http://www.mypage.org", "-1", status)
%ENDIF 
 % DEFINE { ...%}
 
...
 
%HTML(OUTPUT) {
 <title>This is the page title
 </head>
 <body>
 <center>
 This is the Main Heading
 <p>It is $(time). Have a nice day!
 </body>
 </html>
  
%} 

Example 2: Places the function in the HTML block because the decision to cache depends on the expected size of the HTML output

%DEFINE { ...%}
 
...
 
%FUNCTION(DTW_SQL) count_rows(){
  select count(*) from customer
%REPORT{
 %ROW{
  @DTW_ASSIGN(ALL_ROWS, V1)
%}
%}
%}
 
%FUNCTION(DTW_SQL) all_customers(){
  select * from customer
%}
 
%HTML(OUTPUT) {
<html>
<head>
 <title>This is the customer list
 </head>
 <body>
 
@count_rows()
 
 %IF ($(ALL_ROWS) > "100")
 @DTW_CACHE_PAGE("mymacro.mac", "http://www.mypage.org", "-1", status)
%ENDIF
 
@all_customers() 
 
 </body>
 </html>
%}

In this example, the page is cached or retrieved based on the expected size of the HTML output. HTML output pages are considered cache-worthy only when the database table contains more than 100 rows. Net.Data always sends the text in the OUTPUT block, This is the customer list, to the browser after executing the macro; the text is never cached. The lines following the function call, @count_rows(), are cached or retrieved when the conditions of the IF block are satisfied. Together, both parts form a complete Net.Data output page.

Example 3: Dynamically retrieves the cache ID and the cached page ID

%HTML(OUTPUT) {
 %IF (customer == "Joe Smith")
 
@DTW_CACHE_PAGE(@DTW_rGETENV("DTW_MACRO_FILENAME"), @DTW_rGETENV("URL"),"-1", status)
 
%ENDIF
 
...
 
<html>
 <head>
 <title>This is the page title</title>
 </head>
 <body>
 <center>
 <h3>This is the Main Heading</h3>
 <p>It is @DTW_rDATE(). Have a nice day!
 </body>
</html>
 
%}

DTW_DATE

Purpose

Returns the current system date in the specified format.

Format

@DTW_DATE(format, stringOut)

@DTW_DATE(stringOut)

@DTW_rDATE(format)

@DTW_rDATE()

Parameters

Table 31. DTW_DATE Parameters

Return Codes

Table 32. DTW_DATE Return Codes

Examples

Example 1: Normal date format

@DTW_DATE(results)

• Returns: results = "25 Apr 1997"

Example 2: European date format

@DTW_DATE("E", results)

• Returns: results="25/04/97"

Example 3: US date format

%HTML(report){
<P>This report created on @DTW_rDATE("U").

• Returns: 04/25/97

DTW_EXIT

Purpose

Specifies to leave the macro immediately. Net.Data sends any Web pages that are generated prior to DTW_EXIT() being called to the Web browser .

Format

@DTW_EXIT()

Return Codes

Table 33. DTW_EXIT Return Codes

Usage Notes

1. Use DTW_EXIT() to immediately stop the processing of a macro. Using this technique saves the time Net.Data would use to process the entire file.
2. Ensure that the entire macro is syntactically correct before adding the DTW_EXIT() function. Using DTW_EXIT() causes Net.Data to stop processing the macro when it encounters the call to this function, which can prevent you from catching errors that occur after the DTW_EXIT() function has been processed.

Examples

Example 1: Exiting a macro

%HTML(cache_example) {
 
<html>
 <head>
 <title>This is the page title</title>
 </head>
 <body>
 <center>
 <h3>This is the Main Heading</h3>
 <!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!>
 <! Joe Smith sees a very short page                   !>
 <!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!>
 %IF (customer == "Joe Smith")
 
@DTW_EXIT()
 
%ENDIF
 
...
 
</body>
 </html>
 %}

DTW_GETCOOKIE

Purpose

Returns the value of the specified cookie.

Format

@DTW_GETCOOKIE(IN cookie_name, OUT cookie_value)

@DTW_rGETCOOKIE(IN cookie_name)

Parameters

Table 34. DTW_GETCOOKIE Parameters

Return Codes

Table 35. DTW_GETCOOKIE Return Codes

Usage Notes

Define and retrieve a cookie in two separate HTTP requests. Because a cookie is visible only after it has been sent to the client, if a macro tries to get a cookie that was defined in the same HTTP request, you might receive unexpected results.

Examples

Example 1: Retrieves cookies that contain user ID and password information

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

Example 2: Determines if a cookie for a user exists before gathering user information

%MESSAGE {
    8000 : "" : continue
%}
 
%HTML(welcome) {
  <html>
  <body>
  <h1>Net.Data Club</h1>
  @DTW_GETCOOKIE("NDC_name", name)
  %IF ($(RETURN_CODE) == "8000") %{ The cookie is not found. %}
  <form method="post" action="remember">
  <p>Welcome to the club. Please enter your name.<br>
  <input name="name">
  <input type="submit" value="submit"><br>
  </form>
  %ELSE
  <p>Hi, $(name). Welcome back.
  %ENDIF
  </body>
  </html>
  %}

The HTML welcome section checks whether the cookie NDC_name exists. If the cookie exists, the browser displays a personalized greeting. If the cookie does not exist, the form prompts for the user's name, and posts it to the HTML remember section, which sets the user's name into the cookie NDC_name as shown below:

%HTML(remember) {
  <html>
  <body>
  <H1>Net.Data Club</H1>
  @DTW_SETCOOKIE("NDC_name", name, "expires=Wednesday, 01-Dec-2010 00:00:00;path=/")
  <p>Thank you.
  <p><a href="welcome">Come back</a>
  </body>
  </html>
  %}

DTW_GETENV

Purpose

Returns the value of the specified environment variable.

Format

@DTW_GETENV(envVarName, envVarValue)

@DTW_rGETENV(envVarName)

Parameters

Table 36. DTW_GETENV Parameters

Return Codes

Table 37. DTW_GETENV Return Codes

Usage Notes

You can also use the ENVVAR statement to reference the values of environment variables. For more information, see ENVVAR Statement.

Examples

Example 1: Returns the value for the PATH statement on the OUT parameter

@DTW_GETENV(myEnvVarName, myEnvVarValue)

• Input: myEnvVarName = "PATH"
• Returns: myEnvVarValue = "/usr/bin"

Example 2: Returns the value for the PATH statement

@DTW_rGETENV(myPath)

• Input: myPath = "PATH"
• Returns: "/usr/bin"

Example 3: Returns the value for the protocol of the server

The server is @DTW_rGETENV("SERVER_PROTOCOL").

• Returns: "HTTP/1.0"

DTW_GETINIDATA

Purpose

Returns the value of the specified configuration variable.

Format

@DTW_GETINIDATA(iniVarName, iniVarValue)

@DTW_rGETINIDATA(iniVarName)

Parameters

Table 38. DTW_GETINIDATA Parameters

Return Codes

Table 39. DTW_GETINIDATA Return Codes

Usage Notes

1. If a configuration variable is specified that is not the configuration file, Net.Data returns an empty string.
2. For OS/390, OS/2, Windows NT, and UNIX users: configuration path variables (MACRO_PATH, EXEC_PATH, and INCLUDE_PATH), as well as ENVIRONMENT statements, cannot be retrieved with this call.
3. For OS/400 users: ENVIRONMENT statements cannot be retrieved with this call.

Examples

Example 1: Returns the Net.Data path variable value

@DTW_GETINIDATA(myEnvVarName, myEnvVarValue)

• Input: myEnvVarName = "FFI_PATH"
• Returns: myEnvVarValue = "D:\FFI"

DTW_HTMLENCODE

Purpose

Encodes selected characters using HTML character escape codes.

Format

@DTW_HTMLENCODE(stringIn, stringOut)

@DTW_rHTMLENCODE(stringIn)

Parameters

Table 40. DTW_HTMLENCODE Parameters

Return Codes

Table 41. DTW_HTMLENCODE Return Codes

Usage Notes

1. Use this function to encode character data that you do not want the Web browser to interpret as HTML. For example, by using the appropriate escape code, you can display characters such as less-than (<) and greater-than (>) within a Web page, which would otherwise be interpreted by the browser as components of HTML tags.
2. Table 42 shows the characters that are encoded by the DTW_HTMLENCODE function.
   

   Table 42. Character Escape Codes for HTML
   

   Character	Name	Code
   SPACE	Space	 
   "	Double quote	"
   #	Number sign	#
   %	Percent	%
   &	Ampersand	&
   [	Left bracket	(
   ]	Right bracket	)
   +	Plus	+
   \	Slash	/
   :	Colon	:
   ;	Semicolon	&#59;
   <	Less than	&#60;
   =	Equals	&#61:
   >	Greater than	&#62:
   ?	Question mark	&#63:
   @	At sign	&#64;
   /	Backslash	&#92;
   ^	Carat	&#94;
   {	Left brace	&#123;
   |	Straight line	&#124;
   }	Right brace	&#125;
   ~	Tilde	&#126;

Examples

Example 1: Encodes the space character

@DTW_HTMLENCODE(string1,string2)

• Input: string1 = "Jim's dog"
• Returns: string2 = "Jim's&#32;dog"

Example 2: Encodes spaces, the less-than sign, and the equal sign

@DTW_rHTMLENCODE("X <= 10")

• Returns: "X&#32;&#60;&#61;&#32;10"

DTW_QHTMLENCODE

Purpose

Performs the same function as @DTW_HTMLENCODE but also encodes the single-quote character (') as &#39;. The HTML character escape codes that DTW_QHTMLENCODE uses are shown in Table 42.

Format

@DTW_QHTMLENCODE(stringIn, stringOut)

@DTW_rQHTMLENCODE(stringIn)

Parameters

Table 43. DTW_QHTMLENCODE Parameters

Return Codes

Table 44. DTW_QHTMLENCODE Return Codes

Examples

Example 1: Encodes an apostrophe and a space

@DTW_QHTMLENCODE(string1,string2)

• Input: string1 = "Jim's dog"
• Returns: string2 = "Jim&#39;s&#32;dog"

Example 2: Encodes apostrophes, spaces, and an ampersand

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

• Returns: "John&#39;s&#32;&#38;&#32;Jane&#39;s"

DTW_SENDMAIL

Purpose

Dynamically builds and transmits electronic mail (e-mail) messages.

Format

@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)

Parameters

Table 45. DTW_SENDMAIL Parameters

Return Codes

Table 46. DTW_SENDMAIL Return Codes

Usage Notes

1. You can use the optional configuration variable, DTW_SMTP_SERVER, to specify the SMTP server to use for transmitting e-mail messages. The value of this parameter can either be a host name, an IP address, or a node and name. When this variable is not defined, Net.Data uses the local host as the SMTP server. See the configuration chapter in the Net.Data Administration and Programming Guide for your operating system to learn more about this variable.
2. OS/400, OS/2, Windows NT, and UNIX users: Standard Simple Mail Transfer Protocol (SMTP) servers accept only 7-bit data, such as U.S. ASCII characters. If your message has 8-bit characters, it is recommended that you specify an Extended Simple Mail Transfer Protocol (ESMTP) server; ESMTP servers accept 8-bit characters. Net.Data does not encode your 8-bit data into 7-bit data. If you do not have access to an ESMTP server, remove all 8-bit characters from the e-mail message.

   Net.Data for OS/390 users do not need to modify e-mail messages for SMTP servers.

3. Character set support:
   • OS/400 users: You can use the optional configuration variable, DTW_SMTP_CHARSET to specified which ASCII character to use when converting the message from EBCDIC to ASCII. If DTW_SMTP_CHARSET is not specifcied, the default character set is iso-8859-1. See the configuration chapter in Net.Data Administration and Programming Guide for OS/400 to learn more about this variable and the supported character sets.
   • OS/2, Windows NT, and UNIX users: Table 47 describes the supported character sets:
     

     Table 47. Character sets supported by Net.Data
     

     Locale	Character set	OS/2 or UNIX codepage	Windows NT codepage
     U.S, Western Europe	"iso-8859-1"	819	1252
     Japan	"x-sjis"	943	932
     Chinese (simplified)	"gb2312"	1381	936
     Korea	"euc-kr"	970	949
     Chinese (traditional)	"big5"	950	950

4. The following list describes conditions under which Net.Data does not send an e-mail message:
   • The specified SMTP server cannot be reached.
   • The specified SMTP server does not support the Extended Simple Mail Transfer Protocol (ESMTP), but the specified e-mail message contains non-U.S. ASCII characters.

Examples

Example 1: Function call that builds and sends a simple e-mail message

@DTW_SENDMAIL("<ibmuser1@ibm.com>", "<ibmuser2@ibm.com>", "There is a meeting at 9:30.", 
"Status meeting")

The DTW_SENDMAIL function sends an e-mail message with the following information:

Date: Mon, 3 Apr 1998 09:54:33 PST
To: <ibmuser2@ibm.com>
From: <ibmuser1@ibm.com>
Subject: Status meeting
 
There is a meeting at 9:30.
 

The information for Date is constructed by using the system date and time functions and is formatted in a SMTP-specific data format.

Example 2: Function call that builds and sends an e-mail message with multiple recipients, carbon copy and blind carbon copy recipients, and the company name

@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")

The DTW_SENDMAIL function sends an e-mail message with the following information:

Date: Mon, 3 Apr 1998 09:54:33 PST
To: IBM User 2 <ibmuser2@ibm.com>, IBM User 3 <ibmuser3@ibm.com>, IBM User 4 <ibmuser4@ibm.com>
CC: IBM User 5 <ibmuser5@ibm.com>
BCC: IBM User 6 <ibmuser6@ibm.com>
From: IBM User 1 <ibmuser1@ibm.com>
ReplyTo: meeting@ibm.com
Organzation: IBM
Subject: Status meeting
 
There is a meeting at 9:30.

Example 3: Macro that builds and sends e-mail through a Web form interface

  %HTML(start) {
  <html>
  <body>
  <h1>Net.Data E-Mail Example</h1>
  <form method="post" action="sendemail">
  <p>To:<br><input name="recipient"><p>
  Subject:<br><input name="subject"><p> 
  Message:<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 E-Mail Example</h1>
  @DTW_SENDMAIL("Net.Data E-mail Service <netdata@us.ibm.com>", recipient, message, subject)
  <p>E-mail has been sent out.
  </body>
  </html>
  %}

This macro sends e-mail through a Web form interface. The HTML start section displays a form into which the recipient's e-mail address, a subject, and a message can be typed. When the user clicks on the Send E-mail button, the message is sent out to the recipients specified in the HTML(sendemail) section. This section calls DTW_SENDMAIL and uses the parameters obtained from the Web form to determine the content of the e-mail message, as well as the sender and recipients. Once the e-mail messages have been sent, a confirmation notice is displayed.

Example 4: A macro that uses an SQL query to determine the list of recipients

%Function(DTW_SQL) mailing_list(IN message) {
  SELECT EMAIL_ADDRESS FROM CUSTOMERS WHERE ZIPCODE='CA'
    %REPORT {
      Sending out product information to all customers who live in California...<P>
      %ROW {
        @DTW_SENDMAIL("John Doe Corp. <John.Doe@doe.com>", V1, message, "New Product Release")
        E-mail sent out to customer $(V1).<BR>
      %}
    %}
  %}

This macro sends out an automated e-mail message to a specified group of customers determined by the results of a SQL query from the customer database. The SQL query also retrieves the e-mail addresses of the customers. The e-mail contents are determined by the value of message and can be static or dynamic (for example, you could use another SQL query to dynamically specify the version number of the product or the prices of various offerings).

DTW_SETCOOKIE

Purpose

Generates JavaScript code that sets a cookie on the client system.

Format

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

@DTW_SETCOOKIE(IN cookie_name, IN cookie_value)

Parameters

Table 48. DTW_SETCOOKIE Parameters

@DTW_SETCOOKIE("my_cookie_name", 
  @DTW_rURLESCSEQ("my cookie value"))

Return Codes

Table 49. DTW_SETCOOKIE Return Codes

Usage Notes

1. If the client Web browser does not support Java Script, the browser does not set the cookie.
2. Because DTW_SETCOOKIE generates Java Script code, do not call DTW_SETCOOKIE inside a <SCRIPT> or <NOSCRIPT> HTML element.
3. To retrieve a cookie, use the DTW_GETCOOKIE() function. See DTW_GETCOOKIE to learn how to define a cookie.
4. Define and retrieve a cookie in two separate HTTP requests. Because a cookie is visible only after it has been sent to the client, if a macro tries to get a cookie that was defined in the same HTTP request, you might receive unexpected results.

Examples

Example 1: Defines cookies that contain user ID and password information with the Secure advanced option

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

Example 2: Defines cookies that contain the expiration date advanced option

@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")

Function calls should be on one line; the lines are split in this example for formatting purposes.

Example 3: Determines if a cookie for a user exists before gathering user information

%HTML(welcome) {
  <html>
  <body>
  <h1>Net.Data Club</h1>
  @DTW_GETCOOKIE("NDC_name", name)
  %IF ($(RETURN_CODE) == "8000") %{ The cookie is not found. %}
  <form method="post" action="remember">
  <p>Welcome to the club. Please enter your name.<br>
  <input name="name">
  <input type="submit" value="submit"><br>
  </form>
  %ELSE
  <p>Hi, $(name). Welcome back.
  %ENDIF
  </body>
  </html>
  %}

The HTML(welcome) section checks whether the cookie NDC_name exists. If the cookie exists, the browser displays a personalized greeting. If the cookie does not exist, the browser prompts for the user's name, and posts it to the HTML(remember) section. This section records the user's name into the cookie NDC_name as shown below:

%HTML(remember) {
  <html>
  <body>
  <H1>Net.Data Club>
  @DTW_SETCOOKIE("NDC_name", name, "expires=Wednesday, 01-Dec-2010 00:00:00;path=/")
  <p>Thank you.
  <p><a href="welcome">Come back</a>
  </body>
  </html>
  %}

DTW_SETENV

Purpose

Assigns an environment variable with a specified value and returns the previous value.

Format

@DTW_SETENV(envVarName, envVarValue, prevValue)

@DTW_rSETENV(envVarName, envVarValue)

Parameters

Table 50. DTW_SETENV Parameters

Return Codes

Table 51. DTW_SETENV Return Codes

Usage Notes

If no previous value for the environment variable is found, an empty string is returned.

Examples

Example 1: Returns the value for the previous path

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

• Input: envVarName = "PATH", envVarValue = "myPath"
• Returns: prevValue = "myPreviousPath"

Example 2: Returns the value for the previous path and assigns the value for PATH value

@DTW_rSETENV("PATH", "myPath")

• Input: envVarName = "PATH", envVarValue = "myPath"
• Returns: "myPreviousPath", PATH = "myPath"

DTW_TIME

Purpose

Returns the current system time in the specified format.

Format

@DTW_TIME(stringIn, stringOut)

@DTW_TIME(stringOut)

@DTW_rTIME(stringIn)

@DTW_rTIME()

Parameters

Table 52. DTW_TIME Parameters

Return Codes

Table 53. DTW_TIME Return Codes

Examples

Example 1: Twenty-four hour clock format

@DTW_TIME(results)

• Returns: results = "10:30:53"

Example 2: Civil time format

@DTW_TIME("C", results)

• Returns: results = "10:30AM"

Example 3: Returns the number of minutes since midnight with the function call

@DTW_rTIME("M")

• Returns: "630"

Example 4: Returns the default time and data formats with the function call

%REPORT{
<P>This report was created at @DTW_rTIME(), @DTW_rDATE().
%}

• Returns: This report was created 15:04:39, 01 May 1997.

DTW_URLESCSEQ

Purpose

Replaces selected characters not allowed in a URL with their escape values, known as URL-encoded codes.

Format

@DTW_URLESCSEQ(stringIn, stringOut)

@DTW_rURLESCSEQ(stringIn)

Parameters

Table 54. DTW_URLESCSEQ Parameters

Return Codes

Table 55. DTW_URLESCSEQ Return Codes

Usage Notes

Use this function to pass any of the characters listed in Table 56 to another macro or HTML block.

Table 56. Character Escape Values for URLs

Examples

Example 1: Replaces the space and an ampersand characters in string1 with their escape values and assigns the result to string2

@DTW_URLESCSEQ(string1,string2)

• Input: string1 = "Guys & Dolls"
• Returns: string2 = "Guys%20%26%20Dolls"

Example 2: Replaces space and ampersand characters with their escape codes.

@DTW_rURLESCSEQ("Guys & Dolls")

• Returns: "Guys%20%26%20Dolls"

Example 3: Uses DTW_rURLESCSEQ in a ROW block, and replaces space and 'at' characters with their escape codes.

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

• Input: V1="Patrick O'Brien", V2="obrien@ibm.com"
• Returns:

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

When the application user clicks on the name "Patrick O'Brien," the values specified for the name and e-mail address flow within the query string of the URL that causes Net.Data to execute the input section of the fullrpt.mac macro.