head     56.3;
access   paws bayes jws quist brad dew jwh;
symbols  ;
locks    ; strict;
comment  @# @;


56.3
date     93.01.27.13.40.10;  author jwh;  state Exp;
branches ;
next     56.2;

56.2
date     93.01.27.12.15.10;  author jwh;  state Exp;
branches ;
next     56.1;

56.1
date     91.11.05.10.02.47;  author jwh;  state Exp;
branches ;
next     55.1;

55.1
date     91.08.25.10.37.39;  author jwh;  state Exp;
branches ;
next     54.1;

54.1
date     91.03.18.15.38.07;  author jwh;  state Exp;
branches ;
next     53.1;

53.1
date     91.03.11.19.36.22;  author jwh;  state Exp;
branches ;
next     52.1;

52.1
date     91.02.19.09.22.29;  author jwh;  state Exp;
branches ;
next     51.1;

51.1
date     91.01.30.16.21.08;  author jwh;  state Exp;
branches ;
next     50.1;

50.1
date     90.10.29.16.34.57;  author jwh;  state Exp;
branches ;
next     49.1;

49.1
date     90.08.14.14.18.37;  author jwh;  state Exp;
branches ;
next     48.1;

48.1
date     90.07.26.11.25.13;  author jwh;  state Exp;
branches ;
next     47.1;

47.1
date     90.05.14.11.11.58;  author dew;  state Exp;
branches ;
next     46.1;

46.1
date     90.05.07.08.59.11;  author jwh;  state Exp;
branches ;
next     45.1;

45.1
date     90.04.19.16.06.53;  author jwh;  state Exp;
branches ;
next     44.1;

44.1
date     90.04.01.22.28.11;  author jwh;  state Exp;
branches ;
next     43.1;

43.1
date     90.03.20.14.17.34;  author jwh;  state Exp;
branches ;
next     42.1;

42.1
date     90.01.23.18.00.55;  author jwh;  state Exp;
branches ;
next     41.1;

41.1
date     89.12.22.11.42.34;  author jwh;  state Exp;
branches ;
next     40.1;

40.1
date     89.09.29.12.03.35;  author jwh;  state Exp;
branches ;
next     39.1;

39.1
date     89.09.26.16.48.36;  author dew;  state Exp;
branches ;
next     38.1;

38.1
date     89.08.29.11.39.56;  author jwh;  state Exp;
branches ;
next     37.1;

37.1
date     89.05.12.11.53.30;  author dew;  state Exp;
branches ;
next     36.1;

36.1
date     89.02.06.10.30.51;  author dew;  state Exp;
branches ;
next     35.1;

35.1
date     89.02.02.13.49.03;  author dew;  state Exp;
branches ;
next     34.1;

34.1
date     89.01.23.16.22.39;  author jwh;  state Exp;
branches ;
next     33.1;

33.1
date     89.01.16.11.53.07;  author dew;  state Exp;
branches ;
next     32.1;

32.1
date     89.01.10.12.03.39;  author bayes;  state Exp;
branches ;
next     31.1;

31.1
date     88.12.14.18.24.16;  author bayes;  state Exp;
branches ;
next     30.1;

30.1
date     88.12.09.14.01.07;  author dew;  state Exp;
branches ;
next     29.1;

29.1
date     88.10.31.15.45.36;  author bayes;  state Exp;
branches ;
next     28.1;

28.1
date     88.10.06.11.11.08;  author dew;  state Exp;
branches ;
next     27.1;

27.1
date     88.09.29.11.55.21;  author bayes;  state Exp;
branches ;
next     26.1;

26.1
date     88.09.28.14.24.11;  author bayes;  state Exp;
branches ;
next     25.1;

25.1
date     88.03.02.09.52.17;  author bayes;  state Exp;
branches ;
next     24.1;

24.1
date     87.08.31.10.27.59;  author jws;  state Exp;
branches ;
next     23.1;

23.1
date     87.08.26.11.18.45;  author bayes;  state Exp;
branches ;
next     22.1;

22.1
date     87.08.17.11.57.20;  author bayes;  state Exp;
branches ;
next     21.1;

21.1
date     87.08.12.14.39.57;  author bayes;  state Exp;
branches ;
next     20.1;

20.1
date     87.07.30.11.51.03;  author bayes;  state Exp;
branches ;
next     19.1;

19.1
date     87.06.01.09.08.34;  author jws;  state Exp;
branches ;
next     18.1;

18.1
date     87.05.20.16.09.38;  author bayes;  state Exp;
branches ;
next     17.1;

17.1
date     87.04.30.11.12.22;  author jws;  state Exp;
branches ;
next     16.1;

16.1
date     87.04.26.16.21.49;  author jws;  state Exp;
branches ;
next     15.1;

15.1
date     87.04.13.10.05.33;  author jws;  state Exp;
branches ;
next     14.1;

14.1
date     87.04.01.16.17.46;  author jws;  state Exp;
branches ;
next     13.1;

13.1
date     87.02.28.19.04.05;  author jws;  state Exp;
branches ;
next     12.1;

12.1
date     87.02.02.13.59.23;  author jws;  state Exp;
branches ;
next     11.1;

11.1
date     87.01.19.10.25.27;  author jws;  state Exp;
branches ;
next     10.1;

10.1
date     86.12.24.11.41.59;  author jws;  state Exp;
branches ;
next     9.1;

9.1
date     86.12.12.15.28.06;  author bayes;  state Exp;
branches ;
next     8.1;

8.1
date     86.11.27.12.34.32;  author jws;  state Exp;
branches ;
next     7.1;

7.1
date     86.11.20.14.51.46;  author hal;  state Exp;
branches ;
next     6.1;

6.1
date     86.11.04.18.41.24;  author paws;  state Exp;
branches ;
next     5.1;

5.1
date     86.10.28.17.30.47;  author hal;  state Exp;
branches ;
next     4.1;

4.1
date     86.09.30.20.23.54;  author hal;  state Exp;
branches ;
next     3.1;

3.1
date     86.09.01.13.09.41;  author hal;  state Exp;
branches ;
next     2.1;

2.1
date     86.07.30.15.23.28;  author hal;  state Exp;
branches ;
next     1.1;

1.1
date     86.06.30.17.38.11;  author danm;  state tmp;
branches ;
next     ;


desc
@Base file for PWS 3.2 release.

@


56.3
log
@
pws2rcs automatic delta on Wed Jan 27 13:14:25 MST 1993
@
text
@\pause on
\format
\pageno
\spec
  PASCAL Opt. 715
  PASCAL 1.0 I/O System Internal Docs
  Don Cameron                12-Feb-82
				       40
			  A-98261-90405
\head"PASCAL 1.0 I/O System Internal Docs (RAM:12-Feb-82)"
\sect"5-"
\right b
Hewlett-Packard Company Confidential
Desktop Computer Division
R&D Lab I Sec. 2

\center b
Chapter 5:  I/O System Internal Documentation
---------------------------------------------



\image b
This document describes
  1. The compiler-file system interface
  2. The internal structure of a Pascal file variable
  3. Some aspects of I/O support routines which are unique
     to HP Standard Pascal

FILE INFORMATION BLOCK

The storage associated with a Pascal file variable is viewed by the
system as a File Information Block (FIB).  An FIB associates a Pascal
file variable with a mass storage file or a device such as a printer
or CRT.

Actual declarations of types used to declare type FIB can be accessed
by unassembling the interface text of modules Sysglobals and Fs in
*SYSTEM.LIBRARY.

\need 35
An FIB is declared as

\image b
TYPE
  FIB = RECORD
	  CASE SOURCETYPE OF
	    STRG: (FSTRG: STRING255);
	    PHILE:
	      (FWINDOW: WINDOWP;
	       FLISTPTR: FIBP;
	       FREADABLE,
	       FWRITEABLE,
	       FEOF,
	       FEOLN: BOOLEAN;
	       FSTATE: (FNEEDCHAR,FGOTCHAR);
	       FGETOK,
	       FISTEXTVAR:
		  BOOLEAN;
	       FRECSIZE: SHORTINT;
	       CASE FISOPEN: BOOLEAN OF
		 TRUE:
		   (FISBLKD: BOOLEAN;
		    FUNIT: UNITNUM;
		    FVID: VID;
		    FREPTCNT,
		    FNXTBLK,
		    FMAXBLK: SHORTINT;
		    FMODIFIED:BOOLEAN;
		    FHEADER: DIRENTRY;
		    FNXTBYTE,FMAXBYTE: SHORTINT;
		    FBUFCHNGD: BOOLEAN;
		    CASE FSOFTBUF: BOOLEAN OF
		      TRUE:
			(FBUFFER: PACKED ARRAY [0..FBLKSIZE] OF CHAR)))
	  END; {FIB}


\need 3
Sourcetype      Discriminates between file variables, used in 'normal'
		I/O, and strings, used in calls on the standard procedures
		Strread and Strwrite.

Fstrg           Destination string for Strwrite; source string for Strread.

\need 3
Fwindow         Pointer to the lookahead buffer associated with the FIB.
		The buffer consists of Frecsize bytes and holds one file
		component.

\need 24
Flistptr        Pointer to next FIB in a linked LIFO list.  This list
		is used to close a routine's files when the routine
		terminates via normal exit, Escape, or nonlocal GOTO.
		FIB's on the Pascal stack should be placed on this list
		at routine entry.  Non-stack file variables such as those
		in the heap must NOT be placed on this list.

		For an FIB whose address is -588(a6),
		a code sequence to add the FIB to the list is

\image b
			lea -588(a6),a0
			move.l sysglobals-6(a5),4(a0)
			move.l a0,sysglobals-6(a5)

		FIB's on this list should be removed prior to routine exit
		by the sequence

\image b
			move.l xx,-(sp)
			jsr asm_closefiles

		where xx is an address > that of any local FIB's,
		and <= the value SP will have after the routine exits.

Freadable       True if file may be used for input.

Fwriteable      True if file may be used for output.

\need 3
Feof            End-of-file indicator.  For output files and closed files
		Feof is always true.  For input files Feof becomes true
		when end-of-file is encountered during an input operation.

\need 2
Feoln           True if end-of-line was the last character read from a text
		file.  Only valid for text file variables.

\need 2
Fstate          Fneedchar implies that the window is currently empty, while
		Fgotchar indicates that the current record is in the window.

\need 3
Fgetok          If true, a reference to the file window variable will
		replace the current contents of the window with the next
		component of the file.  False inhibits this action.

Fistextvar      True if file variable is of type Text.

\need 2
Frecsize        Size of a file component, in bytes.  For FILE OF <type>,
		Frecsize = Sizeof(<type>).

\need 2
Fisopen         True if the file variable has an association with an
		external file or device.

\need 4
Fisblkd         True if the associated file is on a blocked device.
		Mass storage devices such as disks are divided into
		512 byte blocks, while devices such as printers, the
		CRT and keyboard are unblocked.

Funit           System logical unit number associated with the file.

Fvid            Volume name associated with the file.

Freptcnt        Used by system in handling text file blank compression.

\need 2
Fnxtblk         Next relative block to access.  Relative block numbers
		begin with zero.

Fmaxblk         Highest-numbered relative block ever accessed.

