9.181 RESTORE_SAVED_LIST
Note: Built-In Function Rules Usage Options
Restores the contents of a previously saved permanent or temporary working list.
|
Portability Considerations
|
RESTORE_SAVED_LIST and SAVE_LIST should be used in the same context. That is, you should not use SAVE_LIST from within a function run on the WEB and later restore the saved list from within a function run as a Visual LANSA function.
|
Arguments
|
No
|
Type
|
Req/ Opt
|
Description
|
Min Len
|
Max Len
|
Min Dec
|
Max Dec
|
|
1
|
A
|
Req
|
Name of previously saved list to be restored.
|
1
|
10
|
|
|
|
Return Values
|
No
|
Type
|
Req/ Opt
|
Description
|
Min Len
|
Max Len
|
Min Dec
|
Max Dec
|
|
1
|
L
|
Req
|
Working List for saved list to be loaded/restored into.
|
1
|
10
|
|
|
|
2
|
A
|
Opt
|
Return Code
'OK' - List retrieved
'OV' - List full
'NR' - List not found
|
2
|
2
|
|
|
|
3
|
N
|
Opt
|
Length of each list entry
|
1
|
15
|
0
|
0
|
|
4
|
A
|
Opt
|
Type of list
'P' - Permanent list
'T' - Temporary List
|
1
|
1
|
|
|
|
Technical Notes
- This Built-In Function is designed to restore a saved working list, or to retrieve the contents of a working list passed between jobs (e.g. interactive to batch). It is not designed for retrieving working list details of a program in the same job. The exchange of working list details between programs in the same job can be achieved in a much more efficient manner by using the RCV_LISTS and PASS_LISTS parameters of the FUNCTION and CALL commands.
- File DC@F80 in the LANSA data library is used to store saved list details. This file should be considered in your backup and restore procedures.
- The target list must be the same size or bigger than the saved list or none of the information saved will be restored. This scenario will return an 'OV' return code and an empty list.
- Deleted record space in file DC@F80 is reorganized and removed during a normal LANSA internal database reorganization. This reorganization also deletes any temporary lists that have exceeded their retention period.
- You can reorganize file DC@F80 to free deleted record space at any time by using the IBM i RGZPFM (Reorganize Physical File Member) command. Use DC@F80V1 as the sequencing logical view.
- The backup and recovery of data area DC@A08 and database file DC@F80 (and its logical views DC@F80V1 and DC@F80V2) is your responsibility.
- Movement of DC@F80 or saved lists between machines or between environments is your responsibility.
Example
A list has been saved. This list is a list of clients that have been selected by user to be printed on a report. The name of the list has been passed to this job by the submitting job.
DEF_LIST NAME(#RSTLST) FIELDS((#CLICDE) (#CLIDES)) TYPE(*WORKING)
DEF_LINE NAME(#LINE1) FIELDS((#CLICDE) (#CLIDES) (#CLIAD1) (#CLIAD2) (#CLIAD3) (#CLIPHO) (#CLIFAX))
DEFINE FIELD(#LSTNME) TYPE(*CHAR) LENGTH(10)
********** Clear the list
CLR_LIST NAMED(#RSTLST)
********** Restore the list
USE BUILTIN(RESTORE_SAVED_LIST) WITH_ARGS(#LSTNME) TO_GET(#RSTLST)
********** Process the list
SELECTLIST NAMED(#RSTLST)
FETCH FIELDS(#LINE1) FROM_FILE(CLIMASTER) WITH_KEY(#CLICDE)
PRINT LINE(#LINE1)
ENDSELECT
********** Close print file
ENDPRINT
********** Submit job to delete list
USE BUILTIN(DELETE_SAVED_LIST) WITH_ARGS(#LSTNME)
