READFILE - Read string from text file

Syntax:	READFILE	[ file name ] [ variable ] [ /options ]
Arguments:	[ file name ]	A variable or string to specify the file name to read; if no Path is defined Robo-FTP’s working folder is used.
	[ variable ]	A variable to store characters read from the file; if the variable does not previously exist, it is created.
Options:	/allowall	Do not strip unprintable characters; these characters are replaced with a space character.
	/length=xx	Maximum number of characters to read; if not specified the maximum of 4096 characters is used.
	/record=xx	The specific record number to read; records are delimited by carriage-return/line-feed pairs.
	/record=next	Read the next sequential record; records are delimited by carriage-return/line-feed pairs.
	/record=last	Read the last record in the file and set the value of the %recordcount internal variable.
	/termchr=lf	Terminate the read when a line-feed is received; this changes the default of a carriage-return terminating character.
	/termchr=none	Do not use either a line-feed or carriage-return as a read terminating character; any unprintable characters read are replaced by a space character.
	/termseq="xxx"	Terminate the read when the specified termination sequence is read.

This script command reads characters from a specified text file. This command is oriented toward reading complete records of printable characters from a file with each record terminated by a carriage-return/line-feed (CR/LF). The carriage-return/line-feed are not returned in the [ variable ] string.

The scope of this command (and the WRITEFILE command) is not to provide full function file I/O to your script files but rather to provide temporary storage for small amounts of information for use by a script file or an external program.

Each read is bound by one of the following: a terminating character, a terminating sequence (/termseq) or the end of the file. If READFILE does not find any of these boundary conditions after 4096 characters it returns an error and [ variable ] is set to an empty string. The /length option may be used to specify a maximum read attempt length less than 4096 characters.

Fixed length records that are not bound by carriage-return/line-feed can be read by using the /length=xx and /termchr=none options.

The record number used in association with the /record=next option is only incremented when there is a match if found and the read completes successfully.

When the /record=xx option is used to read beyond the first record of the file, keep in mind the terminating options in the READFILE command apply to subsequent records. Record numbering begins at one. For example, if you are using the /termseq="end" option to stop reading when the string end is read, all records, except the last, must end with this pattern. If the file contains any data between the last record terminating sequence and the end of the file then that data is the last record in the file.

The /record=next option allows a file to be read sequentially as long as the specified file name is constant - namely, only one file can be read at a time using this option.

To rewind a file (or resume reading from the first record), issue the READFILE command without any arguments (returns no data), specify a different file name or specify /record=1.

The /record=last option reads the last row and sets the value of the %recordcount internal variable to the total number of records in the file. If you use this option, don't forget to rewind before attempting additional reads from the current input file.

Robo-FTP removes any unprintable characters read before they are saved in the specified variable. If the loss of unprintable characters alters the resulting string in an undesirable way by altering character position, for example, you may use the /allowall option. When this option is used, the relative character position of the string is preserved by replacing the unprintable characters with a space character. The fill character defaults to a space.

The next example combines multiple commands to retrieve the next-to-last record in a file:

SETNUM NextToLast = %recordcount - 1
READFILE ;; rewind since the count moved it to the end