Administration and Programming Guide for OS/400

Specifying the Macro HTML blocks in a Transaction

You define which HTML blocks are a part of your transaction by using an identifier, called the transaction handle, in the URL request that invokes the HTML blocks. There are three steps in defining and using a transaction handle:

Define the transaction handle in your macro.
Call the DTW_ACCEPT built-in function to pass the handle name to Net.Data and the Web server.
Specify the handle in the URL request to invoke your next HTML block.

To define a transaction handle:

Define a variable for the transaction handle in the DEFINE section. For example:
```
%DEFINE handle=""
```
Optionally generate a unique transaction handle by specifying the DTW_RTVHANDLE() built-in function in the DEFINE section.
Syntax: @DTW_RTVHANDLE(handle_name)
Example:
```
@DTW_STATIC()
 
%DEFINE handle = ""
@DTW_RTVHANDLE(handle)
 
```

The transaction handle can be any valid character string. However, the DTW_RTVHANDLE() function provides a measure of security by generating a unique transaction handle, preventing others from invoking a macro which would run in your transaction.

To specify a transaction handle to Net.Data:

Specify the value of the transaction handle to Net.Data with the DTW_ACCEPT() built-in function. Because this handle is part of the information contained in the HTTP headers sent to the server, the DTW_ACCEPT() function must be called before any output is generated by the macro. Typically, it will be the first element in your HTML block.

Syntax: @DTW_ACCEPT(handle_name, ["timeout"])

Where timeout is an optional parameter that specifies the number of seconds the Web server should wait for a response from the browser before ending the transaction.

You can call DTW_ACCEPT() within an HTML block or outside of any HTML block. If the function is called outside of any HTML block, the transaction handle and the optional timeout values apply to all HTML blocks within the macro.

Example 1: Specifies a transaction handle for subsequent URL requests to run in this transaction

@DTW_STATIC()
 
%DEFINE handle = ""
@DTW_RTVHANDLE(handle)
 
 
%HTML(Block1){
@DTW_ACCEPT(handle)
 ...
%}

Important: When you call DTW_ACCEPT() as the first element in the HTML block, ensure that there is no white space between the line on which the %HTML statement is specified and the DTW_ACCEPT() call itself. Net.Data considers the white space as text to send to the browser, and issues an error because the DTW_ACCEPT() call is not found before data is sent to the browser.

Example 2: Specifies a transaction handle which applies to all HTML blocks in the macro

@DTW_STATIC()
 
%DEFINE handle = ""
@DTW_RTVHANDLE(handle)
 
@DTW_ACCEPT(handle)
 
%HTML(Block1){
 ...
%}
 
%HTML(Block2){
 ...
%}

To specify the handle when invoking an HTML block that is to run in your transaction:

After you have generated a transaction handle and called the DTW_ACCEPT() function, only URLs with that transaction handle can run in your transaction. The transaction handle must immediately follow the CGI program name in the URL.

Note:

When entering the statements in your code, the URL should be on one line with no spaces, but it is split on two lines here for display purposes.

HTML link:

<A HREF="http://server/Net.Data_invocation_path/transaction_handle/
filename/block/[?name=val&...]">any text</A>

HTML form:

<FORM METHOD=method
 ACTION="http://server/Net.Data_invocation_path/transaction_handle/
filename/block/[?name=val&...]">any text</FORM>

URL:

http://server/Net.Data_invocation_path/transaction_handle/
filename/block/[?name=val&...]

Parameters:

server: Specifies the name of the Web server. If the server is the local server, you can omit the server name and use a relative URL.
Net.Data_invocation_path: The path and filename of the Net.Data executable file. For example, /cgi-bin/db2www/.
transaction_handle: Specifies which URLs are part of a transaction initiated by a Net.Data macro. The identifier is obtained by calling the DTW_RTVHANDLE built-in function and must follow the Net.Data_invocation_path.
filename: Specifies the name of the Net.Data macro file. Net.Data searches for and tries to match this file name with the path statements defined in the MACRO_PATH initialization path variable. See MACRO_PATH for more information.
block: Specifies the name of the HTML block in the referenced Net.Data macro.
method: Specifies the HTML method used with the form. METHOD=POST is recommended.
?name=val&...: Specifies one or more optional parameters passed to Net.Data.

Typically you will provide HTML links to these URLs or specify the URL on a form action tag in your macro.

Example 1: A typical HTML block with links to other macro invocations that run in the same transaction

@DTW_STATIC()
 ...
%define handle = ""
@DTW_RTVHANDLE(handle)
 
%html(report) {
@DTW_ACCEPT(handle)
 ...
<a href="/cgi-bin/db2www/$(handle)/qsys.lib/mylib.lib/
   macros.file/pcgi1.mbr/report2">continue</a><br>
<a href="/cgi-bin/db2www/$(handle)/qsys.lib/mylib.lib/
   macros.file/pcgi1.mbr/quit">quit</a><br>
%}

Example 2: A typical HTML block with a FORM ACTION link to another macro

@DTW_STATIC()
 ...
%define handle = ""
@DTW_RTVHANDLE(handle)
 
%html(input) {
@DTW_ACCEPT(handle)
 ...
<form method=post action="/cgi-bin/db2www/$(handle)/qsys.lib/
mylib.lib/macros.file/pcgi1.mbr/report2">
<p>What type of hardware do you want to see?
<menu>
<li><input type="radio" name="hdware" value="MON" checked>Monitors
<li><input type="radio" name="hdware" value="PNT">Pointing devices
<li><input type="radio" name="hdware" value="PRT">Printers
<li><input type="radio" name="hdware" value="SCN">Scanners
</menu>
</form>
%}

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