Fmodified       True if file has been modified during this association.

\need 4
Fheader         Copy of the associated file's directory entry.  For the
		declaration of a Direntry, see the internal documentation
		on Directory Management, or unassemble Sysglobals interface
		text as suggested above.

Fnxtbyte        Next relative byte to be accessed in Fnxtblk.

Fmaxbyte        Highest-numbered relative byte ever accessed in Fmaxblk.

\need 2
Fbufchngd       True if block now in memory buffer Fbuffer must be written
		to the file.

\need 3
Fsoftbuf        True if file has memory buffer.  Files on unblocked
		devices or untyped file variables (i.e., UCSD type FILE)
		do not have memory buffers.

Fbuffer         Memory buffer area; 512 bytes.


\new
SYSTEM FILE-HANDLING ROUTINES

a. Initialization procedures

   procedure FINITB (var f: fib; window: windowp; recbytes: integer)

     Module: FS

     Initializes F to known state indicating no association with external
     file.  Effects on F:

\image b
       Fisopen := False
       Fwindow := Window
       Fistextvar := (Recbytes = -3)
       if Frecbytes >= 0 then Frecsize := Recbytes
       else if Recbytes := -1 then  {UCSD type FILE}
	 begin Fwindow := nil; Frecsize := 0 end
       else Frecsize := 1;  { text, file of char, etc. }


   procedure FINIT (var f: fib; window: windowp; recwords: integer)

     Module: FS

     Identical to Finit except that record size is in words (1 word =
     2 bytes).  Retained for compatibility with output of pre-Feb 1982
     compilers.


\new
b. Associative procedures

The following procedures create or sever the association between
an FIB and an external file or device.

   procedure FOPEN (var f: fib; var ftitle: string80; typ: faccess)

\image b
     type string80 = string[80]
	  faccess  = (readonly,writeonly,readwrite)

     Module: FS

     Opens file with name Ftitle and associates it with F.  Ftitle is
     a FILE SPECIFICATION (for syntax, see Pascal Language System User's
     Manual, p. 155).

\image b
     Action taken by Fopen depends on the value of Typ.
     Writeonly requests the creation of a new, or 'temporary' file.
     Readonly requests the opening of an old, or 'permanent' file.
     If Typ is Readwrite, Fopen creates a new file if an old one
     does not exist.

     Note: the compiler emits calls to the procedures Fhpopen and Fhpreset
	   rather that Fopen.

\image
     Error conditions:
       Fisopen = true
       Ftitle does not conform to the syntax of a file specification
       Volume specified by Ftitle not on line
       Typ = Readonly and file specified by Ftitle does not exist
       Typ = Writeonly and a new file of same name already exists
	     (each volume may only have one temporary file with a
	      given name).
       Typ = Readwrite and an old file exists, but its type is Text
       Typ = Readwrite, Ftitle includes a size specification, and an
	     old file exists which can not be extended to the
	     specified size (cf. function Cantstretch).
       Typ = Readwrite, an old file does not exist, and Ftitle
	     includes a '.Text' suffix
       Typ = Readwrite, an old file does not exist and a new file of
	     same name already exists.
\format
       Volume specification indicates a blocked device, the medium has no
	     directory, and the file name portion of Ftitle is non-null.  If the
	     medium has no directory, the volume may be opened (e.g., as '#20:'),
	     but a file on the volume cannot be.


\need 4
   procedure FRESET (var f: fib)

     Module: FS

     'Rewinds' the file associated with F.  Does nothing if Fisopen is false.


\need 22
   procedure FHPOPEN (var f: fib; typ: faccess; var title: string80)

\image b
     Pascal equivalent: Open (f,title)
			Reset (f,title)
			Rewrite (f,title)

     Module: FS

     The compiler emits a call to this procedure when it encounters a
     Reset, Rewrite, or Open reference with the file name parameter included.
     Title is a file specification.  Fhpopen severs the current association
     of F (if any), calls Fopen, and sets the following fields in F.

\image
		   Feof            Fgetok          Freadable       Fwriteable
     ------------------------------------------------------------------------
       Reset       false           true            true            false

       Rewrite     true            false           false           true

       Open        false           false           true            true

\format
     Fstate is set to Fneedchar except for UCSD type FILE.


\need 15
   procedure FHPRESET (var f: fib; typ: faccess; istextfile: boolean)

\image b
     Pascal equivalent: Open (f)
			Reset (f)
			Rewrite (f)

     Module: FS

     The compiler emits a call to this procedure when it encounters a
     Reset, Rewrite, or Open reference with the file name parameter omitted.
     If F has a current association (i.e., Fisopen is true), the file is
     rewound by calling Freset.  If there is no current association, Fopen
     is called to create a new file with a file specification of the form
     '@@ <integer> [*]'  (this is the Pascal scratch file mechanism).
     Fhpreset concludes by setting selected FIB fields as in Fhpopen above.


\need 24
   procedure FCLOSE (var f: fib; ftype: closetype)

     type closetype = (cnormal,lock,purge,ccrunch)

     Module: FS

     Severs the connection between F and an external file, closing the file.
     Ftype has the following meaning.

     Cnormal - Remove a new file; close an old one.

     Lock    - Make a new file permanent, adjusting its size so that the
	       highest block accessed becomes the last block of the file.
	       Close an old file.

     Purge   - Remove old or new file.

     Ccrunch - Adjust the size of a permanent file so that the highest block
	       accessed during the current association becomes the last block
	       of the file.  Lock a new file.

\image b
     Error conditions:
       Volume no longer on line.
       File no longer in directory


\need 16
   procedure FCLOSEIT (var f: fib; stype: string255)

     Pascal equivalent: Close (f,stype)

     Module: FS

     The compiler emits a call to this procedure upon encountering a
     reference to Close.  Fcloseit maps Stype into a Closetype and
     calls Fclose.

     Stype maps as follows:

\image b
       'normal', 'temp' => Cnormal
       'lock', ' save'  => Lock
       'purge'          => Purge
       'crunch'         => CCrunch


\new
c. Functions

\need 11
   function FPOSITION (var f: fib): boolean

     Pascal equivalent: Position (f)

     Module: FS

     Returns the index of the current component of the file associated
     with F.  Component numbers begin with 1.

\image b
     Error condition
       Fisopen = false


\need 15
   function FMAXPOS (var f: fib): boolean

     Pascal equivalent: Maxpos (f)

     Module: FS

     Returns the number of the last component of the file associated
     with F.  For a permanent file, Fmaxpos is the highest-numbered
     component ever accessed.  For a new file it is the highest-numbered
     component which may be accessed without increasing the file size.

\image b
     Error conditions
       Fisopen = false
       Freadable = false or Fwriteable = false (i.e., file is not open
		     for direct access)


\need 20
   function FEOF (var f: fib): boolean

     Pascal equivalent: Eof (f)

     Module: FS

     Returns the value of F.Feof.  For files open for direct access, F.Feof
     is defined as Fposition(f) > Fmaxpos(f).  For UCSD type FILE, F.Feof
     is determined by the most recent call on Fblockio.  For typed files
     open for writing, F.Feof is always true.

     F.Feof is true for typed files open for reading if the next component
     of the file does not exist.  If Fstate = Fgotchar, the next component
     exists and is in the file window.  Otherwise procedure Look is called
     to try to read the next component.  This 'look-ahead' is omitted if
     Funit is 1 or 2, indicating the keyboard device.  Consequently EOF can
     never be true for the keyboard.

     There are no error conditions local to Feof; any errors are generated
     by called routines (cf. Fmaxpos, Fposition, Look).


\need 14
   function FEOLN (var f: fib): boolean

     Pascal equivalent: Eoln (f)

     Module: FS

     Returns the value of F.Feoln.  Will return true if the most recent
     character read from the file is the end-of-line marker (chr(13)).
     If Fstate = Fneedchar, procedure Look will be called to read
     the next component unless Funit = 1 or 2.  Applicable only to
     text files.

     No errors are generated locally, but error conditions may be detected
     by procedure Look.


\need 10
   function CANTSTRETCH (var f: fib): boolean

     Module: FS

     Returns true if the file associated with F cannot be extended beyond
     the current end-of-file.  If false is returned, any adjacent free
     blocks following the file have been appended to it.  Note that false
     is returned even if there are no adjacent free blocks, if Fmaxbyte
     is less than Fblksize (indicating space available in the last block).


\new
d. Miscellaneous I/O routines

\need 14
   procedure FPUT (var f: fib)

     Pascal equivalent: Put (f)

     Module: FS

     Writes the current file window contents (Fwindow^[0..Frecsize-1])
     to the file at the current file position, and increments the position.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       No room in file for another component and file cannot
	 be extended (cf. function Cantstretch)


\need 49
   procedure LOOK (var f: fib)

     Module: FS

     If the current file position is beyond end-of-file as given by
     (Fmaxblk,Fmaxbyte) then Feof is set; otherwise Frecsize
     bytes are read from the current file position into Fwindow^.
     If Fistextvar is true then 1 byte is read and the following
     values are treated specially.

       chr(13) = end-of-line character.  Feoln is set and the window
		 Fwindow^[0] is set to blank (chr(32)).

       chr(16) = start of a blank compression sequence, provided Funit
		 is not 1 or 2 (i.e., not the keyboard device).  The window
		 is set to blank and subsequent calls on Look leave the
		 window unchanged until the count of blanks (Freptcnt)
		 is exhausted.

       chr(0) = If the file is a buffered text file (Fsoftbuf=true
		and Fheader.Dfkind = Textfile) the byte begins the zero
		fill which ends a 2 block textfile page.  The file
		pointers (Fnxtblk,Fnxtbyte) are adjusted to index
		the start of the following block and another read is
		attempted.
		Otherwise, receiving a null implies end-of-file and
		Feof is set.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Feof is true on entry

\image
     Effect of Fgetok:
\format
       If Fgetok is false on entry to Look, no read is performed.  This
       condition occurs if the window has been loaded previously and its
       contents have not been used.  Consider the program fragment
\image
		reset(f);
		while not (eof(f) and eoln(f)) do ...
\format
       After the first read Eof will call Look to 'look ahead'.
       Eoln will also call Look, but now the desired byte
       is already in the window and the state of Feoln has
       already been determined.  Hence Look must be inhibited
       from reading and discarding the current window contents.

       Fgetok is always set to false before exiting Look.


\need 16
   procedure FGET (var f: fib)

     Pascal equivalent: Get (f)

     Module: FS

     Discards the current file component and advances the file position.
     If Fstate = Fneedchar then procedure Look is called to perform the
     advance; otherwise, the advance has already occurred..
     In either case the window contents are then 'thrown away' by setting
     Fstate to Fneedchar.  Also, Fgetok is set.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Feof is true on entry


\need 13
   function FBUFFERREF (var f: fib): windowp;

     Pascal equivalent: F^

     Module: FS

     Returns the address of the file window Fwindow.  If Freadable is true
     the routine attempts to load the next component of the file into
     Fwindow, using procedure Look.

\image b
     Error conditions
       Fisopen is false
       Freadable is true and Feof is true


