$List Global and $List Session

$List_Global and $List_Session: Access/create global/session $list

Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $List_Global and $List_Session functions because of the OO ability to declare any object Global or Session (that is, this function is part of Stringlist declaration).

This function returns a $list identifier by which one may refer to a global or session $list in a request. The global or session $list may be one that already exists because of a previous $List_Global, $List_Session, or $ListSave function, or it may be created by the $List_Global or $List_Session function.

$List_Global and $List_Session accept two arguments and return a numeric result.

The first argument is the name of the global or session $list. This is a required argument.

The second argument indicates the type of processing $List_Global or $List_Session is to perform. Valid values are the following:

ANY	If the global or session $list already exists, it is referenced with its current contents. If it does not exist, a new empty global or session $list is created.
OLD	The global or session $list must already exist, that is, it must have been created with a previous $List_Global or $List_Session or saved with a $ListSave.
NEW	The global or session $list must not already exist. If it does, it will be recreated.
PREP	Same as ANY but empties $list if it has data.
PREPANY	Same as ANY but empties $list if it has data.
PREPOLD	Same as OLD but empties $list if it has data.
PREPNEW	Same as NEW.
ANYPREP	Same as ANY but empties $list if it has data.
OLDPREP	Same as OLD but empties $list if it has data.
NEWPREP	Same as NEW.

This is an optional argument and defaults to ANY.

Syntax

<section begin="syntax" /> %RESULT = $List_Global(name, type) <section end="syntax" />

$List_Global Function

%RESULT is set either to the identifier of the global $list, or to a negative error code if an error has occurred.

%RESULT = $List_Session(name, type)

$List_Session Function

%RESULT is set either to the identifier of the session $list, or to a negative error code if an error has occurred.

A particular instance of $List_Global or $List_Session always returns the same $list identifier so it cannot be called multiple times for different global or session $list names to allow simultaneous reference to these $lists.

The scope of a $List_Global or $List_Session identifier is the evaluation of the User Language request in which it was contained. When evaluation is over, global $list data appears exactly like a $ListSave'd (or $ListSav'ed) $list and, in fact, can be $ListRst'ed. For a different request to access that same global $list, it must issue a $List_Global or $ListRst with the same name. A $List_Global can also be issued against a $list that was $LISTSAVE'd, even in the same procedure, as in the following example.

%RC = $ListSave(%LIST, 'NEW.NAME') %GLIST = $List_Global('NEW.NAME')

A $List_Session cannot access a $LISTSAVE'd $list, and $ListRst cannot access a session $list.

Separate $List_Global or $List_Session statements can be issued against the same name. When this is done, each instance of $List_Global or $List_Session will return a separate $list identifier, but they will actually refer to the same underlying $list. For example, the result of the following $List_Global statements is a single global $list with name WHATEVER that contains two items: WASTE NOT is the first, and WANT NOT is the second.

%LIST1 = $List_Global('WHATEVER', 'NEW') %LIST2 = $List_Global('WHATEVER') %RC = $ListAdd(%LIST1, 'WASTE NOT') %RC = $ListAdd(%LIST2, 'WANT NOT')

A $ListImg on a global $list identifier is associated with the $list identifier, not the underlying data, so in the case of multiple $LIST_GLOBALs or $LIST_SESSIONs for the same name, the $ListImg only applies to the $list identifier for which it was issued. For example, the first $ListAddI below adds data to the global $list from image MYIMAGE, while the second $ListAddI adds data from image YOURIMAGE:

%LIST1 = $List_Global('WHATEVER', 'NEW') %LIST2 = $List_Global('WHATEVER') %RC = $ListImg(%LIST1, %MYIMAGE:COUNT) %RC = $ListImg(%LIST2, %YOURIMAGE:COUNT) %RC = $ListAddI(%LIST1) %RC = $ListAddI(%LIST2)

Global and session $list names are kept in CCATEMP. For every $List_Global or $List_Session call, logical I/O (and possibly physical I/O) must be performed to look up the name. As such, it is a good practice to avoid $LIST_GLOBALs or $LIST_SESSIONs for constant names inside a loop, and to make global and session $list identifier variables COMMON rather than letting each subroutine issue a $List_Global or $List_Session function.

If it is uncertain whether the global or session list has been already declared inside a subroutine (or anywhere for that matter), code like the following can be used to ensure that the $List_Global or $List_Session statement is only issued once.

IF NOT %MY.LIST THEN %MY.LIST = $List_Global('MY.LIST', 'ANY') END IF

The PREP prefix or suffix for all the types indicates that the returned $list should be cleared of its contents. For example, after

%LIST1 = $List_Global('WHATEVER', 'NEW') %RC = $ListAdd(%LIST1, 'WASTE NOT') %LIST2 = $List_Global('WHATEVER', 'PREPOLD') %RC = $ListAdd(%LIST2, 'WANT NOT')

the global $list identified by WHATEVER would have a single item with content WANT NOT. Just as type ANY is the default for $LIST_GLOBAL, PREP is the same as PREPANY.

Global $lists can only be restored with a $ListRst if they have not been accessed as $List_Global in the procedure that issues the $ListRst. You can clean up any global $lists with $LIST_GLOBAL_DEL, which can be issued whether or not a name was referenced in the current procedure with a $List_Global. You can clean up any session $lists with $LIST_SESSION_DEL, which can be issued whether or not a name was referenced in the current procedure with a $List_Global.

$List_Global and $List_Session have independent namespaces. That is, the same name used for $List_Global and $List_Session reference different $lists.

A $List_Session call when there is no session open causes a request cancellation.

-3 - No room in CCATEMP to add global name (not possible with OLD) -14 - No global list for name (for type OLD) Already a global list for name (for type NOTOLD) -15 - Invalid type (second parameter)

$List_Global and $List_Session Error Codes

$List_Session is new in Version 6.3 of the Sirius Mods.

• Sirius functions
• Fast/Unload User Language Interface
• Janus Open Client
• Janus Open Server
• Janus Sockets
• Janus Web Server
• Japanese functions
• Sir2000 Field Migration Facility

Products authorizing $List_Global and $List_Session