$lists
Many Sirius $functions manipulate a data structure called a $list. A $list is a collection of variable length strings stored in CCATEMP. Each item in a $list has an associated item number and no length limit.
$lists are always cleaned up (that is, their CCATEMP pages are released, hence they can no longer be accessed) at request termination, except in the case of global $lists. Global $lists are $lists that were saved with $ListSav or $ListSave (and have not been restored with $ListRst) or those that were created with $List_Global. All non-global $lists, except those created with the NOREL attribute on $ListNew, are also cleaned up with the execution of the Release All Records statement.
Every $list has associated with it an integer called a $list identifier. This $list identifier is guaranteed to be greater than 0. Other than this, applications should not depend on the actual values for $list identifiers, because Rocket Software reserves the right to change these as needed.
Any function that creates a $list returns a $list identifier as its result. The following functions create $lists:
- $ListCpy
- $List_Global
- $ListNew
- $ListNewI
- $ListRst
- $ListSort
- $ListSrt
- $ListSub
- $PrcLEx
- $PrcLExG
- $Proc_List
- $Proc_ListG
It is possible to store as many as three gigabytes of data on a single $list. An attempt to store more data into a $list will return an error code identical to a CCATEMP full condition, or it will result in request cancellation, depending on the setting of the $SirParm LISTFC flag.
$lists provide several advantages over arrays:
- Data is stored in CCATEMP, so less server space is used. You can also store much more data in a $list than in an array.
- You do not have to know the size of your $list ahead of time.
- $list items are variable length, thus use only as much space as the data requires.
- $functions are provided to sort, search, and subset $lists.
- You can delete or insert items into a $list.
The one disadvantage of $lists relative to arrays is that they require disk buffer pool access, hence they require a little more CPU to access than array elements. Also, for $lists that have not been accessed in a while, disk writes might be performed and then a disk read might be required for each page that has been written out.
The data associated with a $list identifier can be assigned to a different $list identifier with the $ListMove function.
$lists and ECF
A $list identifier can be passed to an ECF program, as in:
EXTERNAL CALL COBPROG WITH $LIST inlist outlist
Where:
| inlist | The $list identifier to be passed to the ECF program as input. |
|---|---|
| outlist | The $list identifier to receive the data as modified by the ECF program. The contents of this $list are replaced with the ECF program output. The length of the $list items are made to match that of the input $list, and if the output $list is the same identifier as the input $list, the output data simply replaces the original input data. For PARMTYPE=INPUT ECF programs, the output $list is ignored.
|
The input $list is copied into the ECF parameter area before the ECF program is called. The $list items are concatenated and there is no way to determine where one ends and the next begins, so presumably the $list items would all have the same length, or some $list items have the length or number of occurrences of a following set of $list items (which can be used in the ECF program to determine the structure of the data).
More likely, the structure for passing data from a $list to an
ECF program will be a $list where all $list items have the same length.
To facilitate use of such a structure, the $list ECF interface automatically
places a one word (four byte) binary number of occurrences before the
copied $list items in the ECF parameter area.
This makes it possible, if the ECF program is written in COBOL, to refer
to the $list as a DEPENDING array where the number of occurrences
can vary at run-time.
To refer to the $list, the COBOL program would look something like this:
LINKAGE SECTION. 01 STUBB. 03 NUM-HARPOONS PIC 9(9) BINARY 03 HARPOON-INFO OCCURS 0 TO 25000 TIMES DEPENDING ON NUM-HARPOONS. ... PROCEDURE DIVISION USING STUBB.
If for some reason, this count is deemed undesirable in the linkage
structure, it can be suppressed via the NOCOUNT keyword in the EXTERNAL
CALL statement as in:
EXTERNAL CALL COBPROG WITH $LIST %LIST NOCOUNT
Multiple $lists and images can be passed in a single ECF call as in:
EXTERNAL CALL COBPROG WITH $LIST %LIST, INIMAGE, $LIST %LIST2