Net.Data Reference Guide

General Functions

These are general-purpose functions that you can use:

DTW_ADDQUOTE
DTW_DATE
DTW_GETENV
DTW_GETINIDATA
DTW_HTMLENCODE
DTW_QHTMLENCODE
DTW_SETENV
DTW_TIME
DTW_URLESCSEQ

DTW_ADDQUOTE

Purpose

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

Replaces single quotes in an input string with two single quotes. This is needed for SQL statements to complete successfully if a string contains a single quote.

Syntax

@DTW_ADDQUOTE(stringIn, stringOut)
@DTW_rADDQUOTE(stringIn)
@DTW_mADDQUOTE(stringMult, stringMult2, ..., stringMultn)

Parameters

Table 1. 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.

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:

@DTW_ADDQUOTE(string1,string2)

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

Example 2:

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

Returns: The article''s title is ''Once upon a time''

Example 3:

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

DTW_DATE

Purpose

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

Returns the current system date in the specified format.

Syntax

@DTW_DATE(format, stringOut)
@DTW_DATE(stringOut)
@DTW_rDATE(format)
@DTW_rDate()

Parameters

Table 2. 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.

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:

@DTW_DATE(results)

Returns: results = "25 Apr 1997"

Example 2:

@DTW_DATE("E", results)

Returns: results="25/04/97"

Example 3:

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

Returns: 04/25/97

DTW_GETENV

Purpose

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

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

Syntax

@DTW_GETENV(envVarName, envVarValue)
@DTW_rGETENV(envVarName)

Parameters

Table 3. 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.

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:

@DTW_GETENV(myEnvVarName, myEnvVarValue)

Input: myEnvVarName = "PATH"
Returns: myEnvVarValue = "/usr/path"

Example 2:

@DTW_rGETENV(myPath)

Input: myPath = "PATH"
Returns: "/usr/path"

Example 3:

The server is @DTW_rGETENV("SERVER_NAME").

Returns: "www.software.ibm.com"

DTW_GETINIDATA

Purpose

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

Returns the value of the specified configuration variable. If a value is not found, a null string is returned.
Note: Special configuration path variables, MACRO_PATH, EXEC_PATH, and INCLUDE_PATH, as well as ENVIRONMENT statements cannot be retrieved with this call.

Syntax

@DTW_GETINIDATA(iniVarName, iniVarValue)
@DTW_rGETINIDATA(iniVarName)

Parameters

Table 4. 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.

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:

@DTW_GETINIDATA(myEnvVarName, myEnvVarValue)

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

Example 2:

@DTW_rGETINIDATA("HTTP_COOKIE")

Returns: "cookie.txt"

DTW_HTMLENCODE

Purpose

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

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

"1    2     3"

in HTML only shows one space between each number. Use DTW_HTMLENCODE to ensure the right number of spaces are shown.

The follwoing characters are encoded by the DTW_HTMLENCODE function:

Table 5. HTML decimal escape characters

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

Syntax

@DTW_HTMLENCODE(stringIn, stringOut)
@DTW_rHTMLENCODE(stringIn)

Parameters

Table 6. 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 where certain characters have been replaced by the HTML escape character encoding.

Data Type	Parameter	Use	Description
string	`stringIn`	IN	A variable or literal string.
string	`stringOut`	OUT	A variable containing the modified input string where certain characters have been replaced by the HTML escape character encoding.

Examples

Example 1:

@DTW_HTMLENCODE(string1,string2)

Input: string1 = "Jim's dog"
Returns: string2 = "Jim's dog"

Example 2:

@DTW_rHTMLENCODE("X <= 10")

Returns: "X <= 10"

DTW_QHTMLENCODE

Purpose

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

Performs the same function as @DTW_HTMLENCODE, but also encodes the single quote characet (') to . The HTML decimal escape characters that DTW_QHTMLENCODE uses are shown in Table 5.

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_QHTMLENCODE function changes the SQL statement prevents the error:

INSERT INTO USER1.CUSTABLE (LNAME, FNAME)
VALUES ('O&#39;Brien', 'Patrick')

See Example 3 for details.

Syntax

@DTW_QHTMLENCODE(stringIn, stringOut)
@DTW_rQHTMLENCODE(stringIn)

Parameters

Table 7. 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 where certain characters are replaced by the HTML escape character encoding.

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 where certain characters are replaced by the HTML escape character encoding.

Examples

Example 1:

@DTW_QHTMLENCODE(string1,string2)

Input: string1 = "Jim's dog"
Returns: string2 = "Jim's dog"

Example 2:

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

Returns: "John's & Jane's"

Example 3:

%FUNCTION(DTW_SQL) insertName(){
INSERT INTO USER2A.SURVEY
(NAME) VALUES '@DTW_rQHTMLENCODE(fullname)'
%}

Input: fullname = "Patrick O'Brien"
Returns: 'Patrick O'Brien'

DTW_SETENV

Purpose

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

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

Syntax

@DTW_SETENV(envVarName, envVarValue, prevValue)
@DTW_rSETENV(envVarName, envVarValue)

Parameters

Table 8. DTW_SETENV Parameters

Data Type Parameter Use Description
string envVarName IN A variable or literal string representing the environment variable.
string envVarValue OUT A variable or literal string with the value to which the environment variable is set.
string prevValue OUT A variable that contains the previous value of the environment variable. DTW_rSETENV returns the value as the function return value.

Data Type	Parameter	Use	Description
string	`envVarName`	IN	A variable or literal string representing the environment variable.
string	`envVarValue`	OUT	A variable or literal string with the value to which the environment variable is set.
string	`prevValue`	OUT	A variable that contains the previous value of the environment variable. DTW_rSETENV returns the value as the function return value.

Examples

Example 1:

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

Input: myPath = "myPath"
Returns: prevValue = "myPreviousPath"

Example 2:

@DTW_rSETENV("PATH", "myPath")

Input: myPath = "myPath"
Returns: "myPreviousPath", PATH = "myPath"

DTW_TIME

Purpose

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

Returns the current system time in the specified format.

Syntax

@DTW_TIME(stringIn, stringOut)
@DTW_TIME(stringOut)
@DTW_rTIME(stringIn)
@DTW_rTIME()

Parameters

Table 9. 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)
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.

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

@DTW_TIME(results)

Returns: results = "10:30:53"

Example 2:

@DTW_TIME("C", results)

Returns: results = "10:30AM"

Example 3:

@DTW_rTIME("M")

Returns: "630"

Example 4:

%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

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

Replaces characters not allowed in a URL with their escaped values. You must use this function to pass any of the characters listed in Table 10 to another macro file or HTML block.

Table 10. Characters disallowed in URLs

Character Name Code
SPACE Space &#20
" Double quote &#22
# Number sign &#23
% Percent &#25
& Ampersand &#26
/ 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

Syntax

@DTW_URLESCSEQ(stringIn, stringOut)
@DTW_rURLESCSEQ(stringIn)

Parameters

Table 11. 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 not allowed in URLs replaced with their hexidecimal escape values.

Data Type	Parameter	Use	Description
string	`stringIn`	IN	A variable or literal string.
string	`stringOut`	OUT	A variable containing the input string with characters not allowed in URLs replaced with their hexidecimal escape values.

Examples

Example 1:

@DTW_URLESCSEQ(string1,string2)

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

Example 2:

@DTW_rURLESCSEQ("Guys & Dolls")

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

Example 3: This example uses DTW_rURLESCSEQ in a ROW block. 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.

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

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

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