IBM Books

Net.Data 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


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

Purpose

Replaces single quotes in an input string with two single quotes. The replacement is needed so that SQL statements can be processed correctly when a string contains a single quote.

Consider using this function for all SQL INPUT statements. 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')

Format

@DTW_ADDQUOTE(stringIn, stringOut)

@DTW_rADDQUOTE(stringIn)

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

Values

Table 25. DTW_ADDQUOTE Parameters
Data Type Parameter Use Description
string stringIn IN A variable or literal string. DTW_mADDQUOTE can have multiple input strings.
string stringOut OUT A variable that contains the modified form of stringIn.
string stringMult INOUT

  • On input: A variable that contains a string.

  • On output: A variable containing the input string with each single quote (') character replaced by two single-quote characters.

Examples

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

@DTW_ADDQUOTE(string1,string2)

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

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

@DTW_mADDQUOTE(string1,string2)

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)')
%}

DTW_CACHE_PAGE


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






Purpose

Begins caching all HTML output following the function's position in the macro file. When invoked, this function 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 file, 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.

Determining the location of the DTW_CACHE_PAGE function in the macro file:

Format

@DTW_CACHE_PAGE(cacheid, url, age, status)

Values

Table 26. DTW_CACHE_PAGE Parameters
Parameter Use Description
cache_id IN A string variable identifying the cache where the page will be placed.
cached_page_ID IN A string variable containing an identifier used to locate the cached page in a subsequent DTW_CACHE_PAGE cache request. The string can be a URL.
age IN A string variable containing a length of time in seconds. This parameter determines whether a page has expired. If the page is older than age, the page is not sent to the browser.

If age is specified as -1, and the page exists in the cache, Net.Data sends it to the Web browser regardless of its age directly from the cache. Net.Data does not replace the page in the cache.

status OUT A string variable indicating the state of the cached page. Possible values are in lowercase:

  • ok: The output page will be cached when the macro execution terminates.

  • new: The page is not in the cache.

  • renew: The page is in the cache, but has expired.

  • no_cache: The cache identifier specified does not exist. It must be defined in the cache configuration files. Your macro can continue executing without page caching.

  • inactive: The cache you specified has been marked inactive. Your macro can continue executing without page caching.

  • busy: Your macro has issued the DTW_CACHE_PAGE built-in function before in this execution. Your macro can continue executing.

  • error: An error occurred while trying to communicate with the cache.

Examples

Example 1: Places the DTW_CACHE_PAGE function at the beginning of the macro file 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


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

Purpose

Returns the current system date in the specified format.

Format

@DTW_DATE(format, stringOut)

@DTW_DATE(stringOut)

@DTW_rDATE(format)

@DTW_rDATE()

Values

Table 27. DTW_DATE Parameters
Data Type Parameter Use Description
string format IN A variable or literal string specifying the data format. Valid formats include:

D - Day of the year (001-366)

E - European date format (dd/mm/yy)

N - Normal date format (dd mon yyyy)

O - Ordered date format (yy/mm/dd)

S - Standard date format (yyyymmdd)

U - USA date format (mm/dd/yy)

The default is N.

string stringOut OUT A variable that contains the date in the specified format.

Examples

Example 1: Normal date format 

@DTW_DATE(results)

Example 2: European date format 

@DTW_DATE("E", results)

Example 3: US date format 

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

DTW_EXIT


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

Purpose

Specifies to leave the macro immediately. Net.Data ensures that the page the macro created so far will be sent to the browser.

Performance tip: Use DTW_EXIT to stop the processing of a macro file when output has been generated in order to save the time Net.Data has to process the entire file.

Important! 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 file 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.

Format

@DTW_EXIT()

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


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

X X X

Purpose

Specifies the name of a cookie to be read and returns the value of the cookie.

Tip: 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.

Format

@DTW_GETCOOKIE(IN cookie_name, OUT cookie_value)

@DTW_rGETCOOKIE(IN cookie_name)

Values

Table 28. DTW_GETCOOKIE Parameters
Data Type Parameter Use Description
string cookie_name IN A variable or literal string that specifies the name of the cookie.
string cookie_value OUT A variable containing the value of the cookie retrieved by the function, such as user state information.

Usage

If the cookie is not found, usage note 8000 is returned. The cookie might not be found for the following reasons:

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 browser 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


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

Purpose

Returns the value of the specified environment variable. You can also use ENVVAR to reference the values of environment variables. For more information, see ENVVAR Statement.

Format

@DTW_GETENV(envVarName, envVarValue)

@DTW_rGETENV(envVarName)

Values

Table 29. DTW_GETENV Parameters
Data Type Parameter Use Description
string envVarName IN A variable or literal string.
string envVarValue OUT The value of the environment variable specified in envVarName. A null string is returned if the value is not found.

Examples

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

@DTW_GETENV(myEnvVarName, myEnvVarValue)

Example 2: Returns the value for the PATH statement 

