\documentstyle{deproc}
\begin{document}
\title{MODIFYING FMS-11 TO PROVIDE READ-WITH-TIMEOUT\\
       AND VIDEO ATTRIBUTE CONTROL}
\author{Joseph E. Kulaga\\
        Argonne National Laboratory\\
        Chemical Technology Division\\
        Argonne, Illinois}
\begin{abstract}
FMS-11/RSX V2.0 is a forms-oriented video I/O management
system that is well suited for use in traditional data
entry applications.  A recent attempt to use FMS-11 in
a real-time process control application exposed several
deficiencies.  This paper describes modifications and
additions to FMS-11 required by the application, such
as video attribute control, ''read with timeout,'' and
programmable default menu responses.  Some discussion is
presented on the techniques used to approach this type
of problem.
\end{abstract}
\maketitle
\footnotetext[1]{The submitted manuscript has been authored
by a contractor of the U.S. Government under contract No.
W-31-109-ENG-38.  Accordingly, the U.S. Government retains
a nonexclusive, royalty-free license to publish or reproduce
the published form of this contribution, or allow others
to do so, for U.S. Government purposes}
\section{Background}
The Fossil Energy Users Laboratory (FEUL) at Argonne National
Laboratory is a Department of Energy facility constructed to accommodate
a wide range of experiments related to coal and oil combustion.  The 
facility has been used to acquire data for the design and operation of
a magneto-hydrodynamic power station, to study the control of \(NO_{x},
SO_{x}\), and particulate emissions, and to verify instrumentation
and heat transfer computer codes.  The oil combustor portion has been
in operation since 1980, and the coal combustor portion since 1985.

A decision was made recently to upgrade both the hardware and software
used in the facility's data acquisition system,
replacing an LSI 11/23 running an RT-11 based software system by a 
MicroPDP-11/73 running RSX-11M+.  The software system requirements 
included the capability of periodic accumulation of data of from 100 
to 300 sensors, periodic display of the data in real time, logging of 
all data to disk, and printing subsets of the data periodically.  Most 
off-line data analysis was to be accomplished on a VAX.

In designing the method by which a user interacts with an on-line data
acquisition system such as we are discussing, one generally must decide
between a command language based system and a menu driven system.  The
command language based system has the potential of supplying a wider
range of interaction capabilities, but generally requires a more
sophisticated user, i.e., one more aware of the computer environment
and the details of the software system and its components.  The menu
driven approach, however, provides a much more easily mastered interaction 
mechanism.  With this in mind, FMS-11 was chosen as the input/output 
mechanism for all normal user interaction.

\section{Hardware}
Both coal and oil combustor systems accumulate data from a range of
sensor types: thermocouples to measure temperatures ranging from
ambient up to 2000 degrees F, pressure transducers, air flow transducers, 
weight scales, valve positioners, and gas analytical instruments.  
These sensors are multipexed into an analog to digital converter 
and read by the data acquisition task.  The multiplexers and ADC 
are part of a CAMAC-based\footnote{CAMAC is an internationally 
accepted interface standard widely used in data acquisition and 
process control environments.  See the IEEE-583 document.} data 
acquisition system interfaced to the host MicroPDP-11/73 Q-bus 
by means of a CAMAC crate controller.  An RSX-11M/M+ driver is
used to access the CAMAC equipment via the standard QIO mechanism.

\section{Software}
\subsection{Overview}
Much of the user interaction is in the form of a typical menu
based system.  The user selects options from a main menu that in 
turn bring up various forms.  One form is used to supply sensor 
addressing information to the data aquisition program's database.  
A second form is used to supply data conversion / calibration 
coefficients for the fifth order polynomial expression that is used 
to convert the raw data to engineering units.  (The system supports 
up to 64 different coefficient sets which may be assigned to the 
various sensors.)  The option to start data acquisition brings up 
another form which defines run-time variables for the system such 
as the length of the experiment, the data logging rate, the data 
file name, the screen refresh rate, and several others.

