FSTAT Function

result = FSTAT(unit)

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

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

None.

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

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	0
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.

REC_LEN OpenVMS-specific record length, in bytes. This field is always zero under UNIX and Windows.

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:

FUNCTION read_data, file

; Read_data reads all the floating-point values from file and returns
; the result as a floating-point vector.

OPENR, /Get_Lun, unit, file

; Get a unique file unit and open the data file. 

status = FSTAT(unit)

; Retrieve the file status.

data = FLTARR(status.size / 4.0)

; 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.

READU, unit, data

; Read the data.

FREE_LUN, unit

; Deallocate the file unit and close the file.

RETURN, data

; Return the data.

END

; This is the end of the read_data function.

Assuming that a file named herc.dat exists and contains 10 floating-point values, the following statements:

a = read_data('herc.dat')

; Read floating-point values from herc.dat.

INFO, a

; Show the result.

will produce the following output:

See Also

CLOSE, FREE_LUN, GET_LUN, OPEN (UNIX/OpenVMS), OPEN (Windows), POINT_LUN

For more information, see Getting Information About Files in Chapter 8 of the PV-WAVE Programmer's Guide.

For background information, see Logical Unit Numbers (LUNs) in Chapter 8 of the PV-WAVE Programmer's Guide.