SOFTWARE MANAGEMENT UTILITY (SMUT)
USER GUIDE (v1.00)



1. Introduction

SMUT is a library system to aid software development and maintenance. SMUT
stores files in a library, keeps track of changes made to those files, and
records user access to the files.

During development team members continually make changes to project files.
SMUT stores, keeps track of, and monitors these files (called elements). SMUT
also lets you manipulate collections of files (called groups or classes).

SMUT stores project files in a central library where they are available to all
team members. Some of the functions that can be performed are as follows:

1) Store elements in a library;

2) Retrieve elements from the library for local modification and test;

3) Prevent concurrent modification of the same element;

4) Create successive versions (called generations) of an element;

5) Compare an element with other elements and external files to establish
the differences;

6) Organise related library elements into groups;

7) Define a set of various generations to be a baseline or release
version of a project;

8) Track which users are working on which generations;

9) Maintain a historical account of library transactions.



2. Libraries

A SMUT library is stored in a DOS subdirectory which is dedicated to that
library. The subdirectory contains the database, history file and all the
elements. When SMUT is first invoked the current SMUT library is unset and
will need to be selected by the SET LIBRARY command. Once set the library
directory is stored in memory such that even if SMUT is exited and
subsequently rerun it will still be valid.



3. Elements

Each new file which is put into the library becomes an element. An element
will contain all versions (generations) of that file. Subsequent generations
of a file are stored as changes from the previous generation, in this way many
generations of a single element can be stored in a single DOS file using a
relatively small amount of disk space.

Any format DOS file can be handled by SMUT. The only command which is
dependant on file format is the DIFFERENCE command which will give an error if
a non text file is specified.

When a file is first put into a library (using the CREATE ELEMENT command) it
is registered as generation 1. Subsequent generations are registered as
generation 2, 3, etc.

A generation is reserved (using the RESERVE command) when it is taken out of
the library to be worked on. Once a generation is reserved it cannot be
reserved again until the previous reservation is cancelled. A reservation is
cancelled when an updated generation is put into the library thereby creating
a descendant of the reserved generation (using the REPLACE command) or the
reservation is cancelled (using the UNRESERVE command).

SMUT allows multiple development paths for a single element. This is done by
creating a variant, that is a new and parallel development path. When a
generation is replaced normally the generation number will be incremented; if
however a variant ident (a single letter) is specified in the REPLACE command
(using the V flag) then a variant will be created. For example, generation 5
would have generation 6 as its direct descendant in its main line of decent
but could also have generation 5X1 as its descendant in a variant line of
decent identified by the letter X. Generation 5 can have in addition to its
main descendant (generation 6) up to 26 variants.

Once a variant has been created then that will have a main line of decent
characterised by incrementing generation numbers (e.g. 5X1, 5X2, 5X3, etc.).

The process of forming a variant line of decent can be applied recursively to
any level. For example generation 5X9 would have a descendant on its main line
of decent of 5X10, however a variant generation 5X9A1 could be established.



4. Groups and Classes

SMUT allows certain entities to be collected together and manipulated as a
whole.

Elements can be collected into groups.

A collection of generations which form a baseline or release version and can
be collected into a class.



5. Users

Each library maintains a list of users that are allowed access. Each user has
a password associated with it to protect unauthorised access and a priority to
limit the types of operations which can be performed by some users.

The current user is initially unset and is set either by the SET USER or SET
LIBRARY commands which will require correct entry of that users password. The
current user remains set until it is changed to another user (using the SET
USER command) or becomes unset by either the UNSET USER command or by
selecting a new library.

The current user and user priority are stored with the current library in
memory and will hence remain set with subsequent calls to SMUT. However to
protect against unauthorised access by people subsequently using the library,
the user is unset automatically 10 minutes after the last command has been
entered.

