$Lstr Global and $Lstr Session

$Lstr_Global and $Lstr_Session: Bind to global/session longstring

Note: Many $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.

Syntax

%rc = $Lstr_Global([gname], lstr, [options])

%rc = $Lstr_Session([gname], lstr, [options])

Syntax terms

%rc	A numeric return code that is set to 0 or, if CCATEMP is full, to -3.
gname	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.
lstr	A longstring %variable. It cannot be a complex subroutine parameter. This is a required argument.
options	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.

Usage notes

• $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.
• $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.

Example

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

%rc = $Lstr_Global('SUNSHINE', %long) %long = 'PARAKEET'

Products authorizing $Lstr_Global and $Lstr_Session

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