%		BAISLEY$PAPERS:CCSPEECH.TeX
%
%  This file is the preliminary version of a talk given at the Fall '86
%  DECUS in San Francisco by Wayne E. Baisley, Rockwell International / 
%  Graphic Systems Division, Lombard, Illinois.
%
%  This file, when run through TeX, will be formatted as described below.
%  It uses the macro package DEPROC.TeX plus a few locally defined macros,
%  all of which are given at the top of the file.
%
%  Although essentially complete, and to the best of my knowledge correct,
%  some details can be expected to change prior to publication.  Particularly,
%  the figures are not complete, and this version is geared toward speaking 
%  rather than reading.  The final version should appear in the Proceedings.
% 
%  Wayne E. Baisley
%  Rockwell International / Graphic Systems Division
%  455 Eisenhower Lane
%  Lombard, Illinois  60148-5410
%
%  September 30, 1986
%
%  WARNING!  DO NOT TYPE ANY OF THE FOLLOWING 10 CHARACTERS EXCEPT AS DIRECTED:
%                &   $   #   %   _   {   }   ^   ~   \   

\parskip=2ex plus 1pt

\input deproc

%\def\SpeechFormat{\OneCol	% Barbara Beeton's SpeechFormat
%	\magnification=\magstep1
%	\headmargin=9pc
%	\Adjustxy
%	\normalcollgt=40pc
%	\collgt=\normalcollgt
%	\resetpagelgt }

\SpeechFormat

\NoParIndent

%\def\TalkFormat{\OneCol		% Like Barbara Beeton's only different
%		\magnification=\magstep2}
%
%\TalkFormat

%	macros needed for this talk

%\font\tenbf=cmbx10
%\font\twlvbf=cmbx12
%\font\twlvrm=cmr12
\font\big=cmr12
\font\btt=cmss10
\font\bigtt=cmss12
\define\GSD{Rockwell~International / Graphic~Systems~Division}
\define\Proc{Proceedings}
\define\DP{{\tt DEPROC}}
\define\DProc{{\sl DECUS \Proc}}
\define\POBox{P.\thinspace O.~Box }
\define\TB{{\sl The \TeX book}}
\define\TUB{TUGboat}
\define\TUG{\TeX\ Users Group}
\def\vax{\leavevmode\hbox{\btt V\kern-.4em A\kern-.04em X}}
\def\vaxc{\leavevmode\hbox{\btt V\kern-.4em A\kern-.04em X C}}
\def\VAX{\leavevmode\hbox{\bigtt V\kern-.4em A\kern-.04em X}}
\def\VAXC{\leavevmode\hbox{\bigtt V\kern-.4em A\kern-.04em X C}}
\def\cc{\leavevmode\hbox{\btt C}}
\def\system{\leavevmode\hbox{\btt system}}
\def\System{\leavevmode\hbox{\btt System}}
\def\SYSTEM{\leavevmode\hbox{\bigtt system}}
\def\boxit#1{\vbox{\hrule\hbox{\vrule\kern5pt\vbox{\kern5pt#1\kern5pt}\kern5pt\vrule}\hrule}}
\def\rsx{\leavevmode\hbox{\btt RSX}}
\def\rsxm{\leavevmode\hbox{\btt RSX-11M}}

\title{Filling Some Holes In The \VAXC\ Run-Time Library ---\\
    The ``\SYSTEM'' function and related support routines}
\author{Wayne~E.~Baisley\\
    \GSD\\
    Lombard,~Illinois\\
    \\
    LT108, DECUS Fall 1986 Symposium\\
    San Francisco, California}

\begin{abstract}
The \vaxc\ Run-Time Library provides VMS support for a 
large subset of the UNIX system support routines.  One notable exception is the 
``\system'' function, which passes a command line to a shell or Command 
Line Interpreter (probably the easiest way to make any utility ``callable'').
This paper describes an implementation of the ``\system'' function using \vaxc.
Also described are a number of related and general support routines, and header 
files.
\end{abstract}

\begin{document}

\maketitle
\NoParIndent

\section UNIX is the source of many useful programs and ideas

%\footnotetext[\dag]{UNIX is a trademark of AT\&T Bell Laboratories} 
%UNIX\footnotemark[\dag]  is the source of many useful programs and ideas

UNIX %\footnote[\dag]{UNIX is a trademark of AT\&T Bell Laboratories}
has been the source of many very useful programs and ideas.  For example

\smallskip

\item[\bullet]	The Make utility which automates compilation and linking
		based on dependency rules and file time-stamps
\item[\bullet]	The Source Code Control System, or SCCS, for managing 
		multiple versions of source files
