%
% < Template for Standalone Documents >
%

\input{read_general:[procedures]sesdfmt.tex} 	% Latex input file defining standard format

\newcommand{\revision}{Rev. A}			% latest revision letter

\newcommand{\version}{Version 1}		% latest version 

\newcommand{\rcms} {{\it Remote CMS \/}}
\newcommand{\runningtitle}{Remote CMS Tool V1.0}  	% title for top of page
\newcommand{\control}{ SCI89152 }		% ST ScI control number
\newcommand{\modname}{{\bf rcms.tex}}		% file name in library
\newcommand{\modlibe}{{\bf read\_tools:[sogs]}} 	% BROWSE directory
\renewcommand{\date}{{\bf July 20, 1988}}		% Date of Issue
\renewcommand{\author}{Ted Bauer}		% Author(s) of Document

\thispagestyle{empty}			% No header or number on first page
\markboth{\control \hspace{0.3in} \runningtitle \hspace{0.3in} \revision 
\hspace{0.1in} \version \hspace{0.3in}}{\control \hspace{0.3in} \runningtitle 
\hspace{0.3in} \revision \hspace{0.1in} \version \hspace{0.3in}}

\begin{document}
\vspace*{1in} 
\begin{center} 

{\Large{\bf Remote CMS Tool}}\footnote{This is module \modname{} in 
library \modlibe{}, printed \today} \\

\bigskip
\begin{bf} 
\control \\
\revision \\ 
\date \\
\bigskip 
\end{bf} 
\author \\ 
\bigskip
\vspace*{2.0in}
{\bf Abstract } \\
\bigskip
\end{center}

% ABSTRACT 

The \rcms tool provides an interface to CMS libraries on a
different DECnet node.

\clearpage				% Table of Contents page

\tableofcontents

\clearpage

\section{Introduction}

The \rcms tool provides a CMS interface to CMS libraries on a
different DECnet node.  This lets the user issue CMS commands 
that access a CMS library on a different VAX without having to
log onto that node.

\subsection{Features}

\begin{enumerate}

\item {\bf Command Interface \/}

The \rcms command interface is identical to CMS except that you
use RCMS instead.  Prompting for parameters and remarks
will occur just like in CMS. The SET LIBRARY command is an exception to
these two features (discussed next).

\item{\bf Set Library Command \/}

The \rcms SET LIBRARY command has two restrictions that are different 
from CMS.  The first is that you must enter the entire SET LIBRARY
command because the library name gets parsed by the \rcms tool.
The second is the library name must have a node name on it, a feature
not supported by CMS (and the major reason behind this tool).

\item{\bf File I/O \/}

CMS commands that require input/output files access/create these files 
on your node (known as the CLIENT node), not the node (known as the
SERVER node) where the CMS library lies.  Any CMS command that has
a /INPUT or /OUTPUT qualifier is parsed on the CLIENT node and 
altered (if necessary) to direct input from/output to your node.

\item{\bf No CMS on CLIENT Node \/}

When using the \rcms tool you DO NOT have to have CMS installed
on your CLIENT node.  All CMS activity occurs accross the network at the SERVER
node.

\item{\bf CMS Version 2.3\/}

The \rcms tool has been tested with CMS V2.3.  The tool will be upgraded
to work with CMS V3.0 in the future.

\end{enumerate}

\clearpage

\section{Invoking the Remote CMS Tool}

Use the following command to invoke the \rcms tool:

\bigskip
\begin{verbatim}
   $ RCMS :== $SYS$SYSTEM:RCMS

   $ RCMS    <Any-CMS-command>
\end{verbatim}
\bigskip

{\bf $<$Any-CMS-command$>$ \/} - CMS commands 
are listed in any CMS manual - no reiteration
is needed here.

\subsection{Examples}

Some sample invocations follow:

{\tt\small
 \begin{verbatim}

   $ RCMS SET LIB NEWT::SPSS_CMS     ! This is slightly different from CMS

   $ RCMS

   $ RCMS CREATE ELEMENT/KEEP/NOREF/NOCONCURR any_old_element.dat 

   $ RCMS SHOW LIBRARY/FULL

   $ RCMS 
     RCMS> SHOW LIBRARY
     RCMS> SHOW RESERVATIONS/OUT=reserve.dat
     RCMS> RESERVE any_element.dat "You can reserve with this"
     RCMS> ^Z

 \end{verbatim}
}

\section{Setting Your Remote CMS Library}

The first RCMS command you must always issue is the RCMS SET LIBRARY
command.  This causes a logical name RCMS\$LIB to be defined on
your node that gets translated when passing commands to the 
RCMS process on the SERVER node.

Valid RCMS SET LIBRARY commands must have the NODE name and CMS 
library directories specified.  These cannot be combined into a
single logical name - the RCMS CLIENT process does not translate
the library name - rather it parses it.
However, a logical name can be specified after the node name.
It must be defined in a group logical name table that you
have access to on the SERVER node or in the system logical name table on
that SERVER node.

