Read

Purpose

To read "words" of data from a sequential file, device, or text field and move them to one or more variables.

Syntax

Read [Channel {channel-num}] {variable} […] {variable}

Parameters

Channel:
channelNum - Input channel to read data from. If omitted, the channel will be that specified in the most recently executed Direct_Input, read, read_block, or readln command in which channel was specified or implied.
Variable:
The first variable is required, may be of any type except Indicator, and cannot be a constant. Additional variables may be on the command line, separated by spaces, without limit.

What It Does

The Read command reads data from the input file or device named in the most recently executed Direct_Input command. The first Read command in the program reads data from the first line of the input file or device until it finds a comma or end of line character. Then it moves the data to the variable. If the end character was a comma and there is another variable, data will be read into the next variable until the next comma or end of line.

Example

For the following examples, assume the file infile.txt has two lines, as follows:

One, Dos , "Trois", "Vier ", 'Cinque'
Six, Siete , "Huit", "Neun ", 'Dieci'

String s1 s2 s3 s4 s5 s6
Number n1 n2 n3 n4 n5 n6
Direct_Input "infile.txt"
Read s1 s2

The Read command would read One into String Variable s1, and Dos (followed by two spaces) into Variable s2. The leading space before Dos would be discarded.

When the last variable has been read into, execution proceeds to the next command, even if unread data remains on the current line. If an end of line is encountered before the variables are exhausted, the remaining variables are made blank if they are of type String or zero if they are of type Date or Number, and execution proceeds to the next command.

Successive Read commands pick up where the previous Read command left off, until an end of line character is encountered. To read past an end of line character in a data file, you must use a readln command. When an end of line character is encountered, Predefined Indicator seqeol is set true. When an end of file character is encountered, Predefined Indicator seqeof is set true.

Assume the Read command in the program above were followed by this command:

Read s3 s4 s5 s6

This command would read Trois into s3, Vier (followed by a space) into s4, and Cinque into s5. The embedding characters (" and ') would be discarded. s6 would be blank, even if it had data in it previously, because an end of line character comes after Cinque. Any further Read commands would read nothing until a readln command was executed.

The point in a file at which reading is done can also be changed by use of the set_channel_position command.

Read uses commas to divide sequential data into variables, and it discards leading spaces and tabs unless they are embedded in quotation marks. It ignores commas embedded between single or double quotation marks as field separators and instead treats them as part of the data. The comma is referred to as the "delimiter" character since it separates the variables on the input line. The quotation marks are referred to as "embedding" characters. Embedding characters and delimiters are discarded from read data.

Read checks read data for the types of the destination variables and truncates any items which exceed the declared length of String variables. Different types of variables may be intermixed in the same Read command.

Assume the first Read command above were replaced by a command which referred to the Numbers declared in the program:

Read n1 n2 n3

This command would generate three DataFlex errors, since the data does not qualify for Type Number.

Notes

It is highly recommended to always use the channel feature when doing any sequential I/O, thus making your code more reusable and ready for use with multiple I/O channels if the need arises.
To delimit data which itself contains quotation marks, use single quotation marks, or apostrophes (') to delimit the item. Use double quotation marks (") to embed single quotation marks.
```
'The Hungry "i"', "Johnny's Bar"
```
The quotation marks around "i" will be passed as data, not treated as embedding characters, since they are themselves embedded in single quotation marks ('). The apostrophe (') in Johnny's will not be treated as an embedding character because it is enclosed in double quotation marks. Embedding characters may be intermixed in the same file and line in this manner.
The DataFlex READ command always expects a comma to be the value terminator. This means that if you want to use the READ command, your data should contain a dot as decimal separator and the DF_DECIMAL_SEPARATOR should be set to Ascii (".") before reading the data. Thousand separators should not be present in CSV files.
Unwanted items in a source file may be discarded by reading them to a "discard" variable, which must be established before the Read command.
```
string sKeep1 sKeep2 sDiscard
read sDiscard sDiscard sDiscard sKeep1 sDiscard sKeep2
```
This command would move the first three data items to String Variable sDiscard, the fourth to Variable sKeep1, the fifth to sDiscard, and the sixth to sKeep2.
For data files which contain end of line characters, the readln command is required to discard the end of line characters and enable Read commands to read beyond the first line. For such files, always follow Read or a series of Reads with a readln.
```
Repeat
    Read sVariable
    Send ProcessVariable sVariable
    If (SeqEOL)
        Readln
Until (SeqEOF)
```
In this example, the Read sVariable and processing statements are executed continuously until Predefined Indicator seqeof is true. When the end of a line is read, Predefined Indicator seqeol is set true, and the readln command is executed, discarding the end of line character and enabling the read loop to continue executing.
Read and readln cannot be used on global strings longer than 255 characters unbroken by delimiters (comma, and/or end of line characters). Such strings must be dealt with by the read_block command or with local strings. The use of global variables is discouraged for this and other reasons.
The input file or device must be opened with the Direct_Input command prior to using Read.
You can use Read Block to read an entire file into a UChar.