FSTAT Function

Reference Guide > F Routines > FSTAT Function

FSTAT Function

Returns an expression containing status information about a specified file unit.

Usage

result = FSTAT(unit)

Input Parameters

unit—The file unit (logical unit number) about which information is required.

Returned Value

result—A structure expression of type FSTAT containing status information about unit.

Keywords

None.

Discussion

FSTAT can be used to get more detailed information, as well as information that can be used from within a PV-WAVE program.

Example 1

To get detailed information about the standard input, enter the command:

INFO, /Structures, FSTAT(0)

This causes the following to be displayed on the screen:

** Structure FSTAT, 10 tags, 32 length:

UNIT	LONG	0
NAME	STRING	'<stdin>'
OPEN	BYTE	1
ISATTY	BYTE	1
READ	BYTE	1
WRITE	BYTE	0
TRANSFER_COUNT	LONG	0
CUR_PTR	LONG	8112
SIZE	LONG	10000
REC_LEN	LONG	0

The fields of the FSTAT structure provide the following information:

UNIT—The file unit number.

NAME—The name of the file.

OPEN—Nonzero if the file unit is open. If OPEN is 0, the remaining fields in FSTAT contain no useful information.

ISATTY—Nonzero if the file is actually a terminal instead of a normal file.

READ—Nonzero if the file is open for read access.

WRITE—Nonzero if the file is open for write access.

TRANSFER_COUNT—The number of scalar data items transferred in the last I/O operation on the unit. This is set by the following routines: READ, READF, READU, PRINT, PRINTF, and WRITEU. TRANSFER_COUNT is useful when you are attempting to recover from input/output errors.

CUR_PTR—The current position of the file pointer, given in bytes from the start of the file. If the device is a terminal (ISATTY is nonzero), the value of CUR_PTR will not contain useful information.

SIZE—The current length of the file, in bytes. If the device is a terminal (ISATTY is nonzero), the value of SIZE will not contain useful information.

Example 2

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 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, unit, file, /Get_Lun

   ; 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

; Create a file containing 10 floating-point values.

OPENW, unit, 'ten_floats.dat', /Get_Lun

WRITEU, unit, FINDGEN(10)+0.1

FREE_LUN, unit

; Read floating-point values from ten_floats.dat and show result.

a = read_data('ten_floats.dat')

INFO, a

; produces the following output:

; A                    FLOAT      =Array(10)