$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