When data acquisition begins, a number of independent tasks begin
to execute in traditional RSX fashion.  An acquisition task
is begun which accumulates data, converts the raw information into
engineering units, checks for out-of-range conditions, and stores the 
results in a dynamic region.  A disk update task is initiated
whose function is to retrieve data from the dynamic region upon
request of the data acquisition task and write the data to a file.
A printing task is initiated whose function is to periodically
print results for all sensors at a user defined interval.
A data display task is also invoked which
periodically displays selected groups of data on a terminal using
the FMS routines.  Since the coal combustor data acquisition system
uses slightly more than 100 sensors and the oil combustor data
acquisition system uses slightly more than 300 sensors, it is obvious
that only a small fraction of these may be displayed at any given time.

It was decided that for each system it was necessary to display a
small subset of all data at all times in a primary display window,
with a secondary window reserved for selected subsets of data.  
The users thus needed the capability of selecting which subset should 
be displayed in the secondary window.  A problem arises, however, 
in allowing a periodic screen refresh (on the order of once
every ten seconds) and simultaneously allowing user input to select
the secondary window contents.

\subsection{Required features}
A user option field is normally trivial to implement with the
FMS-11 FGET routine.  The problem, however, is that the
read I/O request must be satisfied with user input.  In this
particular case, however, the data display must be periodically
refreshed at a predetermined user rate without user intervention,
i.e., the user should not have to request a screen update.
The FGET routine (as well as other FMS routines) does not feature
a timeout option on the read request.  In order to provide the
necessary functionality it was decided to add a read-with-timeout
option to the DEC FMS-11 code.

A second feature not supplied by DEC was also deemed necessary for 
this application, namely run-time control of the video attributes
of a particular field.  The user has the option of setting high
and low alarm points for all sensors, and the alarm flag state
for each sensor is logged with the data when the data file is
periodically updated.  It was decided that the user should be
given some visual indication on the CRT if one or more sensors
on the current display exceeded either the high or low alarm
points.  The obvious choice would be to have the video attribute
of the sensor data display set to ''flash'' for any out-of-range 
sensor, a capability not supplied by FMS-11.

\subsection{Implementation goals}

The primary goal of this effort was to supply the needed
functionality but with the absolute minimum modification of DEC
code in the form driver package.  In addition, any modification
was to be restricted to a single routine if possible, and as
much support code as possible was to be contained in subroutines
independent of the form driver package.

\section{Investigating FMS-11}

The FMS-11 manual supplied by DEC does not reveal the data structures
used by the form driver.  Examining the source code, one can find a
few routines that are reasonably documented, but, for the most part,
the source code is undocumented.  Without documentation, one must resort
to a little detective work.

\subsection{Researching terminal input}
An initial attempt was made to trace the program flow from a high
level entry point, such as the FGET call, down to the lowest level
code which actually performed the QIO.  This proved difficult
since the code consists of subroutines which call subroutines which
invoke macros which call subroutines which invoke macros, ..., and
so on!  The source code was searched with the EDT editor for any QIO's,
and a single character QIOW call was found in the FDVTIO subroutine.
This QIOW performs a read with terminator table and no echo, using
event flag T\$IEFN.  The code appears to read a single character
into a buffer and pass it along to the code which verifies that the
character input is appropriate for the field that is being read.
A legitimate character is then echoed to the terminal screen and the
input process continues for another character.  This seemed to be
the appropriate point to add the timeout feature.

\subsection{Researching video attribute control}
Researching the method of video attribute control required a bit
more work.  One can set any combination of four basic video attributes
for any field on a form, namely: underline, bold, reverse video, and
blinking.  It was logical to assume that these attributes must be
defined in some fashion in the impure area that must be reserved for
each form that is to be displayed on the screen.  A special program was
written that displayed a trivial form on the screen, and wrote a file
containing the contents of the impure area after the form was displayed.
A minor change was made to the video attributes of a field on this test
form and the contents of the impure area was again dumped to a file.
The two files were compared using the DMP and CMP utilities after simple
changes to the test form and a good deal of the data structure
maintained in the impure area was revealed.  The location of the video
attribute byte was readily apparent, as were several other control
variables.  The key item was that the location of the video attribute 
byte was at a fixed offset from the field name.

A segment of the basic data structure of a field entry in the impure
data region may be represented as follows:

