ANS Forth RFI 0001: regarding the "flag" returned by <a href=dpans11.htm#11.6.1.2090>READ-LINE</a> at end of file

This document is produced by TC X3J14 as its clarification of questions raised about ANSI X3.215-1994, American National Standard for Information Systems - Programming Languages - Forth.

The questions covered herein were raised by query

Q0001, regarding the "flag" returned by READ-LINE at end of file boundary conditions.

There are four parts in this document:

1. The original question as received.
2. The TC's reply.
3. The Letter Ballot issued by TC Chair.
4. TC Chair's statement of ballot results.

## Q0001 as received

The following query has been assigned number Q0001 and has been tentatively assigned to Mitch Bradley for drafting a response. - Greg Bailey, by direction, Tue, 21 Mar 95 12:40:30 PST

    Subject: Request for clarification--READ-LINE
    To: x3j14@minerva.com, erather@aol.com
    From: lgc@bluemax.jpl.nasa.gov (Loring Craymer)
    Date: Mon, 23 Jan 95 09:14:21 -0800
    Message-Id: <9501231714.AA00637@bluemax>
    Received: from bluemax.jpl.nasa.gov by med3.minerva.com
    ; Mon, 23 Jan 1995
    11:00 PST
    Content-Type: text
    >From lgc Mon Jan 23 09:14:21 0800 1995 remote from bluemax.jpl.nasa.gov
    Received: from bluemax (bluemax.jpl.nasa.gov [128.149.53.31]) by
    telerobotics.jpl.nasa.gov (8.6.8/8.6.6) with SMTP id KAA00235; Mon, 23 Jan
    1995 10:57:40 -0800
    Received: by bluemax (920110.SGI/911001.SGI) for
    @telerobotics.jpl.nasa.gov:erather@aol.com id AA00637; Mon, 23 Jan 95 09:14:21
    -0800
    Content-Length: 1072

Dear Elizabeth:

In the course of writing a test suite for the FILE wordset, I've discovered that the READ-LINE definition is glaringly incomplete. For this reason, I am submitting this request for clarification (I assume that email is sufficient; I don't recall that a more formal process is required).

Request for clarification:

    11.6.1.2090
    READ-LINE
    ( c-addr u1 fileid -- u2 flag ior)

What is the meaning of "flag"? The rationale suggests that it is an end-of-file flag (or not-end-of-file from the behavior documented in the definition), but this is not clear from the definition.

What happens if the end of the file is encountered while reading a line? The definition states that "If the operation succeeded, flag is true and ior is zero", but success is not defined. I assume that success is either that u1 characters were read or that a line terminator was encountered.

Suggested resolution: flag is true unless the end-of-file is encountered, in which case it is false. ior does not reflect whether the end-of-file was encountered or not.

--Loring

## TC Reply to Q0001

    From: Erather@aol.com
    Subject: Official Response to Q0001
    To: X3J14 Technical Committee
    Cc: lbarra@itic.nw.dc.us
    Date: Fri, 31 Mar 95 12:51:59 PST
    Doc#:  X3J14/Q0001R
    Reference Doc#:  X3.215.1994 ANS Forth
    Date:  March 31, 1995
    Title: Response to Request for Interpretation Q0001, Clarification of
    READ-LINE

Q0001 DRAFT rev 1

Key

> Indicates lines from the original inquiry. The entirty text of the inquiry is cited in this way.

> Indicates excerpts from the standard

Unmarked lines comprise the response to the inquiry.

> Request for clarification:

>     11.6.1.2090
>     READ-LINE
>     ( c-addr u1 fileid -- u2 flag ior)

> What is the meaning of "flag"? The rationale suggests that it is an end-of-file flag (or not-end-of-file from the behavior documented in the definition), but this is not clear from the definition.

In the following excerpt from the definition of READ-LINE , the word "if" means "If and only if".

> If the operation is initiated when the value returned by FILE-POSITION is equal to the value returned by FILE-SIZE for the file identified by fileid, flag is false ...

> What happens if the end of the file is encountered while reading a line? The definition states that "If the operation succeeded, flag is true and ior is zero", but success is not defined. I assume that success is either that u1 characters were read or that a line terminator was encountered.

"success" means that one of the following situations occurred:

1. Some non-terminator characters were read into the buffer or
2. A line with a valid terminator sequence, but no characters other than the terminator sequence, was read. In this case, u2=0, flag=true, and ior=zero.

Specifically, if the last line in the file is non-empty, but has no terminator, an attempt to read that line will "succeed", returning the number of characters thus read, and flag will be true. The next read, assuming that no intervening REPOSITION-FILE occurs, will return u2=0, flag=false, ior=false.

Here is complete list of return value combinations and their meanings:

    u2	flag	ior	Meaning
    --	----	---	-------
    X	X	nonzero	Something bad and unexpected happened
    			(end-of-file is not "unexpected")

    0	false	zero	End-of-file; no characters were read

    0	true	zero	A blank line was read

    0<u2<u1	true	zero	The entire line was read

    u1	true	zero	A partial line was read; the rest would
    			not fit in the buffer, and can be acquired
    			by additional calls to READ-LINE.

> Suggested resolution: flag is true unless the end-of-file is encountered, in which case it is false. ior does not reflect whether the end-of-file was encountered or not.

## Letter Ballot

    From: Erather@aol.com
    Subject: Letter Ballot 012
    To: X3J14 Technical Committee
    Cc: lbarra@itic.nw.dc.us
    Date: Fri, 31 Mar 95 12:54:23 PST
    X3 Subgroup Letter Ballot
    Authorized by X3 Procedures - Distributed by X3 Subgroup X3J14  Project:
     X3J14, ANS Forth
    Doc#:  X3J14/LB012
    Reference Doc#s:  X3J14/Q0001R, X3.215.1994 ANS Forth
    Date:  March 31, 1995
    Title: Response to Request for Interpretation Q0001
    Ballot Period:  30 Days
    Ballot Closes NOON DATE:  April 30, 1995
    Respond to:  greg@minerva.com
            or:  Elizabeth D. Rather, Chair
                 FORTH, Inc.
                 111 N. Sepulveda Blvd.  Suite 300
                 Manhattan Beach, CA  90266
                 (310) 372-8493    FAX (310) 318-7130

    Statement:
        Document X3J14/Q0001R contains a proposed Response to Request for
        Interpretation Q0001.

    Question:
        Do you agree that this response represents the intended interpretation of
        X3.215.1994 ANS Forth?

    YES____ NO____ ABSTAIN____  [NO or ABSTAIN votes require an explanation]

    Signature:  [not required for email ballots]
    Name:
    Organization:

    INSTRUCTIONS:
    Please return the entire letter ballot with your response _either_ by email
    to greg@minerva.com _or_ by regular mail or fax to me at the above address,
    before the closing date & time.

    All TC members must vote.  Failure to vote in two consecutive ballots may
    cause you to lose your voting rights in X3J14.

    Thank you for your participation.

    Elizabeth D. Rather, Chair, X3J14

## Results of Letter Ballot

    From: Erather@aol.com
    Subject: Letter Ballot Results
    To: X3J14 Technical Committee
    Date: Fri, 05 May 95 18:50:18 PDT
    Letter ballots 12 [and 13] have closed.  Both passed.  Results follow.

    Letter ballot 12:  13 yes, 0 no, 0 abstaining.

    [irrelevant material deleted]

    Thank you all for your participation.  Of the 14 votes received, 9 came by
    email, and the rest by fax (plus mine!).

    Regards...
    Elizabeth