Some sample SET LIBRARY commands follow:

{\tt\small
 \begin{verbatim}

   $ RCMS SET LIB NEWT::SPSS_CMS
   $ RCMS SET LIB NEWT::disk$hercules:[lib.spss.source.cms]
   $ RCMS SET LIB NEWT::devtools_cms
   $ RCMS SET LIB NEWT::DEVTOOLS_CMS

 \end{verbatim}
}

\section{How the Remote CMS Tool Works}

{\tt\small
 \begin{verbatim}

Client Sends/Server Reads:    Startup
                              Handshake
                              Commands
                              Parameters
                              Remarks
                              What CMS Library
                              What Default Directory
                              What NODE

Server Sends/Client Reads:    Startup
                              Handshake
                              Need Parameters
                              Need Remarks 
                              Status
                              CMS Command Output
                              CMS Status (%CMS)
                 
 \end{verbatim}
}

When you issue an RCMS command at your terminal 
the \rcms tool translates the RCMS\$LIB logical name to see if it
has been defined.  If so it picks off the SERVER node name and 
issues some commands to start the SERVER process via DECNet.

After initial startup, the two processes immediately send a handshake
message to each other to ensure the link is in tact before processing
any commands.

The CLIENT task (your terminal commands this) parses all input commands
to see if they need massaging with /INPUT or /OUTPUT qualifiers.
It then sends the command to the SERVER task.  The SERVER task tries to execute
the CMS command.  If any CMS parameters or remarks are needed it 
asks the CLIENT for more information (who in turn prompts you for this).
After the command is executed on the SERVER node, all CMS messages
are queued up and sentback to the CLIENT for display
on your terminal.  Likewise screen output any CMS commands, such as SHOW, 
get sent back to the CLIENT for display on your terminal.

If you have just entered the command RCMS, the CLIENT process is placed in
interactive mode and a prompt:\\
\begin{verbatim}
                            RCMS>
\end{verbatim}
will appear until you enter Ctrl-Z.  This is the recommended usage of the 
\rcms tool since this minimizes the startup time for the CLIENT
and SERVER processes.

\section{RCMS.COM}

This command procedure gets executed at the SERVER node
when you execute the RCMS command.  It defines the symbol
RCMS as a foreign command with executeable RCMS.EXE.

The command procedure is listed below:

{\tt\small
 \begin{verbatim}

   $! File:        RCMS.COM
   $! Purpose:     Used to start up the Remote CMS SERVER process.
   $! DLM:         7/18/88
   $!
   $!                                                ! Make sure network task
   $ IF F$MODE() .NE. "NETWORK" THEN $ EXIT         
   $!                                                ! Set up RCMS as foreign command
   $ RCMS :== $SYS$SYSTEM:RCMS                       ! Installed via NCP
   $! RCMS :== $SYS$LOGIN:RCMS                       ! Installed in your login directory
   $!                                                ! Execute SERVER task
   $ RCMS SERVER
   $!                                                ! LOGOUT
   $ LOGOUT/FULL

 \end{verbatim}
}

\section{Installing the Remote CMS Software}

The \rcms software must be installed on both the CLIENT and SERVER nodes.
There are two files that are needed to run the \rcms tool: RCMS.COM and 
RCMS.EXE.  On the CLIENT node, only the latter file is necessary, and 
a foreign command symbol must be set up to invoke the tool from that node.
On the SERVER node, there are two ways the the \rcms software 
can be installed:  in your login directory, or in a system area using NCP.

Regardless of how it is installed, inorder to use the \rcms
you must have proxy login access both to the SERVER node from the CLIENT
and from the SERVER node to the CLIENT.  

\subsection{Login Directory}

The \rcms software can be installed so that only your account
on the SERVER (remote) node can execute it.
The command procedure RCMS.COM and executable RCMS.EXE must be copied to your
login directory at the remote node.  RCMS must be edited to 
execute the RCMS.EXE out of your login directory.

\subsection{Systemwide via NCP}

The \rcms tool can also be set up so that it is accessible to multiple 
users, and not tied to any one specific login account.  This must be
done using VAX/VMS Network Control Program (NCP).  This must be done
by your System Administrator, but the steps are as follows:

{\tt\small
 \begin{verbatim}

   $ RUN SYS$SYSTEM:NCP                               ! Invoke NCP
   NCP> DEFINE OBJECT                                 ! Set up RCMS as object
                                                      ! TASKNAME = REMOTE$CMS
               ...
   NCP> LIST KNOWN OBJECT SUMMARY                     ! List it to see if it OK
   NCP> EXIT

 \end{verbatim}
}

When you define the object in NCP a series of questions are
asked about the setup of this task as a remote task.  The following information
must be given:

