Administration and Programming Guide for OS/400

Example of a Persistent Macro

The following simple macro contains multiple HTML blocks that run in a single transaction:

@dtw_static()
%define a = "0"
%define(transient) b = "0"
%define handle = ""
@dtw_rtvhandle(handle)
 
%html(report) {
@dtw_accept(handle)
a = $(a)<br>
b = $(b)<br>
@dtw_add(a, "2", a)
@dtw_add(b, "2", b)
<a href="/cgi-bin/db2www/$(handle)/qsys.lib/mylib.lib/macros.file/pcgi1.mbr/report2">
click here to continue</a><br>
<a href="/cgi-bin/db2www/$(handle)/qsys.lib/mylib.lib/macros.file/pcgi1.mbr/quit">
click here to quit</a><br>
%}
 
%html(report2) {
@dtw_accept(handle)
a = $(a)<br>
b = $(b)<br>
@dtw_add(a, "2", a)
@dtw_add(b, "2", b)
<a href="/cgi-bin/db2www/$(handle)/qsys.lib/mylib.lib/macros.file/pcgi1.mbr/report3">
Click here to continue</a><br>
<a href="/cgi-bin/db2www/$(handle)/qsys.lib/mylib.lib/macros.file/pcgi1.mbr/quit">
Click here to quit</a><br>
%}
 
%html(report3) {
@dtw_accept(handle)
a = $(a)<br>
b = $(b)<br>
@dtw_add(a, "2", a)
@dtw_add(b, "2", b)
<a href="/cgi-bin/db2www/$(handle)/qsys.lib/mylib.lib/macros.file/pcgi1.mbr/quit">
Click here to quit</a><br>
%}
 
%html(quit) {
@dtw_terminate()
a = $(a)<br>
b = $(b)<br>
done
%}

Assuming the first call is to the HTML block report, Net.Data:

1. Calls the DTW_STATIC() function, which indicates that this macro is persistent.
2. Creates variable a as a STATIC variable because the default for persistent macros is STATIC.
3. Creates variable b as a TRANSIENT variable because it is explicitly defined with the TRANSIENT attribute.
4. Calls DTW_RTVHANDLE(), which generates a transaction handle and puts it in the variable handle.
5. Starts processing the HTML block report and calls DTW_ACCEPT(), which tells Net.Data what the transaction handle is for this transaction.
6. Finds output to send to the browser, which causes Net.Data to send the HTTP header to the Web server indicating a transaction is starting.
7. Displays the HTML page. The variables a and b both have a value of 0.

After the first page output is sent to the browser, users can choose to either continue with the transaction or quit. If they choose to continue, the Web server invokes URL:

/cgi-bin/db2www/$(handle)/qsys.lib/mylib.lib/macros.file/pcgi1.mbr/report2

The Web server recognizes the transaction handle as the one specified by Net.Data in the HTTP header. It invokes Net.Data as a persistent CGI program, which means the macro invocation is part of the current transaction.

When the HTML block report2 is invoked, Net.Data:

1. Calls the DTW_STATIC() function, which indicates this macro is persistent.
2. Recognizes that variable a is a STATIC variable and keeps the current value rather than re-initializing it to 0.
3. Recognizes that variable b is a TRANSIENT variable, creates a new instance of the variable, and initializes it to 0.
4. Calls DTW_RTVHANDLE(), which generates a transaction handle and puts it in the variable handle.
5. Starts processing the HTML block report2 and calls DTW_ACCEPT(), which tells Net.Data what the transaction handle is for this transaction.
6. Finds output to send to the browser, which causes Net.Data to send the HTTP header to the server indicating a transaction is continuing.
7. Displays the HTML page. Variable a will have a value of 2 and variable b will have a value of 0. The value of variable a is saved from the previous invocation because it is a static variable. The value of variable b is reset to 0.

After the second page is sent to the browser, the user can choose to either continue with the transaction or quit. If they choose to quit, the Web server invokes the following URL:

/cgi-bin/db2www/$(handle)/qsys.lib/mylib.lib/macros.file/pcgi1.mbr/quit

The Web server recognizes the transaction handle as the one specified by Net.Data in the HTTP header, and invokes Net.Data as a persistent CGI program, which means the macro invocation is part of the current transaction.

When the HTML block quit is invoked, Net.Data:

1. Calls the DTW_STATIC() function, which indicates this macro is persistent.
2. Recognizes that variable a is a STATIC variable and keeps the current value rather than re-initializing it to 0.
3. Recognizes that variable b is a TRANSIENT variable, creates a new instance of the variable, and initializes it to 0.
4. Calls DTW_RTVHANDLE(), which generates a transaction handle and puts it in the variable handle.
5. Starts processing the HTML block quit and calls DTW_TERMINATE(), which tells Net.Data that this is the last invocation in this transaction.
6. Finds output to send to the browser, which causes Net.Data to send the HTTP header to the server indicating a transaction is ending.
7. Displays the HTML page. Variable a has a value of 4 and variable b has a value of 0.
8. Cleans up all variables and other resources that have transaction level scope, because the DTW_TERMINATE() call has been executed.