$Web_Last_Modified
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