\begin{enumerate}

  \item{\bf Number \/} - Identifies task (object) by number.  This will
			 always be 0 since the \rcms tools is a user-written
			 program.
  \item{\bf File \/} - Identifies what command procedure will be executed
                       on that node to start up the remote task.
  \item{\bf Priveleges \/} - Specifies those priveleges needed by the object
                             to run.  No special priveleges are needed for the
                             \rcms tool.
  \item{\bf Proxy \/} - Assigns default proxy access control for the \rcms 
		 	object.  
  \item{\bf Account, User, Password } - Not specified.

\end{enumerate}

\section{Limitations}

\begin{enumerate}

\item {\bf CMS DECNet Interface \/}

This first release of the \rcms tools utilizes the CMS DECNet interface when
reading/writing files to the CLIENT node.  For whatever reasons, CMS's
DECNet interfaces are very slow.  A future release of the RCMS tool may 
pass files directly between the CLIENT and SERVER via their DECNet link.

\end{enumerate}

\section{About The Software}

There are many files that are associated with this tool:

\bigskip

\begin{enumerate}

\item{\it RCMS.EXE\/}

Executable for the \rcms tool.

\item{\it RCMS.COM \/}

Explained earlier.

\item{\it RCMS.MMS\/}

This is the MMS file that maintains the RCMS.EXE executable.

\item{\it RCMS.OPT\/}

Linker options file used to create RCMS.EXE.

\item{\it RCMS\_C\_TRNLOG.C \/} 

Used to translate RCMS\$LIB.

\item{\it RCMS\_CMS\_MESSAGE\_HANDLER.C \/} 

SERVER CMS message handler routine.  Queues up CMS status
messages before sending them back to CLIENT.

\item{\it RCMS\_ESTABLISH\_LINK.C \/} 

SERVER/CLIENT routine that established DECNet link
between two tasks.

\item{\it RCMS\_EXECUTE\_CMS\_COMMAND.C \/} 

SERVER routine that calls CMS\$CMS to execute
the CMS comamnd from client.

\item{\it RCMS\_GET\_DEFAULT\_DIR.C \/}

CLIENT routine that does a SHOW DEFAULT.

\item{\it RCMS\_GET\_INPUT\_COMMAND.C \/} 

CLIENT routine that gets a CMS command
from user.

\item{\it RCMS\_GET\_NODE\_NAME.C \/} 

CLIENT routine that gets current node name to be passed
to the SERVER.

\item{\it RCMS\_HANDSHAKE.C \/} 

CLIENT/SERVER routine that sends/read handshake
messages at startup.

\item{\it RCMS\_MAIN.C \/} 

Main program for CLIENT/SERVER.

\item{\it RCMS\_READ\_CMS\_COMMAND.C \/} 

SERVER routine that reads a CMS command from the
CLIENT task.

\item{\it RCMS\_READ\_MESSAGE.C \/} 

CLIENT/SERVER routine that reads data from
opposite task.

\item{\it RCMS\_SCAN\_CMS\_COMMAND.SCN \/}

CLIENT routine that parsed the CMS command before it sends it to
the SERVER to see if it needs to massage any /INPUT or /OUTPUT
qualifiers.

\item{\it RCMS\_SEND\_CMS\_COMMAND.C \/} 

CLIENT routine that ships the CMS command
to the SERVER.

\item{\it RCMS\_SEND\_CMS\_PARAMETER.C \/} 

CLIENT routine that ships CMS parameters 
to the SERVER when an incomplete command is
sent.

\item{\it RCMS\_SEND\_MESSAGE.C \/} 

CLIENT/SERVER routine that sends data to 
opposite task.

\item{\it RCMS\_SETUP\_MESSAGE\_HEADERS.C \/} 

CLIENT/SERVER routines that initialize their
mesasge headers beform sending them to opposite
task via SEND\_MESSAGE.

\item{\it RCMS\_UTILS.C \/}

Set of utility routines used by CLIENT/SERVER.
Primarily VAX descriptor routines.

\item{\it RCMS\_DEFINE\_CMSLIB.C \/}

CLIENT routine that define RCMS\$LIB 
logical.

\item{\it RCMS\_GET\_FIRST\_COMMAND.C \/}

CLIENT routine that gets the  first command
and determines whether \rcms is in interactive
mode or not.

\item{\it RCMS\_SEND\_CMS\_SET\_LIBRARY\_COMMAND.C \/}

CLIENT routine that sends SERVER a set library 
command.

\item{\it RCMS\_SET\_LIBRARY\_COMMAND.SCN \/}

CLIENT routine that calls routine to see if
a SET LIBRARY command issued.

\item{\it RCMS\_TRANSLATE\_CMSLIB.C \/}

CLIENT routine that translates RCMS\$LIB to see if the \rcms
has been invoked earlier.

\item{\it RCMS\_TRASH\_LINK.C \/}

CLIENT routine that disconnects the link to the SERVER
in order to be restarted on another node.

\item{\it RCMS\_SCAN\_FOR\_SET\_LIB.SCN \/}

CLIENT routine that scans for a SET LIBRARY command
with a node name on the library specification.

\end{enumerate}

\end{document}