OPENR/OPENU/OPENW

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.

Logical Unit Numbers and Application Development

Logical Unit Numbers (LUNs) are assigned to individual files when the files are opened by the IDL OPENR/OPENU/OPENW commands, and are used to specify which file IDL should read from or write to. There are a total of 128 LUNs available for assignment to files. While it is possible to assign any of the integers between 1-99 to a given file, when writing applications for others it is good programming practice to let IDL assign and manage the LUNs itself. By using the GET_LUN keyword to the OPEN routines, you can ask IDL to assign a free Logical Unit Number between 100-128 to the specified file. Letting IDL assign the LUN from the list of free unit numbers ensures that your application does not attempt to use a LUN already in use by someone else’s application. See the GET_LUN keyword for details. See Understanding (LUNs) for additional information on LUNs.

Examples

The following example opens the IDL distribution file people.dat and reads an image from that file:

; Open 'people.dat' on file unit number 1. The FILEPATH 
; function is used to return the full path name to this
; distribution file.
OPENR, 1, FILEPATH('people.dat', SUBDIR = ['examples','data'])
; Define a variable into which the image will be read:
image=BYTARR(192, 192, /NOZERO)
; Read the data:
READU, 1, image
; Display the image:
TV, image

Syntax

There are three forms of the OPEN procedure:

OPENR, Unit, File

OPENW, Unit, File

OPENU, Unit, File

Keywords (all platforms): [, /APPEND | , /COMPRESS] [, BUFSIZE={0 | 1 | value>512}] [, /DELETE] [, ERROR=variable] [, /F77_UNFORMATTED] [, /GET_LUN] [, /MORE] [, /NOEXPAND_PATH] [, /STDIO] [, /SWAP_ENDIAN] [, /SWAP_IF_BIG_ENDIAN] [, /SWAP_IF_LITTLE_ENDIAN] [, /VAX_FLOAT] [, WIDTH=value] [, /XDR]

UNIX-Only Keywords: [, /RAWIO]

Arguments

Unit

The unit number to be associated with the opened file.

File

A string containing the name of the file to be opened. Under UNIX, the filename can contain any wildcard characters recognized by the shell specified by the SHELL environment variable. However, it is faster not to use wildcards because IDL doesn’t use the shell to expand file names unless it has to.

Note: The optional Record_Length argument is obsolete, and should not be used in new code.

Keywords

Note: Platform-specific keywords are listed at the end of this section.

APPEND

Set this keyword to open the file 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. The APPEND and COMPRESS keywords are mutually exclusive and cannot be specified together.

BUFSIZE

Set this keyword to a value greater than 512 to specify the size of the I/O buffer (in bytes) used when reading and writing files. Setting BUFSIZE=1 (or any other value less than 512) sets the buffer to the default size, which is platform-specific. Set BUFSIZE=0 to disable I/O buffering.

Note that the buffer size is only changeable when reading and writing stream files. Under UNIX, the RAWIO keyword must not be set. Also note that the system stdio may choose to ignore the buffer size setting.

COMPRESS

If COMPRESS is set, IDL reads and writes all data to the file in the standard GZIP format. IDL's GZIP support is based on the freely available ZLIB library by Mark Adler and Jean-loup Gailly (see www.zlib.org for details). This means that IDL's compressed files are 100% compatible with the widely available gzip and gunzip programs. COMPRESS cannot be used with the APPEND keyword.

Tip: The FILE_GZIP/FILE_GUNZIP and ZLIB_COMPRESS/ZLIB_UNCOMPRESS routines can also be used to process GZIP files and streams.

DELETE

Set this keyword to delete the file when it is closed.

Note: Setting the DELETE keyword causes 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

A named variable to place the error status in. If an error occurs in the attempt to open File, IDL normally takes the error handling action defined by the ON_ERROR and/or ON_IOERROR procedures. OPEN always returns 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 !ERROR_STATE.MSG.

For example, statements similar to the following can be used to detect errors:

; Try to open the file demo.dat:

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

; If err is nonzero, something happened. Print the error message to

; the standard error file (logical unit -2):

IF (err NE 0) then PRINTF, -2, !ERROR_STATE.MSG