\need 24
   function FBLOCKIO (var f: fib; var a: window;
			  nblocks,rblock: integer; doread: boolean): integer

     Pascal equivalent: Blockread (f,a,k,r)
			Blockwrite (f,a,k,r)

     Module: FS

     Transfers Nblocks 512-byte blocks between the file associated
     with F and memory starting at addr(A).  Rblock specifies the
     relative block number in the file, starting with zero.  If Rblock
     is negative a sequential transfer is performed, i.e., the transfer
     begins with the block number given by Fnxblk.  Doread specifies the
     direction of transfer.

     The returned value specifies the number of blocks actually transferred.
     Normally the returned value equals Nblocks unless end-of-file is en-
     countered.  If this happens during a read, Feof is set.   During a
     write, EOF causes the routine to call Cantstretch to extend the file
     and the write is retried; if EOF occurs again Feof is set.

\image b
     Error conditions:
       Fisopen is false
       see also Unitread/Unitio error conditions


\need 26
   procedure FSEEK (var f: fib; recnum: integer)

     Pascal equivalent: Seek (f,recnum)

     Module: MFS

     Operates on direct access files only (Freadable and Fwriteable both set).
     Positions the file so that the component with index Recnum is the
     next to be read or written.  Component indices begin with 1.
     The file position is computed assuming Frecsize is the component
     size; a 512-byte block may not contain any partial components.

\image b
     The following fields in F are set by Fseek:
       Feof   :=  False
       Fstate :=  Fneedchar
       Fgetok :=  False

\image b
     Error conditions
       Fisopen is false
       Freadable is false or Fwriteable is false.
       Fheader.Dfkind = Textfile
       Fsoftbuf is false (i.e., the file must be on a blocked device
	 and may not be a UCSD type FILE)
       Attempting to seek beyond EOF and the file cannot be extended
	 sufficiently


\need 15
   procedure FWRITEBIN (var f: fib; var x: integer)

\image b
     Pascal equivalent: Write (f,a)  where f is a file of type T and
					   a is a variable of type T

     Module: MFS

     Moves Frecsize bytes from memory starting at addr(x) to the
     file and advances the file position.  Uses Fput.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       No room in file for another component and file cannot
	 be extended (cf. function Cantstretch)


\need 14
   procedure FREADBIN (var f: fib; var x: integer)

\image b
     Pascal equivalent: Read (f,a)  where f is a file of type T and
					  a is a variable of type T

     Module: MFS

     Moves Frecsize bytes from the file to memory starting at addr(x)
     and advances the file position.  Uses Look.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true on entry
	 (i.e., there must be a component to read)


\new
e. Text file I/O routines

   Text file I/O involves conversion between the internal form of a value
   and its external representation.  For output a field width parameter
   is included and the external representation of a value is written
   right-justified in a field of the specified width, preceded by blanks
   if needed.   If the field width is too small, strings, packed
   arrays of character, and enumerated constants are truncated.  A field
   width parameter of -1 specifies default width.

\need 18
   procedure FWRITEINT (var f: fib; i: integer; rleng: shortint)

     type shortint = -32768..32767   n.b. subranges of integer are
				     allocated 2 bytes if possible.

     Pascal equivalent: Write (f,i:rleng)

     Module: FS

     Converts the 4-byte integer I to its character representation and
     writes it to the file associated with F, right-justified in a field
     of width Rleng.  Default field width is 12.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)




\need 15
   procedure FWRITEWORD (var f: fib; i,rleng: shortint)

     Pascal equivalent: Write (f,i:rleng)

     Module: FS

     Converts the 2-byte integer I to its character representation and
     writes it to the file associated with F, right-justified in a field
     of width Rleng.  Default field width is 12.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 14
   procedure FWRITECHAR (var f: fib; ch: char; rleng: shortint)

     Pascal equivalent: Write (f,ch:rleng)

     Module: FS

     Writes the character Ch to the file associated with F, right-justified
     in a field of width Rleng.  Default field width is 1.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 7
   procedure FPAGE (var f: text)

     Pascal equivalent: Page (f)

     Module: FS

     Identical to Fwritechar (f,chr(12),1)


\need 17
   procedure FWRITEREAL (var f: fib; x: real; w,d: shortint)

     Pascal equivalent: Write(f,x:w:d)

     Module: MFS

     Converts x to a character representation as specified by
     D and writes it to the file associated with F, right-justified
     in a field of width W.  D = -1 specifies scientific notation, while
     D >= 0 requests a fixed point representation with D digits to the
     right of the decimal point.  The default field width is 12.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 15
   procedure FWRITESTR (var f: fib; anyvar s: string80; rleng: shortint)

     Pascal equivalent: Write(f,s:rleng);

     Module: FS

     Writes S[1..Min(Strlen(S),Rleng)] to the file associated with F,
     right-justified in a field of width Rleng.  The default field
     width is Strlen(S).

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 15
   procedure FWRITEPAOC (var f: fib; var a: window; aleng,rleng: shortint)

     Pascal equivalent: Write (f,p:rleng)
			where p is a packed array [1..aleng] of char

     Module: FS

     Writes A[1..min(aleng,rleng)] to the file associated with F, right-
     justified in a field of width Rleng.  The default field width is Aleng.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 44
   procedure FWRITEENUM (var f: fib; i: shortint; rleng: shortint; p: vptr)

     Pascal equivalent: Write(f,e:rleng) where e is an expression of an
			enumerated type

     Module: MFS

     Writes the external representation of I to the file associated with
     F, right-justified in a field of width Rleng.  If Rleng is >= 0, exactly
     Rleng characters are written (i.e., the external representation may
     be truncated).  The default field width is the width of the enumerated
     constant to be written.  P is the 4-byte address of a table containing
     the external representations of values of an enumerated type.  I is used
     to select the entry in the table to be written.

     There is a mapping between objects of an enumerated type and the
     non-negative integers 0,1,2,... such that for a Pascal type declared as
\image
	 Type Color = (Red,Green,Blue)
\format
     the internal representations of the constants Red, Green, and Blue are
     0, 1 and 2 respectively.

     The first 2 bytes of the table addressed by P contain a 2-byte
     integer specifiying the number of entries in the table.  The entries
     follow in reverse order: byte 3 begins the entry with highest index.
     Each entry is in the form of an object of type String: a length byte
     followed by the external representation of an enumerated constant.
     The entries are contiguous but no entry may start on an odd boundary.
     For type Color the bytes of the table are as follows

\image b
	      Offset  0 1   2  3456  7 8  90123  4  567
	      Value   0 3   4 'BLUE' 0 5 'GREEN' 3 'RED'

     If this is confusing, write a Pascal program containing the type
     declaration for which a table is desired and call the standard
     procedure Write to write one of the type's values.  An Unassembly
     of the program will contain a copy of the table.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 16
   procedure FWRITEBOOL (var f: fib; b: boolean; rleng: shortint)

     Pascal equivalent: Write (f,b:rleng);

     Module: MFS

     Writes the literal 'FALSE' or 'TRUE' to the file associated with
     F according to the value of B.  The literal is right-justified
     in a field of width Rleng; if Rleng is >= 0, exactly Rleng characters
     are written.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 14
   procedure FWRITELN (var f: fib)

     Pascal equivalent: Writeln(f)

     Module: FS

     Writes an end-of-line marker to the file associated with F.
     Equivalent to Fwritechar(f,chr(13),1);

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 32
   procedure FREADINT (var f: fib; var i: integer; stype: sourcetype)

     type sourcetype = (phile,strg)

     Pascal equivalent: Read (f,i)

     Module: FS

     Reads characters from F expecting the syntax of an <integer number>.
     The syntax is

\image b
	  <integer number> ::= <sign> <unsigned integer>
	  <unsigned integer> ::= <digit sequence>
	  <digit sequence> ::= <digit> {<digit>}
	  <digit> ::= 0|1|2|3|4|5|6|7|8|9
	  <sign> ::= + | - | <empty>
	  <empty> ::=

     where { <x> } means "0 or more occurences of <x>".  Leading blanks
     and end-of-lines are skipped.  The number is converted to internal
     form and assigned to the 4-byte integer I.  Sourcetype should be Phile;
     to convert from a string to an integer, see Freadstrint below.

     On exit, Fstate = Fgotchar and Fgetok = False since an additional
     character not included in the integer has been loaded into Fwindow.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true
       Character sequence violates syntax of <integer number>
       Integer value not in range -2^31..2^31-1


\need 8
   procedure FREADWORD (var f: fib; var i: shortint)

     Pascal equivalent: Read (f,i)

     Module: FS

     Analog of Freadint for 2-byte integers.  The value read must be
     in the range -32768..32767.


\need 49
   procedure FREADCHAR (var f: fib; var ch: char)

     Pascal equivalent: Read (f,ch)

     Module: FS

     Reads the next character from F and assigns is to Ch.  On exit,
     Fgetok is true and Fstate = Fneedchar.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true on entry


   procedure FREADREAL (var f: fib; var x: real; stype: sourcetype)

     Pascal equivalent: Read (f,x)

     Module: MFS

     Scans characters from F expecting a sequence which conforms to the
     syntax for a <real number>.  Leading blanks and end-of-lines are
     skipped.  The syntax is (cf. Freadint above)

\image b
	  <real number> ::= <sign><input real number><exponent>
	  <input real number> ::= . <digit sequence> |
				  <unsigned integer>.<digit sequence> |
				  <unsigned integer> |
				  <unsigned integer> .
	  <exponent> ::= E <scale factor> | L <scale factor>| E | L |
			 <empty>
	  <scale factor> ::= <integer number>

     The resulting string is converted to internal form and assigned to X.
     Sourcetype should be Phile; to convert from a string to a real, see
     Freadstrreal below.

     On exit, Fstate = Fgotchar and Fgetok = False since an additional
     character not included in the number has been loaded into Fwindow.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true
       Sequence read does not conform to syntax for <real number>
       Absolute value of number outside the range
	       2.22507385850720E-308 .. 1.79769313486231E+308
       Too many characters in <real number>


\need 21
   procedure FREADSTR (var f: fib; var s: string)

     Pascal equivalent: Read (f,s)

     Module: FS

     Reads characters from F until Strmax(S) characters are read
     or end-of-line or end-of-file is encountered (however, if Funit
     is 1 then end-of-line is the only terminator).  The resulting
     string (NOT including any end-of-line terminator) is assigned
     to S.

     If Feoln is true on entry because end-of-line terminated a previous
     string or PAOC read then the end-of-line is skipped and the read
     proceeds with the next character.  Otherwise no characters are read
     and the null string is assigned to S.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true on entry


\need 23
   procedure FREADPAOC (var f: fib; var a: paoc; aleng: shortint)

\image b
     Pascal equivalent: Read (f,p)
			where p is a packed array [1..aleng] of char

     Module: MFS

     Reads characters from F until Aleng characters are read or
     end-of-line or end-of-file is encountered (however, if Funit
     is 1 then end-of-line is the only terminator).  The resulting
     character sequence (NOT including any end-of-line terminator) is
     assigned to A; if the sequence contains less than Aleng characters
     then A is padded on the right with blanks.

     If Feoln is true on entry because an end-of-line terminated a previous
     PAOC or string read then the end-of-line is skipped and the read proceeds
     with the next character.  Otherwise no characters are read and A is set
     to all blanks.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true on entry


