ASSOC

The ASSOC function associates an array structure with a file. It provides a basic method of random access input/output in IDL.

Unformatted data files generated by FORTRAN programs under UNIX contain an extra long word before and after each logical record in the file. ASSOC does not interpret these extra bytes but considers them to be part of the data. This is true even if the F77_UNFORMATTED keyword is specified in the OPENR/OPENU/OPENW statement. Therefore, ASSOC should not be used with such files. Instead, such files should be processed using READU and WRITEU.

Associated file variables cannot be used for output with files opened using the COMPRESS keyword to OPEN. This is due to the fact that it is not possible to move the current file position backwards in a compressed file that is currently open for writing. ASSOC is allowed with compressed files opened for input only. However, such operations may be slow due to the large amount of work required to change the file position in a compressed file.

Effective use of ASSOC requires the ability to rapidly position the file to arbitrary positions. In general, files that require random access may not be good candidates for compression. If this is necessary however, such files can be processed using READU and WRITEU.

Tip: The three OPEN procedures open a specified file for input and/or output. OPENR (OPEN Read) opens an existing file for input only. OPENW (OPEN Write) opens a new file for input and output. If the file exists, it is truncated and its old contents are destroyed. OPENU (OPEN Update) opens an existing file for input and output. Appending to a file will not overwrite or affect other files on the system.

Syntax

Result = ASSOC( Unit, Array_Structure [, Offset] [, /PACKED] )

Return Value

Returns a value that when assigned to a variable, stores the association between an array structure and a file in an associated variable. This variable provides a means of mapping a file into vectors or arrays of a specified type and size.

Arguments

Unit

The IDL file unit to associate with Array_Structure.

Array_Structure

An expression of the data type and structure to be associated with Unit are taken from Array_Structure. The actual value of Array_Structure is not used.

Offset

The offset in the file to the start of the data in the file, in bytes.

Keywords

PACKED

When ASSOC is applied to structures, the default action is to map the actual definition of the structure for the current machine, including any holes required to properly align the fields. (IDL uses the same rules for laying out structures as the C language). If the PACKED keyword is specified, I/O using the resulting variable instead works in the same manner as READU and WRITEU, and data is moved one field at a time and there are no alignment gaps between the fields.

Examples

Suppose that the file images.dat holds 5 images as 256-element by 256-element arrays of bytes. Open the file for reading and create an associated variable by entering:

OPENR, 1, 'images.dat' ;Open the file as file unit 1.

A = ASSOC(1, BYTARR(256, 256, /NOZERO)) ;Make an associated variable.

Now A[0] corresponds to the first image in the file, A[1] is the second element, etc. To display the first image in the file, you could enter:

TV, A[0]

The data for the first image is read and then displayed. Note that the data associated with A[0] is not held in memory. It is read in every time there is a reference to A[0]. To store the image in the memory-resident array B, you could enter:

B = A[0]

You can also refer to individual elements within an associated array directly, using multiple subscripts.

Version History

Original

Introduced