\documentstyle[a4,12pt]{article}
\begin{document}
\author{APM Manual pages}
\title{                USEFUL Utilities for the APM system.}
\maketitle
\parskip .1 in
\setcounter{secnumdepth}{10}
\parindent 0in

\section{Preamble}
\hspace*{ 0.2 in} These utilities were written by members of CS4 for general use. There is no
official guarantee of support of anything here but what actually happens is
that a scan is done of the USEFUL utilities over the summer. Anything genuinely
useful is grabbed and incorporated in the system. Anything useless or
unmaintainable is discarded. (New and exciting ways to clear the screen come
in the first category).

If you have a routine you think might be useful, this is what you do...

In the program...
Put in at least the following documentation at the top of the program..
What it does. \hspace{ 0.3 in} What parameters it takes. \hspace{ 0.2 in} Who wrote it \& When.

As a separate file..
Create a document describing the utility for the user. Describe what it does,
and the parameters (as in the program) plus details of any error messages it
produces , who wrote it and what level of support you offer etc. etc.
This need not be very long - a screenful will often do.

Ask me (JHB) for the USEFUL password if you don't know it already. Put your
source and .MOB files in USEFUL: and mail me details of where the
documentation file is. I will then put it in HELP USEFUL.

** End of JHB Bit **


\hspace*{ 0.2 in} These utilities are contained in the directory 'USEFUL' on the new filestore
and may be accessed by adding either of the commands USEFUL:SETUP or
SETUP USEFUL to the end of your login file, or editing USEFUL:SETUP.MOB
into your login file (this on is not recommended as new commands and system
changes will leave you behind).

*** If you do not currently either preload USEFUL:WHODAT.MOB or give the
*** command SETUP USEFUL in your login file, then you should, as about 90\%
*** of all programs contained in USEFUL use it and you will get a very poor
*** response if you do not preload this file as it will be loaded every time
*** you use one of the commands, then thrown away.

\section{Individual Commands}

Suggestions for new commands are always welcome, or why not implement some
yourself.

\subsection{FIND}

\hspace*{ 0.3 in} FIND \hspace{ 0.2 in} user\{,user,user...\} eg \} FIND GJK \hspace{ 0.5 in} finds GJK
\\ \hspace*{ 2.3 in} \} FIND GDMR,RWT \hspace{ 0.2 in} finds GDMR and RWT

This command is used to find a person (as on VAX). If the user is logged on
then his location is printed, otherwise a message left by that user (using
the command GONE) is printed.

\hspace*{ 3.9 in} Supported by AJS

\subsection{FINDALL}

\hspace*{ 0.2 in} FINDALL

This command is used to print the 'GONE' message of every user that has
used the GONE command.

\hspace*{ 3.9 in} Supported by MDP

\subsection{GONE}

\hspace*{ 0.2 in} GONE message \hspace{ 0.9 in} e.g. \} GONE Home to bed

This command is used to leave a message and log off. Other users can read
the message by using the command FIND (or FINDALL).

e.g. \hspace{ 0.3 in} \} GONE Home To Bed
\\ \hspace*{ 0.5 in} AJS going Home To Bed at 03.34 am on the 1st of April 1984

\hspace*{ 3.9 in} Supported by MDP

\subsection{LASTLOG}

\hspace*{ 0.2 in} LASTLOG

This allows the user to keep a note of when they last logged on, this is stored
in a file 'LOGIN.LOG'. If this command is put in your login file, then the date
and time of your last login are printed out, then the current date and time are
written to this file. You can then see if you logged in when 'YOU' were not
around.....

\hspace*{ 3.9 in} Unsupported

\subsection{NAME}

\hspace*{ 0.2 in} NAME \hspace{ 0.3 in} wildname \hspace{ 0.5 in} e.g. \} NAME gr \hspace{ 1.1 in} looks for all names \&
\\ \hspace*{ 3.8 in} usernames with 'GR' in
\\ \hspace*{ 3.8 in} them.
\\ \hspace*{ 2.1 in} \} NAME * \hspace{ 1.1 in} prints everybody.

This command is used to find the username or full name of someone for whom you
only know part of the name. Useful if their username is not what you expect it
to be (e.g. on vax). The names are not matched phonetically as on VAX but this
may be implemented.

e.g. \} NAME mart
\\ \hspace*{ 0.3 in} Martin Platts (MARTIN) \hspace{ 0.6 in} but this would be under MDP on VAX.

\hspace*{ 3.9 in} Supported by MDP

\subsection{PORTANAL}

\hspace*{ 0.2 in} PORTANAL

This command gives info on the ports connected to the filestore, i.e. where they
are and how active (how long since it was last used, useful for killing ports).
It now gives the name of the person using that port if there is someone, other-
wise it says the port is '*Free*'.

