See Also: File I/O Commands, Direct_Input, Readln, Read_Block, Set_Channel_Position, SeqEOF, SeqEOL, Write, UCharArrayToString, Channel command component, Sequential File I/O
To read a line of data from a sequential file, device, text field, or image, and move its "words" into one or more variables.
ReadLn [Channel {channelNum}] {variable} […{variable}]
channel channelNum
Input channel to read data from. If omitted, the channel will be that specified in the last executed Direct_Input, Read, Read_Block, or ReadLn command in which channel was specified or implied.
Variable
Optional, 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.
If no argument is passed, the current line is read and "discarded", the position in the current input channel is advanced to the next line.
If one variable is passed, the entire line is read into that variable.
If multiple variables are passed, one "word" is read into each variable until the last variable, which will hold the entire remainder of the line.
The last variable passed to ReadLn is treated differently from the preceding variables, since it may contain more than one "word". Data placed into all variables preceding the last variable is handled using the Read command. Data placed into the last variable is handled by the ReadLn command itself, which does not strip embedding or delimiting characters.
Readln reads data from the input file or device named in the most recently executed Direct_Input command. The first ReadLn command in the program reads data from the first line of the input file or device until it finds an end of line character. Then it moves the data to variable (if at least one variable was passed). If there is more than one variable, ReadLn will perform an internal read command on the portion of the data read in which precedes the first embedded comma (,) in the data and move it to the first variable, and the remainder into the next, and so on until there are no more commas in the remaining data, or the variables are exhausted.
Readln sets Predefined Indicator SeqEOL false every time it is executed, and Predefined Indicator SeqEOF true when the end of the file is reached.
For the following example, assume file infile.txt has two lines, as follows:
One, "Dos" , "Trois"
Four, "Cinco", "Six"
String s1 s2 s3 s4
Number n1 n2 n3
Direct_Input "infile.txt"
Readln s1 s2 s3
The ReadLn command would read One into String Variable s1, Dos into Variable s2, and "Trois" into Variable s3. The spaces around Dos would be discarded, since ReadLn executed a read command on it, but the quotation mark which began the third value ("Trois") would not be stripped, because ReadLn itself does not strip embedding or delimiting characters.
Readln reads all of the remainder of the input line into its last variable, regardless of delimiting characters which might be in that remainder, and it strips only the end of line character from the data, not delimiters or embedded characters. When the last variable has been read into, execution proceeds to the next command. See the read command for a complete discussion of delimiting, embedding, and discard characters.
If a tab character (ASCII 9) is processed through the last variable of a ReadLn command, it will be replaced with the number of spaces required to pad the string to a length which is a multiple of 8 (the standard tab function). Thus, if the input line were <tab>A, the command ReadLn var would produce output of 8 spaces followed by an A. If the input line were B<tab>A, the output would be B followed by 7 spaces followed by an A. This replacement does not occur for variables preceding the last one, since they are processed internally by the read command. If the file is opened in BINARY: mode the tab replacement does not take place.
If an end-of-line is encountered before the variables are exhausted, the remaining variables are filled with blank ("") if they are of type String or zero if they are of type Date or a numeric data type, and execution proceeds to the next command. When the number of variables exceeds the number of delimited items on the line in this manner, delimiters and embedded characters are stripped from the contents of all variables, because they were all read in internally by the read command. The first variable after the last delimited item discards the end-of-line character in the input data. A dummy variable may be provided for this purpose.
For the following example, assume file infile.txt has two lines, as follows:
One, "Dos" , "Trois"
Four, "Cinco", "Six"
String s1 s2 s3 s4
Number n1 n2 n3
Direct_Input "infile.txt"
Readln s1 s2 s3 s4
In this example, String Variable s1 would contain One, s2 would contain Dos, s3 would contain Trois, and s4, having discarded the end of line character, would be blank.
Successive ReadLn commands pick up where the previous ReadLn command left off, that is, on the next line of data.
Readln 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 ReadLn command.
Assume the first ReadLn command above were replaced by a command which referred to the numbers declared in the program:
Readln n1 n2 n3
This command would generate three DataFlex errors, since the data does not qualify for Type Number.
A very common use of ReadLn is to read a comma-separated values (CSV) file.
For the following example demonstrates how to read a CSV file containing customer data.
Procedure ReadCustomerCSVFile
String sCustomerName sVoid
Integer iCustId
Number nPurchases nBalance
Direct_Input "CustomerData.Csv"
Repeat
Readln iCustId sCustomerName nPurchases nBalance
If (iCustId > 0) Begin
// process data
End
Until (SeqEOF)
Close_Input
End_Procedure
Send ReadCustomerCSVFile
Another very common use of ReadLn is to read files and subfolders of a disk folder.
For the following example demonstrates how to read a files and folders from a disk folder. After each loop iteration, sLine will contains either a file or subfolder name. Subfolder names are enclosed in [ and ] characters. For example "[SubFolderName]".
Procedure ReadDiskFolder String sFolder
String sLine
Direct_Input ("dir: " + sFolder)
Repeat
Readln sLine
Showln sLine
Until (SeqEof)
Send Info_Box "Done"
End_Procedure
String sFolder
Move "C:\MyProject\Data" to sFolder
Send ReadDiskFolder sFolder
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.
The point in a file at which reading is done can also be changed by use of the Set_Channel_Position command.
If there is no data on the input line a blank or zero will be returned in variable, as appropriate.
Because
ReadLn executes internal read commands whenever it is executed with
more than one argument, the result of this line of code:
Readln s1 s2 s3
is exactly the same as the result of this line of code:
Read s1 s2
Readln s3
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 string variables. The use of global variables is discouraged for this and other reasons.
When the dir: driver is used with a Direct_Input command to read an operating system folder, ReadLn should be used to bring one line (file or subfolder) of the folder into the program.
The input file or device must be opened with the Direct_Input command prior to using ReadLn.
You can use Read_Block to read an entire file into a UChar[].