$Web_Save_Recset

From m204wiki
Revision as of 13:48, 26 June 2013 by Dme (talk | contribs) (→‎Syntax terms)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Save set of records

$Web_Save_Recset saves a Model 204 list or foundset so it can be restored in the same or a later session (with $Web_Restore_Recset).

$Web_Save_Recset accepts three arguments, the first one required, and it returns a string containing a 16-byte identifier (all displayable characters) for the saved record set, or it returns a null indicating that the record set could not be saved. The returned identifier must be passed to $Web_Restore_Recset to restore the saved record set.

Syntax

%id = $Web_Save_Recset( name, [timeout], [rcvar], [opts] )

Syntax terms

name A string containing the name of the list or foundset to be saved. The name of a foundset is the label for the FIND statement associated with the foundset. name can contain the word "LIST," which means that the name must match the name of a list, not a foundset.
timeout The maximum length of time that the record set will be saved. If timeout is greater than the value of the SRSMAXTO system parameter, the SRSMAXTO value will be used for the maximum timeout. If the timeout parameter is not specified or is 0, the record set will timeout after the number of seconds specified by the SRSDEFTO system parameter.
rcvar A variable to receive a return code indicating the exact nature of the error if $Web_Save_Recset returns a null. Possible values for rcvar are
0 No error.
1 Not a valid found set or list.
2 Feature not available (SRSMAX=0 or SRSMAXTO=0).
3 Group too large. This can only happen if SRSMAX is very small, like 1 or 2.
4 Can't SATTACH PST. This means that the Model 204 NSUBTKS system parameter should be increased.
5 No free session blocks
6 User limit exceeded
7 COPY type save requested for exclusively locked recordset, or saved recordset would conflict with other locks held by user
8 CCATEMP full (request cancelled)
opts A blank-delimited set of options that affects the function's behavior. This argument is optional, and it can contain the following options:
CANCEL Cancel the request, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.
ERROR Return an error code of 5, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.
STEAL Steal the oldest saved record set of $list, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.
UCANCEL Cancel the request, if the maximum allowed (SRSMAXUS) saved record sets and $lists are in-use by the requesting userid.
UERROR Return an error code of 6, if the maximum allowed (SRSMAXUS) saved record sets and $lists are in-use by the requesting userid.
USTEAL Steal the oldest saved record set of $list, if the maximum allowed (SRSMAXUS) saved record sets and $lists are in-use by the requesting userid.
MOVE Do a move-style save, that is, move to the saved version the pointers to the source record set, so the source record set looks empty after the save. This is more efficient than a COPY style save, but it does produce a potentially problematic side-effect.
COPY Do a copy-style save, that is, copy the contents of the source record set to the saved version, so the source record set is not modified after the save. This is less efficient than a MOVE style save, but it does avoid a potentially problematic side-effect.

Note: The default behavior of $Web_Save_Recset is as if STEAL, USTEAL, and MOVE were specified. You can use the system parameter SRSPARM to change this default.

Usage notes

  • $Web_Save_Recset will not save a sorted set. It will save both lists and foundsets with any kind of enqueueing — share locks (normal FIND statement), unlocked (FIND WITHOUT LOCKS or FDWOL), and exclusively locked (FIND AND RESERVE or FDR). The enqueue on the record set is held by the saved record set PST, until the record set is discarded because of timeout or restored via $Web_Restore_Recset. The list or foundset to be saved can be associated with a group rather than a file.
  • $Web_Save_Recset can be used on non-Janus Web Server threads by Janus Web Server customers. In fact, a record set can be saved on one type of thread (say a Janus Web Server thread) and restored on another (say a VTAM 3270 thread).
  • $Web_Save_Recset returns a 16-byte identifier made up of displayable characters. This identifier is required to restore the record set. In a web application, this means that the identifier should be stashed in a cookie or an invisible form field for retrieval by a procedure that would issue a $Web_Restore_Recset.

Examples

  1. In the following example, a range find is done and the results are saved via $Web_Save_Recset. The identifier is then saved in a cookie using the $Web_Set_Cookie function.

    * Do a nasty range find F: FIND ALL RECORDS FOR WHICH SDATE IS IN RANGE FROM 19960101 TO 19961231 END FIND * Save the results for later %ID = $Web_Save_Recset('F') * Save ID in a cookie %RC = $Web_Set_Cookie('FINDID', %ID)

  2. In the following example, the result of a find is placed on a list and then saved via $Web_Save_Recset.

    * Place results onto a list PLACE RECORDS IN NASTYFIND ON SAVELIST * Save the results for later %ID = $Web_Save_Recset('LIST SAVELIST')

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=$Web_Save_Recset&oldid=60553"