Unit

The unit number to be associated with the opened file.

File

A string containing the name of the file to be opened. Note the following platform-specific behaviors:

• 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. No wildcard characters are allowed under VMS.
• Under VMS, filenames that do not have a file extension are assumed to have the .DAT extension. No such processing of file names occurs under Unix.

Record_Length

The Record_Length argument has meaning only under VMS. It specifies the file record size in bytes. This argument is required when creating new, fixed-length files, and is optional when opening existing files. If this argument is present when creating variable-length record files, it specifies the maximum allowed record size. If this argument is present and no file organization keyword is specified, fixed-length records are implied.

Due to limitations in RMS (the VMS Record Management System), the length of records must always be an even number of bytes. Odd record lengths are therefore automatically rounded up to the nearest even boundary.

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.

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 NOSTDIO keyword must not be set. Also not that the system stdio may choose to ignore the buffer size setting.

DELETE

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

CAUTION: 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 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. Print the error message to the standard error file (logical unit -2).

F77_UNFORMATTED

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 method is necessary because FORTRAN input/output is based on record-oriented files, while Unix files are simple byte streams that 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 to be processed by both IDL and FORTRAN. See UNIX-Specific Information for further details.

CAUTION: Do not confused this keyword with the VMS-only keyword FORTRAN.

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.
• The following statements show how to output a file named text.dat to the terminal:

OPENR, inunit, 'text.dat', /GET_LUN; Open the text file.

OPENW, outunit, '/dev/tty', /GET_LUN, /MORE
; Open the terminal as a file.

line = '' & READF, inunit, line ; Read the first line.

WHILE NOT EOF(inunit) DO BEGIN ; While there is text left, output it.

    PRINTF, outunit, line

    READF, inunit, line

ENDWHILE

FREE_LUN, inunit & FREE_LUN, outunit ; Close the files and deallocate the units.

Under VMS, the MORE keyword is only allowed for stream mode files.

SWAP_ENDIAN

When performing binary I/O on the specified file, all multi-byte data has its byte ordering swapped. 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

Equivalent to SWAP_ENDIAN, but only takes effect if the current system has big endian byte ordering. Note that this keyword does not refer to the byte ordering of the input data, but to the computer hardware.

SWAP_IF_LITTLE_ENDIAN

Equivalent to SWAP_ENDIAN, but only takes effect if the current system has little endian byte ordering. Note that 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 superceeds any setting of the SWAP_ENDIAN, SWAP_IF_BIG_ENDIAN, or SWAP_IF_LITTLE_ENDIAN keywords.

The default setting for this keyword is FALSE. Under VMS, starting the VAX_FLOAT option to the IDL command at startup has the effect of changing this default and making it TRUE. See Command Line Options for details on this qualifier. You can change this setting at runtime using the VAX_FLOAT function.

CAUTION: Please read Note On IEEE to VAX Format Conversion before using this feature.

WIDTH

The desired output width. When using the defaults for formatted output, IDL uses the following rules to determine where to break lines:

• If the output file is a terminal, the terminal width is used. Under VMS, if the file has fixed-length records or a maximum record length, the record length is used.
• Otherwise, a default of 80 columns is used.

The WIDTH keyword allows the user to override this default.

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. XDR is described in Portable Unformatted Input/Output ".

Under VMS, the XDR keyword can only be used with stream files.

MACCREATOR

Use this keyword to specify a four-character scalar string identifying the Macintosh file creator code of the file being created. For example, set

MACCREATOR = 'MSWD'

to create a file with the creator code MSWD . The default creator code is MIDL .

MACTYPE

Use this keyword to specify a four-character scalar string identifying the Macintosh file type of the file being created. For example, set

MACTYPE = 'PICT'

to create a file of type PICT . The default file type is TEXT .

BINARY

Set this keyword to treat opened files as binary files. When writing text to a binary file, CR/LF pairs are written as LF only. Note that setting the BINARY keyword alone does not ensure that a routine that writes to the file will not change the mode to text.

NOAUTOMODE

Set this keyword to prevent IDL routines such as PRINTF from automatically changing the mode from binary to text, or vice versa.

NOSTDIO

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 NOSTDIO. When using NOSTDIO, 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 NOSTDIO.
• 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.

BLOCK

Set this keyword to process the file using RMS block mode. In this mode, most RMS processing is bypassed and IDL reads and writes to the file in disk block units. Such files can only be accessed via unformatted I/O commands. Block mode files are treated as an uninterpreted stream of bytes in a manner similar to Unix stream files.

For best performance, by default IDL uses RMS block mode for fixed length record files. However, when the SHARED keyword is present, IDL uses standard RMS mode. Do not specify both BLOCK and SHARED.

This keyword is ignored when used with stream files.

