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.                  |