OS/2 Shareware BBS: 18 REXX/18-REXX.zip/rio111.zip/RXFile.doc

Text File | 1997-02-13 | 29KB | 808 lines

RXFile: A Rexx I/O class implementation  1.11 - Max Marsiglietti 1996.

This is the official RXFile documentation. You'll find here all the
informations you need for using the RXFile library for NetRexx.

To get best results in visualization of this document, use a monospaced font.
English is not my language. Please adjust your instruments accordingly. :)

INDEX:
 1.... Introduction
  1.1.   - What is RXFile.


 2.... Use of the RXFile class
  2.1    - in Java.
  2.2    - in NetRexx.
  2.3    - A detailed explanation of all the methods.
   2.3.1   - Before we begin.
   2.3.2   ** RXFile constructors in NetRexx **
   2.3.3   ** The STREAM command **
   2.3.4   ** The CHARS command **
   2.3.5   ** The LINES command **
   2.3.6   ** The CHARIN command **
   2.3.7   ** The LINEIN command **
   2.3.8   ** The CHAROUT command **
   2.3.9   ** The LINEOUT command **

   2.3.10  ** The DELETE command **
   2.3.11  ** The RENAME command **
   2.3.12  ** The MKDIR command **
   2.3.13  ** The MKDIRS command **
   2.3.14  ** The PROPERTIES command **
   2.3.15  ** The FILETREE command **
   2.3.16  ** The SETPARMS command **
   2.3.17  ** The GETPARMS command **
   2.3.18  ** The ADDCURSOR command **
   2.3.19  ** The GETCURSOR command **
   2.3.20  ** The DELCURSOR command **
   2.3.21  ** The DELALLCURSORS command **
   2.3.22  ** The ATTACHTOINPUTSTREAM command **
   2.3.23  ** The ATTACHTOOUTPUTSTREAM command **


 3.... Other stuff
  3.1    - This package contents.
  3.2    - License.
  3.3    - Contacting the author.
  3.4    - Release History.



1. I N T R O D U C T I O N
--------------------------

Notice: NetRexx, OS/2 are copyright of IBM Corp.
        JAVA is a copyright of SUN Microsystems, Inc.

Other trademarks in this document are owned by the respective companies.
Whatever. :)

Warning: in this document I will assume that the reader knows
what NetRexx is and how to build applications in NetRexx.
JAVA I/O specific knowledge it's not required.

Many people think that JAVA is only useful for writing web applets;
it is my opinion that this statement is reductive.
JAVA makes a great language for a variety of purposes, expecially
those requiring cross-platform development.

One of the less-explored areas of what I call 'the jungle of JAVA
APIs' is the one that deals with streams and files in general.
While there is in the JAVA developer's toolkit a plethora of examples
to show how easy and cool is doing graphics with this language,
there is not a single example specific to file usage.
Not that JAVA is lacking stuff, it's only that this stuff is
buried under the documentation.

The JAVA approach approach to files and streams is somewhat confusing;
there are many classes, a bunch of interfaces, and some of these
apparently aren't so useful for the everyday work of Joe Programmer.
That's what this package is for: helping you to manage files
and streams in Java through the use of the NetRexx compiler.


1.1 What is RXFile.
-------------------

RXFile is a JAVA CLASS that contains a number of functions that
deal with files and stdin/stdout streams.

RXFile was born to fill a gap in the NetRexx implementation;
therefore, most of the methods in this class follow the syntax
of the corresponding REXX statements.
NetRexx is a compiler that comes as a JAVA executable and therefore
can be used on every platform that has a JAVA implementation;
it produces JAVA binary code and, optionally, a JAVA source.
The source language accepted by this compiler is a REXX-like
language.

NetRexx is required in order to use this class, at least the
classes; download them from the URL below, and add them to
your Java developing environment.
All the examples are written in NetRexx, but the API syntax
in this document follows the Java syntax.

To find out more, point your browser to:
http://www2.hursley.ibm.com/netrexx/



2. U S E  O F  T H E  R X F I L E  C L A S S
--------------------------------------------


2.1 In JAVA:
------------

Just make sure that your Java environment variables
knows where RXFile.class is stored, then you can just
add this line to your source:

import RXFile;

along with the required NetRexx imports.


