add_copyright.plm.compin 03/29/79 1424.2r w 03/31/78 0851.6 5319 .ifi init_plm "AN51" .sr section 1 .ifi l1h "N__a_m_e: add_copyright" The add_copyright command adds a copyright notice to a source program. If the program already contains a copyright notice no change is made to the segment. Different notices are used for each different language suffix. .ifi l2h "Usage" add_copyright path .spb 2 where path is the name of the source program to be modified. .spb 2 Consult the description of the copyright_notice_ subroutine for details of the operation of this command. .brf .~ Under "Usage": copyright_notice_ subroutine .fin .inl 0  as_who.plm.compin 03/29/79 1424.3r w 03/22/78 0834.3 25182 .ifi init_plm "AN51" .srv section 1 .ifi l1h "N__a_m_e: as_who" The as_who command is a privileged version of the who command used by the answering service. It extracts information directly from the answer_table rather than from whotab. .ifi l2h "E__n_t_r_y: as_who$as_who_init" This entry must be invoked prior to the other entries if an answer_table other than the standard one (found in >system_control_1) is to be used. .ifi l2h "Usage" as_who$as_who_init path .spf 2 where path is a pathname of a nonstandard answer_table. .inl 0 .ifi l2h "E__n_t_r_y: as_who$how_many_users" This entry prints the number of users, the time of system initialization, and the time of the last shutdown (or crash). .ifi l2h "Usage" as_who$how_many_users .ifi l2h "E__n_t_r_y: as_who$hmu" This entry prints the number of users currently logged in. .ifi l2h "Usage" as_who$hmu .ifi l2h "E__n_t_r_y: as_who" This entry lists the selected users and prints other information specified in the -long control argument below. .ifi l2h "Usage" as_who -control_args- User_ids .spf 2 where: .spf .inl 12 .unl 12 1. control_args .brf are selected from the following: .spf .unl 5 -long, -lg .brf specifies that the long form of output including login time, tty ID, etc., are printed. .spf .unl 5 -name, -nm .brf specifies that the users are sorted by name. .spf .unl 5 i -project, pj .brf specifies that the users are sorted by project. .spf .unl 12 2. User_ids .brf are of the form Person_id.Project_id.tag. .inl 0 .ifi l2h "Note" If an argument is not one of the above, it is assumed to be a User_id in one of the following formats: .spf .inl 22 .unl 22 Person_id.Project_id lists all users logged in with the specified name and project. .spb .unl 22 Person_id lists all users logged in with the specified name. .spb .unl 22 .bbl 1 .Project_id lists all users logged in with the specified project. .spb .inl 0 The default sort is by login time. .spb 2 If no arguments are specified, name and project for each user are returned. Anonymous users' true login names are shown, preceded by an asterisk (*). .spb 2 Specification of -long returns time of login, tty ID, device channel, weight, Person_id and Project_id for each user, as well as flags indicating special variables. .spb 2 A flag of N indicates that the user has the nolist bit and will not be listed on an ordinary who. .spb 2 A flag of + identifies a user with the nobump attribute. .spb 2 A flag of > indicates that a user whose grace period has not yet run out is subject to bumping by other members of the project. .spb 2 A flag of X indicates that a user has been bumped but has not yet logged out." .fin .inl 0 .brp  backup_dump.plm.compin 03/29/79 1424.3r w 03/17/78 1249.5 11853 .ifi init_plm "AN51" .srv section 1 .ifi l1h "N__a_m_e: backup_dump" The backup_dump module can be called as a command or as a subroutine. It sets up the requested control arguments and dumps the appropriate directories and segments. .ifi l2h "Usage" backup_dump -control_args- .spf 2 where control_args represents the current arguments, selected from the list shown in the description of the bk_arg_reader_ subroutine in this document. .ifi l2h "Notes" If a pathname is not given (see below), dumping begins with the current working directory. Unless flags have been set by previous calls in the process, the defaults are: -all, -err_offl, -map, -nodebug, -nohold, -1tape, -sweep, and -tape. .spb 2 Option settings, except for the pathname, are retained (in static storage) from one invocation to the next unless overridden by a supplied argument. Errors are handled by the condition handler in the following manner. If the error can be ignored, idump_signal writes the condition name and the erroneous pathname offline, terminates the current segment, and proceeds to the next entry. If the error cannot be ignored, the condition name is written online and the listener is called. At this point, commands can be typed at the terminal in an attempt to correct the problem. .fin .inl 0  backup_load.plm.compin 03/29/79 1424.3r w 03/17/78 1227.1 30069 .ifi init_plm "AN51" .srv section 1 .ifi l1h "N__a_m_e: backup_load" The backup_load command prompts the user for the names of tapes that are to be loaded. This command is the primary procedure of the reloader for the backup system. It can be called directly, but is usually invoked by the operational interface procedure reload. .ifi l2h "Usage" .fif backup_load -control_args- pathname .spf 2 .fin where control_args can be one or more of the following: .spf .inl 12 .unl 7 -debug enables unprivileged operation for debugging and unprivileged users. .spf .unl 7 -first loads the first copy only of the branch encountered on the tape (applicable to retrievals only). .spf .unl 7 -last loads all copies encountered on the tape so that the last one remains after the tape has been loaded. .spf .unl 7 -map enables map writing. .spf .unl 7 -nodebug enables normal operation. .spf .unl 7 -nomap disables map writing. .spf .unl 7 -noquota does not reload quotas. .spf .unl 7 -quota enables reloading of quotas on directories. .spf .unl 7 -notrim disables pruning of excess entries. .spf .unl 7 -trim enables pruning of excess entries in a directory. .spf .inl 0 If a control argument without a hyphen is encountered, it is taken to be the pathname of a retrieval control segment and the load is therein controlled. If no pathname is given, everything on the tape is reloaded. .ifi l2h "Notes" For compatibility with previous systems, backup_load is temporarily accepting control arguments without hyphens. For as long as hyphens remain optional, the first unrecognized argument is taken to be the name of the retrieval control file. .ifi l2h "Format of the Retrieval Control File" The retrieval is controlled by an ASCII segment containing one line for each entity to be reloaded. A line can contain a single pathname or two pathnames separated by an equal sign. The left-hand-side specifies the object sought and the right-hand-side, if present, specifies the new name under which that entity is to be reloaded. The sought pathname must begin with a > and end with either an entryname or the characters >**. If an entryname is specified, a single entity by that name is retrieved. If >** is specified, the entire directory hierarchy, beginning at the point indicated in the pathname, is retrieved. .ifi l2h "Examples" A retrieval control file containing the line: .spf >udd>Multics>** .spf 2 causes the tape to be searched for directories and segments whose first two pathname components are >user_dir_dir>Multics. These items are reloaded as found. .spb 2 A retrieval control file containing the line: .spf >ldd>a>b>c .spf causes the tape to be searched for the segment >library_dir_dir>a>b>c. This item is reloaded as found. .spb 2 A retrieval control file containing the line: .spf >ldd>a>b=c .spf causes the tape to be searched for the segment >library_dir_dir>a>b. This item is reloaded under the name >ldd>a>c. .spb 2 A retrieval control file containing the line: .spf >ldd>x>y>**=>ldd>z>y .spf causes the tape to be searched for directories and segments whose first three pathname components are >library_dir_dir>x>y. These items are reloaded in the subtree >ldd>z>y. .fin .inl 0  bk_arg_reader_.plm.compin 03/29/79 1424.3r w 03/23/78 0929.4 82620 .ifi init_mpm "AN51" .srv section 1 .ifi l2h "N__a_m_e: bk_arg_reader_" The bk_arg_reader_ subroutine handles most argument reading for backup and the reloader. It is called from all of the backup command programs, start_dump, backup_dump, reload and backup_load. The main function of bk_arg_reader_ is to set flags and to enter data, such as pathnames, in the backup external static segment bk_ss_. .ifi l2h "Usage" .all .inl 10 .unl 5 declare bk_arg_reader_ entry (fixed bin, ptr, fixed!bin(35)); .unl 5 .spf call bk_arg_reader_ (iac, ialp, ocode); .spf 2 .inl 0 where: .spf .inl 12 .unl 12 1. iac (Input) .brf is the index of the first argument to be processed. .spb .unl 12 2. ialp (Input) .brf is a pointer to an argument list. .spb .unl 12 3. ocode (Output) .brf is the standard status code .inl 0 .ifi l2h "E__n_t_r_y: bk_arg_reader_$dump_arg_reader" This entry is called by start_dump, catchup_dump, complete_dump, and backup_dump to handle input arguments. .ifi l2h "Usage" .all .inl 10 .unl 5 declare bk_arg_reader_$dump_arg_reader entry (fixed!bin, ptr, fixed!bin(35)); .unl 5 .spf call bk_arg_reader_$dump_arg_reader (iac, ialp, ocode); .spf 2 .inl 0 .alb Same arguments as above. .ifi l2h "E__n_t_r_y: bk_arg_reader_$reload_arg_reader" This entry is called by each of the reload commands (reload, iload, retrieve, and backup_load) to handle input arguments. .ifi l2h "Usage" .all .inl 10 .unl 5 declare bk_arg_reader_$reload_arg_reader entry (fixed!bin, ptr, fixed!bin(35)); .unl 5 .spf call bk_arg_reader_$reload_arg_reader (iap, ialp, ocode); .spf .alb .inl 0 Same arguments as above. .ifi l2h "Notes" The bk_arg_reader_ subroutine handles three classes of arguments: those common to both reloading and dumping, those related only to reloading, and those related only to dumping. In addition, there are arguments used only by a particular entry or by all but one entry. Finally, there are control arguments that merely direct the handling of an immediately following argument. .spb 2 Control arguments and a few other arguments should be preceded by a minus sign (-). Arguments that immediately follow control arguments cannot be preceded by a minus sign (-). .ifi l2h "Arguments Common to All Backup Commands" .inl 15 .unl 15 -all causes switches to be set indicating that no date testing is to be done except to ensure that reloading older copies of directories does not overwrite newer ones. Default varies with the particular entry called. .spf .unl 15 -control indicates that the following argument is a dump control file name if entry was through the dump_arg_reader entry or a retrieval control file name if entry was through the reload_arg_reader entry. .spf .unl 15 -debug disables those hphcs_ calls that set quotas and transparency switches. .spf .unl 15 -nodebug enables hphcs_ calls to set quotas and the transparency switches. This is the default. .spf .unl 15 -err_offl causes error messages to be output into a file rather than online. The name of the error file is given on the first error encountered. This is the default. .spf .unl 15 -err_onl causes error messages to be output onto the user's console. .spf .unl 15 -map causes a list of the segments and directories processed to be output into a file. This is the default. .spf .unl 15 -nomap inhibits listing of the names of processed segments and directories and turns _o_n the tape switch if entry was through dump_arg_reader (see -tape). .spf .unl 15 -operator indicates that the next argument is the operator's (or user's) name or initials up to 16 characters in length. .spf .unl 15 ->string if the user originally invoked reload$retrieve or backup_load, then >string must be the pathname of a retrieval control file. If entry to bk_arg_reader_ was through the dump_arg_reader entry then >string must be the pathname of a segment to be dumped or a directory where dumping of a subtree is to begin. .spf .unl 15 -x.... assumes this argument to be a date, where x is a decimal integer; an attempt is made to convert it to a storage system date using convert_date_to_binary_. (See date information shown below under "Otherwise Unrecognized Arguments".) .inl 0 .ifi l2h "Arguments Recognized by the Dumper" .inl 15 .unl 15 -contin continues by starting incremental backup after the catchup pass. This is the default. .spf .unl 15 -nocontin ends the dump after the catchup pass. .spf .unl 15 -dtd causes each segment to be tested and dumped only if the segment or its branch has been modified since the last time it was dumped. .spf .unl 15 -hold causes the current dump tape or tapes to remain mounted and inhibits rewinding after the current dump cycle is completed. This is set by the dumper. .spf .unl 15 -nohold causes the dump tape or tapes to be rewound and unloaded at the end of the current dump cycle. This is the default. .spf .unl 15 -only indicates that only the requested segment or directory and its branch are to be dumped. (See ->string above.) .spf .unl 15 -sweep indicates that the whole subtree beginning with the given directory is to be dumped, subject to the dtd and date criteria if they have been invoked. (See ->string -dtd and -x... above). This is the default. .spf .unl 15 -output causes dump information to be output onto tape if the tape switch is on. This is the default. .spf .unl 15 -nooutput inhibits writing on tape even if tape switch is on. This is used for a dumper test run or debugging. .spf .unl 15 -restart indicates that the next argument is the pathname of a segment or directory where dumping is to be restarted. Use of this feature assumes that there is a dump control file. Its normal usage is in conjunction with catchup_dump or complete_dump where a failure of some nature has occurred. .spf .unl 15 -tape allows writing onto a dump output tape. This is the default. .spf .unl 15 -notape inhibits writing onto a dump output tape. This also causes a map to be output even if it was previously inhibited. (See -map above). .spf .unl 15 -tapes indicates that the next argument is the number of output tape copies to be made. Only 1 or 2 are allowed and the default is one. .spf .unl 15 -1tape sets the number of tape copies to 1 as an alternative to the -tapes argument. .spf .unl 15 -2tapes sets the number of tape copies to 1 as an alternative to the -tapes argument. .spf .unl 15 -wakeup indicates that the next argument is the wake-up interval between dump cycles given in minutes. .spf .inl 0 A__r_g_u_m_e_n_t_s_R__e_c_o_g_n_i_z_e_d__b_y__t_h_e_R__e_l_o_a_d_e_r .spf .inl 15 .unl 15 -first prevents searching a tape for additional copies of a requested segment or subtree after the first copy has been retrieved. .spf .unl 15 -last indicates that the last copy of a given segment or subtree on a tape or set of tapes is to be retrieved. This is the default. .spf .unl 15 -quota causes quotas to be reset during reload and suspended during retrieval. This is the default. .spf .unl 15 -noquota inhibits resetting and suspension of quotas. .spf .unl 15 -reload enables actual reloading of segments into the hierarchy. This is the default. .spf .unl 15 -noreload inhibits actual reloading of segments into the hierarchy. This is a debugging tool and when map is enabled (see -map) it also causes the names and access control lists (ACLs) that would have been reloaded to be put into the map. .spf .unl 15 -qcheck disables suspension of quota checking. .spf .unl 15 -noqcheck enables suspension of quota checking. This is the default. .spf .unl 15 -trim enables deletion of all entries in a directory not found in the copy of that directory being reloaded. (Entries deleted since an earlier version of the directory existed are deleted when a later version is reloaded.) This is the default for reload and iload. .spf .unl 15 -notrim inhibits deletion of entries in a directory. Entries can only be added or modified. This is the default for retrieve. .inl 0 .ifi l2h "Otherwise Unrecognized Arguments" .inl 15 .unl 15 -....... an attempt is made to translate otherwise unrecognized arguments into a storage system date using convert_date_to_binary_. Dates have special meaning for various entries and functions: .spb 2 To the dumper a date means that only segments that have been modified or whose entries have been modified since the date given are to be dumped. .spb 2 To the retriever a date means load the first copy of a segment or subtree dumped after the date given. Thus if several copies of a segment exist on a single dump tape, the user can indicate by this means which copy is to be retrieved. .spb 2 The convert_date_to_binary_ subroutine is used to convert dates; any format of date acceptable to it is acceptable to bk_arg_reader_. An easy format to remember is MM/DD/YY tttt.t.  canon_.plm.compin 03/29/79 1424.3r w 03/22/78 0912.0 22374 .ifi init_mpm "AN51" .srv section 2 .ifi l1h "N__a_m_e: canonicalizer_" The canonicalizer_ subroutine canonicalizes an input string according to standard Multics format. The string is placed into the caller's buffer in canonical form if its length is not greater than that of the buffer. If the canonical string does not fit into the caller's buffer, the error code error_table_$area_too_small is returned. The partial string is not returned. .ifi l2h "Usage" .all .inl 10 .unl 5 declare canonicalizer_ entry (ptr, fixed!bin, ptr, fixed!bin, fixed!bin bit(4) aligned, fixed!bin); .unl 5 .spf call canonicalizer= (inptr, inlength, outptr, maxlength, outlength, flags, code); .alb .inl 0 .spf 2 where: .spf .inl 12 .unl 12 1. inptr (Input) .brf is a pointer to the string to be canonicalized. .spf .unl 12 2. inlength (Input) .brf is the length of the input string. .spf .unl 12 3. outptr (Input) .brf is a pointer to the buffer in which the canonicalized string is to be placed. .spf .unl 12 4. maxlength (Input) .brf is the character length of the output buffer. .spf .unl 12 5. outlength (Output) .brf is the returned string length. .spf .unl 12 6. flags .brf is a set of bit flags, each controlling a canonicalization function. These bits are, from the left: .spf .inl 12 Canoncalization control. This bit must be _o_n for the string to be canonicalized. .spf 2 Erase/Kill control. If this bit is _o_n, erase and kill characters in the string are processed with their erase and kill functions. .spf 2 Escape control. If this bit is _o_n, escape characters in the string are processed with their escape functions. .sfp 2 TTY33 convention indicator. If this bit is on, special escape conventions for the TTY33-type character set are processed. The escape control bit must also be _o_n to allow processing of escape characters if this mode is desired. (Input) .spf .unl 12 7. code (Output) .brf is a standard Multics status code. .inl 0 .ifi l2h "Note" This routine does not alter the cases of letters, regardless of the value of the TTY33 convention indicator. It is assumed that case processing has already taken place, but without deleting the escape characters responsible for capitalization, since their initial presence is essential to correct canonicalization. In this mode, single escape characters preceding capital letters are simply deleted.  comnd_proces_.plm.compin 03/29/79 1424.4r w 04/04/78 0851.1 15651 .ifi init_plm "AN51" .ifi l2h "N__a_m_e: command_processor_" The command_processor_ subroutine is the Multics command language interpreter. It parses a command line and invokes the specified command or commands. It is called through the subroutine cu_$cp. .ifi l2h "Usage" .all .inl 10 .unl 5 declare command_processor_ entry (ptr, fixed!bin(21), fixed!bin(35)); .spf .unl 5 call command_processor_ (line_ptr, line_len, code); .alb .spf 2 .inl 0 where: .spf .inl 12 .unl 12 1. line_ptr (Input) .brf is a pointer to the command line. .spf .unl 12 2. line_len (Input) .brf is the length of the command line. .spf .unl 12 3. code (Output) .brf is a standard Multics status code that equals 0 if there are no errors in the command line; equals 100 if a null line was typed. code is nonzero if there is an error in the line. .inl 0 .ifi l2h "E__n_t_r_y: command_processor_$af" This entry point expands the contents of an active string (minus the surrounding brackets) and returns the resulting value. .ifi l2h "Usage" .all .inl 10 .unl 5 declare command_processor_$af entry (char(*), bit(1) aligned, char(*) aligned varying, fixed!bin(35)); .spf .unl 5 call command_processor_$af (line, rescan_sw, return_value, code); .alb .inl 0 .spf .spf where: .spf .bbk .inl 12 .unl 12 1. line (Input) .brf is the active string to be expanded. .bek .spf .unl 12 2. rescan_sw (Input) .brf is on to scan the string and the return string for imbedded active functions and to expand these. .spf .unl 12 3. return_value (Output) .brf is the result of the expansion. .spf .unl 12 4. code (Output) .brf is a standard status code. .inl 0  copy_arch.plm.compin 03/29/79 1424.4r w 03/28/78 0901.9 22671 .ifi init_plm "AN51" .srv section 1 .ifi l1h "N__a_m_e: copyright_archive" The copyright_archive command adds a copyright notice to each component of an archive of source commands. If a program already contains a copyright notice no change is made to it. Different notices are used for each different language suffix. If adding the copyright notices would cause the archive to overflow, an error message is typed and no modifications are made to the archive. .ifi l2h "Usage" copyright_archive archive_path {-control_args} {paths} .spf 2 where: .spf .inl 12 .unl 12 1. archive_path .brf is the pathname of the archive to be modified. .spf .unl 12 2. path_i .brf is the component name to be modified. If no n_i is given, the entire archive is processed. .spf .unl 12 3. control_args .brf are selected from the following: .spf .unl 5 -check .brf no modification is made to the archive. The archive length is tested for overflow, and if -long is specified, comments are printed describing what would be done if archive were modified. .spf .unl 5 -long, -lg .brf messages are printed describing what is done to the archive. .spf .unl 5 -suffix Z .brf the copyright messages are named suffix.Z where type is pl1, alm, etc. If this argument is not specified, the default suffix is copyright. .inl 0 .ifi l2h "Operation" The copyright_archive command makes two passes over the archive: the first checks to see what change in length would be made to the archive, and the second makes the changes. .spb 2 The copyright messages are inserted at the beginning of each component unless the component begins with the string %;!-- in this case the notice is inserted right after the percent and semicolon characters. .spb 2 The copyright messages are assumed to reside in >ldd>include unless the command .spf 1 copyright_archive$test dir_name .spf 1 has been executed. Both directory name and suffix are effective for all subsequent invocations until reset. .spb 2 If a language has no corresponding copyright notice segment, an error message is printed and no change is made to that component. The dates in the archive header are left undisturbed by this command. .spb 2 If a segment named suffix.Z_delete is found in the notice directory (where Z is usually copyright and suffix is the language suffix), each component selected is checked to see if the notice in the delete segment is present; if so, the old notice is deleted before the new notice is added. .fin .inl 0  copyr_notice_.plm.compin 03/29/79 1424.4r w 03/28/78 0922.1 19476 .ifi init_plm "AN51" .srv section 2 .ifi l2h "N__a_m_e: copyright_notice_" The copyright_notice_ subroutine adds (and optionally deletes) copyright notices to source program segments. .ifi l2h "Usage" .all .inl 10 .unl 5 declare copyright_notice_ entry (char(*) aligned, char(*) aligned, fixed!bin(35)); .spf .unl 5 call copyright_notice_ (dir_name, entryname, code); .spb 2 .alb .inl 0 .spf 2 where: .spf .inl 12 .unl 12 1. dir_name (Input) .brf is the pathname of the directory containing the segment to be modified. .spf .unl 12 2. entryname (Input) .brf is the entryname of the segment. .spf .unl 12 3. code (Output) .brf is a standard status code. .inl 0 .ifi l2h "Operation" The copyright_notice_ subroutine extracts the language suffix from its second argument and searches the notice directory for segments named suffix.Z and suffix.Z_delete, where Z is the string copyright unless changed by a call to copyright_notice_$set_suffix. .spb 2 If a delete notice exists and is in the segment, it is removed. If the segment does not contain a copy of the new notice it is added at the top of the segment or following an initial percent-semicolon character string. .spb 2 If no notice segments are found for the given language type, the error code error_table_$typename_not_found is returned. .ifi l2h "E__n_t_r_y: copyright_notice_$set_suffix" This entry point sets the name of the copyright notice segments. The default is suffix.copyright and suffix.copyright_delete where suffix is the language suffix. .ifi l2h "Usage" .all .inl 10 .unl 5 declare copyright_notice_$set_suffix entry (char(*)); .spb .unl 5 call copyright_notice_$set_suffix (x); .spf 2 .inl 0 where x (Input) is the new suffix. .ifi l2h "E__n_t_r_y: copyright_notice_$test" This entry sets the directory to be searched for copyright notice segments. The default is >ldd>include. .ifi l2h "Usage" .all .inl 10 .unl 5 declare copyright_notice_$test entry (char(*)); .spf .unl 5 call copyright_notice_$test (d); .spf 2 .inl 0 where d (Input) is the directory to be searched for copyright notices.  edit_mst_header.plm.compin 03/29/79 1424.4r w 03/07/78 1101.9 33003 .ifi init_plm "AN51" .sr Charsw -1 .sr section 1 .ifi l1h "N__a_m_e: edit_mst_header, emh" The edit_mst_header command takes an MST header file and produces a new MST header file. The nature of the editing is specified in a third edit_header file. .spb Editing is performed by header entry. A header entry is a fini or collection header statement or a series of statements describing a single segment on the MST. An example of the latter is a series of statements beginning with a name statement and ending with an end statement. In the edit_header file, header entries can be preceded by a control line. Following is a list of recognized control lines and their effect: .inl 5 .spb .unl 5 1. skip_to: -- the old header file is scanned starting at the current position until a header entry is found whose first line matches the first line of the header entry immediately following this control line in the edit_header file. The current position in the old header file is set to the beginning of the matching header entry. If no match is found, a message is printed on the terminal and the command returns. .spb .unl 5 2. skip_thru: -- same as skip_to:, only the current position in the old header file is placed at the beginning of the header entry immediately following the matching header entry. .spb .unl 5 3. copy_to: -- the old header file is copied starting at the current position to the new header file until a header entry in the old header file whose first line matches the first line of the header entry following the control line in the edit_header file is found. The current position is set to the beginning of the matching header entry and the matching header entry is not copied. If no match is found, an error message is printed on the terminal and the command returns. .spb .unl 5 4. copy_thru: -- same as copy_to:, except the current position is set to the header entry in the old header file following the matching header entry and the matching header entry is copied. .spb .unl 5 5. copy_to, replace: -- same as copy_thru:, except the header entry following the control line in the edit_header file is copied into the new header file instead of the matching header entry in the old header file. .spb .inl 0 If no control line precedes a header entry in the edit_header file, then this header entry is simply copied into the new header file. .spb All comparisons are based on the first line of the header entry, the first line being those characters occurring before a comma (,) or a semicolon (;). All blanks, tabs, newlines, and all characters occurring between /* and */ are ignored. .ifi l2h "Example" name: abc, cde, fgh; .brf end .spb matches: .spb name: /* comment */ abc, fgh, g; .spb end; .spb 2 because the first line in both cases is: .spb name:abc .spb however, .spb name: abc; .brf end; .spb does not match: .spb object: abc; .brf end; .ifi l2h "Usage" emh edit old new .spb where: .spb .inl 12 .unl 12 1. edit identifies the edit header file whose pathname is edit.edit_header. .spb .unl 12 2. old identifies the old header file whose pathname is old.header. old can also be -hard for the current hardcore header file or -soft for the current softcore header file. .spb .unl 12 3. new identifies the new header file whose pathname is new.header If new is omitted, the new header file is assumed to have the entryname of edit.header in the user's working directory. If the new header segment does not exist, it is created. .fin .inl 0 .brp  et.plm.compin 03/29/79 1424.4r w 03/07/78 1109.8 326421 .sr Name "et" .sr Line "__" .sr Section "1" .sr Volume "AN51" .ifi PLM_head N__a_m_e: et et is a program that can be used to set up and test EIS instructions in a controlled environment. The user must prepare an input script describing the EIS instructions to be tested. From this input script the EIS tester builds the EIS instructions (one at a time) and the indirect words, descriptors, and data that each instruction needs. The instruction to be tested is set up in a special ALM segment (etx). et calls etx in order to execute the EIS instruction. etx returns to et when the instruction has been executed. After executing the instruction, et tests to see if the instruction has executed correctly. Before et calls etx to execute the instruction, it sets up some special padding around the data field that is modified by the EIS instruction. Eight special characters (octal 717) are put in front of and at the end of the result data string. The result area itself is initialized to all zero bits. When called to execute the EIS instruction, etx does the following: 1. Saves the current pointers and registers. 2. Loads the pointers and registers from values set up by et. These are the values of the pointers and registers when the EIS instruction is actually being executed. 3. Sets indicators to preinstruction test values. .spb a. All indicators except the following are _o_f_f. b. The BAR MODE indicator is _a_l_w_a_y_s _o_n. .inl 9 .unl 9 c. If the test instruction is expected to turn _o_n any of the three overflow indicators (ov, eo, eu), then the om OVERFLOW MASK indicator is turned _o_n so an overflow fault is not taken. .inl 0 4.!!!Transfers to the instruction area in etx itself where et has set up the EIS instruction and its descriptors. 5. After the EIS instruction has been executed, etx stores the values of the indicators and pointers and registers so that et can examine them. 6.!!!The pointers and registers that were saved by etx are now reloaded. 7. etx returns to et. After the execution of the EIS instruction, et makes the following tests: 1.!!!Checks to see that the data resulting from the instruction is correct. 2. Checks to see that the indicators are set correctly. 3.!!!Checks to see that a truncation fault was correctly taken or not taken. .spb I__n_s_t_r_u_c_t_i_o_n_A__r_e_a The EIS instruction is set up in a special area in etx. This area consists of seven words. The first three words of the instruction area are set up in the last three words of a page. The last four words of the instruction area are the first four words of the next page. By positioning the instruction in the instruction area, the user can position the instruction on a PAGE boundary. Those words in the instruction area that are not used for the EIS instruction itself are set up as nops. The default position of the instruction word is in instruction area word 4. This places the instruction at word zero of a page. PAGE A WORD 1 WORD 2 WORD 3 --------------- .brf PAGE B WORD 4 <-- Default position of .brf WORD 5 instruction word. .brf WORD 6 WORD 7 .spb D__a_t_a_A__r_e_a_s The data referenced by each descriptor of the instruction is set up in a special data area. There is one data area used for every descriptor of the instruction. Each data area consists of three pages. The default starting position of the data is character zero of word zero of page 2. The last 32 words of page 1 and the first 32 words of page 3 can also be used to hold the test data. Thus the maximum data size of any string is 1088 words or 4352 characters (9 bit). The user can position the start of the data string so that it starts in page 1. Thus the user can define data strings that cross page boundaries. Long data strings cross two page boundaries. .spb N__o_t_e .spb 2 Depending on what modification is used by the instruction, the data areas used may or may not be in the same segment. If a descriptor is referenced via an indirect word, then the descriptor is set up in a special page all its own. Depending upon the modification used in the indirect word, the descriptor may be in different segments. P__a_g_e_F__a_u_l_t_s .spb 2 The user has control over a maximum of 14 page faults during the testing of any EIS instruction. These 14 pages have consistent meaning to et even though for different tests they may actually be physically different pages in different segments. The 14 pages are: .inl 8 .fif 1. Page 1 of the instruction area. 2. Page 2 of the instruction area. 3. Page containing indirect descriptor 1. 4. Page 1 of data area 1. 5. Page 2 of data area 1. 6. Page 3 of data area 1. 7. Page containing indirect descriptor 2. 8. Page 1 of data area 2. 9. Page 2 of data area 2. 10. Page 3 of data area 2. 11. Page containing indirect descriptor 3. 12. Page 1 of data area 3. 13. Page 2 of data area 3. 14. Page 3 of data area 3. .fin .inl 0 .brp R__e_g_i_s_t_e_r_A__s_s_i_g_n_m_e_n_t The user can control the type of modification used by each EIS instruction tested. However, for each type of modification (depending upon the descriptor number) et assigns the register to be used. The specific use of pointers and registers is not under user control when he is using the et script input method. .spb Pointer registers not used during the instruction are set to null. Index registers and the A and Q that are not used, are set to 8191 decimal (17777 octal). AR modification involves the use of a pointer register. Both descriptors and indirect words can use AR modification. A general rule followed by et is that: AR MODIFICATION => THE DATA REFERENCED IS IN AN EXTERNAL SEGMENT. The pointer registers used by et for the EIS instruction are: .inl 5 AR modification in a descriptor - descriptor 1 - pr1 descriptor 2 - pr2 descriptor 3 - pr3 AR modification in an indirect word - descriptor 1 - pr4 descriptor 2 - pr5 descriptor 3 - pr7 .inl 0 Pr6 is used to point to the current stack frame of the user and _m_u_s_t be preserved in a valid state in order for any conditions to be signalled correctly. Index register modification can be specified for descriptors and for indirect words. The effective offsets used for index modification are always set up by et in terms of _w_o_r_d_s. The index registers assigned by et and the effective word offset they contain are given below. .spb .inl 12 .unl 7 NOTE: For some descriptors the value in the index register must be in units of characters. The character size also varies with the value of the "ta" field of the descriptor. .inl 5 .spb 2 INDEX register modification of a descriptor - descriptor 1 - X1 1 word descriptor 2 - X2 2 words descriptor 3 - X3 3 words INDEX register modification of an indirect word - descriptor 1 - X4 4 words descriptor 2 - X5 5 words descriptor 3 - X7 7 words .inl 0 RL modification can be specified for the descriptors of certain instructions. The value put in the register is specified by the user. The register assigned is controlled by et. The following registers are used. .spb descriptor 1 - A descriptor 2 - Q descriptor 3 - X6 .spb S__e_g_m_e_n_t_s_U__s_e_d__b_y__e_t__t_o_E__x_e_c_u_t_e__a_n_I__n_s_t_r_u_c_t_i_o_n If AR modification is not used by descriptors or indirect words, then the following is in segment etx: instruction area (always in etx) all indirect descriptors all data areas Any descriptors referenced via indirect words are put in the following segments. .spb .inl 12 .unl 7 NOTE: If the descriptor itself does _n_o_t use AR modification then the data field for this descriptor is also in the same segment as the descriptor. descriptor 1 - eti1 descriptor 2 - eti2 descriptor 3 - eti3 .inl 0 Any descriptors that use AR modification (either in an mf field or in the descriptor itself) references data areas in the following segments. .spb .inl 12 .unl 7 NOTE: Whether or not the descriptor is referenced via an indirect word does not change the segment where the data field is set up as long as the descriptor uses AR modification. descriptor 1 - etd1 descriptor 2 - etd2 descriptor 3 - etd3 .inl 0 _e_t_P__r_i_n_t_O__u_t .spb et prints a message noting the beginning of each instruction test. It also prints the number of this test. If there were errors, it prints the incorrect data or incorrect indicators. If the user does not specify the -bf control argument, then the data that et has set up for this instruction is printed before the instruction is executed. The following notes describe this print out: 1.!!!!Pointers enclosed in parentheses point to where the data is set up in the et segments. 2.!!!If none of the pointer registers are used by the instruction, then none are printed. The same is true of the registers. 3. The names of the pages that take faults may not be the names of all the pages specified in a "page" statement. Only the names of the pages actually used by the instruction and specified to take faults are printed. 4. If the first word of a data string does not begin at character zero of a word or if the string does not use all four characters of the last word, then the unused characters of the first and last words of the string are printed as blank " " characters. 5. The test string is not printed from one of the areas used by the instruction but rather from one of the buffers used by et. 6. The test and result strings were both padded by et with special characters. These special characters are not printed out in octal like the rest of the string. Instead each of these special characters is printed as three x's "xxx". .spb H__o_w__t_o_C__a_l_l__e_t .spb et (eis_tester) is the main procedure in the EIS instruction tester. It calls "et_test" to parse the statements in the user provided data file. It translates these statements into the data needed to build and test an EIS instruction in the external segment etx. After building the instruction, this procedure calls etx in order to execute the EIS instruction. When etx returns, the results of the EIS instruction are examined. et continues to build and test EIS instructions until there is no data left in the input file. .spb .inl 12 .unl 7 NOTE: The failure of one instruction only causes the termination of that one instruction test. Any remaining instructions specified in the input file are processed and tested. .inl 0 et has two entries. Both are called with one command control argument - a pathname. .inl 30 .unl 30 1. et aaaa The pathname "aaaa" refers to a segment that contains input script data that defines the instruction to test. This is the main entry. .inl 30 .unl 30 2. et$gen aaaa The pathname "aaaa" refers to a procedure that generates the et data needed to test _o_n_e instruction. In addition, each entry can be called with optional control arguments. These optional control arguments can be in any order after the pathname argument. .inl 20 .unl 20 a. "-bf" Specifies that brief mode is entered. All but identification and error messages are suppressed. .inl 20 .unl 20 b. "-nox" Specifies _n_o execute mode. This implies that the instruction is set up but not executed. It is used to test the validity of the input script. .inl 20 .unl 20 c. "-dl" Specifies that this test is to be run in a debugging loop. Each instruction is tested 10 times. The results from the test are not checked. Each time through the loop the instruction is set up completely including all the specified page faults. .inl 20 .unl 20 d. "-do" X X is a positive integer that specifies the _n_u_m_b_e_r of the test to be processed. .inl 20 .unl 20 e. "-st" X X is the number of the first test processed. All remaining tests in the input segment are also processed. .spb .inl 0 .brp H__o_w__t_o_W__r_i_t_e_S__c_r_i_p_t_I__n_p_u_t_T__e_s_t_s .spb The script input test consists of a series of et statements. The first statement in any test _m_u_s_t be an "inst" statement. This statement signifies the beginning of _o_n_e test. An input script segment can contain several tests. All statements from the beginning of the "inst" statement to the beginning of the next "inst" statement (or if none is found to the end of the segment) are considered part of the same test. The format of a statement is as follows: .fif name required_field -control argument...-control argument...; .fin 1.!!!The first field in all statements _m_u_s_t be its four character statement name. There are four types of et statements. They are discussed in detail below. The four types of statements are: .spb .inl 19 .unl 19 inst - defines the instruction word and many control variables .inl 20 .unl 20 desc - defines a descriptor .inl 20 .unl 20 data - defines the data associated with a descriptor .inl 19 .unl 19 page - used to control the page faults taken by the instruction .inl 0 2. In some statements (all but page) the second field in the statement _m_u_s_t be some required information. 3. The other fields in the statement represent optional control arguments data that may or may not be given. Each control argument field _m_u_s_t begin with a "-". 4. All statements must end with a ";". 5. There can be any number of blanks, tabs, and new line characters between any fields in the statement, including before the name field. 6.!!!Wherever blanks are permitted (see 5. above) there can also be comment fields. Comments _m_u_s_t begin with the characters "/*" and end with the characters "*/". .spb .brn 10 I__n_s_t_S__t_a_t_e_m_e_n_t .spb The "inst" statement defines the beginning of an et test. It is used to define all of the fields in the instruction word of the EIS instruction. It is also used to set up the following special control arguments. .spb .inl 10 .unl 10 Instruct et to execute this instruction several times. .spb .unl 10 Position the instruction within the instruction area. .spb .unl 10 Define an identifying string that is printed with the test. .inl 0 An "inst" statement has the following format: .fif inst opcode_mnemonic -control argument...-control argument...; .fin 1.!!!The first field in the statement _m_u_s_t be "inst". 2. The second field in the statement _m_u_s_t be the mnemonic name of a storage type EIS instruction. (As opposed to address register type EIS instructions that are not tested by et.) 3. Any number of valid "inst" statement control argument fields can follow, in any order. Each must begin with a "-". The control arguments allowed in an "inst" statement are: .inl 20 .unl 20 a. -tbA is used to turn _o_n the Truncation Bit. A is either "y" or "n" and signifies whether or not the instruction is to take a truncation fault. "y" => yes, "n" => no. .unl 20 b. -fb is used to turn _o_n the Fill Bit. .unl 20 c. -pb is used to turn _o_n the Plus Sign Bit. .unl 20 d. -rb is used to turn _o_n the Rounding Bit. .unl 20 e. -fcA defines the Fill Character. A is the character used. .unl 20 f. -mcA defines the Mask Character A is the character used. .spb .inl 15 .unl 7 NOTE: For both "fc" and "mc" control arguments, the character immediately following the control argument name is used. .inl 20 .unl 20 g. -ln X defines the Loop Number. This is the number of times this instruction test is performed. The default is 1. The maximum value of X is 4. .unl 20 h. -io X defines the Instruction Offset. It is used to position the instruction on a page boundary. The default is 0. This places the instruction at word 0 of the second page of the instruction area. X indicates the number of words of the instruction placed in the first page of the instruction area. The maximum value of X is 3. .unl 20 i. -nt "A...A" defines a Note. It can be used to identify each test. The term consists of a character string between quotes. Up to 32 characters can be used. No embedded quotes are allowed. .unl 20 j. -bo AAA defines a Boolean Operator. AAA is the name of the operator. The names et has assigned to the Boolean Operators are given below. Next to these names are the actual BOLR codes they represent. .fif .inl 10 "zer" - 0000 "and" - 0001 "axr" - 0010 "mov" - 0011 "xra" - 0100 "ra2" - 0101 "xor" - 0110 "or " - 0111 "nor" - 1000 "nox" - 1001 "iv2" - 1010 "xrx" - 1011 "inv" - 1100 "xxr" - 1101 "nan" - 1110 "set" - 1111 .inl 20 .unl 20 .fin k. -ir is a multifield control argument that defines the correct state of the indicator registers after the EIS instruction has been executed. An ir control argument has the following format: -ir ind . . ind . . . ind .inl 24 .unl 14 1) The first field in the control argument _m_u_s_t be the control argument name "-ir". .inl 24 .unl 14 2) Following the first field can be any number of ind terms. These terms can be in any order and can be separated by any number of skip fields. .inl 24 .unl 14 3) Each ind term is a two character identifier of an indicator register. The ind term values acceptable are: .fif .inl 14 a) zr - zero b) ng - negative c) cr - carry d) ov - overflow e) eo - exponent overflow f) eu - exponent underflow g) om - overflow mask h) tr - tally runout i) pe - parity error j) pm - parity mask k) bm - BAR mode - Really _n_o_t .brf BAR mode l) tn - truncation m) mw - multi-word instruction n) ab - ABSOLUTE mode .fin .inl 20 .unl 20 l -mfX is a multifield control argument that defines one mf field of the instruction. X denotes which mf field is being defined. It must be from 1 to 3 and is associated with descriptor X. .spb .inl 17 .unl 7 NOTE: Some instructions do _n_o_t have mf fields in the instruction word for all of their descriptors. The "-mfX" control argument is then used to specify any AR or REG modification in the descriptor itself. .inl 20 An mf control argument has the following format: -mfX term . . . term .inl 24 .unl 4 1) The first field in the control argument is the control argument name "-mf". .inl 24 .unl 4 2) Immediately following it _m_u_s_t be the number of the descriptor to which this mf field relates. Below X is used to indicate this value. .inl 24 .unl 4 3) Following the descriptor number can be up to four terms. All are optional control arguments. They can be specified in any order. The valid terms are: .inl 34 .unl 10 a) ar This term specifies that the descriptor is to use Address Register modification. In Multics it is called pointer register modification. The pointer assigned is prX. When this term is specified, the data referenced by this descriptor is placed in a different segment from the descriptor. It goes in segment etdX. .inl 34 .unl 10 b) rl L This term specifies that the descriptor is to use Register Length modification. This term _m_u_s_t be followed by a decimal number "L", which specifies the character length of the data. This value is placed in the selected register and the "n" field of descriptor X contains the register modification tag code. The registers assigned are: .spb .inl 30 X = 1 - A X = 2 - Q X = 3 - x6 .inl 34 .unl 10 c) idA This term specifies that descriptor X is to be referenced via an indirect word in the instruction. The character immediately following the "id" term denotes what modification is to be used in the indirect word. .inl 39 .unl 6 A = "a" (ida) This implies Address (pointer) Register modification. When this is specified, the descriptor is placed in a segment other than the segment containing the instruction. This is etiX. .spb .inl 39 .unl 6 NOTE: If the descriptor does not specify AR modification, then the data for this descriptor is also in segment etiX. The pointer registers assigned to the indirect word are: .spb .fif indirect word 1 => pr4 indirect word 2 => pr5 indirect word 3 => pr7 .fin .inl 39 .unl 6 A = "r" (idr) This implies Register modification. The indirect word is modified by index register 4,5, or 7. .spb .inl 39 .unl 6 NOTE: This modification is in terms of _w_o_r_d_s. .inl 39 .unl 6 A = "b" (idb) This implies both "a" and "r" modification as described above. .inl 34 If A is none of the above, then there is no modification in the indirect word. .inl 34 .unl 10 d) reg This term specifies that descriptor X is to be modified by an index register. The value in the index register is a character offset and is (x * 4). The index register assigned is index register X. The value placed in index register X is dependent upon the type of instruction and the appropriate character size. It is in the following units: .spb .inl 40 .unl 20 WORDS for those descriptors that have no mf field in the instruction word. .unl 20 BITS for all bit string instructions. .unl 20 CHARS for all others. The actual units depend upon the character size. The default is a 9-bit character size. .inl 0 E__x_a_m_p_l_e_s__o_f_I__n_s_t_S__t_a_t_e_m_e_n_t_s .fif # /* Example 1. */ inst mlr -nt "Example 1 " -fc* /* Comments can go anywhere except inside a term */ -fbn -mf2 /* Note order is not important. */ rl 3 id ar reg -mf1 ar idb reg rl 3 ; /* Statement must end with ";" */ /* Example 2. */ inst cmpc /* mnemonic name must * be first term. */ -mf1 ar -nt " example 2" -mf2 rl 3 .bbl 1 -fc /* Use escape to enter octal character 001 */ -ir cr zr ; /* Indicator bm is on by default. */ /* Example 3. */ inst scm -nt "scm examp." -mc9 -ln 3 /* Make this test 3 times. */ -io 2 /* Put instruction word and first descriptor * in page 1 of instruction area. */ -mf1 reg ar -mf2 ida; /* Example 4. */ inst ad3d -mf3 ar -mf2 reg -mf1 idr -rb -pb; /* Example 5. */ inst csr -fb -bo and -mf 2 rl 36; .spb 2 D__e_s_c_S__t_a_t_e_m_e_n_t .fin .spb "desc" statements are used to specify certain fields in the descriptors. Each desc statement deals with only one descriptor. The fields in a descriptor not specifically set up by a "desc" or an "inst" statement are set to zero. If zero bits in all of the fields is what you want, then no desc statement need be specified for that descriptor. In general the order of the desc statements is not important and they can be mixed in with any other statements in any order. One exception is noted below. A desc statement has the following format. desc num -control argument . . . -control argument ; 1. The first field in the statement _m_u_s_t be "desc". 2. The second field in the statement _m_u_s_t be the number of the descriptor. It _m_u_s_t be either "1", "2", or "3". 3.!!Any number of valid "desc" statement control arguments may follow. The format is the same for all desc control arguments. It is: -name term 4. name is the two character name of the control argument and term is the data associated with this control argument. The valid control argument names are: .inl 20 .unl 20 a. cp is the original character position within a word of 9-bit characters. It is used in bit string instructions. Its term must be a number from 0 to 3. .unl 20 b. bp is the original bit position within a 9-bit character. Its term must be a number from 0 to 8. .unl 20 c. cn is the original character number within the data word referenced by the original data word address. It is used in character string instructions. Its term must be a number from 0 to 7. The meaning of this term is defined by the "ta" and "tn" fields. .spb .inl 12 .unl 7 NOTE: If the instruction is CMPC, SCD, SCDR, SCM, or SCMR; then the "desc 2" statement can _n_o_t specify a "ta" field. Descriptor 2 must use the value specified in descriptor 1. To use this feature the "desc 1" statement _m_u_s_t _p_r_e_c_e_e_d the "desc 2" statement. .inl 20 .unl 20 d. ta defines the alphanumeric character type. Its term must be either: 9, 6, or 4. .unl 20 e. tn defines the type of numeric character. Its term must be either 9 or 4. .unl 20 f. sd is the sign and decimal type. Its term must be one of the following characters: .inl 5 .fif .spb f - Floating point, leading sign l - Leading sign, scaled t - Trailing sign, scaled n - No sign, scaled .fin .inl 20 .unl 20 g. sf is the scaling factor. Its term is a signed (or unsigned) decimal number. .unl 20 h. ns is the number of characters or bits in a string. Its term is an unsigned decimal number. .unl 20 i. nn is the number of characters in a numeric string. Its term is an unsigned decimal number that must not be greater than 64. .inl 0 E__x_a_m_p_l_e_s .fif /* Example 1. */ desc 1 -ns 8 -ta 6 -cn 5; /* Example 2. */ desc 3 -cp 2 -bp /* Comments can come between control argument names * and the term. */ 5; /* No ns control argument. This is valid if -mf3 * control argument in inst statement * specified rl term. */ /* Example 3. */ desc 2 -tn 4 -cn 3 -sd n /* No sign. */ -sf -100 -nn 12; .spb 2 D__a_t_a_S__t_a_t_e_m_e_n_t .fin "data" statements are used to describe the data that a descriptor references. Every test requires at least as many data statements as there are descriptors for the EIS instruction being tested. et knows which descriptor references the result data. The data entered for this descriptor is not set up in the data area referenced by the descriptor. Instead this data area is initialized to all zero bits. The input data is saved and used to test the result of the instruction. Some special notes about data statements are given below: 1. For those instructions that both read and write data into the same string (e.g., ad2d, sb2d), the user must enter a "data 3" statement, which describes the resulting data that is referenced by descriptor 2. The data input via the "data 2" statement is the data initially referenced by descriptor 2. 2. The data pointer for each descriptor is set by default to character 0 of word 0 of page 2 of the data area for that descriptor. The user can adjust this data pointer by certain character offsets. (9-bit characters) 3. The input string defined by the user is placed in the data area starting at the _f_i_r_s_t character referenced by the effective data pointer. It is important to remember this. If the descriptor associated with this data area specifies that the first character of the string is _n_o_t character 0 of the first word, then _y_o_u must reserve the missing data when _y_o_u specify the input string. A "data" statement has the following format: data num -control argument data_field ... data_field; 1. The first field in the statement _m_u_s_t be "data". 2. The second field in the statement _m_u_s_t be the number of the data field. It must be either "1", "2", or "3". .spb .inl 12 .unl 7 NOTE: In some cases a "data 3" statement is valid even when there is no third descriptor. In this case it is used to input test data. .inl 0 3. The following control argument field can occur anywhere after the number field. .spb .inl 15 .unl 15 -do X The X field must be a decimal integer from -128 to +4096. It represents a _c_h_a_r_a_c_t_e_r offset from character 0 of the middle page of the data area. .spb .inl 12 .unl 7 NOTE: If the descriptor that points to this data does not use AR or REG modification, then only offsets that are a multiple of 4 are accepted. .inl 0 4. Data can be defined by the following types of data fields. They can be intermixed. The maximum size of the data is 1088 words (4352 characters). .spb .inl 12 .unl 7 NOTE: The data used by EIS instructions is always _s_t_r_i_n_g type data and thus the input modes are limited to the two described below. .inl 14 .unl 10 a. ASCII - Input data can be an ASCII string. It must be enclosed in quotes. The maximum size of any one field is 256 characters. Quote characters can be entered in the string by expressing them as double quotes. ("") .inl 14 .unl 10 b. OCTAL - Data can be entered as a string of octal digits. The first nonoctal digit type character found indicates the end of the string of octal data. The converted octal string is padded on the right with zero bits to make it an integral number of 9 bit characters. .inl 0 5. Repetition Factor (XX) - An unsigned decimal number enclosed in parenthesis can be used to specify the repetition of a field. Only the data field immediately following the repetition field is repeated. .fif E__x_a_m_p_l_e /* Example 1. four characters of data starting at the * beginning of the default data area. */ data 3 "abcd"; /* Example 2. Moves the same data field back two * characters. This splits the string across a page. .spb .inl 0 .unl 7 * NOTE: The input string is the same even though it is entered differently. */ */ data 2 -do -2 "ab" "cd"; /* Example 3. The same as example 2 only it specifies * some of the data in octal. */ data 1 "ab" 143144 -do -2; /* Example 4. A string of: * "12121212121212121212", that is 10 "12" strings. */ data 2 "12" 061062 "1" "2" 061 062 (3) "12" (3) 061062; /* Example 5. The effective data address to be * word 1 of page 2 of the data area. However, the "cn" * field of the descriptor specifies that the first * character of the word that is used is character * 3. Put some fill characters in the first * three characters. */ data 2 -do 4 "***" /* Fill characters. Not * referenced by the instruction. */ "abcd" ; /* The actual data string with which * the instruction works. */ .spb 2 .fin P__a_g_e_S__t_a_t_e_m_e_n_t The "page" statement is used to control page faults during the execution of the EIS instruction. The default case is that no page faults occur. et requires that the user specify those pages on which he wants to take faults. .inl 12 .unl 7 NOTE: If the user specifies a page that is not actually used by the instruction (for example, the third page of a data area that has a one character string), there is no harm. There is also no page fault. .spb .inl 0 All the pages used by an EIS instruction have been assigned names. For pages other than the two instruction area pages, the names can reference physically different pages. Their use by the EIS instruction is always the same. The format of a "page" statement is: page -control argument . . . -control argument ; 1. The first field in the statement _m_u_s_t be the statement name "page". 2. The other fields are control arguments that specify what pages are to have page faults. The following page names are defined: .inl 17 .unl 17 in1 in2 The two pages of the EIS instruction itself. .unl 17 id1 id2 id3 The pages used by descriptors referenced via indirect words. .unl 17 d11 d12 d13 The three pages of data referenced by descriptor 1. .unl 17 d21 d22 d23 The three pages of data referenced by descriptor 2. .unl 17 d31 d32 d32 The three pages of data referenced by descriptor 3. .inl 0 3. If the "-all" control argument is entered, then _a_l_l of the pages defined for this instruction take a page fault. If other control arguments are entered along with the "-all" control argument, then the pages specified do _n_o_t have page faults. .fif E__x_a_m_p_l_e /* Example 1. */ page -in2 -id3 -d32 -d12 -d12 -d11 -id1; /* Example 1. */ page -all; /* Example 3. Take faults on ALL pages EXCEPT * pages in2 and id3 */ page -in2 -all -id3; /* Notice order is not * important. */ .spb 2 E__x_a_m_p_l_e_s__o_f_A__c_t_u_a_l_T__e_s_t_S__c_r_i_p_t_s__a_n_d_T__h_e_i_r_O__u_t_p_u_t /* mlr10 * * This test is the same as the test mlr3 except that * the descriptors use AR, REG, and RL modification * AND uses indirect descriptors. The indirect * words use both REG and AR modification. */ inst mlr -nt "10." -io 1 -mf1 rl 20 ar /* This puts the data in etd1. */ reg /* Use index register 1.. */ idb /* This adds indirect descriptors. Descriptors * go in segments eti1 and eti2. */ -mf2 idb rl 20 reg ar; desc 1 -cn 2; desc 2 -cn 2; data 1 -do -20 " " (5) "abcd" ; data 2 -do -20 000 000 (5) "abcd" ; /* Fill for -cn 2 * must be zeros. */ page -in1 -in2 -d22 -d21 -d11 -d12 -id1 -id2 -id3 -d33; et mlr10 -nox et TEST 1 (mlr) EIS instruction: ( 262|3777 ) Ind Desc. 000172100571 - - - -- - - - 400034000114 -> 100007200005 ( 327|100 ) 500043000115 -> 200016200006 ( 330|100 ) Pointer Registers: ( 262|20 ) pr0 - pr3 777777|1 332|1763 333|1753 777777|1 pr4 - pr7 327|40 330|30 777777|1 777777|1 Index Registers: ( 262|70 ) X0 - X7 17777 4 10 777 4 5 17777 17777 A 000000000024 Q 000000000024 Test Indicators: ( 262|111 ) 000000000200 This test take 8 page faults. in1 in2 id1 d11 d12 id2 d21 d22 data field 1 ( 332|1773 ) 000000141142 143144141142 143144141142 143144141142 143144141142 143144 data field 2 ( 333|1773 ) Result data field initialized to all zero bits. test data ( 262|15776 ) xxxxxxxxxxxx xxxxxxxxxxxx 040040141142 143144141142 143144141142 143144141142 143144141142 143144xxxxxx xxxxxxxxxxxx xxxxxx /* Test mvt instruction. */ inst mvt -nt "3" -fc /* Char is octal 1. */ -mf1 rl 3 ar reg idr -mf2 ar reg ida -mf3 reg ar; desc 2 -ns 8; data 1 -do -2 003 002 001; data 2 -do -6 "321111" "11"; data 3 -do -1 "0" "123"; page -all -in2; et TEST 1 (mvt) EIS instruction: ( 262|4000 ) Ind Desc. - - - -- - - - 001132160571 051774000014 -> 100007000005 ( 262|52000 ) 500050000100 -> 200016000010 ( 330|100 ) 300025000113 Pointer Registers: ( 262|20 ) pr0 - pr3 777777|1 332|1767(18) 333|1756(18) 334|1747(27) pr4 - pr7 777777|1 330|30 777777|1 777777|1 Index Registers: ( 262|70 ) X0 -X7 17777 4 10 777 4 5 17777 17777 A 000000000003 Q 000000017777 Test Indicators: ( 262|111 ) 000000000200 This test takes 11 page faults. id1 d11 d12 d13 id2 d21 d22 d23 d31 d32 d33 data field 1 ( 332|1777(18) ) 003002 001 data field 2 ( 333|1776(18) ) Result data field initialized to all zero bits. data field 3 ( 334|1777(27) ) 060 061062063 test data ( 262|15776 ) xxxxxxxxxxxx xxxxxxxxxxxx 063062061061 061061061061 xxxxxxxxxxxx xxxxxxxxxxxx  get_device_status.plm.compin 03/29/79 1424.5r w 03/17/78 1226.4 4788 .ifi init_plm "AN51" .srv section 1 .ifi l1h "N__a_m_e: get_device_status, gds" The get_device_status command prints the current assignment of the specified device. If the calling process has hphcs_ privileges, the command prints the process_group_id of the process to which the device is assigned. Otherwise, it just reports the device as being assigned to another process. .ifi l2h "Usage" get_device_status ionames .spb 2 where ionames are the names of I/O devices about which information is desired. .fin .inl 0  get_lock_id_.plm.compin 03/29/79 1424.5r w 03/22/78 1241.9 5103 .ifi init_mpm "AN51" .srv section 2 .ifi l2h "N__a_m_e: get_lock_id" The get_lock_id_ subroutine returns the 36-bit unique lock ID to be used by a process in setting locks. By using this lock ID a convention can be established so that a process wishing to lock a data base and finding it already locked can verify that the lock is set by an existing process. .ifi l2h "Usage" declare get_lock_id_ entry (bit(36) aligned); .spf call get_lock_id_ (lock_id); .spb 2 where lock_id is the unique identifier of this process. (Output) .fin .inl 0 .brp  get_prim_nam_.plm.compin 03/29/79 1424.6r w 03/28/78 0824.4 12096 .ifi init_plm "AN51" .srv section 2 .ifi l2h "N__a_m_e: get_primary_name" The get_primary_name_ subroutine locates a segment in a given directory, and returns the first, or primary, name of that segment. For example, if foo.archive is the primary name of an archive that contains component able.pl1, and if able.pl1 is another name on the archive, then get_primary_name_ returns the name foo.archive when called with the name able.pl1. .ifi l2h "Usage" .all .inl 10 .unl 5 declare get_primary_name_ entry (char(*), char(*), char(*), fixed!bin(35)); .unl 5 .spf call get_primary_name_ (dir_name, entryname, prime_name, code); .spf 2 .alb .inl 0 where: .spf .inl 12 .unl 12 1. dir_name (Input) .brf is the directory to be searched. .spf .unl 12 2. entryname (Input) .brf is the name of the segment to be located. .spf .unl 12 3. prime_name (Output) .brf is the primary name of the segment, if it is found. .unl 12 .spf 4. code (Output) .brf is a nonstandard status code; see Note below. .inl .ifi l2h "Note" On return, if code = 0, the segment was found, and prime_name is the primary name of the segment. If code = 1, then the segment was not found in the directory searched. Any other value of code is a standard status code returned from a call to hcs_$status_.  grab_tape_drive.plm.compin 03/29/79 1424.6r w 03/17/78 0817.6 14841 .ifi init_mpm "AN51" .srv section 1 .ifi l2h "N__a_m_e: grab_tape_drive, gtd" The grab_tape_drive command allows the user to request a number of nine and/or seven track tape drives and have a given command executed when the tape drives are simultaneously available. The grab_tape_drive command checks the tape drive command configuration every 10 seconds and when there are sufficient drives available, the given command is executed. .ifi l2h "Usage" grab_tape_drive -control_args- command_line .spf 2 where control_args may be taken from the following list: .spf .inl 12 .unl 5 -t9 n finds _n free 9 track tape drives before executing the command line. The default if -t9 n and -t7 n are both omitted is one 9 track drive. spf .unl 5 -t7 n finds _n free 7 track tape drives before executing the command line. spf .unl 5 -info, in lists the tape drive configuration and!returns without further processing. spf .unl 5 -long, -lg lists the tape drive configuration every minute. spf .unl 20 2. command_line is the (optional) command line to be executed when the specified number of tape drives are free. .inl 0 .ifi l2h "Notes" It is possible for a tape drive to be attached by another process after grab_tape_drive finds the drive free and before the caller's program is executed and attaches the drive. If the command to be executed calls com_err_ with the system code "no device available", grab_tape_drive continues to check the tape drive configuration and retry the command. Such a retry is attempted five times. .spf 2 This command requires access to certain privileged gates into the supervisor.  hash_.plm.compin 03/29/79 1424.6r w 04/05/78 1429.4 58320 .ifi init_mpm "AN51" .srv section 2 .ifi l2h "N__a_m_e: hash_" The hash_ subroutine is used to maintain a hash table It contains entry points that initialize a hash table and insert, delete, and search for entries in the table. .spb A hash table is used to locate entries in another data table when the length of the data table or the frequency with which its entries are referenced makes linear searching uneconomical. .spb A hash table entry contains a name and a value. The name is a character string (of up to 32 characters) that is associated in some way with a data table entry. The value is a fixed binary number that can be used to locate that data table entry (for example, an array index or an offset within a segment). The entries in the hash table are arranged so that the location of any entry can be computed by applying a hash function to the corresponding name. .spb It is possible for several names to hash to the same location. When this occurs, a linear search from the hash location to the first free entry is required, to find a place for a new entry (if adding), or to find out whether an entry corresponding to the name exists (if searching). The more densely packed the hash table, the more likely this occurence is. To maintain a balance between efficiency and table size, hash_ keeps a hash table approximately 75% full, by rehashing it (i.e. rebuilding it in a larger space) when it becomes too full. .spb The number of entries is limited only by the available space. The table uses eight words per entry plus ten words for a header. If an entire segment is available to hold the table, it may have over 32,000 entries. .ifi l2h "E__n_t_r_y: hash_$make" This entry point initializes an empty hash table. The caller must provide a segment to hold it, and must specify its initial size (see hash_$opt_size). .ifi l2h "Usage" declare hash_$make entry (ptr, fixed!bin, fixed!bin(35)); .spb call hash_$make (table_ptr, size, code); .spb 2 where: .spf .inl 12 .unl 12 1. table_ptr (Input) .brf is a pointer to the table to be initialized. .spb .unl 12 2. size (Input) .brf is the initial number of entries. .spb .unl 12 3. code (Output) .brf is a standard status code. It will be zero if there is no error, or error_table_$invalid_elsize if size is too large. .inl 0 .ifi l2h "E__n_t_r_y: hash_$opt_size" This entry point, given the number of entries to be placed in a new hash table initially, returns the optimal size for the new table. This function is used when rehashing a full hash table, and should be used when making a new hash table. .ifi l2h "Usage" declare hash_$opt_size entry (fixed!bin) returns (fixed!bin); .spf size=hash_$opt_size (n_entries); .spb 2 where: .spf .inl 12 .unl 12 1. n_entries (Input) .brf is the number of entries to be added. .spb .unl 12 2. size (Output) .brf is the optimal table size for that number of entries. .inl 0 .ifi l2h "E__n_t_r_y: hash_$in" This entry point adds an entry to a hash table. If the additional entry would make the table too full, the table will be rehashed before the new entry is added (see the description of the rehash_ subroutine). .ifi l2h "Usage_" declare hash_$in entry (ptr, char(*), fixed!bin, fixed!bin(35)); .spf call hash_$in (table_ptr, name, value, code); .spb 2 where: .spf .inl 12 .unl 12 1. table_ptr (Input) .brf is a pointer to the hash table. .spb .unl 12 2. name (Input) .brf is a name associated with a data table entry. It may be up to 32 characters long. .spb .unl 12 3. value (Input) .brf is the locator (e.g. index or offset) of the data table entry associated with the following values: .spb 0 entry added successfully .brf error_table_$segnamdup entry already exists, with same value .brf error_table_$namedup entry already exists, with different values .brf error_table_$full_hashtbl hash table is full and there is no room to .brf rehash it into a larger space .inl 0 .ifi l2h "E__n_t_r_y: hash_$inagain" This entry point adds an entry to a hash table. It is identical to the hash_$in entry except that it will never try to rehash the table. The new entry will be added unless the tape is completely full. This entry point is used by the rehash_ subroutine to avoid loops. It can also be used by an application that has a hash table imbedded in a larger data base, where automatic rehashing would damage the database. .ifi l2h "Usage" declare hash_$inagain entry (ptr, char(*), fixed!bin, fixed!bin(35)); .spf call hash_$inagain (table_ptr, name, value, code); .spb 2 where the arguments are the same as those for the hash_$in entry point, above. .inl 0 .ifi l2h "E__n_t_r_y: hash_$search" This entry point searches a hash table for a given name and returns the corresponding locator value. .ifi l2h "Usage" declare hash_$search entry (ptr, char(*), fixed!bin, fixed!bin(35)); .spf call hash_$in (table_ptr, name, value, code); .spb 2 where: .spf .inl 12 .unl 12 1. table_ptr (Input) .brf is a pointer to the hash table. .spb .unl 12 2. name (Input) .brf is the name to be searched for. It may be up to 32 characters long. .spb .unl 12 3. value (Output) .brf is the locator value corresponding to name. .spb .unl 12 4. code (Output) .brf is a standard status code. It can be: .spf 0 name was found .brf error_table_$noentry name was not found in the hash table .inl 0 .ifi l2h "E__n_t_r_y: hash_$out" This entry point deletes a name from the hash table. .ifi l2h "Usage" declare hash_$out entry (ptr, char(*), fixed!bin, fixed!bin(35)); .spf call hash_$out (table_ptr, name, value, code); .spb 2 where: .spf .inl 12 .unl 12 1. table_ptr (Input) .brf is a pointer to the hash table. .spb .unl 12 2. name (Input) .brf is the name to be deleted. Its maximum length is 32 characters. .spb .unl 12 3. value (Output) .brf is the locator value corresponding to name. .spb .unl 12 4. code (Output) .brf is a standard status code. It can be: .spf 0 name was found and deleted .brf error_table_$noentry name was not found in the hash table  instr_speed.plm.compin 03/29/79 1424.6r w 03/14/78 1234.1 6111 .ifi init_plm "AN51" .srv section 1 .ifi l1h "N__a_m_e: instr_speed" This command attempts to measure the speed of a processor by timing a series of code sequences. The code sequences are chosen to test the more common and important sequences of instruction as well as to get a general idea of the limiting speed which can be expected. It is generally useful to previously select a given processor (with the use of the set_proc_required command) before running timing tests. .ifi l2h "Usage" instr_speed .ifi l2h "Note" Code sequences which take longer than expected, probably due to interrupt or fault action, are factored out and not counted. .fin .inl 0  list_assigned_devices.plm.compin03/29/79 1424.7r w 03/07/78 1102.4 4320 .sr Name "list_assigned_devices" .sr Line "_____________________" .sr Section "1" .sr Volume "AN51" .ifi PLM_head N__a_m_e: list_assigned_devices, lad .spb The list_assigned_devices command prints the device name of all devices assigned to the calling process as reflected by the assignment table in ring 0. It does not use the per-process attach table and can be useful if that table has been rendered incorrect. .spb 2 U__s_a_g_e .spb list_assigned_devices  list_sub_tree.plm.compin 03/29/79 1424.7r w 03/28/78 0805.7 11331 .ifi init_plm "AN51" .srv section 2 .ifi l2h "N__a_m_e: list_sub_tree, list" The list_sub_tree command lists the segments in a specified subtree of the hierarchy. The complete subtree is listed unless the -depth control argument is specified. .ifi l2h "Usage" list_sub_tree {path} {-control_args} .spb 2 where: .spb .inl 12 .unl 12 1. path (Input) .brf is the pathname of the subtree to be listed. The last pathname specified is the only one listed. If no pathname is given, the subtree under the working directory is listed. .spf .unl 5 -all, -a .brf prints all the names of each segment. The default is to print only the primary names. .spb .unl 5 -depth N, -dh N .brf specifies the depth in the hierarchy that is to be scanned. The depth is relative to the base of the specified subtree. N must be a decimal integer. .inl 0 .ifi l2h "Notes" For each level in the hierarchy that is listed, the names are indented three more spaces, making it possible to see exactly which segments exist at what depth in the hierarchy. .spf 2 For each segment listed, two numbers are listed out. The first is the number of records used by the segment and the second is an obsolete quantity (device_id) that should be ignored.  print_dump_tape.plm.compin 03/29/79 1424.9r w 03/21/78 1303.7 9450 .ifi init_mpm "AN51" .srv section 1 .ifi l2h "N__a_m_e: print_dump_tape, pdt" This command is used to print the BOS dump tapes. These tapes are written as unblocked BCD records. .ifi l2h "Usage" print_dump_tape -control_arguments- .spb 2 where the control arguments can be chosen from the following list: .spb .inl 12 .unl 7 tape_number .brf is the number of the dump tape to be printed. If this option is not specified, "*** dump tape ***" is used in the mount message. .spb .unl 7 printer .brf is the name of the printer to be used. This name must begin with "prt". If this option is not specified, "prtb34" is used. .spb .unl 7 -file pathname .brf is used to direct the output into a file instead of printing it online. .spb .unl 7 -page page_no .brf is used to start printing the tape at the specified page number. .inl 0 .ifi l2h "Notes" The following I/O switches are used: .spb .inl 12 .unl 7 dump_tape_in .brf for input .spb .unl 7 dump_to_printer .brf for output (usually to a printer but possibly to a file) .inl 0  print_gen_info_.plm.compin 03/29/79 1425.0r w 03/07/78 1103.7 13140 .sr Name "print_gen_info_" .sr Line "_______________" .sr Section "2" .sr Volume "AN51" .ifi PLM_head N__a_m_e: print_gen_info_ .spb The print_gen_info_ subroutine is used to print out general information about an object segment. The format of the output is the same as the print_gen_info command. .spb 2 U__s_a_g_e .spb declare print_gen_info_ entry (ptr, fixed bin(24), .brf char(*), fixed bin(35)); .spb call print_gen_info_ (p, bc, stream, code); .spb where: .spb .inl 15 .unl 15 1. p is a pointer to the object segment of interest. (Input) .spb .unl 15 2. bc is the bit count of the object segment. (Input) .spb .unl 15 3. stream is the name of the I/O switch over which the information is to be output. (Input) .spb .unl 15 4. code is a standard Multics status code. (Output) .spb 2 .inl 0 E__n_t_r_y: print_gen_info_$component .spb This entry prints the information about a particular component of a bound segment over the I/O switch specified. .spb 2 U__s_a_g_e .spb declare print_gen_info_$component entry (ptr, .brf fixed bin(24), char(*), fixed bin(35), char(*)); .spb call print_gen_info_$component (p, hc, stream, code, name); .spb where: .spb .inl 15 .unl 15 1-4. are the same as the print_gen_info_ entry. .spb .unl 15 5. name is the name of the component within the bound segment for which information is to be printed. (Input.  print_sample_refs.plm.compin 03/29/79 1425.1r w 03/21/78 1214.7 27945 .ifi init_mpm "AN51" .srv section l .ifi l2h "N__a_m_e: print_sample_refs, psrf" The print_sample_refs command interprets the three data segments produced by the sample_refs command, and produces a printable output segment which contains the following information: a detailed trace of segment references; a segment number to pathname dictionary; and histograms of the Procedure Segment Register (PSR) and Temporary Segment Register (TSR) segment reference distributions. (See the description of the sample_refs command.) .ifi l2h "Usage" print_sample_refs name -brief .spb 2 where: .spb .inl 12 .unl 12 1. name specifies the names of the data segments to be interpreted, as well as the name of the output segment to be produced. name may be either an absolute or relative pathname. If name does not end with the suffix srf, it is assumed. .spf 2 The appropriate directory is searched for three segments with entrynames as follows: .spf (entry portion of) name.srf1 .brf (entry portion of) name.srf2 .brf (entry portion of) name.srf3 .spf 2 The output segment is placed in the user's working directory with the entryname: .spf (entry portion of) name.list .spf .unl 12 2. -brief, -bf .brf specifies that the detailed trace of segment references is not to be generated. .inl .ifi l2h "Notes" The print_sample_refs command is able to detect a reused segment number. The appearance of a parenthesized integer preceding a segment number indicates reusage. .spb 234|6542 >udd>user>bound_alpha_|6542 .brf (1) 234|2104 >udd>user>max35|512 .brf (2) 234|6160 >system_library_languages>assign_|6160 .spb .bbk The occurrence of the above three lines in the detailed trace indicates the following: .brf .spb .inl 10 .unl 5 1. a reference was made to location 6542 in bound_alpha_. The particular component of bound_alpha_ being referenced could not be determined. bound_alpha_ was assigned segment number 234. .spb .unl 5 2. a reference was made to location 512 in max35. max35 is a component of a bound segment whose name can be determined from the segment number to pathname dictionary. The segment bound_alpha_ has been terminated and, when the segment of which max35 is a component was initiated, it was assigned segment number 234. .spb .unl 5 3. a reference was made to location 6160 in assign_. The segment of which max35 is a component has been terminated and, when assign_ was initiated, it was assigned segment number 234. .inl 0 .spb The appearance of a segment number suffix (i.e., 1, 2, etc.) indicates a component of a bound segment. .spf 310 >system_library_standard>bound_ti_term_ .brf 310.1 tssi_ .brf 310.2 translator_info_ .spf The appearance of the above lines in the segment number to pathname dictionary indicate that tssi_ was the first component of bound_ti_term_ to be referenced, and that translator_info_ was the second component of bound_ti_term_ to be referenced. .brf .~ Under "Name": sample_refs command .bek  print_translator_s.plm.compin 03/29/79 1425.1r w 03/21/78 1205.5 2475 .ifi init_mpm "AN51" .srv section 1 .ifi l2h "N__a_m_e: print_translator_search_rules, ptsr" The print_translator_search_rules command prints the current translator search rules in effect for the calling process. .ifi l2h "Usage" print_translator_search_rules  ring_zero_peek_.plm.compin 03/29/79 1425.2r w 03/21/78 1204.3 8469 .ifi init_mpm "AN51" .srv section 2 .ifi l2h "N__a_m_e: ring_zero_peek_" The ring_zero_peek_ subroutine is used to extract data from the hardcore supervisor. Data that is not generally available to normal users is returned only to privileged users. .ifi l2h "Usage" declare ring_zero_peek_ entry (ptr, ptr, fixed!bin (18), .brf fixed!bin (35)); .spb call ring_zero_peek_ (ptr0, ptr_user, nwords, status); .spb 2 where: .spf .inl 12 .unl 12 1. ptr0 (Input) .brf is a pointer to the data in ring 0 that is to be copied out. .spb .unl 12 2. ptr_user (Input) .brf is a pointer to the region in the user's address space where the data is to be copied. .spb .unl 12 3. nwords (Input) .brf is the number of words to be copied. .spb .unl 12 4. status (Output) .brf is a returned status code whoch is nonzero if the user did not have access to the requested data.  s1ft.plm.compin 03/29/79 1425.2r w 03/07/78 1104.1 11826 .ifi init_plm "AN51" .sr section 1 .sr Charsw -1 .ifi l0h "Commands" This Program Logic Manual (PLM) is not structured in the same manner as most others in this series. The S__y_s_t_e_m T__o_o_l_s PLM consists only of a number of command and subroutine descriptions with no design motivation, implementation description, or data structure description except what is needed to describe the use of the command or subroutine as a tool. If design and implementation documentation is desired for a particular command, it should be available in the C__o_m_m_a_n_d I__m_p_l_e_m_e_n_t_a_t_i_o_n PLM, Order No. AN67, in this series. The I__n_d_e_x PLM, Order No. AN50, may be of use in trying to find out which command or subroutine may be wanted and in which PLM a detailed description can be found. .spb 2 This section, command descriptions, is arranged alphabetically. For programs that consist of a set of several related commands, the set may be documented within one command description. Also, the set is arranged according to the order in which the commands are used rather than alphabetically. .brf .~ first paragraph: C__o_m_m_a_n_d I__m_p_l_e_m_e_n_t_a_t_i_o_n PLM, Order No. AN67 .~ and I__n_d_e_x PLM, Order No. AN50 .fin .inl 0 .brp  s2ft.plm.compin 03/29/79 1425.3r w 03/07/78 1104.1 7038 .ifi init_plm "AN51" .sr section 2 .sr Charsw -1 .ifi l0h "Subroutines" This section consists only of subroutine descriptions; no design motivation, implementation description, or data structure description is included except what is needed to describe the use of the subroutine as a tool. If a more detailed description is desired, check the I__n_d_e_x PLM, Order No. AN50, to find out which PLM contains more material on a specific subroutine. .spb 2 This section, subroutines, is arranged alphabetically. For programs that consist of a set of several related subroutines, the set may be documented within one subroutine description. Also, the set is arranged according to the order in which the subroutines are used rather than alphabetically. .fin .inl 0 .brp  sample_refs.plm.compin 03/29/79 1425.3r w 03/23/78 0759.1 28854 .ifi init_mpm "AN51" .srv section 1 .ifi l2h "N__a_m_e: sample_refs, srf" The sample_refs command periodically samples the machine registers in order to determine which segments a process is referencing. Three output segments are produced, that are interpretable by the print_sample_refs command. (See the description of the print_sample_refs command.) .ifi l2h "Usage" sample_refs -control_args- .spb 2 where control_args can be chosen from one of the following two control groups: .spb 1. arguments that initiate sampling are: .spb .inl 12 .unl 5 -time _n .brf specifies the rate in milliseconds!!at!!which .unl 5 -tm _n .brf the process is sampled. _n must be a positive integer. The default is _n = 1000; i.e., the process is sampled once every second. .spb .unl 5 -segment name .brf specifies the names to!!be!!given!!the!!three .unl 5 -sm name .brf output segments. name can be either an absolute or relative pathname. If name does not end with the suffix srf, it is assumed. The output segments are named as follows: .spf .unl 5 (entry portion of) name.srf1 .unl 5 (entry portion of) name.srf2 .unl 5 (entry portion of) name.srf3 .spb The default causes the output segments to be placed in the user's working directory, with entrynames as follows: .spf .unl 5 mm/dd/yy__hhmm.m_zzz_www.srf1 .unl 5 mm/dd/yy__hhmm.m_zzz_www.srf2 .unl 5 mm/dd/yy__hhmm.m_zzz_www.srf3 .spb .unl 12 2. the argument that terminates sampling is: .spb .unl 5 -reset .brf specifies that the process is no longer to be .unl 5 -rs .brf sampled. .inl .ifi l2h "Notes" Only one active invocation per process is permitted. Attempting a secondary invocation of sample_refs causes the first invocation to be terminated, whereupon the new invocation proceeds normally. .spb 2 The machine registers can be sampled only when the process is running in a ring other than ring 0. Were a process to use, for example, a total of 100 seconds of processor time, and sample_refs, running at a sample rate of _n = 1000, were to record only 23 samples, it would indicate that 77 seconds of processor time were spent in ring 0. .spb 2 Under certain conditions, the contents of one of the machine registers sampled--the Temporary Segment Register (TSR)--can be invalid. This invalidity is noted, but does not necessarily indicate that the process is in error. .spb 2 At the maximum sample rate, 1 millisecond, execution time can be increased by as much as 50%. Using a 1 second sample rate, the increase in execution time is negligible. .spb 2 Accuracy of sample rates less than 1000 milliseconds (sample rates _n < 1000) is not guaranteed due to load factors. The accuracy of such sample rates _i_n_c_r_e_a_s_e_s with load. .spb 2 If the process being sampled should be terminated without an invocation of sample_refs with the -reset option, interpretable output segments are still produced; however, both the off-time and the last recorded sample can be invalid. .brf .~ Under "name": print_sample_refs command  send_admn_com.plm.compin 03/29/79 1425.4r w 03/22/78 1244.1 12636 .ifi init_mpm "AN51" .srv section 1 .ifi l1h "N__a_m_e: send_admin_command, sac" The send_admin_command command can be used by authorized system administrators to request execution of commands by the initializer process, and to change the admin mode password. .spb 2 This command can be used to send a command to the initializer. .ifi l2h "Usage" sac commandline .spf 2 where commandline is the desired command line. It must be 80 characters or less. If it contains embedded blanks, they must be enclosed in  quotes. .ifi l2h "Notes" The command line is stored in the segment, >system_control_dir>communications, and a wake-up is sent to the initializer. When the wake-up is received, the initializer types a message, executes the command, and stores the message in log. .spb 2 To print any unexecuted command in system_control_dir>communications type: .spf sac -print .spb 2 To cancel an unexecuted command in system_control_dir>communications type: .spf sac -cancel .spb 2 To change the operator password for admin mode (also stored in system_control_dir>communications) type: .spb sac -chpass .brf or .brf sac -cp. .spb 2 The command requests both the old password and the new password. .spb 2 The new password is stored in the segment and an online message sent to the operator explaining that the password has been changed.  set_proc_required.plm.compin 03/29/79 1425.4r w 03/23/78 0922.1 6156 .ifi init_mpm "AN51" .srv section 1 .ifi l2h "N__a_m_e: set_proc_required, sprq" The set_proc_required command is primarily used as a processor T&D aid when it is desired to run a particular (set of) program(s) on a particular CPU. It instructs the scheduler to restrict the calling process to run only on the specified processor. The current configuration can be determined with the print_configuration_deck command. .ifi l2h "Usage" set_proc_required cpu_tag .spb where cpu_tag is the character string representation of the processor tag for the CPU to be selected. .ifi l2h "Example" set_proc_required a .brf .~ Under "Name": print_configuration_deck command  setquota.plm.compin 03/29/79 1425.4r w 03/23/78 0720.4 9306 .ifi init_mpm "AN51" .srv section 1 .ifi l2h "N__a_m_e: setquota, sq" The setquota command requires access to the highly privileged gate and places an arbitrary secondary storage quota on a specified directory. .ifi l2h "Usage" setquota pathname1_ quota1_ ... pathname_n quota_n .spb 2 where: .spb .inl 12 .unl 12 1. pathname_i .brf is the name of the directory on which the quota is to be placed. The active function wd can be used to specify the working directory. .spb .unl 12 2. quota_i .brf is the quota in 1024 word pages to be placed on the directory. .inl 0 .ifi l2h "Examples" setquota > 29902 .spf setquota >udd>Multics>Jones 0 .ifi l2h "Note" No permission in the directory is required to use this command. It is not necessary that the new quota be greater than the current number of pages being used by this directory. This command causes the directory to have a terminal quota even if it is set to zero. This command does not cause the inferior counts of the superior directory to be updated.  system_info_.plm.compin 03/29/79 1425.5r w 03/22/78 1118.0 21519 .ifi init_mpm "AN51" .srv.section 1 .ifi l2h "N__a_m_e: system_info_"  The entry points discussed in this description are provided by the system_info_ subroutine for the use of system modules in addition to those described in the M_P_M_ S__u_b_r_o_u_t_i_n_e_s, Order No. AG93. .spb 2 The following entry points are documented in the M_P_M_ S__u_b_r_o_u_t_i_n_e_s: .spb .inl 5 .fif system_info_$device_prices system_info_$device_rates system_info_$installation_id system_info_$next_shutdown system_info_$prices system_info_$rates system_info_$shift_table system_info_$sysid system_info_$timeup system_info_$titles system_info_$users .inl 0 .ifi l2h "Entry: system_info_$abs_chn" This entry returns the event channel and process ID for the process that is running the absentee user manager. .ifi l2h "Usage" .inl 10 .unl 5 .all declare system_info_$abs_chn entry (fixed bin(71), bit(36) aligned); .spf .unl 5 call system_info_$abs_chn (ec, pid); .spf 2 .inl 0 .alb where: .spf .fin .inl 12 .unl 12 1. ec (Output) .brf is the event channel over which signals to absentee_user_manager_ should be sent. .spf .unl 12 2. pid (Output) .brf is the process ID of the absentee manager process (currently the initializer). .inl 0 .ifi l2h "Entry: system_info_$next_shift_change This entry point returns the time of the next shift change. .ifi l2h "Usage" .all .inl 10 .unl 5 declare system_info_$next_shift_change entry (fixed bin, fixed!bin(71), fixed!bin) .spf .unl 5 call system_info_$next_shift_change (nowshift, changetime, newshf); .spb 2 .inl 0 where: .spf .inl 12 .unl 12 1. nowshift (Output) .brf is the current shift number. .spf .unl 12 2. changetime (Output) .brf is the time the shift changes. .spf .unl 12 3. newshf (Output) .brf is the shift after changetime. .inl 0 .ifi l2h "E__n_t_r_y: system_info_$shift_table" This entry point returns the system's local shift definition table. .ifi l2h "Usage" declare system_info_$shift_table ((336) fixed bin); .spf call system_info_$shift_table (stt); .spf 2 where stt (Output) is a table of shifts, indexed by half-hour within the week. stt(1) gives the shift for 0000-0030 Mondays, etc. .~ Under "Name": M_P_M_ S__u_b_r_o_u_t_i_n_e_s, Order No. AG93 .fin .inl 0 .brp  teco_error.plm.compin 03/29/79 1425.5r w 03/14/78 1225.3 3285 .ifi init_mpm "AN51" .srv section 1 .ifi l1h "N__a_m_e" The teco_error subroutine, which is most frequently used as a command, prints the long form of a teco error message given the short term. .ifi l2h "Usage" declare teco_error entry (char(*)); .spf call teco_error (name); .spf 2 where name is the short form of a teco error message. (Input)  teco_gt_mcro_.plm.compin 03/29/79 1425.6r w 03/23/78 1004.1 7866 .ifi init_mpm "AN51" .srv section 2 .ifi l2h "N__a_m_e: teco_get_macro_" The teco_get_macro_ subroutine is called by teco to search for an external macro. .spb 2 By default the following directories are searched: .spb .fif 1. working directory 2. home directory 3. system_library_tools .fin .ifi l2h "U__s_a_g_e" .all .inl 10 .unl 5 declare teco_get_macro_ entry (char(*) aligned, ptr, fixed!bin, fixed!bin(35)); .spb .unl 5 call teco_get_macro_ (mname, mptr, mlen, code); .alb .unl 10 .spb 2 where: .spb .inl 12 .unl 12 1. mname (Input) .brf is the name of the macro to be found. .spb .unl 12 2. mptr (Output) .brf is a pointer to the macro. .spb .unl 12 3. mlen (Output) .brf is the length of the macro. .spb .unl 12 4. code (Output) .brf is a standard Multics status code.  teco_ssd.plm.compin 03/29/79 1425.6r w 03/22/78 0947.4 4383 .ifi init_mpm "AN5[" .srv section 1 .ifi l2h "N__a_m_e: teco_ssd" The teco_ssd command allows the user to specify a directory for teco to search when trying to find a teco macro to execute. The directory so specified is searched instead of the user's directory. .ifi l2h "Usage" teco_ssd path .spb where path is the absolute pathname of a directory to be searched by teco_get_macro_ instead of the user's home directory. .brf .~ Under "Usage": teco_get_macro_ subroutine  test_cpu.plm.compin 03/29/79 1425.6r w 03/22/78 0922.1 8082 .ifi init_mpm "AN51" .srv section 1 .ifi l2h "N__a_m_e: test_cpu" This command is a processor T & D aid used to check out the hardware status of processors. It contains a number of simple test programs that have brought out 6180 processor problems in the past. The program is occasionally updated to include new test cases as they are developed. The primary use of the command is to verify that the processors are still working correctly (generally after some independent processor change is made) for at least the small set of test cases contained in the program. .ifi l2h "Usage" test_cpu -testname- .spf 2 If a control argument is given, it is interpreted as the name of one of the test cases available. If no control argument is given, all tests are run. If more than one control argument is given, a list of all legal test cases is printed but no tests are actually run.  test_tape.plm.compin 03/29/79 1425.7r w 03/22/78 0944.9 29718 .ifi init_mpm "AN51" .srv section 1 .ifi l2h "N__a_m_e: test_tape" The test_tape command invokes a Device Interface Module (DIM) whose only function is to write and read a tape to determine its reliability. It reports all hardware detected errors (parity, read after write, etc.) and the software detected incorrect data condition. The test_tape command can also be used to do compatibility checks between drives (i.e., write a tape on one, read it on another). .ifi l2h "U__s_a_g_e" test_tape mode pattern count volumeid density .spb 2 where: .spb .inl 12 .unl 12 1. mode .brf is the mode of the test. If the character -w is present in the mode string, then the tape is written. If -r is present, then the tape is read. Either -wr or -rw are also legal, but note that the tape is always written first and read second. .spb .unl 5 2. pattern .brf specifies the word of octal data to be used to fill the buffers. It should take the form -ptrn followed by a space and up to 12 octal digits. If less than 12 digits are given, the field is padded on the left with zeros. .spb .unl 5 3. count .brf indicates the number of writes to be performed in creating the tape. Each write operation creates three 272-word physical records. .inl 0 .ifi l2h "N__o_t_e_s" If no arguments are specified, the tape is both written and read, with a data pattern of 525252525252, for the entire length of the tape. .spb 2 The test_tape command senses the end of tape mark (EOT) and stops even if the record count has not been exhausted. .spb 2 This command has four control arguments that control what happens when an error is encountered. They are: .spb .inl 12 .unl 12 print,noprint .brf controls printing of an error when it occurs. Statistics are kept of all errors. The default is print. .spb .unl 12 halt,nohalt .brf tells test_tape to terminate when an error is encountered. The default is nohalt. .spb .unl 12 retry,noretry .brf specifies that if the I/O is in error that it should be retried. test_tape retries 25 times before giving up. Statistics are kept of all recoverable errors. The default is retry. .spb .unl 12 sleep,nosleep .brf specifies that test_tape should sleep when a nonrecoverable error is found. This allows the operator to mark the tape. The program pauses for two minutes and then continues. The default is nosleep. .spb 2 .inl 0 These control arguments can be changed by using the change entry point of test_tape. The change control argument accepts up to 99 arguments, each of which can be one of the above or the string options. The latter causes test_tape to print the control arguments in effect. .ifi l2h "E__x_a_m_p_l_e_s" test_tape$change sleep noprint options .spb results in the sleep control argument being enabled, the print control argument being disabled, and a list of the current control arguments being printed. .spb 2 The change entry offers another advantage in that the user can quit out of an executing test and change the current control arguments. In the example the user has decided that he is getting too much output and wishes to stop the printing. He presses the QUIT button and types: .spb test_tape$change noprint; start .spb The change takes effect immediately.  unasign_devic.plm.compin 03/29/79 1425.9r w 03/21/78 1451.0 7668 .ifi init_mpm "AN51" .srv section 1 .ifi l2h "N__a_m_e: unassign_device" The unassign_device command causes the specified I/0 device to become unassigned using the facilities of the Hardcore Ring I/0 Assignment Manager (IOAM). If the caller has the ability to call hphcs_ entries, this command works for a device attached to any process; otherwise it works only for devices attached to the calling process. .spb 2 This command bypasses the attach table of the relevant process, thus leaving it in an inconsistent state, with possible dire consequences for the process if it should use the switch again. Normally, a user should never need to use this. The io_call command should be used to detach a device from command level. .ifi l2h "Usage" unassign_device ionames .spf 2 where ionames are the names of I/O devices to be freed.  value.plm.compin 03/29/79 1426.0r w 03/22/78 1155.2 18405 .ifi init_mpm "AN51" .srv section 1 .ifi l1h "N__a_m_e: value" The value command returns a character string associated with a named item in a user symbol table segment. This enables administrative exec_com segments to reference variables. .spf 2 Command entry points are provided to set entries in the symbol table and to list the symbol table. .ifi l2h "E__n_t_r_y" This entry is meant to be called as an active function. It looks up its argument in the segment value_seg in the user's current working directory, and returns the value associated with the argument. If no value is found, the string undefined is returned. .ifi l2h "Usage" [value ident] .ifi l2h "Note" This call returns the value associated with ident to the command processor. .ifi l2h "E__n_t_r_y: value$set" This command entry can set entries in value_seg or delete entries from value_seg. .ifi l2h "Usage" value$set ident val .spf .inl 4 .unl 4 Sets identifier ident to have the value val. .spf .inl 0 value$set ident .spf .inl 4 .unl 4 Removes the definition of ident from value_seg. .inl 0 .ifi l2h "Note" Both ident and val can be up to 32 characters long. .ifi l2h "E__n_t_r_y" This command entry lists particular values in value_seg or lists the whole segment. .ifi l2h "Usage" value$dump ident .spf lists the value of ident. .spf value$dump .spf lists the contents of value_seg. .ifi l2h "E__n_t_r_y" This command entry causes the value command and active function to use a value_seg given by pathname. .ifi l2h "Usage" value$set_seg path .spf 2 where path causes the value command to use the segment identified by path instead of value_seg for the rest of the process or until another call to value$set_seg. .ifi l2h "Note" For this entry only, if the symbol table segment does not exist, it is created. .ifi l2h "Example:" .fif value$set it output_file value$set name1 """John Smith""" .spf dprint -he [value name1] [value it] .fin .inl 0 .brp  virt_cpu_tim_.plm.compin 03/29/79 1426.0r w 03/16/78 0801.6 5931 .ifi init_mpm "AN51" .srv section 2 .ifi l2h "N__a_m_e: virtual_cpu_time_" The virtual_cpu_time_ subroutine returns the CPU time used by the calling process not spent handling page faults, or system interrupts. It is therefore a measure of the CPU time within a process that is independent of other processes, current configuration, and overhead to implement the virtual memory for the calling process. .ifi l2h "Usage" .all .inl 10 .unl 5 declare virtual_cpu_time_ entry returns (fixed!bin(71)); .unl 5 .spf time = virtual_cpu_time_ (); .inl 0 .alb .spf 2 where time is the virtual CPU time in microseconds, used by the calling process. (Output)  rehash_.plm.compin 03/29/79 1426.1rew 04/05/78 1530.7 11313 .ifi init_mpm "AN51" .srv section 2 .ifi l2h "N__a_m_e_: rehash_" This subroutine rehashes (reformats into a different size) a hash table of the form that is maintained by the hash_ subroutine. In most cases, hash_ calls rehash_ automatically when a table becomes too full. For hash tables that are imbedded in larger databases, the database maintainer must monitor the density of the hash table and call rehash_ when necessary to maintain the optimal table size. See the description of the hash_ subroutine for more information. .ifi l2h "Usage" declare rehash_ entry (ptr, fixed!bin, fixed!bin(35)); .spf call rehash_ (table_ptr, size, code); .spb 2 where: .spf .inl 12 .unl 12 1. table_ptr (Input) .brf is a pointer to the table to be rehashed. .spb .unl 12 2. size (Input) .brf is the new size of the hash table. See the description of hash_$opt_size. .spb .unl 12 3. code (Output) .brf is a standard status code. It may be: .spf 0 table rehashed successfully .brf error_table_$invalid_elsize size is too large .brf error_table_$full_hashtbl size is not large enough to hold all .brf the entries in the current hash table.  covsix.compin 03/29/79 1428.2rew 04/04/78 1104.1 15210 .inl 42 306 Beacon Street No. 2 .brf Somerville, MA 02143 .brf April 4, 1978 .spb .inl Joanna Stevens .brf TMI Systems Corporation .brf 1 Broadway .brf Cambridge, MA 02142 .spb 2 Dear Ms. Stevens, .spb I am interested in a position at the entry level as a computer programmer or as a technical writer in software documentation. I recently learned of your organization through the Boston Sunday Globe. .spb I have an extensive background in the hard sciences, my two principal areas of concentration having been in mathematics and physics. During the past fall semester I took an introductory computer course in the Civil Engineering Department of MIT and did well in it. I have also had almost two years' experience as a technical editor for the MIT Press, with complete editorial responsibility for books whose subject matter ranges from scholarly mathematics to that of a broader scientific nature, directed to the educated lay public. For further information on my background please refer to the enclosed resume. .spb I am interested in TMI Systems Corporation because I seek challenging work in a high-quality working environment. I believe that the combination of my background in the sciences, my communications skills, and my need to make the most of my intellectual capabilities would enable me to make a valuable contribution to your organization in either of the capacities I have mentioned. .spb I will therefore be in contact with you by telephone on Tuesday April 11 to discuss the possibility of an interview. In the meantime may I suggest Friday April 21 as a day that would be convenient for me. .spb 3 .unl -37 Sincerely, .spb 2 .unl -37 Jay W. Flynn  listng_tpe_pr.pln.compin 03/11/80 1240.1rew 03/24/78 1317.8 100656 .ifi init_mpm "AN51" .srv section 1 .ifi l2h "N__a_m_e: listing_tape_print, ltp" The listing_tape_print command is the driving module for the listing tape system. It has as entries the various commands that govern the functions of the listing tape system. .spb 2 A listing tape is a single logical entity containing files in a sorted order. The files consist of single segments or multisegment files. The files are sorted according to the ASCII collating sequence by name, area name and system number in that order. A listing tape can exist physically as one reel or several reels of tape taken in a specific order. It can also exist as a segment or a multisegment file in the hierarchy. .spb 2 At the beginning of a listing tape is a dictionary or list of all the files on the tape in sorted order. The list consists of the name of the file together with other information such as area name, system number, unique identifier, date the file was last modified and last dumped, and the size of the file in words. .spb 2 When a listing tape is to be created from the contents of a directory, the names are first sorted and a dictionary is constructed. This dictionary is then used to place the files on the listing tape in the sorted order. Similarly, when merging tapes and/or directories, a dictionary is read or created for each input source. A merged output dictionary is created and the output listing tape is constructed using this resulting dictionary. .ifi l2h "E__n_t_r_y: listing_tape_print, ltp" This command causes some or all of the files on a listing tape to be printed. .ifi l2h "Usage" listing_tape_print -control_args- .spb 2 where control_args are one or more of the following: .spf .inl 12 .unl 7 -ip_n reel_name_m .brf indicates the names of the reels of an input listing tape. At least one input listing tape must be specified although more than one can be specified by repeating the -ip_n reel_name sequence. Drive type 7 or 9 track is indicated by making _n either 7 or 9. If _n is not given, 9 is assumed. reel_name_m is the name of the mth reel of a listing tape. The reels must be specified in their proper order since a listing tape is a single logical entity and the files it contains are in sorted order. Also, for the same reason, all reels must be specified if any are to be used. .spf .unl 7 -device device_name, -dv device_name .brf is the name of the device to be attached for output. If the -pd argument is not used, then the device name is assumed to be a printer device name such as prta or prtb. If the -pd argument is present with a Device Interface Module (DIM) name other than that for the printer, then a device name appropriate to that DIM should be used. Thus, if the DIM name is tape_, then an appropriate tape name should be given, i.e., listing_tape_23 or m1692. .spb .unl 7 -printer_dim dim_name, -pd dim_name .brf indicates that the following argument is the name of a DIM such as tape_ or file_. The printer DIM (prtdim_) is the default, but this control argument allows for the user's own DIM or output onto a tape or into a segment or multisegment file. .spb .unl 7 -file_input file_name, -fi file_name .brf indicates that file_name is the pathname of a control file. .spb .unl 7 -area_name aname, -an aname .brf indicates that aname is an area name of the area to be considered. .spb .unl 7 -first file_name, -ft file_name .brf indicates that file_name is the name of the first file on the listing tape to be printed. .spb .unl 7 -copy n, -cp n .brf indicates that _n is the number of copies to be printed of each file output. The maximum is 2. .inl 0 .ifi l2h "Notes" The listing_tape_print command first checks for an input print file. If there is no input print file and if an area name is given, it prints all files with that area name. If there is neither an input print file nor an area name, then all files on the tape are printed. In any of the above cases, if there is a -first file name, then all files prior to the given file name are skipped, remembering that the tape is sorted, before any printing begins. .ifi l2h "E__n_t_r_y: listing_tape_dictionary, ltd" This command causes the dictionary of the files on the listing tape to be copied from the listing tape into a file in the user's working directory. The name of the file is name_of_first_reel.dict. .ifi l2h "Usage" listing_tape_dictionary -ip reel_name1 .spf 2 where: .spb .inl 12 .unl 12 1. -ip .brf indicates that the names of the reels of an input listing tape follow. At least one input listing tape must be specified although more then one may be specified by repeating the -ip_n reel_name sequence. Drive type 7 or 9 track is indicated by making _n either 7 or 9. If _n is not given, 9 is assumed. .spf .unl 12 2. reel_name1 .brf is the name of the first reel of a listing tape. Since only the first reel is used, it is not necessary to specify the succeeding reels even though each reel has a dictionary before any other data. Only the first reel can be specified separately in this manner. .inl 0 .ifi l2h "E__n_t_r_y: listing_tape_merge, ltm" This command causes one or more input listing tapes and possibly the contents of one or more dictionaries to be merged. An output listing tape is generated as the result of this merge operation. .spb 2 .ifi l2h "Usage" listing_tape_merge -control_args- .spb 2 where control_args can be one or more of the following: .spf .inl 12 .unl 7 -output_n output_reel_name_m, -op_n output_reel_namem .brf is a control argument indicating the names of the output reels. One output listing tape must be specified, i.e., at least one reel. Drive type 7 or 9 track is given by making _n either 7 or 9. If n is not given, 9 is assumed. output_reel_name_m is the name of the mth output reel. All reels must be specified and in their proper order. Enough reels must be specified to hold all of the output generated or the current command is aborted with an error. If the first four characters of the reel name are "file" then the output is placed in a segment or multisegment file with the given reel name. .spb .unl 7 -input_n reel_namem, -ip_n reel_name_m .brf indicates the names of the reels of an input listing tape. At least one input listing tape must be specified although more than one can be specified by repeating the -ip_n reel_name sequence. Drive type 7 or 9 track is indicated by making _n either 7 or 9. If n is not given, 9 is assumed. reel_name_m is the name of the mth reel of a listing tape. The reels must be specified in their proper order since a listing tape is a single logical entity and the files it contains are in sorted order. Also, for the same reason all reels must be specified if any are to be used. .spb .unl 7 -directoryI_ dir_name, -dri dir_name .brf indicates that the ith directory pathname follows. A directory must be specified. Up to ten directories, 0 through 9, are allowed. .spb .unl 7 -area_name aname, -an aname .brf indicates that aname is the area name to be associated with the segments in the ith directory. An area name is any string of up to 16 characters. If no area name is given for the ith directory a default area name of "hardcore" is associated with that directory. .spb .unl 7 -system_number snumber, -sn snumber .brf indicates that snumber is the system number to be associated with the segments in the ith directory. A system number has four fields and is a maximum of 16 characters. The four fields are: .spb .inl +5 .unl 5 1. a numeric field of 1 to 8 digits .unl 5 2. a single character nonnumeric field .unl 5 3. a second numeric field of 1 to 8 digits .unl 5 4. any ASCII characters the first being nonnumeric .spb .inl 10 In sorting, the second field is ignored. If no system number is given for the ith directory, then the segment name of the directory is used as the system number. Thus, for directory >ldd>listings>18-36, the default system number is 18-36. .spb .unl 5 -file_input file_name, -fi file_name .brf indicates that file_name is the pathname of a segment containing a list of segments and their associated area names. For the ltm command list list is used to delete segments. Using the input file in another way, all files with dates earlier than a begin date are deleted. (See "Notes" below.) .spb .unl 5 -link yes_no, -lk yes_no .brf indicates that yes_no, which is either yes or no, tells this command whether or not to process links in the directories given above. .ifi l2h "Notes" For the ltm command, at least one input listing tape and one output listing tape are required. .spb 2 The file input segment has the following format for deletion. Each line has one or two arguments. Each argument begins with a minus sign (-) and is terminated by a blank or a newline character. The first argument is always present, and is the name of the segment to be operated upon. The second argument, if present, is an area name. If no area name is given, then the last area name given is the default area name. The initial default area name is blank. .spb The file input segment format for use as a begin date has a plus sign (+) as the first character followed by a date and time expressed as mm/dd/yy tttt. .ifi l2h "E__n_t_r_y: listing_tape_create, ltc" The ltc command exists for historical and aesthetic reasons. It differs from the ltm command only in that no input listing tape need be specified. .ifi l2h "Examples" To create a listing tape from a single directory, type: .spb .fif ltc -dr0 >ldd>listings>17-36 -an0 hardcore -sn0 17-36 -op tape1 .spb or: .spb ltc -dr0 >ldd>listings>17-36 -op tape1 .spb To create a listing tape from several directories, type: .spb ltc -dr0 >ldd>listings>17-3b -dr1 >ldd>listings>17-3c -dr2 >ldd>listings>14-43x -an2 soft -op tape1 tape2 .spb To output into the file file_foo, type: .spb ltc -dr0 >ldd>listings>18-36 -op file_foo .spb To merge several tapes and directories, type: .spb ltm -ip tape1 tape2 -ip xtape13 xtape14 xtape15 -dr0 >ldd>listings>18-0a -dr1 >ldd>listings>new_dims -an1 dims -sn1 31-4c -op otape4 otape5 otape6 otape7 .spb To delete from a listing tape, type: .spb ltm -ip tape33 tape34 tape35 -fi delete_list -op tape1 tape2 tape3 .spb To get a dictionary, type: .spb ltd -ip xtape13 .spb 2 where xtape13 is the first reel of a listing tape. .spb .brn 10 To print all, type: .spb ltp -ip xtape13 xtape14 xtape15 -dv prta .spb To output all into a file zilch, type: .spb ltp -ip xtape72 file_ -dv zilch .spb To print by area name, type: .spb ltp -ip tape27 tape28 -dv prta -an hardcore .spb To print according to an input file, type: .spb ltp -ip tape43 -fi print_list -dv prtb .spb An example of an input list for printing or deleting is: .spb -acc.list -hardcore -ab.list -zero.list -command -foo.list -aaagh.list -active .spb In this example, ab.list has the default area name hardcore, while foo.list has the default area name command. .fin ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved