Copyrights

How to handle end of file

The MUMPS standard does not contain pure definition how application must handle end of file on read, so developers can have some trouble with proper end of file handling.

On read from file are possible four situations to make decision about read from the file must be ended:

• application know where end of file is located, for example, this lenght contains in the file header
• application know special end-of-file indicator in input byte stream
• application handle an error <ENDOFFILE>
• application handle a special $zeof indicator

First two cases are very trivial, so we review two other.

Handle an error <ENDOFFILE>.

In this case application must set up error handler before read from the file and execute read. If MiniM process detect end of file and read is impossible, process generates an error <ENDOFFILE> and control flow is passed to error handler. There application must close file if this is need and handle an error.

Text value of error "ENDOFFILE" does not included into MUMPS standard, but error generation, if read is impossible, is meaning. MiniM uses the "ENDOFFILE" text value for an error for compatibility with other MUMPS servers and better application portability.

Error handling subroutine got control on any error occured, so application developer must distinquish different errors if this need.

Example how to read text file and wait error <ENDOFFILE>:

eof1  ; k  d eof1^eof w
 ; first sample is based on standard error handling
 ; read file up to <ENDOFFILE> error was reached
 ; read from this file all lines into local variable
 n dev="|FILE|c:\temp\dat.txt",lines,line,oldio=$io
 ; set error trapping handler
 n $et="g eof1end"
 ; read all lines
 o dev:("rt") u dev
 f  r line s lines($i(lines))=line
eof1end
 c dev      ; close device in any case
 ; no more error handling on end of file
 ; or continue error handling
 i $ze["<ENDOFFILE>" s $ec=""
 ; restore current device
 u oldio
 q

Handle special $zeof indicator

In this case application must switch process into special mode for $zeof handling by calling special $v("proc",5) function. Both system variable $zeof and function $v("proc") are not included into MUMPS standard, so application developer must consider this while write portable applications.

In this mode application must check special indicator $zeof and stop reading if $zeof value is on (equal 1).

Example how to read text file and check $zeof indicator:

eof2  ; k  d eof2^eof w
 ; second sample is based on using
 ; nonstandard $zeof system variable
 ; read from file up to $zeof indicator will be on
 n dev="|FILE|c:\temp\dat.txt",lines,line,oldio=$io
 ; set $zeof behavior, does not raise an error and
 ; set $zeof indicator
 n oldeof=$v("proc",5,0)
 ; read all lines
 o dev:("rt") u dev
 ; if $zeof is on, don't read more lines
 f  r line q:$zeof  s lines($i(lines))=line
 ; restore eof behavior
 i $v("proc",5,oldeof)
 ; close device
 c dev
 ; restore current device
 u oldio
 q

MiniM applies $zeof indicator only to devices with type |FILE|, |PIPE|, |TCP|, |STORE| and external ZDEVICE if he supports $zeof handling. $zeof indicator is applied only to current device.

MiniM sets up $zeof indicator if one of read string or read character commands cannot read one byte becouse input byte sequence was terminated and read is impossible. If read of one or more bytes are possible, read command returns result. If read is impossible by any other case, read command generate a <READ> error.