Fileopen

Version: 1.0             13-NOV-2006

This archive contains the following files:
   FileOpen.rexx                          Collection of I/O routines.
   FileOpen_Doc.txt                       This file.
   FileOpen_CopyByChar.rexx               Sample program.
   FileOpen_CopyByLine.rexx               Sample program.
   FileOpen_TestFile.txt                  Sample input file.

This is a collection of Rexx/ARexx routines which perform I/O.  I 
created them to allow me to create Rexx programs which will work on 
both Amiga and Windows platforms without having to modify the code
because of the differences in I/O between Rexx and ARexx.

On the Amiga platform ARexx connects a real filename to a logical name 
when the file is opened and from that point on the logical name is used
exclusively to perform other operations.  Whereas with standard Rexx, 
the real filename is always used for performing all operations.

In all of these functions the first two arguments are:
Argument 1: "LogicalFile"
   This is the logical file name to which the external file will be 
   connected when the file is opened on the Amiga.  This argument is 
   not used on the Windows platform.
Argument 2: "FileName"
   This is the name of the external file.  On the Amiga platform it is
   only used when the file is opened.  On the Windows platfrom it is 
   always used.

The functions are:

FileOpen( LogicalFile, FileName, Mode )
   Argument 3: "Mode"
   This is one of the following:
      "R" for Read
      "W" for Write
      "A" for Append
   This function returns true if the file was successfully opened or
   false if it could not be opened.

FileRead( LogicalFile, FileName )
   This function reads the next line from the file.  The line is 
   returned as the function's result.

FileWrite( LogicalFile, FileName, Line )
   Argument 3: "Line"
   This is a string variable that contains the next line of data to be
   written to the file.  The function always returns a result of zero.

FileChRead( LogicalFile, FileName, Length )
   Argument 3: "Length"
   Length defines the number of characters to be read from the input
   file. 
   The characters read are returned as the function's result.

FileChWrite( LocigalFile, FileName, String )
   Argument 3: "String"
   String contains the character or characters to be written to the
   output file.  This function always returns a result of zero.

FileEOF( LogicalFile, FileName )
   This function returns true if the end of file has been reached or
   flase if the end of file has not been reached.

FileClose( LogicalFile, FileName )
   This closes the file.  On the Amiga, true is returned if the file 
   was closed or flase is if the file could not be closed.  On Windows,
   true is always returned.

FileExists( FileName )
   Whoops!  This function only has one argument.  This function trys 
   to open the specified FileName and returns true if the file exists
   or flase if the file does not exist.

There are two example programs supplied:
   FileOpen_CopyByLine.rexx
      This program copies a file by reading and writing one line at a
      time until and end-of-file is reached.  You can then compare the
      files and/or file sizes to show that things worked right.
   FileOpen_CopyByChar.rexx
      This program copies a file by reading and writing one character 
      at a time until and end-of-file is reached.  You can then compare 
      the files and/or file sizes to show that things worked right.

There is one test file supplied:
   FileOpen_TestFile.txt
      This is a very short text file which can be used as input to 
      either of the above two test programs.  This file is exactly 
      65 bytes long.

Testing: This code has been tested on an AmigaOne with ARexx version 
1.15 and on a Windows XP machine with Regina Rexx version 3.3.