2.2 In NetRexx:
---------------

 import RXFile

Is required in your NetRexx source file.



2.3 A detailed explanation of all the methods.
----------------------------------------------

 Why did I state 'methods', and not also 'properties' or 'exceptions' ?
Simply put, the RXFile class has no public properties (variables),
and doesn't throw exceptions. Instead, it has methods to find out
if there have been errors, and to query the value of some properties.


2.3.1 Before we begin
---------------------

The following instructions are designed to be 100% compatible with the original
IBM SAA REXX implementation, so if you find any discrepancy, write to the author.
(Go to the end of the document for more informations)

Note: As you may know, the newline sequence is not standard among the operating
systems. I.e., in Unix it's \n, in DOS-Win-OS/2 is \r\n, in Macs is \r etc.
RXFile automatically sets the correct newline (currently \n, \r and \r\n are
supported, since I know of these), but you can override this choice with
the 'setparms' function.


2.3.2 ** RXFile constructors in NetRexx **
------------------------------------------

Note that the semicolon is optional:

Myfile = RXFile();

or

Myfile = RXFile("filename");

or

Myfile = RXFile(InputStream isInputStream , OutputStream osOutputStream )

This constructor assigns isInputStream, osOutputStream to the in/out
streams that are normally given to console.

or

Myfile = RXFile("filename", "c", "command");

The above constructor works as in the STREAM command.

The default return strings for the following functions are:
 SYNTAX ERROR:
 READY:       (no errors)
 NOTREADY:32  (file in use)
 NOTREADY:110 (file not found)
 NOTREADY:EOF (end of file reached)
 WEIRD ERROR: (this is a catch for bugs)
 NOFILEOPEN:  (if the user requested an operation to be done only on open files)
 ILLEGAL:WRONG ACCESS MODE (i.e. if you try to read a write-only file)
 ILLEGAL:ALREADY EXISTS    (if the command implied creation of something)
 ILLEGAL:CANT ACCESS TARGET
 ILLEGAL:ALREADY INIT       (used for the setparms command)

Unless stated otherwise.


2.3.3 ** The STREAM command **
------------------------------

Used to open/close a file, query informations about that file
and/or status, and seek the file cursor to a given location.

Rexx status = RXFile.stream(Rexx filename, "c", Rexx command);
Rexx status = RXFile.stream("c", Rexx command);
Rexx status = RXFile.stream("d");
Rexx status = RXFile.stream("s");

More in details:


Rexx status = RXFile.stream(Rexx filename, "c", Rexx command);

The commands available are:
"open"           opens a file for read and write operations.
"open read"      opens a file for read operations.
"open write"     opens a file for write operations.
"query exists"   returns the absolute path name, or the null string if
                 that file doesn't exists.
"query size"     returns the size, in bytes, of the file.
"query datetime" returns a value useful for file comparisons (it
                  doesn't return a REAL date & time, due to the
                  lack of such an API in JAVA).
"close"          closes the stream.

Warning: if you issue one of the next three commands when you
are in 'separate r/w cursors' mode, you actually move both cursors.

Warning 2: In REXX, the first byte of the stream is at position '1', not
'0' like Java. Therefore, if you do an absolute seek ('=N'), you should
remember that to seek the first byte in the stream you have to
issue "seek =1". All the other seek instructions are relative, so you
can specify an offset = 0.

"seek =N"        The stream cursor is positioned to absolute position N
                 (in bytes; an ASCII newline is \r\n == two bytes).
"seek -N"        The stream cursor is positioned N bytes back from the
                 current position.
"seek +N"        The stream cursor is positioned N bytes forward from the
                 current position.
"seek <N"        The stream cursor is positioned N bytes back from the
                 end of the file.

Functions available only if you choose separate r/w cursors:
(see the SETPARMS function)

"rseek =N"        The stream read cursor is positioned to absolute position N
                 (in bytes; an ASCII newline is \r\n == two bytes).
"rseek -N"        The stream read cursor is positioned N bytes back from the
                 current position.
"rseek +N"        The stream read cursor is positioned N bytes forward from the
                 current position.
"rseek <N"        The stream read cursor is positioned N bytes back from the
                 end of the file.
