DTW_CACHE_PAGE

AIX HP-UX Linux OS/2 OS/390 OS/400 PTX SUN Win NT
X






X

Purpose

Caches partial or complete Web pages that are generated as a result of the processing of macros.

Format

@DTW_CACHE_PAGE(cacheID, pageID, age, status)

Parameters

Table 30. DTW_CACHE_PAGE Parameters
Parameter Use Description
cacheID IN A string variable identifying the cache where the page will be placed.
pageID IN A string variable containing an identifier used to locate the cached page in a subsequent DTW_CACHE_PAGE cache request. The string can be a URL.
age IN A string variable containing a length of time in seconds. This parameter determines whether a page has expired. If the page is older than age, the page is not sent to the browser.

If age is specified as -1, and the page exists in the cache, Net.Data sends it to the Web browser regardless of its age directly from the cache. Net.Data does not replace the page in the cache.

status OUT A string variable indicating the state of the cached page. Possible values are in lowercase:
  • ok: The output page will be cached when the macro execution terminates.
  • new: The page is not in the cache.
  • renew: The page is in the cache, but has expired.
  • no_cache: The cache identifier specified does not exist. It must be defined in the cache configuration files. Your macro can continue executing without page caching.
  • inactive: The cache you specified has been marked inactive. Your macro can continue executing without page caching.
  • busy: Your macro has issued the DTW_CACHE_PAGE built-in function before in this execution. Your macro can continue executing.
  • error: An error occurred while trying to communicate with the cache.

Return Codes

Table 31. DTW_CACHE_PAGE Return Codes
Return Code Explanation
-1001 The server could not process a Net.Data request to allocate memory.
1001 An input parameter contained a NULL value.
1002 An input parameter contained a string value which consisted of the null-terminating character.
1003 An incorrect number of parameters were passed on a function call.
1005 A parameter passed on a function call, required to be a string variable, was of a different variable type.
1006 A literal string was passed on a function call for a parameter which was required to be an output parameter.
1007 A parameter contains a value which is not valid.

Usage Notes

  1. When invoked, DTW_CACHE_PAGE() attempts to retrieve the specified page from the cache and to send it to the Web browser as if it were the output page generated from the macro. If the page is found and it has not expired, Net.Data stops processing the macro, exits from the macro, and sends the cached page to the Web browser.

    If the requested page is not in the cache or the existing cached page is older than the value of age, Net.Data generates a new output page. When the macro successfully completes, Net.Data sends the new page to the browser and caches the page.

  2. For most caching applications, specify DTW_CACHE_PAGE() at the top of the macro to cache all of the Web page that is generated when the macro executes. This technique makes it easier to maintain the macro when the macro is updated. For example, when the function is in the middle of the macro, it might not be noticed when a HTML report section is added earlier in the macro. Net.Data would not cache the new report output. Additionally, this method improves performance as Net.Data stops all further processing when it determines that the page is cached.

    For advanced caching applications, you can place the function in specific locations of the macro when you need to make the decision to cache at a specific point during processing, rather than at the beginning of the macro. For example, you might need to make the caching decision based on how many rows are returned from a query or function call.

Examples

Example 1: Places the DTW_CACHE_PAGE() function at the beginning of the macro to capture all HTML output

%IF (customer_status == "Classic")
@DTW_CACHE_PAGE("mymacro.mac", "http://www.mypage.org", "-1", status)
%ENDIF 
 % DEFINE { ...%}
 
...
 
%HTML(OUTPUT) {
 <title>This is the page title
 </head>
 <body>
 <center>
 This is the Main Heading
 <p>It is $(time). Have a nice day!
 </body>
 </html>
  
%} 

Example 2: Places the function in the HTML block because the decision to cache depends on the expected size of the HTML output

%DEFINE { ...%}
 
...
 
%FUNCTION(DTW_SQL) count_rows(){
  select count(*) from customer
%REPORT{
 %ROW{
  @DTW_ASSIGN(ALL_ROWS, V1)
%}
%}
%}
 
%FUNCTION(DTW_SQL) all_customers(){
  select * from customer
%}
 
%HTML(OUTPUT) {
<html>
<head>
 <title>This is the customer list
 </head>
 <body>
 
@count_rows()
 
 %IF ($(ALL_ROWS) > "100")
 @DTW_CACHE_PAGE("mymacro.mac", "http://www.mypage.org", "-1", status)
%ENDIF
 
@all_customers() 
 
 </body>
 </html>
%}

In this example, the page is cached or retrieved based on the expected size of the HTML output. HTML output pages are considered cache-worthy only when the database table contains more than 100 rows. Net.Data always sends the text in the OUTPUT block, This is the customer list, to the browser after executing the macro; the text is never cached. The lines following the function call, @count_rows(), are cached or retrieved when the conditions of the IF block are satisfied. Together, both parts form a complete Net.Data output page.

Example 3: Dynamically retrieves the cache ID and the cached page ID

%HTML(OUTPUT) {
 %IF (customer == "Joe Smith")
 
@DTW_CACHE_PAGE(@DTW_rGETENV("DTW_MACRO_FILENAME"),
@DTW_rGETENV("URL"),"-1", status)
 
%ENDIF
 
...
 
<html>
 <head>
 <title>This is the page title</title>
 </head>
 <body>
 <center>
 <h3>This is the Main Heading</h3>
 <p>It is @DTW_rDATE(). Have a nice day!</p>
  </center>
 </body>
</html>
 
%}


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