Implement PRIVATE and PUBLIC keywords for fine tuning of scope of variables (MAP or DIMX) in the context of functions and ++includes. Below is an update of the various combinations (including STATIC), prefaced with a few definitions relating to variable scope and duration:
Global (scope): Potentially visible from everywhere in the program. (Note: global variables are not visible within functions and procedures unless ++pragma auto_extern declared within the routine.) This is the default for MAP variables except when declared inside a function or proc.
Local (scope): Visible only within the function or procedure in which the variable was declared. This is the default for variables mapped within a function or procedure.
File (scope): Visible only within the ++include file. Requires PRIVATE keyword (PRIVATE MAPn...) and should only be used within ++include files that are collections of functions and procedures. The PRIVATE MAP statement must appear outside of any functions or procedures.
Static (duration): Variable persists for duration of program. This is the default except for variables mapped within functions/procedures. Prefixing such MAP statements with STATIC will give them static duration. Unlike automatic variables (see below), there is only one copy of each static variable in memory, even in the case of recursion.
Automatic (duration): Variable is automatically created and destroyed at runtime for each instance of a function or procedure. This is the default for variables mapped inside of a function or procedure. These are also called "stack" variables, because they are allocated on the stack. (When the function or procedure returns, they get popped off the stack.) Note that in the case of recursion, you can have multiple instances of a stack variable (one for each nesting level of the function call). Like all variables, they are always pre-initialized to zero or null (unless the MAP statement contains an explicit initialization value).
Now, let's review the new keywords STATIC, PRIVATE, PUBLIC:
MAP... Defines a global, static variable, unless it occurs within a function or procedure, in which case it defines a local automatic variable. Local variables (whether static or automatic) are invisible outside that routine. Note that if a MAP statement contains an explicit initialization value, then it has the effect of an assignment statement that gets executed at runtime. Thus, if MAP statement is in the flow of control in such a way that it can be executed multiple times, the definition of the variable only occurs once (by the compiler) but the optional initialization would occur each time the MAP statement was executed.
STATIC MAPn... Used only within functions and procedures to force creation of a static variable rather than the normal automatic stack variable. Note that if the MAP statement contains an initial value, it will only be assigned once.
PRIVATE MAPn... Used only within a ++include file, and outside of any function or procedure. This defines a variable that has file scope, and in particular will be visible within any function or procedure inside the current ++include file. This is useful when a group of related procedures need to share a few global variables that the outside program has no business knowing about.
DIMX... Defines a variable to be dynamically allocated at runtime. Note that the compiler defines the variable when the DIMx statement is encountered (as it would for a MAP statement), but the variable cannot be referenced at runtime until the DIMX statement is executed. The actual memory for the variable is allocated outside the user partition, and gets cleaned up when the program (or SBX) ends. If DIMx occurs within a function or procedure, by default the variable would be a local stack variable and thus only accessible between the time the DIMX was executed and when the routine ended. Since the cleanup doesn't occur until the program ends, this could cause a build-up of memory allocations and thus is not recommended. (See STATIC DIMX or PRIVATE DIMX or PUBLIC DIMX). Note that DIMX is an extended implementation of the original DIM statement, which is now deprecated and not officially supported within functions.
STATIC DIMX... STATIC DIMX is to DIMX as STATIC MAPn is to MAPn. Used only within functions or procedures to cause the DIMX allocation to persist. As a practical matter, to avoid executing the DIMX statement multiple times (if the function is called multiple times) you will probably have to associate it with another local STATIC flag variable that you set when the DIMX is executed.
PRIVATE DIMX... PRIVATE DIMX is to DIMX as PRIVATE MAPn is to MAPn (i.e. declares the variable to have file scope and static persistence), except that it only makes sense for such a statement to occur within a function or procedure within a ++include file. (Although DIMX, like MAPn, is preprocessed by the compiler for the purposes of "defining" the variable, regardless of where it occurs in the source code; DIMX statements need to be actually executed before the variable can be referenced. Since statements occurring outside of a function but inside of a BSI are for most practical purposes, outside of the flow of statement execution, it doesn't make sense for PRIVATE DIMX to be anywhere but inside a function or procedure.) However, once executed, the variable will be accessible from other routines within the same ++include file. As with other PRIVATE variables, this is useful when a set of related functions or procedures wish to share access to a dynamically allocated structure.
PUBLIC DIMX... This is a special form of DIMX that can occur only inside a function or procedure. (Unlike PRIVATE DIMX, it doesn't have to be within a ++include file.) It overrides the normal default of local scope and stack persistence for variables defined within a function of procedure, instead making the variable visible anywhere in the entire program. This is handy in a situation where you want to use a function or procedure to create a dynamic memory structure (perhaps by loading the data from or across the internet) that is then available in the main program.