@DTW_rGETENV(myPath)

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

The server is @DTW_rGETENV("SERVER_NAME").

DTW_GETINIDATA


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

Purpose

Returns the value of the specified configuration variable. If a value is not found, a null string is returned.

Restriction: For non-OS/400 operating systems, configuration path variables (MACRO_PATH, EXEC_PATH, and INCLUDE_PATH), as well as ENVIRONMENT statements, cannot be retrieved with this call. On the OS/400 operating system, this restriction applies only to ENVIRONMENT statements.

Format

@DTW_GETINIDATA(iniVarName, iniVarValue)

@DTW_rGETINIDATA(iniVarName)

Values

Table 30. DTW_GETINIDATA Parameters
Data Type Parameter Use Description
string iniVarName IN A variable or literal string.
string iniVarValue OUT The value of the configuration variable specified in iniVarName.

Examples

Example 1: Returns the Net.Data path variable value 

@DTW_GETINIDATA(myEnvVarName, myEnvVarValue)

DTW_HTMLENCODE


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

Purpose

Encodes characters using standard HTML decimal escape codes for many, but not all, characters. You can use this function to encode data that you do not want the Web browser to interpret as HTML. For example, by using the appropriate escape character, you can display less-than (<) and greater-than (>) signs, which are usually reserved for HTML tags.

In a second example, the following string in HTML only shows one space between each number: 

1    2     3

Use DTW_HTMLENCODE to ensure that the right number of spaces are shown.

Table 31 shows the characters that are encoded by the DTW_HTMLENCODE function.

Table 31. HTML Decimal Escape Characters
Character Name Code
SPACE Space &#32;
" Double quote &#34;
# Number sign &#35;
% Percent &#37;
& Ampersand &#38;
[ Left bracket &#40;
] Right bracket &#41;
+ Plus &#43;
\ Slash &#47;
: Colon &#58;
; 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;

Format

@DTW_HTMLENCODE(stringIn, stringOut)

@DTW_rHTMLENCODE(stringIn)

Values

Table 32. DTW_HTMLENCODE Parameters
Data Type Parameter Use Description
string stringIn IN A variable or literal string.
string stringOut OUT A variable containing the modified input string in which certain characters have been replaced by the encoded HTML escape characters.

Examples

Example 1: Encodes the space character 

@DTW_HTMLENCODE(string1,string2)

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

@DTW_rHTMLENCODE("X <= 10")

DTW_QHTMLENCODE


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

Purpose

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

Format

@DTW_QHTMLENCODE(stringIn, stringOut)

@DTW_rQHTMLENCODE(stringIn)

Values

Table 33. DTW_QHTMLENCODE Parameters
Data Type Parameter Use Description
string stringIn IN A variable or literal string.
string stringOut OUT A variable that contains the modified form of stringIn in which certain characters are replaced by the encoded HTML escape characters.

Examples

Example 1: Encodes an apostrophe and a space 

@DTW_QHTMLENCODE(string1,string2)

Example 2: Encodes apostrophes, spaces, and an ampersand 

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

DTW_SENDMAIL


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

X X X

Purpose

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

This function works with an optional configuration variable, DTW_SMTP_SERVER, which specifies the SMTP server to use for transmitting e-mail messages. The value of this parameter can either be a host name or an IP address. 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 to learn more about these variables.

National Language Issues: 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.

Troubleshooting: The following list describes conditions under which Net.Data does not send an e-mail message:

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)

Values

Table 34. DTW_SENDMAIL Parameters
Data Type Parameter Use Description
string sender IN A variable or literal string that specifies the author's address. This parameter is required. Valid formats are:

  • Name <user@domain>

  • <user@domain>

  • user@domain
string recipient IN A variable or literal string that specifies the e-mail addresses to which this message will be sent. This value can contain multiple recipients, separated by a comma (,). This parameter is required. Valid recipient formats are:

  • Name <user@domain>

  • <user@domain>

  • user@domain
string message IN A variable or literal string that contains the text of the e-mail message. This parameter is required.
string subject IN A variable or literal string that contains the text of subject line.
string CarbonCopy IN A variable or literal string that contains the e-mail addresses, or names and e-mail addresses of additional recipients. This value can contain multiple additional recipients separated by a comma (,). See the Recipient parameter for valid recipient formats.
string BlindCarbonCopy IN A variable or literal string that contains the e-mail addresses, or names and e-mail addresses of additional recipients, but the recipients do not appear in the e-mail header. This value can contain multiple additional recipients separated by a comma (,). See the Recipient parameter for valid recipient formats.
string ReplyTo IN A variable or literal string that contains the e-mail address to which replies to this message should be sent. Valid ReplyTo formats are:

  • Name <user@domain>

  • <user@domain>

  • user@domain
string Organization IN A variable or literal string that contains the organization name of the sender.

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


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

X X X

Purpose