\need 23
   procedure FREADENUM (var f: fib; var i: shortint;
			p: vptr; stype: sourcetype)

     Pascal equivalent: Read (f,e) where e is a variable of an enumerated type.

     Module: MFS

     Reads a sequence of characters from F according to the syntax of
     a Pascal identifier and attempts to match the identifier with an entry
     in the table addressed by P (cf. Fwriteenum above for the table
     structure).  Leading blanks and end-of-lines are skipped.  If a match
     is found the entry's index is assigned to I; otherwise, a value range
     error ( Escape(-8) ) is generated.  Alphabetic characters read are
     converted to upper case prior to the table search.  Stype should be
     Phile; to convert from a string to an enumerated value, see Freadstrenum
     below.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true on entry
       Character sequence from F not an identifier
       Identifier read fails to match any table entry


\need 21
   procedure FREADBOOL (var f: fib; var b: boolean; stype: sourcetype)

     Pascal equivalent: Read (f,b)

     Module: MFS

     Reads a sequence of characters from F according to the syntax of
     a Pascal identifier and attempts to match the identifier with the
     strings 'TRUE' and 'FALSE'.  Leading blanks and end-of-lines are skipped.
     If a match is found the corresponding Boolean value is assigned to B;
     otherwise, a value range error is generated.  Alphabetic characters
     read are converted to upper case prior to the match.  Stype should be
     Phile; to convert from a string to a Boolean value, see Freadstrbool
     below.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true on entry
       Character sequence from F not an identifier
       Identifier read fails to match 'TRUE' or 'FALSE'


\need 17
   procedure FREADLN (var f: fib)

     Pascal equivalent: Readln (f)

     Module: FS

     Reads characters from the textfile associated with F until an end-of-line
     character is found.  If Feof is true on entry, no characters are read.
     On exit the file is positioned past the end-of-line by setting the
     following values:
\image b
			 Fstate := Fneedchar
			 Fgetok := True
			 Feoln  := False

\image b
     Error conditions
       Fisopen is false
       Freadable is false



\new
e. Strread/Strwrite support routines

   HP Standard Pascal allows the programmer to access the conversion
   capabilities of textfile I/O independent of any file operations.
   Instead, the external representations of data objects are written
   to or read from a string variable.

   Two standard procedures are provided:

\image b
     Strread (S,P1,P2,<list>)
       where S  is a string containing a character sequence which is the
		external representation of the values to be assigned to
		the variables in <list>
	     P1 is the index in S where the read is to begin
	     P2 is the index in S of the last character read plus one
	     <list> is identical to its counterpart in the standard
		procedure Read

\image b
     Strwrite (S,P1,P2,<list>)
       where S is a string to receive the external representations
		of the values of the variables in <list>.  If the
		length of S is incrementedduring the write
		then Strlen(S) is increased.
	     P1 is the index in S where writing is to begin.
		If P1 > Strlen(S) + 1, it is an error.
	     P2 is the index in S of the last character to be
		written plus one
	     <list> is identical to its counterpart in the
		standard procedure Write


\need 17
   procedure FWRITESTRINT (var t: string; var p2: integer;
			   i: integer; rleng: shortint)

\image
     Pascal equivalent:  Strwrite (t,k,p2,i:rleng)
\format
			   (the compiler generates code to assign K to P2
			    before calling Fwritestrint)

     Module: FS

     Converts the 4-byte integer I to its external representation and
     writes it to T starting at T[P2], right-justified in a field of
     width Rleng.  Default field width is 12.  On exit, P2 is assigned
     the index of the last character written, plus one.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(T)+1 on entry
       P2 > Strmax(T)+1 on exit


\need 16
   procedure FWRITESTRWORD (var s: string; var p2: integer; i,rleng: shortint)

\image
     Pascal equivalent:  Strwrite (s,k,p2,i:rleng)
\format
			   (the compiler generates code to assign K to P2
			    before calling Fwritestrword)

     Module: FS

     Converts the 2-byte integer I to its external representation and
     writes it to S starting at S[P2], right-justified in a field of
     width Rleng.  Default field width is 12.  On exit, P2 is assigned
     the index of the last character written, plus one.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit


\need 15
   procedure FWRITESTRCHAR (var s: string; var p2: integer;
			    ch: char; rleng: shortint)

\image
     Pascal equivalent: Strwrite(s,k,p2,ch:rleng)
\format
			   (the compiler generates code to assign K to P2
			    before calling Fwritestrchar)

     Module: FS

     Writes the character Ch to S starting at S[P2], right-justified in a
     field of width Rleng.  Default field width is 1.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit


\need 18
   procedure FWRITESTRREAL (var r: string; var p2: integer;
			    x: real; w,d: shortint)

\image
     Pascal equivalent: Strwrite(s,k,p2,x:w:d)
\format
			   (the compiler generates code to assign K to P2
			    before calling Fwritestrreal)

     Module: MFS

     Converts x to a character representation as specified by D and
     writes it to S starting at S[P2], right-justified in a field of width W.
     D = -1 specifies scientific notation, while D >= 0 requests a fixed
     point representation with D digits to the right of the decimal point.
     The default field width is 12.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit


\need 15
   procedure FWRITESTRSTR (var s: string; var p2: integer;
			   anyvar t: string255; rleng: shortint)

\image
     Pascal equivalent: Strwrite(s,k,p2,t:rleng)
\format
			   (the compiler generates code to assign K to P2
			    before calling Fwritestrstr)

     Module: FS

     Writes T[1..Min(Strlen(T),Rleng)] to S starting at S[P2], right-justified
     in a field of width Rleng.  The default field width is Strlen(T).

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit


\need 16
   procedure FWRITESTRPAOC (var s: string; var p2: integer;
			    var a: window; aleng,rleng: shortint)

\image
     Pascal equivalent: Strwrite(s,k,p2,p:rleng)
\format
			  where P is a packed array [1..Aleng] of char
			  (the compiler generates code to assign K to P2
			   before calling Fwritestrpaoc)

     Module: FS

     Writes A[1..min(aleng,rleng)] to the file associated with F, right-
     justified in a field of width Rleng.  The default field width is Aleng.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit


\need 22
   procedure FWRITESTRENUM (var s: string; var p2: integer;
			    i,rleng: shortint; p: vptr)

\image
     Pascal equivalent: Strwrite(s,k,p2,e:rleng)
\format
			  where e is an expression
			  of an enumerated type
			  (the compiler generates code to assign K to P2
			   before calling Fwritestrenum)

     Module: MFS

     Writes the external representation of I to S starting at S[P2],
     right-justified in a field of width Rleng.  If Rleng is >= 0, exactly
     Rleng characters are written (i.e., the external representation may
     be truncated).  The default field width is the width of the enumerated
     constant selected.  P is the 4-byte address of a table containing
     the external representations of values of an enumerated type (cf.
     Fwriteenum above for the table structure).  I is used to select the
     table entry.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit

\need 17

   procedure FWRITESTRBOOL (var s: string; var p2: integer;
			    b: boolean; rleng: shortint)

\image
     Pascal equivalent: Strwrite(s,k,p2,b:rleng)
\format
			   (the compiler generates code to assign K to P2
			    before calling Fwritestrbool)

     Module: MFS

     Writes the literal 'FALSE' or 'TRUE' to S starting at S[P2].  The
     desired literal is selected by B and written right-justified in
     a field of width Rleng; if Rleng >= 0, exactly Rleng characters
     are written.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit



\need 16
   procedure FREADSTRINT (anyvar s: string255; var p2,i: integer)

\image
     Pascal equivalent: Strread(s,k,p2,i)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrint)

     Module: FS

     Reads characters from S starting at S[P2] expecting the syntax
     of an <integer number> (cf. Freadint above).  Leading blanks
     and end-of-lines are skipped.

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry
       Character sequence violates syntax of <integer number>
       Integer value not in range -2^31..2^31-1


\need 10
   procedure FREADSTRWORD (var s: string255; var p2: integer; var i: shortint)

\image
     Pascal equivalent: Strread(s,k,p2,i)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrword)

     Module: FS

     Analog of Freadstrint for 2-byte integers.  The value read must lie
     in the range -32768..32767.


\need 12
   procedure FREADSTRCHAR (var s: string255; var p2: integer; var ch: char)

\image
     Pascal equivalent: Strread(s,k,p2,ch)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrchar)

     Module: FS

     Essentially, Ch := S[P2]; P2 := P2+1.

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry


\need 23
   procedure FREADSTRREAL (var s: string255; var p2: integer; var x: real)

\image
     Pascal equivalent: Strread(s,k,p2,x)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrreal)

     Module: MFS


     Scans characters starting at S[P2] expecting a sequence which conforms
     to the syntax for a <real number> (cf. Freadreal above).  Leading blanks
     and end-of-lines are skipped.

     The resulting string is converted to internal form and assigned to X.
     Sourcetype should be Phile; to convert from a string to a real, see
     Freadstrreal below.

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry
       Sequence read does not conform to syntax for <real number>
       Absolute value of number outside the range
	       2.22507385850720E-308 .. 1.79769313486231E+308
       Too many characters in <real number>


\need 16
   procedure FREADSTRSTR (var t: string255; var p2: integer; var s: string)

\image
     Pascal equivalent: Strread(t,k,p2,s)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrstr)

     Module: FS

     Moves characters from T starting at T[P2] to the string S and
     sets the length of S.  An end-of-line character in T terminates
     the move and P2 is positioned past the end-of-line.  Otherwise,
     Min (Strlen(S),Strlen(T)-P2+1) characters are moved (i.e., S
     is filled if T has enough characters to do so).

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry


\need 17
   procedure FREADSTRPAOC (var s: string255; var p2: integer;
			   var a: paoc; aleng: shortint)

\image
     Pascal equivalent: Strread(s,k,p2,a)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrpaoc)

     Module: MFS

     Moves Aleng characters from S starting at S[P2] to A.  If Strlen(S)-P2+1
     is less than Aleng or an end-of-line character is encountered in S before
     Aleng characters have been moved, then P is padded on the right with
     blanks.  If an end-of-line in S terminates the move, P2 is positioned
     past the end-of-line.

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry


\need 21
   procedure FREADSTRENUM (var s: string255; var p2: integer;
			   var i: shortint; p: vptr)

\image
     Pascal equivalent: Strread(s,k,p2,e)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrenum)

     Module: MFS

     Reads a sequence of characters from S starting at S[P2] according to the
     syntax of a Pascal identifier and attempts to match the identifier with
     an entry in the table addressed by P (cf. Fwriteenum above for the table
     structure).  Leading blanks and end-of-lines are skipped.  If a match
     is found the entry's index is assigned to I; otherwise, a value range
     error ( Escape(-8) ) is generated.  Alphabetic characters read are
     converted to upper case prior to the table search.

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry
       Character sequence from S not an identifier
       Identifier read fails to match any table entry


\need 20
   procedure FREADSTRBOOL (var s: string255; var p2: integer; var b: boolean)