"wseek =N"        The stream write cursor is positioned to absolute position N
                 (in bytes; an ASCII newline is \r\n == two bytes).
"wseek -N"        The stream write cursor is positioned N bytes back from the
                 current position.
"wseek +N"        The stream write cursor is positioned N bytes forward from the
                 current position.
"wseek <N"        The stream write cursor is positioned N bytes back from the
                 end of the file.

Rexx status = RXFile.stream("c", Rexx command);

This command can be issued only when a file
has already been opened by executing a .stream call.

The commands available are:
"close"          closes the stream.
"query exists"   returns the absolute path name, or the null string.
"query size"     returns the size, in bytes, of the file.
"query datetime" returns a value useful for file comparisons (it
                  doesn't return a REAL date & time, due to the
                  lack of such an API in JAVA).

Warning: if you issue one of the next three commands when you
are in 'separate r/w cursors' mode, you actually move both cursors.

Warning 2: In REXX, the first byte of the stream is at position '1', not
'0' like Java. Therefore, if you do an absolute seek ('=N'), you should
remember that to seek the first byte in the stream you have to
issue "seek =1". All the other seek instructions are relative, so you
can specify an offset = 0.

"seek =N"        The stream cursor is positioned to absolute position N
                 (in bytes; an ASCII newline is \r\n == two bytes).
"seek -N"        The stream cursor is positioned N bytes back from the
                 current position.
"seek +N"        The stream cursor is positioned N bytes forward from the
                 current position.
"seek <N"        The stream cursor is positioned N bytes back from the
                 end of the file.

Functions available only if you choose separate r/w cursors:
(see the SETPARMS function)

"rseek =N"        The stream read cursor is positioned to absolute position N
                 (in bytes; an ASCII newline is \r\n == two bytes).
"rseek -N"        The stream read cursor is positioned N bytes back from the
                 current position.
"rseek +N"        The stream read cursor is positioned N bytes forward from the
                 current position.
"rseek <N"        The stream read cursor is positioned N bytes back from the
                 end of the file.
"wseek =N"        The stream write cursor is positioned to absolute position N
                 (in bytes; an ASCII newline is \r\n == two bytes).
"wseek -N"        The stream write cursor is positioned N bytes back from the
                 current position.
"wseek +N"        The stream write cursor is positioned N bytes forward from the
                 current position.
"wseek <N"        The stream write cursor is positioned N bytes back from the
                 end of the file.


Rexx status = RXFile.stream("d");
Rexx status = RXFile.stream("s");

Both these commands return the status of the stream.
(they can be issued only when a file has already been opened by
executing a .stream call)

The difference between them is that the latter form is more terse,
the former is more verbose.


2.3.4 ** The CHARS command **
-----------------------------

Rexx RXFile.chars();
Rexx RXFile.chars(Rexx rFileName);

This command lets you know if there are, and how many are they,
characters to be read in a stream or standard input.

More in details:

Rexx RXFile.chars();

This command returns how many bytes are present in the
currently opened stream. If no stream is currently open,
it returns with the number of the available bytes from
stdin (Warning: this doesn't work right now for stdin;
it always returns '0').

Rexx RXFile.chars(Rexx rFileName);

*This command works with files only, no standard input.*

This command returns how many bytes are present in the
file rFileName.
rFileName is opened with both read and write access
permissions, and a precedently open file, if exists, is closed.

Of course, if the file name is the same of the one which is
(if any) currently in use, the file won't be touched, meaning
that the r/w cursors will be left untouched.

The only exception is the following: if you opened rFileName
precedently with only read OR write permissions, the file will be
closed and then reopened with read+write permissions.
This is because lines(filename) opens the file with both read
and write access capabilities.

After this operation, the currently opened file is rFileName.


2.3.5 ** The LINES command **
-----------------------------

Rexx RXFile.lines();
Rexx RXFile.lines(Rexx rFileName);

This command lets you know if there are still lines to be read
in a stream or standard input.

More in details:

Rexx RXFile.lines();

This command returns "1" if there are more lines to be read
(or overwritten) in the file currently in use, else it returns "0" .
If no stream is opened, it checks for the presence of lines
to be read in stdin .

Rexx RXFile.lines(Rexx rFileName);

*This command works with files only, no standard input.*