Defines a cookie name, value, and options, such as expiration date and security requirement.

To retrieve a cookie, use the DTW_GETCOOKIE() function. See DTW_GETCOOKIE to learn how to define a cookie.

When the secure requirement is not specified, the cookie can be sent over unsecured channels. The secure option does not require that the browser encrypt the cookie, nor does it ensure that the page containing the DTW_SETCOOKIE statement is transmitted over SSL.

Tips:

Restriction:

Format

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

@DTW_SETCOOKIE(IN cookie_name, IN cookie_value)

Values

Table 35. DTW_SETCOOKIE Parameters
Data Type Parameter Use Description
string cookie_name IN A variable or literal string that specifies the name of the cookie
string cookie_value IN A variable or literal string the specifies the value of the cookie.
string advanced_options IN A string that contains optional attributes, separated by semicolons, that are used to define the cookie. These attributes are:

expires = date
Specifies a date string that defines the valid lifetime of the cookie. After the date expires, the cookie is not longer stored or retrieved. Syntax: 
weekday, DD-month-YYYY HH:MM:SS GMT

Where:

weekday
Specifies the full name of the weekday.

DD
Specifies the numerical date of the month.

month
Specifies the three-character abbreviation of the month.

YYYY
Specifies the four-character number of the year.

HH:MM:SS
Specifies the timestamp with hours, minutes, and seconds.

domain = domain_name
Specifies the domain attributes of the cookie, for use in domain attribute matching.

path = path
Specifies the subset of URLs in a domain for which the cookie is valid.

secure
Specifies that the cookie is transmitted only over secured channels to HTTPS servers.

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

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


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

Purpose

Assigns an environment variable with a specified value and returns the previous value. A null string is returned if no previous value is found.

Format

@DTW_SETENV(envVarName, envVarValue, prevValue)

@DTW_rSETENV(envVarName, envVarValue)

Values

Table 36. DTW_SETENV Parameters
Data Type Parameter Use Description
string envVarName IN A variable or literal string representing the environment variable.
string envVarValue IN A variable or literal string with the value to which the environment variable is assigned.
string prevValue OUT A variable that contains the previous value of the environment variable.

Examples

Example 1: Returns the value for the previous path 

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

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

@DTW_rSETENV("PATH", "myPath")

DTW_TIME


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

Purpose

Returns the current system time in the specified format.

Format

@DTW_TIME(stringIn, stringOut)

@DTW_TIME(stringOut)

@DTW_rTIME(stringIn)

@DTW_rTIME()

Values

Table 37. DTW_TIME Parameters
Data Type Parameter Use Description
string stringIn IN A variable or literal string specifying the time format. Valid formats are:

C - Civil time (hh:mmAM/PM using a 12-hour clock)

L - Local time (hh:mm:ss)

N - Normal time (hh:mm:ss using a 24-hour clock); default

H - Number of hours since midnight

M - Number of minutes since midnight

S - Number of seconds since midnight

string stringOut OUT A variable that contains the time in the specified format.

Examples

Example 1: Twenty-four hour clock format 

@DTW_TIME(results)

Example 2: Civil time format 

@DTW_TIME("C", results)

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

@DTW_rTIME("M")

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

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

DTW_URLESCSEQ


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

Purpose

Replaces characters that are not allowed in a URL with their escape values, also known as URL-encoded values. You must use this function to pass any of the characters listed in Table 38 to another macro file or HTML block.

Table 38. Characters Not Allowed in URLs
Character Name Code
SPACE Space %20
" Double quote %22
# Number sign %23
% Percent %25
& Ampersand %26
+ Plus %2B
\ Backslash %2F
: Colon %3A
; Semicolon %3B
< Less than %3C
= Equals %3D
> Greater than %3E
? Question mark %3F
@ At sign %40
[ Left bracket %5B
/ Slash %5C
] Right bracket %5D
^ Carat %5E
{ Left brace %7B
| Straight line %7C
} Right brace %7D
~ Tilde %7E

Format

@DTW_URLESCSEQ(stringIn, stringOut)

@DTW_rURLESCSEQ(stringIn)

Values

Table 39. DTW_URLESCSEQ Parameters
Data Type Parameter Use Description
string stringIn IN A variable or literal string.
string stringOut OUT A variable containing the input string with characters that are not allowed in URLs that are replaced with their hexadecimal escape values.

Examples

Example 1: Replaces the spaces and an ampersand in string1 with their URL escape codes and assigns the result to string2 

@DTW_URLESCSEQ(string1,string2)

Example 2: Converts spaces and an ampersand to URL-encoded format 

@DTW_rURLESCSEQ("Guys & Dolls")

Example 3: Uses DTW_rURLESCSEQ in a ROW block, and converts spaces and the at sign to URL-encoded format 

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

When the application user clicks on the name, the name and e-mail address are sent to the input block of the Net.Data macro fullrpt.mac with the encoded values as variables name and email.

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]