\image
     Pascal equivalent: Strread(s,k,p2,b)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrbool)

     Module: MFS

     Reads a sequence of characters from S starting at S[P2] according to
     the syntax of a Pascal identifier and attempts to match the identifier
     with one of the strings 'TRUE' and 'FALSE'.  Leading blanks and
     end-of-lines are skipped.  If a match is found the corresponding
     Boolean value is assigned to B; otherwise, a value range error is
     generated.  Alphabetic characters read are converted to upper case
     prior to the match.

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry
       Character sequence from S not an identifier
       Identifier read fails to match 'TRUE' or 'FALSE'


\center b
				   * * * * *

@


56.2
log
@
pws2rcs automatic delta on Wed Jan 27 11:57:27 MST 1993
@
text
@d1 1539
@


56.1
log
@Automatic bump of revision number for PWS version 3.25
@
text
@a0 1539
\pause on
\format
\pageno
\spec
  PASCAL Opt. 715
  PASCAL 1.0 I/O System Internal Docs
  Don Cameron                12-Feb-82
				       40
			  A-98261-90405
\head"PASCAL 1.0 I/O System Internal Docs (RAM:12-Feb-82)"
\sect"5-"
\right b
Hewlett-Packard Company Confidential
Desktop Computer Division
R&D Lab I Sec. 2

\center b
Chapter 5:  I/O System Internal Documentation
---------------------------------------------



\image b
This document describes
  1. The compiler-file system interface
  2. The internal structure of a Pascal file variable
  3. Some aspects of I/O support routines which are unique
     to HP Standard Pascal

FILE INFORMATION BLOCK

The storage associated with a Pascal file variable is viewed by the
system as a File Information Block (FIB).  An FIB associates a Pascal
file variable with a mass storage file or a device such as a printer
or CRT.

Actual declarations of types used to declare type FIB can be accessed
by unassembling the interface text of modules Sysglobals and Fs in
*SYSTEM.LIBRARY.

\need 35
An FIB is declared as

\image b
TYPE
  FIB = RECORD
	  CASE SOURCETYPE OF
	    STRG: (FSTRG: STRING255);
	    PHILE:
	      (FWINDOW: WINDOWP;
	       FLISTPTR: FIBP;
	       FREADABLE,
	       FWRITEABLE,
	       FEOF,
	       FEOLN: BOOLEAN;
	       FSTATE: (FNEEDCHAR,FGOTCHAR);
	       FGETOK,
	       FISTEXTVAR:
		  BOOLEAN;
	       FRECSIZE: SHORTINT;
	       CASE FISOPEN: BOOLEAN OF
		 TRUE:
		   (FISBLKD: BOOLEAN;
		    FUNIT: UNITNUM;
		    FVID: VID;
		    FREPTCNT,
		    FNXTBLK,
		    FMAXBLK: SHORTINT;
		    FMODIFIED:BOOLEAN;
		    FHEADER: DIRENTRY;
		    FNXTBYTE,FMAXBYTE: SHORTINT;
		    FBUFCHNGD: BOOLEAN;
		    CASE FSOFTBUF: BOOLEAN OF
		      TRUE:
			(FBUFFER: PACKED ARRAY [0..FBLKSIZE] OF CHAR)))
	  END; {FIB}


\need 3
Sourcetype      Discriminates between file variables, used in 'normal'
		I/O, and strings, used in calls on the standard procedures
		Strread and Strwrite.

Fstrg           Destination string for Strwrite; source string for Strread.

\need 3
Fwindow         Pointer to the lookahead buffer associated with the FIB.
		The buffer consists of Frecsize bytes and holds one file
		component.

\need 24
Flistptr        Pointer to next FIB in a linked LIFO list.  This list
		is used to close a routine's files when the routine
		terminates via normal exit, Escape, or nonlocal GOTO.
		FIB's on the Pascal stack should be placed on this list
		at routine entry.  Non-stack file variables such as those
		in the heap must NOT be placed on this list.

		For an FIB whose address is -588(a6),
		a code sequence to add the FIB to the list is

\image b
			lea -588(a6),a0
			move.l sysglobals-6(a5),4(a0)
			move.l a0,sysglobals-6(a5)

		FIB's on this list should be removed prior to routine exit
		by the sequence

\image b
			move.l xx,-(sp)
			jsr asm_closefiles

		where xx is an address > that of any local FIB's,
		and <= the value SP will have after the routine exits.

Freadable       True if file may be used for input.

Fwriteable      True if file may be used for output.

\need 3
Feof            End-of-file indicator.  For output files and closed files
		Feof is always true.  For input files Feof becomes true
		when end-of-file is encountered during an input operation.

\need 2
Feoln           True if end-of-line was the last character read from a text
		file.  Only valid for text file variables.

\need 2
Fstate          Fneedchar implies that the window is currently empty, while
		Fgotchar indicates that the current record is in the window.

\need 3
Fgetok          If true, a reference to the file window variable will
		replace the current contents of the window with the next
		component of the file.  False inhibits this action.

Fistextvar      True if file variable is of type Text.

\need 2
Frecsize        Size of a file component, in bytes.  For FILE OF <type>,
		Frecsize = Sizeof(<type>).

\need 2
Fisopen         True if the file variable has an association with an
		external file or device.

\need 4
Fisblkd         True if the associated file is on a blocked device.
		Mass storage devices such as disks are divided into
		512 byte blocks, while devices such as printers, the
		CRT and keyboard are unblocked.

Funit           System logical unit number associated with the file.

Fvid            Volume name associated with the file.

Freptcnt        Used by system in handling text file blank compression.

\need 2
Fnxtblk         Next relative block to access.  Relative block numbers
		begin with zero.

Fmaxblk         Highest-numbered relative block ever accessed.

Fmodified       True if file has been modified during this association.

\need 4
Fheader         Copy of the associated file's directory entry.  For the
		declaration of a Direntry, see the internal documentation
		on Directory Management, or unassemble Sysglobals interface
		text as suggested above.

Fnxtbyte        Next relative byte to be accessed in Fnxtblk.

Fmaxbyte        Highest-numbered relative byte ever accessed in Fmaxblk.

\need 2
Fbufchngd       True if block now in memory buffer Fbuffer must be written
		to the file.

\need 3
Fsoftbuf        True if file has memory buffer.  Files on unblocked
		devices or untyped file variables (i.e., UCSD type FILE)
		do not have memory buffers.

Fbuffer         Memory buffer area; 512 bytes.


\new
SYSTEM FILE-HANDLING ROUTINES

a. Initialization procedures

   procedure FINITB (var f: fib; window: windowp; recbytes: integer)

     Module: FS

     Initializes F to known state indicating no association with external
     file.  Effects on F:

\image b
       Fisopen := False
       Fwindow := Window
       Fistextvar := (Recbytes = -3)
       if Frecbytes >= 0 then Frecsize := Recbytes
       else if Recbytes := -1 then  {UCSD type FILE}
	 begin Fwindow := nil; Frecsize := 0 end
       else Frecsize := 1;  { text, file of char, etc. }


   procedure FINIT (var f: fib; window: windowp; recwords: integer)

     Module: FS

     Identical to Finit except that record size is in words (1 word =
     2 bytes).  Retained for compatibility with output of pre-Feb 1982
     compilers.


\new
b. Associative procedures

The following procedures create or sever the association between
an FIB and an external file or device.

   procedure FOPEN (var f: fib; var ftitle: string80; typ: faccess)

\image b
     type string80 = string[80]
	  faccess  = (readonly,writeonly,readwrite)

     Module: FS

     Opens file with name Ftitle and associates it with F.  Ftitle is
     a FILE SPECIFICATION (for syntax, see Pascal Language System User's
     Manual, p. 155).

\image b
     Action taken by Fopen depends on the value of Typ.
     Writeonly requests the creation of a new, or 'temporary' file.
     Readonly requests the opening of an old, or 'permanent' file.
     If Typ is Readwrite, Fopen creates a new file if an old one
     does not exist.

     Note: the compiler emits calls to the procedures Fhpopen and Fhpreset
	   rather that Fopen.

\image
     Error conditions:
       Fisopen = true
       Ftitle does not conform to the syntax of a file specification
       Volume specified by Ftitle not on line
       Typ = Readonly and file specified by Ftitle does not exist
       Typ = Writeonly and a new file of same name already exists
	     (each volume may only have one temporary file with a
	      given name).
       Typ = Readwrite and an old file exists, but its type is Text
       Typ = Readwrite, Ftitle includes a size specification, and an
	     old file exists which can not be extended to the
	     specified size (cf. function Cantstretch).
       Typ = Readwrite, an old file does not exist, and Ftitle
	     includes a '.Text' suffix
       Typ = Readwrite, an old file does not exist and a new file of
	     same name already exists.
\format
       Volume specification indicates a blocked device, the medium has no
	     directory, and the file name portion of Ftitle is non-null.  If the
	     medium has no directory, the volume may be opened (e.g., as '#20:'),
	     but a file on the volume cannot be.


\need 4
   procedure FRESET (var f: fib)

     Module: FS

     'Rewinds' the file associated with F.  Does nothing if Fisopen is false.


\need 22
   procedure FHPOPEN (var f: fib; typ: faccess; var title: string80)

\image b
     Pascal equivalent: Open (f,title)
			Reset (f,title)
			Rewrite (f,title)

     Module: FS

     The compiler emits a call to this procedure when it encounters a
     Reset, Rewrite, or Open reference with the file name parameter included.
     Title is a file specification.  Fhpopen severs the current association
     of F (if any), calls Fopen, and sets the following fields in F.

\image
		   Feof            Fgetok          Freadable       Fwriteable
     ------------------------------------------------------------------------
       Reset       false           true            true            false

       Rewrite     true            false           false           true

       Open        false           false           true            true

\format
     Fstate is set to Fneedchar except for UCSD type FILE.


\need 15
   procedure FHPRESET (var f: fib; typ: faccess; istextfile: boolean)

\image b
     Pascal equivalent: Open (f)
			Reset (f)
			Rewrite (f)

     Module: FS

     The compiler emits a call to this procedure when it encounters a
     Reset, Rewrite, or Open reference with the file name parameter omitted.
     If F has a current association (i.e., Fisopen is true), the file is
     rewound by calling Freset.  If there is no current association, Fopen
     is called to create a new file with a file specification of the form
     '@@ <integer> [*]'  (this is the Pascal scratch file mechanism).
     Fhpreset concludes by setting selected FIB fields as in Fhpopen above.


\need 24
   procedure FCLOSE (var f: fib; ftype: closetype)

     type closetype = (cnormal,lock,purge,ccrunch)

     Module: FS

     Severs the connection between F and an external file, closing the file.
     Ftype has the following meaning.

     Cnormal - Remove a new file; close an old one.

     Lock    - Make a new file permanent, adjusting its size so that the
	       highest block accessed becomes the last block of the file.
	       Close an old file.

     Purge   - Remove old or new file.

     Ccrunch - Adjust the size of a permanent file so that the highest block
	       accessed during the current association becomes the last block
	       of the file.  Lock a new file.

\image b
     Error conditions:
       Volume no longer on line.
       File no longer in directory


\need 16
   procedure FCLOSEIT (var f: fib; stype: string255)

     Pascal equivalent: Close (f,stype)

     Module: FS

     The compiler emits a call to this procedure upon encountering a
     reference to Close.  Fcloseit maps Stype into a Closetype and
     calls Fclose.

     Stype maps as follows:

