Brain Imaging & Analysis Center

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:

             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:
DEFINE(2), NAMES(1), POINTER(3), RELEASE(2), VARIABLES(1)

CIGAL Home, CIGAL Manual, Commands List, Manual Help