ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

home *** CD-ROM | disk | FTP | other *** search

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / PROG / UTILITY / SMUT100.ZIP / SMUT.DOC next >

Wrap

Text File | 1991-03-14 | 33.5 KB | 1,074 lines

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: <command> <parameters> <flags> Where: <command> 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). <parameters> 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> 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 <file1> <file2> Priority: 1 History: No Description: Compare the contents of <file1> and <file2> for equality. Both <file1> and <file2> can be either a generation or a DOS file. SMUT scans the field for a semicolon (;) to determine which. CREATE CLASS Format: CREATE CLASS <class name> [<remark>] Priority: 2 History: Yes Description: Create a class of the specified name. CREATE ELEMENT Format: CREATE ELEMENT <element name> [<remark>] {-F<file>|-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 <group name> [<remark>] Priority: 2 History: Yes Description: Create a group of the specified name. CREATE LIBRARY Format: CREATE LIBRARY <library directory> <user name> [<remark>] 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 <user name> [<remark>] [-P<priority>] 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 <class name> [<remark>] [-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 <element name> [<remark>] 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 <group name> [<remark>] [-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 [<before date>] Priority: 3 History: Yes Description: Delete all or part of the contents of the history file. If <before date> is specified then all history records on or before that date are deleted. If <before date> 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 <user name> [<remark>] 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 <file1> <file2> [<remark>] {-F<output file>|-H|-N|-W<window size>|-M<max differences>} Priority: 1 History: Yes Description: Find the differences between the text files <file1> and <file2>. Both files must be text files. The output is either sent to file <output file> if the F flag is specified or the screen if it is not. Both <file1> and <file2> 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 <class name> [<remark>] [-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 <generation> [<remark>] {-H|-F<filename>} 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 [<command>] 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 <element name> <group name> [<remark>] Priority: 2 History: Yes Description: Insert the specified element into the specified group. INSERT GENERATION Format: INSERT GENERATION <generation name> <class name> [<remark>] 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 <old group name> <new group name> [<remark>] Priority: 2 History: Yes Description: Modify the name and optionally the remark associated with the specified group. MODIFY CLASS Format: MODIFY CLASS <old class name> <new class name> [<remark>] Priority: 2 History: Yes Description: Modify the name and optionally the remark associated with the specified class. MODIFY ELEMENT Format: MODIFY ELEMENT <old element name> <new element name> [<remark>] Priority: 2 History: Yes Description: Modify the name and optionally the remark associated with the specified element MODIFY LIBRARY Format: MODIFY LIBRARY <remark> Priority: 3 History: Yes Description: Modify the remark associated with the current library. MODIFY PASSWORD Format: MODIFY PASSWORD [<remark>] 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 <user name> [<remark>] {-P<priority>|-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 <remark> Priority: 1 History: Yes Description: Enter a remark into the history file. REMOVE ELEMENT Format: REMOVE ELEMENT <element name> <group name> [<remark>] Priority: 2 History: Yes Description: Remove the specified element from the specified group. REMOVE GENERATION Format: REMOVE GENERATION <generation name> <class name> [<remark>] Priority: 2 History: Yes Description: Remove the specified generation from the specified class. REPLACE Format: REPLACE <generation> [<remark>] {-F<filename>|-K|-V<id>} 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 <generation> [<remark>] {-F<filename>|-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 <directory> Priority: 0 History: No Description: Set the current working directory and drive. SET LIBRARY Format: SET LIBRARY <directory> [<user name>] 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 <user name> 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 [<class name>] {-L<filename>|-A<filename>} 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<filename>|-A<filename>} 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 [<element name>] {-T|-L<filename>|-A<filename>} 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 [<group name>] {-L<filename>|-A<filename>} 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 [<date1> [<date2>]] {-L<filename>|-A<filename>} 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<filename>|-A<filename>} 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<filename>|-A<filename>} 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 [<user name>] {-L<filename>|-A<filename>} 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<filename>|-A<filename>} 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 <generation> [<remark>] 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.