\hspace*{ 3.9 in} Supported by MDP

\subsection{PORTKILL}

\hspace*{ 0.2 in} *** Working, but killing of ports is not permitted by law (i.e. GDMR) ***

\hspace*{ 0.2 in} PORTKILL \hspace{ 1.1 in} e.g. \} PORTKILL \hspace{ 1.0 in} prompts for all ports.

\hspace*{ 2.1 in} \} PORTKILL 23 \hspace{ 0.8 in} kills port 23.

This command requires the user to be privileged so that ports connected to the
filstore can be killed remotely. It displays the port number, where it is
connected to and what activity state the port is in, and prompts. Any answer
beginning with 'Y' or 'K' will perform the kill.

\hspace*{ 3.9 in} Unsupported

\subsection{PRINT}
This command is really a frig to send a file to the old filestore using the
EFTP command, the one you know and love \{sounds of choking\}. You can even
print VAX files by specifying the filename in whatever format EFTP accepts
this week (wild cards are accepted).

\hspace*{ 3.9 in} Contributed by ICE
\\ \hspace*{ 3.9 in} Unsupported

\subsection{SUICIDE}

\hspace*{ 0.2 in} SUICIDE

This command is useful in killing off spare processes under your username that
Rainer \& EFTP have left lying about the system. It will prompt you for each
process in turn and you type either 'Y' or 'y' if you want it deleted, anything
else will do nothing (e.g. Return).

Privileged users are allowed to kill any process on the system so be careful
what you say to Rainer. When killing other users off the full word 'YES' or
'yes' is needed.

\hspace*{ 3.9 in} Supported by MDP

\subsection{USERS}

\hspace*{ 0.2 in} USERS

This command displays all currently logged on users and their locations.
Various qualifiers are available and the qualifiers may be shortened.
The number of remote users is displayed at the bottom of the display along
with the number of internal filestore copies, these 2 figures are only shown
if non zero.

\hspace*{ 0.2 in} \} users/active \hspace{ 0.5 in} displays the users and roughly how active they
\\ \hspace*{ 1.7 in} are. (This is done by looking at when they last
\\ \hspace*{ 1.7 in} communicated with the File Server and thus if
\\ \hspace*{ 1.7 in} the user is engaged in a long edit it may appear
\\ \hspace*{ 1.7 in} that the user is asleep)

\hspace*{ 0.2 in} \} users/brief \hspace{ 0.6 in} displays just the usernames

\hspace*{ 0.2 in} \} users/full \hspace{ 0.7 in} displays the users plus their station ID

\\ \hspace*{ 0.2 in} \} users/remote \hspace{ 0.5 in} displays those users who are logged on from
\\ \hspace*{ 1.7 in} ECSVAX or ECSUNIX

\hspace*{ 0.2 in} \} users/alpha \{/wee\} these commands allow the user to see who is using
\\ \hspace*{ 0.2 in} \} users/bravo \{/big\} one of the other APM filestores on the system.
\\ \hspace*{ 0.2 in} \} users/portable \{/mini\}
\\ \hspace*{ 0.2 in} \} users/all \hspace{ 0.7 in} this is the same as '/wee/big/mini'.

\hspace*{ 0.2 in} \} users/uic \hspace{ 0.7 in} displays the UICs (according to VAX) of the
\\ \hspace*{ 1.7 in} logged on users

\hspace*{ 0.2 in} \} users/verybrief \hspace{ 0.3 in} displays the number of logged on users

\hspace*{ 0.2 in} \} users/group=51 \hspace{ 0.4 in} displays the logged on users with UICs of group 51

\hspace*{ 3.9 in} Supported by AJS

\subsection{VFILES}

\hspace*{ 0.2 in} *** Super new enhanced program ***
\\ \hspace*{ 0.2 in} VFILES wildfile \hspace{ 0.7 in} e.g. \} f w::x*: displays all files on WEE fs
\\ \hspace*{ 3.2 in} in all dirs. starting with X.
\\ \hspace*{ 2.4 in} \} f .mob \hspace{ 0.3 in} displays all .MOB files
\\ \hspace*{ 2.4 in} \} f fmacs:* displays all extensionless files
\\ \hspace*{ 3.2 in} in directory FMACS

This command is an implementation of the FILES command for VAX, it also accepts
a few qualifiers which should come after the command and be separated by a space
from the parameter (if any). This now accepts node names as part of the filespec
standard names are accepted as nodename '::' normal pathname.

