READ Procedures

Reads input into variables:

READ reads ASCII (formatted) input from the standard input stream (file unit 0).

READF reads ASCII input from a specified file.

READU reads binary (unformatted) input from a specified file. (No processing of any kind is done to the data.)

READU_32 reads a long data type as a 4-byte value from the given input stream. It is useful in reading 32-bit Longs on a 64-bit system. In addition, it can be used to read any other PV-WAVE data types.

For READU_32 the number of variables that can be read from a file is limited to 20.

READU_32 cannot read structures from a binary file. To read a structure, you must read them elementwise.

To read 32-bit integer values from a binary file in 64-bit PV-WAVE, we recommend using the INT32 bit data type and the READU routine instead of READU_32.

Usage

READ, var1, ... , varn 
READF, unit, var1, ... , varn 
READU, unit, var1, ... , varn 
READU_32, unit, var1, ... , var20

Input Parameters

unit—The file unit from which the input will be taken.

vari—The named variables to receive the input.

Keywords

Format—(READ and READF only). Lets you specify the format of the input in precise detail, using a FORTRAN-style specification. FORTRAN-style formats are described in the PV‑WAVE Programmer’s Guide.

If Format keyword is not present, PV‑WAVE uses default rules for formatting the output. These are described in the PV‑WAVE Programmer’s Guide.

Reading binary XDR data into a PV-WAVE LONG variable in PV-WAVE 64-bit causes 8 bytes to be extracted from the XDR file. In order to read 4 byte values from a binary XDR file, you must pass the READ routine a PV-WAVE INT32 variable.

Endian—(READU_32) This keyword is required when using READU_32 and specifies the endianness of the input file. The Endian keyword can have the following values:

0—File was created on a big endian machine.

1—File was created on a little endian machine.

Discussion

When writing a PV-WAVE structure to a binary file, the Writ strips out any alignment padding that may exist in memory between structure elements. The READ routines expect this and place each structure element at the appropriate memory location when the file is read into a PV-WAVE structure. However, when you write a C structure to a binary file as a single unit it may contain padding that does not match what the PV-WAVE READ routines expect. To avoid problems, you can either add dummy elements to the PV-WAVE structure you send to the READ routine or, more easily, write out the C structure one element at a time, thus eliminating any padding between elements.

READ and READF Procedures—If the Format keyword is not present and READ is called with more than one parameter, and the first parameter is a scalar string starting with the characters '$(', this initial parameter is taken to be the format specification, just as if it had been specified via the Format keyword. This feature is maintained for compatibility with Version 1 of PV-WAVE.

READU Procedure—For nonstring variables, the number of bytes required for vari is input. For string variables, PV-WAVE reads exactly the number of bytes contained in the existing string.

Example 1

This example reads a string from the standard input stream using the READ procedure. The value of the string is then displayed.

; Define a variable with string type.
b = ' '
; Read a string from the terminal and display the contents of b.
READ, 'Enter a string: ', b
; PV-WAVE prints:
; Enter a string: 
; Enter the following string: This is a string.
PRINT, b
; PV-WAVE prints: This is a string.

Example 2

In this example, three integers are read from the standard input stream into a three-element integer array, nums, using READ. A file named readex.dat is then opened for writing, and the integers in nums are written to the file using PRINTF. The file is then closed. The Format keyword is used with PRINTF to specify the format of the integers in the file. The readex.dat file is then opened for reading, and the integers are read into a three-element integer array using READF with the Format keyword. The file is then closed and the values that were read from readex.dat are displayed.

; Create a three-element integer array.
nums = INTARR(3)
READ, 'Enter 3 integers: ', nums
; Read three integers from the standard input stream.
; Enter 3 integers: 3 5 7
PRINT, nums
; PV-WAVE prints: 3       5       7
; Open the readex.dat file for writing.
OPENW, unit, 'readex.dat', /Get_Lun
; Write the integers to the file using a specified format.
PRINTF, unit, nums, Format = '(3i1)'
; Close the file and free the file unit number.
FREE_LUN, unit
; Open the readex.dat file for reading.
OPENR, unit, 'readex.dat', /Get_Lun
; Create a new three-element integer array.
ints = INTARR(3)
; Read the three integers from the readex.dat file using the
; same specified format as when they were written.
READF, unit, ints, Format = '(3i1)'
; Display the integers read from the file.
PRINT, ints
; PV-WAVE prints: 3       5       7
FREE_LUN, unit

Example 3

In this example, READU is used to read an image of a galaxy from the file
whirlpool.img, which is contained in the subdirectory data under the main PV-WAVE distribution directory.

; Open the file whirlpoo.img for reading.
OPENR, unit, FILEPATH('whirlpool.img', Subdir='data'), /Get_Lun
; Create a byte array large enough to hold the galaxy image.
a = BYTARR(512, 512)
; Read the image data.
READU, unit, a
FREE_LUN, unit

Example 4

The data file used in this example is a binary file that was created by 32-bit PV-WAVE on a big-endian system. This file contains a 32-bit integer, a single-precision floating point, and a double-precision floating point value.

; Open the data file.
OPENR, unit, !Data_dir + '/big_endian_data.dat', /Get_lun
; Define the variables. Note, the variable for the integer
; value is defined as a LONG, which is a 32-bit integer in
; 32-bit PV-WAVE and a 64-bit integer in 64-bit PV-WAVE.
a = 0L
b = 0.0
c = 0.0D
; Read the file using READU_32.
READU_32, unit, Endian=0, a, b, c
FREE_LUN, unit
INFO, a, b, c
; Use the IS_LITTLEENDIAN() routine to determine
; if the system is a little endian system.
; If it is, reverse the byte order of each variable.
IF IS_LITTLEENDIAN() EQ 1 THEN BYTESWAP, a 
IF IS_LITTLEENDIAN() EQ 1 THEN BYTESWAP, b
IF IS_LITTLEENDIAN() EQ 1 THEN BYTESWAP, c
INFO, a, b, c
; PV-WAVE prints:
; A        LONG      =    12345
; B        FLOAT     =    13.4500
; C        DOUBLE    =    98.760000

Example 5

The data file used in this example is a binary file that was created by 32-bit PV-WAVE on a big-endian system. This file contains a 32-bit integer, a single-precision floating point, and a double-precision floating point value.

; Open the data file.
OPENR, unit, !Data_dir + '/big_endian_data.dat', /Get_lun
; Define the vaiables. Note, the variable for the integer
; value is defined as INT32, a 32-bit integer.
a = INT32(0)
b = 0.0
c = 0.0D
; Read the file.
READU, unit, a, b, c
FREE_LUN, unit
INFO, a, b, c
; Use the IS_LITTLEENDIAN() routine to determine
; if the system is a little endian system.
; If it is, reverse the byte order of each variable.
IF IS_LITTLEENDIAN() EQ 1 THEN BYTESWAP, a
IF IS_LITTLEENDIAN() EQ 1 THEN BYTESWAP, b
IF IS_LITTLEENDIAN() EQ 1 THEN BYTESWAP, c
INFO, a, b, c
; PV-WAVE prints:
; A        INT32     =    12345
; B        FLOAT     =    13.4500
; C        DOUBLE    =    98.760000

See Also

GET_LUN, OPEN (Unix), OPEN (Windows)

For more information and examples, see the READU and WRITEU topics in the PV‑WAVE Programmer’s Guide.

For more information on format specification codes, see the PV‑WAVE Programmer’s Guide.