READFILE Read string from text file |
Top Previous Next |
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 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.
Consider the following examples:
;; "rewind" the file pointer READFILE
;; read the first record of a file READFILE "datafile.txt" first_record
;; read until a line-feed is found READFILE "datafile.txt" file_record /termchr=lf
;; read the third record of a file READFILE "datafile.txt" third_record /record=3
The next example combines multiple commands to retrieve the next-to-last record in a file:
READFILE ;; "rewind" the file pointer (to be safe) READFILE "datafile.txt" rec /record=last ;; count the records SETNUM NextToLast = %recordcount - 1 READFILE "datafile.txt" rec /record=NextToLast ;; finally got it!
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.
FTPLOGON "partner.business.com" /user="MyUserID" /pw="secret" READFILE ;; "rewind" the file pointer (fail-safe) :begin READFILE "c:\automatic\UploadList.dat" rec /record=next IFERROR GOTO done ;; break out of loop when no more files in list SENDFILE rec ;; upload file GOTO begin ;; loop back to get next file name :done FTPLOGOFF DELETE "c:\automatic\UploadList.dat"
Note: There is a corresponding loop example on the Help topic page for the WRITEFILE command.
Related command(s): WRITEFILE, WORKINGDIR, COPY, RENAME, DELETE, APPEND |