Miscellaneous File Management Tasks
This section describes utility commands that have been provided to simplify your interaction with data files. It also describes the FSTAT command, which is a valuable source of information about open files.
Locating Files
The FINDFILE function returns an array of strings containing the names of all files that match its parameter list. The parameter list may contain any wildcard characters understood by your system. For example, to determine the number of procedure files that exist in the current directory:
PRINT, '# PV‑WAVE.pro files:', N_ELEMENTS(FINDFILE('*.pro'))Flushing File Units
To increase efficiency, PV-WAVE buffers its I/O in memory. This means that when data is output, there is a brief interval of time during which data is in memory, but has not actually been placed into the file. Normally, this behavior is transparent to the PV-WAVE user (except for the improved performance).
The FLUSH routine exists for those rare occasions where a program needs to be certain that the data has actually been written to the file immediately. For example, to flush file unit 1:
FLUSH, 1
Positioning File Pointers
Each open file unit has a file pointer associated with it. This file pointer indicates the position at which the next I/O operation will take place.
The POINT_LUN procedure allows the file pointer to be positioned arbitrarily. The file position is specified as the number of bytes from the start of the file. The first position in the file is position 0 (zero).
note | Large File versions of POINT_LUN and FSTAT are also available on 32-bit systems where Large Files are supported. Large Files are files greater then 231 Bytes in length. LFPOINT_LUN and LFSTAT are identical in function to POINT_LUN and FSTAT, but some argument and return types were changed to accomodate larger values. |
The following statement rewinds file unit 1 to its beginning:
POINT_LUN, 1, 0
while the following sequence of statements will position it at the end of the file:
tmp = FSTAT(1)
POINT_LUN, 1, tmp.size
note | Moving the file pointer to a position beyond the current end-of-file causes a UNIX file to grow by that amount. (This is the standard UNIX practice.) |
Testing for End-of-File
The EOF function is used to test a file unit to see if it is currently positioned at the end of the file. EOF returns true (1) if the end-of-file condition is true, and false (0) otherwise. For example, to read the contents of a file and print it on the screen:
; Open file demo.doc for reading.
OPENR, 1, 'demo.doc'
; Create a variable of type string.
line = ''
; Read and print each line, until the end of file is encountered.
WHILE (not EOF(1)) DO BEGIN READF, 1, line & $
PRINT, line & END
; Done with the file.
CLOSE, 1
Getting Information About Files
Using the INFO Procedure
Information about currently open file units is available by using the Files keyword with the INFO procedure. If no parameters are provided, information about all currently open user file units (units 1-128) is given. For example, to get information about the three special units (–2, –1, and 0), the command:
INFO, /Files, -2, -1, 0
causes the following to be displayed on the screen if you are running PV-WAVE in a UNIX environment:
Unit Attributes Name
-2 Write, Truncate, Tty, Reserved <stderr>
-1 Write, Truncate, Tty, Reserved <stdout>
0 Read, Tty, Reserved <stdin>
or causes the following to be displayed on the screen if you are running under Windows:
Unit Attributes Name
-2 Write, Truncate, Tty, Reserved <stderr>
-1 Write, Truncate, Tty, Reserved <stdout>
0 Read, Tty, Reserved <stdin>
For more information about the INFO command, refer to
Chapter 13: Getting Session Information.
Use the Information from FSTAT
FSTAT is a structure that contains details about all currently allocated LUNs. You can use the FSTAT function to get more detailed information, including information that can be used from within a PV-WAVE program. It returns an expression of type structure with a name of FSTAT containing information about the file. For example, to get detailed information about the standard input, the command:
INFO, /Structures, FSTAT(0)
causes the following to be displayed on the screen:
** Structure FSTAT, 10 tags, 32 length:
Since PV-WAVE allows keywords to be abbreviated to the shortest non-ambiguous number of characters,
INFO, /St, FSTAT(0)
will also work (and save some typing). The fields of the FSTAT structure are defined as part of its description in the PV‑WAVE Reference.
Sample Usage—FSTAT Function
The following function can be used to read single-precision floating point data from a file into a vector when the number of elements in the file is not known. This function uses FSTAT to get the size of the file in bytes and then divides by 4 (the size of a single-precision floating-point value) to determine the number of values:
; Read_data reads all the floating-point values from file and
; returns the result as a floating-point vector.
FUNCTION read_data, file
; Get a unique file unit and open the data file.
OPENR, /Get_Lun, unit, file
; Retrieve the file status.
status = FSTAT(unit)
; Make an array to hold the input data. The size tag of status
; gives the number of bytes in the file and single-precision
; floating-point values are four bytes each.
data = FLTARR(status.size / 4.0)
; Read the data.
READU, unit, data
; Deallocate the file unit and close the file.
FREE_LUN, unit
; Return the data.
RETURN, data
END
Assuming that a file named herc.dat exists and contains 10 floating-point values, the following statements:
; Read floating-point values from herc.dat.
a = read_data('herc.dat'); Show the result.
INFO, a
will produce the following output:
A FLOAT = Array(10)
Getting Input from the Keyboard
The GET_KBRD function returns the next character available from the standard input (file unit 0) as a single character string. It takes a single parameter named Wait. If Wait is zero, GET_KBRD returns the null string if there are no characters in the terminal typeahead buffer. If Wait is nonzero, the function waits for a character to be typed before returning.
Sample Usage—GET_KBRD Function
A procedure that updates the screen and exits when <Return> is typed might appear as:
; Procedure definition.
PRO UPDATE, ...
; Loop forever, updating the screen as needed.
WHILE 1 DO BEGIN
; Read character, no wait.
CASE GET_KBRD(0) OF
'' : .... ; Process letter A.
'' : .... ; Process letter B.
... ; Process other alternatives.
STRING("15B): RETURN
; Exit if <Return> is detected (ASCII code = 15 octal).
ELSE:
; Ignore all other characters.
ENDCASE
ENDWHILE
END
