.MH "Subsystem Management" This section outlines the day-to-day responsibilities of the Subsystem Manager: adding and removing user accounts, keeping track of local hardware configuration changes, maintaining local tools, etc. .SH "Adding and Deleting Users" Adding and deleting Subsystem user accounts boils down to the maintenance of one file and one directory. .pp The list of authorized users is addressed by the template "=userlist=". On a standard Subsystem, it resides in the file //extra/users. There is one line in the user list corresponding to each authorized Subsystem user. Users may appear in any order in the user list, although conventionally it is kept sorted alphabetically. The format of a line in the user list is as follows: .sp .ne 5 .in +5 .nf Columns Information [cc]mc | 1-32 User's login name, in upper case, left- [cc]mc justified, blank-padded [cc]mc | 33 Blank 34-80 User's name and commentary information .sp .ne 4 .ti -5 Example: .sp 123456789012345678901234567890123456789... BURDELL George P. Burdell (Development) [cc]mc .sp .in -5 .fi Whenever someone is added to the Subsystem user community, an appropriate entry must be made in "=userlist=". Whenever a user is no longer authorized to use the system, his entry must be removed. .pp Each Subsystem user possesses a "profile" directory, which must be created for him by the Subsystem Manager. When adding an account, create the profile directory with the [cc]mc | command [cc]mc .be mkdir =vars=/ -o .ee [cc]mc | if it is a password directory or just .be mkdir =vars=/ sacl =vars=/ =adlurw $rest=lu .ee if it is an ACL protected directory. [cc]mc "" represents the login name of the new user. "" represents a standard file system owner password, which must be cited by the user when he enters the [cc]mc | Subsystem if his variables directory is password protected. [cc]mc Example: .be mkdir =vars=/gpb -o sesame .ee When a user is removed from the system, his profile directory must be deleted. This can be done most conveniently with the 'del' command: .be del -sd =vars=/: .ee For example, .be del -sd =vars=/gpb:sesame .ee In addition to the above measures for removing a user's account, the Subsystem Manager should check for any undelivered mail, gossip messages, or news articles. See the [bf Operation of Communications Systems] subsection below. .SH "Specifying Local Hardware Configuration" The screen editor 'se' and a number of other programs that employ the virtual terminal handler library need to know the type and make of the terminals attached to each AMLC line on the system. This information is contained in the terminal list, which resides in the file "=termlist=" (nominally "//extra/terms"). Each line of the terminal list has the following format: .sp .ne 11 .in +5 .nf Columns Information 1-3 Octal AMLC line number (000-177) 4 Blank 5-9 Three digit decimal user number of associated process, in parentheses 10 Blank 11-16 Terminal type (as recognized by the Subsystem); blank if unknown 17 Blank 18-80 Comments (usually physical location of terminal, etc.) .sp .ne 4 .ti -5 For example: .sp .ne 2 12345678901234567890... 007 (009) b200 George Burdell's office (Room 1729) .sp .in -5 .fi The contents of the "=termlist=" file must be kept up-to-date, or the 'e', 'whereis', 'se', and 'term_type' commands will cease to operate properly. .SH "Adding Terminal Types" [cc]mc | To extend the terminal type knowledge of the Subsystem, there are [cc]mc three places where changes need to be made in Subsystem files. These locations are the "=ttypes=" file, the "=vth=" directory, and various files under the screen editor directory, "=src=/spc/se.u". [cc]mc | In all cases, the mnemonic for the new terminal may not be longer than six characters. .# This is a bozo restriction, but c'est la vie... [cc]mc .pp The "=ttypes=" file contains the terminal's general attributes. Its format consists of a mnemonic for the terminal name, the full terminal name, and then a series of flags. These flags currently indicate whether the terminal type is supported by 'se', whether the terminal type is supported by the VTH package, and whether the terminal type represents an upper-case only terminal. .pp The file "=src=/spc/se.u/how_to_add_terminal_types" gives the details on adding new terminal types to the screen editor. Basically, new code must be added for the cursor movement routines and the editor must be recompiled and installed so that it incorporates the new code. [cc]mc | Also, the screen editor's 'usage' routine, as well as the Reference Manual entry, should be updated to include the mnemonic of the new terminal. [cc]mc .pp To add a new terminal type to the VTH package, an initialization file must be created in the "=vth=" directory, with the same name as the mnemonic that you have chosen for that terminal type. To find out what the format and contents of this file should be, please refer to the other files in that directory for examples. .pp [cc]mc * [cc]mc .SH "Adding Local Tools and Library Routines" When the Subsystem is used for program development, there is a tendency for an installation to collect a set of locally-useful tools. Here are a few suggestions on how to incorporate these local tools into the Subsystem environment. .pp Of course the primary repository for local commands is the directory 'lbin'. The Georgia Tech 'lbin' is supplied on the release tape as an example of a local command library, and because some of the commands contained therein may be of general use. To place a local tool in 'lbin', simply copy its object code into the directory and use the 'chat' command to make sure it is readable by [cc]mc | all users, or if the 'lbin' is ACL protected then the command will automatically be readable. [cc]mc .pp Since the command search rule employed by the command interpreter may be changed by the user, any number of local command directories may be created. For example, a directory named 'games' might be created for the purpose of keeping employees out of the local arcade at lunchtime. A search rule including this directory might be .be ^int,^var,&,=lbin=/&,=bin=/&,//games/& .ee Any of the programs in 'games' may then be invoked without need for using their full pathnames. .pp Of course, local subprogram libraries may also be created at will. As with standard Primos, the only steps necessary to make such libraries accessible are to place them in 'lib' and make them readable by all users. .SH "Adding Local Documentation" If local tools and libraries are added to the Subsystem (as outlined above), there will be a need for some means of documenting them. Sections three and four of the Reference Manual are provided for this purpose. .pp Section three of the Manual deals with local commands. To document such a command, one places a standard documentation file in "=doc=/man/s3" and uses "=doc=/build/rebuild" to place a formatted copy in "=doc=/fman/s3". The documentation may then be extracted by the 'help' command, or printed with the entire manual by executing "=doc=/print/man". .pp A standard documentation file for a command has several distinguishing characteristics. First, the documentation for a tool named "xxx" resides in a file named "xxx.d". Second, the structure of the file's contents is determined by a number of standard text formatter macro commands. Each macro begins a separate subject in a manual entry. They must appear in the following order: ".hd" (heading), ".ds" (description), ".es" (examples), ".fl" (files used), ".me" (messages issued), ".bu" (bugs and deficiencies), and ".sa" (see also). If a section is empty, it should be omitted entirely. .pp Once a documentation file has been entered, it must be formatted and the formatted copy placed in a separate directory. The shell program "=doc=/build/rebuild" has been provided for this purpose. An example: .be =doc=/build/rebuild s3 xxx .ee This would format the file "=doc=/man/s3/xxx.d" and place the result in "=doc=/fman/s3/xxx.d", where it may be accessed by 'help' and 'usage'. .pp Section four of the Manual deals with local library subprograms. The documentation procedure for subprograms is similar to that for major tools; an unformatted copy of the documentation is placed in "=doc=/man/s4", and a formatted copy in "=doc=/fman/s4". Again, this makes the documentation available through 'help'. .pp Formatter macros for library routine documentation differ somewhat from those for command documentation. In order, they are: ".hd" (header), ".fs" (function of subprogram), ".im" (implementation sketch), ".am" (arguments modified by subprogram), ".ca" (other subprograms called by this subprogram), ".bu" (bugs or deficiencies), and ".sa" (see also). Again, if a section is empty, it should be omitted entirely. .pp The rebuild procedure for subprogram documentation is very similar to that for command documentation; simply use "s4" in place of "s3" in the "rebuild" command. [cc]mc | .SH "Operation of the 'Cron' Program" One of the new features of Version 9 of Software Tools is the 'cron' program, which allows the system administrator to arrange for the computer to automatically do tasks of a periodic nature. The manual entry for 'cron' (help cron) will give you the information you need in setting up 'cron'. As distributed, "=cronfile=", contains an example entry and a brief description of what cronfile entries should look like, and "=system=/cron.comi" contains an example startup file to initialize 'cron'. 'Cron' executes as an ordinary Software Tools user so it must have an entry in "=varsdir=" and "=userlist=" (see [bf Adding and Deleting Users] in this section). The 'cron' user must have all permission to the directory "=crondir=". As supplied, 'cron' expects to be run as the system administrator with an ACL protecting "=crondir=" ("=crondir=" is protected with SYSTEM having $all access and everyone else has "list" and "use" privileges). .pp The supplied Primos routine SPH should be used to start 'cron'. The following command should be entered at the console or placed in the Primos cold start command file ('c_prmo' or 'primos.comi'): .be SPH SYSTEM>CRON.COMI -U -P -V 1 -G .ee where is the name under which 'cron' should run, is 'cron's login project, and is the list of file system groups with which the 'cron' user should be associated. For example, the following will startup 'cron' with all the default attributes and no groups: .be SPH SYSTEM>CRON.COMI -U SYSTEM -P DEFAULT -V 1 -G .ee [cc]mc .SH "Operation of Communications Systems" The Subsystem provides three different means of passing information from user to user: the postal service, the grapevine, and the news service. .PH "Postal Service" Most electronic communication between Subsystem users is accomplished through the mail system. The 'mail' command stores arbitrary messages in the directory "=mail=" (nominally "//extra/mail"), from where they may be retrieved by the addressee at a later time. All letters are postmarked with the time of mailing and the login name of the sender. Whenever a user enters the Subsystem via 'swt', he is informed if there is any undelivered mail addressed to him. .PH "Grapevine" 'Mail' is not real-time; a letter sent is generally not received until [cc]mc | the next time a user enters the Subsystem, or if the user has set his mail notification in the Shell, the next time the Shell notifies him. [cc]mc The "grapevine" managed by the 'to' command alleviates some of this problem. Messages sent from user to user via 'to' are stored in the directory "=gossip=" (nominally "//extra/gossip"), which is searched by the command interpreter before executing each terminal-level command. Thus, the delay between sending a message with 'to' and its receipt by the addressee is no longer than the longest time he spends executing a command. Since users typically spend a great deal of time text editing, the screen editor has also been given the ability to display a message sent by 'to'. See the "om" command in 'se' for details. .PH "News Service" Occasionally an item of general interest or special importance must be delivered to the user community at large. The Subsystem news service provides a means of delivering these articles, while making an archival copy of them and placing their headlines in an index file for later reference. .pp Since the disk space required to store undelivered news articles may be prohibitively expensive, users who wish to receive news must "subscribe" to the service with the 'subscribe' command. This need only be done once in an account's lifetime. The list of subscribers may be found in the file "=news=/subscribers". .pp News articles are published with the 'publish' command. 'Publish' takes one file name argument. The named file is copied into the news boxes ("=news=/delivery/") of all subscribers, an archival copy is made in "=news=/articles", and the first line is entered into the index file "=news=/index" for later reference. .pp News articles that were published incorrectly or are outdated may be removed with the 'retract' command. 'Retract' can remove one or more articles at one time by specifying the article numbers as arguments. A notice of retraction for each article removed is placed in the news boxes of all subscribers who have seen the retracted article; subscribers who have not seen a retracted article are not notified of the retraction. Since removal of outdated news articles is not of great importance, such articles may be retracted quietly by using the "-q" option. .pp When a subscriber enters the Subsystem, he is informed if there is any news he has not yet seen. He may then retrieve the article with the 'news' command. At any time, he may also use the 'news' command to review the index or any archived articles. .SH "Modifying the Dictionary of English Words" The dictionary of words supplied with the Subsystem is still rather incomplete, and may require additions from time to time. [cc]mc | .pp The template =new_words= is commented out in the system template file. If you make it an active template (by removing the comment symbol), the 'spell' program will write into =new_words= any words it finds which are not in the dictionary. (=new_words= is defined to be =aux=/spelling/new_words.) You may then wish to periodically clean up the file as follows: .be cd =aux=/spelling sort new_words | uniq >new_words .ee which will sort the file and remove duplicate entries. You can then go through the file with a dictionary, and remove words which are misspelled. .pp To add new words to the dictionary, the following procedure is recommended. .pp Obtain a list of words to be added, or use =new_words= as described above (or both). [cc]mc Obtain from each word as many derivative words as possible, by changing prefixes and suffixes, forming compounds, etc. Check each of these for correct spelling. .pp [cc]mc | Attach to the directory "=aux=/spelling/new" and split the new words [cc]mc into the word files there according to the following scheme: .be 4 dictionary ordinary English words gazetteer names and trademarks abbreviations abbreviations, acronyms glossary computer science terms .ee Words may appear in more than one file; for example, "assemble" may appear both in the dictionary and in the glossary. .pp When the new words have been split to their respective files, [cc]mc | append these files onto the files of the same name in "=aux=/spelling." You may then empty out the files in "=aux=/spelling/new" by 'echo'ing into them. Go back to "=aux=/spelling", and [cc]mc execute the shell program 'build', which combines the files to form the file 'words', which is used by the spelling check program. [cc]mc | You may also run the program 'info' in "=aux=/spelling" for more information. [cc]mc