COM allocates a block of memory where variables can be held in "common" between one or more program contexts. Any subprogram or main context can access a "common" variable by including a COM statement which references the correct block of memory. One unnamed COM block is provided. To reference it, leave off the block name. The unnamed COM block must be declared in the main context. All other COM blocks are referenced by name. The name is global to all contexts.
Declaring a COM block
A COM block may contain so many variables that it takes several lines to declare them all. As long as all the COM statements are in the same context and all reference the same block name (or all have no block name), it is completely legal to divide the COM block declaration onto several lines. The following is an example:
COM /Block1/ Var1,Var2
COM /Block1/ Var3,Var4
Furthermore, the statements don't have to be next to each other. In fact, statements declaring two or more COM blocks can be intermixed. The COM statements must preceed any OPTION BASE statement that is present.
Parameters are not allowed in COM statements. Numeric variables are considered REAL until an INTEGER declaration is seen. Variables are then considered INTEGER until a REAL, I/O path or string is declared. String variables must have their length declared when declared in a COM block. Buffer variables are declared by specifying BUFFER after each variable's name. BUFFER variables are used with the TRANSFER statement.
The maximum number of array dimensions is six and the lower bound must be less than or equal to the upper bound value. In the first context that an array or string is declared, the COM statement must explicitly specify array subscript bounds and string lengths. In subsequent contexts, COM statements need only specify the string name or the array name with a full array specifier "(*)".
Matching COM blocks
The COM blocks in each context must match. In a given COM block, the individual variable names do not have to match, but the number of variables and their type must agree. The boundaries of arrays do not have to be the same, but the RANK (number of dimensions) and the SIZE must match.
Creation and Deletion of COM blocks
COM variables have a different lifetime than normal variables. When a COM block is created, the variables are all initialized to zero (or zero length strings). The variables then exist and retain values assigned to them until the COM block is deleted.
A COM block is initially created when a program context is "prerun" and the context declares a COM block that does not already exist. A prerun will be done when you:
Press RUN or STEP when no program is running
Execute the RUN command when no program is running
Execute GET or LOAD command that begins program execution
During prerun, if a COM block is declared which already exists, the new and old declarations are compared for compatibility. If they are found to be compatible, then the COM block is left untouched and the variables retain their previous values. If they are found to be incompatible then an error is returned. If a REDIM can make arrays compatible, then the arrays will be REDIMed. A COM block exists until a SCRATCH A or SCRATCH C deletes it. Even if you delete the program which refers to a COM block, it remains in memory until a SCRATCH A or C is executed.
When you LOAD a new program, all COM blocks in memory will be checked against the COM blocks defined in the new program and any unreferenced COM blocks will be deleted.