NOTE: With some controller/disk combinations, RMS does not allow transfer of an odd number of bytes.

DEFAULT

A scalar string that provides a default file specification from which missing parts of the File argument are taken. For example, to make .LOG be the default file extension when opening a new file, use the command:

OPENW, 'DATA', DEFAULT='.LOG'

This statement will open the file DATA.LOG.

EXTENDSIZE

File extension is a relatively slow operation, and it is desirable to minimize the number of times it is done. In order to avoid the unacceptable performance that would result from extending a file a single block at a time, VMS extends its size by a default number of blocks in an attempt to trade a small amount of wasted disk space for better performance. The EXTENDSIZE keyword overrides the default, and specifies the number of disk blocks by which the file should be extended. This keyword is often used in conjunction with the INITIALSIZE and TRUNCATE_ON_CLOSE keywords.

FIXED

Set this keyword to indicate that the file has fixed-length records. The Record_Length argument is required when opening new, fixed-length files.

FORTRAN

Set this keyword to use FORTRAN-style carriage control when creating a new file. The first byte of each record controls the formatting.

INITIALSIZE

The initial size of the file allocation in blocks. This keyword is often used in conjunction with the EXTENDSIZE and TRUNCATE_ON_CLOSE keywords.

KEYED

Set this keyword to indicate that the file has indexed organization. Indexed files are discussed in " VMS-Specific Information ".

LIST

Set this keyword to specify carriage-return carriage control when creating a new file. If no carriage-control keyword is specified, LIST is the default.

NONE

Set this keyword to specify explicit carriage control when creating a new file. When using explicit carriage control, VMS does not add any carriage control information to the file, and the user must explicitly add any desired carriage control to the data being written to the file.

PRINT

Set this keyword to send the file to SYS$PRINT, the default system printer, when it is closed.

SEGMENTED

Set this keyword to indicate that the file has VMS FORTRAN-style segmented records. Segmented records are a method by which FORTRAN allows logical records to exist with record sizes that exceed the maximum possible physical record sizes supported by VMS. Segmented record files are useful primarily for passing data between FORTRAN and IDL programs.

SHARED

Set this keyword to allow other processes read and write access to the file in parallel with IDL. If SHARED is not set, read-only files are opened for read sharing and read/write files are not shared. The SHARED keyword cannot be used with STREAM files.

CAUTION: It is not a good idea to allow shared write access to files open in RMS block mode. In block mode, VMS cannot perform the usual record locking that prevents file corruption. It is therefore possible for multiple writers to corrupt a block mode file. This warning also applies to fixed-length record disk files, which are also processed in block mode. When using SHARED, do not specify either BLOCK or UDF_BLOCK.

STREAM

Set this keyword to open the file in stream mode using the Standard C Library (stdio).

SUBMIT

Set this keyword to submit the file to SYS$BATCH, the default system batch queue, when it is closed.

SUPERSEDE

Set this keyword to allow an existing file to be superseded by a new file of the same name, type, and version.

TRUNCATE_ON_CLOSE

Set this keyword to free any unused disk space allocated to the file when the file is closed. This keyword can be used to get rid of excess allocations caused by the EXTENDSIZE and INITIALSIZE keywords. If the SHARED keyword is set, or the file is open for read-only access, TRUNCATE_ON_CLOSE has no effect.

UDF_BLOCK

Set this keyword to create a file similar to those created with the BLOCK keyword except that new files are created with the RMS undefined record type. Files created in this way can only be accessed by IDL in block mode, and cannot be processed by many VMS utilities. Do not specify both UDF_BLOCK and SHARED.

VARIABLE

Set this keyword to indicate that the file has variable-length records. If the Record_Length argument is present, it specifies the maximum record size. Otherwise, the only limit is that imposed by RMS (32767 bytes). If no file organization is specified, variable-length records are the default.

CAUTION: VMS variable length records have a 2-byte record-length descriptor at the beginning of each record. Because the FSTAT function returns the length of the data file including the record descriptors, reading a file with VMS variable length records into a byte array of the size returned by FSTAT will result in an RMS EOF error.

Note On IEEE to VAX Format Conversion

Translation of floating-point values from the IDL's native (IEEE) format to the VAX format and back (IEEE to VAX to IEEE) is not a completely reversable operation, and should be avoided when possible. There are many cases where the recovered values will differ from the original, including:

• The VAX floating point format lacks support for the IEEE special values (NaN, Infinity). Hence, their special meaning is lost when they are converted to VAX format and cannot be recovered.
• Differences in precision and range can also cause information to be lost in both directions.

Research Systems recommends using IEEE/VAX conversions only to read existing VAX format data, and strongly recommends that all new files be created using the IEEE format.

See for more information.