\hspace*{ 0.2 in} \} f/today \hspace{ 0.9 in} displays all files modified today.
\\ \hspace*{ 0.2 in} \} f/yesterday \hspace{ 0.6 in} displays all files modified yesterday.
\\ \hspace*{ 0.2 in} \} f/info \hspace{ 0.9 in} displays all information \hspace{ 0.2 in} \{f/i, same as f/p/s/d\}.
\\ \hspace*{ 0.2 in} \} f/perm or f/prot \hspace{ 0.3 in} displays the protection on the files \{f/p\}.
\\ \hspace*{ 0.2 in} \} f/size \hspace{ 0.9 in} displays the file sizes \{f/s\}.
\\ \hspace*{ 0.2 in} \} f/date \hspace{ 0.9 in} displays the last written date of the file \{f/d\}.
\\ \hspace*{ 0.2 in} \} f/short \hspace{ 0.9 in} displays the information in short format (as fmac:f).

\hspace*{ 0.2 in} A new feature has been added to files, in that the command now can take wild
carded directories, hence commands such as the following are possible.

\hspace*{ 0.3 in} \} f s*:*.mob \hspace{ 0.6 in} all .MOB files in directories beginning with S
\\ \hspace*{ 0.3 in} \} f P::*W*:** \hspace{ 0.5 in} all files in any directory with a W in on PORTABLE FS.
\\ \hspace*{ 0.3 in} \} f GMC.\%:* \hspace{ 0.7 in} all extensionless files in directories beginning with
\\ \hspace*{ 1.7 in} 'GMC.' followed by a single letter or digit.

 The program also gives a different output if the file to be searched for does
not contain wild cards, in this case the output merely lists the directories
found containing such a file.

\hspace*{ 0.2 in} \} f *:login.mob \hspace{ 0.5 in} lists all directories containing a login file.

 This command is culled from the old VFILES and the old FINDFILE (as requested
by HMD).

\hspace*{ 3.9 in} Supported by MDP



\section{Information for programmers}
These declarations define the names, usernames and groups of the acreditted
users on 'this' filestore. I say 'this' as there will soon be another new
filestore and it may have different users on it. The include file is
"USEFUL:WHODAT.INC", the object is "USEFUL:WHODAT.MOB"