This command returns "1" if there are more lines to be read
(or overwritten) in the file rFileName, else it returns "0" .
rFileName is opened with both read and write access permissions,
and a precedently open file, if exists, is closed.

Of course, if the file name is the same of the one which is
(if any) currently in use, the file won't be touched, meaning
that the r/w cursors will be left untouched.

The only exception is the following: if you opened rFileName
precedently with only read OR write permissions, the file will be
closed and then reopened with read+write permissions.
This is because linein(filename) opens the file with both read
and write access capabilities.

After this operation, the currently opened file is rFileName.


2.3.6 ** The CHARIN command **
------------------------------

Rexx RXFile.charin();
Rexx RXFile.charin(Rexx rFileName);
Rexx RXFile.charin(long lStartPos, int iHowManyBytes);
Rexx RXFile.charin(Rexx rFileName, long lStartPos, int iHowManyBytes);

This command gets one or more bytes from the standard input or
a currently opened stream.

The commands which include also rFileName allow to close the currently opened
stream and open the new one before actually doing the work without issueing
a separate .stream command. These commands default to read AND write
capabilities.

More in details:

Rexx RXFile.charin();

Returns the next byte from the currently used stream.
If no stream is currently open, it returns the next byte
from the standard input.

Rexx RXFile.charin(long lStartPos, int iHowManyBytes);

*This command works with files only, no standard input.*

Returns lHowManyBytes, starting from the absolute position lStartPos.
If you specify a value of 0 (zero) for lStartPos, the bytes after
the current cursor position in the stream will be read.
(The first character in the stream is numbered 1)


2.3.7 ** The LINEIN command **
------------------------------

Rexx RXFile.linein();
Rexx RXFile.linein(Rexx rFileName);
Rexx RXFile.linein(int iLine, int iCount);
Rexx RXFile.linein(Rexx rFileName, int iLine, int iCount);

This command returns zero or one lines of **ASCII** characters
from the standard input or the stream in use.

The commands which include also rFileName allow to close the currently opened
stream and open the new one before actually doing the work without issueing
a separate .stream command. These commands default to read AND write
capabilities.

More in details:

Rexx RXFile.linein();

Returns the next line from a stream, or from the stdin if no stream
is currently open.

Rexx RXFile.linein(int iLine, int iCount);

*This command works with files only, no standard input.*

Returns iCount lines (where iCount can be only zero or one) from
the currently in use stream, starting from position iLine
where iLine can be zero (read the next line), or one (read the
first line of the stream).
Why to get zero lines? Because this way we have an alternative way
to position the cursor at the beginning of the file.

Rexx RXFile.linein(Rexx rFileName);

*This command works with files only, no standard input.*

Returns the first line from stream rFileName (thus opening it with both read
and write access permissions, as well as closing a precedently open file if any).
After this operation, the currently opened file is rFileName.


2.3.8 ** The CHAROUT command **
-------------------------------

Rexx RXFile.charout(Rexx rToWrite);
Rexx RXFile.charout(Rexx rToWrite, long lStartPos);
Rexx RXFile.charout(Rexx rFileName, Rexx rToWrite);
Rexx RXFile.charout(Rexx rFileName, Rexx rToWrite, long lStartPos);

This command is used to write a string on a stream, or on stdout.

The latter two syntaxes allow to start working on a new file without issueing
a separate stream command.

More in details:

Rexx RXFile.charout(Rexx rToWrite);

Writes the Rexx string rToWrite to the currently opened stream, at the
current cursor position. If no stream is in use, the string is
put on stdout (usually the screen).

Rexx RXFile.charout(Rexx rToWrite, long lStartPos);

*This command works with files only, no standard input.*

This version of the command also allows to specify an absolute
starting position for the write on the stream. If lStartPos
is equal to zero, then the write will occur at the current
cursor position in the stream.


2.3.9 ** The LINEOUT command **
-------------------------------

Rexx RXFile.lineout(Rexx rToWrite);
Rexx RXFile.lineout(Rexx rToWrite, long lStartPos);
Rexx RXFile.lineout(Rexx rFileName, Rexx rToWrite);
Rexx RXFile.lineout(Rexx rFileName, Rexx rToWrite, long lStartPos);

