Janus Web Server Saved Record Set Support
Web applications are basically connectionless — that is, no connection is maintained between browser and server over end-user interactions. This actually simplifies much of web coding, because it becomes the browsers job to maintain context, and because applications must be written in a way that reduces dependencies among the individual pieces.
In cases where some context must be maintained between pages, browsers can be made to hold this context via cookies, invisible form parameters, or isindex data in the URL.
There are some cases, however, where the context associated with a page might be a found set or a list. The contents of, or record numbers in, the list can be stashed in cookies or invisible form fields, but this becomes impractical for more than a few hundred records. Alternatively, the data used to build the foundset or list could be stored in cookies or invisible form fields, and the list or foundset could be rebuilt for each page. This could be very expensive if there was a significant amount of processing used to build the record set.
As an example, suppose a Janus Web Server application allows users to specify complex combinations of search criteria to build a set of records. The original search might be very expensive and might even take several CPU seconds to process. Now suppose that as part of the processing, the Janus Web Server application returns the number of records in the record set and the first 100 records to the browser with a link to retrieve the next 100 records. If the end-user clicks on the link to retrieve the next 100 records, it would be highly desirable to avoid re-doing the expensive find processing used to originally build the record set.
It is for this kind of application that Janus Web Server Saved Record Set Support was written. This support consists of some system parameters and some $functions that were introduced in Sirius Mods version 5.1.
Saved Record Set Support makes it possible to save the results of complex finds between web requests, even though the web requests are not part of a single connection, and in fact, are separated by a logoff and a logon. Record sets can be saved with the function $Web_Save_Recset. The pointers to the record enqueuing table entries associated with the saved record set are saved in a virtual storage area allocated at initialization.
The record sets are saved until they are restored and released, or until they have not been referred to for some time and so "timeout." While at least one record set is saved, a PST called SRSPST is always running in order to do the following:
- Timeout old saved record sets
- Hold the record locking enqueues associated with the saved record sets
- Hold share enqueues on the files with which saved record sets are associated, to prevent these files from being INITIALIZE'd or FREE'd
Finally, the saved record sets can be restored with the $Web_Restore_Recset function. $Web_Save_Recset and $Web_Restore_Recset are available only to Janus Web Server customers, but they can actually be used by non-Janus Web Server threads. In fact, a $Web_Restore_Recset can be issued on a different port or even different thread type from the port or thread on which the $Web_Save_Recset was issued, as long as the restoring userid is the same as the saving userid.
Because this facility is a system-wide facility, it is controlled by system parameters, one of which (SRSMAX) must be set as a User 0 parameter, and the others which can be reset by a system manager. The allocation of the saved record set table in virtual storage is controlled by the SRSMAX parameter, which defaults to 0. This means that to use Saved Record Set Support a system manager must set SRSMAX to a positive value on the User 0 parameters. The system parameters related to Saved Record Set Support are these:
| SRSDEFTO | The default timeout value (in seconds) to be used for saved record sets if none is specified on the $Web_Save_Recset function. If SRSDEFTO exceeds SRSMAXTO, SRSMAXTO will effectively act as the default timeout value. The default for SRSDEFTO is 900 which means 15 minutes. Setting SRSDEFTO to 0 means no record sets will be saved unless an explicit timeout is specified in the $Web_Save_Recset function. |
|---|---|
| SRSMAX | Maximum number of total saved record sets in the system. This parameter defaults to 0 and must be set to a positive value to allow use of the saved record set feature of Janus Web Server. If this parameter is 0, $Web_Save_Recset will never save a record set. The number of record sets that can actually be saved at a give time might be somewhat less than this value if many of the saved record sets are associated with groups with large numbers of members. The saved record set feature will use approximately 64*SRSMAX bytes of virtual storage.
If SRSMAX record sets are already saved and a user issues a $WEB_SAVE_RECSET, the oldest saved record set is discarded, even if it has not yet reached its timeout limit. |
| SRSMAXTO | Maximum length of time (in seconds) that a saved record set can be saved without being referenced. The actual maximum length of time a record set will be saved can be set in the $Web_Save_Recset function but will be set to SRSMAXTO if that value exceeds SRSMAXTO. Similarly, if a timeout is not specified on the $Web_Save_Recset so the timeout value is derived from SRSDEFTO, but SRSDEFTO is greater than SRSMAXTO, SRSMAXTO will be used as the timeout. The default for SRSMAXTO is 3600, which means a maximum timeout of one hour.
SRSMAXTO can be reset. By resetting SRSMAXTO to 0, the saved record set facility is temporarily disabled and all enqueues associated with saved record sets are freed. This can be useful in clearing up an enqueuing problem caused by one or more saved record sets. Resetting SRSMAXTO will dynamically adjust the timeout for any record sets saved with a higher timeout value. So if there is a saved record set with a timeout of 1800 seconds when SRSMAXTO is reset to 300, that record set's timeout is updated to 300. If that record set had been saved more than 300 seconds before the reset, it would be immediately discarded. |
| SRSMAXUS | Maximum number of saved record sets per user. This limit is a per-userid limit and applies even if the userid is being used from multiple web browsers. The default for SRSMAXUS is 0, which means that there is no per-user limit for saved record sets. SRSMAXUS can be used to ensure that a single user, either as the result of a programming error or simply through running frequent queries, does not monopolize the saved record set facility.
Allowing saved record sets for public URLs severely limits the usefulness of the SRSMAXUS parameter, because all saved record sets for public URLs will be saved under the WEBUSER userid. |
The timeouts on saved record sets are a trade-off between the cost of re-doing a complex find and the cost of stashing the record set and the CCATEMP I/O associated with moving the bitmap pages for the record set out of the buffer pool and then back in. In general, low timeouts (on the order of 120 seconds or less) are called for when the processing to build the record set is not too expensive, while longer timeouts (up to 3600 seconds or more) are called for when the processing to build the record set is expensive.
Applications that use $Web_Restore_Recset should always be prepared to re-do the processing used to build the original record set. This is because the $Web_Restore_Recset might fail, for any of a number of reasons, including a saved record set timeout or a cycling of the Online. This is generally not an onerous restriction, as the code to build the original record set can generally be placed in the same procedure that does the $Web_Restore_Recset.
The following example illustrates the use of alternate paths for doing either a $Web_Restore_Recset or a re-issue of a Find statement.
* Get the ID and try to restore the record set %id = $web_form_parm('FINDID') If %id Ne '' Then %rc = $web_restore_recset('F1', %id) If not %rc Then Jump to GOTF1 End if End find %start = $web_form_parm('FINDSTART') %end = $web_form_parm('FINDEND') F1: Find all records for which SDATE is in range %start to %end End find GOTF1:
To ensure the validity of the saved record sets, Janus Web Server holds a share lock on the FILE resource of any file that has a saved record set associated with it, whether in FILE or GROUP context. This prevents the file from being physically closed by the Online that has the saved record set and prevents many file maintenance functions on the file such as the INCREASE or DELETE FIELD commands or RESET for certain file parameters. In an emergency situation where some kind of file maintenance function needs to be performed immediately, a STOP FILE command can be issued for the file and all saved record sets associated with the file will be discarded. Furthermore, while the file is STOP'ed, no record sets will be saved for the file.
The contents of $lists can also be saved and restored with the $Web_Save_List and $Web_Restore_List. These functions are very much like their record set equivalents, except that instead of a found set label or list name, they accept a $list identifier as input. A saved $list is treated as a saved record set for SRSMAX, SRSMAXTO, SRSMAXUS, and SRSDEFTO processing. For example, if SRSMAXUS is set to 5, a given user can have any combination of saved record sets and $lists as long as the total number of them doesn't exceed 5.