\%const \%integer Min FS Users, \hspace{ 0.2 in} \{ a lower bound on the range
\\ \hspace*{ 1.1 in} Max FS Users \hspace{ 0.3 in} \{ the number of actual acreditted users

\hspace*{ 0.2 in} ! This array contains the usernames of the users on this filestore.
\\ \hspace*{ 0.2 in} ! the 3 arrays are parallel and refer to the same order of users.
\%external \%string (6) \%array \%spec FS Users (Min FS Users : Max FS Users)

\hspace*{ 0.2 in} ! This array contains the real names of the users on this filestore.
\%external \%string (31) \%array \%spec FS Names (Min FS Users : Max FS Users)

\hspace*{ 0.2 in} ! This array contains the group of the users on this filestore.
\%external \%byte \%integer \%array \%spec FS Grps (Min FS Users : Max FS Users)


These are utility routines required by some of the programs contained in the
user USEFUL. They are really for us but others may use them.

\hspace*{ 0.2 in} ! Converts 'IT' into Upper Case
\%external \%routine \%spec Upper Case (\%string(*) \%name it)

\hspace*{ 0.2 in} ! Converts 'IT' into Lower Case
\%external \%routine \%spec Lower Case (\%string(*) \%name it)

\hspace*{ 0.2 in} ! returns the index of 'WHO' in 'FS Users', Max FS Users+1 if not found.
\%external \%integer \%fn \%spec Find Index (\%string (7) who)

\hspace*{ 0.2 in} ! returns the current directory.
\%external \%string (6) \%fn \%spec Current Directory

\hspace*{ 0.2 in} ! returns the username of the current user, "" if not logged on.
\%external \%string (6) \%fn \%spec Current User


\hspace*{ 0.2 in} ! returns xx in a hex string
\%external \%string (2) \%fn \%spec Hex 2 (\%integer xx)

\hspace*{ 0.2 in} ! breaks 'LINE' over lines every 80 cols. (no final newline)
\%external \%routine \%spec Format (\%string (255) Line)

\hspace*{ 0.2 in} ! returns true if S matches the 'wild string' P.
\%external \%predicate \%spec Matches (\%string (*) \%name s, p)

\hspace*{ 0.2 in} ! Prints 'COUNT', followed by 'WHAT', followed by 's' if 'COUNT' \# 1
\%external \%routine \%spec Announce (\%string (80) What, \%integer Count)

\hspace*{ 0.2 in} ! Returns the number of minutes since the latest of the 2 times.
\%external \%integer \%fn \%spec Minimum Difference \%alias "USE\_MinDiff" \%c
\\ \hspace*{ 0.2 in} (\%string (31) One, Two)



\%record \%format User Fm (\%string (6) User Name, \{User Name of this user \hspace{ 0.3 in} \}
\\ \hspace*{ 1.7 in} \%string (6) Directory, \{Current directory(e.g. SET)\}
\\ \hspace*{ 1.7 in} \%string (21) Login Time,\{Time user logged in \hspace{ 0.5 in} \}
\\ \hspace*{ 1.7 in} \%byte Uno, \hspace{ 0.9 in} \{Filestore User No \hspace{ 0.7 in} \}
\\ \hspace*{ 2.1 in} Pno, \hspace{ 0.9 in} \{Filestore Port No \hspace{ 0.7 in} \}
\\ \hspace*{ 2.1 in} Flags, \hspace{ 0.8 in} \{ \#0 if Privileged \hspace{ 0.7 in} \}
\\ \hspace*{ 2.1 in} Location, \hspace{ 0.6 in} \{Terminal Ether Address \hspace{ 0.3 in} \}
\\ \hspace*{ 1.7 in} \%short Difference) \hspace{ 0.4 in} \{Minutes since did something\}

\hspace*{ 0.2 in} ! Reads the list of users on the system, returns them in the array
\%external \%routine \%spec Get Unos From FS \%alias "USE\_GFsUnos" \%c
\\ \hspace*{ 0.2 in} (\%record (User Fm) \%array \%name Users (1:*),
\\ \hspace*{ 0.3 in} \%integer \%name Number of Users,
\\ \hspace*{ 0.3 in} \%integer \%name Number of Internal Copies)


\section{Software ALERT}
As of today (20/04/84) a new release of USEFUL software is in service, there are
only 3 main changes are these are :
\\ \hspace*{ 0.2 in} -- The commands are now parsed using 'PAM' hence command line format is now
\\ \hspace*{ 0.4 in} the same as used in Imp, IE, Ecce and lots of other programs.
\\ \hspace*{ 0.4 in} This enables the user to change the symbols representing the separators
\\ \hspace*{ 0.4 in} between parameters and qualifiers (currently / and -) to whatever is
\\ \hspace*{ 0.4 in} desired, this can be done with the predefined command PAMSET.

\hspace*{ 0.2 in} -- The commands now use a file of external routines and data, this means that
\\ \hspace*{ 0.4 in} the database of usernames, names, user groups and various utility routines
\\ \hspace*{ 0.4 in} can now be shared between all programs rather than one copy each as
\\ \hspace*{ 0.4 in} before.

\hspace*{ 0.4 in} *** This means that if the user does not preload this object file
\\ \hspace*{ 0.4 in} *** as described earlier then they will get very poor response
\\ \hspace*{ 0.4 in} *** from about 90\% of the programs contained in USEFUL.

\hspace*{ 0.2 in} -- More wildcards are now permitted, notably in VFILES, CLEAN and FINDFILE.


\section{User Information}
\hspace*{ 0.2 in} The file USEFUL:WHODAT.MOB is used by almost all these utilities since it
required to be installed (this is done for you), but it should really be
preloaded by giving the command

\hspace*{ 0.2 in} \} Preload Useful:WhoDat.Mob

\hspace*{ 0.2 in} In your login file, if you use 'USEFUL:SETUP' or the better 'SETUP USEFUL',
then this will do this for you.

\hspace*{ 0.2 in} Wherever qualifiers are given to commands, the symbol '/' is used as in
VAX/VMS, all commands use 'PAM' and so the default settings do not allow the
use of '/' here but use '-'. The separators between parameters are also
different, they are shown here as a space (as VMS) rather than the default '/'.

\hspace*{ 0.2 in} To use the 'space' and '/' (remember IMP \& IE \& ECCE also use PAM) the
command sequence is:

\hspace*{ 0.2 in} \} Pamset
\\ \hspace*{ 0.2 in} GroupSeparator then Keyflag: /


\hspace*{ 0.2 in} Many commands take parameters and qualifiers, some of which are not easy
to remember. PAM provides a way of deternining these parameters at runtime,
by specifying the command you require followed by '??', PAM will prompt
you for all parameters and qualifiers showing their default values (if they
have one).

\section{ USEFUL Hall of fame}
Things which originated here and have been incorporated in the system

Alistair Scobie (AJS) and Martin Platts (MDP) CS4 83/84
\\ \hspace*{ 0.2 in} SEARCH
\\ \hspace*{ 0.2 in} PERUSE
\\ \hspace*{ 0.2 in} CLEAN
\\ \hspace*{ 0.2 in} The idea of a user database (USEFUL got there first)
\\ \hspace*{ 0.2 in} Some bits of ID

\vspace{.75in} view:Useful printed on 09/02/89 at 17.24

\newpage
\tableofcontents
\end{document}
