#164 RexxRef: hard to follow doc about I/O errors

Reference (110)

Rexx Reference manual suggestion:
less run-around in documentation of I/O errors.

In open,
it says "Opens the tream and returns READY:. If the method is
unsuccessful, it returns an error message string in the same form
that the description method uses. For most error conditions, the
additional information is in the form of a numeric return code. This
return code is the value of ERRNO, which is set whenever one of the
file system primitives returns with a -1."

Note: "description" is not a link.

In description,
it says "Returns any descriptive string associated with the current
state of the stream or the Nil object if no descriptive string is
available. The description method is identical with the STATE method
except that the string that description returns is followed by a
colon and, if available, additional information about ERROR or
NOTREADY states."

Note: "STATE" is not a link.

In state,
It says "Returns a string indicating the current stream state. The
returned strings are as follows:
The tream has been subject ot an erroneous operation (possibly during
input, output, or through the STREAM function). See Errors during
Input and Output. ..."

"Errors during Input and Output" is a link to 14.5. Errors during
Input and Output.

14.5. Errors during Input and Output,
Refers the reader back to STATE and DESCRIPTION methods for further

7.4.60. STREAM,
Refers the user to Chapter 14 Input and Output Streams, and to state, for further info.

Thus, the doc. for error conditions is rather serpentine.

I suggest that someplace should document the exact format of returned
values for I/O methods, with examples. Good places to put that might
be 14.4. Examples of Input and Output (by enhancing the existing
examples), or 14.5. Errors during Input and Output.

Something on the order of:

afile = .stream~new('my.file.that.exists')
say afile~open('READ')
/ says "READY:" /
say afile~state()
/ says "READY" (no trailing colon) /
say afile~description()
/ says "READY:" /
. . .
bfile = .stream~new('non.existant.file')
say bfile~open('READ')
/ says "ERROR:2" on Linux ???????? on Windows /
say bfile~state()
/ says "ERROR"
say bfile~description()
says "ERROR:2 No such file or directory" on Linux
and ??????? on Windows */

Note: the result of creating the above Linux example somewhat
surprised me. Based on the descriptions of open and description, I did not expect to see any difference between
the return value for open() and that for description().

Another possibility might be to add an I/O error section to Appendix
C. Error Numbers and Messages.

Also, it would be very helpful if the documentation suggested how the
reader could look up ERRNO values for their platform (since
open, specifically mentions ERRNO).



Cancel   Add attachments