EXODUS/packages/seacas/doc-source/supes/extlib.tex

\chapter{EXTENSION LIBRARY} \label{sec:extlib}
The SUPES Extension Library provides a uniform interface to
necessary operating system functions which are not included in the ANSI
FORTRAN-77 standard.
While the Extension Library itself is implemented in the C programming language,
the interface from a FORTRAN calling program is implemented in
the same manner as in previous versions of SUPES~\cite{SUPES}.
Thus, in the sections below which describe the calling sequence,
the calls are defined accordingly.
This package makes it possible to maintain many codes on
different operating systems with a single point of support for system
dependencies.
Moreover,
this maintenance is done via a single set of source files which
should not only reduce the time involved in bookkeeping,
but allow for the procedures for building a SUPES library to be codified
as well.
These routines provide very basic operating system support;
they are not intended to implement clever features of a favorite system, to
make FORTRAN behave like a more elegant language, or to improve execution
efficiency.

Each module included in the SUPES Extension Library must satisfy the
following criteria:
\begin{enumerate}
\item The routine must provide a service which is beneficial to a wide
range of users.

\item This task cannot be accomplished via standard FORTRAN.

\item This capability must be generic to scientific computers.  Extension
library routines must be supportable on virtually any system.
\end{enumerate}

The SUPES Extension Library routines are designed to minimize the
effort required to implement this software on a new operating system.
This is especially true given that the current single set of source
files handle a variety of system architectures and software
configurations, making those files useful as starting points for a new
port.

Operating system dependencies have been isolated at the lowest
possible level with the major difficulty of a specific port being that
of supplying the proper FORTRAN interface with each C subprogram
module.

\section{User Interface Routines}
This section prescribes the calling sequence for FORTRAN Extension routines
that are meant to be called directly from application programs.

