home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
C!T ROM 2
/
ctrom_ii_b.zip
/
ctrom_ii_b
/
PROGRAM
/
C
/
PSCM12
/
READ.ME
< prev
next >
Wrap
Text File
|
1990-12-03
|
28KB
|
745 lines
PSCM -- The Project Source Code Manager December 3rd, 1990
PSCM - Project Source Code Manager
PSCM consists of two main programs: CHECKIN and CHECKOUT. These
two programs control a project database that contains the
complete source code and support files for a project. The basic
function of PSCM is to maintain and archive various versions of
the project as it evolves. At any point in time it should be
possible to retrieve the full set of files needed to create the
project at any point in time.
PSCM manages the different revisions by assigning a Version
Number to each different version of the files. This number has
three parts as follows:
M.N.R where:
M The major version number. This number must be at least
1 and as high as 32767.
N The minor version number. This number may range from 0
to 32767.
R The revision number. This number may range from 0 to
32767 and is used to indicate intermediate revisions
between releases.
When a project's files are identified by only the major and minor
version numbers, this is referred to as a "Version". When the
revision number is included, this is called an "Instance". When a
set of files is retrieved for a particular Version, the most
recent Instance of all files is retrieved. It is also possible to
retrieve a specific revision of a file.
The database maintains an internal directory of files that
constitute a project set. This directory is only maintained at
the Version level, not at the Instance level. This means that if
a file is deleted, it cannot be retrieved at a prior Instance
within the same Version.
PSCM stores only the latest instance of a file in the database.
Prior instances are stored as "Difference Scripts". These scripts
are generated and used by the two PSCM support programs: DIFS and
MRGS. DIFS compares two files and produces a file that describes
how they differ. MRGS uses a script file and the original source
file to produce the second source file.
PSCM also allows the inclusion of comments in the database file.
When one or more files have been changed, and new Instances of
the files are added to the database, an optional comment may be
generated and saved. Along with the comment is a list of the
files modified and their revision level and file date and time.
These comments may be either listed one at a time or all comments
at once.
During development it may be required to take a "Snapshot" of the
current revision level of all files in the database. PSCM allows
PSCM page 1
PSCM -- The Project Source Code Manager December 3rd, 1990
this function through the use of "Sets". When a Set is created, a
record is made of all files at their most recent Instance. This
is stored along with a comment which can be used to describe the
Set. At any point in time it is possible to recreate the exact
state of these files using the CHECKOUT program's Set command. It
is also possible to generate a list of all Sets in the database.
The PSCM Configuration File
PSCM uses a configuration file to store some basic information
used when expanding some of the special macro strings described
later. The configuration file is an eight line text file. The
first line in the file is called the "System" line. The text of
the first line is used when expanding the System Name macro. The
remaining seven lines are called "User Parameters". They are used
when expanding the seven User macros.
When the CHECKOUT program begins execution, it attempts to open
the configuration file "PSCM.CFG" in the current directory. If it
cannot find the file in the current directory, and you are using
DOS version 3.0 or later, it will attempt to load the
configuration file from the directory where the CHECKOUT program
was loaded from. This allows you to have a default configuration
stored in the same directory as the CHECKOUT.EXE file and to have
a project specific configuration in the working directory.
page 2 PSCM
PSCM -- The Project Source Code Manager December 3rd, 1990
The Project Source Files
A Project's source files are plain ASCII text files that contain
the source code for a project. The source files may also include
the various support files used to create and maintain the project
such as a make file and batch files. For example, the PSCM
project has several 'C' code source files, a couple of 'C' header
files, a make file and a few batch files. Taken together, these
files are all that is necessary to recreate the entire project
from scratch.
-----------------------------------------------------------------
NOTE PSCM can only work with plain ASCII text files. It will
not handle word processor files properly. The various
control codes in most word processor files will give
the PSCM database file serious brain damage.
-----------------------------------------------------------------
The Project Database File
The Project Database file is used to hold all information about
the project's source files. There is no requirement on the name
of the file, however the convention is to name it the same as the
project with no extension. For example, my project file for PSCM
is named "PSCM". The project database file need not even be in
the same directory as the rest of the project files. This allows
you to place the project file on another drive or in another
directory for that added "Peace of Mind."
The Item File System (IFS)
PSCM uses a database manager called "The Item File System". This
DBMS allows records in the database to be of varying lengths. It
is also very fast because it uses a hashing algorithm to store
the records. When a project file is first created (by the CHECKIN
program) it is given a default size (called a "Modulo") of 47. As
the project database file grows it may be necessary to resize the
file to improve retrieval speed. The ISIZE program is used to
resize the project database file. Use the following command:
ISIZE -r PROJECT
The ISIZE program will inspect the project database file and then
create a new file with a new size and copy all items from the old
file to the new file. It will then delete the old file and rename
the new file to the old file name.
PSCM page 3
PSCM -- The Project Source Code Manager December 3rd, 1990
The CHECKIN Program
The CHECKIN program is used to add project files to the database
and to create new Versions or Instances of files. CHECKIN is also
used to add comments to the database and to create project Sets.
Adding New Files to a Project Database
When adding one or more new files to the project database, or
when creating a new Version level, the Version numbers must be
specified via a command line switch as follows:
CHECKIN -vM.N PROJECT FILE1.C FILE2.C ... FILEn.C
The '-v' switch is used to specify the major and minor version
numbers. Note that the revision number is not specified, it is
set to 0 by the program. If a copy of the file already exists at
the specified Version level, an error will occur.
Updating Files in the Project Database
To create a new Instance of an existing file, the following
command line is used:
CHECKIN -i PROJECT FILE1.C FILE2.C ... FILEn.C
-or-
CHECKIN -i PROJECT
-or-
CHECKIN -iM.N PROJECT FILE1.C FILE2.C ... FILEn.C
-or-
CHECKIN -iM.N PROJECT
When no file names are specified on the CHECKIN command line, all
source files that have been modified since they were last checked
in are updated. This is a shorthand way of updating all modified
files.
The first command form is used to create new Instances for the
specified files at the most recent Version level. The second
command is the same except that all modified files in the most
recent Version are updated to a new Instance. These two forms are
the most common used in project management.
The third and fourth commands are similar to the first two except
a specific Version level is updated instead of the most recent.
These command forms are used when a previous CHECKOUT was run to
retrieve a Version other than the most recent.
Adding Comments to the Project Database File
The '-i' switch is used to create new Instances of source files.
But it is also possible to add a comment record at the same time.
The following commands behave the same except that they also
allow an optional comment record to be created and saved with the
page 4 PSCM
PSCM -- The Project Source Code Manager December 3rd, 1990
files. The comment record contains one or more lines of text and
a list of the files updated. The following command forms are used
to create comment records:
CHECKIN -c PROJECT FILE1.C FILE2.C ... FILEn.C
-or-
CHECKIN -c PROJECT
-or-
CHECKIN -cM.N PROJECT FILE1.C FILE2.C ... FILEn.C
-or-
CHECKIN -cM.N PROJECT
Saving a Set of Files in the Database
During the development process it may be useful to save a record
of the current revision level of all files in the database. This
record is called a "Set". It is commonly used as a place marker
to indicate where specific test versions of the project were
generated and released. For example, if you are in the habit of
releasing preliminary versions to a small group of testers, the
Set function can be used to regenerate the source code used for
each tester's version of the program.
The command used to generate a Set is:
CHECKIN -s PROJECT
-or-
CHECKIN -sM.N PROJECT
Note that no file names are specified on the command line. This
is because the Set command generates and saves a list of all
files in the database. The first command form will generate a set
for the most recent Version, while the second form is used to
create a set for a specified version.
-----------------------------------------------------------------
NOTE None of the CHECKIN command forms will alter the source
files. They are left on disk exactly as before CHECKIN
was run.
-----------------------------------------------------------------
PSCM page 5
PSCM -- The Project Source Code Manager December 3rd, 1990
Special Macros in Source Files
When files are retrieved for editing, certain special "Macro"
strings are left in the unexpanded form. When files are retrieved
for making (i.e. compiling, assembling, etc.) these Macros are
expanded. The Macros can be used to specify version numbers, file
dates and times, file names, etc.
The Macros are used to place information about the system,
project, or file in the text of the file. When the file is
retrieved for making, the Macros are replaced with the
information specified. There are two types of date and time
macros. One form is used to place the current system date and
time in the file. This is the system date and time when the file
is retrieved. The other form is used to place the file's time and
date in the text. This is the date and time of the last
modification to the file.
The Macros are as follows:
@#T System Time in the form hh:mm:ss
@#D System Date in the form mm/dd/yy
@#P Project name
@#S System name from the PSCM config file
@#1 User parameter 1 from the PSCM config file
@#2 User parameter 2 from the PSCM config file
@#3 User parameter 3 from the PSCM config file
@#4 User parameter 4 from the PSCM config file
@#5 User parameter 5 from the PSCM config file
@#6 User parameter 6 from the PSCM config file
@#7 User parameter 7 from the PSCM config file
@#v Version number in the form M.N
@#r Revision number in the form M.N.R
@#M Major version number
@#N Minor version number
@#R Revision number
@#d File date in the form mm/dd/yy
@#t File time in the form hh:mm:ss
@#f File name and extension in the form filename.ext
@#F File name part only (no extension)
@#c Revision history comments
page 6 PSCM
PSCM -- The Project Source Code Manager December 3rd, 1990
The '@#c' macro is slightly different than all the others. When
it is processed, it puts the revision history comments for the
file in the text. The part of the line already printed is put at
the beginning of each line before it is inserted in to the text.
For example, if the lines:
/*
* @#c */
are in the source text, they will be expanded to look like:
/*
*
* Revision M.N.R entered at HH:MM:SS on MM/DD/YY
* Comment line 1
*
* Revision M.N.R entered at HH:MM:SS on MM/DD/YY
* Comment line 1
* Comment line 2
*
* */
Only those comments entered when a file was updated and then
checked in using the CHECKIN option '-c' will be printed. Even
though the comment may have been entered when more than one file
was updated, the comment text will be printed if the current file
was included in the update.
The comment text is placed in the text file starting with the
most recent revision and proceeding to the oldest. When a file is
extracted at a specific revision, only those comments which were
entered before or at the revision are placed in the file. If no
comments are found, the '@#c' macro is simply discarded.
PSCM page 7
PSCM -- The Project Source Code Manager December 3rd, 1990
The CHECKOUT Program
The CHECKOUT program is used to retrieve files from the most
recent or a specified Version level. The files can be retrieved
for one of two purposes: Editing or Making.
Retrieving for Editing or Making
When files are retrieved for editing, all special Macros are left
in their unexpanded form and the file is written to disk as a
modifiable file. When files are retrieved for making, the special
Macros are replaced by the appropriate information and the file
is marked read-only. This prevents modification of the file.
When a file is retrieved (either for editing or making) it is
actually retrieved if the file on disk is different than the
retrieved version or the last version was retrieved for the
opposite purpose. For example, if a file is retrieved for editing
and the version on disk is different (i.e. has a different date
and time stamp) then the file will be written to disk. If the
file is the same but was last retrieved for editing and is now
being retrieved for making, the file will be written to disk.
Note that when a file is checked in (using the CHECKIN program)
the file on disk is assumed to be retrieved for editing.
The command line for CHECKOUT is as follows:
CHECKOUT -e[M.N[.R]] PROJECT [FILE1.C FILE2.C ... FILEn.C]
-or-
CHECKOUT -m[M.N[.R]] PROJECT [FILE1.C FILE2.C ... FILEn.C]
The '-e' switch is used to retrieve files for editing. The '-m'
switch is used to retrieve files for making. Only one is allowed
on the command line.
When the Version level is omitted, the most recent version is
retrieved. If the Revision number is omitted, the most recent
Instance is retrieved. Note that you must specify a Version in
order to specify a Revision.
If you do not specify any file names on the command line, all
files which are different than the version on disk will be
retrieved. If one or more files are named in the command, only
those files will be retrieved. Note that a file will be retrieved
only if the version on disk is different (has a different time
and date) or was last retrieved for the opposite purpose (editing
versus making.)
page 8 PSCM
PSCM -- The Project Source Code Manager December 3rd, 1990
Listing the Files in the Project Database
The CHECKOUT program is also used to list files in a specific or
the latest version. The listing shows each file's name, time and
date, and full version and revision number. The command is as
follows:
CHECKOUT -l[M.N[.R]] PROJECT [FILE1.C FILE2.C ... FILEn.C]
As with the other forms of the CHECKOUT command, the version and
revision numbers and the file names are optional.
Listing Comments in the Project Database
CHECKOUT can also list the comment records stored in the
database. When new Instances of files are created using the '-c'
switch in the CHECKIN program, a comment record is saved along
with a list of the files that were updated. CHECKOUT can list
either a specified comment record or all comment records. The
commands used are as follows:
CHECKOUT -c[M.N] PROJECT
-or-
CHECKOUT -cM.N.R PROJECT
The first command form is used to list all comment records. If a
Version is specified then all comments for that version will be
listed. Otherwise all comments for the latest version are listed.
The second command form is used to list a specific comment
record. As with files, all comment records are assigned a
Revision number. This revision number is not related to the
revision numbers of the other files in the database, it is simply
used to track sequential comments.
The output from the Comment command is sent to STDOUT. This means
that it may be redirected to a file or piped to another program
if desired. (For a complete discussion of redirection and pipes,
please refer to your DOS manual.)
Listing or Retrieving Files Sets
The CHECKOUT program is also used to list or retrieve Sets saved
in the project database using the CHECKIN program. The Set
command forms are as follows:
CHECKOUT -s[M.N] PROJECT
-or-
CHECKOUT -sM.N.R PROJECT
-or-
CHECKOUT -rM.N.R PROJECT
The first form is used to list all Sets saved in the project
database file. If a Version is specified then only Sets for that
PSCM page 9
PSCM -- The Project Source Code Manager December 3rd, 1990
version are listed. If the Version is omitted, then the Sets for
the most recent Version are listed. The listing includes the
comment saved when the Set was created along with a list of all
files and their revisions that were saved in the Set. The listing
is sent to STDOUT so it may be redirected to a file or piped to
another program.
To retrieve the files from a specific Set, the second and third
command forms are used. An exact Version and Instance must be
specified. Note that the Revision numbers of the Sets are not
related to the Revision numbers for files. All files are
retrieved at the Version and Instance specified in the Set.
When the '-s' switch is used, the files are retrieved for Making,
so all special macros are expanded and the files are marked as
read-only to prevent modification. If the '-r' switch is used,
then the files are retrieved for Editing. All macros are left
unexpanded and the files are made modifiable. Once a Set has been
retrieved, the files may be used to rebuild the project or simply
viewed or printed as desired.
page 10 PSCM
PSCM -- The Project Source Code Manager December 3rd, 1990
PSCM is ShareWare
I have been a software developer for many years. During that time
I have acquired and used many very good programs through the
"ShareWare" system. ShareWare allows you to try a program before
buying it. It does not mean the program is free, nor does it mean
that it is a limited version of a commercial program.
I wrote PSCM as an answer to my needs in software development. I
first came across the idea of source code and revision management
when I ported some code from DOS to Unix. The SCCS system on Unix
was very neat, but horribly cryptic and cumbersome. Since then I
have hunted for a good source code manager, but everything is
either priced way out of my range or just wasn't designed to work
with a MAKE program.
PSCM is designed to work with most types of MAKE programs. When
files are retrieved they are given the proper time and date so
MAKE can make the right decisions about what should be rebuilt.
PSCM will only store or retrieve files that are different thus
easing the control issues. All in all I like it. But then I'm
biased, I wrote it.
If you try PSCM and you like it and intend to use it, a donation
of $25 is suggested. Educational institutions may register PSCM
for $15. With a donation of $40 I will send the latest version of
PSCM, laser printed docs, and a BIG thank you. If you need a
bunch of copies, contact me and we can work something out.
To register your copy, print out and complete the registration
form (REGISTER.FRM) and mail or FAX it to:
J. Bart Henthorn
10607 E. Lowry Pl.
Aurora, CO 80010-4035
FAX: (303) 341-7336
Visa and MasterCard credit cards are welcome. But come early
'cause I don't accept American Express!
PSCM page 11
PSCM -- The Project Source Code Manager December 3rd, 1990
Revision History
Date Vers Comments
11/15/90 1.0 Initial Release: CHECKIN.EXE, CHECKOUT.EXE,
DIFS.EXE, MRGS.EXE, ISIZE.EXE
11/18/90 1.1 Enhancements and Bug Fixes:
Added support for Comments and Sets.
Fixed bug regarding file selection in
CHECKOUT.EXE
11/18/90 1.1a Fixed bug that caused wrong time/date stamps
on files listed in a Set. The files were
retrieved with the proper time and date,
just the listing in the Set was wrong.
Added mode to allow extracting Sets for
Editing as well as Making.
12/03/90 1.2 New Version 1.2:
Added support for revision comments placed in
files extracted for making.
page 12 PSCM