10.3.1.3. Files

aa) A "file" is the means of communication between a particular-program and a book which has been opened on that file via some channel. It is a structured value which includes a reference to the book to which it has been linked {10.3.1.4.bb } and a separate reference to the text of the book. The file also contains information necessary for the transput routines to work with the book, including its current position cpos in the text, its current "state" {bb}, its current "format" {10.3.4 } and the channel on which it has been opened.

bb) The "state" of a file is determined by five fields:

· read mood, which is true if the file is being used for input:

· write mood, which is true if the file is being used for output:

· char mood, which is true if the file is being used for character transput;

· bin mood, which is true if the file is being used for binary transput:

· opened, which is true if the file has been linked to a book.

cc) A file includes some "event routines", which are called when certain conditions arise during transput. After opening a file, the event routines provided by default return false when called, but the programmer may provide other event routines. Since the fields of a file are not directly accessible to the user, the event routines may be changed by use of the "on routines" (l,m,n,o,p,q,r). The event routines are always given a reference to the file as a parameter. If the elaboration of an event routine is terminated, then the transput routine which called it can take no further action: otherwise, if it returns true, then it is assumed that the condition has been mended in some way, and, if possible, transput continues, but if it returns false, then the system continues with its default action. The on routines are:

· on logical file end. The corresponding event routine is called when, during input from a book or as a result of calling set, the logical end of the book is reached (see 10.3.1.6.dd ).

Example: The programmer wishes to count the number of integers on his input tape. The file intape was opened in a surrounding range. If he writes: ,

BEGIN INT n := 0;
  on logical file end (intape, (REF FILE file) BOOL: GOTO f);
  DO get (intape, LOC INT); n +:= 1 OD;
  f: print (n)
END

BEGIN INT n := 0; FILE auxin := in tape;
  on logical file end (auxin, (REF FILE file) BOOL: GOTO f);
  DO get (auxin, icc INT); n+:= 1 OD;
  f: print (n)
END

· on page end. The corresponding event routine is called when the current line number exceeds the number of lines in the current page and further transput is attempted (see 10.3.1.6.dd ).

· on line end. The corresponding event routine is called when the current character number of the file exceeds the number of characters in the current line and further transput is attempted (see 10.3.1.6.dd ),

Example: The programmer wishes automatically to give a heading at the start of each page on his file f: .

on page end (f, (REF FILE file) BOOL:
    (put(file, (newpage, "page number ", whole (i +:= 1.0),
        newline)); TRUE)
        ¢ it is assumed that i has been declared elsewhere ¢)

Example: The programmer wishes to read sums of money punched as "$123.45", ",$23.45", ",$3.45", etc.: .

on char error (stand in, (REF FILE f, REF CHAR sugg) BOOL:
      IF sugg = "0"
      THEN CHAR c; backspace (f); get (f, c);
          ( c = "$" | get (f, sugg); TRUE | FALSE)
      ELSE FALSE
      FI );
INT cents; readf(($3z"."dd$, cents))

( 1)

during formatted transput an attempt is made to transput a value under the control of a "picture" with which it is incompatible, or when the number of "frames" is insufficient. If the routine returns true, then the current value and picture are skipped and transput continues; if the routine returns false, then first, on output, the value is output by put, and next undefined is called;

( 2)

during input it is impossible to convert a string to a value of some given mode (this would occur if, for example, an attempt were made to read an integer larger than max int {10.2.1.c } ).

dd) The conv field of a file is its current conversion key {10.3.1.2.bb }. After opening a file, a default conversion key is provided. Some other conversion key may be provided by the programmer by means of a call of make conv {j}. Note that such a key must have been provided in the library-prelude.

ee) The routine make term is used to associate a string with a file. This string is used when inputting a variable number of characters, any of its characters serving as a terminator.

ff) The available methods of access to a book which has been opened on a file may be discovered by calls of the following routines (note that the yield of such a call may be a function of both the book and the channel, and of other environmental factors not defined by this Report):

· get possible, which returns true if the file may be used for input;

· put possible, which returns true if the file may be used for output;

· bin possible, which returns true if the file may be used for binary transput;

· compressible, which returns true if lines and pages will be compressed {10.3.1.6.aa } during output, in which case the book is said to be "compressible";

· reset possible, which returns true if the file may be reset, i.e., its current position set to (1, 1, 1);

· set possible, which returns true if the file may be set, i.e., the current position changed to some specified value; the book is then said to be a "random access" book and, otherwise, a "sequential access" book:

· reidf possible, which returns true if the idf field of the book may be changed:

· chan, which returns the channel on which the file has been opened {this may be used, for example, by a routine assigned by on physical file end, in order to open another file on the same channel}.

gg) On sequential access books, undefined {10.3.1.4.a } is called if binary and character transput is alternated, i.e., after opening or resetting {10.3.1.6.j }, either is possible but, once one has taken place, the other may not until after another reset.

hh) On sequential access books, output immediately causes the logical end of the book to be moved to the current position (unless both are in the same line); thus input may not follow output without first resetting {10.3.1.6.j },

Example:

BEGIN FILE f1, t2; [1: 10000]INT x; INT n := 0;
      open (f1, "", channel 2);
      f2 := f1;
      ¢ now f1 and f2 can be used interchangeably ¢
      make conv (f1, flexocode); make conv (f2, telexcode);
      ¢ now f1 and f2 use different codes; flexocode and telexcode are defined in the \p{library-
prelude} for this implementation ¢
      reset (f1);
      ¢ consequently, f2 is reset too ¢
      on logical file end (f1, (REF FILE f) BOOL: GOTO done);
      FOR i DO get (f1, x [i]); n := i OD;
      ¢ too bad if there are more than 10000 integers in the input ¢
      done:   
        reset (f1); for i to n DO put (f2, x [i]) OD;
      close (f2) ¢ f1 is now closed too ¢
  END

a)

MODE FILE =
  STRUCT (REF BOOK {?} book, UNION (FLEXTEXT, TEXT) {?} text, CHANNEL {?} chan,
    REF FORMAT {?} format, REF INT {?} forp,
    REF BOOL {?} read mood, {?} write mood, {?} char mood, {?} bin mood, {?} opened,
    REF POS {?} cpos ¢ current position ¢,
    STRING {?} term ¢ string terminator ¢,
    CONV {?} conv ¢ character conversion key ¢,
    PROC (REF FILE ) BOOL {?} logical file mended, {?} physical file mended,
    ¢ a¢page mended, {?} line mended, {?} format mended,
    ¢ a¢value error mended,
    PROC (REF FILE, REF CHAR) BOOL {?} char error mended);

b) PROC get possible = (REF FILE f)BOOL: (opened OF f | (get OF chan OF f)(book OF f) | undefined; SKIP);

c) PROC put possible = (REF FILE f)BOOL: (opened OF f | (put OF chan OF f)(book OF f) | undefined; SKIP);

d) PROC bin possible = (REF FILE f)BOOL: (opened OF f | (bin OF chan OF f)(book OF f) | undefined; SKIP);

e) PROC compressible = (REF FILE f)BOOL: (opened OF f | (compress OF chan OF f)(book OF f) | undefined; SKIP);

f) PROC reset possible = (REF FILE f)BOOL: (opened OF f | (reset OF chan OF f)(book OF f) | undefined; SKIP);

g) PROC set possible = (REF FILE f)BOOL: (opened OF f | (set OF chan OF f)(book OF f) | undefined; SKIP);

h) PROC reidf possible = (REF FILE f)BOOL: (opened OF f | (reidf OF chan OF f)(book OF f) | undefined; SKIP);

i) PROC chan = (REF FILE f)CHANNEL: (opened OF f | chan OF f | undefined; SKIP);

j) PROC make conv = (REF FILE f, PROC(REF BOOK)CONV c)VOID: (opened OF f | conv OF f := c(book OF f) | undefined);

k) PROC make term = (REF FILE f, STRING t)VOID: term OF f := t;

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

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

n) PROC on page end = (REF FILE f, PROC(REF FILE )BOOL p)VOID: page mended OF f := p;

o) PROC on line end = (REF FILE f, PROC(REF FILE )BOOL p)VOID: line mended OF f := p;

p) PROC on format end = (REF FILE f, PROC(REF FILE)BOOL p)VOID: format mended OF f := p;

q) PROC on value error = (REF FILE f, PROC(REF FILE)BOOL p)VOID: value error mended OF f := p;

r) PROC on char error = (REF FILE f, PROC(REF FILE , REF CHAR)BOOL p)VOID: char error mended OF f := p;

s) PROC reidf = (REF FILE f, STRING idf)VOID: IF opened OF f reidf possible(f) idfok(idf) THEN idf OF book OF f := idf FI;
 
Next