CIGAL Reference Manual, Chapter 3 (Functions): file
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], [VARIABLES]). 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]), 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.
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)
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)