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

\begin{titlepage}
    \vspace*{1.0in}
    \begin{flushright}
          {\Large\bf Scientific Software  System (\scubed)} \\[.25cm]
          {\rule[.1in]{4.5in}{.02in}}\\[.25cm]
          {\large\bf Reference Manual} \\
          {(Incomplete Preliminary Version)}\\[2.0cm]
          {\large\bf Version 1.0} \\
          {\today}\\[4.0cm]
          {\bf John Burton}\\
          {\bf Larry Gordley}\\[1.0cm]
          {G \& A Technical Software}\\
          {28 Research Drive}\\
          {Hampton, VA. 23666}\\
          {(804)--865--7491}\\
    \end{flushright}
\end{titlepage}

\vfill
\begin{center}
\large
\copyright\ Copyright 1992 by G \& A Technical Software, Inc.,\\ 28 Research Drive,
Hampton. Virginia, 23666.\\
\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{\scubed User's Guide}
There are many facets to remote sensing data processing. Most require complicated
mathematical procedures that will be be refined through research efforts in coming years. These
efforts will 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 the analysis of remote sensing data that can be rapidly adapted to the
needs of the individual researcher, including the simple incorporation of new
processing techniques.

Most remote sensing instruments require two distinct
phases (or levels) of data processing to infer geophysical information. Level I
processing  conditions the measurement data by removing undesirable
instrument effects and calibrating to scientific units. Level II processing involves
an iterative modification of the assumed geophysical state to allow the measurement
model to match the measurement
data. Occasionally when processing the data produced by particular instruments, the
above distinction becomes somewhat blurred. Part of the Level I signal
conditioning may need to be included in the iterative modification of the geophysical
model. The \scubed package provides the necessary flexibility to enable the researcher
to process data using whatever methodology he or she desires.

\subsection{Basic Design Overview}

\scubed Objectives:
\begin{enumerate}
  \item Easy and reliable modification of system.
  \item Modification without high level code change, aiding in configuration
        control.
  \item Easy maintenance of modularity throughout code evolution.
  \item Simple use of complex modules.
  \item Easy incorporation of new analysis techniques.
  \item Simple interface to graphical analysis tools.
  \item Encouragement of structured programming methodologies.
\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 three major
components; the Parameter Definition Table (PDT), the Process Configuration Tables
(PCTs), and the Process Control Program (PCP). The PDT defines the constants and
datasets that will be used by the system. Similarly, the PCTs define the order
in which procedures are executed and which datasets are passed to a given procedure.
The PCP is the program that ties everything together. It controls
the operation of \scubed based on the information provided by the PDT and 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 linking to the main
        program and modifying the appropriate PCT file(s) before execution.
\end{enumerate}

\subsubsection{PDT - Parameter Definition Table}

The PDT is initialized during the program (PCP) start up by reading a PDT file. By
default the PDT filename is {\em program}.pdt where {\em program} is the name of the executable
program created during the {\em make} process. The PDT file contains information
defining the type of data, number of
dimensions, and size of each dimension for all datasets defined. 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 syntax of the PDT file 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 (as opposed to an array) dataset. Additionally each
dataset can be initialized within the PDT 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 section \ref{sec:PDTsyntax}

\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 GROUP construct. 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.


\subsubsection{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
PCP execution. Like the PDT, the PCT's are initialized from the appropriate 
PCT files during PCP startup. 

\begin{figure}[htb]
{\small\tt
\input{testitpct}
}
\caption{\label{fig:simplepct} Example of a simple 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;
CPRINTARRAY  :arr1,arr2,arr3,m1,m2,m3;
FILLARRAY    :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 section \ref{sec:PCTsyntax}.

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.


\subsubsection{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 PDT file and creates the required datasets.
  \item Reads the PCT files and organizes the PCT's into a tree structure consisting
        of PCT's nodes and 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 PDT and PCT
files shown in figures \ref{fig:simplepdt} and \ref{fig:simplepct} are named
{\tt example.pdt} and {\tt example.pct} respectively, a typical invocation of the
program
{\tt\begin{verbatim}
example -b
\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 section \ref{sec:PCPsyntax} for more about operating modes).
  \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}[htbp]
\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}[htbp]
\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}.

\raggedbottom
\newpage

\section{\scubed Reference Manual}

\subsection{\label{sec:PDTsyntax}PDT Syntax}

There are three basic quantities defined in the PDT configuration file, {\em
constants}, {\em datasets}, and {\em groups}, all of which must be
defined prior to use.

\subsubsection{Constants}

A constant is specified using the syntax
\[
  \mbox{\rm CONST:}<name> = <ivalue> \, ; \, [<comment>] 
\]
where:
\begin{eqnarray*}
  <name> &\equiv& \mbox{\rm the name of the constant} \\
  <ivalue> &\equiv& \mbox{\rm the integer value expression to be assigned to $<name>$} \\
  <comment> &\equiv& \mbox{\rm anything between the semi--colon and the end of the line.}
\end{eqnarray*}
Anything enclosed in square brackets $[\,\,]$ is considered optional, and the
 user need not include it in the PDT or PCT file.
$<ivalue>$ is an expression that evaluates to an integer value, and can include the following
arithmetic operations:
\begin{eqnarray*}
  \mbox{\rm +} &\equiv& \mbox{\rm integer addition} \\
  \mbox{\rm -} &\equiv& \mbox{\rm integer subtraction} \\
  \mbox{\rm *} &\equiv& \mbox{\rm integer multiplication} \\
  \mbox{\rm /} &\equiv& \mbox{\rm integer division} \\
  \mbox{\rm \%} &\equiv& \mbox{\rm integer modulus} \\
  \mbox{\rm **} &\equiv& \mbox{\rm integer exponentiation}
\end{eqnarray*}

\subsubsection{Datasets}

The definition of a dataset is accomplished via
\[
<type>\,:\,<namelist>\,[\,:\,<dimlist>\,]\,[\,=\,<ivalue>\,]\,;\,[\,<comment>\,]
\]
where:
\begin{eqnarray*}
  <type> &\equiv& \mbox{\rm the data type contained by the dataset(s) in $<namelist>$} \\
  <namelist> &\equiv& \mbox{\rm the list of one or more dataset names} \\
  <dimlist> &\equiv& \mbox{\rm list of zero or more values indicating the size of each dimension} \\
  <ivalue> &\equiv& \mbox{\rm the initial value(s) of the dataset} \\
  <comment> &\equiv& \mbox{\rm anything between the semi-colon and the end of the line.}
\end{eqnarray*}

The $<type>$ of the dataset can be one of BYTE, STRING, INT, REAL, DREAL, COMP, and
DCOMP. The correspondence of these type to the data types found in FORTRAN and C are
given in table \ref{tbl:datatypes}

\begin{table}[htb]
\begin{center}
\begin{tabular}{||l|l|l||}   \hline 
  \scubed PCT & FORTRAN & C \\  \hline
  BYTE & INTEGER*1 & unsigned char \\
  STRING & CHARACTER*(*) & char * \\
  INT & INTEGER*4 & int \\
  REAL & REAL*4 & float \\
  DREAL & REAL*8 & double \\
  COMP & COMPLEX*8 & struct\{ float imag, real \} \\
  DCOMP & COMPLEX*16 & struct\{ double imag, real \}  \\
  \hline
\end{tabular}
\caption{\label{tbl:datatypes} Correspondence of Data Types}
\end{center}
\end{table}

Each dataset can have multiple dimensions, the size of each dimension is defined by
the corresponding $<dim>$, which can be either the name of a previously defined
constant or an integer value. The correspondence of the dimensioning of \scubed
datasets to FORTRAN and C is given in table \ref{tbl:dimensions} for example datasets
ARR1, ARR2, and ARR3, which are real arrays of 1, 2, and 3 dimensions respectively.

\begin{table}[htb]
\begin{center}
\begin{tabular}{||l|l|l||} \hline
  \scubed PCT & FORTRAN & C \\ \hline
  REAL:ARR1:6 & REAL ARR1(6) & float arr1[6] \\
  REAL:ARR2:6,4 & REAL ARR2(6,4) & float arr2[4][6] \\
  REAL:ARR3:6,4,3 & REAL ARR3(6,4,3) & float arr3[3][4][6] \\
  \hline
\end{tabular}
\caption{\label{tbl:dimensions} Correspondence of Dimensioning Constructs}
\end{center}
\end{table}

\subsubsection{Groups}

Often in a large software package, many executable modules operate on the
same sets of information. If the information set consists of several datasets
and constants, it can be tedious to write the executable entries for these
modules in the PCTs. One method to make this process faster and more comprehensible
is through the use of {\em groups}. Basically a group is defined by associating
a name with an group of datasets and / or constants as shown below. When used in the
parameter list of an executable entry in a PCT, the {\em group} is expanded to the 
list of datasets / constants in the order defined.
A group is specified using the syntax
\[
  \mbox{\rm GROUP:}<name> : <namelist> \, ; \, [<comment>] 
\]
where:
\begin{eqnarray*}
  <name> &\equiv& \mbox{\rm the name to be associated with the group of datasets.} \\
  <namelist> &\equiv& \mbox{\rm the list of one or more previously defined dataset names} \\
  <comment> &\equiv& \mbox{\rm anything between the semi--colon and the end of the line.}
\end{eqnarray*}

\subsubsection{Dataset Initialization}

Initialization of a dataset is accomplished using the $<ivalue>$ construct,
where
\[ <ivalue> \equiv \{\,<value\,list>\,\} \]
and
\[ <value\,list> \equiv <value1> , <value2> , \ldots , <valueM>, \]
for datasets of {\em any} types or
\[ <ivalue> \equiv \mbox{\rm ``character string ''} \]
for datasets of type STRING.
$<valueM>$ is either a single character /  numeric value, or a single character /
numeric value with a repeat factor as shown in the following example:
\[ \mbox{\rm REAL : ARR1 : 20} = \{ 14*27.59, 12.3, 5*1.223 \}; \]
The PDT configuration file given in Appendix A shows clearly how datasets can be
initialized.

\subsubsection{Static Datasets}

By default a dataset will reside on the {\em heap}, the portion of memory
that is used by C when dynamically allocating memory to a routine. 
This provides the ability to tailor, at runtime,  the amount of 
memory used by an application. The drawback to this scheme is that it
does require a small amount of overhead to initially allocate the dataset memory.
Normally this overhead is not noticeable but in certain instances, such as
attempting to allocate individual datasets that approach the size of primary
memory, this overhead can become substantial. 
In these instances it is generally more efficient to {\em statically}
allocate the dataset, which places it on the runtime stack. This will reduce the
startup time at the expense of not being able to modify the size of the dataset
during program execution. Statically allocating a dataset is accomplished using the
following construct.
\[ \mbox{\rm STATIC : } <name1> , <name2> , \cdots , <nameN> ; \]
where $<name1>, \cdots , <nameN>$ are the name of datasets that have been previously
defined. 


\subsection{\label{sec:PCTsyntax}PCT Syntax}

The PCT configuration file establishes which routines will be used, the order in
which they will be used, and the parameters that are to be passed to each. The syntax
of the PCT file is as follows:
\begin{eqnarray*}
  <Title>\,;\, &  [\,<comment>\,]  \\
  <EOL>\,;\, &  [\,<comment>\,]  \\
  <EOI>\,;\, &  [\,<comment>\,]  \\
  <Entry>\,;\, &  [\,<comment>\,]  \\
  \vdots & \vdots \\
  <Entry>\,;\, &  [\,<comment>\,]  \\
\end{eqnarray*}
where:
\begin{eqnarray*}
  <Title> &\equiv& \mbox{\rm Title of this PCT} \\
  <comment> &\equiv& \mbox{\rm anything between the semi--colon and the end of the line.} \\
  <EOL> &\equiv& \mbox{\rm Execution Order List} \\
  <EOI> &\equiv& \mbox{\rm Execution Order Index} \\
\end{eqnarray*}
When parsing the PCT file, the PCP assumes
that the first line of the PCT file is the title, the second line is the execution order list,
the third line is the execution order index, and the remaining lines are the entries.
\[
<Entry> = <key>\,:\,<type>\,:\,<name>\,:\,<param\,list>\,;\,[\,<comment>\,]
\]
where:
\begin{eqnarray*}
  <key> &\equiv& \mbox{\rm Unique character identifier for EOL} \\
  <type>&\equiv& \mbox{\rm One of : PN, CF, CS, FF, FS, DF, DS} \\
  \mbox{\rm PN} &\equiv& \mbox{\rm Process Configuration Table (PCT)} \\
  \mbox{\rm CF} &\equiv& \mbox{\rm ``C'' Function} \\
  \mbox{\rm CS} &\equiv& \mbox{\rm ``C'' Subroutine} \\
  \mbox{\rm FF} &\equiv& \mbox{\rm ``FORTRAN'' Function} \\
  \mbox{\rm FS} &\equiv& \mbox{\rm ``FORTRAN'' Subroutine} \\
  \mbox{\rm DF} &\equiv& \mbox{\rm ``DataSet'' Function} \\
  \mbox{\rm DS} &\equiv& \mbox{\rm ``DataSet'' Subroutine} \\
  <name> &\equiv& \mbox{\rm Name of the executable module or PCT} \\
  <param\,list> &\equiv& <parameter>\, | \, <parameter>\,,\,<param\,list> \,|\, <fname>\\
  <parameter> &\equiv& \, |\, <identifier> \,|\,<ivalue>\,|\,<string> \\
  <identifier> &\equiv& \mbox{\rm Name of a dataset or constant defined in the PDT} \\
  <ivalue> &\equiv& \mbox{\rm Integer value to be passed to $<name>$} \\
  <string> &\equiv& \mbox{\rm Quote enclosed character string to be passed to $<name>$} \\
  <fname> &\equiv& \mbox{\rm Name of PCT file defining  PCT $<name>$}
\end{eqnarray*}
The use of the vertical bar ($|$) indicates ``or'', i.e.
\[
  <parameter> \equiv \, |\, <identifier> \,|\,<ivalue>\,|\,<string>
\]
means that
$<parameter>$ is equal to (can be replaced by) an $<identifier>$ {\bf or} an
$<ivalue>$ {\bf or} a $<string>$.

An entry can be one of two major types, a PCT 
(which is a recursive definition: a PCT can contain a PCT , which can
contain a PCT ...), or an Executable. A PCT is identified by $<type> =
\mbox{\rm PN}$. It also has only one ``parameter'' in its parameter list, which is
the name of the file containing the configuration information for that PCT node. An
Executable node can be classified as one of several types depending on the way
parameters are to be passed,
via C language passing mechanism (``C''), via FORTRAN language passing
mechanism (``F''), or the routine expects the dataset data structure to be passed (``D''),
and if it returns a value (function ``F'') or not (subroutine ``S'').

The C language parameter passing mechanism implies that the routine is
written in C according to the following conventions:
\begin{itemize}
  \item Parameters are passed by reference, not by value, so the C routine
        should expect a pointer to the data object, not the data object itself.
  \item Each additional dimension, after the first, on a multidimensional array 
        requires an additional
        level of indirection. i.e. if the dataset to be passed to a C routine has
        been declared {\tt REAL: arr3: m1,m2,m3} then within the C routine it should
        be declared as {\tt float  ***arr3;}. Subsequent manipulation can be
        accomplished as though the declaration had been {\tt float
        arr3[m3][m2][m1]}. Note the reversed dimension declarations. This is
        necessary because C uses row--major ordering for multi-dimensional arrays,
        where FORTRAN uses column--major ordering. The array declaration syntax for the
        PDT file was designed to be consistent with the FORTRAN convention, 
        column--major ordering.
  \item Strings are NULL terminated, BLANK filled character arrays whose length is
        specified in the PDT file.
\end{itemize}

The parameter passing mechanism for \scubed attempts to make interfacing  FORTRAN
routines as simple and straight forward as possible. For the most part a standard
FORTRAN approach with some minor restrictions was used to handle parameter passing.
Specifically the FORTRAN routine should:
\begin{itemize}
  \item Declare strings passed as parameters to have ``previously defined limits'',
        i.e. the size of the string was declared in the calling program. This
        declaration is accomplished via {\tt CHARACTER*(*) string}.
  \item Declare arrays as predefined (similar to the string declaration) or explicitly
        include the array's dimensioning information in the parameter list.
        Dimensioning arrays within a routine to a different size (particularly
        a larger size) than was declared in the PDT file will lead to 
        unpredictable results. (Note: there is a run time option that will
        perform runtime bounds checking upon exit from each routine call
        from a PCT)
\end{itemize}

Each dataset that is declared in the PDT and subsequently used in a PCT has
associated with it some bookkeeping information that is maintained by the \scubed
program. This includes such information as the name of the dataset, the type of the
data, the number of dimensions, the size of each dimension, and a pointer (memory
address) to the beginning of the data. Most of the time the user does not need
to access this information and will simply want the data (or rather a pointer
to the data - FORTRAN passes parameters by reference to the data by default),
which is what a routine declared as ``C'' or ``F'' will have passed to it. On
the other hand, a routine declared as ``D'' will have the entire dataset data
structure passed to it. Such a routine can then modify any of the bookkeeping
information about the dataset. Care should be taken when modifying dataset
information in this way, since such modifications could have unpredictable 
results.


In general, routines written in FORTRAN will be either ``FF'' or ``FS'', routines
written in C will be either ``CF'' or ``CS''. The ``DF'' and ``DS'' types are used only
when it is necessary to manipulate the entire dataset data structure instead of just
the data. 


An executable classified as a function (``F'') is expected to return an integer
value. This value is in turn used to modify how the system is functioning.
A return value of zero (0) indicates that the PCT should continue executing according
to the Execution Order List and Execution Order Index. A return value of one (1)
indicates that the PCT should halt at this point and return control to the calling or
parent PCT node. The next time the child PCT node is called, it will pick up where it
left off by starting  to execute at the next routine indicated in the Execution Order
List. A return value of greater than one (1) specifies how many levels of PCTs to
ascend.  (A return value of 2 would mean to halt this PCT and the parent PCT,
3 would mean to halt this PCT, the parent PCT, and the grandparent PCT, etc.)



\subsection{\label{sec:PCPsyntax}PCP Syntax}

The Process Control Program performs two major functions. First it creates and
initializes the \scubed runtime environment, and then it calls (executes) the
appropriate routines as specified by the PCT files. The PCP has several command line
options that affect overall execution. The user can specify an alternate base name for the
primary PCT and PDT files, i.e. if the user specifies a base name of {\em foo}
then the PCP will look for the two files {\em foo}.pdt and {\em foo}.pct. Otherwise
the PCP will look for the two files {\em program}.pdt and{\em program}.pct.
Execution of the PCP will then continue based on the files specified. The user has a
choice of several operating modes; 
\begin{itemize}
  \item Normal mode (default) displays no information about the execution
        progress.
  \item Bounds check mode (-b command line option) checks for dataset bounds
        violations (modifying memory beyond the limits of a dataset) after each
        routine called at the PCT level.
  \item Profile mode (-p command line option) displays cumulative execution
        statistics concerning how many times each routine was called and the total 
        time spent in each routine.
  \item Verbose mode (-v command line option) displays information concerning
        which routine is currently executing and how much time was required for that 
        routine to execute.
\end{itemize}  

Extensions to the capabilities of the PCP are primarily added via the \scubed
utilities library. The current utilities library provides PCT looping constructs DSZ
(decrement and skip if zero) and ISE (increment and skip if equal), conditional
branching (if\_then\_else), file copying, and creation of child processes via a system
call. These routines are discussed in greater detail in the Appendices.


\subsection{\scubed Based Implementation}

To create an \scubed based
program the user needs to determine which routines will be called, what order they
will be called in, and the type, size and dimensionality of each parameter required
by the particular routine. The user then creates PDT and PCT files based on this
information. The PDT file is used to define the
size, type, and dimensionality of each variable that will be passed to the various
routines. The PCT files are used to define which routines are called, what
order they are called in, and which parameters are passed to them. 
As a starting point, in addition to the \scubed library and PCP main routine, the \scubed 
package includes a basic set of routines for analyzing data generated by the
SAFIRE instrument. These routines are supplied in two libraries, the GATS LINECAL library 
of limb line-by-line radiance profile routines, and the SDAS library of data analysis
routines specifically tailored for the SAFIRE instrument data.

In many situations the \scubed library (and PCP main routine) combined with the 
SDAS data analysis
routines will satisfy the researcher's processing and analysis needs. 
In other situations the researcher will want to include their own routines in the
\scubed hierarchy for a particular aspect of processing. Both situations are
discussed in greater detail below.


\subsubsection{Initial Installation}

Before an \scubed program can be created, the \scubed package must be installed.
The \scubed software package is currently supported only on AIX 3.1.5 (IBM's version of
UNIX) running on the IBM RS/6000 architecture. Work is in progress to port \scubed to
Sun OS 4.1.1 running on the Sun Sparc architecture. To be installed on a particular
system, the \scubed package requires the system to have both a FORTRAN 77 compiler
and a C compiler (preferably ANSI C compliant). The \scubed software package is
supplied in UNIX {\em tar} file format. To install \scubed on a UNIX system simply
follow the steps given below.
\begin{enumerate}
  \item Create a temporary directory for use during the installation process.
        Although the directory can have any legal name, for purposes of these
        instructions it will be called {\tt TEMP}.
  \item Place the {\tt S3.tar} file in {\tt TEMP}.
  \item Type {\tt tar -xvf S3.tar >\& tar.log}
  \item After the {\tt tar} command finishes, the following files should be in {\tt TEMP}:
  \begin{enumerate}
    \item {\tt Makefile}
    \item {\tt Manifest}
    \item {\tt README}
    \item {\tt Version}
    \item {\tt tar.log}
  \end{enumerate}
        and the following subdirectories:
  \begin{enumerate}
    \item {\tt Linecal}
    \item {\tt S3}
    \item {\tt SDAS}
  \end{enumerate}
  \item Compare {\tt Manifest} to {\tt tar.log}. They should contain the 
        same filenames. If not, you should contact G \& A Technical Software.
  \item Decide where various files needed by the \scubed package will be located:
  \begin{enumerate}
    \item Set the environmental variable S3SRCDIR to the directory that will contain
          the \scubed PCP source file ({\tt s3main.c}) (for example
          {\tt setenv S3SRCDIR /usr/local/src} ).
    \item Set the environmental variable S3INCDIR to the directory that will contain
          the \scubed include (header) files  (for example 
          {\tt setenv S3INCDIR /usr/local/include} ).
    \item Set the environmental variable S3LIBDIR to the directory that will contain
          the \scubed, SDAS, and LINECAL libraries (for example 
         {\tt setenv S3LIBDIR /usr/local/lib} ).
    \item Set the environmental variable S3BINDIR to the directory that will contain
          the \scubed {\tt setup} utility program (for example 
          {\tt setenv S3BINDIR /usr/local/bin} ).
  \end{enumerate}
     The particular directories specified above are examples for installing the
     \scubed package on a system where multiple users will be using the package and 
     would probably require help from the Systems Administrator (the installation
     process needs {\em write access} to the specified directories). For a single
     user, simply set the environmental variables to specify directories within the 
     users directory structure. 
     The environmental variables specified will be used both during the installation process and
     every time the \scubed based program is reconfigured, so it is advisable to make
     them a permanent part of the environment (i.e. have them set during the login
     process via either the {\tt .cshrc} or {\tt .login} files for the {\tt csh} or {\tt
     tcsh} user shell, or the {\tt .profile} file for the {\tt sh} or {\tt ksh} user
     shell. 
  \item Once the environmental variables have been set, make sure you are in the {\tt
        TEMP} directory and type {\tt make >\& make.log}. This process compiles and
        creates the libraries that are used by the \scubed system and will take
        several minutes to complete.
  \item Once the {\tt make} process has been successfully completed (check {\tt
        make.log} for any error messages), now type {\tt make install >\&
        install.log}. The {\tt install} process will copy the appropriate files 
        to the directories specified by {\tt S3SRCDIR, S3INCDIR, S3LIBDIR,}
        and {\tt S3BINDIR} (requires {\em write} access to these directories).
\end{enumerate}
The initial installation is now complete.


\subsubsection{Creating \scubed Application Programs}

Once the \scubed package has been installed, the user can begin
to create application programs. 
As a first step copy the file {\tt Makefile.s3} from the {\tt S3SRCDIR}
and rename it {\tt Makefile}(i.e. {\tt cp S3SRCDIR/Makefile.s3 Makefile}). 
As mentioned previously, the \scubed package provides
the appropriate routines to perform basic limb profile retrievals. To create an
\scubed program {\tt example2} that will only use routines in the SDAS or LINECAL libraries, the
user will need to create a PDT {\tt example2.pdt} file defining the required
parameters and a primary PCT file {\tt example2.pct} defining the routines used, the
parameters to be passed to them, the order in which they are called, and any
secondary PCT files that are to be used. The user must also create any secondary PCT files
required. Modify the
the line in {\tt Makefile} that reads {\tt NAME = safire} to read {\tt NAME =
example2}. Now simply type {\tt make} and if no errors are encountered, an executable
program file named {\tt example2} will be created in the current directory.
This process of \scubed program creation is shown diagrammatically in 
figure \ref{fig:creation}, where the {\tt make} process is represented by the thick
lined box.


Since for this example, all the executable routines are provided with the \scubed
package, once the  program has been created, the only time that it would be necessary to do
a {\tt make} is when:
\begin{enumerate}
  \item Adding a new routine to a PCT file (i.e. adding a routine that is not
        in one of the PCT files).
  \item Changing the name, size, type or dimensionality of a dataset that is declared
        STATIC in the PDT file.
\end{enumerate}

Adding routines that are not provided with the \scubed package, i.e. {\em user
defined routines}, is covered in the reference section \ref{sec:userroutines}.

\subsubsection{\label{sec:userroutines}Adding User Defined Routines}

Adding a user defined / created routine to an \scubed based program is 
accomplished by:
\begin{enumerate}
  \item Specifying the user routine in the appropriate PCT file(s).
  \item Defining the required datasets in the PDT file.
  \item Specifying the location of the user routine in
        {\tt Makefile}.
  \item Typing {\tt make}
\end{enumerate}
The {\tt Makefile} assumes that the user routine will be available in one of two
forms, source code (FORTRAN or C) in a file in the current directory, or in a 
previously compiled library (see figure \ref{fig:creation}) To include a routine 
that is in a source file, simply
modify the {\tt USROBJS = } line in the {\tt Makefile} to include the name of the 
source file with a {\tt .o} extension (i.e. if the source code is in a file named
{\tt routine.f}, modify the {\tt USROBJS = } line to read {\tt USROBJS = routine.o}).
This will cause {\tt make} to compile the source file and link it to the \scubed
program. Anytime the source file is modified, a {\tt make} should be performed.
To include a routine that is in a precompiled library, simply modify the {\tt USRLIBS
=} line in the {\tt Makefile} to include the pathname of the library (i.e. if the
library is {\tt /u/jcburt/lib/libjunk.a}, modify the {\tt USRLIBS = } line to read
{\tt USRLIBS = /u/jcburt/lib/libjunk.a}). In this case, the user is responsible for 
ensuring that the specified library is current, {\tt make} will not be able to 
determine if the library is up-to-date. 

\subsubsection{Running \scubed Application Programs}

To run an \scubed based program, simply type in its name followed by any command line
switches. If we wanted a verbose execution of {\tt example} with a execution profile
displayed at the end, simply type {\tt example -v -p}. {\tt example} will then read
the files {\tt example.pdt} and {\tt example.pct}, and then perform the operations
specified in the PCT file(s) (see figure \ref{fig:execution}). If a new routine was
added with out subsequently performing a {\tt make} the \scubed program will halt
with an error message indicating that it can't find the routine. If this occurs,
simply run {\tt make} which should correct the problem.

\newpage


\appendix
\raggedbottom

\section{\scubed Example}


\begin{figure}[htb]
\centerline{\psfig{figure=sdas-pct.eps,height=6.0in}}
\caption{\label{fig:pctstruct} PCT Structure for \scubed Example}
\end{figure}
\clearpage
\newpage


\subsection{Example PDT configuration file}
\input{pdt}
\clearpage
\newpage

\subsection{Example PCT configuration files}
\input{pct}
\clearpage
\newpage

\section{\scubed Utility Routines}
The following pages contain descriptions of the \scubed utility routines. The primary
purpose of these routines is to provide the user access to the Execution Order
Control information stored in the Process Control Table(s), and to perform some
simple operations on datasets.

\newpage

{\input{get_eol}}
\newpage
{\input{get_eoi}}
\newpage
{\input{set_eol}}
\newpage
{\input{set_eoi}}
\newpage
{\input{increment}}
\newpage
{\input{decrement}}
\newpage
{\input{resize}}
\newpage
{\input{ise}}
\newpage
{\input{dsz}}
\newpage
{\input{ifthenelse}}
\newpage
{\input{call_sys}}
\newpage
{\input{copyf}}
\end{document}