Priorities are in the range 0 (lowest) to 3. Priority 0 is the priority
allocated before a user has been set. Users are allocated priorities of 1 to
3. Increasing priority gives an increasing number of available commands. The
priority level at which each command becomes available is given with that
commands description in appendix A. The use of each priority is as follows:
Priority 0: Examine library status
Priority 1: Extract data
Priority 2: Insert data and create library entities
Priority 3: System manager functions

Once set the user name fulfils two roles. Firstly it is stored in the history
file against each command issued by that user. Secondly it is recorded in the
database against each reservation made by that user. At priority 2 only the
user that reserved a generation may replace or unreserve it. However a user at
priority 3 (system manager level) is not subject to this restriction.



6. History

SMUT maintains a history file which records all transactions which either
insert data into the library, retrieve data from the library, or modify the
library. Each transaction is stored together with the date, time and the user
that performed it.

The date and time of a transaction is taken from DOS. Each time the library is
opened (before most commands) the DOS date and time are checked against the
date and time of the last entry in the history file. If the DOS date and time
is earlier than the date and time of the last transaction then the operator is
asked to confirm whether the present DOS date and time is correct. If the DOS
date and time is incorrect then the operator is prompted for a new date and
time. Once the operator confirms that the date and time is set correctly then
all entries in the history files which are marked as having been recorded
after that time are marked as "undated" as the date and time must have been
incorrect at the time the transaction was recorded.



7. Remarks

Many commands allow optional remarks to the specified. The purpose of these is
twofold. Firstly they are stored in the history file to give an explanation of
the purpose of the transaction. Secondly when appended to a command which
creates a database entity they are stored with that entity to give some
explanation of what that entity is or is used for.



8. Working directory

SMUT maintains the DOS current working directory and allows it to be changed
and its contents to be examined (SET DIRECTORY and SHOW DIRECTORY commands)
without the need to return to DOS.



9. Files

When a library is created the result will be a directory containing two files:
the database and history file (SMUT.SMU and HIST.SMU respectively).
Subsequently an additional file with an extension of .SMU will be created for
each element created in the library. It is recommended that no other files are
stored in this directory.

The SMUT library has no knowledge of the directory in which it is located.
Consequently providing all the files were copied to another directory they
would function perfectly satisfactorily there. This also allows a backup or
archive copy of a library to be made by simply copying the files to the backup
media.



10. Command input

There are two modes of command input. Firstly commands can be input directly
at the DOS level by appending them to the SMUT command thus:

SMUT SHOW DIRECTORY

The command is executed and the system returns to the DOS prompt.

Secondly by entering only SMUT on the DOS command line the SMUT prompt will be
displayed and many commands can be entered until SMUT is exited with the QUIT
command.

Each command has a number of fields separated by one or more spaces. Commands
are of the general form:



Where:
is a one or two word command. For each word only sufficient
letters to make the command unambiguous need be typed (e.g.
REPLACE could be input as REP but not RE which would be
confused with REMARK, REMOVE and RESERVE).
the number and type of parameters are dependant on the
command. Parameters are order dependant and can specify such
things as names of entities, directory names, remarks, etc.
The restrictions on naming are given below.
flags convey optional information and are order independent.
A flag is introduced by the string '-n' where 'n' is a
single alphabetic character which identifies the flag. Some
flags require additional information such as files name,
etc.

Naming restrictions are as follows:
1. Element, Group and Class names are limited to 20 characters. Any
character which is valid in a DOS file name can be used.
2. User names and passwords are limited to 20 alpha/numeric
characters.
3. Remarks are limited to 60 characters. Because the space character
is used to delimit fields in the command line, if it is required
to include spaces with a remark then the remark field should be
enclosed within double quotes thus; "a remark containing spaces".
4. Generations are specified by element name followed by a semicolon
(;) and the version string (e.g. FILE.C;15B6). If the final
numeric subfield is omitted the generation referenced will be the
latest in that line of decent (e.g. FRED; means the latest
generation in the main line of decent and FRED;1A2A means the
latest generation in the 1A2A line of decent).
5. No input field is case dependant.
6. Dates are input in the form dd-mm-yyyy where dd is the day, mm is
the month and yyyy is the year.