\image b
       'normal', 'temp' => Cnormal
       'lock', ' save'  => Lock
       'purge'          => Purge
       'crunch'         => CCrunch


\new
c. Functions

\need 11
   function FPOSITION (var f: fib): boolean

     Pascal equivalent: Position (f)

     Module: FS

     Returns the index of the current component of the file associated
     with F.  Component numbers begin with 1.

\image b
     Error condition
       Fisopen = false


\need 15
   function FMAXPOS (var f: fib): boolean

     Pascal equivalent: Maxpos (f)

     Module: FS

     Returns the number of the last component of the file associated
     with F.  For a permanent file, Fmaxpos is the highest-numbered
     component ever accessed.  For a new file it is the highest-numbered
     component which may be accessed without increasing the file size.

\image b
     Error conditions
       Fisopen = false
       Freadable = false or Fwriteable = false (i.e., file is not open
		     for direct access)


\need 20
   function FEOF (var f: fib): boolean

     Pascal equivalent: Eof (f)

     Module: FS

     Returns the value of F.Feof.  For files open for direct access, F.Feof
     is defined as Fposition(f) > Fmaxpos(f).  For UCSD type FILE, F.Feof
     is determined by the most recent call on Fblockio.  For typed files
     open for writing, F.Feof is always true.

     F.Feof is true for typed files open for reading if the next component
     of the file does not exist.  If Fstate = Fgotchar, the next component
     exists and is in the file window.  Otherwise procedure Look is called
     to try to read the next component.  This 'look-ahead' is omitted if
     Funit is 1 or 2, indicating the keyboard device.  Consequently EOF can
     never be true for the keyboard.

     There are no error conditions local to Feof; any errors are generated
     by called routines (cf. Fmaxpos, Fposition, Look).


\need 14
   function FEOLN (var f: fib): boolean

     Pascal equivalent: Eoln (f)

     Module: FS

     Returns the value of F.Feoln.  Will return true if the most recent
     character read from the file is the end-of-line marker (chr(13)).
     If Fstate = Fneedchar, procedure Look will be called to read
     the next component unless Funit = 1 or 2.  Applicable only to
     text files.

     No errors are generated locally, but error conditions may be detected
     by procedure Look.


\need 10
   function CANTSTRETCH (var f: fib): boolean

     Module: FS

     Returns true if the file associated with F cannot be extended beyond
     the current end-of-file.  If false is returned, any adjacent free
     blocks following the file have been appended to it.  Note that false
     is returned even if there are no adjacent free blocks, if Fmaxbyte
     is less than Fblksize (indicating space available in the last block).


\new
d. Miscellaneous I/O routines

\need 14
   procedure FPUT (var f: fib)

     Pascal equivalent: Put (f)

     Module: FS

     Writes the current file window contents (Fwindow^[0..Frecsize-1])
     to the file at the current file position, and increments the position.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       No room in file for another component and file cannot
	 be extended (cf. function Cantstretch)


\need 49
   procedure LOOK (var f: fib)

     Module: FS

     If the current file position is beyond end-of-file as given by
     (Fmaxblk,Fmaxbyte) then Feof is set; otherwise Frecsize
     bytes are read from the current file position into Fwindow^.
     If Fistextvar is true then 1 byte is read and the following
     values are treated specially.

       chr(13) = end-of-line character.  Feoln is set and the window
		 Fwindow^[0] is set to blank (chr(32)).

       chr(16) = start of a blank compression sequence, provided Funit
		 is not 1 or 2 (i.e., not the keyboard device).  The window
		 is set to blank and subsequent calls on Look leave the
		 window unchanged until the count of blanks (Freptcnt)
		 is exhausted.

       chr(0) = If the file is a buffered text file (Fsoftbuf=true
		and Fheader.Dfkind = Textfile) the byte begins the zero
		fill which ends a 2 block textfile page.  The file
		pointers (Fnxtblk,Fnxtbyte) are adjusted to index
		the start of the following block and another read is
		attempted.
		Otherwise, receiving a null implies end-of-file and
		Feof is set.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Feof is true on entry

\image
     Effect of Fgetok:
\format
       If Fgetok is false on entry to Look, no read is performed.  This
       condition occurs if the window has been loaded previously and its
       contents have not been used.  Consider the program fragment
\image
		reset(f);
		while not (eof(f) and eoln(f)) do ...
\format
       After the first read Eof will call Look to 'look ahead'.
       Eoln will also call Look, but now the desired byte
       is already in the window and the state of Feoln has
       already been determined.  Hence Look must be inhibited
       from reading and discarding the current window contents.

       Fgetok is always set to false before exiting Look.


\need 16
   procedure FGET (var f: fib)

     Pascal equivalent: Get (f)

     Module: FS

     Discards the current file component and advances the file position.
     If Fstate = Fneedchar then procedure Look is called to perform the
     advance; otherwise, the advance has already occurred..
     In either case the window contents are then 'thrown away' by setting
     Fstate to Fneedchar.  Also, Fgetok is set.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Feof is true on entry


\need 13
   function FBUFFERREF (var f: fib): windowp;

     Pascal equivalent: F^

     Module: FS

     Returns the address of the file window Fwindow.  If Freadable is true
     the routine attempts to load the next component of the file into
     Fwindow, using procedure Look.

\image b
     Error conditions
       Fisopen is false
       Freadable is true and Feof is true


\need 24
   function FBLOCKIO (var f: fib; var a: window;
			  nblocks,rblock: integer; doread: boolean): integer

     Pascal equivalent: Blockread (f,a,k,r)
			Blockwrite (f,a,k,r)

     Module: FS

     Transfers Nblocks 512-byte blocks between the file associated
     with F and memory starting at addr(A).  Rblock specifies the
     relative block number in the file, starting with zero.  If Rblock
     is negative a sequential transfer is performed, i.e., the transfer
     begins with the block number given by Fnxblk.  Doread specifies the
     direction of transfer.

     The returned value specifies the number of blocks actually transferred.
     Normally the returned value equals Nblocks unless end-of-file is en-
     countered.  If this happens during a read, Feof is set.   During a
     write, EOF causes the routine to call Cantstretch to extend the file
     and the write is retried; if EOF occurs again Feof is set.

\image b
     Error conditions:
       Fisopen is false
       see also Unitread/Unitio error conditions


\need 26
   procedure FSEEK (var f: fib; recnum: integer)

     Pascal equivalent: Seek (f,recnum)

     Module: MFS

     Operates on direct access files only (Freadable and Fwriteable both set).
     Positions the file so that the component with index Recnum is the
     next to be read or written.  Component indices begin with 1.
     The file position is computed assuming Frecsize is the component
     size; a 512-byte block may not contain any partial components.

\image b
     The following fields in F are set by Fseek:
       Feof   :=  False
       Fstate :=  Fneedchar
       Fgetok :=  False

\image b
     Error conditions
       Fisopen is false
       Freadable is false or Fwriteable is false.
       Fheader.Dfkind = Textfile
       Fsoftbuf is false (i.e., the file must be on a blocked device
	 and may not be a UCSD type FILE)
       Attempting to seek beyond EOF and the file cannot be extended
	 sufficiently


\need 15
   procedure FWRITEBIN (var f: fib; var x: integer)

\image b
     Pascal equivalent: Write (f,a)  where f is a file of type T and
					   a is a variable of type T

     Module: MFS

     Moves Frecsize bytes from memory starting at addr(x) to the
     file and advances the file position.  Uses Fput.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       No room in file for another component and file cannot
	 be extended (cf. function Cantstretch)


\need 14
   procedure FREADBIN (var f: fib; var x: integer)

\image b
     Pascal equivalent: Read (f,a)  where f is a file of type T and
					  a is a variable of type T

     Module: MFS

     Moves Frecsize bytes from the file to memory starting at addr(x)
     and advances the file position.  Uses Look.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true on entry
	 (i.e., there must be a component to read)


\new
e. Text file I/O routines

   Text file I/O involves conversion between the internal form of a value
   and its external representation.  For output a field width parameter
   is included and the external representation of a value is written
   right-justified in a field of the specified width, preceded by blanks
   if needed.   If the field width is too small, strings, packed
   arrays of character, and enumerated constants are truncated.  A field
   width parameter of -1 specifies default width.

\need 18
   procedure FWRITEINT (var f: fib; i: integer; rleng: shortint)

     type shortint = -32768..32767   n.b. subranges of integer are
				     allocated 2 bytes if possible.

     Pascal equivalent: Write (f,i:rleng)

     Module: FS

     Converts the 4-byte integer I to its character representation and
     writes it to the file associated with F, right-justified in a field
     of width Rleng.  Default field width is 12.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)




\need 15
   procedure FWRITEWORD (var f: fib; i,rleng: shortint)

     Pascal equivalent: Write (f,i:rleng)

     Module: FS

     Converts the 2-byte integer I to its character representation and
     writes it to the file associated with F, right-justified in a field
     of width Rleng.  Default field width is 12.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 14
   procedure FWRITECHAR (var f: fib; ch: char; rleng: shortint)

     Pascal equivalent: Write (f,ch:rleng)

     Module: FS

     Writes the character Ch to the file associated with F, right-justified
     in a field of width Rleng.  Default field width is 1.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 7
   procedure FPAGE (var f: text)

     Pascal equivalent: Page (f)

     Module: FS

     Identical to Fwritechar (f,chr(12),1)


\need 17
   procedure FWRITEREAL (var f: fib; x: real; w,d: shortint)

     Pascal equivalent: Write(f,x:w:d)

     Module: MFS

     Converts x to a character representation as specified by
     D and writes it to the file associated with F, right-justified
     in a field of width W.  D = -1 specifies scientific notation, while
     D >= 0 requests a fixed point representation with D digits to the
     right of the decimal point.  The default field width is 12.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 15
   procedure FWRITESTR (var f: fib; anyvar s: string80; rleng: shortint)

     Pascal equivalent: Write(f,s:rleng);

     Module: FS

     Writes S[1..Min(Strlen(S),Rleng)] to the file associated with F,
     right-justified in a field of width Rleng.  The default field
     width is Strlen(S).

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 15
   procedure FWRITEPAOC (var f: fib; var a: window; aleng,rleng: shortint)

     Pascal equivalent: Write (f,p:rleng)
			where p is a packed array [1..aleng] of char

     Module: FS

     Writes A[1..min(aleng,rleng)] to the file associated with F, right-
     justified in a field of width Rleng.  The default field width is Aleng.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 44
   procedure FWRITEENUM (var f: fib; i: shortint; rleng: shortint; p: vptr)

     Pascal equivalent: Write(f,e:rleng) where e is an expression of an
			enumerated type

     Module: MFS

     Writes the external representation of I to the file associated with
     F, right-justified in a field of width Rleng.  If Rleng is >= 0, exactly
     Rleng characters are written (i.e., the external representation may
     be truncated).  The default field width is the width of the enumerated
     constant to be written.  P is the 4-byte address of a table containing
     the external representations of values of an enumerated type.  I is used
     to select the entry in the table to be written.

     There is a mapping between objects of an enumerated type and the
     non-negative integers 0,1,2,... such that for a Pascal type declared as
\image
	 Type Color = (Red,Green,Blue)
\format
     the internal representations of the constants Red, Green, and Blue are
     0, 1 and 2 respectively.

     The first 2 bytes of the table addressed by P contain a 2-byte
     integer specifiying the number of entries in the table.  The entries
     follow in reverse order: byte 3 begins the entry with highest index.
     Each entry is in the form of an object of type String: a length byte
     followed by the external representation of an enumerated constant.
     The entries are contiguous but no entry may start on an odd boundary.
     For type Color the bytes of the table are as follows

\image b
	      Offset  0 1   2  3456  7 8  90123  4  567
	      Value   0 3   4 'BLUE' 0 5 'GREEN' 3 'RED'

     If this is confusing, write a Pascal program containing the type
     declaration for which a table is desired and call the standard
     procedure Write to write one of the type's values.  An Unassembly
     of the program will contain a copy of the table.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 16
   procedure FWRITEBOOL (var f: fib; b: boolean; rleng: shortint)

     Pascal equivalent: Write (f,b:rleng);

     Module: MFS

     Writes the literal 'FALSE' or 'TRUE' to the file associated with
     F according to the value of B.  The literal is right-justified
     in a field of width Rleng; if Rleng is >= 0, exactly Rleng characters
     are written.

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 14
   procedure FWRITELN (var f: fib)

     Pascal equivalent: Writeln(f)

     Module: FS

     Writes an end-of-line marker to the file associated with F.
     Equivalent to Fwritechar(f,chr(13),1);

\image b
     Error conditions:
       Fisopen is false
       Fwriteable is false
       Insufficient room in the file and the file cannot be extended
	 (cf. function Cantstretch)


\need 32
   procedure FREADINT (var f: fib; var i: integer; stype: sourcetype)

     type sourcetype = (phile,strg)

     Pascal equivalent: Read (f,i)

     Module: FS

     Reads characters from F expecting the syntax of an <integer number>.
     The syntax is

\image b
	  <integer number> ::= <sign> <unsigned integer>
	  <unsigned integer> ::= <digit sequence>
	  <digit sequence> ::= <digit> {<digit>}
	  <digit> ::= 0|1|2|3|4|5|6|7|8|9
	  <sign> ::= + | - | <empty>
	  <empty> ::=

     where { <x> } means "0 or more occurences of <x>".  Leading blanks
     and end-of-lines are skipped.  The number is converted to internal
     form and assigned to the 4-byte integer I.  Sourcetype should be Phile;
     to convert from a string to an integer, see Freadstrint below.

     On exit, Fstate = Fgotchar and Fgetok = False since an additional
     character not included in the integer has been loaded into Fwindow.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true
       Character sequence violates syntax of <integer number>
       Integer value not in range -2^31..2^31-1


\need 8
   procedure FREADWORD (var f: fib; var i: shortint)

     Pascal equivalent: Read (f,i)

     Module: FS

     Analog of Freadint for 2-byte integers.  The value read must be
     in the range -32768..32767.


\need 49
   procedure FREADCHAR (var f: fib; var ch: char)

     Pascal equivalent: Read (f,ch)

     Module: FS

     Reads the next character from F and assigns is to Ch.  On exit,
     Fgetok is true and Fstate = Fneedchar.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true on entry


   procedure FREADREAL (var f: fib; var x: real; stype: sourcetype)

     Pascal equivalent: Read (f,x)

     Module: MFS

     Scans characters from F expecting a sequence which conforms to the
     syntax for a <real number>.  Leading blanks and end-of-lines are
     skipped.  The syntax is (cf. Freadint above)

\image b
	  <real number> ::= <sign><input real number><exponent>
	  <input real number> ::= . <digit sequence> |
				  <unsigned integer>.<digit sequence> |
				  <unsigned integer> |
				  <unsigned integer> .
	  <exponent> ::= E <scale factor> | L <scale factor>| E | L |
			 <empty>
	  <scale factor> ::= <integer number>

     The resulting string is converted to internal form and assigned to X.
     Sourcetype should be Phile; to convert from a string to a real, see
     Freadstrreal below.

     On exit, Fstate = Fgotchar and Fgetok = False since an additional
     character not included in the number has been loaded into Fwindow.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true
       Sequence read does not conform to syntax for <real number>
       Absolute value of number outside the range
	       2.22507385850720E-308 .. 1.79769313486231E+308
       Too many characters in <real number>


\need 21
   procedure FREADSTR (var f: fib; var s: string)

     Pascal equivalent: Read (f,s)

     Module: FS

     Reads characters from F until Strmax(S) characters are read
     or end-of-line or end-of-file is encountered (however, if Funit
     is 1 then end-of-line is the only terminator).  The resulting
     string (NOT including any end-of-line terminator) is assigned
     to S.

     If Feoln is true on entry because end-of-line terminated a previous
     string or PAOC read then the end-of-line is skipped and the read
     proceeds with the next character.  Otherwise no characters are read
     and the null string is assigned to S.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true on entry


\need 23
   procedure FREADPAOC (var f: fib; var a: paoc; aleng: shortint)

\image b
     Pascal equivalent: Read (f,p)
			where p is a packed array [1..aleng] of char

     Module: MFS

     Reads characters from F until Aleng characters are read or
     end-of-line or end-of-file is encountered (however, if Funit
     is 1 then end-of-line is the only terminator).  The resulting
     character sequence (NOT including any end-of-line terminator) is
     assigned to A; if the sequence contains less than Aleng characters
     then A is padded on the right with blanks.

     If Feoln is true on entry because an end-of-line terminated a previous
     PAOC or string read then the end-of-line is skipped and the read proceeds
     with the next character.  Otherwise no characters are read and A is set
     to all blanks.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true on entry


\need 23
   procedure FREADENUM (var f: fib; var i: shortint;
			p: vptr; stype: sourcetype)

     Pascal equivalent: Read (f,e) where e is a variable of an enumerated type.

     Module: MFS

     Reads a sequence of characters from F according to the syntax of
     a Pascal identifier and attempts to match the identifier with an entry
     in the table addressed by P (cf. Fwriteenum above for the table
     structure).  Leading blanks and end-of-lines are skipped.  If a match
     is found the entry's index is assigned to I; otherwise, a value range
     error ( Escape(-8) ) is generated.  Alphabetic characters read are
     converted to upper case prior to the table search.  Stype should be
     Phile; to convert from a string to an enumerated value, see Freadstrenum
     below.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true on entry
       Character sequence from F not an identifier
       Identifier read fails to match any table entry


\need 21
   procedure FREADBOOL (var f: fib; var b: boolean; stype: sourcetype)

     Pascal equivalent: Read (f,b)

     Module: MFS

     Reads a sequence of characters from F according to the syntax of
     a Pascal identifier and attempts to match the identifier with the
     strings 'TRUE' and 'FALSE'.  Leading blanks and end-of-lines are skipped.
     If a match is found the corresponding Boolean value is assigned to B;
     otherwise, a value range error is generated.  Alphabetic characters
     read are converted to upper case prior to the match.  Stype should be
     Phile; to convert from a string to a Boolean value, see Freadstrbool
     below.

\image b
     Error conditions:
       Fisopen is false
       Freadable is false
       Eof(F) is true on entry
       Character sequence from F not an identifier
       Identifier read fails to match 'TRUE' or 'FALSE'


\need 17
   procedure FREADLN (var f: fib)

     Pascal equivalent: Readln (f)

     Module: FS

     Reads characters from the textfile associated with F until an end-of-line
     character is found.  If Feof is true on entry, no characters are read.
     On exit the file is positioned past the end-of-line by setting the
     following values:
\image b
			 Fstate := Fneedchar
			 Fgetok := True
			 Feoln  := False

\image b
     Error conditions
       Fisopen is false
       Freadable is false



\new
e. Strread/Strwrite support routines

   HP Standard Pascal allows the programmer to access the conversion
   capabilities of textfile I/O independent of any file operations.
   Instead, the external representations of data objects are written
   to or read from a string variable.

   Two standard procedures are provided:

\image b
     Strread (S,P1,P2,<list>)
       where S  is a string containing a character sequence which is the
		external representation of the values to be assigned to
		the variables in <list>
	     P1 is the index in S where the read is to begin
	     P2 is the index in S of the last character read plus one
	     <list> is identical to its counterpart in the standard
		procedure Read

\image b
     Strwrite (S,P1,P2,<list>)
       where S is a string to receive the external representations
		of the values of the variables in <list>.  If the
		length of S is incrementedduring the write
		then Strlen(S) is increased.
	     P1 is the index in S where writing is to begin.
		If P1 > Strlen(S) + 1, it is an error.
	     P2 is the index in S of the last character to be
		written plus one
	     <list> is identical to its counterpart in the
		standard procedure Write


\need 17
   procedure FWRITESTRINT (var t: string; var p2: integer;
			   i: integer; rleng: shortint)

\image
     Pascal equivalent:  Strwrite (t,k,p2,i:rleng)
\format
			   (the compiler generates code to assign K to P2
			    before calling Fwritestrint)

     Module: FS

     Converts the 4-byte integer I to its external representation and
     writes it to T starting at T[P2], right-justified in a field of
     width Rleng.  Default field width is 12.  On exit, P2 is assigned
     the index of the last character written, plus one.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(T)+1 on entry
       P2 > Strmax(T)+1 on exit


\need 16
   procedure FWRITESTRWORD (var s: string; var p2: integer; i,rleng: shortint)

\image
     Pascal equivalent:  Strwrite (s,k,p2,i:rleng)
\format
			   (the compiler generates code to assign K to P2
			    before calling Fwritestrword)

     Module: FS

     Converts the 2-byte integer I to its external representation and
     writes it to S starting at S[P2], right-justified in a field of
     width Rleng.  Default field width is 12.  On exit, P2 is assigned
     the index of the last character written, plus one.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit


\need 15
   procedure FWRITESTRCHAR (var s: string; var p2: integer;
			    ch: char; rleng: shortint)

\image
     Pascal equivalent: Strwrite(s,k,p2,ch:rleng)
\format
			   (the compiler generates code to assign K to P2
			    before calling Fwritestrchar)

     Module: FS

     Writes the character Ch to S starting at S[P2], right-justified in a
     field of width Rleng.  Default field width is 1.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit


\need 18
   procedure FWRITESTRREAL (var r: string; var p2: integer;
			    x: real; w,d: shortint)

\image
     Pascal equivalent: Strwrite(s,k,p2,x:w:d)
\format
			   (the compiler generates code to assign K to P2
			    before calling Fwritestrreal)

     Module: MFS

     Converts x to a character representation as specified by D and
     writes it to S starting at S[P2], right-justified in a field of width W.
     D = -1 specifies scientific notation, while D >= 0 requests a fixed
     point representation with D digits to the right of the decimal point.
     The default field width is 12.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit


\need 15
   procedure FWRITESTRSTR (var s: string; var p2: integer;
			   anyvar t: string255; rleng: shortint)

\image
     Pascal equivalent: Strwrite(s,k,p2,t:rleng)
