$Web Last Modified: Difference between revisions

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

@@ Line 1: / Line 1: @@
 {{DISPLAYTITLE:$Web_Last_Modified}}
-<span class="pageSubtitle"><section begin="desc" />Specify date/time response last updated<section end="desc" /></span>
+<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> requires one argument and returns a numeric status code. It is also [[Calling Sirius Mods $functions|callable]].
-$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.
 ==Syntax==
-<p class="syntax"><section begin="syntax" /> %RC = $Web_Last_Modified( mod_time )
+<p class="syntax"><span class="term">%rc</span> = <span class="literal">$Web_Last_Modified</span>(<span class="term"> mod_time</span> )
-<section end="syntax" /></p>
+</p>
+===Syntax terms===
-$Web_Last_Modified requires one argument and returns a numeric status code. It is also callable (see [[Calling_Sirius_Mods_$functions|Calling Sirius Mods $functions]]).
+<table>
-<table class="syntaxTable">
 <tr><th>mod_time</th>
-<td>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.
+<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>
-<table class="syntaxTable">
+===Return codes===
-<tr><th>Code</th>
+<table class="thJustBold">
-<td>Meaning</td></tr>
+<tr class="head"><th>Code</th>
+<th>Meaning</th></tr>
 <tr><th>1</th>
-<td>URL has not been modified since browser last downloaded it.</td>
+<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>
-A "Not Modified" response has been sent to the browser and the connection has been closed.<tr><th>0</th>
-<td>Last-modified time has been set.</td>
+<tr><th>0</th>
-The browser does not have a current version of the URL so the response data must be generated.<tr><th>-1</th>
+<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>
+<tr><th>-1</th>
 <td>Not a web thread</td></tr>
 <tr><th>-4</th>
 <td>Invalid datetime value</td></tr>
 </table>
-<p class="caption">$WEB_LAST_MODIFIED return codes</p>
+==Usage notes==
+<ul>
+<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>
+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>
-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.
+<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>
+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>
-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.
+<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>
-$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.
+<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>
-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.
+==Examples==
+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
-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.
+CUSTID = %CUSTID
-<p class="code"> FM: IN CUSTOMER FIND ALL RECORDS FOR WHICH
+RECTYPE = 'MASTER'
- CUSTID = %CUSTID
+END FIND
- RECTYPE = 'MASTER'
+FOR EACH RECORD IN FM
- END FIND
+%MASTER_TIME = $WEB_DATE2NS(TIMESTAMP, 'YYYYMMDDHHMISS')
- FOR EACH RECORD IN FM
+END FOR
- %MASTER_TIME = $WEB_DATE2NS(TIMESTAMP, 'YYYYMMDDHHMISS')
- END FOR
- FB: IN TRANSACT FIND ALL RECORDS FOR WHICH
+FB: IN TRANSACT FIND ALL RECORDS FOR WHICH
- CUSTID = %CUSTID
+CUSTID = %CUSTID
- RECTYPE = 'BALANCE'
+RECTYPE = 'BALANCE'
- END FIND
+END FIND
- FOR EACH RECORD IN FB
+FOR EACH RECORD IN FB
- %BALANCE_TIME = $WEB_DATE2NS(TIMESTAMP, 'YYYYMMDDHHMISS')
+%BALANCE_TIME = $WEB_DATE2NS(TIMESTAMP, 'YYYYMMDDHHMISS')
- END FOR
+END FOR
- %LAST_MODIFIED = $Max(%MASTER_TIME, %BALANCE_TIME)
+%LAST_MODIFIED = $Max(%MASTER_TIME, %BALANCE_TIME)
- IF $Web_Last_Modified(%LAST_MODIFIED) THEN
+IF $Web_Last_Modified(%LAST_MODIFIED) THEN
- STOP
+STOP
- END IF
+END IF
 </p>
+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.
-In the above example, the User Language 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 <var>$Web_Last_Modified</var>, the IF clause above should probably be rewritten as:
+<p class="code">IF $Web_Last_Modified(%LAST_MODIFIED) THEN
+IF <var>$Web_Last_Modified</var> NE 1 THEN
-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:
+%RC = $Web_Done(500, 'Bad %LAST_MODIFIED')
-<p class="code"> IF $Web_Last_Modified(%LAST_MODIFIED) THEN
+END IF
- IF $Web_Last_Modified NE 1 THEN
+STOP
- %RC = $Web_Done(500, 'Bad %LAST_MODIFIED')
+END IF
- END IF
- STOP
- END IF
 </p>
 or:
-<p class="code"> IF $Web_Last_Modified(%LAST_MODIFIED) EQ 1 THEN
+<p class="code">IF $Web_Last_Modified(%LAST_MODIFIED) EQ 1 THEN
- STOP
+STOP
- END IF
+END IF
 </p>
+==See also==
-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.
+<ul>
+<li><var>[[$Web_Expire]]</var>
-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 .
+</ul>
-See also [[$Web_Expire]].
 [[Category:Janus Web Server $functions|$Web_Last_Modified]]