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)