11. Installation

In order to install SMUT the files SMUT.EXE, SMUT.OVL, SMUT.REG and SMUT.HLP
should be copied to a directory which is specified in the DOS PATH command in
AUTOEXEC.BAT.

Additionally the FILES parameter in CONFIG.SYS should be set to at least 10.

SMUT requires DOS to be at version 3 or above.



12. NET usage

The SMUT library is opened before most commands are actioned and
closed after them. This means that where the library is shared, such
as on a PC network, more than one user can access it. If a user tries
to open the library while it is already open to another user then a
warning message will be displayed and SMUT will continue to attempt to
open the library at intervals. If SMUT continues to fail to open the
library then additional warning messages will be displayed and the
operator may abort the command by pressing Esc.

The library may be locked open by a user (using the LOCK LIBRARY
command) hence preventing other users gaining access until either SMUT
is exited or the library is unlocked (using the UNLOCK LIBRARY
command).



13. Help facility

Online help is available on each command. By typing HELP followed by
the one or two word command a short description of that command will
be displayed. The specified command can be abbreviated following the
same rules as if it were being entered as a command to be actioned.



Appendix A - Command Description

This appendix contains a description of each command. The following
information is given for each command:

Format: The format of the command. Fields contained in brackets ([])
are optional. Fields contained within braces ({}) are
optional and can be specified in any order, each optional
field being separated by a bar (|).

Priority: The user priority below which the command is unavailable.

History: Whether the transaction is stored in the history file.

Description: A description of the commands function.

Examples: Where it is thought helpful one or more examples of the
commands use.



COMPARE

Format: COMPARE

Priority: 1

History: No

Description: Compare the contents of and for equality. Both
and can be either a generation or a DOS file.
SMUT scans the field for a semicolon (;) to determine which.



CREATE CLASS

Format: CREATE CLASS []

Priority: 2

History: Yes

Description: Create a class of the specified name.



CREATE ELEMENT

Format: CREATE ELEMENT [] {-F|-K}

Priority: 2

History: Yes

Description: Create the named element at generation 1 from an input file.

By default the input file is the file in the current working
directory with the same name as the element. Alternatively
this can be overridden by including the F flag and specifying
a different input file.

Normally the input file is deleted after the element is
created. This can be suppressed by specifying the K flag.

Examples: CREATE ELEMENT TEST.C "TEST FILE"

Create the element TEST.C at generation 1 from the file of the
same name in the current working directory and associate the
remark TEST FILE with it. Delete TEST.C from the current
working directory.

CREATE ELEMENT TESTDOC "TEST DOCUMENTATION" -FA:\JIM\T.DOC -K

Create the element TESTDOC at generation 1 from the file T.DOC
on drive A in directory \JIM and associate the remark TEST
DOCUMENTATION with it. Suppress deletion of the source file.



CREATE GROUP

Format: CREATE GROUP []

Priority: 2

History: Yes

Description: Create a group of the specified name.



CREATE LIBRARY

Format: CREATE LIBRARY []

Priority: 0

History: Yes

Description: Create a library in the specified directory. Create a user of
the specified name in the new library. The users password will
be set to be identical to its name and the user priority to 3.
The newly created library and user become the current library
and user. If the specified library directory exists then it
must be empty; if it does not exist it will be created
providing it is a subdirectory of an existing directory.

Example: CREATE LIBRARY A:\FILES\ALL JIM

If the directory A:\FILES\ALL does not exist then create it
providing the directory A:\FILES exists. Create a library in
subdirectory A:\FILES\ALL providing it is empty. Create a user
JIM in that library with a password of JIM and priority of 3.
Set the current library and user to be the newly created
library and user.

CREATE LIBRARY SAVESET MANAGER "PROJECT FILES"

