1 :Info: update_seg: us: 07/20/86 update_seg, us
2
3
4 Syntax as a command:
5 us operation arguments -control_arguments
6
7
8 Function: This command is used to define the contents of a
9 modification and to install or de-install the modification in one or
10 more system or user libraries. Refer to the "Installation Process"
11 section below for more details.
12
13
14 Arguments:
15 operation
16 designates the operation to be performed. See "List of Operations"
17 below.
18 arguments
19 are optional arguments which depend upon the particular operation to
20 be performed.
21
22
23 Operation Groups: The operations permitted by update_seg are grouped
24 into five functional categories, as shown below.
25
26
27 _
28 set_defaults, sd |
29 initiate, in | Creation operations
30 print_defaults, pd _|
31 _
32 add |
33 delete, dl | Definition operations
34 move, mv |
35 replace, rp _|
36
37
38 _
39 print, pr | Listing operations
40 list, ls _|
41 _
42 install | Installation operations
43 de_install _|
44 _
45 clear _| Clearing operation
46
47
48 The creation operations create and initiate an installation object io
49 segment in which a modification is defined. The definition operations
50 define the segments of the modification, and the steps which must be
51 performed to install those segments. The listing operations list the
52 segments of the modification and the installation steps to be performed
53 for those segments. The installation operations install and de-install
54 the modification. Finally, the clearing operations reset an io segment
55 when an installation has failed and the modification has been
56 installed.
57
58
59 List of operations:
60 add
61 defines a segment which is to be added to a library.
62 clear
63 clears all error codes set during a prior installation or
64 de-installation operation.
65 de_install
66 de-installs the modification defined in an installation object
67 segment.
68 delete
69 defines a segment which is to be deleted from a library.
70 initiate
71 creates a new installation object io segment and initiates it for
72 use by update_seg.
73
74
75 install
76 installs the modification defined in an io segment.
77 list
78 creates an installation listing segment containing information about
79 an io segment.
80 move
81 defines a library segment to be moved to another library directory.
82 print
83 prints information about the modification defined in an io segment.
84 print_defaults
85 prints the default values associated with an io segment.
86 replace
87 defines a segment which is to replace another segment in a library.
88 set_defaults
89 sets the global default ACL, ring brackets, and documentation
90 directory.
91
92
93 Installation Process: A modification is a group of physically- or
94 logically-related segments that must be installed in a library at the
95 same time in order to maintain library consistency and integrity. For
96 example, a source segment and its compiled object segment are
97 physically-related segments which must be installed concurrently to
98 ensure that library source segments correspond to library object
99 segments. On the other hand, two object segments that interact with
100 one another are logically-related segments that must be installed
101 concurrently to ensure proper operation.
102
103
104 The update_seg command is the library maintainer's interface to the
105 Multics Installation System MIS. MIS installs the related segments
106 of a modification into a library at the same time or nearly so:
107
108 1. by dividing the installation of each segment into a series of
109 steps getting the unique id names and ACL of new and old
110 segments copying the target segment adding to and deleting from
111 the target segment's names freeing names on the old segment
112 etc.
113 2. by performing one step for all segments of the modification before
114 moving on to the next step.
115 3. by installing the segments which are used by library users e.g.
116 object segments as a group after installing the other segments in
117 the modification e.g. source segments archives and info
118 segments.
119
120
121 Using this strategy, the installation window the period of library
122 inconsistency can be reduced to less than one minute per modification,
123 and is usually about five seconds per modification.
124
125
126 MIS offers several benefits to the library maintainer. The MIS
127 subroutines which perform each installation step are all restartable.
128 If a system failure or a process failure occurs during an installation,
129 the installation can be resumed from the point of interruption, as long
130 as the Multics Storage System remains intact across the failure.
131
132
133 The MIS subroutines are also reversible. Each MIS subroutine performs
134 a specific installation function when invoked in "installation" mode
135 with a group of arguments. The same MIS subroutine will perform the
136 logical inverse of its installation function a de-installation
137 function when it is invoked in "de-installation" mode with the same
138 group of arguments. If a bad modification has been installed, it can
139 be removed from the libraries by invoking MIS in "de-installation"
140 mode, without the use of supplementary tools or special procedures.
141
142
143 MIS provides planned automatic error recovery. If MIS detects a fatal
144 installation error, it can recover automatically from the error by
145 invoking, in "de-installation" mode, the installation subroutines which
146 completed before the fatal error occurred. Most common installation
147 errors name duplication entry not found record quota overflow etc.
148 are handled in this manner.
149
150
151 MIS allows a limited degree of rerunnability. All MIS subroutines are
152 rerunnable after having been invoked in "de-installation" mode, as long
153 as the segments in the modification have not been changed since the
154 de-installation. The installer can correct many minor errors e.g.
155 name duplications without having to start the installation from the
156 very beginning.
157
158
159 Finally, MIS automatically documents an installation. An MIS
160 subroutine creates a description of a modification, and appends this
161 description to an ASCII installation log as a part of the installation.
162 In addition, a paragraph summarizing the modification can be inserted
163 at the top of an installations info segment to notify users of changes
164 to the libraries.
165
166
167 update_seg stores the definition of a modification in an installation
168 object io segment as a list of tasks. The task list consists of one
169 or more task blocks, each representing a call to one of the MIS
170 installation subroutines. The defined modification is installed by
171 sorting these task blocks by type of installation step and calling the
172 MIS subroutines associated with the order task blocks. The update_seg
173 command interfaces with the MIS task list processor and installation
174 subroutines to perform the definition and installation operations.
175
176
177 Access required: Update_seg can install segments in any ring from 1 to
178 7 if the user has access to the installation_tools_ gate. If
179 installation_tools_ is not accessible, then segments can be installed
180 in any ring from the current ring of execution to ring 7.
181
182
183
184 :Info: update_seg.add: us.add:
185 07/21/86 update_seg add operation
186
187
188 Syntax as a command:
189 us add new_seg target_seg -control_args
190
191
192 Function: This operation defines a segment which is to be added to a
193 library as part of a modification. The definition is appended to the
194 currently-initiated io segment. The following installation steps are
195 required for the most common case of the add operation.
196
197
198 1. Get the unique id of the new segment.
199 2. Get the names on the new segment.
200 3. Gather detailed information about the new segment for
201 documentation of the installation.
202 4. Create a uniquely-named target segment in the library, and copy
203 the contents of the new segment into the target segment.
204 5. Set the ring brackets on the target segment.
205 6. Set the ACL on the target segment.
206 7. Add the new segment's names to the uniquely-named target segment.
207 8. Remove the unique name from the target segment.
208 9. Document the addition of the new segment to the library.
209
210
211 Arguments:
212 new_seg
213 is the pathname of the new segment to be added to the library. A
214 relative or absolute pathname may be given.
215 target_seg
216 is the pathname of the target segment which is to be created in the
217 library directory. A relative or absolute pathname may be given,
218 and the Multics equal convention may be used to equate components in
219 the final entrynames in the new_seg and target_seg pathnames. Note
220 that an error will occur if the final entryname of the target_seg
221 pathname is not one of the names placed on the target segment as it
222 is installed.
223
224
225 Control arguments:
226 -acl mode1 User_id1 ... modeN User_idN
227 defines the access control list ACL to be placed on the target
228 segment. Normally the default ACL is used. Each access mode is
229 paired with the access control name which follows. modeI is any
230 valid access mode for segments eg r re rw rew null n. User_idI
231 is an access control name that must be of the form
232 Person_id.Project_id.tag. Missing components in the access control
233 name are assumed to be "*". If the last modeI has no User_idI
234 following it, the user's Person_id and Project_id are assumed.
235 -add_name names, -an names
236 defines a list of names to be added to the target segment, where
237 names are one or more entrynames.
238
239
240 -archive, -ac
241 specifies that the segment being defined in a definition operation
242 is an archive, and that the names of its archive components are to
243 be added to the target segment of the definition operation.
244 Normally the archive component names are not added to the target
245 segment.
246 -defer, -df
247 specifies that the installation subroutines which gather information
248 about the segments in a definition operation should defer their
249 information gathering until the installation operation is performed.
250 Thus, changes made to the segment after the modification is defined
251 will be reflected in the installed segment. Normally, name and ACL
252 changes made between the definition and installation operations are
253 not reflected in the installed target segment. Segment replacements
254 during this period cause a fatal installation error.
255
256
257 -delete_acl User_ids, -da User_ids
258 defines a list of ACL entries which are to be removed from the ACL
259 of the target segment of a definition operation. A User_id is an
260 access control name that must be of the form
261 Person_id.Project_id.tag. Missing components in the access control
262 name are assumed to be "*".
263 -delete_name names, -dn names
264 defines a list of names to be removed from the target segment of a
265 definition operation, where names are one or more entrynames.
266 -initial_acl, -iacl
267 specifies that the Initial ACL IACL for segments of the target
268 directory is to be placed on the target segment.
269 -log
270 specifies that detailed information about the installation of the
271 target segment is to be logged in Installations.log.
272
273
274 -max_length N, -ml N
275 specifies that the maximum length attribute of the target segment of
276 a definition operation is to be set. If N > 0, the maximum length
277 is set of N words. If N = 0, the maximum length is set to the
278 current length of the segment being installed. If N is omitted, the
279 maximum length is set to sys_info$max_seg_size. If -max_length is
280 omitted, the maximum length is set to sys_info$default_max_length
281 for regular segments, and to the current length of the segment being
282 installed for special segments. See -special_seg below for
283 information about special segments.
284 -name names, -nm names
285 defines the list of names to be placed on the target segment, where
286 names are one or more entrynames. Normally, the names on the new
287 segment are placed on the target segment.
288
289
290 -ring_brackets r1 r2 r3, -rb r1 r2 r3
291 defines a set of ring brackets to be placed on the target segment,
292 where r1 is the write bracket, r2 is the read bracket, and r3 is the
293 gate bracket. If r2 is omitted, it is set to the maximum of the
294 following values: the write bracket, the current validation level,
295 or 5. If r3 is omitted, it is set to the maximum of the following
296 values: the read bracket, the current validation level, or 5. It
297 may not be specified unless r2 is also specified. Normally, the
298 default ring brackets are placed on the target segment.
299
300
301 -set_acl mode1 User_id1 ... modeN User_idN,
302 -sa mode1 User_id1 ... modeN User_idN
303 defines a list of ACL entries which are to be added to the ACL of
304 the target segment. modeI is any valid access mode for segments
305 eg r re rw rew null n. User_idI is an access control name that
306 must be of the form Person_id.Project_id.tag. Missing components in
307 the access control name are assumed to be "*". If the last modeI
308 has no User_idI following it, the user's Person_id and Project_id
309 are assumed.
310 -special_seg, -ss
311 defines the target segment of a definition operation as a special
312 segment. The properties of special segments are described below
313 under "Special Segments."
314
315
316 Special Segments: The -special_seg control argument is used to reduce
317 the installation window for the user-visible segments of a
318 modification. For example, if a modification contains two bound
319 segments, one of which calls the other, then it is important to reduce
320 the time between the installation of the first segment and the
321 installation of the second. Otherwise, users of the first segment
322 could receive errors when it tried to reference the second.
323
324
325 To reduce the length of user-observable installation windows, the
326 segments of a modification being installed in user search directories
327 can be defined as special segments which have the following properties:
328
329
330 1. The final installation of all special segments adding names to
331 these segments is deferred until all regular segments have been
332 installed.
333
334 2. The de-installation of a modification causes the regular segments
335 which were installed to be deleted from the library. Special
336 segments are renamed instead of being deleted.
337
338 3. The default setting for the maximum length attribute of segments
339 differs for special segments from that used for regular segments.
340 Special segments use the current length of the segment being
341 installed as the default maximum length. Regular segments use
342 sys_info$default_max_length.
343
344
345 Deferring the final installation of special segments until the last
346 possible moment provides several desirable advantages. If a fatal
347 error occurs while installing a regular segment, no special segments
348 will have been installed and the user-visible portions of the libraries
349 will remain in a consistent state. In addition, the installation
350 window for special segments is shortened by grouping them together at
351 the end of the installation, because there are fewer segments going
352 through the final installation step adding names at the same time.
353 This further reduces the user's exposure to library inconsistencies.
354
355
356 Special segments cannot be deleted by a de-installation operation
357 because some users may being using them. However, renaming the special
358 segments prevents more users from using them after they have been
359 de-installed.
360
361
362
363 :Info: update_seg.clear: us.clear:
364 07/21/86 update_seg clear operation
365
366
367 Syntax as a command:
368 us clear io_seg -control_args
369
370
371 Function: This operation clears all error codes set during a prior
372 installation or de-installation operation. This allows the io segment
373 to be printed or listed prior to a reinstallation of the modification
374 without having prior error messages appear in the output.
375
376
377 The clear operation also clears segment unique identifiers stored in
378 the modification definition. These unique identifiers are stored to
379 ensure that the segments defined in modification definition operations
380 are those which are actually installed or de-installed. Clearing these
381 identifiers disables such checking, and allows the de-installation of a
382 modification whose segment unique identifiers have been reset by a
383 Multics storage system reload.
384
385 NOTE: Extreme care should be taken when clearing segment unique
386 identifiers to ensure that the correct segments will be
387 de-installed by the subsequent de_install operation.
388
389
390 Arguments:
391 io_seg
392 is an optional argument which specifies the pathname of an existing
393 io segment which is to be cleared. If the final entryname does not
394 have an io suffix, then one is assumed. See "Notes" below for a
395 discussion of this argument.
396
397
398 Control arguments:
399 -error, -er
400 specifies that error codes stored in the modification definition are
401 to be reset.
402 -uid
403 specifies that unique identifiers for the segments in the
404 modification are to be reset, thus disabling unique identifier
405 checking during subsequent installation and de-installation
406 operations.
407
408
409 Notes: If an io_seg argument is given with the clear operation, the
410 named io segment is reinitiated and it remains initiated after the io
411 segment has been cleared. Thus, all further update_seg operations
412 refer to this initiated io segment. If no io_seg argument is given,
413 then the currently-initiated io segment is cleared, if one is
414 initiated.
415
416
417
418 :Info: update_seg.de_install: us.de_install:
419 07/21/86 update_seg de_install operation
420
421
422 Syntax as a command:
423 us de_install io_seg -control_args
424
425
426 Function: This operation de-installs the modification defined in an io
427 segment. The modification must have been previously installed, either
428 completely or partially.
429
430
431 Arguments:
432 io_seg
433 is an optional argument which specifies the pathname of an existing
434 io segment defining the modification to be de-installed. If the
435 final entryname does not have an io suffix, then one is assumed.
436 See "Notes" below for a discussion of this argument.
437
438
439 Control arguments:
440 -severity N, -sv N
441 defines the severity level of fatal de-installation errors. All
442 errors whose severity is equal to or greater than N are treated as
443 fatal errors. N must be an integer from 1 to 5 inclusive. The
444 default severity is 1, making all deinstallation errors fatal.
445 Refer to "Controlling the Fatality of Deinstallation Errors" below
446 for a description of the severity levels associated with the various
447 kinds of deinstallation errors.
448 -stop
449 disables the automatic error recovery mechanism, causing update_seg
450 to stop when a fatal deinstallation error occurs. Refer to
451 "Deinstallation Errors" below for more information.
452
453
454 Notes: If an io_seg argument is given with the de_install operation,
455 the named io segment is reinitiated, and it remains initiated after the
456 modification has been de-installed. Thus, all further update_seg
457 operations refer to this initiated io segment. If no io_seg argument
458 is given, then the modification defined in the currently-initiated io
459 segment is de-installed, if one is initiated.
460
461
462 Access required: As with the install operation, The Multics
463 Installation System calls entries in the installation_tools_ gate in
464 order to install Multics System Library segments into rings 1-7. If
465 the library maintainer does not have access to this gate, then
466 update_seg can install segments in rings from the current ring of
467 execution to ring 7.
468
469
470 Deinstallation Errors: If an error occurs during the deinstallation of
471 a modification, a message is printed to diagnose the error. As with
472 installation errors, the message for a deinstallation error has a
473 Warning caption for a nonfatal error or an Error caption for a fatal
474 error.
475
476
477 A nonfatal error does not stop the deinstallation. A fatal error stops
478 the deinstallation and automatically reinstalls the modification. When
479 the stop control argument is given, a fatal error stops the
480 deinstallation without reinstalling it.
481
482
483 Controlling the Fatality of Deinstallation Errors: A given
484 deinstallation error may be nonfatal or fatal, depending upon the
485 severity level associated with that error, and upon the fatal severity
486 level given by the library maintainer in the -severity control
487 argument. The errors which fall into each severity level are described
488 below:
489
490 severity 1
491 Errors incurred while: restoring a name which is already on an old
492 segment; removing a name which is not on the target segment; or
493 deleting the target segment.
494 severity 2
495 Errors incurred while: restoring a name on an old segment which is
496 already on another entry in the old segment's directory; removing
497 the final name from the target segment; or resetting the ACL or ring
498 brackets on the target segment.
499 severity 3
500 All other errors.
501
502
503 Correcting Fatal Deinstallation Errors: Fatal deinstallation errors
504 usually occur because the segments in the target directory or their
505 attributes have been changed since the modification was installed.
506 Such modifications could occur: if a subsequent modification affected
507 one or more of the segments of the modification; if the Multics storage
508 system was reloaded, causing a new unique identifier to be assigned to
509 each segment; if a system crash forced the target directory to be
510 salvaged; etc.
511
512
513 The proper corrective action for most deinstallation errors involves
514 returning the segments in the modification to their state just after
515 installation. In some cases, this may be as simple as deinstalling a
516 subsequent modification. In other cases, returning to the installation
517 state may be undesirable. For example, the deinstallation of a
518 subsequent modification could restore a module with a serious bug. It
519 might be better to replace all bad modules with fixed versions if these
520 are available, rather than restoring to modules with worse bugs.
521
522
523 In some cases, returning to the installation state may be impossible.
524 It would be very difficult to restore the unique identifiers for
525 segments in a reloaded directory. The update_seg clear -uid operation
526 is provided to disable unique identifier checking by update_seg in such
527 cases. However, it must be used with extreme caution. Without this
528 checking, other segments besides those in the modification may be
529 affected by the deinstallation.
530
531
532 Finally, it may not be possible to restore segments in a salvaged
533 directory to their original state. In such cases, it may be necessary
534 to use -severity 4 in the de-install operation to de-install other
535 portions of the installation, and then to de-install portions in the
536 salvaged directory manually. Care must be taken in such operations,
537 because the library will be inconsistent until both the automatic and
538 manual de-installation operations are complete. Having such a large
539 de-installation window may necessitate performing the de-installation
540 during a special session of Multics when users are not allowed to log
541 on.
542
543
544 Recovering from a Crash: As with an install operation, a
545 de-installation interrupted by a system crash can be restarted by using
546 the de_install operation, or can be reversed by using the install
547 operation.
548
549
550
551 :Info: update_seg.delete: update_seg.dl: us.delete: us.dl:
552 07/21/86 update_seg delete dl operation
553
554
555 Syntax as a command:
556 us dl target_seg -control_args
557
558
559 Function: This operation defines a segment which is to be deleted from
560 a library as part of a modification. The definition is appended to the
561 currently-initiated io segment. The following steps are required for
562 the most common case of the delete operation.
563
564
565 1. Get the unique id of the segment to be deleted the target
566 segment.
567 2. Get the names on the target segment.
568 3. Gather detailed information about the segment being deleted for
569 documentation of the installation.
570 4. Add a unique name to the target segment.
571 5. Free the names on the target segment.
572 6. Document the deletion of the target segment from the library.
573
574
575 At the time of the installation operation, the segment is not actually
576 deleted from the library. Instead, the segment's names are freed and a
577 unique name is added to the segment to mark it as a candidate for
578 deletion by the library_cleanup command at some later date. The
579 segment cannot be deleted because it cannot be terminated in the
580 process of any library user who might be using it.
581
582
583 The segment's names are freed by adding an integer suffix to the
584 primary segment name, as described in the lfree_name command
585 description in Section XIII; and by deleting any other names on the
586 segment. The renamed primary name is retained to identify the segment.
587 The remaining names are deleted to prevent library users from
588 referencing the segment.
589
590
591 Arguments:
592 target_seg is the pathname of the segment to be deleted from the
593 library. A relative or absolute pathname may be given.
594
595
596 Control arguments:
597 -defer, -df
598 specifies that the information gathering in steps 1-3 above is to be
599 deferred until the installation operation.
600 -log
601 specifies that detailed information about the deletion of the target
602 segment is to be logged in Installations.log.
603 -special_seg, -ss
604 defines the target segment to be a special segment. The properties
605 of special segments are described below under "Special Segments."
606
607
608 Special Segments: The -special_seg control argument is used to reduce
609 the installation window for the user-visible segments of a
610 modification. For example, if a modification contains two bound
611 segments, one of which calls the other, then it is important to reduce
612 the time between the installation of the first segment and the
613 installation of the second. Otherwise, users of the first segment
614 could receive errors when it tried to reference the second.
615
616
617 To reduce the length of user-observable installation windows, the
618 segments of a modification being installed in user search directories
619 can be defined as special segments which have the following properties:
620
621
622 1. The final installation of all special segments adding names to
623 these segments is deferred until all regular segments have been
624 installed.
625
626 2. The de-installation of a modification causes the regular segments
627 which were installed to be deleted from the library. Special
628 segments are renamed instead of being deleted.
629
630 3. The default setting for the maximum length attribute of segments
631 differs for special segments from that used for regular segments.
632 Special segments use the current length of the segment being
633 installed as the default maximum length. Regular segments use
634 sys_info$default_max_length.
635
636
637 Deferring the final installation of special segments until the last
638 possible moment provides several desirable advantages. If a fatal
639 error occurs while installing a regular segment, no special segments
640 will have been installed and the user-visible portions of the libraries
641 will remain in a consistent state. In addition, the installation
642 window for special segments is shortened by grouping them together at
643 the end of the installation, because there are fewer segments going
644 through the final installation step adding names at the same time.
645 This further reduces the user's exposure to library inconsistencies.
646
647
648 Special segments cannot be deleted by a de-installation operation
649 because some users may being using them. However, renaming the special
650 segments prevents more users from using them after they have been
651 de-installed.
652
653
654
655 :Info: update_seg.initiate: update_seg.in: us.initiate: us.in:
656 07/21/86 update_seg initiate in operation
657
658
659 Syntax as a command:
660 us in io_seg -control_args
661
662
663 Function: This operation is the first operation required to install a
664 modification. It creates a new installation object io segment and
665 initiates it for use by update_seg.
666
667
668 Only one io segment can be initiated in a process at any given time.
669 This restriction allows the library maintainer to omit the io segment
670 name from most update_seg operations. When the io segment name is
671 omitted, then the operation refers to the io segment which is currently
672 initiated. This is usually the io segment segment named in the last
673 initiate operation.
674
675
676 Besides creating new io segments, the initiate operation can be used to
677 switch to and initiate another existing io segment, or to change the
678 attributes of an existing io segment.
679
680
681 Arguments:
682 io_seg
683 is the pathname of the io segment to be initiated. If the final
684 entryname does not have an io suffix, then one is assumed. If
685 io_seg is omitted, then the attributes of the currently-initiated io
686 segment are changed.
687
688
689 Control arguments:
690 -acl mode1 User_id1 ... modeN User_idN
691 defines the default access control list ACL used by the initiated
692 io segment. This ACL is placed on new segments being added to a
693 library when no -acl control argument is given in an add definition
694 operation. modeI is any valid access mode for segments eg r re rw
695 rew null n. User_idI is an access control name that must be of the
696 form Person_id.Project_id.tag. Missing components in the access
697 control name are assumed to be "*". If the last modeI has no
698 User_idI following it, the user's Person_id and Project_id are
699 assumed. Normally, the global default ACL is used as the default
700 ACL on a new io segment. Use the update_seg print_defaults
701 operation to print the global default ACL.
702
703
704 -fill, -fi
705 reformats the text of the modification summary entered with the -log
706 control argument. Reformatting is done similar to the "fill-on" and
707 "align-left" controls of the compose command. default
708 -log
709 indicates that a summary of the modification is to be typed in as
710 part of the initiate operation. This summary is placed in one or
711 more documentation segments, as described under "Automatic
712 Documentation" below. Normally, no summary is associated with a new
713 io segment.
714 -no_fill, -nfi
715 uses the modification summary exactly as typed.
716
717
718 -restart, -rt
719 indicates that the io segment identified by io_seg exists and is to
720 be reinitiated. Normally a new io segment is created when io_seg is
721 given.
722
723
724 -ring_brackets r1 r2 r3, -rb r1 r2 r3
725 defines the default ring brackets used by the initiated io segment.
726 These ring brackets are placed on new segments being added to a
727 library when no -ring_brackets control argument is given in an add
728 definition operation. r1 is the write bracket, r2 is the read
729 bracket, and r3 is the gate bracket. If r2 is omitted, it is set to
730 the maximum of the following values: the write bracket, the current
731 validation level, or 5. If r3 is omitted, it is set to the maximum
732 of the following values: the read bracket, the current validation
733 level, or 5. It may not be specified unless r2 is also specified.
734 Normally, the global default ring brackets are used as the default
735 ring brackets on a new io segment. Use the update_seg
736 print_defaults operation to print the global default ring brackets.
737 -set_log_dir path, -sld path
738 gives the pathname of the documentation directory to be used by the
739 io segment. Normally the working directory is used.
740
741
742 Global Defaults: The global default ACL, ring brackets, and
743 documentation directory have the values shown below:
744
745 ACL: re *.*.*
746 ring brackets: 1,5,5
747 documentation directory: working directory
748
749
750 These values may be changed for the life of the library maintainer's
751 process by using the set_defaults operation. The current global
752 defaults may be printed by using the print_defaults operation.
753
754
755 Automatic Documentation: The directory defined in a -set_log_dir
756 control argument is called the documentation directory. Two types of
757 information about a modification are logged in segments contained in
758 this directory.
759
760
761 Installations.info
762 A summary of each the modification is inserted at the beginning of
763 Installations.info. The library maintainer specifies this summary
764 information in the update_seg initiate operation, via the -log
765 control argument. This is a segment designed to inform users of
766 recent changes to the libraries.
767 Installations.log
768 Detailed information about which segments and bound segment
769 components are changed by the modification is appended to
770 Installations.log, along with the summary described above. This log
771 contains a permanent record of all installations.
772
773 Use of these documentation segments is shared among several different
774 update_seg installers by using a lock word in the segment
775 Installations.lock.
776
777
778 When the -log control argument is given, the initiate operation
779 responds by printing "Input." All subsequent lines typed by the
780 library maintainer are used as a summary of the modification being
781 defined in the io segment. Input of the summary ends when the library
782 maintainer types a line containing only a period .. The summary is
783 placed in both of the documentation segments when the modification is
784 installed.
785
786
787 When -fill is given or used by default, the summary lines are truncated
788 or filled out to 65 characters to improve the readability of the
789 documentation segments. A completely blank line or a line beginning
790 with a space or horizontal tab HT character will force a break in the
791 filling of the previous line.
792
793
794 The summary of a modification can be changed at any point before the
795 modification is installed before an installation operation.
796 Reinitiating the io segment with the -log control argument causes any
797 previously-defined summary to be replaced by a new summary.
798
799
800 The summary associated with any io segment can be printed by the "us
801 print -log" operation.
802
803
804
805 :Info: update_seg.install: us.install:
806 07/21/86 update_seg install operation
807
808
809 Syntax as a command:
810 us install io_seg -control_args
811
812
813 Function: This operation installs the modification defined in an io
814 segment.
815
816
817 Arguments:
818 io_seg
819 is an optional argument specifying the pathname of an existing io
820 segment defining the modification to be installed. If the final
821 entryname does not have an io suffix, then one is assumed. See
822 "Notes" below for a discussion of this argument.
823
824
825 Control arguments:
826 -severity N, -sv N
827 defines the severity level of fatal installation errors. All errors
828 whose severity is equal to or greater than N are treated as fatal
829 errors. N must be an integer from 1 to 5 inclusive. The default
830 severity is 1, making all installation errors fatal. Refer to
831 "Controlling the Fatality of Installation Errors" later in this
832 section for a description of the severity levels associated with the
833 various kinds of installation errors.
834 -stop
835 disables the automatic error recovery mechanism, causing update_seg
836 to stop when a fatal installation error occurs. Refer to
837 "Installation Errors" below for more information.
838
839
840 Notes: If an io_seg argument is given with the install operation, the
841 named io segment is reinitiated and it remains initiated after the
842 modification has been installed. Thus, all further update_seg
843 operations refer to this initiated io segment. If no io_seg argument
844 is given, then the modification defined in the currently-initiated io
845 segment is installed.
846
847
848 Any error codes which were set during a prior installation operation
849 are automatically cleared before beginning the installation. This
850 ensures that all errors which may be reported pertain to the current
851 installation operation.
852
853
854 Access required: The Multics Installation System calls entries in the
855 installation_tools_ gate in order to install Multics System Library
856 segments into rings 1-7. If the library maintainer does not have
857 access to this gate, then update_seg can install segments in rings from
858 the current ring of execution to ring 7.
859
860
861 Installation Errors: If an error occurs during the installation of a
862 modification, a message is printed to diagnose the error. Two types of
863 errors may occur: nonfatal errors and fatal errors. The diagnostic
864 message for a nonfatal error begins with a Warning caption, while that
865 for a fatal error begins with an Error caption.
866
867
868 Nonfatal errors do not stop the installation, but are merely diagnosed
869 as they occur so that the library maintainer can take corrective action
870 after the installation is complete.
871
872
873 Fatal errors have a more serious impact on the installation. Normally,
874 the occurrence of a fatal error stops the installation of the
875 modification, and automatically de-installs all portions of the
876 modification which were installed prior to the error. When the -stop
877 control argument is given, the occurrence of an error merely stops the
878 installation.
879
880
881 The -stop control argument should be used with care because stopping
882 the installation of a modification will probably leave the target
883 library in an inconsistent state. When -stop is used, the library
884 maintainer must recover from any installation errors as quickly as
885 possible to reduce this period of inconsistency. Because the normal
886 error recovery procedures minimize the period of library inconsistency
887 and are so fast and easy to use, the -stop control argument is not
888 recommended for general use.
889
890
891 Controlling the Fatality of Installation Errors: A given installation
892 error may be nonfatal or fatal, depending upon the severity level
893 associated with that error and upon the fatal severity level given in
894 the -severity control argument.
895
896
897 The Multics Installation System defines four severity levels, numbered
898 1 through 4. One of these severity levels is assigned to each possible
899 installation error, depending upon how severely that error impacts the
900 installation. Errors with a high severity level impact an installation
901 more severely than those with a lower severity. The errors which fall
902 into each severity level are described below:
903
904 severity 1
905 Errors incurred while: adding a name which is already on the target
906 segment; deleting a name or ACL entry which is not on the target
907 segment; or processing an archive with more than 100 components.
908 severity 2
909 Errors incurred while: adding an invalid ACL entry to the target
910 segment; adding a name which is already on another entry in the
911 target directory; setting the target segment's bit count, maximum
912 length attribute, or safety switch; deleting the final name from the
913 target segment; and freeing the names on the old segment.
914 severity 3
915 All other errors except for record quota overflows.
916 severity 4
917 Record quota overflow errors.
918
919
920 The library maintainer must determine which severity levels shown above
921 contain errors fatal to the installation being performed. The
922 maintainer should then set the fatal severity level for the
923 installation by using the -severity control argument.
924
925
926 Determination of the fatal severity level greatly depends on the type
927 of modification being installed. A severity 1 error occurring during
928 the modification of a heavily-used user search directory could have
929 severe consequences for the library users, and would probably warrant a
930 fatal severity level of 1. On the other hand, a severity 1 error
931 occurring during the installation of new information segments into a
932 documentation directory would have less impact on library users, since
933 no users would be depending upon the new segments. A fatal severity
934 level of 2 might be appropriate in this case.
935
936
937 Low fatal severity levels are recommended for general use. The
938 automatic error recovery for fatal errors is very fast and subsequent
939 reinstallation of the modification is easy do to. High fatal severity
940 levels should be used only in unusual circumstances and with extreme
941 caution.
942
943
944 Correcting Fatal Installation Errors: If a fatal installation error
945 occurs, the normal error recovery procedure automatically de-installs
946 all portions of the modification installed before the error occurred.
947 The library maintainer can follow one of the two strategies below to
948 correct the error:
949
950 1. If the error did not involve the definition of the modification
951 the contents attributes or pathnames of any of the segments in
952 the modification, then the library maintainer can correct the
953 cause of the error and reinstall the modification using the
954 install operation. An example of such an error is a record quota
955 overflow in the target directory, or a name duplication between
956 the target segment and an existing library entry.
957
958 2. If the error did involve the definition of the modification, then
959 the library maintainer must redefine the modification correctly in
960 a new io segment and reinstall the modification using the install
961 operation. An example of such an error is an attempt to place the
962 wrong name on a target segment causing a name duplication, or a
963 -delete_name control argument attempting to delete the final name
964 from a target segment.
965
966
967 If the -stop control argument was given with the install operation,
968 then the installation is stopped if a fatal error occurs without
969 de-installing whatever portions of the modification were installed
970 prior to the error. The library maintainer can follow one of three
971 strategies to correct the error:
972
973 1. If the error did not involve the modification definition, the
974 library maintainer can correct the error and continue the
975 installation by using the install operation.
976
977 2. If the error did not involve the modification definition, the
978 library maintainer can use the de_install operation to de-install
979 the modification until the error is corrected, and then use the
980 install operation to reinstall the modification.
981
982 3. If the error did involve the modification definition, the library
983 maintainer must use the de_install operation to de-install the
984 modification, must then redefine the modification correctly in a
985 new io segment, and install that segment using the install
986 operation.
987
988
989 Recovering From a Crash: If the system should crash during an
990 installation, or a fatal process error occur during an installation,
991 then the installation of the modification can be continued by using the
992 install operation. Alternately, parts of the modification installed
993 prior to the crash can be de-installed by using the de_install
994 operation.
995
996
997 While it is usually safe to attempt to de-install a modification after
998 a system crash, the de-installation will probably fail if the crash has
999 affected any Multics storage system directory referenced as part of the
1000 modification. If such a failure occurs, it is necessary to complete
1001 the de-installation manually by using the l_free_name,
1002 l_set_ring_brackets, l_set_acl, l_delete, l_delete_name, and l_rename
1003 commands.
1004
1005
1006
1007 :Info: update_seg.list: update_seg.ls: us.list: us.ls:
1008 07/21/86 update_seg list ls operation
1009
1010
1011 Syntax as a command:
1012 us ls io_seg -control_args
1013
1014
1015 Function: This operation creates an installation listing segment
1016 containing information about an io segment. The listing segment is
1017 created in the working directory. If the listed io segment is named
1018 io_seg.io, then its listing segment is named io_seg.il. The
1019 installation listing normally contains the following information items.
1020
1021
1022 1. The pathname of the io segment.
1023 2. The date and time at which the installation listing was created.
1024 3. The access identifier of the process which created the io segment.
1025 4. The version of update_seg used to create the io segment.
1026 5. The date and time at which the last creation, definition, or
1027 listing operation was performed on the io segment.
1028 6. If the modification has been installed, the access identifier of
1029 the process which installed the modification and the date and time
1030 of installation.
1031 7. If the modification has been de-installed, the access identifier
1032 of the process which de-installed the modification and the date
1033 and time of de-installation.
1034 8. If the io segment has been cleared see the description of
1035 "update_seg clear", the access identifier of the process which
1036 cleared the io segment and the date and time of clearing.
1037
1038
1039 9. The summary of the modification, if one was defined when the io
1040 segment was initiated.
1041 10. A list of the definition operations performed on the io segment.
1042 This list includes the pathnames of the target segment, old
1043 segment, and/or new segment for each definition operation.
1044 11. If the modification has been installed, a list of any errors which
1045 occurred during the installation.
1046 12. A description of the modification which includes the following
1047 information for each modification segment:
1048 a. The type of definition operation add delete replace or move
1049 and the pathnames of the target segment, old segment, and/or new
1050 segment given in the definition of each modification segment.
1051 b. A list of control arguments given in the definition operation.
1052 c. The names, ACL, and ring brackets to be placed on the target
1053 segment.
1054 d. The detailed information about each modification segment used to
1055 document the installation.
1056
1057
1058 Arguments:
1059 io_seg
1060 is an optional argument specifying the pathname of an existing io
1061 segment which is to be listed. If the final entryname does not have
1062 an io suffix, then one is assumed. See "Notes" below for a
1063 discussion of this argument.
1064
1065
1066 Control arguments:
1067 -brief, -bf
1068 suppresses item 12 above from the listing.
1069 -long, -lg
1070 appends to the listing a detailed description of the modification
1071 which includes the installation steps required to install each
1072 modification segment.
1073
1074
1075 Notes: If an io_seg argument is given with the list operation, the
1076 named io segment is reinitiated, and it remains initiated after the io
1077 segment has been listed. Thus, all further update_seg operations will
1078 refer to this initiated io segment. If no io_seg argument is given,
1079 then the currently-initiated io segment is listed, if one is initiated.
1080
1081
1082 The -brief and -long control arguments can be used together to provide
1083 a detailed description of the modification without the regular
1084 description outlined in item 12 above. The detailed description
1085 includes all of the information in the regular description. However,
1086 because of the length of the detailed description, it is often useful
1087 to have both the shorter regular description as a quick reference and
1088 the longer detailed description for an installation step reference.
1089
1090
1091
1092 :Info: update_seg.print: update_seg.pr: us.print: us.pr:
1093 07/21/86 update_seg print pr operation
1094
1095
1096 Syntax as a command:
1097 us pr io_seg -control_args
1098
1099
1100 Function: This operation prints information on the terminal about the
1101 modification defined in an io segment. One set of information is
1102 included for each segment of the modification. This information
1103 normally includes the following items.
1104
1105 1. The type of definition operation add delete replace or move,
1106 and the pathnames of the target segment, old segment, and/or new
1107 segment given in the definition of each modification segment.
1108
1109 2. A list of the control arguments given in the definition operation.
1110
1111 3. The names, ACL, and ring brackets to be placed on the target
1112 segment.
1113
1114 4. The detailed information about the modification segment to be
1115 included in Installations.log when the -log control argument was
1116 given in the definition operation.
1117
1118
1119 Arguments:
1120 io_seg
1121 is an optional argument which specifies the pathname of an existing
1122 io segment whose modification is to be printed. If the final
1123 entryname does not have an io suffix, then one is assumed. See
1124 "Notes" below for a discussion of this argument.
1125
1126
1127 Control arguments:
1128 -brief, -bf
1129 suppresses information items 2-4 given above from the printed
1130 output.
1131 -error, -er
1132 suppresses information about all modification segments except those
1133 that encountered an error during the most recent attempt to install
1134 or de-install the modification. The printed information includes
1135 the installation step in which the error occurred, and an error
1136 message describing the error.
1137
1138
1139 -log
1140 prints only the summary of the modification provided when the io
1141 segment was initiated.
1142 -long, -lg
1143 adds a list of the installation steps required to install each
1144 modification segment to the printed information.
1145
1146
1147 Notes: If an io_seg argument is given with the print operation, the
1148 named io segment is reinitiated and it remains initiated after the
1149 modification information has been printed. Thus, all further
1150 update_seg operations will refer to this initiated io segment. If no
1151 io_seg argument is given then the modification information for the
1152 currently-initiated io segment is printed.
1153
1154
1155 The -brief and -long control arguments can be used together to suppress
1156 information items 2-4 given in the list above while including a list of
1157 installation steps. Similarly, the -long and -error control arguments
1158 can be used together to print all of the installation steps, rather
1159 than just those in which an error occurred.
1160
1161
1162
1163 :Info: update_seg.print_defaults: update_seg.pd: us.print_defaults: us.pd:
1164 07/21/86 update_seg print_defaults pd operation
1165
1166
1167 Syntax as a command:
1168 us pd io_seg
1169
1170
1171 Function: This operation prints the global default ACL, ring brackets,
1172 and documentation directory. It also prints the default values
1173 associated with an io segment. The default documentation directory is
1174 printed only if different from the working directory.
1175
1176
1177 Arguments:
1178 io_seg
1179 is an optional argument which specifies the pathname of an existing
1180 io segment whose defaults are to be printed. If the final entryname
1181 does not have an io suffix, then one is assumed.
1182
1183
1184 Notes: If an io_seg argument is given with the print_defaults
1185 operation, the named io segment is reinitiated, and remains initiated
1186 after the defaults have been printed. Thus, all further update_seg
1187 operations will refer to this initiated io segment. If no io_seg
1188 argument is given, then the defaults of the initiated io segment are
1189 printed if one is initiated.
1190
1191
1192
1193 :Info: update_seg.move: update_seg.mv: us.move: us.mv:
1194 07/21/86 update_seg move mv operation
1195
1196
1197 Syntax as a command:
1198 us mv old_seg target_seg -control_args
1199
1200
1201 Function: This operation defines a segment which is a library segment
1202 to be moved to another library directory as part of a modification.
1203 The definition is appended to the currently-initiated io segment. The
1204 following steps are required for the most common case of the move
1205 operation.
1206
1207
1208 1. Get the unique id of the segment to be moved the old segment.
1209 2. Get the names on the old segment.
1210 3. Get the ACL on the old segment.
1211 4. Get the ring brackets on the old segment.
1212 5. Gather detailed information about the old segment for
1213 documentation of the installation.
1214 6. Create a uniquely-named target segment in the other library, and
1215 copy the contents of the old segment into this target segment.
1216 7. Set the ring brackets on the target segment to those on the old
1217 segment.
1218 8. Set the ACL on the target segment to that on the old segment.
1219 9. Add a unique name to the old segment.
1220
1221
1222 10. Free the names on the old segment.
1223 11. Add the old segment's names to the target segment.
1224 12. Remove the unique name from the target segment.
1225 13. Document the movement of the library segment.
1226
1227
1228 Arguments:
1229 old_seg
1230 is the pathname of the segment to be moved. A relative or absolute
1231 pathname may be given.
1232 target_seg
1233 is the pathname specifying where the old segment is to be moved to.
1234 A relative or absolute pathname may be given, and the Multics equal
1235 convention may be used to equate components in the final entrynames
1236 of the old_seg and target_seg pathnames. Note that an error will
1237 occur if the final entryname of the target_seg pathname is not one
1238 of the names placed on the target segment as it is installed.
1239
1240
1241 Control arguments:
1242 -acl mode1 User_id1 ... modeN User_idN
1243 defines the access control list ACL to be placed on the target
1244 segment. Normally the default ACL is used. Each access mode is
1245 paired with the access control name which follows. modeI is any
1246 valid access mode for segments eg r re rw rew null n. User_idI
1247 is an access control name that must be of the form
1248 Person_id.Project_id.tag. Missing components in the access control
1249 name are assumed to be "*". If the last modeI has no User_idI
1250 following it, the user's Person_id and Project_id are assumed.
1251 -add_name names, -an names
1252 defines a list of names to be added to the target segment, where
1253 names are one or more entrynames.
1254
1255
1256 -archive, -ac
1257 specifies that the segment being defined in a definition operation
1258 is an archive, and that the names of its archive components are to
1259 be added to the target segment of the definition operation.
1260 Normally the archive component names are not added to the target
1261 segment.
1262 -defer, -df
1263 specifies that the installation subroutines which gather information
1264 about the segments in a definition operation should defer their
1265 information gathering until the installation operation is performed.
1266 Thus, changes made to the segment after the modification is defined
1267 will be reflected in the installed segment. Normally, name and ACL
1268 changes made between the definition and installation operations are
1269 not reflected in the installed target segment. Segment replacements
1270 during this period cause a fatal installation error.
1271
1272
1273 -delete_acl User_ids, -da User_ids
1274 defines a list of ACL entries which are to be removed from the ACL
1275 of the target segment of a definition operation. A User_id is an
1276 access control name that must be of the form
1277 Person_id.Project_id.tag. Missing components in the access control
1278 name are assumed to be "*".
1279 -delete_name names, -dn names
1280 defines a list of names to be removed from the target segment of a
1281 definition operation, where names are one or more entrynames.
1282 -initial_acl, -iacl
1283 specifies that the Initial ACL IACL for segments of the target
1284 directory is to be placed on the target segment.
1285 -log
1286 specifies that detailed information about the installation of the
1287 target segment is to be logged in Installations.log.
1288
1289
1290 -max_length N, -ml N
1291 specifies that the maximum length attribute of the target segment of
1292 a definition operation is to be set. If N > 0, the maximum length
1293 is set of N words. If N = 0, the maximum length is set to the
1294 current length of the segment being installed. If N is omitted, the
1295 maximum length is set to sys_info$max_seg_size. If -max_length is
1296 omitted, the maximum length is set to sys_info$default_max_length
1297 for regular segments, and to the current length of the segment being
1298 installed for special segments. See -special_seg below for
1299 information about special segments.
1300 -name names, -nm names
1301 defines the list of names to be placed on the target segment, where
1302 names are one or more entrynames. Normally, the names on the new
1303 segment are placed on the target segment.
1304
1305
1306 -ring_brackets r1 r2 r3, -rb r1 r2 r3
1307 defines a set of ring brackets to be placed on the target segment,
1308 where r1 is the write bracket, r2 is the read bracket, and r3 is the
1309 gate bracket. If r2 is omitted, it is set to the maximum of the
1310 following values: the write bracket, the current validation level,
1311 or 5. If r3 is omitted, it is set to the maximum of the following
1312 values: the read bracket, the current validation level, or 5. It
1313 may not be specified unless r2 is also specified. Normally, the
1314 default ring brackets are placed on the target segment.
1315
1316
1317 -set_acl mode1 User_id1 ... modeN User_idN,
1318 -sa mode1 User_id1 ... modeN User_idN
1319 defines a list of ACL entries which are to be added to the ACL of
1320 the target segment. modeI is any valid access mode for segments
1321 eg r re rw rew null n. User_idI is an access control name that
1322 must be of the form Person_id.Project_id.tag. Missing components in
1323 the access control name are assumed to be "*". If the last modeI
1324 has no User_idI following it, the user's Person_id and Project_id
1325 are assumed.
1326 -special_seg, -ss
1327 defines the target segment of a definition operation as a special
1328 segment. The properties of special segments are described below
1329 under "Special Segments."
1330
1331
1332 Notes: Just as in a delete operation, the old segment in a move
1333 operation is not deleted at the time of the installation operation.
1334 Instead, the old segment's names are freed, and a unique name is placed
1335 on the segment to mark it as a candidate for deletion by the
1336 library_cleanup command at a later date.
1337
1338
1339 Special Segments: The -special_seg control argument is used to reduce
1340 the installation window for the user-visible segments of a
1341 modification. For example, if a modification contains two bound
1342 segments, one of which calls the other, then it is important to reduce
1343 the time between the installation of the first segment and the
1344 installation of the second. Otherwise, users of the first segment
1345 could receive errors when it tried to reference the second.
1346
1347
1348 To reduce the length of user-observable installation windows, the
1349 segments of a modification being installed in user search directories
1350 can be defined as special segments which have the following properties:
1351
1352
1353 1. The final installation of all special segments adding names to
1354 these segments is deferred until all regular segments have been
1355 installed.
1356
1357 2. The de-installation of a modification causes the regular segments
1358 which were installed to be deleted from the library. Special
1359 segments are renamed instead of being deleted.
1360
1361 3. The default setting for the maximum length attribute of segments
1362 differs for special segments from that used for regular segments.
1363 Special segments use the current length of the segment being
1364 installed as the default maximum length. Regular segments use
1365 sys_info$default_max_length.
1366
1367
1368 Deferring the final installation of special segments until the last
1369 possible moment provides several desirable advantages. If a fatal
1370 error occurs while installing a regular segment, no special segments
1371 will have been installed and the user-visible portions of the libraries
1372 will remain in a consistent state. In addition, the installation
1373 window for special segments is shortened by grouping them together at
1374 the end of the installation, because there are fewer segments going
1375 through the final installation step adding names at the same time.
1376 This further reduces the user's exposure to library inconsistencies.
1377
1378
1379 Special segments cannot be deleted by a de-installation operation
1380 because some users may being using them. However, renaming the special
1381 segments prevents more users from using them after they have been
1382 de-installed.
1383
1384
1385
1386 :Info: update_seg.replace: update_seg.rp: us.replace: us.rp:
1387 07/21/86 update_seg replace rp operation
1388
1389
1390 Syntax as a command:
1391 us rp new_seg old_seg target_seg -control_args
1392
1393
1394 Function: This operation defines a segment which is to replace another
1395 segment in a library as part of a modification. The definition is
1396 appended to the currently-initiated io segment. The following steps
1397 are required for the most common case of the replace operation.
1398
1399
1400 1. Get the unique id of the segment to be replaced the old segment.
1401 2. Get the names on the old segment.
1402 3. Get the ACL on the old segment.
1403 4. Get the ring brackets on the old segment.
1404 5. Get the unique id of the segment to replace the old segment the
1405 new segment.
1406 6. Get the names on the new segment.
1407 7. Gather detailed information about the new segment for
1408 documentation of the installation.
1409 8. Create a uniquely-named target segment in the library, and copy
1410 the contents of the new segment into this target segment.
1411 9. Set the ring brackets on the target segment to those on the old
1412 segment.
1413 10. Set the ACL on the target segment to that on the old segment.
1414
1415
1416 11. Add a unique name to the old segment.
1417 12. Free the names on the old segment.
1418 13. Add the new segment's names to the target segment.
1419 14. Remove the unique name from the target segment.
1420 15. Document the replacement of the library segment.
1421
1422
1423 Arguments:
1424 new_seg
1425 is the pathname of the new segment to be installed. A relative or
1426 absolute pathname can be given.
1427 old_seg
1428 is the pathname of the library segment which is to be replaced. A
1429 relative or absolute pathname may be given, and the Multics equal
1430 convention may be used to equate components in the final entrynames
1431 of the new_seg and old_seg pathnames. Note that, if the target_seg
1432 argument is omitted, an error will occur if the final entryname of
1433 the old_seg pathname is not one of the names placed on the target
1434 segment as it is installed.
1435
1436
1437 target_seg
1438 is the optional pathname of the target segment, if this differs from
1439 the pathname of the old segment. A relative or absolute pathname
1440 may be given, and the Multics equal convention may be used to equate
1441 components in the final entrynames of the target_seg and old_seg
1442 pathnames. Normally the pathname of the old segment is formed by
1443 using the directory portion of old_seg and the final entryname
1444 portion of new_seg i.e. directory old_seg>entry new_seg.
1445 Note that an error will occur if the final entryname of the
1446 target_seg pathname is not one of the names placed on the target
1447 segment as it is installed.
1448
1449
1450 Control arguments:
1451 -acl mode1 User_id1 ... modeN User_idN
1452 defines the access control list ACL to be placed on the target
1453 segment. Normally the default ACL is used. Each access mode is
1454 paired with the access control name which follows. modeI is any
1455 valid access mode for segments eg r re rw rew null n. User_idI
1456 is an access control name that must be of the form
1457 Person_id.Project_id.tag. Missing components in the access control
1458 name are assumed to be "*". If the last modeI has no User_idI
1459 following it, the user's Person_id and Project_id are assumed.
1460 -add_name names, -an names
1461 defines a list of names to be added to the target segment, where
1462 names are one or more entrynames.
1463
1464
1465 -archive, -ac
1466 specifies that the segment being defined in a definition operation
1467 is an archive, and that the names of its archive components are to
1468 be added to the target segment of the definition operation.
1469 Normally the archive component names are not added to the target
1470 segment.
1471 -defer, -df
1472 specifies that the installation subroutines which gather information
1473 about the segments in a definition operation should defer their
1474 information gathering until the installation operation is performed.
1475 Thus, changes made to the segment after the modification is defined
1476 will be reflected in the installed segment. Normally, name and ACL
1477 changes made between the definition and installation operations are
1478 not reflected in the installed target segment. Segment replacements
1479 during this period cause a fatal installation error.
1480
1481
1482 -delete_acl User_ids, -da User_ids
1483 defines a list of ACL entries which are to be removed from the ACL
1484 of the target segment of a definition operation. A User_id is an
1485 access control name that must be of the form
1486 Person_id.Project_id.tag. Missing components in the access control
1487 name are assumed to be "*".
1488 -delete_name names, -dn names
1489 defines a list of names to be removed from the target segment of a
1490 definition operation, where names are one or more entrynames.
1491 -initial_acl, -iacl
1492 specifies that the Initial ACL IACL for segments of the target
1493 directory is to be placed on the target segment.
1494 -log
1495 specifies that detailed information about the installation of the
1496 target segment is to be logged in Installations.log.
1497
1498
1499 -max_length N, -ml N
1500 specifies that the maximum length attribute of the target segment of
1501 a definition operation is to be set. If N > 0, the maximum length
1502 is set of N words. If N = 0, the maximum length is set to the
1503 current length of the segment being installed. If N is omitted, the
1504 maximum length is set to sys_info$max_seg_size. If -max_length is
1505 omitted, the maximum length is set to sys_info$default_max_length
1506 for regular segments, and to the current length of the segment being
1507 installed for special segments. See -special_seg below for
1508 information about special segments.
1509 -name names, -nm names
1510 defines the list of names to be placed on the target segment, where
1511 names are one or more entrynames. Normally, the names on the new
1512 segment are placed on the target segment.
1513
1514
1515 -old_name, -onm
1516 specifies that the names on the old segment are to be placed on the
1517 target segment. Normally, the names on the new segment are placed
1518 on the target segment.
1519 -ring_brackets r1 r2 r3, -rb r1 r2 r3
1520 defines a set of ring brackets to be placed on the target segment,
1521 where r1 is the write bracket, r2 is the read bracket, and r3 is the
1522 gate bracket. If r2 is omitted, it is set to the maximum of the
1523 following values: the write bracket, the current validation level,
1524 or 5. If r3 is omitted, it is set to the maximum of the following
1525 values: the read bracket, the current validation level, or 5. It
1526 may not be specified unless r2 is also specified. Normally, the
1527 default ring brackets are placed on the target segment.
1528
1529
1530 -set_acl mode1 User_id1 ... modeN User_idN,
1531 -sa mode1 User_id1 ... modeN User_idN
1532 defines a list of ACL entries which are to be added to the ACL of
1533 the target segment. modeI is any valid access mode for segments
1534 eg r re rw rew null n. User_idI is an access control name that
1535 must be of the form Person_id.Project_id.tag. Missing components in
1536 the access control name are assumed to be "*". If the last modeI
1537 has no User_idI following it, the user's Person_id and Project_id
1538 are assumed.
1539 -special_seg, -ss
1540 defines the target segment of a definition operation as a special
1541 segment. The properties of special segments are described below
1542 under "Special Segments."
1543
1544
1545 Notes: The -name and -old_name control arguments are mutually
1546 exclusive. If both are given in a replace operation, then the last one
1547 given is used.
1548
1549
1550 Just as in a delete operation, the old segment in a replace operation
1551 is not deleted at the time of the installation operation. Instead, the
1552 old segment's names are freed, and a unique name is placed on the
1553 segment to mark it as a candidate for deletion by the library_cleanup
1554 command at a later date.
1555
1556
1557 Special Segments: The -special_seg control argument is used to reduce
1558 the installation window for the user-visible segments of a
1559 modification. For example, if a modification contains two bound
1560 segments, one of which calls the other, then it is important to reduce
1561 the time between the installation of the first segment and the
1562 installation of the second. Otherwise, users of the first segment
1563 could receive errors when it tried to reference the second.
1564
1565
1566 To reduce the length of user-observable installation windows, the
1567 segments of a modification being installed in user search directories
1568 can be defined as special segments which have the following properties:
1569
1570
1571 1. The final installation of all special segments adding names to
1572 these segments is deferred until all regular segments have been
1573 installed.
1574
1575 2. The de-installation of a modification causes the regular segments
1576 which were installed to be deleted from the library. Special
1577 segments are renamed instead of being deleted.
1578
1579 3. The default setting for the maximum length attribute of segments
1580 differs for special segments from that used for regular segments.
1581 Special segments use the current length of the segment being
1582 installed as the default maximum length. Regular segments use
1583 sys_info$default_max_length.
1584
1585
1586 Deferring the final installation of special segments until the last
1587 possible moment provides several desirable advantages. If a fatal
1588 error occurs while installing a regular segment, no special segments
1589 will have been installed and the user-visible portions of the libraries
1590 will remain in a consistent state. In addition, the installation
1591 window for special segments is shortened by grouping them together at
1592 the end of the installation, because there are fewer segments going
1593 through the final installation step adding names at the same time.
1594 This further reduces the user's exposure to library inconsistencies.
1595
1596
1597 Special segments cannot be deleted by a de-installation operation
1598 because some users may being using them. However, renaming the special
1599 segments prevents more users from using them after they have been
1600 de-installed.
1601
1602
1603
1604 :Info: update_seg.set_defaults: update_seg.sd: us.set_defaults: us.sd:
1605 07/21/86 update_seg set_defaults sd operation
1606
1607
1608 Syntax as a command:
1609 us sd -control_args
1610
1611
1612 Function: This operation sets the global default ACL, ring brackets,
1613 and documentation directory associated with an installation object io
1614 segment.
1615
1616
1617 Control arguments:
1618 -acl mode1 User_id1 ... modeN User_idN
1619 defines a new global default access control list ACL. This ACL is
1620 placed on all segments being added to the library if -acl is not
1621 given in the "update_seg add" operation. modeI is any valid access
1622 mode for segments eg r re rw rew null n. User_idI is an access
1623 control name that must be of the form Person_id.Project_id.tag.
1624 Missing components in the access control name are assumed to be "*".
1625 If the last modeI has no User_idI following it, the user's Person_id
1626 and Project_id are assumed.
1627
1628
1629 -ring_brackets r1 r2 r3, -rb r1 r2 r3
1630 defines a new set of global default ring brackets. These ring
1631 brackets are placed on all segments being added to the library if
1632 -ring_brackets is not given in the "update_seg add" operation. r1
1633 is the write bracket, r2 is the read bracket, and r3 is the gate
1634 bracket. If r2 is omitted, it is set to the maximum of the
1635 following values: the write bracket, the current validation level,
1636 or 5. If r3 is omitted, it is set to the maximum of the following
1637 values: the read bracket, the current validation level, or 5. It
1638 may not be specified unless r2 is also specified.
1639 -set_log_dir path, -sld path
1640 defines the directory identified by path as the directory containing
1641 the installation log and installation info segments. These segments
1642 are described further under "Automatic Documentation" below.
1643
1644
1645 Notes: If one or more control arguments listed above are omitted, then
1646 the corresponding global default value remains unchanged.
1647
1648
1649 Automatic Documentation: The directory defined in a -set_log_dir
1650 control argument is called the documentation directory. Two types of
1651 information about a modification are logged in segments contained in
1652 this directory.
1653
1654
1655 Installations.info
1656 A summary of each the modification is inserted at the beginning of
1657 Installations.info. The library maintainer specifies this summary
1658 information in the update_seg initiate operation, via the -log
1659 control argument. This is a segment designed to inform users of
1660 recent changes to the libraries.
1661 Installations.log
1662 Detailed information about which segments and bound segment
1663 components are changed by the modification is appended to
1664 Installations.log, along with the summary described above. This log
1665 contains a permanent record of all installations.
1666
1667
1668 Use of these documentation segments is shared among several different
1669 update_seg installers by using a lock word in the segment
1670 Installations.lock. All of these segments or links to the segments
1671 must appear in the log directory.
1672
1673
1674 :Info: update_seg.examples: us.examples:
1675 07/21/86 Examples of update_seg Operation
1676
1677
1678 Examples: The following are typical examples of terminal sessions
1679 using update_seg to modify segments. Brief explanations of each
1680 command line typed by the user are given below each example.
1681
1682
1683 Example 1
1684
1685
1686 ! update_seg initiate >udd>Multics>example1
1687 ! update_seg add >udd>Multics>seg1 >sss>seg1
1688 ! update_seg replace >udd>Multics>seg2 >sss>seg2
1689 ! update_seg delete >sss>seg3
1690 ! update_seg move >sss>seg4 >unbundled>seg4
1691 ! update_seg install
1692 Installation beginning.
1693 Installation complete.
1694 ! update_seg list
1695 ! eor example1.il
1696 1 request signalled, 0 already queued.
1697
1698 Example 1 creates and initiates an io segment called example1.io in the
1699 directory >udd>Multics, using global default values for the default ACL
1700 and ring brackets. It defines a modification consisting of four
1701 segments. seg1 is to be added to >sss, with default ACL and ring
1702 brackets. seg2 is to replace segment >sss>seg2; the old segment's ACL
1703 and ring brackets are placed on the target segment. >sss>seg3 is to be
1704 deleted. >sss>seg4 is to be moved to the directory >unbundled. After
1705 definition the modification, it is installed. A listing is created
1706 showing the operations performed during the library modification, along
1707 with any errors which may have occurred. The listing in example1.il is
1708 then dprinted.
1709
1710
1711
1712 Example 2
1713
1714
1715 ! us initiate example2 -acl re User.Multics -rb 4 5 5
1716 ! us add >udd>Multics>seg5 >sss>seg5
1717 ! us add seg6 >sss>seg6 -acl re *.Multics -rb 1 5 5
1718 ! us replace seg7 >sss>== -acl re User.Multics n * -ss -log
1719 ! us install
1720 Installation beginning.
1721 Copying special target segments.
1722 Adding names to special target segments.
1723 Installation complete.
1724
1725 Example 2 creates an io segment called example2.io, setting the default
1726 ACL to re User.Multics and the default ring brackets to 4,5,5. Adds
1727 seg5 to the directory >sss, using the default ACL and ring brackets.
1728 Adds seg6 to >sss, with an ACL of re *.Multics.* and ring brackets
1729 1,5,5. Replaces >sss>seg7 with a new version, with an ACL of
1730 re User.Multics.* and null *.*.* on the target segment. Put the ring
1731 brackets of >sss>seg7 on the target segment. Also treat the target
1732 segment as a special segment and log the modification of this segment
1733 in Installations.log.
1734
1735
1736
1737 Example 3
1738
1739
1740 ! update_seg initiate >udd>Multics>example1 -restart
1741 ! update_seg de_install
1742 De-installation beginning.
1743 Non-special target segments deleted.
1744 De-installation complete.
1745 ! update_seg de_install example2
1746 De-installation beginning.
1747 Names removed from special target segments.
1748 Non-special target segments deleted.
1749 De-installation complete.
1750 ! update_seg list -long
1751
1752 Reinitiates example1.io, the io segment created in Example 1 above.
1753 De-installs the modification defined in this io segment. Reinitiates
1754 example2.io, io segment created in Example 2. De-installs the
1755 modification defined in this io segment. Creates a listing segment,
1756 example2.il.
1757
1758
1759
1760 Example 4
1761
1762
1763 ! us initiate library -log
1764 Input.
1765 ! MCR 128: Fix bug in the delete command bound_fscom1_
1766 ! which prevented segments whose copy switch is on from
1767 ! being deleted.
1768 ! .
1769 ! us rp bound_fscom1_.s.archive >ldd>sss>s== -archive
1770 ! us rp bound_fscom1_.archive >ldd>sss>o>== -archive
1771 ! us rp bound_fscom1_ >sss>== -ss -log
1772 ! us install
1773 Installation beginning.
1774 Copying special target segments.
1775 Adding names to special target segments.
1776 Installation complete.
1777
1778 Example 1 creates and initiates a new io segment called library.io.
1779 The -log control argument is used to add a summary of the modification
1780 to the io segment. This summary is inserted at the top of
1781 Installations.info, and appended to the end of Installations.log when
1782 the modification is installed. The modification replaces
1783 >ldd>sss>s>bound_fscom1_.s.archive, and
1784 >ldd>sss>o>bound_fscom1_.archive. Archive component names to the
1785 target archive segments, and the old segment's ACL and ring brackets
1786 are used. The modification replaces >sss>bound_fscom1_, logging the
1787 replacement of this segment in Installations.log and treating the
1788 target segment as a special segment.