F77_UNFORMATTED

Unformatted variable-length record files produced by FORTRAN programs running on platforms that use stream files (UNIX and Microsoft Windows) contain extra information along with the data in order to allow the data to be properly recovered. This method is necessary because FORTRAN input/output is based on record-oriented files, while files that are simple byte streams do not impose any record structure. Set the F77_UNFORMATTED keyword to read and write this extra information in the same manner as f77(1), so that data can be processed by both IDL and FORTRAN. See Reading and Writing FORTRAN Data for further details.

Note: On 64-bit machines, some Fortran compilers will insert record markers that are 64-bit integers instead of the standard 32-bit integers. When reading FORTRAN data, IDL will attempt to recognize the presence of 64-bit record markers and switch to the appropriate format. When writing unformatted Fortran files, IDL will continue to use 32-bit record markers.

GET_LUN

Set this keyword to use the GET_LUN procedure to set the value of Unit before the file is opened. Instead of using the two statements:

GET_LUN, Unit

OPENR, Unit, 'data.dat'

you can use the single statement:

OPENR, Unit, 'data.dat', /GET_LUN

If MORE is set, and the specified File is a terminal, then all output to this unit is formatted in a manner similar to the UNIX more(1) command and sent to the standard output stream. Output pauses at the bottom of each screen, at which point the user can press one of the following keys:

Space: Display the next page of text.
Return: Display the next line of text.
‘q’ or ‘Q’: Suppress all remaining output.
‘h’ or ‘H’: Display this list of options.

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

; Open the text file:

OPENR, inunit, 'text.dat', /GET_LUN

; Open the terminal as a file:

OPENW, outunit, '/dev/tty', /GET_LUN, /MORE

; Read the first line:

line = '' & READF, inunit, line

; While there is text left, output it:

WHILE ~ EOF(inunit) DO BEGIN

   PRINTF, outunit, line

   READF, inunit, line

ENDWHILE

; Close the files and deallocate the units:

FREE_LUN, inunit & FREE_LUN, outunit

NOEXPAND_PATH

Set this keyword to specify that the File argument be used exactly as supplied, without applying the usual file path expansion.

RAWIO

This keyword is only available on UNIX platforms.

Set this keyword to disable all use of the standard UNIX I/O for the file, in favor of direct calls to the operating system. This allows direct access to devices, such as tape drives, that are difficult or impossible to use effectively through the standard I/O. Using this keyword has the following implications:

No formatted or associated (ASSOC) I/O is allowed on the file. Only READU and WRITEU are allowed.
Normally, attempting to read more data than is available from a file causes the unfilled space to be set to zero and an error to be issued. This does not happen with files opened with RAWIO. When using RAWIO, the programmer must check the transfer count, either via the TRANSFER_COUNT keywords to READU and WRITEU, or the FSTAT function.
The EOF and POINT_LUN functions cannot be used with a file opened with RAWIO.
Each call to READU or WRITEU maps directly to UNIX read(2) and write(2) system calls. The programmer must read the UNIX system documentation for these calls and documentation on the target device to determine if there are any special rules for I/O to that device. For example, the size of data that can be transferred to many cartridge tape drives is often forced to be a multiple of 512 bytes.

STDIO

Forces the file to be opened via the standard C I/O library (stdio) rather than any other more native OS API that might usually be used. This is primarily of interest to those who intend to access the file from external code, and is not necessary for most files.

Note: If you intend to use the opened file with the READ_JPEG or WRITE_JPEG procedures using their UNIT keyword, you must specify the STDIO keyword to OPEN to ensure that the file is compatible.

The only exception to this rule is if the filename ends in .jpg or .jpeg and the STDIO keyword is not present in the call to OPEN. In this case OPEN uses stdio by default, covering most uses of jpeg files without requiring you to take special steps.

SWAP_ENDIAN

Set this keyword to swap byte ordering for multi-byte data when performing binary I/O on the specified file. This is useful when accessing files also used by another system with byte ordering different than that of the current host.

SWAP_IF_BIG_ENDIAN

