READ Instruction

READ( options ) arrays, variables, array elements

READ reads data into arrays and other variables. It supports free-format, Fortran-format, and binary-format data. By contrast, INPUT is strictly for free-format. READ will not work with data series—use the DATA instruction to read data into series. WRITE is the analogous instruction for outputting information.

Parameters

arrays,...

These are the objects for which data is to be read. You can use any combination of variables. You can use arrays of arrays, but any arrays must be dimensioned ahead of time (unless you use the option VARYING, or are reading from a MATLAB file).

Options

FORMAT=[FREE]/BINARY/CSV/DIF/MATLAB/PRN/TDF/WKS/XLS/XLSX/"( FORTRAN format )"

This tells READ the format of the data. See below for information on how the format option affects the way that READ fills arrays.

SHEET="worksheet name" [unused]

When reading an Excel file with multiple worksheets, you can use SHEET to identify which you want to read. READ reads the first by default.

UNIT=[DATA]/INPUT/other unit

RATS I/O unit supplying input.

VARYING/[NOVARYING]

STATUS=INTEGER variable set to 0,1 status

SINGLELINE/[NOSINGLELINE]

These are discussed under "Advanced Options" below.

TOP=top line to process [1]

BOTTOM=top line to process [last]

LEFT=leftmost column to process [1]

RIGHT=rightmost column to process [last]

You can use these if you want to ignore text above, below, to the left, or to the right of the data you want to read.

Description

The READ instruction reads information into the arrays and variables in the order listed. The manner in which arrays are read depends upon the FORMAT option.

•With FORMAT=FREE, READ is identical to INPUT except for the different default setting for the UNIT and SINGLELINE options. It reads RECTANGULAR arrays by rows, and SYMMETRIC or PACKED arrays by the rows of the lower triangle. It can read more than one row from a single line.

•With FORMAT=CSV, TDF, PRN, WKS, XLS, and XLSX, READ fills cells in the target variables based on the arrangement of the data on the file. If you don’t have enough values in a row, the remaining elements get missing value codes.

•With FORMAT=MATLAB, READ will read (and dimension) only full arrays which exist with the same name on the file.

•With FORMAT=BINARY, READ processes arrays in their internal order. RECTANGULAR arrays are read by columns, SYMMETRIC or PACKED by the rows of the lower triangle

•With a FORTRAN format, READ requires that each array and each row of an array begin on a new line. The format should be the format required to read a single row, not the whole array. As with FORMAT=FREE, it reads RECTANGULAR arrays by rows and SYMMETRIC or PACKED arrays by the rows of the lower triangle. A VECTOR is treated like a single row.

Notes

You should use FORMAT=BINARY only to read data written out of RATS using WRITE(FORMAT=BINARY). If the binary data are generated in some other fashion, it is possible that the byte streams won’t match and you will end up with gibberish.

Examples

declare symmetric d(3,3)

read(unit=input,format="(3f6.2)") d

10.00

-5.20 12.20

1.30 5.40 14.60

read(unit=input,format=free) d

10.0 -5.2 12.2 1.3 5.4 14.6

The two READ instructions put the same set of numbers into the SYMMETRIC array D. The first is an example of a formatted read: each row of data for the array appears on a separate line. The second creates the same matrix using the free format option.

declare rectangular a

open data arrayin.mat

read(format=matlab) a

This reads the array A from a MATLAB file. It will take its dimensions from the matrix A on the file.

Advanced Options

varying/[novarying]

status=INTEGER variable set to 0,1 status

singleline/[nosingleline]

The VARYING and STATUS options allow you to work with lists whose size you do not want to set in advance.

You can use VARYING to input data for a single VECTOR array of any numeric or character type. With VARYING, the VECTOR is filled with as much data as is available. By default, this is the entire contents of the data file. With SINGLELINE, it will read data only from a single line. (SINGLELINE will be ignored if you use FORMAT=BINARY).

If you use the option STATUS, READ does not give you an error if there is not enough data to fill all the variables. Instead it sets your STATUS variable to 0. If the READ is successful, it sets the status variable to 1.

Example with VARYING

dec vector[label] tickers

open data tickers.lst

read(varying) tickers

do i=1,%rows(tickers)

....

end do i

This reads labels from the file TICKERS.LST, then loops over the number of elements processed.