\begin{picture}(200,300)
\put( 40,250){\framebox(150,20){Flag  word}}
\put( 40,230){\dashbox{5}(150,20){Field  Name}}
\put( 40,210){\dashbox{5}(150,20){( six  characters )}}
\put(115,200){\makebox(0,0){( ASCII )}}
\put( 40,170){\framebox(150,20)}
\put( 40,150){\framebox( 75,20){Clear Char}}
\put(115,150){\framebox( 75,20){Video Attr}}
\put( 40,130){\framebox(150,20)}
\put( 40,110){\framebox( 75,20)}
\put(115,110){\framebox( 75,20){\# Field Char}}
\put( 40, 90){\framebox( 75,20){\# Def Char}}
\put(115, 90){\framebox( 75,20)}
\put( 40, 70){\framebox( 75,20){Field type}}
\put(115, 70){\framebox( 75,20){\# Help Char}}
\put( 40,260){\line(0,-1){220}}
\put(190,260){\line(0,-1){220}}
\put(115, 50){\makebox(0,0){etc.}}
\end{picture}

Though most of the entries of this structure have fixed offsets (from
the assumed beginning of the structure), several form options may
produce a data structure that is quite a bit longer than the segment
pictured above.  For example, if one has defined a default field
content, the actual contents in ASCII follow the default field length
byte immediately, displacing all that follows.  Likewise, if help text
is defined for a given field, it immediately follows the help text 
length byte, displacing anything that follows.  The video attribute 
byte, however, is found at a fixed offset from the field name.

\section{Implementing the features}
\subsection{Read-with-Timeout}
In keeping with the twin goals of modifying the DEC code as little
as possible and doing only what was necessary to accomplish the
project requirements, it was decided to use the timeout feature
for a single character option field rather than a field of arbitrary
length.  A single character field using decimal input allows up to
ten user options, numbered 0 - 9, more than sufficient for this
application.  One could likewise support single character options 
containing alphanumerics and support many more options if necessary,
though if the application became that complex, one should probably
find a better way to implement it.

Adding the read-with-timeout for a single input character feature 
was simply a matter of changing the QIOW in subroutine FDVTIO to a QIO,
adding a MRKT\$ mark time directive for the desired timeout period,
and performing a WTLO\$ wait for logical OR of the event flags for the
QIO and the mark time.  The handling of user input proceeds as normal.
In the case of a timeout, however, the code must supply data as if
the user had entered it, echo it to the screen, and return it to the
calling program.

Two global variables were introduced into the FDVTIO source, called
\$TMO\$ and \$DCHR\$, the timeout period in seconds, and the default 
input character, respectively.  Two simple subroutines were written 
to set the timeout period (subroutine FSTMO) and set the default 
character (subroutine FSDEFC).  At execution time, a test is made on 
\$TMO\$ and if no timeout period is specified, the standard FDVTIO 
routine QIOW is processed normally.  If \$TMO\$ is non-zero, the 
alternate QIO is executed and the mark time is issued.  If the mark 
time event flag is detected prior to I/O completion, an IO.KIL is 
issued for the terminal QIO and the default character supplied by the 
calling program is inserted into the terminal buffer, simulating user 
input.

\subsection{Video Attribute Control}
Once the data structure maintained in the impure area for a given 
field was understood, it was a simple matter to write a routine to 
permit run-time manipulation of a field's video attribute.  Subroutine
FMVID was written to scan the impure area for the field name, which
is stored as a blank padded ASCII string.  The video attribute byte 
for the field in question can then easily be changed to any legitimate
value reflecting the desired combination of the following four possible 
attributes:
\begin{itemize}
  \item bit 0 - underline
  \item bit 1 - reverse video
  \item bit 2 - bold
  \item bit 3 - blink
\end{itemize}

The one assumption made in implementing the field name scan routine
was that the name starts on a word boundary.  It was also observed that
the first field name never began less than \(400_{8}\) bytes from the 
beginning of the impure area.

\section{Software availability}
All of the software discussed above has been submitted to the Fall 1987
RSX SIG tape.  The distribution consists of four Macro-11 assembly language
subroutines (FMVID, FSTMO, FSDEFC, FRVID) and a SLP file to modify the 
FDVTIO subroutine of the form driver library.  The SLP file may be applied 
to the FDVTIO.MAC subroutine source of FMS-11 V2.0 or V2.1. 
\end{document}
