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; the variable is created if it did not previously exist.
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 a default of 1 MB (1048576) 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=any	Stop reading the record on a carriage-return only, line-feed only, or a carriage-return/line-feed pair sequence.
	/termchr=lf	Terminate the read when a line-feed is received; this changes the default of a carriage-return/line-feed pair (crlf). Useful for text files containing UNIX-style line endings, as commonly found on UNIX, Linux, and Mac OS X systems.
	/termchr=cr	Terminate the read when a carriage return is received; this changes the default of a carriage-return/line-feed pair (crlf). Useful for text files containing line endings as found on classic Macintosh systems (pre-OS X).
	/termchr=crlf	Terminate the read when a carriage-return/line-feed pair is received. When the /termchr option is not explicitly provided, this crlf setting is used by default. Useful for text files containing Windows/DOS-style line endings.
	/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. Use the GETPROPERTY to command to read smaller amounts of information used only within Robo-FTP scripts.

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 the /length value characters it returns an error and [ variable ] is set to an empty string. The /length option defaults to 1 MB (1048576) but may be set to any value your available memory allows.

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

The READFILE command may be used inside a loop to process every row in a file. The loop in the following example reads a text file that contains a list of named files that must each be uploaded to a remote server.

Note: There is a corresponding loop example on the Help topic page for the WRITEFILE command.