File Functions

General

Files can be referenced as a string containing the name of the file ie "TEST.DAT" or the file handle that is returned from OPEN function. (Normally the second way if prefered when you want to open 2 or more files with the same name).
There are always 5 (3) special files for MSDOS (UNIX):

Handle	FileName	Description
0	<STDIN>	Standard input
1	<STDOUT>	Standard output
2	<STDERR>	Standard error
3	<STDAUX>	Standard auxiliary file, ie COM1:
4	<STDPRN>	Standard printer file, ie LPT1:

All open files are closed at the end of the program from REXX interpreter except in the case of an error.

CHARIN( [stream[,[start][,[length]]]] )

reads length bytes (default=1) from stream (default="<STDIN>") starting at position start

ch = charin("new.dat")	/* read one byte */
ch = charin("new.dat",3,2)	/* read two bytes from position in file 3 */

CHAROUT( [stream[,[string][,[start]]]] )

write string to stream (default="<STDOUT>") starting at position start

CALL charout "new.dat","hello"	/* writes "hello" to file */
CALL charout "new.dat","hi",2)	/* writes "hi" at position 2 */

CHARS( [stream] )

returns the number of characters remaining in stream.

CHARS("new.dat")

/* maybe 100 */

CLOSE( file )

closes an opened file. file may be string or the handle number

CALL close 'new.dat'	/* these two cmds are exactly the same */
CALL close hnd	/* where hnd=open('new.dat','w') */

EOF( file )

returns 1 at eof, -1 when file is not opened, 0 otherwise

DO	UNTIL eof(hnd)=1
	SAY read(hnd)	/* type file */
END

FLUSH( file )

flush file stream to disk

CALL flush 'new.dat'

LINEIN( [stream[,[start][,[lines]]]] )

reads lines lines (default=1) from stream (default="<STDIN>") starting at line position start

line = linein("new.dat")	/* read one line */
line = linein("new.dat",3,2)	/* read two lines from new.dat starting at line 3 */

LINEOUT( [stream[,[string][,[start]]]] )

write string with newline appended at the end to stream (default="<STDOUT>") starting at line position start

CALL lineout "new.dat","hello"	/* writes line "hello" to file */
CALL lineout "new.dat","hi",2)	/* writes line "hi" at line position 2 */

LINES( [stream] )

returns the number of lines remaining in stream. start

LINES("new.dat")

/* maybe 10 */

OPEN( file, mode )

opens a file. mode follows C prototypes:

"r"	for read	"w"	for write
"t"	for text,	"b"	for binary
"a"	for append	"+"	for read/write

and returns the handle number for that file. -1 if file is not found!
For Windows CE, one can open a serial port COMx and select the communication settings by using a filename with the following syntax: "COMn:baudspeed,bitlength,parity,stopbits,bufferlength". where baudspeed can take the values 300,600,1200,2400,...,115200 bitlength=7|8, parity=N|E|O|M, stopbits=1|2, bufferlength default is 128.

hnd	= open('new.dat','w')
IF	hnd = -1 THEN DO
	SAY 'Error: opening file "new.dat".'
	...
END
irda = open('com3:115200,8,N,1,128','rw')

READ( [file][,<length | "Char" | "Line" | "File">])

reads one line from file. If the second argument exists and it is a number it reads length bytes from file otherwise reads a Char, Line or the entire File. If file is not opened, it will be opened automatically in "r" mode. If file is ommited, it is assumed to be <STDIN>

kbdin = READ()	/* reads one line from stdin */
keypressed = read(,1)	/* -//- char -//- */
linein = read('new.dat')	/* reads one line from file */
linein = read(hnd)	/* -//- */
ch = read('new.dat',"C")	/* if file 'data' is not opened
	then it will be opened in "r" mode */
CALL write "new",read("old","F")	/* copy file */

SEEK( file [,offset [,<"TOF" | "CUR" | "EOF">]])

move file pointer to offset relative from TOF Top Of File (default), CUR Current position, EOF End Of File and return new file pointer. This is an easy way to determine the filesize, by seeking at the end,

filesize = seek(file,0,"EOF")	/* return file size */
CALL seek 'data',0,"TOF"	/* sets the pointer to the start of the file */
filepos = seek('data',-5,"CUR")	/* moves pointer 5 bytes backwards */

STREAM( stream[,[option][,command]] )

STREAM returns a description of the state, or the result of an operation upon the stream named by the first argument.
option can be "Command", "Description", "Status"
When option is "Command" the third argument must exist and can take on of the following values:

READ	open in read-only mode ASCII
READBINARY	open in read-only mode BINARY
WRITE	open in write-only mode ASCII
WRITEBINARY	open in write-only mode BINARY
APPEND	open in read/write-append mode ASCII
APPENDBINARY	open in read/write-append mode BINARY
UPDATE	open in read/write mode (file must exist) ASCII
UPDATEBINARY	open in read/write mode BINARY
CREATE	open in read/write mode ASCII
CREATEBINARY	open in read/write mode BINARY
CLOSE	closes the file
FLUSH	flush the contents of the file
RESET	set the pointer to Top Of File

When option is "Status", STREAM returns the current status of the stream can be on of the followings:
"READY", "ERROR", "UNKNOWN"
When option is "Description", STREAM returns a description of the last error.

CALL stream "new.dat","C","WRITE"

CALL stream "new.dat","C","CLOSE"

CALL stream "new.dat","S"

WRITE( [file][, string[,newline]])

writes the string to file. returns the number of bytes written. If string doesn't exist WRITE will write a newline to file. If a third argument exists a newline will be added at the end of the string. If file is not opened, it will be opened automatically with "w" mode. If file is ommited, it is assumed to be <STDOUT>

CALL write 'data','First line',nl;
CALL write ,'a'	/* writes 'a' to stdout */
CALL write '','one line',nl	/* write 'one line' to stdout */
CALL write 'output.dat','blah blah'	/* writes 'blah blah' to 'output.dat' file*/