OPEN Procedures (Windows)

Reference Guide > O Routines > OPEN Procedures (Windows)

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.

Usage

OPENR, unit, filename

OPENU, unit, filename

OPENW, unit, filename

Input Parameters

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

filename—The name of the file to be opened.

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.)

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

note	Delete deletes the file 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.

For example, 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).

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.

Width—Specifies the 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 the output file is not a terminal, 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. 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 for reading.

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

; Create a 256-by-256 byte array to hold the image.

ct = BYTARR(512, 512)

; Read the image.

READU, unit, ct

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

FREE_LUN, unit

; Display the image.

TVSCL, ct