Dear user of, we will have a scheduled downtime for FTP

at July, 22nd from 7am approx. till 4pm

BREXX, File Functions
Previous Top Index Next

File Functions


There are two sets of I/O functions, the REXX-STEAM functions and the BREXX I/O routines.

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 */

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')
IFhnd = -1 THEN DO
SAY 'Error: opening file "new.dat".'
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:
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*/

Previous Top Index Next