$Lstr_Global and $Lstr_Session

From m204wiki
Revision as of 21:21, 22 November 2011 by DmeWiccan (talk | contribs) (1 revision)
Jump to navigation Jump to search

and $Lstr_Session: Bind to global/session longstring

Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no direct OO equivalent for the $Lstr_Global and $Lstr_Session functions because setting Longstrings as session or global variables can be accomplished on the declarations.

This function binds a longstring %variable to a global or session longstring. That is, the longstring %variable assumes the value of the global or session longstring and any changes to the longstring %variable are reflected in the global or session longstring. The global or session longstring could be one that already existed because of a previous $Lstr_Global, $Lstr_Session, $Lstr_Global_Set or $Lstr_Session_Set call.

$Lstr_Global and $Lstr_Session accept three arguments and return a numeric result.

Syntax

<section begin="syntax" /> %RC = $Lstr_Global(gname, lstr, options) <section end="syntax" />

$Lstr_Global Function

%RC is set to 0 or, if CCATEMP is full, to -3.

%RC = $Lstr_Session(gname, lstr, options)

$Lstr_Session Function

%RC is set to 0 or, if CCATEMP is full, to -3.

  • The first argument is the name of the global or session longstring. This is an optional argument and, if not specified, the longstring %variable is unbound from whatever global or session longstring it's bound to, if any, and then set to null.
  • The second argument is a longstring %variable. It cannot be a complex subroutine parameter. This is a required argument.
  • The third argument indicates the type of processing $Lstr_Global or $Lstr_Session is to perform. Valid values of this optional argument are listed below; the default is ANY.
    ANY If the global or session longstring already exists, it is referenced with its current contents. If it does not exists, a new null global or session longstring is created.
    OLD The global or session longstring must already exist, that is, it must have been created with a previous $LSTR_GLOBAL, $LSTR_SESSION, $LSTR_GLOBAL_SET, or $Lstr_Session_Set call.
    NEW The global or session longstring must not already exist. The global or session longstring will be created if this is the case.
    PREP Same as ANY but empties the longstring if it has data.
    PREPANY Same as ANY but empties the longstring if it has data.
    PREPOLD Same as OLD but empties the longstring if it has data.
    PREPNEW Same as NEW.
    ANYPREP Same as ANY but empties the longstring if it has data.
    OLDPREP Same as OLD but empties the longstring if it has data.
    NEWPREP Same as NEW.

$Lstr_Global and $Lstr_Session will automatically unbind a previous bind for its input longstring %variable. In such a case, the value of the previously bound global or session longstring is not affected.

Only one %variable in a request can be bound to the same global name. To access the same global name in multiple complex subroutines, use a COMMON %variable in the $Lstr_Global or $Lstr_Session call.

In the following example, the global longstring SUNSHINE is set to the value PARAKEET.

%RC = $Lstr_Global('SUNSHINE', %LONG) %LONG = 'PARAKEET'

$Lstr_Global and $Lstr_Session have independent namespaces. That is, the same name used for $Lstr_Global and $Lstr_Session references different longstrings. A $Lstr_Session call when there is no session open causes a request cancellation.

You can clean up any global longstrings with $Lstr_Global_Del, which can be issued whether or not a name was referenced in the current procedure with a $Lstr_Global. You can clean up any session longstrings with $Lstr_Session_Del, which can be issued whether or not a name was referenced in the current procedure with a $Lstr_Global.

$Lstr_Global and $Lstr_Session are new in Version 6.3 of the Sirius Mods.

Products authorizing $Lstr_Global and $Lstr_Session