If the subdirectory SAVESET of the current working directory
does not exist then create it. Providing the subdirectory is
empty create a library in it. Create a user MANAGER in that
library with password of MANAGER and priority of 3. Associate
the remark PROJECT FILES with that library. Set the current
library and user to the newly created library and user.



CREATE USER

Format: CREATE USER [] [-P]

Priority: 3

History: Yes

Description: Create a user of the specified name. Associate the specified
remark with the user. The user priority will default to 1
unless overridden by the P flag. The user password will be
prompted twice. Input of the password will not be echoed and
only if both inputs match will the user be created.

Example: CREATE USER BILL -P2

Create user BILL with a priority of 2.



DELETE CLASS

Format: DELETE CLASS [] [-R]

Priority: 2

History: Yes

Description: Delete the specified class. If the -R flag is specified then
any generations contained in the class are first removed. If
the -R flag is not specified then deletion will only be
allowed if the class is already empty.



DELETE ELEMENT

Format: DELETE ELEMENT []

Priority: 2

History: Yes

Description: Delete the specified element. If the element is contained in a
group, any of its generations are contained in a class, or any
of its generations are reserved then deletion will be
disallowed.



DELETE GROUP

Format: DELETE GROUP [] [-R]

Priority: 2

History: Yes

Description: Delete the specified group. If the -R flag is specified then
any elements contained in the group are first removed. If the
-R flag is not specified then deletion will only be allowed if
the group is already empty.



DELETE HISTORY

Format: DELETE HISTORY []

Priority: 3

History: Yes

Description: Delete all or part of the contents of the history file. If
is specified then all history records on or
before that date are deleted. If is not
specified then all history records are deleted.

Example: DELETE HISTORY 17-12-1989

Delete all history records with dates on or before 17-12-1989.



DELETE LIBRARY

Format: DELETE LIBRARY

Priority: 3

History: No

Description: Delete the current library. The operator is asked to input the
present users password again to confirm that library deletion
is required. Following deletion the current library and user
become unset.



DELETE USER

Format: DELETE USER []

Priority: 3

History: Yes

Description: Delete the specified user. Deletion is only allowed if the
specified user has no outstanding reservations. It is not
possible to delete the current user, hence the library can
never contain less than one priority 3 user.



DIFFERENCE

Format: DIFFERENCE []
{-F

|-H|-N|-W|-M}

Priority: 1

History: Yes

Description: Find the differences between the text files and
. Both files must be text files. The output is either
sent to file

if the F flag is specified or the
screen if it is not. Both and can be either a
generation or a DOS file. SMUT scans the field for a semicolon
(;) to determine which. Normally line numbers are generated in
the output, this can be suppressed by specifying the N flag.
The difference process can be caused to terminate after a
certain number of differences have been encountered using the
M flag. If the M flag is not specified then the difference
process will run until all differences are found.

The difference process is achieved by scanning a window across
both files and looking for a match. The default window size is
3 however this can be overridden using the W flag.

This command is only recorded in the history file if the H
flag is specified.

Example: DIFFERENCE DATA.ASM;5 DATA.ASM; -M50 -W5 -FDATA.DIFF

Determine the differences between generations 5 and the latest
generation in the main line of decent of element DATA.ASM
using a window size of 5 and send them to file DATA.DIFF in
the current working directory. Terminate the process after 50
differences are found.

DIFFERENCE PROG$5;2B1B12 A:\PROG -H

Determine the differences between generation 2B1B12 of element
PROG$5 and file PROG in the root directory of drive A with the
default window size of 3 and display them on the screen.
Record the command in the history file.



FETCH CLASS

Format: FETCH CLASS [] [-H]

Priority: 1

History: Yes

Description: Fetch all the generations contained within the specific class
but do not mark them as reserved. The generations will be
copied to files in the current working directory with the same
name as the generations.

This command is only recorded in the history file if the H
flag is specified.



FETCH GENERATION

Format: FETCH GENERATION [] {-H|-F}

Priority: 1

History: Yes