This command is used to write a string adding a CR+LF (\r\n)
or a LF (\n) (depending on how/if you called SETPARMS) on a stream,
or on stdout.

The latter two syntaxes allow to start working on a new file without issueing
a separate stream command.

More in details:

Rexx RXFile.lineout(Rexx rToWrite);

Writes the Rexx string rToWrite to the currently opened stream, at the
current cursor position, and adds a CR+LF or LF at the end of it.
If no stream is in use, the string is put on stdout (usually the screen).

Rexx RXFile.lineout(Rexx rToWrite, long lStartPos);

*This command works with files only, no standard input.*

This version of the command also allows to specify an absolute
starting position for the write on the stream. If lStartPos
is equal to zero, then the write will occur at the current
cursor position in the stream.
Please note that lStartPos can only be assigned the values zero or one,
one meaning "write at the beginning of the file" and zero meaning
"write at the current cursor position in the stream".


The next commands are not ported from REXX. However, since they are
very useful when dealing with I/O procedures, I have included them
in the RXFile package.


2.3.10 ** The DELETE command **
-------------------------------

Rexx RXFile.delete(Rexx FileName);

This command deletes a file.


2.3.11 ** The RENAME command **
-------------------------------

Rexx RXFile.rename(Rexx OldFileName, Rexx NewFileName);

This command renames OldFileName into NewFileName.


2.3.12 ** The MKDIR command **
------------------------------

Rexx RXFile.mkdir(Rexx DirName);

Creates the directory DirName.


2.3.13 ** The MKDIRS command **
-------------------------------

Rexx RXFile.mkdirs(Rexx DirName);

Creates the directory that comes last in DirName,
and all the preceding directories if they are not present.

i.e. if you have DirName set to "/usr/max/I/LOVE/WARP/CONNECT",
and you don't have the directories I, LOVE, WARP and CONNECT, but
you have usr and max, this function will create all of the ones that
are not there, where mkdir would have failed since to create CONNECT
you had to have all of usr, max, I, LOVE, WARP already created.

YMMV. This is the one API I have never tested. :)


2.3.14 ** The PROPERTIES command **
-----------------------------------

Rexx RXFile.properties(Rexx FileName);

Returns the properties of the specified file or directory.

Properties:

The returned string is a four character string; every character
can be '-' if the property is not valid for FileName or:

 f if the specified FileName refers to a file.
 d if the specified FileName refers to a directory.
 w if the specified FileName is writable.
 r if the specified FileName is readable.

Example: 'f-wr' means that FileName is a file and we have both
read and write permissions for it.


2.3.15 ** The FILETREE command **
---------------------------------

Rexx[] RXFile.filetree(Rexx DirName);

This command returns all the file names for the specified directory.
If the directory name is invalid (if there is not such a directory)
you will get the "NOTREADY:NOSUCHDIRECTORY" error as the first and
unique element of the returned array.
If the directory is empty you will get "NOTREADY:DIRECTORYISEMPTY".


2.3.16 ** The SETPARMS command **
---------------------------------

Rexx RXFile.setparms(boolean bSepCurs, boolean bRN);

This command, to be issued before opening any file (but only if
needed), is used to define some RXFile options.

