local Name [Subscript] [= Value] Type, ... local @ Name [Subscript] Type, ... local * Name [Subscript] Type, ... local Name = Value, ... local Name |= Expression local Name([Parameter, ...]) => Expression | Condition
Local variables, pointers, Micros, and Macros can only be used in the procedure in which they are declared. Micros are defined by including a constant value expression and excluding the type. If a variable has a primitive type, an initial value may also be coded. Variables and pointers are both typed.
Pointer variables are denoted by a leading at sign or star (@, *). An at sign indicates a Reference pointer that only allows read access to an object. A star declares a Wizard pointer that lets you can change things it points to.
Variables and pointers may also declare array ranges. Bounds are constant integer expressions or enumerations. The lower bound defaults to zero if not included. Up to 10 array dimensions can be declared.
Range := Dimension, ... Dimension := [Lower to] Upper
@Name [= 0] Type '|' Type [ '|' ... ] *Name [= 0] Type '|' Type [ '|' ... ]
Variant pointers can reference one of several types or contain zero. They may also be used as a structure field or an Exit parameter.
There must be fewer types in the list of types than the smallest alignment of the types in the list. For example, if the smallest alignment is a Word (4 bytes) the list can contain either two or three types. Consequently variants cannot reference byte or parcel aligned objects.
A variant pointer may be assigned to the address of an object or the address in an invariant pointer. The type of the variable or invariant pointer must be in the variant type list.
Variant = @Variable :Point a variant pointer at a variable. Variant = @Pointer :Set a variant pointer to an invariant pointer.
A variant pointer may also be assigned to the address in another variant pointer, but only if the type lists match and are declared in the same order.
Variant = @Variant :Copy one variant pointer to another.
Variables can not be accessed directly through a variant pointer. To do this you must first assign the variant pointer to an invariant pointer. The current type of the variant pointer must match or zero will be assigned.
Pointer = @Variant :Cast a variant to an invariant pointer.
The current type contained in a variant pointer can be determined using the Parcel function. It will returns the position of the type corresponding to the current setting or zero if the variant pointer is set to zero. Note that variant pointers can not encode a Parcel as well (see Pointer.help).
parcel( @Variant )
A variable length array can also be declared to dynamically allocate an array. Dynamic arrays are Local to a procedure. The upper most bound can be an expression using any Entry and Change parameters, constants, and intrinsic functions. If included the lower bound must be constant expressions.
method PROCESS.NAME entry Name string local Name.C[ length( Name )] byte :Allocate space for a C string. Name.C = To.C.String( Name ); :Fill the array with null terminated text.
Variable length arrays are allocated on the heap and are accessed via an internal Local pointer. The array is deallocated upon exit from the procedure. This includes cases where the precedure exits due to an exception or was unwound while processing an exception. Any Postconditions are checked prior to allocating the array.
When you invoke a procedure, memory for its Local variables is allocated on the program stack. The allocated space is dirty so it also needs to be initialized; which is called cleaning. Compilers may also create temporary Local variables that are also allocated and cleaned. To leave a Local variable or array uninitialized declare it with a default value of "?".
Local variables are initialized each time the method is called. If no initial value is declared then pointers, numeric, and enumerated variables are set to zero. String variables are set to an empty string. Numeric and enumerated variables may be left uninitialized by using a question mark as the initial value. This improves performance where speed is critical, especially for large arrays.
If a Class or Type declaration includes a structure type then the fields are are initialized in the same way as Local variables. Fields are cleaned unless given a default "?" value.
If the procedure declares any variable length arrays, they are allocted from heap memory. Every element of the array is then cleaned unless declared with a default value of "?". Upon exit they are drained and the allocated memory is freed.
Upon return from a procedure Local variables are drained; which is the process of releasing its resources. They also are drained when exiting due to an exception, returning from an exception handler, or unwinding due to an exception further down the call stack.
Upon exit from a method, any heap memory used by Local variables is freed if they are Strings, structures, or variable length arrays. If a Drain method is declared for a structure that corresponds to a structure, it is automatically invoked and typically deallocates memory. Additionally a Drain method may release any other resources used by the subject variable.
Sequences that have Local variables need to save them between calls. On the first iteration sequence Locals are allocated in heap memory instead of the program stack. There they are cleaned and the sequence body begins running. Later when a sequence is terminated its Locals are drained and deallocated from the heap.
Entry, Change, and Exit Parameter
