\documentstyle[11pt,mymacros,gatsman]{article}
\begin{document}
\pagenumbering{roman}

\author{John Burton \\ Larry Gordley}
\package{Scientific Software System (\scubed)}
\rpttype{User's Guide}
\version{2.0}
\reportnum{GATS-1994-03}
\maketitle

\vfill
\begin{center}
\large
\copyright\ Copyright 1992-2005 by G \& A Technical Software, Inc.,\\ 11864 Canon Blvd., Suite 101,
Newport News Virginia, 23606.\\
\vspace{0.1in}
All Rights Reserved. No part of this publication or software may
be reproduced, stored in a retrieval system, or transmitted, in any
form or by any means, electronic, mechanical, photocopying, recording,
or otherwise, without prior written permission of G \& A Technical Software, Inc.
\end{center}
\vfill
\newpage


\tableofcontents
\newpage

\listoffigures
\addcontentsline{toc}{section}{List of Figures}
\newpage
%\listoftables
%\addcontentsline{toc}{section}{List of Tables}
\clearpage
\newpage
\pagenumbering{arabic}
\input psfig

\section{Introduction}

There are many facets to scientific modeling, analysis and data processing. Most
require complicated mathematical procedures that will be be refined through research
efforts spanning several years. These efforts often involve scientists and software
developers from a variety of research centers. The purpose of the Scientific Software
System (\scubed) is to provide a flexible basis for research software development
that can be rapidly adapted to the needs of both individual and group efforts, which
includes orderly evolution of complex software.

Research scientists must have detailed control of their software. Science is by
nature experimental, which translates to fast and frequent changes. These two facts
are often neglected by programming purists who insist on rigid developmental rules.
Somebody once stated that ``Creative minds are seldom tidy''. But large untidy
programs, even if spawned by creativity, will eventually become a severe burden to
maintaining that creative momentum. So scientists are torn between the excitement of
racing to an answer and the future's demand for maintaining order, structure, and
documentation. \scubed solves this dilemma by supplying the ability to do both.

The \scubed package is a software development tool that encourages the use of
top-down software design techniques and modular programming concepts. \scubed
combines the flexibility and rapid prototyping of an interpreted programming language
(such as BASIC) with the power and speed of a compiled programming language (such as
FORTRAN or C). Central to \scubed is the top-down design concept that each task
can be divided into a series of sub-tasks, and each sub-task can be further
divided into a series of sub-tasks. For software development
this implies that each of the higher level modules (tasks) should be essentially a series
calls to lower level modules (sub-tasks). In essence an \scubed program is simply a
list of calls to executable modules. The order in which the modules are called
can be dynamically changed at run-time.

\section{Basic Design Overview}

The primary \scubed objectives are:
\begin{enumerate}
  \item Easy to use. After setup, the user needs to know the syntax for defining a
        variable and calling a module, and little else.
  \item Easy and reliable modification of the system, allowing efficient  group
        development efforts.
  \item Modification without high level code change, aiding in configuration
        control.
  \item Easy maintenance of modularity throughout code development, facilitating a
        continuing orderly evolution.
  \item Simple use of complex modules.
  \item Easy incorporation of new analysis techniques.
  \item Simple interface to graphical analysis tools.
  \item Strong inducement to use structured programming methodologies.
  \item Simplification of understanding and documentation.
\end{enumerate}

These objectives can be accomplished with strict definition and control of data flow
and module interface, and flexible definition of processing logic and data
structures. The method used to achieve these goals is based on four major components;
the Executable Module Table (EMT), the Parameter Definition Table (PDT), the Process
Configuration Tables (PCTs), and the Process Control Program (PCP). The EMT defines
the executable modules that will be used by the system, including type of routine and
the name of the object file.The PDT defines
the constants and datasets that will be used by the
system. Similarly, the PCTs define the order in which modules are executed and which
datasets are passed to a given module.  The PCP is the program that ties everything
together. It dynamically loads the modules specified in the EMT, allocates memory for
the datasets specfied in the PDT, and controls the module execution sequence based on
the information provided by the PCT's. The use of this architecture provides
additional desirable research features:
\begin{enumerate}
  \item Module execution can be easily reconfigured, either before or during
        execution by simply modifying the PCT's.
  \item Program control can be exercised from any module in the system.
  \item Interactive graphical control can be realized simply by inserting 
        independently developed and tested graphics modules.
  \item The user can install his own routines by simply specifing the executable
        module in the EMT file and modifying the appropriate PCT file(s) before execution.
  \item Modules can be written in various languages (currently limited to 
        C and FORTRAN).
\end{enumerate}

\subsection{EMT - Executable Module Table}

The EMT file contains the names of all the functions and subroutines (and associated
filenames) that are called
directly from the PCT level of an \scubed program. Also included in the EMT are the
names of any library and object files that support those functions and subroutines.
All the exectuable modules listed in the EMT file are collected into a shared library
whose members are dynamically loaded as needed during program execution. An example
of an EMT file is included below in figure \ref{fig:simpleemt}.

\begin{figure}[htb]
{\small\tt
\input{testitemt}
}
\caption{\label{fig:simpleemt} Example of a simple EMT file}
\end{figure}

\subsection{PDT - Parameter Definition Table}

The PDT file defines the type of data, number of dimensions, and size of each
dimension for all datasets that are used by an \scubed program. A dataset {\bf must}
be defined in the PDT file before it can be used by the program.  The PDT can be
thought of as a large (FORTRAN) common block of global data structures, but with
critical distinctions:
\begin{enumerate}
  \item The data structures are held in a file, eliminating the
        necessity of code change to a common block. 
  \item The data structures can be accessed only through the calling 
        parameters associated with routines specified in the PCT's. 
\end{enumerate}
This forces preservation of modularity while permitting rearrangement of logic and data
structures with little or no code change.

The PDT file syntax allows the definition of constants which can be later
used to dimension datasets. Each dataset can have zero or more dimensions, with zero
dimensions indicating a simple dataset containing a single value. Additionally each
dataset can be initialized within the PDT file or from an \scubed
control file. An example PDT file, shown in
figure \ref{fig:simplepdt}, demonstrates the basic syntax of a PDT file. Further
details concerning the syntax of a PDT file are provided in the \scubed Reference Manual.

\begin{figure}[htb]
{\small\tt
\input{testitpdt}
}
\caption{\label{fig:simplepdt} Example of a simple PDT file}
\end{figure}

One construct that should be noted in the example PDT file, figure
\ref{fig:simplepdt}, is the {\em group} construct. {\em group} associates a name
with an ordered group of datasets and / or constants, which can later be used
to pass those datasets / constants to an executable module.


\subsection{PCT - Process Configuration Tables}

In contrast to the PDT, which remains unchanged after initialization, the PCT's are
actively involved in the control of the program's execution. Each PCT 
consists of an {\em Execution Order List} (EOL), an {\em
Execution Order Index} (EOI) and an {\em Execution Entry List} (EEL).
Each Execution Entry either specifies a call to an executable module or transfer of
control to another PCT. This
structure is analogous to the multi-level menu interfaces used by many popular
software packages. In these packages, each menu option either performs some operation
or produces a sub--menu. The order in which the entries of a PCT are executed is
controlled by the EOL and EOI. To provide
flexibility, the EOL and EOI for any PCT can be modified at any time during
program execution. Like the PDT, the PCT's are initialized from the appropriate 
PCT files during program startup. 

\begin{figure}[htb]
{\small\tt
\input{testitpct}
}
\caption{\label{fig:simplepct} Example of a simple PCT file}
\end{figure}

\begin{figure}[htb]
{\small\tt
\input{test2pct}
}
\caption{\label{fig:simplesubpct} Example of a simple sub-PCT file}
\end{figure}

The example PCT file given in figure \ref{fig:simplepct} shows the the basic
syntax of a simple PCT file. The PCT file contains a verbal description of the
purpose of the PCT, the EOL, the EOI, and a list of entries. The EEL is
constructed from the list of entries on program startup. The characters comprising
the EOL correspond to the first letter in each line of the list of entries. This
first character is referred to as the entry label. The
letter ``z'' is used to indicate that execution in this PCT should be halted at
this point and control should be passed to the calling or parent PCT. If there
is no parent PCT then execution of the program is halted. The EOI is an index into
the EOL, with zero (0) being the index of the first character in the EOL. The example
in figure \ref{fig:simplepct} will execute the specified routines in the following
order: 
{\tt\begin{verbatim}
FPRINTARRAY  :arr1,arr2,arr3,m1,m2,m3;
FILLARRAY    :arr1,arr2,arr3,m1,m2,m3;
FPRINTARRAY  :arr1,arr2,arr3,m1,m2,m3;
CPRINTARRAY  :arr1,arr2,arr3,m1,m2,m3;
CPRINTARRAY  :arr1,arr2,arr3,m1,m2,m3;
FILLARRAY    :arr1,arr2,arr3,m1,m2,m3;
CPRINTARRAY  :arr1,arr2,arr3,m1,m2,m3;
DUMP         :arr1,arr2,arr3,m1,m2,m3;
\end{verbatim}}

The next set of characters after the entry label specify what type of routine each
entry is. In the example, {\tt FPRINTARRAY} and {\tt FILLARRAY} are FORTRAN
Subroutines, and {\tt CPRINTARRAY} and {\tt DUMP} are C Subroutines. Other
possibilities are described in the \scubed Reference Manual.

It should be noted that when a {\em group} name is encountered in a PCT, the
PCP (described below) simply substitutes the datasets / constants associated
with that group (in the order given in the PDT file) and then passes them
to the executable module.


\subsection{PCP - Process Control Program}

The Process Control Program is the system manager. The PCP
consists of two primary routines, one to initialize the environment which:
\begin{enumerate}
  \item Parses the command line options to determine the operating mode
        of the system.
  \item Reads the EMT file, ensures that the executable module is still current
        relative to its source code, and creates dynamic links to those modules.
  \item Reads the PDT file, creates and initializes the required datasets.
  \item Reads the PCT files and creates an execution tree whose interior nodes are 
        PCTs and whose exterior or terminal nodes are executable modules.
\end{enumerate}
The second primary routine traverses the PCT tree created during initialization in
the order specified by the EOL and EOI, and executes the appropriate modules.

For example, assuming we have an \scubed application program named {\tt example}
and the EMT, PDT and PCT
files shown in figures \ref{fig:simpleemt}, \ref{fig:simplepdt}, and  \ref{fig:simplepct} are named
{\tt example.emt}, {\tt example.pdt} and {\tt example.pct} respectively, a typical invocation of the
program
{\tt\begin{verbatim}
s3 -b example 
\end{verbatim}
}
would result in the following actions:
\begin{enumerate}
  \item Set the operating mode for {\tt example} to check for dataset bounds
        violations (see the \scubed Reference Manual for more about operating modes).
  \item Read EMT file {\tt example.emt} :
     \begin{enumerate}
       \item Compare the timestamps for:
         \begin{itemize}
           \item  {\tt fillarray.o} vs. {\tt fillarray.f}
           \item {\tt fprintarray.o} vs. {\tt fprintarray.f}
           \item {\tt ./csubs/cprintarray.o} vs. {\tt ./csubs/cprintarray.c}
           \item {\tt ./csubs/dump.o} vs. {\tt ./csubs/dump.c}
         \end{itemize}
       \item Recompile any modules that are out of date.
       \item Dynamically load the executable modules so that they may be
             called by the PCP.
     \end{enumerate}
  \item Read PDT file {\tt example.pdt} :
     \begin{enumerate}
       \item Create {\em constant} entries for {\tt m1, m2,} and {\tt m3}.
       \item Create {\em dataset} entries for {\tt arr1, arr1,} and {\tt arr3}.
       \item Allocate memory for datasets {\tt arr1, arr2,} and {\tt arr3}.
       \item Initialize {\tt arr1, arr2,} and {\tt arr3} to the specified
             value.
     \end{enumerate}
  \item Read PCT file {\tt example.pct}: and create a PCT tree containing 1 PCT 
        entry and 4 executable entries.
  \item Start executing {\tt example.pct}. Repeat the following until EOL(EOI) equals ``z''.
    \begin{enumerate}
      \item Get the character EOL(EOI).
      \item Call routine with label given by EOL(EOI).
      \item Check datasets for bounds violations.
      \item Increment EOI.
    \end{enumerate}
\end{enumerate}
This is shown diagrammatically in figure \ref{fig:execution}.

\begin{figure}[htb]
\centerline{\psfig{figure=execution.eps,height=2.85in}}
\caption{\label{fig:execution} Executing an \scubed Program}
\end{figure}

The creation of the executable program {\tt example}, as shown in figure
\ref{fig:creation}, is accomplished by simply typing {\tt make} which in turn
performs a three step
process. First the {\tt setup} utility program reads the PDT and PCT files to obtain
certain information about the routines {\tt fillarray, fprintarray, cprintarray,} and
{\tt dump}. Next, this information is inserted into the main program (PCP) file
which is then compiled along with the files {\tt fillarray.f, fprintarray.f,
cprintarray.c,} and {\tt dump.c}. Finally, these five files are linked together along
with the \scubed library to create an executable program. These steps are all
controlled by the file {\tt Makefile} which controls the {\tt make} process.


\begin{figure}[htb]
\centerline{\psfig{figure=creation.eps,height=2.85in}}
\caption{\label{fig:creation} Creation of an \scubed Program}
\end{figure}

Once the executable program has been created, the user has a limited freedom
to modify how the program executes without having to recreate (re-{\tt make})
the program. The user may:
\begin{itemize}
  \item Change the EOL or EOI line of the PCT file, modifying the order in which
        the routines are executed, or which routines are executed.
  \item Remove a routine from the PCT file.
  \item Change the parameters being passed to a routine.
\end{itemize}
Any other modifications will generally require a re-{\tt make}.

%\section{\scubed Shell}
%
%In order to produce an \scubed based executable via the {\tt make} command,
%the user needs to specify certain information, primarily concerning
%where the \scubed utility programs are located, where the \scubed libraries are
%located, and where the user routines can be found. This information is normally
%passed to the {\tt makefile} either via environmental variables or through
%the command line. To users unfamiliar with the {\tt make} process, this can be
%somewhat confusing. The \scubed Shell is a curses based menu driven user interface 
%provided to help make the process of producing \scubed based executable programs
%less confusing. 
%
%
%\begin{figure}[htb]
%\begin{center}
%\begin{tabular}{|rcl|} \hline
%    &  &  \\
%  0 &-& Configure \\
%  1 &-& Edit File \\
%  2 &-& Make Executable \\
%  3 &-& Execute\\
%ESC &-& Exit  \\
%  &   & \\
% Choice &$=>$& \hfill \\
%\hline
%\end{tabular}
%\caption{\label{fig:s3shell1}Initial \scubed Shell Screen }
%\end{center}
%\end{figure}
%
%Figure \ref{fig:s3shell1} shows the opening menu for the \scubed Shell which
%provides the following functionality:
%\begin{description}
%  \item[Configure:] Allows the user to specify information to be used for \scubed
%                   based applications (sub-menu shown in figure \ref{fig:s3shell2}
%  \item[Edit:] Allows the user to edit a file using the editor specified previously
%               (see figure \ref{fig:s3shell3}).
%  \item[Make:] Creates an executable \scubed application program based
%               on the PCT, user library, and user object files specified.
%  \item[Execute:] Runs the executable \scubed application as a subprocess
%                  under \scubed Shell.
%  \item[Exit:] Exit \scubed Shell and return to the command line.
%\end{description}
%
%\begin{figure}[htb]
%\begin{center}
%\begin{tabular}{|rcl|} \hline
%    &  &  \\
%  0 &-& Environment \\
%  1 &-& Files \\
%  2 &-& Options \\
%  3 &-& Save \\
%  4 &-& Load \\
%ESC &-& Exit  \\
%  &   & \\
% Choice &$=>$& \hfill \\
%\hline
%\end{tabular}
%\caption{\label{fig:s3shell2}\scubed Shell Configuration Sub-menu }
%\end{center}
%\end{figure}
%
%Figure \ref{fig:s3shell2} shows the Configuration menu for the \scubed Shell which
%provides the following functionality:
%
%\begin{description}
%  \item[Environment:] Specifies the pathnames where the \scubed utilities,
%                      libraries, and include files are located. Also allows
%                      specification of which text editor to use.
%  \item[Files:] Specifies the name of the primary and secondary PCT files, and
%                the names of the user library and object files.
%  \item[Options:] Specifies the command line switches to be passed to the
%                  text editor, the compiler and the \scubed application.
%  \item[Save:] Saves the configuration information in the specified file.
%  \item[Load:] Loads the configuration information from the specified file.
%  \item[Exit:] Return to the main menu.
%\end{description}
%
%
%
%\begin{figure}[htb]
%\begin{center}
%\begin{tabular}{|rcl|} \hline
%    &  &  \\
%  0 &-& Edit Any File\\
%  1 &-& Edit C File \\
%  2 &-& Edit FORTRAN File \\
%  3 &-& Edit Header File \\
%  4 &-& Edit Make File \\
%  5 &-& Edit PCT File \\
%  6 &-& Edit PDT File \\
%ESC &-& Exit  \\
%  &   & \\
% Choice &$=>$& \hfill \\
%\hline
%\end{tabular}
%\caption{\label{fig:s3shell3}\scubed Shell Edit File Sub-menu }
%\end{center}
%\end{figure}
%
%Figure \ref{fig:s3shell3} shows the Edit File menu for the \scubed Shell which
%provides the following functionality:
%
%\begin{description}
%  \item[Any:] Generates a list of all files in the current directory and prompts
%              the user to choose one.
%  \item[C:] Generates a list of all files with a .c or .C extension and prompts
%            the user to choose one.
%  \item[FORTRAN:] Generates a list of all files with a .f or .F extension and
%                  prompts the user to choose one.
%  \item[Header:] Generates a list of all files with a .h extension and
%                 prompts the user to choose one.
%  \item[Make:] Generates a list of all files containing ``make'' in the name and
%               prompts the user to choose one.
%  \item[PCT:] Generates a list of all files with a .pct or .PCT extension and
%              prompts the user to choose one.
%  \item[PDT:] Generates a list of all files with a .pdt or .PDT extension and
%              prompts the user to choose one.
%  \item[Exit:] Return to the main menu.
%\end{description}
%
\end{document}
