Reference

Persistent Macro Functions

The persistent macro functions support transaction processing in Net.Data by helping you define which macro blocks are persistent within a single transaction. Use these functions to define the start and end of a transaction, which HTML blocks are persistent throughout the transaction, the scope of the variables within the transaction, and whether to commit or rollback changes within the transaction.

• DTW_ACCEPT
• DTW_COMMIT
• DTW_ROLLBACK
• DTW_RTVHANDLE
• DTW_STATIC
• DTW_TERMINATE

DTW_ACCEPT

Purpose

Defines the transaction handle used to invoke a persistent macro.

Format

@DTW_ACCEPT(handle, timeout)

@DTW_ACCEPT(handle)

Parameters

Table 209. DTW_ACCEPT Parameters

Return Codes

Table 210. DTW_ACCEPT Return Codes

Usage Notes

1. Net.Data requires that the transaction handle be included in the URL that invokes the macro as a response from the Web browser. When a request comes in to the Web server, the server uses the transaction handle to route the request to the CGI process that is processing the transaction.

   The transaction handle must be called at the start of each HTML block in the macro until the last logical block, which contains a call to DTW_TERMINATE(). If either a call to DTW_ACCEPT() or DTW_TERMINATE() is not found before any text is output to the browser, a Net.Data error occurs.

2. You can specify a timeout value for this page that overrides the timeout value specified on the @DTW_STATIC() function. The Web server waits for specified amount of time (in seconds) for the user to respond to this request.
3. If this function is called when the macro is not in a persistent state, a Net.Data error occurs.
4. The URLs containing the transaction handle can be coded as actions on form push buttons or as hypertext links on the page presented to the browser.

Examples

Example 1:

%DEFINE handle = ""
@DTW_RTVHANLDE(handle)
 
%HTML(REPORT){
@DTW_ACCEPT(handle)
 ...
%}

DTW_COMMIT

Purpose

Makes permanent any pending changes made to resources under commitment control since the last commitment boundary and establishes a new commitment boundary.

Format

@DTW_COMMIT()

Parameters

None.

Return Codes

Table 211. DTW_COMMIT Return Codes

Examples

Example 1: Specifies a commit

@DTW_COMMIT()
%HTML(report){
%}
 

DTW_ROLLBACK

Purpose

Reestablishes the last commitment boundary as the current commitment boundary. All changes to resources under commitment control for the process that Net.Data is running under made since the last commitment boundary are backed out.

Format

@DTW_ROLLBACK()

Parameters

None.

Return Codes

Table 212. DTW_ROLLBACK Return Codes

Examples

Example 1: Specifies a rollback

@DTW_ROLLBACK() 
%HTML(report){
%}

DTW_RTVHANDLE

Purpose

Generates and returns a transaction handle that is unique to this macro across separate invocations and is calculated based on a combination of thread information, timestamp, and current user.

Format

@DTW_RTVHANDLE(handle)

Parameters

Table 213. DTW_RTVHANDLE Parameters

Return Codes

Table 214. DTW_RTVHANDLE Return Codes

Usage Notes

The transaction handle can be used to ensure that URLs specified as part of a persistent transaction are unique to the HTTP server and can be securely identified as valid requests.

Examples

Example 1: Defines the handle variable used to retrieve the transaction handle

%DEFINE handle = ""
@DTW_RTVHANLDE(handle)

DTW_STATIC

Purpose

Indicates that the entire macro is persistent.

Format

@DTW_STATIC(timeout)

@DTW_STATIC()

Parameters

Table 215. DTW_STATIC Parameters

Return Codes

Table 216. DTW_STATIC Return Codes

Usage Notes

1. DTW_STATIC should be the first statement in the macro. All variables defined in the macro after this function call will be persistent across multiple macro invocations unless specified otherwise and until DTW_TERMINATE() is called or the process is ended.
2. A timeout value, in seconds, can be specified on the function call to indicate the amount of time the process Net.Data is running under waits for a response from the browser. If the timeout value expires, the process ends, and all changes to resources under commitment control since the last commitment boundary are rolled back.
3. If a timeout value is specified on a subsequent @DTW_ACCEPT() call, Net.Data overrides this value with the value in the subsequent call. If a timeout value is not specified on this call or a subsequent @DTW_ACCEPT() call, the Web server default timeout value is used.

Examples

Example 1: A call to DTW_STATIC() specifying a timeout value of 60 seconds.

@DTW_STATIC("60")

DTW_TERMINATE

Purpose

Ends a persistent transaction. All changes to resources under commitment control since the last commitment boundary are made permanent.

Format

@DTW_TERMINATE()

Parameters

None

Return Codes

Table 217. DTW_TERMINATE Return Codes

Usage Notes

1. The DTW_TERMINATE function is called at the start of the logical last HTML block of the persistent transaction before any text is output to the browser. If any text output appears before the function, within the block, a Net.Data error will occur. Note that there could be more than one logical last HTML block depending on how the application is written.
2. If this function is called when the macro is not in a persistent state, a Net.Data error will occur.

Examples

Example 1: Terminates the persistent transaction

%HTML(QUIT){
@DTW_TERMINATE()
 ...
%}