When bSepCurs is 1, you have two distinct cursors, one for read
and one for write. Otherwise, you only have one cursor (this is
the default, and it's also the way OS/2 REXX works).

When bRN is 1, the character used to do a newline is \r\n (dec 13 10);
when this parameter is set to zero, the newline is only \n .
This property is set upon RXFile variable's instantiation to follow
whatever is the system's default


2.3.17 ** The GETPARMS command **
---------------------------------

Rexx RXFile.getparms();

This command is used to retrieve the status of some RXFile options.

It returns a Rexx string which is composed of two binary digits, ie "11".

When the first is 1, you have two distinct cursors, one for read
and one for write. Otherwise, you only have one cursor (this is
the default, and it's also the way OS/2 REXX works).

When the second is 1, the character used to do a newline is
\r\n (dec 13 10); when this parameter is set to zero,
the newline is only \n . This property is set upon instantiation to follow
whatever is the system's default, but can be changed with the SETPARMS command.


2.3.18  ** The ADDCURSOR command **
-----------------------------------

Rexx RXFile.addcursor(Rexx rKey, long lCursPos);

This command stores (into the variable's memory, which is unique for every
RXFile instance) the lCursPos cursor position, under the name rKey.
You can retrieve this information later, with getcursor, or delete it with
delcursor or delallcursors.

This is useful when you have to work on many points of a file.


2.3.19  ** The GETCURSOR command **
-----------------------------------

Rexx RXFile.getcursor(Rexx rKey);

This command retrieve (from the variable's memory, which is unique for every
RXFile instance) the cursor position which has been stored under the name rKey.
If you request a cursor position that hasn't been stored, you'll get the message
"Error: no such cursor." instead of a Rexx string representing a long.


2.3.20  ** The DELCURSOR command **
-----------------------------------

Rexx RXFile.delcursor(Rexx rKey);

This command deletes (from the variable's memory, which is unique for every
RXFile instance) the cursor position which has been stored under the name rKey.


2.3.21  ** The DELALLCURSORS command **
---------------------------------------

Rexx RXFile.delallcursors();

This command deletes (from the variable's memory, which is unique for every
RXFile instance) all of the cursor positions which have been stored.


2.3.22  ** The ATTACHTOINPUTSTREAM command **
---------------------------------------------

Rexx RXFile.attachtoinputstream(InputStream is)

This command redirects the InputStream 'is' to the default InputStream for that
RXFile instance (i.e. replacing user input from console). You didn't know
that RXFile had an InputStream, or you didn't find notice of this fact anywhere?
That's because it's a private property. Now you can interact with it this way.


2.3.23  ** The ATTACHTOOUTPUTSTREAM command **
----------------------------------------------

Rexx RXFile.attachtooutputstream(OutputStream os)

This command redirects the OutputStream 'os' to the default OutputStream for that
RXFile instance (i.e. replacing console output).





3. O T H E R   S T U F F
------------------------



3.1 THIS PACKAGE CONTENTS
-------------------------

This package should contain:

 RXFile.doc   .. this document.
 guru.doc     .. working code to use in your programs.
 RXFile.class .. the RXFile class for NetRexx (and Java).
 *.nrx ..  => Examples for the RXFile class.
 *.cmd ..   => Examples for the RXFile class (REXX files).



3.2 LICENSE
------------

RXFile is not public domain: it is freeware. It means that you can freely
use it in your programs, be them for personal use and/or commercial use.
However, the sources are not provided, and you cannot modify or disassemble
the class, in any way. Also, if you re-distribute this program, you cannot
charge any money for it, apart from media costs (eg. diskette cost).
If you plan to use this class on a project of yours, you must give credits
to the author (Max Marsiglietti) of this.

I am not responsible or liable in any way for damages
deriving from the use of this product. Use it at your own risk.


3.3 CONTACTING THE AUTHOR
-------------------------

This library is intended to follow more closely possible the REXX language I/O
functions. If you find any discrepancy from them, or bugs, please report all
of your comments to:

 Max Marsiglietti,

 E-mail:
  [e-mail] (Internet), 2:332/529.12 (Fidonet)

 Snail Mail:
  V.Landino 13,
  41049, Sassuolo (MO)
  Italy.



3.4 History
-----------

1.11 .. (13-feb-97) Fixed a bug in mkdirs.
1.10 .. (19-dec-96) Added support for Mac line termination (\r).
1.09 .. (03-dec-96) Fixed a bug in filetree, added new return
        codes for that function.
1.08 .. (12-nov-96) Fixed a problem with lineout console output,
        added redirected in/out capabilities (attachtoinputstream
        and attachtooutputstream). Reworked a bit some internals.
1.07 .. Internal changes, for synchronization with RXDbase.
1.06 .. Fixed the 'rename' function.
1.05 .. Now linein should work with both \r\n and \n terminated ASCII
        files, independently from the platform.
1.04 .. Fixed strange behaviour of linein. Compiled with NetRexx 0.81.
1.03 .. Bug fixes to the docs and internal changes for RXDbase.
1.02 .. Bug fixes to stream and lineout. Works with NetRexx 0.79.
1.01 .. Added a cursor stack: addcursor, getcursor, delcursor,
                              delallcursors functions added.
1.00 .. First implementation of RXFile.

Thanks, and good work with RXFile!