\format
			   (the compiler generates code to assign K to P2
			    before calling Fwritestrstr)

     Module: FS

     Writes T[1..Min(Strlen(T),Rleng)] to S starting at S[P2], right-justified
     in a field of width Rleng.  The default field width is Strlen(T).

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit


\need 16
   procedure FWRITESTRPAOC (var s: string; var p2: integer;
			    var a: window; aleng,rleng: shortint)

\image
     Pascal equivalent: Strwrite(s,k,p2,p:rleng)
\format
			  where P is a packed array [1..Aleng] of char
			  (the compiler generates code to assign K to P2
			   before calling Fwritestrpaoc)

     Module: FS

     Writes A[1..min(aleng,rleng)] to the file associated with F, right-
     justified in a field of width Rleng.  The default field width is Aleng.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit


\need 22
   procedure FWRITESTRENUM (var s: string; var p2: integer;
			    i,rleng: shortint; p: vptr)

\image
     Pascal equivalent: Strwrite(s,k,p2,e:rleng)
\format
			  where e is an expression
			  of an enumerated type
			  (the compiler generates code to assign K to P2
			   before calling Fwritestrenum)

     Module: MFS

     Writes the external representation of I to S starting at S[P2],
     right-justified in a field of width Rleng.  If Rleng is >= 0, exactly
     Rleng characters are written (i.e., the external representation may
     be truncated).  The default field width is the width of the enumerated
     constant selected.  P is the 4-byte address of a table containing
     the external representations of values of an enumerated type (cf.
     Fwriteenum above for the table structure).  I is used to select the
     table entry.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit

\need 17

   procedure FWRITESTRBOOL (var s: string; var p2: integer;
			    b: boolean; rleng: shortint)

\image
     Pascal equivalent: Strwrite(s,k,p2,b:rleng)
\format
			   (the compiler generates code to assign K to P2
			    before calling Fwritestrbool)

     Module: MFS

     Writes the literal 'FALSE' or 'TRUE' to S starting at S[P2].  The
     desired literal is selected by B and written right-justified in
     a field of width Rleng; if Rleng >= 0, exactly Rleng characters
     are written.

\image b
     Error conditions:
       P2 < 1 or P2 > Strlen(S)+1 on entry
       P2 > Strmax(S)+1 on exit



\need 16
   procedure FREADSTRINT (anyvar s: string255; var p2,i: integer)

\image
     Pascal equivalent: Strread(s,k,p2,i)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrint)

     Module: FS

     Reads characters from S starting at S[P2] expecting the syntax
     of an <integer number> (cf. Freadint above).  Leading blanks
     and end-of-lines are skipped.

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry
       Character sequence violates syntax of <integer number>
       Integer value not in range -2^31..2^31-1


\need 10
   procedure FREADSTRWORD (var s: string255; var p2: integer; var i: shortint)

\image
     Pascal equivalent: Strread(s,k,p2,i)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrword)

     Module: FS

     Analog of Freadstrint for 2-byte integers.  The value read must lie
     in the range -32768..32767.


\need 12
   procedure FREADSTRCHAR (var s: string255; var p2: integer; var ch: char)

\image
     Pascal equivalent: Strread(s,k,p2,ch)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrchar)

     Module: FS

     Essentially, Ch := S[P2]; P2 := P2+1.

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry


\need 23
   procedure FREADSTRREAL (var s: string255; var p2: integer; var x: real)

\image
     Pascal equivalent: Strread(s,k,p2,x)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrreal)

     Module: MFS


     Scans characters starting at S[P2] expecting a sequence which conforms
     to the syntax for a <real number> (cf. Freadreal above).  Leading blanks
     and end-of-lines are skipped.

     The resulting string is converted to internal form and assigned to X.
     Sourcetype should be Phile; to convert from a string to a real, see
     Freadstrreal below.

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry
       Sequence read does not conform to syntax for <real number>
       Absolute value of number outside the range
	       2.22507385850720E-308 .. 1.79769313486231E+308
       Too many characters in <real number>


\need 16
   procedure FREADSTRSTR (var t: string255; var p2: integer; var s: string)

\image
     Pascal equivalent: Strread(t,k,p2,s)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrstr)

     Module: FS

     Moves characters from T starting at T[P2] to the string S and
     sets the length of S.  An end-of-line character in T terminates
     the move and P2 is positioned past the end-of-line.  Otherwise,
     Min (Strlen(S),Strlen(T)-P2+1) characters are moved (i.e., S
     is filled if T has enough characters to do so).

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry


\need 17
   procedure FREADSTRPAOC (var s: string255; var p2: integer;
			   var a: paoc; aleng: shortint)

\image
     Pascal equivalent: Strread(s,k,p2,a)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrpaoc)

     Module: MFS

     Moves Aleng characters from S starting at S[P2] to A.  If Strlen(S)-P2+1
     is less than Aleng or an end-of-line character is encountered in S before
     Aleng characters have been moved, then P is padded on the right with
     blanks.  If an end-of-line in S terminates the move, P2 is positioned
     past the end-of-line.

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry


\need 21
   procedure FREADSTRENUM (var s: string255; var p2: integer;
			   var i: shortint; p: vptr)

\image
     Pascal equivalent: Strread(s,k,p2,e)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrenum)

     Module: MFS

     Reads a sequence of characters from S starting at S[P2] according to the
     syntax of a Pascal identifier and attempts to match the identifier with
     an entry in the table addressed by P (cf. Fwriteenum above for the table
     structure).  Leading blanks and end-of-lines are skipped.  If a match
     is found the entry's index is assigned to I; otherwise, a value range
     error ( Escape(-8) ) is generated.  Alphabetic characters read are
     converted to upper case prior to the table search.

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry
       Character sequence from S not an identifier
       Identifier read fails to match any table entry


\need 20
   procedure FREADSTRBOOL (var s: string255; var p2: integer; var b: boolean)

\image
     Pascal equivalent: Strread(s,k,p2,b)
\format
			   (the compiler generates code to assign K to P2
			    before calling Freadstrbool)

     Module: MFS

     Reads a sequence of characters from S starting at S[P2] according to
     the syntax of a Pascal identifier and attempts to match the identifier
     with one of the strings 'TRUE' and 'FALSE'.  Leading blanks and
     end-of-lines are skipped.  If a match is found the corresponding
     Boolean value is assigned to B; otherwise, a value range error is
     generated.  Alphabetic characters read are converted to upper case
     prior to the match.

\image b
     Error conditions:
       P2 <1 or P2 > Strlen(S) on entry
       Character sequence from S not an identifier
       Identifier read fails to match 'TRUE' or 'FALSE'


\center b
				   * * * * *

@


55.1
log
@Automatic bump of revision number for PWS version 3.25A
@
text
@@


54.1
log
@Automatic bump of revision number for PWS version 3.24
@
text
@@


53.1
log
@Automatic bump of revision number for PWS version 3.24B
@
text
@@


52.1
log
@Automatic bump of revision number for PWS version 3.24A
@
text
@@


51.1
log
@Automatic bump of revision number for PWS version 3.24d
@
text
@@


50.1
log
@Automatic bump of revision number for PWS version 3.23c
@
text
@@


49.1
log
@Automatic bump of revision number for PWS version 3.24b
@
text
@@


48.1
log
@Automatic bump of revision number for PWS version 3.24a
@
text
@@


47.1
log
@Automatic bump of revision number for PWS version 3.23
@
text
@@


46.1
log
@Automatic bump of revision number for PWS version 3.23
@
text
@@


45.1
log
@Automatic bump of revision number for PWS version 3.23C
@
text
@@


44.1
log
@Automatic bump of revision number for PWS version 3.23B
@
text
@@


43.1
log
@Automatic bump of revision number for PWS version 3.23aA
@
text
@@


42.1
log
@Automatic bump of revision number for PWS version 3.23e
@
text
@@


41.1
log
@Automatic bump of revision number for PWS version 3.23d
@
text
@@


40.1
log
@Automatic bump of revision number for PWS version 3.23c
@
text
@@


39.1
log
@Automatic bump of revision number for PWS version 3.23b
@
text
@@


38.1
log
@Automatic bump of revision number for PWS version 3.23a
@
text
@@


37.1
log
@Automatic bump of revision number for PWS version 3.3a
@
text
@@


36.1
log
@Automatic bump of revision number for PWS version 3.22
@
text
@@


35.1
log
@Automatic bump of revision number for PWS version 3.22
@
text
@@


34.1
log
@Automatic bump of revision number for PWS version 3.22
@
text
@@


33.1
log
@Automatic bump of revision number for PWS version 3.22D
@
text
@@


32.1
log
@Automatic bump of revision number for PWS version 3.22C
@
text
@@


31.1
log
@Automatic bump of revision number for PWS version 3.22B
@
text
@@


30.1
log
@Automatic bump of revision number for PWS version 3.22A
@
text
@@


29.1
log
@Automatic bump of revision number for PWS version 3.22b
@
text
@@


28.1
log
@Automatic bump of revision number for PWS version 3.3b
@
text
@@


27.1
log
@Automatic bump of revision number for PWS version 3.3a
@
text
@@


26.1
log
@Automatic bump of revision number for PWS version 3.3 Synch
@
text
@@


25.1
log
@Automatic bump of revision number for PWS version 3.2Y
@
text
@@


24.1
log
@Automatic bump of revision number for PWS version 3.2
@
text
@@


23.1
log
@Automatic bump of revision number for PWS version 3.2P
@
text
@@


22.1
log
@Automatic bump of revision number for PWS version 3.2N
@
text
@@


21.1
log
@Automatic bump of revision number for PWS version 3.2M
@
text
@@


20.1
log
@Automatic bump of revision number for PWS version 3.2L
@
text
@@


19.1
log
@Automatic bump of revision number for PWS version 3.2K
@
text
@@


18.1
log
@Automatic bump of revision number for PWS version 3.2J
@
text
@@


17.1
log
@Automatic bump of revision number for PWS version 3.2I+
@
text
@@


16.1
log
@Automatic bump of revision number for PWS version 3.2I
@
text
@@


15.1
log
@Automatic bump of revision number for PWS version 3.2H
@
text
@@


14.1
log
@Automatic bump of revision number for PWS version 3.2G
@
text
@@


13.1
log
@Automatic bump of revision number for PWS version 3.2F
@
text
@@


12.1
log
@Automatic bump of revision number for PWS version 3.2E
@
text
@@


11.1
log
@Automatic bump of revision number for PWS version 3.2D
@
text
@@


10.1
log
@Automatic bump of revision number for PWS version 3.2C
@
text
@@


9.1
log
@Automatic bump of revision number for PWS version 3.2B
@
text
@@


8.1
log
@Automatic bump of revision number for PWS version 3.2A
@
text
@@


7.1
log
@Automatic bump of revision number for PWS version 3.2l
@
text
@@


6.1
log
@Automatic bump of revision number for PWS version 3.2k
@
text
@@


5.1
log
@Automatic bump of revision number for PWS version 3.2j
@
text
@@


4.1
log
@Automatic bump of revision number for PWS version 3.2i
@
text
@@


3.1
log
@Auto bump revision for PAWS 3.2h
@
text
@@


2.1
log
@Auto bump rev number to 2.1 for sys 3.2e.
@
text
@@


1.1
log
@Initial revision
@
text
@@