\item[\bullet]	The Shells which are programmable Command Line Interpreters
\item[\bullet]	Pipes which allow the output of one program to be fed directly 
		into another without creating a temporary file
\item[\bullet]	Grep, Who, and other utilities
\item[\bullet]	And, of course, the \cc\ language

\smallskip


\section VMS is flexible enough to capitalize on, or at least to accommodate, UNIX ideas

Fortunately for \vax\ users, VMS is flexible enough to capitalize on, 
or at least to accommodate, these useful UNIX ideas.  For example, 

\smallskip

\item[\bullet]	The Module Management System, or MMS, which is very similar to 
		Make
\item[\bullet]	The Code Management System, or CMS, which is analogous to SCCS
\item[\bullet]	The DEC/Shell product which is the UNIX Bourne shell, 
		complete with pipes and many UNIX utilities on VMS
\item[\bullet]	Grep, Who, and other utilities, which are available from DECUS 
\item[\bullet]	And, of course, \vaxc\ along with the \vaxc\ Run-Time Library

\smallskip
All these items, and others, are readily available VMS equivalents of 
UNIX concepts and programs.

%(VMS users owe UNIX and its developers some 
%respect at least for the richness of VMS's features.)

\section VMS can do anything UNIX can do better

I conclude therefore that

\smallskip

\centerline{VMS can do anything UNIX can do better}

\smallskip


\section The \vaxc\ Run-Time Library provides most of the useful UNIX \cc\ features

Let's take a closer look at the \vaxc\ Run-Time Library, which is what DEC 
calls their collection of \cc\ support routines.
The \vaxc\ Run-Time Library provides most of the useful features of UNIX \cc, 

\smallskip

\item[\bullet]	The character string manipulation functions
\item[\bullet]	The standard, meaning portable or generic, I/O functions
\item[\bullet]	The UNIX-specific I/O functions
\item[\bullet]	The {\em curses} CRT window management functions
\item[\bullet]	And many others

The \vaxc\ Run-Time Library also provides unique VMS features, such as DECnet 
and RMS support, and the \vaxc\ calling standard, which allows \vaxc\ to call 
and be called by any other \vax\ language.

The \vaxc\ compiler, besides all the standard language features also supports 
the \vax\ Language Sensitive Editor and the Common Data Dictionary.  It even 
goes UNIX one better by producing listings if you want it to.

\section The \VAXC\ Run-Time Library omits at least one of the commonly-used UNIX \cc\ features

One particularly useful UNIX \cc\ feature has yet to be exploited by the \vaxc\ 
developers, however.  

\centerline{The \system\ function ---}
\smallskip

\item[]		is a means of ``easily'' passing a command to the shell or 
Command Line Interpreter (CLI).  What do I mean by ``easily''?  Well, 
certainly not necessarily easy to implement, at least on VMS.  But an example 
will show how easy it is to use.  The \cc\ statement at the bottom of this 
slide \smallskip

\item[]		stat = \system\ (``\hbox{\btt A command I want done}'');
\smallskip

shows a static command string being passed to the \system\ function for 
execution, with the exit status to be stored in the variable ``stat''.

It's that easy to use.  And you needn't limit yourself to canned command
strings as is the case in this example.  You can construct the command string
on the fly, which is very useful, since string manipulation is one of \cc's
stronger points. 

%This approach epitomizes the UNIX philosophy to software; a collection of 
%mostly simple functions that work well together.

\section The \system\ function provides a very useful service

	We first used \system\ on \rsxm\ to integrate separate Whitesmiths
Ltd.\ \cc\ compiler components.  Rather than having to invoke a command file
or run the individual components, a single command could be issued.  For
example, the command shown at the top of this slide 

\smallskip
\item[]		$>$pcc -fps xyz.c
\smallskip
passes a sequence of commands to the \rsx\ CLI known as MCR.  This 
command sequence is abbreviated on the lower half of the slide.
\smallskip
\item[]		pcc$>$ cpp -xi qr:[301,376] -o xyz.tm1 $>$xyz.er0 xyz.c
\item[]		pcc$>$ del xyz.er0;*
\item[]		pcc$>$ cp1 -o xyz.tm2 $>$xyz.er1 xyz.tm1
\item[] $\vdots$
\item[]		pcc$>$ del xyz.tm4;*
\smallskip
As you can see, the ability to construct a command string based on the file
name xyz.c, and the command line options which is the ``-fps'' part, is
enormously useful, and has the advantage of being ``portable'' in the sense
that it doesn't depend directly on \rsx\ system directives.  Incidentally, the
``-fps'' stands for ``produce a full listing'', ``don't submit the listing to
the print queue'', and ``show me the MCR commands as they are issued''. This
terse, even cryptic approach to command line options epitomizes the UNIX
philosophy.  Form takes a back seat to function.  VMS is nearly the opposite, 
with every option spelled out.  At least it lets you abbreviate.

\section We had to reinvent the \system\ function for VMS

	A year or so after using \system\ in the PCC program, we began using a
\vax\ for \rsx\ development, and had to write a \system\ function to work with
VMS.  This proved much more difficult than for \rsx, which had involved little
more than the Spawn (\hbox{\btt SPWN\$}) and Wait For Single Event Flag
(\hbox{\btt WTSE\$}) directives. 

	Fortunately, the \hbox{\btt LIB\$SPAWN} routine in the VMS Run-Time 
Library does nearly all that \system\ requires.  As represented in this slide, 
it creates a subprocess, copies logical names and DCL symbols, handles many 
other messy details, and then passes the command to the CLI.  

	However, it is fairly slow since a new process is created and then
deleted for each call to \hbox{\btt LIB\$SPAWN}.  And we had problems with
using it from MMS (which is also based on \hbox{\btt LIB\$SPAWN}), from batch
jobs, and from batch jobs using MMS.  One other obnoxious side-effect was that
some ways of using \hbox{\btt LIB\$SPAWN} produced log-out messages from the
subprocess after each \system\ call. 
\midinsert
$$\boxit{\vbox{\hsize 2.5truein \vsize 1.5truein \noindent \strut Process
\vskip .5truein system (``\hbox{\btt TIME}'')}}\hskip 1truein
\boxit{\vbox{\hsize 2.5truein \vsize 1.5truein \noindent \strut Subprocess
\vskip .5truein \$ TIME}}$$
\endinsert
{\bf Figure 1}

\section And then performance was improved greatly
%Making \system\ perform ``well'' on VMS required some effort
	Performance was improved greatly by calling \hbox{\btt LIB\$SPAWN} to
create a subprocess just once, and then reusing it as a ``server'' for DCL
commands. 

	Mailboxes are used to feed commands to the ``server'' and to retrieve
output and status information, as shown in this slide. \System\ writes
commands to the input mailbox, as represented by the upper arrow, which are
handled by the subprocess's CLI.  Any output or error messages are written to
the output mailbox represented by the lower arrow, read by \system, and
echoed on the terminal.  \System\ also uses the mailboxes to obtain the exit
status of the command.  More about that in a minute. 
\midinsert
$$\boxit{\vbox{\hsize 2.5truein \vsize 1.5truein \noindent \strut Process
\vskip .5truein \system\ calls}}\hskip 1truein
\boxit{\vbox{\hsize 2.5truein \vsize 1.5truein \noindent \strut Subprocess
\vskip .5truein DCL Server}}$$
\endinsert
{\bf Figure 2}

\section The implementation of \system\ on VMS was complicated, though straightforward

As I said before, the implementation of \system\ on VMS was complicated;
however it was straightforward.

	Many factors contributed to the difficulty.  
\smallskip

\item[\bullet]	First, we must create mailboxes.  Not terribly difficult, but 
something of a nuisance, particularly since we have to avoid any mailbox name 
conflicts.  We chose to derive the mailbox names from the name of the calling 
image and the process id (also called the P-I-D, or pid).  For example, we 
might name an input mailbox PCC\_0063\_INPUT.
\item[\bullet]	Next, arguments to the VAX Run-Time Libraries and System 
Services are usually passed by descriptor.  Not a terrible burden, but not 
as simple as passing by reference, either.  This is another example of 
the difference between UNIX and VMS.  UNIX typically uses NUL-terminated 
strings, which are adequate for most situations, but not all.  VMS uses a 
general-purpose object-oriented data structure called a descriptor, which is 
very flexible but more trouble than strings.  Both have their place.  They're 
just different.
\item[\bullet]	Next, we must obtain the image exit status for each command 
we issue to the ``server''.  As I mentioned before, \system\ uses the
mailboxes to do this.  The trick here is to wait for a read to be posted by
the subprocess's CLI for the input mailbox, issue another command to that CLI
to write the current value of the \hbox{\btt \$STATUS} symbol to the output
mailbox, read the result, and finally return its severity portion (the low
order 3 bits) to the caller.  This trick works like magic, and isn't
confounded by attempts of images in the subprocess to read from the mailbox,
because of the way DCL handles commands lines which start with a dollar sign. 
% \System\ doesn't allow the subprocess to obtain input directly from 
%\system's caller.
We could have used other means such as accounting messages to get the exit
status, but this one is quite adequate. 

	There are a few other less interesting but important items which 
\system\ must take care of, such as 
\item[\bullet]	handling unexpected subprocess termination,
\item[\bullet]	handling \^{}Y and \^{}C aborts, and
\item[\bullet]	cleaning up on the exit of the image calling \system.
\smallskip

	So, in spite of all the work and messy details involved, VMS 
proves quite amenable to an well-behaved, high-performance implementation 
of \system.

\section The \system\ function serves as a useful example

Besides the service it performs, the \system\ function serves as a useful 
programming example of 
\smallskip

\item[\bullet]	how to use the \hbox{\btt LIB\$SPAWN} routine,
\item[\bullet]	calling VMS System Services from C,
\item[\bullet]	using descriptors in C,
\item[\bullet]	writing AST service routines,
\item[\bullet]	writing exit handlers,
\item[\bullet]	using the VMS Message facility, and
\item[\bullet]	how VMS can be difficult for programming.
\smallskip


\section Other related functions were developed along with \system

Other related functions were developed along with \system\ which are of some 
utility on their own.

\item[\bullet]	{\em cimageid}	returns the name of the currently 
executing image as a string.  It is used by \system\ to construct the mailbox 
and subprocess name strings. 
\item[\bullet]	{\em complain}	is a simple way to produce VMS-style
error messages
\item[\bullet]	{\em crembx}		creates a mailbox with a given name 
and certain fixed parameters such as buffer length
\item[\bullet]	{\em chain}		executes a single DCL command and
exits, using the \hbox{\btt LIB\$DO\_COMMAND} Run-Time Library routine.
It is significantly faster than \system\ for a single command since it doesn't 
create a subprocess.

\section Now it's my turn to grouse about UNIX C

Now, let's let UNIX C take a little heat.

		The string functions
\smallskip

\item[\bullet]	{\em strcat}		- concatenate two strings
\item[\bullet]	{\em strcpy}		- copy a string
\smallskip

return the address of the beginning of the output 
string.  The ending address is far more useful.

The same is true of their bounded counterparts
\smallskip

\item[\bullet]	{\em strncat}		- concatenate up to `n' characters
\item[\bullet]	{\em strncpy}		- copy up to `n' characters
\smallskip


\section So some new string functions were invented

\smallskip

\item[\bullet]	{\em strzcat}		- concatenate two strings
\item[\bullet]	{\em strzcpy}		- copy a string
\smallskip

and their bounded counterparts
\smallskip

\item[\bullet]	{\em strxcat}		- concatenate up to `x' characters
\item[\bullet]	{\em strxcpy}		- copy up to `x' characters
\smallskip

	These functions perform exactly as the standard versions 
but return the address of the terminating \hbox{\btt NUL} byte, rather than 
the beginning address of the output buffer.


\section These new functions make constructing a string so easy $\ldots$

	This slide has an example which is a fragment from the PCC program.  
And of course, the output of these operations is eventually passed to the 
\system function.
\smallskip

\item[]		cp = {\em strzcpy} (\&cmdbuf, ``cpp -xo'');
\item[]		cp = {\em strzcpy} (cp, outname);
\item[]		cp = {\em strzcpy} (cp, ``.tm1'');
\item[]		$\vdots$

The statements here show the string ``cpp -xo xyz.tm1'' being constructed in
the buffer named {\em cmdbuf}.  The character pointer {\em cp} is used as a
place-holder at each statement, and then used as the starting address for the
next copy operation.  Of course, this could have been done with the {\em 
strcat} function, but {\em strcat} must find the end of the string each time
before it copies.  And, with my approach, you can easily record the address of
intermediate points in the output string rather than have to search for them
later. 

\section So once again I conclude that

\smallskip

\centerline{VMS can do anything UNIX can do better}

\smallskip

\section Future enhancements which I am unlikely to make

\smallskip

\item[\bullet]	The popen (and pclose) function, which could be
		implemented as a variation of the \system\ function


\item[\bullet]	Any number of esoteric UNIX functions which the
		\vaxc\ developers weren't interested in either


\section DECUS has it now

	This software is available on the Symposium
Languages and Tools tape, in the directories
[\hbox{\btt RIGS . CCLIB} . . . ].
\smallskip

\item[\bullet]	Sources
\item[\bullet]	Command and MMS Procedures
\item[\bullet]	Object Library
\item[\bullet]	Documentation


\section Questions, anyone
	
%
%	Where'd you get such a stupid idea ?
%
\end{document}
\bye