\subsection{Get Today's Date (EXDATE)}

\code{CALL EXDATE( STRING )}

\begin{argy}{STRING}{CHARACTER$*$8}{Write Only}
Current date formatted as ``MM/DD/YY'' where ``MM'', ``DD'', and ``YY'' are
two digit integers representing the month, day, and year, respectively.  For
example, ``07/04/86'' would be returned on July 4, 1986.
\end{argy}

\subsection{Get Time of Day (EXTIME)}

\code{CALL EXTIME( STRING )}

\begin{argy}{STRING}{CHARACTER$*$8}{Write Only}
Current time formatted as ``HH:MM:SS'' where ``HH'', ``MM'', and ``SS'' are
two digit integers representing the hour (00-24), minute, and second,
respectively.  For example, ``16:30:00'' would be returned at 4:30 PM.
\end{argy}

\subsection{Get Accumulated Processor Time (EXCPUS)}

\code{CALL EXCPUS( CPUSEC )}

\begin{argy}{CPUSEC}{REAL}{Write Only}
Accumulated CPU time in seconds.  The base time is undefined; only relative
times are valid.  This is an unweighted value which measures performance
rather than cost.
\end{argy}

\subsection{Get Operating Environment Parameters (EXPARM)}

\code{CALL EXPARM( HARD,SOFT,MODE,KCSU,KNSU,IDAU )}

\begin{argy}{HARD}{CHARACTER$*$8}{Write Only}
System Hardware ID.  For example, ``CRAY-1/S''.
\end{argy}

\begin{argy}{SOFT}{CHARACTER$*$8}{Write Only}
System Software ID.  For example, ``COS 1.11''.
\end{argy}

\begin{argy}{MODE}{INTEGER}{Write Only}
Job mode: 0 = batch, 1=interactive.  For this purpose, an interactive
environment means that the user can respond to unanticipated questions.
\end{argy}

\begin{argy}{KCSU}{INTEGER}{Write Only}
Number of character storage units per base system unit.
\end{argy}

\begin{argy}{KNSU}{INTEGER}{Write Only}
Number of numeric storage units per base system unit.
\end{argy}

\begin{argy}{IDAU}{INTEGER}{Write Only}
Units of storage which define the size of unformatted direct access I/O
records: 0 = character, 1 = numeric.
(For a more in-depth discussion of this topic, the reader is
referred to the VAX FORTRAN manual,
section 13.1.21.)
\end{argy}

The ANSI FORTRAN standard defines a character storage unit as the amount of
memory required to store one CHARACTER element.  A numeric storage unit is
the amount of memory required to store one INTEGER, LOGICAL, or REAL
element.  For this routine, a base system unit is defined as the smallest
unit of memory which holds an integral number of both character and numeric
storage units.

The last three parameters above can be used to calculate the proper value
for the RECL specifier on the OPEN statement for a direct access I/O unit.
For example, if NUM is the number of numeric values to be contained on a
record and IDAU=0, set RECL = ( NUM * (KCSU + KNSU-1) ) / KCSU.


\subsection{Get Unit File Name or Symbol Value (EXNAME)}

\code{CALL EXNAME( IUNIT,NAME,LN )}

\begin{argy}{IUNIT}{INTEGER}{Read Only}
Unit number if IUNIT $>$ 0, or symbol ID if IUNIT $\leq$ 0.
\end{argy}

\begin{argy}{NAME}{CHARACTER$*$($*$)}{Write Only}
File name or symbol value obtained from the operating system. It is assumed
that the unit/file name or symbol/value linkage will be passed to this
routine at program activation.
\end{argy}

\begin{argy}{LN}{INTEGER}{Write Only}
Effective length of the string returned in NAME.  Zero indicates that no
name or value was available.
\end{argy}

This routine provides a standard interface for establishing execution time
unit/file connection on operating systems (such as CTSS) which do not
support pre-connection of FORTRAN I/O units.  The returned string is used
with the FILE specifier in an OPEN statement, as in the following example.
\begin{verbatim}
      CALL EXNAME( 10,NAME,LN )
      OPEN( 10,FILE=NAME(1:LN),... )
\end{verbatim}
The symbol mode of this routine provides a standard path through which to
pass messages at program activation.  An example use is identifying the
target graphics device for a code which supports multiple devices.

\section{Utility Support Routines}
The routines prescribed in this section are intended primarily to support
the SUPES free field input and memory manager utilities.  While calling
these routines directly will not disturb the internal operation of these
other facilities, the use of EXMEMY (section~\ref{sec:exmemy}) in
conjunction with the memory manager is discouraged.

\subsection{Convert String to Uppercase (EXUPCS)} \label{sec:exupcs}

\code{CALL EXUPCS( STRING )}

\begin{argy}{STRING}{CHARACTER$*$($*$)}{Read and Write}
Character string for which lowercase letters will be translated to
uppercase.  All other characters which are not in the printable ASCII character
set are converted to spaces.
\end{argy}

\subsection{Prompt/Read/Echo Input Record (EXREAD)} \label{sec:exread}

\code{CALL EXREAD( PROMPT,INPUT,IOSTAT )}

\begin{argy}{PROMPT}{CHARACTER$*$($*$)}{Read Only}
Prompt string.
\end{argy}

\begin{argy}{INPUT}{CHARACTER$*$($*$)}{Write Only}
Input record from standard input device.
\end{argy}

\begin{argy}{IOSTAT}{INTEGER}{Write Only}
ANSI FORTRAN I/O status:\\
\begin{tabular}{cccl}
IOSTAT &$<$ & 0 & End of File\\
IOSTAT &=   & 0 & Normal\\
IOSTAT &$>$ & 0 & Error\\
\end{tabular}
\end{argy}

This routine will prompt for input if the standard input device is
interactive.  In any case, the input line will be echoed to the standard
output device with the prompt string as a prefix.


\subsection{Evaluate Numeric Storage Location (IXLNUM)}

\code{NUMLOC = IXLNUM( NUMVAR )}

\begin{argy}{NUMVAR}{INTEGER or REAL}{Read Only}
Any numeric variable.
\end{argy}

\begin{argy}{NUMLOC}{INTEGER}{Write Only}
Numeric location of NUMVAR.  This value is an address measured in ANSI
FORTRAN numeric storage units.
\end{argy}


\subsection{Evaluate Character Storage Location (IXLCHR)}

\code{CHRLOC = IXLCHR( CHRVAR )}

\begin{argy}{CHRVAR}{CHARACTER}{Read Only}
Any character variable.
\end{argy}

\begin{argy}{CHRLOC}{INTEGER}{Write Only}
Character location of CHRVAR.  This value is an address measured in ANSI
FORTRAN character storage units.
\end{argy}


\subsection{Get/Release Memory Block (EXMEMY)} \label{sec:exmemy}

\code{CALL EXMEMY( MEMREQ,LOCBLK,MEMRTN )}

\begin{argy}{MEMREQ}{INTEGER}{Read Only}
Number of numeric storage units to allocate if MEMREQ $>$ 0, or release if
MEMREQ $<$ 0.
\end{argy}

\begin{argy}{LOCBLK}{INTEGER}{Read (release) or Write (allocate)}
Numeric location of memory block.  This value is an address measured in ANSI
FORTRAN numeric storage units. Only memory previously allocated to the
caller via EXMEMY can be released via EXMEMY.
\end{argy}

\begin{argy}{MEMRTN}{INTEGER}{Write Only}
Size of memory block returned in numeric storage units.
\end{argy}

In allocate mode, \code{MEMRTN < MEMREQ} indicates that a sufficient amount of
storage could not be obtained from the operating system.  \code{MEMRTN > MEMREQ}
indicates that the operating system rounded up the storage request.

In release mode, memory will always be released from the high end of the
block downward.  \code{MEMRTN = 0} indicates that the entire block was returned to
the operating system.