Description: Fetch a specific generation but do not mark it as reserved.
Normally the generation will be copied to a file in the
current working directory with the same name as the
generation. This can be overridden using the F flag.

This command is only recorded in the history file if the H
flag is specified.

Examples: FETCH GENERATION X.DAT;6

Fetch the contents of generation 6 of element X.DAT into file
X.DAT on the current working directory.

FETCH GENERATION DATA;1 -FTEMP.COR -H

Fetch the contents of generation 1 of element DATA into file
TEMP.COR in the current working directory and record the
transaction in the history file.



HELP

Format: HELP []

Priority: 0

History: No

Description: If a command is specified then the help text for that command
is displayed. If no command is specified then a list of
available SMUT commands is displayed.



INSERT ELEMENT

Format: INSERT ELEMENT []

Priority: 2

History: Yes

Description: Insert the specified element into the specified group.



INSERT GENERATION

Format: INSERT GENERATION []

Priority: 2

History: Yes

Description: Insert the specified generation into the specified class.



LOCK LIBRARY

Format: LOCK LIBRARY

Priority: 3

History: No

Description: Lock the library thereby preventing other NET users from
gaining access.



MODIFY GROUP

Format: MODIFY GROUP []

Priority: 2

History: Yes

Description: Modify the name and optionally the remark associated with the
specified group.



MODIFY CLASS

Format: MODIFY CLASS []

Priority: 2

History: Yes

Description: Modify the name and optionally the remark associated with the
specified class.



MODIFY ELEMENT

Format: MODIFY ELEMENT []

Priority: 2

History: Yes

Description: Modify the name and optionally the remark associated with the
specified element



MODIFY LIBRARY

Format: MODIFY LIBRARY

Priority: 3

History: Yes

Description: Modify the remark associated with the current library.



MODIFY PASSWORD

Format: MODIFY PASSWORD []

Priority: 1

History: Yes

Description: Prompt the operator for a new password for the current user.
The password is input (without echo) twice, and only if both
inputs match is the password changed.



MODIFY USER

Format: MODIFY USER [] {-P|-W}

Priority: 3

History: Yes

Description: Optionally modify the priority, password and remark associated
with the specified user. The remark is modified if it is
specified. The priority is modified if the P flag is specified.
If the W flag is specified then a new password is prompted for.
The password is input (without echo) twice, and only if both
inputs match is it password changed.



QUIT

Format: QUIT

Priority: 0

History: No

Description: Terminate SMUT and return to DOS.



REMARK

Format: REMARK

Priority: 1

History: Yes

Description: Enter a remark into the history file.



REMOVE ELEMENT

Format: REMOVE ELEMENT []

Priority: 2

History: Yes

Description: Remove the specified element from the specified group.



REMOVE GENERATION

Format: REMOVE GENERATION []

Priority: 2

History: Yes

Description: Remove the specified generation from the specified class.



REPLACE

Format: REPLACE [] {-F|-K|-V}

Priority: 2 providing the generation was originally reserved by the
current user, else 3.

History: Yes

Description: Replace a reserved generation. Normally from a file with the
same name as the element unless overridden by the F flag.
Delete the input file unless suppressed by the K flag.
Normally generate the next generation in the main line of
decent unless overridden by the V flag.

Example: REPLACE BIGDATA;12

Replace generation 12 of element BIGDATA with the contents
of the file BIGDATA in the current directory thereby
creating generation 13. The file BIGDATA is then deleted.

REPLACE FRED;2A2 -FFRED.TMP -VX

Replace generation 2A2 of element FRED with the contents of
the file FRED.TMP in the current directory thereby creating
the first generation of a variant line of decent, 2A2X1. The
file FRED.TMP is then deleted.



RESERVE

Format: RESERVE [] {-F|-D}

Priority: 2

History: Yes

Description: Mark the specified generation as reserved by the current
user. Unless the D flag is specified the contents of the
reserved generation is written to an output file. Normally
the output file is that with the same name as the element in
the current working directory, however this can be
overridden using the F flag. If the D flag is specified then
the output is not copied to a file but is discarded.

