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 255 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.
	/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.

Under control of command options, reads of character strings not bounded by carriage-return/line-feeds are possible. For example, records of fixed lengths can be read by using the /length=xx and /termchr=none options.

In a READFILE command where /termchr=none and /termseq="xx" are defined, the command returns an error if the specified terminating string is not located within /length number of characters (if specified) or within the default of 255 characters. An empty string is also returned. This provides an easy way to determine if the desired terminating sequence is present or not. 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 all 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 must end with this pattern.

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, omit the /record=next option, or specify /record=1.

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.