Brain Imaging & Analysis Center

usage: ptr = file(fname,recsiz,xdim,ydim,zdim,hdrsiz,wdsiz)
or: ptr = file()

FILE creates a pointer to a disk file, which makes the file appear as an internal CIGAL data variable. This function must be assigned to a pointer variable (see VARIABLES(1), DECLARE(2)). The FILE command is a special case of the POINTER command (see POINTER(3))– it is specialized in that the first argument is taken to be a file name, not a variable name.

Assigning a file to a pointer:

Any binary (i.e, non-ASCII) file can be assigned to a pointer and then manipulated the same as any other CIGAL variable. The meanings of the arguments to FILE are given below. If the file is in a data format recognized by CIGAL (e.g., TIFF; see FILES(1)) then the only argument required for the FILE command is the file name, FNAME. For unrecognized data file formats the other options are strongly advised.

 FNAME  must be a character string containing the name, or a number in which
        case the file name is taken to be the character string DATADIR with
        the specified number added at the end (see [DATADIR][4], [VARIABLES][1]).
 
 RECSIZ is the buffer size (in bytes) assigned to this pointer-- ideally
        an integral multiple or factor of XDIM.  Keep in mind that CIGAL uses
        3 buffers for each variable so that the total buffer space allocated
        will be 3 x RECSIZ (times the number of bytes per data element-- see
        WDSIZ below).
 
 XDIM   is the length of the data set in the X dimension
 
 YDIM   is the length of the data set in the Y dimension
 
 ZDIM   is the length of the data set in the Z dimension
        Note: If YDIM and ZDIM are both 1, the pointer behaves as an ARRAY
              variable.  If ZDIM is 1, the pointer behaves as a MATRIX
              variable.  Otherwise, the pointer behaves as a SOLID variable.
 
 HDRSIZ is the header offset value. It specifies the number of bytes to ignore
        at the beginning of the file
 
 WDSIZ  is the format of individual data words (see [VARIABLES][1]), as follows:
          1 - bit                8 - byte (8 bits)       96 - real (32 bits)
          2 - crumb (2 bits)    16 - integer (16 bits)  136 - vector (64 bits)
          4 - nibble (4 bits)   32 - long (32 bits)

The named file is opened when it is assigned to a pointer and remains open as long as the pointer remains assigned to that file.

Releasing an assigned file:

     An assigned file is released and closed when the pointer is assigned to
     another variable (eg., using the FILE or POINTER command), or to nothing, eg.,
         ptr = file()

The file is also unassigned automatically if the pointer variable itself is released, either by the RELEASE(2) command or when local variables are released at the termination of a macro command (see MACROS(1), DECLARE(2)).

NOTE: Data files do not have to be assigned to a pointer to be used by CIGAL. Read or write files using the READ, WRITE, INPUT, and OUTPUT commands, or as a file variable by prefixing the filename with the appropriate data type character (see VARIABLES(1)). Assigning to a pointer variable has several advantages, however, as described under the POINTER command.

Examples:

  1) Declare a pointer variable, PP, and assign it to an image file:
            declare pointer pp
            pp = file('cellimage',1536,768,640,1,18,8)

  2) Assign a disk file to the internal pointer variable ZIMAGE, to be used
     for storing the Z direction information of the graphics display:
            zimage = file(ztmp,1024,512,512,1,0,16)

See Also:
DATADIR(4), DECLARE(2), FILES(1), MACROS(1), OFFSET(2), PIN(2), POINTER(3), PROJECTION(3), RELEASE(2), ROTATE(2), SCALE(2), SIMAGE(4), TIFF(1), TRANSFORM(3), VARIABLES(1), VIMAGE(4), YZIMAGE(4), ZIMAGE(4)

CIGAL Home, CIGAL Manual, Functions List, Manual Help