1 :Info: history_comment: hcom: 1988-03-10 history_comment, hcom
2
3 Syntax as an active function:
4 hcom OPERATION PATH args -control_args
5
6
7 Syntax as a command: hcom OPERATION PATH ARGS -control_args
8
9
10 Function: adds, checks, displays, formats and updates software change
11 history comments within a given source module.
12
13
14 Arguments:
15 OPERATION
16 designates the operation to be performed. See "List of operations"
17 below.
18 PATH
19 is the name of a source code program that requires history comments.
20 The language suffix must be included.
21 ARGS
22 are optional arguments appropriate to the particular operation being
23 performed.
24
25
26 List of operations:
27 Information about each history comment operation may be obtained
28 by typing: help hcom.OPERATION
29 add
30 adds a new history comment to a source program.
31 add_field, af
32 add missing fields to an existing history comment.
33 replace_field, rpf
34 replaces fields in an existing history comment.
35 display, ds
36 displays one or more history comments in a source program.
37 format, fmt
38 reformats history comments in a source program, placing them in
39 standard form.
40
41
42 check, ck
43 checks history comments in a source program prior to its submission
44 for installation to ensure that all fields except the INSTALL_ID are
45 present.
46 compare, cmp
47 displays the differences, if any, between the source and original
48 modules.
49 exists
50 checks to see if a history comment with certain attributes exists.
51 get
52 gets one or more field values from selected history comments.
53 install
54 checks history comments in a source program prior to its
55 installation for completeness, and updates the INSTALL_ID field.
56
57
58 Control arguments:
59 -control_args
60 are optional control arguments which vary with the operation being
61 performed. Allowed values are described by the help file for each
62 operation. Type: help hcom.OPERATION
63
64
65 Notes on history comment format:
66 Following is a pl1 history comment example. Other languages will
67 have the comment delimiters appropriate for their respective
68 language.
69
70 /****^ HISTORY COMMENTS:
71 1) change1985-05-12 HSmith, approve1985-05-25 MCR2355,
72 audit1985-05-26 Jones, install1985-05-30 MR11.0-3382:
73 Increased size of test_array to eliminate subscript error.
74 2) change1985-05-28 HSmith, approve1985-05-29 MCR2356,
75 audit1985-06-05 Rogers, install1985-06-10 MR11.0-3384:
76 Added the -brief and -long control arguments.
77 END HISTORY COMMENTS */
78
79
80 To determine if prior history comments exist in the module, the
81 source module is checked for a line containing the history comment
82 block beginning; i.e., a line beginning with the appropriate comment
83 delimiter, containing the words "HISTORY COMMENTS:". If this is
84 found, the program then checks for the history comment block ending;
85 i.e., a line containing "END HISTORY COMMENTS".
86
87
88 List of history comment fields:
89 The fields within a given history comment are identified as follows:
90
91 NO) change CHANGE_DATE CHANGE_PERSON_ID,
92 approve APPROVE_DATE APPROVE_ID,
93 audit AUDIT_DATE AUDITOR_PERSON_ID,
94 install INSTALL_DATE INSTALL_ID: SUMMARY
95
96 The fields in a history comment are named as described below. The
97 sample validation routine, hcom_default_validate_, validates field
98 formats used by the Multics Development Center as described below.
99 However, each site may provide its own validation routines to
100 tailor the contents of the user-settable field values.
101
102
103 NO
104 is the number of the history comment. Comments are numbered
105 sequentially in chronological order, starting with 1. supplied
106 by hcom
107 CHANGE_DATE
108 date yyyy-mm-dd on which history comment was first added to
109 the source module. supplied by hcom
110 CHANGE_PERSON_ID
111 person_id of the person who added the history comment. supplied
112 by hcom
113 APPROVE_DATE
114 date yyyy-mm-dd on which an approval value was supplied
115 for a history comment. supplied by hcom
116
117
118 APPROVE_ID
119 identifier authorizing the change. The default validation routine
120 expects an identifier in the form "TYPEnnnn" for MCRs Multics
121 Change Request, PBFs Post-installation Bug Fix associated with
122 MCRnnnn or MECRs Multics Emergency Change Request; i.e.,
123 MCR6734, PBF6734, MECR0102. For critical fixes the identifier
124 should be in the form of fix_nnnn or fix_nnnn.ds. The maximum
125 length of this field is 24 characters. supplied by user
126 AUDIT_DATE
127 date yyyy-mm-dd audit field added to history comment.
128 supplied by hcom
129 AUDIT_PERSON_ID
130 person_id of the person who audited the source module. supplied
131 by hcom
132
133
134 INSTALL_DATE
135 date yyyy-mm-dd install field added to history comment.
136 supplied by hcom
137 INSTALL_ID
138 value identifying either a specific installation or the installer
139 of a critical fix. The default validation routine expects an
140 identifier in the form "MRrel-nnnnn", consisting of a release
141 number and installation sequence counter, e.g., MR12.0-00234. For
142 a critical fix, the validation routine expects a person-id naming
143 the person who installed the fix. The maximum length of this
144 field is 24 characters. supplied by user
145 SUMMARY
146 brief description of the change made to the module. This field
147 contains text up to 2000 characters and is not validated.
148 supplied by user
149
150
151 Notes: The following is a typical usage pattern expected for the
152 various operations of the history_comment command.
153
154 o The developer makes a change to the source module. He could add a
155 new history comment by hand perhaps using an Emacs extension to
156 prompt for field values. Or after adding the change, he could
157 use the history_comment add operation to add a new comment. A
158 typical command line might be:
159
160 hcom add prog.pl1
161
162
163 o The developer may not have had approval for the change at the time
164 the history comment was added. When approval is gained, he can
165 use the history_comment add_field operation to add the approve
166 field. For example:
167
168 hcom af prog.pl1 -approve MCR7235
169
170
171 o The developer can display the history comments in a program, or
172 even compare the comments in a modified version of a program with
173 those in the library copy of the program. For example:
174
175 hcom display prog.pl1 new -orig lpn prog.pl1
176
177 would display the new history comments in the source module, while
178
179 hcom compare prog.pl1 -orig lpn prog.pl1
180
181 would display the differences between the source module and the
182 original module.
183
184
185 o When the change is audited, the auditor uses the history_comment
186 add_field operation to supply an audit field for all new or
187 incomplete history comments. For example:
188
189 hcom af prog.pl1 -audit
190
191 o When the developer is ready to submit the change for installation,
192 he uses the history_comment check operation to ensure that all
193 comment fields except the install field have been supplied in each
194 changed module. Since the developer has a site-defined
195 validation routine called hcom_site_validate_ in his object
196 search rules, this routine is used to fully validate the fields
197 of all comments.
198
199 hcom check prog.pl1 -orig lpn prog.pl1
200
201
202 o When the installer receives the modules in an installation, he
203 uses the history_comment install operation to ensure that new
204 history comments describing the changes are present. The install
205 operation also adds an identifier to each new comment, indicating
206 in which installation it was installed. The installer can use a
207 special library-defined validtion routine to perform special
208 field validations. In the example below, this library validation
209 routine is called hcom_mdc_validate_.
210
211 hcom install prog.pl1 -vdt hcom_mdc_validate_ -install
212 MR12.0-0023 -orig lpn prog.pl1
213
214
215 Notes on the validation routine:
216 A site can define a site-wide history comment validation routine to
217 validate the contents of the APPROVE_ID and INSTALL_ID fields of
218 history comments. This routine is called hcom_site_validate_. If it
219 is found in the user's object search rules, the history_comment
220 command will automatically use this validation routine instead of
221 using hcom_default_validate_. Also, the -validate control argument
222 allows use of a user-supplied validation subroutine to validate the
223 APPROVE_ID and INSTALL_ID fields. This user routine can have any
224 name.
225
226 For information about the calling sequence of the validation routine,
227 type: help hcom_validation_rtn_
228
229
230 :Info: hcom.add: 2021-11-13 hcom add operation
231
232
233 Syntax as a command: hcom add PATH -control_args
234
235
236 Function: adds a new history comment to the requested module. The
237 summary field is required, all other history comment fields are
238 optional.
239
240
241 Arguments:
242 add
243 the operation to be performed.
244 PATH
245 is the name of a source code program that requires history comments.
246 The language suffix must be included. An archive pathname may be
247 given.
248
249
250 Control arguments for field input:
251 -summary TEXT, -sm TEXT
252 gives text describing the change. If the text contains spaces,
253 quotes, parentheses, etc, the TEXT must be enclosed within quotes.
254 -input_summary, -ism
255 prompts the user for the summary field. This is a multiline field.
256 See "Notes" below. This is the default.
257 -fill, -fi
258 Set fill mode on for the summary field. In fill mode text words
259 are moved from line to line in such a way that the last word does
260 not extend past the right margin. This is the default.
261 -nofill, -nfi
262 Set the fill mode off for the summary field.
263
264
265 -approve APPROVE_ID, -apv APPROVE_ID
266 specifies the APPROVE_ID field. The maximum length of this field is
267 24 characters. See "List of history comment fields" above for a
268 description of valid APPROVE_IDs.
269 -input_approve, -iapv
270 prompts for an APPROVE_ID. This is the default. This is a single
271 line field value.
272 -no_approve, -napv
273 specifies that an APPROVE_ID is not being entered.
274
275
276 -install INSTALL_ID, -in INSTALL_ID
277 specifies an identifier associated with installing the changed
278 module into execution libraries. See "list of history comment
279 fields" above for a description ov valid INSTALL_IDs. The maximum
280 length of this field is 24 characters.
281 -input_install, -iin
282 prompts for the INSTALL_ID. This is a single line field.
283 -no_install, -nin
284 Suppresses the prompt for INSTALL_ID. This is the default, since
285 the installation ID is usually specified when the module is being
286 installed rather than when the history comment is first added.
287
288
289 Control arguments:
290 -validate RTN, -vdt RTN
291 validates user-supplied fields in the history comment, using a
292 user-supplied validation routine. RTN must be a virtual entrypoint
293 acceptable to subroutine cv_entry_. If -validate is not supplied,
294 the default is to validate using the hcom_site_validate_
295 subroutine, if your site has provided such a routine, or
296 hcom_default_validate_subroutine provided with the history_comment
297 command.w
298 -critical_fix, -cfix
299 specifies that critical fix history comments are allowed in the
300 program. All comments following the first, which contains critical
301 fix field values, must also contain critical fix field values.
302
303
304 Notes: For multiline fields, all input is treated as text until
305 reading a line with just a period .. Input lines beginning with ".."
306 are treated as Multics command lines, rather than as part of the field
307 value. After the command line is executed, the user may continue
308 answering the prompt, or may replace input text typed so far with a new
309 answer. Optional field values answered with just a period cause the
310 field to be omitted from the history comment.
311
312 For single line fields, input ends when a carriage return is typed. If
313 the input line begins with "..", the text which follows is treated as a
314 Multics command line. After the command line is executed, the user is
315 prompted again for the question. Optional field values answered with
316 just a carriage return cause the field to be omitted from the history
317 comment.
318
319
320 :Info: hcom.add_field: hcom.af: 1988-03-10 hcom add_field operation
321
322 Syntax as a command: hcom af PATH COMMENT_SPECS -control_args
323
324
325 Function: inserts missing fields in selected comments.
326
327
328 Arguments:
329 add_field, af
330 the operation to be performed.
331 PATH
332 is the name of a source code program that requires history comments.
333 The language suffix must be included. An archive pathname may be
334 given.
335 COMMENT_SPECS
336 specify which history comments are to be updated. See "List of
337 Comment Specifiers" below. The default is to select comments which
338 are missing the fields given by the "Control Arguments for Field
339 Input" below.
340
341
342 Control arguments:
343 -validate RTN, -vdt RTN
344 validates user-supplied fields in the history comment, using a
345 user-supplied validation routine. RTN must be a virtual entrypoint
346 acceptable to subroutine cv_entry_. If -validate is not supplied,
347 the default is to validate using the hcom_site_validate_
348 subroutine, if your site has provided such a routine, or
349 hcom_default_validate_subroutine provided with the history_comment
350 command.
351 -critical_fix, -cfix
352 specifies that critical fix history comments are allowed in the
353 program. All comments following the first, which contains critical
354 fix field values, must also contain critical fix field values.
355
356
357 Control arguments for field input:
358 -approve APPROVE_ID, -apv APPROVE_ID
359 inserts the missing APPROVE_ID field. The maximum length of this
360 field is 24 characters. See "List of history comment fields" above
361 for a description of valid APPROVE_IDs.
362 -input_approve, -iapv
363 prompts for a new APPROVE_ID. This is a single line field value.
364 This is the default if no field input control arguments are given.
365 -no_approve, -napv
366 does not replace the APPROVE_ID field, or prompt for missing approve
367 fields. This is the default if any field input control arguments
368 are given.
369 -audit, -aud
370 inserts the users person_id in the AUDIT_PERSON_ID field.
371
372
373 -no_audit, -naud
374 does not add the AUDIT_PERSON_ID field. This is the default.
375 -install INSTALL_ID, -in INSTALL_ID
376 specifies an identifier associated with installing the changed
377 module into execution libraries. See "List of history comment
378 fields" above for a description of valid INSTALL_IDs. The
379 maximum length of this field is 24 characters.
380 -input_install, -iin
381 prompts for the INSTALL_ID. This is a single line field.
382 -no_install, -nin
383 does not set the INSTALL_ID field or prompt for missing install
384 fields. This is the default.
385
386
387 List of comment specifiers:
388 I, I:J
389 selects the comments by a comment number or a range of numbers.
390 The keywords "first" or "f" and "last" or "l" may be given to
391 identify the first and last comments.
392 all, a
393 selects all comments.
394 complete, cpt
395 selects comments which include all fields.
396 incomplete, icpt
397 selects comments which are missing the approve, audit or install
398 field.
399 approved, apv
400 selects comments which have an approve field.
401
402
403 unapproved, unapv
404 selects comments which do not have an approve field.
405 audited, aud
406 selects comments which have an audit field.
407 unaudited, unaud
408 selects comments which do not have an audit field.
409 installed, in
410 selects comments which have an install field.
411 uninstalled, unin
412 selects comments which do not have an install field.
413
414
415 new
416 when -original is given, selects comments which do not appear in the
417 original earlier version of the program.
418 old
419 when -original is given, selects comments which appear in both the
420 original and new versions of the program.
421
422
423 Notes: If no control args are given, the default is to print selected
424 history comments and prompt the user for missing approve fields.
425
426
427 :Info: hcom.check: hcom.ck: 1988-03-10 hcom check operation
428
429 Syntax as an active function: hcom ck PATH -control_args
430
431
432 Syntax as a command: hcom ck PATH -control_args
433
434
435 Function: presubmission check run by developers to ensure that at
436 least one history comment has been added to describe modifications to
437 the source module. These history comments will be incomplete, because
438 they will not have an install field. But all other fields should be
439 supplied prior to submission.
440
441 The presubmission check looks for one or more incomplete or new if
442 -original is given history comments, and verifies that their summary,
443 approve, and audit fields are given while the install field is missing.
444 The active function returns true if the check succeeds the history
445 comments are ready for submission, and false otherwise.
446
447
448 Arguments:
449 check, ck
450 the operation to be performed.
451 PATH
452 is the name of a source code program that has history comments. The
453 language suffix must be included. An archive pathname may be given.
454
455
456 Control arguments:
457 -original orig_path, -orig orig_path
458 specifies that the current version of the source program is to be
459 cross checked with an earlier version given as orig_path to ensure
460 that there are new history comments in the current module. An
461 archive pathname may be given. The equal convention is allowed.
462 The default is to check for incomplete history comments in the given
463 source program.
464
465
466 -validate RTN, -vdt RTN
467 validates user-supplied fields in the history comment, using a
468 user-supplied validation routine. RTN must be a virtual entrypoint
469 acceptable to subroutine cv_entry_. If -validate is not supplied,
470 the default is to validate using the hcom_site_validate_
471 subroutine, if your site has provided such a routine, or
472 hcom_default_validate_subroutine provided with the history_comment
473 command.
474
475
476 :Info: hcom.compare: hcom.cmp: 1988-03-10 hcom compare operation
477
478 Syntax as an active function: hcom cmp PATH -control_args
479
480
481 Syntax as a command: hcom cmp PATH -control_args
482
483
484 Function: displays the differences, if any, between the source module
485 and the original module. The active function returns true if the
486 comments in the source and original modules are identical and false
487 otherwise.
488
489
490 Arguments:
491 compare, cmp
492 the operation to be performed.
493 PATH
494 is the name of a source code program that has history comments. The
495 language suffix must be included. An archive pathname may be given.
496
497
498 Control arguments:
499 -original orig_path, -orig orig_path
500 specifies the path name of an earlier version of the module. An
501 archive pathname may be given. The equal convention is allowed.
502 This control argument is required.
503 -validate RTN, -vdt RTN
504 validates user-supplied fields in the history comment, using a
505 user-supplied validation routine. RTN must be a virtual entrypoint
506 acceptable to subroutine cv_entry_. If -validate is not supplied,
507 the default is to validate using the hcom_site_validate_
508 subroutine, if your site has provided such a routine, or
509 hcom_default_validate_subroutine provided with the history_comment
510 command.
511
512
513 :Info: hcom.display: hcom.ds: 1988-03-10 hcom display operation
514
515 Syntax as a command: hcom ds PATH COMMENT_SPECS -control_args
516
517
518 Function: displays selected history comments. Optionally, compares
519 history comments in a program with those in an earlier version of the
520 program, displaying old comments which appear in both versions or new
521 comments which do not appear in the earlier version.
522
523
524 Arguments:
525 display, ds
526 the operation to be performed.
527 PATH
528 is the name of a source code program. The language suffix must be
529 included. An archive pathname may be given.
530 COMMENT_SPECS
531 select which history comments to display. The default is to
532 display new comments if -original is given, or all comments if
533 -original is omitted. See "List of Comment Specifiers" below.
534
535
536 Control arguments:
537 -original orig_path, -orig orig_path
538 specifies the path name of an earlier version of the module. An
539 archive pathname may be given. The equal convention is allowed.
540 -validate RTN, -vdt RTN
541 validates user-supplied fields in the history comment, using a
542 user-supplied validation routine. RTN must be a virtual entrypoint
543 acceptable to subroutine cv_entry_. If -validate is not supplied,
544 the default is to validate using the hcom_site_validate_
545 subroutine, if your site has provided such a routine, or
546 hcom_default_validate_subroutine provided with the history_comment
547 command.
548
549
550 List of comment specifiers:
551 I, I:J
552 selects the comments by a comment number or a range of numbers.
553 The keywords "first" or "f" and "last" or "l" may be given to
554 identify the first and last comments.
555 all, a
556 selects all comments.
557 complete, cpt
558 selects comments which include all fields.
559 incomplete, icpt
560 selects comments which are missing the approve, audit or install
561 field.
562 approved, apv
563 selects comments which have an approve field.
564
565
566 unapproved, unapv
567 selects comments which do not have an approve field.
568 audited, aud
569 selects comments which have an audit field.
570 unaudited, unaud
571 selects comments which do not have an audit field.
572 installed, in
573 selects comments which have an install field.
574 uninstalled, unin
575 selects comments which do not have an install field.
576
577
578 new
579 when -original is given, selects comments which do not appear in the
580 original earlier version of the program.
581 old
582 when -original is given, selects comments which appear in both the
583 original and new versions of the program.
584
585
586 :Info: hcom.exists: 1988-03-10 hcom exists operation
587
588 Syntax as an active function:
589 hcom exists PATH COMMENT_SPECS -control_args
590
591
592 Syntax as a command:
593 hcom exists PATH COMMENT_SPECS -control_args
594
595
596 Function: prints or returns true if any history comments matching all
597 the COMMENT_SPECS are found in every selected module; prints or returns
598 false otherwise.
599
600
601 Arguments:
602 exists
603 the operation to be performed.
604 PATH
605 is the name of the source code program that requires comments. The
606 language suffix must be included. An archive pathname may be given.
607 COMMENT_SPECS
608 select which history comments to display. The default is "all",
609 to check whether any comments exist in the source module. See "List
610 of comment_spec values" below.
611
612
613 Control arguments:
614 -original orig_path, -orig orig_path
615 specifies the path name of an earlier version of the module. An
616 archive pathname may be given. The equal convention is allowed.
617 This argument is used in conjunction with the comment specifiers old
618 or new.
619 -validate RTN, -vdt RTN
620 validates user-supplied fields in the history comment, using a
621 user-supplied validation routine. RTN must be a virtual entrypoint
622 acceptable to subroutine cv_entry_. If -validate is not supplied,
623 the default is to validate using the hcom_site_validate_
624 subroutine, if your site has provided such a routine, or
625 hcom_default_validate_subroutine provided with the history_comment
626 command.
627
628
629 List of comment specifiers:
630 I, I:J
631 selects the comments by a comment number or a range of numbers.
632 The keywords "first" or "f" and "last" or "l" may be given to
633 identify the first and last comments.
634 all, a
635 selects all comments.
636 complete, cpt
637 selects comments which include all fields.
638 incomplete, icpt
639 selects comments which are missing the approve, audit or install
640 field.
641 approved, apv
642 selects comments which have an approve field.
643
644
645 unapproved, unapv
646 selects comments which do not have an approve field.
647 audited, aud
648 selects comments which have an audit field.
649 unaudited, unaud
650 selects comments which do not have an audit field.
651 installed, in
652 selects comments which have an install field.
653 uninstalled, unin
654 selects comments which do not have an install field.
655
656
657 new
658 when -original is given, selects comments which do not appear in the
659 original earlier version of the program.
660 old
661 when -original is given, selects comments which appear in both the
662 original and new versions of the program.
663
664
665 :Info: hcom.format: hcom.fmt: 1988-03-10 hcom format operation
666
667 Syntax as a command: hcom fmt PATH COMMENT_SPECS -control_args
668
669
670 Function: reformats selected history comments in a program, including
671 putting date fields into standard "yyyy-mm-dd" format, filling lines of
672 all comment entries to 79 character width, validating field values,
673 etc. The default value is to format "all" comments.
674
675 Existing date fields must be a single token that is acceptable to
676 convert_date_to_binary_.
677
678
679 Arguments:
680 format, fmt
681 the operation to be performed.
682 PATH
683 is the name of the source code program who history comments are to
684 be reformatted. The language suffix must be included. Archive
685 pathnames are not allowed. An archive pathname may be given.
686 COMMENT_SPECS
687 select which history comments to display. The default is "all",
688 to check whether any comments exist in the source module. See "List
689 of comment_spec values" below.
690
691
692 Control arguments:
693 -validate RTN, -vdt RTN
694 validates user-supplied fields in the history comment, using a
695 user-supplied validation routine. RTN must be a virtual entrypoint
696 acceptable to subroutine cv_entry_. If -validate is not supplied,
697 the default is to validate using the hcom_site_validate_
698 subroutine, if your site has provided such a routine, or
699 hcom_default_validate_subroutine provided with the history_comment
700 command.
701 -fill, -fi
702 Set fill mode on for the summary field. In fill mode text words
703 are moved from line to line in such a way that the last word does
704 not extend past the right margin. This is the default.
705 -nofill, -nfi
706 Set the fill mode off for the summary field.
707
708
709 -renumber, -rnb
710 specifies that the history comments within the current module can be
711 renumbered if they are out of sequence.
712 -no_renumber, -nrnb
713 prints an error if history comment numbers are out of sequence.
714 This is the default.
715
716
717 List of comment specifiers:
718 I, I:J
719 selects the comments by a comment number or a range of numbers.
720 The keywords "first" or "f" and "last" or "l" may be given to
721 identify the first and last comments.
722 all, a
723 selects all comments.
724 complete, cpt
725 selects comments which include all fields.
726 incomplete, icpt
727 selects comments which are missing the approve, audit or install
728 field.
729
730
731 approved, apv
732 selects comments which have an approve field.
733 unapproved, unapv
734 selects comments which do not have an approve field.
735 audited, aud
736 selects comments which have an audit field.
737 unaudited, unaud
738 selects comments which do not have an audit field.
739 installed, in
740 selects comments which have an install field.
741 uninstalled, unin
742 selects comments which do not have an install field.
743
744
745 new
746 when -original is given, selects comments which do not appear in the
747 original earlier version of the program.
748 old
749 when -original is given, selects comments which appear in both the
750 original and new versions of the program.
751
752
753 :Info: hcom.get: 1988-03-10 hcom get operation
754
755 Syntax as an active function:
756 hcom get PATH COMMENT_SPECS -control_args
757
758
759 Syntax as a command: hcom get PATH COMMENT_SPECS -control_args
760
761
762 Function: returns or prints given field values from selected history
763 comments.
764
765
766 Arguments:
767 get
768 the operation to be performed.
769 PATH
770 is the name of the source code program whose history comment fields
771 are to be returned. The language suffix must be included. An
772 archive pathname may be given.
773 COMMENT_SPECS
774 specify from which history comments field values are extracted.
775 At least one specifier must be given. See "List of Comment
776 Specifiers" below.
777
778
779 Control arguments:
780 -original orig_path, -orig orig_path
781 specifies the path name of an earlier version of the module. An
782 archive pathname may be given. The equal convention is allowed.
783 This argument is used in conjunction with the comment specifiers old
784 or new.
785 -field_name FIELDS, -fn FIELDS
786 specify which fields from the selected history comments are to be
787 returned or printed. All arguments following -fn that do not begin
788 with a hyphen are considered field names. See "List of field names"
789 below for a list of fields which can be selected. The default is to
790 return or print all fields of matching entries.
791
792
793 -validate RTN, -vdt RTN
794 validates user-supplied fields in the history comment, using a
795 user-supplied validation routine. RTN must be a virtual entrypoint
796 acceptable to subroutine cv_entry_. If -validate is not supplied,
797 the default is to validate using the hcom_site_validate_
798 subroutine, if your site has provided such a routine, or
799 hcom_default_validate_subroutine provided with the history_comment
800 command.
801
802
803 List of field names:
804 The following values may be given with the -field_name control
805 argument to specify which field to return.
806 change_date, cdt
807 date on which the history comment was first entered.
808 change_person_id, cpi
809 person_id of the person who entered the history comment.
810 approve_date, apvdt
811 date on which the approve field was entered.
812 approve_id, apvi
813 identifier from the approve field.
814 audit_date, auddt
815 date on which the audit field was entered.
816 audit_person_id, audpi
817 person_id of the person who audited the source module.
818
819
820 install_date, indt
821 date on which the install field was entered.
822 install_id, ini
823 identifier from the install field.
824 summary, sm
825 summary field from the history comment.
826
827
828 List of comment specifiers:
829 I, I:J
830 selects the comments by a comment number or a range of numbers.
831 The keywords "first" or "f" and "last" or "l" may be given to
832 identify the first and last comments.
833 all, a
834 selects all comments.
835 complete, cpt
836 selects comments which include all fields.
837 incomplete, icpt
838 selects comments which are missing the approve, audit or install
839 field.
840 approved, apv
841 selects comments which have an approve field.
842
843
844 unapproved, unapv
845 selects comments which do not have an approve field.
846 audited, aud
847 selects comments which have an audit field.
848 unaudited, unaud
849 selects comments which do not have an audit field.
850 installed, in
851 selects comments which have an install field.
852 uninstalled, unin
853 selects comments which do not have an install field.
854
855
856 new
857 when -original is given, selects comments which do not appear in the
858 original earlier version of the program.
859 old
860 when -original is given, selects comments which appear in both the
861 original and new versions of the program.
862
863
864 Notes: If several history comments are selected, specified fields from
865 the first selected comment are returned or printed, followed by fields
866 from the second selected comment, etc. If the selected field is not
867 present in a given history comment, then a null string is returned for
868 that field. Multiline field values are returned in a single line with
869 newline characters replaced by a space as a quoted string.
870
871
872 :Info: hcom.install: 1988-03-10 hcom install operation
873
874 Syntax as an active function: hcom install PATH -control_args
875
876
877 Syntax as a command: hcom install PATH -control_args
878
879
880 Function: system integration personnel use the install operation to
881 perform a preinstallation check on modules being installed. It
882 performs a variety of steps, including checking that new history
883 comments exist and are properly filled in. If the check succeeds, an
884 installation id is placed in the comment. The active function returns
885 true if the check succeeds the history comments are ready for
886 installation, and false otherwise.
887
888
889 Arguments:
890 install
891 the operation to be performed.
892 PATH
893 is the name of a source code program that requires history comments.
894 The language suffix must be included. An archive pathname may be
895 given.
896
897
898 Control arguments:
899 -original orig_path, -orig orig_path
900 specifies the path name of an earlier module copy which is already
901 installed in the software library. This library copy is compared
902 with the version being submitted, as described in the notes below.
903 An archive pathname may be given. The equal convention is allowed.
904 -validate RTN, -vdt RTN
905 validates user-supplied fields in the history comment, using a
906 user-supplied validation routine. RTN must be a virtual entrypoint
907 acceptable to subroutine cv_entry_. If -validate is not supplied,
908 the default is to validate using the hcom_site_validate_
909 subroutine, if your site has provided such a routine, or
910 hcom_default_validate_subroutine provided with the history_comment
911 command.
912
913
914 -errors, -er
915 displays history comments that fail the installation checks. This
916 is the command default.
917 -no_errors, -ner
918 suppresses display of failing history comments. This is the active
919 function default.
920
921
922 Control arguments for field input:
923 -approve APPROVE_ID, -apv APPROVE_ID
924 specifies the APPROVE_ID field to be assigned to all history
925 comments which are missing an approve field. An error occurs if
926 this argument is given but no comments are missing the approve
927 field. See "List of history comment fields" above for a description
928 of valid APPROVE_IDs. This control argument is used when only the
929 installer knows what the approval identifier is eg only he knows
930 what the Multics Emergency Change Request MECR number is because
931 this number is assigned at installation time. The maximum length
932 of this field is 24 characters. If the AUDIT_DATE AND
933 AUDIT_PERSON_ID fields are missing when the -apv argument is given,
934 an error message is issued but processing continues.
935
936
937 -input_approve, -iapv
938 prompts for an APPROVE_ID. This is a single line field value.
939 -no_approve, -napv
940 specifies that an APPROVE_ID is not being entered. This is the
941 default.
942 -install INSTALL_ID, -in INSTALL_ID
943 specifies an identifier associated with installing the changed
944 module into execution libraries. This identifier is placed in the
945 all history comments which are missing the install field. An error
946 occurs if every comment has an install field. See "List of history
947 comment fields" above for a description of valid INSTALL_IDs. The
948 maximum length of this field is 24 characters.
949 -input_install, -iin
950 prompts for the installation identifier. This is the default.
951
952
953 Notes: The install operation performs the following steps:
954
955 1) Make a working copy of history comments in the new module.
956 2) If -original is given, check comments in the original module against
957 those in the working copy:
958 a) check for comments in the original which do not appear in the
959 working copy. This indicates changes which have been backed out.
960 If any are found, print an error and stop further checking.
961 b) copy the install identifier from comments in the original module
962 into corresponding comments in the working copy which are missing
963 this identifier. This can occur when the developer makes changes
964 to a modified version of the program before that modified version
965 is installed in the libraries.
966
967
968 3) If -approve or -input_approve is given, check for comments in the
969 working copy which are missing the approve field. If none are
970 found, report an error and stop further checking. If the AUDIT_DATE
971 and AUDIT_PERSON_ID fields are missing an error message is issued
972 but processing continues.
973 4) If -install or -input_install is given, check for comments in the
974 working copy which are missing the install field. If none are
975 found, report an error and stop further checking. This indicates
976 that the developer forgot to add a history comment when he modified
977 the module.
978 5) Check for completeness of summary, and audit fields in all history
979 comments. If the AUDIT_DATE and AUDIT_PERSON_ID fields are missing,
980 an error message is issued but processing continues. If incomplete
981 or erroneous entries are found, report an error and stop further
982 checking.
983
984
985 6) If -approve or -input_approve is given, place the approve identifier
986 in the working copy's new history comments. If -install or
987 -input_install is given, place the installation identifier into the
988 working copy's new history comments.
989 7) Reformat the new history comments in the working copy.
990 8) If no error occurred, replace history comments in the new module
991 with the working comments built by the install operation.
992
993
994 :Info: hcom.replace_field: hcom.rpf: 1988-03-10 hcom replace_field operation
995
996 Syntax as a command: hcom rpf PATH COMMENT_SPECS -control_args
997
998
999 Function: replaces existing comment fields in selected history
1000 comments.
1001
1002
1003 Arguments:
1004 replace_field, rpf
1005 the operation to be performed.
1006 PATH
1007 is the name of a source code program that requires history comments.
1008 The language suffix must be included. An archive pathname may be
1009 given.
1010 COMMENT_SPECS
1011 specify which history comments are to be updated. See "List of
1012 Comment Specifiers" below.
1013
1014
1015 Control arguments:
1016 -original orig_path, -orig orig_path
1017 specifies the path name of an earlier version of the module. An
1018 archive pathname may be given. The equal convention is allowed.
1019 This argument is used in conjunction with the comment specifiers old
1020 or new.
1021 -validate RTN, -vdt RTN
1022 validates user-supplied fields in the history comment, using a
1023 user-supplied validation routine. RTN must be a virtual entrypoint
1024 acceptable to subroutine cv_entry_. If -validate is not supplied,
1025 the default is to validate using the hcom_site_validate_
1026 subroutine, if your site has provided such a routine, or
1027 hcom_default_validate_subroutine provided with the history_comment
1028 command.w
1029
1030
1031 -critical_fix, -cfix
1032 specifies that critical fix history comments are allowed in the
1033 program. All comments following the first, which contains critical
1034 fix field values, must also contain critical fix field values.
1035
1036
1037 Control arguments for field input:
1038 At least one of the following control arguments must be given:
1039 -summary -input_summary -audit
1040 -approve -input_approve
1041 -install -input_install
1042 -approve APPROVE_ID, -apv APPROVE_ID
1043 replaces the APPROVE_ID field. The maximum length of this field is
1044 24 characters. See "List of history comment fields" above for a
1045 description of valid APPROVE_IDs.
1046 -input_approve, -iapv
1047 prompts for a new APPROVE_ID. This is a single line field value.
1048 -no_approve, -napv
1049 does not replace the APPROVE_ID field, or prompt for missing approve
1050 fields. This is the default.
1051
1052
1053 -summary TEXT, -sm TEXT
1054 replaces the text describing the change. If the text contains
1055 spaces, quotes, parentheses, etc, the TEXT must be enclosed within
1056 quotes.
1057 -input_summary, -ism
1058 prompts the user for a new summary field. This is a multiline
1059 field.
1060 -no_summary, -nsm
1061 does not replace the summary field. This is the default.
1062 -fill, -fi
1063 Set fill mode on for the summary field. In fill mode text words
1064 are moved from line to line in such a way that the last word does
1065 not extend past the right margin. This is the default.
1066 -nofill, -nfi
1067 Set the fill mode off for the summary field.
1068
1069
1070 -audit, -aud
1071 puts the users person_id in the AUDIT_PERSON_ID field.
1072 -no_audit, -naud
1073 does not add the AUDIT_PERSON_ID field. This is the default.
1074 -install INSTALL_ID, -in INSTALL_ID
1075 specifies an identifier associated with installing the changed
1076 module into execution libraries. See "List of history comment
1077 fields" above for a description of valid INSTALL_IDs. The maximum
1078 length of this field is 24 characters.
1079 -input_install, -iin
1080 prompts for the INSTALL_ID. This is a single line field.
1081 -no_install, -nin
1082 does not set the INSTALL_ID field or prompt for missing install
1083 fields. This is the default.
1084
1085
1086 List of comment specifiers:
1087 I, I:J
1088 selects the comments by a comment number or a range of numbers.
1089 The keywords "first" or "f" and "last" or "l" may be given to
1090 identify the first and last comments.
1091 all, a
1092 selects all comments.
1093 complete, cpt
1094 selects comments which include all fields.
1095 incomplete, icpt
1096 selects comments which are missing the approve, audit or install
1097 field.
1098 approved, apv
1099 selects comments which have an approve field.
1100
1101
1102 unapproved, unapv
1103 selects comments which do not have an approve field.
1104 audited, aud
1105 selects comments which have an audit field.
1106 unaudited, unaud
1107 selects comments which do not have an audit field.
1108 installed, in
1109 selects comments which have an install field.
1110 uninstalled, unin
1111 selects comments which do not have an install field.
1112
1113
1114 new
1115 when -original is given, selects comments which do not appear in the
1116 original earlier version of the program.
1117 old
1118 when -original is given, selects comments which appear in both the
1119 original and new versions of the program.
1120
1121
1122 :Info: hcom_validation_rtn_: 2020-05-19 hcom_validation_rtn_
1123
1124
1125 Function:
1126 A site can define a site-wide history comment validation routine to
1127 validate the contents of the APPROVE_ID and INSTALL_ID fields of
1128 history comments. This routine is called hcom_site_validate_. If it
1129 is found in the user's object search rules, the history_comment
1130 command will automatically use this validation routine instead of
1131 using hcom_default_validate_.
1132
1133
1134 Also, the -validate control argument allows use of a user-supplied
1135 validation subroutine to validate the APPROVE_ID and INSTALL_ID
1136 fields. This user routine can have any name.
1137
1138
1139 The calling sequence of both the hcom_site_validate_ subroutine and
1140 user-written routines is shown below. For a user-written routine, the
1141 name hcom_site_validate_ would be replaced with whatever name the user
1142 chooses for the routine.
1143
1144
1145 Syntax:
1146 dcl hcom_validation_rtn_ entry char* var char* var
1147 char* var bit1 char* var char* var;
1148
1149 call hcom_validation_rtn_ caller field_name input_value
1150 result_bit canonical_value field_type;
1151
1152
1153 Arguments:
1154 caller
1155 is the name of the calling program, on whose behalf the validation
1156 routine should report errors, ask questions, etc. Input
1157 field_name
1158 is the name of the field being validated. This argument may have a
1159 value of either APPROVAL_FIELD_NAME or INSTALL_FIELD_NAME. These
1160 named constants are declared in hcom_field_names.incl.pl1. Input
1161 input_value
1162 is the field value supplied by the user. Input
1163
1164
1165 result_bit
1166 is either "1"b if the input value is valid or "0"b if the input
1167 value is invalid. Output
1168 canonical_value
1169 is the canonical text form of the field_name and input_value.
1170 Output
1171 field_type
1172 canonical text form of the field_name for use in error messages.
1173 Output
1174
1175
1176 :hcom:
1177 /****^ HISTORY COMMENTS:
1178 1) change1988-03-10LJAdams, approve, audit, install:
1179 Create info seg with full documentation for the hcom command.
1180 2) change2019-05-29GDixon, approve2019-05-29MCR10065,
1181 audit2019-09-20Swenson, install2019-09-20MR12.6g-0030:
1182 Change hcom.add.info to reference info_seg.history_comment.info for
1183 instruction on adding the first history comment to an info seg. Also, add
1184 a history_comments chunk to end of this info seg.
1185 3) change2019-09-29GDixon, approve2019-09-29MCR10067,
1186 audit2019-10-20Swenson, install2021-05-27MR12.6g-0056:
1187 Change format used for date fields to the specifier: yyyy-mm-dd, now that
1188 4-digit dates are required by this command.
1189 4) change2020-05-28GDixon, approve2021-02-22MCR10088,
1190 audit2021-05-27Swenson, install2021-05-27MR12.6g-0056:
1191 Change to new Operations Format to standardize presentation of
1192 multi-operation command/AF info segments, using the new format implemented
1193 by verify_info.
1194 5) change2021-11-13GDixon, approve2021-12-07MCR10105,
1195 audit2021-12-10Swenson, install2021-12-10MR12.8-1014:
1196 Remove references to info_seg.history_comment.info. That info segment
1197 is no longer needed when adding first history comment to an info seg.
1198 END HISTORY COMMENTS */