There are three types of variables:
- Explicitly defined variables using the %DEFINE statement.
- Pre-defined variables, which are variables that are made available by Net.Data and are set to a value.
- Implicitly defined variables, which are of four types:
- Variables that are not explicitly defined but are instantiated when first referenced.
- Parameter variables that are part of a %FUNCTION block definition and that can only be referenced within a %FUNCTION block.
- Variables that get instantiated by Net.Data and correspond to form data or URL data name-value pairs.
- Variables associated with a Net.Data table and that can only be referenced within a %ROW block or %REPORT block.
An identifier may be a variable or a function call. An identifier becomes visible (i.e. can be referenced) with its declaration or instantiation. The region where an identifier is visible is referred to as scope. There are five types of scope: global, macro file, function block, report block, and row block
An identifier has global scope if it can be referenced from anywhere within a macro file. Identifiers that are global in scope are: the built-in functions, form data, URL data, and variables instantiated from within an %HTML block.
An identifier has macro file scope if its declaration appears outside of any block. A block starts with an opening "{" and ends with "%}". (Note that %DEFINE blocks are excluded from this definition and should be treated as separate %DEFINE statements.) An identifier with macro file scope is visible from the point it is declared to the end of the macro file.
An identifier has function block scope if its declaration (i.e. parameters) or instantiation is located inside a %FUNCTION block (this also applies to variables that are referenced within a %REPORT or %ROW block but were not explicitly defined within the macro file or implicitly defined by Net.Data).
An identifier has report block scope if it can only be referenced from within a %REPORT block (e.g. table column names N1,...Nn). Only those variables that Net.Data implicitly defines as part of its table processing can have a report block scope. Any other variables that get instantiated will have function block scope.
An identifier has row block scope if it can only be referenced from within a %ROW block (e.g. table field values V1,...,Vn). Only those variables that Net.Data implicitly defines as part of its table processing can have a row block scope. Any other variables that get instantiated will have function block scope.
A reference to an identifier will result in that identifier being replaced with the value of the identifier. If a reference to a variable has no value associated with it, or a funtion call does not have a return value, the reference will get replaced by an empty string.
EXAMPLE 1
The following macro illustrates variable scope. The macro includes a function block (scope_test) and an HTML block (define1). The function block expects two parameters, p1 (input-only) and p2 (output-only). It also contains a report block.
%function(DTW_REXX) scope_test(IN p1, OUT p2){return%report {@dtw_assign(p2, "123")@dtw_assign(y, "yyy")From within function block: x=$(x), y=$(y), p2=$(p2)%}%}%html(define1) {@dtw_assign(x, "xxx")@scope_test("xx", z)
From within html block: x=$(x), y=$(y), z=$(z)%}
Assuming that the Web macro is stored in library NETDATA, file BASEMAC2, member DEFINE1, we reference the macro by loading the following URL (from a browser):
http://hostname/cgi-bin/db2www/qsys.lib/ netdata.lib/basemac2.file/define1.mbr/define1
The first statement in the HTML block is a call to a built-in function that assigns the string "xxx" to an undefined variable x. Since x was not defined previously, Net.Data instantiates x with global scope, and assigns it the value of the string "xxx". The following statement is a function call to scope_test(), passing it two parameters, a literal string ("xx") and an undefined variable (z). Again, since z is undefined it gets instantiated with global scope and is assigned the value of the NULL string.
Within the function block, p1 has a value of xx and p2 has the value of the NULL string since it is an OUT parameter. In the report block, p2 gets assigned the string 123 and y gets assigned the string yyy. Since p2 is an OUT parameter, upon the completion of the function block the variable z will be set to the value of p2. The variable y is undefined and thus gets instantiated by Net.Data with function block scope since it is referenced within the function block.
EXAMPLE 2
Here is a macro that defines two variables, VAR1 and VAR2, using the %DEFINE statement. It then references the variables in the %HTML block, including a variable that has not been previously defined (VAR3) and a predefined Net.Data variable (DTW_MACRO_FILENAME):
%define VAR1 = "variable one value."%define VAR2 = "variable two value."%HTML(define2) {The value of VAR1 is: $(VAR1)
The value of VAR2 is: $(VAR2)
The value of VAR3 is: $(VAR3)
The macro that is being processed is: $(DTW_MACRO_FILENAME)%}
Assuming that the Web macro is stored in library NETDATA, file BASEMAC2, member DEFINE2, we reference the macro by loading the following URL (from a browser):
http://hostname/cgi-bin/db2www/qsys.lib/ netdata.lib/basemac2.file/define2.mbr/define2
EXAMPLE 3
An alternate way to explicitly define variables is to define the variables in one %DEFINE block. Here is is the macro in example 1 written with one %DEFINE block:
%define {VAR1 = "variable one value."VAR2 = "variable two value."%}%HTML(define3) {The value of VAR1 is: $(VAR1)
The value of VAR2 is: $(VAR2)
The value of VAR3 is: $(VAR3)
The macro that is being processed is: $(DTW_MACRO_FILENAME)%}
Assuming that the Web macro is stored in library NETDATA, file BASEMAC2, member DEFINE3, we reference the macro by loading the following URL (from a browser):
http://hostname/cgi-bin/db2www/qsys.lib/ netdata.lib/basemac2.file/define3.mbr/define3
EXAMPLE 4
Below is an example of a macro accessing data sent to Net.Data via the URL route. You reference URL data like you would any other Net.Data variable:
%HTML(define4) {The value of P1 is: $(P1)
The value of P2 is: $(P2)%}
Assuming that the Web macro is stored in library NETDATA, file BASEMAC2, member DEFINE4, we reference the macro by loading the following URL (from a browser):
http://hostname/cgi-bin/db2www/qsys.lib/ netdata.lib/basemac2.file/define4.mbr/define4?P1=D1&P2=5
EXAMPLE 5
You can do a lot of neat stuff with referencing variables from within a string value. For example, the following macro sets VAR1 to a string that references a URL data variable, and VAR2 to the lowercase equivalent of the URL data variable by using the DTW_rLOWERCASE() built-in function:
%define VAR1 = "Form data variable is $(P1)"%define VAR2 = "Form data variable in lowercase is @DTW_rLOWERCASE(P1)"%HTML(define5) {$(VAR1)
$(VAR2)%}
Assuming that the Web macro is stored in library NETDATA, file BASEMAC2, member DEFINE5, we reference the macro by loading the following URL (from a browser):
http://hostname/cgi-bin/db2www/qsys.lib/ netdata.lib/basemac2.file/define5.mbr/define5?P1=D1
EXAMPLE 6
Another useful feature is defining a variable that results in a program being called by using the %EXEC form of the %DEFINE statement. In the macro below, anywhere the variable PGMVAR is referenced will result in the program "/QSYS.LIB/NETDATA.LIB/DOSOME.PGM" being called.
%define PGMVAR = %EXEC "/QSYS.LIB/NETDATA.LIB/DOSOME.PGM"%HTML(define6) {$(PGMVAR)%}
Assuming that the Web macro is stored in library NETDATA, file BASEMAC2, member DEFINE6, we reference the macro by loading the following URL (from a browser):
http://hostname/cgi-bin/db2www/qsys.lib/ netdata.lib/basemac2.file/define6.mbr/define6
EXAMPLE 7
Changing the value of a Net.Data variable is done by using the built-in function DTW_ASSIGN(). The following Web macro switches the values of VAR1 and VAR2 so that VAR1 contains the value of VAR2 and VAR2 contains the value of VAR1:
%define VAR1 = "TRUE"%define VAR2 = "FALSE"%HTML(define7) {BEFORE DTW_ASSIGN(): VAR1 = $(VAR1) and VAR2 = $(VAR2)@DTW_ASSIGN(VAR1, VAR2)@DTW_ASSIGN(VAR2, "TRUE")
AFTER DTW_ASSIGN(): VAR1 = $(VAR1) and VAR2 = $(VAR2)%}
Assuming that the Web macro is stored in library NETDATA, file BASEMAC2, member DEFINE7, we reference the macro by loading the following URL (from a browser):
