This section describes the language constructs used in the Net.Data macro.
Each language construct description can contain the following information:
The following constructs are used in the macro; please refer to each constructs description for syntax and examples.
Purpose
Documents the functions of the Net.Data macro. Because the COMMENT block can be used anywhere in the macro, it is not documented in the other syntax diagrams.
The COMMENT block can also be used in the Net.Data initialization file.
Syntax
>>-%{---text---%}----------------------------------------------><
Values
Context
Comments can be placed anywhere between Net.Data language constructs in a Net.Data macro or the Net.Data initialization file
Restrictions
Any text or characters are allowed; however, comment blocks cannot be nested.
Examples
Example 1: A basic comment block
%{
This is a comment block. It can contain any number of lines
and contain any characters. Its contents are ignored by Net.Data.
%}
Example 2: Comments in a FUNCTION block
%function(DTW_REXX) getAddress(IN name, %{ customer name %}
IN phone, %{ customer phone number %}
OUT address %{ customer address %}
)
{
....
%}
Example 3: Comments in an HTML block
%html(report) {
%{ run the query and save results in a table %}
@myQuery(resultTable)
%{ build a form to display a page of data %}
<form method="POST" action="report">
%{ send the table to a REXX function to send the data output %}
@displayRows(START_ROW_NUM, submit, resultTable, RPT_MAX_ROWS)
%{ pass START_ROW_NUM as a hidden variable to the next invocation %}
<input name="START_ROW_NUM" type="hidden" value="$(START_ROW_NUM)">
%{ build the next and previous buttons %}
%if (submit == "both" || submit == "next_only")
<input name="submit" type="submit" value="next">
%endif
%if (submit == "both" || submit == "prev_only")
<input name="submit" type="submit" value="previous">
%endif
</form>
%}
Example 4: Comments in a DEFINE block
%define {
START_ROW_NUM = "1" %{ starting row number for output table %}
RPT_MAX_ROWS = "25" %{ maximum number of rows in the table %}
resultTable = %table %{ table to hold query results %}
%}
Example 5: Comments in the Net.Data initialization file
%{ changes: removed RETURN_CODE parm and DTW_DEFAULT ENVIRONMENT statement %}
...
ENVIRONMENT (DTW_SQL) dtwsql (IN LOCATION, DB2SSID, DB2PLAN, TRANSACTION_SCOPE)
ENVIRONMENT (DTW_ODBC) odbcdll (IN LOCATION, TRANSACTION_SCOPE)
ENVIRONMENT (DTW_PERL) perldll ()
ENVIRONMENT (DTW_REXX) rexxdll ()
ENVIRONMENT (DTW_FILE) filedll ()
ENVIRONMENT (DTW_APPLET) appldll ()
ENVIRONMENT (DTW_SYSTEM) sysdll ()
Purpose
The DEFINE section defines variables names in the declaration part of the macro and can be either a statement or a block.
The variable definition can be on a single line, using double quotes (""), or can span multiple lines, using brackets and a percent sign ({ %}). After the variable is defined, you can reference it anywhere in the macro.
Syntax
>>-%DEFINE----+----------------------------+-------------------->
| (1) |
'-(--+-STATIC---------+---)--'
| (1) |
'-TRANSIENT------'
>-----+-| define entry |--------------------------+------------><
'-{--+------------------------------+---%}--'
| .------------------------. |
| V | |
'----+-define entry------+--+--'
'-include statement-'
define entry
.--------------------------.
V |
|---+-variable name--=--+-"-----+--------------------+--+---"---+-+->
| | +-string-------------+ | |
| | +-variable reference-+ | |
| | '-function call------' | |
| | .--------------------------. | |
| | V | | |
| +-{-----+--------------------+--+---%}--+ |
| | +-string-------------+ | |
| | +-variable reference-+ | |
| | +-function call------+ | |
| | '-new_line-----------' | |
| +-exec statement------------------------+ |
| +-table statement-----------------------+ |
| +-envvar statement----------------------+ |
| +-| conditional variable |--------------+ |
| '-| abbreviated conditional variable |--' |
'-list statement----------------------------------------------'
>---------------------------------------------------------------|
conditional variable
|---variable name---?------------------------------------------->
.--------------------------.
V |
>-----+-"-----+--------------------+--+---"---+----------------->
| +-string-------------+ |
| +-variable reference-+ |
| '-function call------' |
| .--------------------------. |
| V | |
'-{-----+--------------------+--+---%}--'
+-string-------------+
+-variable reference-+
'-function call------'
.--------------------------.
V |
>-------:--+-"-----+--------------------+--+---"---+------------|
| +-string-------------+ |
| +-variable reference-+ |
| '-function call------' |
| .--------------------------. |
| V | |
'-{-----+--------------------+--+---%}--'
+-string-------------+
+-variable reference-+
'-function call------'
abbreviated conditional variable
.--------------------------.
V |
|---?----+-"-----+--------------------+--+---"---+--------------|
| +-string-------------+ |
| +-variable reference-+ |
| '-function call------' |
| .--------------------------. |
| V | |
'-{-----+--------------------+--+---%}--'
+-string-------------+
+-variable reference-+
'-function call------'
Notes:
Values
Context
The DEFINE block or statement must be in an IF block or outside all other blocks in the declaration part of the Net.Data macro.
Restrictions
%DEFINE var = "The value is $(var)."
Examples
Example 1: Simple variable definitions
%DEFINE var1 = "orders" %DEFINE var2 = "$(var1).html"
During run time, the variable reference $(var2) is evaluated as orders.html.
Example 2: Quotes inside a string
%DEFINE hi = "say ""hello""" %DEFINE empty = ""
When displayed, the variable hi has the value say "hello". The variable empty is null.
Example 3: Definition of multiple variables
%DEFINE{ DATABASE = "testdb"
home = "http://www.software.ibm.com"
SHOWSQL = "YES"
PI = "3.14150"
%}
Example 4: Multiple-line definition of a variable
%DEFINE text = {This variable definition
spans two lines
%}
Example 5: This example of a conditional variable demonstrates how the variable var takes the resulting value inside the quotations marks ("") if the resulting value does not contain any NULL values.
%DEFINE var = ? "Hello! $(V)@MyFunc()" %}
Purpose
Defines a variable as an environment variable in the DEFINE block. When the ENVVAR variable is referenced, Net.Data returns the current value of the environment variable by the same name.
Syntax
>>-%ENVVAR-----------------------------------------------------><
Context
The ENVVAR statement can be in the DEFINE block or statement.
Values
Restrictions
The ENVVAR statement can contain no other elements.
Examples
Example 1: In this example, ENVVAR defines a variable, which when referenced, returns the current value for the environment variable SERVER_SOFTWARE, the name of the Web server.
%DEFINE SERVER_SOFTWARE = %ENVVAR
%HTML (REPORT){
The server is $(SERVER_SOFTWARE).
%}
Purpose
Specifies an external program to execute when a variable is referenced or a function is called.
When Net.Data encounters an executable variable in a macro, it looks for the referenced executable program using the following method:
Authorization Tip: Ensure that the user ID under which Net.Data executes has access rights to any files referenced by the EXEC statement or block. See the section on specifying Web server access rights to Net.Data files in the configuration chapter of Net.Data Administration and Programming Guide for your operating system for more information.
The EXEC statement and block are used in two different contexts and have different syntax, depending where they are used. Use the EXEC statement in the DEFINE block, and use the EXEC block in the FUNCTION block.
Syntax
The EXEC statement syntax when used in the DEFINE block:
.--------------------------.
V |
>>-%EXEC------"-----+--------------------+--+---"--------------><
+-string-------------+
+-variable reference-+
'-function call------'
The EXEC block syntax when used in the FUNCTION block:
.-------------------------.
V |
>>-%EXEC------{----+-string-------------+--+---%}--------------><
+-variable reference-+
'-function call------'
Values
Context
The EXEC block or statement can be found in these contexts:
Restrictions
The EXEC block or statement can contain these elements:
The following Net.Data-provided language environments support the EXEC statement:
Examples
Example 1: Executable file referenced by a variable
%DEFINE mycall = %EXEC "MYEXEC.EXE $(empno)"
%HTML (report){
<P>Here is the report you requested:
<HR>$(mycall)
%}
This example executes MYEXEC.EXE on every reference to the variable, mycall.
Example 2: Executable file referenced by a function
%FUNCTION(DTW_REXX) my_rexx_pgm(INOUT a, b, IN c, INOUT d){
%EXEC{ mypgm.cmd this is a test %}
%}
This example executes mypgm.cmd when the function my_rexx_pgm is called.
Purpose
Defines a subroutine that Net.Data invokes from the macro. The executable statements in a FUNCTION block can be inline statements directly interpreted by a language environment, or they can be a call to an external program.
If you use the EXEC block within the FUNCTION block, it must be the only executable statement in the FUNCTION block. Before passing the executable statement to the language environment, Net.Data appends the file name of the program in the EXEC block to a path name determined by the EXEC_PATH configuration statement in the initialization file. The resulting string is passed to the language environment to be executed.
The method that the language environment uses to process the EXEC block depends on the particular language environment; the REXX, System, and Perl Net.Data-provided language environments support the EXEC block.
When characters that match Net.Data language constructs syntax are used in the language statements section of a function block as part of syntactically valid embedded program code (such as REXX or Perl), they can be misinterpreted as Net.Data language constructs, causing errors or unpredictable results in a macro.
For example, a Perl function might use the COMMENT block delimiter characters, %{. When the macro is run, the %{ characters are interpreted as the beginning of a COMMENT block. Net.Data then looks for the end of the COMMENT block, which it thinks it finds when it reads the end of the function block. Net.Data then proceeds to look for the end of the function block, and when it can't be found, issues an error.
Use one of the following methods to use Net.Data special characters as part of your embedded program code, without having them interpreted by Net.Data as special characters:
For example, the following Perl function contains characters representing a COMMENT block delimiter, %{, as part of its Perl language statements:
%function(DTW_PERL) func() {
...
for $num_words (sort bynumber keys %{ $Rtitles{$num} }) {
&make_links($Rtitles{$num}{$num_words});
}
...
%}
To ensure that Net.Data interprets the %{ characters as Perl source code rather than as a Net.Data COMMENT block delimiter, rewrite the function in either of the following ways:
%function(DTW_PERL) func() {
%EXEC{ func.prl %}
%}
%define percent_openbrace = "%{"
%function(DTW_PERL) func() {
...
for $num_words (sort bynumber keys $(percent_openbrace) $Rtitles{$num} }) {
&make_links($Rtitles{$num}{$num_words});
}
...
%}
Syntax
>>-%FUNCTION--(--lang_env--)--function_name--| parm passing spec |-->
.-;---------------------------------------------.
>----+-| returns spec |--{--| function body |----%}--+---------><
parm passing spec
|---(--+---------------------------------------------+---)------|
| .-,-------------------------------------. |
| | (1) | |
| V .-IN-------. | |
'----+----------+---+-----------+---name---+--'
+-OUT------+ '-datatype--'
'-INOUT----'
returns spec
|---+----------------------+------------------------------------|
'-RETURNS--(--name--)--'
function body
|---+-------------------------------+--------------------------->
| .--------------------------. |
| V | |
+----inline statement block---+-+
'-exec block--------------------'
>-----+-----------------------------------------------+---------|
| .---------------------. |
| V (2) | |
+----report block--------+---+----------------+-+
| '-message block--' |
| .--------------------------. |
| V | |
'-message block-----+--------------------+--+---'
| (2) |
'-report block-------'
Notes:
Values
Context
The FUNCTION block can be found in these contexts:
Restrictions
DB2 has the following restrictions:
Examples
The following examples are general and do not cover all language environments. See Net.Data Language Environment Reference for more information about using FUNCTION blocks with a specific language environment.
Example 1: A REXX substring function
%DEFINE lstring = "longstring"
%FUNCTION(DTW_REXX) substring(IN x, y, z) RETURNS(s) {
s = substr("$(x)", $(y), $(z));
%}
%DEFINE a = {@substring(lstring, "1", "4")%} %{ assigns "long" to a %}
When a is evaluated, the @substring function call is found and the substring FUNCTION block is executed. Variables are substituted in the executable statements in the FUNCTION block, then the text string s = substr("longstring", 1, 4) is passed to the REXX interpreter to execute. Because the RETURNS clause is specified, the value of the @substring function call in the evaluation of a is replaced with "long", the value of s.
Example 2: Invoking an external REXX program
%FUNCTION(DTW_REXX) my_rexx_pgm(INOUT a, b, IN c, OUT d) {
%EXEC{ mypgm.cmd this is a test %}
%}
%HTML(INPUT) {
<P> Original variable values: $(w) $(x) $(z)
<P> @my_rexx_pgm(w, x, y, z)
<P> Modified variable values: $(w) $(x) $(z)
%}
Variables w and x correspond to the INOUT parameters a and b in the function. Their values and the value of y, which corresponds to the IN parameter c, should already be defined from HTML form input or from a DEFINE statement. Variables a and b are assigned new values when parameters a and b return values. The variable z is defined when the OUT parameter d returns a value.
/* Sample REXX Program for Example 2 */ /* Test arguments */ num_args = arg(); say 'There are' num_args 'arguments'; do i = 1 to num_args; say 'arg' i 'is "'arg(i)'"' end; /* Set variables passed from Net.Data */ d = a || b || c; /* concatenate a, b, and c forming d */ a = ''; /* reset a to null string */ b = ''; /* reset b to null string */ return;
There are 1 arguments arg 1 is "this is a test"
The EXEC statement tells the REXX language environment to tell the REXX interpreter to execute the external REXX program mypgm.cmd. Because the REXX language environment can directly share Net.Data variables with the REXX program, it assigns the REXX variables a, b, and c the values of the Net.Data variables w, x and y before executing mypgm.cmd. mypgm.cmd can directly use the variables a, b, and c in REXX statements. When the program ends, the REXX variables a, b, and d are retrieved from the REXX program, and their values are assigned to the Net.Data variables w, x, and z. Because the RETURNS clause is not used in the definition of the my_rexx_pgm FUNCTION block, the value of the @my_rexx_pgm function call is the null string, "", (if the return code is 0) or the value of the REXX program return code (if the return code is nonzero).
Example 3: An SQL query and report
%FUNCTION(DTW_SQL) query_1(IN x, IN y) {
SELECT customer.num, order.num, part.num, status
FROM customer, order, shippingpart
WHERE customer.num = '$(x)'
AND customer.ordernumber = order.num
AND order.num = '$(y)'
AND order.partnumber = part.num
%REPORT{
<P>Here is the status of your order:
<P>$(NLIST)
<UL>
%ROW{
<LI>$(V1) $(V2) $(V3) $(V4)
%}
</UL>
%}
%}
%DEFINE customer_name="IBM"
%DEFINE customer_order="12345"
%HTML(REPORT) {
@query_1(customer_name, customer_order)
%}
The @query_1 function call substitutes IBM for $(x) and 12345 for $(y) in the SELECT statement. Because the definition of the SQL function query_1 does not identify an output table variable, the default table is used (see the TABLE variables block for details). The NLIST and Vi variables referenced in the REPORT block are defined by the default table definition. The report produced by the REPORT block is placed in the output HTML where the query_1 function is invoked.
Example 4: A system call to execute a Perl script
%FUNCTION(DTW_SYSTEM) today() RETURNS(result) {
%exec{ perl "today.prl" %}
%}
%HTML(INPUT) {
@today()
%}
$date = `date`;
chop $date;
open(DTW, "> $ENV{DTWPIPE}") || die "Could not open: $!";
print DTW "result = \"$date\"\n";
When the @today function call is encountered, Net.Data performs variable substitution on the executable statements. In this example, there are no Net.Data variables in the executable statements, so no variable substitution is performed. The executable statements and parameters are passed to the System language environment, which creates a named pipe and sets the environment variable DTWPIPE to the name of the pipe.
Then the external program is called with the C system() function call. The external program opens the pipe as write-only and writes the values of output parameters to the pipe as if it were a standard stream file. The external program generates HTML output by writing to STDOUT. In this example, the output of the system date program is assigned to the variable result, which is the variable identified in the RETURNS clause of the FUNCTION block. This value of the result variable replaces the @today() function call in the HTML block.
Example 5: Perl language environment
%FUNCTION(DTW_PERL) today() RETURNS(result) {
$date = `date`;
chop $date;
open(DTW, "> $ENV{DTWPIPE}") || die "Could not open: $!";
print DTW "result = \"$date\"\n";
%}
%HTML(INPUT) {
@today()
%}
Compare this example with Example 4 to see how the EXEC block is used. In Example 4, the System language environment does not understand how to interpret Perl programs, but the language environment does know how to call external programs. The EXEC block tells it to call a program called perl as an external program. The actual Perl language statements are interpreted by the external Perl program. Example 5 has no EXEC block, because the Perl language environment is able to directly interpret Perl language statements.
Purpose
Invokes a FUNCTION block, MACRO_FUNCTION block, or built-in function with specified arguments. If the function is not a built-in function, you must define it in the Net.Data macro before you specify a function call.
Syntax
>>-@function_name---(------------------------------------------->
>-----+-----------------------------------------------+--)-----><
| .-,----------------------------------------. |
| V | |
'----+-variable_name-----------------------+--+-'
+-variable reference------------------+
+-function call-----------------------+
| .-------------------------. |
| V | |
'-"----+-string-------------+--+---"--'
+-variable reference-+
'-function call------'
Values
Context
Function calls can be found in these contexts:
Restrictions
Examples
Example 1: A call to the SQL function formQuery
%FUNCTION(DTW_SQL) formQuery(){
SELECT $(queryVal) from $(tableName)
%}
%HTML (input){
<P>Which columns of $(tableName) do you want to see?
<FORM METHOD="POST" ACTION="report">
<INPUT NAME="queryVal" TYPE="CHECKBOX" VALUE="NAME">Name
<INPUT NAME="queryVal" TYPE="CHECKBOX" VALUE="MAIL">E-mail
<INPUT NAME="queryVal" TYPE="CHECKBOX" VALUE="FAX">FAX
<INPUT TYPE="SUBMIT" VALUE="Submit request">
%}
%HTML (report){
<P>Here are the columns you selected:
<HR>@formQuery()
%}
Example 2: A call to a REXX function with input and output parameters
%FUNCTION(DTW_REXX) my_rexx_pgm(INOUT a, b, IN c, OUT d) {
%EXEC{ mypgm.cmd this is a test %}
%}
%HTML(INPUT) {
<P> Original variable values: $(w) $(x) $(z)
<P> @my_rexx_pgm(w, x, y, z)
<P> Modified variable values: $(w) $(x) $(z)
%}
Example 3: A call to a REXX function, with input parameters, that uses variable references and function calls
%FUNCTION(DTW_REXX) my_rexx_pgm(IN a, b, c, d, OUT e) {
...
%}
%HTML(INPUT) {
<p> @my_rexx_pgm($(myA), @getB(), @retrieveC(), $(myD), myE)
%}
Example 4: A macro that illustrates the use of the INOUT parameter.
%DEFINE a = "initial value of a"
%FUNCTION(DTW_REXX) func1(INOUT x) {
Say 'value at start of function:<br>
Say 'x =' x
Say '<p>'
x = "new value of a"
%REPORT {
<p>value at start of report block:<br>
x = $(x)<br>
@dtw_assign(x, "newest value of a")
value at end of report block:<br>
x = $(x)<br>
%}
%}
%HTML(report) {
initial values:<br>
a = $(a)<br>
@func1(a)
value after function call:<br>
a = $(a)<br>
%}
Resulting output:
initial values: a = initial value of a value at start of function: x = initial value of a value at start of report block: x = new value of a value at end of report block: x = newest value of a value after function call: a = newest value of a
Purpose
Defines how a Web page is to be presented. The name of the HTML block to be executed is specified on the URL when Net.Data is invoked. The HTML block can contain most Net.Data macro language statements and any valid presentation statements, such as HTML and Javascript.
Syntax
>>-%HTML----(--name--)------------------------------------------>
.-----------------------------.
V |
>-----{-----+-----------------------+--+---%}------------------><
+-exec_sql statement----+
+-variable reference----+
+-if block--------------+
+-function call---------+
+-HTML statement--------+
+-include statement-----+
+-include_url statement-+
'-while block-----------'
Values
Context
The HTML block can be found in these contexts:
Restrictions
The HTML block can contain these elements:
Examples
Example 1: HTML block with include files for headings and footings
%HTML(example1){
%INCLUDE"header.html"
<P>You can put <EM>any</EM> HTML in an HTML block.
An SQL function call is made like this:
@xmp1()
%INCLUDE"footer.html"
%}
Example 2: HTML block with a name that contains a period
%HTML(my.report){
%INCLUDE"header.html"
<P>You can put <EM>any</EM> HTML in an HTML block.
An SQL function call is made like this:
@xmp1()
%INCLUDE"footer.html"
%}
Performs conditional string processing. The IF block provides the ability to test one or more conditions, and then to perform a block of statements based on the outcome of the condition test. You can use the IF block in the declaration part of a Net.Data macro, the HTML block, the MACRO_FUNCTION block, the REPORT block, the WHILE block, and the ROW block, as well as nest it inside another IF block.
String values in the condition list are treated as numeric for comparisons if they are strings that represent integers and have no leading or trailing white space. They can have a single leading plus (+) or minus (-) sign.
Restriction: Net.Data does not support numerical comparison of non-integer numbers; for example, floating point numbers.
Nested IF blocks: The rules for IF block syntax are determined by the block's position in the macro. If an IF block is nested within an IF block that is outside of any other block in the declaration part, it can use any element that the outside block can use. If an IF block is nested within another block that is in an IF block, it takes on the syntax rules for the block it is inside.
In the following example, the nested IF block must follow the rules used when it is inside an HTML block.
%IF block
...
%HTML block
...
%IF block
You can nest up to 1024 IF blocks.
Syntax
>>-%IF--| condition list |-------------------------------------->
>-----| statement_block |--| else_if spec |--%ENDIF------------><
condition list
|---(--+-(--condition list--)----------------+---)--------------|
+-condition list--&&--condition list--+
+-condition list--||--condition list--+
+-!--condition list-------------------+
+-| condition |-----------------------+
'-| term |----------------------------'
statement_block
.---------------------------------.
V |
|------+---------------------------+--+-------------------------|
| (1) |
+-define block--------------+
| (1) |
+-define statement----------+
| (2) |
+-exec_sql statement--------+
| (1) |
+-function block------------+
+-function call-------------+
| (1) |
+-HTML block----------------+
| (2) |
+-HTML statement------------+
+-if block------------------+
+-include statement---------+
+-include_url statement-----+
| (1) |
+-macro_function block------+
| (1) |
+-message block-------------+
| (2) |
+-string--------------------+
| (2) |
+-variable reference--------+
| (2) |
'-while block---------------'
condition
|---term--+-<--+---term-----------------------------------------|
+->--+
+-<=-+
+->=-+
+-!=-+
'-==-'
term
|---+-variable_name-----------------------+---------------------|
+-variable reference------------------+
+-function call-----------------------+
| .-------------------------. |
| V | |
'-"----+-string-------------+--+---"--'
+-variable reference-+
'-function call------'
else_if spec
|---+---------------------------------------------------------------+->
| .----------------------------------------------------. |
| V | |
'--+----%ELIF--(--condition_list--)--| statement_block |---+-+--'
'-%ELSE--| statement_block |------------------------------'
>---------------------------------------------------------------|
Notes:
Values
If either condition is not true, a normal string comparison is performed.
Context
The IF block can be found in these contexts:
Restrictions
The IF block can contain these elements when located outside of any other block in the declaration part of the Net.Data macro:
The IF block can contain these elements when located in the HTML block, MACRO_FUNCTION block, REPORT block, ROW block, or WHILE block of the Net.Data macro:
You can nest up to 1024 IF blocks.
Examples
Example 1: An IF block in the declaration part of a Net.Data macro
%DEFINE a = "1"
%DEFINE b = "2"
...
%IF ($(DTW_HTML_TABLE) == "YES")
%define OUT_FORMAT = "HTML"
%ELSE
%define OUT_FORMAT = "CHARACTER"
%ENDIF
%HTML(REPORT) {
...
%}
Example 2: An IF block inside an HTML block
%HTML(REPORT) {
@myFunctionCall()
%IF ($RETURN_CODE) == $(failure_rc))
<P> The function call failed with failure code $(RETURN_CODE).
%ELIF ($(RETURN_CODE) == $(warning_rc))
<P> The function call succeeded with warning code $(RETURN_CODE).
%ELIF ($(RETURN_CODE) == $(success_rc))
<P>The function call was successful.
%ELSE
P>The function call returned with unknown return code $(RETURN_CODE).
%ENDIF
%}
Example 3: A numeric comparison
%IF (ROW_NUM < "100")
<p>The table is not full yet...
%ELIF (ROW_NUM == "100")
<p>The table is now full...
%ELSE
<p>The table has overflowed...
%ENDIF
A numeric comparison is done because the implicit table variable ROW_NUM always returns an integer value, and the value that is being compared is also an integer.
Example 4: Nested IF blocks
%IF (MONTH == "January")
%IF (DATE = "1")
HAPPY NEW YEAR!
%ELSE
Ho hum, just another day.
%ENDIF
%ENDIF
Purpose
Reads and incorporates a file into the Net.Data macro in which the statement is specified.
Net.Data searches the directories specified in the INCLUDE_PATH statement in the initialization file to find the include file.
You can use include files the same way you can in most high-level languages. They can insert common headings and footings, define common sets of variables, or incorporate a common subroutine library of FUNCTION block definitions into a Net.Data macro.
Net.Data executes an INCLUDE statement only once when processing the macro and inserts the content of the included file at the location of the INCLUDE statement in the macro. Any variable references in the name of the included file are resolved at the time the INCLUDE statement is first executed, not when the content of the included file is to be executed.
When an INCLUDE statement is in a ROW or WHILE block, Net.Data does not repeatedly execute the INCLUDE statement. Net.Data executes the INCLUDE statement the first time it executes the ROW or WHILE block, incorporates the content of the included file into the block, and then repeatedly executes the ROW or WHILE block with the content of the included file.
Authorization Tip: Ensure that the user ID under which Net.Data executes has access rights to any files referenced by the INCLUDE statement. See the section on specifying Web server access rights to Net.Data files in the configuration chapter of Net.Data Administration and Programming Guide for more information.
Tip: If you want to include an HTML file from a local Web server, use the INCLUDE_URL construct as shown in Example 3 for INCLUDE_URL. By using the demonstrated syntax, you do not have to update the INCLUDE_PATH in the Net.Data initialization file to specify directories that are already known to the Web server.
Syntax
.-------------------------.
V |
>>-%INCLUDE----"----+-string-------------+--+---"--------------><
'-variable reference-'
Values
Context
The INCLUDE statement can be found in these contexts:
Restrictions
The INCLUDE statement can contain these elements:
Function calls in the string are not allowed.
You can nest up to ten INCLUDE statements.
Examples
Example 1: An INCLUDE statement in an HTML block
%HTML(start){
%INCLUDE "header.hti"
...
%}
Example 2: An INCLUDE statement in a REPORT block
%REPORT {
%INCLUDE "report_header.txt"
%ROW {
%INCLUDE "row_include.txt"
%}
%INCLUDE "report_footer.txt"
%}
Example 3: Variable references in an INCLUDE statement
%define library = "/qsys.lib/mylib.lib/" %define filename = "macros.file/incfile.mbr" %include "$(library)$(filename)"
Purpose
Reads and incorporates another file into the Net.Data generated output in which the statement is specified. The specified file can exist on a local or remote server.
Using the INCLUDE_URL statement, you can invoke one macro from another macro without requiring the application user to select a Submit button.
Net.Data executes an INCLUDE_URL statement only once when processing the macro and inserts the content of the included file at the location of the INCLUDE_URL statement in the macro. Any variable references in the name of the included file are resolved at the time the INCLUDE_URL statement is first executed, not when the content of the included file is to be executed.
When an INCLUDE_URL statement is in a ROW or WHILE block, Net.Data does not repeatedly execute the INCLUDE_URL statement. Net.Data executes the INCLUDE_URL statement the first time it executes the ROW or WHILE block, incorporates the content of the included file into the block, and then repeatedly executes the ROW or WHILE block with the content of the included file.
Syntax
.-------------------------.
V |
>>-%INCLUDE_URL---"------+-string-------------+--+--"----------><
'-variable reference-'
Values
Context
INCLUDE_URL statements can be found in these contexts:
Restrictions
INCLUDE_URL statements can contain these elements:
On OS/390, the INCLUDE_URL file can be up to 256 KB. Other operating systems do not have a limit.
When using the INCLUDE_URL statement, do not start an infinite sequence of macro requests by invoking the current macro file recursively.
INCLUDE_URL is not supported in the OS/400 environment.
Examples
Example 1: Including an HTML file from another server
%include_url "http://www.ibm.com/path/myfile.html"
Example 2: Including an HTML file from a remote server by calling the server name
%include_url "myserver/path/myfile.html"
Where myserver is the server name.
Example 3: Including an HTML file from the local Web server
%include_url "/path/myfile.html"
Tip: By using this method, you do not have to update the INCLUDE_URL path in the Net.Data configuration file to specify directories that are already known to the Web server. If the string does not begin with a slash, Net.Data assumes the string is a server name and attempts to retrieve the file from the server with the corresponding name.
Example 4: Including other Net.Data macros from a remote server
%REPORT{
<P>Current hot pick as of @DTW_rTIME():
%include_url "http://www.ibm.com/cgi-bin/db2www/hotpic.mac/report?custno=$(custno)"
In this example, the macro hotpic.mac is called and custno is sent as a variable. If the string begins with a slash, Net.Data retrieves the INCLUDE file from the local Web server.
Purpose
Builds a delimited list of values. You can use the LIST statement when you construct SQL queries with multiple items like those found in some WHERE or HAVING clauses.
Syntax
.--------------------------.
V |
>>-%LIST--"-----+--------------------+--+---"----variable name--><
+-string-------------+
+-variable reference-+
'-function call------'
Values
Context
The LIST statement can be found in these contexts:
Restrictions
The LIST statement can contain these elements:
Examples
Example 1: A list of variables
%DEFINE{
DATABASE="custcity"
%LIST " OR " conditions
conditions="cond1='Sao Paolo'"
conditions="cond2='Seattle'"
conditions="cond3='Shanghai'"
whereClause=conditions ? "WHERE $(conditions)" : ""
%}
Purpose
Defines a subroutine that can be invoked from the Net.Data macro. The executable statements in a MACRO_FUNCTION block must be Net.Data macro language source statements.
Syntax
>>-%MACRO_FUNCTION--function_name--| parm passing spec |-------->
(4)
>-----| returns spec |-------{--| function body |----%}--------->
.--------------------------.
V |
>--------+--------------------+--+--%}-------------------------><
| (3) |
'-report block-------'
parm passing spec
|---(--+-----------------------------+---)----------------------|
| .-,---------------------. |
| | (1) | |
| V .-IN-------. | |
'----+----------+---name---+--'
+-OUT------+
'-INOUT----'
returns spec
(4)
|----------+----------------------+-----------------------------|
'-RETURNS--(--name--)--'
function body
.----------------------------------.
V |
|------+----------------------------+--+------------------------|
+-exec_sql statement---------+
+-variable reference---------+
+-if block-------------------+
+-function call--------------+
+-HTML statement-------------+
+-include statement----------+
| (2) |
+-include_url statement------+
'-while block----------------'
Notes:
Values
Context
The MACRO_FUNCTION block can be found in these contexts:
Restrictions
The MACRO_FUNCTION block can contain these elements:
Not supported for OS/400
Examples
Example 1: A macro function that specifies message handling
%MACRO_FUNCTION setMessage(IN rc, OUT message) {
%IF (rc == "0")
@dtw_assign(message, "Function call was successful.")
%ELIF (rc == "-1")
@dtw_assign(message, "Function failed, out of memory.")
%ELIF (rc == "-2")
@dtw_assign(message, "Function failed, invalid parameter.")
%ENDIF
%}
Example 2: A macro function that specifies header information
%MACRO_FUNCTION setup(IN browserType) {
%{ call this function at the top of each HTML block in the macro %}
%INCLUDE "header_info.html"
@dtw_rdate()
%IF (browserType == "IBM")
@setupIBM()
%ELIF (browserType == "MS")
@setupMS()
%ELIF (browserType == "NS")
@setupNS()
%ELSE
@setupDefault()
%ENDIF
%}
Purpose
Specifies messages to display and actions to take based on the return code from a function.
Define the set of return codes, along with their corresponding messages and actions in the MESSAGE block. When a function call completes, Net.Data compares its return code with return codes defined in the MESSAGE block. If the function's return code matches one in the MESSAGE block, Net.Data displays the message and evaluates the action to determine whether to continue processing or exit the Net.Data macro.
A MESSAGE block can be global in scope, or local to a single FUNCTION block. If the MESSAGE block is defined at the outermost macro layer, it is considered global in scope. When multiple global MESSAGE blocks are defined, only the last block processed is considered active. If the MESSAGE block is defined inside a FUNCTION block, the block is local in scope to the FUNCTION block where it is defined. See the MESSAGE block section in the Net.Data Administration and Programming Guide for return code processing rules.
Syntax
>>-%MESSAGE--{-------------------------------------------------->
.--------------------------------------------------------------------------------------.
V |
>--------+--------------------------------------------------------------------------------+--+>
'--+-| return code spec |--+--:---| message text spec |----+------------------+--'
'-| SQLSTATE |----------' '-| action spec |--'
>----%--}------------------------------------------------------><
return code spec
|---+-DEFAULT---------------+-----------------------------------|
+-+DEFAULT--------------+
+- -DEFAULT-------------+
+-+----+---msg_code-----+
| +- --+ |
| '-+--' |
+-include statement-----+
'-include_url statement-'
SQLSTATE
|---SQLSTATE--:------state_id-----------------------------------|
message text spec
.--------------------------.
V |
|----+-"-----+--------------------+--+---"---+------------------|
| +-string-------------+ |
| +-variable reference-+ |
| +-function call------+ |
| '-(new_line)---------' |
| .--------------------------. |
| V | |
+-{-----+--------------------+--+---%}--+
| +-string-------------+ |
| +-variable reference-+ |
| '-function call------' |
+-include statement---------------------+
'-include_url statement-----------------'
action spec
.-EXIT-----.
|---+-:--+----------+--------+----------------------------------|
| '-CONTINUE-' |
+-include statement------+
'-include_url statement--'
Values
Context
The MESSAGE block can be found in these contexts:
Restrictions
The MESSAGE block can contain these elements:
For OS/390, OS/2, Windows NT, and UNIX operating systems: SQL functions cannot be called from inside SQL functions.
Examples
Example 1: A local MESSAGE block
%{ local message block inside a FUNCTION block %}
%FUNCTION(DTW_REXX) my_function() {
%EXEC { my_command.cmd %}
%MESSAGE{
-601: {<H3>The table has already been created, please go back and enter your name.</H3>
<P><a href="input">Return</a>
%}
default: "<H3>Can't continue because of error $(RETURN_CODE)</H3>"%} : exit
%}
Example 2: A global MESSAGE block
%{ global message block %}
%MESSAGE {
-100 : "Return code -100 message" : exit
100 : "Return code 100 message" : continue
+default : {
This is a long message that spans more
than one line. You can use HTML tags, including
links and forms, in this message. %} : continue
%}
%{ local message block inside a FUNCTION block %}
%FUNCTION(DTW_REXX) my_function() {
%EXEC { my_command.cmd %}
%MESSAGE {
-100 : "Return code -100 message" : exit
100 : "Return code 100 message" : continue
-default : {
This is a long message that spans more
than one line. You can use HTML tags, including
links and forms, in this message. %} : exit
%}
Example 3: A MESSAGE block containing INCLUDE statements.
%message {
%include "rc1000.msg"
%include "rc2000.msg"
%include "defaults.msg"
%}
Purpose
Formats output from a function call. You can enter a table name parameter to specify that the report is to use the data in the named table. Otherwise, the report is generated with the first output table found in the function parameter list, or with the default table data if no table name is in the list.
Syntax
>>-%REPORT----+-------------+--{-------------------------------->
'-(--name--)--'
.-----------------------------.
V |
>--------+-----------------------+--+---+-----------+----------->
+-string----------------+ '-row block-'
+-if block--------------+
+-variable reference----+
+-function call---------+
+-HTML statements-------+
+-include statement-----+
+-include_url statement-+
'-while block-----------'
.-----------------------------.
V |
>--------+-----------------------+--+--%}----------------------><
+-string----------------+
+-if block--------------+
+-variable reference----+
+-function call---------+
+-HTML statements-------+
+-include statement-----+
+-include_url statement-+
'-while block-----------'
Values
Context
The REPORT block can be found in these contexts:
Restrictions
The REPORT block can contain these elements:
For OS/390, OS/2, Windows NT, and UNIX operating systems: SQL functions cannot be called from inside SQL functions.
For OS/390: REPORT blocks are not allowed in MACRO_FUNCTION blocks.
Examples
Example 1: A two-column HTML table showing a list of names and locations
%FUNCTION(DTW_SQL) mytable() {
%REPORT{
<H2>Query Results</H2>
<P>Select a name for details.
<TABLE BORDER=1>
<TR><TD>Name</TD><TD>Location</TD>
%ROW{
<TR>
<TD>
<a href="/cgi-bin/db2www/name.mac/details?name=$(V1) &location=$(V2)">$(V1)</a></TD>
<TD>$(V2)</TD>
%}
</TABLE>
%}
Selecting a name in the table calls the details HTML block of the name.mac Net.Data macro and sends it the two values as part of the URL. In this example, the values can be used in name.mac to look up additional details about the name.
Purpose
Processes each table row returned from a function call. Net.Data processes the statements within the ROW block once for each row.
Syntax
.-----------------------------.
V |
>>-%ROW--{-------+-----------------------+--+--%}--------------><
+-string----------------+
+-if block--------------+
+-variable reference----+
+-function call---------+
+-HTML statements-------+
+-include statement-----+
+-include_url statement-+
'-while block-----------'
Values
Context
The ROW block can be found in these contexts:
Restrictions
The ROW block can contain these elements:
For OS/390, OS/2, Windows NT, and UNIX operating systems: SQL functions cannot be called from inside SQL functions.
Examples
Example 1: A two-column HTML table showing a list of names and locations
%REPORT{
<H2>Query Results</H2>
<P>Select a name for details.
<TABLE BORDER=1>
<TR><TD>Name</TD><TD>Location</TD>
%ROW{
<TR>
<TD>
<a href="/cgi-bin/db2www/name.mac/details?name=$(V1)&location=$(V2)">$(V1)</a></TD>
<TD>$(V2)</TD>
%}
</TABLE>
%}
Selecting a name in the table calls the details HTML block of the name.mac Net.Data macro and sends it the two values as part of the URL. In this example, the values can be used in name.mac to look up additional details about the name.
Purpose
Defines a variable which is a collection of related data. The variable contains a set of rows and columns including a row of column headers describing the fields in each row. A table statement can only be in a DEFINE statement or block.
When a TABLE variable is referenced, Net.Data displays the content of the table as either a plain character table, or as an HTML table if the DTW_HTML_TABLE variable is set to YES.
Syntax
>>-%TABLE--| upper limit |-------------------------------------><
upper limit
|---+--------------------+--------------------------------------|
'-(--+-number-+---)--'
'-ALL----'
Values
Context
The TABLE statement can be found in these contexts:
Restrictions
The TABLE statement can contain these elements:
Examples
Example 1: A Net.Data table with an upper limit of 30 rows
%DEFINE myTable1=%TABLE(30)
Example 2: A Net.Data table that uses the default of all rows
%DEFINE myTable2=%TABLE
Example 3: A Net.Data table that specifies all rows
%DEFINE myTable3=%TABLE(ALL)
Purpose
Provides a looping construct based on conditional string processing. You can use the WHILE block in the HTML block, the REPORT block, the ROW block, the IF block, and the MACRO_FUNCTION block. String values in the condition list are treated as numeric for comparisons if they are strings that represent integers and have no leading or trailing white space. They can have a single leading plus (+) or minus (-) sign.
Syntax
>>-%WHILE--| condition list |---{------------------------------->
.-----------------------------.
V |
>--------+-----------------------+--+--%}----------------------><
+-exec_sql statement----+
+-function call---------+
+-HTML statement--------+
+-if block--------------+
+-include statement-----+
+-include_url statement-+
+-while block-----------+
+-variable reference----+
'-string----------------'
condition list
|---(--+-(--condition list--)----------------+---)--------------|
+-condition list--&&--condition list--+
+-condition list--||--condition list--+
+-!--condition list-------------------+
+-| condition |-----------------------+
'-| term |----------------------------'
condition
|---term--+-<--+---term-----------------------------------------|
+->--+
+-<=-+
+->=-+
+-!=-+
'-==-'
term
|---+-variable_name-----------------------+---------------------|
+-variable reference------------------+
+-function call-----------------------+
| .-------------------------. |
| V | |
'-"----+-string-------------+--+---"--'
+-variable reference-+
'-function call------'
Values
If either condition is not true, a normal string comparison is performed.
Context
The WHILE block can be found in these contexts:
Restrictions
The WHILE block can contain these elements:
Examples
Example 1: A WHILE block that generates rows in a table
%DEFINE loopCounter = "1"
%HTML(build_table) {
%WHILE (loopCounter <= "100") {
%{ generate table tag and column headings %}
%IF (loopCounter == "1")
<TABLE BORDER>
<TR>
<TH>Item #
<TH>Description
</TR>
%ENDIF
%{ generate individual rows %}
<TR>
<TD>
<TD>$(loopCounter)
<TD>@getDescription(loopCounter)
</TR>
%{ generate end table tag %}
%IF (loopCounter == "100")
</TABLE>
%ENDIF
%{ increment loop counter %}
@dtw_add(loopCounter, "1", loopCounter)
%}
%}