$Web Last Modified: Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
mNo edit summary |
||
| (13 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{DISPLAYTITLE:$Web_Last_Modified}} | {{DISPLAYTITLE:$Web_Last_Modified}} | ||
<span class="pageSubtitle" | <span class="pageSubtitle">Specify date/time response last updated</span> | ||
<var>$Web_Last_Modified</var> indicates the date and time that a response entity was last updated. More precisely, it indicates the date and time that the data used to generate the response entity was last updated. | <var>$Web_Last_Modified</var> indicates the date and time that a response entity was last updated. More precisely, it indicates the date and time that the data used to generate the response entity was last updated. | ||
<var>$Web_Last_Modified</var> requires one argument and returns a numeric status code. It is also | <var>$Web_Last_Modified</var> requires one argument and returns a numeric status code. It is also [[Calling Sirius Mods $functions|callable]]. | ||
==Syntax== | ==Syntax== | ||
<p class="syntax">< | <p class="syntax"><span class="term">%rc</span> = <span class="literal">$Web_Last_Modified</span>(<span class="term"> mod_time</span> ) | ||
< | </p> | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table | <table> | ||
<tr><th>mod_time</th> | <tr><th>mod_time</th> | ||
<td>A date/time expressed in seconds since 12 AM on January 1, 1900. You can use the $ | <td>A date/time expressed in seconds since 12 AM on January 1, 1900. You can use the <var>$Web_DateNS</var> function to get the current date in this format or use <var>$Web_Date2NS</var> to produce a date in this format from a date and time stamp in a file. This value is required and must be greater than or equal to 0. | ||
</td></tr></table> | </td></tr></table> | ||
===Return codes=== | ===Return codes=== | ||
<table class=" | <table class="thJustBold"> | ||
<tr><th>Code</th> | <tr class="head"><th>Code</th> | ||
<th>Meaning</th></tr> | <th>Meaning</th></tr> | ||
<tr><th>1</th> | <tr><th>1</th> | ||
<td>URL has not been modified since browser last downloaded it. A "Not Modified" response has been sent to the browser and the connection has been closed. </td></tr> | <td>URL has not been modified since browser last downloaded it. A "Not Modified" response has been sent to the browser and the connection has been closed. </td></tr> | ||
<tr><th>0</th> | <tr><th>0</th> | ||
<td>Last-modified time has been set. | <td>Last-modified time has been set. | ||
The browser does not have a current version of the URL so the response data must be generated.</td></tr> | The browser does not have a current version of the URL so the response data must be generated.</td></tr> | ||
<tr><th>-1</th> | <tr><th>-1</th> | ||
<td>Not a web thread</td></tr> | <td>Not a web thread</td></tr> | ||
<tr><th>-4</th> | <tr><th>-4</th> | ||
<td>Invalid datetime value</td></tr> | <td>Invalid datetime value</td></tr> | ||
| Line 34: | Line 38: | ||
==Usage notes== | ==Usage notes== | ||
<ul> | <ul> | ||
<li>Use <var>$Web_Last_Modified</var> to avoid re-generating or re-sending the same data. With $ | <li>Use <var>$Web_Last_Modified</var> to avoid re-generating or re-sending the same data. With <var>$Web_Last_Modified</var>, a response is sent only if the data used to generate the response has been modified since the browser last downloaded it. | ||
<p> | <p> | ||
The first time a browser requests a URL, <var>$Web_Last_Modified</var> simply sets a response header parameter called "Last-Modified" with the indicated time. If the browser should request the same URL, it will pass this time back as the value of the "If-Modified-Since" parameter. If this parameter is set by a browser, <var>$Web_Last_Modified</var> compares its input time with the time in the "If-Modified-Since" parameter. If the input time is less than or equal to the time in the "If-Modified-Since" parameter, <var>$Web_Last_Modified</var> simply sends a "Not Modified" response to the browser and closes the connection. </p> | The first time a browser requests a URL, <var>$Web_Last_Modified</var> simply sets a response header parameter called "Last-Modified" with the indicated time. If the browser should request the same URL, it will pass this time back as the value of the "If-Modified-Since" parameter. If this parameter is set by a browser, <var>$Web_Last_Modified</var> compares its input time with the time in the "If-Modified-Since" parameter. If the input time is less than or equal to the time in the "If-Modified-Since" parameter, <var>$Web_Last_Modified</var> simply sends a "Not Modified" response to the browser and closes the connection. </p></li> | ||
<li><var>$Web_Last_Modified</var> is not cumulative. That is, the time set for the "Last-Modified" parameter will be the value passed in the last <var>$Web_Last_Modified</var> call in a web application. In addition, if the time passed to <var>$Web_Last_Modified</var> is less than the value in the "If-Modified-Since" request header parameter, it '''immediately''' sends the "Not Modified" response and closes the connection. | <li><var>$Web_Last_Modified</var> is not cumulative. That is, the time set for the "Last-Modified" parameter will be the value passed in the last <var>$Web_Last_Modified</var> call in a web application. In addition, if the time passed to <var>$Web_Last_Modified</var> is less than the value in the "If-Modified-Since" request header parameter, it '''immediately''' sends the "Not Modified" response and closes the connection. | ||
<p> | <p> | ||
These two facts together, strongly suggest that in cases where a response entity is comprised of multiple data sources, each with a possibly different time stamp, the determination of the appropriate last-modified time should be made in <var class="product">User Language</var> before invoking $Web_Last_Modified. In general, the last-modified time should be the most recent (maximum) of the time stamps from the data used to generate the response. </p> | These two facts together, strongly suggest that in cases where a response entity is comprised of multiple data sources, each with a possibly different time stamp, the determination of the appropriate last-modified time should be made in <var class="product">User Language</var> before invoking <var>$Web_Last_Modified</var>. In general, the last-modified time should be the most recent (maximum) of the time stamps from the data used to generate the response. </p></li> | ||
<li>Browsers send back the time stamp received in the "Last-Modified" parameter verbatim in the "If-Modified-Since" parameter. This eliminates any need for synchronization of the server clock and the browser clock. | <li>Browsers send back the time stamp received in the "Last-Modified" parameter verbatim in the "If-Modified-Since" parameter. This eliminates any need for synchronization of the server clock and the browser clock. </li> | ||
<li>A final caution: <var>$Web_Last_Modified</var> has a resolution of one second, as do the underlying HTTP parameters: "Last-Modified" and "If-Modified-Since". It is quite possible for a <var class="product">Model 204</var> record to be updated several times within a second. Casual use of time stamps in these cases (no matter what their resolution) can result in a browser being incorrectly informed that a URL has not been modified. To avoid this, it is important to ensure that time stamps on a record '''always''' increase by at least one second no matter what the actual update times. A discussion of this and other browser cache related issues is found in [[Janus Web Server application coding considerations#Understanding browser caching| | <li>A final caution: <var>$Web_Last_Modified</var> has a resolution of one second, as do the underlying HTTP parameters: "Last-Modified" and "If-Modified-Since". It is quite possible for a <var class="product">Model 204</var> record to be updated several times within a second. Casual use of time stamps in these cases (no matter what their resolution) can result in a browser being incorrectly informed that a URL has not been modified. To avoid this, it is important to ensure that time stamps on a record '''always''' increase by at least one second no matter what the actual update times. A discussion of this and other browser cache related issues is found in [[Janus Web Server application coding considerations#Understanding browser caching|Understanding browser caching]]. </li> | ||
</ul> | </ul> | ||
==Examples== | ==Examples== | ||
In the following example, a customer ID has a MASTER and a BALANCE record associated with it, each with its own time stamp. If neither of these records has been updated since the last time the browser requested the URL associated with this customer ID, there is no need to re-send the response. | In the following example, a customer ID has a <code>MASTER</code> and a <code>BALANCE</code> record associated with it, each with its own time stamp. If neither of these records has been updated since the last time the browser requested the URL associated with this customer ID, there is no need to re-send the response. | ||
<p class="code">FM: IN CUSTOMER FIND ALL RECORDS FOR WHICH | <p class="code">FM: IN CUSTOMER FIND ALL RECORDS FOR WHICH | ||
CUSTID = %CUSTID | CUSTID = %CUSTID | ||
| Line 72: | Line 76: | ||
</p> | </p> | ||
In the above example, the <var class="product"> | In the above example, the <var class="product">SOUL</var> program exits immediately if a "Not Modified" response is sent to the browser as indicated by a return code of 1 from <var>$Web_Last_Modified</var>. Note however, that the above code will also exit immediately if the value passed to <var>$Web_Last_Modified</var> were invalid, since <var>$Web_Last_Modified</var> returns a -4 if it receives invalid input. This could happen if both time stamps in a customer's record had bad data in it. This type of bug could be fairly difficult to track down, since it would probably result in no data being sent to the browser. | ||
If there is any doubt at all about whether an invalid value might be passed to $ | If there is any doubt at all about whether an invalid value might be passed to <var>$Web_Last_Modified</var>, the IF clause above should probably be rewritten as: | ||
<p class="code">IF $Web_Last_Modified(%LAST_MODIFIED) THEN | <p class="code">IF $Web_Last_Modified(%LAST_MODIFIED) THEN | ||
IF <var>$Web_Last_Modified</var> NE 1 THEN | IF <var>$Web_Last_Modified</var> NE 1 THEN | ||
Latest revision as of 20:29, 2 September 2014
Specify date/time response last updated
$Web_Last_Modified indicates the date and time that a response entity was last updated. More precisely, it indicates the date and time that the data used to generate the response entity was last updated.
$Web_Last_Modified requires one argument and returns a numeric status code. It is also callable.
Syntax
%rc = $Web_Last_Modified( mod_time )
Syntax terms
| mod_time | A date/time expressed in seconds since 12 AM on January 1, 1900. You can use the $Web_DateNS function to get the current date in this format or use $Web_Date2NS to produce a date in this format from a date and time stamp in a file. This value is required and must be greater than or equal to 0. |
|---|
Return codes
| Code | Meaning |
|---|---|
| 1 | URL has not been modified since browser last downloaded it. A "Not Modified" response has been sent to the browser and the connection has been closed. |
| 0 | Last-modified time has been set. The browser does not have a current version of the URL so the response data must be generated. |
| -1 | Not a web thread |
| -4 | Invalid datetime value |
Usage notes
- Use $Web_Last_Modified to avoid re-generating or re-sending the same data. With $Web_Last_Modified, a response is sent only if the data used to generate the response has been modified since the browser last downloaded it.
The first time a browser requests a URL, $Web_Last_Modified simply sets a response header parameter called "Last-Modified" with the indicated time. If the browser should request the same URL, it will pass this time back as the value of the "If-Modified-Since" parameter. If this parameter is set by a browser, $Web_Last_Modified compares its input time with the time in the "If-Modified-Since" parameter. If the input time is less than or equal to the time in the "If-Modified-Since" parameter, $Web_Last_Modified simply sends a "Not Modified" response to the browser and closes the connection.
- $Web_Last_Modified is not cumulative. That is, the time set for the "Last-Modified" parameter will be the value passed in the last $Web_Last_Modified call in a web application. In addition, if the time passed to $Web_Last_Modified is less than the value in the "If-Modified-Since" request header parameter, it immediately sends the "Not Modified" response and closes the connection.
These two facts together, strongly suggest that in cases where a response entity is comprised of multiple data sources, each with a possibly different time stamp, the determination of the appropriate last-modified time should be made in User Language before invoking $Web_Last_Modified. In general, the last-modified time should be the most recent (maximum) of the time stamps from the data used to generate the response.
- Browsers send back the time stamp received in the "Last-Modified" parameter verbatim in the "If-Modified-Since" parameter. This eliminates any need for synchronization of the server clock and the browser clock.
- A final caution: $Web_Last_Modified has a resolution of one second, as do the underlying HTTP parameters: "Last-Modified" and "If-Modified-Since". It is quite possible for a Model 204 record to be updated several times within a second. Casual use of time stamps in these cases (no matter what their resolution) can result in a browser being incorrectly informed that a URL has not been modified. To avoid this, it is important to ensure that time stamps on a record always increase by at least one second no matter what the actual update times. A discussion of this and other browser cache related issues is found in Understanding browser caching.
Examples
In the following example, a customer ID has a MASTER and a BALANCE record associated with it, each with its own time stamp. If neither of these records has been updated since the last time the browser requested the URL associated with this customer ID, there is no need to re-send the response.
FM: IN CUSTOMER FIND ALL RECORDS FOR WHICH CUSTID = %CUSTID RECTYPE = 'MASTER' END FIND FOR EACH RECORD IN FM %MASTER_TIME = $WEB_DATE2NS(TIMESTAMP, 'YYYYMMDDHHMISS') END FOR FB: IN TRANSACT FIND ALL RECORDS FOR WHICH CUSTID = %CUSTID RECTYPE = 'BALANCE' END FIND FOR EACH RECORD IN FB %BALANCE_TIME = $WEB_DATE2NS(TIMESTAMP, 'YYYYMMDDHHMISS') END FOR %LAST_MODIFIED = $Max(%MASTER_TIME, %BALANCE_TIME) IF $Web_Last_Modified(%LAST_MODIFIED) THEN STOP END IF
In the above example, the SOUL program exits immediately if a "Not Modified" response is sent to the browser as indicated by a return code of 1 from $Web_Last_Modified. Note however, that the above code will also exit immediately if the value passed to $Web_Last_Modified were invalid, since $Web_Last_Modified returns a -4 if it receives invalid input. This could happen if both time stamps in a customer's record had bad data in it. This type of bug could be fairly difficult to track down, since it would probably result in no data being sent to the browser.
If there is any doubt at all about whether an invalid value might be passed to $Web_Last_Modified, the IF clause above should probably be rewritten as:
IF $Web_Last_Modified(%LAST_MODIFIED) THEN IF $Web_Last_Modified NE 1 THEN %RC = $Web_Done(500, 'Bad %LAST_MODIFIED') END IF STOP END IF
or:
IF $Web_Last_Modified(%LAST_MODIFIED) EQ 1 THEN STOP END IF