9.185 SAVE_LIST
Note: Built-In Function Rules Usage Options
Permanently or temporarily saves the contents of a working list.
|
Portability Considerations
|
SAVE_LIST and RESTORE_SAVED_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
|
L
|
Req
|
Working List to be saved
|
1
|
10
|
|
|
|
2
|
N
|
Req
|
Length of each list entry i.e. Total length of all fields in the entry. For packed fields allow (SIZE/2)+1.
This parameter is ignored for RDMLX lists. Any value can be specified. Whatever the list entry length is, it will be saved correctly.
|
1
|
15
|
0
|
0
|
|
3
|
A
|
Opt
|
Type of list
'P' - Permanent list
'T' - Temporary List
If not specified, the list is assumed to be temporary.
|
1
|
1
|
|
|
|
4
|
N
|
Opt
|
Retention period (in days) for temporarily saved lists.
Only use a value in the range 1 to 90. If not specified, a default value of 7 is assumed for temporary lists.
|
1
|
2
|
0
|
0
|
|
5
|
A
|
Opt
|
Name that list is to be saved with. If this argument is not specified, or passed as blank a unique list name will be automatically assigned.
|
10
|
10
|
|
|
|
Return Values
|
No
|
Type
|
Req/ Opt
|
Description
|
Min Len
|
Max Len
|
Min Dec
|
Max Dec
|
|
1
|
A
|
Req
|
Returned name of saved list
|
10
|
10
|
|
|
|
Technical Notes
- This Built-In Function is designed to permanently save a working list, or to pass the contents of a working list between jobs (e.g. interactive to batch). It is not designed to exchange working lists details between programs 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.
- Automatically assigned list names are assigned from data area DC@A08 in the LANSA data library. In system restore situations the value in this data area should be restored as well, and then verified as being a larger number than the highest valued record found in file DC@F80.
- The automatic list name assignment procedure locks and retrieves data area DC@A08, then increments its value by 1, then returns the new value to the data area and finally unlocks it. The data area contains a 9 digit number, and the final 10 character list name is created by prefixing the assigned 9 digits with the unique prefix of the current partition.
- The automatic list name assignment logic prevents the same name from ever being assigned to more than one executing IBM i task. However, this may not be the case when you are using manually assigned list names. For instance if two IBM i tasks attempt to save a list with manually assigned name 'TESTLIST', unpredictable results may occur.
- 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.
- 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.
- It is good practice to specifically delete temporary lists use the DELETE_SAVED_LIST Built-In Function, rather than waiting for them to exceed their retention period and thus be automatically deleted during the next internal reorg.
- 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 is displayed to the user. The user can select entries from the list to be output to a printer. By saving a list of selected entries this can later be restored by a print job to create the output.
DEF_LIST NAME(#CLIENTS) FIELDS((#SELECTOR *SEL) #CLICDE #CLIDES)
DEF_LIST NAME(#SAVLST) FIELDS(#CLICDE #CLIDES) TYPE(*WORKING)
DEFINE FIELD(#LSTNME) TYPE(*CHAR) LENGTH(10)
********** Clear the list
CLR_LIST NAMED(#CLIENTS)
CLR_LIST NAMED(#SAVLST)
********** Build the browselist
SELECT FIELDS(#CLIENTS) FROM_FILE(CLIMASTER)
ADD_ENTRY TO_LIST(#CLIENTS)
ENDSELECT
********** Allow user to select clients for print
DISPLAY BROWSELIST(#CLIENTS)
SELECTLIST NAMED(#CLIENTS) GET_ENTRYS(*SELECT)
ADD_ENTRY TO_LIST(#SAVLST)
ENDSELECT
********** Save the list
USE BUILTIN(SAVE_LIST) WITH_ARGS(#SAVLST 50 T 10) TO_GET(#LSTNME)
********** Submit job to print client information
SUBMIT PROCESS(PRINTS) FUNCTION(CLIENTS) EXCHANGE(#LSTNME)
