OPEN Procedures (UNIX)

PV-WAVE Foundation > Reference Guide > Procedure and Function Reference: O > OPEN Procedures (UNIX)

Open a specified file for input/output:

OPENR (OPEN Read) opens an existing file for input only.

OPENU (OPEN Update) opens an existing file for input and output.

OPENW (OPEN Write) opens a new file for input and output.

note	When you use OPENW to create a new file under UNIX, if the file exists, it is truncated and its old contents destroyed.

Usage

OPENR, unit, filename [, record_length]

OPENU, unit, filename [, record_length]

OPENW, unit, filename [, record_length]

Input Parameters

unit—The logical unit number to be associated with the opened file.

filename—The name of the file to be opened. The name may contain any wildcard characters recognized by the shell specified by the SHELL environment variable. However, it is faster not to use wildcards because PV-WAVE doesn’t use the shell to expand filenames unless it has to.

Keywords

Append—If present and nonzero, causes the file to be opened with the file pointer at the end of the file, ready for data to be appended. (Normally, the file is opened with the file pointer at the beginning of the file.) Under UNIX, use of Append prevents OPENW from truncating existing file contents.

Delete—If present, causes the file to be deleted when it is closed.

note	Delete will cause the file to be deleted even if it was opened for read-only access. In addition, once a file is opened with this keyword, there is no way to cancel its operation.

Error—If present and nonzero, specifies a named variable into which the error status should be placed. (If an error occurs in the attempt to open filename, PV-WAVE normally takes the error handling action defined by ON_ERROR and/or ON_IOERROR.)

The OPEN procedures always return to the caller without generating an error message when Error is present. A nonzero error status indicates that an error occurred. The error message can then be found in the system variable !Err_String.

Statements similar to the following can be used to detect errors:

OPENR, 1, 'demo.dat', Error=err

; Try to open the file demo.dat.

IF (err NE 0) then PRINTF, -2, !Err_String

; If err is nonzero, something happened, so print the error

; message to the standard error file (logical unit –2).

F77_Unformatted—If present and nonzero, specifies that PV-WAVE is to read and write extra information in the same manner as F77. This allows data to be processed by both FORTRAN and PV-WAVE.

Unformatted, variable-length record files produced by UNIX FORTRAN programs contain extra information along with the data in order to allow the data to be properly recovered. This is necessary because FORTRAN is based on record-oriented files, while UNIX files are simple byte streams that do not impose any record structure.

Get_Lun—If present and nonzero, calls the GET_LUN procedure to set the value of unit before the file is opened. Thus, the two statements:

GET_LUN, unit

OPENR, unit, 'data.dat'

can be written as:

OPENR, unit, 'data.dat', /Get_Lun

String_Xdr—If present and nonzero, interprets the XDR strings in READU, WRITEU procedures as standard XDR strings (string length encoded as an unsigned integer) followed by the “length” bytes of the string. By default, XDR strings in PV‑WAVE are interpreted as string length encoded as two unsigned integers followed by the “length” bytes of the string.

More—If present and nonzero, and the specified filename is a terminal, formats all output to the specified unit in a manner similar to the UNIX more command. Output pauses at the bottom of each screen, at which point you can press one of the following keys:

<Space>—Causes the next page of text to be displayed.

<Return>—Causes the next line of text to be displayed.

<Q>—Suppresses all following output.

<H>—Displays the list of available options at this point.

For example, the following statements show how to output a file named text.dat to the terminal:

; Open the text file and the terminal as a file.

OPENR, inunit, 'test.dat', /Get_Lun

OPENW, outunit, '/dev/tty', /Get_Lun, /More

; Read the first line.

line = '' & readf, inunit, line

; While there is text left, output it.

while not eof(inunit) do begin

printf, outunit, line

readf, inunit, line

ENDWHILE

; Close the files and deallocate the units.

FREE_LUN, inunit & FREE_LUN, outunit

Width—Specifies desired width for output. If this keyword is not present, PV-WAVE uses the following rules to determine where to break lines:

If the output file is a terminal, the terminal width is used.

If neither condition above applies, a default of 80 columns is used.

XDR—If present and nonzero, opens the file for unformatted XDR (eXternal Data Representation) input/output via the READU and WRITEU procedures.

Using this keyword makes binary data portable across different machine architectures by reading and writing all data in a standard format. When a file is open for XDR access, the only I/O data transfer procedures that can be used with it are READU and WRITEU.

If you open an XDR file with OPENU, you must use Append in the OPENU call to move the file pointer to the end of the file. By default, when an existing XDR file is opened with OPENU, the I/O transfer is set for writing, and the file pointer is set to the beginning of the file. The !XDR_LONG system variable controls the number of bytes for LONG data types written to an XDR file.

note	Reading binary XDR data into a PV-WAVE LONG variable on a 64-bit machine causes 8 bytes to be extracted from the XDR file. In order to read 4 byte values from a binary XDR file you must pass the READ routine a PV-WAVE INT32 variable.

Example

This example uses OPENR to open the head.img file for reading. This file is in the subdirectory data, under the main PV-WAVE distribution directory. The image is read from the file, and the file is closed.

; Open head.img and create a 256-by-256 byte array to hold image.

OPENR, unit, FILEPATH('head.img', Subdir = 'data'), /Get_Lun

ct = BYTARR(512, 512)

READU, unit, ct

; Close head.img and free the file unit number associated with it.

FREE_LUN, unit

TVSCL, ct