Subsections

- Logical file end
- Physical file end
- Value error
- Char error
- Exercises

# Events

Algol 68 transput is characterised by its use of events. In the limited transput supplied with the a68toc compiler, only four kinds of events are detected. These are:

1. The end of the file when reading. This is called the “logical file end”.
2. The end of the file when writing. This is called the “physical file end”.
3. A value error.
4. A character error.

The default action when an event occurs depends on the event. However, the default action can be replaced by a programmer-defined action using one of the “on”-procedures.

## Logical file end

When the logical end of a file has been detected, the default action is to terminate the program immediately. All open files will be closed by the operating system, but any buffered output files will lose any data in the buffer. A programmer-supplied action must be a procedure with the header

       (REF FILE f)BOOL:

The yield should be `TRUE` if some action has been taken to remedy the end of the file, in which case transput is re-attempted, or `FALSE`, when the default action will be taken.

The procedure `on logical file end` has the header

       PROC on logical file end=
          (REF FILE f,
           PROC(REF FILE)BOOL p)VOID:

and an example will help explain its use. Here is a program which will display the contents of its text input file and print a message at its end.

       PROGRAM readfile CONTEXT VOID
       USE standard
       IF FILE inf; []CHAR infn="textbook";
          open(inf,infn,stand in channel)/=0
       THEN
          put(stand error,
              ("Cannot open ",
               infn,newline));
          exit(1)
       ELSE
          on logical file end(inf,
             (REF FILE f)BOOL:
                (write(("End of ",
                        idf(f),
                        " read",newline));
                 close(f);  FALSE));
          STRING line;
          DO
             get(inf,(line,newline));
             write((line,newline))
          OD
       FI
       FINISH

The anonymous procedure provided as the second parameter to `on logical file end` prints an informative message and closes the book before yielding `FALSE`. Since in this case all we want is for the program to end when the input has been read, the default action is fine. Notice also that the `DO` loop simply repeats the reading of a line until the `logical file end` procedure is called. The procedure `idf` is described in section 9.11.

You should be careful if you do any transput on the parameter `f` in the anonymous routine otherwise you could get an infinite loop (a loop which never ends). Also, because the `on logical file end` procedure assigns its procedure parameter to its `REF FILE` parameter, you should be wary of using `on logical file end` in limited ranges. The way out of this problem is to make a local copy of the `REF FILE` parameter as in:

       BEGIN
          FILE loc f:=stand in;
          on logical file end(
               f,(REF FILE f)BOOL: ...);
            ...
       END

Any piece of program which will yield an object of mode `PROC(REF FILE)BOOL` in a strong context is suitable as the second parameter of `on logical file end`.

If you want to reset the action to the default action, use the phrase

       on logical file end(f,no file end)

## Physical file end

The physical end of a file is met on writing if, for example, the disk is full. It can also occur when using the `mem channel` (see section 9.10). The default action closes all open files (but the buffers of buffered files will not be flushed to disk) and terminates the program with an exit value of 255.

A replacement procedure should have the mode

       PROC(REF FILE)BOOL

and it should yield `TRUE` if the event has been remedied in some way, in which case transput will be re-attempted, and `FALSE` otherwise (when the default action will be elaborated).

The default procedure can be replaced with a procedure defined by the programmer using the procedure `on physical file end` which has the header:

       PROC on physical file end =
          (REF FILE f,
           PROC(REF FILE)BOOL p)VOID:

## Value error

This event is caused by the following circumstances:-

1. If an integer is expected, then the value read exceeds `max int`.
2. If a real number is expected, then the value read exceeds `max real`.
3. If a complex number is expected, then the value read for either the real part or the imaginary part exceeds `max real`.

The procedure `on value error` lets the programmer provide a programmer-defined procedure whose header must be

       (REF FILE f)BOOL:

although any identifier could replace the `f`. Transput on the file `f` within the procedure should be avoided (but see `backspace` below), but any other transput is allowable, but try to ensure that a value error won't occur!

If the programmer-supplied routine yields `TRUE`, transput continues, otherwise an error message is issued to `stand error` and the program aborted with an exit value of `247`.

## Char error

This event can occur when reading a number if the number is entirely absent so that the first character is neither a sign nor a digit. In this case a default procedure is called having the header

       (REF FILE f,REF CHAR c)BOOL:

The default procedure can be replaced with a programmer-defned procedure using the procedure `on char error`.

The char error procedure is called with the `c` referring to a suggested value for the next character. The replacement character must be a member of a particular set of characters. The default value is `0`. If the procedure returns `FALSE` the default suggested character will be used, otherwise the value referred to by `c` will be used. Thus the programmer-supplied procedure can not only change the default suggested character, but can also perform such other actions as are deemed necessary (such as logging the error).

The event can also occur when reading the digits before a possible `"."` for real numbers and the digits after the `"."`. For complex numbers, after the real part, an `i` or `I` is expected and its non-appearance will cause the `char error` procedure to be executed. The default suggestion is `i`, but can be replaced by another character and optional actions.

For a `BITS` 10.3 value, whenever a character which is neither `flip` nor `flop` is met, the `char error` procedure is called with `flop` as the suggested value. Thus the available suggested character sets are:-

1. For digits: 0...9
2. For exponent: `e E` \
3. For plus i times: `i I`
4. For flip or flop: `FT` (uppercase only) respectively

## Exercises

9.7
  Write a program whose input book has the identification `inbook` and which contains lines of differing length. Use `on logical file end` to specify a procedure which establishes the output book `outbook`, writes the average length and closes it and then yields `FALSE`. Ans