:Info: history_comment: hcom: 03/10/88 history_comment, hcom Syntax as an active function: [hcom operation path {args} {-control_args}] Syntax as a command: 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. 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 */ Notes: To determine if prior history comments exist in the module, the source module is checked for a line containing the history comment block beginning; i.e., a line beginning with the appropriate comment delimiter, containing the word "HISTORY", and containing the word "COMMENTS:". If this is found, the program then checks for the history comment block ending; i.e., a line containing "END HISTORY COMMENTS". 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) 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: 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 validtion 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] Validation routine: 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-written routine, the name hcom_site_validate_ would be replaced with whatever name the user chooses for the routine. Syntax of validation routine: dcl validation_rtn_ entry (char(*) var, char(*) var, char(*) var, bit(1), char(*) var, char(*) var); call validation_rtn_ (caller, field_name, input_value, result_bit, canonical_value, field_type); Arguments for validation routine: 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 canonical text form of the field_name for use in error messages. (Output) List of Related Info Segments: Additional information may be obtained on the history comment operations by referring to the following info segments: history_comment.add.info (hcom.add.info) history_comment.add_field.info (hcom.af.info) history_comment.check.info (hcom.ck.info) history_comment.compare.info (hcom.cmp.info) history_comment.display.info (hcom.ds.info) history_comment.exists.info (hcom.exists.info) history_comment.format.info (hcom.fmt.info) history_comment.get.info (hcom.get.info) history_comment.install.info (hcom.install.info) history_comment.replace_field.info (hcom.rpf.info) :Info: history_comment.add: hcom.add: 03/10/88 hcom add operation 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. -fill, -fi Set fill mode on for the summary field. In fill mode text words are moved from line to line in such a way that the last word does not extend past the right margin. This is the default. -nofill, -nfi Set the fill mode off for the summary field. -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 ov 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 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 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.w -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. :Info: history_comment.add_field: history_comment.af: hcom.add_field: hcom.af: 03/10/88 hcom add_field operation 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: -validate RTN, -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint 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. 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. -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. 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. Notes: If no control args are given, the default is to print selected history comments and prompt the user for missing approve fields. :Info: history_comment.check: history_comment.ck: hcom.check: hcom.ck: 03/10/88 hcom check operation Syntax as an active function: [hcom ck path {-control_args}] Syntax as a command: 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. -validate RTN, -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint 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. :Info: history_comment.compare: history_comment.cmp: hcom.compare: hcom.cmp: 03/10/88 hcom compare operation Syntax as an active function: [hcom cmp path -control_args] Syntax as a command: 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 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. :Info: history_comment.display: history_comment.ds: hcom.display: hcom.ds: 03/10/88 hcom display operation 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 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 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. :Info: history_comment.exists: hcom.exists: 03/10/88 exists operation Syntax as an active function: [hcom exists path {comment_specs} {-control_args} Syntax as a command: 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. This argument is used in conjunction with the comment specifiers old or new. -validate RTN, -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint 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 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. :Info: history_comment.format: history_comment.fmt: hcom.format: hcom.fmt: 03/10/88 hcom format operation Syntax as a command: hcom fmt path {comment_specs} {-control_args} Function: reformats selected history comments in a program, including putting date fields into standard "yy-mm-dd" format, filling lines of all comment entries to 79 character width, validating field values, etc. The default value will be to format "all" comments. Notes: 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. 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: -validate RTN, -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint 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. -fill, -fi Set fill mode on for the summary field. In fill mode text words are moved from line to line in such a way that the last word does not extend past the right margin. This is the default. -nofill, -nfi Set the fill mode off for the summary field. -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. 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. :Info: history_comment.get: hcom.get: 03/10/88 hcom get operation 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. This argument is used in conjunction with the comment specifiers old or new. -field_name FIELDS, -fn FIELDS specify which fields from the selected history comments are to be returned or printed. All arguments following -fn that do not begin 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. -validate RTN, -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint 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. 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. :Info: history_comment.install: hcom.install: 03/10/88 hcom install operation Syntax as an active function: [hcom install path -control_args] Syntax as a command: 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: -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. -validate RTN, -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint 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 fail the installation checks. This is the command default. -no_errors, -ner suppresses display of failing history comments. This is the active function default. 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. -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. 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. :Info: history_comment.replace_field:history_comment.rpf:hcom.replace_field:hcom.rpf: 03/10/88 hcom replace_field operation 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: -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 argument is used in conjunction with the comment specifiers old or new. -validate RTN, -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint 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.w -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. 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 -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. -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. -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. -fill, -fi Set fill mode on for the summary field. In fill mode text words are moved from line to line in such a way that the last word does not extend past the right margin. This is the default. -nofill, -nfi Set the fill mode off for the summary field. -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. 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. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved