MULTICS TECHNICAL BULLETIN MTB-716-02
To: MTB Distribution
From: Lynda J. Adams
Gary C. Dixon
W. Olin Sibert
Date: September 27, 1985
Subject: Multics Configuration Management:
Tracking Software Changes for MR12.0
ABSTRACT
Configuration Management is the management of changes to systems.
MTB-713, "MR11 Configuration Management", describes our current
procedures for proposing, reviewing, implementing, installing and
tracking software changes. MTB-712, "Policy and Procedures for
Software Integration", describes procedures for software
installation in more detail.
In reviewing these procedures, the Multics B2 Evaluation Team
found several shortcomings. This MTB briefly describes the
shortcomings, and proposes minor changes to the Multics
configuration management process to correct them.
Revision 1 includes enhancements to the history_comment command
writeup, marked with change bars.
Revision 2 includes some significant changes to the |
history_comment command control arguments. The entire command is |
marked with change bars. |
Comments should be sent to the authors:
via Forum:
>udd>Multics>mtgs>Multics_Issues (multics) on System-M
via Multics Mail:
Sibert at System-M (for Installation Database)
GDixon at System-M (for history_comment Command)
via Telephone:
GDixon: (602) 249-6772
Sibert: (617) 646-8619
Forum transactions are preferred.
_________________________________________________________________
Multics Project internal working documentation. Not to be
reproduced or distributed outside the Multics Project.
MTB-716-02 Config Mgt Changes
CONTENTS
Page
1: Introduction . . . . . . . . . . . . . . . . . 0
2: The Problem . . . . . . . . . . . . . . . . . . 1
3: The Solution . . . . . . . . . . . . . . . . . 2
3.1: Installation Database . . . . . . . . . . . . 2
3.1.1: Database Format . . . . . . . . . . . . . . 4
3.1.2: Installation Reasons . . . . . . . . . . . 6
3.1.3: Installation Preparation Tools . . . . . . 7
3.2: History Comments . . . . . . . . . . . . . . 9
3.2.1: New Fields, Standard Format, Comment Tools 10
3.2.2: Existing, Old Format History Comments . . . 12
3.2.3: Submission and Installation Checks . . . . 12
3.2.4: Related Issues . . . . . . . . . . . . . . 12
Appendix A: Documentation for the history_comment
Command/AF . . . . . . . . . . . . . . . . . . . . 13
| history_comment (hcom) . . . . . . . . . . . . . 14
_________________________________________________________________
Config Mgt Changes MTB-716-02
1: INTRODUCTIONN
Configuration management (CM) is a process for managing how a
system is changed. The process must allow change in a
straightforward and simple manner while helping to promote the
overall goals of the system (correct operation, proper
enforcement of security features, adequate performance and
reliability, etc).
MDC uses its CM process to ensure the quality of software changes
to the Multics operating system. The process uses many
operations to achieve this quality (eg, peer review of proposals
and implemented code, tracking of system changes, regression
tests for major changes, maintenance of system libraries for
shipping software to customers, performance testing, etc).
CM procedures are a factor considered in granting a B2 security
rating, since responsibility for insuring the integrity of the
security mechanisms during system changes rests with the
configuration management process. When the Department of Defense
Computer Security Center (DoDCSC) team evaluating Multics for a
B2 security rating (the B2 Team) reviewed our CM procedures, they
found that the overall procedures were reasonable.
However, an examination of typical system changes found
indications that the CM process was somewhat ineffective. It was
difficult to track changes from conception to installation, or to
refer from a changed module back to design documentation. Also,
they found many indications of the CM process not being followed
(changes installed without MCRs or MECRs, changes installed
without proper history comments, etc).
Typical questions asked by the B2 team in its investigation of CM
were:
What modules were changed as part of MCRnnnn?
What MCRs changed module_name.pl1?
The team found many instances in which these questions could not
be answered.
Clearly, it is important for the CM process to provide MDC with
information to answer such questions. When trying to extend the
functionality or fix bugs in software modules, developers need to
know when a module was changed, why and how it was changed, and
by whom. From a B2 evaluation standpoint, it is important to
understand how the programs which enforce security policies
change from release to release.
Unfortunately, our current CM process makes it difficult
(sometimes impossible) to answer such questions. Given an MCR
MTB-716-02 Config Mgt Changes
number, there is no easy way to determine what modules were
changed for the MCR. Given a module name, there is no easy way
to determine what MCRs, MTBs and other documentation describe the
changes made to the module.
Also, our CM process lacks safeguards to ensure that
configuration management information is always gathered. Minor
slips in the current process (eg, forgetting a history comment at
the beginning of a program) can cause loss of configuration
management information needed to answer the two questions above.
2: THEPROBLEM
The problems in our CM process stem from its division into three
stages without having adequate information tying the stages
together. The three stages are:
o proposing a change (MTB, design review, MCR, and MCRB
approval);
o implementing the change (coding, testing, auditing, and
submitting an MSCR); and
o installing the change (packaging submissions together,
recompiling, producing cpa records of changes, regression
and performance testing, and installation into system
libraries).
During the proposal stage, the relationship between MTBs and MCRs
is established on the MCR form, which lists numbers of relevant
MTBs. Sometimes, MTB numbers are accidentally forgotten from the
MCR form. A prime cause of such omissions is performing the
items above out of order. The MTB may be written many months
before the MCR gets submitted. It is easy to forget to refer to
an MTB number in the rush of preparing a last minute MCR.
During the implementation stage, the relationship between MCR
numbers and new or changed modules is specified only on the MSCR
form. When the changes are submitted for installation, it is
easy to forget to put MCR numbers on the MSCR form. And when an
MSCR covers changes for several MCRs, it becomes impossible to
determine which module was modified for a particular MCR, since
MCR numbers are grouped together on the MSCR form rather than
being specified for each module.
The information relating MCRs with modules becomes even more
tenuous during and after the installation stage, because the
MCR/module correspondence information is not available online.
It is only available on the hardcopy MSCR form, which gets filed
in Phoenix. Having only hardcopy data makes quick listing of
Config Mgt Changes MTB-716-02
modules associated with a given MCR difficult, and makes listing
MCRs associated with a given module impossible.
In summary, the problem which must be addressed is lack of CM
information tying MTB and MCR numbers to changed modules. The
information must be available online, in a central database to
allow quick searches for modules modified by a given MCR. And it
must be available for each module, to permanently record the MCRs
associated with the module. Also, checks must be added to the CM
process to ensure that the information is gathered. Such
information would improve MDC's CM process by making it always
possible to answer the two questions shown above.
3: THESOLUTION
To resolve these problems, we propose to change the CM process in
two ways:
o create a new installation database maintained by the System
Integration staff which provides information about each
package of changes to be installed. For each installation
package, a database entry would record: the installation
identifier; numbers of MCRs, MECRs, PBFs, etc associated
with software in the installation; and names of modules
added, replaced, or deleted by the change. The database
would thereby relate MCR/MECR/PBF numbers to the names of
modules changed by the MCR or MECR.
o change the history comments in source programs to include
the MCR number, auditor's name and date, and installation
identifier, as well as a summary of the change. Such
entries would permanently record the MCRs associated with a
given module in the module source itself. It is easier to
maintain this information by storing it in the module, to
ensure that it remains synchronized with actual changes to
the source module. Storing the information in the source
also provides a cross reference from the module to records
in the installation database. And it allows developers and
installers to perform automatic checks which ensure that CM
information isn't forgotten.
In implementing the changes proposed above, our goals are to
interfere as little as possible with the existing CM process, and
to add to the developer's workload as little as possible.
3.1: InstallationDatabase
To satisfy the requirements for configuration management, a
database is required that can answer questions about the contents
and purposes of software installations.
MTB-716-02 Config Mgt Changes
The procedures and installation tools used for MR10.2 (described
in MTB-712, by Rich Holmstedt) does collect most of the necessary
information, but in a form that cannot be used for any automated
process, and that does not contain any cross referencing
information or error checking. Consequently, the collected
information is incomplete, fraught with inconsistencies, and, for
some installations, missing entirely.(1)
The purpose of the database and data entry tools described here
is to eliminate those difficulties, and to collect the required
information during the installation process in a machine
interpretable form. The goal for these tools is to be as easy to
use as the tools in use now, while enforcing the requirements for
consistency.
The installations database is a lister file (actually, more than
one if the first one overflows for any given release; MR11 would
just have fit in a single one). It contains one record for each
distinct installation. These records are created by a set of
programs and exec_coms that prompt for information about an
installation.
An "installation" in this system continues to mean what it means
today: one or more MSCRs, describing some set of programs that
is installed in a single operation. This set of programs may be
quite large, and include changes described by multiple MCRs.
Installation tracking is easiest when individual installations
are small, but that is not a requirement.(2) This database is
completely independent of the various automated MSCR/installation
form mechanisms; only the description and names of the submitters
and auditors could be collected from such automated MSCRs,
anyway.
_________________________________________________________________
(1) For example, of the installations recorded in
Installations.log for MR10.2, nearly 15 percent had no
textual description at all, and an additional 20 percent did
not specify any MCR or MECR in their descriptions.
(2) Ideally, we would like to have one "installation" correspond
to one MSCR, but MSCRs are often installed in batches to make
the installer's job easier. Certain database fields
(submitter, auditor) are only really meaningful if most
installation records correspond to a single MSCR. It is also
desirable to have MSCRs themselves be less encompassing, and
have individual MSCRs for individual changes, rather than a
single MSCR covering, say, a week's worth of mostly unrelated
hardcore changes. Since the new installation preparation
tools should actually be easier for the installer to use, we
should examine the possibility of making average
Config Mgt Changes MTB-716-02
3.1.1: DATABASE FORMAT
Information gathered from the System Integration installer by the
installation preparation tools is formatted into database
records, containing the following fields:
Installation ID
A unique number identifying the installation. This is a new
field; prior to MR11, installations were not identified
except by MCR number. It serves as a way to locate the CPA
output segments from the preparation step, and to trace back
to paper records if necessary. This field is supplied
automatically by the installation tools, and has the format
"MRxx.x-nnnn".
Installation Time
The date and time at which the installer prepared (via
pinst.ec) the installation. This field is supplied
automatically by the installation tools.
Installation Type
The type of this installation: "install" or "de_install".
This field is supplied automatically by the installation
tools. All transactions against the system libraries are
recorded in the database, although most fields are valid
only for "install" installations. Only the ID, time, type,
installer, and log fields are valid for de-installations.
Submitter
The person-id(s) of the person(s) submitting the
installation. This is a new field. It is supplied by the
installer, who copies it from the MSCR(s). If the
installation includes multiple MSCRs, this field contains
the names of all the submitters.
Auditor
The person-id(s) of the person(s) named as having audited
the installation. This is a new field. It is supplied by
the installer, who copies it from the MSCR(s), as for the
submitter field.
Installer
The person-id of the System Integration person actually
installing this particular set of changes into the system
libraries. This field is supplied automatically by the
installation tools.
Reason
_________________________________________________________________
installations smaller.
MTB-716-02 Config Mgt Changes
The stated reasons for this installation: MCR, PBF, MECR
numbers, etc. This is a single field that lists all the
appropriate numbers, as in "MCR7231", "PBF6906", "MECR0102",
"INFO", "LIB", etc. A complete list of reasons is shown
below. This field is supplied by the installation tools,
which prompt the installer for the information and verify
that it is correct.
Description
A text description of the installation. This is the text
that appears in the XXX.changes.info segments. It consists
of (1) a canned string listing the date, time, installation
ID, and reasons, (2) an optional text description supplied
by the installer, (3) the SUMMARY fields of all the MCRs
listed as being installed, (4) the TITLE fields of all MCRs
listed as PBFs in this installation, and (5) the
descriptions of all the MECRs. Except for the optional
overall description, this field is supplied entirely by the
installation tools. The installer has the opportunity to
review and edit the description before it is used, in case
it is necessary to edit out inappropriate parts of MCR
descriptions. This description field requires much less
typing by the installer, since the list of bound segments
can be omitted, and for most installations, the MCR
summaries are sufficient to describe the installation.
Change Log
This field contains, in its entirety, the "change log"
produced by update_seg to describe the actual changes it
makes. It is inserted by the installation tools after
update_seg has run to completion.
The two fields most important for crossreferencing are the
Reasons and Change Log fields. To answer questions about a
particular MCR, one need only search for records containing that
string in the Reasons field. To answer questions about a
particular program, one need only search for records containing
the program name as a string in the Change Log field. Both of
these will produce a series of Installation IDs, auxiliary
information, and descriptions, from which one can go to the
appropriate CPA directories, MSCR(s), MCR(s), or whatever.
Answering questions about individual programs is critically
dependent on the automated history comment mechanism described
below. Only the combination of those plus the database makes it
possible to track changes for individual MCRs in large
installations.
Because the reason field is constructed by a program, and has a
fixed format, it can be processed to create a crossreference
listing of installations affected by a particular MCR, sorted by
MCR number, generate statistics about PBFs, track MECRs, etc.
Config Mgt Changes MTB-716-02
Each "reason" is a separate token (to the command processor), and
they are separated by spaces.
Although this is in theory true of the change log, its format is
much more complicated, and not subject to easy parsing after the
fact. However, any desired crossreferencing (installations or
MCRs affecting a particular module) is already provided by the
history comments automatically inserted in the source.
3.1.2: INSTALLATION REASONS
Each installation must have one or more "reasons" for being
installed. These reasons are prompted for when the database
record is being prepared,(1) and are automatically validated by
an MDC-specific validation routine used both by the installation
tools and the history comment program. The reasons identify the
paperwork preceding the actual change, and have one of the
following forms:
MCRnnnn
Identifies an MCR describing the change. The title of the
MCR is displayed for verification when the installer gives
this as a reason, and the summary(2) field of the MCR is
included into the installation info in the database record.
This information is derived from the online MCR database.
PBFnnnn
Identifies a Post-Installation Bug Fix (PBF) to some
specified MCR. The title of the MCR is displayed for
verification, and is also included in the installation info.
nnnn refers to the number of the MCR associated with the
module being fixed by the PBF.
MECRnnnn
Identifies an MECR describing the change. The MECR
description is displayed for verification (from the System-M
MECR database), and included in the installation info.
Since all MECRs are generated on System-M, the MECR numbers
no longer include a "P" (for Phoenix). nnnn refers to the
_________________________________________________________________
(1) Also when adding history comments
(2) The summary field is not currently available in the MCR
lister database; this may not be practical. We are examining
how difficult it would be to add the summary field to the
lister database.
MTB-716-02 Config Mgt Changes
MECR number assigned by Phoenix System Integration personnel
when an MECR is installed. This is the sequence number of
the MECR lister database entry associated with the MECR.
INFO Identifies an installation consisting solely of info
segments (provided by the documentation unit, presumably).
Since there is no formal paperwork for an info segment
installation, nothing is displayed for verification. For an
info segment installation, the installer must manually
include a short description of the info segments concerned
when prompted later for the description.
LIB Identifies an installation made for the purpose of library
maintenance, such as updating protection notices. As for
INFO installations, there is no verification, and the
installer must manually provide a description later.
OUTSIDE
Identifies an installation of software from an outside
source: third-party software, presumably. Again, since
there is no formal paperwork, the installer must provide a
description.
OTHER
Identifies an installation made for some reason other than
those listed above. This should be used sparingly, since it
defeats the whole purpose of the installation tracking
system.
3.1.3: INSTALLATION PREPARATION TOOLS
The new tools and procedures to be used by System Integration
personnel when installing an MSCR are basically the same as those
described in MTB-712. The major difference is that instead of
writing a single Reasons description for update_seg while
preparing the installation exec_com, the installer responds to a
prompting program that asks for the various database fields.
Once all fields are prompted for, their values are stored in an
installation exec_com, which the installer can edit as needed.
The output of the prompting program is a listin file containing a
single record that is used to create the new database record when
the actual installation exec_com is run, later, to make the
installation.
A major improvement in consistency is provided by this prompter,
since it enforces a fixed format for information required to do
crossreferences. In particular, for each MCR, it provides the
installer with the title of the MCR, allowing him to verify that
the MCR number is correct (for PBFs, the title of the affected
MCR is displayed; for MECRs, the MECR title).
Config Mgt Changes MTB-716-02
Because the text is being mechanically generated, in order to
avoid redundant information in the database and provide a fixed
format, the change log info segments (online.changes.info,
hardcore.changes.info, etc.) are updated explicitly by the
installation exec_com, rather than by update_seg.(1) The text
provided to update_seg as log information for Installations.log
and Installations.info includes only the installation number,
date, and time.
Since the change log field of the database is generated by
update_seg, the Installations.log is created in the installation
directory(2) for each installation, and contains only the
description of the current installation. This avoids any need to
separate out (as by an editor macro, for instance) the "new" part
of Installations.log. This Installations.log segment is combined
with the listin file generated earlier by the prompter and used
to generate the new database record after the installation has
been performed.
Because the installation database is limited to a single segment,
the tools complain if the lister file grows large (more than 200
records, say), and refuse to even begin if it is near overflowing
(more than 250 records). This will give the installer the
opportunity to rename the old lister files and save them away
without danger of the process blowing up in the middle because
there isn't any room. The display tools, much like the MCR
database tools, understand naming conventions for old lister
files, and reference them all when required.
Another change is that all installations are identified by a
particular unique identifier. This number identifies the audit
directory, and thus the module CPAs in that directory. It has
the form "MRxx.x-nnnn", where "MRxx.x" is the release this
installation is targeted for, and "nnnn" is a sequentially
assigned number that is unique for all time. For ease of typing,
the CPA directories will have two names: the long form, and a
short name consisting of the unique number only.
The module CPAs are maintained somewhat better: rather than just
generating a "MODULE.cpa" segment for each changed module, the
installation preparation tools generate different types of
comparison segments for the different cases. A MODULE.cpa
_________________________________________________________________
(1) ==> This is probably not right, but I'm still not sure
exactly what it should do. There may be modifications
required for update_seg.
(2) Previously, a link was made in the installation directory to
the standard Installations.log segment, and this is still
done for Installations.info and Installations.lock.
MTB-716-02 Config Mgt Changes
segment is created, comparing the module against the current
library copy, for any module that is actually changed. A
zero-length MODULE.eq segment is created for any module that is
just being recompiled. A MODULE.new segment is created for any
module that is new with this installation, and contains the
original source for the module. No segment at all is created for
modules that are deleted by an installation.
Since only modules actually changed have CPA output, this allows
quick identification of significant changes. Following that,
"print -match" can be used to pick out changes for particular
MCRs (identified by history comments).
By using the CPA outputs, it is possible to mechanically
reconstruct the source for a module at any time in its life by
applying the CPA outputs with the "recreate" command.(1)
3.2: HistoryComments
The CM process requires that each change to a source module be
logged in a history comment, as a method of tracking when, why
and by whom the module is changed. The current history comment
mechanism has several shortcomings:
o History comments are not always added. Sometimes both the
developer and auditor overlook the missing comment, thereby
causing loss of this important CM information.
o History comments make no reference to the MCRs or MTBs
describing the change, making it difficult for someone to
review the design documents for a change once the module is
installed.
o History comments do not mention who audited the change.
When problems arise with a module and the developer is
unavailable, it is useful to be able to turn to the auditor
as another person who has knowledge of the code.
o History comments do not indicate when a given change was
actually installed. Sometimes, changes are made months (or
years) prior to their installation in the system libraries.
It is thereby difficult to determine when a particular
change actually reached customer sites. Such information is
important when creating critical fixes, advising customer
sites about software problems, designing future changes to
the module, etc.
_________________________________________________________________
(1) Although the MCR board rejected this, if not installed in the
system, it will be part of the installation tools library.
Config Mgt Changes MTB-716-02
o History comments are sometimes backed out, along with the
changes they describe, when a developer accidentally
installs a module which does not include changes installed
earlier. If the CM process could ensure that history
comments were added for every change, then we could compare
a changed module with the library copy, with missing history
comments indicating that a change is being backed out.
Correcting the shortcomings above will make it easier for Multics
developers to maintain the software and to install high-quality
products.
3.2.1: NEW FIELDS, STANDARD FORMAT, COMMENT TOOLS
The shortcomings above will be corrected by adding several new
fields to source module history notices: MCR and MECR numbers,
auditor person_id and date of audit, and installation id.
Recognizing that the information in the new fields often isn't
available when a new history comment is added to a source
program, our proposal includes creation of a new tool called
history_comment (hcom) to update existing history comments in a
source module at a later date. The program will also add new
history comments and display selected history comments.
Programmed maintenance of history comments requires
standardization of their format. The proposed format is:
/* HISTORY COMMENTS:
no) change(<date>, <dev_pers_id>), approve(<date>,<mcr_no>),
audit(<date>, <auditor_pers_id>), install(<date>, <inst_id>):
<summary of change>
END HISTORY COMMENTS */
An example of two history comments in a PL/I program is:
/****^ HISTORY COMMENTS: |
1) change(85-05-12, GDixon), approve(85-05-12, MCR2355),
audit(85-05-26, Sibert), install(85-05-30, MR11.0-3382):
Increased size of test_array to eliminate subscript error.
2) change(85-05-28, LJAdams), approve(85-05-30, MCR2356),
audit(85-06-05, GDixon), install(85-06-10, MR11.0-3384):
Added the -brief and -long control arguments.
END HISTORY COMMENTS */
History comments will appear immediately after the pnotice, if a |
pnotice is present, or at the beginning of the source file if no |
pnotice is present. Include files generally do not have a |
leading pnotice, but do have a leading header line which names |
the include file. For include files, the history comment will |
immediately follow this header line. |
MTB-716-02 Config Mgt Changes
Every history comment begins with a sequence number, to help
identify particular comments, make it easier to determine when
there is a missing notice (when a change is being backed out),
and to help in validating history comment format. Each comment
contains a change field identifying who created or changed the
module, and a summary field briefly describing the change. These
are the minimum fields required in a properly formatted comment.
When the change is approved, the history_comment update operation
adds an approve field containing the MCR or MECR number for
regular changes (eg, MCR6678, MECR0105) to an existing comment.
For post-installation bug fixes, the original MCR number is given
with a PBF prefix (eg, PBF6678).
At the point where the change is audited, either the auditor or
developer uses the history_comment update operation to add an
audit field to existing history comments.
And when the change is being installed, System Integration
personnel will add to existing comments an install field
identifying the release and installation which includes the
module.
An Emacs extension will be provided in Emacs pl1-mode to setup
the HISTORY COMMENTS header and END HISTORY COMMENTS footer, and
to add a standard history comment as the program is actually
being changed. This should make it easier for the developer to
record changes as they are made without requiring a separate step
outside of the editor. The Emacs extension will prompt for
individual fields, validate MCR numbers, format the summary
field, etc.
The program and Emacs extension should make it just as easy to
enter a standard format history comment as entering unformatted
comments today.
3.2.2: EXISTING, OLD FORMAT HISTORY COMMENTS
The CM process will require every program installed following the
unfreeze of MR11.0 to have one or more history comments in the
new format. As existing programs are modified, the developer can
simply begin adding standard history comments, leaving existing
comments as they are. This avoids start-up costs associated with
converting existing history comments to the new format.
However, the standard format was designed to make it easy for
developers to use Emacs to edit the existing comments into the
new format, if they so choose. For programs which have a fairly
standard history comment format, it should be fairly simple to
write an Emacs editor macro to put them into the standard format.
Also, the history_comment tool will have an option for putting
Config Mgt Changes MTB-716-02
dates into standard format, for refilling entries, etc to
simplify conversion of existing comments. The existing comments
must indicate that auditor and installation id information is
unknown by editing in "audit(), install()" as the last two items
of each edited history comment header. These empty fields will
tell the history_comment program not to diagnose the missing
fields as an error.
3.2.3: SUBMISSION AND INSTALLATION CHECKS
The history_comment program will provide a check operation which
developers can use just prior to software submission to ensure
that a new history comment is present, and that all fields except
the installation id are supplied. This check will help
developers make sure their source programs are ready to install.
Similarly, history_comment will provide an installation operation
to be used by the System Integration staff to make sure that new
history comments are supplied in all source programs, make sure
that no changes are being backed out by an installation, and to
fill in an installation ID (and optionally an MECR number for
emergency changes) into the new history comments. This will help
ensure that CM information isn't lost or accidentally omitted.
3.2.4: RELATED ISSUES
If the <dev_pers_id> and <audit_pers_id> fields are to be
validated at all (against some database of known person_ids, such
as the Mail Table), Multics developers must have the same
person_ids on every MDC system (ACTC, CISL, MIT and M). This is
not currently true today. Person_id differences between systems
would be caught by the field validation checks performed in the
install operation when the code was installed on System M.
To avoid such problems in the first version, we will simply not
validate these person_id fields, other than for format (name <23
chars with initial capital letter).
APPENDIX A:DOCUMENTATION FOR THE history_comment COMMAND/AF
The following module description documents the user interface and
functionality of the proposed history_comment command. |
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| Name: history_comment (hcom)
|
|
| SYNTAX AS A COMMAND:
|
| hcom operation path {args} {-control_args}
|
|
| SYNTAX AS AN ACTIVE FUNCTION:
|
| [hcom operation path {args} {-control_args}]
|
|
| FUNCTION: adds, checks, displays, formats and updates software
| change history comments within a given source module.
|
|
| ARGUMENTS:
|
| operation
| designates the operation to be performed. See "List of
| Operations" below.
|
| path
| is the name of a source code program that requires history
| comments. The language suffix must be included.
|
| args
| are optional arguments appropriate to the particular operation
| being performed.
|
|
| CONTROL ARGUMENTS:
|
| -control_args
| are optional control arguments which vary, depending on the
| particular operation to be performed. Allowed values are
| described below for each operation.
|
|
| LIST OF OPERATIONS:
|
| add
| adds a new history comment to a source program.
|
| add_field, af
| add missing fields to an existing history comment.
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
replace_field, rpf |
replaces fields in an existing history comment. |
|
display, ds |
displays one or more history comments in a source program. |
|
format, fmt |
reformats history comments in a source program, placing them |
in standard form. |
|
check, ck |
checks history comments in a source program prior to its |
submission for installation to ensure that all fields except |
the INSTALL_ID are present. |
|
compare, cmp |
displays the differences, if any, between the source and |
original modules. |
|
exists |
checks to see if a history comment with certain attributes |
exists. |
|
get |
gets one or more field values from selected history comments. |
|
install |
checks history comments in a source program prior to its |
installation for completeness, and updates the INSTALL_ID |
field. |
|
|
HISTORY COMMENT FORMAT: |
|
Following is a pl1 history comment example. Other languages will |
have the comment delimiters appropriate for their respective |
language. |
|
/****^ HISTORY COMMENTS: |
1) change(85-05-12, HSmith), approve(85-05-25, MCR2355), |
audit(85-05-26, Jones), install(85-05-30, MR11.0-3382): |
Increased size of test_array to eliminate subscript error. |
2) change(85-05-28, HSmith), approve(85-05-29 MCR2356), |
audit(85-06-05, Rogers), install(85-06-10, MR11.0-3384): |
Added the -brief and -long control arguments. |
END HISTORY COMMENTS */ |
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| LIST OF HISTORY COMMENT FIELDS:
|
| The fields within a given history comment are identified as
| follows:
|
| NO) change (CHANGE_DATE, CHANGE_PERSON_ID),
| approve (APPROVE_DATE, APPROVE_ID),
| audit (AUDIT_DATE, AUDITOR_PERSON_ID),
| install (INSTALL_DATE, INSTALL_ID): SUMMARY
|
| The fields in a history comment are named as described below.
| The sample validation routine, hcom_default_validate_, validates
| field formats used by the Multics Development Center as described
| below. However, each site may provide its own validation
| routines to tailor the contents of the user-settable field
| values.
|
| NO
| is the number of the history comment. Comments are numbered
| sequentially in chronological order, starting with 1.
| (supplied by hcom)
|
| CHANGE_DATE
| date (yy-mm-dd) on which history comment was first added to
| the source module. (supplied by hcom)
|
| CHANGE_PERSON_ID
| person_id of the person who added the history comment.
| (supplied by hcom)
|
| APPROVE_DATE
| date (yy-mm-dd) on which an approval value was supplied for a
| history comment. (supplied by hcom)
|
| APPROVE_ID
| identifier authorizing the change. The default validation
| routine expects an identifier in the form "TYPEnnnn" for MCRs
| (Multics Change Request), PBFs (Post-installation Bug Fix
| associated with MCRnnnn), or MECRs (Multics Emergency Change
| Request); i.e., MCR6734, PBF6734, MECR0102. For critical
| fixes the identifier should be in the form of fix_nnnn or
| fix_nnnn.ds. The maximum length of this field is 24
| characters. (supplied by user)
|
| AUDIT_DATE
| date (yy-mm-dd) audit field added to history comment.
| (supplied by hcom)
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
AUDIT_PERSON_ID |
person_id of the person who audited the source module. |
(supplied by hcom) |
|
INSTALL_DATE |
date (yy-mm-dd) install field added to history comment. |
(supplied by hcom) |
|
INSTALL_ID |
value identifying either a specific installation or the |
installer of a critical fix. The default validation routine |
expects an identifier in the form "MRrel-nnnnn", consisting of |
a release number and installation sequence counter, e.g., |
MR12.0-00234. For a critical fix, the validation routine |
expects a person-id naming the person who installed the fix. |
The maximum length of this field is 24 characters. (supplied |
by user) |
|
SUMMARY |
brief description of the change made to the module. This |
field contains text (up to 2000 characters) and is not |
validated. (supplied by user) |
|
|
NOTES: |
|
The following is a typical usage pattern expected for the various |
operations of the history_comment command. |
|
o The developer makes a change to the source module. He could |
add a new history comment by hand (perhaps using an Emacs |
extension to prompt for field values). Or after adding the |
change, he could use the history_comment add operation to |
add a new comment. A typical command line might be: |
|
hcom add prog.pl1 |
|
o The developer may not have had approval for the change at |
the time the history comment was added. When approval is |
gained, he can use the history_comment add_field operation |
to add the approve field. For example: |
|
hcom af prog.pl1 -approve MCR7235 |
|
o The developer can display the history comments in a program, |
or even compare the comments in a modified version of a |
program with those in the library copy of the program. For |
example: |
|
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| hcom display prog.pl1 new -orig [lpn prog.pl1]
|
| would display the new history comments in the source module,
| while
|
| hcom compare prog.pl1 -orig [lpn prog.pl1]
|
| would display the differences between the source module and
| the original module.
|
| o When the change is audited, the auditor uses the
| history_comment add_field operation to supply an audit field
| for all new or incomplete history comments. For example:
|
| hcom af prog.pl1 -audit
|
| o When the developer is ready to submit the change for
| installation, he uses the history_comment check operation to
| ensure that all comment fields except the install field have
| been supplied in each changed module. Since the developer
| has a site-defined validation routine called
| hcom_site_validate_ in his object search rules, this routine
| is used to fully validate the fields of all comments.
|
| hcom check prog.pl1 -orig [lpn prog.pl1]
|
| o When the installer receives the modules in an installation,
| he uses the history_comment install operation to ensure that
| new history comments describing the changes are present.
| The install operation also adds an identifier to each new
| comment, indicating in which installation it was installed.
| The installer can use a special library-defined validation
| routine to perform special field validations. In the
| example below, this library validation routine is called
| hcom_mdc_validate_.
|
| hcom install prog.pl1 -vdt hcom_mdc_validate_ -install
| MR12.0-0023 -orig [lpn prog.pl1]
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
VALIDATION ROUTINE CALLING SEQUENCE: |
|
|
A site can define a site-wide history comment validation routine |
to validate the contents of the APPROVE_ID and INSTALL_ID fields |
of history comments. This routine is called hcom_site_validate_. |
If it is found in the user's object search rules, the |
history_comment command will automatically use this validation |
routine instead of using hcom_default_validate_. Also, the |
-validate control argument allows use of a user-supplied |
validation subroutine to validate the APPROVE_ID and INSTALL_ID |
fields. This user routine can have any name. |
|
The calling sequence of both the hcom_site_validate_ subroutine |
and user-written routines is shown below. For a user-writter |
routine, the name hcom_site_validate_ would be replaced with |
whatever name the user chooses for the routine. |
|
dcl hcom_site_validate_ entry (char(*) var, char(*) var, |
char(*) var, bit(1), char(*) var, char(*) var); |
|
call hcom_site_validate (caller, field_name, input_value, |
result_bit, canonical_value, field_type); |
|
caller |
is the name of the calling program, on whose behalf the |
validation routine should report errors, ask questions, etc. |
(Input) |
|
field_name |
is the name of the field being validated. This argument may |
have a value of either APPROVAL_FIELD_NAME or |
INSTALL_FIELD_NAME. These named constants are declared in |
hcom_field_names.incl.pl1. (Input) |
|
input_value |
is the field value supplied by the user. (Input) |
|
result_bit |
is either "1"b if the input value is valid or "0" b if the |
input value is invalid. (Output) |
|
canonical_value |
is the canonical text form of the field_name and input_value. |
(Output) |
|
field_type |
is the canonical text form of the field_name for use in error |
messages. (Output) |
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| Operation: add
|
|
| SYNTAX AS A COMMAND:
|
| hcom add path {-control_args}
|
|
| FUNCTION: adds a new history comment to the requested module.
| The summary field is required, all other history comment fields
| are optional.
|
|
| ARGUMENTS:
|
| path
| is the name of a source code program that requires history
| comments. The language suffix must be included. An archive
| pathname may be given.
|
|
| CONTROL ARGUMENTS FOR FIELD INPUT:
|
| -summary TEXT, -sm TEXT
| gives text describing the change. If the text contains
| spaces, quotes, parentheses, etc, the TEXT must be enclosed
| within quotes.
|
| -input_summary, -ism
| prompts the user for the summary field. This is a multiline
| field. See "Notes" below. This is the default.
|
| -approve APPROVE_ID, -apv APPROVE_ID
| specifies the APPROVE_ID field. The maximum length of this
| field is 24 characters. See "List of history comment fields"
| above for a description of valid APPROVE_IDs.
|
| -input_approve, -iapv
| prompts for an APPROVE_ID. This is the default. This is a
| single line field value.
|
| -no_approve, -napv
| specifies that an APPROVE_ID is not being entered.
|
| -install INSTALL_ID, -in INSTALL_ID
| specifies an identifier associated with installing the changed
| module into execution libraries. See "List of history comment
| fields" above for a description of valid INSTALL_IDs. The
| maximum length of this field is 24 characters.
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
-input_install, -iin |
prompts for the INSTALL_ID. This is a single line field. |
|
-no_install, -nin |
Suppresses the prompt for INSTALL_ID. This is the default, |
since the installation ID is usually specified when the module |
is being installed rather than when the history comment is |
first added. |
|
|
CONTROL ARGUMENTS: |
|
-validate RTN, -vdt RTN |
validates user-supplied fields in the history comment, using a |
user-supplied validation routine. RTN must be a virtual |
entrypoint name acceptable to subroutine cv_entry_. If |
-validate is not supplied, the default is to validate using |
the hcom_site_validate_ subroutine, if your site has provided |
such a routine, or hcom_default_validate_ subroutine provided |
with the history_comment command. |
|
-critical_fix, -cfix |
specifies that critical fix history comments are allowed in |
the program. All comments following the first, which contains |
critical fix field values, must also contain critical fix |
field values. |
|
|
NOTES: |
|
For multiline fields, all input is treated as text until reading |
a line with just a period (.). Input lines beginning with ".." |
are treated as Multics command lines, rather than as part of the |
field value. After the command line is executed, the user may |
continue answering the prompt, or may replace input text typed so |
far with a new answer. Optional field values answered with just |
a period cause the field to be omitted from the history comment. |
|
For single line fields, input ends when a carriage return is |
typed. If the input line begins with "..", the text which |
follows is treated as a Multics command line. After the command |
line is executed, the user is prompted again for the question. |
Optional field values answered with just a carriage return cause |
the field to be omitted from the history comment. |
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| Operation: add_field, af
|
|
| SYNTAX AS A COMMAND:
|
| hcom af path {comment_specs} {-control_args}
|
|
| FUNCTION: inserts missing fields in selected comments.
|
|
| ARGUMENTS:
|
| path
| is the name of a source code program that requires history
| comments. The language suffix must be included. An archive
| pathname may be given.
|
| comment_specs
| specify which history comment(s) are to be updated. See "List
| of Comment Specifiers" below. The default is to select
| comments which are missing the fields given by the "Control
| Arguments for Field Input" below.
|
|
| CONTROL ARGUMENTS FOR FIELD INPUT:
|
| -approve APPROVE_ID, -apv APPROVE_ID
| inserts the missing APPROVE_ID field. The maximum length of
| this field is 24 characters. See "List of history comment
| fields" above for a description of valid APPROVE_IDs.
|
| -input_approve, -iapv
| prompts for a new APPROVE_ID. This is a single line field
| value. This is the default if no field input control
| arguments are given.
|
| -no_approve, -napv
| does not replace the APPROVE_ID field, or prompt for missing
| approve fields. This is the default if any field input
| control arguments are given.
|
| -audit, -aud
| inserts the users person_id in the AUDIT_PERSON_ID field.
|
| -no_audit, -naud
| does not add the AUDIT_PERSON_ID field. This is the default.
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
-install INSTALL_ID, -in INSTALL_ID |
specifies an identifier associated with installing the changed |
module into execution libraries. See "List of history comment |
fields" above for a description of valid INSTALL_IDs. The |
maximum length of this field is 24 characters. |
|
-input_install, -iin |
prompts for the INSTALL_ID. This is a single line field. |
|
-no_install, -nin |
does not set the INSTALL_ID field or prompt for missing |
install fields. This is the default. |
|
|
CONTROL ARGUMENTS: |
|
-validate RTN, -vdt RTN |
validates user-supplied fields in the history comment, using a |
user-supplied validation routine. RTN must be a virtual |
entrypoint name acceptable to subroutine cv_entry_. If |
-validate is not supplied, the default is to validate using |
the hcom_site_validate_ subroutine, if your site has provided |
such a routine, or hcom_default_validate_ subroutine provided |
with the history_comment command. |
|
-critical_fix, -cfix |
specifies that critical fix history comments are allowed in |
the program. All comments following the first which contains |
critical fix field values must also be critical fix history |
comments. |
|
|
LIST OF COMMENT SPECIFIERS: |
|
I, I:J |
selects the comment(s) by a comment number or a range of |
numbers. The keywords "first" or "f" and "last" or "l" may be |
given to identify the first and last comments. |
|
all, a |
selects all comments. |
|
complete, cpt |
selects comments which include all fields. |
|
incomplete, icpt |
selects comments which are missing the approve, audit or |
install field. |
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| approved, apv
| selects comments which have an approve field.
|
| unapproved, unapv
| selects comments which do not have an approve field.
|
| audited, aud
| selects comments which have an audit field.
|
| unaudited, unaud
| selects comments which do not have an audit field.
|
| installed, in
| selects comments which have an install field.
|
| uninstalled, unin
| selects comments which do not have an install field.
|
| new
| when -original is given, selects comments which do not appear
| in the original (earlier) version of the program.
|
| old
| when -original is given, selects comments which appear in both
| the original and new versions of the program.
|
|
| NOTES:
|
| If no control args are given, the default is to print selected
| history comments and prompt the user for missing approve fields.
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
Operation: check, ck |
|
|
SYNTAX AS A COMMAND: |
|
hcom ck path {-control_args} |
|
|
SYNTAX AS AN ACTIVE FUNCTION: |
|
[hcom ck path {-control_args}] |
|
|
FUNCTION: presubmission check run by developers to ensure that |
at least one history comment has been added to describe |
modifications to the source module. These history comments will |
be incomplete, because they will not have an install field. But |
all other fields should be supplied prior to submission. |
|
The presubmission check looks for one or more incomplete (or new |
if -original is given) history comments, and verifies that their |
summary, approve, and audit fields are given while the install |
field is missing. The active function returns true if the check |
succeeds (the history comments are ready for submission), and |
false otherwise. |
|
|
ARGUMENTS: |
|
path |
is the name of a source code program that has history |
comments. The language suffix must be included. An archive |
pathname may be given. |
|
|
CONTROL ARGUMENTS: |
|
-original orig_path, -orig orig_path |
specifies that the current version of the source program is to |
be cross checked with an earlier version (given as orig_path) |
to ensure that there are new history comments in the current |
module. An archive pathname may be given. The equal |
convention is allowed. The default is to check for incomplete |
history comments in the given source program. |
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| -validate RTN, -vdt RTN
| validates user-supplied fields in the history comment, using a
| user-supplied validation routine. RTN must be a virtual
| entrypoint name acceptable to subroutine cv_entry_. If
| -validate is not supplied, the default is to validate using
| the hcom_site_validate_ subroutine, if your site has provided
| such a routine, or hcom_default_validate_ subroutine provided
| with the history_comment command.
|
| -errors, -er
| displays history comments that failed check. This is the
| command default.
|
| -no_errors, -ner
| suppresses display of history comments that failed check.
| This is the active function default.
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
Operation: compare, cmp |
|
|
SYNTAX AS A COMMAND: |
|
hcom cmp path -control_args |
|
|
SYNTAX AS AN ACTIVE FUNCTION: |
|
[hcom cmp path -control_args] |
|
|
FUNCTION: displays the differences, if any, between the source |
module and the original module. The active function returns true |
if the comments in the source and original modules are identical |
and false otherwise. |
|
|
ARGUMENTS: |
|
path |
is the name of a source code program that has history |
comments. The language suffix must be included. An archive |
pathname may be given. |
|
|
CONTROL ARGUMENTS: |
|
-original orig_path, -orig orig_path |
specifies the path name of an earlier version of the module. |
An archive pathname may be given. The equal convention is |
allowed. This control argument is required. |
|
-validate RTN, -vdt RTN |
validates user-supplied fields in the history comment, using a |
user-supplied validation routine. RTN must be a virtual |
entrypoint name acceptable to subroutine cv_entry_. If |
-validate is not supplied, the default is to validate using |
the hcom_site_validate_ subroutine, if your site has provided |
such a routine, or hcom_default_validate_ subroutine provided |
with the history_comment command. |
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| Operation: display, ds
|
|
| SYNTAX AS A COMMAND:
|
| hcom ds path {comment_specs} {-control_args}
|
|
| FUNCTION: displays selected history comments. Optionally,
| compares history comments in a program with those in an earlier
| version of the program, displaying old comments (which appear in
| both versions) or new comments (which do not appear in the
| earlier version).
|
|
| ARGUMENTS:
|
| path
| is the name of a source code program. The language suffix
| must be included. An archive pathname may be given.
|
| comment_specs
| select which history comment(s) to display. The default is to
| display new comments if -original is given, or all comments if
| -original is omitted. See "List of Comment Specifiers" below.
|
|
| CONTROL ARGUMENTS:
|
| -original orig_path, -orig orig_path
| specifies the path name of an earlier version of the module.
| An archive pathname may be given. The equal convention is
| allowed.
|
| -validate RTN, -vdt RTN
| validates user-supplied fields in the history comment, using a
| user-supplied validation routine. RTN must be a virtual
| entrypoint name acceptable to subroutine cv_entry_. If
| -validate is not supplied, the default is to validate using
| the hcom_site_validate_ subroutine, if your site has provided
| such a routine, or hcom_default_validate_ subroutine provided
| with the history_comment command.
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
LIST OF COMMENT SPECIFIERS: |
|
I, I:J |
selects the comment(s) by a comment number or a range of |
numbers. The keywords "first" or "f" and "last" or "l" may be |
given to identify the first and last comments. |
|
all, a |
selects all comments. |
|
complete, cpt |
selects comments which include all fields. |
|
incomplete, icpt |
selects comments which are missing the approve, audit or |
install field. |
|
approved, apv |
selects comments which have an approve field. |
|
unapproved, unapv |
selects comments which do not have an approve field. |
|
audited, aud |
selects comments which have an audit field. |
|
unaudited, unaud |
selects comments which do not have an audit field. |
|
installed, in |
selects comments which have an install field. |
|
uninstalled, unin |
selects comments which do not have an install field. |
|
new |
when -original is given, selects comments which do not appear |
in the original (earlier) version of the program. |
|
old |
when -original is given, selects comments which appear in both |
the original and new versions of the program. |
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| Operation: exists
|
|
| SYNTAX AS A COMMAND:
|
| hcom exists path {comment_specs} {-control_args}
|
|
| SYNTAX AS AN ACTIVE FUNCTION:
|
| [hcom exists path {comment_specs} {-control_args}
|
|
| FUNCTION: prints or returns true if any history comments
| matching all the comment_specs are found in every selected
| module; prints or returns false otherwise.
|
|
| ARGUMENTS:
|
| path
| is the name of the source code program that requires comments.
| The language suffix must be included. An archive pathname may
| be given.
|
| comment_specs
| select which history comment(s) to display. The default is
| "all", to check whether any comments exist in the source
| module. See "List of comment_spec values" below.
|
|
| CONTROL ARGUMENTS:
|
| -original orig_path, -orig orig_path
| specifies the path name of an earlier version of the module.
| An archive pathname may be given. The equal convention is
| allowed.
|
| -validate RTN, -vdt RTN
| validates user-supplied fields in the history comment, using a
| user-supplied validation routine. RTN must be a virtual
| entrypoint name acceptable to subroutine cv_entry_. If
| -validate is not supplied, the default is to validate using
| the hcom_site_validate_ subroutine, if your site has provided
| such a routine, or hcom_default_validate_ subroutine provided
| with the history_comment command.
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
LIST OF COMMENT SPECIFIERS: |
|
I, I:J |
selects the comment(s) by a comment number or a range of |
numbers. The keywords "first" or "f" and "last" or "l" may be |
given to identify the first and last comments. |
|
all, a |
selects all comments. |
|
complete, cpt |
selects comments which include all fields. |
|
incomplete, icpt |
selects comments which are missing the approve, audit or |
install field. |
|
approved, apv |
selects comments which have an approve field. |
|
unapproved, unapv |
selects comments which do not have an approve field. |
|
audited, aud |
selects comments which have an audit field. |
|
unaudited, unaud |
selects comments which do not have an audit field. |
|
installed, in |
selects comments which have an install field. |
|
uninstalled, unin |
selects comments which do not have an install field. |
|
new |
when -original is given, selects comments which do not appear |
in the original (earlier) version of the program. |
|
old |
when -original is given, selects comments which appear in both |
the original and new versions of the program. |
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| Operation: format, fmt
|
|
| SYNTAX AS A COMMAND:
|
| hcom fmt path {-control_args}
|
|
| FUNCTION: reformats all history comments in a program, including
| putting date fields into standard "yy-mm-dd" format, filling
| lines of all comment entries to 75 character width, validating
| field values, etc.
|
| Note: The date must be a single token that is acceptable
| to convert_date_to_binary_.
|
|
| ARGUMENTS:
|
| path
| is the name of the source code program who history comments
| are to be reformatted. The language suffix must be included.
| Archive pathnames are not allowed. An archive pathname may be
| given.
|
|
| CONTROL ARGUMENTS:
|
| -validate RTN, -vdt RTN
| validates user-supplied fields in the history comment, using a
| user-supplied validation routine. RTN must be a virtual
| entrypoint name acceptable to subroutine cv_entry_. If
| -validate is not supplied, the default is to validate using
| the hcom_site_validate_ subroutine, if your site has provided
| such a routine, or hcom_default_validate_ subroutine provided
| with the history_comment command.
|
| -renumber, -rnb
| specifies that the history comments within the current module
| can be renumbered if they are out of sequence.
|
| -no_renumber, -nrnb
| prints an error if history comment numbers are out of
| sequence. This is the default.
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
Operation: get |
|
|
SYNTAX AS AN ACTIVE FUNCTION: |
|
[hcom get path comment_specs -control_args] |
|
|
SYNTAX AS A COMMAND: |
|
hcom get path comment_specs -control_args |
|
|
FUNCTION: returns or prints given field values from selected |
history comments. |
|
|
ARGUMENTS: |
|
path |
is the name of the source code program whose history comment |
fields are to be returned. The language suffix must be |
included. An archive pathname may be given. |
|
comment_specs |
specify from which history comment(s) field values are |
extracted. At least one specifier must be given. See "List |
of Comment Specifiers" below. |
|
|
CONTROL ARGUMENTS: |
|
-original orig_path, -orig orig_path |
specifies the path name of an earlier version of the module. |
An archive pathname may be given. The equal convention is |
allowed. |
|
-field_name FIELDS, -fn FIELDS |
specify which fields from the selected history comments are to |
be returned or printed. All arguments following -fn up to the |
first argument which begins with a hyphen are considered field |
names. See "List of field names" below for a list of fields |
which can be selected. The default is to return or print all |
fields of matching entries. |
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| -validate RTN, -vdt RTN
| validates user-supplied fields in the history comment, using a
| user-supplied validation routine. RTN must be a virtual
| entrypoint name acceptable to subroutine cv_entry_. If
| -validate is not supplied, the default is to validate using
| the hcom_site_validate_ subroutine, if your site has provided
| such a routine, or hcom_default_validate_ subroutine provided
| with the history_comment command.
|
|
| LIST OF FIELD NAMES:
|
| The following values may be given with the -field_name control
| argument to specify which field to return.
|
| change_date, cdt
| date on which the history comment was first entered.
|
| change_person_id, cpi
| person_id of the person who entered the history comment.
|
| approve_date, apvdt
| date on which the approve field was entered.
|
| approve_id, apvi
| identifier from the approve field.
|
| audit_date, auddt
| date on which the audit field was entered.
|
| audit_person_id, audpi
| person_id of the person who audited the source module.
|
| install_date, indt
| date on which the install field was entered.
|
| install_id, ini
| identifier from the install field.
|
| summary, sm
| summary field from the history comment.
|
|
| LIST OF COMMENT SPECIFIERS:
|
| I, I:J
| selects the comment(s) by a comment number or a range of
| numbers. The keywords "first" or "f" and "last" or "l" may be
| given to identify the first and last comments.
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
all, a |
selects all comments. |
|
complete, cpt |
selects comments which include all fields. |
|
incomplete, icpt |
selects comments which are missing the approve, audit or |
install field. |
|
approved, apv |
selects comments which have an approve field. |
|
unapproved, unapv |
selects comments which do not have an approve field. |
|
audited, aud |
selects comments which have an audit field. |
|
unaudited, unaud |
selects comments which do not have an audit field. |
|
installed, in |
selects comments which have an install field. |
|
uninstalled, unin |
selects comments which do not have an install field. |
|
new |
when -original is given, selects comments which do not appear |
in the original (earlier) version of the program. |
|
old |
when -original is given, selects comments which appear in both |
the original and new versions of the program. |
|
|
NOTES: |
|
If several history comments are selected, specified fields from |
the first selected comment are returned or printed, followed by |
fields from the second selected comment, etc. If the selected |
field is not present in a given history comment, then a null |
string is returned for that field. Multiline field values are |
returned in a single line (with newline characters replaced by a |
space) as a quoted string. |
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| Operation: install
|
|
| SYNTAX AS A COMMAND:
|
| hcom install path -control_args
|
|
| SYNTAX AS AN ACTIVE FUNCTION:
|
| [hcom install path -control_args]
|
|
| FUNCTION: system integration personnel use the install operation
| to perform a preinstallation check on modules being installed.
| It performs a variety of steps, including checking that new
| history comments exist and are properly filled in. If the check
| succeeds, an installation id is placed in the comment. The
| active function returns true if the check succeeds (the history
| comments are ready for installation), and false otherwise.
|
|
| ARGUMENTS:
|
| path
| is the name of a source code program that requires history
| comments. The language suffix must be included. An archive
| pathname may be given.
|
|
| CONTROL ARGUMENTS FOR FIELD INPUT:
|
| -approve APPROVE_ID, -apv APPROVE_ID
| specifies the APPROVE_ID field to be assigned to all history
| comments which are missing an approve field. An error occurs
| if this argument is given but no comments are missing the
| approve field. See "List of history comment fields" above for
| a description of valid APPROVE_IDs. This control argument is
| used when only the installer knows what the approval
| identifier is (eg, only he knows what the Multics Emergency
| Change Request (MECR) number is, because this number is
| assigned at installation time). The maximum length of this
| field is 24 characters. If the AUDIT_DATE AND AUDIT_PERSON_ID
| fields are missing when the -apv argument is given, an error
| message is issued but processing continues.
|
| -input_approve, -iapv
| prompts for an APPROVE_ID. This is a single line field value.
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
-no_approve, -napv |
specifies that an APPROVE_ID is not being entered. This is |
the default. |
|
-install INSTALL_ID, -in INSTALL_ID |
specifies an identifier associated with installing the changed |
module into execution libraries. This identifier is placed in |
the all history comments which are missing the install field. |
An error occurs if every comment has an install field. See |
"List of history comment fields" above for a description of |
valid INSTALL_IDs. The maximum length of this field is 24 |
characters. |
|
-input_install, -iin |
prompts for the installation identifier. This is the default. |
|
-no_install, -nin |
specifies that no installation identifier is being given. |
|
|
CONTROL ARGUMENTS: |
|
-original orig_path, -orig orig_path |
specifies the path name of an earlier module copy which is |
already installed in the software library. This library copy |
is compared with the version being submitted, as described in |
the notes below. An archive pathname may be given. The equal |
convention is allowed. ...kx -errors, -er displays history |
comments that fail the installation checks. This is the |
command default. |
|
-no_errors, -ner |
suppresses display of failing history comments. This is the |
active function default. |
|
-critical_fix, -cfix |
specifies that critical fix history comments are allowed in |
the program. All comments following the first which contains |
critical fix field values must also be critical fix history |
comments. |
|
-validate RTN, -vdt RTN |
validates user-supplied fields in the history comment, using a |
user-supplied validation routine. RTN must be a virtual |
entrypoint name acceptable to subroutine cv_entry_. If |
-validate is not supplied, the default is to validate using |
the hcom_site_validate_ subroutine, if your site has provided |
such a routine, or hcom_default_validate_ subroutine provided |
with the history_comment command. |
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| NOTES:
|
| The install operation performs the following steps:
|
| 1) Make a working copy of history comments in the new module.
| 2) If -original is given, check comments in the original module
| against those in the working copy:
| a) check for comments in the original which do not appear in
| the working copy. This indicates changes which have been
| backed out. If any are found, print an error and stop
| further checking.
| b) copy the install identifier from comments in the original
| module into corresponding comments in the working copy
| which are missing this identifier. This can occur when the
| developer makes changes to a modified version of the
| program before that modified version is installed in the
| libraries.
| 3) If -approve or -input_approve is given, check for comments in
| the working copy which are missing the approve field. If none
| are found, report an error and stop further checking. If the
| AUDIT_DATE and AUDIT_PERSON_ID fields are missing an error
| message is issued but processing continues.
| 4) If -install or -input_install is given, check for comments in
| the working copy which are missing the install field. If none
| are found, report an error and stop further checking. This
| indicates that the developer forgot to add a history comment
| when he modified the module.
| 5) Check for completeness of summary, and audit fields in all
| history comments. If the AUDIT_DATE and AUDIT_PERSON_ID
| fields are missing, an error message is issued but processing
| continues. If incomplete or erroneous entries are found,
| report an error and stop further checking.
| 6) If -approve or -input_approve is given, place the approve
| identifier in the working copy's new history comments. If
| -install or -input_install is given, place the installation
| identifier into the working copy's new history comments.
| 7) Reformat the new history comments in the working copy.
| 8) If no error occurred, replace history comments in the new
| module with the working comments built by the install
| operation.
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
Operation: replace_field, rpf |
|
|
SYNTAX AS A COMMAND: |
|
hcom rpf path comment_specs -control_args |
|
|
FUNCTION: replaces existing comment fields in selected history |
comments. |
|
|
ARGUMENTS: |
|
path |
is the name of a source code program that requires history |
comments. The language suffix must be included. An archive |
pathname may be given. |
|
comment_specs |
specify which history comment(s) are to be updated. See "List |
of Comment Specifiers" below. |
|
|
CONTROL ARGUMENTS FOR FIELD INPUT: |
|
At least one of the following control arguments must be given: |
|
-summary -input_summary |
-approve -input_approve |
-install -input_install |
-audit |
|
-summary TEXT, -sm TEXT |
replaces the text describing the change. If the text contains |
spaces, quotes, parentheses, etc, the TEXT must be enclosed |
within quotes. |
|
-input_summary, -ism |
prompts the user for a new summary field. This is a multiline |
field. |
|
-no_summary, -nsm |
does not replace the summary field. This is the default. |
|
-approve APPROVE_ID, -apv APPROVE_ID |
replaces the APPROVE_ID field. The maximum length of this |
field is 24 characters. See "List of history comment fields" |
above for a description of valid APPROVE_IDs. |
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
| -input_approve, -iapv
| prompts for a new APPROVE_ID. This is a single line field
| value.
|
| -no_approve, -napv
| does not replace the APPROVE_ID field, or prompt for missing
| approve fields. This is the default.
|
| -audit, -aud
| puts the users person_id in the AUDIT_PERSON_ID field.
|
| -no_audit, -naud
| does not add the AUDIT_PERSON_ID field. This is the default.
|
| -install INSTALL_ID, -in INSTALL_ID
| specifies an identifier associated with installing the changed
| module into execution libraries. See "List of history comment
| fields" above for a description of valid INSTALL_IDs. The
| maximum length of this field is 24 characters.
|
| -input_install, -iin
| prompts for the INSTALL_ID. This is a single line field.
|
| -no_install, -nin
| does not set the INSTALL_ID field or prompt for missing
| install fields. This is the default.
|
|
| CONTROL ARGUMENTS:
|
| -original orig_path, -orig orig_path
| specifies the path name of an earlier version of the module.
| An archive pathname may be given. The equal convention is
| allowed.
|
| -critical_fix, -cfix
| specifies that critical fix history comments are allowed in
| the program. All comments following the first which contains
| critical fix field values must also be critical fix history
| comments.
|
| -validate RTN, -vdt RTN
| validates user-supplied fields in the history comment, using a
| user-supplied validation routine. RTN must be a virtual
| entrypoint name acceptable to subroutine cv_entry_. If
| -validate is not supplied, the default is to validate using
| the hcom_site_validate_ subroutine, if your site has provided
| such a routine, or hcom_default_validate_ subroutine provided
| with the history_comment command.
______________________ ______________________
history_comment (hcom) history_comment (hcom)
______________________ ______________________
LIST OF COMMENT SPECIFIERS: |
|
I, I:J |
selects the comment(s) by a comment number or a range of |
numbers. The keywords "first" or "f" and "last" or "l" may be |
given to identify the first and last comments. |
|
all, a |
selects all comments. |
|
complete, cpt |
selects comments which include all fields. |
|
incomplete, icpt |
selects comments which are missing the approve, audit or |
install field. |
|
approved, apv |
selects comments which have an approve field. |
|
unapproved, unapv |
selects comments which do not have an approve field. |
|
audited, aud |
selects comments which have an audit field. |
|
unaudited, unaud |
selects comments which do not have an audit field. |
|
installed, in |
selects comments which have an install field. |
|
uninstalled, unin |
selects comments which do not have an install field. |
|
new |
when -original is given, selects comments which do not appear |
in the original (earlier) version of the program. |
|
old |
when -original is given, selects comments which appear in both |
the original and new versions of the program. |