Read

READ

read { #|% <i> {,}} { <varlist> | l<svar> |
(l)<svar> | h<svar>| (h)<svar>}

read db {, <varlist> | l<svar> | (l),svar>|
h<svar>| (h)<svar>}

Function

Read data from a current input data file, or from an external program via a weasel.

Read data from a current opened database. The command READ DB works only if a SQL database has previously been opened, using the command DB. Readable data are produced by SQL commands that return information extracted from tables. For example a SQL "select" statement over a table puts data on the DB channel, which can be read by READ DB.

The length of a DAT file extends to 256 characters.

Parameters

#<i>	An indication of the logical unit on which the data file is already open. Up to 10 may be open for input at once. If this parameter is omitted, then input logical unit 1 is assumed.

%<i>	Data is to be read from a weasel rather than a data file. Up to 5 weasels may be active at the same time.

varlist	A list of selected variables, the values of which are to be read from the data file or weasel or database

l<svar> l)<svar>	Implies that the whole of the next line of the data file or weasel is to be read into string variable <svar>. The second form should be used to avoid ambiguities if using a string variable the name of which name begins with 'L' is to be used. If the line being read is longer than 132 characters then the next logical variable is used to hold the excess characters. (see notes below)
h<svar> or (h)<svar>	Implies that the whole of the next line of the data file or weasel is to be read into string variable <svar> even if the line begins with #. The second form should be used to avoid ambiguities if a string variable whose name begins with 'H' is to be used.
db	Skip one line of the data, i.e. read nothing.
	With no parameters (other than the logical unit) skip one line of the data file or weasel, i.e. read nothing.

Examples

read p1,my_string,v10\20,new_point,s15

read #2, l10

read #2, lmy_string

read %1, l15

read %1, lmy_string

read

# get the address of a client from the database
string surname, address
db database customers
db separator "'"
label 1
surname=''
ask 'give surname of client':surname
if surname='': db exit;exit
db select address from clients where \
lname = "^surname"
read db,address
eof db: tell 'client not found.'
else tell 'address: ^address'
goto 1

Notes

Unless the H parameter is used, a line beginning with # will be ignored by the read. The use of the forms (L) and (H), as opposed to L and H, is always recommended even if no ambiguity is present.

Consecutive fields within the data file or weasel may be separated by spaces and/or a comma.
String variable fields may appear within single quotes.

If there are more variables in "varlist" than there are values on an input line, then the remaining variables will be read from the next input line. This wraparound feature can be suppressed by the WRAPAROUND command. Each READ command will always start reading from the next new line in the data file or weasel.

The end-of-file indicator will be set when an attempt is made to read beyond the end of a file. This may be tested for by the EOF command. The error flag will also be set.

Weaselling may not be available at all installations. When reading from a weasel, a data line beginning with | (concatenation) will be executed as an inline modelling command. Database communication may not be available at all installations.

If you need a READ DB to return NULL when strings filled with all-blanks are returned then there is an environment variable called PATCH4244 to implement this behaviour. Refer to the Patches section of configuration for the details of this option.

When reading a line longer than 132 characters, the “next” variable is filled with the excess characters. This means that if a command like READ #1,(L)S1 is issued and the line is longer than 132 characters then S2 variable will also be filled. This behaviour introduced in V12.5.3 is active by default and is also driven by an environment variable. When setting the variable PATCH4473=no the newly defined behaviour is not active. The default is PATCH4473=yes