CIGAL Reference Manual, Chapter 2 (Commands): DECLARE
usage: declare [ qualifiers ] vname(dimensions) [ = memory ]
DECLARE is used to create new variables. In this command the arguments are not position dependent but are simply processed from left to right. This is done to allow you to include as many qualifiers as you want.
The qualifiers specify what type of variable you are declaring. (For a general discussion of CIGAL variables see VARIABLES(1).) The recognized qualifiers are indicated in the following table. For each section (A, B, or C) a valid DECLARE command can include up to 1 item from each column:
Scope Memory Loc. Word Size Varb. Type ====== =========== ========= ========== A) GLOBAL HIGH BIT NUMBER LOW CRUMB ARRAY FILE NIBBLE MATRIX CORE BYTE SOLID INTEGER IMAGE LONG REAL B) GLOBAL HIGH VECTOR LIST LOW STRING FILE C) GLOBAL POINTER
These qualifiers can entered be in any order.
The variable name can be any character string up to 12 letters that is not already a variable or command name (see NAMES(1)).
If the variable is an ARRAY, MATRIX, IMAGE, SOLID, VECTOR LIST, or STRING then you can also specify the dimensions if you wish. Specifying the dimensions forces the program to allocate a fixed amount of space for the variable, whereas if you don't specify the dimensions then the size of the variable will not be set, nor memory allocated, until you assign values to the variable. For example:
declare byte matrix mm(3,4)
creates a 3 x 4 byte matrix with fixed memory. However,
declare byte matrix jj
creates a byte matrix variable but allocates no space. If you later say:
jj = mm * 10
then a 3 x 4 matrix will be created for JJ and loaded with MM*10. You can change its size simply by assigning it a matrix of a different size. Or you can relaease all of JJ's memory, but keep the variable, by typing:
You can use the “= MEMORY” arguments if you want to create a stack variable that shares memory with another, previously declared stack variable. (This is analogous to an EQUIVALENCE statement in FORTRAN or a UNION declaration in C.) For example, the following two variables share the same memory:
declare global byte array bbuf(200) declare global integer matrix mbuf(10,10) = bbuf
In the second declaration, the INTEGER MATRIX variable MBUF is assigned the same memory storage as the BYTE ARRAY variable BBUF. The second variable need not use all of the memory of the first variable, but it must not be bigger than the first. When sharing memory keep in mind the different sizes for BIT, CRUMB, NIBBLE, BYTE, INTEGER, LONG and REAL words (1, 2, 4, 8, 16, 32, and 32 bits respectively). The MEMORY argument need not point to the beginning of a preexisting variable; for example,
declare global real array rbuf(25) = bbuf(100)
In this case the REAL variable RBUF shares memory with the second half of the BYTE variable BBUF. However, the Memory argument MUST BEGIN ON A BYTE BOUNDARY; when sharing memory with BIT, CRUMB, or NIBBLE variables be sure that the Memory argument is aligned on an 8-bit address.
NOTE: You MUST leave spaces before and after the '=' sign preceding the MEMORY argument.
In CIGAL, you can use shared memory among ARRAY, MATRIX, IMAGE, SOLID, STRING, or VECTOR LIST variables, but not POINTER, NUMBER, STRING LIST, or VECTOR variables. Any number of legal variables can share the same memory. The variables sharing memory can also be of any data type (i.e., BYTE, INTEGER, etc.) or dimensions. However, all variables with shared memory must be declared globally (see below), which means that they must include the explicit GLOBAL option if they are created within a macro command. In addition, the dimensions of variables sharing memory must be declared explicitly.
For example, assuming that BBUF and NBUF are declared as: declare global byte array bbuf(200) declare global nibble array nbuf(200) the following memory sharing declarations are legal: declare global integer matrix vbuf(10,10) = bbuf declare global integer array wbuf(50) = nbuf declare global bit solid xbuf(8,10,20) = bbuf declare global integer matrix ybuf(10,5) = bbuf(100) declare global crumb array zbuf(800) = bbuf whereas the following declarations are illegal: declare global integer matrix mbuf = bbuf ; no MBUF dimensions declare global integer matrix mbuf(20,10) = bbuf ; too big declare global integer matrix mbuf(10,10)=bbuf ; missing spaces declare global string list mbuf(10,10) = bbuf ; invalid type declare global integer matrix mbuf(10,10) = 100 ; invalid address declare global byte array mbuf(20) = nbuf(1) ; not byte aligned
If a variable is declared with a CORE qualifier then you must include the dimensions, if applicable, and you must also specify where in the physical memory that the core variable should map. In this case the MEMORY argument is the physical memory address, in bytes. For example:
declare core byte matrix vga0(320,200) = 0a0000h
creates a core variable that maps a matrix to the video graphics display memory (at physical address A0000 Hex [A000:0000]). This matrix corresponds to the display used for VGA video mode 19. Writing to VGA0 will immediately modify the display screen if you are in VGA graphics mode. Similarly, declaring number variable:
declare global core integer memsiz = 413H
lets you read the computer's memory size register as CIGAL variable MEMSIZ. This feature can be used to read or write anywhere in the computer's memory. You must exercise the appropriate caution before changing the values in the key control registers.
If the GLOBAL qualifier is specified, or if the DECLARE command is executed at the interactive level, then the new variable will be globally available. If not, the variable only exists for the duration of the macro it is declared in.
DEFINE(2), NAMES(1), POINTER(3), RELEASE(2), VARIABLES(1)