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:
jj =
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.
See also: VARIABLES[1], RELEASE[2], DEFINE[2], POINTER[3], NAMES[1].