Setting this keyword is equivalent to setting SWAP_ENDIAN; it only takes effect if the current system has big endian byte ordering. This keyword does not refer to the byte ordering of the input data, but to the computer hardware.

SWAP_IF_LITTLE_ENDIAN

Setting this keyword is equivalent to setting SWAP_ENDIAN; it only takes effect if the current system has little endian byte ordering. This keyword does not refer to the byte ordering of the input data, but to the computer hardware.

VAX_FLOAT

The opened file contains VAX format floating point values. This keyword implies little endian byte ordering for all data contained in the file, and supersedes any setting of the SWAP_ENDIAN, SWAP_IF_BIG_ENDIAN, or SWAP_IF_LITTLE_ENDIAN keywords.

The default setting for this keyword is FALSE.

Note: Please read Note on Accessing Data in VAX Floating Point Format before using this feature.

WIDTH

The desired output width. If no output width is specified, IDL uses the following rules to determine where to break lines:

If the output file is a terminal, the terminal width is used.
Otherwise, a default of 80 columns is used.

XDR

Set this keyword to open the file for unformatted XDR (eXternal Data Representation) I/O via the READU and WRITEU procedures. Use XDR to make binary data portable between 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.

Note on Accessing Data in VAX Floating Point Format

The floating-point number format used by a program such as IDL is determined entirely by the computer hardware upon which it runs. In the early years of computing it was common for different machines to have incompatible floating-point formats. In the 1970s and 1980s, PDP-11 and VAX minicomputers were widely used for scientific computation, and their floating-point format (known as VAX F and D floating) became the de facto standard for science. Early versions of IDL used these formats.

In ensuing years, the computing industry has converged upon a floating-point standard known as IEEE 754, commonly referred to as “IEEE floating” or “IEEE arithmetic.” Other formats (including the VAX formats) have diminished in importance. Now, all common computing hardware uses the IEEE format, which has significant advantages over earlier formats:

Binary data is portable to almost all current and foreseeable computing hardware and operating systems, requiring at most simple byte-swapping.
Special Infinity and Not A Number (NaN) values for undefined computations allow exceptional computations to be carried out in a well-defined manner (and at full speed) by modern pipelined computer architectures.

This convergence gained momentum in the 1980s as workstations and personal computers came into prominence. As a result, almost all versions of IDL since 1987 have used IEEE floating point arithmetic, and all current versions of IDL use this format.

Despite the almost universal current use of the IEEE format, valuable older data stored in the VAX floating-point formats exists at various scientific institutions around the world. In order to allow access to this data, IDL is able to read and write data in these formats. The VAX_FLOAT keyword to the OPEN procedure is used to enable this feature.

When converting between VAX and IEEE formats, you should be aware of the following basic numerical issues in order to get the best results. Translation of floating-point values from IDL’s native IEEE format to the VAX format and back (that is, VAX to IEEE to VAX) is not a completely reversible operation, and should be avoided when possible. There are many cases where the recovered values will differ from the original values, including:

The VAX floating-point format lacks support for the IEEE special values (NaN and Infinity). Hence, their special meaning is lost when they are converted to VAX format and cannot be recovered.
The IEEE and VAX floating formats have intrinsic differences in precision and range, which can cause information to be lost in both directions. When converting from one format to another, IDL rounds the value to the nearest representable value in the target format.

As a practical matter, an initial conversion of existing VAX format data to IEEE cannot be avoided if the data is to be used on modern machines. However, each format conversion can add a small amount of error to the resulting values, so it is important to minimize the number of such conversions. Use IEEE/VAX conversions only to read existing VAX format data. Create all new files using the native IEEE format. This introduces only a single unavoidable conversion, and minimizes the resulting conversion error.

Version History

Original	Introduced
Pre-6.2	Deprecated BINARY, BLOCK, DEFAULT, EXTENDSIZE, FIXED, FORTRAN, INITIALSIZE, KEYED, LIST, MACCREATOR, MACTYPE, NON, NOAUTOMODE, NOSTDIO, PRINT, SEGMENTED, SHARED, STREAM, SUBMIT, SUPERSEDE, TRUNCATE_ON_CLOSE, UDF_BLOCK, and VARIABLE keywords