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:
OPENR, 1, FILEPATH('people.dat', SUBDIR = ['examples','data'])
image=BYTARR(192, 192, /NOZERO)
READU, 1, 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:
OPENR, 1, 'demo.dat', ERROR = err
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
MORE
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:
OPENR, inunit, 'text.dat', /GET_LUN
OPENW, outunit, '/dev/tty', /GET_LUN, /MORE
line = '' & READF, inunit, line
WHILE ~ EOF(inunit) DO BEGIN
PRINTF, outunit, line
READF, inunit, line
ENDWHILE
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
|
See Also
CLOSE, FILE_GZIP, FILE_GUNZIP, GET_LUN, POINT_LUN, PRINT/PRINTF, READ/READF, READU, WRITEU, ZLIB_COMPRESS, ZLIB_UNCOMPRESS, General File Access