Examples: RESERVE Y.DAT;7M

Fetch the contents of the latest generation in the 7M line
of decent of element Y.DAT into file Y.DAT on the current
working directory and mark it as reserved by the current
user.

RESERVE DATA;1 -FTEMP.COR

Fetch the contents of generation 1 of element DATA into file
TEMP.COR on the current working directory and mark it as
reserved by the current user.



SET DIRECTORY

Format: SET DIRECTORY

Priority: 0

History: No

Description: Set the current working directory and drive.



SET LIBRARY

Format: SET LIBRARY []

Priority: 0

History: No

Description: Set the current library and optionally prompt for the
specified users password and if correct set that user to be
the current user. This command is actioned in two parts so
that if setting the user fails (because the user name does
not exist or the password is incorrect) the new library will
still be set.



SET USER

Format: SET USER

Priority: 0

History: No

Description: Prompt for the specified users password and if correct set
that user to be the current user.



SHOW CLASS

Format: SHOW CLASS [] {-L|-A}

Priority: 0

History: No

Description: If a class name is specified, show the generations contained
in that class. If no class name is specified then list all
the classes. If neither the L nor A flag is specified output
is to the screen; if the L flag is specified then a new file
(of the given file name) is created and the output sent to
that; if the A flag is specified then the output is appended
to the given existing named file.



SHOW DIRECTORY

Format: SHOW DIRECTORY {-L|-A}

Priority: 0

History: No

Description: Show the current working drive and directory and all the
files contained therein. The A and L flags function as in
SHOW CLASS.



SHOW ELEMENT

Format: SHOW ELEMENT [] {-T|-L|-A}

Priority: 0

History: No

Description: If the element name is specified, show the generations of
that element. If the element name is not specified then list
all elements. If an element name is specified then the -T
flag can optionally be included to change the form the
version numbers are displayed in. With the -T a tree type
display is given; otherwise they are simply listed. The A
and L flags function as in SHOW CLASS.



SHOW GROUP

Format: SHOW GROUP [] {-L|-A}

Priority: 0

History: No

Description: If a group name is specified, show the elements contained in
that group. If no group name is specified then list all the
groups. The A and L flags function as in SHOW CLASS.



SHOW HISTORY

Format: SHOW HISTORY [ []] {-L|-A}

Priority: 0

History: No

Description: Show the contents of the history file. If no dates are
specified then show the whole file. If one date is specified
then show only entries after that date. If two dates are
specified then show entries between the two dates. The A and
L flags function as in SHOW CLASS.



SHOW LIBRARY

Format: SHOW LIBRARY {-L|-A}

Priority: 0

History: No

Description: Show the current library, current user and current working
directory. The A and L flags function as in SHOW CLASS.



SHOW RESERVATIONS

Format: SHOW RESERVATIONS {-L|-A}

Priority: 0

History: No

Description: Show all the reserved generations and the users that have
reserved them. The A and L flags function as in SHOW CLASS.



SHOW USER

Format: SHOW USER [] {-L|-A}

Priority: 0

History: No

Description: If the user name is specified show information about that
user. If the user name is not specified then list all the
users. The A and L flags function as in SHOW CLASS.



SHOW VERSION

Format: SHOW VERSION {-L|-A}

Priority: 0

History: No

Description: Show the current version of SMUT and additional registration
information. The A and L flags function as in SHOW CLASS.



UNLOCK LIBRARY

Format: UNLOCK LIBRARY

Priority: 1

History: No

Description: Allow library access by other NET users.



UNRESERVE

Format: UNRESERVE []

Priority: 2 providing the generation was originally reserved by the
current user, else 3.

History: Yes

Description: Unreserve a reserved generation.



UNSET USER

Format: UNSET USER

Priority: 1

History: No

Description: Unset the current user. The priority will hence become 0.