AG92 06B_multics Cmds_Nov87 06B Multics Cmds Nov87
AG92-06B_multicsCmds_Nov87 AG92-06B_multicsCmds_Nov87
User Manual: AG92-06B_multicsCmds_Nov87
Open the PDF directly: View PDF .
Page Count: 1353
Download | ![]() |
Open PDF In Browser | View PDF |
Multics Commands and Active Functions Honeywell Bull MULTICS COMMANDS AND ACTIVE FUNCTiONS SUBJECT Description of Standard Multics Commands and Active Functions SPECIAL INSTRUCTIONS This publication supersedes the previous edition of the manual, Order No. AG92-05, dated January 1983, and its addendum AG92-05A, dated December 1983. Marginal change indicators (change bars and asterisks) indicate technical changes. SOFTWARE SUPPORTED Multics Software Release 11.0 ORDER NUMBER AG92-06 February 1985 Hone~ell Bull PREFl\CE The Multics Commands and Active Functions manual is organized into four sections. Section 1 contains a basic introduction to manual use and term definition. Section 2 contains the standard Multics commands and active functions arranged by function. Section 3 contains the descriptions of those commands and active functions in alphabetical order. Section 4 describes the requests used to gain access to the system. Throughout this manual. references are made to the Multics Programmer's Reference Manual (AG91) and the Multics Subrouti nes and I/O Modules (AG93). For convenience, these are referred to in the text as the Programmer's Reference Manual and the Subroutines manual. Significant Changes in AG92-06B The disconnect command was added to section 3. The following commands changed abbrev contents dial fortran help print_motd switch_on SWitch_off to improve functionality: The following commands have been extensively revised: copy _dump_tape compare_dump_tape read_tape_and_query The enter_output_request command was revised to satisfy a customer change request. Honeywell Bull disclaims the implied warranties oi merchaniabiiity and fitness for a particular purpose and makes no express warranties except as may be stated in its written ...greement with and for its customer. In no event is Honeywell Bull liable to anyone for any indirect, special or consequential damages. The information and specifications in this document are subject to change without notice. Consult your Honeywell Bull Marketing Representative for product or service availability. Copyright @ Honeywell Bull Inc., 1985 File No.: lLI3 AG92-06 CONTENTS Section 1 1-5 1-5 1-6 1-6 1-6 1-6 1-6 1-6 1-7 1-7 1-7 1-8 1-8 1-8 1-13 1-13 Section 2 Ref erence to Commands and Active Functions . . . . . . . . . . . . . . . . . 2-1 Section 3 Commands and Active Functions. . . . . . . . . . . . . . . . . . . . . . . . . abbrev (ab) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . accept_messages (am) . . . . . . . . . . . . . . . . . . . . . . . . . . accepting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . acquire_resource (aqr) . . . . . . . . . . . . . . . . . . . . . . . . . . add_name (an) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . add_pnotice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . add_search_paths (asp) . . . . . . . . . . . . . . . . . . . . . . . . . add_search_rules (asr) . . . . . . . . . . . . . . . . . , ; ; ; . . . . . adjust_hit_count (abc) . . . . . . . . . . . . . . . . . . . . . . . . . . after (af) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . aIm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . alm_abs (aa) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . and . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . answer 3-1 3-2 3-8 3-12 .....1 "PI ,y """PII (",'l .. _1\ •••••.•••••••••••••••••••••••••• archive (ac) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . archive_sort (as) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . archive_table (act) . . . . . . . . . . . . . . . . . . . . . . . . . . . . area_status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . assign_resource (ar) . . . . . . . . . . . . . . . . . . . . . . . . . . . attach_audit (ata) . . . . . . . . . . . . . . . . . . . . . . . . . . . . attach_Iv (aIv) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . bef ore (be) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12/87 1-1 1-1 Manual Use and Term Definition . . . . . . . . . . . . . . . . . . . . . . . . Description of Manual Format . . . . . . . . . . . . . . . . . . . . . . . General Definition of a Command . . . . . . . . . . . . . . . . . . . . . General Definition of an Active Function . . . . . . . . . . . . . . . . . Examples of Command vs Active Function Use. . . . . . . . . . . . . . Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Storage System Entry Types . . . . . . . . . . . . . . . . . . . . . . . . . Segtnent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Link . . . . . . . . . . . , . . . . . . . . . . . . . . . . . . . . . . . . Multisegtnent File . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Management File . . . . . . . . . . . . . . . . . . . . . . . . . Extended En try Types . . . . . . . . . . . . . . . . . . . . . . . . . . Date/Time Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Date/Time Input Values . . . . . . . . . . . . . . . . . . . . . . . . Time Strings (DT Values) . . . . . . . . . . . . . . . . . . . . . Date/Time Output Values . . . . . . . . . . . . . . . . . . . . . . . Time Format .. . . . . . . . . . . . . . . . . . . . . . . . . . . iii 3-12 3-14 3-14.2 3-15 3-17 3-18 3-19 3-20 3-48 3-50 3-50 3-53 3-54 3-64 3-65 3-67 3-68 3-71 3-78 3-79 3-80 AG92-06B before.Journal_status (bjst) . . . . . . . . . . . . . . . . . . . . . . . binarv (bin) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . bind ~(bd) .- . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . bj_rngr _call (bjrnc) . . . . . . . . . . . . . . . . . . . . . . . . . . . bool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . byte . . . . . . . calc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . calendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . calendar_clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cancel_abs_request (car) . . . . . . . . . . . . . . . . . . . . . . . . . cancel_cobol_program. (ccp) . . . . . . . . . . . . . . . . . . . . . . cancel_daemon_request (cdr) . . . . . . . . . . . . . . . . . . . . . . cancel_output_request (cor) . . . . . . . . . . . . . . . . . . . . . . . cancel_resource (cnr) . . . . . . . . . . . . . . . . . . . . . . . . . . cancel_retrieval_request (crr) . . . . . . . . . . . . . . . . . . . . . . canonicalize (canon) . . . . . . . . . . . . . . . . . . . . . . . . . . . canonicalize_mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . ceil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . change___default_wdir (cdwd) . . . . . . . . . . . . . . . . . . . . . . change_error_mode (cern) . . . . . . . . . . . . . . . . . . . . . . . . change_ wdir (cwd) . . . . . . . . . . . . . . . . . . . . . . . . . . . . check_file_system_damage (cfsd) . . . . . . . . . . . . . . . . . . . . check_iacl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . check_info_segs (cis) . . . . . . . . . . . . . . . . . . . . . . . . . . clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . close_file (cn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cobol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cobol_abs (cba) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . collate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . collate9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . comp_dir_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . compare_ascii (cpa) . . . . . . . . . . . . . . . . . . . . . . . . . . . compare_confiLdeck . . . . . . . . . . . . . . . . . . . . . . . . . . compare_dump_tape . . . . . . . . . . . . . . . . . . . . . . . . . . . compare_entry _names (cen) . . . . . . . . . . . . . . . . . . . . . . . compare_object (cob) . . . . . . . . . . . . . . . . . . . . . . . . . . compare_pll (cpp) . . . . . . . • . . . . . . . . . . . . . . . . . . . . component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . connect . . . • . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . convert_characters (evc) . . . . . . . . . . . . . . . . . . . . . . . . . convert_ee (cvee) . . . . . . . . . . . . . . . . . . . . . . . . . . . . copy (cp) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . copy_acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . copy_cards (ccd) . . . . . . . . . . . . . . . . . . . . . . . . = • • • • copy_characters (cpch) . . . . . . . . . . . . . . . . . . . . . . . . . copy_dir (cpd) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . copy_dump_tape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . copy_file (cpf) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . copy_iacI_dir .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . copy_iacl_seg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . copy_names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12/87 iv 3-81 3-84 3-85 3-92 3-97 3-98 3-98.1 3-99 3-102 3-107 3-108 3-110 3-111 3-113 3-115 3-116 3-118 3-119 3-121 3-121 3-122 3-123 3-124 3-125 3-126 3-128 3-129 3-130 3-134 3-136 3-136 3-137 3-140 3-142 3-146 3-148 3-150 3-150.1 3-151 3-152 3-152 3-153 3-154 3-155 3-158 3-160 3-161 3-162 3-163 3-165 3-167.1 3-171 3-172 3-172 AG92-06B create (cr) ............................... . create_area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . create_data_segment (cds) . . . . . . . . . . . . . . . . . . . . . . . . create_dir (cd) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . create_dm_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cross_reference (cref) . . . . . . . . . . . . . . . . . . . . . . . . . . cumulative_page_trace (cpt) . . . . . . . . . . . . . . . . . . . . . . . cv_ttf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . date_compiled (dtc) . . . . . . . . . . . . . . . . . . . . . . . . . . . date_deleter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . date_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . date_time_after (dtaf) . . . . . . . . . . . . . . . . . . . . . . . . . . date_time_before (dthe) . . . . . . . . . . . . . . . . . . . . . . date_time_equal (dteq) . . . . . . . . . . . . . . . . . . . . . . . . . date_time_interval (dti) . . . . . . . . . . . . . . . . . . . . . . . . . date_tirne_valid (dtv) . . . . . . . . . . . . . . . . . . . . . . . . . . day . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . day_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . debug (db) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . decat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . decimal (dec) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . decode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . decode_access_class (dac) . . . . . . . . . . . . . . . . . . . . . . . . default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . default_wdir (dwd) . . . . . . . . . . . . . . . . . . . . . . . . . . . defer_messages (dm) . . . . . . . . . . . . . . . . . . . . . . . . . . . delete (dl) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . delete_acl (da) . . . . . . . . . . . . . . . . . . . . . . . . . . = • • • delete_dir (dd) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . delete_external_variables (dev) . . . . . . . . . . . . . . . . . . . . . delete_iacl_dir (did) . . . . . . . . . . . . . . . . . . . . . . . . . . . delete_iacl_seg (dis) . . . . . . . . . . . . . . . . . . . . . . . . . . . delete_message (dIm) . . . . . . . . . . . . . . . . . . . . . . . . . . delete_name (dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . delete_search_paths (dsp) . . . . . . . . . . . . . . . . . . . . . . . . delete_search_rules (dsr) . . . . . . . . . . . . . . . . . . . . . . . . delete_volume_quota (dlvq) . . . . . . . . . . . . . . . . . . . . . . . describe_entry _type (dset) . . . . . . . . . . . . . . . . . . . . . . . descrihe_psp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . detach_audit (dta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . detach_Iv (dlv) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . dial_manager_call . . . . . . . . . . . . . . . . . . . . . . . . . . . . dial_out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . directories (dirs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . directory (dir) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . discard_output (dco) . . . . . . . . . . . . . . . . . . . . . . . . . . . disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . display_audit_file (daf) . . . . . . . . . . . . . . . . . . . . . . . . . display_cobol_run_unit (dcr) . . . . . . . . . . . . . . . . . . . . . . display_component_name (dcn) . . . . . . . . . . . . . . . . . . . . . display_entry_point_dcI (depd) . . . . . . . . . . . . . . . . . . . . . display_mailins-address (dsmla) . . . . . . . . . . . . . . . . . . . . display _pllio_error (dpe) . . . . . . . . . . . . . . . . . . . . . . . . 12/87 v 3-173 3-174 3-175 3-176 3-179 3-180.1 3-185 3-188 3-189 3-190 3-192 3-194 3-195 3-195 3-196 3-1% 3-198 3-199 3-200 3-201 3-226 3-227 3-227 3-229 3-229 3-230 3-231 3-232 3-233 3-235 3-236 3-236 3-238 3-239 3-241 3-243 "'" ""AI"'" -,-.l~-' 3-244 3-244.1 3-246 3-247 3-247 3-248 3-250 3-255 3-256 3-256.1 3-256.2 3-257 3-260 3-260 3-261 3-263 3-264 AG92-()6B display _pnotice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . display _subsystem_usage . . . . = = • = = = = = = • • • • • • • • • • • • display_time_info (dsti) . . . . . . . . . . . . . . . . . . . . . . . . . display_ ttt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . divide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . dm_display _ version . . . . . . . . . . . . . . . . . . . . . . . . . . . dm_user_shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . do_subtree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . dprint (dp) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . dpunch (dpn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . dump_segment (Os) . . . . . . . . . . . . . . . . . . . . . . . . . . . edm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . encode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . encode_access_class (eac) . . . . . . . . . . . . . . . . . . . . . . . . enter_abs_request (ear) . . . . . . . . . . . . . . . . . . . . . . . . . enter_output_request (oor) . . . . . . . . . . . . . . . . . . . . . . . enter_retrieval_request (err) . . . . . . . . . . . . . . . . . . . . . . entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . en try _path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . equal_name (enm) . . . . . . . . . . . . . . . . . . . . . . . . . . . . exec_com, ec (version 2) . . . . . . . . . . . . . . . . . . . . . . . . exec_com, ec (version 1) . . . . . . . . . . . . . . . . . . . . . . . . execute_string (exs) . . . . . . . . . . . . . . . . . . . . . . . . . . . exists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . expand_cobol_source (ecs) . . . . . . . . . . . . . . . . . . . . . . . explain_doc (edoc) . . . . . . . . . . . . . . . . . . . . . . . . . . . . exponent_control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . fast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . file_output (fo) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . floor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . format_document (fdoc) . . . . . . . . . . . . . . . . . . . . . . . . format_line (fl) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . format_line_nnl (flnn}) . . . . . . . . . . . . . . . . . . . . . . . . . format_pH (fp) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . format_string (fstr) . . . . . . . . . . . . . . . . . . . . . . . . . . . fortran (ft) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . fortran_abs (fa) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . gcos (gc) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . general_ready (gr) . . . . . . . . . . . . . . . . . . . . . . . . . . . . generate_pnotice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_dir_quota . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_effective_access (gea) . . . . . . . . . . . . . . . . . . . . . . . . get_ips_mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_library_segment (gls) . . . . . . . . . . . . . . . . . . . . . . . . get_mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_pathname (gpn) . . . . . . . . . . . . . . . . . . . . . . . . . . . get_quota (gq) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_system_search_rules (gssr) . . . . . . . . . . . . . . . . . . . . . greater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12/87 vi 3-265 3-266 3-268 3-269 3-270 3-270 3-271 3-271 3-276.1 3-278 3-282 3-285 3-289 3-290 3-293 3-294 3-294 3-300 3-314 3-316 3-317 3-317 3-318 3-319 3-320 3-336 3-346 3-350.1 3-350.5 3-352 3-355 3-356 3-356 3-358 3-359 3-360 3-366 3-368 3-370 3-392 3-394 3-399 3-401 3-403 3-410 3-412 3-413 3-414 3-415 3-419 3-419 3-420 3-422 3-422 AG92-06B hash_table (ht) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . have_mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . have_messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . have_Queue_entries . . . . . . . . . . . . . . . . . . . . . . . . . . . help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . hexadecimal (hex) . . . . . . . . . . . . . . . . . . . . . . . . . . . . high . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . high9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . history_comment (hcom) . . . . . . . . . . . . . . . . . . . . . . . . home_dir (hd) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . hour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . how_many_users (hmu) . . . . . . . . . . . . . . . . . . . . . . . . . hunt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . hunt_dec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . if . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . immediate_messages Om) . . . . . . . . . . . . . . . . . . . . . . . . indent Ond) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . index . . . . . . . . . index_set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ini tia te (in) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . io_call (io) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . is_component_pathname (icpn) . . . . . . . . . . . . . . . . . . . . . kermit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16_ftf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . last_message (lm) . . . . . . . . . . . . . . . . . . . . . . . . . . . . last_message_destination (lmds) . . . . . . . . . . . . . . . . . . . . . last_message_sender (lms) . . . . . . . . . . . . . . . . . . . . . . . . last_message_time (lmt) . . . . . . . . . . . . . . . . . . . . . . . . . length Un) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . less . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . library_descriptor (Ids) . . . . . . . . . . . . . . . . . . . . . . . . . library_fetch (If) . . . . . . . . . . . . . . . . . . . . . . . . . . . . line_length (II) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . link (lk) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . linkage_editor (le) . . . . . . . . . . . . . . . . . . . . . . . . . . . . links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . list (Is) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . list_abs_requests Oar) . . . . . . . . . . . . . . . . . . . . . . . . . . list_accessible (lac) . . . . . . . . . . . . . . . . . . . . . . . . . . . . list_acl Oa) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . list_daemon_requests (Idr) . . . . . . . . . . . . . . . . . . . . . . . list_dir_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . list_emacs_ctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . list_entry_types (lset) . . . . . . . . . . . . . . . . . . . . . . . . . . list_external_variables (lev) . . . . . . . . . . . . . . . . . . . . . . . list_fortran_storage (lfs) . . . . . . . . . . . . . . . . . . . . . . . . list_heap_variables (Ihv) . . . . . . . . . . . . . . . . . . . . . . . . . list_help (lh) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . list_iacl_dir (lid) . . . . . . . . . . . . . . . . . . . . . . . . . , . . . list_iacl_seg (lis) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . list_mdir (lmd) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . list_not_accessible (lnac) . . . . . . . . . . . . . . . . . . . . . . . . list_output_requests (lor) . . . . . . . . . . . . . . . . . . . . . . . . list_pnotice_names . . . . . . . . . . . . . . . . . . . . . . . 0 12/87 vii • • 0 • • • • • • • • • • • • 0 • • • • • • • • • 3-423 3-425 3-427 3-429 3-430 3-432.8 3-432.9 3-432.9 3-432.9 3-432.23 3-432.23 3-432.24 3-432.26 3-432.27 3-432.29 3-439 3-440 3-442 3-442 3-444 3-445 3-466.1 3-467 3-476 3-477 3-478 3-479 3-480 3-481 3-482 3-483 3-485 3-489 3-490 3-492 3-492.3 3-492.4 3-500 3-503 3-504 3-506 3-509 3-510 3-510 3-511 3-511 3-512 3-512.1 3-513 3-514 3-516 3-518 3-519 3-521 AG92-()6B list_ref_names (Irn) . . . . . . . . . . . . . . . . . . . . . . . . . . . list_resource_types Ort) . . . . . . . . . . . . . . . . . . . ; ; " " list_resources (Ir) . . . . . . . . . . . . . . . . . . . . . . . . . . . . list_retrieval_requests (Irr) . . . . . . . . . . . . . . . . . . . . . . . list_sub_tree (1s1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . list_tape_contents (Itc) . . . . . . . . . . . . . . . . . . . . . . . . . list_temp_segments . . . . . . . . . . . . . . . . . . . . . . . . . . .. Iogin_args. . . . . . logout . . . . . . . . Ions-date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. lonuear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. low . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lower_case (Iowercase) . . . . . . . . . . . . . . . . . . . . . . . . .. ltrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Iv_attached . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. mail (mn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. manage_volume_pool (mvp) . . . . . . . . . . . . . . . . . . . . . . master _directories (mdirs) . . . . . . . . . . . . . . . . . . . . . . .. max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. mbx_create (mber) . . . . . . . . . . . . . . . . . . . . . . . . . . .. memo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. menu_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . menu_delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . menu_describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. menu_display . . . , . . . . . , . . . , . . . . . . . . . . . . . . . .. menuJet_choice . . . . . . . . . . . . . . . . . . . . . . . . . . . .. menu_list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. merge_ascii (rna) . . . . . . . . . . . . . . . . . . . . . . . . . . . .. message_status (msgst) . . . . . . . . . . . . . . . . . . . . . . . . .. micro_transfer (mt) . . . . . . . . . . . . . . . . . . . . . . . . . . . min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . minus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. minute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. monitor_quota . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. month . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. month_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . move (mv) .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. move_abs_request (mar) . . . . . . . . . . . . . . . . . . . . . . . .. move_daemon_request (mdr) . . . . . . . . . . . . . . . . . . . . .. move_dir (mvd) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . move_names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . move_output_request (mor) . . . . . . . . . . . . . . . . . . . . . .. move_quota (mq) . . . . . . . . . . . . . . . . . . . . . . . . . . . . mtape_deIete_defaults . . . . . . . . . . . . . . . . . . . . . . . . .. mtapeJet_defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . mtape_set_defaults . . . . . . . . . . . . . . . . . . . . . . . . . . .. msfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. nequal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. network_request (nr) . . . . . . . . . . . . . . . . . . . . . . . . . . new_proc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. ngreater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. nless . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. no_save_on_disconnect . . . . . . . . . . . . . . . . . . . . . 12/87 viii 3-522 3-523 3-524 3-525 3-527 3-528 3-531 3-532 3-534 3-535 3-536 3-536 3-537 3-538 3-538 3-539 3-542 3-556 3-558 3-558 3-559 3-563 3-565 3-566 3-567 3-567 3-570 3-570 3-574 3-575 3-578 3-579 3-579 3-580 3-581 3-582 3-583 3-584 3-585 3-587 3-590 3-592 3-592 3-594 3-596 3-597 3-598 3-596 3-597 3-597 3-601 3--605 3--605 3-6OQ AG92-06B non branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . non directories (nondirs) . . . . . . . . . . . . . . . . . . . . . . . , , nonfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . nonlinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . nonmaster_directories (nmdirs) . . . . . . . . . . . . . . . . . . . . . nonmsfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . nonnull_links (nnlinks) . . . . . . . . . . . . . . . . . . . . . . . . . nonobject_files (nobfiles) . . . . . . . . . . . . . . . . . . . . . . . . nonobject_msfs (nobmsfs) . . . . . . . . . . . . . . . . . . . . . . . . nonobject_segments (nobsegs) . . . . . . . . . . . . . . . . . . . . . . nonsegments (nonsegs) . . . . . . . . . . . . . . . . . . . . . . . . . . nonzero_files (nzfiles) . . . . . . . . . . . . . . . . . . . . . . . . . . nonzero_msfs (nzmsfs) . . . . . . . . . . . . . . . . . . . . . . . . . nonzero_segments (nzsegs) . . . . . . . . . . . . . . . . . . . . . . . not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . nothing (nt) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . null_links (nlinks) . . . . . . . . . . . . . . . . . . . . . . . . . . . . object_files (obfiles) . . . . . . . . . . . . . . . . . . . . . . . . . . . object_msfs (obmsfs) . . . . . . . . . . . . . . . . . . . . . . . . . . object_segments (osegs) . . . . . . . . . . . . . . . . . . . . . . . . . octal (oct) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . or . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . overlay (ov) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . page_ trace (pgt) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pascal (pas) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pascal_area_status . . . . . . . . . . . . . . . . . . . . . . . . . . . . pascal_create_area . . . . . . . . . . . . . . . . . . . . . . . . . . . . pascal_cross_reference (pascal_cref) . . . . . . . . . . . . . . . . . . pascal_delete_area . , . . . . . . . . . . . . . . . . . . . . . . . . . . pascal_display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pascal_file_status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pascal_inden t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pascal_reset_area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pascal_set_prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . peruse_crossref (perer) . . . . . . . . . . . . . . . . . . . . . . . . . picture (pic) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pl1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pl1_abs (pa) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pH_macro (pmac) . . . . . . . . . . . . . . . . . . . . . . . . . . . . plus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ........... t .t"11111. 1..-.\ \.t"1 J • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • print_attach_table (pat) . . . . . . . . . . . . . . . . . . . . . . . . . print_auth_names (pan) . . . . . . . . . . . . . . . . . . . . . . . . . print_bind_map (pbm) . . . . . . . . . . . . . . . . . . . . . . . . . print_configuration_deck (pcd) . . . . . . . . . . . . . . . . . . . . . print_default_wdir (pdwd) . . . . . . . . . . . . . . . . . . . . . . . print_error_message (pem) . . . . . . . . . . . . . . . . . . . . . . . print_link_info (pli) . . . . . . . . . . . . . . . . . . . . . . . . . . . print_linkage_usage (plu) . . . . . . . . . . . . . . . . . . . . . . . . print_mail (prm) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . print_messages (pm) . . . . . . . . . . ............ . 12/87 ix 3-606 3-607 3-608 3-609 3-610 3-611 3-612 3-613 3-614 3-616 3-616.1 3-616.2 3-616.3 3-616.4 3-616.5 3-616.5 3-616.6 3-616.7 3-616.8 3-616.9 3-616.10 3-616.11 3-618 3-619 3-620 3-622 3-626 3-628 3-629 3-630 3-631 3-632.3 3-632.3 3-632.5 3-632.5 3-632.6 3-633 3-634 3-636 3-637 3-644 3-645 3-651 3-652 3-656 3-657 3-658 3-659 3-661 3-662 3-663 3-665 3-665 3-670 AG92-06B print_motd (pmotd) . . . . . . . . . . . . . . . . . . . . . . . . . . . print_proc_auth (ppa) . . . . . . . . . . . . . . . . . . . . . . . . . . print_relocation_info (pri) . . . . . . . . . . . . . . . . . . . . . . . prin t_request_types (prt) . . . . . . . . . . . . . . . . . . . . . . . . print_sample_refs . . . . . . . . . . . . . . . . . . . . . . . . . . . . print_search_paths (psp) . . . . . . . . . . . . . . . . . . . . . . . . print_search_rules (psr) . . . . . . . . . . . . . . . . . . . . . . . . . print_terminal_types (ptt) . . . . . . . . . . . . . . . . . . . . . . . . print_time_defaults (ptd) . . . . . . . . . . . . . . . . . . . . . . . . print_ttt_path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . print_wdir (pwd) . . . . . . . . . . . . . . . . . . . . . . . . . . . . probe (pb) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . process_dir (pd) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . process_switch_off (pswf) . . . . . . . . . . . . . . . . . . . . . . . . process_switch_on (pswn) . . . . . . . . . . . . . . . . . . . . . . . . profile (pr) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . program_in terrupt (pi) . . . . . . . . . . . . . . . . . . . . . . . . . progress (pg) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . qedx (qx) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . quotient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . read_mail (rdm) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . read_tape_and_query (rtq) . . . . . . . . . . . . . . . . . . . . . . . ready (rdy) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ready_off (rdf) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ready_on (rdn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rebuild_dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reconnect_ec_disable . . . . . . . . . . . . . . . . . . . . . . . . . . . reconnect_ec_enable . . . . . . . . . . . . . . . . . . . . . . . . . . . reductions (rdc) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . release (r1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . release_resource (rlr) . . . . . . . . . . . . . . . . . . . . . . . . . . rename (rn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reorder_archive (ra) . . . . . . . . . . . . . . . . . . . . . . . . . . . repeat_line (rpl) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . repeat_query (rq) . . . . . . . . . . . . . . . reprint_error (re) . . . . . . . . . . . . . . . . . . . . . . . . . . . . reserve_resource (rsr) . . . . . . . . . . . . . . . . . . . . . . . . . . reset_external_variables (rev) . . . . . . . . . . . . • . . . . . . . . . reset_ips_mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . resolve_linkage_error (rIe) . . . . . . . . . . . . . . . . . . . . . . . resource_status (rst) . . . . . . . . . . . . . . . . . . . . . . . . . . . resource_usage (ru) . . . . . . . . . . . . . . . . . . . . . . . . . . . response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reverse (rv) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reverse_after (rvan . . . . . . . . . . . . . . . . . . . . . . . . . . . reverse_before (rvbe) . . . . . . . . . . . . . . . . . . . . . . . . . . reverse_decat (rvdecat) . . . . . . . . , . reverse_index (rvindex) . . . . . . . . . . . . . . . . . . . . . . . . . reverse_search (rvsrh) . . . . . . . . . . . . . . . . . . . . . . . . . . reverse_substr (rvsubstr) . . . . . . . . . . . . . . . . . . . . . . . . reverse_verify (rvverify) . . . . . . . . . . . . . . . . . . . , . . . . revert_output (ro) . . . . . .. . . . . . . . . . e 12/87 x • • e e e , e , • • • • , • 3-673 3-673.1 3-674 3-674.1 3-675 3-677 3-678 3-678 3-678 3-680 3-680 3-680 3-707 3-707 3-708 3-708 3-714 3-715 3-717 3-728 3-730 3-731 3-731 3-741 3-749 3-749 3-750 3-750 3-751 3-751 3-752 3-790 3-790 3-791 3-792 3-793 3-794 3-796 3-796 3-798 3-798 3-799 3-800 3-802 3-803 3-806 3-807 3-808 3-809 3-810 3-811 3-812 3-812.1 3-813 AG92-D6B rtrim run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . run_cobol (rc) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . runoff (rf) .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . runoff _abs (rfa) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sample_refs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . save_dir_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . save_history_registers . . . . . . . . . . . . . . . . . . . . . . . . . . save_on_disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . search (srh) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . segments (segs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . send_mail (sdm) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . send_message (sm) . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_acl (sa) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_bit_count (sbc) . . . . . . . . . . . . . . . . . . . . . . . . . . . set_cc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_dir_ring_brackets (sdrb) . . . . . . . . . . . . . . . . . . . . . . set_epilogue_command . . . . . . . . . . . . . . . . . . . . . . . . . set_fortran_common (sfc) . . . . . . . . . . . . . . . . . . . . . . . . set_iacl_dir (sid) . . . . . set_iacl_seg (sis) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_ips_mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_mailin~address (smla) ...................... . set_max_Iength (smI) . . . . . . . . . . . . . . . . . . . . . . . . . . set_mdir_account (smda) . . . . . . . . . . . . . . . . . . . . . . . . set_mdir_owner (smdo) . . . . . . . . . . . . . . . . . . . . . . . . . set_mdir_quota (smdq) . . . . . . . . . . . . . . . . . . . . . . . . . set_resource (setr) . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_rin&-brackets (srb) . . . . . . . . . . . . . . . . . . . . . . . . . set_search_paths (ssp) . . . . . . . . . . . . . . . . . . . . . . . . . . set_search_rules (ssr) . . . . . . . . . . . . . . . . . . . . . . . . . . set_severity_indicator (ssi) . . . . . . . . . . . . . . . . . . . . . . . sel_system_storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_time_default (std) . . . . . . . . . . . . . . . . . . . . . . . . . . set_ttt_path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_tty (stty) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_user_storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set_volume_quota (svq) . . . . . . . . . . . . . . . . . . . . . . . . . severity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . shortest_path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sort_seg (ss) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sort_strings (sstr) . . . . . . . . . . . . . . . . . . . . . . . . . . . . start (sr) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . status (st) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . stop_cobol_run (scT) . . . . . . . . . . . . . . . . . . . . . . . . . . . stop_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strip_component (spc) . . . . . . . . . . . . . . . . . . . . . . . . . . strip_entry (spe) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . substitute_arguments (sbag) . . . . . . . . . . . . . . . . . . . . . . . substr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12/87 xi 3-814 3-814 3-819 3-822 3-842 3-844 3-845 3-846 3-847 3-847 3-848 3-849 3-851 3-861 3-864.1 3-867 3-868 3-869 3-870 3-871 3-872 3-873 3-875 3-875 3-876 3-877 3-877 3-878 3-879 3-881 3-882 3-883 3-884 3-884 3-885 3-887 " 00..,. ,,)-001 3-896 3-898 3-899 3-900 3-901 3-903 3-912 3-919 3-919 3-926 3-927 3-928 3-928 3-930 3-931 3-932 3-935 AG92-()6B suffix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . syn_output (so) ............................ . system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .............................. . system_type tape_archive (ta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tape_in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tape_out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . teco . . . . . . . . . . . . . . . . . teco_error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . teco_ssd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . terminal_output (to) . . . . . . . . . . . . . . . . . . . . . . . . . . . ! __ +_ 1 . _ \ 4- _ _ _ U;llllllli1LC \ LillI • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • terminate_ref name (tmr) . . . . . . . . . . . . . . . . . . . . . . . . terminate_segno (tms) . . . . . . . . . . . . . . . . . . . . . . . . . . terminate_single_refname (tmsr) . . . . . . . . . . . . . . . . . . . . test_archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . total_output_requests (tor) . . . . . . . . . . . . . . . . . . . . . . . trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . trace_meters (tmt) . . . . . . . . . . . . . . . . . . . . . . . . . . . . trace_stack (ts) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . transaction (txn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . translate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . trunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . truncate (tc) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unassign_resource (ur) . . . . . . . . . . . . . . . . . . . . . . . . . . underline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unlink (uI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . upper _case (uppercase) . . . . . . . . . . . . . . . . . . . . . . . . . user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . validate_info_seg (vis) . . . . . . . . . . . . . . . . . . . . . . . . . . validate_pictured_data (vpcl) . . . . . . . . . . . . . . . . . . . . . . value_defined (vdf) . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . .. . . . . . . . ..... . value_delete (vdI) .. valueJet (vg) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . value_list (vIs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . value_path (vp) . . . . . . . . . . .......... . value_set (vs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . value_set_path (vsp) . . . . . . . . . . . . . . . . . . . . . . . . . . . verify . . . . . . . . . , . . . . . . . . . . . . . . . . . . . . . . . . . vfile_adjust (vfa) . . . . . . . . . . . . . . . . . . . . . . . . . . . . vfile_find_bad_nodes . . . . . . . . . . . . . . . . . . . . . . . . . . vfile_status (vfs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . walk_subtree (ws) . . . . . . . . . . . . . . . . . . . . . . . . . . . . watch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . where (wh) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . where_doc (wdoc) . . . . . . . . . . . . . . . . . . . . . . . . . . . . where_search_paths (wsp) . . . . . . . . . . . . . . . . . . . . . . . . who . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . window_call (wdc) .... . workin~dir (wd) . . . . . . . . . . . . . . . . . . . . . . . . 12/87 xii 3-935 3-940 3-940 3-940.3 3-940.4 3-951 3-965 3-971 3-1006 3-1007 3-1007 3-1008 3-1009 3-1010 3-1011 3-1012 3-1012 3-1012.1 3-1013 3-1014 3-1024 3-1026 3-1027 3-1037 3-1038 3-1039 3-1040 3-1040 3-1041 3-1042 3-1043 3-1044 3-1045 3-1049 3-1051 3-1050 3-1052 3-1054 3-1057 3-1060 3-1060 3-1064 3-1065 3-1065 3-1067 3-1072 3-1074 3-1076 3-1078 3-1080 3-1080.2 3-1082 3-1084 3-1094 AG92-06B year . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. zero_segments (zsegs) . . . . . . . , , , . . . . . . . . . . . . . . .. Section 4 Access to the System . . . . . . . . , . . . . . . . . . . . . . . . . . . . . . . access_class (ace) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . dial (d) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enter (e) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enterp (ep) . . . . . . . . . . . . . . . . . . . . . : . . . . . . . hangup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . hello . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . help (HELP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . login (I) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . noecho . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . slave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . terminal_id (tid) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . terminal_ type (ttp) . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1094 3-1095 4-1 4-2 4-2 4-3 4-4 4-4 4-6 4-6 4-7 4-7 4-15 4-16 4-17 4-17 4-18 4-19 4-19 Index 12/87 xiii AG92-06B SECTION 1 MANUAL USE AND TERM DEFINITION This section deals with the proper use of this manual, a description of the format used, and a general definition of terms. You are encouraged to take advantage of the information available in the manual's detailed index and table of contents. The index alphabetically lists programs by name and subject Cross-references among command descriptions assist in locating programs applicable to a given task. DESCRIPTION OF MA.~UAL FORMAT Section 2 contains a breakdown by function of the programs described in this manual. Section 3 contains an alphabetized listing of the standard Multics system commands and active functions. Section 4 contains descriptions of the preaccess and access requests that are used to gain access to the Multics system. Each command description provides, minimally, the long (and short) name, syntax line, and function of the program. Standard headings, in the order in which they appear, when present, are as follows: SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION FUNCTION ARGUMENTS CONTROL ARGUMENTS ACCESS REQUIRED NOTES EXAMPLES Syntax lines give the order of required and optional arguments accepted by a command or active function. Optional portions in the syntax line are enclosed in braces ({}). The syntax for active functions is always enclosed in brackets ([]), which are required for active function use. To indicate that a command accepts more than one of a specific argument, an "s" is added to the argument name (e.g., {paths} , -control_args). Keep in mind the difference between a plural argument name that is enclosed in braces (optional) anc one that is not {required}: if it is enclosed in braces, you need not give any argument of that type; if it is not, you must supply at least one argument of that type. Thus you could write "paths" in a usage line as: pathl {path2 ••• pathN} The convention of using "paths" rather than using the above is merely to save space. 1-1 AG92-06 Different arguments that you must give in pairs are numbered: xxxl yyyl { ••• xxxN yyyN} To indicate that you must provide the same generic argument in pairs, the arguments are given letters and numbers: argl arg2 { ••• arglN arg2N} Some of the standard arguments accepted by commands and active functions are: STR any character string. N any character string that represents a number, either decimal or binary. Examples are integers (5, 1024, or 101b), real numbers (1.37 or -10.01b), and floating-point numbers (1.3e+4 or 1010.001e+5b). DT or time_string a date-time character string. Examples are "4/25/84 noon est Sun", "November 7", "7:30 pm. 10 June 1985", and "midnight". (See "Date/Time Values" below for a description of valid time strings.) star_name any pathname or User_id conforming to the star convention, described under "Star Names" in the Programmer's Reference Manual. virtual_pointer A virtual pointer is a character string representation of a pointer value. It consists of a segment identifier (pathname, reference name, or segment number) and an optional octal offset into the segment In the table that follows, W is an octal word offset from the beginning of the segment; it can have a value from 0 to 777777 inclusive. B is a decimal bit offset within the word; it can have a value from 0 to 35 inclusive. The possible forms are: pathIW(B) points to the octal word W, decimal bit B, of the segment or multisegment file (MSF) identified by absolute or relative pathname path. If the path you give identifies a MSF, the offset given is in component 0 of the MSF. pathlW same as path IW(O). path I same as path I0(0). path same as path I0(0). path Ientry_pt points to the word identified by entry point entry_pt in the object file (segment or MSF) identified by path. 11/86 1-2 AG92-Q6A dir>entry$entry_pt points to the word identified by entry point entry_pt in the object file identified by patbname dir>entry. Ientry$entrj_pt points to the word identified by entry point entry_pt in the object file identified by pathname entry. I or <, as a reference name otherwise. A null pointer is represented by the virtual pointer 7777711, -111, or -1. 11/86 1-3 AG92-06A virtual_en try is a character string representation of an entry value. It consists of a segment identifier and an optional offset into the segment. In the table that follows, W is an octal word offset from the beginning of the segment; it can have a value from 0 to 777777 inclusive. The possible forms are: pathlW entry at octal word W of segment or multisegment file (MSF) identified by absolute or relative pathname path. If the path you give identifies a MSF. the offset given is in component 0 of the MSF. path 1 same as path IO. path Ientry_pt entry at word identified by entry point entry_pt in the object file (segment or MSF) identified by path. dir>entry$entry_pt entry at word identified by entry point entry_pt in the object file identified by pathname dir>entry. entry$en try_pt entry at word identified by entry point entry_pt in the object file identified by pathname entry. or < characters. A virtual entry that does not contain $ or I is interpreted as a pathname if it contains > or <, as a reference name otherwise. A null pointer is represented by the virtual pointer 7777711. -111, or -1. 11/86 1-4 AG92-D6A Use of a patbname in a virtual entry initiates the referenced segment with a reference name equal to its final entryname. Name duplication errors occurring during the initiation are resolved by terminating the previously known name. Arguments, when present, are listed with a brief description and the default value, if any. To indicate one of a group of the same arguments, an "in is added to the argument name (e.g., pathi, User_idi). The list of control arguments give the possible values for -control_args in the syntax line. The long name and the short one (if any) are given. For simplicity, common control argument values are indicated as follows: STR any character string; individual command descriptions indicate any restrictions (e.g., must not exceed 136 characters). 11/86 1-4.1 AG92-06A This page intentionally left blank. 11/86 AG92-06A N any number; individual command descriptions indicate whether N is octal or decimal and any other restrictions (e.g., cannot be greater than 4). DT a date-time character string (see "Date/Time Values" below). ID a numerical request identifier as described in the Programmer's Reference Manual. path the pathname of an entry; unless otherwise indicated. it may be either a relative or an absolute pathname. The lines below are samples of control arguments that take values: -access_name STR, -an STR -ring N, -rg N -date DT, -dt DT -pathname path, -pn path The "Notes" section is used to provide additional information and cross-reference with other manuals. Examples, while not extensive, try to provide additional help and insight on the proper use and formatting of commands and active functions. Examples showing lines that you type are preceded by an exclamation mark (!). Examples of command use show the response you can expect to see on the terminal. Examples of active function use show the return value substituted by the command processor for the active string. GE~~RAL DEFINITION OF A COl\fl\fAL'U) A command performs some action f or you, such as displaying inf ormation on your terminal, formatting a report, or compiling a program. Each command has a specific purpose. The default action performed by a command is generally the most common use of the command. Many commands have optional arguments that refine the actions that are performed. You can invoke commands at the beginning of a command line at command level and can put multiple commands on a single line, with a semicolon (;) as a delimiter between each one. GENERAL DEFINITION OF AN ACfIVE FUNCfION An active function is most frequently used to shorten the amount of typing required to invoke a c.o!!LT!land. You invoke (surrounded by brackets []). which is before the command line containing it together with the exec_com. abbrev, language macros. an active function inside an active string replaced by a character string return value is executed. Active functions are often used and do commands to implement command When you give multiple commands on a line, active functions in each are expanded before execution. This means that the first command is executed before active functions in the second command invocation are expanded. Therefore the execution of a command may affect the values of active functions that appear later in the line. 1-5 AG92-()6 EXAMPLES OF COMMAND VS ACTIVE FUNCTION USE You can invoke many programs as either a command or active function. The format of the active function return string is slig..htly different from the command's printed output. In these examples, and all interactive examples throughout this manual, lines you type are preceded with an exclamation point (0. status reportl -nm names: report_first_quarter.runoff reportl.runoff reportl versus the corresponding status active function: string [status reportl -nmJ report_first_quarter.runoff reportl.runoff reportl ERRORS Commands report errors by signaling command_error and printing a message. Messages that do not begin with "Warning:" usually terminate execution of the command, though later commands on the same line are subsequently executed. Active functions report errors by signaling active_function_error. The default action is to print a message and return to command level. Respond by typing: release to abort the command line, and then issue. the corrected line. The command_error and active_function_error conditions are further described in the Programmer's Reference Manual. The basic elements within the Multics storage system are segments and directories. Multics supports additional entry types that are maintained for convenience or to aid programmers who require a storage medium with special qualities or attributes. The various entry types are described below. Segment The segment is the unit of storage of the Multics System that is analogous to a file on other systems. A segment is a collection of instructions or data you specify. Directory A directory is a catalog of subordinate entries. 1-6 AG92-()6 Link A link entry is a reference to an entry in another directory. You make the reference by giving the pathname of the target entry. Multisegment File Very large data bases may exceed the size of a single segment In such cases Multics treats this data base as a group of segments in a single multisegment file. The segments are grouped under a common directory whose multisegment file indicator is set The directory and its contents are called a multisegment file (MSF). Any directory whose multisegment file indicator is not 0 is an MSF. For an MSF this indicator is a count of the number of segments it contains. Not all of the attributes listed above are applicable to MSFs. Some of the attributes are the same for any entry; however. due to the nature of an MSF when viewed as a file. many of the attributes are implemented differently. For example. the bit count of an MSF is the sum of the bit counts of the segments it contains. The access control list for an MSF directory applies to ail of the segments it contains. You can use the safety switch attribute; however if you set it for one of the segments in the MSF, you should set it for all of them. For more information on these and other attributes of MSFs. see the msf_manager_ subroutine. Most standard system programs that work on segments also work on MSFs; however . some commands and subroutines give unpredictable results when used on MSFs. You should consult the individual command or subroutine description before invoking it on an MSF. Data Management File A data management (DM) file is composed of a set of .pages known as. control intervals, numbered from 0 through N and addressable only through software calls to the file manager. Data is accessed by specifying a control interval number, byte offset. and length. You can implement DM files with concurrency control and recovery support. At present the ability to use data management files is available only to programs accessing files through the Multics Relational Data Store (MRDS) facility. Extended Entry Types The Multics storage system supports special-case entry types called extended entry types. They are so called because the Multics storage system has been enhanced (extended) to treat these storage elements as segments (even though they are structured differently from segments). The following system-supplied storage system elements have been implemented as extended entries: mailboxes, forum meetings. message segments, before journals, and the person name table. Most file system commands (e.g., copy. set_acl, etc.) will operate on extended entries. Each extended entry is identified by a suffix appended to the entry name. as described below: 1-7 AG92-06 NAME SUFFIX rna i 1box .mbx forum meeting message segment before journal person name table .forum .ms .bj .pnt DATE/TIME VALVES Multics use of date/time values is described in the following subsections. Multics accepts dates from the year 0001 through 9999. The Julian calendar is used for dates from 0001-01-01 through 1582-10-04. The Gregorian calendar is used for dates from 1582-01-15 through 9999-12-31. (The dates from October 5, 1582 through October 14, 1582 do not exist; they were dropped when the Gregorian calendar was adopted.) The leap day is always February 29. The lower limit on dates of January 1, 0001 A.D., was picked since it begins the era; the upper limit of December 31, 9999, was chosen to limit year numbers to four digits. The time zones as now defined are used regardless of the year. The Multics date/time software does not account for "leap seconds", and, therefore, the difference between any two binary clock values that are precisely an integral number of days (hours. minutes. seconds. etc.) apart is guaranteed to be evenly divisible by the number of microseconds in a day (hour, minute, second,etc.). Date/Time Input Values Often you must supply date and time information to a command. Programs that accept date and time information use the convert_date_to_binary_ subroutine (see the Subroutines manual) to convert a time string to an internal (binary) value. TIME STRINGS (DT VALUES) The time string can have up to six parts: adverbial offset, date. time, day of week, signed offset, and time zone. Adverbial offsets, if present, must appear leftmost in the string. Beyond that, all the parts are optional and can be in any order. The parts can be made up of alphabetic fields. numeric fields, and special characters. An alphabetic field is made up of letters and must contain a whole word or an abbreviation (often made up of the first three letters of the word). No distinction is made between uppercase and lowercase characters. Although this description gives examples in English, each of the words is available in several languages. You can use any of these languages in time strings, but all words' within a given string must be in the same language. To see the languages defined on your site, type display_time_info -lang A numeric field consists of an optionally signed integer of one or more decimal digits. The special characters that you can use in either alphabetic or numeric fields are: the slash (/), the period (.), the colon (:), the plus (+), the minus (-), and the comma (,). Blanks are not required between aiphabetic and numeric fields in the time strings; however they are required between two numeric fields unless the second field begins 1-8 AG92-Q6 with a plus or minus sign. For example, 2days4hours10minutes 1245.17+7hours 10/17/79Wednesday Unless otherwise indicated in the command description, supply the input time string as a single argument. This means that you must enclose within quotations time strings that contain spaces. Alternatively you can use underscores instead of blanks in the time string. For example. Usually when you enter a time string, the time zone is omitted. Although the ,time zone is seldom seen. it is very important: it determines the interpretation of items given in the time string; it is also involved in defaults supplied for missing items. All defaults are taken from the current absolute time, adjusted by a working time zone. If you give a zone in the string. that becomes the working zone; otherwise the process default time zone is used. This means that whether you "XXXX_ast", or set the process you get the same absolute time. output conversion, while giving zone, type convert a string with an explicit zone, such as default to "ast" and then convert the string "XXXX", (Note that setting the process default also influences an explicit zone does not.) To display your default The six parts of the time string are described below. In these descriptions whenever an assumed value is mentioned, it refers to the current date/time adjusted to the working zone. 1. date is the day of the year; you can specify only one date. You can supply a date using normal date format, calendar date format, day of the week. date keywords, fiscal week. request-id, or you can omit it entirely. If no date is present. it is assumed to be the next occurrence of the time specified; for instance. "lOA" gives the date on which 10:00am next occurs. If you give no date and time, the current date is used. In normal date format, you can specify dates is month (or month abbreviation). day of month. and year; or as day of month. month. and year. The year is optional and, if omitted, is assumed to be the year in which the date occurs next; that is, if today is March 16. 1985, then March 20 is equivalent to March 20. 1985; while March 12 is the same as March 12. 1986. There are three forms of normal date: 16 March March 16 3/16 16 March 1985 March 16 1985 3/16/85 Ma r c h 16 , 1985 3/16/1985 (The comma is op-t i ona 1) The calendar date format allows you to supply dates as a year, month, and day of month, separated by minus signs. This is the International Standards Organization (ISO) standard format The year is required. and you can give it as a year of the century. For example. 1-9 AG92-06 85-12-31 or 1985-12-31 represents December 31, 1985. The day of the week is a date specifier if present with no other form of date. It then selects the first occurrence of the named day after today. The date keywords are "yesterday", "today", and "tomorrow"; for instance, 6:35A today yesterday +120days The fiscal week is of the form F\Vyyyyww. P\V is . the fiscal indicator (in English), yyyy is the year number, and ww is the week number. The fiscal week begins on Monday and ends on Sunday. This form converts to the date of Monday, but you can select a day within the week by adding a day name; for example, "FW198413 m" gives "03/26/84 0000. Mon", while "FW198413 m Wed" gives "03/28/84 0000. Wed". You can separate the fiscal indicator from the number, but the ordering must remain. i.e., "FW185425" or "FW 185425", but not "185425 FW". A request-id is a 19-character string used by several programs in the system, such as list_output_request. It contains a complete date from year, in century, down through microseconds in this form yymmddHHMMSS.SSSSSS If you provide no zone, it is interpreted in GMT, not the process default. A request-id specifies a iime as wen as a date, so you can give no other time specification. 2. day of week is a day of the week (e.g., Monday) and can be present only once. When the day of the week is present along with one of the other forms of date specification, that date must fall on the indicated day of the week. You can optionally follow it by a comma. 3. time is the time of day and can only be present once. If omitted, it is assumed to be the current time. You can give time as 24-hour format, 12-hour format, or the time keyword "now". The 24-hour time format consists of a four-digit number followed by a period: hhmm., where hh represents hours and mm is minutes. You can follow this number by an optional decimal fraction-of-a-minute field (e.g., hhmm.m). Also acceptable are hours and minutes fields separated by colons (hh:mm). You can optionally follow this by either a fraction-of-a-minute field (hh:mm.m) or a seconds field (hh:mm:ss). The seconds, in turn, can include a fraction-of -second field (e.g., hh:mm:ss.s). Examples of 24-hour time are: 1545 .1545.715 15:45 15:45.715 15:45:42 15:45:42.08 1-10 AG92-Q6 You must end the 12-hour time format with a meridiem designator (i.e.• A. P, am, pm, noon (n). midnight (m). You can indicate midnight and noon by giving just the meridiem designator . You can precede the designator by time expressed as hours. hours: minutes, or hours:minutes:seconds (including an optional fraction of a second or fraction of a minute). Examples of 12-hour time are: midnight 5 am 5:45A 3:59:59.000001pm 11:07:30.5pm 12 n There is a set of illegal times--24:oo-24:59--which are handled anyway. These are taken to mean 00:00-00:59 of the following day; midnight <00:00) is the beginning of a day. not the end. 4. signed offset is an adjustment to be made to the clock value specified by the other fields. You can supply offsets in any the following units: year month week day hour minute second microsecond years months weeks days hours minutes seconds microseconds yr mo wk da hr min sec usec Each unit can be present one or more times, each preceded by an optionally signed fixed point number. If offset fields are the only thing present. the offsets are added to the default values of date and time, as described above. If the month offset results in a nonexistent date (e.g., "Jan 31 3 months" would yield April 31), the last date of the resulting month is used (i.e., April 30). Examples of offset fields are: 3 weeks -60 hours (60 hours before 3 weeks after now) 1.5 hr 5min (an hour and 35 minutes from now) 1 hour 5 minutes (an hour and five minutes from now) The order in which offset values are applied to the clock value can affect the resultant clock value. Offset values are applied in the following order: year, month. week, day, hour. minute, second. microsecond "Monday 6 am 2 weeks" means "two weeks after the next occurrence of Monday. at 6:00 am on that day". Assuming that today is September 25, 1985. then 10/1 -1 day +1 month 1-11 AG92-06 results in a clock value for 10/31/85, rather than for 10/30/85. Note: There is also a nonoffset use of these words, available in combination with the word "this". Some of these combinations can be used in building date and time parts. For example, "this_month_1,_thisJear or "this_hour:23" is valid, while just "this_day" is not. The exact form of this combination varies according to the language used. In some languages the word for "this" changes according to the gender of the unit it is applied to; in others there may be a single word that does the job. To list the word used as "this" for each unit, type ii display_time_info -offset -language LANGUAGE_NAME 5. adverbial offset is a before/after kind of adjustment that you can use any number of times. You can recognize it by the presence of "before", "on", or "after" in the time string. If present, it must appear first These are the forms available: DAY-NAME before DAY-NAME on or before DAY-NAME before or on DAY-NAME after DAY-NAME on or after DAY-NAME after or on SIGNED-OFFSETs b,efore SIGNED-OFFSETs after When adverbial offsets are present, they partition a time string into a series of adjustments followed by a base time. These sections are processed from right to left The example below has 3 sections: first· "6:00 am 400sec" is handled, supplying all necessary defaults and making the ordinary (400sec) offset adjustment; then "Monday after" is applied to give a new value; finally "2 wk -5min after" is applied to this new value to give the final value. 2 wk -5min after Monday after 6:00 am 400sec 20 minutes before now 2 days after today 2500 weeks after 1776-7-4 Tue after Mon on or after 11/1 The last item describes election day in the USA: the first Tuesday after the first Monday in November. 6. zone is the time zone to be used in making the conversion to Greenwich mean time, which is the internal form of all clock readings. It can be either a zone differential or any of the zone abbreviations known at your site. A zone differential is a five-character string, "sHHMM" (s is a sign, HH is a two-digit hour. and MM is a two-digit minute). You can use this only immediately following a time specification: "12:15-0330" says that 12:15 is the local time, and -0330 specifies that the local time was generated by subtracting 3.5 hours from GMT. To list the zone abbreviations known at your site, type 1-12 AG92-Q6 If any defaults are needed, the current instant is broken down into years, months, days, and so forth with respect to a "working zone". This working zone can make much difference because, for example. at a given instant it can be Tuesday in New York and Wednesday in Bankok, or it can be 22:07 in London and 3:37 in Singapore. Thus the zone is as important in applying defaults to week days and years as it ~s to hours and minutes. Many of the date/time commands allow you to supply a "-zone X" argument. In this case, X can be any of the zones known at you site; it can't be a time dif f eren tial. Date/Time Output Values One way to get a clock value into a readable form is by using the date/time commands (calendar_clock, day, etc). The first argument to the clock command is a control string describing. the format wanted. All other date/time commands have intrinsic formats. These commands convert a readable tim'e string to an internal value and then convert this internal clock reading to the specified output time format. An input time string is converted to internal form by convert_date_to_binary_. This is the usual form for storing dates in data bases. To convert an internal clock reading into a readable form, you can call date_time_ to get a 24-character form like this: 03/14/79 0000.0 cet Pri But when other formats are needed, date_time_$format is available. It takes a clock value and a control string describing the format wanted and returns a string ready for printing. An effort has been made to make all date/time outputs from the system software usable as date/time inputs to system software, but the time format mechanism is so flexible that you can easily use it to generate formats that are not recognizable. Also some strings are apparently recognized, even though they are ambiguous. Por instance, "7/1/82" means the 7th month, first day in the United States, but in many European countries would mean the 7th day of the first month. Multics follows the American interpretation. TIME FORMAT The control string for the date_time_Sformat subroutine, clock command, and other commands that expect a time_format argument is either a keyword or a character string consisting of text and/or selectors. The selectors are always identified by a leading circumflex character (A). There are two types of selectors: A , which allows a keyword to be embedded within a forma~ and the general form AX.X. XX is a two-letter code that specifies what information is wanted. You can place an optional PL/I picture specification between the A and XX if the default fomr is not adequate. If the control string does not contain any circumflex characters, it must then be one of the known set of keywords. Each keyword identifies a control string for a predetermined format named by that keyword. 1-13 AG92-06 LIST OF FORMAT KEYWORDS all A9999yc- Amy- Adm_AHd: AMH:A99.(6)9UMAzd_ Aza_ Ada dcAdc UCA Uc. Afi A(6)9fw Ama dyAdy calendar_clock A9999yc-Amy-Adm_A Hd: AMH:A 99. (6)9UM_ Aza_ Ada. clock A9999yc- Amy- Adm J\Hd: AMH:A99.(6)9UM Aza Ada. date is the process default value for date. date_time is the process default value for date and time. iso_date A9999yc- Amy- Adm. iso_date_time A9999yc- Amy- Adm AHd:AMH:ASM Aza. iso_IonLdate A9999yc- Amy- Adm Ada. iso_IonLdate_time A9999yc-J\my- Adm AHd: AMH:A99.(6)9UM Aza. iso_IonLtime AHd: AMH: A99.(6)9UM. iso_time AHd:AMH:ASM. multics_date Amy / Adm/ AyC. multics_date_time Amy/Adm/Ayc AHd A99v.9MH Axxxxza Axxxda. multics_time AHd:AMH. request_id AycAmyAdmAHdAMHA99.(6)9UM. The output from this keyword is specified in the process default time zone; therefore if you want a valid request-id. specify -zone GMT in commands or give GMT as the zone argument when calling date=,-time_$format with the request_id keyword (see "Request IDs" in Section 3 of the Programmer's Reference Manual). system_date_time is the system default value for date and time. 1-14 AG92-06 system_date is the system default value for date. system_time is the system default value for time. time is the process default value for time. Your site can change the "system" strings. For an application that depends upon the historic formats the three builtin "multics" strings are available. Processing of a control string proceeds by scanning the control string until a circumflex is found or the end of the string is reached. Any text (including any blanks) passed over is copied to the output string. The selector is then interpreted and executed. This causes a datum from the input clock value to be edited into the output string. Processing continues in this way until the control string is exhausted. You can express dates and times placed in the output string in units of years, months, weeks, days, hours, minutes, seconds, and microseconds, and the total calendar value as a single unit; for example, you could express the calendar value representing 79-09-08 9:42A GMT as 1979 years, as 722i02 days. or as 722702.112499 days. This is the set of "total" selectors: Ayc Amc Adc AHc AMc ASC AUC You can unit has units for day. and Amy Adm Adw AHd AHh AMH ASM AUS total total total total total total total number number number number number number number of of of of of of of years in the calendar value months in the calendar value days in the calendar value hours in the calendar value minutes in the calendar value seconds in the calendar value microseconds in the calendar ·value. also express dates and times as the number of units remaining after a larger been removed from the calendar value; for example, 09/08/79 09:42 includes the 9th month of the year, the 8th day of the month. the 9th hour of the the 42nd minute of the hour. The following are the most common: month in the year day of the month day of the Week hour of the day (24-hour format) hour in half day (12-hour format) minute of the hour second of the minute microsecond of the second. There are several items of date/time data that are nonnumeric, such as day of week, day of month, and time zone used for conversion. 1-15 AG92-06 ~n ""ma Adn Ada Azn Aza Azd Ami Afi month name month name, abbreviated (char (3» day name day name, abbreviated (char (3» time zone name time zone name, abbreviated (char (4» zone different i a 1 (char (5) ) meridiem indicator (A or P) fiscal indicator (FW in Engl ish) The selectors of numeric data are, in general, made up of two letters taken from this sequence: c y m w d H M S U. These letters stand for calendar, year, month, week, day, hour, minute, second, and microsecond. respectively. All 81 combinations are not, however. valid. The form can generally be read as "unit of unit", e.g., "seconds of week". The first unit is always smaller than the second one. In trying to keep the specifiers reasonably mnemonic (in English) there is a problem: both month and minute begin with an "m". So all date values are used as lowercase letters while all time values are in uppercase. It is difficult to try to handle all the forms needed in a general manner. Hd is hour of the day and is thus 24-hour time; this is not always what is wanted. Hh is chosen as hour in half day to get the 12-hour form of time. To go along with this there is "mi" for Meridiem Indicator. which gives A or P to make up AM or PM. This· does not give AM or PM because ANSI and ISO standards specify that time be given as "3P", not "3PM". If you want the M, put the literal in, e.g., ""miM". Another way of looking at a calendar value is in terms of fiscal week. This is selected with the ""fw" code. Its value is four digits of year followed by two digits of week number, i.e., yyyyww. The default picture has been chosen to give a value of yww. The associated fiscal indicator is selected by ""fi". A complete value is obtained by specifying ""fi"fw". The table below shows the complete set of selectors. The row specifies what unit is wanted. the column specifies within what other unit. e.g., "Sy is seconds of year. 1-16 AG92-06 DATE/TIME SELECTORS of of calen- year ------dar microsecond I AUC t AUy minute hour day month year of day of hour of of minute second +------+------+------+------+------+------+------+------+ I AUm I AUW I AUd I AUH I AUM I AUS I +------+------+------+------+------+------+------+------+ I ASC I ASy I ASm I ASW I ASd I ASH I ASM I +------+------+------+------+------+------+------+ I AMc I AMy I AMm I AMw I AMd I AMH I +------+------+------+------+------+------+ I AHc I AHy I AHm I A~~ I AHd I +------+------+------+------+------+ I Adc I Ady I Adm I Adw I month day zone +------+------+------+------+ +------+------+------+ I Amn I Adn I Azn I I I Amy I name +------+------+ +------+------+------+ abbrev I Ama I Ada I Aza I I Ayc I +------+ +------+------+------+ I AHh I <-hour of half day differential I Azd I +------+ (l2-hour form) +------+ I Ami I <-meridiem indicator ("A" or "pll) +------+ I Afw I <-fiscal week (form: yyyyww) +------+ I Afi I <-fiscal indicator ("FW" in Engl ish) +------+ I second of week of month I I I I I I I You can control the formatting of date and time values by an optional PL/I picture specification included in the selector; for instance. a code of A0099yc formats the total years in the calendar value into a two-digit year of the 20th century and A9999yc provides a full. four-digit year. The following is a brief description of the most frequently used picture characters. For more details on PL/I pictures. see the Multics PL/I Language Specification manual (AG94) and the Multics PL/I Reference Manual (AM83). 9 represents a mandatory decimal digit in the displayed value. z represents a decimal digit in the displayed value. Nonsignificant zeros on the left are replaced by a space when they occupy a "z" digit position. produces a period in the displayed value. This has no relation to the· location of the decimal point in the value actually being displayed. If zero suppression is in effect, this is replaced with a space. produces a comma in the displayed value. period. v It has all the characteristics of the locates the value's decimal point in the result This determines how the value digits are oriented with respect to the picture specification. If you supply no "v", it. is assumed to appear after the rightmost picture character. 1-17 AG92-D6 The picture characters above are sufficient for displaying most numeric values. For example. the control string "99Hd"99.v9MH represents the time in hours. minutes, and tenth of minutes: the control string "zz9.999vUS represents the number of milliseconds of the second. using the decimal point and "v" to scale the microsecond unit. Scaling can also be performed by a picture scale factor. f(N) scales the value by multiplying or dividing by a power of 10. thus shifting the location of the decimal point in the value. For example. f(2) shifts the decimal two places left. effectively dividing the value by 100; f(-3) shifts three places right. effectively multiplying by 1000. Using a picture scale factor. you can display the milliseconds in excess of a second to the nearest tenth using the control string "zz9.9f(3)US. You can display a value of 48634 microseconds as " 48.6" milliseconds. There are two extensions to numeric picture handling that you can use in time format selectors: Z represents a decimal digit in the displayed value. Nonsignificant zeros to the left of the decimal point are omitted when they occupy a "Z" digit position; to the right of the decimal point they are omitted when they occupy a "Z" digit position. Z characters must appear as the leftmost or rightmost digit positions in the picture specification since these are the positions that nonsignificant zeros can occupy. Z performs a selective ltrim or rtrim (of zero) operation on the displayed value. For example. you can specify the millisecond specification given above as "ZZ9.9ZZUS without using a picture scale factor; with this specification you can display 48630 microseconds as 48.63 milliseconds (without the leading space or trailing zero). o represents a decimal digit in the displayed value that should be omitted. Specifying "99yc for a year like 1941 results in a size condition since it takes four digits to handle that number. To get the year in century you can use "0099yc; this gives four digits into which the value is placed and then the first two digits are discarded. A picture like 00z9 with a value of 1502 gives 02 because the zero suppression applies to 1502. and then the first two digits are dropped. You can format character date/time values such as day of the week. month name. and time zone using a character picture specification with the "x" picture character. x represents a position that can contain any character. Since national characters occur in some of the time names, avoid use of the "a" picture character. Values are left-justified in the picture specification, with truncation of the rightmost characters if the value is longer than the picture or padding with spaces on the right if the value is shorter than the picture. For example. "xxxxxxxxdn displays Wednesday as "Wednesday" and Monday as "Monday n. You can use a picture repetition factor to shorten the control string to ""(9)xdw". With "(5)xmn January is displayed as "Janua" and May is displayed as "May". (Note that in some languages the abbreyjation of a time name is not the first three letters of it.) 1-18 AG92-Q6 The selector picture specification allows an extension of the "x" picture specification. X represents an optional character position in the displayed value. The character position is omitted if there is no corresponding character in the value being displayed. X characters must appear as the rightmost character position in the picture specification since this is the position that nonsignificant spaces can occupy. X performs a selective rtrirn operation on the displayed value. The code A(9)Xdw displays Wednesday and Monday both without trailing spaces. The table below shows the default picture specifications for all selectors. The row specifies what unit is wanted. the column specifies within what other unit DEFAULT PICTURE VALUES of of calen- year dar microsecond second mi nute hour day month year I of month I of week of day of hour of of minute second +------+------+------+------+------+------+------+------+ I (18) Z91 (14) Z91 (13) Z91 (12) Z91 (11) Z91 (10) Z91'(8) Z9 I (5) Z9 I +------+------+------+------+------+------+------+------+ I (12) Z91 (12) Z91 (8) Z9 I (6) Z9 I (5) Z9 I (4) Z9 I 99 I +------+------+------+------+------+------+------+ I (10) Z91 (6) Z9 I (5) Z9 I (5) Z9 I (4) Z9 I 99 I +------+------+------+------+------+------+ I (8) Z9 I (4) Z9 I (3) Z9 I (3) Z9 I 99 I +------+------+------+------+------+ I (7)Z9 I 999 I 99 I 9 I month day zone +------+------+------+------+ +------+------+------+ I I 99 I name I (32) X I (32) X I (64) X I +------+------+ +------+------+------+ I 0099 I abbrev I (8) X I (8) X I (8) X I +------+ +------+------+------+ 1 99 I <-hour of half day differential I s 9999 I +------+ (12-hour form) +------+ x <-meridiem indicator +------+ 10009991 <~fjscai week (form: yyyyww) +------+ I xx I <-fiscal indicator +------+ I 1 1-i9 AG92-06 The following table shows how date and times strings are displayed by a variety of control strings. Amn AZ9dm, A9999yc displays September 8. 1979. Amn Az9dm, A9999yc displays September 8, 1979. Adm Ama A9999yc Azn displays 08 Sep 1979 Mountain Standard Time. Amy /Adm/Ayc AHd A99v.9MH Aza Ada displays 09/08/79 0242.4 mst Sat. AHd:AMH:ASMAzd displays 02:42:25-0700. A9999yc- Amy- Adm_AHd: AMH:A99.(6)9UM_ Aza_ Ada displays "1979-o9-o8_02:42:25.048634_mst_Sat <_A xyzA -> displays <-o2:42xyz09/08/79->. 1-20 AG92-06 SECTION 2 REFERENCE TO COMMANDS AND ACTIVE FUNCTIONS The Multics commands and active functions are presented in this section by functional use. ACCESSING THE MULTICS SYSfEM access_class dial echo enter hangup hello help. HELP login logout MAP modes noecho slave terminal_id terminal_type * COMMAND LINE PROCESSING abbrev answer convert_ec default do do_subtree exec_com execute_string if login_args on pause program_interrupt 11/86 progress query release response run select set_epilogue_command severity start stop_run subSiiiUie_arguments walk_subtree 2-1 AG92-o6A PROCESS ENVIRONMENT change_error_mode exponent_control general_ready home_dir logout new_proc no_save_on_disconnect print_auth_names print_proc_auth process_dir process_switch_off process_switch_on ready ready_off ready_on reconnect_ec_disable reconnect_ec_enable reprin t_error save_on_disconnect set_tty system user STORAGE SYSTEM NAMES add_name branches component compare_entry_names copy_names def aul t_wdir delete_name directories directory entries entry entry_path equal_name files get_pathname home_dir is_component_pathname links list list_subtree list_ref_names list_temp_segments master_directories move_names msfs non branches nondirectories 11/86 nonfiles nonlinks nonmaster_directories nonmsfs nonnull_links nonobject_files nonobject_msfs nonobject_segmen ts nonsegments nonzero_files nonzero_msf s nonzero_segmen ts nun_links object_files object_msfs object_segments path process_dir rename segments shortest_path strip strip_component strip_entry suffix workinLdir zero_segments 2-2 AG92-06A CREATING AND EDITING SEGMEN1S adjust_bit_count canonicalize convert_characters convert_ec file_output format_pll indent merge_ascii copy create delete edm emacs expand_cobol_source set_bit_count sort_seg teco teco_error qedx teco_ssd SEGMENT A'ITRIBUTES add_name adjust_bit_count check_file_system_damage copy_acl copy_names delete_acl delete_name describe_entry_type get_effective_access list_acl list_entry_types list_temp_segments rename set_acl set_bit_count set_max_Iength set_rin~brackets status switch_off switch_on truncate vfile_adjust vfile_status SEGMENT MANIPULATION archive archive_sort canonicalize compare compare_ascii compare_pll contents copy create decode delete dump_segment encode initiate linkage_editor mbx_create merge_ascii move overlay print reorder_archive sort_seg tape_archive terminate terminate_ref name terminate_segno terminate_single_refname truncate DATA MANAGEMENT FILE MANIPULATION bef ore~ournal_status bj_mgr_call create_dm_file 11/86 dm_display_ version dm_user_shutdown transaction 2-3 AG92-06A DIRECfORY ATTRIBUTES add_name check_file_system_damage copy_acl copy_iacl_dir copy_iacl_seg copy_names delete_acl delete_iacl_dir delete_iacl_seg delete_name get_dir_quota get_eiiective_access get_quota list_acl list_iacl_dir list_iacl_seg move_dir_quota move_quota rename set_acl set_dir_rinLbrackets set_iacl_dir set_iacl_seg set_mdir_account status ____ !._1.. _~~ :SWl~n_Ull switch_on DIRECfORY MANIPULATION ° comp_dir_inf copy_dir create create_dir date_deleter delete delete_dir directories do_subtree link linkage_editor list list_dir_inf list_sub_tree move_dir rebuild_dir save_dir_inf unlink walk_subtree ° ° EXTENDED ENTRY TYPES add_name copy copy_names delete delete_acl delete_name describe_entry_type entries exists list_acl list_entry_types move move_names rename set_acl set_bit_count set_max_Iength set_rinLbrackets status switch_off switch_on 2-4 AG92-06 LINKS AND SEARCH FACILITIES add_search_paths add_search_rules change_wdir change_default_wdir default_wdir delete_search_paths delete_search_rules get_system_search_rules hunt hunt_dec initiate list_ref_names print_default_wdir print_search_paths print_search_fules print_wdir resolve_linkage_error set_search_patbs set_search_rules terminate where where_search_paths. workin~dir ACCESS CONTROL AND RINGS OF PROTECTION check_iacl copy_acl copy_iacl_dir copy_iacl_seg delete_acl delete_iacl_dir delete_iacl_seg get_eff ective_access list_accessible list_acl list_not_accessible list_iacl_dir list_iacl_seg print_auth_names print_proc_autb set_acl set_iacl_dir set_iacl_seg * set_dir_rin~brackets set_rin~brackets STORAGE SYSTEM, LOGICAL VOLUMES attach_Iv delete_volume_quota detach_Iv list_mdir lv_attached set_mdir_account set_mdir_owner set_mdir_quota set_volume_quota STORAGE SYSTEM BACKUP AND RETRIEVAL cancel_retrieval_request compare_dump_tape copy_dump_tape en ter_retrieval_request list_retrieval_requests * ONLINE INFORMATION check_info_segs explain_doc help how_many_users list_help print_motd tutorial validate_inf o_seg where_doc who 2-5 AG92-06 MENU AND VIDEO SYSTEM menu_create menu_delete menu_describe menu_display menuJet_choice menu_list window _call INTERUSER COMMUNICATION * accept_messages accepting def er_messages delete_message display_mailin~address have_mail have_messages immediate_messages last_message last_message_destination last_message_sender last_message_ time mail message_status mox_create print_mail prin t_messages read_mail send_mail send_message set_mailin~address who INPUT/OUTPUT SYSTEM CONTROL attach_audit cancel_daemon_request cancel_output_request close_file connect copy_cards copy_file detach_audit dial_manager_call dial_out discard_output display _audi t_f ile dprint dpunch enter_output_request file_output get_mode have_Queue_entries io_call kermit 16_ftf line_length list_daemon_requests list_emacs_ctls list_output_requests micro_ transf er move_daemon_request move_output_request networ k_request print print_attach_table prin t_request_ types prin t_ terminal_ types repeat_line set_tty tape_archive tape_in tape_out total_output_requests vfile_adjust vfile_find_bad_nodes vfile_status window_call 2-6 AG92-06 FORMAITED OUTPUT FACILITIES cancel_daemon_request cancel_output_request dprint dpunch en ter_output_request format_document format_line f ormat_line_nnl format_pll format_string have_Queue_entries indent list_daemon_requests list_output_requests move_daemon_request mOVe_output_request overlay picture print prin t_request_types runoff runoff_abs set_cc sort_strings total_output_requests TERMINAL ' INTERFACE PROGRAMS cv_ttf connect dial_out display_ttt get_mode kermit line_length 16_ftf micro_transf er network_request prin t_terminal_types print_ttt_path set_ttt_path set_tty window_call CONTROL OF ABSENTEE COMPUTATIONS cancel_abs_request cobol_abs enter_abs_request fortran_abs list_abs_requests move_abs_request pll_abs runoff_abs PROGRAMMING LANGUAGES (COMPILERS) 11/86 aIm pascal_cross_reference alm_abs apl basic cobol cobol_abs create_data_segment fortran f ortran_abs list_fortran_storage pascal pascal_area_status pascal_create_area pascal_delete_area pascal_display pascal_file_status pascal_indent pascal_reset_area pascal_set_prompt pll pll_abs pll_macro reductions 2-7 AG92-06A PROGRAMMING/DEBUGGING AIDS add_pnotice cancel_cobol_program close_file create_data_segment cumulative_page_trace debug delete_external_variables display_cobol_run_uni t display_entry_point_dcl display_pllio_error display_pnotice expand_cobol_source exponent_con trol fast format_pll history_comment indent io_call list_external_variables list_f ortran_storage list_pnotice_names nothing print_bind_map print_error_message print_link_inf0 prin t_linkage_usage print_sample_refs probe process_switch_off process_switch_on profile progress reset_external_variables run run_cobol sample_refs save_history _registers set_fortran_common set_cc set_severity_indicator severity signal stop_run stop_cobol_run trace trace_meters trace_stack valid_pictured_data watch OBJECf SEGMENT MANIPULATION archive archive_table bind compare_object cross_reference date_compiled display_component_name bunt_dec linkage_editor print_bind_map print_link_inf0 prin t_relocation_inf 0 reorder_archive AREA MANAGEMENT area_status create_area set_system_storage set_user_storage PERFORMANCE MONITORING FACILITIES cumulative_page_trace page_trace prin t_linkage_usage profile 11/86 progress trace trace_meters watch 2-8 AG92-06A SYSTEM LIBRARIES add_pnotice cross_reference describe_psp display _pnotice generate_pnotice get_library_segment library_descriptor library_fetch list_pnotice_names peruse_crossref ARCHIVE SEGMENT MANIPULATION archive archive_sort archive_table bind compare_ascii component get_library_segment is_component_pathname library_fetch linkage_editor merge_ascii path print print_link_inf0 reorder_archive strip_component test_archive SYSTEM MAINTENANCE AND DEBUGGING TOOLS get_ips_mask monitor_quota reset_external_variables reset_ips_mask set_ips_mask RESOURCE CONTROL PACKAGE attach_Iv acquire_resource assign_resource cancel_resource detach_Iv list_resources list_resource_types Iv_attached release_resource reserve_resource resource_status unassign_resource TAPE MAINTENANCE UTILITIES list_tape_contents manage_volume_pool read_tape_and_query mtape_delete_defaults mtapeJet_defaults mtape_set_defaults tape_archive tape_in tape_out CONDITION HANDLING change_error_mode display_pllio_error on 11/86 reprin t_error signal 2-9 AG92-06A SETI1NG AND srORING VARIABLES delete_external_variables list_extemal_variables reset_external_variables value_defined value_delete valueJet value_list value_path value_set value_set_path ADMINISTRATIVE UTILITIES * check_file_system_damage compare_configuration_deck deiete_volume_quota list_mdir monitor_quota print_configuration_deck set_mdir_account ARITHMETIC OPERATIONS calc ceil divide floor index_set max min mod plus quotient times trunc minus LOGICAL OPERATIONS and equal exists greater if less nequal ngreater nless not or select CONVERSION OPERATIONS binary convert_characters convert_ec cv_ttf decimal dump_segment hexadecimal octal 2-10 AG92-06 CHARACI'ER STRING OPERATIONS after before b001 byte collate collate9 copy_characters decat format_line f ormat_line_nnl format_string high high9 index index_set length low lower_case ltrim picture DATE A~l) unique upper_case verify TIMES calendar calendar_clock clock date date_time date_time_after date_time_before date_time_equal date_time_interval date_time_valid day daY.Jlame 11/86 rank reverse reverse_after reverse_before reverse_decat reverse_index reverse_search reverse_substr reverse_verify rtrim search sort_strings string substr translate underline display_time_info hour Ions-date lonuear memo minute month month_name print_time_defaults set_time_default time year 2-11 AG92-06A SECTION 3 COMMANDS AND ACTIVE FUNCTIONS This section contains descriptions of the Multics commands and active functions, presented· in alphabetical order. 3-1 AG92-06 abbrev abbrev Name: abhreY, ab SYNTAX AS A COMMAND ab {-control_args} SYNTAX AS AN ACTIVE FUNCTION Cab] FUNCTION provides a mechanism for abbreviating parts of or whole command lines in the Muttics command environmenL As an active functi~ returns "true" if abbreviation expansion of command lines is currently enabled, "false" otherwise. CONTROL ARGUMENTS -esalpe STR, -esc STR changes the abbrev escape character used to indicate that a command line is actually a request line. STR must be a single, nonblank character. (See "Notes on Control Requests" and the .escape control request.) (Default a period [.J) -off disables abbreviation expansion in subsequent command lines (see the .quit request). -on enables abbreviation expansion within subsequent command lines until you use either -off or .quit. (Default) -profile path, -pC path changes the patbname of the profile segment. The "profile" suffix is assumed if you don't supply it. If the specified segment is nonexistent, you are asked for permission to create it. (See the .use request.) (Default >udd>ProjectJd>Penonjd>Personjd.profi1e) cbf NOTES The abbrev command sets up a special command processor that is called for each command line input to the system until abbrev processing is explicitly reverted. The abbrev command processor checks each input line to see if it is an abbrev request line, recopized by a period as the first nonblank character of the line, and, if so, acts on that request (see "List of Control Requests"). If the input line is not an abbrev request line and abbreviations are included in the line, they are expanded only once (i.e.. they cannot be nested) and the expanded string is passed on to the normal Multies command processor. The abbrev command processor is, therefore, spliced between the listener and the normal command processor. 11/86 3-2 A092-()6A abbrev abbrev NOTES ON CONTROL REQUESTS An abbrev request line has a period (.) as the first nonblank character of the line. An abbrev request line. with the exception of .s and . , is neither checked for embedded abbreviations nor (even in part) passed on to the command processor. If the command line is not an abbrev request line. abbrev expands it and passes it on to the current command processor. LIST OF CONTROL REQUESTS The character immediately after the period of an abbrev request line is the name of the request The following requests are recognized: prints "abbrev" followed by the current version number of the abbrev processor . • passes on to the current command processor without expanding it. Using this request, you can issue a command line that contains abbreviations that are not to be expanded . • a adds the abbreviation to the current profile segment. It is an abbreviation for . The string can contain any characters. If the abbreviation already exists, you are asked whether to redefine it You must respond with "yes" or "no." The abbreviation must be no longer than eight characters and must not contain break characters. • ab adds an abbreviation that is expanded only if found at the beginning of a line or directly following a semicolon (;) in the expanded line. In other words, this is an abbreviation for a command name. • abf adds an abbreviation that is expanded only at the beginning of a line and forces it to replace any previous one with the same name. You are not asked whether to redefine it .af adds an abbreviation to the profile segment and forces it to overwrite any previous one with the same name. You are not asked whether to redefine it. .d ••• deletes the specified abbreviations from the current profile "segment. .f enters a mode (the. default) that forgets each command line after executing it (see .r and .s). • 1 .•• lists the specified abbreviations and the strings they stand for. If none are given. all abbreviations in the current profile segment are listed. 3-3 AG92-06 abbrev abbrev .a NAME LINE adds the abbreviation NAME to the current profile segment. It is an abbreviation for LINE. The LINE string can contain any characters except break sequences. (See "Notes on Break Sequences. ") If the abbre·viation already exists, you are asked whether to redefine it; respond with "yes" or "no." .ab NAME LINE adds an abbreviation that is expanded only if found at the beginning of a line or after a semicolon (;), semicolon vertical bar pair (; I), or left bracket ([) in the expanded line. In other words, this is an abbreviation for a command name. .abf NAME LINE adds an abbreviation that is expanded only at the beginning of a line and forces it to replace any previous one with the same name. You are not asked whether to redefine it. .af NAME LINE adds an abbreviation to the profile segment and forces it to overwrite any previous one with the same name. You are not asked whether to redefine it. .debug invokes debug to debug a process in which it is no longer possible to execute commands although it is still possible to execute abbrev request lines. .delete NAMEs•. d1 NAMEs.. 0 NAMEs deletes the specified abbreviations from the current profile . .edit NAME invokes Qedx to edit the definition of the specified abbreviation (see "Notes on Editing Abbreviations") . .escape {STR}, .esc {STR} changes the escape character used to indicate that a command line is actually a request line. STR must be a single, non blank character. If you give no STR, the escape character presently in use is displayed. (Default: a period [.J) .forget, .f disables .remember; i.e., it forgets each command line after executing it (see .remember and .show). (Default) .1 {NAMEs} displays the names, switches, and definitions of the specified abbreviations in alphabetical order. If you give no names, all abbreviations in the profile are listed. . la STRs displays the names, switches, and definitions of any abbreviations whose names start with one of the given strings. Supply at least one string. 11/87 3-4 AG92-06B abbrev abbrev .lab, la Ab STRs displays the names, switches. and definitions of abbreviations which are beginning-of-line abbreviations (lab) or not beginning-of-line abbreviations (laAb), starting with STRs. .lb. lAb {names} displays the names, switches, and definitions of the given abbreviations; lb for beginning-of-line, lAb for not beginning of line abbreviations. If no names are given, lists all of the abbreviation-type. .Is STRs displays the names. switches. and definitions of any abbreviation which contain STRs in its name. .Isb, lsA b STRs displays the names, switches, and definitions of any beginning-of-line abbreviations (lsb) or not beginning-of -line abbreviations whose name contains STRs. .lx STRs displays the names, switches and definitions of abbreviations whose definitions contain STRs. .Ixb, lxAb STRs displays the names, switches and definitions of beginning-of -line abbreviations (lxb) or not beginning-of-line abbreviations (IxAb) whose definitions contain STRs. 11/87 3-4.1 AG92-06B abbrev abbrev paren theses apostrophe period semicolon less than greater than brackets braces vertical bar ,o < > [] {} I The two-character-sequence archive component pathname delimiter (::) is also recognized as a break sequence. EXAIVIPLES Suppose that you wish to abbreviate the pathname of a directory in which you do a lot of work. Instead of having to type the entire pathname every time you need to reference it, it can be called up easily with much fewer keystrokes as in the following examples: Invoke the abbrev command: ! ab Define the abbreviation: ! .a myinfo >udd>States>Washington>info Now that "myinfo" is defined. you can change to that directory. ! cwd my info . Change to the inferior directory called data_dire ! cwd myinfo>data_dir Another useful abbreviation is for the enter_output_request command, when you frequently use a certain printer queue and a special request type. The do command is used to substitute arguments into the abbrev. For example: ! . ab pr i ntx do "eor &1 -q 2 -rqt x 1200 -nt -he "By George lill Now to request a printout of a segment contained in "myinfo," type: ! printx myinfo>dat~.list With the do command you can also perform a series of functions that are defined by one simple abbrev; for example: .ab send_cp do "sms Lincoln.States A copy of &1 that I've prepared this week is being printed for you.; printx -dl -he Lincoln &1 11 AG92-06 abbrev abbrev NOTES ON BREAK SEQUENCES When abbrev expands a command line, it treats certain character sequences as special break sequences. An abbreviation cannot contain break sequences. Any character string up to eight characters long and bounded by break sequences can be expanded. The string is looked up in the current profile segment and. if found, the expanded form is placed in a copy of the command }jne to be passed on to the normal command processor. The following single-character break sequences are recognized by abbrev: apostrophe backquote braces brackets dollar sign formfeed greater than horizontal tab less than newline parentheses period quote semicolon space vertical bar vertical tab {} [] $ FF > HT < NL 0 II I VT The beginning and end of the line and the two-character-sequence archive component pathname delimiter (::) are also break sequences. LIST OF ABBREVIATION DEFINITION SWITCHES The following switch is part of the definition of each abbreviation: beginninLof_line, bol specifies that this abbreviation is only expanded in a command when appearing at the beginning of a line or immediately after the semicolon (;), semi-colon vertical bar pair (; I) or left bracket (D. (I.e., when the abbreviation is used as the command name). If this switch is off, the expansion occurs anywhere on a command line. NOTES ON EDITING ABBREVIATIONS When you invoke the edit request to edit an abbreviation, it first displays the definition of the abbreviation and then invokes Qedx with the definition in buffer O. Using the Qedx write request without a pathname saves the revised definition in the profile segment. Using the read or write request with a pathname, in any buffer, makes the pathname be interpreted as the name of an abbreviation. Presently, you can't read a buffer from, or write it to, a segment. 11/87 3-6 AG92-06B abbrev abbrev When writing a buffer and an abbreviation of the given name does not exist, it is created with the bol switch set off. If the abbreviation already exists and is not the default for the buffer as displayed by. the Qedx status request, abbrev asks for permission to overwrite the definition of the abbreviation. In this' case, the abbreviation retains its original setting of the bol switch. EXAMPLES Suppose that you wish to abbreviate the pathname of a directory in which you do a lot of work. Instead of having to type the entire pathname every time you need to reference it, you can use fewer keystrokes, as in the following examples: Invoke the abbrev command: , I ab Define the abbreviation I .a Opinfo >user_dir_dir>Antarctica>Opus>Opus.profile Now that "Opinfo" is defined, you can change to that directory. I cwd Opinfo Change to the inferior directory called data_dir. I cwd Opinfo>data_dir When you frequently use a certain printer queue and a special request type, an abbreviation for the enter_output_request command is I .ab printx do lIeor &1 -q 2 -rqt x1200 -nt -he IIBy Jove llll Now, to request a printout of a segment contained in "Opinfo," type: I printx myinfo>data~list With the do command you can also perform a series of functions that are defined by one simple abbrev; for example, .ab send_cp do II sms Opus.Antarctica A copy of &1 that live prepared this week is being printed for you.; printx -d1 -he Opus &1 11 11/86 3-7 AG92-()6A abbrev Then the following send a message and a copy of data.list to Opus. send_cp data.list An abbreviation can invoke other abbreviations, as seen above. If you want to ensure, within the do's command line, that a string not be expanded, enclose it in an extra layer of quotes; for example, • ab eor do 1IIIIIeerllll &1 -rqt x 1200 -q 3" Name: accept_messages, am SYNTAX AS A COMMAND am {mbx_specification} {-control_args} FUNCTION initializes or reinitializes your process both for accepting messages that are sent by send_message and for notifications. ARGUMENTS mbx_specification specifies the mailbox on which messages are to be accepted. If not given, the user's default mailbox (>udd>Project>Person>Person.mbx) is used. LIST OF MBX SPECIFICATIONS -log specifies the user's logbox and is equivalent to -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx -mailbox path, -mbx path specifies the pathname of a mailbox. The suffix .mbx is added if necessary. -save path. -sv path specifies the pathname of a savebox. The suffix .sv.mbx is added if necessary. -user STR specifies either a user's default mailbox or an entry in the system mail table. STR is any noncontrol argument, and is first interpreted as -mailbox STR; if no mailbox is found. STR is then interpreted as -save STR; if no savebox is found, it is interpreted as -user STR. 11/86 3-8 AG92-06A CONTROL ARGUMEIVTS -brief, -bf prevents accept_messages from informing you that it is creating a mailbox, and prints messages in short format -call {cmdline} when the message is received, instead of printing it in the default format, accept_messages calls the command processor with a string of the form cmdline number sender time message {path} where: cmdline is any Multics command line; enclose it in quotes if it contains blanks or other command language characters. number is the sequence number of the message, assigned when you use -hold_messages; otherwise it is O. sender is the User_id of the person who sent the message. time is the date-time the message was sent message is the message sent path is the pathname of the mailbox to which the message was sent message was sent to the default mailbox, path is omitted. To suppress a previous =call, give -call with no cmdline If the arg-lL.~ent -flush Dr discards messages sent before the specified date-time (see Section 1 for a description of valid Dr values). This control argument should be used by operators and consultants. -hold_messages, -hdmsg holds messages until explicitly deleted by delete_message. Messages printed when -hold_messages is in effect are preceded by an identifying number. 11/86 3-9 AG92-06A -holdJlotifications, -hdnt holds notifications in the mailbox after being printed. This implies -notifications. -long, -lg precedes every message printed by the sender's PersoD_id and Project_id and prints the date-time string. It prints the message number only if you use ....hold_mesages (Default) -no_holdJllessages, -nhdmsg reverts -hold_messases_ -nojold_notifications, -nhdnt deletes notifications after being printed. (Default) -noJlotifications, -nnt deletes notifications as they are received. This implies -nojoldJlotifications. -no_print, -npr does not print old messages (Default) -noJhort_pref~ -nshpfx does not print the prefix when me ges are printed in short formal -notifications, -nt prints notifications. (Default) -prefix STR, -pCx STR places STR in front of all messages printed as they are received. STR can be up to 12 characters long, and can contain the ioa_ control strinp A /, A I, and A_ if desired. -print, -pc prints aU messages that you received since the last time you were accepting messages The messages are deleted after printing, unls you are holding them. -short, -sh precedes eonseeutive messages from the same sender by "-" instead of the PersoD_id and Project_id, and prints the date-time string only if 15 than five minutes have passed since the previous message. It omits the date if the current msage and the previous one are received on the same date. -short_pref~ -shpfx prints the prefix when masages are printed in short formal (Default) 11/86 3-10 AG92-06A -time N, -tIn N prints undeleted messages every N minutes, preceded by a message of the form You have X messages where X is the number of undeleted messages. If N equals 0, the time mode is reset. NOTES A default mailbox is created the first time you issue print_mail read_mail or accept_messages. The default mailbox is >udd>Project_id>Person_id>Person_id.mbx Messages sent when you are not logged in or when you are deferring messages (see defer_messages) are saved in the mailbox; you can read them later with print_messages. The send_mail command stores mail in the same mailboL Don't share the same mailbox with others. At any time, only one process can be accepting messages from a given mailboL If you create two processes that accept messages from the same mailbox, the second process (i.e., the one issuing an accept_messages most recently) automatically take over the command function. The first process receives no indication that messages are being routed to the second process. If the second process logs out or is destroyed, the messages do not revert to an earlier process; thus if you send a message to that mailbox. you axe informed that the addressee is c1L~ent1y not accepting m~~ges or is not logged in. So if you are registered on multiple projects using a common mailbox. be aware that this behavior affects your processes. Generally don't accept messages in absentee processes; the start_up.ec should distinguish between interactive and absentee processes, and should issue accept_messages only in an interactive process. You can accept messages on more than one mailbox at a time and on a mailbox other than the default. If you use a nondefault mailbox and it does not exist, accept_messages queries you whether it should be created. When messages are printed from a nondefault mailbox, the mailbox is always identified. 11/86 3-11 AG92-06A accepting Name: accepting SYNTAX AS A COMMAND accepting address SYNTAX AS AN ACTiVE FUNCTION [accepting address] FUNCTION determines whether messages are being accepted on the mailbox specified by the address supplied. ARGUMENTS address can be of the form Person_id.Project_id to specify a mailbox belonging to that person; a string containing at least one > or < to specify the pathname of a mailbox; one of the arguments -mailbox (-mbx), -log, or -save (-sv), immediately followed by a string giving the pathname of a mailbox, logbox, or save box, respectively; -last_message_destination (-lmds) if you have used send_message in this process; or -last_message_sender (-lms) if a message has been received in the user's default mailbox. Name: acquire_resource, aqr SYNTAX AS A COMMAND aqr type STRl { ••• STRs} {-control_args} aqr type -number N {-control_args} FUNCTION selects a resource of a given type from a free pool of all such resources and makes you the accounting owner of the resource. You are given full control over the access rights for all users of the resource, as well as control over many parameters of the resource. Ownership of the resource is terminated by release_resource. ARGUMENTS type is a resource type defined in the resource type description table (RTDT). 11/86 3-12 AG92-06A acquire_resource STRs is the unique identifying name of the particular resource being acquired. If STR looks like a control argument, precede it by -name (-nm). If you give no -name, a resource is chosen to satisfy any constraints imposed by the control arguments given. CONTROL ARGUMENTS -access_class accr, -acc accr sets the initial AIM access class parameters, where accr is' an access class range. Users at any authorization within the access class range inclusive are allowed to read and write to the resource (provided they also meet other access requirements). (See "Notes.") -acs_path path specifies the pathname of the access control segment (ACS) for this resource. You must create the ACS and set the desired access control list. If the ACS doesn't exist or you don't specify it. the default access is rew to the accounting owner and null to all others. If path is a null string, any eXisting ACS is disassociated from the resource. -alloc SIR sets the allocation state of the resource to allocated or free, where SIR must be either "on" (allocated) or "off" (free). The allocation state flag exists for your convenience and is largely ignored by resource management. (Default off) -attributes SIR, -attr SIR searches for resources possessing the attributes specified in STR~ If you give -attr with -nm, then the resource specified by the explicit name is searched for, and, when found, its attributes are set to those specified with -attr. -comment STR, -com STR specifies the desired value of the comment string for this resource, where STR can be an arbitrary comment string with a maximum length of 168 characters. -lock STR locks or unlocks the resource, preventing or allowing use of that resource, where STR must be either "on" (prevents use of the resource) or "off" (allows use of the resource). (Default: off) -number N, -nb N specifies that the number of such resources to be acquired is N. If you supply no -nb, 1 is assumed. You can supply -nb only if you supply no name. 11/86 3-13 AG92-G6A ARGUMENTS path is the pathname of a segment~ rnultisegment file, data management file, directory, extended entry, or link. This argument can consist of "-name STR" to specify a nonstandard entryname STR which already exists and which begins with a hyphen or contains ASCII control characters or any of the nonstandard characters ", <, >, $, %. 1, *, =, (,), [,], ::. names are additional names to be added. This argument can consist of "-name STR" when the entryname begins with a hyphen. The other nonstandard characters detailed above are not recommended for entrynames and this command will not generate entrynames which contain them. CONTROL ARGUMENTS -brief, -bf suppresses the error message "Name already on entry." -long, -lg does not suppress the error message "Name already on entry." (Default) ACCESS REQUIRED You need modify permission on the parent directory. NOTES Two entries in a directory cannot have the same entryname; therefore add_name takes special action if the added name already exists. If the added name is an alternate name of another entry, the name is removed from this entry, added to the entry specified by path, and you are informed of this action. If the added name is the only name of another entry, you are asked whether to delete this entry. If you answer "yes." the entry is deleted and the name is added to the entry spe-eified by path; if you :L.'1swer "no," no action is taken. See the delete_name and rename commands. EXAMPLES The command line an >my_dir>example.pll sample.pll adds the name sample.pll to the segment example.pll in the directory >my_dir. 11/87 3-14.1 AG92-06B The command line an >udd>**~private ==.personal adds to every entry having a name with ttprivate'~ as the last component a name with "personal" as the last component Name: add_pnotice SYNTAX AS A COMMAND add_pnotice path {-control_args} FUNCTION protects source code programs by adding, at the beginning of a program, a software protection notice (copyright public domain, or trade secret notice) in a box delimited as a comment Multiple protection notices are supported. You can protect archives of source code programs using this command. The archive pathname convention is supported. If a particular language or suffix is not supported, an appropriate message is printed. ARGUMENTS path is the name of a source code program or an archive of source programs. You can give an archive component pathname to name a single archive component You must include the language suffix or archive suffix. CONTROL ARGUMENTS -brief, -bf suppresses printing of both the source program name and the name of the pnotice that was added. -default_copyright, -dc specifies that the notice to be added to the segment is the default copyright notice. Normally, this is a Honeywell copyright, but your site can change the default (see "Notes"). -default_trade_secret, -d ts specifies that the notice to be added to the segment is the default trade secret notice. Normally, this is a Honeywell trade secret notice, but your site can change the default (see "Notes"). -long. -lg specifies that both the name of the source program and the name of the pnotice are printed when a protection notice is added. (Default) -name STR. -nm STR where STR specifies the name of a protection notice template to be added (see "Notes"). 11/87 3-14.2 AG92-06B NOTES If you give no control arguments and there are no existing pnotices in the program. an error message is issued and no changes are made to the program. If copyright pnotices are found and you use -dc or -nm. the 10-year rule is applied to the named pnotice; that is. if the notice is more than nine years old. a new copy of the notice is added with the r.urrent year. If copyright pnotices exist and you give neithe;- -dc nor -nm, the 10-year rule is applied to the most recent copyright pnotice. You can obtain a list of available copyright and trade secret protection notice template names with list_pnotice_names; you can use -nm to specify any of these templates. To list the pnotice segments in a source porgram. use display_pnotice. A given program may contain several copyright notices or a trade secret notice or a public domain notice. but cannot contain a mixture of pnotice types. 11/87 3-14.3 AG92-06B -owner SlR -ow STR specifies that this is an acquisition for the user specified by STR. If you give STR as "system," the resource is assigned to the system pool; if as "free," the resource is acquired to the free pool (effectively the same as no -ow). If STR is of the form Person_id.Project_id (where neither Person_id nor Project_id can be a star), the user specified has all the rights of ownership to the resource, as if he had acquired it personally, except that if you give ff-rll on", the .owner can't release (give up ownership of) the resource voluntarily. (See "Notes. ") -priv specifies that a privileged call is to be made to obtain the status of this resource. -release_lock STR, -rll STR specifies whether this resource can be released by the owner or only by a privileged process, where STR must be either "on" or "off." If you supply no -rll, the resource can be released by the owner. (See "Notes.") ACCESS REQUIRED You need execute access to the rcp_admin_ gate to use -access_class. -owner. -priv, or -release_lock. NOTES This command acquires a resource for either you (requestor) or the user specified by -ow. If you are registered on more than oneprojeci and need corresponding access. or other users (on any project) need access to acquire a resource, you must create or modify the ACS. You must then specify the new/modified ACS by using "aqr -acs_path." The User_id (Person_id.Project_id) specifies the user to be added to, or deleted from, the ACS. You must give -priv with -ace. -ow, and -rHo Name: add_name, an SYNTAX AS A COMMAND an path names {-control_args} FUNCTION adds alternate name(s) to a segment. multisegment file (MSF). directory, link. data management (DM) file, or extended entry. 11/86 3-14 AG92-06A SYNTAX AS A COMMAND asp search list search pathl {-control_args} ••• search_pathN {-contro 1 args}FUNCTION adds one or more search paths to the specified search list. ARGUMENTS search_list is the name of the search list to which the new search paths are added. Synonyms of search_list are described in the individual command descriptions. search_pathi specifies a new search path. where search_pathl is a relative or absolute pathname or a keyword. (For a list of acceptable keywords see "List of Keywords" below.) Each search_path argument can be followed by either the -after •. -before. -first. or -last control argument to specify its position within the search list. If no search path position control argument is specified. -last is assumed. CONTROL ARGUMENTS are used only after the search_path argument. search_pa tho Only one is allowed for each -after STR. -af STR specifies that the new search path is positioned after the STR search path. The current search path is an absolute or relative pathname or a keyword. In representing STR it is necessary to use the same name that appears when the print_search_paths (psp) command is invoked. -bef ore STR, -be STR specifies that the new search path is positioned before the STR search path. -first. -ft specifies that the new search path is positioned as the first search path in the search liSL specifies that the new search path is positioned as the last search path in the search list. LIST OF KEYWORDS Listed below are the keywords accepted as search paths in place of absolute or relative pathnames. There is no restriction as to the position of any of these keywords within the search list. 3-15 AG92-06 -home_dir, -hd -process_dir, -pd -referencins-dir, -rd -workins-dir, -wd NOTES In addition, a pathname can be specified with the Multics active function [user name] or [user project]. A search path enclosed in quotes is not expanded when placed in the search iist It is expanded when referenced in a user's process. This feature allows search paths to be defined that identify the process directory or home directory of any user. If a link target does not exist, the search facility continues to search for a matching entryname. LIST OF RELATED SEARCH FACILITY COMMANDS add_search_paths, asp delete_search_paths, dsp prin t_search_paths, psp set_search_paths, ssp where_search_paths. wsp EXAMPLES The command line asp translator >udd>Project_id>Person_id>include adds the absolute pathname >udd>Project_id>Person_id>include as a search path. This new search path is positioned as the last search path in the translator search list. The command line asp trans doc>info adds the absolute pathname represented by the relative pathname info_files as a search path to the info search list. This new search path is positioned in the info search list after the >doc>info search path. 3-16 AG92-06 The command line asp translator >udd>[user project]>incl -be >ldd>include adds the unexpanded pathname >udd> [user project] >incl to the translator search list. This new search path is positioned before the >ldd>include search path. SYNTAX AS A COMMAND asr pathl {-controi_args} ••• pathN {-control_args} FUNCTION adds pathnames and keywords to the search rules for object segments. ARGUMENTS pathi is the absolute or relative pathname of a directory or one of the keywords listed below. I CONTROL .ARGUMENTS -after path. -af path appends the previous path argument after the existing search rule named by path. -before path. -be path inserts the previous path argument before the existing search rule named by path. -force. -fe deletes any old occurrence of path in the search rules before adding the new rule. -no_force, -nfc fails and prints an error message if a rule to be added already exists in a different position. (Default) LIST OF KEYWORDS Both pathi and path arguments can be either pathnames or keywords. The defined keywords are: initiated_segments ref erencin~dir workin~dir 3-17 AG92-06 In addition, path in control args can be: home_dir process_dir any site-defined keywords NOTES No warning is printed if a rule to be' added already exists in the same position as that for which it is intended. The limit on the number of search rules allowed for a process is 21. SYNTAX AS A COMMAND abc paths {-control_args} FUNCTION sets the bit count of a segment that for some reason docs not have its bit count set properly (e.g., the program that was writing the segment got a fault before the bit count was set or the process terminated without the bit count being set). ARGUMENTS paths are the pathnames of segments and multisegment files. allowed. The star convention is CONTROL ARGUMENTS -character, -ch set the bit count to the last nonzero character. (Default: the last nonzero word) -chase chases links when using the star convention. nonstarred pathnames) (Default: to chase links only for -long, -lg print a message when the bit count of a segment is changed, giving the old and new values. -no_chase does not chase links when using the star convention. (Default) 3-18 AG92-06 after ACCESS REQUIRED You must have write access on the segment or multisegment file. NOTES The adjust_hit_count command looks for the last nonzero 36-hit word or (if specified) the last nonzero character in the segment and sets the hit count to indicate that the word or character is the last meaningful data in the segment. If the hit count of a segment can be computed but cannot be set (e.g., the user has improper access to the segment), the computed value is printed so that the user can use the set_hit_count command after resetting access or performing other necessary corrective measures. The adjust_hit_count command should not he used on segments in structured files. The vfile_adjust command should be used to adjust inconsistencies in structured files. Name: after, af SYNTAX AS A COMMAND af STRA STRB SYNTAX AS AN ACTIVE FUNCTION [af STRA STRB] FUNCTION returns the string following the first occurrence of STRB in STRA. If STRB does not occur in STRA, the null string is returned. EX.4MPLES string [after abcdef123def456 def] 123def456 string [after abcdef gh] string [format_line XyAaZZ [after 1.4596e+17 7]] XYZZ 3-19 AG92-o6 aIm aIm Name: aIm SYNTAX AS A COMMAND alm path {-control_args} FUNCTION ALM is the standard Multics assembly language. It is commonly used for privileged supervisor code, higher level support operators and utility packages, and data bases. It is occasionally used for efficiency or for hardware features not accessible in higher level languages; however, its routine use is discouraged. The aIm command invokes the ALM assembler to translate a segment containing the text of an assembly language program into a Multics standard object segment. A listing segment can also be produced. These segments are placed in the user's current working directory. The ALM language is described briefly in this command description. Processor Manual (AL39) fully describes the instruction set The Multics ARGUMENTS path is the pathname of an ALM source segment that is to be translated by the ALM assembler. If path does not have a suffix of aIm, one is assumed. However, the suffix must be the last component of the name of the source segment CONTROL ARGUMENTS are optional arguments that can only appear after the path argument. The control argumen ts are: -arguments STR, -ag STR indicates that the assembled program may expect arguments. If present, it must be the last control argument to the aIm command and must be followed by at least one argument See "Macros in ALM" later in this description. -brief. -bf prevents errors from being printed on the terminal. Any errors are flagged in the listing (if one has been requested). -list, -Is produces an assembly listing segment. -no_symbols suppresses the listing of a cross-reference table in the listing segment. This cross-reference table is included by default in the listing segment when the -list control argument is given. 3-20 AG92-06 aIm aIm NOTES The only result of invoking the aIm command without control arguments is to generate an object segment A successful assembly produces an object segment and leaves it in the user's working directory. If an entry with that name existed previously in the directory, its access control list (ACL) is saved and given to the new copy. Otherwise. the user is given re access to the segment with ring brackets v,v,v where v is the validation level of the process that is active when the object segment is created. If the user specifies the -list control argument. the aIm command creates a listing segment in the working directory and gives it a name consisting of the entryname portion of the source segment with the suffix list rather than aIm (e.g., a source segment named prt_conv_.alm would have a listing segment named prt_conv_.lisd. The ACL is as described for the object segment except that the user is given rw access to the newly created segment. Previous copies of the object segment and the listing segment are replaced by the new segments created by the compilation. The assembler is serially reusable and sharable. but cannot be reentered once translation has begun; that is, it cannot be interrupted during execution. invoked again. then restarted in its previous invocation. ERROR CONDITIONS Errors arising in the command interface, such as inability to locate the source segment. are reported in the normai Muitics manner. Some conditions can arise within the assembler that are considered malfunctions in the assembler; these are reported by a line printed on the terminal and also in the listing. Any of the above cases is immediately fatal to the translation. Errors detected in the source program, such as undefined symbols, are reported by placing one-letter error flags at the left margin of the erroneous line in the listing segment. Any line so flagged is also printed on the user's terminal, unless the -brief control argument is in effect. Flag letters and their meanings are given below. LI ST OF FLAGS B mnemonic used belongs to obsolete (Honeywell Model 645) processor instruction set. D error in macro definition or macro expansion; more detailed diagnostic for specific error given in listing. E malformed expression in arithmetic field. F error in formation of pseudo-operation operand field. M reference to a multiply defined symbol. 3-21 AG92-o6 aIm aIm N unimplemented or obsolete pseudo-operation. o unrecognized opcode. p phase error; location counter at this statement has changed between passes, possibly due to misuse of org pseudo-operation. R expression produces an S error in the definition of a symbol. T undefined modifier (tag field). U reference to an undefined symbol. 7 digi t 8 or 9 appears in an octal field. .'1'~ "J p"'. The errors B, E, M, 0, P, and U are considered fatal. If any of them occurs, the standard Multics "Translation failed" error message is reported after completion of the translation. ALM LANGUAGE An ALM source program is a sequence of statements separated by newline characters or semicolons. The last statement must be the end pseudo-operation. Fields must be separated by white space, which is defined to include space, tab, new page. and percent characters. A name is a sequence of uppercase and lowercase letters, digits, underscores, and periods. A name must begin with a letter, period, or underscore and cannot be longer than 31 characters. LABELS Each statement can begin with any number of names, each followed immediately by a colon. Any such names are defined as labels, with the current value of the location counter. A label on a pseudo-operation that changes location counters or forces even alignment (such as org or its) might not refer to the expected location. White space is optional. It can appear before, after, or between labels, but not before the colon. OPCODE The first field after any labels is the opcode. It can be any instruction mnemonic or anyone of the pseudo-operations listed later in this description under "Pseudo-operations." The opcode can be omitted, and any labels are still defined. White space can appear before the opcode, but is not required. 3-22 AG92-06 aIm aIm OPERAND Following the opcode, and separated from it by mandatory white space, is the operand field. For instructions, the operand defines the address, pointer register, and tag (modifier) of the instruction. For each pseudo-operation, the operand field is described under "Pseudo-operations" below. The operand field can be omitted in an instruction. Those pseudo-operations that use their operands generally do not permit the operand field to be omitted. NOTES Since the assembler ignores any text following the end of the operand field, this space is commonly used for comments. In those pseudo-operations that do not use the operand field, all text following the opcode is ignored and can be used for comments. Also, a quote character (") in any field introduces a comment that extends to the end of the statement. (The only exceptions are the ace. aci, and bci pseudo-operations, for which the quote character can be used to delimit literal character strings.) The semicolon ends a statement and therefore ends a comment as well. INSTRUCTION OPERANDS The operand field of an instruction can be of several distinct formats. Most common is the direct specification of pointer register. address. and tag (modifier). This consists of three subfields, any of which can be omitted. The first subfield specifies a pointer register by number, user-defined name, or predefined name (prO, prl, pr2, pr3, pr4, pr5, pr6. pr7). The subfield ends with a vertical bar. If the pointer register and vertical bar are omitted, no pointer register is used in the instruction. The second subfield is any arithmetic expression, relocatable or absolute. This is the address part of the instruction, and its default is zero. Arithmetic expressions are defined below under "Arithmetic Expressions." The last subfield is the modifier or tag. It is separated from the preceding subfields by a comma. If the tag subfield and comma are omitted, no instruction modification is used. (This is an all zero modifier.) Valid modifiers are defined below under "Modifiers." Other formats of instruction operands symbolic name defined by temp, tempd, can be used in an arithmetic expression), register is specified explicitly. This form are used to imply pointer registers. If a or temp8 is used in the address subfield (it then pointer register 6 is used if no pointer can have a tag subfield. Similarly, if an external expression is used in the address subfield, then pointer register 4 is implied; this causes a reference through a link. The pointer register sub field may not be specified explicitly. If a modifier subfield is specified, it is taken as part of the external expression; the instruction has an implicit n* modifier to go through the link pair. External expressions are defined below under "External Expressions." 3-23 AG92-06 aIm aIm A literal operand begins with an equal sign followed by a literal expression. The literal expression can be enclosed in parentheses. It has no pointer register but can have a tag subfield. A literal reference normally causes the instruction to refer to a word in a literal pool that contains the value of the literal expression. However, if the modifier du or dl is used, the value of the Hteral is placed directly in the instruction address field. Literal expressions are defined below under "Literal Expressions. " SPECIAL INSTRUCTION FORMATS Certain instructions assembled by the ALM assembler do not follow the standard opcode-operand format as described above. These instructions fall into three basic classes: the repeat instructions, special treatment of the index and pointer register instructions, and EIS instructions. Each of these special cases is described below. REPEAT INSTRUCTIONS The repeat instructions are used to repeat either one or a pair of instructions until specified termination conditions are met There are two basic forms: rpt tally,delta,terml,term2, •.• ,termN generates the machine rpt instruction as described in the Multics Processor Manual. Both tally and delta are absolute arithmetic expressions. The termi specify. the termination conditions as the names of corresponding conditional transfer instructions. This same format can be used with the rpt, rpd, rpda, and rpdb pseudo-operations: rptx ,delta generates the machine rpt instruction with a bit set to indicate that the tally and termination conditions are to be taken from index register O. This format can be used wi th rplx and rpdx. INDEX REGISTER INSTRUCTIONS The opcodes for manipulation of the index registers have the general form opxN. where N specifies the index register to be used in the operation. ALM allows the more general form: opx index,operand which assembles opxN, where index is an absolute arithmetic expression whose value is N. This format can be used for all index register instructions. POINTER REGISTER INSTRUCTIONS As with the index register instructions, the opcodes f or the manipulation of the pointer registers have the general form oprN, where N specifies the pointer register to be used. ALM extends this form to allow: 3-24 AG92-06 aIm aIm opr pointer,operand which assembles as oprN, where N is found as follows: If pointer is a built-in pointer name (prO. prl, etc.), that register is selected; otherwise, pointer must be an absolute arithmetic expression whose value is N. This format can be used with all pointer register instructions except spri. EIS MULT/WORD INSTRUCTIONS An EIS multiword instruction consists of an operation code word. followed by one or more descriptor words. The descriptor words can be assem bled by using the desc pseudo-operations listed under "Pseudo-operations" below. The operation code word has the following general form: eisop (MF1), (MF2) ,keywordl (octexpression) ,keyword2 where: MFl,MF2 are EIS modification fields as described in "EIS Modifiers" below. keyword 1 can be either fill. bool. or mask. octexpression is a logical expression that specifies the bits to be placed in the appropriate parts of the instruction. keyword2 can be round. enablefault. or ascii; these cause single option bits in the instruction to be set. Keywords can appear in any order. before or after an MF field. This format can be used for all Multics EIS multi word instructions. EIS SINGLE-WORD INSTRUCTIONS The Multics processor contains a set of 10 instructions that may be used to alter the contents of an address register. These instructions have the following general form: opcode prloffset,modifier where: pr selects the address register that is to be modified by the instruction. offset is a value whose interpretation is dependent upon the opcode used. 3-25 AG92-06 aIm aIm modifier must be one of the register modifiers (au, ql, xO, etc.). These instructions have two modes of operation depending on the setting of bit 29 in the instruction. If bit 29 is 1, the current contents of the selected address register are used in determining its new contents; if bit 29 is 0, the contents of the word and bit offset portions of the selected address register are assumed to be zero at the start of the instruction (this results in a load operation into the selected address register). ALM normally sets bit 29 to 1, unless the opcode ends in x (e.g., awdx is an awd instruction with bit 29 set to 0). This format can be used with a4bd, a6bd, a9bd, abd, awd, s4bd, s6bd, s9bd, sbd, and swd. EXAMPLES OF INSTRUCTION STATEMENTS Seven examples of instruction statements are shown below. A brief description of each example follows the sample statements. xlab: II Example 1 • II Example 2. II Example 3. lda eax7 p r OI2,": xlab-l reel l[eloek_],* segref adl sys_info,time_delta time delta+l temp lxl0 nexti 1 ink tra goto, I[unwinder_] pr4Igoto,* •• Example 5. ana ada =o777777,du =v36/list_end-l •• Examp 1e 6. a9bd p r 3lO,qu •1 Examp 1e 7 (a) • a9bdx p r 31O,qu II Example 7 (b) • •• Example 4. next i ,,'c Example 1 shows direct specification of address, pointer register, and tag fields. In the second instruction, no pointer register is specified, and the symbol xlab is not external, so no pointer register is used. Example 2 shows an explicit link reference. Indirection is specified for the link, as the item at clock_ (in sys_info) is merely a pointer to the final operand. Example 3 uses an external expression as the operand of the adl instruction. In this particular case, the operand itself is in sys_info. Example 4 uses a stack temporary. Since the word is directly addressable using pr6, the modifier specified is used in the instruction. 3-26 AG92-o6 aIm aIm Example 5 shows a directly specified opera..Tld that refers to an external entity. Unlike segref. it is necessary in this case to specify the pointer register and modifier fields. Example 6 uses two literal operands. value to be stored in the literal pool. Only the second instruction causes the literal In Example 7(a), the values in pr3 are added to the values calculated using the q register (see Section 4 of the Multics Processor Manual, AL39). In Example 7(b), the word and bit offset of pr3 are replaced by those calculated using the q register. ARITHMETIC EXPRESSIONS An arithmetic expression consists of names (other than external names) and decimal numbers joined by the ordinary operators + - * /. You can use parentheses with their normal meaning. An asterisk in an expression, when not used as an operator, has the value of the current location counter. All intermediate and final results of the expression must be absolute or relocatable with respect to a single location counter. A relocatable expression cannot be multiplied or divided. LOGICAL EXPRESSIONS A logical expression is composed of octal constants and absolute symbols combined with the Boolean operators + (OR), - (XOR) , * (AND), and J\ (NOT). You can use parentheses with their normal meaning. EXTERNAL EXPRESSIONS An external expression refers symbolically to some other segment It consists of an external name or explicit link reference, an optional arithmetic expression added or subt!acte.d, and an optional modifier subfield. An external name is one defined by the segref pseudo-operation. An explicit link reference must begin with a segment name enclosed in angle brackets «» and followed by a vertical bar (I). You can optionally follow this by an entryname in square brackets ([]). For example: I [entrynameJ 0,5": An alternative form of external expression must begin with a segment name followed by a dollar sign. You can follow this by an entryname, an arithmetic expression, or a modifier, all of which are optional. For example: segname$ segname$entryname-l segname$+3,5 11/86 3-27 AG92-Q6A aIm aIm A segment name of *text, *link, or *static indicates a reference to this procedure's text, linkage, or static sections. A segment name of *system indicates a reference to the external variable (or common block) entryname, which is managed by the linker. A link pair is constructed for each combination of segment name, entryname, arithmetic expression, and tag that is ref erenced. LITERAL EXPRESSIONS A literal reference causes the instruction to refer to a word in a literal pool that contains the value specified. However, the du and dl modifiers cause the value to be stored directly in the address field of the instruction. The literal pool is allocated in the text section. The various formats of literals are described in the following paragraphs. A decimal literal can floating point. If the A binary scale factor from floating point. positioned to the right be signed. If it contains a decimal point or exponent, it is exponent begins with "d" instead of "e", it is double precision. beginning with "b" indicates fixed point and forces conversion The binary point in a literal with a binary scale factor is of the bit indicated by a decimal integer following the "b". An octal literal begins with an "0" followed by up to 12 octal digits. ASCII literals can occur in two forms. One form begins with a decimal number between 1 and 32 followed by "a" followed by the number of data characters specified by the integer preceding the "~", which can cross statement delimiters. The other form begins with "a" followed by up to four data characters, which can be delimited by the newline character. A GBCD literal begins with "h" followed by up to six data characters. which can be delimited by the newline character. Translation is performed to the 6-bit character code. An ITS (lTP) literal begins with "its" (nitp") followed by a parenthesized list containing the same operands accepted by the its Htp) pseudo-operation. The value is the same as that created by the pseudo-operation. A variable-field literal begins with nv" followed by any number of decimal, octal, and ASCII subfields as in the vfd pseudo-operation. You must enclose it in parentheses if a modifier subfield is to be used. If you use a variable-field literal, octal literal, or fixed-point literal (decimal literals with a "b" binary scale factor) with du or dl modification, then the lower 18 bits of the literal are placed in the address field of the instruction. If you use any other type of literal with du or dl modification. then the upper 18 bits of the literal are placed in the address field of the instruction. 3-28 AG92-06 aIm aIm MODIFIERS These specify indirection, index register address modification, immediate operands, and miscellaneous tally word operations. They can be specified as 2-digit octal numbers (particularly useful for instructions like stba) or symbolically using the mnemonics described here. Simple register modification is specified by using any of the register designators listed below. It causes the contents of the selected register to be added to the effective address. Designators ----------xO xl x2 x3 x4 x5 x6 x7 n au al qu 0 1 2 3 4 5 6 7 none ",1 "I' ic Register ------ndex reg ster 0 ndex reg ster 1 ndex reg ster 2 ndex reg ster 3 ndex reg ster 4 ndex reg ster 5 ndex reg ster 6 ndex register 7 (no mod i f i cat ion) A bits 0-17 A bits 18-35 or 0-35 Q bits 0-17 n ~. .... :+"'-=» ... l~_:2C f\_:2C ."" J:.J or '" J:.J instruction counter 't In addition to the above, any symbol that is not otherwise a valid modifier (e.g., au, ql, x7) may be used as a modifier to designate an index register. Thus, equ lda regc,3 spIO,*regc is equivalent to: Register-then-indirect modification is specified by using any of the register designators followed by an ~~terisk. If the asterisk is usPJ.! alone, it is equivalent to the n* modifier. The register is added to the effective address. then the address and modifier fields of the word addressed are used in determining the final effective address. Indirect cycles continue as long as the indirect words contain an indirect modifier. Indirect-then-register modification is specified by placing an asterisk before anyone of the register designators listed above. 3-29 AG92-Q6 aIm aIm Direct modifiers are du and dl. They cause an immediate operand word to be fabricated from the address field of the instruction. For dl, the 18 address bits are right-justified in the effective operand word; for du they are left-justified. In either case, the remaining 18 bits of the effective operand are filled with O's. Segment addressing modifiers are its and itp; they can only occur in an indirect word pair on a double-word boundary. The addressing modifier its causes the address field of the even word to replace the segment number of the effective address, then continues the indirect cycle with the odd word of the pair. Nearly an indirection in Multics uses ITS pairs. For itp, see the Multics Processor Manual. Tally modifiers i, ci, SC, ser, ad, sd, id, di, idc, and dic control incrementing and decrementing of the address and tally fields in the indirect word. They are difficult to use in Multics because the indirect word and the data must be in the same segment. Fault tag modifiers fl, f2, and f3 cause distinct hardware faults whenever they are encountered. The modifier f2 is reserved for use in the Multics dynamic linking mechanism; the other modifiers result in the signalling of the conditions fau1t_ta~1 and fault_ta~3. EIS MODIFIERS An EIS modifier appears in the first word of an EIS multi word instruction. It affects the interpretation of operand descriptors in subsequent words of the instruction. No check is made by ALM to determine whether the modifier specified is consistent with the operand descriptor specified elsewhere. An EIS modifier consists of one or more subfields separated by commas. Each subfield contains either a keyword as listed below, a register designator, or a logical expression. The values of the subfields are OR'ed together to produce the result. Keyword pr id rl xN Meaning Descriptor contains a pointer register reference. Descriptor is an indirect word pointing to the true descriptor. Descriptor length field names a register containing data length. Descriptor address is offset by the value in index register N (N can be 0 - 7, as above). SEPARATE STATIC OBJECT SEGMENTS If a separate static object segment is desired, a joint pseudo-operation specifying static should exist in the program. LIST OF PSEUDO-OPERATIONS The pseudo-operations are listed below in alphabetical order. Additional pseudo-operations are provided by the macro facility. See "Macros in ALM" (following this list of pseudo-operations) for a further description of their syntax. 3-30 AG92-Q6 ~m ~m acc / string/ ,expression assembles the ASCII string into as many contiguous words as are required (up to 42). The delimiting character (/ above) can be Clny chCiracter other than white space. The quoted string can contain newline and semicolon characters. The length of the string is placed in the first character position in acc format If present, expression defines the length of the string; otherwise, the length is the actual length of the quoted string. If the given string is shorter than the defined length, it is padded on the right with blanks. If it is longer, it will be truncated to the defined length. aci / string/ ,expression is similar to acc, but no length is stored. The first character position contains the first character in aci format ac4 /string/ ,expression is similar to aci, but only the rightmost four bits of each ASCII character are stored into the corresponding character position of a string of 4-bit characters. If the given string is shorter than the defined length. it is padded on the right with zeros. arg operand assem bles exactly like an instruction with a zero opcode. Any form of instruction operand can be used. bci / string/ ,expression is similar to aci, but uses GBCD 6-bit character codes and GBCD blanks for padding. bfs name, expression reserves a block of expression words with name defined as the address of the first word after the block reserved. bool name, expression defines the symbol name with the logical value expression. See the definition of logical expressions above under "Logical Expressions." bss name, expression defines the symbol name as the address of a block of expression words at the current location. The name can be omitted, in which case the storage is still reserved. call routine(arglist) calls out to the procedure routine using the argument list at arglist Both routine and arglist can be any valid instruction operand, including tags. If arglist and the parentheses are omitted, an empty argument list is created. All registers are saved and restored by call. dec numberl,number2•... ,numberN assembles the decimal integers number1, number2, through numberN into consecutive words. 3-31 AG92-06 aIm aIm desc4a address(offset),length desc6a address(offset),length desc9a address(offset),length generates one of the operand descriptors of an EIS multiword instruction. The address is any arithmetic expression. possibly preceded by a pointer register subfield as in an instruction operand. The offset is an absolute arithmetic expression giving the offset (in characters) to the first bit of data. It can be omitted if the parentheses are also omitted. The length is either a built-in index register name (aI, au, ql, xO, etc.) or an absolute arithmetic expression for the data length field of the descriptor. The character size (in bits) is specified as part of the pseudo-operation name. desc4fl address(offset),length,scale desc4ls address(offset),length,scale desc4ns address(offset),length.scale desc4ts address( off set) ,length, scale generates an operand descriptor for a decimal string. The scale is an absolute arithmetic expression for a decimal scaling factor to be applied to the operand. It can be omitted, and is ignored in a floating-point operand. Data format is specified in the pseudo-operation name: desc4fl indicates floating point, desc4ls indicates leading sign fixed point. desc4ns indicates unsigned fixed point, and desc4ts indicates trailing sign fixed point Nine-bit digits can be specified by using desc9fl. desc9ls, desc9ns, and desc9ts. descb address(offset),length generates an operand descriptor for a bit string. Both offset and length are in bits. dup expression duplicates all source statements following the statement containing the dUPe The number of times that the statements are duplicated is equal to the value of the expression. This value must be positive and nonzero. Also, dup statements may not be nested. dupend terminates the range of a dup pseudo-operation. eight (see the even pseudo-operation) end terminates the source segment 3-32 AG92-06 aIm aIm entry namel,name2, ... ,n~~eN generates entry sequences for labels name1, name2, through nameN and makes the externally defined symbols namel, name2, through nameN refer to the entry sequence code rather than directly to the labels. The entry sequence performs such functions as initializing base register pr4 to point to the linkage section, which is necessary to make external symbolic references (link, segref, explicit links). The entry sequence can use (alter) base register pr2, index registers 0 and 7. and the A and Q registers. It requires pr6 and pr7 to be properly set (as they normally are). entrybound places the current value of the location counter in the object_map entrybound field. If more than one such operation is encountered, the last one is effective. (See gate_macros.incl.alm). Setting the entry bound of the object segment's directory entry is still necessary (see hcs_$set_entry_bound). equ name, expression defines the symbol name with the arithmetic value expression. even inserts padding (nop) to a specified word boundary. ext_entry label {/code_labeI} {,size} {,name} makes a probe-able entry sequence for label with a stack frame size of size and with descriptors at label name. If you specify code_label, it is assigned the value of the address of the code associated with the entry sequence. firstref extexpression1 (extexpression2) calls the procedure extexpression1 with the argument pointer extexpression2 the first time (in a process) that this object segment is linked to by an external symbol. If you omit extexpression2 and the parentheses, an empty argument list is supplied. The expressions are any external expressions, including tags. If extexpression2 exists. the actual argument of the trap procedure (ex texpression 1) is a pointer to the link to extexpression2. For example. suppose that the trap procedure is an external pl1 procedure and that the argument is a number in the text section of the program containing the firstref statement, then the firstref statement looks like firstref trap_proc$trap_proc«*text>lfirstref_argument) where firstref_argument is a label on the number and the trap procedure looks iike 11/86 3-33 AG92-06A aIm alm trap_proe: proe(arg_ptr); del arg_ptr ptr; del based_ptr ptr based; del arg fixed fin (35) based; del number fixed bin (35); getlp sets the pointer register pr4 to point to the linkage section. You can use this with segdef to simulate the effect of entry. Ihis operator can use pointer register pr2, index registers 0 and 7, and the A and Q registers. and requires pr6 and pr7 to be set properly. include segmentname inserts the text of the segment segmentname.incl.alrn immediately after this statement The "translator" (trans) search list is used to locate the segment (see the search commands). inhibit off instructs assembler to tum off the interrupt inhibit bit (bit 28) in subsequent instructions. This mode continues until you use the inhibit on pseudo-operation. inhibit on instructs assembler to turn on bit 28 in subsequent instructions. continues until you use the inhibit off pseudo-operation. This mode itp prno.offset. tag generates an lIP pointer referencing the prno pointer register. its segno.offset,tag generates an ITS pointer to the segno segment, word offset , with optional modifier tag. If the current location is not even, a word of padding (nop) is inserted, which causes any labels on the statement to be incorrectly defined. join /text/ name1,name2, ... /link/ name3,name4•... / static / name5,name6, .... appends the location counters name1, name2, etc., to the text section; appends the location counters name3, name4, etc., to the linkage section; and appends the location counters name5, name6, etc., to the static section. Any number of names can appear. Each name must have been previously referred to in a use statement Any location counters not joined are appended to the text section. If you give both link and static in join pseudo-operations, a warning is prin ted on the terminal. 11/86 3-34 AG92-06A aIm aIm link name,extexpression defines the symbol name with the value equal to the offset from lp to the link pair generated for the external expression extexpression. An external expression can include a tag subfield. The name is not an external symbol, so an instruction should refer to this link by ttpr41 name,.". maclist keyword {save} indicates how listing of statements generated by macro expansion is to be done. The following keywords are accepted: off suppresses the listing of macro-generated statements and object code. 11/86 3-34.1 AG92-06A aIm aIm on lists such statements and their associated object code. object lists only the object code . restore reverts the macro listing mode to a previously saved setting. The save argument. if present, saves the current macro listing in a pushdown stack. The default macro listing mode is on. macro name indicates the start of a macro definition. When a macro name is defined. it may then be used as a pseudo-operation to trigger the expansion of the macro. See "Macros in ALM" below for a complete description of the definition and expansion of macros in ALM. mod inserts padding (nop) to an word boundary. name objectname specifies again the object segment name as it appears in the object segment. By default. the storage system name is used. null is ignored. This pseudo-operation is used for comments. oct numberl,number2•...• numberN is like dec, with octal integer constants. odd (see the even pseudo-operation) org expression sets the location counter to the value of the absolute arithmetic expression . The expression can only use symbols previously defined. perprocess_static turns on the object segment's per process static switch. See the description of the run command for an explanation of perprocess static. push expression creates a new stack frame for this procedure. containing expression words. If expression is omitted (the usual case). the frame is just large enough to contain all cells reserved by temp. tempd. and temp8. rem (see the null pseudo-operation) 3-35 AG92-06 aIm aim return is used to return from a procedure that has performed a push. segdef name1,name2, ... ,nameN makes the labels namet name2, through nameN available to the linker for referencing from outside programs, USing the symbolic names name1, name2, through nameN. Such incoming ref erences go directly to the labels name1, name2 through nameN so the segdcf pseudo-operation is usually used for defining external static data. For program entry points, the entry pseudo-operation is usually used. segref segname,name1,name2, ... ,nameN defines the symbols namet name2, through nameN as external symbols referencing the entry points namet name2, through nameN in segment segname. This defines a symbol with an implicit base regi:~~er reference. set name,expression assigns the arithmetic value expression to the symbol name. Its value can be reset in other set statements. short_call routine calls out to routine usi .ig the argument list pointed to by prO. Only pr4 and pr6 are preserved by short_call. short.,return is used to return from a procedure that has not performed a push. sixtyfour (see the even pseudo-operation) source_line numtnum2,num3.num4 {,num5} generates a statement map entry for statement num5 (default 1) of line num2 in file numl that starts after character num3 and has a length of num4. source_seg num1,path {,num2 {,num3} } generates a source map entry for file flum1 with pathname path, a unique id of num2, and a date time contents modified clock value of num3. The unique id and dtcm will be looked up if not specified. temp namel(nl).name2(n2), ... ,nameN(nN) defines the symbols name1, name2, through nameN to reference unique stack temporaries of nt n2. through nN words each. Each n: is an absolute arithmetic expression and can be omitted (the parentheses should also be omitted). The default is one word per namei. 11/87 3-36 AG92-06B aIm aIm temp8 namel(nl),name2(n2) ..... nameN(nN) is similar to temp. except that 8-word units are allocated. each on an 8-word boundary. tempd namel(nl),name2(n2) •... ,nameN(nN) is similar to temp, except that n1 (n2 through nN) double words are allocated, each on a double-word boundary. use name assembles subsequent code into the location counter name. The default location counter is ".text.". 11/87 3-36.1 AG92-06B aIm aIm vfd TILl / expressionl,T2L2/ expression2, ...• TNLN / expressionN is variable format data. Each expressioni is of type Ti and is stored in the next Li bits of storage. As many words are used as required. Individual items can cross word boundaries and exceed 36 bits in length. Type is indicated by the letters "a" (ASCII constant) or "0" (logical expression) or none (arithmetic expression). Regardless of type, the low-order Li bits of data are used, padded if needed on the left The Ti can appear either before or after Li. Restrictions: The total length of the variable format data cannot exceed 128 words. A relocatable expression cannot be stored in a field less than 18 bits long, and it must end on either bit 17 or bit 35 of a word. zero expressionl.expression2 assembles expression 1 into the left 18 bits of a word and expression2 into the right 18 bits. Both subfields default to zero. MACROS IN ALM The ALM macro facility provides a means for defining and using sequences of text to be inserted at various points in an ALM program. Each such sequence of text, called a macro, is defined by the use of the macro pseudo-operation in ALM. A macro definition consists of all text following the line containing the macro pseudo-operation until the character string. &end. The sequence of text is named by the symbol appearing as the operand to the macro pseudo-operation. At any point in a program subsequent to the definition of a macro. the macro name can be used as a pseudo-operation in ALM. Whenever it is so used, AL~1 inserts the text sequence defined as that macro. The macro facility is purely text manipulative. It deals with macro definitions as a continuous stream of text characters interspersed with control sequences. Each control sequence begins with the & character. The control sequence &end terminates the macro definition. When a macro is invoked by using its name as a pseudo-operation, the macro definition is scanned from left to right All text between control sequences is copied, and variable inf ormation is inserted in plaCe of the control sequences. The resulting macro expansion is presented to ALM for assembly. Macros may be given arguments by placing operands in fields corresponding to the operands of a pseudo-operation. These arguments can be substituted into the expanded copy of the macro as specified by various control sequences within the macro definition. Control sequences are also provided to facilitate iteration, conditional text selection. unique symbol generation, and other operations. The macro facility also provides a set of special from the regular ALM pseudo-operations. These the conditional assembly of source lines and the terminal during assembly. The argument syntax of as that of macros. not the expressions and symbols 3-37 pseudo-operations that are distinct special pseudo-operations allow for printing of messages to the user's these pseudo-operations is the same of the ALM assembler. AG92-06 aIm aIm CONTENTS OF A Iv1ACRO The body of a macro (i.e., the text starting on the line following the macro pseudo-operation and ending just before the character string &end) can include any text and control sequences which, when expanded, yield valid ALM source code. The body of a macro can include invocations of other macros and even the definition of other macros. ivlacfo definitions are snown in the assemDlY llsung with their internal line numbers to the left of the ALM source line number. (These internal numbers are used in diagnostics produced by the macro expander.) Macros may be redefined, the later definition replacing the earlier. Macros may also redefine all existing ALM operations and pseudo-operations. An example macro is given below: macro move_a_to_b lda a sta &end b INVOKING A MACRO A macro is invoked by specifying its name as a pseudo-operation. Arguments to the macro can appear in the variable field separated by commas. A comment may follow the argument list. separated from it by white space or a double quote. Arguments to macros that include spaces, tabs. newline characters, commas, or semicolons must be enclosed in matching parentheses. The parentheses are stripped from the argument during macro expansion. The use of parentheses allows macro invocations to extend over several lines. Argument lists may also be continued on successive source lines by following the last macro argument of a line with a comma. Leading white space preceding the continuation of the argument list on the next line is ignored. Code and statements produced by the macro facility are placed in the assembly listing without source line numbers. Symbols used by a macro expansion appear in the cross-reference listing as though they were ref erenced on the line of the macro invocation. The listing of statements produced by macro expansion may be controlled through the use of the maclist pseudo-operation. See the description under "Pseudo-operations" above. RESTRICTIONS Any macro definition that begins in an include file must end in that include file. A macro must be defined before it is expanded. 11 can appear before its definition within another macro definition. but that other macro may not be expanded until the macro it invokes is defined. 3-38 AG92-06 aIm aIm Macros may be invoked in code produced by macro expansions. The depth of such recursion, however, must not exceed the current limit of 100. LIST OF CONTROL SEQUENCES Character substitutions and conditional expansions at the time of macro expansion are effected by the control sequences detailed below. The use of any ampersand followed by any sequence not defined below is noted by ALM as an assembly error. &0, &1, &2 the character & followed immediately' by any positive decimal integer « 100) is replaced, upon expansion. with the corresponding argument passed to the macro (see "Notes" and "Examples" below). The special sequence &0 causes a reference to a unique label at the start of the macro expansion. The label is generated only if the &0 sequence is generated within a macro. &u is expanded to be a unique character string of the form ... 00000, ... 00001, etc., that is different from any other such strings expanded with &u control. &p is expanded to be the same string as the previous' &u expansion. &n is expanded to be the same as the next &u &U is expanded to be a unique character string of the form .. _00000 •.. _00001; however, multiple occurrences of &U within the same macro yield the same string. &(N inOlcates the beginning oi an iteraiion sequence. The text fonowing the &(N and up to but not including the next &) is expanded repeatedly (see "Iteration" below). &i is expanded to the particular element of the iteration set for which the current iteration is being performed (see "Iteration" below). &x is expanded into the decimal integer corresponding to the relative posltlon of the particular element of the iteration set over which the current iteration is being performed. &AN is expanded to be the Nth argument following the -ag or -arguments control argument to the aIm command. 3-39 AG92-06 aIm aIm &K is expanded as a decimal number equal to the number of arguments in the curren t macro invocation. &k is expanded as a decimal number equal to the number of elements in the current iteration set ""'~.1'hl .1..1.... is expanded as a decimal number equal to the length in characters of the Nth argument in the current macro invocation. && is expanded to a single & character. macro expansions. This facilitates macro definitions within &FN expands to a string constructed by concatenating all arguments to the macro invocation, from the Nth onward, separated by commas. If N is not given, 1 is assumed. &FqN or &FQN is similar to &FN, except that each argument is enclosed in parentheses as it is concatenated to the expanded string. This control sequence should be used when sublists of macro arguments are to· be passed to other macros and there is a possibility that some of these arguments may contain white space, newline characters, etc. &fN is similar to &FN, except that the elements of the current iteration set are concatenated. &fqN or &fQN is similar to &FqN and &FQN, except that the elements of the current iteration set are enclosed in parentheses. &RM,N is used to cause iteration over the arguments in a macro invocation, as opposed to the iteration elements of a single macro argument The use of &R affects the operation of the next &( control sequence. The M is a decimal number equal to the number of the first argument to be selected; N is a decimal number equal to the number of the last argument to be selected. If N is missing or zero, it is assumed to be equal to the number of arguments in the macro invocation. If M is missing or zero, it is assumed to be 1 (see "Notes" below). 3-40 AG92-06 aIm aIm &[ marks the start of a selection group. The text following the & [ and up to but not including the matching &J is expanded conditionally. The elements of a selection group are separated by the control sequence & . Each element can contain other selection groups to a nesting depth of 10. When a macro is expanded, only one element of a selection group is used. This element is chosen by a control sequence preceding the & [ control sequence. &sN selects the Nth element of the following selection group. All expanded text between the &s and & [ control sequences is interpreted as the decimal number N. If N is zero or greater than the number of elements in the selection group, no element is selected. &=c1.c2 all expanded text between the &= and the next & [ control sequence is broken in to two character strings. If no comma is found in the expanded text, c2 is taken to be a null string. If the two strings are equal, by character string comparison, the first element of the following selection group is used. Otherwise, the second element, if present, is used. &A=c1,c2 the &A= control sequence is identical to the &= control sequence, except that the first element is selected if the strings are unequal, and the second, if present, is selected if they are equal. &>nl,n2 & =nl,n2 &<=n1,n2 these control sequences are similar to the &= and &A= control sequences, except that the expanded text between this control sequence and the next & [ control sequence is interpreted as two decimal integers. If no comma is found, n2 is taken to be zero. An arithmetic comparison of the numbers is performed, as specified by the particular control sequence used. A result of true causes the first element of the following selection group to be used. A result of false causes the second element, if present, to be used. &end signifies the end of the macro definition. The statement contaInmg the &end control sequence is not part of the macro body, and hence, is not included as part of the macro definition. NOTES Decimal numbers produced by &K, &k, and &x are generated with no leading blanks or zeros. The number zero is generated as the single digit O. 3-41 AG92-06 aIm , aIm Numeric arguments to &N, &(N, &FN. &fN, &FqN, &fqN, and &AN can be comprised of from zero to three digits. These numbers must appear as such in the unexpanded macro definition. If numeric text is to follow one of the above control sequences, all three digits of N must be supplied. The numbers used by &RM.N. as well as the strings and numbers used by the relational and selection control sequences can be of any length. They appear in the expanded text and need not necessarily be in the macro definition. These expanded strings and numbers are, of course, not placed in the final macro expansion being generated. If a given macro argument is not specified in a particular invocation of that macro, a null character string is used for that argument during macro expansion. ITERATION The macro facility provides the ability to map the expansion of a subset of a macro definition over a set of elements, expanding that part of the definition repeatedly, selectively substituting each element of the iteration set in turn. By means of this technique, lists may be processed. An iteration set consists of elements separated by commas. It has the same syntax as the argument list of a macro invocation, including conventions on the use of parentheses for quoting and continuation via the trailing comma. Two types of iteration sets may be referenced in a macro expansion: The argument list to a macro invocation itself may be used as an iteration set, in which case the arguments of the macro invocation are the elements. This type of iteration set is specified by means of the &R control sequence. Any argument to a macro invocation may be used as an iteration set. if it, internally. has the same syntax as an argument list to a macro invocation. This type of iteration set is specified when &R is not used. The text between the sequences &( and &) is expanded once for each element in the iteration set, in left to right order. If the second form of iteration set is used, the number of the argument to the macro invocation may appear (one to three digits, no digits are mapped into 1) immediately after the &( sequence. Any occurrence of the sequence &i between the sequences &( and &) is replaced by the current element of the iteration set. The sequence &x is replaced by the decimal number of the relative position of that element in the iteration set (not the argument number, in the first type of iteration set). Iterations may not be nested. Any iteration that starts in an element of a selection group must end in that element of a selection group. No iteration may end in any element of a selection group unless it started in that element of that selection group. 3-42 AG92-Q6 aIm aIm MACRO FACILITY PSEUDO-OPERATIONS The macro facility provides a set of pseudo-operations in addition to the macro pseudo-operation already described. These pseudo-operations are different from the other pseudo-operations provided by the assembler insofar as the syntax of their arguments. which is the syntax of macro invocation arguments. with all quoting and continuation conventions of them, and not the syntax of other pseudo-operation arguments to the assembler. The use of these pseudo-operations. like all other ALM pseudo-operations. is not limited to code produced by macro expansion. They can be placed anywhere in source segments and include files. as well as in macro code. but the conditional pseudo-operations can not be nested. warn prints out its first argument on the user's terminal, preceded by the string "ALM assembly:" and followed by a newline character. This argument, without the prefix. is also placed in the program listing. ife the character strings that are the first and second arguments to ife are compared. If they are the same character string, all assembler statements between the one containing the end string ifend in any the string ifend is none of these lines of the argument list to ife, and the next one containing the context at all are assembled. No part of the line containing assembled. If the first and second arguments are not equal, are assembled. ine the same as ife, but assembly of the text up to ifend proceeds only if the first two arguments are not equal by character string comparison. ifint the first argument to the ifint pseudo-operation is inspected to decimal integer. If so, all assembler statements between the end of the arglL'llent list to ifint and the next one containing any context at all are "If the first argument to ifint is not a of these lines are assembled. see if it is a valid one containing the the string ifend in valid integer, none inint the same as ifint. but assembly of the text up to ifend proceeds only if the first argument is not a valid decimal integer. 3-43 AG92-06 aIm aIm ifarg all of the arguments to the aIm command following the -ag or -arguments control argument are inspected, and compared with the first argument to ifarg. If any of these command arguments compare equal, by character string comparison, to the first argument to ifarg, all assembler statements between the one containing the end of the argument list to ifarg and the first one containing the string ifend in any context at all are assembled. No part of the line containing the ifend is assembled. If the first argument to ifarg does not appear among the arguments following -ag or -arguments; none of these line.s are a.~sembled. inarg the same as ifarg, but assembly of the text up to ifend proceeds only if the first argument to inarg is not found among the arguments to the aIm command following -ag or -arguments. In all of the conditional constructs above, the key string, ifend, must appear in the same source segment or macro expansion as the statement containing the conditional pseudo-operation. If the ifend key string appears in the ifend_exit string, and the entire construct appears in a macro expansion, and the predicate of the conditional construct is met (Le.. the statements are being assembled, not skipped), the assembler ceases to take input from that macro expansion, as though the last statement in that macro expansion had been assembled. EXAMPLES The following macro definitions show typical expansions: macro load ld&l &2 Send might be used as follows: load xO,temp ldxO temp load a, (spI3,)':) lda spI3,)': or: The use of parentheses in the second example causes the comma to be ignored as a parameter delimiter. The macro definition: &U macro lda tpl sta sta &end test &1 &U iast minus &2 might be used as follows: 3-44 AG92-06 aIm aIm test a,b lda tpl sta .• _00000: sta a _00000 last_minus b The following example shows how iteration is used. The macro definition: macro vfd &R& ( table 18/&i,18/&0 &) & end might be used as follows: e 1: table 4,6,8, 10 vfd vfd vfd vfd 18/4,18/e1 18/6,18/el 18/8,18/e1 18/10,18/el The following example shows how conditional expansion can be used. def ini tion: macro lda ife aos ifend Send The macro meter &1 &2,on meterword,al might be used as follows: meter foo,on lda aos The following macro shows how &x &(3 mi~it foo meterword,al be used. The macro definition: macro eppbp spribp cal1m &i &2+&x 1:2 eaq 11 s staq call Send 36 &2 &1 (&2) &) 2~"&x-2 might be used as follows: ca 11m sys,arg, (=1, (=14aError from Ad.» 3-45 AG92-{)6 aIm aIm yielding: eppbp spribp eppbp spribp =1 arg+ 1)'(2 =14aError from "'d. arg+2,'c2 eaq 1 1 _ 2":4- 2 I I;) staq ca 11 ?!.. ,JU arg sys (arg) The following macro definition shows how conditional expansion might be used: macro &R& (&=&x, 1&[ tab9 vfd &;,&]o9/&i&) &end This macro might be invoked as follows: tab9 16,42,13,36,67 vfa o9/16,o9/42,o9/i3,o9/36,o9/67 expanding to: The following example shows how macros may be defined by macros. and used to powerful effect These macros allow a call like a PL/I call to be generated, with descriptors. The following macro is invoked to declare variables by specifying their address, data type, and precision: macro macro eppO epp1 &&end declare dc 1 & 1 &2 =v1/1,6/&3, 17/0, 12/&4 &end This macro may be invoked as follows: or: declare count,buffer+2,fixed,17 declare progname, (1 p Ixli nk, :':) , char, 32 These macro invocations cause the following macro definitions to be produced: 3-46 AG92-o6 aIm aIm macro eppO eppl &end dcl_count buffer+2 =vl/l,6/fixed, 17/0, 12/17 macro eppO eppl &end dcl progname I 1P xli nk, ~': =v1/1,6/char, 17/0, 12/32 Assume that at some point in the assembly the statements: equ equ char,21 fixed,l defining the PL/I descriptor types for these data types appear. The following macro definition, when invoked, generates a full descriptors. Assume that the statement: PL/I call with tempd arg 1 (16) appears at some point in the program. &R2& ( macro dcl_&i spriO spri1 gca 11 arg 1+21:&x arg 1+2":&K - 2+2":&x &) 1daq staq ca 11 &end =v18/2*&K-2, 18/0, 18/2*&K-2, 18/4 argl &1 (arg i) \Vhen the following macro invocation is issued: gcal1 program,count,progname the following expansion is immediately produced: dcl count spriO argl+2*1 spr i 1 argl+2"c3-2+2"c1 dcl_progname spriO argl+2*3-2 spril argl+2*3-2+2*2 Idaq staq call =v18/2*3-2, 18/0,18/2*3-2, 18/4 argl program (argl) 3-47 AG92-D6 aIm This is further expanded when the dcl_count and dcl_progname macros are expanded to: eppO epp1 spriO spr i 1 eppO buffer+2 =vl/1,6/fixed, 17/0, 12/17 arg 1+21(1 arg 1+2'':3-2+2* 1 epp1 spriO spr i 1 1daq staq =v1/1,6/char, 17/0, 12/32 arg1+2*2 arg 1+2'''3-2+2*2 =v18/2*3-2,18/0, 18/2*3-2, 18/4 arg1 ca 11 program (arg 1) 1p Ixli nk , ,,: which is precisely the code required for a full PL/I call. Name: alm_abs, aa SYNTAX AS A COMMAND aa paths {-a1m_arg} {-dp_args} {-contro1_args} FUNCTION submits an absentee request to perform ALM assemblies. The absentee process for which alm_abs submits a request assembles the segments named and sends to the printer and deletes each listing segment if it exists. If you don't give -output_file, an output segment (path.absout) is created in your working directory. If you supply more than one path, the first is used. If the segment to be assembled cannot be found, no absentee request is submitted. ARGUMENTS paths are pathnames of segments to be assembled. alm_arg can be the -list control argument to the aIm command. dp_args can be one or more control arguments (except -delete) accepted by the dprint command. 3-48 AG92--()6 CONTROL ARGUMENTS -hold specifies that alm_abs should not dprint or delete the listing segment. -limit N, -li N places a limit on the CPU time used by the absentee process. The must be a positive decimal integer giving the limit in seconds. The is defined by your site for each queue. An upper limit is defined for each queue on each shift Jobs exceeding the upper limit for the are deferred to a shift with a higher limit parameter N default limit by your site current shift -output_file path, -of path specifies that absentee output is to go to a segment with a pathname of path. -queue N, -q N is the priority queue of the request The default queue is defined by your system administrator. (See "Notes.") NOTES Control arguments and segment pathnames can be mixed freely and can appear anywhere on the command line after the command. All control arguments apply to all segment pathnames. If an unrecognizable control argument is given, the absentee request is not submitted. Unpredictable results can occur if two absentee requests are submitted that could simultaneously attempt to assemble the same segment or write into the same absout segment. When performing several assemblies, it is more efficient to give several segment pathnames in one command rather than several commands. With one command. only one process is set up. The links that need to be snapped when setting up a process and when invoking the assembler need be snapped only once. If the -queue control argument is not specified, the request is submitted into the default absentee priority queue defined by the site and. if requested (via -list), the listing files are dprinted in the default queue of the request type specified on the command line (via dp_args). (If no request type is specified, the "printer" request type is used.) If requested (via -l1St} when the -queue conrrol are dprinted in the same queue as is used for type specified for dprinting (via dp_args) does not (i.e.. the lowest priority) queue available for the iSSUed. 3-49 argument is specified, the iisting files the absentee request. If the request have that queue, the highest-numbered request type is used and a warning is AG92-06 and answer Name: and SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION FUNCTION returns true if all the tf_args are equal to true, otherwise it returns false. If there are no tf_args, it returns the and-identity "true". If any of the tf_args has a value other than true or false, an error message is printed. EXAMPLES The command line and Cst -ssw ([segs **])] returns true if all segments in the current working directory have their safety switches on, or if there are no segments in the working directory. The active function [and [equal &rl a] [equal &r2 b]] inside an exec_com returns true only if the first. argument to ec is "a" and the second is "b". Name: answer SYNTAX AS A COMMAND answer STR {-control_args} command_l ine FUNCTION provides preset answers to questions asked by another command. 3-50 AG92-o6 answer answer ARGUMENTS STR is the desired answer to any question. If the answer is more. than one word, it must be enclosed in quotes. If STR is -query, the question is passed on to the user. The -query control argument is the only one that can be used in place of STR. command_line is any Multics command line. It can contain any number of separate arguments (Le.. have spaces within it) and need not be enclosed in quotes. CONTROL ARGUMENTS -brief, -bf suppresses printing (on the user's terminal) of both the question and the answer. -call STR evaluates the active function string STR to obtain the next answer in a sequence. STR must be quoted if it contains command language characters. The surrounding brackets must be omitted, as in "segs *.pll". The return value "true" is translated to "yes". and "false" to "no". All other return values are passed as is. -match STR answers only questions whose text matches STR. If STR is surrounded by slashes (/). it is interpreted as a qedx regular expression. Otherwise, answer tests whether STR is literally contained in the text of the question. Multiple occurrences of -match and -exclude are allowed (see Notes below). They apply to the entire command line. -exclude STR, -ex STR passes on, to the user or other handler, questions whose text matches STR. If STR is surrounded by slashes (/). it is interpreted as a qedx regular expression. Otherwise, answer tests whether STR is literally contained in the text of the question, Multiple occurrences of -match and -exclude are allowed (see Notes below). They apply to the entire command line. -query skips the next answer in a sequence, passing on the question to the user. answer is read from the user_io I/O switch. The -then SIR supplies the next answer in a sequence. -times N gives the previous answer (STR, -then STR. or -query) N times only, where N is an integer). 3-51 AG92-o6 answer answer NOTES Answer provides preset responses to questions by establishing an on unit for the condition command_question, and then executing the designated command. If the designated command calls the command_query_ subroutine to ask a question, the on unit is invoked to supply the answer. The on unit is reverted when the answer command returns to command level. See the Programmer's Reference Manual for a discussion of the command_question condition. If a question is asked that requires a yes or no answer, and the preset answer is neither "yes" nor "no", the on unit is not invoked. The last answer specified is issued as many times as necessary, unless followed by the -times N control argument The -match and -exclude control arguments are applied in the order specified. Each -match causes a given question to be answered if it matches STR, each -exclude causes it to be passed on if it matches STR. A question that has been excluded by -exclude is reconsidered if it matches a -match later in the command line. For example, the command line answer yes -match /fortran/ -exclude /fortran_io/ -match /Afortran_iol answers questions containing the string Ufortran". except that it does not answer questions containing "fortran_io", except that it DOES answer questions BEGINNING with "fortran_io". EXAMPLES To delete the tesC_dir directory without being interrogated by the delete_dir command, type: answer yes -bf delete_dir test_dir To automatically see the first three blocks of an info segment named fred.info and then be interrogated about seeing any more blocks, type: answer yes -times 2 help fred The help command prints the first block, then prints another block every time the user answers yes. In this example, the first three blocks are printed before the user is interrogated. Sequences of answers are especially useful in exec_corns and absentee jobs. To supply the sequence of answers "yes, no, no, yes", type: answer yes -then no -times 2 -then yes command_l ine To supply the sequence of answers "no, ask the user twice, yes, no", type: answer no -query -times 2 -then yes -then no command_line 3-52 AG92-Q6 answer apl To supply the answer "start_seg" once and call the temp_seg active function times, type: successiv~ answer start_seg -call "temp_seg args" command_line To substitute the query "More?" for the one printed by help, type: answer -call "query More?" -bf help fo Name: apI, v2apI SYNTAX AS A COMMAND FUNCTION invokes the APL interpreter. optionally loading a saved workspace. ARGUMENTS workspace...:.id is the path name of a saved workspace to be loade-d. The default is to user's continue workspace, if any, otherwise to provide a clear wQrkspa.ce. CONTROL ARGUMENTS -briei_errors, -bfe prints short error messages. (Default) -check, -ck causes a compatibility error to occur if a monadic transpose of rank greater than 2 or a residue or encode with a negative left argument is encountered, (The definition of these cases in Version 2 APL is different from Version 1.) -debug, -db calls the listener (cu_$cI) upon system errors. This puts you at a new command level. The default is to remain in APL. This control argument is intended for debugging apl itself. -lonK-errors, -lge prints long error messages. The short form of the message is printed, followed by a more detailed explanation of the error. -no_quit_handler, -nqh ignores the quit condition. (Default: to trap all quits within APL) 3-53 AG92-Q6 apl archive -temp_dir path. -td path changes the directory that is used to hold the temporary segments that contain the active workspace to path. (Default: to use the process directory) -terminal_type STR, -ttp STR specifies the kind of terminal being used. Possible values of STR are: 1050 1030 ASCII TELERAYll TYPEPAIRED 2741 BITPAIRED LA36 TEK4015 TN300 ARDS TEK4013 This control argument specifies which one of several character translation tables is to be used by APL when reading or writing to the terminal. Since there are several different kinds of APL terminals, each incompatible with the rest, it is important that the correct table be used. Specifying a terminal type to APL changes the terminal type only as long as APL is active. The default depends on the user's existing terminal type (see the set_tty command). These terminal types default to the same APL terminal type: 1050. 2741. C0RR2741. ARDS, TN3oo, TEK4013, TEK4015, ASCII, LA36. TELERA Yl1. All other terminal types default to ASCII. The APL terminal types BITPAIRED and TYPEPAIRED are generic terminal types that can be used with any APL/ ASCII terminal of the appropriate type. C0RR2741 -user_number N sets the APL user number (returned by some APL functions) to N. (Default: 100) NOTES This command invokes the Version 2 APL interpreter, which replaces the obsolete Version 1 APL interpreter. For a complete description of the APL language, terminal conventions, and directions for converting Version 1 APL workspaces, refer to Multics APL (AK95). Name: archive, ac SYNTAX AS A COMMAND ac operation archive_path paths FUNCTION combines an arbitrary number of separate segments into one single segment. The constituent segments that comprise the archive are called components of the archive segment. For more information on how archives can be sorted and reordered, see the archive_sort and reorder_archive commands. 3-54 AG92-o6 archive archive ARGUMENTS operation is one of the functions listed below under "List of Operations." archive_path is the pathname of the archive segment to be created or used. The archive suffix is added if you do not supply it. If the archive segment does not exist for replace and append operations, it is created. The star convention can be used with extraction and table of contents operations. paths are the components to be operated on by table of contents and delete operations. The star and equal conventions cannot be used. For append, replace, update and extract operations, each path specifies the pathname of a segment corresponding to a component whose name cannot be used. (Some operations may not require any path arguments; refer to the specific operation for details.) LIST OF OPERATIONS The archive command performs a variety of operations that you can employ to create new archive segments and to maintain existing ones. The operations are: Table of Contents Operation t print the entire table of contents if no components are named by the path arguments; otherwise print information about the named components only. Title and column headings are printed at the top. t1 print the table of contents in long form; information for each component. operates like t, printing more tb print the table of contents, briefly; operates like t, except that the title and column headings are suppressed. tlb print the table of contents in long form, briefly; operates like tl, except that the title and column headings are suppressed. Append Operation a append named components to the archive segment If a named component is already in the archive, a diagnostic is issued and the component is not replaced. At least one component must be named by the path arguments. 3-55 AG92-06 archive archive ad append and delete; operates like a and then deletes all segments that have been appended to the archive. adf append and force deletion; operates like a and then forces deletion of all segments that have been appended to the archive. ca copy and append; operates like a, appending components to a copy of the new archive segment created in your working directory. cad copy, append, and delete; operates like ad, appending components to a copy of the archive segment and deleting the appended segments. cadf copy, append, and foree deletion; operates like adf, appending components to a copy of the archive segment and forcibly deleting the segments requested for appending. Replace Operation r replace components In, or add components to, the archive segment. When no components are named in the command line, all components of the archive for which segments by the same name are found in your working directory are replaced. When a component is named, it is either replaced or added. rd replace and delete; operates like r, replacing or adding components, then deletes all segments that have been replaced or added. rdf replace and f oree deletion; operates like rand f orees deletion of all replaced or added segments. cr copy and replace; operates like r, placing an updated copy of the archive segment in your working directory instead of changing the original archive segment. crd copy, replace and delete; operates like rd, placing an updated copy of the archive segment in your working directory. crdf copy. replace. and force deletion; operates like rdf, placing an updated copy of the archive segment in your working directory. 3-56 AG92-06 archive archive Update Operation u update; operates like r except that it replaces only those components for which the corresponding segment has a date-time modified later than that associated with the component in the archive. ud update and delete; operates like u and deletes all updated segments after the archive has been updated. udf update and force deletion; operates like u and forces deletion of all updated segments. eu copy and update; operates like u, placing an updated copy of the archive segment in your working directory. cud copy, update. and delete; operates like ud, placing an updated copy of the archive segment in your working directory. cudf copy, update, and delete force; operates like udf, placing an updated copy of the archive segment in your working directory. Deiete Operation d delete from the archive those components named by the path arguments. cd copy and delete; operates like d, placing an updated copy of the archive segment in the working directory. Extract Operation x extract from the archive those components named by the path arguments, placing them in segments in the storage system. The directory where a segment is placed is the dir€Ctory portion of the path argument. The access mode stored with the archive component is placed on the segment for the user performing extraction. If no component names are given, all components are extracted and placed in segments in the working directory. The archive segment is not modified. xd extract and delete; operates like x but deletes the component from the archive if it is extracted successfully. 3-57 AG92-06 archive archive xdf extract, delete force and delete component; operates like xd, forcing deletion of any duplicate names or segments found where the new segment is to be created. xf extract and delete force; operates like x, forcing deletion of any duplicate names or segments found where the new segment is to be created. NOTES The process of placing segments in an archive is particularly useful as a means of eliminating wasted space that occurs when individual segments do not occupy complete pages of storage. Archiving is also convenient as a means of packaging sets of related segments; it is used this way when interfacing with the Multics binder (see the bind command description in this document). The table of contents operation and the extract operation use the existing contents of an archive segment; the other operations change the contents of an archive segment A new archive segment can be created with either the append or replace operation. In each of the operations that add to or replace components of the archive, the original segment is copied and the copy is written into the archive, leaving the original segment untouched unless deletion is specified as part of the operation. Use of the various operations is illustrated in the "Examples" at the end of this description. The table of contents operation is used to list the contents of an archive segment. It can be made to print information in long or brief form with or without column headings. The append operation is used to add components to the archive segment and to create new archive segments. When adding to an existing archive, if a component of the same name as the segment requested for appending is already present in the archive segment, a diagnostic message is printed on your terminal and the segment is not appended. When several segments are requested for appending, only those segments whose names do not match existing components are added to the archive segment. The replace operation is similar to the append operation in that it can add components to the archive segment, and therefore it is also used to create new archive segments. However. unlike the append operation. if a component of the same name as the segment requested for replacing is already present in the archive segment, that component is overwritten with the contents of the segment When several segments are requested for replacing. those segments whose names do not match existing components are added to the archive segment. as in the append operation. The update operation replaces existing components only if the date-time modified of a segment requested for updating is later than that of the corresponding component currently in the archive segment. When a segment whose name does not match an existing component of the archive segment is requested for updating. it is not added to the archive segment. 3-58 AG92-06 archive archive The delete operation is used only to delete components from archive segments. It cannot delete segments from the storage system and is not analogous to the deletion feature described below. The extract operation is used to create copies of archive components elsewhere in the storage system. The extract operation performs a function opposite to the append operation. In addition to the operations described above. there are two features. copying and deletion. that can be combined with certain operations to modify what they do. Since copying and deletion are features and not operations. they cannot stand alone. but must always be combined with those operations that permit their use. The deletion feature is distinct from the delete operation. The copying feature can be combined with the append. replace. update. and delete operations. Since an archive segment can be located anywhere in the storage system. it is occasionally convenient to move the segment during the maintenance process or to modify the original segment while temporarily retaining an unmodified version. When the copying feature is used, the original archive segment is copied from its location in the storage system. updated. and placed in your working directory. The deletion feature can be combined with the append. replace. and update operations to delete segments from the storage system after they have been added to or replaced in an archive segment. The deletion can be forced to bypass the system's safety function. i.e.. you are not asked whether to delete a protected segment before the deletion is performed. (This is analogous to the operation of the delete -force command.) Nothing is deleted until after the archive segment has been successfully updated. Deletion of segments (deletion feature) is not to be confused with deletion of components from archive segments. The delete operation is a stand-alone function of the archive command that operates only on components of archive segments, deleting them from the archive. The deletion feature, on the other hand, performs deletions only when combined with an operation of the archive command, and then deletes only segments from the storage system after copies of ihose segments have been added to, or used to update. archive segments. The archive command can operate in two ways: if no components are named on the command line, the requested operation is performed on all existing components of the archive segment; if components are named on the command line, the operation is performed only on the named components. The star convention can be used in the archive segment pathname during extract and table of contents operations; it cannot be used during append, replace. update. and delete operations. No commands other than archive. archive_table. archive_sort, and reorder_archive should be used to manipulate the contents of an archive segment; using a text editor or other command might result in unspecified behavior during subsequent manipulations of that archive segment 3-59 AG92-()6 archive archive Each component of an archive segment retains certain attributes of the segment from which it was copied. These consist of one name, the effective mode of the user who placed the component in the archive, the date-time last modified, the bit count, and the date-time placed in the archive. When a component is extracted from an archive segment and placed in the storage system, the new segment is given the name of the component, the bit count of the component, and the mode associated with the component for the user performing the extraction. The date-time-modified value of a component has a precIsIon of one tenth of a minute. This means that a copy of a component modified less than a tenth of a minute after the archived copy is not updated. Users who use exec_coms to update archives should be aware of this limitation. Date-time values are stored in ASCII without a time zone. The time is expressed relative to the time zone set for the process that placed the component in the archive. If the time zone set during the archive update operation differs from the zone set when the component was first archived, the update will not be performed correctly. This can cause a component to be updated needlessly, or prevent a component from being updated even though changes were made to its corresponding segment The time zone of a process can be changed via the set_time_zone command. The archive command maintains the order of components within an archive segment When new components are added. they are placed at the end. The archive_sort or reorder_archive commands can be used to change the order of components in an archive segment The archive command cannot be used recursively. You are asked a question if the command detects an attempt to use the archive command prior to the completion of its last operation. Because the replacement and deletion operations are not indivisible. it is possible for them to be stopped before completion and after the original segment has been truncated. This can happen. for example. if one gets a record quota overflow. When this situation occurs, a message is printed informing you what has happened. In this case, the only good copy of the updated archive segment is contained in the process directory. Archive segments can be placed as components inside other archive preserving their identity as archives, and can later be extracted intact segments, When the archive command detects an internal inconsistency, it prints a message and stops the requested operation. For table of contents and extraction operations, it will have already completed requests for those components appearing before the place where the format error is detected. For segment deletions after replacement requests, if the specified component name is a link to a segment, the segment linked to is deleted. The link is not unlinked. 3-60 AG92-Q6 archive archive The archive command observes segment protection by interrogating you when (unforced) deletion is requested of a segment to which you do not have write permission. If you can obtain write permission (i.e.. has modify permission on the superior directory) and replies that the segment should be deleted. the segment is deleted. The archive command refers to the archive segment by full pathname (rather than only the entryname portion) in all printed messages. EXAMPLES Assume that you have several short segments and wants to consolidate them to save space. The working directory, >udd>Proj ect_i d>d i r _one, might initially look like the following: 1 i st Segments = 5, Lengths = 5· eps i lon delta gamma beta alpha rw rw rw rw rw You create an archive segment (using the append operation) containing four of the five segments. archive a greek alpha beta gamma delta archive: Creating >udd>Project_id>dir_one>greek.archive The working directory then has one more segment (the archive segment), and a table of contents of the new archive segment shows the four components. 1: i:I ...... .., ~ Segments = 6, Lengths = 6. rw rw rw rw rw rw greek.archive eps i lon delta gamma beta alpha 3-61 AG92-06 archive archive archive tl greek >udd>Project_id>dir_one>greek.archive updated name alpha beta gamma del ta 09/12/82 09/12/82 09/12/82 09/12/82 mode 1435.0 1435.0 1435.0 1435.0 rw rw rw rw modified 09/12/82 09/12/82 09/12/82 09/12/82 1434.2 1434.2 1434.2 1434.2 length 441 257 694 109 After changing the segment delta, you replace it in the archive segment and appends (using the replace operation) the segment epsilon to the archive segment You also delete the component gamma. archive r greek delta epsilon archive: epsilon appended to >udd>Project_id>dir_one>greek.archive archive d greek gamma A table of contents new shows a different set of components: archive t greek >udd>Project_id>dir~one>greek.archive updated 09/12/82 09/12/82 09/12/82 09/12/82 name 1435.0 1435.0 1437.5 1437.5 alpha beta delta eps i lon You later replace the component alpha with an updated copy and deletes the storage system segment alpha, causing the updated column of a table of contents to change and a list of the working directory to show one less segment. archive rd greek alpha archive t greek >udd>Project_id>dir_one>greek.archive updated 09/12/82 09/12/82 09/12/82 09/12/82 name 1641.5 1435.0 1437.5 1437.5 alpha beta delta eps i lon 3-62 AG92-06 archive archive 1 is t Segments = 5, Lengths = 5· greek.archive eps i 10n delta gamma beta rw rw rw rw rw In another directory, >udd>Project_id>dir_two, which contains a more recent version of the segment alpha, you copy and update the archive segment, causing the component alpha to be replaced and the updated archive segment to be placed in the working directory. archive cu greek archive: Copying >udd>Project id>dir one>greek.archive archive: alpha updated in >udd>Proje~t_id>dir_two>greek.archive 1 is t Segments rw rw = 2, Lengths = 2. greek.archive alpha archive t greek >udd>Project_id>dir_two>greek.archive updated 09/12/82 09/12/82 09/12/82 09/12/82 name 1648.3 1435.0 1437.5 i437.5 alpha beta delta eps i 10n ac t greek >udd>Project_id>dir_one>greek.archive updated 09/12/82 09/12/82 09/12/82 09/12/82 name 1641 .5 1435.0 1437.5 1437.5 alpha beta delta eps i lon 3-63 AG92-()6 archive Notice that the entry in the updated column for the component alpha differs in the two tables of contents. Finally, you extract two components into the new working directory, presumably to work on them. archive x greek beta delta 1 i st Segments"" 4, Lengths rw rw rw rw - I. At. delta beta greek.archive alpha Name: archive_sort, as SYNTAX AS A COMMAND as paths FUNCTION sorts the components of an archive segment. The components are sorted into ascending order by name using the standard ASCII collating sequence. The original archive segment is replaced by the sorted archive. For more information on archives and reordering them, see the archive and the reorder_archive commands. ARGUMENTS paths are the pathnames of the archive segments to be sorted. You need not supply the archive suffix. NOTES There can be no more than 1000 components in an archive segment that is to be sorted. Storage system errors encountered while attempting to move the temporary sorted copy of the archive segment back into your original segment result in diagnostic messages and preservation of the sorted copy in your process directory. If the original archive segment is protected, you are interrogated to determine whether it should be overwri tten. 3-64 AG92-06 Name: archive_table, act SYNTAX AS A COMMAND act archive_path {starnames} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [act archive_path {starnames} {-control_args}] FUNCTION returns the names of specified archive components in a specified archive segment. As a command, archive_table prints one component name per line. M an active function, it returns names individually requoted and separated by single spaces. ARGUMENTS archive_path is the pathname of an archive segment, with or without the archive suffix. The star convention is not allowed. starnames are optional component names to be matched against names of archive components.. The star convention is allowed. CONTROL. ARGUMENTS -absolute_pathname, -absp causes component names to be returned as absolute pathnames, of the form ARCH I VE_D I R>ARCH I VE_NAME: : COMPONENT_NAME, rather than just the component names. -bit_count, -bc returns the bit count of the selected components. -component_name, -cnm returns only the component name portion of the selected components. It has no effect if -no_name is selected. (Default) returns the date-time-contents-modified of last updated in the archive. when the component was -date_time_updated, -dtud returns the date-time when the selected components were last updated in the archive. -header, -he prints a header. Not accepted by the active function. 3-65 AG92-G6 -mode, -md returns the access mode of the selected components. -name, -nm returns the name of the selected components. (Default) -no_bit_count, -nbc suppresses bit count information. (Default) -no_date_time_contents_modified, -ndtcm suppresses date-time-contents-modified information. (Default) -no_date_time_updated, -ndtud suppresses component update time information. (Default) -no_header, -nhe prints no header. (Default) -no_name, -nnm suppresses component name information. -no_requote does not requote component attribute groups. -requote causes the attributes of each component to be requoted as a single entity. This control argument is ignored by the command. (Default) NOTES ON ACTIVE FUNCTION If -name is given, archive_table always requotes the component name (if -component_name is selected) or archive pathname (if -absolute_pathname is selected). If more than one of -bit_count, -date_time_contents_modified, -date_time_updated, -mode, and -name is supplied, the selected attributes are returned, separated by a space. The order of items is always: name, date-time-contents-modified, mode, date-time-updated, bit count; which is the same order found when using the archive command's "tl" key. If -no_requote is used, the selected attributes for each component are returned separated by spaces. If more than one component is specified, successive component attributes are separated by a space. If -requote is given; the selected attributes for each component are requoted separated by spaces. If more than one component is supplied, then each component's requoted attribute group is separated from the others by a space. 3-66 AG92-06 EXAMPLES The following examples assume an archive ("sample") with "two", and "three (3t. Note that the practice of including segment names typically requires more complicated command be avoided; it is included here only to clarify the requoting three components: "one". characters such as " " in line constructs and should of names. act sample -he -nm -dtcrn -dtud -mode -bc >udd>A_Project>A_person>sample.archive UPDATED NAME one two three 0) MODE 12/01/82 1513.4 12/01/82-1513.4 12/01/82=15 13.4 do lido IIl1format line 1I111111 name ! ... ([act sample =m -bc]) name = one, length = 36. name = two, length = 63. name = three (3), length = 90. r r r MODIFIED LENGTH 36 63 12/01/82 1512.9 12/01/82-1513.0 12/01/82=1513.2 = "a, length = "'a.1I111I1I &&rf1 90 1111 &fl ll do lido IIlIformat line 1IIIIIIIitem = "a." 1I1I1 &&rfllill &rfl" ([act sample =nm -bc -no_requote]) tem = one. tern 36. tern = two. tern = 63. tern = three 0) . tern = 90. format line IIbit count of component IIlIone lili is "'a." I ... [act-sample -nnrn -bc one] bit count of component "one" is 36~ ! Name: area_status SYNTAX AS A COMMAND area_status virtual_pointer {-control_args} FUNCTION displays some information about an area. 3-67 AG92-06 ARGUMENTS virtual_pointer is a virtual pointer specifier to the area to be looked at (see Section 1 for a description of virtual pointers). CONTROL ARGUMENTS -lnn~ '&"'&'&'b' -1~ .&.b dumps the contents of each block in both octal and ASCII format -trace displays a trace of all free and used blocks in the area. NOTES If the area has internal format errors, they are reported. The command does not report anything about (old) buddy system areas except that the area is in an obsolete formal Name: assign_resource, ar SYNTAX AS A COMMAND ar resource_type {-control_args} SYNTAX AS AN ACTIVE FUNCTION Car resource_type {-control_args}] FUNCTION calls the Resource Control Package (RCP) to assign a resource to the user's process. ARGUMENTS resource_type specifies the type of resource to be assigned. Currently, only device types can be designated. The -device control argument is used to name a specific device to assign. Other control arguments are used to indicate characteristics of the device to be assigned. The following device type keywords are supported: tape_drive disk_drive console 3-68 AG92-06 printer punch reader special CONTROL ARGUMENTS -comment STR, -com STR is a comment string that is displayed to the operator when the resource is assigned. If more than one string is required, the entire string must be in quotes. Only printable ASCII characters are allowed. Any unprintable characters (like tabs or new lines) found in this string are converted to blanks. -density N, -den N supplies the density capability characteristic of a tape drive. There can be more than one instance of this argument. A tape drive is assigned that is capable of being set to all of the indicated densities. The acceptable values for this argument are: 200, 556, 800, 1600, and 6250. Note that the values permitted depend on the particular hardware on the system. -device STR, -dv STR specifies the name of the device to be assigned. If used, other control arguments that indicate device characteristics are ignored (see "Examples~' below). If used with -long, a message containing the name of the assigned device is printed on the user's terminal; otherwise, no message is printed. If found several times on the command line, the last one supplied overrides any previous ones. -line_length N, -11 N supplies the line length of a printer. Its value must be one that is found in the "line length" field of a printer PRPH configuration card. If this field is not given on a printer PRPH configuration card, this device characteristic is ignored f or this printer. -long, -lg prints all of the device characteristics of the assigned device. only the name of the assigned device is printed. If not supplied, -model N specifies the device model number characteristic. Only a device that has this model number is assigned. To find the acceptable model numbers. use prin t_conf iguration_deck. 3-69 AG92-()6 -number N. -nb N suppplies the number of resources to assign. All of the resources assigned have the device characteristics indicated by any other arguments passed to this command. If -number is not given. one resource is assigned. -speed N gives the speed of a tape drive. The acceptable values depend on the particular hardware on the system and can be: 75. 125. or 200. -system, -sys indicates that the user wants to be treated as a system process during this assignment If not used or if the user does not have the appropriate access. then the Rep assumes that this assignment is for a nonsystem process. -track N. -tk N specifies the track characteristic of a tape drive. The value can be either 9 or 7. If both -track and -volume are not given. a track value of 9 is used when assigning a tape device. -train N, -tn N specifies the print train characteristic of a printer. -volume STR. -vol STR specifies the name of a volume. If possible. the device assigned is one on which this volume has already been placed. If this is not possible (e.g., the volume is on a device assigned to a process) any available, appropriate, and accessible device is assigned. -wait {N}, -wt {N} indicates that the user wants to wait if the assignment cannot be made at this time because the resources are assigned to some other process. The value N designates the maximum number of minutes to wait If N minutes elapse and a resource is not yet assigned, an error message is printed. If N is not given. it is assumed that the user wants to wait indefinitely. NOTES An assigned device still is successfully assigned, specific device that is unless the user asks for must be attached by a call to some I/O module. If a device the name of the device is printed. If the user requests a successfully assigned, the name of the device is not printed it NOTES ON ACTIVE FUNCTION The active function returns "true" if an assignment was successful or "false" if the resource is unavailable. Other errors are reported by active_fnc_error_. The -long control argument is not allowed. Use list_resources to obtain the name of the assigned device(s). 3-70 AG92-()6 EXAMPLES In the first example, the user issues assign_resource with the tape_drive keyword and -model. The system responds with the name of the assigned device. ar tape_drive -model 500 Device tape_04 assigned In the next example, the user issues assign_resource with tape_drive and -device and -long. The system responds with the name of the assigned device and the model number, track, density, and speed characteristics. ar tape_drive -device tape_OS -long Device tape_OS assigned Model = 500 Tracks = 9 Densities = 200 556 800 1600 = 125 Speed In the last example, the user issues assign_resource as an active function with tape_drive and -model. The system returns "true" if a model 610 tape drive was assigned, "false" if not. format_line Ear tape drive -model 610] true Name: attach_audit, ata SYNTAX AS A COMMAND ata {old_switch {new_switch}} {-control_args} FUNCTION sets up a specified I/O switch, with a stream_input_output opening, to be audited by the audit_ I/O module. ARGUMENTS old_switch is the name of an I/O switch to be audited. The default is user_i/o. If only one switch is specified, it is the old_switch. 3-71 AG92-06 new_switch is the name of an I/O switch to be used by the audit_ I/O module. If only one switch argument is given. it is the old_switch. The default value for new_switch is audit_i/o. , where has the value MM/DD/YY.hhmm.m. CONTROL ARGUMENTS -modes STR set the modes on the switch being audited using STR as the mode string. -pathname path. -pn path specifies that path is the pathname of the audit file to use. If pathname is not given. the audit file is in your home directory and named date. audit -truncate. -tc truncates the audit file if it already exists. If this control argument is not given. the audit file is extended by default NOTES If used with no arguments. attach_audit sets up auditing for the user_i/o I/O switch with input and output audited and editing on. Auditing of old_switch is done by moving the attachment of old_switch to new_switch and then attaching old_switch to new_switch via audit_. See the audit_ I/O module and the detach_audit command for more information. LIST OF AUDITING REQUESTS A three-character sequence is used to make an auditing request: the audit trigger character ("!" by default), followed by the specific request character, followed by a newline. An auditing request can either be alone on a line or have text preceding it on the same line. When an unrecognized request is given. the entire line is treated as a regular input line (with no special processing). prints the combination of input and/or output being audited. !? prints a brief description of available auditing requests. !e enters the audit editor. The entry preceding this sequence becomes the current line to be edited. !E enters the audit editor, and processes any text preceding the sequence on the same line as editing requests. If no text precedes the sequence, the effeet is the same as for !e. 3-72 AG92-06 !a expands abbreviations in the input line (see the abbrev command). !r redisplays the input line and strips off the newline. Further input can then be appended to the redisplayed line until another newline is typed, but no further erase or kill processing is performed on the redisplayed portion. The redisplayed line plus the appended input (if any) becomes the input line that is returned to the I/O module being audited. !t instructs the audit_ I/O module not to log the input line; this makes the input line transparent !d specifies that the input line to which this is appended is deleted. This is used to kill a line that has been redisplayed with the !r request !n specifies no operation; this is useful when the !n follows another auditing request sequence that you do not want interpreted. NOTES ON AUDIT FILE The audit file, by default, has the pathname: >udd>Project_id>Person_id>date.audit where date is the first eight characters (the date portion) returned by the date_time_ subroutine at the time of attaching, and is of the form MM/DD/YY. This pathname can also be specified using active functions: [home_dir]>[date].audit The default audit file size is unlimited. and the audit file can become a multisegment file. Audit files contain binary information. Use the display_audit_file command to print the contents of audit files. The audit editor operates on entries, rather than lines, and the entry type identifiers are: EL edit line IC input characters IL input line DC output characters 3-73 AG92-06 TC trace of control operations TM trace of modes operations NOTES ON AUDIT EDITOR The audit editor is invoked by typing the e or E auditing request sequence described above. It edits and executes lines that have been logged by the audit_ I/O module. The syntax of editing requests is similar to that of qedx requests (see the qedx command in this manuaI). Any number of requests can be on the same line and spaces are ignored. Addressing is done the same way as in the qedx editor, with two exceptions. The n." is a request for self-identification rather than an indicator for the current entry, and addresses are expressed in terms of entries in the audit file rather than lines in a buffer. The edit buffer contains only one entry at a time. If the default search tag is in use, as is the case unless specifically overridden, the absolute entry number refers to the number of entries, with the default search tag, from the beginning of the file. Similarly. a relative entry address refers to the number of entries, with the default search tag. before or after the current address. LIST OF EDITING REQUESTS The audit editor requests are presented below in two categories: familiar (qedx-like) requests, and special requests. FAMILIAR REQUESTS s/REGEXP/STR/ substitutes the string STR for occurrences of the regular expression REGEXP in the edit buffer. ADR locates the entry with address ADR. If ADR is not followed by a request, the audit file entry is printed. An ADR can contain an absolute entry reference at its beginning, relative addresses in any portion. and regular expressions in any portion. If a regular expression in the address is preceded by the less than character «), a backward search is done to find a match for the regular expression. An absolute address is either a number, or the dollar sign ($) to indicate the last entry in the audit file. {ADR 1, ADR2J P prints the current entry if no ADR is specified; prints the addressed audit file entry if a single address is specified; prints entries from address 1 through address 2 if two addresses are specified. = prints the current entry number. This value is dependent on the current default search tag. If the default search tag changes, the current entry may also change. 3-74 AG92-06 • .STR passes the string STR to the command processor and then returns to the audit editor. q quits the editor and returns the current line to the I/O module being audited, with the !e or !E sequence included. SPECIAL REQUESTS expand, .expand expands abbreviations in the edit buffer (see the abbrev command). off, .off disables auditing of input and output in the editor. on, .on enables auditing of input and output in the editor. 1, • 1 addresses the last audit file entry returned by the audit editor. r [STR] , • r [STR] quits the editor and returns the string STR to the I/O module being audited. If STR is not specified, the r request quits the editor and returns the edit buffer. n, • n returns a newline character. type, . type prints the audit file entry type of the current position. exec, .exec passes the edit buffer to the command processor and returns to the audit editor. d/STR/, .d/STR/ sets the default search tag to the string STR. If STR is only one character, only the first character of the tag is used to determine if an entry is seen (in counting entries and doing searches). If STR is two characters, the match is made on both characters of the tag. 1, .1 prints a brief description of available audit editor requests. '''' overrides the default search tag for those requests following on the same line (i.e., any tag is matched). A newline reestablishes the default search tag. 3-75 AG92-()6 NOTES The REGEXP field expression. The STR the & convention is REGEXP specified LTl of a substitute request is interpreted as a qedx-style regular field of a substitute request is also interpreted as in qedx, and supported. If REGEXP is null in a substitute request. the last a previous substitute request is used. No lines in the audit file are changed by the editor; only copies are modified. If execution of a request should fail for any reason, the processing of that request line is aborted. you are informed of the failure and a new request is prompted for. Note that this means you are left in the editor when a problem is encountered executing a request line associated with an E audit request. The audit editor may be entered recursively, and each level of the editor has its own memory for the last returned line from its level. If the audit editor is being aUdited, the audit editor can be invoked from within the editor. For every level of the editor. a distinct last returned line is remembered. EXAMPLES To set up with a default audit file in· your home_dir: ata To set up with an audit file in the process_dir: ata -pn [pd]>my_audit_file To set the audit file to be a circular file of 5 records: To re-execute the last use of the pll command: site>dm>system_low>system_default -lg pathname: journal uid: activity: control interval size: contro 1 i nterva 1s: control intervals used: last control interval buffered: put: flushed: -On dt-s-k: time last control interval queued: written: time header updated: last record id: images not on disk: images being flushed: users: transactions: >sit~>Data_Management>system_low>system_default.bj 132233107561 in use 4096 bytes 4000 86 86 86 86 86 01/14/85 1104.9 est 01/14/85 1104.9 est 01/14/85 1104.9 est 000001260013 o o 2 1 where: pathname is the path name of the before journal. journal uid is the octal unique identifier of the before journal. activity is "in use" if a process currently has Lhe before journal open. "not in use" otherwise. control interval size is the size of each control interval in the before journal, in bytes. Currently 4096 bytes is the only supported size. control intervals is the number of control intervals in the before journal. 3-82 AG92-D6 bef ore~ournal_status before~ournal_status control intervals used is the number of control intervals in the before journal containing before images still needed to roll back modifications made by a transaction. Images that are not needed include those that have- -already - been- used in a complete- rollback and those for a transaction that has ended. last control interval buffered indicates the last control interval put in a special buffer used for before journals. last control interval put indicates the last control interval put into the before journal. last control interval flushed indicates the last control interval flushed to disk. last control interval on disk indicates the last control interval safely on disk. time last control interval queued is the last time a before image was put in the before journal. time last control interval written is the last time a control interval was written to disk. time header updated is the last time the header of the before journal was written. last re.cord id is the address of the last before image in the journal. images not on disk is the number of images not written to disk yet images being flushed is the number of before images for which a flush from memory to disk has been requested. users is the number of users with openings. transactions is the number of active transactions in the before journal. 3-83 AG92-()6 before.Journal_status binary The example below requests the status, in long form, of the system_low system default before journal, which is not in use. bjst >site>dm>system_10w>system_defau1t -lg pathname: journal uid: activity: control interval size: control intervals: time header updated: >site>dm>system_default.bj 127120202215 not in use 4096 bytes 4000 08/26/84 1228.6 edt Name: binary, bin SYNTAX AS A COMMAND bin values SYNTAX AS AN ACTIVE FUNCTION [b i n va 1ues] FUNCTION returns one or more values in binary. ARGUMENTS value is a value to be processed. The last character of value indicates its type. Acceptable types are binary (b), quartenary (q), octal (0), hexadecimal (x), and unspec (u). Any valid PL/I real value is allowed. The absence of any specifier means decimal. The unspec value is limited to eight characters. EXAMPLES string [binary 657.40] 11 0 100 1 1 1 . 1 string [bin abcu] 1100001001100010001100011 3-84 AG92-06 bind bind Name: bind, bd SYNTAX AS A COMMAND bd path_specs {-control_args} FUNCTION produces a single bound object segment from one or more unbound object segments, which are called the components of the bound segment You can use archive segments or unarchived segments to specify pathnames of object components. ARGUMENTS path_specs can be one or more of the following logically concatenated in a left-to-right order to produce a single sequence of input component object segments. -archive PATHs, -ac PATHs indicates that each PATH is the pathname of an archive segment containing one or more object segments. If the .archive suffix does not exist. it is assumed. (All arguments following -archive but preceding the next control argument arc considered to be pathnamesJ -segment PATHs, -sm PATHs indicates that each PATH is the pathname of a stand-alone segment The pathname is trie.d as given, i.e., no suffixes are assumed. (All arguments following -segment but preceding the next control argument are considered to be pathnames.) PATHs functions exactly as -archive PATHs. CONTROL ARGUMENTS -bindfile path, -bdf path specifies the name (not pathname) of the bind file to be used to control the binding process. The suffix .bind is assumed. (See "Notes on Bindfile" below.) -brief. -bf suppresses printing of warning messages. -force_order, -fco is equivalent to including a Force_Order statement in the bind file. Since the need to use Force_Order is often temporary and caused by update archives that have had components deleted. this is preferable to using the Force_Order statement because you need only use it while the temporary condition exists. 3-85 AG92-06 bind bind -force_update path_specs, -fud path_specs is similar in function to -update except that the path_specs (see the path_specs argument above) specified following -force_update need not exist. Any path that exists is treated the same way as for -update and any that doesn't is simply ignored. This is useful for constructing abbreviations used for binding objects that mayor may not have update paths in various locations. -list, -Is produces a ltsttng segment whose name is aenvea nom the name or tne bound object segment plus a suffix of list The listing segment is generated to dprint; it contains the bound segment's bind control segment (see "Notes on Bindfile"), its bind map, and that information from the bound object segment printed by the print_link_info command. You can't invoke -list with -map. In the absence of -list or -map, no listing segment is generated. -map produces a listing segment (with the suffixes list and map) that contains onlytbe bind map information. It is incompatible with -list In the absence of -list or -map, no listing segment is generated. -update path_specs, -ud path_specs indicates that the following list of path_specs (see the path_specs argument above) specifies update rather than input object segments. The update object segments are matched against the input object segments by object segment name. Matching update object segments replace the corresponding input object segments; unmatched ones are appended to the sequence of input object segments. If several update object segments have the same name, only the last one encountered is boa'1d into the bound segment NOTES Compilers and the assembler produce unbound object segments. Binding has three benefits: the reduction of storage fragmentation, the prelinking of external references between the components, and the reduction of size of address space necessary to execute the components. Each of these benefits saves CPU time and storage usage if the set of components bound is used with regularity. This reduction in usage translates directly into lower charges for the users of the bound segment. System efficiency is also increased by binding together common sets of programs. A reference in one component to an entry point defined in another component is resolved during the binding. This prelinking avoids the cost of dynamic linkin& and it also ensures that the reference is linked to the component regardless of the state of a process at the moment that dynamic linking takes place. References to an entrypoint are prelinked unless the contrary is specified by an instruction in the bindfile. The bindfile is a segment containing instructions that control various aspects of the binding operation (see "Notes on Bindfile" below). (See the print_link_info command.) 3-86 AG92-06 bind bind NOTES ON OUTPUT The binder produces as its output two segments: an executable bound objectsegm-ent and an optional. printable ASCII listing segment The name of the bound segment is. by default. derived from the entryname of the first input archive segment encountered by stripping the archive suffix from it. The name of the listing segment is derived from the name of the bound segment by adding the list suffix to it. Use of the Objectname master statement in the bind file (see "List of Master Keywords" below) allows the name of the bound segment to be stated explicitly. In addition. use of the Addname master statement in the binding instructions adds additional segment names to the bound segment. The primary name of the bound segment must not be the same as the name of any component. NOTES ON BINDFILE SELECTION As the binder is examining the archive components and loose segments, it is also looking for a bind file. Any segment whose name ends with the suffix "bind" is considered a bindfile. If you specify -bind file, only bindfiles by that name are considered and the last one by that name is selected; otherwise the first bindfile found among the input segments and all bindfiles among the update segments are considered and the last one is selected. If more than one bind file is found among the input segments, the second through last are ignored and generate a warning. NOTES ON BINDFILE The bindfile is a segment containing symbolic instructions that control the operation of the binder. The syntax of the bind file statements consist oj a keyword foliowed by zero or more parameters and then delimited by a statement delimiter. Master statements pertain to the entire bound object segment; normal statements pertain to a single component object within the bound segment Master statements are identified by master keywords that begin with a capital letter; normal keywords begin with a lowercase letter. A keyword designates a certain action to be undertaken by the binder pertaining to parameters following the keyword. LIST OF MASTER KEYWORDS Objectname the parameter is the segment name of the new bound object Order the parameters are a list of objectnames in the desired binding order. In the absence of an order statement, binding is done in the order of the input sequence. If an Order statement is present in the bindfile, every object segment being bound must be mentioned in its parameter list Force_Order same as Order except that the list of parameters can be a subset of the input sequence, allowing the archive segments to contain additional segments that are not to be bound (e.g., source programs). However, the parameter list must include all segments mentioned in objectname statements. 3-87 AG92-06 bind bind Partial_Order same as Order except that the list of parameters can be a subset of the input sequence; the named objectnames are placed in the bound output segment in the order specified and the remaining objects are placed after those named, in the order of the input sequence. Ignore the parameters can be a subset of the input sequence, indicating objects not to be ;nl'lnnM ;n A.A.& ............... ...,... ........ tnp hnnnn .a........ nntnnt "' ....,....... ~O'Tnpnt ......,.1:)&.................... ....... -., . . , , , ... Tnp ... ..... .., ;O'nnTPn ...C>-"'... "............ nh;pl't~ " ......,J .......... ...., !::ITP wr........... d111 1Ttpnt;nnM "''''''.&.......... .......... ..&..&W'........ ;n ... ...... the bound segment's source map. Global the single parameter can be retain, delete, or no_link. The parameter selected pertains to all component object segments within the bound segment. A global or explicit statement concerning a single component object or a single external symbol of a component object overrides the Global statement for that component object or symbol. Addname the parameters are the symbolic names to be added to the bound segment. If Addname has no parameters, it adds to the bound segment the segment names and synonyms of those component objects for which at least a single entrypoint was retained. No_Table does not require parameters. It omits from the bound segment the symbol tables from all the component symbol sections containing symbol tables. If you don't give this keyword, all symbol tables are kept. Perprocess_Static does not require parameters. It turns on the perprocess_static flag of the bound segment. which prevents the internal static storage from being reset during a run unit. The Order. Force_Order. and Partial_Order statements are mutually contradictory; only one of these can be present in any bindfile. If you supply no bindfile, the binder assumes default parameters corresponding to the following: Objectname: segment name of the first input archive file. Global: retain; /*regenerate all definitions*/ 3-88 AG92-06 bind bind LIST OF NORMAL KEYWORDS objectname the-single parameter is the name of a component object as it appea-rs in the archive segment. The objectname statement indicates that all following normal statements (up to but not including the next objectname statement) pertain to the component object whose name is the parameter of the objectname statement synonym the parameters are symbolic segment names declared to be synonymous to the component object's objectname. When b is declared to be a synonym for a, references (in the bound components) of the form b or b$x (any x) are resolved during binding by searching for a definition of b or x in component a. Give the synonym instruction if such references are to be prelinked. The synonym instruction also affects dynamic linking so that if b is a reference name for the bound segment, then references of the form b or b$x are resolved by searching component a. In this case the synonym instruction may reduce the cost of dynamic linking, and it avoids possible ambiguities when two components contain definitions for the symbol b. State explicitly in a synonym statement all the normally used segment names of a component object. For example. the create and create_dir commands are implemented in one procedure. and both have abbreviations; thus a bindfHe for the bound segment in which this procedure resides contains objectname: create; synonym: create, cr, create_dirt cd; Failure to state segment names results in inefficient linker performance. retain the parameters are the names of entrypoints defined within the component object segment that you wish to retain as entrypoints of the bound object segment. delete the parameters are the names of entrypoints defined within the component object segment that you don't wish to be retained as entrypoints of the new bound segment no_link the parameters are the names of entrypoints that are not to be prelinked during binding. This statement impHes th.at the spp....cified na..rnes be retained. The retain, delete, and no_link statements are considered exclusive. An error message is displayed if the binder recognizes that two or more such statements were made regarding any single entrypoint 11/86 3-89 AG92-()6A bind bind global the single parameter can be retain, delete, or no_link. The parameter selected becomes effective for all entrypoints of the component object An explicit retain, delete, or no_link statement concerning a given entrypoint of the component object overrides the global statement for that specific entrypoint A global no_link causes all external references to the component object to be regenerated as iinks to entrypoints; this aiiows execution time substitution of such a component by a free-standing version of it for debugging purposes, for example. "_"-1_ LiiUIC; does not require parameters. It retains the symbol table for the component and is needed to override the No_Table master keyword. LIST OF BINDFILE DELIMITERS keyword delimiter used to identify a keyword followed by one or more parameters. A keyword that is followed by no parameters is delimited by a statement delimiter.. statement delimiter , parameter delimiter. The last parameter is delimited by a statement delimiter. /* begin comment */ end comment NOTES ON ERROR MESSAGES The binder produces three types of error messages. Messages beginning with the word "Warning" do not necessarily represent errors, but warn you of possible inconsistencies in the input components or bind file. Messages beginning with the word "bind" normally represent errors in the input components. Errors detected during the parsing of the bindfile have the format ERROR J SEVERITY 3 IN LINE N or WARNING J IN LINE N where J is the error number and N is the line number of the erroneous statement If an error is detected during parsing, the binder aborts because it cannot bind according to your specifications. The message IIbind: * 11/86 Fatal error has occurred; binding unsuccessful. 1I indicates that it was impossible for the binder to produce an executable object segment because of errors detected during binding. 3-90 AG92-D6A bind bind EXAMPLES The bindfile for the debug command, which is named bound_debug. bind, is as follows: Objectname: GI oba I : Addname; objectname: synonym: retain: bound_debug; delete; I*delete all old definitions*1 I*add names debug, db, list_arg_ and gr_print to bound segment bound_debug*1 debug; I*indicate db is synonymous to debug*1 db; debug, I*retain entrynames debug$debug and debug$db*1 db; objectname: retain: list_arg_; list_arg_; I*retain entryname list_arg_$list_ar9_*/ objectname: retain: gr_print; gr_print; The following illustrates other uses of the bind file: Objectname: G1aba 1: Order: Addname: bound test; delete; I*delete all old definitions*1 test, I*list all components in the order they are to be bound*1 test_utility, test_init, reset; test, test_utility, I*add so that link can be snapped to version in bound segment*1 reset; I*omit all symbol tables*1 objectname: retain: reset; reset; objectname: synonym: no_link: test_utility; rest_of_test; test_utility; table; I*another entrypoint*1 I*do not prelink to this entrypoint; generate external link*1 I*keep this component's symbol tabJe*1 3-91 AG92-06 Name: bLmgr_call, bjmc SYNTAX AS A COMMAND bjmc key {path} {-contro1_args} SYNTAX AS AN ACTIVE FUNCTION rbimc key fDathl _-- ~ .. - - - - - , _.- - - - -,. f-control arosll .. - - - - - - - - - - - .., - I .. FUNCTION enables you to manipulate before journals in your process by calling before.Journal_manager_ entry points from command level. This command is part of the command level interface to Multics data management (DM) (see the Programmer's Reference Manual). ARGuMENtS key designates the before journal manager operation to be performed. See "List of Operations" below for a description of each operation, its command and active function syntax lines, and specific application. path specifies the absolute or relative pathname of the before journals being manipulated (required for all key operations except get_default_path). Give -pathname (-pn) PATH with patbnames constructed with leading minus signs to distinguish them from control arguments. If you supply no .bj suffix, it is assumed. CONTROL ARGUMENTS can be one or more control arguments, depending on the particular operation. LIST OF OPERATIONS Each operation is described in the general format of a command/active function. Where appropriate, notes and examples are included for clarity. Operation: close, cl SYNTAX AS A COMMAND bjmc cl path 3-92 AG92-()6 SYNTAX AS AN ACTIVE FUNCTION [bjmc c 1 path] FUNCTION closes the before journal specified by path. Separate pathnames" by spaces if multiple journals are to be closed. Specifically close by name each journal opened in the process. The active function returns true if the journals were closed successfully, false otherwise. ARGUMENTS path is the absolute or relative pathname of before journals to be closed. supply no . bj suffix, it is assumed. if you NOTES If a before journal being closed by this operation is the default journal, the last journal opened in the process becomes the default Operation: closed SYNTAX AS A COMMAND bjmc closed path SYNTAX AS AN ACTIVE FUNCTION [bjmc closed path] FUNCTION returns true if the before journal specified by path is not open in your process, false otherwise. ARGUMENTS path is the absolute or relative pathname of a before journal. If you don't give the .bj suffix, it is assumed. 3-93 AG92-06 Operation: create, cr SYNTAX AS A COMMAND bjrnc cr path {-control_args} SYNTAX AS AN ACTIVE FUNCTION ______ +k ! ____ + __ 1 ____ 1' r~: LUJIII\.. \,,1 t-'QLII t"\"VIILIVI_QI~;:)JJ FUNCTION creates the before journal specified by path. The active function returns true if the before journal is created successfully, false otherwise. ARGUMENTS path is the absolute or relative pathname of the before journals to be created. If you supply no .bj suffix, it is assumed. CONTROL ARGUMENTS -length N, -In N specifies the size of the before journal. where N is the number of 4096-byte control intervals. Once established, you can't alter a journal's size. (Default if you specify no value at the time of creation, the size is 64 control intervals) -transaction_storage_limit N, -tsl N specifies the maximum number of bytes a single transaction can use in the before journal (Defaul t the en tire journal) NOTES Before journals are extended entry types; you can delete them using the delete command. You can only delete before journals if they are not required for recovery. Operation: get_default_path, gdp SYNTAX AS A COMMAND bjrnc gdp SYNTAX AS AN ACTIVE FUNCTION [bjrnc gdp] 3-94 AG92-06 FUNCTION returns the pathname of the process's default before journal. Operation: open, 0 SYNTAX AS A COMMAND bjmc path 0 SYNTAX AS AN ACTIVE FUNCTION [bjmc 0 path] FUNCTION opens the before journal specified by path. The active function returns true if the journal is opened successfully, false otherwise. ARGUMENTS path is the absolute or relative pathname of before journals to be opened in your process. If you supply no .bj suffix, it is assumed. NOTES If no journal has been specifically designated as the default (see the set_default_path operation) for your process, the last before journal opened in the process becomes the default If no journal is opened in your process when a transaction is started, the system before journal is opened and used as the default Operation: opened SYNTAX AS A COMMAND bjmc opened path SYNTAX AS AN ACTIVE FUNCTION [bjmc opened path] FUNCTION returns true if the before journal specified by path is opened in your process, false otherwise. 3-95 AG92-06 b001 ARGUMENTS path is the absolute or relative pathname of a before journal. If you supply no .bj suffix, it is assumed. SYNTAX AS A COMMAND bjmc sdp path SYNTAX AS AN ACTIVE FUNCTION [bjmc sdp path] FUNCTION sets the default before journal for the process to the specified pathname. The active function returns true if the pathname is successfully set, false otherwise. ARGUMENTS path is the absolute or relative pathname of the before journal to be used as the default by your process. If you supply no .bj suffix, it is assumed. NOTES If no default before journal is set for your process, the last journal opened in the process is used as the default (see the open operation). If no before journal is open in the process when a transaction is started, the system before journal is opened and used as the default Name: bool SYNTAX AS A COMMAND bool 81 B2 83 SYNTAX AS AN ACTIVE FUNCTION [bool Bl 82 83] 3-96 AG92-G6 bool bool FUNCilON performs bit string operations on character string representations of bit strings. ARGUMENTS B1, B2, and B3 are bit strings entered as 0 and 1 characters. NOTES The shorter of the two strings is extended at the right with zeroes to equal the length of the longer string. B3 must be four bits long. It causes the following logical operations to be performed on Bl and B2. B3 Name Result 0000 0001 0010 0011 0100 0101 0110 0111 1000 1001 1010 1011 1100 clear and all zeroes B1 & B2 B1 &"'B2 B1 AB1 & B2 B2 (B 1&"'B2) I ("'B 1&B2) B1 1 B2 move B1 move B2 xor or "'or "'xor invert B2 invert B1 ilOl 1110 1111 "'and "'clear I '" (B 1 B2) = ("'B 1&"'82) "'«B1&"'B2) I (AB1&B2» AB2 A ("'B 1&B2) = (B 1 I"'B2) AB1 "'(B1&"'B2) = ("'B1IB2) A (B 1&B2) = ("'B 1 I"'B2) all ones = ("'B1IB2) & (B1 1"'B2) EXAMPLES s tr i ng [boo 1 1010 0101 0111] 1111 string [bool 1001001 1101001010 0110] 0100000010 3-97 AG92-06 branches branches Name: branches SYNTAX AS A COflllMAND branches star_names {-control_args} SY/,ITAX AS AN ACTIVE FUlvCTION [branches star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of segments, directories, and multisegment files (MSFs) that match one or more star names. ARGUMENTS star_name .is a·star name to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. (Default to return entrynames) -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a star name. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per branch is returned; i.e., if a branch has more than one name that matches star_name, only the first match found is returned. Since each entryname (or pathname) returned by branches is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. 11/86 3-98 AG92-06A byte byte Name: byte SYNTAX AS A COMMAND byte N SYNTAX AS AN ACTIVE FUNCTION [byte N] 11/86 3-98.1 AG92-06A This page intentionally left blank. 11/86 AG92-06A calc byte FUNCTION Prints or returns the character in a specified position in the Multics ASCII collating sequence. ARGUMENTS N is the zero-ongtn position of the desired character in the collating sequence. If the number ends with the character "0", it is interpreted as an octal number; otherwise it is decimal. Name: calc SYNTAX AS A COMMAND calc {expression} SYNTAX AS AN ACTIVE FUNCTION [calc expression] FUNCTION provides you with a calculator capable of evaluating arithmetic expressions with operator precedence, a set of often-used functions, and a memory that is symbolically addressable (i.e., by identifier). ARGUMENTS expression is an aritfu"'I1etic expression specified, the calc command expression must be quoted characters. Variables are not (see below) to be evaluated. If this argument is prints its value and returns to command level. The if it contains spaces or other command language allowed. LIST OF REQUESTS print "calc". • • STR execute the Multics command line STR. type value of expression. 3-99 AG92-G6 calc calc = assign value of expression to variable. 1 i st list variables. return to command level. NOTES Invocation of calc with a newline enters calculator mode. You can then type in expressions, assignment statements, or list requests, separated from each other by one or more newline characters. All of these operations are described below. You must use the quit request with a newline character to return to command level. NOTES ON EXPRESSIONS Arithmetic expressions involving real values and the operands +, -, *, I. and ** (addition, subtraction. multiplication. division, and exponentiation) can be typed in. A prefix of either plus or minus is allowed. Parentheses can be used, and blanks between operators and values are ignored. Calc evaluates each expression according to rules of precedence and prints out the result. The quit request (followed by a newline character) returns you to command level. The order of evaluation is as follows: expressions within parentheses function references prefix +, prefix - ** *, I +, - For example, if you type: calc responds = 14 Operations of the same level are processed from lei! to right except for the prefix plus and minus, which are processed from right to left. This means 2**3.*4 is evaluated as (2**3}**4. 3-100 AG92-Q6 calc calc Numbers can be integers (123), fixed point (1.23) and floating point (1.23e+2, 1. 23e2, 1.23E2, or 1230E-l). All are stored as float bin(27). An accuracy of about. seven figures is maintained. Variables (see below) can be used in place of constants, e.g., pi * r ** 2. Seven functions are provided: sin, cos, tan, atan, abs, In, and log (In is base e, log is base 10). They can be nested to any level, e.g.• sin(In{var).S*pi/180). NOTES ON ASSIGNMENT STATEMENTS The value of an expression can be assigned to a variable. The name of the variable must be from one to eight characters in length and must be made up of letters (uppercase and/or lowercase) and the underscore character U. The form is = For example, the following are legal assignment statements: x = Rho 35 = sin(2*theta) The calc command does not print any response to assignment statements. The variables "pi" and "e" have preassigned values of 3.14159265 and 2.7182818, respectively. NOTES ON THE LIST REQUEST If "list" is typed, calc prints out the names and values of all the variables that have been declared so far. The value of any individual variable can be displayed by typing the name of the variable followed by a newline character. OTHER REQUESTS Typing n." on a line by itself causes calc to identify itself by printing "calc". Typing a line beginning with two periods ".. " causes the remainder of the line to be passed to Multics as a command line, and executed. Typing "q" causes calc to return to the calling program, i.e., to command level. 3-101 AG92-Q6 calendar calendar Name: calendar SYNTAX AS A COMMAND ca1endar {paths} {-control_args} FUNCTION ARGUMENTS paths are the pathnames of segments that contain a list of events in the form of text to be inserted into the calendar (see "Notes" below). CONTROL ARGUMENTS -box_height N, -bht N sets the number of lines available for notes in each box to N, an integer number. The default for N is 7 if you don't use -box_height If N is less than 7, the marginal calendars for the previous and following months cannot be printed. -date DT, -dt DT identifies which month is printed. If you supply no -date, the current month is printed. (See Section 1 for a description of valid DT valUes.) -fiscal_week, -fw labels boxes with fiscal week numbers. This command assumes that each fiscal week begins on Monday and ends on Sunday and fiscal week 1 is the first full week of the calendar year; therefore fiscal week 1 of 1984 begins on Monday, January 2. -force, -fc prints a calendar regardless of errors in the input files. -julian, -jul places in the lower left corner of each day box the number of days of the year that have passed, including the current day, and in the lower right the number of days remaining in the year after the current day. This control argument effectively reduces the number of lines in each box that are available for notes. -stop, -sp waits until you type a single newline character before printing the calendar and after printing it -wait, -wt waits for a single newline character from you before printing the calendar. Characters typed before the newline are ignored. This allows you to position the paper and to add simple top-of -form notes. 3-102 AG92-06 calendar calendar NOTES ON OUTPUT Each box for a calendar day is 16 characters wide. Its height is determined by the -boX_height control argument; but if that control argument is not used. each box is 7 lines high. Each box in the calendar contains the number of the day of the month; other information can also appear in the box, at your option. The month preceding the specified' month and the month following it are also printed. NOiES ON INPUT Each segment contains lines that set up a string to be inserted into the appropriate box of the calendar. The fields in these lines are separated by commas and have the form: opcode,dtfield, ••• ,dtfield,text The first field is the operation code (either date. reI. repeat, easter or rename). The second and succeeding fields depend on which operation code is used. Lines that produce a date not in the current month are ignored. Lines beginning with an asterisk (*) are comment lines. Leading space is NOT allowed. NOTES If the command finds errors in its arguments it reports the errors and does not print a calendar. If it finds errors in an input file. it stops after all errors have been reported, unless you give -force to indicate that the calendar should be printed in spite of errors. Users can insert several lines of text for any date. This is accomplished by supplying multiple date or reI entries for the desired date (see Washington's birthday under "Examples" below). The number of lines available is controlled by the -box_height control argument THE DATE OPERATION CODE The date operation code has the following syntax: date,DT,TEXT The first field is the date operation code itself, date. The second field. DT, is any date acceptable to the convert_date_to_binary_ subroutine. This date is converted relative to the day before the beginning of the month. so that "Mon" is the first Monday in the month. etc. The third field. TEXT. is arbitrary text Up to 16 characters are inserted into the calendar in the appropriate place, if the date specified by DT falls in the month for which the calendar is being printed. 3-103 AG92-06 calendar calendar An example of the date operation code: date,07/04,lndependence Day THE REL OPERATION CODE The reI operation code allows a note to be inserted for a day that is calculated relative to the beginning of a month. It is useful for events that are defined to occur, for example, on the first Tuesday after the first Monday of a month. Its syntax is as follows: rel,MONTHNO,RELDT1,RELDT2,TEXT The first field is the reI operation code itself, reI. The second field, MONTHNO, is a one or two digit number, or 0, -1, or +1. If it is -asimpie-number---(l through -ll-areaccepted),- it-indicates--the -month-from-which the-event is to be calculated. If it is 0 it indicates that the target date is to be calculated relative to the month for which the calendar is being printed. A MONTHNO of -1 indicates that the date is calculated relative to the month before the printed month; +1 indicates the month after the printed month. The third field, RELDTl, is a date (acceptable to the convert_date_to_binary_ subroutine) that is converted relative to the month specified by the MONTHNQ of the second field. More precisely, it is converted relative to the day before the beginning of the specified month. The fourth field, RELDT2, is a date (acceptable to the convert_date_to_binary_ subroutine) that is converted relative to the date indicated by the RELDT1 of the third field. It specifies the date selected for the insertion of the TEXT. The fifth field, TEXT, is arbitrary text to be inserted in the calendar if the date ultimately calculated from MONTHNO, RELDTl, and RELDT2 falls in the month for which the calendar is being printed. An example of the reI operation code rel,11,Mon,Tue,Election Day defines the first Tuesday after the first Monday in November, and places the text, "Election Day", in the proper calendar day box. THE REPEAT OPERATION CODE The repeat operation code inserts a note into the boxes for several days that are separated by a constant interval of time. Its purpose is to enter notations for a series of repeating events, such as regular meetings. The syntax is as follows: 3-104 AG92-06 calendar calendar repeat,STARTDT,END_OR_COUNT,INTERVAL,TEXT The first field is the repeat operation code itself, repeat The second field, STARTDT, is the date on which the series of events starts. It is a date acceptable to the convert_date_to_binary_ subroutine, or O. The date is converted relative to the day before the beginning of the month to be printed. A STARTDT of o indicates that the series starts on the first day of the printed month. The third field, END_OR_COUNT, is the end date (last day on which the event may potentially occur), or 0, or a count of the number of events in the series. A date (acceptable to the convert_date_to_binaTY_ subroutine) is converted relative to the day before the beginning of the month to be printed. An END_OR_COUNT of 0 indicates that the series continues throughout the entire month being printed. An integer number, rather than a date or 0, gives the number of events in the series. The fourth field, INTERVAL, is any offset acceptable to the convert_date_to_binaTY_ subroutine, or O. If the INTERVAL is an offset, it is truncated to an integral number of days; but if it is less than one day, it is treated as if it were 1 day. Thus, 75 hours gives an interval of 3 days, 5 hours gives an interval of 1day. If the INTERVAL is given as 0, it indicates an interval of 1 day. The fifth field, TEXT, is arbritrary text to be placed in the box of each day in the series. Examples of the repeat operation code: repeat,04/01/80,lO,lweek,Karate Lesson places the text "Karate Lesson" in the calendar boxes for April 1, 8, 15, etc., through June 3, 1980. repeat,08/04/80,o8/o8/80,lday,Hang Glider Meet places the text "Hang Glider Meet" in every calendar box from August 47 1980 to August 8, 1980. THE EASTER OPERATION CODE The easter operation code calculates the date for Easter and inserts its text in that date if it falls in the printed month. The syntax is: easter,TEXT There are only two fields, the operation code, easter, and the text to be placed in the box. An example: easter,Family reunion 3-105 AG92-06 calendar calendar THE RENAME OPERATION CODE The rename operation code allows you to change the names of days or m.onths. Its syntax is iename,OLDNAME,NEWNAME The OLDNAME field gives the name of a day or month to be changed. If the name nf tl"l~t ,.l.. .. ..,. ......A .;... +l.."" "'''4040'''''''+ ; ......"' ..... t;__ _~ tl.. .... W,l...... -n~'U ....J nl" ft'\n ... tl"l u'~r ~"''I7';ftnrl.., ,t'.l"''' .lVw.:I.lJ .l.l.l 1.J..l'" "'&..i.L.L"'.L.L" .L.L.l YV\.ICI.&..LV.L.l VI I.J.l" command, OLDNAME must be the current name. The NEWNAME field gives the name to replace the OLDNAME. For example, rename, Monday,Lundi. Vol Vol ol,uV,u ..,u "'.l.lQ..l.l6~ nUooll EXAMPLES The following illustrates the kind of segment you might create to put fixed holidays into a calendar. *-hofidays 'Ie date,Ol/Ol,New Year's Day date,02/02,Ground Hog Day rel,2,Mon,2 weeks,Washington's rel,2,Mon,2 weeks, birthday easter,Easter rel,4,Mon,2 weeks,Patriot's Day rel,5,Sun,1 week,Kother's Day rel,5,05/24,Kon,Kemorial Day date,07/04,lndependence Day rel,9,O,Kon,Labor Day rel,lO,Kon,l week,Columbus Day date,11/11,Veterans Day rel,ll,Kon,Tue,Election Day rel,11,Thu,3 weeks,Thanksgiving date,12/25,Christmas Day 11/86 3-106 AG92-06A calendar calendar Additionally you might create a segment to include personal information in a calendar. * personal calendar info * l date,05/21,Kirsten s Birthday l date,11/16,Mom s Birthday repeat,Saturday,O,lweek,Racquetbal1 Fred Assume you want a calendar for the coming December, including fiscal week numbers, holidays, and personal information. If the above segments are named "holidays" and "personal" (and are in your working directory). you type the following to print the calendar on the terminal: calendar -dt 12/01 -fw holidays personal 11/86 3-106.1 AG92-06A This page intentionally left blank. 11/86 AG92-06A calendar_clock calendar_clock Name: calendar_clock SYNTAX AS A COMMAND calendar_clock {time_string} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [calendar_clock {time_string} {-control_args}] FUNCTION returns the complete clock value from the four-digit year down through the microsecond in a sequence that allows direct comparison, e.g.• "1982-12-23_18:06:30.421857JIllt_Thu". The format string to produce this is "/\ 9999yc-/\my-l\dm_/\ Hd: /\ MH: /\ 99. (6)9UM_1\ za_/\da". ARGUMENTS time_string indicates the date about which information is desired. If you supply no time_string. the current date is used. The time string is concatenated to form a single argument even if it contains spaces; you need not quote it (See Section 1 for a description of valid time_string values.) CONTROL ARGUMENTS -language STR. -lang STR STR specifies the language in which month names. day names, and zone names are to be expressed. (Default English) -zone STR STR specifies the zone to be used to express the result Mean Time, GMT) (Default Greenwich NOTES Use the print_time_defaults command to display the default language and zone. Use the display_time_info command to display a list of all acceptable language and zone values. 3-107 AG92-06 SYNTAX AS A COMMAND car request_identifiers {-control_args} FUNCTION allows you to delete a request for an absentee computation that is no ionger needed. ARGUMENTS you can chose request_identifiers from the following: path is the full or relativepathname for the absentee input segment of requests to be canceled. You can use the star convention. -entry S1R -et STR identifies requests to be canceled by STR, the entryname portion of the absentee input segment pathname. You can use the star convention. -id ID identifies one or more requests to be canceled by request identifier. You can give this identifier to further define any path or -entry identifier (see "Notes"). CONTROL ARGUMENTS -all, -a searches all priority queues for the specified request type starting with the highest priority queue and ending with the 10wesL It is incompatible with -queue. -brief, -bf suppresses messages telling that a particular request identifier was not found or that requests were canceled when using star names or -all. -foreground, -fg specifies that the foreground absentee queue contains the request(s) to be canceled. -queue N, -q N specifies that queue N of the request type contains the requests to be canceled, where N is a decimal integer specifying the number of the queue. If you omit it, all the queues are searched. -sender STR specifies that only requests from sender SIR should be canceled. You must also give one or more request identifiers. In most cases the sender is an RJE station identifier. 3-108 AG92-06 -user User_id specifies the name of the submitter of the request to be canceled if it is not the same as the group identifier of the process. You can give the User_id as Person_id.Project_id, Person_id, or .Project_id. Both r and d extended access to the queue are required. This control argument is primarily for operators and administrators. ACCESS REQUIRED You need 0 extended access to the queue to cancel your own request and r and d extended access to cancel somebody else's request NOTES If you supply -id. only one path or -entry is allowed. If you give -id in addition to a path or -entry, they must match the same request If you provide any path or -entry STR request identifiers, only one -id ID request identifier is accepted and it must match any requests selected by path or entryname. You can supply multiple -id ID identifiers in a single command invocation only if you give no path or entry request identifiers. The -queue, -foreground, and -all control arguments are mutually incompatible. Normally, deletion can be made only by the user who originated the request When star names are not used and a single request identifier matches more than one request in the queue(s) searched, none of the requests are canceled. However, a message is printed telling how many matching requests there are. If the absentee process has already logged in, the user is given the choice of bumping the job and cancelling the request from the queue, or allowing the job to continue running and remain in the queue. This allows the user to cancel a running absentee process. When a running absentee process is canceled by a user or an operator. the message "Process terminated by the system. The reason will be sent by Multics mail." will appear in the absentee output segment. EXAMPLES The command line car >udd>Demo>CPEBach>dump>translate deletes the absentee request that the user had made in the default queue that was associated with the control segment >udd>Demo>CPEBach>dump>translate.absin. 3-109 AG92--()6 The command line car >udd>Demo>LNTolstoy>doc>**.draft deletes the absentee requests that the user made in the default queue that were associated with all control segments ending with the ~~.draitabsin;; component combination found in the >udd>Demo>LNTolstoy>doc directory. SYNTAX AS A COMMAND ccp names {-control_arg} FUNCTION causes one or more programs in the current COBOL run unit to be canceled. ARGUMENTS names are the reference names of COBOL programs that are active in the current run unit. If the name specified in the PROG-ID statement of the program is different from its associated name argument~ name must be in the form refname$PROG-ID. CONTROL ARGUMENTS -retain_data, -retd leaves the data segment associated with the program intact for debugging purposes. (See "Notes" below.) NOTES The results of the cancel_cobol_program command and the execution of the CAl'lCEL statement from within a COBOL program are similar. The only difference is that if a name argument is not actually a component of the current run unit, an error message is issued and no action is taken; for the CANCEL statement, no warning is given in such a case. To preserve program data for debugging purposes, the -retain_data control argument should be used. The data associated with the canceled program is in its last used state; it is not restored to its initial state until the next time the program is invoked in the run unit 3-110 AG92-06 Canceling ensures that the next time the program is invoked within the run unit, its data is in its initial state. Any files that have been opened by the program and are still open are closed and the COBOL _data segment is truncated. Refer to the run_cobol command for information concerning the run unit and the COBOL runtime environment Also refer to the related commands display_cobol_run_unit (dcr) and stop_cobol_run (seT). Name: canceLdaemon_request, cdr SYNTAX AS A COMMAND cdr request_identifiers {-control_args} FUNCTION deletes an I/O daemon request that is no longer needed. ARGUMENTS request_identifiers can be chosen from the following: path identifies a request to be canceled by the full or relative patbname of the input data segment The star c-onvention is allowed. -entry STR, -et STR identifies a request to be canceled by STR, the entryname portion of the input data segment pathname. The star convention is allowed. -id ID identifies one or more requests to be canceled by request identifier. You can use this identifier 10 further define any path or -entry identifier (see ;'Notes"). CONTROL ARGUMENTS -all, -a searches all priority queues for the specified request type starting with the highest priority queue and ending with the lowest It is incompatible with -queue. -brief, -bf suppresses messages telling that a particular request identifier was not found or that requests were canceled when using star names or -all. -queue N, -q N specifies that queue N of the request type contains the requests to be canceled, where N is a decimal integer specifying the number of the queue. ~f you omit it, all the queues are searched. 3-111 AG92-06 -request_type STR., -rqt STR indicates that the request to be canceled is to be found in the queue for the request type identified by STR. If you don't supply -request_type, the default is "printer." The print_request_types command lists the request types. -user User_id specifies the name of the submitter of the request to be canceled if it is not the same as the group identifier of the process. The User_id can be equal to Person_id.Project_id, Person_id, or .Project_id. Both rand d extended access to the queue are required. This control argument is primarily for operators and administrators. ACCESS REQUIRED You need 0 extended access to the queue to cancel your own request and rand d extended access to cancel somebody else's request NOTES If you supply -id, only one path or -entry is allowed. If you give -id in addition to a path or -entry, they must match the same request If you provide any path or -entry STR request identifiers, only one -id ID request identifier is accepted and it must match any requests selected by path or entryname. You can specify multiple -id ID identifiers in a single command invocation only if you give no path or -entry request identifiers. \V-nen you don't use star names and a single request identifier matches more than one request in the queue(s) searched, none of the requests are canceled; however a message is printed telling how many matching requests there are. Normally, deletion can be made only by the user who originated the request. If the request is already running, the entry is still removed from the queue but the running request is not stopped. You are given a message stating that the request is running. When a request has been removed from the queue after it has started running and before it has finished, any user requested deletion of the segment (done with the -delete control argument to the dprint and enter_output_request commands) are ignored by the system. See the dprint, dpunch, and enter_output_request commands. 3-112 AG92-06 EXAMPLES The command line cdr >udd>Alpha>Doyle>dump>translate.list deletes the request that the user made in queue 3 of the default request type printer to print the segment >udd>Alpha>Doyle>dump>translate.list The command line cdr >udd>Alpha>Lamb>dump>probe.pl1 -request_type punch deletes the request that the user made in queue 3 of request type "punch" to punch the segment >udd>Alpha>Lamb>dump>probe.pll. The command line cdr joe sam *.* cancels the requests to print segments joe, sam, and any requested segments with two-component entrynames in the current working directory in queue 3 of the printer request type. Name: cancel_output_request, cor SYNTAX AS A COMMAND cor request_identifiers {-control_args} FUNCTION deletes an I/O daemon request that is no longer needed. ARGUMENTS request_identifiers can be chosen from the following: path identifies a request to be canceled by the full or relative pathname of the input data segment The star convention is allowed. -entry STR, -et STR identifies a request to be canceled by STR, the entryname portion of the input data segment pathname. The star convention is allowed. 3-113 AG92-06 cancel_output_request -id ID identifies one or more requests to be canceled by the request identifier. You can use this identifier to further define any path or -entry identifier (see "Notes"). CONTROL ARGUMENTS -all, -a searches all priority queues for the specified request type starting with the highest priority queue and ending with the lowest It is incompatible with -queue. -brief, -bf suppresses messages telling that a particular request identifier was not found or that requests were canceled when using star names or -all. -plot specifies that the requests to be canceled are found in the queue(s) associated with "" "" tne defautrplottet "t'equest "type---(see- "Notes" ""below)." -print, -pr specifies that the requests to be canceled are found in the queue(s) associated with the default printer request type (see "Notes"). -punch. -pch specifies that the requests to be canceled are found in the queue(s) associated with the default punch request type (see "Notes"). -queue N, -q N specifies that queue N of the request type contains the requests to be canceled, where N is a decimal integer specifying the number of the queue. If you omit it, all the queues are searched. -request_type STR -rqt STR indicates that the requests to be to be canceled is to be found in the queue for the request type identified by STR (see "Notes"). -user User_id specifies the name of the submitter of the request to be canceled if it is not the same as the group identifier of the process. The User_id can be equal to Person_id.Project_id, Person_id, or .Project_id. Both r and d extended access to the queue are required. This control argument is primarily for operators and administrators. ACCESS REQUIRED You need 0 extended access to the queue to cancel your own request and rand d extended access to cancel somebody else's request 3-114 AG92-o6 NOTES You can specify multiple -id ID identifiers in a single command invocation only if you give rio path or -entry request identifiers. If you give any path or -entry STR request identifiers. only one -id ID request identifier is accepted and it must match any requests selected by path or entryname. When you don't use star names and a single request identifier matches more than one request in the queue(s) searched, none of the requests are canceled; however a message is printed telling how many matching requests there are. Normally, deletion can be made only by the user who originated the request If the request is already running, the entry is still removed from the queue but the running request is not stopped. You are given a message stating that the request is running. When a request has been removed from the queue after it has started running and before it has finished. any user requested deletion of the segment (done with the -delete control argument to the dprint and enter_output_request commands) are ignored by the system. The -print, -punch, -plot, and -request_type control arguments are mutually exclusive. If you supply none. then cor searches the default request type used by eor -print (as displayed by the print_request_types command). See the dprint, dpunch. and enter_output_request commands. Name: cancel_resource, cnr SYNTAX AS A COMMAND cnr -id reservation_id {-control_arg} FUNCTION cancels reservations made with obtainabie from iist_resources. reserve_resource using the reservation identifier ARGUMENTS reservation_id must be present and is the reservation identifier of the reservation to be canceled. 3-115 AG92-{)6 CONTROL ARGUMENTS -priv allows a privileged cancellation to be done, such as the cancellation of a reservation belonging to another user. Use of -priv requires access to rcp_sys_. Name: cancel_retrieval_request, crr SYNTAX AS A COMMAND err request_identifiers {-eontrol_args} FUNCTION allows you---to-delete a--request for a volume retrieval -that-is no- longer-- needed. ARGUMENTS request_identifiers can be chosen from the following: path identifies a retrieval request to be canceled by the full or relative pathname of the segment or subtree. The star convention is allowed. -entry STR, -et STR identifies requests to be canceled by STR, the entryname portion of the segment or subtree pathname. The star convention is allowed. -id ID identifies one or more requests to be canceled specified by request ID number. This identifier can be used to further define any path or -entry identifier (see "Notes"). CONTROL ARGUMENTS -all. -a indicates that all retrieval queues are to be searched starting with the highest priority queue and ending with the lowest priority queue. This control argument is incompatible with the -queue control argument. -brief, -bf suppresses messages telling you that a particular request identifier was not found or that requests were canceled when using star names or the -all control argument. 3-116 AG92-06 -queue N, -q N specifies that retrieval queue N contains the request to be canceled, where N is a decimal integer specifying the number of the queue. If this control argument is omitted, only the default priority queue is searched. This. control argument is incompatible with the -all control argument -user User_id specifies the name of the submitter of the requests to be canceled, if not equal to the group identifier of the process. The User_id can be Person_id.Project_id, Person_id, or .Project_id. Both r and d extended access to the queue are required. This control argument is primarily for operators and administrators. ACCESS REQUIRED You must have 0 extended access to the queue to cancel your own requests. You must have r and d extended access to cancel a request entered by another user. NOTES If any path or -entry STR request identifiers are given, only one -id ID request identifier will be accepted and it must match any requests selected by path or entryname. Multiple -id ID identifiers can be specified in a single command invocation only if no path or entry request identifiers are given. Normally! deletion can be made only by the user who originated the request When star names are not used and a single request identifier matches more than one request in the queue{s) searched, none of the requests are canceled. However, a message is printed telling how many matching requests there are. EXAMPLES The command line: err >udd>Demo>BSpoek>dump>translate deletes the retrieval request for the specified segment or subtree that you had made in queue 3. 3-117 AG92-06 canonicalize canonicalize Name: canonicalize, canon SYNTAX AS A COMMAND canon pathl {path2} {-control_args} FUNCTION ensures that the contents of a segment are in canonical form. ARGUMENTS path1 is the pathname of the input segment path2 is the pathname of the output segment. If you omit path2, path1 is overwritten ·with·the--canonica:lized- -contents of the -jnput segment. CONTROL ARGUMENTS -force, -fc overwrites the output file without querying. -input_tabs -every X, -itabs -ev X replaces tabs with the appropriate number of spaces, assuming that tabs are at 1+n*X (where n = 1, 2, 3,... ). (Default: every 10) -input_tabs n1,n2, ... ,n20, -itabs n1,n2, ... ,n20 replaces tabs with the appropriate number of spaces, assuming that tab stops are as specified. If tabs are found in the input segment beyond the stops specified, every 10 is assumed. -no_force, -nfc queries before overwriting an existing segment (Default) -no_output_tabs, -notabs does not place tabs in the output (Default) -output_tabs -every X, -otabs -ev X inserts tabs at 1+n*X. -output_tabs nl,n2, ... ,n20, -otabs nl,n2, ... ,n20 inserts tabs at the tab stops specified. You can give up to 20 tab stops. No spaces are ailowed in the iisl 11/86 3-118 AG92-Q6A canonicalize canonicalize NOTES The command ensures that all characters in a print position are order and removes all ASCII carriage-return (015) characters. canonicalize replaces blank spaces with the appropriate tab stops. canonicalize replaces horizontal tab stops with the correct number sorted in the proper If you use -otabs, If you use -notabs, of blank spaces. EXAMPLES To canonicalize the segment named "my_prog" and establish tab stops at three specified positions, type: canon my_prog -otabs 7,21,35 To canonicalize the same segment, rename it to "new_prog", and set up tab stops at 15-space intervals, type: To canonicalize the segment "new_prog", which already contains tab stops that are now to be replaced with blank spaces, type: canon new_prog -itabs -ev 15 11/86 3-118.1 AG92-o6A This page intentionally left blank. . 11/86 AG92-06A canonicalize_mailbox canonicalize To canonicalize the segment "old_prog", which already contains tab stops that are now to be replaced with blank spaces, you can accomplish both operations in one pass by typing: Name: canonicalize_mailbox SYNTAX AS A COMMAND canonicalize_maiibox path {-control_args} FUNCTION converts the messages in a mailbox into their canonical form as defined by the MR10.2 mail system. ARGUMENTS path is the pathname of the mailbox whose messages are to be converted. The suffix "mbx" is supplied if needed. The star convention is accepted. CONTROL ARGUMENTS -force, -fc temporarily alters your access to the mailbox when necessary to convert the messages in the mailbox (see "Access Required" below). -no_force, -nfc never alters your access to the mailbox. (Default) -privilege, -priv uses privileges to bypass the restrictions on the canonicalization process introduced by the Access Isolation Mechanism (see "Notes on AIM" below). -no_privilege, -npriv does not use privileges. (Default) ACCESS REQUIRED You must have status (s), modify (m), and append (a) access to the directory containing the mailbox. In addition, if -force is not specified, you must have read (r), add (a), and delete (d) extended access to the mailbox itself. 3-119 AG92-06 canonicalize_mailbox canonicalize_mailbox If -privilege is specified, you must have execute (e) access to the system_privilege_ gate. In addition, your maximum process authorization must be system_high. NOTES The canonical form of a message is similar to the text 01 me printed representation of that message when formatted using the default formatting modes. iviessages stored in mailboxes prior to :iviRl0.2 were not stored in their canonical form. Unless these messages are converted to their canonical form, subsystems, such as read_mail, that provide the option to select messages by content are required to format the messages during the search. This formatting while searching severely affects the performance of the selection process. Messages stored in a mailbox after the installation of MR10.2 are stored in canonical form and will not affect the performance of context searches. This command needs to be used only once on any given mailbox. Preferably, use this command on any large mailbox (e.g., logboxes or saveboxes containing more than fifty messages). This command first creates a new mailbox in the same directory as the mailbox whose messages are to be converted. The messages are then read from the original message, canonicalized, and stored in the new mailbox. Next. the names, access control list, maximum length, and safety switch setting of the original mailbox are moved to the new mailbox. Finally, the original mailbox is deleted. If the directory containing the original mailbox has insufficient quota for the new mailbox, the original mailbox is left intact and an error message is printed. The record of any process accepting messages on the original mailbox is lost during the canonicalization process. You must reissue the accept_messages command, if needed, for each mailbox that is processed by canonicalize_mailbox. Because of the nature of accept_messages, the explicit pathname of your default mailbox (>udd>Project_id>Person_id>Person_id.mbx) must be supplied if that mailbox is canonicalized in order to reaccept messages. After a mailbox has been canonicalized, all messages in the mailbox are owned by the user who issued canonicalize_mailbox. If you originally placed a message in the mailbox, you cannot delete it if you have own (0) extended access on the mailbox. Normally this canonicalization's side effect is invisible for logboxes and saveboxes as only the creator of the logbox or savebox has access on that mailbox. NOTES ON AIM If the Access Isolation Mechanism (AIM) is in force at a site, several restrictions are placed on the use of canonicalize_mailbox. These restrictions are eliminated through the use of -privilege provided that you have sufficient access to it (see "Access D ...",.~ ....,.A" Q,vv,,,,,,. ""'''''11.0\ ~'''''1u.u""" 3-120 AG92-Q6 canonicalize_mailbox ceil To use canonicalize_mailbox, your process authorization must be equal to the access class of the directory containing the mailbox whose messages are to be converted. Unlike ordinary segments, the access class of a mailbox may be greater than that of its containing directory. Each message in a mailbox has its own access class; the access class of the mailbox specifies the maximum access class for any message that may be added to the mailbox. If the access class of a mailbox is greater than your process authorization, it may contain messages that you cannot read. If you were to canonicalize that mailbox, any such messages would be lost Therefore, canonicalize_mailbox queries f or permission to continue if asked to process a mailbox whose access class is greater than the process authorization. Unless you are quite certain that there are no upgraded messages in the mailbox, answer "no" to this query and ask a system administrator to canonicalize the mailbox using -privilege. The canonicalized mailbox created by t.his command has an access class equal to your maximum process authorization. If this access class is less than the previous one, a warning is issued. If the new access class is insufficient (e.g., a mailbox shared by several users with different maximum authorizations), ask a system administrator to reclassify the mailbox via the reclassify_sys_seg command. Name: ceil SYNTAX AS A COMMAND ce i 1 num SYNTAX AS AN ACTIVE FUNCTION [ce i 1 nurn] FUNCTION returns the smallest decimal integer greater than or equal to its argument. EXAMPLES string [ceil 4.7] 5 ~Tr;~n _ ..... II:' rr~il __ I ' ~ -~~1 .,-j.J -3 3-121 AG92-06 Name: change_default_wdir, cdwd SYNTAX AS A COMMAND cdwd {path} FUNCTION records a s~~ified directory as your default working directory for the duration of the current process or until you issue the next change_default_wdir command. ARGUMENTS path is the pathname of a directory. If path is not specified, the current working directory becomes the default working directory. NotES· The change_default_wdir command is used in conjunction with the change_wdir command. When the change_wdir command is issued with no argument, the default working directory becomes the current working directory. The original default working directory is your horne directory upon logging in. See also the descriptions of the change_wdir and print_default_wdir commands. SYNTAX AS A COMMAND cern {-control_args} FUNCTION controls the amount of information printed by the default handler for system conditions. CONTROL ARGUMENTS -brief. -bf prints only the condition name. -long, -lg prints more complete messages. In particular, if the condition was detected in a 3-122 AG92-o6 support procedure, the name of that procedure is printed besides the name of the most recent user procedure. If a segment that signaled a condition (or caused it to be signaled) is bound, both the offset relative to the base of the procedure and the offset relative to the base of the segment are printed. NOTES If you don't issue cern or issue it with no control arguments, you receive default length error messages. These messages are intermediate in length between the brief and long messages. For a complete discussion of conditions and their handling see the Programmer's Reference Manual. See the reprint_error command for a similar, but more selective, capability. Name: change_wdir, cwd SYNTAX AS A COMMAND cwd {path} FUNCTION changes your working directory to the directory specified as an argument ARGUiviEtvTS path is the patbname of a directory. directory is assumed. If you supply no path, the default working ACCESS REQUIRED You must have s permission on the directory containing path. NOTES A working directory is a directory in which your activity is centered. Its pathname is remembered by the system so that you need not type the absolute pathname of segments inferior to that directory" If path specifies a nonexistent directory, an error message is printed on your terminal and the current working directory is not changed. 3-123 AG92-06 You don't need access to path to use change_wdir. However, once the working directory has been changed, you can proceed only according to your access to path. That is, to effectively use path as a working directory, you must have sma access permission for path. However, restricted uses are possible in accordance with the access mode attributes on the directory. For example, you must have at least status permission to list the directory. See also the change_default_wdir and print_default_wdir commands. SYNTAX AS A COMMAND cfsd {path} {-control_args} FUNCTION finds damaged segments and connection failures. ARGUMENTS path is a pathname specifying what is to be checked. It can be a star name, an absolute or relative pathname, or -workin~dir (-wd). If you provide -subtree, path cannot be a star name (i.e., it must be a directory). If you give no path, you must supply -pathname. CONTROL ARGUMENTS -brief, -bf suppresses error messages about incorrect access to directories and no star name matches. (Default: to print these messages) -call STR executes "STR path damaged" for each damaged segment and "STR path connection_failure" for each connection failure. STR is a command to be executed for each damaged segment. (Default: if you don't give -call, to print an error message for each damaged segment and each connection failure) -depth N, -dh N looks only N directories down; if you supply it, -subtree is implied. (Default: to search downwards in all directories that are eligible for searching) 11/86 3-124 AG92-Q6A -multisegment_file, -msf checks components of MSFs. (Default) -no_multisegment_file. -no_msf does not check components of MSFs. -pathname path, -pn path specifies that the next argument is to be used as a pathname rather than as a controi argument. 11/86 3-124.1 AG92-06A This page intentionally left blank. 11/86 AG92-06A -subtree. -subt checks all segments in, and all directories below, the specified directory. EXAMPLES The command line cfsd >udd>Proj>CLDCarrol checks the directory >udd>Proj>CLDCarrol to see if the directory is damaged. The command line cfsd >udd>Proj>GJCasanova -subt -msf starts at >udd> Proj>GJCasanova looking for damaged segments, directories, or MSF components, continuing down the directory hierarchy until the bottom is reached. The command line cfsd >udd>Proj -dh 2 checks, only for damaged segments. the project directory >udd>Proj and the directories directly underneath it Name: check_iacl SYNTAX AS A COMMAND check_iacl {path} {-control_args} FU,VCTION lists segments whose access control lists (ACLs) disagree with the initial ACL for segments (for a description of ACLs, see the Programmer's Reference ManuaI). ARGUMENTS path is the pathname of the directory whose segment ACLs are to be checked against the segment initial ACL. If you omit path, the working directory is assumed. 3-125 AG92-()6 CONTROL ARGUMENTS -all. -a lists User_ids in a segment ACL excluded from the initial ACL and User_ids included in the initial ACL but omitted from a segment ACL. If you give no -all, only User_ids in addition to those in the initial ACL are listed. -exclude User_id. -ex User_id exciudes the specified User_io irom the comparison. You can supply up to 10 -exclude control arguments. You can use the star convention. EXAMPLES check_iacl oldMap.com.runoff ACt added_: _rew__ James. Demo. * ACL added: rew Stevenson.Work.* add_search.com.runoff ACL added: rew James.Demo.* SYNTAX AS A COMMAND cis {-control_args} SYNTAX AS AN ACTIVE FUNCTION [cis {-control_args}] FUNCTION prints a list of info segments modified since a given time. CONTROL ARGUMENTS -absolute_pathname, -absp prints or returns absolute pathnames of segments rather than entrynames. -brief, -bf does not print either the ~~No change" message or, if used with -call, the names of changed info segs. Don't use -brief with the active function. 3-126 AG92-o6 -call cmdline calls the command processor with "cmdline path" for each changed segment; path is___ the __ absolute pathname of.a changed- segment- If-cmdline-contains- bl-anks.itmust be enclosed in quotes. Don't use -call with the active function. -date DT, -dt DT uses the date Dr instead of the date in your default value segment The date in the value segment is not updated. See Section 1 for a description of valid DT values. -long, -lg prints the date-time-entry-modified as well as the segment name. Don't use -long with the active function. -no_update, -nud does not update the date in your value segment -pathname star_path, -pn star_path checks all segments that match star_path, which is a pathname with a star name in the entryname portion. You can supply more than one -pathname. If you give none, the directories in the "info_segments" ("info_segs", "info") search list are used; **.info is used as the entryname= -time_checked, -tmck prints the date-time that is stored in your default value segment indicating from when checking of modified info segments occurs if -date is not given. This c.ontrol argt.L.1llent is i..'1compatible \-'/ith all others when used with the active function. It does not update the time in your value segment when it is the only control argument NOTES The first time you invoke cis, it sets the date in your default value segment. The value segment is created if one does not exist and is normally >udd>Project_id>Person_id>Person_id.value but can be changed by the value_set_path command. For links that match the star names, the date-time-entry-modified of the link's target is checked rather than that of the link itself. Zero-length info segments are not reported as being modified. The cis active function returns entrynames of selected info segments separated by spaces. If you give -absolute_pathname, it returns full pathnames of info segments separated by spaces. 3-127 AG92-()(j clock WARNING Since the cis active function also sets the date in your default value segment, a command line using [cis] sets this date before processing any of the returned info seg names; As a result, segments can be unintentionally skipped and not seen a second time if a command line containing [cis] is interrupted. Name: clock SYNTAX AS A COMMAND clock time_format {time_string} {control_args} SYNTAX AS AN ACTIVE FUNCTION [clock time_format {time_string} {control_args}] FUNCTION returns a string whose content time_format string. is entirely controlled by specifications in the ARGUMENTS time_format an ioo_-like control string describing the desired result in terms of literal characters and/or date/time selectors. (See Section 1 for a description of time_format> time_string indicates the date about which information is desired. If you supply no time_string, the current date is used. The time string is concatenated to form a single argument even if it contains spaces; you need not quote it (See Section 1 for a description of valid time_string values.) CONTROL ARGUMENTS -language STR, -lang STR STR specifies the language in which month names, day names, and zone names are to be expressed. (Default: the process default) -zone STR STR specifies the zone to be used to express the result. default) 3-128 (Default: the process AG92-06 clock NOTES Use the print_time_defaults command to display the default language and zone. Use the display_time_info command to display a list of all acceptable language and zone values. SYNTAX AS A COMMAND cf {filenames} {-control_args} FUNCTION closes the specified files belonging to the specified language(s). ARGUMENTS filenames are the names of files opened by the specified language(s). CONTROL ARGUMENTS -all, -a cioses all open files that belong to the speciiied language(s). filename appears. in this case no -language SlR -lang STR specifies that files belonging to language STR are to be closed. STR is the unabbreviated name of the language's compiler (e.g.. pascal) and can be any language that supports the file-closing subroutine interfaces. If you give no -lang, it closes all open FORTRAN, Pascal, and PL/I files. NOTES The format of a FORTRAN file name is fileNN. where NN is a two-digit number other than 00; e.g., fHe05. PL/I and Pascal file names are selected by you and can have any format. If a specified file cannot be found. an error message is printed indicating the name of the file. The rest of the specified files are closed. For each filename. all files of that name belonging to the specified language(s) are closed. The command "close_file -an does not affect I/O switches that are not associated with FORTRAN. Pascal, or PL/I files. 11/86 3-129 AG92-06A cobol cobol Name: cobol SYNTAX AS A COMMAND cobol path {-control_args} FUNCTION invokes the COBOL compiler to translate a segment containing the text of a COBOL source program into a Multics object segment A listing segment can also be produced. These segments are placed in your working directory. You can't call this command recursively. ARGUMENTS path is the pathname of a COBOL source segment to be translated by the COBOL compiler. If path does not-have the .cobol suffix,oneis assumed;- however that suffix must be the last component of the name of the source segment CONTROL ARGUMENTS -brief, -bf causes error messages written to the user_output I/O switch to contain only an error number and statement identification, once the full message has been given on the first occurrence. In the normal, nonbrief mode, an explanatory m.essage is prin ted for each occurrence. -card meaningless trailing blanks are removed from a standard fixed format COBOL source program in card image format Characters in the identification field (columns 73-80) are ignored. -check, -ck is used for syntactic and semantic checking of a COBOL program. No code is generated. -expand. -exp a standard fixed format COBOL source program that possibly contains COpy and REPLACE statements is translated into an equivalent source program that does not contain these statements. -format, -fmt pseudo-free form COBOL source program is translated into a standard fixed format COBOL source program. For details concerning pseudo-free format see the expand_cobol_source command. 3-130 AG92-06 cobol cobol -levelNM, -levNM causes L-type diagnostics at severity M to be written to the user_output switch whenever a COBOL source line contains a language construct outside the subset specified -byN . ---The-value -- M -can- --be- ---one---tlitougB. - tliree- ailif --specifies - "tlie seveTi ty of the diagnostic. If M is omitted, severity 3 is assumed. The value N can be one through five, corresponding to the four levels specified by the Federal Information Processing Standards Publication, December 1. 1975 (FIPS PUB 21-1) and to the extended version of COBOL supported by Multics. These values are 1 2 3 4 5 low level low intermediate level high intermediate level high level Multics COBOL extensions If a program compiles without any L-type diagnostics, it means the program is an acceptable subset of Multics COBOL at the level requested. The default is level 5. -list, -ls produces a source program listing with symbols, followed by an assembly-like listing of the compiled object program. Use of the -list control argument significantly increases compilation time and should be avoided whenever possible by using the -map control argument -map produces a source program listing with symbols, followed by a map of the object code generated by this compilation. The -map control argument produces sufficient information to allow you to debug most problems online. -no_table, -ntb suppresses the generation of a full symbol table for use by symbolic debuggers. -profile, -pf generates additional code to meter the execution of individual statements. Each statement in the object program contains an additional instruction to increment an internal counter associated with that statement After a program has been executed, the profile command can be used to print the execution counts. -runtime_check, -rck produces an object program in which parameters are validated according to number and type, performs bounds checking on all subscripted referenced, performs string range checking on all variable length string references, and verifies the validity of every index name modification. -severityN, -svN causes error messages whose severity is less than N (where N is 1. 2, 3, or 4) to not be written to the user_output I/O switch. All errors are written into the listing. If this control argument is not given, a severity level of 2 is assumed. See the description of severity levels under "Notes on Error Diagnostics" below. 3-131 AG92-D6 cobol cobol -table, -tb generates a full symbol table for use by symbolic debuggers. The symbol table is part of the symbol section of the object program and consists of two parts -- a statement table that gives the correspondence between source line numbers and object locations and an identifier table that contains information about every identifier actually referenced by the source program. The table appears in the symbol section of the object segment produced by the compilation. This control argument usually causes the object segment to become significantly longer. If the -format. -expand or -card control argument is given with the -table control argument, the symbolic debuggers are not able to display the source statements. (Default) -temp_dir path, -td path creates the compiler's internal work files in the specified directory rather than in the process directory. This control argument may be necessary for very large source files (over approximately 3000 lines) that incur record quota overflow in the process directory during compilation. -debug, -db leaves the work files generated by the compiler intact after a compilation. This control argument is used for debugging the compiler. The command cobol$clean_up can be used to discard these files. Also, this causes severity 4 errors to not unwind and abort the compilation, but rather to invoke a new level of the command processor at the point of the error. -time, -tm prints the time (in seconds) and the number of page faults taken by each phase of the compiler; prints the totai time at the end of the compilation. This information is directed to the user_output I/O switch. NOTES The only result of invoking the cobol command without control arguments is to generate an object segment containing a full symbol table. A normal compilation produces an object segment and leaves it in directory. If an entry with that name already exists in the directory, its list (ACL) is saved and given to the new copy of the object segment; are given re access to the segment with ring brackets v,v,v where v is level of the process that is active when the object segment is created. your working access control otherwise you the validation If you specify the -map or -list control arguments, the cobol command creates a listing segment in the working directory and gives it a name consisting of the entryname portion of the source segment with a suffix of list rather than cobol (e.g., a source segment named business. cobol would have a listing segment named business.list). The ACL is set as described for the object segment except that you are given rw access to it when newly created. Previous copies of the object segment and the listing segment are replaced by the new segments created by the compilation. 3-132 AG92-06 cobol cobol The control arguments -format, -card and -expand cause the source program to be pre-translated before compilation. The transformations available are a subset of the transformations available by using the expand~cobol~so-urce· command~ - -The translated source program is placed in your process directory with the suffix ex. cobol. Thus compiling name. cobol produces the segment [pd] >name.ex.cobol. If the segment being compiled has the suffix ex.cobol then these control arguments are ignored. The control arguments -format and -card are inconsistent but either can be used in combination with the control argument -expand. The control argument -expand must be used if the source program contains COpy and REPLACE statements. For information on COBOL, see the Multics COBOL User's Guide (AS43) and the Multics COBOL Reference Manual (AS44). See also the description of the profile command. NOTES ON ERROR DIAGNOSTICS The COBOL compiler can diagnose and issue messages for about 800 different errors. These messages are graded in severity as follows: 1 Warning only. Compilation continues without ill effect 2 Correctable error. The compiler attempts to remedy the situation and continues, possibly without ill effect The assumptions the compiler makes in remedying the situation. however, do not necessarily guarantee the right results. 3 Uncorrectable but recoverable error. That is. the program is definitely in error and no meaningful object code can be produced, but the compiler can continue executing and diagnosing further errors. 4 Unrecoverable error. The compiler cannot continue beyond this error. A message is printed and control is returned to the cobol command. The command writes an abort message on the error_output I/O switch and returns to its caller. indicated above, you can set the severity level so as not to be bothered by minor error messages. You can also specify the -brief control argument so that the message is shorter. Since the default severity level is 2, you must explicitly specify the -severity1 (or -svl) control argument when invoking the cobol command to have warning messages printed. Neither the -severityN nor -brief centrol argument has any effect on the contents of the listing segment if one is produced. As 3-133 AG92-06 cobol An example of an error message in its long form is 22 ** use after error procedure on extend. 1 5-250 A use procedure has already been associated with this processing mode. If the -brief control argument is specified and message 5-250 has previously been given in its long form, you instead see 22 use after error procedure on extend. 1 If you have set the severity level to 3, no message is printed at all. Notice that the number of asterisks immediately preceding the error indicator corresponds to the severi ty--Ievel of ---the error.If a listing is produced, the error messages appear interspersed with the lines of the source program. No more than 300 messages are printed in the listing. NOTES ON LISTING The listing created by the cobol command is a line-numbered image of the source segment with diagnostics interspersed. This is followed by a cross-reference table of all the names defined within the program. Following the cross-reference table is the object code map. which gives the starting location in the text segment of the instructions for each statement in the program. The map is sorted by ascending storage locations. Finally, the listing contains an assembly-like list of the object code produced. The executable instructions are grouped under an identifying header, which contains the source statement that produced the instruction. Opcode, pointer-register, and modifier mnemonics are printed alongside the octal instruction. If the address field of the instruction uses the Ie (self-relative) modifier. the absolute text location corresponding to the relative address is printed on the remarks field of the line. Name: cobol_abs, cba SYNTAX AS A COMMAND cba paths {-cobol_args} {-dp_args} {-control_args} FUNCTION submits an absentee request to perform COBOL compilations. The absentee process for which cobol_abs submits a request compiles the segments named and prints and deletes the listing segment 3-134 AG92-06 ARGUMENTS paths are the pathnames of segments to be compiled. cobol_args can be one or more control arguments accepted by the cobol command. dp_args can be one or more control arguments (except -delete, -dI) accepted by the dprint command. CONTROL ARGUMENTS -queue N, -q N is the priority queue of the request. The default queue is defined by your site. (See "Notes" for a description of the interaction with the dprinting of output files.) -hold, -hd specifies that cobol_abs should not print or delete the listing segment. -limit N, -li N places a limit on the CPU time used by the absentee process. The parameter N must be a positive decimal integer specifying the limit in seconds. The default limit is defined by the site for each queue. An upper limit is defined by the site for each queue on each shift. Jobs with limits exceeding the upper limit for the current shift are deferred to a shift with a higher limit. -output_file path, -of path specifies that absentee output is to go to the segment whose pathname is path. NOTES Control arguments and segment pathnames can be mixed freely and can appear anywhere on the command line after the command. All control arguments apply to all segment pathnames. If an unrecognizable control argument is given. the absentee request is not submitted. Unpredictable results can occur if two absentee requests are submitted that could simultaneously attempt to compile the same segment or write into the same absout segment. When doing several compilations, it is more efficient to give several segment pathnames in one command rather than several commands. With one command, only one process is set up. Thus the dynamic intersegment links that need to be snapped when setting up a process and when invoking the compiler need be snapped only once. 3-135 AG92--D6 collate9 If the -output_file control argument is not specified, an output segment, path.absout, is created in your worktng directory (if more than one path is specified, only the first is used). If none of the segments to be compiled can be found, no absentee request is submitted. If the -queue control argument is not specified, the request is submitted into the deiauli absenree priority queue deiined by the site and, if requested, the output files will be dprinted in the default queue of the request type specified on the command line. (If no request type is specified, the "printer" request type is used.) If the -queue control argument is specified, and, if requested, the output files will be dprinted in the same queue as is for the absentee request If the request type specified for dprinting does not have that queue, the highest numbered queue available f or the request type is used and a warning is issUed. Name: collate SYNTAX AS A COMMAND co 11 ate SYNTAX AS AN ACTIVE FUNCTION [co 11 ate] FUNCTION returns the 128 characters of the ASCII character set in collating sequence. Name: collate9 SYNTAX AS A COMMAND co 11 ate9 SYNTAX AS AN ACTIVE FUNCTION [co 11 ate9] 3-136 AG92-06 collate9 FUNCTION returns a character string containing all possible nine-bit bit patterns rather than just the 128 ASCII characters, theref ore making the returned string 512 characters long. SYNTAX AS A COMMAND comp_dir_info pathl path2 {-control_args} FUNCTION compares two directory information segments created by save_dir_info and reports on the differences. ARGUMENTS path1 is the pathname of the old directory information segment If the dir_info suffix is not supplied, it is assumed. path2 is the pathname of the new directory information segment If the dir_info suffix is not supplied, it is assumed. CONTROL ARGUMENTS -brief, -bf compares and prints minimum information. -long, -lg compares and prints all information. -verbose, -vb compares and prints almost all information. (Default) NOTES Output from the comp_dir_info command is written on the user_output I/O switch. Unless the -brief control argument is specified, a form feed character is transmitted and then a heading is printed that identifies the directories being compared and the times the information was saved. Output is in three sections: 3-137 AG92-06 modif ied en tries deleted entries added en tries and is identified by entry type (dir. seg, or link) and the entryname. For deletions and additions, a heading of the form: deleted: entry entryname is printed, followed by a listing of the attributes of the deleted or added entry, in the format: item_name: value For' segments that have been modified, a heading of the form: modified: entry entryname is printed, followed by a line of the following formats: item_name changed from value1 to value2 item_name added: value (The second format is used to report the addition or deletion of names, ACL entries, etc.) The list below shows the output items according to the control argument and entry type. The control arguments are listed in order of their verbosity; i.e., the -brief (-bf) control argument prints out the least information, the -verbose (-vb) control argument prints out more information (including the "-bf" items), and the -long (-lg) control argument prints out all of the items listed. segments: -bf names ring brackets damaged switch property list deletion of ACL truncation -vb safety switch -lg copy switch tpd switch no_complete_dump_switch no_incremental_dump switch security OOS switch author bit count author date modified volume bit count entry point bound ACL audit flag mUILlclass switch access class date branch modified records used max length 3-138 AG92-06 directories: -bf names ring brackets damaged switch property list deletion of ACL sons volume master dir quota MSF indicator -vb safety switch -lg date branch modified copy switch date modified tpd switch no_complete_dump_switch no=incremental_dump switch security DOS switch author bit count author ACL audit flag multiclass switch access class initial seg ACL initial dir ACL links: -bf names type 1 ink target -vb date link modified -lg link dumped When looking for a match between the old and new dir_info segments, the comp_dir_info command looks first for a match on the unique ID item. If no match is found, it looks for any entry with a name matching the primary name of the old entry. If a match is found, the comp_dir_info command checks a set of items (depending on the specified control argument) to determine whether to report the entry as modified. The names item is always checked. The date dumped and date used items are never compared. Other checking is dependent upon the control argument If comp_dir_info completes a pass wit...1J.ou.t finding any modifications, deletions, Of additions, it prints "Identical". Invoking the command with a more verbose control argument can detect some changes. 3-139 AG92-G6 compare compare Name: compare SYNTAX AS A COMMAND compare pathl{loffsetl} path2{loffset2} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [compare pathl{!offsetl} path2{!offset2} {-control=args}] FUNCTION compares two files (segments, multisegment files, or archive components) and lists their differences. The comparison is a word-by-word check and can be made with a mask so that only specified parts of each word are compared. The active function returns true if the compared portions are identical, false otherwise. ARGUMENTS .path!, path2 are the pathnames of the files to be compared. The equal convention is allowed for path2. Either can be an archive component pathname. offsetl. offset2 are octal offsets within Ule files if Lltey are segments or archive components. If you omit them~ the entire contents are compared. The comparison begins at the word specified or at the first word of the segment if you specify no offset CONTROL ARGUMENTS -brief; -bf prints only the first and last words of each block of discrepancies that is four or more words in length (see "Notes"). -inhibit_error, -ihe causes the active function to return "false" rather than produce an error if one of the files to be compared does not exist An error still occurs if neither file exists. -length N, -In N makes the comparison continue for no more than N (octal) words. -long, -lg prints all discrepancy words (see "Notes"). (Default) -mask N uses the octal mask N in the comparison. If N is less than 12 octal digits, it is padded on the left with zeros. 3-140 AG92-06 compare compare -no_inhibit_error, -nihe suppresses the effect of -inhibit_error. -short, -sh prints a single line for each block of discrepancies: 120 words at: 1631 1100 words at: 33404 (See "Notes. tt) -totals, - tt prints a single line for the entire comparison: 17 differences, 3140 words total. NOTES The maximum number of words to be compared is the word count of the first segment minus its offset or the word count of the second segment minus its offse~ whichever is greater. If you supply -length. comparison stops after the specified number of words. If the segments are of unequal length, the remaining words of the longer segment are printed as discrepancies. The word count of a segment is computed by dividing the bit count plus 35 by 36. If the word count minus the offset is less than zero~ an error message is printed and the command is aborted. Any discrepancies found by the command are listed in the following fonnat: offset 4 6 contents 404000000002 404000000023 offset 4 6 contents 000777000023 677774300100 To compare segments containing only ASCII character string data, use the compare_ascii command. Multisegment files (MSFs) are compared component by component, with headers of the form "Component :". Excess components of the longer MSF are listed, the same as for excess words in a longer segment When a segment is compared to an MSF. a header of the form "Segment/component 0:" or "Component O/segment" is printed at the beginning. You can't use -brief, -long, and -short in the active function. 3-141 AG92-06 Name: compare_ascii, cpa SYNTAX AS A COMMAND cpa paths {-control_args} FUNCTION An exec_com tool called compare_pll compares PL/I source segments of dissimilar formats via the format_pll command (see compare_pll). ARGUMENTS paths are the pathnames of the segments to be compared. The equals and archive component pathname conventions are allowed. Up to six segments can be compared. in addition to the original if one is supplied. The equal convention can be used in any pathname except the first one on the command line, which is assumed to be the original unless otherwise specified. CONTROL ARGUMENTS -extend when -output_file is given. the output is appended to the output file if it already exists. (Def ault) -header, -he prints a heading. giVlng the full path name and identifying letter of each segment This heading is not printed by default -minchars NN specifies the minimum number of characters that must be identical for compare_ascii to assume that it has found the end of a difference (see "Notes"). (Default: 20) -minlines NN specifies the mlnlmum number of lines that must be identical for compare_ascii to assume that it has found the end of a difference (see "Notes"). (Default: 2) -no_header. -nhe does not print the header information. (Default) -no_numbers. -nnb does not print identifying letter and line numbers preceding the lines from the segments being compared. (Default: to print them) 3-142 AG92-06 -no_original, -no_orig indicates that no original segment is supplied. If neither -no_original nor -original is given, the first pathname on the command line is assumed to be the original. -no_output_file, -nof specifies Ll}at output is to be printed on the terminal. (Default) -no_totals, -ntt does not print the totals line. -original pathA, -orig pathA specifies the pathname pathA of the original segment of which the others are modif ied versions. -output_file path, -of path directs the output of the comparison to the file specified by path. The equal convention is allOWed, and is applied to the original path. -print_new_lines, -pnl prints only new lines. New lines are lines found in one or more of the modified versions but not in the original. An original must be supplied if this argument is used. -totals, -tt prints only the totals line, giving the number of differences and the number of changed lines. (Default: to print discrepancies and the totals line) -truncate, -tc specifies that the output file be truncated before the comparison is written into it. NOTES The output is produce pathB. identifies each letter A or B pathB). organized with the assumption that the pathA segment was edited to This command prints lines that were added, replaced, or deleted; it line by line number within the respective segment and also by the to indicate which segment the line is from (A for pathA and B for Values for minchars and minlines can be specified without being preceded by control arguments. The order is: minchars minlines. The values of minchars and minlines control the size of displayed differences. Large values for these parameters cause small, closely-spaced differences to be displayed as one large difference, while very small values (such as -minlines 1 -minchars 2) will cause small changes to be displayed individually but might also cause large differences to be broken down into small parts, thereby giving a misleading picture of what was actually done to produce the modified versions. The user should adjust these parameters to produce the most useful results. 3-143 AG92-()6 EXAMPLES The examples of compare_ascii usage below are based on the segments yesterday. menu and today. menu displayed here side by side. yesterday.menu today.menu Breakfast Menu: Breakfast Menu: I •. ! _ _ I •• : __ ,",UI~t: '"'U 1 \.ott:: Toast Eggs Luncheon Menu: Hot dogs Mi 1k French fries Supper Menu: Toast Eggs Luncheon Menu: Hamburger Mil k Salad French fries Svpper.M~n~: Stea.k . Baked potato Coffee Chicken Rice Coffee The default operation of compare_ascii is illustrated by the command line: cpa yesterday.menu today.menu A6 Hot dogs A7 Mi 1k Changed by B to: Hamburger B6 Mil k B7 Salad 88 A10 Steak A11 Baked potato Changed by B to: B11 Chicken B12 Rice Comparison finished: 2 differences, 9 lines. 3-144 AG92-06 The following command line shows the use of the -original, -header. -minlines, and -minchars control arguments. Notice that the lower values of minlines and minchars isolate the two changes within the Luncheon menu. cpa today.menu -orig yesterday.menu -he -minchars 5 -minlines 1 A >udd>m>Jones>yesterday.menu (original) B >udd>m>Jones>today.menu (new) A6 Hot dogs Changed by B to: B6 Hamburger Inserted in B: B8 Salad Preceding: A8 French fries Steak A10 All Baked potato Changed by B to: B 11 Chicken B12 Rice Comparison finished: 3 differences, 7 lines. In the following example the printing of line numbers, old lines. and the totals line have been suppressed. giving better visibility to what is new in today. menu. cpa yesterday.menu today.menu -pnl -nnb -ntt -minchars 5 -minlines 1 Hamburger Salad Chicken Rice 3-145 AG92-D6 compare_con figuration_deck compare_configuration_deck Name: compare_configuration_deck SYNTAX AS A COMMAND compare_configuration_deck pathl {path2} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [compare_configuration_deck pathl {path2}] FUNCTION compares either a saved copy of the configuration deck or the configuration deck for the running system to a saved copy. As an active function, returns either "true" or "false" to indicate whether the two configuration decks are equivalent. ARGUMENTS pathl is the pathname of a saved copy of the configuration deck. path2 is the pathname of a copy of the configuration deck to be compared against pathl. If not supplied, >sl1>confi!Ldeck (the configuration deck for the running system) is used. CONTROL ARGUMENTS -brief, -bf suppresses informational messages and printing of the identifying headers. -label, -lbl displays cards with mnemonic labels for each field. -long, -lg prints all output. (Default) -no_label, -nlbl does not display field labels. (Default) OUTPUT FORMAT (-LONG MODE) The long output format consists of up to four sections, each of which is printed WHn an identifying header if it is not empty. The four sections are added cards, deleted cards, changed cards, and mem cards. The section for mem cards is printed only if the order or number of mem cards in the two decks differs; otherwise only changed mem cards are printed. The changed cards are listed in pairs, such as: 3-146 AG92-06 compare_configuration_deck Was: mem mem a a 123. 123. on off The first line (prefaced by Was:) is the card from the saved deck and the second is the current card. If the two decks are different in order or number. this is announced and both decks are printed entirely. OUTPUT FORMAT (-BRIEF MODE) The brief output format omits the section headings and the message "The two decks are identical." Cards are identified by preface--added cards are prefaced by "New:" and deleted cards by "Old:". Changed cards are listed in pairs, in the same format as in the long output mode. If the mem cards section is printed, it is the last section. The mem cards are listed in two groups, with the first card in each group prefaced by Was: for the first group or Now: for the second group, and all the other cards in the group are listed with no preface. NOTES This command is fairly accurate when identifying "changed" cards--it knows about the cards (such as mem, cpu, etc.) that may appear several times and may specify multiple items and identifies them by their operands as well as by name. It decides that the two decks are completely different if there appear to be more than 32 differences between them. EXAMPLES OF LONG MODE OUTPUT Note that because the mem cards have been reordered the changed card for mem A is not listed in the changed cards section. Cards added in current deck: parm chwm dirw ttyb 7000. salv pdlv 1 Cards deleted from old deck: intk warm 3 star Changed cards: Was: cpu b 6 cpu b 6 off on mem cards are reordered: Was: mem a 258. on mem c 258. on mem b 258. on Now: mem c 258. on mem a 258. off mem b 123. on 3-147 AG92-D6 EXAMPLES OF BRIEF MODE OUTPUT This output is equivalent to the sample output for the long mode shown above. Old: New: Was: Now: Was: Now: salv intk cpu cpu mem mem mem mem mem mem pdlv 1 warm 3 star b 6 off b 6 on a 258. on c 258. on b 258. on c 258. on a 258. off b 123· on SYNTAX AS A COMMAND FUNCTION This command compares MuItics storage system hierarchy dump data on two sets of input tape; a master set and a copy set Options allow selective comparing based upon pathname specifications in a selection file, and comparing using a storage system file containing an image of a set of dump tapes, rather than tapes. CONTROL ARGUMENTS -abort indicates that comparing of the master with the copy should stop when the first discrepancy is found. -copy_file OUT_PATH, -cf OUT_PATH gives the pathname of a copy file to be compared with the master data. -copy_volume VOLNAMES, -evol VOLNAMES gives a list of tape volume names. The master data is compared with this copy tape volume set. The names are separated from one another by a blank. Up to 20 voiume names can be given. This control argument may be followed by the control arguments described below in .tControl arguments for volume attribUtes". x 11/87 3-148 AG92-06B -master_file IN_PATH. -mf IN_PATH gives the pathname of a file containing an image of the backup dump tape. This file must have been created by a prior invocation of copy_dump_tape. It contains the master data to be copied. -master_volume VOLNAMES. -mvol VOLNAMES gives a list of tape volume names containing the master data to be copied. The names are separated from one another by a blank. Up to 20 volume names can be given. This control argument may be followed by the control arguments described below in "Control arguments for volume attributes". -maximize_devices. -maxdv indicates that all tape drives reserved by the process or assigned to the process are to be used equally (round-robin) when mounting tapes. -no_abort, -nabort indicates that comparing master and copy should continue when errors are encountered, un til 20 discrepancies are found. This is the def aul t -no_maximize_devices. -nmaxdv allows RCP to select which tape drives to use when reading tapes. This is the default. -no_select. -nslct indicates that all master data is to be compared with copy data. This is the default -no_trace. -ntrace prevents tracing information from being printed. This is the default -select SELECT_PATH, -slct SELECT_PATH gives the pathname of a fHe similar to a standard backup_dump control file. This file gives paths of master files to be selected for comparison. See "Notes on control file." =trace {TYPE} controls printing of trace information while comparing. This information is primarily used for debugging compare_dump_tape. See "List of trace types". CONTROL ARGUMENTS FOR VOLUME ATTRIBUTES The following control arguments define attributes of tape volumes given in preceding -master_volume or -copy_volume control argument 11/87 3-149 AG92-{)6B compare_dump_tape -density DEN, -den DEN gives a tape density. DEN may be 800, 1600 or 6250. The input tapes are mounted on a tape drive capable of reading density DEN. However, the actual density at which the input tapes are written determines the density used for reading. The default density is 1600 BPI (bits per inch). -track TK, -tk TK mounts tapes on a tape drive capable of handling tapes containing TK tracks. TK may be 7 or 9. The default track size is 9. LIST OF TRACE TYPES One of the following trace types may be given as an operand with the -trace control argument. These arguments control the type of trace information printed. If any tracing is enabled, then attach descriptions are printed in addition to the segment information described below. compare, cmp during the compare operation, trace master segments selected by paths in the -select file. This is the default if -trace is specified without a TYPE operand. off turn off tracing. This is equivalent to -no_trace. rejects, reject, rej print master segments unmatched or rejected by paths in the -select file. LIST OF SEVERITY VALUES compare_dump_tape sets an external variable to indicate the success or failure of copy and compare operations. This variable may be examined using the severity command/active function. For example: &goto RESULT_& [severity compare_dump_tape] The following severity values can be returned. o The compare operation completed successfully. 2 The compare operation completed successfully, but one or more paths given in the -select file were not matched by master segments. These pathnames are listed in a message printed by compare=dump_tape. 3 The compare operation found discrepancies between master and copy segments. 11/87 3-149.1 AG92-06B compare_dump_tape 4 The compare operation failed, due to fatal errors. These errors are listed in error messages printed by compare_dump_tape. NOTES Either -master_file or -master_volume must be given to specify the source of master input data. Either -copy_file or -copy_volume must be given to specify the source of copy input data. NOTES ON CONTROL FILE The control file specified by -select is an ASCII segment containing pathnames of entries (segments, MSFs, and directory subtrees). Each pathname must be given on a separate line. Absolute pathnames must be given, with each entryname of the path being a primary name (the first name of the entry). Master entries matching one of the paths are compared. Master entries which are superior to one of the paths are also compared. If a path identifies a directory, master entries inferior to that directory are compared. A pathname preceded by a circumflex (A) character identifies entries which are NOT to be compared, unless later entries in the control file override the rejection. For example-- 1\ >library_dir_dir> hardcore >library_dir_air> hardcore>inf 0 >library_dir_dir> hardcore>inf0> hardcore.header selects all entries in the subtree below >lihrary_dir_dir>hardcore, except those in the info directory. However, the hardcore.header entry in the info directory is selected. 11/87 3-149.2 AG92-06B compare_en try_names Name: compare_entry_names, cen SYNTAX AS A COMMAND cen pathl path2 FUNCTION compares the names on two entries in the storage system and prints information about the diff erences. ARGUMENTS path 1 is the pathname of the first entry. You can't use the star convention. path2 is the pathname of the second entry. You can use the equal convention. 11/87 3-150 AG92-06B compare_object Name: compare_object, cob SYNTAX AS A COMMAND cob oldpath newpath {-control_args} FUNCTION compares two object segments and optionally prints out the changes made to the segment specified by oldpath to yield the segment specified by newpath. The assumption is that the first segment is older than the second and that they were both produced from the same source segment but, potentially, by different versions of a language processor. ARGUMENTS oldpath is the pathname of the first segment. newpath is the pathname of the second segment. You can use the equal convention. CONTROL ARGUMENTS -all, -a compares the text, definition, and linkage section of the two segments. segments have separate static sections, these are compared also. (Default) -brief, -bf prints out by section a summary of discrepancies suppressing detailed listing of the discrepancies. 11/86 3-150.1 in If the the object segments, AG92;,.06A This page intentionally left blank. 11/86 AG92-06A -defs compares the definition sections of the two segments. -link, -lk compares the linkage sections of the two segments. -static compares the static section of two segments with separate static; otherwise compares the linkage sections. -text compares the text sections of the two segments. NOTES If no control arguments are specified, the text, definition, and linkage sections of the two segments are compared. In comparing the lengths of the symbol sections of the two segments, the command uses a heuristic to determine whether a discrepancy is serious or trivial (e.g., caused by differences in pathnames of include files). This heuristic errs in the direction of caution and tends to be inaccurate for large object segments. Name: compare_pll, cpp SYNTAX ec >t>cpp pathl path2 FUNCTION The compare_pll exec_com compares two PL/I programs of dissimilar formats. ARGUMENTS path!, path2 are the relative or absolute pathnames of the source programs to be compared. The .pll suffix is assumed. The star convention is not allowed; the equal convention is allowed for path2. Archive component pathnames are allowed. NOTES All format_pll control comments are removed from both programs. Then, format_pll is used to put both programs into a canonical style. The compare_ascii command is used to see how the source programs differ. Vertical white space inserted or deleted between statements is not ignored. The line numbers in the compare_ascii output is not accurate due to possible white space or statements broken over lines. 3-151 AG92-06 component connect Name: component SYNTAX AS A COMMAND component path SYNTAX AS AN ACTIVE FUNCTION [component path] FUNCTION returns the archive component name portion of path after it has been expanded into an absolute pathname. If you don't supply an archive component pathname, then this command / active function is equivalent to entry. ARGUMENTS path is the pathname whose archive component name portion is to be returned. NOTES Since the pathname is returned in quotes. the command processor treats it as a single argument regardless of special characters in the name. EXAMPLES component >udd>Multics>Library>Source>bound_command_demos_os::program.pll program.pll component >udd>Proj>Myname>start_up.ec start_up.ec Name: connect SYNTAX AS A COMMAND connect channel {destination} {-control_args} FUNCTION permits you to access a remote system through a dial-out channel (see the dial_out command). 3-152 AG92-06 contents contents Name: contents SYNTAX AS A COMMAND contents path {-control_args} SYNTAX AS AN ACTIVE FUNCTION [contents path {-control_args}] FUNCTION prints or returns the contents of a segment or archive component as a character string. Newline characters in the segment are changed to blanks in the string. ARGUMENTS path is an absolute or relative pathname to the segment or archive component to be processed CONTROL ARGUMENTS -exclude /REGEXP /, -ex /REGEXP / does not print lines containing a string matching the regular expression REGEXP (see the qedx command). -exclude STR. -ex STR does not print lines containing STR. Exclusion is done after matching; thus, t'-match A -ex B" prints all lines with an A except those with a B. -from /REGEXP/, -fm /REGEXP/ begins with the first line matching REGEXP. -from No -fm N begins printing from the Nth line. (Default: 1) -match /REGEXP / prints only lines containing a string matching REGEXP. -match STR prints only lines containing STR. -newline. -nl leaves newline characters in the segment unchanged. -no_neWline, -nn1 changes newline characters in the segment to blanks in the string. (default) 11/87 3-153 AG92-()6B contents contents -requote_line, -rql requotes each line in the segment and changes newline characters in the segment to blanks. -to /REGEXP / stops printing with the first line matching REGEXP. The search for REGEXP begins after the first line printed. -to N stops printing with line number N. (Default: to print all lines) 11/87 3-153.1 AG92-06B con vert_characters maintains converted character character convert_characters a from_string and a to_string that define the conversion to be made. The segment is the same as the original except that every instance of the i'th of from_string present in the original segment is replaced by the i'th of to_string. The conversion for the key "sp" uses a from_string and to_string that must have been previously set by use of the "from" and "to" keys. ARGUMENTS key! any of the keys listed below in "List of keywords". oldpath the pathname of a segment to be converted. If this argument is omitted, the from_string and to_string related to key! are printed. newpath the pathname of the output segment. If this argument is omitted, newpath is assumed to be the same as oldpath, and the converted copy replaces the original. key2 either "to" or "from" to set to_string or from_string for the "sp" key. char_string is the string to be set as to_string or from_string. If it contains blanks, it must be enclosed in quotes. LIST OF KEYWORDS Ic converts alphabetic characters to lowercase. uc converts alphabetic characters to uppercase. mp converts from Multics PL/I format to IBM 360 PL/I. bcd converts BCD special characters to ASCII/EBCDIC equivalents. 3-154 AG92-06 convert_characters convert_characters char_string is the string to be set as from_string or to_string. If it contains blanks, enclose it in quotes. LIST OF KEYWORDS bcd converts BCD special characters to ASCII/EBCDIC equivalents. lc converts alphabetic characters to lowercase. mp converts from Multics PL/I format to IBM 360 PL/I. uc converts alphabetic characters to uppercase. 11/86 3-154.1 AG92-06A This page intentionally left blank. 11/86 AG92-06A convert_ec convert_characters dart converts Multics special characters to corresponding Dartmouth special characters as follows: > + " < > + " ? 1 sp uses conversion strings set earlier char_stringl;cvc to char_string2 by the from and to keys: cvc from NOTES The most recent setting of from_string and to_string in your process is used for conversion with the "sp" key. No conversion is attempted for the "sp" key unless both the from_string and the to_string are of the same non-zero length. Any character not present in the from_string is not changed. Name: eonvert_ee, evee SYNTAX AS A COMMAND cvec path {-control_args} FUNCTION Converts an exec_com from one version to another. By default, it converts a Version 1 (old version) exec_com to Version 2, inserting the line "&version 2" at the beginning. ARGUMENTS path is the pathname of an exec_com or absin segment. The ec suffix is added if neither suffix is present. The star convention is allowed. 3-155 AG92-D6 CONTROL ARGUMENTS -chase finds and chases links matching path if path is a starname. (Default: -chase if path is not a starname, -no_chase if path is a starname) -check, -ck prints warning and error messages but does not change the segment or produce an .......... +........ + UULPUL ~.:1 .... lU!I;;. -force, -fc in the absence of -output_file and -check, forces the original segment to be overwritten even if errors occur. (Default: to create a copy in the process directory if errors occur) -no_chase __ 4~ __ l1.()J __()~r~~e._QrLJill~~._ (~J::lult: ~~h_~ if path is not a~~r.n_~!!l:~. _-::~o_chase if path is a starname) -no_check, -nck converts the segment in addition to printing warning and error messages. (Default) -no_force, -nfc does not replace the original segment or create an output file with -output_file if errors (as opposed to warnings) occur. (Default) -output_file path. -of path places the converted segment in path instead of the original segment specified by path. The equal convention is allowed in path. If the output segment already exists. it is overwritten. If errors occur, the converted segment is placed instead in the process directory. -severity N, -sv N where N is a number from 0 to 3, suppresses warnings/errors with severities lower than N. The default is -sv 2. Severities are as follows: o 1 2 3 warnings requiring no conversion. warnings (nonstandard but valid syntax), such as unrecognized &strings converted to &&string. errors that can be converted. such as unrecognized &string at the beginning of a line converted to a comment errors that cannot be converted. ACCESS REQUIRED Read access on pathl, write access on the output file or append on the parent of the output file if the output file does not exist. 3-156 AG92-06 NOTES Use of -output_file is recommended rather than overwriting the original segment, so that original and converted copies can be compared. The simple conversion rules can, in complicated cases, change the intent of expressions. Therefore, a copy of the original should be kept until the converted exec_com has been shown to operate correctly. LIST OF CONVERSIONS (V1 -> V2) leading and trailing whitespace -> literals such as &SP this conversion is performed because Version 2 strips leading and whitespace from lines. trailing & -> &new comment sequence. &... & -> &&... && strings of two or more ampersands are doubled. &(. ..) -> &&<. .. ) unrecognized by Version 1, the construct on the left is used in Version 1 ec's to pass &(.. .) parameters to other programs. &NN -> &(NN) Version 2 requires parameters wiih iwo or more digits to have the digits enclosed in parentheses. &0, &qO -> &ec_path &rO -> "&ec_patb" new construct to get the expanded, suffixed pathname of the ec. &if [... ] -> &if [... ] the & [ ... J construct is uniformly required to expand active functions in control lines. &command_line... -> &trace &command... &comment_line... -> &trace &comment .. &control_line... -> &trace &control. .. &input_line... -> &trace &input. .. new tracing statement &trace. &unrecognized (beginning of line) -> &-&unrecognized comments entire line if begins with unrecognized keyword. &unrecognized -> &&unrecognized all other unrecognized Version 1 &keywords are converted to literals. 3-157 AG92-Q6 copy EXAMPLES The command line cvec >udd>m>Vivaldi>collect -of collect.v2 converts the exec_com >udd>m> Vivald1>collect.ec into Version 2 and places the Version 2 copy in collect v2.ec in the working directory. Name: copy, cp SYNTAX AS A COMMAND cp pathl {path2 ••. pathlN path2N} {-control_args} FUNCTION copies specified segments. multisegment files (MSFs). data management (DM) files. and extended entries in the specified directories with the speciiied names. Optionally it copies access control lists (ACLs) , ring brackets, and multiple names. ARGUMENTS path! is the pathname of a segment, MSF, DM file, and extended entry to be copied. If it is the name of a link, the command copies the target of the hnk. The star convention is allowed. (See "Notes" below.) path2 is the pathname of a copy to be created from pathl. If you don't give path2. the copy is placed in your working directory with the entryname of pathl." The equal convention is allowed. CONTROL ARGUMENTS -acl copies the ACL. -all, -a copies mUltiple names, ACLs, and ring brackets. -brieL -bf suppresses warning messages (see "Notes"). -chase copies the targets of links that match pathl (see "Notes" for the default). 11/87 3-158 .A.. G92-06B copy copy -extend appends the contents of pathl to the contents' end of path2. An error occurs if path2 does not already exist. -force. -fc with -extend or -update, forces writing of the file contents regardless of whether you have write access to path2; in all other cases (replacing the entire file), forces deletion of an existing path2. -long. -lg prin ts warning messages. (Def aul t) -name. -nm copies multiple names. -no_ac1 does not copy the ACL. (Default) -no_chase does not copy the targets of links that match pathl (see "Notes"). -no_force, -nfc does not force write without write access or force deletion of an existing path2. (Default) -no_name, -nnm does not copy multiple names. (Default) -no_rb, -nrb does not copy ring brackets. (Default) -no_rin~brackets. -replace, -rp replaces the entire file path2, rather than modifying its contents as is done by -extend and -update. (Default) -rb copies the ring brackets of pathl to path2. It is incompatible with -extend and -update. -rin~brackets, -update, -ud replaces the contents of path2 with those of pathl without deleting path2 or changing any of its attributes. An error occurs if path2 does not already exist. ACCESS REQUIRED You need read access for pathl; write access for path2, unless you use -force with -extend or -update; status permission for the directory containing pathl if you supply -acl, -all, or -name; modify permission for the directory containing path2 if you give -acl, -all, or -name; append permission for the directory containing path2 if you select neither -extend nor -update. 3-159 AG92-Q6 copy NOTES The control arguments can appear once anywhere after the command name and apply to the entire command line. The default for chasing links depends on pathl: if it is not a starname. links are chased by default; if it is a starname, links are not chased. The initial ACL of the target directory doesn't affect the ACL of the segment or multisegment file being copied. The AIM access class of a segment is not copied by -acl. Since two entries in a directory cannot have the same entryname, copy takes special action if the name of path1 already exists in the directory specified by path2: if path1 has an alternate name, the entryname that would have resulted in a duplicate name is removed, you are informed of this action, and the copying operation takes place; if path1 has only one en try name, the entry that already exists in the directory must be deleted to rem-ove the name, you are asked if the--detetion should be done, and the copying operation does not take place if you answer "no." This command prints a warning message if the bit count of path1 is less than its current length ("Bit count inconsistent with current length.. .'t) or if the current length is greater than the number of records used ("Current length is not the same as records used... n). EXAMPLES The command iine copy >old_dir>fred.list george.= copies segment or multisegment file named fred.list in the directory >old_dir into the working directory as george.1ist Name: copy _acl SYNTAX AS A COMMAND copy_acl pathl path2 ••. pathlN {path2N} FUNCTION copies the access control list (ACL) from one segment, directory, multisegment file, data management file, or extended entry to another. replacing the current ACL if necessary. (For a description of ACLs, see the Programmer's Reference ManuaL) 3-160 AG92-06 copy_acl ARGUMENTS path1 is the pathname of a file or directory whose ACL is to be copied. You can specify your working directory with -workins-directory (-wd). The star convention is allowed. path2 is the pathname of a file or directory into which the initial ACL is to be copied. You can specify your working directory with -workins-directory (-wd). The equal convention is allowed. ACCESS REQUIRED You require status permission for the containing directory of path1 and modify permission for the containing directory of path2. Name: copy_cards, ccd SYNTAX AS A COMMAND FUNCTION copies specified card image segments from system pool storage into your directory. The segments to be copied must have been created using the Multics card input facility. ARGUMENTS deck_name is the name that was entered on the deck_id card when the card deck was submitted for reading. The star convention is allowed. new_deck_name is the pathname of the segment in which the matching card image segment is to be placed. If omitted, your working directory and deck_name are assumed. The equal convention is allowed. NOTES See the description of the card input facility in the Programmer's Reference Manual for the format of the control cards needed when submitting a card deck to be ready by system operations. The user process executing this command must have the proper access to the card image segment in order to perform the copy. When there are multiple copies of the same deck in pool storage, all are copied. 3-161 AG92-o6 copy_cards copy_characters When deck_name is a starname and there are several matching card image segments in pool storage to which you have access, all are copied. When an attempt is made to read a card deck having the same name as some previously read deck still in pool storage, a numeric suffix is added to the name of the new deck, e.g., "deck_name. 1". Repp..ated name duplications cause successively larger numeric suffixes to be used. (Name duplications can only occur f or decks of the same access class submitted by the same user.) This command informs you of such duplications (if any) and retrieves all copies of the specified deck. Only those card decks having an access class equal to your current authorization can be copied. Other decks are not found. EXAMPLES The command line ccdmy~deck- copies your card image segment named my_deck from the card pool storage into your current working directory. Name: copy_characters, cpch SYNTAX AS A COMMAND cpch STR N SYNTAX AS AN ACTIVE FUNCTION [cpch STR N] FUNCTION returns a quoted string containing N copies of a specified string. EXAMPLES string [cpch 111 2 3 II 3] 123 1 231 2 3 3-162 AG92-o6 copy_dir Name: copy_dir, cpd SYNTAX AS A COMMAND FUNCTION copies a directory and its subtree to another point in the hierarchy. You can also specify which portions of the subtree be copied and can control the processing of links. ARGUMENTS source_dir is the pathname of a directory to be copied. The star convention is allowed to match directory names. Matching names associated with other storage types are ignored. The source_dir can not be contained in target_dire target_dir is the pathname of the copy of the source_dire The equal convention is allowed. If target_dir is not specified. the copy is placed in the working directory with the entryname of source_dire If the target_dir does not exist, it is created. CONTROL ARGUMENTS -acl gives the ACL on the source_dir entry to its copy in target_dire Although initial ACLs are still copied, they are not used in setting the ACL of the new entries when this control argument is specified. (See "Notes on Access Provision" below.) -brief. -bf suppresses the printing of warning messages such as "Bit count is inconsistent with current length" and "Current length is not the same as records used." -chase copies the target of a link. Chasing the links eliminates link translation. (Default: not to chase links) -force executes the command. when target_dir already exists, without asking you. -f orce is not selected, you are queried. If -no_link_translation. -nIt copies links with no change. If there are references to the source directory in the link pathname of a link being copied, the link pathname is changed to refer to the target directory. (Default to translate links being copied) 3-163 AG92-D6 copy_dir copy_dir -primary, -pri copies only primary names. selected entries are copied. If -primary is not given, all the names of the -replace! -rp deletes the existing contents of target_dir before the copying begins. If target_dir is nonexistent or empty, this control argument has no effect (Default: to append the contents of source_dir to the existing contents of target_did LIST OF ENTRY TYPE KEYS Entry type keys control what type of storage system entries in the subtree are copied. If no entry_type_key is specified, all entries are copied. The keys are -branch, -br -directory, -dr -file~--f -link, -lk -multisegment_file, -msf -non_null_link, -nnlk -segment, -sm If one or more entry_type_keys are specified, but not the -directory key, the subtree of source_dir is not walked. ACCESS REQUIRED Status permission is required for source_dir and all the directories in its tree. Status permission is required for the directory containing source_dir. Read access is required on all files under source_dire Append and modify permission are required for the directory containing target_dir if target_dir does not exist prior to the invocation of copy_dire Modify and append permission are required on target_dir if it already exists. This command does not force access. If -acI is not specified, the system default ACLs are added, then the initial ACL for the containing directory is applied (which may change the system-supplied ACL). Initial ACLs are always copied for the current ring of execution. NOTES If target_dir already exists and -force is not specified, you are so informed and asked if processing should continue. If target_dir is contained in source_dir, an appropriate error message is printed and control is returned to command level. If name duplication occurs while appending the source_dir to the target_dir and the name duplication is between directories, you are queried whether processing should continue. If you answer yes, the contents of the directory are copied (appended) but none of the attributes of that directory are copied; if you answer no, the directory and its subtree is skipped. If name duplication occurs between segments, you are asked whether to delete the existing one in target_oir 3-164 AG92-06 If you give -replace or target_dir does not exist, name duplication does not occur. If part of the tree is not copied (by specifying a storage system entry key). problems with link translation may occur. If the link target in the source_dir tree was in the part of the tree not copied, there may be no corresponding entry in the target_dir tree. Hence translation of the link causes the link to become nUll. See also the copy. move, and move_dir commands. EXAMPLES The command line cpd old_source new_source -segment -acl copies all the segments with their ACLs in the directory old_source to the directory new_source. The command line cpd old_user new_user -branch copies all the segments. directories, and multisegment files from the directory old_user to the directory new_user (no links are copied). SYNTAX AS A COMMAND FUNCTION This command copies Multics storage system hierarchy dump data from a set of input (master) tapes to a set of output (copy) tapes. Options allow comparing master and copy tapes after the copy operation; selective copying based upon pathname specifications in a selection file; and copying/comparing from or to a storage system file containing an image of a set of dump tapes. rather than tapes. x 11/87 3-165 AG92-06B CONTROL ARGUMENTS -abort indicates that comparing of the master with the copy should stop when the first discrepancy is found. -compare, -cmp indicates that master and copy should be compared after the copy is generated. Any discrepancies are reported to the user. -input_file IN_PATH, -if IN_PATH gives the pathname of a file containing an image of the backup dump tape. This file must have been created by a prior invocation of copy_dump_tape. It contains the master data to be copied. -input_volume VOLNAMES, -ivol VOLNAMES gives a list of input tape volume names containing the master data to be copied. The names are separated from one another by a blank. Up to 20 volume names can be given. This control argument may be followed by the control arguments described below in "Control arguments for volume attributes". -map {MAP_PATH} controls the generation and naming of a dump map, If -map is given with a MAP_PATH, then a dump map listing the copied files is generated in that file. A suffix of map is assumed if not supplied. If no MAP_PATH is given, the map is generated in a file in the working directory. The file name is derived from other control arguments, as follows. If -select SELECT_PATH is given. then the map file name is the final entryname from SELECT_PATH. If -select is omitted but -ovol VOLNAME is given. the map file is called VOLNAME.map. If -of OUT_PATH is given, the map file is the final entryname from OUT_PATH. Otherwise, the map file name is a unique character string (returned by the unique_chars_ subroutine). -maximize_devices, -maxdv indicates that all tape drives reserved by the process or assigned to the process are to be used equally (round-robin) when copying from or to tape, and that during comparison, tape volumes are to be mounted on a different tape drive than was used during copying. This helps detect tape failures caused by reading or writing on a poorly calibrated tape drive. -no_abort, -nabort indicates that comparing master and copy should continue when errors are encountered, until 20 discrepancies are found. This is the default 11/87 3-166 AG92-G6B -no_compare, -ncmp indicates that master and copy are not to be compared after the CO?y operation. This is the default. -no_map, -nmap indicates that no backup map of the copied data is to be produced. This is the default. -no_maximize_devices. -nmaxdv allows Rep to select which tape drives to use when reading or writing tapes. This is the default. -no_select, -nslct indicates that all master data is to be copied and compared. This is the default. -no_trace, -n trace prevents tracing information from being printed. This is the default. -output_discard, -od indicates that no output copy is to be generated. This is useful in conjunction with -map to produce a map of the master data, or in conjunction with -trace for debugging purposes. -output_file OUT_PATH, -of OUT_PATH gives the pathname of a copy file into which the master data is copied. -output_volume VOLNAMES, -ovol VOLNAMES gives a list of output tape volume names. The mac;ter data is copied onto this copy tape volume set The names are separated from one another by a blank. Up to 20 volume names can be given. This control argument may be followed by the control arguments described below in "Control arguments for volume attributes". -select SELECT_PATH, -sIct SELECT_PATH gives the pathname of a file similar to a standard backup_dump control file. This file gives paths of master files to be selected for copying. See "Notes on control file." -trace {TYPE} controls printing of trace information while copying and comparing. This information is primarily used for debugging copy_dump_tape. See "List of trace types". CONTROL ARGUMENTS FOR VOLUME ATTRIBUTES The following control arguments define attributes of tape volumes given in preceding -input_volume or -output_volume control argument. -density DEN, -den DEN gives a tape density. DEN may be 800, 1600 or 6250. If given for input tapes, the tapes are mounted on a tape drive capable of reading density DEN. However. the actual density at which the input tapes are written determines the density used for reading. If given for output tapes, the tapes are written at density DEN. The default density is 1600 BPI (bits per inch). 11/87 3-166.1 AG92-06B -track TK, -tk TK mounts tapes on a tape drive capable of handling tapes containing TK tracks. TK may be 7 or 9. The default track size is 9. LIST OF TRACE TYPES One of the following trace types may be given as operand with the -trace control argument. These arguments control the type of trace information printed. If any tracing is enabled, then attach descriptions are printed in addition to the segment information described below. all, a during both copy and compare operations, trace master segments selected by paths in the -select file. compare, crop during the compare operation, trace master segments selected by paths in the -select file. No segments are traced during the copy operation. copy, cp during the copy operation, trace master segments selected by paths in the -select file. No segments are traced during the compare operation. This is the default if -trace is specified without a TYPE operand. off turn off tracing. This is equivalent to -no_trace. rejects, reject, rej print master segments unmatched or rejected by paths in the -select file. LIST OF SEVERITY VALUES copy_dump_tape sets an external variable to indicate the success or failure of copy and compare operations. This variable may be examined using the severity command/active function. For example: 11/87 3-166.2 AG92-06B The following severity values can be returned. o Both copy and compare operations completed successfully. 2 The copy and compare operations completed successfully, but one or more paths given in the -select file were not matched by master segments. These pathnames are listed in a message printed by copy_dump_tape. 3 The copy operation completed successfully. but the compare operation found discrepancies between master and copy segments. 4 Either copy or compare operations failed, due to fatal errors. These errors are diagnosed in error messages. NOTES Either -input_file or -input_volume must be given to specify the source of master input data. -output_discard. -output_file. or -output_volume must be given to specify the target for copied data. NOTES 0,"-/ COIVT ROL FILE The control file specified by -select is an ASCII segment containing pathnames of entries (segments, MSFs, and directory subtrees). Each pathname must be given on a separate line. Absolute pathnames must be given. with each entryname of the path being a primary name (the first name of the entry). Master entries matching one of the paths are copied and compared. Master entries which are superior to one of the paths are also copied/compared. If a path identifies a directory, then master entries inferior to that directory are copied/compared. A pathname preceded by a circumflex (A) character identifies entries which are NOT to be copied or compared. unless later entries in the control file override the rejection. For example->library_dir_dir> hardcore A>library_dir_dir>hardcore>info >library_dir_dir>hardcore>info>hardcore.header selects all entries in the subtree below >library_dir_dir>hardcore. except those in the info directory. However. the hardcore.header entry in the info directory is selected. 11/87 3-167 AG92-06B copy_file Name: copy_file copy_file, cpf SYNTAX AS A COMMAND FUNCTION copies records from an input file to an output file that has been restructured for maximum compactness. The input and output file records must be structured (see "Notes on Unstructured Files" below). The input file can be copied either partially or in its entirety. 11/87 3-167.1 AG92-06B copy_file copy_file ARGUMENTS ifi_control_arg the input file from which records are read can be specified by either of the following: -input_switch STR. -isw STR specifies the input file by means of an already-attached I/O switch name. where STR is the switch name. -input_description STR, -ids STR specifies the input file by means of an attach description STR. STR must be enclosed in quotes if it contains spaces or other command language characters. out_control_arg the output file to which the records are written can be specified by either of the following: -output_switch STR. -osw STR specifies the output file by means of an already-attached I/O switch name. where STR is the switch name. -output_description STR. -ods STR specifies the output file by means of an attach description STR. STR must be enclosed in quotes if it contains spaces or other command language characters. CONTROL ARGUMENTS -all. -a copies until the input file is exhausted. (Default) -brief. -bf suppresses a message indicating the number of records or lines actually copied. -count N. -ct N copies until N records have been copied or the input file is exhausted, whichever occurs first, where N is a positive integer. (Default: to copy until the input file is exhausted) -from N, -fm N copies records beginning with the Nth record of the input file. where N is a positive integer. (See "Notes.") (Default: to begin copying with the "next record") -keyed conies both records and kevs from a keyed seauential innut file to a keyed seQuential output file. (See ~'Notes· ·on Keyed Fil~. n) (Defa~1t: to copy records from an input file, keyed or not, to a sequential output file) 3-168 AG92-o6 copy_file -long, -lg prints a message indicating the number of records or lines actually copied: "345 records copied". (Default) -start STR. -sr STR copies records beginning with the record whose key is STR. where STR is 256 or fewer ASCII characters. (Default to begin copying with the "next record") -stop STR, -sp STR copies until the record whose key is STR has been copied or the input file is exhausted. whichever occurs first, where STR is 256 or fewer ASCII characters. This control argument can be given without specifying -start However, if -start is supplied. the STR used with -stop must be greater than or equal to (according to the ASCII collating sequence) the STR given with -start. -to N copies until the Nth record has been copied or the input file is exhausted, whichever occurs first, where N is a positive integer greater than or equal to the N given with -from. If you use -to, you must give -from. NOTES If either the input or output specification is an attach description, it is used to attach a uniquely named I/O switch to the file. The switch is opened, the copy performed, and then the switch is closed and detached. Alternately the input or output file can be specified by an I/O switch name. Use either io_call or iox_ to attach the file ~';n~ ,t-'J..IU'. tn """ tl-te- ;~"n"!lt.jn" ....1..1."" .L.I.ly"',..,u,. ....I."'.&..& nf ,.nn" f';le"'.I. "'''.t'J-...... .&'-''. If the input file is specified by an I/O switch name and the switch is not open, copy_file opens it for (keyed->sequential_input, performs the copy, and closes it. If the switch is already open when copy_file is invoked, the opening mode must be or sequential_input, sequential_input_output, keyed_sequential_input, keyed_SeQuential_update. The switch is not closed after the copy has been performed. The "next record" must be defined if neither -start nor -from is speciiied as the absolute starting position within the input file. If the I/O switch is opened by copy_file, the next record is the first record of the file; otherwise the next record is the one at which the file is positioned when copy_file is invoked. If the output file is specified by an I/O switch name and the switch is not open, copy_file opens it for (keyed->sequential_output, performs the copy, and closes it. If the switch is already open when copy_file is invoked, the opening mode must be sequential_output, sequential_in put_output, keyed_sequential_output, keyed_SeQuential_update, direct_output, or direct_update. (In update mode, output file records with keys that duplicate input file records are rewritten.) The switch is not closed after the copy has been performed. The following control arguments are mutually exclusive: -from and -start; -to, -stop. -count, and -all; -brief and -long. 3-169 AG92-()6 copy_file copy_file NOTES ON UNSTRUCTURED FILES This command operates by performing record I/O on structured files. If you want to copy from/to an unstructured file, you can use the record_stream_ I/O module: cpf -ids "record_stream_ -target vfile_ pathname" -osw OUT which takes lines from the file specified. by pathname via the vfile_ I/O module, transforms them into records via the record_stream_ I/O module, and copies them to the I/O switch named OUT. NOTES ON KEYED FILES The command can copy a keyed sequential file to produce an output file that has been restructured for maximum compactness as a keyed file or as though it were sequential. By default it copies only records and does not place keys in the output file. To copy the keys, use -keyed. When you select -keyed the input file must be a keyed sequential file: Whether keys ate copIed ()root,cnOosecontrolargilnients-to delimit the range of records to be copied (e.g.. -start, -stop). Copying is always performed in key order. If the keyed file has keys but no records (e.g., a dictionary file), the file, its keys, and its associated record descriptors are copied. EXAMPLES To copy an entire file from an already-attached file to the segment in_copy, type cpf -isw in -ods "vfi le_ in_copy" To print the first 13 records of a tape file: cpf -ct 13 -ids "tape_ansi_ 887677 -name TEST21 -ret all" -ods "record_stream_ user_output" To copy 13 records from an already-attached file to another already-attached file, starting with the 56th record of the input file: cpf -isw in -osw out -from 56 -ct 13 To copy records 43 through 78 from an already-attached file to an already-attached file: cpf -isw in -osw out -from 43 -to 78 To copy all but the first seven records from segment testdata.11 to an already-attached file: cpf -ids "vfi le testdata.ll" -osw out -fm 8 3-170 AG92-06 To copy an entire keyed sequential file with keys: cpt -isw in -osw out -all -keyed To copy 13 records of a keyed sequential file starting with the record whose key is ASD66 to a sequential output file, the following line is typed. (No keys are copied.) cpt -isw in -osw out -sr Aso66 -ct 13 To copy the records and keys from a keyed sequential file up to and including the record whose key is bb"bb, type cpt -keyed -isw in -osw out -sp "bb llll bb" SYNTAX AS 'A COMMAND copy_iac1_dir pathl path2 {. •• pathlN path2N} FUNCTION copies the initial access control list for directories (directory initial ACL) of one directory to L~other, replacing Li.e current directory initial ACL if necessary. (See the Programmer's Reference Manual for a description of initial ACLs.) ARGUMENTS path1 is the pathname of a directory. You can specify your working directory with -workinLdirectory (-wd). The star convention is allowed. I paOO is the pathname of the target directory. You can specify your working directory with -workinLdirectory (-wd). The equal convention is allowed. I ACCESS REOUIRED You need status permission on path1 and modify permission on paOO. 3-171 AG92-06 SYNTAX AS A COMMAND copy_iacl_seg pathl path2 { ••• pathlN path2N} FUNCTION copies a segment initial access control list (initial ACL) irom one directory to another, replacing the current initial ACL if necessary. (See the Programmer's Reference Manual for a description of initial ACLs.) -ARGUMENTS path1 is the directory from which the initial ACL is to be copied. You can specify youf--working -directer-yas -wor-kinL-directory (~wd). -You-can-- use-the star convention. path2 is the directory into which the initial ACL is to be copied. You can specify your working directory as -wd. You can use the equal convention. ACCESS REQUIRED You need status permission on path1 and modify permission on path2. Name: copy_names SYNTAX AS A COMMAND copy_names pathl {path2 .•• pathlN path2N} FUNCTION copies all the names of one entry--directory, segment, multisegment file (MSF), data management (DM) file, extended entry, or link--to another. ARGUMENTS path1 is the pathname of the entry whose names are to be copied. You can use the _ star convention. 11/86 3-172 AG92-06A create path2 is the pathname of the entry to which all names are copied. If you omit path2N, names are copied into an entry in you working directory with the same entryname as path1N. You can use the equal convention. NOTES All names are left on the original entry. The two entries cannot reside in the same directory because duplicate names are not allowed in a directory. Only one matching name per entry is used when resolving the equal name. This is the first matching name on that entry (in the order returned by hcs_$star-> for which the specified equal name exists. Name: create, cr SYNTAX AS A COMMAND cr paths {-control_args} FUNCTION creates a storage system entry for an empty segment in any directory. ARGUMENTS paths are pathnames of segments to be created. CONTROL ARGUMENTS -max_length N, -ml N sets the maximum length of the created entry to N. Used with -msf. -ml sets future MSF components to N words long. -multisegment_file, -msf creates an MSF with one empty component, instead of an empty segment When you foresee that you need much storage, creating an MSF prevents the expensive copying occurri~"1g when a segment is converted 10 an tv1SF. -name STR, -nm STR specifies an entryname STR that begins with a minus sign, to distinguish it from a control argument -rin!-.brackets N1 {N2 {N3}}, -rb N1 {N2 {N3}} specifies the desired ring brackets for the created segment. N3 defaults to N2. which defaults to Nl, which defaults to your validation level. 11/86 3-173 AG92-06A create ACCESS REQUIRED You must have m access to a directory to create the segment, and you are given rw to it. ,'VOTES If there is a one-name segment with an identical name to the segment you are creati..'lg, you are asked whether to delete the old segment. If it has multiple names. the conflicting one is removed and a message is issued to you. In either case, since the directory is being changed, you must also have modify permission f or the directory. All directories specified in paths must already exist; that is, only a single level of the storage system hierarchy can be created with this command. See the create_dir and link commands for the creation of directories and links. EXAMPLES The command line cr first_class_mail >udd>Demo>IEBunin>alpha>beta creates the segment first_class_mail in the working directory and the segment beta in the directory >udd>Demo>IEBunin>alpha. Name: create_area SYNTAX AS A COMMAND create_area virtual_pointer {-control_args} FUNCTION creates an area and initializes it with user-specified information. area management control ARGUMENTS virtual_pointer is a virtual pointer specifier to the area to be created (see Section 1 ior a description of virtual pointers). If the segment already exists, the specified portion is still initialized as an area. 3-174 AG92-06 CONTROL ARGUMENTS -dont_free is used during debugging to disable the free mechanism. This does not affect the allocation strategy. -extend causes the area to be extensible. i.e.• span more than one segment This feature should be used only for perprocess, temporary areas. -id STR specifies a string to be used in constructing the names of the components of extensible areas. -no_freeing allows the area management mechanism to use a faster allocation strategy that never frees. -size N specifies the octal size, in words, of the area being created or of the first component, if extensible. If this control argument is omitted, the default size of the area is the maximum size allowable for a segment. The minimum area is forty octal words. -zero_on_alloc instructs the area management mechanism to clear blocks at allocation time. -zero_on_free instructs the area management mechanism to clear blocks at free time. Name: create_data_segment, cds SYNTAX AS A COMMAND cds path {-control_arg} FUNCTION translates a create_data_segment (CDS) source program into an object segment A listing segment is optionally created. These results are placed in your working directory. This command cannot be called recursively. 3-175 AG92-06 ARGUMENTS path is the pathname of a CDS segment. If path does not have a cds suffix. one is assumed; however the cds suffix must be the last component of the name of the source segment. CONTROL .ARGUMENTS -list. -Is produces a source listing of the CDS program used to generate the data segment followed by object segment information (as printed by the print_link_info command) about the actual object segment created. NOTES The source for create_data_segment programs is standard PL/I with the restriction the program include a call- to· ... the . create=data:....segmenl_ subroutine. create_data_segment_ subroutine creates a standard object segment from PL/I structures passed to it as parameters. These data structures can be initialized arbitrarily complex PL/I statements in the CDS program. that The data with Since the create_data_segment command invokes the PL/I compiler to first compile the CDS segment. any errors that the compiler finds are reported by its standard technique. If any errors with a severity greater than 2 occur. the CDS run is aborted and an object segment is not created. Name: create_dir, cd SYNTAX AS A COMMAND cd paths {-control_args} FUNCTION creates a specified directory branch in a specified directory or in your working directory; that is. it creates a storage system entry for an empty subdirectory. ARGUMENTS paths are pathnames of directories to be created. 3-176 AG92-06 CONTROL ARGUMENTS -access_class SlR -acc STR applies to each pathi and upgrades each directory created to the specified access class. You can give the access class with either long or short names. -account STR, -acct STR specifies the volume quota account from which the created master directory is to draw its quota, where STR must match an existing quota account on the given logical volume. If omitted, an account that matches the owner User_id is used (if any). You can supply -account only if you select -logical_volume. -dir_quota N specifies the directory quota to be given to the directory when it is created, where N must be a positive integer and applies to each pathi. If omitted. the directory is given zero directory quota. -logical_volume VOL, -Iv VOL specifies that each directory created is to be a master directory whose segments are to reside on the logical volume named VOL. -name STR, -nm STR specifies an entryname STR that begins with a minus sign. to distinguish it from a control argument, or consists solely of white space. -owner USER_ID. -ow USER_ID specifies the owner of the created master dire.ctory. You can supply -owner only if you select -logical_volume. (Default: your User_id) -quota N specifies the segment quota to be given to the directory when it "is created. where N must be a positive integer and applies to each pathi. You must provide -quota if you use either -access_class or -logical_volume. If omitted, the directory is given zero segment quota. -rin~brackets Nl {N2} , -rb Nl {N2} specifies the ring brackets of the created directory. defaults to 7. N2 defaults to Nl. which ACCESS REQUIRED You must have a access to a directory in order to create a subdirectory in that directory. The -account and -owner control arguments are allowed only for volume administrators (i.e.. only those who have e access to the volume). 3-177 AG92-o6 NOTES If you specify a directory or segment quota and the directory you are creating is not a master directory. the containing directory must have sufficient directory or segment quota to move quota to the directory being created (see move_quota). If the creation of a new subdirectory introduces a duplication of names within the directory and if the old entry has only one name. you are asked whether to delete the old entry. If the old entry has multiple names. the conflicting name is removed and a message is issued to you. You are given sma access on the created subdirectory. All superior directories specified in pathi must already exist. That is. you can only create a single level of storage system directory hierarchy in a single invocation of create_dire To create a master directory. you must have a quota account on the logical volume with sufficient volume quota to create the directory. If you are not a volume administrator. you can create a master directory only if the administrator has created a quota account that matches your User_ide A master directory must always have a nonzero quota; therefore you must always give -quota when creating a master directory. You can create a master directory even though the logical volume is not mounted. Each upgraded directory must have a quota greater than zero and must have an access class that is greater than its containing directory. The specified access· class must also be less than. or equal to. the maximum access authorization of the process. When you supply -access_class. the command does not create a new directory through a link. Creating through links is allowed only when the access class of the containing directory is taken as the default. See the create and link commands for the creation oi segments and links. EXAMPLES The command line cd sub >my_dir>a1pha>new creates the directory sub immediately inferior to your current working directory and the directory new immediately inferior to the directory >my_dir>alpha. The directories my_dir and alpha must already exist. Both directories are assigned the access class of their containing directory. 3-178 AG92-06 The command line cd subA -access_class a,cl,c2 -quota 5 creates the directory subA, immediately inferior to your working directory. with an access class of a.cl,c2 and a quota of five pages. (The access class names a. cl, and c2 used in the example represent possible names defined for your site. See print_auth_names for details on access class names.) The command line cd subB -logical_volume volz -quota 100 creates a master directory subB immediately inferior to your working directory. Segments created in this new directory will reside on the logical volume named volz. The directory subB is given a quota of 100 records. SYNTAX AS A COMMAND FUNCTION creates an unpopulated data management (DM) file for use with Multics data management (see the Programmer's Reference 1v1anuaI). Files created in this manner would be used primarily for test purposes or in applications calling the file_manager_ subroutine directly. ARGUMENTS path is the pathname of the DM file to be created. CONTROL ARGUMENTS -concurrency, -conc provides automatic concurrent access protection to a protected OM file by enforcing locking conventions on get and put operations to the file (see ·'Notes·'). (Default) -no_concurrency. -nconc turns concurrency protection off for a protected OM file. saving on overhead when locking is unnecessary (see "Notes"). 3-179 AG92-06 -no_rollback, -nrIb turns the rollback capability off for a protected OM file, saving on overhead when rollback is unnecessary (see "Notes"). -protected. -prot creates a protected OM file. which means the file is entitled to the protection features provided by the integrity services of data management You can access a protected DM file only within the context of a transaction. (See "Notes. It) (Default) -rins-brackets W {R}, -rb W {R} sets the write ring bracket to Wand the read ring bracket to R. If you don't specify the read ring bracket. it defaults to the value given for the write ring bracket Both Wand R must be greater than or equal to your validation level. -rollback. -rIb provides an automatic rollback capability for a protected OM file by logging before images of modifications made to the file. These images are used in the event of transaction. process, or system failure to restore the file to its original state. (See "Notes.") (Default) -unprotected. -unprot. -not_protected. -nprot creates an unprotected DM file, without the benefit of integrity services. You can access an unprotected DM file outside a transaction. (See "Notes. n) ACCESS REQUIRED You need sma access on the directory in which the OM file is created and s access on the directory containing that directory. NOTES The -unprotected control argument is mutually exclusive with -concurrency, -no_concurrency. -no_rollback, -protected. and -rollback. If you use two mutually exclusive control arguments. the rightmost option in the command line takes precedence. This command is part of the command level interface to Multics data management. 11/86 3-180 AG92-06A cross_ref erence cross_reference Name: cross_reierence, crei SYNTAX AS A COMMAND cref library_descriptions {-control_args} FUNCTION creates a cross-reference listing of any number of object programs. The listing contains information about each object module encountered, including the location of each program, its entry points and definitions, any synonyms. and which other modules encountered reference each entry point or definition. It also optionally supplies a cross-reference listing of include files used by the modules encountered. 11/86 3-180.1 AG92-06A This page intentionally left blank. 11/86 AG92-06A cross_reference cross_reference ARGUMENTS library_descriptions can be chosen from the following: paths are the pathnames of segments to be examined and cross-referenced. The star convention is allowed. -library library_name {-all} paths. -lb library_name {-all} paths specifies that all modules represented by paths are treated by the cross-referencer as if they were in a common library of that name. The library_name argument can be any identifier you choose. If -library contains -all. all the module names encountered are considered external (see "Resolving References.") This control argument is generally used only for cross-references of the Multics hardcore libraries. CONTROL ARGUMENTS -brief. -bf suppresses nonfatal error messages. messages to the output file. It does not affect the reporting of error -first specifies. with -input_file. that once any instance of a particular module has been located. the cross-referencer need not search the remaining directories for other instances of modules with the same name. If omitted. the cross-referencer searches an libraries in the search list for each moduie name suppiied. -include_files. -icf cross-references include files used by all modules examined. -input_file path. -if path uses a control file describing the modules to be cross-referenced instead of the library descriptions. If the crl suffix is not part of the supplied filename. it is assumed. If -input_file is given. no library descriptions are allowed. -line_length N. -11 N formats lines in the output file to the given line length. (Default: 132) -output_file path. -of path creates the cross-reference list in a segment of the specified name. If the cross-reference suffix is not part of the supplied filename. it is assumed. If -output_file is not selected. but -input_file is, the output file takes its name from the input file. with the suffix ".crossref" replacing the suffix ".crI"; otherwise, the output file is named "crossref.crossref". 3-181 AG92-D6 cross_ref erence -short, -sh does not include in the output referenced modules that are not included in the scope of any library_descriptions. With -short, the output reflects only the interrelationships among the modules in the libraries specified. MODULE EXAMINATION Module examination is performed in two' passes: the first defines all the segment names, synonyms, and definitions; the second examines external references and attempts to resolve them with existing definitions. Segments encountered fall into four classes: nonobject. bound segments, stand-alone modules, and archives. When a nonobject segment is encountered, a warning message is printed and the segment is included in the results of the cross-reference. When a bound segment is found, a warning message is printed and the segment is ignored. Bound segments are useless to the cross-referencer. since information necessary to determine which components use which external reference links is no longer available due to the binding process. Use instead the object archive from which it was bound. When a stand-alone segment is met, it is analyzed for entry points. definitions, and external references. All additional names on the segment are entered as synonyms for the module. This information is then included in the results of the cross-reference. When an archive is encountered, each component is analyzed for entry points. definitions, and external references. If a bind file exists, synonyms for each component are derived from "synonym" statements in the bind file. when they exist. This information is then inciuded in the results of the cross-reference. Modules are also identified by the segment in which they are found (either themselves. for a stand-alone segment, or the containing archive, for an archive) and by the library_name of the directory in which they are found. If the directory is given without a library_name, the pathname of the directory is used as the library_name. This allows having multiple occurrences of segments with the same name, as long as they differ by at least one of these identification criteria. RESOLVING REFERENCES When a module is examined by the cross-referencer, its name and synonyms are classified as "internal" or "external" by the following criteria: 1. If the module is stand alone, its name and synonyms are external. 2. If the module is archived and the library description contained -all . its name and all its synonyms are considered external. 3-182 AG92-()6 cross_reference 3. cross_reference If the module is archived and the library description did not contain -all, its name and each of its synonyms are external only if they appear in the "Addname:" statement of the bind file. If no bindfile exists. the name and synonyms are considered internal. The cross-referencer tries to resolve external references on a best-match basis by using the following criteria: 1. If the reference can be satisfied by a definition in the same module. that definition is used. 2. If the referencing module is part of a bound segment and can be satisfied by a definition in the same bound segment, that definition is used. 3. If the reference can be satisfied by an external definition in the same library_name. that definition is used. 4. Otherwise. the first external definition found that satisfies the reference is used. If more than one such definition exists. a warning message is printed. FORMAT OF A DRIVING FILE If -input_file is given. the cross-referencer takes its input from a special file. The first lines of the file must contain the names of one or more directories to be searched. They are specified in the following manner: -1 ibrary: pathname 1 pathname_2 (OR -library -all:) 1 i brary_name_a library.;.name_b Each pathname_i specifies a directory to be searched. When present, a library name (which can contain spaces) is used to describe the preceding directory name. (See "Module examination" above.) The tokens "-wd" or semicolon ends the search list The next information in the file is a list of the segments to be examined. They must appear one to a line. If you wish to defhle explicitly synonyms for any modules that would not otherwise be generated (e.g., a nonapparent reference name by which a segment is sometimes initiated), they can be included in this section with one or more lines of the form: modulename synl syn2 •.• synN These lines do not by themselves cause the cross-referencer to search for the module "modulename", since it may not be a freestanding segment Any synonyms defined in this manner are considered external. 3-183 AG92-{)6 cross_reference A file can consist of several repetitions of the format described above; that is, a search list, segment names, another search list. more segment names, etc. Whenever a new search list is found, it replaces the old search list If a driving file is to be used, make it consist of multiple occurrences of a one-directory search list followed by the segments contained in that directory. Here is example of a centrol file constructed to cross-reference a student subsystem: -library: >udd>Class>systemdir>object CLASS SUBSYSTEM; class_login_responder.archive class_tests.archive student_grades_database audit_procedure class_uti 1 ities.archive unallowed_compiler_stub fortran pll unallowed_compiler_stub SPECIAL CASES Segments with unique names and with single-digit last components are ignored, since these are conventions used by the system library tools to denote segments to be deleted shortly. Archives whose names are identical with the exception of a different numeric next-to-Iast component are considered the same archive. Definitions or entry points in archive components that masquerade as segment names by an added name on the bound segment. without being defined as a synonym fOT their containing component, are not cross-referenced satisfactorily. INCLUDE FILES The cross-reference listing of include files, when requested, is appended to the regular output of the cross-referencer. Each include file met is classified by its entryname and its date/time modified. This ensures that modules that use different versions of the same include file are apparent. EXAMPLES The following command produces a cross_reference listing of the Standard Service System in the file "standard.crossref": cref -library STANDARD >ldd>sss>o>** -of standard To produce a cross-reference listing of the hard core library, you can use cref -library HARD -all >ldd>h>x>* >ldd>h>o>*.archive -of hard 3-184 AG92-o6 cross_reference OUTPUT EXAMPLE Entries are separated by dashed lines in the output listing. The following is a sample entry: ----------*****bound_x_ in SSS sample_segname SYNONYM: one_entrypoint program_a second_entrypoint program_a unused entrypoint undefined_ent (1) *****--------------one syn, another_syn program_b program_c The entry shown is for segment "sample_segname", which is a component of bound_x_ in the library specified as SSS. It possesses three entry points: "one~entrypoint". "second_entrypoint", and "unused_entrypoint". The information shows that "sample_segname$one_entrypoint" is called by module "program_a" and module "program_b". The question mark after entry point "undefined_ent" signifies that this entry point is an implicit definition: the module "program_d" refers to "sample_segname$undefined_ent". but that entry point does not exist (A diagnostic is printed when this situation is encountered.) All error messages produced during the run, including warning messages that may not have been printed at the terminal because of -brief, are -appended to the end of the output file for reference. Name: cumulative_page_trace, cpt SYNTAX AS A COMMAND cpt command_line {-control_args} FUNCTION accumulates page trace data so that of a command or subsystem can be one invocation of itself to the next. that have been referenced by your produced by page_trace. the total set of pages used during the invocation determined. The command accumulates data from The output is in tabular format showing all pages process. You can obtain the same trace as that ARGUMENTS command_line is a character string to be interpreted by the command processor as a command line. If this character string contains blanks, enclose it in quotes. All procedures invoked as a result of processing this command line are metered by cumulative_page_trace. 3-185 AG92-D6 CONTROL ARGUMENTS -count. -ct prints the accumulated results. gIvIng the number of each page and the number of faults for each page. Do not use -count with -print or -total (see "Notes" below). -flush clears primary memory before each invocation of the command line and after each interrupt. This helps you determine the number of page faults but increases the cost. -interrupt N. -int N interrupts execution every N virtual CPU milliseconds for page fault sampling. (Def ault: 500 CPU milliseconds) -long, -lg produces output in long format. giving full pathnames. -loop N calls the command to be metered N times. -print. -pr prints the accumulated results. giving the number of each page referenced. Do not use -print with -count or -total (see "Notes. tt) -prin t_linkage_f aul ts prints all accumulated linkage faults and calls the hcs_$make_ptr entry point -reset, -rs resets the table of accumulated data.. If the table is not reset. data from the current use of cumulative_page_trace is added to that obtained earlier in the process. -short, -sh formats output for a line length of 80. -sleep N waits for N seconds after each call to the command being metered. -temp_dir path, -td path creates temporary segments, used for flushing main memory. in the directory identified by path. Use -temp_dir with -flush. (Default: to create them in the process directory) -timers includes all faults between signal and restart 3-186 AG92-()6 cumulative_page_trace -total. -tt prints the total number of page and segment faults and the number of pages referenced for each segment Do not use -total with -count or -print (see "Notes.") - trace_linkage_f aul ts accumulates linkage. page. and segment fault information. -trace path writes the trace on the segment "path" using an I/O switch named "cpt.out" (see "Examples"); cumulative_page_trace attaches and detaches this switch. NOTES This command operates by sampling and reading the system invocation of a command and at repeated intervals. trace array aiter At least one of three generic operations must be requested. They may all be combined and. if so. are performed in the following order: resetting the table of accumulated data. calling the command to be metered. applying the specified control arguments, and printing the results in the specified format. If 500 milliseconds is too long. messages indicate that some page faults may have been missed; choose then a smaller value, but the cost of a smaller value is high and may cause additional side effects. If the command or subsystem to be metered includes the taking of CPUT interrupts, then supply -timers, which includes some of the page faults of the metering mechanism as well. You can give only one of -count. -print. or -total. Each of these control arguments produces printed output in a different iormat. If you want more than one format. invoke the command once for each format. For -flush to operate correctly, the directory used for temporary segments must have sufficient quota for as many pages as there are in main memory. EXAMPLES The command line cpt "pll test" -interrupt 400 -trace trace_out calls the pH command to compile the program named "test." requesting an interrupt every 400 milliseconds to obtain page trace information. Trace information is placed in a segment named "trace_out." The command line cpt "list -pn >udd>Multics" -loop 2 -sleep 10 calls the list command twice and sleeps for 10 seconds between calls. 3-187 AG92-()6 The command line cpt -print prints the accumulated results of previous metering. The command line cpt !Ideo ls" -trace cpt. trace produces the following output: LINKAGE FAULT BY RESOLVED LINK TO MAKE-PTR-CALL 2.05 3. 14 674 256 10. 18 5.18 310 bound_meterin9_: cpt l 21 36 bound_library_l_$cp 7 s where the first column is the event, what is happening (if it is blank. it means that there is a page fault); the second is the CPU time; the third, the segment number; the fourth, the page number; and the fifth, the name of the segment SYNTAX AS A COMMAND FUNCTION compiles a terminal type file (TIF) into a terminal type table (TIT) for installation. ARGUMENTS path is the pathname of the TIF to be compiled. It must have the ttf suffix. The resulting TIT is placed in your working directory; its entry name is the same as the entryname of the TIF with the ttt suffix added. CONTROL ARGUMENTS -brief, -bf prints all error messages produced by cv_ttf in short form. -long. -lg prints all error messages produced by cv_ttf in long form. 3-188 AG92-06 date -severity N, -sv N does not write error messages whose severity is less than N (where N is 0, 1, 2, 3, or 4) to the user_output switch. If not given, a severity level of 0 is assumed; i.e., all error messages are written to the user_output switch. (See "Notes on . Severity Values. n) NOTES If neither -brief nor -long is selected, the first instance of a given error produces a long message and all subsequent instances of that error produce short messages. NOTES ON SEVERITY VALUES This command associates the following severity values to be used by the severity active function: Value o 1 2 3 4 5 Meaning No compilation yet or no error Warning Correctable error Fatal error Unrecoverable error Could not find source Name: date SYNTAX AS A COMMAND date {time_string} {-control_arg} SYNTAX AS AN ACTIVE FUNCTION FUNCTION returns a date of the form "mm/dd/yy" (e.g.. "12/23/82"). The format string to produce this is "Amy/Adm/Aye". ARGUMENTS time_string indicates the date about which inf ormation is desired. If you supply no time_string, the current date is used. The time string is concatenated to form a single argument even if it contains spaces; you need not quote it (See Section 1 for a description of valid time_string valUes.) 3-189 AG92-06 date CONTROL ARGUMENTS -zone STR STR specifies the zone that is to be used to express the result (Default: the process default) NOTES Use the print_time_defaults command to display the default zone. display_time_info command to display a list of all acceptable zone values. Use the Due to exec_coms, etc., that have been built around the expected date format, this command does not honor the process date format (set by set_time_default). You are encouraged to use "clock date" instead of date to get the proper default handling. Name: date_compiled, dtc SYNTAX AS A COMMAND dtc path {-control_arg} {components} SYNTAX AS AN ACTIVE FUNCTION [dtc path {-controi_arg} {components}] FUNCTION prints the date and time compiled and the compiler identifier for an object file or an archive of object segments. For a bound object file, it prints the date and time compiled for each component. The active function returns the first line of output that would be printed if you invoked it as a command. ARGUMENTS path is the pathname of an object segment, bound object segment, bound object multisegment file (MSF), or an archive of object segments. components are names of components in a bound object file or archive of object segments. If you supply component names, information on only these components is listed. CONTROL ARGUMENTS -brief, -bf lists only the date and time compiled (see "Examples"). 11/86 3-190 AG92-06A -long, -lg lists the date and time compiled, the file name! your User_id, and the long form of the compiler identifier (see "Examples"). I NOTES If an archive is listed! the bind file is ignored. If you give neither control argument! dtc lists the date and time compiled! the file name! your User_id! and the short compiler identifier (see "Examples"). I EXAMPLES To check the compilation date of a private version of the list command in your working directory, type dtc list -bf 04/11/83 0922.2 To check information on the latest compilation of a Multics-system-installed command that is unbound, such as demo_command, type dtc >system_library_standard>demo_command 03/09/83 i615.2 demo_command ARomanov.SysMaint.a PL/i To get compilation information on an entire bound object segment that is part of the standard M ultics system. type dtc >sss>bound binder - - Bound 10/26/83 1337.4 bound_binder_ ARomanov.SysMaint.a binder 07/26/82 1048.4 bind ARomanov.SysMaint.a PL/I 10/26/83 1328e2 bx_ ARomanov.SysMaint.a cds 12/27/82 1354.3 old_make_bindmap_ BDerek.SysMaint.a PL/I To get detailed information on one component of a bound object segment (in this case, bind in bound_binder->, type dtc >sss>bound_binder_ -19 bind 07/26/83 1048.4 bind ARomanov.SysMaint.a Multics PL/I Compiler, Release 25q, of May 22, 1983 11/86 3-191 AG92-06A Name: date_deleter SYNTAX AS A COMMAND FUNCTION deletes segments and multisegment files (MSFs) older than a specified number of days or older than a given date-time. ARGUMENTS dir_path is the pathname of the directory in which the deletions are to occur; dir_path can be -workinLdirectory (-wd) to indicate the working directory. cutoff is a positive integer number of days. If it is an integer N, files with a date more than N days old are deleted; if it is a date-time DT, files with a date earlier than DT are deleted. (See Section 1 for a description of valid DT valUes.) star_names are the optional starnames of files to be deleted. If you supply none, all files older than the specified number of days are deleted; otherwise only files matching one or more of the starnames, and older than the specified number of days, are deleted. CONTROL ARGUMENTS -absolute_pathname, -absp prints the entire pathname of the entnes listed by -long, -query_all, and -query_each. (Default: to print entrynames) -all, -a, -branch, -br deletes directories, segments, and multisegment files. -date_time_contents_modified, -dtcm uses the date/time value specified in the dtcm attribute to calculate date. (Default) deletion -date_time_dumped, -dtd uses the dtd of each entry instead of the dtcm. -date_time_entry_modified, -dtem uses the dtem of each entry instead of the dtcm. -date_time_used, -dtu uses the dtu of each entry instead of the dtcm. 3-192 AG92-()6 -directory. -dr deletes directories only. -entryname, -etnm prints only the entrynames of the files listed by -query_each rather than the entire pathname. (Default) -long. -query_all. and -file. -f deletes segments and multisegment files. (Default) -long, -lg prints a message of the form "Deleted " for each entry deleted. -multisegment_file. -msf multisegment files only. -name STR. -nm STR specifies a starnarne STR that begins with a minus sign. to distinguish it from a control argument -query_all. -qya lists all entries to be deleted and queries whether they should be deleted or not -query_each. -qye queries for every entry to be deleted. -segment. -sm deletes segments only. EXAMPLES Tne command line date_deleter >ldd>old 7 deletes all files in >ldd>old last modified more than a week ago. The command line date_deleter >udd>Proj>listing_pool 2 **.list deletes all listing files in the directory >udd>Proj>listins-pool that are more than two days old. 3-193 AG92-06 Name: date_time SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION [date_time {time_string} {DT} {-control_args}] FUNCTION returns a date and time value for a specified date-time or the current date-time consisting of a date, a time from 0000.0 to 2359.9, a time zone, and a day of the week. The date and time value is returned as a single quoted string of the form "mm/dd/yy hhmm.m zzz www" (e.g., "06/01/84 0840.9 mst Fri"). The format string to produce this is "Amy / Adm/ Ayc AHd A99v.9MH AxxxxzaAxxxda". ARGUMENTS time_string indicates the date_time about which information is desired. If you supply no time_string, the current date and time are used. The time string is concatenated to form a single argument even if it contains spaces; you need not quote it (See Section 1 f or a description of valid time_string values.) CONTROL ARGUMENTS -language STR, -lang STR STR specifies the language in which month name, day names, and zone names are to be expressed. (Default: the process default) -zone STR STR specifies the zone that is to be used to express the result. process defaul t) (Default: the NOTES Use the print_time_defaults command to display the default language and zone. Use the display_time_info command to display a list of all acceptable language and zone values. Due to exec_corns, etc., that have been built around the expected date_time format, this command does not honor the process date_time format (set by set_time_default>. You are encouraged to use "clock date_time" in place of date_time to get the proper default handling. 3-194 AG92-D6 Name: date_time_after, dtaf SYNTAX AS A COMMAND dtaf A B {-control_arg} SYNTAX AS AN ACTIVE FUNCTION [dtaf A B {-control_arg}] FUNCTION returns "true" if the date-time A is later than the date-time B. ARGUMENTS A and B indicates the date and time about which information is desired (see Section 1 for a description of valid time_string values). CONTROL ARGUMENTS -date, -dt compares only the date portions of A and B as represented in GMT. If the day that A falls on is after the day that B falls on, the value returned is "true". I Name: date_time_before, dtbe SYNTAX AS A COMMAND dtbe A B {-control_arg} SYNTAX AS AN ACTIVE FUNCTiON [dtbe A B {-control_arg}] FUNCTION returns "true" if the date-time A is earlier than the date-time B. ARGUMENTS A and B indicates the date and time about which information is desired (see Section 1 for a description of valid time_string values). 3-195 AG92-06 CONTROL ARGUMENTS -date, -dt compares only the date portions of A and B as represented in GMT. If the day that A falls on is before the day that B falls on, the value returned is "true". SYNTAX AS A COMMAND dteq A B {-control_arg} SYNTAX AS AN ACTIVE FUNCTION [dteq A B {-control_arg}] FUNCTION returns "true" if the date-time strings A and B are equivalent ARGUMENTS A and B indicates the date and time about which information is desired (see Section 1 for a description of valid time_string values). CONTROL ARGUMENTS -date, -dt compares only the date portions of A and B as represented in GMT. If A and B fall on the same day, the value returned is "true". Name: date_time_interval, dti SYNTAX AS A COMMAND dti {time_stringl} time_string2 {-control_args} SYNTAX AS AN ACTIVE FUNCTION [dti {time_stringl} time_string2 {-control_args}J 3-196 AG92-06 date_time_in terval FUNCTION returns the difference between two date values, relative to the first, in offset terms: "0 yr 0 mo --2 da -6 hr 0 min -4.64 sec". You are able to specify that the result be only in terms of certain units. ARGUMENTS time_string1 is the beginning of the interval. If not specified, the current time is used (see "Notes"). time_string2 is the end of the interval. If the end is earlier than the beginning, all numbers are preceeded by a minus sign (see "Notes"). CONTROL ARGUMENTS -brief, -bf specifies that the units displayed are in the abbreviated form (Default). -fractional_digits {N}, -fd {N} specifies the maximum number of fractional digits to be included on the smallest unit The value being formatted is rounded to the number of digits specified. All trailing zeros are removed and then the decimal point if it is last N can't exceed 20. If you supply no N, the maximum is used. (Default 2) -zero_units, -zu specifies that all units are output even if their value is zero (e.g., "2 da 0 hr 0 min 4.2 sec". -language STR, -lang STR STR specifies the language in which the result is to be expressed. This can be in any of the languages known to the date / time system. If STR is "system_lang", the system default is used. If you choose no -language or it is present with STR being "", the per-process default is used. Use the display_time_info command to obtain a list of acceptable language values. -long, -lg specifies that the units displayed are in the singular/plural form. -no_zero_uni~, -nzu specifies that any unit that has a value of zero are not included in the output; however if all units are zero, the smallest is shown with the value of "0". Example: "2 da 4.2 sec". (Default) 3-197 AG92-D6 -units STRs specifies that the result is to be expressed in terms of a given set of units. All arguments following -units on the command line are taken as the set of units to use; therefore make -units, if given, the last control argument You can enter the units in any language available on the site and in any order. All units, however, must be in the same language. These are the units that you can specify: year. month, week, day. hour, minute, second, and .microsecond. The output appears in that order. NOTES When you specify no units, this set is used: years, months. days. hours, minutes. seconds. A default result could look like this: "-2 da -6 hr -4.05 sec"; but if the arguments given were: -fd -units hr min, the same interval could be: -54 hr -0.0676252166666666666 min. Note that there is a truncation in the first instance to two decimal places with the corresponding loss of accuracy. See Section 1 for a description of valid time_string values. SYNTAX AS A COMMAND dtv time_string SYNTAX AS AN ACTIVE FUNCTION FUNCTION returns "true" if the argument is a valid date-time string. "false" otherwise. ARGUMENTS time_string is a string that is checked. Since the concatenation of all the arguments is checked. the argument need not be quoted if it contains white space. (See Section 1 for a description of valid time_string valUes.) 3-198 AG92-06 day EXAMPLES dtv foo returns IIfalse". format_line [dtv 12/31/83 8pm] returns "true". Name: day SYNTAX AS A COMMAND day {time_string} {-control_arg} SYNTAX AS AN ACTIVE FUNCTION [day {time_string} {-control_arg}] FUNCTION returns a one= or two-digit number oi a day oi the month, irom 1 to 31. The format string to' produce this is "AZ9dm". ARGUMENTS time_string indicates the day about which information is desired. If you supply no time_string, the current day is used. The time string is concatenated to form a single argument even if it contains spaces; you need not quote it. (See Section 1 for a description of valid time_string values.) CONTROL ARGUMENTS -zone STR STR specifies thp, zone that is to be used to express the process def aul1) {Default: the NOTES Use the print_time_defaults command to display the default zone. display_time_info command to display a list of all acceptable zone values. Use the * 3-199 AG92-06 day_name Name: day_name SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION FUNCTION returns the full name of a day of the week for a specified date or the current date. The format string to produce this is ""dn". ARGUMENTS time_string indicates the day_name about which information is desired. If you supply no time_string. the current day_name is used. The time string is concatenated to form a single argument even if it contains spaces; you need not quote it. (See Section 1 for a description of valid time_string valUes.) CONTROL ARGUMENTS -language STR. -lang STR STR specifies the language in which month name, day names. and zone names are to be expressed. (Default: the process default) -zone STR STR specifies the zone that is to be used to express the result. process default) (Default: the Use the print_time_defaults command to display the default language and zone. Use NOTES the display_time_info command to display a list of all acceptable language and zone values. 3-200 AG92-06 debug debug Name: debug, db SYNTAX AS A COMMAND debug FUNCTION is an interactive debugging aid to be used in the Multics environment. It allows you to look at or modify data or code. You can stop execution of a program and examine its state by inserting "breakpoints" in the program before and/or during execution. A concise syntax for user requests, coupled with a complete system of defaults for unspecified items. allows you to make many inquiries with little effort Symbolic references permit you to retreat from the machine-oriented debugging techniques of conventionai systems and to refer to variables of interest directly by name. The debug command uses a segment in the home directory to keep track of information about breaks. This segment is named Person_id.breaks. where Person_id is your login name. The break segment is created if not found. If the segment cannot be created. the break features of debug are disabled and unusable. Users who do not need the sophisticated machine level debugging provided by this command should refer to the probe command in this manual. With the debug command you can Look at data or code; Modify data or code; Set a break; Perform (possibly nonlocaI) transfers; Call procedures; Trace the stack being used; Look at procedure arguments; Control and coordinate breaks; Continue execution after a. break fault; Change the stack reference frame; Prin t machine registers; Execute commands. 3-201 AG92-Q6 debug debug These functions are provided by two types of debug requests: data requests and control requests. The first five functions above are performed by data requests; the others. by control requests. Multiple debug requests (either data or control) can be placed on a line separated by semicolons (;). NUMBER REPRESENTATION CONVENTIONS Debug uses both octal and decimal' representation of numbers. In general, machine-dependent numbers such as pointers. offsets, and registers are assumed to be octal, while counting arguments (e.g., specifying a source line number. printing the first 20 lines) and variables referenced by name are assumed to be decimal. A decimal default can be changed to octal by preceding the number with the escape sequence "&0". An octal default can be changed to decimal by preceding the number with "&d". Example Descri ption x assign the value 8 to the program variable x. Program variables ref erenced by name are assumed to be decimal; if octal representation is preferred. type: x = &010 $q = 8 77 assign the value of 77 to the q-register. Register values are machine dependent and assumed to be octal; if decimal representation is preferred. type: $q = &d63 I test I &a19 print line 19 of the source segment for test. &a19,s8 print 8 source lines, beginning at line 19. DAT A REQUESTS Data requests consist of three fields and have the following format: The generaiized address defines the actual data or code of interest. It is ultimately reduced to segment number and offset by debug before being used. The operator field indicates to debug which function to perform, e.g., print or modify the data ref erenced by the generalized address. The operands field mayor may not be necessary, depending on the operator. When these fields are specified. they are separated by blanks or commas. 3-202 AG92-06 debug debug When debug decodes a data request, it parses the generalized address and generates a pointer to the data being referenced. This pointer, called the working pointer. is changed whenever the generalized address is changed. It points into either the working segment, its stack frame, or its linkage section. The actual segment depends on the most recent specification in a generalized address. The form for a generalized address is as follows: / / where each of the four fields is optional. The segment name is either a pathname, a reference name, or a segment number, and defines what is called the working segment. The segment ID specifies which of the data bases associated with the working segment is to be used in setting the working pointer. The segment ID can be one of the following: &s &1 &t &a &p &i refers to the stack frame if the working segment is a procedure segment with an active stack frame. refers to an active linkage section (i.e., one with an entry in the linkage offset table (LOT) for your ring). refers to the working segment itself. refers to the source program for the working segment refers to the parameters of an active invocation of a procedure. refers to an active internal static section (i.e., one with an entry in the internal static offset table (I SOT) for your ring). The offset field is used as an offset within the segment referenced by the working pointer. For the working segment, this offset is relative to the base of the segment. If the working pointer points into an active stack frame, the offset is reiative to the base of that frame. If the working pointer points into an active linkage section, the offset is relative to the beginning of that linkage section. The offset can be either a number or a symbolic name. If a symbolic name is specified, a symbol table must exist for the working segment. See the translator commands for descriptions of symbol table creation. If a symbolic name begins with a numeric character, the escape characters &n (f or name) must precede the name. to avoid interpreting the name as a number. For example: /test/ &n10&t can be used in a debug request to specify the location associated with FORTRAN line number (i.e., label) 10. The relative offset field allows you to relocate the working pointer by a constant value or register. For example, if you wish to reference the fourth word after the stack variable i, you could use /test/i+4 as the generalized address. The relative offset can also assume the value of a register. For example, if the a-register contains the value 4 at the time of a break, then: 3-203 AG92-06 debug debug /test/l00&s$a sets the working pointer to offset 104 from the base of the stack frame. It is important to note that a + sign is not present when a register is used. (See "Registers" below.) The three most common values for the segment In field are &t, &s, and &1. These designate that the working pointer is to refer to, respectively, the working segment itself, its active stack frame, or its active linkage section. In addition, two other possible values of segment In allow alternate methods of ref erring to locations in either the working segment or its stack frame. A segment In of &a refers to the ASCII source program for the working segment Associated with this segment ID is a decimal line number, which must immediately follow the &a. This line number is used to generate a working pointer to the first word of code compiled for that line. A relative offset can follow the line number. Note that the line-number /code-Iocation association can only be determined if a symbol table exists for the working segment This example: /test_seg/ &a219+36 generates a working pointer that points to after the first word of code generated for test_seg. If an offset field is given before the working pointer is generated solely from A segment In of &p refers to If the current defaults specify specifies the parameter that is relative offset can be specified. the thirty-sixth (octal) word in the text line 219 in the source for the segment &a, the offset is ignored. The offset of the line number and the relative offset the parameters of an active invocation of a procedure. an active stack frame, a number following the &p to be addressed. The offset field is ignored, but a This example: /test_seg/ &s;&p4+36,a14 causes the stack frame for test_seg to be the working segment, and the first 14 characters of the data contained at a location 36 words after the beginning of the fourth parameter are printed in ASCII format It is not necessary to specify all four fields of a generalized address. In fact, every field is optional. If a field is not specified, a default value is assumed that is frequently the last value that the field had. For example: /test_seg/line&s+ 3 followed by the generalized address +4 is acceptable. The latter request is equivalent to / test_seg/line&s+ 7 3-204 AG92-Q6 debug debug One time that the defaults assumed are not the values of the previous data request is when a symbolic variable name or label is specified that causes some field to change. If this is the case, debug might recognize that the segment ID, for example, of the previous data request is not valid and set it appropriately. For example: followed by regp would cause the defaults to be changed to if regp is found at a relative offset of 140 (octal) in the linkage section. Note that the segment ID is changed to &1 where it remains until explicitly or implicitly changed again. Defaults are also reset to values different from the previous values when the segment name field is specified in a generalized address. In this case, the following actions are taken: 1) If the segment name begins with &n. take the rest of the characters composing the segment name and go to step 3 below. treating the string as a name. This convention allows the use of debug on segments whose names are composed of numeric characters. 2) If the segment name is really a segment number. this number is used in a search of all active stack frames to see if one exists for this segment. The search is from the highest stack depth (deepest in recursion) to the base of the stack so that if an active stack frame is found. it is the one most recently used. If an active stack frame is found. the generalized address defaults are set as follows: working segment the one specifie-d by the given segment number. offset zero. segment ID &s, i.e.. the working pointer points into the latest stack frame for the working segment. relative offset zero. If no active stack frame is found. the defaults are set as above except that the segment ID is &t instead of &s, i.e., the working pointer points into the working segment itself. 3) If the segment name is a reference name known in this ring. the segment number for the segment being referenced is found. and then the defaults are calculated as if this segment number were given directly. 3-205 AG92-D6 debug debug 4) If the segment name is a pathname, the specified segment is initiated (it can already have been known) and the returned segment number is used as above. 5) If the segment name is of the form segname$entname, the stack is searched from the highest active frame (as in step 2) for the most recent frame associated with the entry point entname in the segment segname. The working segment becomes segname, and the remaining defaults are set as described in step 2. The entire set of defaults that apply to a debug data request can be determined at any time by issuing the .d control request to print defaults. For the format and use of this request, see the description under "Control Requests" below. OPERATOR FIELD OF DATA REQUESTS After decoding the generalized address and determining the working pointer, debug checks the operator. The following five operators are recognized: (comma) print = assign < set a break > alter program control (i.e., "go to") can a procedure If a debug request is terminated before an operator is encountered either by a semicolon or a newline character, the default operator used is ",", i.e., print The one exception is that a blank line is ignored. The first. second, and fifth operators above have operands. PRI NT REQUEST For the print request, there are three optional operands. They are a single character specifying the output mode desired; a number indicating how much output is being requested; and a number in parentheses indicating the size of the output The size has two meanings that are dependent on the output mode being used. 1) If the mode is comp-8 or comp-5, the size is the number of digits plus the sign, if present. 2) If the mode is not comp-8 or comp-5, the size is the number of bits to use in prin ting one item. The size specification is permitted for the following modes: 0, h, d, e, f, p, comp-5, comp-8. It is ignored for the following modes: i, I, a. b, comp-6. comp-7. All of the arguments are optional and spaces can appear between arguments. For example: 142&s,o(18)12 3-206 AG92-o6 debug debug requests that 12 (decimal) half words starting at 142 (octal) in the stack be printed in octal format. The following output modes are available for print requests (see "Output Modes" below f or a full description): a b comp-5 comp-6 comp-7 comp-8 d e el ASCII f bit string f1 COBOL COBOL COBOL COBOL 9 decimal floating point with exponent long floating point with exponent h n 0 p s floating point long floating point graphic half-carriage octal instruction code for 1 i ne number no output octal pointer source statement The request +36,a14 requests that 14 (decimal) characters starting at 36 (octal) words after the current working pointer be printed in ASCII format. The output might be 1416 1416 ">user_dir_dir>" The two numbers printed in most output modes should be interpreted as follows: 1) If the data is from a stack frame. the first number is the relative offset from the base of the stack segment and the second number is the relative offset within the stack frame. If the second number is negative, the variable does not exist in the current stack frame and is a parameter or a global variable. 2) If the data is from a linkage section, the first number is the offset within the combined linkage segment and the second number is the offset within the linkage section. 3) For all other segments, both numbers are the same and represent the offset within the segment. If a mode is not specified for output, the last specified mode is used unless debug realizes another mode is more appropriate (e.g., when a symbol specifies a variable of a different type). If the amount of output is not specified, it is assumed to be one unit, i.e., one word for octal output, one line for source output, one character for ASCII output, etc. 3-207 AG92-D6 debug debug ASSIGN REQUEST When modifying data or code, the operands (at least one is expected) specify the new values to use. For example: i = 8; pel) = 206110, 206132 assigns the decimal value 8 to i and the values 206110 and 206132 to p(l) and p(2), respectively. (It is assumed that both are variables that are defined for the current working segment) If more than one operand is specified in an assignment request, consecutive words starting at the working pointer are changed. This is illustrated by the assignment to the pointer array p. There are nine acceptable forms for assignment operands: 1. octal number 2. decimal number 3. character string 4. register value (see "Registers" below) 5. instruction format input 6. floating point number 7. pointer 8. bit string 9. variable Whether a A variable Assignment overridden number is assumed to be octal or decimal on input depends on the target. referenced by name is assumed to be decimal unless overridden by "&0". to a location specified by offset is assumed to take an octal value unless by n&d". x = 99 (decimal) +2 = 77 (octal) Character strings being input must be bracketed by quote characters (n). Bit strings being input must be bracketed by quote characters and followed by a b. Floating point numbers must not have exponents. 3-208 AG92-06 debug debug The word-offset portion of a pointer value being input can optionally be followed by either a decimal bit offset in parentheses. a ring number in square brackets. or both. If both a bit offset and a ring number are specified. the ring number must follow the bit offset. with no intervening blanks. For example: p = 206125 (29); q = 2521104 [5]; rp = 211 1200 (3) [4] The format for instruction input is (opcode address. tag) The address can specify a base register or a number. For example: /test/Iab2 = (Ida pr6120) (sta prOI2,,·:0) (nop 0) Some value must be given for the address field. The zero opcode is specified by the opcode argo Input of bit strings and character strings changes only those bits or characters specified. i.e.• a full word might not be completely changed. Several types of input can be interspersed in the same assignment request. example: /145/13000 = "names" For &d16 126 When different types of input are specified In one request. you should be aware that the bit offset of the temporary working pointer might be ignored for certain types of input In the example above, the ASCII for "name" is placed at 145113000 and the ASCII for "s" is placed in the first character position of. 145113001. The next assignment argument (&d16) fills in 145113001 with the decimal 16 and hence overwrites the "s" of the previous argument.' In order to better specify more complicated assignments, a repetition factor is provided. Ii a single number' (decimal) appears in parentheses in an assignment. the next data item is assigned repeatedly (Le., the specified number of times), updating the working pointer each time. An example of this is string = (32)" II "alpha" which results in string being modified so that the first 32 (de.cimaI) characters blanks. and the 33rd through the 37th contain the string "alpha". SET BREAK REQUEST A breakpoint is a special modification to the code of a program that. when executed. causes control to pass to debug. You are then free to examine and change the states of variables, set other breaks, continue execution, etc. When setting a break. the working pointer is used directly unless it points into the stack. In that case, the working pointer is temporarily forced to the text. To set a break at the label 3-209 AG92-()6 debug debug loop_here in the program parse_words, type: You can also type /parse_words/loop_here+23< to set the breakpoint 23 (octal) locations after the first word of code for the statement labelled loop_here in the text segment. You can also set a break by specifying a line number. For example: /rand/ &a26< sets a break at the first word of code generated for line 26 (decimal) of the source program. The break number printed by debug when setting a breakpoint is used as the name of the break when referring to breaks. After a break is reset, the break number is reused. (Resetting a break restores the code to its previous value.) Once a break has been set at a given location, another break cannot be set there. The list breaks control requests .bl and . bgl can be used to find out which breaks are set. ALTER PROGRAM CONTROL REQUEST To alter program control by issuing an explicit transfer, type: /216/2176> causing debug to search the stack for an active stack frame for the segment 216 (octal) and set the stack pointer to this frame. It then transfers to 2176 (octal) in the text associated with this stack frame. If no active stack frame is found, debug prints a message and waits for further requests. CALL A PROCEDURE REQUEST You can cause debug to call a specified procedure and return values into specified locations. This is done by specifying := as the operator in a data request. This operator expects one operand that is a procedure name with its associated arguments. There are two slightly different ways to invoke this feature: first, to invoke a procedure as a function call (with the argument n+1 being the returned value); and second, to explicitly call a procedure. When a procedure is invoked as a function reference, the current working pointer is used as the last argument in the argument list and, hence, the procedure returns a value into wherever the working pointer is pointing. For example: 3-210 AG92-06 debug debug /test/fi := sqrt_(2.0) causes the sqrt_ function to be called with the first argument 2.0 and the return argument of fi; debug converts the 2.0 into a floating point number before the call. If no fields are present before the := is encountered. debug does not specify a return argument in the call. (The '- can be thought of as "call" in a PL/I program.) For example: := who sets up a call to who$who with no arguments. The call : = rename (lifoOIl, "moo") and oerename foo moo are functionally equivalent. (See Multics command execution under "Control Requests" below.) The method debug uses in setting up the call is to use ten temporary storage areas, one for each of ten possible arguments. debug converts the arguments appropriately and stores the values in these areas. Each area starts on an even location and consists of eight words. These temporary storage areas can be looked at or altered with For example: standard data requests. They are named %1, ••. , %10 . := cpu_time_and_paging_(O,O,O) %l,d %2,d %3,d prints three decimal numbers. all being return values from hcs_$usage_values. The actual call that debug made had three arguments that were all O. (The first words of the first three storage areas were zeroed out prior to the call.) The above call can also be made as follows: If this is done, the third argument is not zeroed before the call. Variables can also be used as arguments. For example: sum : = sqr t_ (n) No conversion is done by debug if n is fixed and sqrt_ expects a floating argument The above mentioned temporaries can be used to do simple mode conversion. example, to get the floating point representation of 3.7 (in octaI) , type: %1 = 3.7; For ,0 3-211 AG92-06 debug debug To find the ASCII value for 137 (octal), type: %1 = 137137137137 ; ,a4 A reference to one of these storage areas causes the working segment to be changed to the stack segment If one of the arguments in a procedure call is the character %, the temporary storage for that argument is not changed (e.g., overwritten with the usual argument value). Results from some previous work can be passed in that argument position. For example: %2 := sqrt (2.0) : = i oa_ (II ,%) "'e" REGISTERS The hardware registers at the time of a fault (in particular a break fault) are available to you f or inspection or change. These registers are ref erenced by preceding the register name immediately by a dollar sign ($). The register can be looked at by merely typing the register name. For example: $a prints the contents of the a-register at the time of the last fault The value in the a-register can be changed to octal 146 by typing $a = 146 Decimal input is allowed also: $a = &d19 The value in a pointer register, the tpr, or the ppr can be set to a pointer: $prO = 25411173 $ppr :: 512\0 The value assigned must always be a pointer. No assignment may be made to the registers regs, ind, seu, all, or prs. The register name must always be given on the input line. You are warned that the working pointer is not set or referenced by register operations. 3-212 AG92-06 debug debug The predefined register names used by debug are a all aq eaq even exp i nd odd ppr prN pr s q r a 1r regs scu tpr t r xN a-register. alI machine conditions. the a- and q-registers considered as a single register. the exponent, a- and q-registers in floating point format even instruction of Store Control Unit (SCU) data. exponent register. indicator register. odd instruction of seu data. procedure pointer register. pointer register N where N can be 0 through 7. alI pointer registers. q-register. ring alarm register. all registers xO, a, q, aq, exp, tr, and ralr. all SeD data. temporary pointer register. timer register. index register N where N can be 0 through 7. You can change the above registers at will (with the exception of i nd and eaq) with the understanding that if execution continues after the break or transfers directly (via > in a data request), the values of. the hardware registers are set to those of the above registers. The values in the registers are automatically filled in by debug (when it is called or faulted into) with those values associated with the last fault found in the stack. You can override these values with the fill registers (.n and crawlout registers (.e) control requests. See "Control Requests" below. You can also define registers and use them as a small symbolic memory. For example: $sta1 = 600220757100; $nop = 11003 allows you to later specify /test/210&t = $sta1 $nop $nop To print out the contents of all user-defined registers, type: $user The setting and displaying of registers follows the syntax of data requests. However. only the register name and a possible new value can appear in a register request. Registers can be specified in a general data request only in the relative offset field and as operands in assignment requests. Register names must be less than or equal to four characters in length. Some examples of the use of registers follow: 3-213 AG92-D6 debug debug /test/i =$q /test/O = $xO /test/46$xO.a5 CONTROL REQUESTS Control requests provide you with useful'· functions not necessarily related to any specific data. The format for a control request is . Control requests and data requests can be freely mixed on a command line if separated by semicolons. However, certain control requests use the entire input line and hence ignore any semicolons found therein. Spaces are not allowed in most control requests. The following is a list of all control requests and the functions they perform. See "Summary of Data and Control Requests" below for a complete review of all requests. Trace Stack The general form is • t i , j The stack is traced from frame i (counting from 0 at the base of the stack) for j frames. where i and j are decimal integers. If i is less than 0, tracing begins at 0; if i is greater than the last valid frame. then only the last frame is traced. If i is not specified. it is assumed to be 0; if j is not specified, all valid stack frames from i on are traced. The name printed in the stack trace is the primary segment name unless the segment is a PL/I or FORTRAN program in which case it is the entryname invoked for the stack frame (i.e.. the label on the entry or procedure statement). Examples: .t2,3 .tlOO Pop Or Push Stack The general form is . + i or . - i The working segment is changed by moving up or down the stack i frames, where i is a decimal integer. For example. if the working segment's active stack frame is at depth 4 in the stack, then: .+3 3-214 AG92-06 debug debug changes the working segment to the segment whose stack frame is at depth 7 in the stack. The defaults for working pointer. segment ID. and offset are reinitialized to the base of the stack frame, &s, and O. respectively. Set Stack The general form is • i The working segment is set to that of stack frame i (starting at O), where decimal integer. The defaults are set as in pushing or popping the stack. is a Execute Multics Command The general form is •. The input line is interpreted as a standard Multics command line and is passed to the standard command processor with any preceding characters blanked out Any valid Multics command line can be given. When setting breaks, the program being debugged must be called in this manner because debug sets up a condition handler (for break faults) that is active only as long as debug's stack frame is active. Print Defaults The general form is • d or . D The output might look like .vm 6,3,2,20 3 /test_seg/14(0)&t,i 212 or 3 />udd>m>foo>test_seg/14(0)&t,i 212 The first number (3 above) is the stack frame depth in decimal, unless there is no stack frame for the working segment, in which case the number is -1. The name of the working segment appears between the slashes (test_seg above); if • D is used, the full pathname occurs here. The offset appears next (14 above); the bit offset (in decimal) of the working pointer appears next; the segment ID (& t above) appears next; the operator appears next (, for print); the output mode appears next (i for instruction); finally the segment number of the working segment appears (212 above). To find the name/segment number association for a given segment, for example segment number 206. type: /206/,n;.d 3-215 AG92--Q6 debug debug yielding 60 /test_caller/O(O)&S,O 206 Knowing the name, you can obtain the same output by typing /test_caller/,n;.d Conti nue Execution After a Break The general forms are • c, i . c t, i . c r, i If i is not specified, it is assumed to be O. If i is specified, the next i break faults for the current break are skipped. The first instruction executed upon continuation is the instruction on which the break occurred. If a t follows the c, debug continues in temporary break mode (see "Break Requests" below). If an r follows the c, debug resets the mode to normal (not temporary). Examples: •c . ,c,3 .ct continue execution . continue execution, but skip the next three break faults for the curren t break. continue execution in temporary break mode. Quit The general form is %.fnt typ%.q%.fnt% This request returns from debug to its caller. Note that if debug was entered via a break, typing . q returns to the last procedure that explicitly called debug. Change Output Mode Requests pertaining to debug's terminal output begin with .m. 1) Enter brief output mode: .mb This request places debug in brief output mode, which is somewhat less verbose than its normal output mode. In particular, assignment requests and the resetting of breaks are not acknowledged on your terminal; the column headings are not printed for a stack trace; the printing of register contents is somewhat more compact; some error messages are abbreviated. 3-216 AG92-06 debug debug 2) Enter long output mode: • m1 This returns debug to long output mode. which results in fuller and more explicit terminal output. Long mode is the initial default Set I/O Switch Names These requests allow you to debug a program that is run with file output because it generates extensive output or a program that is run from within an exec_com after &attach because it requires much input The general form is .si switch_name .so switch_name where switch_name identifies the switch_name to use for input (.si) or output (.so). The named switch must be attached by you before the request is made. If no switch name is given. debug creates one (either debuK-input or debuLoutput). 1) User makes a switch request but does not give a switch name: •s i .so debug creates a switch named debuK-input or debuK-output and attaches it to the user_i/o switch. This is the usual request for debugging programs that require the user_input or user_output switches to be attached to a file instead of to user~i/o. Debug detaches the debuK-input and debuLoutput switches when you quit debug. 2) User makes a switch request and gives the switch name: .si input_switch .so output_switch You must attach t.lJe switch_name before making the request This can be used when you want to read debug requests from a file. The switches can be restored by typing .si user_input .so user_output Examples: You have directed the output switch named user_output to a segment. but wants debug diagnostics to be printed on the terminal. This can be done by typing debug .so 3-217 AG92-06 debug debug Since a switch name is not given with the request, debug sets up a new I/O switch named debu~output as a synonym for user_i/o, which is the terminal in this case. When you quit debug, the switch named debu~output is detached. You want to debug a procedure that uses the user_input switch and has a set of debug requests in another segment named debu~macro. An input switch named macro has been attached to the segment of debug requests. You type debug .si macro and debug takes requests from the switch named macro and does not detach the switch when you exit debug. An attempt by debug to read beyond the end of the macro input stream results in an exit from debug. Break Requests The following control requests are specific to breaks and begin with . b. Reference is made to the default object segment, which is merely that segment that debug is currently working with when performing break requests. The default object segment is generally specified implicitly when a break is set or hit. It can be changed and determined upon request. The default object segment used for break requests is not necessarily the same as the segment addressed by the working pointer used in data requests. Breaks are numbered (named) sequentially starting at 1 but the numbers are unique only for the object segment in which the break resides. You can have several breaks with the same number defined in different object segments. There are two types of global requests that can be performed on breaks. The first. or subglobal requests, refer to all breaks within the default object segment. The second, or global requests, refer to all breaks set by you (as determined from the break segment in the home directory). The subglobal request is specified by omitting the break number in a break request. The global request is specified by a "g" immediately after the "b" of all break requests (see below). The general form of all break requests is . bgx i args where the "g", the number i. and the arguments are optional. The "x" is replaced by the control character for the break request desired. The following break requests are currently defined: 1) Reset a break (or breaks). The forms of the requests are . br i • br . bgr to reset break i of the default object segment. to reset all breaks of the default object segment. to reset all breaks known to debug. 2) List (print information about) a break. The forms of the request are 3-218 AG92-06 debug debug •b 1i •b 1 .bgl to list break i of the default object segment to list all breaks of the default object segment to list all breaks known to debug. 3) Execute a debug request at break time. The forms for this request are .bei .be .bge Specifying the above request causes to be interpreted as a debug input line whenever the appropriate break(s) is encountered. If is nUll, the specified breaks have this execute feature reset to normal. 4) Disable a break (or breaks). The forms of this request are · bo i disable (turn off) break i of the default break segment · bo disable all breaks in the default break segment • bgo disable all breaks known to debug. Disabling a break has the effect of preventing the break from being taken without discarding the information associated with it You can disable a break rather than reset it if the break is to be needed again in the future. A disabled break can be eliminated altogether (reset) by the • br request, or reenabled by the • bn request If the break has already been disabled, these requests have no effect 5) Enable a break or breaks. The forms of this request are • bn i · bn • bgn enable (turn on) break i of the default break segment enable all breaks in the default break segment enable all breaks. This request restores a previously disabled break. If the break was not disabled, the request has no eff eel 6) Establish a temporary command line to encountered. This request is of the form: be executed whenever breaks are .bgt This causes to be executed as a debug request whenever any break is encountered during the current process. The difference between this request and • bge is that when • bge is typed, the associated line remains associated with all breaks until they are reset, or until they are changed by .be requests. It is possible to have a temporary global command without removing request lines associated with individual breaks. If is nUll, a previously-established temporary command line is disestablished. 3-219 AG92-{)6 debug debug 7) Break conditionally. The following requests allow you to change a break into a conditional break, i.e.• a break that stops only if a certain condition is met .bei argl arg2 .be argl arg2 arg 1 and arg2 can be constants or variables; can be = or A=. Whenever a specified break is encountered. a test is made to see if the equality exists and breaks according to whether you specified = or ""= in setting up the conditional break. For example: .be3 i ""= 0 causes break 3 to fault whenever it is encountered and the value of Another example: .be3 i is nonzero. =j causes break 3 to fault whenever it is encountered and the value of i is the same as the value of j. The comparison is a bit by bit comparison with the number of bits to compare being determined by the size and type of the second argument If no arguments are given to a set conditional request. the specified break is set back to a normal break. For example: .be causes all breaks of the default object segment to fault normally. 8) Specify the number of times a break should be ignored (skipped). The general form is .bsi N This causes the number of skips to be assigned to break i of the default object segment to be N. 9) Print or change the default object segment The form for this request is .bd name where name is the (relative) pathname. reference name, or segment number of the segment to become the default object segment. If name is not specified, the pathname of the default object segment is printed. 10) List the current segments that have breaks. The form for this request is .bp This request merely interprets the break segment in the initial working directory. 3-220 AG92-Q6 debug debug Print Arguments The general form is • ai, m Argument i for the current stack frame is printed in the mode specified by m. If i is not specified. all arguments are printed. If m is not specified, debug decides the output mode. Valid values for mare o p d a b I e,f ? full word octal pointer decimal ASCII bit string location of argument floating point debug decides (the default value for m) Examples: .a3 ARG 3: ">user_dir_dir" .a3,o ARG 3: 076165163145 Get Fault Registers The general form is . f For register requests debug uses the machine registers of the last fault found in the stack starting at the frame currently being looked at. (This is the default when debug is entered as a result of a break fault.) Crawlout Registers The general form is • C For register requests debug uses the fault data associated with the last crawlout (abnormal exit from an inner ring). PROGRAM INTERRUPT FEATURE You can interrupt debug by pressing the quit button at any time, in particular during unwanted output To return to debug request level (Le.• to where debug waits for a new request), type: 3-221 AG92-06 debug debug pi which is the standard program interrupt manager. program_interrupt command.) (See the description of the TEMPORARY BREAK MODE When debug is in temporary break mode (placed there via a • c t control request), the following actions are taken automatically: 1) When you continue any break, another (temporary) break is set at the first word of code for the next line of source code after the source statement containing the break being continued. If debug cannot determine the location of the next line of source code, the temporary break is set at the word of object code immediately following the break being continued. 2) A temporary break is restored automatically whenever it is continued. A temporary break must be explicitly reset by you only when it is not continued. Since temporary breaks are set sequentially in a program (i.e., at the next statement in the source program), any transfers within a program can either skip a temporary break or cause code to be executed that was stopped earlier with a temporary break. Temporary break mode is designed to be used in programs that are fairly uniform and sequential in their flow of control. You should list breaks after using temporary break mode to see if any breaks remain active. INDIRECTION It is quite often desirable to reference the data pointed to by the pointer that is pointed to by the working pointer, i.e., to go indirect through the pointer.. You can instruct debug to do this by typing * instead of the segment name, offset, and segment ID in a generalized address. For example: /test/regp might print 1260 110 21412360 To find what two octal words begin at 21412360, type: *,02 This causes the working pointer to be set to 21412360 and not necessarily point into the same segment as before the request. 3-222 AG92-G6 debug debug IMPLEMENTATION OF BREAKPOINTS Breakpoints are implemented by using a special instruction (mme2) that causes a hardware fault whenever it is executed. When the fault is first encountered in a process using the standard process overseer. a static handler for the fault is set up that passes control to debug. When debug is entered via a break, it does the following: 1) fills the registers with those of the break fault; 2) prints the location of the break fault; 3) waits for requests. When continuing after a break fault, debug changes the control unit information so that when it is restarted. it executes the instruction that used to exist where the break word was placed. The debug command keeps track of a default object segment. All break requests made are relative to the default object segment. For example. any reference to break 3 really means break 3 of the default object segment. To change (or find out) the value of the default object segment, the • bd request should be used. VARIABLE NAMES FOR PLII AND FORTRAN PROGRAMS If a symbol table was created for a PL/I or FORTRAN program using the table option, then names of labels, scalars, structures, and arrays can be used. The only restrictions are 1) that the entire structure name must be specified; 2) the only expressions that are allowed for subscripts are of the form: variable +/- constant where var i ab 1e can be an arbitrary reference as above; 3) all subscripts must appear last. If a variable is based on a particular pointer, that pointer need not be specified. Some examples of valid variable references are p-> a. b. c (j ,3) a"b p(3,i+2) -> qp.a.b(x(x(4)+l)->j.a BIT ADDRESSING When a working pointer is a substructure, a bit offset When making references to relocated addresses can still generated to a data item that is based on or is a part of may be required. This bit offset is indeed kept and used. data relative to a working pointer with a bit offset, the contain a bit offset For example, if the working pointer 3-223 AG92-06 debug debug has the value 151 137 06 (13) then the request +16,b3 sets the working pointer to 15 1 137 24 (13} and prints the three bits at this location. OUTPUT MODES The following output modes are acceptable to debug: o The data pointed to by the working pointer is printed in full word octal format, eight words per line. h Half carriage octal: the data is printed as in words per line are printed. d The data is printed in decimal format. eight words per line. a a The data is interpreted as ASCII and printed as such. characters are printed in response to a single request. 0 format except that only four No more than 256 i The data is printed in instruction format. p The data is printed in pointer format, i.e., segment number and offset (and bit offset if nonzero). s One or more source statement lines are printed starting with the line of source code that generated the code pointed to by the working pointer (assumed to be pointing into the text). For example: /test/loop_here+32,s2 prints two lines of source code starting with the line that generated the code, 32 (octal) words after the label loop_here. Another example: /test/&a219,s 3-224 AG92-()6 debug debug prints line number 219 (decimal) of test lang where lang is the appropriate language suffix. Note that if there was no code generated for the specified line. debug prints a message. increments the line number, and tries again for up to 10 lines. The code associated with the specified line number is printed in instruction format The line number is determined as in s type output. For example: /test/&a27,1 prints the code generated for line 27 (decimal) of test lang. n No output. This is used to suppress output when changing defaults. e Floating point with exponent (single precision) el Long floating point with exponent (double precison). f Floating point (single precision). fl Long floating point (double precision). b The data is printed as if it were a bit string. No more than 72 bit positions are printed in response to a single request. g The specified number of characters are interpreted as Multics standard graphics code. The type and value of each recognizable item is printed to the terminal. (Refer to the Muitics Graphics System Manuai, AS40, for details.) comp-5, comp-6. comp-7. comp-8 The data is printed as if it were a COBOL data type. If the size field is used for cornp-5 or comp-8, it is the number of digits plus sign to use in printing the data. comp-5 comp-6 comp-7 comp-8 byte-aligned packed decimal full-word binary integer half-word binary integer digit-aligned packed decimal 3-225 AG92-06 decat decat Name: decat SYNTAX AS A COMMAND decat strA strB C SYNTAX AS AN ACTIVE FUNCTION [decat strA strB C] FUNCTION performs operations on bit or character strings. These operations are specified by a three-digit bit string given last in the usage line. ARGUMENTS strA. strB are character strings or bit strings entered as 0 and 1 characters. c is any three-digit bit string expressed as 0 and 1 characters such as 000.001 •...• 111. NOTES The first occurrence of strB found in strA divides strA into three parts: part prior to strB, part matching strB, and part following strB. The digits given in C correspond to these three parts. The return string contains the parts of str A whose corresponding bit in C is 1. All three parts are returned in their original order of appearance in strA. EXAMPLES decat abcdef123ghi 123 110 abcdef123 string [decat decat. incl.pl1 • incl 101] decat.pl1 3-226 AG92-06 decode decimal Name: decimal, dec SYNTAX AS A COMMAND dec values SYNTAX AS AN ACTIVE FUNCTION [dec va 1ues] FUNCTION returns one or more values in decimal. ARGUMENTS value is a value to be processed. The last character of the value indicates its type. Acceptable types are binary (b), quartenary (q), octal (0), hexadecimal (x), or unspec (u). Any valid PL/I real value is allowed. The absence of any specifier means decimal. The unspec value is limited to eight characters. EXAMPLES dec 110. 1b 6.5 string [dec abcu] 25478243 Name: decode SYNTAX AS A COMMAND decode pathlA {path2A ••• pathlN path2N} {-control_arg} FUNCTION reconstructs an original segment from an enciphered segment according to a key that is not stored in the system. The encode command is used to encipher segments. 3-227 AG92-Q6 decode decode ARGUMENTS pathlA is the pathname of an enciphered segment The code suffix should not be specified because the command attaches the code suffix to the pathl argument (e.g., if you type alpha_x. code as the pathl argument, the command attaches the suffix and looks for a segment named alpha_x. code. code). The star convention is allowed. path2A is the pathname of the deciphered segment to be produced. If the last path2 argument is missing, the command constructs a pathname from the pathl argument (see "Notes" below). The equal convention is allowed. CONTROL ARGUMENTS -key STR specifies the encipherment key STR on the command line and does not query for one. This control argument is useful in exec_corn's for multiple invocations of the command with the same key. NOTES The .decode command requests the key from the terminal only once. specified in an invocation of decode are deciphered with the same key. All segments If the last path2 argument is not given, the command places the deciphered segment in a segment whose name is the pathl argument. minus the code suffix. EXAMPLES If you type the command line decode alpha_x the command looks for an enciphered segment named alpha_x. code and places the deciphered segment produced in a segment named alpha_x, 3-228 AG92-Q6 default SYNTAX AS A COMMAND dac STR SYNTAX AS AN ACTIVE FUNCTION [dac STR] FUNCTION decodes a character string produced by the encode_access_class command or the convert_access_class_$encode subroutine to return the authorization or access class. ARGUMENTS STR is the encoded access class string to be decoded. The null string is converted to the string "system_low." Name: default SYNTAX AS A COMMAND default STRA {STRB} SYNTAX AS AN ACTIVE FUNCTION [default STRA {STRB}] FUNCTION supplies default arguments to commands and can override this default when desired. Use this command with the abbrev and do commands. NOTES If you provide no STRB or it is the null string, STRA is returned (see "Examples"). * EXAMPLES In the first example, you set up an abbreviation using the default active function to automatically compile a program with the -map and -table control arguments. You can override the defaults by specifying more than one argument when using the abbreviation. Assume that comp_pll is an abbreviation for 3-229 AG92-o6 def ault_wdir default do "p11 &1 [default IIII-map -tab1e'"' &2] &f3" Thus typing "comp_pU test" is the same as typing "pH test -map -table"; typing "comp_pH test -list -profile" is the same as typing "pH test -list -profile". The next example shows the null input feature of the default active function. Assume that my_dp is an abbreviation for do "dp -he [string [default [entry &1] &r2]] -q [default 3 &3] &f4 &1" When you type the command line my _dp >udd>Demo>Bach>des i gn_memo. runout '"' 2 -d 1 the null input for the second argument means that default uses the default value for this argument (in this case, the entryname portion of the pathname). Thus the expansion of the command line is dp -he design_memo.runout -q 2 -d1 >udd>Demo>Roy>design_memo.runout Name: default_wdir, dwd SYNTAX AS A COMMAND dwd SYNTAX AS AN ACTIVE FUNCTION [dwd] FUNCTION returns the pathname of the default working dhectory of the process in which you 'invoke it, as set by the change_default_wdir command. 3-230 AG92-()6 Name: defer_messages, dm SYNTAX AS A COMMAND dm {mbx_specification} FUNCTION suspends printing of messages. ARGUMENTS mbx_specification specifies the mailbox on which messages are to be deferred. If not given, the user's default mailbox (>udd>Project>Person>Person.mbx) is used. I LIST OF MBX SPECIFICATIONS -log specifies the user's logbox and is equivalent to -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx -mailbox path, -mbx path specifies the pathname of a mailbox. The suffix .mbx is added if necessary. -save path. -sv path specifies the pathname of a savebox. The suffix .sv.mbx is added if necessary. -user STR specifies either a user's default mailbox or an entry in the system mail table. STR is any noncontrol argument and is first interpreted as -mailbox STR; if no mailbox is found, STR is then interpreted as -save SIR; if no savebox is found, it is interpreted as -user STR. NOTES Deferred messages stay in your mailbox until you issue print_messages. immediate_messages command restores printing of messages as you get them. The For a description of mailbox creation and characteristics see accept_messages. 11/86 3-231 AG92-o6A delete delete Name: delete, dl SYNTAX AS A COMMAND dl {paths} {-control_args} FUNCTION deletes the specified segments, multisegment files (MSFs), data management (DM) files, and/ or extended entries. Use delete_dir to delete directories, unlink to delete links. ARGUMENTS paths are the pathnames of segments, MSFs, DM files, or extended entries. You can use the star convention. CONTROL ARGUMENTS -absolute_pathname, -absp prints the entire pathname of entries listed by -lg, -qya, and -qye. -brief, -bf does not print an error message if a segment, MSF, or DM file to be deleted is not found. =chase deletes targets of links specified by paths as well as segments. -entryname, -etnm prints only the entrynames of the entries listed by -lg, -qya, and -qye, rather than the entire pathname. (Default) -force. -fc deletes the specified entries, whether or not they are protected, without querying. -in terpret_as_extended_en try, -inaee interpret the selected entry as an extended entry type. -in terpret_as_standard_en try, -inase interpret the selected entry as a standard entry type. -long. -lg prints a message of the form "Deleted file " for each entry deleted. 11/86 3-232 AG92-06A delete delete -name STR, -nm STR specifies a nonstandard entryname STR (e.g., an invalid star name such as **.**.compout or a name containing <). -no_chase does not delete targets of links. (Default) -query_all, -qya lists all segments to be deleted and queries whether they should be deleted or not Unless you give -fc. an individual query is given for protected segments. 11/86 3-232.1 AG92-06A delete -query_each, -qye queries for every entry to be deleted. whether it is protected or not Prote.cted segments are noted in the query. ACCESS REQUIRED You must have modify permission on the containing directory. NOTES You must supply at least one path or -name STR. To delete a segment or MSF the entry must have both its safety switch and its copy switch off. If either is on. you are interrogated whether to delete the entry. You can't delete OM files if a transaction is still pending. Name: delete_acl, da SYNTAX AS A COMMAND da path {User_ids} {-control_args} FUNCTION removes entries from the access control lists (ACLs) of nonlink entries in a directory. (For a description of ACLs see the Programmer's Reference Manual.) ARGUMENTS path is the pathname of an entry. If it is -workin~directory (-wd), your working directory is assumed. The star convention is allowed. User_ids are access control names of the form Person_id.Project_id.tag. All ACL entries with matching names are deleted. If you give no User_ids, your Person_id and current Project_id are assumed. CONTROL ARGUMENTS -all, -a deletes all ACL entries except for *.SysDaemon.*. -brief, -bf suppresses the messages "User name not on ACL" and "Empty ACL" 3-233 AG92-o6 -chase chases links when using the star convention. Links are always chased when path is not a star name. -directory. -dr affects only directories. (Default: segments. multisegment files. and directories) -no_chase does not chase links when using the star convention. (Default) -segment. -sm affects only segments and multisegment files. -select_entry_type STR. -slet STR affects only entries of the entry type selected by SIR. which is a comma-delimited list of file system entry types. Use the list_entry_types command to obtain a list of valid entry type values. Example: da ** -slet mbx.segment. ACCESS REQUIRED You need modify permission on the containing directory. Name: delete_dir, dd SYNTAX AS A COMMAND dd {paths} {-contro l_args} FUNCTION deletes the management contents are command to specified directories and any segments. links. multisegment files, data files, and extended entries they contain. All inferior directories and their also deleted. Use the delete command to delete segments and the unlink delete link entries. ARGUMENTS paths are pathnames of directories. The star convention is allowed. CONTROL ARGUMENTS -absolute_pathname. -absp prints the entire pathname of the entries listed by -long. -query_all, and -query_each. 3-234 AG92-06 delete dir delete dir -brief. -bf inhibits the printing of an error message if the directory to be deleted is not found. -entryname. -etnm prints only the entrynames of the entries listed by -long. -query_all, and -query_each. (Default) -force. -fc deletes the specified directories without issuing a query. -long. -lg prints a message of the form "Deleted directory " for each directory deleted. -name SIR. -nm STR specifies a nonstandard entryname SIR which begins with a hyphen or contains ASCII control characters or any of the nonstandard characters n. <. >. $. %, ? *. =, (,), [, ], ::. -query_all. -qya lists all directories to be deleted. and issues one query for all of them. -query_each. -qye issues a query for each directory being deleted. (Default) ACCESS REQUIRED You must have modify permission on both the directory and its superior directory. NOTES At least one path or -name must be given. If -force is not supplied. delete_dir asks you whether to delete the spe-eified directory; it is then deleted only if you type "yes." When deleting a nonempty master directory. or a directory containing inferior nonempty master directories, you must have previously mounted the logical volume(s). If a nonempty master directory for an unmounted volume is encountered. no subtrees of that master directory are deleted, even if they are mounted. When you are deleting a directory containing data management files, you can't delete those files if a transaction is still pending. 11/87 3-235 AG92-D6B delete_external_variables Name: delete_external_variables, dey SYNTAX AS A COMMAND dev names {-control_arg} FUNCTION deletes from your name space specified variables managed by the system for you. All links to those variables are unsnapped and their storage is freed. ARGUMENTS names are the names of the external variables, separated by spaces, to be deleted. CONTROL ARGUMENTS -unlabeled_common, -uc indicates unlabeled (or blank) common. SytvTAX AS A COIVlIVlAND did path {User_ids} {-control_args} FUNCTION deletes entries from a directory's initial access control list (initial ACL) in a specified directory. A directory initial ACL contains the ACL entries to be placed on directories created in the specified directory. (For a description of initial ACLs. see the Programmer's Reference Manual.) ARGUMENTS path specifies a pathname of the directory whose directory initial ACL should be changed. If path is -workinLdirectory (-wd) or omitted, your working directory is assumed. The star convention is allowed. User_ids are access control names of the form Person_id.Project_id.tag. All entries in the directory initial ACL that match the User_ids are deleted (for a description of the matching strategy. see the set_acl command). If you give no User_ids, your Person_id and current Project_id are assumed. 3-236 AG92-06 CONTROL ARGUMENTS -all, -a deletes the entire directory initial ACL except an entry for *.SysDaemon.*. -brief. -bf suppresses the messages "User name not on ACL of path" and "Empty initial ACL." -ring N. -rg N identifies the ring number whose directory initial ACL is to be deleted. It can appear anywhere on the line and affects the whole line. If present, follow it by N (where 0 <= N <= 7). If not given, your ring is assumed. ACCESS REQUIRED You must have modify permission on the directory. EXAMPLES The command line did news .Faculty Dickinson •• deletes from the directory initial ACL of the news directory all entries ending in .Faculty.* 'and all entries with Person_id Dickinson. The command line did -a deletes all entries from the directory initial ACL of the working directory. The command line did store Emerson -rg 5 deletes the entry for Emerson.*.* from the ring 5 directory initial ACL of the store directory. 3-237 AG92-Q6 SYNTAX AS A COMMAND dis path {User_ids} {-control_args} FUNCTION deletes entries from a segment initial access control list (initial ACL) in a specified directory. A segment initial ACL contains the ACL entries to be placed on segments created in the specified directory. (For a discussion of initial ACLs, see "Access Control" in the Programmer's Reference Manual.) ARGUMENTS path specifies the pathname of a directory whose segment initial ACL is to be changed. If it is -workin~directory (-wd) or omitted. your working directory is assumed. The star convention is allowed. User_ids are access control names of the form Person_id.Project_id.tag. All entries in the directory initial ACL that match the User_ids are deleted. (For a description of the matching strategy, see the set_acl command.) If you give no User_ids, your Person_id and current Project_id are assumed. CONTROL ARGUMENTS -all, -a deletes the entire initial ACL except an entry for *.SysDaemon.*. -brief. -bf suppresses the messages "User name not on ACL of path" and "Empty initial ACL." -ring N, -rg N identifies the ring number whose directory initial ACL is to be deleted. It can appear anywhere on the line and affects the whole line. If present, follow it by N (where 0 <= N <= 7). If not given. your ring is assumed. ACCESS REQUIRED Your must have modify (m) permission on the directory. 3-238 AG92-06 EXAMPLES The command line dis news .Multics. JJoyce deletes from the segment initial ACL of the news directory all entries with Project_id Multics and the entry for JJoyce.*.*. The command line dis -a deletes all entries from the segment initial ACL of the working directory. The command line dis store Hawthorne •• -rg 5 deletes all entries with Person_id Hawthorne from the ring 5 segment initial ACL of the store directory. Name: delete_message, dIm SYNTAX AS A COMMAND dlm mS9_specs {mbx_specification} {-control_args} FUNCTION deletes any interprocess messages that were received (and saved in the user's mailbox) while the user was not accepting messages, not logged in, or "accept_messages -hold_messages" was in effect. ARGUMENTS ms~specs are one or more numbers or ranges. Numbers are as printed next to each message when "accept_messages -hold_messages" is in effect. Ranges are of the form N:1vl, where N<=M and both Nand M are valid message numbers. IOU can use the keywords "first" (0 and "last" (1) as message num bers and the keyword "all" (a) as a range (equivalent to "f:l"). mbx_specification specifies the mailbox from which messages are to be deleted. If not given. the user's default mailbox (>udd>Project>Person>Person.mbx) is used. 11/86 3-239 I AG92-06A LIST OF MBX SPECIFICATIONS -log specifies the user's logbox and is equivalent to -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx -mailbox path, -mbx path specifies the pathname of a mailbox. The suffix .mbx is added if necessary. -save path, -sv path specifies the pathname of a savebox. The suffix .sv.mbx is added if necessary. -user STR specifies either a user's default mailbox or an entry in the system mail table. STR is any noncontrol argument and is first interpreted as -mailbox STR; if no mailbox is found, STR is then interpreted as -save STR; if no savebox is found, it is interpreted as -user STR. CONTROL ARGUMENTS -after time_string deletes messages sent after time_string only (see "Notes"). -all, -a delets all messages, including those held by -hold_messages mode (see accept_messages). -before time_string deletes messages sent before time_string only (see "Notes"). -brief, -bf suppresses an error message when no matching messages are found. -comment STR, -com STR deletes messages with comment fields containing STR only. -exclude STR deletes messages with text not containing STR only. -force, -fc deletes selected unseen messages. -from STR, -fm STR deletes messages sent from STR only. STR can be of the form Person. Project, Person, or .Project. 3-240 AG92-06 -long, -}g overrides -brief. -match STR deletes messages with text containing STR only. -messages, -msg deletes regular messages (nonnotifications) only. -no_force, -nfc prevents deletion of unseen messages. (Default) -no_messages, -nmsg suppresses -messages. -no_notifications, -nnt suppresses -notifications. -notifications, -nt deletes notifications only. NOTES If you supply no mailbox. your default one is assumed (for a description of the mailbox see accept_messages and print_maiD. See Section 1 for a description of valid time_string values. Name: delete_name, do SYNTAX AS A COMMAND dn {paths} {-control_args} FUNCTION deletes specified name(s) from segments, multisegment files (MSFs), links, directories, data management (DM) files, or extended entries that have multiple names. ARGUMENTS paths are the pathnames to be deleted. This argument can be "-name STR" to specify a nonstandard name, such as one beginning with a minus sign or containing * or >. The star convention is allowed, but does not apply to STR. 3-241 AG92-o6 delete name delete name ARGUMENTS paths are the path names of a segment, multisegment file, directory, extended entry, or link. This argument can consist of "-name STR" to specify a nonstandard entryname STR which already exists and which begins with a hyphen or contains ASCII control characters or any of the nonstandard characters n, <, >, $, %, ?, *, =, (, ), [, ], ::. CONTROL ARGUMENTS -brief, -bf suppresses error messages when entries are not found with specified pathnames. -long, -lg prints error messages when entries are not found. (Default) ACCESS REQUIRED You need modify permission on the parent directory. NOTES Specify at least one path or "-name STR." The final portion of the relative or absolute pathname is deleted from the storage system entry it specifies, provided that doing so does not leave the segment or directory without a name, in which case an error message is printed. See the add_name and rename commands. EXAMPLES The command line dn alpha >my_dir>beta deletes the name alpha from the names of an entry in the current working directory and also deletes the name beta from the names of an entry in >my_dir. 11/87 3-242 AG92-o6B Name: delete_search_paths, dsp SYNTAX AS A COMMAND dsp search_list search_paths {-control_arg} FUNCTION allows you to delete one or more search paths from the specified search list ARGUMENTS search_list is the name of the search list from which the specified search paths are deleted. Quote it if it contains spaces or other command language characters. search_paths specifies a search path to be deleted. The search path must be an absolute pathname. Use the same name that appears when you invoke print_search_paths. CONTROL ARGUMENTS -all; -8 specifies that the search list itself is to be deleted. Any search paths specified are ignored. Use -all to delete all the search paths in a search list NOTES For a complete list of the search facility commands see add_search_paths. Name: delete_search_rules, dsr SYNTAX AS A COMMAND dsr paths FUNCTION deletes search rules for object segments. ARGUMENTS paths are usually directory pathnames (relative or absolute) to be deleted from the current search rules. One of the paths can be the keyword workin~dir (see "Notes"). 11/86 3-243 AG92-06A NOTES This command accepts no site-defined keywords and no home_dir and process_dir; add_search_rules does. Even though dsr accepts initiated_segments and referencin~dir, be careful because their deletion may lead to unpredictable results. Name: delete_volume_quota, dlvq SYNTAX AS A COMMAND dlvq logical_volume account FUNCTION deletes a quota account for a logical volume; used by the volume executive (the owner or manager of logical volumes). ARGUMENTS logical_volume is the name of the logical volume from which quota is to be deleted. account is the name of the quota account (in the form Person_id.Project_id. tag) to be deleted. ACCESS REQUIRED To use this command you must have e access to the iogical volume. necessary that the volume be mounted. It is not NOTES You can~t delete the quota account if there are still master directories whose quotas are charged against the account to be deleted. You must either delete such directories or transfer them to another account (see the set_mdir_account command). 11/86 3-244 AG92-06A Name: describe_entry_type, dset SYNTAX AS A COMMAND dset type {-control_args} SYNTAX AS AN ACTIVE FUNCTION [dset type -control_arg] FUNCTION prints or returns information about a file system entry type. 11/86 3-244.1 AG92-06A ARGUMENTS type identifies a storage system entry type. Use the list_entry_types command to obtain a list of entry type values. CONTROL ARGUMENTS -all. -a prints all information about the entry type, which includes name, plural name, access modes, supported attributes, and the default values and all names for switches. You can't use -all in the active function. -attributes, -attr prints or returns the names of the storage system attributes that this entry type supports. These are the attributes that can be copied or moved by the copy .and move commands. -default NAME prints or returns the default value of the specified switch for this entry type. You can give only one -default argument. This control argument is incompatible with -all and -switches. -extended_acl. -xacl returns "true" if the entry type supports extended ACLs, "false" otherwise. You can Use it only in the active function. -info_pathname, -ipn prints or returns the pathname of an info segment containing more information about the entry type, if such an info segment is available. -modes prints or returns the acceptable access modes for the specified entry type. -name, -nm prints or returns the name of an entry of the selected entry type. -plural_name, -plnm prints the plural name of the specified entry type. -switches prints the names and default values of all switches supported by the entry type given. NOTES When invoked with no control arguments, the command prints the name, plural name, modes, attributes, info seg pathname, switch names and default values. 3-245 AG92-()6 Name: describe_psp SYNTAX AS A COMMAND describe_psp Marketing_Identifier Key SYNTAX AS AN ACTIVE FUNCTION [describe_psp Marketing_Identifier Key] FUNCTION returns various information about priced separate products (PSP) available to Multics sites. ARGUMENTS Marketin&-Identifier is the Honeywell order number of PSPs (e.g., SGL6803 for COBOL). It can be entered in uppercase or lowercase. LIST OF KEYS sti returns the current software technical identifier for the product released at the instalied release. source returns the absolute path of the product's source archive. object returns the absolute path of the product's object archive. executable returns the absolute path of the product's executable segment. title returns the official name by which the product is known. name returns a short descriptive name by which the product is known. 3-246 AG92-()6 Name: detach_audit, dta SYNTAX AS A COMMAND dta {switchname} FUNCTION removes audit_ from the specified switch (see attach_audit and the audit_ I/O module). ARGUMENTS switchname is the switch from which audit_ is to be removed. If switchname is not specified. user_i/o is assumed. Name: detach_Iv, dlv SYNTAX AS A COMMAND dlv volume_names FUNCTION detaches one or more logical volumes that have been attached for your process by the resource control package (RCP). ARGUMENTS volume_names specifies the volumes to be detached. NOTES You can detach all logical volumes by specifying "all". rather than any volume names. The detaching involves telling the storage system that the logical volume is no longer attached for this process; it does not affect the attached/detached state of the logical volume for any other process. 3-247 AG92-06 dial_manager_call SYNTAX AS A COMMAND dial_manager_call request {STRl {STR2} {STR3}} FUNCTION provides a command interface to the answering service's dial facility. All functions that are available through the dial_manager_ subroutine interface are available through this command. ARGUMENTS request maps into a call to an identically named entry in dial_manager_. Each request requires the use of a particular STR, which is listed in the request description. A request must be one of the following: allow_dials STR, ad STR requests that the answering service establish a dial line to allow terminals to dial to the calling process. STR must be a dial_qualifier as described below. dial_out STRl STR2 {STR3}, do STRl STR2 {STR3} requests that an auto call channel be dialed to a given telephone number and, if the channel is successfully dialed, that the channel be assigned to the requesting process. STRl must be a channel_name and STR2 must be a dial_out_destination as described below. SIR3, which can be omitted, is a reservation_string as described below. privileged_attach STR, pa STR allows a privileged process to attach any terminal that is in the channel master file, and is not already in use. (See the description of dial_manager_$privileged_attach for information on what access is required.) The effect is as if that terminal had dialed to the requesting process. SIR must be a channel_name as described below. registered_server STR, rs STR requests that the answering service allow terminals to dial the calling process using only the dial qualifier. STR must be a dial_qualifier as described below. release_channel STR, rc STR requests the answering service to release the channel specified by channel_name. This channel must be dialed to the caller at the time of the request. If the channel was dialed, the channel is returned to the answering service and another access request may be issued. If the channel is a slave channel, the channel is hung up. STR must be a channel_name as described below. 3-248 AG92-o6 release_channel_no_hangup STR, rcnh STR is the same as release_channel except that this request does not hang up slave channels. STR must be a channel_name as described below. release_dial_id STR, rdi STR informs the answering service that your process wishes to prevent further dial connections, but that existing connections should be kept You can release later any connections kept with the release_channel request STR must be a dial_qualifier as described below. shutoff_dials STR, sd STR informs the answering service that your process wishes to prevent further dial connections and that existing connections should be terminated. STR must be a dial_qualifier as described below. start_report, start turns on the reporting feature (see "Notes" below). stop_report, stop turns off the reporting feature (see "Notes" below). terminate_dial_out STR, tdo STR requests that the answering service hang up an auto call line and unassign it from the requesting process. STR must be a channel_name as described below. STR depends on the request STR is selected from the following list (For details on the interpretation of the following qualifiers see the dial_manager_ subroutine.) channel_name is the name of a tty_channel. dial_qualif ier is the name for which you are to be a dial server. dial_out_destination is the destination (e.g., phone number) of up to 32 characters. reservation_string is a dial_manager_ reservation string of up to 256 characters. 3-249 AG92-06 NOTES This command establishes an event call channel for communication with the answering service. This event channel and its handler (which is an entry point in dial_manager_call) remain active after the command terminates. Any events following the command termination, such as channel hang-ups, dial-ups, and dial requests are decoded using convert_dial_message_ and reported on the user_output I/O switch when they happen. You can turn this reporting feature on (the default) and off by using the start_report and stop_report requests. When the destination specifies an X.25 address you can optionally precede it with "*" or "x29," to indicate that an X.29 (PAD) call should be made. For example, a destination of . x29,3106:mitmul or ,'c 3106: mi tmu 1 specifies an X.29-type call on TYMNET. SYNTAX AS A COMMAND dial_out channel {destination} {-contrcl_args} connect channel {destination} {-control_args} FUNCTION permits you to access a remote system through a dial-out channel. ARGUMENTS channel is the name of the dial-out or slave channel to be used. The star convention is allowed, which means the answering service selects a channel that has a matching name or generic destination and matching attributes (if specified). destination is the dial-out destination. This string is used when making the connection. If omitted. the channel is priv_attached rather than dialed. 11/86 3-250 AG92-o6A CO/ViROL ARGUlViENiS -8 hit does not suppress the parity bit of characters from the foreign system. -abbrev enables abbreviation processing of request lines. -brief. -bf disables printing of informational messages. -echo locally echoes characters typed by you. 11/86 3-250.1 AG92-06A -escape CHAR. -esc CHAR makes CHAR the escape character. (Default:. !) -modes MODES allows you to select the initial values of dial_out's modes (see "List of Modes" below). -no_start_up, -ns disables execution of your start_up. dial_out. command. This is assumed for the connect -profile PATH establishes PATH as the abbrev profile to be used for request lines. your current profile). (Default: -request REQUEST, -rq REQUEST executes the given request before entering its interaction loop. The rightmost -request is the one that is executed. (See "List of Requests" below.) -resource RSC_DESC. -rsc RSC_DESC allows you to specify a resource description to be used when attaching the dial_out channel. -terminal_type TYPE. -ttp TYPE sets the terminal type of the remote connection to TYPE. You can use this for hosts with unusual communications requirements. LiST OF REQUESTS escape CHAR, esc CHAR sets the escape character. file_output PATH, fo PATH starts copying output to a file. interrupt, int, break, brk, ip sends an interrupt signal (line break) to the foreign system. modes STR allows you to control operational modes. revert_output, TO finishes a previous file_output. send STR sends its arguments to the foreign system as if they were typed by you. 3-251 AG92-()6 send_file PATH {-control_arg} sends the contents of pathname PATH to the foreign system. Any characters sent from the foreign system during this time are discarded; thus foreign echo of the file being sent is rejected. (If the foreign echo is slow, you may still see some echo after this request has finished.) Control arguments are: -display_input, -dsin displays characters sent from the foreign system during the transfer. -no_display_input, -ndsin does not display characters sent from the foreign system during the transfer. switch_name returns the name of the I/O switch used by dial_out wait {STR} {-control_args}, [wait {STR} {-control_args}] waits for a specified string to come from the foreign system. With no arguments, this request waits until any characters are sent from the foreign system. Invoked with a string and/or -nl, it waits until the specified string is sent Control arguments are: -nl waits until the specified string is sent with a trailing new line. -nnl waits until the specified string is sent but without a trailing new line. -no_timeout, -ntm specifies that there is no limit to how much time can elapse between character transmissions from the foreign system before dial_out assumes that the foreign system has finished transmi tting. (Def aul t) -timeout N, -tm N specifies the maximum number of seconds that can elapse between character transmissions from the foreign system before dial_out assumes that the foreign system has finished transmitting. As an active request (and if a timeout did not occur), all the text sent from the foreign system since the last text processed by dial_out, including the string specified. is returned as a quoted string. LIST OF MODES echo, "echo enables/disables local echoing of characters typed by you. 3-252 AG92-06 echo_If. Aecho_lf enables/disables echoing of LF after you type a CR. line, " line enables/disables line-at-a-time mode as opposed to character-at-a-time mode for your terminal. quit. Aquit enables/disables transparent quit mode. In this mode the BREAK key performs an "interrupt" request, rather than the normal Multics function. raw, "raw enables/disables direct transmission to the foreign system of characters typed. (Default: raw) send_If, "send_If enables/disables transmISSIon of a LF character as part of the new-line sequence. If you don't set this mode, the new-line sequence consists of CR only; if you set it, it is CR-LF. The new-line sequence is sent when you type the CR key or an NL is encountered in a file. LIST OF SUBSYSTEM REQUESTS prints a line of requests available in dial_out. executes ~1ultics command lines. ? prints a list of requests available in dial_out. abbrev, ab controls abbreviation processing of requests lines. answer provides preset answers to questions asked by another request. do executes/returns a request line with argument substitution. e executes a M ultics command line. execute~ exec_com. ec executes a file of dial_out requests that can return a value. help prints information about dial_out requests and other topics. 3-253 AG92-06 if conditionally executes/returns one of two request lines. list_help, lh displays the name of all dial_out info segments on given topics. quit, q exits dial_out ready, rdy prints a Multics ready message. subsystem_name prints the name of this subsystem. subsystem_version prints the version number of this subsystem. ACCESS REQUIRED You must have the dialok attribute and rw access to the access control segment for the channel (type "user attributes" to determine what attributes you have). NOTES The dial_out command executes your start_up. dial_out exec_com on invocation, whereas the connect command executes an exec_com speciiic to the given destination (or channel if you give no destination). The .dial_out ec suffix for dial_out and connect exec_corns is assumed if you don't supply it The dial_out and connect commands acquire an appropriate communications' channel to a foreign system, execute your dial_out start_up and initial request. and then enter an environment in which characters typed on your terminal are sent to the foreign system and in which characters sent from the foreign system become output at your terminal. When the destination specifies an X.25 address, you can optionally precede it with ,,*n or "x29n • to indicate that an X.29 (PAD) call should be made. For example. a destination of x29,3106:mitmul or 1c 3 106 : mi tmu 1 specifies an X.29-type call on TYMNET. After the dial_out environment is entered. you can enter dial_out requests by preceeding them with the escape character (n" by default). Characters from the escape character to the next escape character or the end of the line are interpreted as a request You must double the escape character to send it to the remote system. 11/86 3-254 AG92-06A directories EXAMPLES dial_out b.h218 9-482-5622 -echo Ready on tty_ b.h218 -destination 9-482-5622 ••• dial_out tymnet x29,3106:p25 Name: directories, dirs SYNTAX AS A COMMAND dirs star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [dirs star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of directories that match one or more star names. ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname. -absp returns absolute pathnames rather than entrynames. (Default to return entrynames) -chase processes the targets of links when you specify a starname. -inhibit_error. -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) 11/86 3-255 AG92-06A directory directories NOTES Only one name per directory is returned; i.e., if a directory has more than one name that matches star_name, only the first match found is returned. Since each entryname (or pathname) returned by directories is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: directory, dir SYNTAX AS A COMMAND d i r path SYNTAX AS AN ACTIVE FUNCTION [dir path] FUNCTION returns the directory portion of path after it has been expanded into an absolute pathname. ARGUMENTS path is the pathname whose directory portion is to be returned. NOTES Since the pathname is returned in quotes, the command processor treats it as a single argument regardless of special characters in the name. EXAMPLES In the working directory >udd>Proj >Myname: dir start_up.ec >udd>Proj>Myname dir >udd>Multics>Library>Source>bound_command_demos_.s::program.pl1 >udd>Multics>Library>Source 11/86 3-256 AG92-06A discard_output discard_output Name: discard_output, dco SYNTAX AS A COMMAND dco {-control_arg} command line FUNCTION executes a command line while temporarily suppressing output on specified I/O switches. ARGUMENTS command_line is a command line. You need not quote it. CONTROL ARGUMENTS -output_switch STR. -osw STR where STR is the name of an I/O switch. If you give no -osw, output on the user_output I/O switch is suppressed. You can specify -osw more than once. NOTES If the command specified in command_line cannot be executed, an error message is printed. 11/86 3-256.1 AG92-06A disconnect Name: disconnect disconnect SYNTAX AS A COMMAND disconnect FUNCTION disconnects the terminal from the current process, suspending that process if the user's disconnect_ok process attribute is on. If the trusted path login installation parm is off the terminal will remain dialed to the system. If the disconnect_ok process attribute is on and the trusted path login installation parm is on then a message will be displayed stating the line must be hung up followed by a hangup. If the disconnect_ok process attribute is off then an message will be displayed stating the process cannot be suspended and no further action will take place. NOTES If disconnect is called from an absentee or daemon process an error message will be returned without further action. When the process is suspended after disconnection. it will remain that way for a period of time equal to or less than the site-specified inactivity time. Contact your project administrator for process attribute information. 11/87 3-256.2 AG92-06B SYNTAX AS A COMMAND daf {path} {-control_args} FUNCTION displays the file produced by the audit_ I/O module. ARGUMENTS path is the path name of the audit file to be displayed. If path is not indicated. the audit file associated with the user_i/o switch is assumed. If user_i/o is not being audited. the audit file currently in use is displayed. CONTROL ARGUMENTS -append_nl. -anI appends new lines to the end of entries that do not end in a new line. It overrides -no_append_nl to the left in the command line. By default. new lines are appended if a "leader generating" control argument (i.e., -class_identifiers. -entry_numbers. or -metering) is present. -class SIRl t .. SIRn} prints the entries having a class identifier matching any of the STRs. identifiers are as follows: Class EL. el (edit line) IL. il (input line) IC. ic (input characters) DC. oc (output characters) IM, tm (trace of modes operations) IC. tc (trace of control operations) If SIR contains only one character. it is matched on the first character of the class identifiers; for example. if SIR is I, entries having either IL or Ie class identifiers are displayed. If -class is not given. the audit file is displayed without class identifiers. -class_identifiers. -cli displays the audit file with the class identifiers before each entry. If -metering is also specified, the metering information precedes class identifiers. -entry_numbers. -etn prints the entry numbers before each entry. 3-257 AG92-()6 . -exclude STRl {. .. STRn}, -ex STRl {. .. STRo} excludes any entries containing strings matching any of the STRs. If -exclude is not chosen, all selected entries are printed. -from STR, -fm STR specifies the first audit file entry to be displayed. If STR is a positive integer, it is interpreted as an entry number. If STR is a positive number containing a decimal point, it is interpreted as a time in 24-hour format If it is neither, the audit file is displayed from the first entry that matches STR. If -from is not supplied, the audit file is displayed from the beginning. -insert_nl, -inl inserts new lines whenever an entry is over length (as determined by -line_length or the current line length for the switch). (Default) -last STR displays entries beginning at the point specified by STR, starting at the end of the audit file. If STR is in entry number format, the first entry displayed is STR entries back from the end of the file. If STR is in time format, the first entry is STR hours and minutes from the end of the file. If STR is a character string, the first entry contains a match for STR searching from the end of the file. If -last is not selected, the audit file is displayed from the beginning. -line_length N, -11 N inserts a new line after the character specified by N if a line· of output is greater than N characters long. A continuation line is indented to allow for any entry descriptors produced by -metering, -entry _numbers, or -class_identifiers and is preceded by an "*" to indicate it is a continuation of the previous line. -match STRl I. .. STRn} prints entries containing strings matching any of the STRs. If it is not specified, all selected en tries are printed. -metering, -mt displays the audit file with metering information at the beginning of each line, preceding the class identifiers if -class or -class_identifiers is also used. -next STR displays a given number of entries from an explicit point in the file to the point specified by STR. If STR is in entry number format, the next STR entries are displayed. If STR is in time format, the entries within the next STR period of time after the beginning entry are displayed. If STR is a character string, the entries up to the next match of STR are displayed. If -next is not selected, all entries to the end of the file are displayed. -no_append_nl, -nanl does not append new lines to entries that do not end in a new line. This control argument overrides the appending of new lines because of "leader generating" control arguments or an occurrence (to the left in the command line) of -append_nl. 3-258 AG92-D6 -no_insert_nl, -ninl does not insert new lines. -output_file path, -of path displays the audit file into the segment named path. -reverse prints the entries in reverse chronological order. -string STR. -str STR uses STR as a character string with no special interpretation. This is useful for preventing STR from being interpreted as a control argument, a time, or an entry number. It can be given with -from, -to, -next. -last. -match, and -exclude. for example, "-from -string 81" (see "Notes"). -switch STR displays the audit file associated with the I/O switch specified by STR if the I/O switch is currently attached. If the I/O switch is not attached. an error message is printed. If -switch is not chosen, the audit file associated with the user_i/o switch is displayed. -to STR stops the display of the audit file at the point specified by STR. where STR can have any of the values for -from. If -to is not specified, the audit file is displayed up to the end. NOTES You specify the format of the output. which entries are selected to be output. and the file to which the output is directed (see attach_audit and the audit_ I/O module). The audit_meter mode must be on for there to be any metering information in the audit file; without this information. time arguments are invalid. The -string control argument is useful in the following situatiOJ.1S. To pass 1005.2 as a character string to be matched. rather than a time value for -from. type: daf -from -string 1005.2 To pass -last as a character string to -match. type: oaf -match 3-259 AG92-D6 SYNTAX AS A COMMAND der {-eontrol_args} FUNCTION displays the current state of a COBOL run unit. CONTROL ARGUMENTS -all. -a prints information about all programs in the run unit. including those that have been cancelled. -files displays information about the current state of the files that have been referenced during the execution of the current run unit. -long, -lg displays more detailed information about each COBOL program in the run unit NOTES The minimal information displayed tells which programs compose the run unit. Optionally. more detailed information can be displayed concerning active illes. data location. and other aspects of the run unit. Refer to the run_cobol command for information concerning the run unit and the COBOL runtime environment Name: display _component_name, dcn SYNTAX AS A COMMAND den path offsets FUNCTION converts an offset within a bound segment (e.g.. bound_zilch_123017) into an offset within the referenced component object (e.g.. comp 11527). This command is especially useful when it is necessary to convert an offset within a bound segment (as displayed by a stack trace) into an offset corresponding to a compilation listing. 3-260 AG92-06 display_component_name ARGU/III E!tITS path is the pathname of a bound object segment or an octal segment number. You can specify a pathname that looks like an octal segment number by -name nnn. offsets are octal offsets within the text of the bound object segment specified by path. EXAMPLES The command line dcn bound_zi1ch_ 17523 64251 might respond with the following lines: 17523 64251 component511057 component7 63 If bound_zilch_ were known with segment number 532, the following command would generate the same output: dcn 532 17523 64251 Name: display_entry_point_del, depd SYNTAX AS A COMMAND depd virtual_entry SYNTAX AS AN ACTIVE FUNCTION [depd virtual_entry] FUNCTION prints a PL/I declare statement describing a procedure entry point or other, system-wide external data constant The command obtains the entry point declaration from data files that contain the declarations of all unusual procedure entry points (ALM segments, procedures written as subroutines but called as functions, etc.) and system-wide external data values (e.g.. sys_info$max_se&-size, iox_$user_output, etc.) or from argument descriptors for the entry point parameters that are included with the procedure entry point itself. 3-261 AG92-06 The active function returns the declaration as a quoted string. ARGUMENTS virtual_entry a character string representation of the procedure entry point or external data value whose declaration is to be printed (see Section 1 for a description of virtual entries). You can use the archive component pathname convention. NOTES Most command and active function entry points do not declare arguments in their procedure statements since they accept a variable number of arguments. They also do not use the options(variable) attribute in their procedure statements. Therefore. when the depd command encounters a procedure entry point with no declared arguments and without options(variable). it ass~es the options(variable) attribute required for commands and active functions and prints a declare statement of the form: del help entry options(variable); depd distinguishes between such assumed options(variable) entries and those that explicitly use the options(variable) attribute in their procedure statement by printing "entry" for the assumed case and "entry()" for the explicit case. Thus, it prints a declaration for depd. which explicitly uses options(variable). as del depd entry() option5(variable); For procedures that use structures as arguments, certain structure declarations are inexactly returned as parameter declarations because the mechanism for encoding argument descriptors does not provide an adequate description of the alignment of a structure. . The descriptor only determines whether the overall structure is packed or not and does not specify whether or not it was originally declared with the aligned attribute. The following structures generate the same argument descriptors, even though PL/I treats the level 1 structures as having different attributes: dell 52 structure al igned, 2 ell fixed bin aligned, 2 e12 fixed bin aligned; del 1 s2 structure, 2 ell fixed bin aligned, 2 e12 fixed bin aligned; depd reproduces the declaration for s2 when either s1 or s2 are used as parameters for an entry point To bypass this problem. declare the subroutine properly in your personal .dcl segment (see "User-provided Data Files" below) and place this segment in your "declare" search paths. 11/86 3-262 AG92-06A display _mailin~address NOTES ON SEARCH LIST The depd command uses the "declare" search list. which has the synonym "dcl", to find data files describing unusual procedure entry points. The default search list identifies the data file: >sss>pll.dcl For more information about search lists, see the descriptions of the search facility commands and, in particular, the add_search_paths command. USER-PROVIDED DATA FILES You can provide data files that redeclare standard system entry points (e.g.. redeclaring a subroutine as a function) or that declare their own entry points or external data items. Data items have the general form of virtual_entry declaration For example: ioa_ entry options(variable) Note that the word "dcl" is not included in the data item. nor does the declaration end with a semicolon (;). External data values are declared in a similar fashion. For example: iox_$user_output ptr external static Name: display_mailin~address, dsmla SYNTAX AS A COMMAND dsmla {names} FUNCTION dispiays the specluea maii taDle entries with default mailing addressees). which appear in the format used in message headers displayed by read_mail. In addition. if the mail table entry specifies an ACS segment to allow other maintainers to update it, this pathname is displayed. 3-263 AG92-06 dispiay_pIlio_error display_mailinLaddress ARGUMENTS names are the Person_ids or aliases of the user whose mailing address should be displayed, or the names or aliases of a mail table entry for a forum or mailing list The command displays the mailing address for each one (printing a warning message for invalid ones). If you give none, the default is your Person_id. Name: display_pllio_error, dpe SYNTAX AS A COMMAND dpe FUNCTION describes the most recent file on which a PL/I I/O error was raised and displays diagnostic information associated with that type of error. This command is designed to be invoked after the occurrence of an I/O error signal during a PL/I I/O operation. EXAMPLES The command line dpe might respond with the following display: Error on file afile Title: vfile_ afile Attributes: open input keyed record sequential Last i/o operation attempted: write from Attempted "write" operation conflicts with fi le "input" attribute. Attempted "from" operation conflicts with file "input" attribute. 3-264 AG92-o6 display_pnotice display_pnotice Name: display_pnotice SYNTAX AS A COMMAND disp1ay_pnotice name {contr01_arg} FUNCTION displays information on software protection notices contained in source programs. ARGUMENTS name is the full or relative pathname of the source language module. The language suffix or the archive suffix must be included if an entire archive is to be processed. The archive pathname convention is supported, but the star convention is not CONTROL ARGUMENTS -brief, -bf specifies that the primary name of notices. without the "pnotice" suffix. be printed instead of the text of notices found. (Default) -long, -lg displays the full text of notices found. A ,"'T'-i'" IYVI CO:> By default. the primary names of protection notices are printed instead of the entire notice text If path includes the full archive name, then archives of source code programs can be audited for protection notices. If a source module does not contain any notices. or contains conflicting notices (copyright and trade secret). an error message is displayed. A warning message is also displayed if there is an embedded notice found in a source program (protection notices should be the first comment encountered). EXAMPLES display pnotice add pnotice.p11 add_pnotice.p11: HIS.1982 display_pnotice add_pnotice.p11 -1g Notices in add_pnotice.p11: Copyr i ght, (C) Honeywe 11 I nformat ion Sys terns Inc., 1982 display_pnotice farf.pI1 Warning: farf.p11 has no protection notice. 3-265 AG92-06 display _subsystem_usage Name: display_subsystem_usage SYNTAX AS A COMMAND display_subsystem_usage sUbsystem_name {-control_args} FUNCTION displays usage information recorded by a subsystem. ARGUMENTS subsystem_name is normally the name of the subsystem whose usage information is (see "Notes on Subsystem Usage Segments" below). to be displayed CONTROL ARGUMENTS -first N prints only the first N entries; when combined with -reverse, prints only the last N entries. The entries are sorted, if requested, before application of -first. It is incompatible with -totals. -header. -he prints a header defining each column of output. (Default) -no_header. -nhe suppresses printing of the header. -no_reverse, -nr\' prints the entries in the selected order. (Default) -reverse, -rv prints the entries in reverse order from that selected. -sort TYPE sorts the individual entries before displaying them. It is incompatible with -totals. (See "List of Sorting Types" below.) -totals, -tt prints only the total number of invocations of the subsystem without listing any individual entries. It is incompatible with -first and -sort. -user NAME prints only those entries for users whose Person_id matches NAME. convention is allowed. The star -version VERSION prints only those entries for users who last used the version of the subsystem named by VERSION. 3-266 AG92-o6 display_subsystem_usage LIST OF SORTING TYPES The TYPE given to -sort must be one of the following: count sorts by the total number of invocations of the subsystem by the user. date_time_used, dtu sorts by the date-time of the last invocation of the subsystem by the user. name sorts by the Person_id of the user whose usage is recorded in this entry. version sorts by the version number of the subsystem's last version used by the user. NOTES The information displayed by this command for a user of the subsystem includes 1. the user's Person_id. 2. the total number of times the user has used this subsystem. 3. the version number of the last version of the subsystem used by the user. 4. the number of times the user has used this version of the subsystem. 5. the date-time the user last used the subsystem. NOTES ON SUBSYSTEM USAGE SEGMENTS Subsystem usage information is recorded in the segment named "subsystem_name.ssusage" (e.g., read_mail. ssusage) , and you can locate that segment by using the linker search rules. If you can't locate it. you can give the pathname of the subsystem usage segment, with or without the ssusage suffix. as an argument to this command in addition to the subsystem name. 3-267 AG92-06 Name: display_time_info, dsti SYNTAX AS A COMMAND dsti -control_args FUNCTION displays information selected from time_info_. CONTROL ARGUMENTS -all, -a specifies an data are to be printed. -day asks for a list of all the day names. -format, -fmt asks for a list of all keywords that can be given in a time_format control string. This list does not include "date". "date_time", and "time" as they are not contained in time_info_. Use print_time_defaults to see them. -language, -lang asks for a list of all the time languages available, showing the name of each language in each language, You would usually use this form alone to enable you to see what languages you can refer to. -language STR, -lang STR asks for the output to be given in language SIR. (Default: to show requested data in the process default language) -map asks for a time zone map of the world. with all the defined time zones and their offsets. Each zone is at its proper place on this map. The map is horizontally broken according to the line length currently in effect -month asks for a list of all the month names. -offset asks for all the offset words to be printed. -table STR. -tb STR STR specifies the pathname of the table to be displayed. (Default the reference name "time_info_") 3-268 AG92-06 -token {STR} displays the structure used for binary, searching the tokens declared in the table. The (iisplay shows all words, with their meanings, in all languages, grouped by token. A token is a word converted to lowercase. If you give STR, only the data for that token is shown. Since STR represents a token and not a word, enter it in lowercase. -word asks for all the miscellaneous words to be printed. -zone asks for a list of all the zones available. Name: display_ttt SYNTAX AS A COMMAND display_ttt {-control_args} FUNCTION prints all or part of a terminal type table (TIT) on your terminal, or outputs it to a file. The output's format is such that you can use it as a terminal type file (TIP). CONTROL ARGUMENTS -header, -he prints a header (see "Notes"). -no_header, -nhe suppresses printing of the header. -output_file PATH, -of PATH directs output to the file whose pathname is PATH. If you omit the ttf suffix from PATH, it is added. If you omit PATH, output is directed to your terminal. -pathname PATH, -pn PATH displays the TIT whose pathname is PATH. If you omit the ttf suffix from PATH. it is assumed. If you omit PATH, the process's current TIT is displayed. -table NAME. -tb NAME displays only the conversion, translation, function keys, or special table named NAME (see "Notes"). -terminal_type NAME. -ttp NAME displays only the terminal type entry for the terminal type named NAME (see "Notes"). 11/86 3-269 AG92-()6A dm_display_version display_ttt NOTES If you give neither -ttp nor -tb, the entire contents of the TIT are displayed. If you give either -ttp or -tp, only the specified terminal type entry or table is displayed without the introductory comment, unless you also give -he. If you give no -nhe, an introductory comment is printed, giving the pathname of the TIT, the date and the 9 9 User_id of the author of the original TIT. Name: divide SYNTAX AS A COMMAND divide numA numB SYNTAX AS AN ACTIVE FUNCTION [divide numA numB] FUNCTION returns the integer part of the decimal quotient of numA divided by numB (see the mod and quotient commands). EXAMPLES string [divide 5 4] 1 Name: elm_display_version SYNTAX AS A COMMAND FUNCTION displays the version of the data management (DM) system software currently in use by the executing process. 3-270 AG92-06 do SYNTAX AS A COMMAND FUNCTION removes the process invoking it from the current invocation of the data management system (DMS). NOTES All user process references to per-process and per-system data are invalidated to permit subsequent reentry to DMS. Ii a transaction is in progress in the process when you issue the command, the DM Daemon (Data_Management. Daemon) rolls it back automatically. Normally all processes using data management are shut down as part of a data management system shutdown, with no explicit user intervention. This command is part of the com.rnand level interface to Multics data. management Use it in a test environment or in debugging. Name: do SYNTAX AS A COMMAND do {-control_args} {control_string {args}} * SYNTAX AS AN ACTIVE FUNCTION [do control_string {args}] FUNCTION substitutes arguments into a control string. The expanded control string is then passed to the command processor or the subsystem request processor for execution. As an active function or active request, returns the expanded control string without executing it 11/86 3-271 AG92-{)6A do do ARGUMENTS control_string is a character string that can contain substitution constructs (see "List of Substitutions" below). args are zero or more character string arguments. Any argument supplied but not referenced by an argument substitution designator is ignored. CONTROL ARGUMENTS If you give control arguments with no control string. subsequent do invocations in the process are affected; with a control string and its arguments. subsequent do invocations are not affected. Give the control arguments first (See "Notes on modes" below.) -abort_line. -abl aborts the line containing the do request if the request line is aborted during execution. Applies only to subsystem request invocations of do. (Default) -brief. -bf does not print the expanded control string. (Default) -control_string. -cs permits a control string to look like a control argument. -go passes the expanded control string to the command processor or subsystem request processor. (Defaul t) -inhibit_error. -ihe, -absentee establishes a handler for the any_other condition during the execution of the expanded command control string. -long. -lg prints the expanded control string on error_output before executing or returning it -no_abort_line, -nabl continues execution with the next request following the do request on the invoking line if the request line do invoked is aborted during execution. Applies only to subsystem request invocations of do. -no_inhibit_error, -nihe. -interactive does not catch any signals. (Default) -nogo does not pass the expanded control string to the request processor. 11/86 3-272 AG92-o6A do do LIST OF SUBSTITUTIONS The following expansion designators appearing in the control string are replaced by their expansion value. as deScribed below. Any other use of the ampersand (&) produces an error. &0, &1, ... &9 expands to the zeroth through ninth arguments. &0 is the control string, &1 is the first argument following the control string, and so on. If the corresponding argument is missing, the designator expands to a null string. &(0), &(1) •... expands to any argument, including arguments after the ninth. Use parenthesis when the argument number is two or more digits. If the corresponding argument is missing, the designator expands to a null string. &qO, ... &q9, &q(O), &q(1), ... expands to the corresponding argument following the control string. Quotes within the argument are doubled, according to the quote depth of the surrounding context within the control string (see "Notes on Quote Doubling" below). &rO, ... &r9, &r(O). &r(1) •... expands to the corresponding argument following the control string. enclosed in an added layer of quotes with internal quotes with the argument doubled accordingly (see "Notes on Requoting" below). This designator keeps the argument as a single unit after one layer of quote stripping by the command processor. &f1 •... &f9, &f(l) •... expands to the Nth through last arguments following the control string, with arguments separated by one space. If N is greater than &n, expands to a null string. &qfl, ... &qf9. &qf(1) •... expands to the Nth through last arguments following the control string, with quotes doubled within arguJ.~ents. ~md arg'..h~ents separated by one space. If N is greater than &n, expands to a null string. &rf1, ... &rf9, &rf(1), ... expands to the Nth through last arguments following the control string, with each argument individually requoted, and arguments separated by one space. If N is greater than &n, expands to a null string. &n expands to the number of arguments you give following the control string. &f &n. &qf &n, &rf &n expands to the last argument following the control string, with quotes doubled (&qf&n) or with requoting (&rf&n). 11/86 3-273 AG92-()6A do do &control_string expands to the control string (without expansions), with quotes doubled. equivalent to &qO. It is &! expands to a unique name. Each use of &! is replaced by a IS-character identifier. Every use within a single invocation is replaced by the same string, but the string is different for every invocation of do. && expands to a single ampersand, to allow ampersands to be literally inserted into the expanded control string. NOTES When the control string is executed, abbreviations are expanded if the abbrev processor is enabled. Since the control string is usually enclosed in quotes, abbreviations in the control string are not expanded until control string expansion. (See the abbrev command.) NOTES ON MODES This command has four modes: the long/brief mode, the nogo/go mode, the abort-line mode, and the inhibit-error mode. These modes are kept in internal static storage and are thus remembered from one invocation of do to the next in a single process. Set the modes for the life of the process by invoking do with control arguments and no control string; set the modes for a single invocation by giving control arguments, a control string, and its arguments. The abort-line mode applies only to subsystem request invocations of do. You can set the mode at command level, but cannot set it for a single command invocation of do. Use the inhibit-error mode mainly in an absentee environment, in which any condition that normally enters a new command level terminates the process. In this mode, any signal caught by do terminates execution of the command line, not the process. The following conditions are not handled by do, however, but are passed on to the command processor: command_error, command_query_error, command_question. program_interrupt, quit, and record_quota_overflow (see the Programmer's Reference ManuaI). The abort-line, inhibit-error, and go/nogo modes have no effect on active function and active request invocations of do. 11/86 3-274 AG92-06A do ~o NOTES ON QUOTE DOUBLING Each parameter designator to be expanded is found nested a certain level deep in quotes. If it is found to be outside quotes. its quote level is zero; if found between a single pair of quotes, its quote level is one; and so on. If an "&q" construct is found nested to quote-level L. then. as the argument is substituted into the expanded control string. each quote character found in the argument is replaced by 2**L quote characters during insertion. This permits the quote character to survive the quote-stripping action to which the command processor subsequently subjects the expanded control string. If the "&q" construct is not between quotes, or if the corresponding argument contains no quotes, quote doubling has no effect NOTES ON REQUOTING If an "&r" construct is found, the substituted argument is placed between an additional level of quotes before having its quotes doubled. For example. if &rl is found nested to quote level L. 2**L quotes are inserted into the expanded control string; then. the first argument is substituted, with each of its quotes replaced by 2**(L+1) quotes; and. finally. 2**L more quotes are placed following it If you give no argument, nothing is placed in the expanded control string; so, you can distinguish between arguments that are not supplied and arguments that are supplied but are nUll. If you give an argument, the expansion of an "&r" construct is identical to the expansion of an "&q" construct surrounded by an extra level of quotes. EXAMPLES Consider the following abbreviations: ADDPLI AUTHOR CREATE LIST LISTAB LISTAC do lifo &1.1ist;ioa_ AI;p1i &l;ro" do lIioa $nn1 &l;status -author &1" do IIcd &l;sis &1 re 1c.Demo rew Jay.*" do lifo Jay.1ist;LISTAB;ws &1 LISTAC;ro;dp -d1 Jay.list" do II. 1" "la;ls -dtem -all P do P2 do "pl1 &1 -1 ist &f2 11 ··pi i &1 - i iSt &2 &3" The command line ADDPLI alpha expands to fo alpha.1ist:ioa_ AI:pli alpha;ro The command line AUTHOR beta prints beta and the author of segment beta. 11/86 3-275 AG92-06A do do The command line CREATE games expands to cd games;sis games re *.Demo rew Jay.* This shows an easy method of automatically setting initial access on the segments that are cataloged in a newly created directory. The command line LIST >udd>Demo>Jay expands to fo Jay.list;LISTAB;ws >udd>Demo>Jay LISTAC;ro;dp -dl Jay.list which is expanded by abbrev to fo Jay.list;do ".l";ws >udd>Demo>Jay "la;ls -dtem -a";ro; dp -dl Jay.list See how you can use do at several levels and how it allows abbreviations within abbreviations. The command line P alpha generates the expansion pll alpha -list whereas the command line P alpha -table expands to pll alpha -list -table Note how references to arguments not supplied are deleted. 11/86 3-276 AG92-06A do The abbreviation P2 is equivalent to P for three or fewer arguments. The command line P2 alpha -table -sv3 -optimize executes the pU command with the -list, -table, -sv3, and -optimize control arguments, whereas P alpha -table -sv3 -optimize omits the -optimize control argument SYNTAX AS A COMMAND Master process or si ngle-process invocations: do_subtree path -control_args Slave process invocations: do_subtree -slave FUNCTION operates on a given directory, called the starting node, and all directories inferior to it by executing one or two given command lines after substituting the pathname of that directory in the command line. The do command performs the substitution, the directory pathname being taken as the first executed at each node before inferior nodes are operated on (the top-down command line) and after inferior nodes are operated on (the bottom-up command line). This command enables you to execute the argument command lines in several processes. The walking of the hierarchy can be substantially speeded up by use of this facility. The process in which the initial command lines in starting node is given is named the master process; the other cooperating processes are called the slave processes. The cooperating processes communicate via a segment called dos_mp_seg, which is found (or created if not found) in the working directory when do_subtree is issued. The master process must be logged in and begin executing first when multiple processes are used. 11/86 3-276.1 AG92-06A ARGUMENTS path is the starting node; -workinLdir (-wd) specifies the working directory of the master process if multiple processes are being used. CONTROL ARGUMENTS -bottom_up SlR -bu STR specifies the bottom-up command line. If STR contains blanks, it must be enclosed in quotes. The name of the directory of execution is the first argument to the do command. Access this value with the string "&r1" rather than "&1" in case any directory names contain special characters. Give one of -bottom_up or -top_down, but you can use both. -first N, -ft N makes N the first level of the directory hierarchy at which the command lines are executed. By definition, the starting node is at level 1. The default is -first 1. -last, -It N makes N the last level in the storage system hierarchy at which the command lines are executed. The default is 99999, i.e., all levels. -long, -Ig prints Lite names of the directories at which the command lines are executed" Unlike walk_subtree, this printing is off by default In multiprocess executions with a bottom-up command line, an asterisk precedes all directory names for which the process executing the bottom-up command line is not the process that en tered the directory first 11/86 3-276.2 AG92-06A -multiprocess, -mp makes the invoking process the master process of a mUltiprocess execution. The dos_mp_seg segment is created in the current working directory and execution begins. As slave processes are started, work is distributed by the master process among the slave processes. Execution ends in all processes simultaneously. The top-down/bottom-up order of execution is guaranteed by all processes: no command line is executed at a given directory until either the top-down command line is executed in all superior directories or the bottom-up command line is executed in all inferior directories. -no_msf does not treat multisegment files as directories. Unlike walk_subtree, multisegment files are treated as directories by default. Avoid -no_msf for most storage system maintenance operations. -slave executes the command line in another process, which must be directory where an active master process has begun executing invocation of do_subtree. The master process uses all control command lines of the slave process. Execution in all processes same time. Don't use more than 35 slave processes. in a working a multiprocess arguments and finishes at the -top_down STR. -td STR specifies the top-down cOqlmand line. If STR contains blanks. it must be enclosed . in quotes. The name of the directory of execution is the first argument to the do command. Access this value with the string "&r1" rather than "&1" in case any directory names contain special characters. Give one of -bottom_up or -top_down, but you can use both. Entry: do_subtree$recover This entry point is used to pick up the work load of a process that has died in a multiprocess execution. The process picking up the work load of the dead process must have as its working directory the directory in which the dos_mp_seg segment for the current multiprocess execution exists. SYNTAX AS A COMMAND do_subtree$recover processnumber ARGUIIIElVTS processnum ber is the process number of the dead process. The process number of a do_subtree process in a multiprocess execution is typed out as it joins the execution. Entry: do_subtree$abort 3-277 AG92-Q6 dprint This entry point halts a multiprocess execution of do_subtree. All processes return to command level at once. The process executing this command must have as its working directory the directory in which the dos_mp_seg segment of the current multiprocess execution exists. SYNTAX AS A COMMAND do_subtree$abort Entry: do_subtree$status This entry point prints out much debugging and status information about all processes involved in a multiprocess execution of do_subtree. including the process identifiers and command lines. The process executing this command must have as its working directory the directory in which the dos_mp_seg of the current multiprocess execution exists. Name: dprint, dp SYNTAX AS A COMMAND dp {-control_args} {paths} FUNCTION queues specified segments and/or multisegment files for printing on one of the Multics line printers. The output is by default identified by your Person_ide This command does not accept standard object segments. Use enter_output_request; it has functionally replaced dprint. ARGUMENTS paths are pathnames of segments and/or multisegment files. The star convention is not allowed. CONTROL ARGUMENTS -access_label, -albl uses the access class of each pathi specified as a label at the top and bottom of every page (see "Notes" below). -brief. -bf suppresses the message "j requests signalled. k already queued. (request_type queue)." This control argument cannot be overruled later in the command line. (See -request_type and -queue below.) 3-278 AG92-06 dprint dprint -bottom_label STR, -blbl STR uses the specified string as a label at the bottom of every page (see "Notes" below). -copy N, -cp N prints N copies (N <= 4) of specified paths. It can be overruled by a subsequent -copy. If pathi is to be deleted after printing. all N copies are printed first If this control argument is not specified, one copy is made. -defer_un til_process_termination, -dupt does not process the request until the requesting process terminates. Process termination is caused by the logout command, new_proc, or a fatal process error. -delete, -dl deletes (after printing) specified paths. -destination STR. -ds STR labels subsequent output with the string deliver the output STR is limited to contains spaces. If -destination is not This control argument can be overruled STR, which is used to determine where to 24 characters and must be quoted if it specified, the default is your Project_ide by a subsequent -destination. -forms STR indicates the type of forms to be used when processing the print file. Standard I/O daemon drivers ignore the forms specification when processing print requests. -header STR, -he STR identifies subsequent output by the string STR. STR is limited to 64 characters and must be quoted if it contains spaces. If -header is not selected. the default is your Person_ide This control argument can be overruled by a subsequent -header. -indent N, -in N prints specified paths so that the left margin is indented N columns. given, no indentation occurs. If not -label STR, -lbl STR uses the supplied string as a label at the top and bottom of every page (see "Notes" below). -line_length N, -11 N prints spp.A;ified paths so that lines longer than N characters are continued on the following line; i.e., no line of output extends past column N. If not chosen. a line length of 136 characters is used. -no_endpage, -nep prints indicated paths so that the printer skips to the top of a page only when a form-feed character is encountered in the input path. This control argument ignores -page_length (if present). 3-279 AG92-06 dprint dprint -no_label, -nlbl does not place any labels on the printed output -non_edited, -ned prints nonprintable control characters as octal escapes rather than suppressing their printing. -notify, -nt sends a confirming message when the requested output is done, showing the pathname and charge. -page_length N, -pI N prints no more than N lines per page, where N is the logical page length (i.e., the number of lines of user data to appear). (Default: varies depending upon the request type) -queue N, -q N prints supplied paths in pnonty queue N. This control argument can be overruled by a subsequent '-queue; if not specified, the default queue for the request type is assumed. (See "Notes" below.) -request_type STR, -rqt STR places specified paths in the queue for requests of the type identified by STR (see "Notes" below). If not specified, the default is "printer." -single, -sg prints specified paths so that any formfeed or vertical-tab character in any of the paths is printed as a single newline character. -top_label SiR, -tIbI STR uses the specified string as a label at the top of every page (see "Notes" below). -truncate, -tc prints specified paths so that any line exceeding the line length is truncated rather than "folded" onto subsequent lines. ACCESS REQUIRED You requires r access to the segment or multisegment file. The process that performs the printing (as obtained by print_request_types) must have at least r access to the file and at least s access to the containing directory to verify that you also have at least r access to the file. If -delete is specified, the I/O coordinator (normally IO.SysDaemon.z) must have at least m access to the containing directory and at least s access to the parent directory of the containing directory to verify that you also have at least m access to the con taining directory. 3-280 AG92-06 dprint dprint NOTES If you invoke dprint without any arguments. the system prints a message giving the status of the default printer queue. If control arguments are present. they affect only paths specified after their appearance in the command line. If control arguments are specified without a following pathi argument, they are ignored for this invocation of the command and a warning message is printed. The -queue 1 control argument places requests in the top priority queue, -queue 2 in the second priority queue, and -queue 3 in the third. There can be 1 to 4 priority queues for a specified request type as determined by the site. Higher priority queues usually have a higher cost associated with them. The -brief, -delete, -single. -truncate, and -no_endpage control arguments cannot be reset in a specified invocation of the command; e.g., once -delete appears in a line, all subsequently specified paths are deleted after printing. The -request_type control argument is used member of a particular group of printers. and remote printers at various locations. or projects. .Only. request types of gelleric print_request_types command to list them. dprint from a private logical volume. to ensure that a request is performed by a e.g., to distinguish between onsite printers between printers being charged to different type "printer" can be specified; use the It is a system restriction that you cannot If a requested output operation cannot be done. the daemon process sends you a message of the form: Request path reason. The -label, -top_label. -bottom_label, and -access_label control arguments allow you to place labels on each page of printed output. The default labels are access labels; i.e., -access_label is assumed. These control arguments are read, in sequence, from left to right by dprint; for example, if -access_label is specified. it is printed at the top and bottom of the page. If you next give -top_label STR. then the top access label becomes STR, but the bottom label remains the same. Each label control argument can override the preceding one. The label lines are printed on the second and the next-to-Iast lines of the page. If the access class of pathi is system_low and the access class name defined for system_low is nUll, then the default access label is blank. The default access label can be overridden by -no_label, if labels are not wanted. or by any other label control argument The top and bottom labels are treated independently; thus, -top_label leaves an access label as the default bottom label. A page label that exceeds 136 characters is truncated to that length. Only the first line of a page label is printed, i.e., a new line terminates the page label. Formfeeds and vertical tabs are not permitted. The label control arguments are incompatible with -no_end page. and they are ignored regardless of the -no_endpage's position in the command line. 3-281 AG92-06 dpunch dprint Segments and multisegment files cannot be printed unless appropriate system processes have sufficient access. The process (normally IO.SysDaemon) that runs devices of the specified class must have r access to all paths to be printed and s permission on the containing directory. A file cannot be deleted after printing unless its safety switch is off and the system process has at least sm access on the containing directory. A file is not deleted if it has a date-time-contents-modified value later than the date-time-contents-modified value at the time of the dprint request This command does not accept the star convention: if it finds a name contaInIng asterisks. it prints a warning message and continues processing the other arguments. If pathi specifies a standard Multics storage system object segment. dprint prints a warning message and continues processing its other arguments. EXAMPLES The command line dp -he Jones -ds BIN-5 -cp 2 -dl testl test7 -he Doe text.runout dprints and then deletes two copies of the segments named test! and test7 in the current working directory (with the header "Jones" and the destination "BIN-5") and two copies of the segment named textrunout in the current working directory with the header "Doe" and destination "BIN-5". Name: dpunch, dpn SYNTAX AS A COMMAND dpn {-control_args} {paths} FUNCTION queues specified segments and/or multisegment files for punching by the Multics card punch. It is similar to dprint Use enter_output_request; it has functionally replaced dpunch. ARGUMENTS paths are pathnames of segments and/or multisegment files. The star convention is not allowed. 3-282 AG92-06 dpunch dpunch CONTROL ARGUMENTS -7punch, -7p punches the specified paths using 7-punch conversion. either -mcc or -raw. It can be overruled by -brief, -bf suppresses the message "j requests signalled, k already queued. (request_type queue)." This control argument cannot be overruled later in the command line. (See -request_type and -queue below.) -copy N, -cp N punches N copies (N <= 4) of specified paths. It can be overruled by a subsequent -copy. If pathi is to be deleted after punching, all N copies are punched first If this control argument is not specified, one copy is made. -defer_until_process_termination, -dupt does not process the request until the requesting process terminates. Process termination is caused by the logout command, new _proc, or a fatal process error. -delete, -dl deletes (after punching) all specified paths. -destination STR, -ds STR uses the string STR to determine where to deliver the deck. If not specified, the default is your Project_id. This control argument can be overruled by a subsequent -destination. -header STR, -he STR identifies subsequent output by the string STR. If not specified, the default is your Person_id. This control argument can be overruled by a subsequent -header. -mcc punches the specified paths using character conversion. It can be overruled by either -raw or -7punch. (Default) -notify, -nt sends a confirming message when the requested output is done, showing the pathname and charge. -queue N, -q N punches speciiied paths in pnonty queue N (N <= 4). It can be overruled by a subsequent -queue. If not specified. the default queue for the request type is assumed. (See "Notes" below.) -raw punches the specified paths using no conversion. It can be overruled by either -mcc or -7punch. 3-283 AG92-06 dpunch dpunch -request_type STR, -rqt STR places specified paths in the queue for requests of the type identified by the string STR (see "Notes" below). If not specified, the default request type is "punch." ACCESS REQUIRED You require r access to the segment or multisegment file. The process that performs the punching (as obtained by print_request_types) must have at least r access to the file and at least s access to the containing directory to verify that you also have at least r access to the file. If -delete is specified, the I/O coordinator (normally 10.SysDaemon.z) must have at least m access to the containing directory and at least s access to the parent directory of the containing directory to verify that you also have at least m access to the containing directory. NOTES If you invoke dpunch without any arguments, the system prints a message giving the status of the default punch queue. control arguments are present, they affect only paths specified after their appearance on the command line. If control arguments are specified without a following pathi argument, they are ignored for this invocation of the command and a warning message is printed. If The -delete control argument is the only one affecting segments that cannot be reset in a specified invocation of the command. Once -delete appears in a line, all subsequent segments are deleted after punching. The -request_type control argument is used to ensure that a request is performed by a member of a particular group of punches; for example, to distinguish between onsite punches and remote punches at various locations, or between punches being charged to diff erent projects. Specify only request types of generic type "punch." List request types by using print_request_types. If a requested output operation cannot be done, the daemon process sends you a message of the form: "Unable to punch" path reason. A segment or multisegment have sufficient access. The specified class must have r containing directory. A file off and the system process file is not deleted if it date-time-contents-modified file cannot be punched unless appropriate system processes process (normally IO.SysDaemon) that runs devices of the access to all files to be punched and s permission on the cannot be deleted after punching unless its safety switch is has at least sm permission on the containing directory. A has a date-time-contents-modified value later than the value at the time the request is completed. 3-284 AG92-o6 dpunch This command does not accept the star convention: if it finds a name containing asterisks, it prints a warning message and continues processing the other arguments. Before deleting a file that has been punched, read the deck back in and compare it (using the compare command) with the original. to ensure the absence of errors. EXAMPLES The command line dpunch a b -7punch -he RBurns copll -dl -he "FSchubert ll alpha punches segments a and b in the current working directory using mcc conversion, punches segment c.pll using 7-punch conversion with "for RBurns" added to the heading, and punches and deletes segment alpha using 7-punch conversion with "FSchubert" added to the heading. Name: dump_segment, ds SYNTAX AS A COMMAND ds path {offset} {length} {-control_args} ds segno {offset} {length} {-control_args} ds virtual_pointer {offset} {length} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [ds path {offset} {length} {-control args}] [ds segno {off set} {l ength} {-control args}] [ds virtual_pointer {offset} {length}-{-control_args}] FUNCTION prints, in octal or hexadecimal format, selected portions of a segment It prints out either four or eight words per line and optionally prints out an edited version of the ASCII, BCD, EBCDIC (in 8 or 9 bits), or 4-bit byte representation. ARGUMENTS _ .....t.. .fJCI.Ul is the pathname or (octal) segment number of the segment to be dumped. If path is a pathname but looks like a number. make the preceding argument be -name. You can use the star convention for the command only. 11/86 3-285 AG92-06A offset is the (octal) offset of the first word to be dumped. If you omit both offset and length, the entire segment is dumped. If you specify offset, add it to the offset given in the virtual pointer (i.e., 234\40 10 5 implies seg 234150 for five words). If you need no offset but need length, supply offset as zero. * length is the (octal) number of words to be dumped. If you supply offset and omit length, one word is dumped. segno is the octal segment number of the segment to be dumped. hardcore segment number. It cannot be a virtual_pointer is an ASCII representation of a pointer (see Section 1). CONTROL ARGUMENTS -4bit prints out, or returns, a translation of the octal or hexadecimal dump based on the Multics unstructured 4-bit byte. The translation ignores the first bit of each 9-bit byte and uses each of the two groups of four bits remaining to generate a digi t or a sign. -address, -addr prints the address (reiative to the base of the segment) with the data. (Defauit) * -bed prints the BCD representation of the words in addition to the octal or hexadecimal dump. There are no nonprintable BCD characters. so periods can be taken literally. It causes the active function to return BCD. -block N, -bk N dumps words in blocks of N words separated by a blank line. The offset, if being printed, is reset to the initial value at the beginning of each block. -character, -ch, -ascii prints the ASCII representation of the words in addition to the octal or hexadecimal dump. Characters that cannot be printed are represented by periods. It causes the active function to return ASCII. (Default) 11/86 3-286 AG92-06A -ebcdic8 prints the EBCDIC representation of each eight bits hexadecimal dump. It causes the active function Characters that cannot be printed are represented by of words is requested to dump, the last four bits of in the translation. in addition to the octal or to return 8-bit EBCDIC. periods. If an odd number the last word do not appear -ebcdic9 prints the EBCDIC representation of each 9-bit byte in addition to the octal or hexadecimal dump. Characters that cannot be printed are represented by periods. It causes the active function to return 9-bit EBCDIC. 11/86 3-286.1 AG92-o6A This page intentionally left blank. 11/86 AG92-06A -entry_point NAME, -ep NAME specifies that the offset of the first word to be dumped is relative to the location defined by the externally available symbol NAME. Use -entry_point only for object segments (created by a compiler or by the create_data_segment command). -header, -he prints a header line containing the pathname (or segment number) of the segment being dumped as well as the date-time printed. (Default: to print a header only if the entire segment is being dumped, i.e., if you give neither the offset nor the length argument) -hex8 prints the dumped words in hexadecimal with nine hexadecimal digits per word rather than octal with 12 octal digits per word. -hex9 prints the dumped words in hexadecimal with eight hexadecimal digits per word rather than 12 octal digits per word. Each pair of hexadecimal digits corresponds to the low-order eight bits of each 9-bit byte. -interpreted, -it prints the data decoded into the indicated format. -long, -lg prints eight words on a line. You can't use -long with -4bit, -bcd, -character, -ebcdicB. -ebcdic9, or -short. (Default: four) -name PATH, -nm PATH indicates that PATH is a pathname even though it may look like an octal segment number. -no_address, -naddr does not print the address. -no_header, -nhe does not print the header line even though the entire segment is being dumped. -no_interpret, -nit suppresses printing of the decoded data. (DefauD -no_raw, -nraw suppresses printing of the raw data. -no_offset. -nofs does not print the offset (Default) -no_suppress_duplicates. -nsd indicates that sequential lines are to be printed even if they would be identical to previous lines. 3-287 AG92-G6 -octal, -oc display the raw data in octal format, with 12 octal digits per word. (Default, for raw data) * -offset {N}, -ofs {N} prints the offset (relative to N words before the start of the data block being dumped) along with the data. If you supply no N, 0 is assumed. -raw indicates that the raw data is to be printed. (Default) -short, -sh compacts lines to fit on a terminal with a short line length. Single spaces are placed between fields, and only the two low-order digits of the address are printed except when the high-order digits change. This shortens output lines to less than SO characters. -suppress_duplicates, -sd indicates that if lines to be printed are identical to the previous line with a single block, they are to be replaced by a short line of equal signs. (Default) NOTES The defaults for use as a command are -address, -no_interpret, -no_offset, -raw, and -supress_duplicates with -header if the entire segment is printed. and -no_header if only parts of the segment are to be printed. The defaults for use as an active function are -no_address, -no_header, -no_interpret, -no_offset, -no_suppress_duplicates, and -raw. Supply only one of -4bit, -bcd, -character, -ebcdicS, or -ebcdic9. If you invoke -4bit. -bed. -character, -ebcdicS. -ebcdic9, -hex8, or -hex9, the information is returned in the specified format only. All other arguments are ignored in active function invocation. In the active function the following control arguments are invalid: -address. -block, -header, -offset. and -suppress_duplicates. When you give conflicting control arguments. the last one on the command line is used. The active function returns either raw data in octal or hexadecimal representation or the interpreted data representation. 3-288 AG92-06 edm edm Name: edm SYNTAX AS A COMMAND edm {path} FUNCTION invokes a simple Multics context editor. It is used for creating and editing ASCII segments. You can't called it recursively. ARGUMENTS path specifies the pathname of a segment path, edm begins in input mode (see subsequently typed as input. If you exist, edm also begins in input mode; begins in edit mode. to be created or edited. If you give no "Notes" below), ready to accept whatever is supply path but the segment does not yet however if the segment already exists. edm LIST OF EDITOR REQUESTS = b c d E f i k 1 merge move n p q qf r s t updelete upwrite v w backup print current line number comment mode mode change bottom change delete execute find insert kill locate insert segment move lines within segment next print quit quitforce retype substitute top delete to pointer write to pointer (upper portion of segment) verbose write 3-289 AG92-06 emacs edm NOTES This command operates in response to requests from you. To issue a request, make edm be in edit mode. This mode is entered in two ways: if the segment already exists, it is entered automatically when you edm invoke; if dealing with a new segment (and edm has been in input mode), you must issue the mode change character. This character is the period, issued as the only character on a line. The command announces its mode by typing "Edit." or '''Input.'' when the mode is entered. From edit mode, input mode is also entered via the mode change character. The edm requests are predicated on the assumption that the segment consists of a series of lines to which there is a conceptual pointer that indicates the current line. (The "top" and "bottom" lines of the segment are also meaningful.) Various requests explicitly or implicitly move the pointer; others manipulate the line currently pointed to. Most requests are indicated by a single character, generally the first letter of the name of the request. For these requests only the single character (and not the full request name) is accepted by the command. Certain requests have been considered sufficiently dangerous, or likely to confuse you, that you must specify their names in full. If you issue a quit signal while in edit mode and then invoke the program_interrupt command, the effect of the last request executed on the edited copy is nullified; in addition, any requests not yet executed are lost. If you type program_interrupt after a quit in comment or input modes, all input since last leaving edit mode is lost; if you wish to keep the input, invoke the start command following the quit. See the FAST Subsystem User's Guide (AU25) for an introduction to the use of edm. Name: emacs SYNTAX AS A COMMAND emacs {-control_args} {paths} FUNCTION enters the Emacs text editor, which has a large repertoire of requests for editing and formatting text and programs. ARGUMENTS paths are pathnames of segments to be read in. Each is put into its own appropriately named buffer. Star and archive component pathnames are accepted. 3-290 AG92-06 emacs emacs CONTROL ARGUMENTS -apply function_name argl arg2 ... argi, -ap function_name arg1 arg2 ... argi evaluates (function_name 'arg1 'arg2 ... 'argi) , where the args are arguments to the named Lisp function (e.g., an Emacs request). This is valuable for constructing abbreviations. This control argument must be the last argument -line_length N, -11 N sets the line length to be different from the terminal's default line length. -force, -fc permits the use of terminal type control arguments (-ttp. -query, -reset) when in the video system; however, the -ttp argument is restricted to video controllers. -line_length N, -11 N sets the line length to be different from the terminal's default line length. -line_speed N, -Is N indicates line speed to obtain proper padding (for ARPANet users), where N is the output line baud rate in bits/second. This control argument is ignored in the video system. -macros path, -macro path. -mc path loads the segment, specified by path, as Lisp, so that features therein are available. -no_force. -nfc prevents the use of terminal type control arguments when in the video system. (Default) -no_start_up, -no_startup. -ns prevents use of your startup (start_up. emacs). -page_length N, -pI N sets the page length iO be different from the terminal's default page length. -query queries you for a terminal type without checking the Multics terminal type first The query response can be any recognized editor terminal type. (See "Notes.") -reset specifies that Emacs disregard the terminal type set by -terminal_type and set it in accord with the Multics terminal type instead (see "Notes"). -terminal_type STR, -ttp STR specifies your terminal type to Emacs, where STR is any recognized editor terminal type or the pathname of a control segment to be loaded. If STR is not a recognized type, Emacs queries you after entry. providing a list of recognized types. (See "Notes.") 11/87 3-291 AG92-06B emacs emacs NOTES None of the terminal type control arguments (-ttp, -reset, -query, -line_speed) are generally necessary; they are only used for solving various communications problems. The control arguments -query, -reset, and -terminal_type are incompatible. You can't use them in the video system unless you provide -force. Emacs is a display-oriented editor designed for use on CRT terminals. Several modes of operation for special applications (e.g., RMAIL, PL/I, FORTRAN) are provided; the default mode entered is Fundamental major mode. For a basic introduction to the Emacs Text Editor and descriptions of the most generally used editing requests of emacs fundamental mode, see the Introduction to Emacs Text Editor (CP31). You can find a tutorial introduction to the Emacs Text Editor, fully describing the editing requests available and containing instructions for using special features of emacs, in the Emacs Text Editor User's Guide (CH27). A guide for programmers writing extensions and terminal control modules (CTLs) in Lisp is provided in the Emacs Extension Writer's Guide (CT52). You can get a complete. list of available requests in emacs via the make-waH-chart request while in emacs. Type the following: emacs ESC-X make-wall-chart where ESC is the escape key on the terminal. In addition, emacs provides its own online, interactive tutorial. which you can invoke by typing the following: emacs A ? where 001\" stands for the CONTROL key. which you must hold down while pressing the underscore character. See also the list_emacs_ctls command. 3-292 AG92-06 encode encode Name: encode SYNT AX AS A COMMAND encode pathlA {path2A •.• pathlN path2N} {-control_args} FUNCTION enciphers a segment's contents according to a key that is not stored in the system. The enciphered segment has the same length as the original segment The encode command provides additional security for data stored in a Multics segment ARGUMENTS pathl is the pathname of a segment to be enciphered. The star convention is allowed. path2 is the pathname of an enciphered segment to be produced. If the last path2 is not specified, it is assumed to be the same as pathl. The equal convention is allowed. This command always appends the code suffix to path2 to produce the name of the enciphered segment CONTROL ARGUMENTS -key STR specifies the encipherment key STR on the command line and does not query for one. This control argument is useful in exec_corn's for multiple invocations of the command with the same key. NOTES The encode command requests an encipherment key (1-11 characters not including space, semicolon, or tab) from the terminal. Printing on the terminal is suppressed (the printer is turned off) while the key is typed. The command then requests that the key be typed again, to guard against the possibility of mistyping the key. If the two keys do not match, the key is requested twice again. All segments specified in an invocation of encode are enciphered with the same key. To reconstruct the original segment from the enciphered segment, see the decode command. 3-293 AG92-06 Name: eneode_aceess~elass, eae SYNTAX AS A COMMAND eac {STR} {-control_arg} SYNTAX AS AN ACTIVE FUNCTION [eac {STR} {-control_arg}] FUNCTION prints/returns an encoded version (a short character string suitable for inclusion in entrynames) of an access class; this is an interface to the subroutine convert_access_class_$encode. ARGUMENTS STR is the access class to be encoded. If you use STR, don't use the control argument If you give no access class, the process's current authorization is used. CONTROL ARGUMENTS -access_class ACC, -ace ACC is an alternate way to specify the access class, where ACe is the access class to be encoded. Name: enter_abs_request, ear SYNTAX AS A COMMAND ear path {-control_args} FUNCTION allows you to request the creation of an absentee process, which you can delay until a specified time. An absentee process executes commands from a segment and places the output in another segment. ARGUMENTS path specifies the pathname of the absentee control segment associated with this request. The absin suffix is assumed. 3-294 AG92-06 CONTROL ARGUMENTS -arguments STRs, -argument STRs, -ag STRs indicates that the absentee control segment requires arguments. STR can be one or more arguments. All arguments following -ag are taken as arguments to the absentee control segment; therefore put -ag last in the command line. -brief, -bf suppresses the message "ID: HHMMSS.f; N already requested." -comment STR, -com STR associates a comment with the request. If STR contains blanks or other command language characters, enclose it in quotes. The comment is printed whenever you or the operator lists the request. It indicates to the operator the time or circumstances when a deferred job should be released, such as when a specified reel of tape is delivered to the computer room. -defer_indef ini tely, -dfi does not run the absentee process until the operator starts it. -extend appends absentee process output to the absout file. It overrides -tc. (Default) -foreground, -fg places the request in the foreground queue, rather than in one of the numbered background queues. For load control and charging, jobs in the foreground queue are treated as interactive logins; that is, a foreground job is logged in as if you would have logged in interactively, and, while logged in, it occupies a primary slot in your load control group. (See -secondary.) -limit N, -li N places a limit on the CPU time used by the absentee process. N must be a positive decimal integer specifying the limit in seconds. Your site defines the default limit for each queue and the upper limit for each queue on each shift. Jobs with limits exceeding the upper limit for the current shift are deferred to a shift with a higher limit. -lon~id, -lgid prints the long form of the request identifier in the normal message: ID: yymmddHHMMSS.ffffff; N already requested -notify. -nt notifies you (by an interactive message sent to your mailbox) when the job is logged in, when it is logged out, or when it is deferred for any reason other than your request. The latter may occur because of the unavailability of resources or a time limit higher than the maximum for the shifl -output_file path, -of path specifies the pathname of the output segment (see "Notes" below). 11/86 3-295 AG92-06A -proxy User_id enters the request on behalf of the specified user. An absentee process of that User_id is logged in to run the job. The system administrator controls the use of -proxy by an access control segment. -queue N, -q N submits the request to queue N, where N is an integer specifying the number of the absentee process queue. Your site administrator designates the default queue. There are four background queues, with queue 1 having the highest priority. Your site determines the highest ntL.~bered queue processed on each shift For convenience in writing exec_corns and abbreviations, the word "foreground" (fg) following -q is equivalent to -fg. -resource STR, -rsc STR specifies resources given in STR (e.g., one or more tape drives); don't start them until they are available. These resources are also reserved for the absentee job before it is logged in. You need not do resource reservation (using the reserve_resource command) in the absin segment. Enclose the resource description in quotes if it contains blanks or other command language characters. -restart, -rt starts over the computation of this request from the beginning if interrupted (for example, by a system crash). (Default: not to restart the computation) -secondary logs in a foreground job as a secondary user (subject to preemption) if there are no primary slots available in your load control group. By default a foreground job is only logged in if a primary process can be created for you. -sender STR enters requests only from sender STR. In most cases, the sender is an RJE station identifier. -time DT, -tm DT delays the creation of the absentee process until a specified date-time. where DT must be a character string acceptable to convert_date_to_binary_ (see the Subroutines manual). If DT contains blanks, enclose it in quotes. -truncate, -tc truncates the absout file, so that the absentee process begins writing at the beginning of the absout file. NOTES The main difference between an absentee process and an interactive one is that in an absentee process the I/O switch user_input instead of being attached to a terminal is attached to an absentee control segment containing commands and control lines, and the I/O switch user_output instead of being attached to a terminal is attached to an absentee output segment. The absentee control segment has the same syntax as an exec_com segment. An error message--unless it says otherwise--indicates that the request has not been submitted. 11/86 3-296 AG92-06A If you don't supply the pathname of the output segment, the output of the absentee process is directed to a segment whose pathname is the same as the absentee control segment, having the absout suffix instead of absin. If you omit the absout suffix from the output segment pathname, the suffix is assumed. The named output segment may or may not already exist If the absout segment exists, the absentee user (Person_id.Project_id.m or, in the case of a proxy request, Person_id.Project_id. p) must have w access to the segment. If the absout segment does not exist, the absentee user requires append permission to the directory in which it is to be created. The command checks for the existence of the absentee input segment and rejects a request for an absentee process if it is not present Specifying -tm is as if you issued ear at the deferred time. Be aware of differing time zones when deferring absentee jobs. If there is a possibility of overlapping times (i.e.. when est changes to edt, etc.), specify the time zone in the value given for -tm. If an absentee job cannot be run or if it terminates abnormally, the system sends an interactive user message to your mailbox. whether or not you give -nt. All input and output that occurs in the absentee job is written to the segment STR.absout in the same directory as the absentee segment STR.absin. This absout segment has its safety switch turned on temporarily while the job is running, since deleting the absout segment crashes the absentee job. The absentee login and logout messages are generated by the absentee process itself. The messages are written to the user_i/o switch. If a fatal process error or certain types of process damage occur, the messages may not ap~~r in the absout segment If you are diverting output to another file (by file_output, for example) when such an error occurs, you may need to issue adjust_bit_count for that file; this is because revert_output was never executed and the bit count of the file being written was not updated. To make sure that the absout is printed after absentee logout, even if it does not reach completion. put the following command line near the beginning of the absin HIe: ear -dupt [user absoutJ where "-dupt" is short for -defer_until_process_termination. To delete the absout when done. make the following the last Hne in the absin file: dl [user absoutJ -force; logout -brief The logout command prevents an abnormal termination trying to write another line to the deleted absout file. 11/86 3-297 AG92-06A An alternative to deleting the absout is to rename it so as to keep only the latest copy: answer yes -brief rename [user absoutJ ===.old This command line, which can appear anywhere in the absin file, forces deletion of any previous old copy and saves the current absout with suffix old for later examination. To delete the absin when completed, make the following the last line in the absin file: dl [user absin]; logout The logout command prevents an abnormal termination trying to read another line from the deleted absin file. The -tc control argument truncates the absout file at the time the absentee job is starting to run. but if the job is being restarted after a system crash, the truncation is not performed. EXAMPLES Suppose you want to request an offline compilation. This can be done with a control segment called absentee_pll.absin containing change_wdir current_dir pll x -table -map eor -delete x.list logout The command line ear absentee_pll creates an absentee process that does the following: 1. 11/86 Sets the working directory to the directory named current_dir, which is inferior to your normal home directory. 3-298 AG92-06A 2. Compiles a PL/I program named x,pll with two control arguments. 3. Prints one copy of the listing segment and then deletes it. 4. Logs out. The output of these tasks appear in the directory containing absentee_pl1.absin in a segment called absentee_pll.absout. 11/86 3-298.1 AG92-06A This page intentionally left blank. 11/86 AG92-06A Suppose that an absentee control segment, trans.absin, contains the following: change_wdir &1 &2 &3 -map &4 eor -delete &3.1ist &goto &2.b & 1abe 1 p 1 1 • b &3 &label fortran.b logout The command line ear trans -li 300 -rt -ag work pl1 x -table requests a restartable absentee process, in the default queue having a CPU limit of 300 seconds, that does the following: 1. Sets the working directory to the directory named "work," which is inferior to the normal home directory. 2. Compiles a PL/I program. x.pll. in that directory and produces a listing segment containing a map and an object segment containing a symbol table. 3. Issues a dprint request for the listing segment. 4. Executes the program "x" just compiled in the 5. Logs out. The command line ear trans -rt -tm IIMonday 2300.00 edt ll -q 2 -ag comp fortran yz creates a request for a restartable absentee process (in queue 2 at the first occurrence of Monday. 11 P.M., Eastern Daylight Time) that does the following: 1. Sets the working directory to the directory named "comp." which is inferior to the home directory. 2. Compiles a FORTRAN program named yz.fortran and produces a listing segment. 3. Issues a dprint request for the listing segment 4. Logs out 3-299 AG92-G6 -non_edi ted, -ned prints nonprintable characters as octal escape sequences (e.g., \000 or \577). A formfeed character in the input file normally begins printing the subsequent output at the top of the next page. Similarly, a vertical-tab character normally begins printing the subsequent output at the next vertical-tab stop. Vertical-tab stops are set at lines 1, 11, 21. 31, 41, and 51. -vertical_space, -vertsp skips to the top of the page when a f ormfeed character is found in the file being processed. It skips to the next vertical-tab stop when a vertical-tab character is encountered. (Default) -no_vertical_space, -nvertsp treats formfeed and vertical-tab characters as newline characters during printing. Print Page Labels The following control arguments govern the printing of labels at the top and bottom margins of each page of printed output. -label {-control_args} SIR. -lbl {-control_args} SIR puts STR as a label at the top and bottom of each printed page. The label can be constructed from SIR using the active string evaluation or the equal convention, as described below. ~active_string. -astr makes SIR an active string, which eor evaluates for each request that is submitted. For example, -label -astr date uses today's date as the label. Ihe pathname of the file being processed can be used in the active string because SIR is evaluated as: [do "[STR]" pathname] For example, -label -astr "date;string -;spe &1" produces the label "12/23/84-test" when submitting a request to print test.pll on December 23, 1984. 3-308 AG92-D6 Name: enter~output_request, eor SYNTAX AS A COMMAND eor {paths} {-control_args} FUNCTION submits requests to printer, punch, or plotter queues. All control arguments are nonpositional. Paired control arguments override one another if both are used in a single command. You can also establish personalized default settings for these control arguments. ARGUMENTS paths are pathnames of segments or multisegment files to be printed, punched, or plotted. The star convention is accepted. Null links and directories matching a starname are ignored without error. BASIC CONTROL ARGUMENTS -print, -pr submits requests for printing. (Default) -punch, -pch submits requests for punching. -plot submits requests for plotting on an installation-defined plotting device. -request_type STR, -rqt STR submits requests to the STR printer, punch, or plotter request type (see "Queuing Controls" below). -queue N, -q N submits requests to queue N of the request type (see "Queuing Controls" below). -header {-control_args} STR, -he {-control_args} STR identifies output with a heading of STR (see "Processing Controls" below). -destination {-control_args} STR. -ds {-control_args} STR labels output with STR, which is used to determine where to deliver the output (see "Processing Controls" below). -copies N, -cp N produces N copies of the printed. punched, or plotted output (see "Processing Controls" below). 3-300 AG92-o6 -delete, -dl deletes files after they are printed, punched, or plotted. -no_delete. -ndl does not delete files after they are printed. punched, or plotted. (Default) -notify, -nt sends a confirming message to the submitter when the request has been processed, showing the pathname and charge. -no_notify, -nnt does not send the confirmation. (Default) BASIC OPERATION: When this command is invoked with a pathname argument, it submits a request to print the file(s) identified by path. Each printed listing is identified by a destination string, which tells the operator how to route the listing to the submitter, and by a heading string, which further identifies the submitter or the listing. When you give no control arguments, eor uses default values for the header, the destination, the request type and priority at which the request is queued, the number of copies to be printed, and so on. This command provides standard settings for control arguments not given. However, it also allows you to change. these default values for the various request types. _ By using user-settable defaults, you can tailor eor to the type of print, punch. or plot requests most frequently queued. (See "Setting Defaults" below.) The eor command offers precise control over how print, punch, or plot requests are queued; how the requests are processed (e.g., formatting of printed pages or conversion of punched .files); and what actions are taken after processing (e.g., delete the file, notify the submitter). However, many users find that the following subset of control arguments provide adequate control for printing, punching, and plotting. CONTROL ARGUMENTS The control arguments accepted by eor are described below, organized by function. QUEUING CONTROLS -print, -pr -punch, -pch -plot -request_type, -rqt -queue. -q -name, -nm -brief, -bf -long, -lg -force, -fc -no_force, -nfc 3-301 AG92-06 PROCESSING CONTROLS -header, -he -destination, -ds -copies, -cp -forms PRINT OUTPUT CONVERSION -non_edited, -ned -edited, -ed -no_vertical_space, -nvertsp -vertical_space, -vertsp POSTPROCESSING CONTROLS -delete, -dl -no_delete, -ndl -notify, -nt -no_notify, -nnt PRINT PAGE LABELS -label, -lbl -top_label, -tlbl -bottom_label, -blbl -access_label, -albl -no_label. -nlbl PREPROCESSING CONTROLS PUNCH OUTPUT CONVERSION -defer_un til_process_termination, -dupt -mcc_punch, -mce -no_defer_until_process_1ermination, -ndupt -raw_punch. -raw -7punch, -7p PRINT FORMAT -page_length, -pI SETTING DEFAULTS -line_length, -11 -list_defaults, -ldft -inden t, -ind -print_defaults, -pdft -truncate. -tc -all. -a -fold -replace_defaults, -rdft -no_end_page, -nep -set_defaults, -sdft -end_page. -ep -delete_defaults, -ddft -default_name, -dnm -set_defaul t_request_ type, -sdrqt Queuing Controls The following control arguments govern how print, punch. and plot requests are submitted. A request is submitted to a particular request type to control where and how it is printed, punched. or plotted. For example, a file to be printed on a remote printer must be submitted to the request type associated with that printer. Similarly, a file to be printed on a special print form must be submitted to a special request type associated with that form. Use the print_request_types (prt) command to list available request types. Some request types are associated with printing, some are for card punching, and others are for plotting of output on installation-defined plotting devices. The request type can be chosen in several ways. -request_type STR, -rqt STR submits requests to the STR printer. punch. or plotter request type. STR must be one of the request types listed by print_request_types. (Default printer when printing, punch when punching. piotter when plotting) 3-302 AG92-06 -punch, -pch submits requests to the default punch request type. -plot submits requests to the default plotter request type. -print, -pr submits requests to the default print request type. (Default) To get the default print, prin t_request_types. punch, and plotter request types, use "eor -ldft" or You can submit requests using priority queue 1, 2, 3. or 4, queue 1 having the highest priority. Requests are processed by the 10 Driver process by priority: all requests from queue 1 are processed before any ones from queue 2, and so on; within a given queue, requests are processed in the order in which they were submitted. The higher the queue number, the quicker the request is processed and the higher the billing rate. Your site associates billing rates with each priority queue. -queue N. -q N submits the request to queue N of the request type. If N is "default" (dft) or "-default" (-dft), the default priority queue is used. Some request types have fewer than four queues, so the default priority queue varies, depending upon the request type. You can submit a request to process a file whose name looks like a control argument or starname. -name path. -nm path submits a request for the single file identified by the pathname. To print, punch. or plot a file the 10 Driver process must have at least r access to the -file and s access - to the directory that contains the file and the file must have a nonzero bit count. The print_request_types command lists the access name associated with the 10 Driver for each request type. -force, -fc forces sufficient access to a file to allow pnntlng, punching, or plotting and adjusts the bit count of segments having a zero bit count. -no_force, -nfc prints an error message for files having a zero bit count and for files to which the 10 Driver has insufficient access. (Default) The eor command reports how many files are submitted during an invocation with a message of the form: J requests submitted; K already in REQUEST_TYPE queue N. 3-303 AG92-06 -long, -lg prints the above message. (Default) -brief, -bf suppresses the above message. Processing Controls The following control arguments govern how the 10 Driver processes the output request The 10 Driver places leading and trailing "banner pages" around a print file to identify it Similarly the driver for central-site card punch devices places specially punched "flip cards" around a punch file. For remote card punches. special ID cards are punched at the start of each output file. For plot requests the 10 driver creates a plotted banner page to identify each plot request The banner pages, flip cards. and ID cards contain a destination, which tells the operator how to route the output back to the submitter, and a heading, which further identifies the file. For printed files the first 13 characters of the destination and header are printed in large, block letters to help identify the file. -header {-control_args} STR, -he {-control_args} STR identifies output with a heading of STR. STR is limited to 59 characters; "quote" it if it contains spaces. If "-default" (-dft) is given, the heading string is reset to its default value. (Default submitter's Person_id) You can construct the heading string from STR using the active string evaluation or the equal convention, as described below. -active_string, -astr makes STR an active string, which eor evaluates for each request that is submitted; for example, -he -astr date uses today's date as the heading. The pathname of the file being processed can be used in the active string because STR is evaluated as: [do "[STR]" pathnatne] For example, -he -astr "date;string -;spe &1" produces the heading "12/23/84-test" when submitting a request to print test.pl1 on December 23, 1984. 11/87 3-304 AG92-06B -equal_name. -enm the heading is constructed by applying the equal convention to STR and the entryname of t.he file being processed. If the STR con tains any equal signs (=) or percent characters (%), then -equal_name is assumed by default unless you supply -string. You can give this operand with -active_string to apply the equal convention to the evaluated active string. -string, -str treats STR as an ordinary heading, even though it may contain equal signs or begin with a hyphen. -destination {-control_args} SIR. -ds {-control_args} SIR labels output with STR, which is used to determine where to deliver the output. STR is limited to 24 characters; quote it if it contains spaces. If "-default" (-dft)is used. the destination string is reset to its default value. (Default submitter's Project_id) You can construct the heading string from STR using the active string evaluation or the equal convention, as described by the control arguments listed with -header above. *.cbn -copies N, -cp N produces N copies of the printed, punched. or plotted output. N can be any number from 1 to 30, or it can be "default" (dft) or "-default" (-dft) to obtain the default number of copies. (Def aul t: 1) -nsep specifies that when multiple copies of a request are processed the inner head and tail sheets should not be included. ~no_separator, -separator, -sep specifies that when multiple copies of a request are processed the inner head and tail sheets should be included. (Default) You can specify the type of software-generated forms to be used when printing a file (e.g., when printing on microfiche equipment); such forms differ from printer paper stock, which you should select by giving a -request_type identifying a set of queues associated with the desired paper stock. -forms SIR specifies the type of forms to be used when printing a file. Currently standard I/O daemon drivers ignore -forms when processing a print request 11/87 3-305 AG92-06B Preprocessing Controls The following control arguments govern when a request is to be processed. -defer_until_process_termination, -dupt does not process the request until the requesting process terminates. Process termination is caused by the logout command, new_proc, or a fatal process error. -no_defer_until_process_termination, -ndupt processes the request normally. (Default) Postprocessing Controls The following control arguments govern what the 10 Coordinator does with a file after it is printed or punChed. -delete, -dl deletes files after they are printed, punched, or plotted. -no_delete, -ndl does not delete files. (Default) If -delete is specified, the 10 Coordinator (usually IO.SysDaemon.z) must have at least m access to the directory containing the entry. A file is not deleted if it is modified after the request to output it is submitted. When the file is processed, the 10 Driver can send a confirmation message of the form: printed PATHNAME $COST queue N DEVICE_NAME PROCESSING_ID where PATHNAME is the pathname of the file that was output, COST is the dollar charge for processing the file, DEVICE_NAME is the name of the physical device on which the file was printed (e.g., prta or MDC_Office. prt) , and PROCESSING_ID is a number by which the file was identified to the operator. -no_notify, -nnt does not notify the submitter. (Default) -notify, -n t notifies the submitted after the entry is printed, punched, or plotted. Print Format The following control arguments govern the format of printed pages. 3-306 AG92-o6 You can control the length of lines in the printed output, the page length. the indentation of the left margin, and the method used in processing lines longer than the line length or pages longer than the page length. For example. when printing on special forms, it is often necessary to specify an indentation for the left margin to position the output properly on the form. Most printers can print at least 132 columns per line, some as high as 136. and up to 66 lines per page. However the maximum line and page length allowed for a particular request type depends upon both the width and the length of print forms mounted on the printer and the line and page length constraints of the printer device. -line_length L. =11 L prints L columns per line only. L can be any number from 1 to 250, or it can be "default" (dft) to obtain the default line length. (Default: varies depending upon the request type) -indent I. -ind 1 indents the left margin by 1 columns. 1 can be any number from 0 to L (the line length) or it can be "default" (df!) to obtain the default indentation. (Default: 0) -truncate. -tc truncates lines longer than L-I columns. -fold continues lines longer than L-I columns on subsequent print lines. -page_length p. -pI P prints no more than P lines per page, where P is the logical page length (i.e.• the number of lines of user data to appear). P can be "default" (dft) to obtain the default page length. (Default: varies depending upon the request type) -end_page. -ep skips to the top of the next page after P lines are printed on a page. (Default) -no_end_page. -nep skips to the top of the page only when a formfeed (newpage) character is encountered in the input Use of -no_end_page disables -page_length. Print Output Conversion The following control arguments govern how nonprinting ASCII (or non-ASCII) characters are printed in the listing. -edited. -ed suppresses printing of nonprintable characters. (Default) 11/87 3-307 AG92-()6B -equal_name, -enm the label is constructed by applying the equal convention to STR and the entryname of the file being processed. If the STR contains any equal signs (=) or percent characters (<]b). then -equal_name is assumed by default (unless -string is given). This operand can be given with -active_string to apply the equal convention to the evaluated active string. -string, -str treats STR as an ordinary label, even though it may contain equal signs or begin with a hyphen. -center centers the label on the printer page, based upon the line length given by -line_length or the default line length associated with the request type. (Default label is left justified) -top_label {-control_args} STR, -tlbl {-control_argsJ STR puts STR as a label at the top of each printed page. The top label can be constructed from STR using the active string evaluation or the equal convention, as described by the control arguments listed with -label above. -bottom_label {-control_args} STR. -blbl {-control_args} STR puts STR as a label at the bottom of each printed page. The bottom label can be constructed as the top label. -access_label, -albl puts. the access class of the entry being printed at the top and bottom of every page; for entries at system_low access class, this is equivalent to -no_label. (Default) -no_label, -nlbl does not place any labels in the printed output. Access labels are centered in the top and bottom margins on each printed page. All other labels are aligned with the left margin. For a file at system_low access class, the access label is a null string. -access_label for such files is equivalent to -no_label. Thus, The top and bottom labels on a page are treated independently. Giving -top_label alone leaves an access label at the bottom of the page; giving -bottom_label alone leaves an access label at the top of each page. When -no_end_page is specified, the top and bottom margins of each page are eliminated; therefore, -no_end_page is incompatible with the label control arguments. 3-309 AG92-06 Punch Output Conversion The following control arguments govern the type of output conversion performed when punching a file. Three conversion modes are available: character conversion using Multics card codes. binary conversion using Multics 7-puneh card codes. or raw (no) conversion. (See the Programmer's Ref erenee Manual for inf ormation on the input/ output system and conversion codes.) -mcc_punch, -mec punches files using character conversion. (Default) -raw_punch. -raw punches files using no conversion. -7punch. -7p punches files using 7-punch conversion. When any of the above control arguments are used, -punch is assumed. Setting DefauIts The following control arguments allow you to print or change the default control argument values used by eor (see "Examples.") A different group of control argument values can be defined for each print. punch, or plot request type. This allows different defaults for local and remote printers and for specialized print forms. Groups of control argument settings are stored for each user in the default value segment (usually a home directory segment called Person_id.value). If it does not already exist. this segment is created automatically the first time you invoke eor. The following control arguments list the values for one or more of the defined groups. -list_defaults, -ldft lists the names of all groups of control argument values that have been defined. Printing, punching, and plotting groups are listed separately. The list also identifies the default group used for printing. punching, or plotting (the group used when -request_type is not given). -print_defaults. -pdft prints the control argument values associated with the group identified by -request_type. If -request_type is omitted, prints values for the default punch group (if punch-oriented control arguments are given), default plot group (if -plot is given). or the default print group. -all, -a prints the control argument values associated with all defined groups (-print_defaults is assumed). 3-310 AG92-Q6 A new group of control argument settings can be defined by referencing the group name in -request_type and using either -replace_defaults or -set_defaults. Similarly, an existing group can be modified or deleted. When defining a group of control argument settings. the group can be initialized to standard settings, and then any control arguments supplied in the command line are used to modify these settings. Alternately, an existing group can be modified by applying the given control arguments to the group without resetting the group to standard values. -replace_defaults, -rdft resets control argument settings in the group to their standard values and then applies the specified control arguments to modify the group. -set_defaults, -sdft adds control arguments given in the command line to the existing default values. -delete_defaults, -ddft deletes the definition of the named group of control argument settings. When eor is invoked without -request_type. a default request type is used. The standard default request type for print requests is "printer". which usually designates the site's local printer; for punch requests is "punch". which usually designates the site's local punch; and for plot requests is "plotter". You can change these default request types. -set_default_request_type STR, -sdrqt STR sets the default request type for printing, punching, or plotting to STR. The print default request type is set by default). STR must be a request type or the name of a group of control argument settings. It is sometimes desirable to define several different groups of control argument settings associated with the same request type. For example. you might want to indent only segments containing Multics mail. Several groups can be associated with the same request type by using the following control argument along with -request_type. -default_name STR, -dnm STR uses STR as the name for a new group of control argument settings being defined. Use -default_name when the name oi the new group differs from the request type defined by the group. Subsequent references to the group are made by using -request_type (i.e., the new group name becomes a user-defined request type). ACCESS REQUIRED The 10 Daemon process that performs the printing or punching must have at least r access to the entry and at least s access to the directory that contains the entry. Use the print_request_types command to print the access name of 10 Daemon processes. 3-311 AG92-o6 If -delete is given, the 10 coordinator (normally 10.SysDaemon.z) must have at least m access to the directory that contains the entry. NOTES If eor is invoked without arguments, it gives the status of the default printer request type. EXAMPLES The following examples illustrate how groups of control argument settings can be defined, modif ied, printed, or deleted. eor -rdft -rqt cisl_prt -nt -q 2 -ind 10 resets the cisl_prt group to the standard control argument values and then applies the -nt, -q, and -ind settings to change the defaults. You can print the new defaults by eor -rqt cisl_prt -pdft cisl_prt: -rqt cisl_prt -print -he "LvBeethoven" -ds ISysLib" ~nt -q 2 -ind 10 ~albl You can make the cisl_prt group the default request type for printing by When you invoke eor without control arguments, the cisl_prt control argument settings are used. You can now modify and print these defaults by eor -ind 0 -sdft -pdft cis l_prt: (defau 1t for pr i nt i ng) -rqt cisi_prt -print -he IJSBach" -ds IISysLib li -nt -q 2 -albl You don't have to give the cisl_prt request type in the command line because it is now the default request type for printing. Several groups of defaults can apply to the same request type by using -default_name. For example, to define a request type to print mait indented by 20, use eor -rdft -dnm mail -rqt printer -ind 20 -pdft -q dft 11/87 3-312 AG92-06B ma i 1 : -rqt printer -print -he "LdVinci ll -ds ISysLib" -q 3 (default) -ind 20 -albl Segments with a mail suffix can be printed with the mail defaults by eor -rqt mail **.mail The mail defaults can be modified by eor -rqt mail -sdft -nt -dl -pdft ma i 1 : -rqt printer -print -he ILdVinci" -ds "SysLib ll -q 3 (default) -dl -nt -ind 20 -albl The known groups of defaults (and their associated request types) can be listed by eor -ldft Defaults for printing: pri'nter mail -rqt printer Defaults for punching: punch (def au 1t) Defaults for plotting: plotter (default) All the groups of control argument settings can be printed by eor -pdft -a cisl_prt: (default for printing) -rqt cisl_prt -print -he "LdVinci ll -ds "SysLib ll -nt -q 2 -albl ma i 1 : -rqt printer -print -he "LdVinci ll -ds "SysLib" -dl -nt -q 3 (default) -ind 20 3-313 -albl AG92-06 printer: -rqt printer -print -he ILdVinci" -ds "SysLib" -q 3 (default) -albl punch: (def au 1t for punch i ng) -rqt punch -punch -he "LdVinci ll -ds IISysLib ll -q 1 (def au 1t) -mcc plotter: (default for plotting) -rqt plotter -plot -he IILdVinci" -ds IISysLib" -q 1 (default) Name: enter_retrieval_request, err SYNTAX AS A COMMAND err path {-control_args} FUNCTION queues volume retrieval requests for specific segments, directories, multisegment files (MSFs). and subtrees. ARGUMENTS path is the pathname of a segment, directory, or node of a subtree. convention is not allowed. The star CONTROL ARGUMENTS -brief, -bf supresses printing of the 10 and number of requests in queue. -from DT, -fm DT specifies that the search for path and all inferior branches, if supplied, stops at time DT; thus, objects dumped before time DT are not recovered. (See Section 1 for a description of valid DT valUes.) If you give no -from. all valid dump volumes are searched. 3-314 AG92-06 -lonLid prints the long ID of the request. (Default to print the short ID) -multisegment_file, -msf specifies that the object named in path is an MSF and that all its components are to be recovered. -new_path newpath specifies that if you have the correct access to retrieve the segment specified in path and to create a segment with the pathname newpath, then the object identified by path is retrieved into newpath. You can't cross-retrieve directories, MSFs, or subtrees. -notify, -nt notifies you by online mail of the success or failure of the request. (Default: not to notify you) -previous, -prev retrieves the object dumped prior to the object presently online. With -prev you can retrieve successively earlier copies of an object. (Default: to retrieve the most recent copy) -queue N, -q N queues requests in priority queue N. (Default: 3) -subtree, -subt retrieves the subtree inf erior to the directory given in path as well as the directory. If a subtree is found intact after a directory is recovered, no further action is taken unless you have provided a time interval (see "Notes"). (Default: not to retrieve subtrees) -to Dr searches for path and all inferior branches from time DT backwards; thus, objects dumped later than time Dr are not recovered. (See Section 1 for a description of valid Dr valUes.) If you don't select -to, time Dr is assumed to be the start of the retrieval operation. ACCESS REQUIRED To retrieve a segment, you need w access to the segment or m access to the con taining directory; to retrieve a directory, you need m access to the directory or m access to the containing directory. NOTES In certain cases where a directory is damaged the inferior subtree may be unavailable until the directory is recovered. When a directory is recovered and you use -subt, a check is made to see if the subtree is available. and, if so, retrieval is assumed complete. 11/86 3-315 AG92-Q6A en ter_retrieval_request entries Retrieval requests of objects for which the online copy is more recent or the same as the dump copy are refused unless you use -fm, -prev, or -to. You need not supply as a set of primary names the pathnames of the segments and directories to be retrieved. Any set of valid entrynames is acceptable. You have to log in to ring 1 to submit retrieval requests for mailboxes and other ring 1 objects. Name: entries SYNTAX AS A COMMAND entries star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [entries star_names {-control_args}] FUNCTION returns the entry names or absolute pathnames of segments, directories. multisegment files (MSFs), links, data management (DM) files, and extended entries that match one or more star names. ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) 11/86 3-316 AG92-06A entries entries -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) -select_en try_type type_name, -slet type_name returns entrynames of entries of the specified type. You need not give the suffix in the starname. Use the list_entry_types command to obtain a list of valid entry type values. NOTES Only one name per entry is returned; i.e., if an entry has more than one name that matches a starname. only the first match found is returned. Since each entryname (or pathname) returned by entries is enclosed in quotes. the command processor treats each name as a single argument regardless of the presence of special characters in the name. See the directories. directory, and entry commands. 11/86 3-316.1 AG92-06A This page intentionally left blank. 11/86 AG92-06A entry_path entry Name: entry SYNTAX AS A COMMAND entry path SYNTAX AS AN ACTIVE FUNCTION [entry path] FUNCTION returns the entryname portion of path. after it has been expanded into an absolute pathname. ARGUMENTS path is the pathname whose entryname portion is to be returned. NOTES Since the pathname is returned in quotes. the command processor treats it as a single argument regardless of special characters in the name. EXAMPLES entry >udd>Proj>Myname>start_up.ec start_up.ec entry >udd>Multics>Library>Source>bound_command_demos_.s::program.pl1 bound_command_demos_.s.archive Name: entry_path SYNTAX AS A COMMAND entry_path path SYNTAX AS AN ACTIVE FUNCTION [entry_path path] 3-317 AG92-06 equal entry_path FUNCTION returns the absolute pathname of the entry represented by the path argument If the path is an archive component pathname. this returns the pathname of the archive segment; otherwise this command is equivalent to the path command. ARGUMENTS path is the pathname whose directory and entryname portion is to be returned as a single absolute pathname. NOTES Since the pathname is returned in quotes, the command processor treats it as a single argument regardless of special characters in the name. EXAMPLES entry_path [hd]>start_up.ec >udd>Proj>Myname>start_up.ec entry_path >udd>Multics>Library>Source>bound_command_demos_.s::program.pl1 >udd>Multics>Library>Source>bound_command_demos_.s.archive Name: equal SYNTAX AS A COMMAND equal STRA STRB SYNTAX AS AN ACTIVE FUNCTION [equal STRA STRB] FUNCTION returns true if str A is equal to strB; otherwise it returns false. ARGUMENTS STRA. STRB are character strings to be compared. 3-318 AG92-Q6 equal NOTES The strings are compared character by character according to their ASCII code value (i.e.. if the first character in each string has the same ASCII code value. compare the second character; if their values are identical, compare the third character; etc.). Strings of unequal length are compared by padding with blanks. EXAMPLES string [equal Ab ab] false string [equal this this] true Name: equal_name, enm SYNTAX AS A COMMAND enm path equal_path SYNTAX AS AN ACTIVE FUNCTION FUNCTION returns a pathname, constructed by applying the equal convention to the specified arguments. ARGUll'IElVTS path is the source pathname to which the equal convention is applied. You can use the archive component pathname convention. equal_path is a pathname whose entryname and component name portions are equal names. NOTES Since the pathname is returned in quotes, the command processor treats it as a single argumen t regardless of special characters in the name. With the active function you can apply equal names within abbreviations and exec_com segments. 3-319 AG92-Q6 exec_com (version 2) For a complete description of the equal convention see the Programmer's Reference Manual. EXAMPLES enm apple.ec orange.== orange.ec enm fruits.archive::apple.ec orange.== orange.ec Name: exec_com, ec (version 2) SYNTAX AS A COMMAND ec {-control_args} path {ec_args} SYNTAX AS AN ACTIVE FUNCTION [ec {-control_args} path {ec_args}] FUivCTiON executes programs written in the exec_com language; used to pass command lines to the Multics command processor and pass input lines to commands reading input. The syntax described here is known as Version 2, so make the first line of the exec_com program be "&version 2i1. For a description of Version 1 syntax. see exec_com (version 1). ARGUMENTS path is the path name of an exec_com program, written using the constructs described below. The suffix ".ec" is assumed if not specified. The star convention is not allowed. ec_args are optional arguments to the exec_com program and are substituted for parameter references such as &1 (see "List of Parameters"). 3-320 AG92-06 exec_com (version 2) exec_com (version 2) CONTROL ARGUMENTS -no_trace KEYWORD_LIST turns off tracing of specified types of exec_com lines, overriding any &trace statements in the exec_com for those types of lines. KEYWORD_LIST is composed of any of the keywords "all_types". "command", "comment", "control", and "input", separated by commas with no intervening space. -trace KEYWORD_LIST turns on tracing of specified types of exec_com lines, overriding any &trace statements in the exec_com for those types of lines. KEYWORD_LIST is composed of any of the following, separated by commas, with no intervening space: all_types, command, comment, control, input turns on tracing for the corresponding type of line(s). unexpanded, expanded, all_expansions or all, both affects how the expansion of lines is traced. These are equivalent to &unexpanded, &expanded, &all_expansions or &all, and &both in &trace statements inside the exec_com. prefix=STR specifies a prefix for traced lines, equivalent to &prefix in &trace statements. osw=SWITCHNAME specifies an I/O switch on which to write the trace, equivalent to &osw in &trace statements. -trace_default uses &trace statements in the exec_com and determine what and how to trace. (Default) the default tracing modes to LIST OF PARAMETERS &1 - &9 expands to the 1st through 9th ec_args or to defaults defined by a &default statement or to the null string if there is no corresponding ec_arg. The string &0 is invalid. &(1) - &(9) are synonyms for &1 - &9. &(11), &(12), etc. expands to the corresponding ec_arg or to a default defined by &default or to null string if there is no corresponding ec_arg. The parentheses are required when there are two or more digits. 3-321 AG92-()6 exec_com (version 2) exec_com (version 2) &q1 - &q9 &q(1). &q(1l), etc. expands to the corresponding argument with quotes doubled according to the quote depth of the surrounding context (see "Notes on Quoting"). This parameter ensures that quotes in the argument to exec_com are handled correctly under the quote-stripping action of the command processor. &r1 - &r9 &r(1), &r(1l), etc. expands to the corresponding argument enclosed in an added layer of quotes and internal quotes doubled accordingly (see "Notes on Quoting"). This parameter keeps the value of the argument as a single unit after one layer of quote stripping by the command processor. &n expands to the number of ec_args specified to exec_com. &f1 - &f9 &f(1), &f(11), etc. expands to a list of the Nth through last ec_args separated by spaces. If N is greater than the value of &n, expands to null string. &qfl - &qf9 &qf(1), &qf(1l), etc. expands to a list of the Nth through last ec_args, with quotes doubled, separated by spaces. If N is greater than the value of &n, expands to null string. This parameter is equivalent to &qN &qN+ 1 &qN+ 2 .... &rfl - &rf9 &rf(1), &rf(11), etc. expands to a list of the Nth through last ec_args, individually requoted. separated by spaces. If N is greater than the value of &n, expands to null string. This parameter is equivalent to &rN &rN+1 &rN+2 .... &f &n, &qf &n, &rf &n expands to the last ec_arg given to exec_com as is, with quotes doubled, or requoted. &condition_info_ptr, &cond_info_ptr inside an &on unit, expands to a virtual pointer «segment_number> I foo". &ec_name expands to the entryname of the exec_com currently running, with any ec or absin suffix removed (the absin suffix is for an exec_com invoked by the absentee facility). This parameter can be used to simulate entrypoints in an exec_com segment, by adding multiple names to the segment and transferring to a different &label depending on the name invoked. &ec_path expands to the expanded, suffixed pathname of the current exec_com. &ec_dir, links in the pathname have not been chased. Unlike &ec_switch expands to the name of the I/O switch over which the exec_com interpreter is reading the exec_com. &handlers expands to a list of condition names for which &on handlers are currently in effect (see "List of Condition-:Handling Statements"). Condition names are individually requoted and separated by spaces. To test whether a handler is currently in effect for NAME, type: n&if & [or [equal NAME (&handlers)]] &then ... " LIST OF VALUE EXPRESSIONS All of these constructs can be nested arbitrarily inside each other. &(NAME) expands to the value assigned to the variable NAME by a previous &set statement in the same exec_com. If NAME contains &'s, it is first expanded. Therefore, &0 constructs can be nested. However, &'s in the expansion are not re-expanded. A second level of expansion must be indicated. consequently, by &(&0). If NAME has not been assigned a value by &set, an error occurs. Variable names are allowed to contain any characters except & and cannot consist solely of digits and white space. &(N) expands to the value of the Nth (where N is a positive integer) ec_arg to exec_com; or if there is no Nth ec_arg, to the last default vaiue assigned to argument N by a &default statement; or if no default value was assigned, to null string. &q(NAME), &q(N) expands to the same thing as &(NAME) or &(N), but with quotes inside the value doubled according to the quote depth of the surrounding context 3-323 AG92-06 exec_com (version 2) exec_com (version 2) &r(NAME). &r(n) expands to the same thing as &(NAME) or &(N). but requoted and with internal quotes doubled. & [ACTIVE STRING]. & I I [ACTIVE STRING] expands to the return value of an active string by calling the command processor. This construct ends with the matching right bracket. The & II [... ] construct is used in &set statements to treat the expansion as a single argument to &set. It is important to note that & [... ] active strings are expanded by exec_com, whereas [... ] strings are expanded at command line execution time. Therefore. II [... ], not & II [... ] , must be used in a command line to treat the expansion as a single command argument. Lf ST OF LITERALS See "Notes on White Space." & " ... " encloses an arbitrary character string to be taken literally. Quotes inside the string must be doubled, and the closing undoubled quote ends the literal string. && expands to a single & character, not further expanded. &, &(N) expands to a single ampersand character (ASCII 046), in which case it is identical to &&. or to N ampersands where N is a positive integer. &SP, &SP(N) expands to a single space character (ASCII 040) or to N spaces. &BS. &BS(N) expands to a single backspace character (ASCII 010) or to N backspaces. &HT, &HT(N) expands to a single horizontal tab character (ASCII 011) or to' N horizontal tabs. &VT. &VT(N) expands to a single vertical tab character (ASCII 013) or to N vertical tabs. &FF, &FF(N), &NP, &NP(N) expands to a single form-feed character (ASCII 014) or to N form feeds. &NL. &NL(N), &LF. &LF(N) expands to a single newline character (ASCII 012) or to N new lines. &QT, &QT(N) expands to a single double-quote character (n) or to N of them. 3-324 AG92-06 exec_com, ec (version 2) exec_com, ec (version 2) expands to a Multics 15-character unique name, for example " BBBhjBnWQpGbbc". Multiple occurrences of &! within the same exec_com expand to the same string. LIST OF PREDICATES &is_defined(NAME) expands to "true" if the variable named NAME has been assigned a value by an &set statement in the current exec_com, "false" otherwise. This construct expands to "true" if &(NAME) can be expanded, "false" if &(NAME) is an error. &is_defined(N) expands to "true" if an Nth (where N is a positive integer) ec_arg is given to exec_com or an Nth default is defined by. the &default statement (see "List of Assignment Statements" below), iifalseil otherwise. &is_absin expands to "true" if the exec_com is being executed by the absentee facility. "false" if it is by the exec_com command or active function. In the case of an absentee executing the start_up.ec, this value is returned as "false" because it is being executed by the exec_com command. The command "ear program" causes the absentee listener to execute program.absin, and then &is_absin returns "true." &is_active_function, &is_af expands to "true" if the exec_com is being executed by the exec_com active function. "false" otherwise. &is_attached expands to "true" if input is currently attached by an &attach statement. "false" otherwise (see "Notes on Input Attachment" below). Input is always attached when running as an absentee. &is_input_Iine expands to "true" if the line in which it appears is being read as an input line by some command. "false" otherwise. &was_attached inside an &on unit. expands to "true" if the parent exec_com was attached by &attach at the time the condition occurred, "false" otherwise (see "List of Condition-Handling Statements" below). Outside an &on unit, always expands to "false. " 11/86 3-325 AG92-06A exec_com, ec (version 2) exec_com, ec (version 2) LIST OF CONTROL STATEMENTS &attach {&trim on/off} causes any commands subsequently invoked in command lines to read their input from the exec_corn rather than from the terminal (see "Notes on Input Attachment" below). Specifying "&trim off" causes the input lines to be read intact, without stripping off the leading and trailing white space as is done with most exec_corn lines. (Default: "&trim on") &detach causes any commands subsequently invoked in command lines to read their input from the terminal (see "Notes on Input Attachment" below). (Default) &if EXPRESSION expands EXPRESSION to get a true or false value. EXPRESSION can contain any exec_com-expandable constructs, such as & [... J (see "List of Value Expressions" above). If the expanded value of EXPRESSION is "true," the following &then statement (if any) is executed next If the value is "false," the following &else statement (if any) is executed next If the value is neither "true" nor "false," an error occurs (see "Examples of if Statements" below). &then LINE &then &do LINES &end &else LINE &else &do LINES &end where LINE is any exec_com line, including another &if statement LINE is executed or not· depending on the value of the preceding &if clause. The &then and &else statements, unlike other exec_com statements, are allowed to appear on the same line with one another and with &if; however, the &then or &else cannot be on a separate line from the LINE or &do that it executes (see "Examples of if Statements" below). The contents of an &do-&end block reference the same variables as the containing exec_corn. No &goto's are allowed into a &do-&end block from outside it. &goto LABEL causes the next statement to be executed to be the statement following the first occurrence of "&label LABEL" in the exec_com. &label LABEL designates a target for "&goto LABEL" and is otherwise ignored. LABEL can contain any characters except &. The string &quit terminates execution of the exec_com. If the program was invoked by the exec_com active function, the active function return· value is a quoted null string (''''). 3-326 AG92-06 exec_com (version 2) exec_com (version 2) &return LINE terminates execution of the exec_com. If the program was invoked by the exec_com active function, the active function value is the (expanded) value of LINE, the rest of the line. If the program was invoked by the exec_com command, the expanded value of LINE is printed on the terminal. LIST OF ASSIGNMENT STATEMENTS &set NAMEI VALUEI ... NAMEn VALUEn assigns values to the variables NAMEI through NAMEn, which are created if no assignments for them already exist. All NAMEj and VALUEj arguments are fully expanded before any values are set Therefore, the statement &set a &(b) b &(a) exchanges the values of the variables a and b. Arguments to &set are delimited by white space. White space and literals inside them must be enclosed in quotes, for example: &set answer "& [response Answer?]" Alternatively, the & II [... ] construct can be used, causing the entire return value to be .taken as a single argument: &set answer & I I [response Answer?] There is no restriction on the lengths of NAMEj or VALUEj. VALUEj can contain any characters. NAMEj cannot be all digits. If VALUEj is the unquoted keyword &undefined, any existing value for NAMEj is deleted and the &is_defined(NAMEj) construct expands to "false." &default VALUEl ... VALUEn assigns default values for the exec_com parameters &(1) through &(n). The default value of &U) only matters if no jth ec_arg was specified to exec_com. The &(j) parameter reference expands to the value of the jth ec_arg; or if there is none, to the jth default value set by &default; or if there is none, to null string. VALUEj arguments are separated by white space, and each is fully expanded before default values are set White space and literal's in them must If VALUEj is the keyword &undefined or &undef, no jth be enclosed in &" ... default value is set. This keyword is used as a place holder to skip the jth position. fl. LIST OF PRINTING STATEMENTS &print LINE prints the expanded remainder of the line, followed by a newline character. If &print appears on a line by itself, a single newline character is printed. 3-327 AG92-06 exec_com (version 2) exec_com (version 2) &print_nnl LINE prints the expanded remainder of the line. without appending a newline character. LIST OF CONDITION-HANDLING STATEMENTS &on CONDITION_LIST &begin LINES &end establishes a condition handler (&on unit) to be invoked whenever any of the conditions named in CONDITION_LIST is signaled. Condition names are separated by white space. LINES is any sequence of exec_com lines, optionally including &goto statements to transfer to labels either inside the &on unit or outside (i.e.• in the parent exec_com). When executed, LINES is treated as a separate exec_com in the sense that changes to its &attach, &ready_proc, and &trace modes (initially off) do not affect the parent exec_com. However, &on units share the parent ec's variables, and any changes to variables affect the parent exec_com. The &begin and &end keywords are required for delimiting LINES, even if it consists of a single line. No &quit statement is required. &revert CONDITION_LIST reverts any &on units for the conditions named in CONDITION_LIST. Condition names are separated by white space. &signal CONDITION_NAME signals the indicated condition. The following statement is allowed only inside &on units: &exit {&continue} causes the &on unit to exit immediately. This statement is useful for conditionally exiting part-way through an &on unit. If &continue is supplied, the condition continues to be propagated to other handlers down the stack. LIST OF TRACING STATEMENTS &list_variables {match_names} {&control_args}, &lsv {match_names} {&control_args} lists the values of all or selected exec_com variables, where match_names are starnames and/or qedx regular expressions surrounded by slashes (/). Control arguments are "&exclude match_name" ("&ex match_name") to prevent certain names from being listed, &variable (&var) to list just the variable names, and &value (&vaI) to list just the values. &ready on &ready off turns ready messages on or off. Turning them on causes the system ready procedure to print a ready message when it is called. The default is off. This statement does not affect whether the ready procedure is called. The ready procedure is normally called after the execution of a command line (see the description of the ready _on command). This statement is ignored in the absentee environmen t. 3-328 AG92-06 exec_com (version 2) exec_com (version 2) &ready_proc on &ready_proc off determines whether or not the system ready procedure is called after each command line is executed. The default is on for the exec_com command, off for the active function. This statement is ignored in the absentee environment. &trace {TYPES} ST ATE {&prefix PREFIX} {&osw SWITCHNAME} sets tracing for one or more kinds of lines specified by TYPES. TYPES can be any combination of the following: &command &comment &control &input &all_types command lines comments, including those sharing other lines control lines, for example, &print. .. lines being read as input to some command specifies all of &ccmmand, &ccmment, &control, and &input. The def aul t if TYPE is omitted is all four types. STATE can be one of the following: off, false on, true &unexpanded &expanded &all disables tracing entirely. enables tracing, in whichever of the f oHowing modes was last specified. The default mode is "&expanded" for command and input lines, "&both" for control lines. prints lines as they appear in the exec_com segment Implies "on". prints lines after all expansion has been done. Implies "on". prints at each stage of expansion. Implies "on". * MeR 6691 &all_expansions &both is a synonym for &all. prints each line as it appears in the exec_com, and again after all expansion. Implies "on". I Defaults for ec's invoked by the exec_com command/active function are "&expanded" for command and input lines, "&unexpanded" for control lines, and "off" for comments. Defaults in the absentee environment are "&expanded" for command and control lines, "off" for control lines and comments. PREFIX designates a string to be printed at the start of each line. prefixes are all null string. Default SWITCHNAME specifies an I/O switch on which to write the trace. The default for all types of lines in ec's invoked by the exec_com command or active function is user_output. The default in the absentee environment is user_io. 3-329 AG92-G6 exec_com (version 2) exec_com (version 2) NOTES ON ABSENTEE ENVIRONMENT An exec_com/absin runs in the absentee environment only when it has been invoked directly by the absentee facility. i.e.. is running an absentee process. Exec_corn's called within an absentee process are said to run in the normal exec_com environment Input lines in an absentee process come from the absin segment running the process. These, along with output lines, are directed to an· absout file. Since both input and output lines are written to the same switch. the default switch is chosen to be user_io for the absentee environment rather than user_output as for exec_corn's. This default applies to all tracing, and ensures that even if user_output is redirected somewhere, the input lines driving the process still appear in the absout The &attach and &detach statements have no effect in the absentee environment, since input to the absentee process always comes from the absin file. The &is_attached predicate always returns true. The &ready and &ready_proc statements also have no effect in the absentee environment Instead, the ready_on and ready_off commands should be used. NOTES ON VERSION The current version of exec_com is known as Version 2 (V2). In many ways similar to the old Version 1 (Vl), it adds automatic variables, parameter defaults, literal character escapes, indentation, comments on lines, line continuation, expansion of active strings in control lines, and tracing of comments and control lines. In addition. there are two incompatible changes between the versions. Whereas VI leaves unrecognized &strings alone, V2 rejects them as syntax errors. This change makes V2 an extensible language. Second. V2 parses lines into control keywords and tokens (separated by white space) before expansion, so that expansion can only change the values of tokens but not the syntax of a line. A V2 exec_com has "&version 2" as its first line. If this first line is not present, the exec_com is interpreted as VI. VI exec_corn's can optionally begin with "&version 1". At some future time. V2 will be the default and "&version 1" will be required. A conversion command is available to translate VI exec_corn's to V2: convert_ec. NOTES ON WHITE SPACE White space (SPACE. HORIZONTAL TAB, VERTICAL TAB, and FORM-FEED) is ignored at the beginning and end of each line, with the exception of input lines specifically read with "&attach &trim off" in effect As a result, exec_com lines can be indented as desired for readability. Intentional white space at the beginning or end of a line (for example, an editor input line) must be specified by literal escapes such as &SP. See "List of Literals". 3-330 AG92-06 exec_com (version 2) exec_com (version 2) NOTES ON COMMENTS Comments are specified by the character sequence &- anywhere in a line. Where this sequence appears (outside of &" ... "), the remainder of the line is a comment and can contain any characters. White space preceding the comment, if any, is ignored, and can be specified by the literal escapes described in "List of Literals." Therefore, comments can be aligned at a particular column without affecting the executable text. NOTES ON CONTINUATION Long command lines and other portions of text that must not be broken can be continued on successive lines by means of the character sequence &+ at the beginning of each continuation line. White space preceding the &+ is ignored. An example is sm Bartley.TRG This is such a long message I prefer to &+ stretch it onto a second line of the exec com. Note that white space following the &+ is part of the executable line, and in the above example it is necessary to separate arguments to sm. Continuation is not affected by intervening comments, whether at the end of executable text lines or on lines by themselves. This feature can be used to comment parts of statements, for example: sa fast_print adros *.Admin &-Maintainers &-The XPer project should be added later &+ aos ,': &-Non-maintainers The complementary character sequences &+ and &- can be thought of as meaning "This is part of the executable text" and "This isn't", respectively. NOTES ON QUOTING The exec_com interpreter strips one layer of exec_com quotes (&" ... ") from the text It does not perform command-processor-type stripping of regular quotes (" ... "). 3-331 AG92-06 exec_com (version exec_com (version 2) 2) To defeat one or more levels of command processor quote stripping, the values of variable and parameter expansions can be quote-doubled or requoted using the "q" and "rn prefixes. Quote doubling doubles existing quote characters in a string according to the depth of quotes inside which the string is currently nested, so that one level of quote stripping by the command processor results in the internal quotes looking the same as they do inside the original string. Requoting goes a step further by first quote-doubling, then surrounding string with an additional layer of quotes, thus causing the entire string to remain a single argument after one level of quote stripping by the command processor. In the examples below, "Level" refers to the number of levels deep in quotes that the parameter reference appears in the exec_com text Assume that the value of the first ec_arg to exec_com is the string a"b containing a single-quote character: &1 Level 0 Level 1 Level 2 &ql &r1 allb a"b lIa"llb li lIalb" '"I"a"b""" IIII"a""""a"I"1 II a" "b" III1"a llll ""b""" "" 1111111111 a" 1111"" IIlIlIbli II 1111" II" The exact number of quote characters is significant; the important thing is that &q protects internal quotes from one level of quote stripping by the command processor, and &r ensures that the value remains a single argument to the command processor. These prefixes are very useful, since. if the value of the first ec_arg (for example) contains a space, the value of &1 substituted into a command line is parsed into more than one command line argument. If a value is nUll, the &q prefix does not affect it, and the &r prefix results in a pair of quotes, doubled according to the quote depth of the context The "q" and "r" prefixes can be used in the following constructs: &ql, &q(1) &qf1, &qf(1) &q&n, &qf&n &q(V AR NAME) &rl, &r(1) &rfl, &rf(1) &r&n, &rf&n &r(V AR NAME) NOTES ON INPUT ATTACHMENT By default, commands invoked by command lines within an exec_com read their input from the terminal. By preceding a command line with an &attach statement, the command can be caused to read input lines from the text of the exec_com instead. Note that "&attach" must precede the line on which the input-reading command is invoked; otherwise, before the &attach statement is encountered, the command will already have asked to read a line from the terminal. An example of &attach usage is 3-332 AG92-06 exec_com (version 2) exec_com (version 2) &attach qedx r actions. table Sa &f3 \f w q &detach This example appends to the segment named actions. table a line consisting of the third through last ec_arg arguments to the exec_com. The &detach statement causes any later input-reading command to get its input from the terminal. While &attach is in effect, the &is_attached predicate expands to "true"; after &detach. it expands to "false". In general, the answer command should be used to answer questions asked by programs via the command_query_ subroutine. Placing the answers in the text using &attach, as in &attach read tape -debug 50065 yes no &detach relies on a spe.cific number of questions being asked, and is therefore prone to fail if. f or example. an error occurs while executing the command. Note that there is no inherent property of a line making it an input line rather than a command line; the distinction is a property of whether input lines are being read by a command. Use of the answer command makes this example less error-prone: answer 50065 -then yes -then no read_.tape -debug 3-333 AG92-06 exec_com (version 2) exec_com (version 2) EXAMPLES OF IF STATEMENTS The line-placement of &then and &else statements is left up to you. Some examples of their usage are &if EXPRESSION &then LINEl &else LINE2 &if EXPRESSION &then LINEl &else LINE2 etc. More examples: &if EXPRl &then &if EXPR2 &then LINEl &else LINE2 &else LINE3 &if EXPRl &then &if EXPR2 &then LINEl &else LINE2 &else LINE3 &if EXPRl &then LINEl &else &if EXPR2 &then LINEl &else LINE2 &eise LiNE3 &if EXPRl &then &do LINEl &if EXPR2 &then LINE2 &else &do LINE3 LINE4 &end &end LIST OF CONSTRUCTS This alphabetical list of exec_com constructs names the sections in which they are documented: &" ... " && &(1), &(11), etc. &(VAR_NAME) & [ ... ] &+ &&! List of literals List of literals List of parameters List of value expressions List of value expressions Notes on continuation Notes on comments List of literals 3-334 AG92-06 exec_com (version 2) exec_com (version 2) &1. &2. etc. &. &BS, &FF, &HT, &&NL, &QT, &SP. &VT &all &attach &both &command &comment &control &default &detach &do &ec_dir &ec_name &ec_path &ec_switch &else &end &expanded &fl, &f(l), etc. &goto &if &input &is_absin &is_active_function, &is_af &is_attached &is_defined &is_input_line &label &n &print &print_nnl &ql, &q(l). etc. &quit &rl. &r(1), etc. &ready &ready_proc &return &set &then &trace &undefined, &undef &unexpanded &version List of parameters List List List List List List List List List List List List List List List List List List List List List List List of of of of of of of of of of of of of of of of of of of of of of of literals tracing statements (&trace) control statements tracing statements (&trace) tracing statements (&trace) tracing statements (&trace) tracing statements (&trace) assignment statements control statements control statements (&if) parameters parameters parameters parameters control statements control statements (&if) tracing statements (&trace) parameters control statements control statements tracing statements (&trace) predicates predicates List of pre-dicates List of predicates List of predicates List of control statements List of parameters List of printing statements List of printing statements List of parameters List of control statements List of parameters List of tracing statements List of tracing statements List of control statements List of assignment statements List of control statements (&if) List of tracing statements List of assignment statements (&default) List of tracing statements (&trace) Notes on version 3-335 AG92-()6 exec_com (version exec_com (version 1) Name: 1) exec_com, ec (version 1) SYNTAX AS A COMMAND ec path {optional_args} FUNCTION executes a sequence of command lines contained in a segment. It allows you to construct command sequences that are invoked frequently without retyping the commands each time. In addition, you can use control strings to substitute argument values into the executed text, manage I/O switches. and execute portions of the text condi tionally. This section describes Version 1 exec_com, which has effectively been replaced by Version 2. The first line of a Version 1 exec_com can optionally be "&version 1"; 1 is currently the assumed version. ARGUMENTS path is the pathname of a segment containing commands to be executed and control statements to be interpreted. The entryname of the segment must have the ec suffix, although you can omit the suffix in the command invOCation. If you supply an entryname only, i.e., one containing no < or > characters, the exec_com search list is used to locate the segment (See "Notes on Search List" below.) optional_args are character strings to be substituted for special strings in the exec_com segment (see "Notes on Argument Substitution.") CONTROL ARGUMENTS -no_trace KEYWORD_LIST turns off tracing of specified types of exec_com lines, overriding any &trace statements in the exec_com for those types of lines. KEYWORD_LIST is composed of any of the keywords "all_types", "command", "comment", "control", and "input", separated by commas with no intervening space. -trace KEYWORD_LIST turns on tracing of specified types of exec_com lines, overriding any &trace statements in the exec_com for those types of lines. KEYWORD_LIST is composed of any of the following, separated by commas, with no intervening space: 3-336 AG92-06 exec_com (version 1) exec_com (version 1) all_types, command, comment, control, input turns on tracing for the corresponding type of line(s). unexpanded. expanded, all_expansions or all, both affects how the expansion of lines is traced. These are equivalent to &unexpanded, &expanded, &all_expansions or &all, and &both in &trace statements inside the exec_com. prefix=STR specifies a prefix for traced lines, equivalent to &prefix in &trace statements. osw=SWITCHNAME specifies an I/O switch on which to write the trace, equivalent to &osw in &trace statements. -trace_default uses &command_line, &comment_line, &control_line, and &input_line statements in the exec_com and the default tracing modes to determine what and how to trace. (Default) NOTES ON INPUT SEGMENT The exec_com segment statements. Normally it exec_com command in for command sequences should contain only command lines. input lines, and control is created using a text editor, such as qedx. You can use the conjunction with the abbrev command to form abbreviations that are used frequently. Vlhen the ampersand character (&) appears in the exec_com segment, it is interpreted as a special character: it denotes a string used for argument substitution and to signify . the start of a control statement NOTES ON ARGUMENT SUBSTITUTION Strings of the form &i in the exec_com segment are interpreted as dummy arguments and are replaced by the corresponding arguments to the exec_com command; for instance, optionai_argl is substituted for the string &i and optional_arglO is substituted for &10. The strings &qi, &ri, &fi, &qfi, and &rfi also indicate argument substitution. The string &qi is replaced by the i'th argument to the exec_com command with quotes dOUbled. The string &ri is replaced by the i'th argument, requoted. Refer to do in this manual for a description of quote doubling and requoting and for examples of the use of &qi, &ri, &fi, &qfi, and &rfi. The string &fi is replaced by a string of the i'th through last arguments to exec_com, separated by blanks. Likewise, &qfi is replaced by a string of the i'th through last arguments with quotes doubled and &rfi is replaced by a string of the i'th through last arguments, requoted. 3-337 AG92-()6 exec_com (version 1) exec_com (version 1) The string &n is replaced by the number of arguments to the exec_com command. The string &f&n, therefore, is replaced by the last argument to exec_com. The string &ec_name is replaced by the entryname portion of the exec_com pathname without the ec suffix. The string &ec_dir is replaced by the directory name portion of the exec_com pathname. The string &ec_switch expands to the name of the I/O switch through which the exec_com is being read. Argument substitution can take place in, .command lines, input lines or in control statements. since the replacement of arguments is done before the check for a control statement. LIST OF PREDICATES The following predicates expand to true or false: &is_active_function. &is_af expands to "true" if exec_com was invoked as an active function. &is_absin expands to "true" if the current exec_com is running as an absentee. &is_attached expands to "true" if &attach is currently in effect. &is_input_line expands to "true" if some program is currently reading input lines under &attach, "false" if lines are interpreted as command lines. LIST OF CONTROL STATEMENTS Control statements permit more variety and control in the execution of the command sequences. Currently the control statements are: &label, &goto, &attach. &detach, &input_line, &command_line, &ready, &print, &quit, &if, &then, and &else. Control statements generally must start at the beginning of a line with no blanks. Two exceptions to this rule are the &then statement, which can follow clause, and the &else statement, which can follow a &then clause. Any statement other than &label, &if, &then, and &else is allowed to follow the words &then and &else. leading an &if control control &label and &goto These statements permit the transfer of control within an exec_com segment &label LOCATION identifies the place to which a goto control statement transfers control. The LOCATION is any string of 32 or fewer characters, unique within the exec_com segment 3-338 AG92-06 exec_com (version 1) exec_com (version 1) &goto LOCATION causes control to be transferred to the place in the exec_com segment specified by the label LOCATION. Execution then continues at the line immediately following the label. &attach, &detach, and &input_line &attach causes the user_input I/O switch to be attached to the exec_com segment. This means that if this control statement is executed, all input read by subsequent commands is taken from the segment rather than from the previous source of data to which the user_input I/O switch was attached. &detach causes the user_input I/O switch to be reverted to its original value. By default, the user_input I/O switch is left attached to its original source. &input_line on causes input lines returned when using the attach feature to be written on the user_output I/O switch. This is the default. &input_line off causes input lines to not be written out. Tracing, &ready, and &print These statements allow the control of the user_output I/O switch. They are useful as tools in observing the progress of the exec_com execution and in printing messages. &command_line on {osw SWITCHNAME} &command_line off {osw SWITCHNAME} causes· subsequent command lines to be written on the user_output I/O switch or on another specified SWITCHNAME before they are executed. The "off" usage causes subsequent command lines to not be written out. &comment_line on {osw SWITCHNAME} &comment_line off {osw SWITCHNAME} controls tracing of comment lines, lines beginning with "&" SWITCHNAME is specified is user_output The default if no &control line on {osw SWITCHNAME} &control-line off {osw SWITCHNAME} controls tracing of &if, &goto and all other exec com control statements. The default if no SWITCHNAME is specified is user_output &input_line on {osw SWITCHNAME} &input_line off {osw SWITCHNAME} controls tracing of lines read as input lines under &attach. The default if no SWITCHNAME is specified is user_output. 3-339 AG92-06 exec_com (version 1) exec_com (version 1) &ready on &ready off causes your ready procedure to print a ready message whenever it is invoked after the execution of a command line. The "off" usage causes your ready procedure not to print ready messages. &ready_proc on &ready_proc off controls whether your ready procedure is called after each command line. default is "on". This mode is completely independent of "&ready". The &print char_string causes the character string following &print to be written out on the user_output I/O switch. The character 1\ is treated as a special character in a print statement The following is a list of strings that can appear and the characters that replace them: AI or ANI AI or ANI A_ or AN- newline character form feed (new page) horizontal tab A where N expresses the number of special characters to be written out No other characters should appear following the 1\ character in the print statement &quit This statement causes the current invocation of exec_com to return to its caller and not to execute subsequent command lines. If exec_com has been invoked as an active function, the return value is the null string. &return rest of line Equivalent to &quit but returns a value. If exec_com was invoked as an active function. the rest of the &return line is returned as the value. Otherwise, the rest of the line is printed before quitting. &if, &then, and &else These statements provide the ability to have command lines, input lines, and control statements interpreted conditionally. The format of these control statements is &if [ACfIVE_FUNCfION {argl} ... {argn}] &then THEN_CLAUSE &else ELSE_CLAUSE The active function reference in an &if control statement is evaluated. If the value of the active function is the string true, THEN_CLAUSE is executed. If the value is false, ELSE_CLAUSE is executed. 3-340 AG92-06 exec_com (version 1) exec_com (version 1) &if [ACTIVE_FUNCfION {argl} ... {argn}] The active function is any active function (user-provided or system-supplied) that returns as its value a string with the value true or false. The arguments to the active function can themselves be active functions. (Nesting of active functions is permitted.) The active function and its optional arguments, enclosed in brackets, must be on the same line as the &if string. An &if must begin a line or immediately follow &then or &else, as in the example: &if [equal &1 tape] &then &if [equal &2 hdr] • &then THEN_CLAUSE This statement must immediately follow the &if statement; it can appear on the same line or on the following line. THEN_CLAUSE is an exec_com statement, and can include a command line, an input line, the null statement and most control statements. The &label, &then, and &else control statements are not allowed. THEN_CLAUSE must be on the same line as &then. &else ELSE_CLAUSE This statement is optional. When it appears, it must immediately follow the &then statement; it can appear on the same line or on the following line. ELSE_CLAUSE is an exec_com statement and can include a command line, an input line, the null statement and most control statements. The &label, &then and &else control statements are not allowed. ELSE_CLA USE must be on the same line. as &else. NOTES ON SEARCH LIST The exec_com command uses the exec_com search list that has the synonym ec. Type: psp ec to see what the current exec_com search list is. The default exeC_com search list is the working directory. For more information on the search facility, see the description of the add_search_paths command in this manual. NOTES ON HANDLING CONDITIONS The on command and active function can be used to handle conditions raised during the execution of an exec_com. To handle command_error when executing the copy command. for example, an exec_com can say: &if [on command_error 1111 -bf copy PROJ_DIR>&l MY_DIR>=] &then &goto copy failed an MY_DIR>&l &l.[date] &label copy_failed &print PROJ_DIR>&l not copied 3-341 AG92-o6 exec_com (version 1) exec_com (version 1) The -bf control argument suppresses a message printed by on when the condition is raised. The discard_output command can be used to suppress output from the command whose success is being tested, for example: &if [on command_error 1111 -bf dco.-osw error_output -osw user_output archive tb source &l.pll] &then &goto no_component &print &l.pll in source.archive &label no_component &print &l.pll not found in source.archive The on command can be used to execute another exec_com, or a recursive entry point in the current one, with a handler in effect. For example: on any_other "ee handler ll ec test_ms &quit &label handler tmr mail mbsa mailbox_ in >sss>ma i 1 &quit &label test_ms tmr mail mbsa mailbox_ in MS>mailbox_ MS>mbsa test.mbx adros MS>mail test &quit For more information, see the description of the on command. NOTES ON HANDLING QUESTIONS The answer command can be used commands invoked in an exec_com. on successive lines of the exec_com only the first three sections of an "no": to supply preset answers to questions asked by (It is not recommended that answers be supplied with &attach on.) The following exec_com prints info segment by answering "yes" twice and then answer yes -times 2 -then no help &1 &quit The following example prints the first three sections of an info segment, then prints the next three only if your answer yes: 3-342 AG92-D6 exec_com (version 1) exec_com (version 1) answer yes -times 2 -then -query -then yes -times 2 -then no help &1 &quit For more information, see the description of the answer command in this manual. NOTES If a line begins with the & character but is not one of the current control statements, the entire line is ignored. This is one way of including comments in the exec_com segment. You are cautioned to leave a blank immediately following the & to ensure compatibility with control requests to be added to exec_com in the future. The' segment executed by exec_com can contain calls to exec_com. You must exercise caution when invoking this feature in conjunction with the &attach feature. wl1en exec_com is called from an exec_com using this feature, the input read by commands in the second exec_com is read from the first exec_com segment. Generally, if the &attach feature is used, all calls to exec_com should be preceded by &detach control statements. Several exec_corns can be combined into one segment, by using the dummy argument &ec_name together with the &label and &goto statements. If exec_corns are grouped together, the exec_com segment should have all the names (concatenated with an ec suffix) on its storage system entry that can replace &ec_name. EXAMPLES Assume that the segment a.ec in your working directory contains pll &1 -table -list dprint -delete &l.list &quit The command line exec com a foo causes the following commands to be executed: pll foo -table -list dprint -delete foo.list 3-343 AG92-()6 exec_com (version 1) exec_com (version 1) Assume that the segment b.ec in your working directory has an additional name a.ec and contains &goto &ec_name & &label b pr i nt & 1 1 99 &quit & &label a pl1 &1 -table -list dprint -delete &l.list &quit The command line causes the following command to be executed: print my_file 1 99 The command line causes the following commands to be executed: pll foo ~table -list dprint -delete foo.list Assume that the segment d.ec in your working directory contains the following: &if [exists segment &lepl 1J &then &else &goto not_found pll &1 -table -list dprint -delete &1.1 ist &quit &label not found &print &l.pll not found &quit If the segment foo.pll exists, the command line causes the following commands to be executed: pl1 foo -table -list dprint -delete foo. list 3-344 AG92-06 exec_com, ec (version 1) exec_com, ec (version 1) If the segment foo.pll does not exist, the command line outputs the following: foo.pl1 not found Assume that the segment testec in your working directory contains &print begin &ec_name exec_com &command_line off create &l.pll &attach edm & 1 • p 11 i &1: proc; &i nput_l i ne off i end &1; w q &detach &goto &2 &label compile p 11 & 1 &label nocompile &print end &ec_name &1 &2 exec_com &quit The command line exec_com test x compile produces the following output: begin test exec com Edit. i x: proc; PL/I end test x compile exec_com 3-345 AG92-06 exec_com, ec (version 1) LIST OF CONSTRUCTS This is an alphabetical list of version 1 exec_com constructs: &is_active_function, &is_af &is_attached &is_input_Iine &label &print &quit &ready &ready_proc &return &then &attach &command_line &comment_line &control_line &detach &else &goto &if &input_Iine &is_absin Name: execute_string, exs SYNTAX AS A COMMAND exs {-control_args} {control_string {args}} SYNTAX AS AN ACTIVE FUNCTION [exs {-control_args} control_string {args}] FUNCTION substitutes arguments into a control string. The expanded control string is then passed to the command processor or the subsystem request processor for execution. As an active function or active request, evaluates the expanded control string as an active function. ARGUMENTS con tro1_string is a character string that can contain substitution constructs (see "List of Substitutions" below). args are zero or more character string arguments. Any argument supplied but not referenced by an argument substitution designator is ignored. 11/86 3-346 AG92-06A COlVTROL ARGUfv1ElVTS AS A COM/VIAND If you give control arguments with no control string, subsequent exs invocations in the process are affected; with a control string and. its arguments, subsequent exs invocations are not affected. Give the control arguments first. (See "Notes on modes" below.) -abort_line, -abl aborts the line containing the exs request if the request line is aborted during execution. Applies only to subsystem request invocations of exs. (Default) -brief, -bf does not print the expanded control string. (Default) -control_string, -cs permits a control string to look like a control argument. -go passes the expanded control string to the command processor or subsystem request processor. (Default) -inhibit_error, -ihe, -absentee establishes a handler for the any_other condition during the execution of the expanded command control string. -long, -lg prints the expanded control string on error_output before executing or returning it -no_abort_line, -nabl continues execution with the next request following the exs request on the same line if the request line exs invoked is aborted during execution. Applies only to subsystem request invocations of exs. -no_inhibit_error, -nihe, -interactive does not catch any signals. (Default) -nogo does not pass the expanded control string to the request processor. CONTROL ARGUMENTS AS AN ACTIVE FUNCTION -brief, -bf does not print the expanded active string. (Default) -control_string, -cs permits a control string to look like a control argument. 11/86 3-347 AG92-06A execute_string -error_value CONTROL_STRING, -erv CONTROL_STRING evaluates and returns the expanded control string if an error occurs, where CONTROL_STRING is a character string that can contain substitution constructs. In a subsystem active request, an error is anything that aborts the line; in an active function, anything that raises the active_function_error condition; in inhibit-error mode, any condition that -inhibit_error would handle as a command. (See "Notes on modes" below.) -inhibit_error, -ihe establishes a handler for the any_other condition during the execution of the expanded control string. Valid only if you give -erv. -long, -lg prints the expanded control string on error_output before it is evaluated. -no_inhibit_error, -nihe does not catch any signals. (Default) -no_rescan, -nrsc does not permit the command processor to rescan the result of the active function for white space, semicolons, parentheses, or brackets. This is equivalent to the II [... J evaluation, but the result is not .protected from reevaluation after exs returns the result, unless II [... J also encloses the exs invocation. (Default) -rescan. -rsc permits the command processor to rescan the result of the active function evaluation. -rescan_tokens, -rsct permits the command processor to rescan only the active function result for white space and quotes. This is similar to I [... J evaluation. in that it strips a level of quotes, but it concatenates the tokens back together without requoting, so that information may be lost. Use -no_rescan and place the I [... J around the execute_string invocation to retain this information. LIST OF SUBSTITUTIONS The following expansion designators appearing in the control string are replaced by their expansion value, as described below. Any other use of the ampersand (&) produces an error. &0, &1, ... &9 expands to the zeroth through ninth arguments. &0 is the control string, &1 is the first argument following the control string, and so on. If the corresponding argument is missing, the designator expands to a null string. &(0), &(1), ... expands to any argument, including arguments after the ninth. Use parenthesis when the argument number is two or more digits. If the corresponding argument is missing, the designator expands to a null string. 11/86 3-348 AG92-06A execute_string execute_string &qO•... &q9. &q(O), &q(1), ... expands to the corresponding argument following the control string. Quotes within the argument are doubled, according to the quote depth of the surrounding context within the control string (see "Notes on Quote Doubling" below). &rO, ... &r9, &r(O), &r(1) •... expands to the corresponding argument following the control string, enclosed in an added layer of quotes with internal quotes with the argument doubled accordingly (see "Notes on Requoting" below). This designator keeps the argument as a single unit after one layer of quote stripping by the command processor. &fl, ... &f9, &f(1) •... expands to the Nth through last arguments following the control string, with arguments separated by one space. If N is greater than &n, expands to a null string. &qfl, ... &qf9. &qf(1) •... expands to the Nth through last arguments following the control string, with quotes doubled within arguments, and arguments separated by one space. If N is greater than &n, expands to a null string. &rf1, ... &rf9, &rf(l), ... expands to the Nth through last arguments following the control string. with each argument individually requoted, and arguments separated by one space. If N is greater than &n, expands to a null string. &n expands to the number of arguments you give following the control string. &f &n, &qf &n, &rf &n expands to the last argument following the control string. with quotes doubled (&qf&n) or with requoting (&rf&n). &control_string expands to the control string (without expansions), with quotes dOUbled. equivalent to &qO. It is &! expands to a unique name. Each use of &! is replaced by a 15-character identifier. Every use within a single invocation is replaced by the same string. but the string is different for every invocation of exs. && expands to a single ampersand, to allow ampersands to be literally inserted into the expanded control string. NOTES This command is similar to the do command. The do command is an older interface that acts like exs as a command and like substitute_arguments as an active function. 11/86 3-349 AG92-06A When the control string is executed, abbreviations are expanded if the abbrev processor is enabled. Since the control string is usually enclosed in quotes, abbreviations in the control string are not expanded until control string expansion. (See the abbrev command.) NOTES ON MODES This command has f our modes: the long/brief mode, the nogo / go mode, the abort-line mode, and the inhibit-error mode. These modes are kept in internal static storage and are thus remembered from one invocation of exs to the next in a single process. Set the modes for the life of the process by invoking exs with control arguments and no control string; set the modes for a single invocation by giving control arguments, a control string, and its arguments. The abort-line mode applies only to subsystem request invocations of exs. You can set the mode at command level, but cannot set it for a single command invocation of exs. Use the inhibit-error mode mainly in an absentee environment, in which any condition that normally enters a new command level terminates the process. In this mode, any signal caught by exs terminates execution of the command line, not the process. The following conditions are not handled by exs, however, but are passed on to the command processor: command_error, command_query_error. command_question, program_interrupt, quit, and record_quota_overflow (see the Programmer's Reference Manual). The abort-line and go/nogo modes have no effect on active function and active request invocations of exs. The active fUi1ction is always evaluated, and execution of the containing command line cannot continue if there is no active function result. The inhibit-error mode is ignored for active function evaluation if you give no -erv. The modes of the exs command are separate' from the modes of the do and substitute_arguments commands, although they provide similar functions. NOTES ON QUOTE DOUBLING Each parameter designator to be expanded is found nested a certain level deep in quotes. If it is found to be outside quotes, its quote level is zero; if found between a single pair of quotes, its quote level is one; and so on. If an "&q" construct is found nested to quote-level L, then, as the argument is substituted into the expanded control string, each quote character found in the argument is replaced by 2**L quote characters during insertion. This permits the quote character to survive the quote-stripping action to which the command processor subsequently subjects the expanded control string. If the "&q" construct is not between quotes, or if the corresponding argument contains no quotes, quote doubling has no effect. 11/86 3-350 AG92-06A execute_string exists NOTES ON REQUOTING If an "&r" construct is found, the substituted argument is placed between an additional level of quotes before having its quotes doubled. For example, if &r1 is found nested to quote level L, 2**L quotes are inserted into the expanded control string; then, the first argument is substituted, with each of its quotes replaced by 2**(L+1) quotes; and, finally, 2**L more quotes are placed following it If you give no argument, nothing is placed in the expanded control string; so, you can distinguish between arguments that are not supplied and arguments that are supplied but are null. If you give an argument, the expansion of an "&r" construct is identical to the expansion of an "&q" construct surrounded by an extra level of quotes. Name: exists SYNTAX AS A COMMAND exists argument {str_args} exists key star_name{s} {-control_arg{s}} SYNTAX AS AN ACTIVE FUNCTION [exists argument {str args}] [exists key star_name{s} {-control_arg{s}}] FUNCTION checks for the existence of various types of items depending on the value of the first argument (key). ARGUMENTS argument is the key "argument" described below in "List of Keys." str_args are character string arguments. key is any key as described below in "List of Keys." star_name {s} are star names to be matched. You can give up to 20 names. 11/86 3-350.1 AG92-06A exists exists CONTROL ARGUMENTS -chase specifies that any keyword that looks for branch entries chase links and look at the link targets. When used. the link names are used for starname matching and the targets for type matching. * * -inhibit_error. -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase specifies that any keyword that looks for branch entries do not chase links. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) -select_entry_type STR, -slet STR selects entries of the types specified by STR. which is a comma-delimited list of file system entry types; for example. exists entry ** -slet ms.mbx. This control argument is recognized when the key is "entry." Use the list_en try_types command to obtain a list of valid entry type values. LIST OF KEYS argument true if you specify any str_args, false otherwise. branch true if any branches--segments. multisegment files (MSFs) pathname matching star_name exist. false otherwise. or directories--with a component true if any archive components with a pathname m~tching star_name exist, false otherwise. Both the archive segment name and the component name can be a star_name. directory, dir true if any directories with a pathname matching star_name exist, false otherwise. entry true if any entries--segments, directories, MSFs, links, data management (OM) files~ or extended entries--with a pathname matching star_name exist, false otherwise. file true if any segments or MSFs with a pathname matching star_name exist, false otherwise. 11/86 3-350.2 AG92-06A exists exists link true if any links with a pathname matching star_name exist, false otherwise. master_directory, mdir true if any master directories with a pathname matching star_name exist, false otherwise. msf true if any MSFs with a pathname matching star_name exist, false otherwise. non_null_link, nonnull_link. nnlink true if any links with a pathname matching star_name exist and point to an existing segment, directory, or MSF, false otherwise. nonbranch true if any links with a pathname matching star_name exist, false otherwise. nondir true if any segments, MSFs, or links with a pathname matching star_name exist, false otherwise. non file true if any links or directories with a pathname matching star_name exist, false otherwise. nonlink true if any directories, segments, or MSFs with a pathname matching star_name exist. false otherwise. nonmaster_directory, nmdir true if any directories that are not master directories with a pathname matching star_name exist. false otherwise. nonmsf true if any directories, segments, or links with a pathname matching star_name exist, false otherwise. nonobject_file, nobfile true if nonobject files with a pathname matching starname exist. false otherwise. Segments or MSFs you do not have at least r access to are ignored. nonobject_msf, nobmsf true if nonobject MSFs with a pathname matching starname exist, false otherwise. MSFs you do not have at least r access to are ignored. nonobject_segment. nobseg true if nonobject segments with a pathname matching star name exist. otherwise. Segments you do not have at least r access to are ignored. 11/86 3-350.3 false AG92-06A exists exists nonobject_segment. noseg true if no executable object segments with a pathname matching start_name exist, false otherwise. Segments you do not have at least r access to are ignored. nonsegment, nonseg true if any links, directories, or MSFs with a pathname matching star_name exist, false otherwise. nonzero_file, nzfile true if any nonzero-length segments or star_name exist, false otherwise. MSFs with a pathname matching nonzero_msf, nzmsf true if any nonzero-length MSFs with a pathname matching star_name exist, false otherwise. nonzero_segment, nzseg true if any nonzero-length segments with pathname matching star_name exist, false otherwise. null_link true if any links with a pathname matching star_name exist and point to nonexistent entries, false otherwise. object_file, obfile true if object files with a pathname matching starname exist, false otherwise. Segments or MSFs you do not have at least r access to are ignored. object_msf, obmsf true if object MSFs with a pathname matching starname exist, false otherwise. MSFs you do not have at least r access to are ignored. object_segment, obseg true if object segments with a pathname matching star_name exist, false otherwise. Segments you do not have at least r access to are ignored. segment, seg true if any segments with a pathname matching star_name exist, false otherwise. zero_segment, zseg true if any zero-length segments with a pathname matching star_name exist, false otherwise. 11/86 3-350.4 AG92-Q6A SYNTAX AS A COMMAND ecs oldpath {newpath} {-control_args} FUNCTION applies a transf ormation to a COBOL source program. The nature of the source transformation is defined by control arguments. If you give no control argument. a segment containing text of a standard format COBOL source program that possibly contains COpy and REPLACE statements is translated into an equivalent source program not containing these statements. ARGUMENTS oldpath is the pathname of the input segment If it does not have a suffix of .cobol. one is assumed. The suffix .cobol. however. must be the last component of the name of the source segment newpath is the pathname of the output segment If it does not have a suffix of .cobol. one is assumed. If you omit it. the translated segment is in the form of the first component with the suffix .ex.cobol. CONTROL ARGUMENTS -card deletes meaningless trailing blanks from a standard fixed-format COBOL source program in card-image format and ignores characters in the identification field (columns 73-80). -expand, -exp translates a standard fixed-format COBOL source program that possibly contains COPY and F-EPLACE statements into an equivalent sourc.e program not containing these statements. (Default) -format. -fmt translates a pseudofree-form COBOL source program into a standard fixed-format COBOL source program. All characters in the source program are left exactly as typed. -lower_case -lc translates a pseudofree-form COBOL source program into a standard fixed-format COBOL source program. All characters except for those in alphanumeric literals are converted to lowercase. 11/86 3-350.5 AG92-06A -no_expand, -no_exp does not translate COpy and REPLACE statements in a standard fixed-format COBOL source program. -upper_case, -uc translates a pseudofree-form COBOL source program into a standard fixed-format COBOL source program. All characters except for those in alphanumeric literals are converted to uppercase. NOTES You can use -fmt,. -lc, and -uc with -exp, but not with -card. Don't use them if the source program is already in standard fixed format The control argument -card causes a standard fixed-format COBOL source program in card image format to be translated into an equivalent standard fixed-format program. If a line is 80 characters long, the identification field is deleted before removing meaningless trailing blanks. You can use -card with -expo 11/86 3-350.6 AG92-06A If the -fmt, -lc, or -uc control arguments are used, the expand_cobol_source command assumes that the input file is in free form (as would be typically typed in from a terminal) and attempts to reformat each line into the standard COBOL reference format described in the Mu/tics COBOL User's Guide (AS43). Statements in a COBOL source program generally begin in area B (column 12 and beyond). However, certain entries must begin in area A (column 8 through 11). These are COBOL-defined division names, section names, paragraph names, level indicators, and certain level numbers, as well as user-defined section names and paragraph names. Additionally, certain characters have special meaning when appearing in the indicator area (column 7), such as the asterisk, slash, hyphen, and letter "d". The expand_cobol_source command recognizes all COBOL-defined names that are required to appear in area A and reformats lines containing them to guarantee that they do so. User-defined section names are recognized by the appearance of the word "section" on the line while words beginning the line and followed immediately by a period are assumed to be user-defined paragraph names. Source lines containing either of these are reformatted similarly to lines containing COBOL-defined sections and paragraphs. Lines beginning with level numbers 01, 66, 77, 88 are reformatted to begin in area A (at column 8) as required in standard American National Standard (ANS)' COBOL. Lines beginning with level numbers 02 through 49 are indented a number of spaces identical to the numeric value of the level number plus seven (e.g., 02 begins at column 9, 05 at column 12). Certain characters force special interpretation when they begin a free form source line. The slash (/) and asterisk (*) when used in this way denote a comment line with or without page eject, respectively; the hyphen (-) denotes a continuation line. Such lines are reformatted so that these special characters appear in the indicator area followed by the rest of the line. Additionally, for continuation lines, the remainder of the line following the hyphen is shifted to begin in area B as COBOL prohibits use of area A in this case. Debugging lines are probably of little interest for Multics COBOL users due to the powerful symbolic debugging facilities available on an interactive basis, but they can be specified in free form source by beginning the line with "d*". In rare instances, in which a user-defined section or paragraph name is specified in a way not contextually recognizable by the expand_cobol_source command. you can force reformatting beginning in area A by beginning the line with "a*" (or "da*" in the case of debugging lines). All other source lines (i.e.. those not beginning with special character(s) and not containing entries required to begin in area A) are reformatted by insertion of eleven blanks forcing commencement in area B. Any indentation already existing in the free form file is thereby maintained relative to column 12. The expand_cobol_source command also converts all horizontal tab characters (ASCII code 011) not contained in nonnumeric literals to spaces. The number of spaces is determined by subtracting the position of the tab character on the source line modulo 10 from 10. In this way, you can input the source program using the tab character as a formatting tool, yet avoid the fact that this is not part of the standard COBOL character set. 3-351 AG92-o6 explain~doc The COBOL source program output is acceptable to any ANS compiler with regard to reference format (Actually, Multics COBOL relaxes many of these format requirements. However, it is usually desirable to eliminate the warnings and observations issued when such ANS rules are violated.) For transportability purposes, the output file can be created entirely in uppercase or lowercase (with the contents of nonnumeric literals left as is) by use of the -upper_case and -lower_case control arguments. If neither is speciiied, the case of all words remains the same as in the input file. Notice, all COBOL-defined names and characters with special meaning are recognized regardless of case, i.e.. they can be all in uppercase. all in lowercase, or in mixed case. For those users wishing to keep source files in free form, identical function described above is available on a per use basis via the -format control argument of the cobol command. Refer to the description of the cobol command for further information. Name: explain_doc, edoc SYNTAX AS A COMMAND edoc manual_name {-control_args} FUNCTION returns information about a specified Multics manuaI(s). ARGUMENTS manual_name is the manual's name, a short name for the manual, or the manual's order number. The name or the short name can contain blank spaces; it need not be enclosed in quotation marks. Capitalizing letters is not necessary. Use iteration to get more than one manual (see "Examples" below). CONTROL ARGUMENTS -all, -a prints all the sections of manual information. -audience, -aud describes the audience for which the manual is intended. -database_pathname PATH. -dbpn PATH specifies the pathname of the data base you want instead of the default one. Once you supply -database_pathname. the specified data base is used for all subsequent invocations of explain_doc during your process until you select another data base. 3-352 AG92-06 -description. -dese returns a brief description of the manual's contents. (Default) -new_features, -nf lists all new features that have been added to the manual with the last update (revision or addendum). -no_aUdience. -no_aud does not describe the manual's intended audience. (Default) -no_description, -no_dese suppresses printing of the brief description of the manual's contents. -no_new_features, -no_nf does not list new features. (Default) -no_request_loop, -nrql does not enter the request loop. -no_table_of_contents, -no_toe does not print the manual's table of contents. (Default) -output_file PATH, -of PATH directs the output to a file instead of to your terminal. -request_loop, -rql enters a request loop after the sections specified by control arguments have been printed. (Default) -table_of_contents, -toe prints the manual's table of contents. NOTES When explain_doc cannot find a data base entry that matches the manual name supplied. it may, in some cases, find a partial match that enables it to identify that name as belonging to a particular group such as the FORTRAN manuals or the Administrator's manuals. In that case, the relevant set of manual names is listed, and you can then choose to see the information on one of those manuals or return to command level. NOTES ON REQUESTS When you have invoked explain_doc and the section has been displayed, you are prompted More information? 3-353 AG92-06 You can respond with one of the following requests: yes, y ? (lists available responses) description. desc audience, aud table_of_contents. toc new _f eatures, nf all, a no, n, quit, q (quits the request loop and returns you to command leveI). EXAMPLES edoc ag92 -audience Title: Mu1tics Commands and Active Functions Order No.: AG92-05A" Release Supported: MR10.2 Audience: Programmers and nonprogrammers who use Mu1tics commands and active functions. More information? r no 13:51 6.782 183 When using iteration, enclose names containing blank spaces within quotes; for instance, ! edoc MAM (i'registration and accounting!! system project) or ! edoc ("mu1tics commands" subroutines) 3-354 AG92-06 exponen t_control exponent_control Name: exponent_control SYNTAX AS A COMMAND exponent_control -control_args FUNCTION controls the behavior of the system in the event of a computational overflow or underflow. CONTROL ARGUMENTS -restart STRs, -rt STRs specifies that either overflow or underflow or both are to be automatically restarted with defined results. STRs can be either or both of the strings "overflow" or "underflow." -fault STRs, -flt STRs specifies that either overflow or underflow or both are to cause the normal fault conditions. -overflow_value STR. -ovfv STR specifies the value to be returned for an overflowing computation. If no value is given the largest possible floating point value is used. -print, -pr prints the current behavior with respect to exponent errors and the current overflow value. NOTES By default Multics signals fault conditions on computational overflows and underflows. See the Programmer's Reference Manual for more information on faults and other unusual c.onditions. This command only affects the system's handling of exponent overflow and underflow when the overflow condition or the underflow condition is raised. In certain cases, the error condition is raised instead. This command does not affect the system's handling of the cases in which the error condition is raised. 3-355 AG92-G6 exponent_control EXAMPLES To restart on underflows: exponent_control -restart underflow To signal a fault on overflows: exponent_control -fault overflow To restart on both underflows and overflows: exponent_control -restart underflow overflow Name: fast SYNTAX AS A COMMAND fast FUNCTION puts you into the FAST subsystem, a time-sharing facility designed primarily for creating and running BASIC and FORTRAN programs. NOTES For a description of the commands available under FAST, see the Multics FAST Subsystem User's Guide (AU25). To exit the subsystem and return to Multics system command level, type quit (q). Name: file_output, fo SYNTAX AS A COMMAND fo {path} {-control_args} FUNCTION directs I/O output switches to a specified file. The effects of this command can be stacked. 3-356 AG92-06 ARGUMENTS path is the pathname of a segment If the segment does not exist, it is created. If you give no path, the segment output_file in your working directory is assumed. CONTROL ARGUMENTS -extend extends the output file. (Default) -source_switch STR, -ssw STR specifies the name of an I/O switch to be redirected. (Default: user_output) -truncate. -tc truncates an existing output file for file_output (Default to extend the output file) NOTES Each command invocation of file_output stacks up another attachment for each of the specified switches. See the revert_output. syn_output, and terminal_output commands. EXAMPLES The command line fo text.cpa;cpa text.old text.new;ro;dp text.cpa makes a comparison of two text segments named text.old and text. new, places the results of that comparison in the output file named text cpa, and dprints the file text.cpa on a remote printer. This sequence of commands within an exec_com segment fo segs_and_links 1s -seg to 1s -directory ro ]5 ~lii"ik ro 11/86 3-357 AG92-06A files lists segments and links in the output file named segs_and_links and lists directories on the terminal. The sequence of lines within an exec_com segment &if &[equal &1 tape] &then io attach sl tape_mult_ &2; io open sl so &if &[equal &1 file] &then io attach sl vfile_ &2; io open sl so &if &[equai &1 tty] &then io attach sl syn_ user_i/o syn_output sl; so sl; ws -wd IIlist -all";ro &if &[not [equal &1 tty]] &then io close sl io detach sl outputs a listing of all segments in a subtree to a file, a tape, or the terminal as specified by the first exec_com argument Name: files SYNTAX AS A COMMAND files star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [files star_names {-control args}] FUNCTION returns the entrynames or absolute pathnames of segments and multisegment files (MSFs) that match one or more star names. ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. 11/86 3-358 AG92-o6A floor files -no_chase does not process the targets of links' when you specify a starname. (Default) -no_inhibit_errort -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per file is returned; i.e., if a file has more than one name that matches a star_name, only the first match found is returned. Since each entrynarne (or pathname) returned by files is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: floor SYNTAX AS A COMMAND floor num SYNTAX AS AN ACTIVE FUNCTION [floor num] FUNCTION returns the largest decimal integer less than t or equal tOt its argument EXAMPLES string [f loor 4.7] 4.0 -5.0 11/86 string [floor -4.7] 3-359 AG92-o6A Name: format_document, fdoc SYNTAX AS A COMMAND fdoc path {-control_args} FUNCTION formats text segments. ARGUMENTS path is the pathname of an input segment or multisegment file. The suffix "fdocin" must be the last component of the entryname; you need not supply fdocin in the command line. CONTROL ARGUMENTS -hyphenate {N}. -hph {N} changes the default hyphenation mode from off to on. N is the length of the smallest separated word part; its default value is 2. (Default: off) -indent {N}. -ind {N} indents the output N spaces from the left margin, in addition to any indention established by the indent control line within the text of the input file. -no_hyphenate. -nhph does not hyphenate words. (Default) -output_file {PATH}, -of {PATH} directs the output to a fHe instead of to your terminal. If you provide no PATH, then the output is written to an output file whose name is formed by replacing the suffix "fdocin" of the input file entry name with the suffix "fdocout". (Default: off) -page_numbers. -pgno ends each page with two blank lines and a centered· page number. (Default: off) LIST OF CONTROL LINES The following is a summary of the control lines recognized by the command: .alb (align both) inserts extra spaces into each line so that both the left and the right margins are even. This control line is effective only if fill (.fin) is also in effect. (Default) • a 11 (align left) does not insert extra spaces into the lines. The left margin is even. the right ragged. This control line is effective only if fill tfin) is also in effect. 3-360 AG92-06 format_document .brf (break format) finishes the current output line by formatting any pending texts as a short line. • brf (break page) finishes the current page, formatting any pending texts as a short line. • fif (fill off) retains lines in the output file as they are in the input file no matter the length. • fin (fill on) restructures the input file lines to the current line length for the output file by taking a word or words from the next line in order to fill the line as close as possible to the current line length. If a line in the input file is longer than the current line length, move a word or words to the next line, etc. (See .alb and .all above.) (Default) .hy hyphenates according to the default. .hyf sets the hyphenation to off. (Default) .hyn {N} sets hyphenation to on. (Default: 2) • _ • I ru'l n loNJ t • • _, ru'l I loNJ n I (indent, indent left margin) sets the indention level. If you give N a + or -. then N is added to or subtracted from the current indention level; without a sign, N becomes the indention level. An error message is displayed if an indention level is less than zero (default) or greater than the line length. • pdl {N} (page length) sets the page length. If you give N a + or - sign, then N is added to or subtracted from the current page length; without a sign, the page length is changed to N. The command inserts blank lines at the top and bottom of each page, so be careful not to set the page length to a value less than 13 (or less than 14 if you are having page numbers printed); if less than 13 or 14, an error message is displayed. (Default: 66) (space format) finishes the current output line and then adds N blank lines. (Default: 1) • pdw {N} (page width) sets the page width (line length). If you give N a + or - sign, then N is added to or subtracted from the current line length; without a sign, the line length is changed to N. An error message is displayed if the set line length does not accommodate the input file. (Default: 65) 3-361 AG92-D6 format_document • un {N}, format_document • un 1 {N} (undent. undent left margin) sets the indention level for the output of the next line only. If you give N a + sign or no sign. then indent N characters less than the current indention level; if you give N a -, then indent N characters more than the current indention level. An error message is displayed if the indention that is caused by undenting is less than zero or more than the line length. NOTES This command takes an input file that you have created using a text editor. formats that file. and either displays it on your terminal or writes it to a new file with a unique name. To direct format_document to perform certain actions. place special control lines in the input file. All control lines begin with a period and must be on a line by themselves. This command makes two assumptions about how the document is to be formatted: it assumes that the output is to be on standard-sized paper with 66 lines per page and lines 65 characters wide (these values represent an 8 1/2 by 11 inch page with one-inch margins all around) and that both the left and right margins are justified. / Output lines are built by the embedded control lines within the input file being formatted; these input control lines do not appear in the output. EXAMPLES The following page shows an example of a business letter created using format_document Suppose the letter is to be printed on a standard 8-1/2 by 11 inch piece of paper with lines 60 characters long. The input file is first created with a text editor. In this example the input file is labeled letter.fdocin. Line numbers are shown on the example to reference comments below. 3-362 AG92-06 format_document format_document 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 36 37 38 39 40 41 42 .pdw 60 •f i f . in 35 9341 Millennium Lane Reston, Virginia 22061 November 24, 1982 . in Zimmerman Widget Company 53698 Dixie Highway Drayton Plains, Michigan 48999 Dear Sir, .fin .un-5 I recently purchased one of your model GX-721 widgets. i feel that your engineering staff deserves high praise for this new model. It is apparent that a great deal of thought has gone into its design. I am particularly pleased with the optional cone top replacement mechanism. .un =5 My purpose in writing this letter, however, is to obtain information. As you are well aware, the filter requires a complete overhaul after each 250 hours of use. The service brochure indicates that the nearest service center to my location is in Chapel Hill, North Carolina, which is a six-hour drive from my residence= If you can direct me to a service center that is more convenient to my location, , would be very grateful. .f i f . in 35 Sincerely yours, 43 44 45 46 47 Michael P. Marley Line 1 sets the line length (page width) to 60 characters. 3-363 AG92-06 format~document Line 2 turns fill mode off so that the lines will appear just the way they are input. If fill mode was not turned off then the address would be reformatted by fdoc, words might be moved from line to line, or extra spaces might be filled in. The same thing is done at line 40 just prior to the closing. Line 3 sets the indention to character position 35 so that the return address be on the right-hand side of the letter starting at character position 35. Lines 4-6 is the return address. Lines 7-9 are three blank lines inserted by pressing the newline (NL) or carriage return (CR) key three times. Line 10 resets the indention level to 0 (the absence of a number after the control gives the default). Lines 11-17 are the address of the recipient, two blank lines, the salutation, and another blank line. Line 18 turns fill mode on. Line 19: the indention level is set to 0 by the control in line 10, but you want to indent the next line by only five characters since it begins a paragraph. To change the indention for only one line you use the undent control, which works in the opposite direction of the indent control: undent subtracts the number from the indention (Le., if you used .un 5 it would move the indention 5 spaces to the left). You want to move 5 spaces to the right to indent the paragraph, so you use a negative number. Lines 20-37 is the body of the letter. No attempt to control the entered line lengths has been made (free form). The fdoc command formats all the data f or you, so long as fill mode is on. Lines can be as short or as long (wrap-around) as you wish. Line 40 turns fill mode off. Line 41 sets the indention to character position 35 so that the letter closing, signature, and sender's name appear on the right side of the page (lines 42-47). Now that your input file (Ietter.fdocin) is ready you can have it formatted and printed on the terminal for your perusal: 3-364 AG92-06 . format_document fdoc letter.fdocin 9341 Millennium Lane Reston, Virginia 22061 November 24, 1981 Zimmerman Widget Company 53698 Dixie Highway Drayton Plains, Michigan 48999 Dear Sir, recently purchased one of your model GX-72l widgets. feel that your engineering staff deserves high praise for this new model. It is apparent that a great deal of thought has gone into it~ design. I am particularly pleased with the optional conetop replacement mechanism. My purpose in writing this letter, however, is to obtain information. As you are well aware, the filter requires a complete overhaul after each 250 hours of use. The service brochure indicates that the nearest service center to my location is in Chapel Hill, North Carolina, which is a six-hour drive from my residence. If you can direct me to a service center that is more convenient to my location, I would be very grateful. Sincerely yours, Michael P. Marley r 1154 o. 149 25 To make a final copy of the letter, you must first center it on the paper. Most terminals and printers print a standard 8-1/2 by 11 inch piece of paper with 85 characters on a line, which means that the lines are 25 characters shorter than the width of the paper, so if each line begins at character position 12 (roughly half of 25) the letter will be centered on the page. The command line 3-365 AG92-06 format_document fdoc letter -indent 12 accomplishes this. If the letter is to be saved in a file so that it can be printed on another terminal or on a high-speed printer, use -output_file: fdoc letter -indent 12 -of In this example, the file is named letter.fdocout If you have a high-quality printing terminal that you wish to use to print this letter on a piece of typing paper, you would type: print letter.fdocout -stop After entering this command, place the typing paper in the terminal, posItIon it so that printing begins at the top, and then enter a carriage return (newline character). The letter is then printed, stopping at the last line. At this point, you can remove the paper and put in a new sheet (if the letter is more than one page). When the letter has been printed you can enter another carriage return and you are returned to Multics command level. Name: format_line, fl SYNTAX AS A COMMAND fl control_string {args} SYNTAX AS AN ACTIVE FUNCTION [fl control_string {args}] FUNCTION returns a single, quoted character string that is formatted from an ioa_ control string and other optional arguments. 3-366 AG92-06 ARGUMENTS control_string is an ioa_ control string used to format the return value of the active function (see "Notes" below). args are character strings substituted in the formatted return value according to the control string. NOTES The following ioa_ control codes are allowed (see the ioa_ subroutine). The control string is output exactly as is except that certain constructs beginning with a caret (A) are expanded, which may involve argument substitution or interpretation. Unimplemented constructs are output as is, but avoid them to allow for future extensions. CONTROL ACCEPTABLE ARGUMENTS Aa Ad ANa ANd Ai Af A.Of Ae ANi ANf AN.Of ANe ANo any character string a character representation of a number, including optional exponent (315.44 or .2789e+2 or 1101b) same as Ad same as Ad same as Ad same as Ad same as Ad "true", "false", or an integer character string any number of any character string AO A [ ••• A ••• A] A( ••• A) or AN ( ••• A) AS an integer character string. ANs In addition, you can use any of the following carriage movement controls: ANI ANx AS AN.Dt ANAR ANt AI AI AX AA where N is an integer count or a "v". When you give "v", an integer character string f rom the args is used for count If you don't give optional arguments, the value returned depends on the ioa_ control string that you specified. 3-367 AG92-{)6 EXAMPLES In an exec_com segment, the lines &if [query [fl IIAa copies already exist.A/Build another?lI] &2] &then ec build_new_data [plus 1 &2] might be expanded when &2 is 3 to 3 copies already exist. Build another? The lines string [fl "Insurance option: [query "No Fault?"]] A[no fault A;regular"']" print the following if you answer "no" to the query Insurance option: regular SYNTAX AS A COMMAND flnnl control_string {args} SYNTAX AS AN ACTIVE FUNCTION [flnnl control_string {args}] FUNCTION is the command/active function interface to the ioa_$nnl subroutine. When used as a command, the formatted string is printed without a trailing newline. ARGUMENTS con trol_string is an ioa_ control string used to format the return value of the active function. args are character strings substituted in the formatted return value according to the control string. 3-368 AG92-06 NOTES The following ioa control codes are allowed (see the ioa_ subroutine). The control string is output exactly as is except that certain constructs beginning with a caret (") are expanded, which may involve argument substitution or interpretation. Unimplemented constructs are output as is, but avoid them to allow for future extensions. CONTROL ACCEPTABLE ARGUMENTS Ai ANi Af ANf A.Of AN~Df Ae ANe AO ANo any character string a character representation of a number, including optional exponent (315.44 or .278ge+2 or 1101b) same as "d same as "d same as "d same as "d same as "d "true", "false", or an integer character string any number of any character string A [ ••• A ••• A] A( ••• A) or AN ( ••• A) AS ANs an integer character string. In addition, you can use any of the followipg carriage movement controls: ANI ANx AB AN.Dt ANI ANA "'t AI AX ANAR ANt AI AA where N is an integer count or a "v". When you give "v", an integer character string from the args is used for count. If you don't give optional arguments, the value returned depends on the ioa_ control string that you specified. 3-369 AG92--D6 Name: format_pll, fp SYNTAX AS A COMMAND FUNCTION formats a PL/I. create_data_segment. reductions. or pH_macro source segment to make it more readable. ARGUMENTS in_path is the pathname of the source segment. Suffixes for PL/I. create_data_segment, reductions. and pH_macro are recognized. If in_path does not have a recognized suffix. format_pH attempts to use in_path. pH or in_path. cds, in that order. CONTROL ARGUMENTS -brief, -bf does not print a warning if the prevailing style differs from the command line modes. -check_comments, -ckcom prints a warning if a comment contains "/*". It is useful if you have omitted a "* I" from a comment. -check_strings, -ckstr prin ts a warning if a character string constant contains " 1*". "* /". or vertical white space. It is useful after receiving an error message indicating that you have omitted a quote from a character string constant -force. -fc forms the prevailing style by concatenating the default style, the prevailing style control comment modes, and the command line modes. If the program already has a prevailing style control comment and the prevailing style differs from the prevailing style control comment modes, the prevailing style control comment is deleted. If you provide -record_style, a new prevailing style control comment is inserted. -long, -lg prints a warning indicating the modes that differ if the prevailing style differs from the command line modes. (Default) -modes STR, -mode STR. -md STR specifies a modes string STR used in forming the prevailing style (see "Notes on Prevailing Style" below). 3-370 AG92-()6 -no_cheek_comments. -nckcom does not print a warning if a comment contains "/*". (Default) -no_cheek_strings, -ncatr does not print a warning if a character string constant contains "/*", "*/", or vertical white space. (Default) -no_force, -nfc forms the prevailing style by concatenating the default style. the command line modes. and the prevailing style control comment modes. (Default) -no_record_style, -nrcst does not put a control comment in the source specifying the prevailing style. (Default) -no_require_stYle_comment. -nrqst formats the source even if it does not already contain a prevailing style control comment (Default) -no_version. -nver does not print the version of format_pH. (Default) =output_file path. -of path specifies the pathname of the formatted source segment The equal convention is allowed. The suffix of in_path is assumed if not specified. If omitted and there were no errors. in_path is overwritten; if omitted and there were errors. a formatted copy is left in the process directory. -record_style, -rest puts a control comment in the source specifying the prevailing style if the source does not already have a prevailing style control comment The comment is placed immediately before the first token of the program so it does not interfere with copyright notices. -require_style_comment, -rqst prints an error message if the source does not already contain a prevailing style control comment This is useful if you are concerned with accidentally destroying the style of a hand-formatted program. -version, -ver prints the version of format_pH. NOTES Alternate methods of formatting particular language constructs are seleeted by means of modes. Several popular styles. consisting of groups of modes, are defined. Modes and styles are specified on the command line and in comments in the source segment An exee_com tool called compare_pH compares PL/I source segments of dissimilar formats via f ormat_pll. 3-371 AG92-06 If you give two opposing control arguments, the rightmost one is chosen. The term "token" excludes comments. See the Multics PL/I Language Specification (AG94) for definitions of words describing syntactic constructs in a PL/I program, e.g., independent statement, declaration list, etc. Condition and label prefixes are not considered part of a statement NOTES ON MODES STRING A modes string changes the style format_pll uses to format a program. It consists of mode names separated by commas. Many modes can be preceded by 1\ to turn the specified mode off. The modes string is processed from left to right; thus, if two or more contradictory modes appear within the same modes string. the rightmost mode prevails. Modes not specified by the modes string are left unchanged. NOTES ON CONTROL COMMENTS A control comment has the form "1* format: STR *1", where STR is a modes string. The control comment can start with one of the other comment indicators listed in "List of Comment Indicators" below. Control comments can occur only before the first token of the program. between a semicolon and the first token of the next statement, or after the last semicolon in the program. Control comments cannot occur in the middle of a statement. Optional horizontal white space can precede "format" or surround STR. Some modes changed by a control comment may not take effect immediately; for example, end statements are formatted according to the modes in effect when the matching do, begin, or procedure statement was formatted. There are two special control comments that are used in if statements. If a comment containing "1* case *I" or "1* tree *In immediately follows the word "if" in an if statement. then the current style is changed for the duration of that if statement; exactly one space must precede and f oHow "case" and "tree". (See case and tree modes in the "List of if Statement Modes" below.) NOTES ON PREVAILING STYLE The style in which format_pll formats a PL/I program is formed from a combination of three sources: format_pU's default style, modes specified on the command line, and control comments in the program. The first control comment of the program preceding the first token of the program is called the prevailing style control comment. A program might not have a prevailing style control comment The style specified by the concatenation of the default style, the command line modes, and the prevailing style control comment modes is called the prevailing style. This is the style in which most of the program is formatted. Since a styleN mode specifies the setting of every mode, if the prevailing style control comment contains a styleN mode, the default format_pll style and the command line modes are ignored. If the program doesn't already have a prevailing style control comment, the command line 3-372 AG92-()6 formats a program in MY_STYLE and records the style in a prevailing style control comment If the program has a prevailing style control comment, the program is formatted in the style specified by its prevailing style control comment and -record_style has no effect The prevailing style control comment created as a result of -record_style always begins with a styleN mode. NOTES ON EXAMPLES The examples show how various program fragments are formatted. If you give no control comment, then style! (default), is assumed; if you give a control comment, the default is used for all unspecified modes. Unless you use delnl,insnl mode, each line of the input source segment contains the same tokens as the corresponding line of the example. If you use delnl,insnl mode, then newline characters are inserted and deleted as required by the style. (See "Notes on Styles" below.) LIST OF MODES Modes for various language constructs are listed separately. styleN specifies formatting style N. revert changes the formatting style to the prevailing style. You can't supply this mode in -modes or in the prevailing style control comment Note that the on mode is changed to the phase specified in the prevailing style. off, "'on leaves the source exactly as it is until a control comment changes the style to on. In this mode, block and group entries and exits are noticed so the program following the on mode control comment is formatted correctly. on, "'off starts formatting the source again. (Default) indN N is the number of columns to indent for each block or group indentation level. An independent statement in a then or else clause that does not have a condition or label prefix is indented a minimum of five columns when not in if then mode even if indN is less than five. This avoids placing the then or else clause on the line after the "then" or "else". The five columns are measured from the column the "else" would start in if the else clause was an indeoendent statement (Default: 5) £ 3-373 AG92-Q6 Example: /* format: ind3 */ if v = 2 then do; x = 12; y = 128; end; else z = 12; llN N is the output line length. (Default: 122) lineconindN N is the number of columns to indent the continuation of lines that exceed the output line length. (Default: 5) equa 1 i ndN if N is greater than zero, places the equal sign of assignment statements in a column indented N columns from the left margin. If in insnl mode, a new line is inserted if necessary to insure that the equal sign is indented the specified column positions. If N is zero, then assignment statements are formatted just as ordinary statements. (Default: 0) Example: /* format: style2,equalind8 */ a index = 12; = 1; second index = 43; initcolN N is the initial column that statements occurring before the first procedure statement should start at This is useful for include files. (Default: 6) NOTES ON DECLARE STATEMENTS Depending upon delnl and insnl modes, each level one identifier that is declared is placed on a Hne by itseif. In indattr mode, all attributes are indented to· the same column. If a declaration list (parenthesized list) has all the attributes factored (i.e., each declaration component- in the declaration list consists only of an identifier) and doesn't contain any comments and none of the identifiers contain a $, then the declaration list is placed on as few lines as possible instead of placing each identifier on a separate line. Examp 1e: de 1 (hbound, index, nu 11) bu i 1tin; LIST OF DECLARE STATEMENT MODES indattr always indents the attributes so they start in the same column. (Default) 3-374 AG92-06 "'indattr doesn't indent the attributes from the identifier being declared. inddels indents declare statements so they start in the same column any other statement would start in. (Default) "inddels always starts declare statements in column 1. deelareindN indents N columns after the start of dcl. (Default: 8) de 1 i ndN indents N columns after the start of dcl. (Default: 8) idindN indents N columns after the start of an identifier before starting the attributes. Ignored if in I\indattr mode. (Default: 23) struelvl indN indents N columns for each level in a structure. (Default: 2) LIST OF IF STATEMENT MODES ifthenstmt outs the then clause on the same line as the "if", if it fits. These criteria must be met: (1) the then clause must be an independent statement and cannot be another if statement; (2) the then clause must not have a condition or label prefix; (3) if in tree mode, the if statement must not have an else clause; (4) if in case mode, the if statement must fall into one of the following categories: (a) there is no else clause, (b) the else clause consists of an if statement, or (c) the if statement under consideration is an else clause of another if statement. Example: 1* format: iftnenstmt *1 if x > 3 then return; "'ifthenstmt doesn't put the then clause on the same line as the "if". (Default) Example: if x > 3 then return; ifthendo puts the "then do" on the same line as the "if", if it fits even if indN is less than five, if the then clause of an if statement is a noniterative do group without a condition or label prefix; puts the "then do" on the same line if it fits and in I\thendo mode; lines the "then" up with the "if" if in thendo mode; puts the "else do" on the same line, if it fits even if indN is less than five, if the else clause of an if statement is a noniterative do group without a condition or label 3-375 AG92-D6 prefix. In Adelnl mode, the "then" or the "else" must already be on the same line as the ttdo". Example: /* format: ifthendo,Aindnoniterdo */ if v = 2 then x = 8; y = 9; do; end; else do; x = 9; y = 92; end; /* format: ind3, ifthendo,Aindnoniterdo */ if v = 2 then do; x = 8; y = 9; end; else do; x = 9; y = 92; end; Aifthendo doesn't put the "then do" on the same line as the "if". (Default) Example: /* format: Aindnoniterdo */ if v = 2 then do; x = 8; y = 9; end; else do; x = 9; y = 92; end; thendo if in ifthendo mode, lines the "then" up with the "if". Example: /* format: ind3,ifthendo,thendo,Aindnoniterdo */ if v = 2 then do; x = 8; y = 9; end; else do; x = 9; y = 92; end; 3-376 AG92-Q6 "thendo if in ifthendo mode. puts the "then do" on the same line as the "if" if it fits. (Default) Example: /* format: ind3,ifthendo,"indnoniterdo */ if v = 2 then do; x = 8; y = 9; end; else do; x y = 9; = 92; end; if then puts the "then" on the same line as the "if". Example: /* format: ind3,ifthen */ if v = 2 then do; x = 12; y = 128; end; else do; x = 128; y - 12; end; "if then lines the "then" up with the "if". (Default) Example: if v = 2 then x = 8; else x = 9; elsestmt places independent statements on the same line as the else clause; places nonindependent statements on the same line as the else clause if indN is set to five or more. (Default) Aelsestmt does not place any statements on the same line the else clause appears on unless the else clause is part of an if statement in "case" mode and the statement following the else clause is another if statement. 3-377 AG92-Q6 Example: /* format: style2, ifthen,Aelsestmt */ if a else = b then x = y; x = Z; indnoniterdo indents the statements of the do group two indentation levels from the column in which the "if" starts if a then or else clause contains a noniterative do group without a condition or label prefix; indents three levels if in indthenelse mode. (Default) Example: if v = 2 then do; x = 3; y = 4; end; else do; x = 35; y = 27; end; Aindnoniterdo indents the statements of the do group one indentation level from the column in which the "if" starts if a then or else clause contains a noniterative do group without a condition or label prefix: indents two levels if in indthenelse mode. Example: /* format: Aindnoniterdo */ if v = 2 then do; x = y = end; else do; x = y = end; 3; 4; 35; 27; inditerdo indents the statements of the do group two indentation levels from the column in which the "if" starts if a then or else clause contains an iterative do group and it does not have a condition or label prefix; indents three levels if in indthenelse mode. (Default) Example: if v = 2 then do i =1 to 4; a (i) = i; end; 3-378 AG92-<>6 "'inditerdo indents the statements of the do group one indentation level from the column in which the "if" starts if a then or else clause contains an iterative do group and it does not have a condition or label prefix; indents two levels if in indthenelse mode. Example: /* format: "'insnl,Ainditerdo */ if v =2 then do i a 0) = i; =1 to 4; end; indnoniterend starts the end statement of the noniterative do group in the same column as the statements of the noniterative do group if a then or else clause contains a noniterative do group without a condition or label prefix. Example: /* format: "'indnoniterdo,indnoniterend */ if v = 2 then do; x = 8; y = 9; end; else do; x y = 9; = 92; end; -~. i ndnon i terend starts the end statement of the noniterative do group in the column that is one indentation level before the column the statements of the noniterative do group start in if a then or else' clause contains a noniterative do group without a condition or label prefix. (Default) Example: /* format: "'indnoniterdo */ if v = 2 then do; x = 8; y = 9; end; else do; x = 9; y :: 92; end; indthenelse indents the then and else clauses two indentation levels from the column in which the "if" is placed. Places the "else" one indentation level from the column in which the "if" is started. If in Aifthen mode and the ifthenstmt and ifthendo modes do not apply to the if statement. places the "then" in the same column as the "else". If in case mode and the if statement under consideration is the else 3-379 AG92-D6 clause of another if statement, then indents from the preceding "else" is placed instead of the column in which case mode this mode is ignored f or the else clause if the an if statement or the if statement under consideration another if statement Example: column in which the the "if" is placed. In else clause consists of is an else clause of I'': format: indthenelse *1 if v = 2 then x = 8; else do; x = 9; ca 11 default; end; Itc format: if v = 2 then else if v then else ca 11 indthene1se )'tl x = 8; = 3 x = 25; error; "'indthene1se indents the then and else clauses one indentation level from the column in which the "if" is placed. Places the "else" in the same column as the "if" is placed. If in f.ifthen mode and the ifthenstmt and ifthendo modes do not apply to the if statement. places the "then" in the same column as the "else". If in case mode and the if statement under consideration is the else clause of another if statement, then indent from the column in which the preceding "else" is placed instead of the column in which the "if" is placed. (Default) Example: !f v = 2 then x = 8; else do; x = 9; ca 11 default; end; if v then else then else = 2 x = 8; if v = 3 x = 25; ca 11 error; case, "'tree indents "else if" clauses like a case statement. (Default) 3-380 AG92-06 Example: if char = "a" then call char a; else if char =-lIb" then call char b; else if char =-IICIl then call char_c; else call error; /* format: ifthenstmt */ if char = lIa ll then call char_a; else if char = IIb ll then call char_b; else if char = II C" then call char_c; else call error; /* Decision tree formatted 1 ike a case statement. */ if condition_l then if condition_2 then ca 11 cond it i on (0); else ca 1 1 cond i t i on (1); else if condition_2 then ca 11 cond i t i on (2); else ca 1 1 cond i t i on (3); tree, ""case indents "else if" clauses like a decision tree. Example: if /* tree */ condition then if condition=2 then ca 1 1 cond it i on else ca 11 cond it ion else if condition_2 then ca 1 1 cond i t i on else ca 1 1 cond j t i on (0); (1); (2); (3); /* Case statement formatted like a decision tree. */ 1* format: tree */ if char = "all then call char_a; else if char = IIb li then call char_b; else if char = IIC" then call char_c; else call error; 3-381 AG92-06 indbegin indents the body of those begin blocks that do not follow then clauses, else clauses, or on statements. (Default) Example: a = 15; begin; x = 21; end; y = 2; "indbegin does not indent the body of those begin blocks that do not follow then clauses, else clauses, or on statements. Example: /* format: "indbegin */ a = 15; begin; x = 21; end; y = 2; indbeginend indents the end statement of those begin blocks that do not follow then clauses, else clauses, or on statements to the level of tbe begin block body. If in I\indbegin mode, this option does not effect the placement of the end statement. The end statement always lines up under the begin block body and in the 5a..rne column as the begin statement since they are the same column. Example: /* format: indbeginend */ a = 15; begin; y Example: = x = 21; end; 2; /* format: "indbegin,indbeginend */ a = 15; begin; x = 21; end; y = 2; "indbeginend places the end statement of those begin blocks that do not follow then clauses, else clauses, or on statements in the same column as the begin statement. (Default) 3-382 AG92-06 indthenbegin indents the body of begin blocks that follow then clauses, else clauses, or on statements. (Default) Example: if a = 2 then begin; x end; y = 15; = 12; Aindthenbegin does not indent the body of begin blocks that follow then clauses, else clauses, or on statements. By default the corresponding end statement is indented one less level than the begin block body (see indthenbeginend). Example: /* format: Aindthenbegin */ if a = 2 then begin; x = 12; end; y = 15; indthenbeginend indents the end statement of those begin blocks that follow then clauses, else clauses, or on statements to the same level- as the begin block body. Example: /* format: indthenbeginend */ if a = 2 then begin; x = 47; end; y Example: = 100; /* format: Aindthenbegin,indthenbeginend */ if a = 89 then begin; x = y; end; y = 100; Aindthenbeginend indents the end statement of those begin blocks that follow then clauses, else clauses, or on statements one less level than the indentation of the begin block body. (Default) Example: if a = b then begin; x = 15; end; y = 9; 3-383 AG92-06 Example: /* format: Aindthenbegin */ if a = b then begin; x = 15; end; y = 9; indproc starts the procedure statement in the same column as other statements of the containing procedure if a procedure is contained within at least two other procedures, i.e.• the procedure is an internal procedure of an internal procedure; starts the procedure statement in column indN+ 1, otherwise. Example: /* format: indproc */ extp: procedure; a = 1; i ntp 1 : procedure; b = 2; intp2: procedure; c = 3; end intp2; end i ntp 1 ; end extp; Aindproc start procedure statements in column indN+ 1. (Default) Example: extp: procedure; a = 1; i ntp 1: procedure; b = 2; intp2: procedure; c = 3; end intp2; end i ntp 1 ; end extp; indprocbody indents the body of the procedure, the statements following the procedure statement, one level farther than the indentation of the procedure statement. (Default) 3-384 AG92-oS Aindprocbody begins the statements following a procedure statement in the same column as the procedure statement. Example: /* format: Aindprocbody */ test: procedure; a = 12; end test; indend starts the end statement of a do group, except those affected by indnoniterend mode, in the same column as the statements of the group. Example: 1* format: indend *1 do i = 1 to 5; a (j) = i; end; Aindend starts the end statement of a do group, except those affected by indnoniterend mode, in the column that is one indentation level before the column the statements of the group start in. (Default) Example: do i = 1 to 5; a 0) = i; end; NOTES ON HORIZONTAL WHITE SPACE All horizontal white space, except within character string constants and comments, is removed from the program. Spaces are inserted before left parentheses, after commas, around operators, and in other places to improve readability. Where possible, horizontal tabs are used to conserve space in the output segment. Statements continued onto another line are indented lineconindN from the current left margin. The left margin at which a statement is indented is increased by indN for every nested begin block, group, and then or else clause except as required by the indnoniterdo. inditerdo. indthenelse, case. indproc, and indprocbody modes. Entry statements are placed in the same column as the corresponding procedure statement. The left margin before a procedure statement is saved; it is restored after the procedure's end statement. After a procedure statement the left margin is increased by indN if the indprocbody option is set. End statements are started in the same column as the statement that began the block or group except as required by the indnoniterend, indend, indbeginend, and indthenbeginend modes. Condition and label prefixes are placed on lines by themselves except possibly in "insnl mode. 3-385 AG92-oS NOTES ON VERTICAL WHITE SPACE Vertical white space within character string constants and comments is never changed. Other vertical white space can be intrastatement and interstatement. In on mode, vertical tabs and newlines before newpages are removed, newlines before vertical tabs are removed, and mUltiple newpages are reduced to one. Then a newline is inserted before and after a sequence of vertical tabs and new pages if there is not already one there. Interstatement vertical white space· is never changed except for the above canonicalizations; intrastatement vertical white space is also canonicalized as above and processed depending upon delnl and insnl modes. LIST OF VERTICAL WHITE SPACE MODES delnl deletes all existing intrastatement vertical white space. "'delnl leaves existing intrastatement vertical white space in the program. (Default) insnl inserts newlines in the program if necessary. Newlines are inserted when statements are too long to fit on a line. To determine where newlines are inserted, various heuristics exist that use the statement type and the precedence of the tokens in. the statement to determine where to insert newlines. The driving force of format_pll is what column statements or other language constructs should start in. Newlines are inserted to start a statement; subset of a statement. or a comment in a particular column. "'insnl doesn't insert newlines into the program. (Default) NOTES ON COMMENTS Comments are classified by where they occur within a PLII program and where they are placed in the output segment They are divided into three categories: intrastatement comments, indented comments, and block comments. Intrastatement comments occur between the first token of a statement and the semicolon ending the statement They are normally separated from surrounding tokens by a space except as required for linecom mode. Comments that follow a semicolon and are separated by at most one newline character are considered indented comments. They are placed in column comcolN. All other comments are block comments. Block comments are placed in column one or indented to the current left margin according to the indcom and indblkcom modes. All comments following a blank line, following a block comment, and before the first token of the program are block comments. Placing a comment in column N means that the" 1*" starts in column N. 3-386 AG92-G6 In these special cases intrastatement comments are treated as indented comments and placed in column comcolN: comments following a comma; preceding the right parenthesis of a declaration component; following the colon in a condition or label prefix; and, in if statements that the ifthenstmt or ifthendo modes do not apply to, following the "then" in if then mode and preceding the "then" in Aifthen mode. A comment indicator is placed at the beginning of a comment to specify where the comment is placed or to inhibit indcomtxt mode on the comment. If necessary, even in Ainsnl mode, a newline is inserted to place the comment in the specified column. Comment indicators consist of the "1*", which starts the comment followed by other characters as listed below. A comment indicator does not affect the classification of succeeding comments. LIST OF COMMENT INDICATORS i* 1** places the comment according to its default classification. places the comment in column comcolN. 1*** indents the comment relative to the current left margin according to indblkcom mode. 1**** places the comment in column one. Example: /* format: ind3,comco121 */ /**** column one comment */ /*** comment indented a = 3; to left margin *1 /** indented comment */ /* indented comment */ /* column one comment by default */ ... = - '#J I,. ..oo:'j I*A places the comment according to its default classification; formats the comment according to Aindcomtxt mode. I**A places the comment in column comcolN; formats the comment according to I\indcomtxt mode. I***A indents the comment relative to the current left margin according to indblkcom mode; formats the comment according to Aindcomtxt mode. 3-387 AG92-06 1****" places the comment in column one; formats the comment according to "indcomtxt mode. LIST OF COMMENT MODES comcolN N is the column indented comments are placed at. (Default: 61) indcom indents block comments relative to the current left margin according to indblkcom mode. This mode doesn't apply before the first token of the program so it doesn't interfere with copyright notices. Example: /**** format: ind3 *1 /* comment indented to left margin */ a = 3; Aindcom places block comment in column one. (Default) Example: /* format: ind3 *1 /* column one comment *1 a = 3; indblkcom starts comments that begin with the n 1***" or "1***1'." comment indicators and in indcom mode, block comments, at the current left margin. (Default) Example: /* format: ind3,indcom */ /**** column one comment */ /*** block = 5; comment */ a Aindblkcom starts comments that begin with the "1***" or "1***1'." comment indicators and in indcom mode, block comments, one indentation level before the current left margin. Example: /* format: ind3,indcom,Aindblkcom */ /**** column one comment */ /*** block comment */ a = 5; 1 inecom intrastatement comments at the end of a line in the original source segment apply to an entire line. These comments are treated as indented comments and are placed in column comcolN. 3-388 AG92-06 Example: /* format: linecom */ if line status < 3 I char_count> /* Is line active? */ 0 then return; "linecom intrastatement comments apply to the preceding token. (Default) Example: /* format: "delnl */ if char I = I040"b3 /-;': space 1~/ char_count> 0 then return; indcomtxt inserts a space if there is no horizontal or vertical white space between the comment indicator and the comment text or between the end of the comment text and the "* I" or the reverse of any comment indicator. Indents the text of continuation lines of a multiline comment so they line up; indenting the text of continuation lines does not apply to in trastatement comments. The horizontal white space between the comment indicator and the comment text on the first line of a comment is not reduced; however, leading horizontal white space on subsequent lines is replaced by sufficient horizontal white space to indent the line. If the comment is placed in column N, the length of the comment indicator is L, then the text of each line of the comment begins in column N+L+ 1. This mode does not apply to comments whose comment indicator ends with "1\". Example: /* format: indcomtxt */ a = 3; /* Here we have a very complicated assignment statement. '1~/ Input: Output: /* format: indcomtxt */ a = 3; /* Here we have a very complicated assignment statement. 1~/ "indcomtxt leaves the white space at the beginning of each line of a comment alone. The character string between the "/*" and the "*/" of a comment is never changed in this mode. (Default) NorES ON iRREVERSiBLE CHANGES Several modes can cause irreversible changes to be made to the source program. Suppose that program p.pll was formatted with style S and does not contain a prevailing style control comment, then style T causes an irreversible change if the following command lines produce a program q.pll that differs substantially from p.pll: format_pll p -modes T -output_file q.pll format_pll q -modes 5 3-389 AG92-Q6 The following modes can cause irreversible changes: delnl. insnl, "1inecom, and indcomtxt If a program is not formatted with format_pH. the on mode may also cause irreversible changes. NOTES ON STYLES style1: on,ind5, 11122, initco16,indattr,inddcls,declareind8, dclind8,idind23,struclvlind2,Aifthenstmt,Aifthendo, Athendo,Aifthen,indnoniterdo,inditerdo, Aindnoniterend,Aindthenelse,case,Aindproc,Aindend, Adelnl,Ainsnl,comco161,Aindcom,indblkcom,Alinecom, Aindcomtxt (Default) style2: stylel,delnl,insnl style3: style2,Ainddcls,declareind10,dclind10, idind20 style4: style1,Aindattr,Ainddcls,declareind9,dcl ind5, ifthendo,Aindnoniterdo,Ainditerdo,indproc,linecom, indcomtxt style5: style2,linecom,ifthen,Aindnoniterdo,indnoniterend, indcomtxt,Aindthenbegin,indthenbeginend,Aindprocbody, Ae l ses tmt,ind8, l180,initcolO,idind24,comco157, lineconind4, Stylel indents declare statements, the attributes of declare statements, and the statements of the do group and lines up the end statement of a noniterative do group in a then or else clause under the "do". No irreversible changes, such as with the delnl, insnl, or indcomtxt modes, are made. Example: /* format: stylel */ declare entryname if x = 2 then do; a = 43; b = 21; end; char (32); Style2 is the same as stylel except it uses the delnl.insnl modes. irreversible changes. It may cause Style3 is the same as style2 except that declare statements start in column one and the identifiers and attributes start in columns aligned on tab stops. It may can cause irreversible changes. Example: 3-390 AG92-06 /* format: sty1e3 */ declare entryname if x = 2 then do; char (32); = = a b 43; 21; end; Style4 starts declare statements in column one, doesn't indent the attributes in declare statements, formats noniterative do groups in then or else clauses by indenting the statements of the noniterative do group one indentation level from the "if" or the "else", and starts the end statement in the same column as the "if" or the "else". This style uses the I\delnl, "insnl modes, but still may cause irreversible changes from indcomtxt mode; it resembles that of the indent command. Example: /* format: style4 */ declare entryname char (32); if x = 2 then do; a = 43; b = 21; end; Style5 starts declare statements in column one. sets the. Hne length to 80 columns, sets the indentation amount to eight columns, sets the line continuation indentation to four columns, places the then clause of the "if/then" statement on the same line with the if, doesn't place any statement on a line with an if statement or else clause except for placing an if statement on the line after an else when in case mode, doesn't indent the procedure body, and doesn't indent the body of "begin/end" blocks or noniterative do groups under if statements. Example: /* format: styleS */ test: procedure; a = 12; if a = b then a = 15; else a = -15; b = 78; if b = c then do; x ;; I; y = 99; a = 0; end; end test; 3-391 AG92-()6 format_string NOTES ON ERROR CHECKING Parenthesis balance checking is done for statements that are not partially contained in include files. A warning is printed if an end statement with a closure label terminates more than one block or group. If you provide no -output_file and there were errors, the source segment is not overwritten and a formatted copy is left in the process directory. An error message is printed if a control comment is incorrect. NOTES ON ERROR SEVERITIES The following severity values are returned by the severity active function when the "format_pll" keyword is used: Value o 1 2 3 4 5 Meaning No error Warning Correctable error Fatal error Unrecoverable error Bad control arguments, could not find source, or other severe errors. NOTES ON MACROS This command makes certain assumptions about macros. Include files must contain complete statements and balanced blocks or groups. Macro constructs can only occur between statements; they must not occur within a statement. All macro constructs are placed in column one. All %then and %else clauses of a %if macro must have the same effect on the current left margin and on block and group nesting; in addition, the effect on block and group nesting can only be to leave it unchanged or to start new blocks or groups. Blocks or groups that were started before the %if macro cannot be closed in the %then or %else clauses. A %then or %else clause cannot start with an else clause. Name: format_string, fstr SYNTAX AS A COMMAND fstr {-control_args} text SYNTAX AS AN ACTIVE FUNCTION [fstr {-control_args} text] 3-392 AG92-{)6 format_string format_string FUNCTION uses format_document_$string to fill and optionally adjust a text string. As a command, it prints the filled and adjusted text; as an active function, it requotes the return value. ARGUMENTS text is the text strings to be filled. If you give more than one, they are concatenated, separated by a space. All arguments that do not begin with a minus and are not an operand of a preceding control argument are treated as text strings, and so are all arguments following the first text string encountered, whether or not they begin with a minus. CONTROL ARGUMENTS -adjust, -adj left- and right-justifies text. -break_word to prevent line length from being exceeded, arbitrarily breaks into two or more parts words that are longer than the current line length and that cannot be hyphenated (when you use -hyphenate). (Default) -column N, -col N formats text as if N-l characters already appeared on the first line. The output begins at column N. (Default: 1) -hyphenate {N}, -hph {N} changes the default hyphenation mode from OFF to ON. The optional parameter N is the length of the smallest separated word part; its default value is 2. -indent N, -ind N indents output N spaces from the left margin. (Default: 0) -line_length N, -11 N sets the line length to N characters. (Def aul t: 65) -no_adjust, -nadj turns off justification. (Default) -no_break_word does not brake words longer than the line length; instead, it returns a line longer than the given line length. -no_hyphenate, -nhph turns off hyphenation. (Default) 3-393 AG92-06 fortran format_string -string text, -str text treats all remaining arguments as part of the text to be formatted. -undent N, -und N undents the first line by N characters. If N is negative, the first line is indented (with respect to the -indent value) by N characters. EXAMPLES ioa_ IIS ubject: be fill ed] Subject: A A _ a" [fstr -in 10 -col 11 -11 20 lengthy subject to lengthy subject to be fill ed fills the subject to lines 20 characters long, indented by 10 characters. output line begins in column 11, and so is not indented. The first The command line fstr -11 23 -in 10 -un -3 -adj Now is the time for all good people to support us Multicians. produces Now is the time for all good people to support us Multicians. Name: fortran, ft SYNTAX AS A COMMAND ft path {-control_args} FUNCTION invokes the FORTRAN compiler. 3-394 AG92-D6 fortran fortran ARGUMENTS path is the pathname of a FORTRAN source segment; you need not give the fortran suffix. CONTROL ARGUMENTS -ansi66 interprets the program according to the 1966 standard for FORTRAN, with Multics FORTRAN extensions. (Default) -ansi77 interprets the program according to the 1977 standard for FORTRAN, with Multics FORTRAN extensions. -auto_zero initializes to zero, when allocated, automatic storage for local variables. (Default) 7069 -binary_floatinLpoint, -bfp makes the internal representation of floating point numbers be 2 ** exponent (Default) * MeR * mantissa. -brief. -bf writes error messages in short iorm. -brief_table, -bftb generates partial symbol table giving correspondence between source line numbers and object locations. -card specifies that the source segment is in card-image format -check, -ck checks the source segment for syntactic and semantic errors. Code generation is skipped; no object segment is produced. -check_multiplY, -ckffipy produces code that checks for integer multiplication overflow. (Default, if you supply -ansi77 but not -optimize) -debuLio, -dbio establishes a new command level after a run-time I/O error. 11/87 3-395 AG92-06B fortran fortran -default_full, -dff sets the default optimizer to "full_optimize" (see -optimize). (Default) -default_safe, -dfs sets the default optimizer to "safe_optimize" (see -optimize). -fold maps uppercase letters to lowercase form. -full_optimize, -full_ot invokes the full optimizer to speed up program execution and reduce its size. -free specifies that the source segment is in free-form format. (Default) -hexadecimal_floatins-poin t, -hfp allows the use of HFP numbers. Real, complex, and double-precision numbers can have four times more magnitude in HFP mode at the expense of some precision. Compilations using -hfp and execution of any such programs require rw access to >sc1>admin_acs>Fortran_hfp.acs. This feature is only supported on the DPS8 hardware. Your site may disallow the use of HFP code by not creating the above access control segment or by denying access to it. -large_array, -la is used when more automatic or static storage is required by a program than would fit in stackframes/linkage sections. Individual arrays and common blocks must not exceed 255K words. (See -very_large_array.) -line_numbers, -In gives a source segment with line numbers. -list, -Is produces a complete source program listing plus an assembly-like listing. -long, -Ig writes error messages in long form. (Default) -Ions-profile, -lpf generates extra code to meter execution of individual statements using virtual CPU time and page fault measurements. -map produces complete source program listing. 11/87 3-396 AG92-06B fortran fortran -no_au to_zero does not initialize to zero. when allocated. automatic storage for local variables; that is. initial values of variables are undefined. It is faster than -auto_zero. -no_cheek_multiply. -nckmpy does not produce code that cheeks for integer multiplication overflow. (Default. if you specify -ansi66 or -optimize) -no_debuLio. -ndbio does not establish a new command level after a run-time I/O error. (Default) -no_fold does not map uppercase letters into lowercase form. (Default) -no_large_array, -nla suppresses large_array. 11/87 3-396.1 AG92-06B fortran fortran -no_line_numbers. -nIn does not give a source segment with line numbers. -no_map produces no program listing. (Default) -no_optimize, -not performs no optimizations. (Default) -no_stringrange, -nstrg does not produce range-checking code for all substring references. (Default, if you use -ansi66 or -optimize) -no_subscriptrange, -nsubrg does not produce range-checking code for all (Default. if you supply -ansi66 or -optimize) subscripted array references. -no_table, -ntb does not generate a runtime symbol table. (Default, if you give -optimize) -no_ version does not print out the version of the current compiler. -no_very_large_array, -nvla suppresses -very_large_array. (Default) -no_vla_parm inhibits -vla_parm. -non_relocatable, -nrlc inhibits generation of relocation information by the compiler. The resulting object segmen t cannot be bound. -optimize, -ot invokes an extra compiler phase just before code generation to perform certain optimiza tions. -profile. -pf generates extra code to meter execution of individual statements. -relocatable, -rIc generates relocation information. (Default) -round rounds intermediate results of real and double-precision calculations before storing. (Default) -safe_optimize, -safe_ot like -optimize, but inhibits some code movement. 3-397 AG92-()6 fortran fortran -severity N, -sv N prints only error messages whose severity is N or greater (where N is 1, 2, 3, or 4). (Default: 1) -stringrange, -strg produces range-checking code for all substring references. (Default, if you give -ansi77 but not -optimize) -subscriptrange, -subrg produces range-checking code for all subscripted array references. (Default, if you specify -ansi77 but not -optimize) -table, -tb generates full symbol table. For use with the probe and debug commands. (Default, unless you use -optimize) -time, -tm prints table giving time (in seconds), number of page faults, and size of temporary area for each phase of the compiler. -time_ot prints out timing information on the subphases of the optimizer. -top_down optimizes loops using a top-down approach. -truncate. -tc truncates intermediate results of real and double-precision computations before storing. -version prints out the version of the FORTRAN compiler before compiling. -very_large_array. -vIa is used when arrays or common blocks have sizes exceeding segment size (255K < array size or common block length < 2**20 [16M] words). It implies -large_array. -vla_parm is used in subroutines when parameters that are passed to them could come from very-large-array procedures. It allows the use of very-large arrays but not of large arrays within the subroutine. 3-398 AG92-D6 fortran NOTES ON SEVERITY VALUES This command associates the following severity values to be used by the severity active function: Value o 1 2 3 4 5 Meaning No compilation yet or no error Warning ()orrectable error Fatal error Unrecoverable error ()ould not find source. NOTES Mutually exclusive control arguments are: -ansi66 and -ansi77 -lonK-profile and -profile -optimize, -safe_optimize and -stringrange, -subscriptrange -round and -truncate For more information on the FORTRAN compiler and on using FORTRAN on Multics, see the Multics FORTRAN Reference Manual (AT58) and the Multics FORTRAN User's Guide (CC70). Name: fortran_abs, fa SYNTAX AS A COMMAND fa paths {-ft_args} {-dp_args} {-control_args} FUNCTION submits an absentee request to perform FORTRAN compilations. ARGUMENTS paths are pathnames of segments to be compiled. ft_args are one or more control arguments accepted by the fortran command. dp_args are one or more control arguments (except -delete) accepted by the dprint command. 11/86 3-399 AG92-06A CONTROL ARGUMENTS -hold specifies that fortran_abs should not dprint or delete the listing segment. -limit N. -Ii N places a limit on the CPU time used by positive decimal integer specifying the limit by your site for each queue on each shift. limit for the current shift are deferred to defined by your site for each queue) the absentee process. N must be a in seconds. An upper limit is defined Jobs with limits exceeding the upper a shift with a higher limit (Default: -output_file path. -of path specifies that absentee output is to go to the segment whose pathname is path. -queue N, -q N is the priority queue of the request (see "Notes" for a description of the interaction with the dprinting of output files). (Default: defined by your site) NOTES The absentee process for which fortran_abs submits a request compiles the segments named and dprints and deletes the listing segment. If you specify no -of. the output segment path.absout is created in your working directory (if more than one path is specified, only the first is used). If none of the segments to be compiled can be found. no absentee request is submitted. You can freely mix control arguments and can put segment pathnames anywhere on the command line after fortran_abs. All control arguments apply to all segment pathnames. If you give an unrecognizable control argument, the absentee request is not submitted. Unpredictable results may occur if you submit two absentee requests that could simultaneously attempt to compile the same segment or write into the same absout segment. When doing several compilations, give several pathnames in one command invocation. With one command. only one process is set up; thus the dynamic intersegment links that need to be snapped when setting up a process and when invoking the compiler need be snapped only once. 11/86 3-400 AG92-06A If you give no -q, the request is submitted into the default absentee priority queue defined by your site and, if requested, the output files is dprinted in the default queue of the request type specified on the command line. (If you give no request type, "printer" is used.) If you give -q, the output files is dprinted in the same number queue as the absentee request If the request type specified for dprinting does not have that queue,. the highest numbered queue available for the request type is used and a warning is issued. 11/86 3-400.1 AG92-06A This page intentionally left blank. 11/86 AG92-06A gcos gcos Name: gcos, gc SYNTAX AS A COMMAND FUNCTION invokes the GCOS environment simulator to run a single GeOS job, immediately. in your process. ARGUMENTS job_deck_path is the pathname of the file contalmng a GeOS job deck. The file can contain ASCII lines or can be in GeOS standard system format. CONTROL ARGUMENTS -ascii, -aci input file contains ASCII lines. -block N, -bk N specifies the block size to be used for gcos tape buffer (in words). For buffers larger than 2800 words, the use must have rw access to >sc1>rcp>workspace.acs. Use of the ",block=nnnn" control on the volume_id for nstd_ tape attachments overrides this buffer size setting. If multiple buffer sizes are supplied on a command line, the rightmost is used. (Default 2800 words; max 4096) -brief, -bf suppresss printing of all terminal output except fatal error messages. -continue, -ctu continues processing the job when a nonfatal error occurs. -debug, -db causes the simulator to call debug command under certain error conditions. -dprint, -dp queues the converted print files for printing followed by deletion (-list is implied). -dprint_options options, -dpo options queues the converted print files for printing, but use -dprint supplied in the options string (-list and -dprint are implied). The options argument must be enclosed in quotes. -dpunch, -dpn queues converted punch files for punching in raw mode, followed by deletion (-raw is implied). 3-401 AG92-06 gcos gcos -dpunch_options options. -dpno options queues converted punch files for punching, but use -dpunch supplied in the options string (-raw and -dpunch are implied). The options argument must be enclosed in quotes. -gcos, -gc input file in GCOS standard system format. -hold. -hd does not perform the default conversion and daemon output of print and punch files. -job_id id, -jd id uses job identification specified by id in the names of files created by the simulator for this job. The id can be any character string of up to 18 characters, or -unique to indicate Multics unique name, or -jd_seg (-jd) to indicate the entryname of job deck segment. -list, -Is converts print files (both sysout and simulated printer) from BCD (or binary) to ASCII and delete the BCD copy. -long, -lg prints certain lines from the execution report in addition to normal terminal output. -lower_case. -lc translates alphabetic BCD characters in print files to lowercase ASCII. (Default: .uppercase) -no_bar, -nobar, -nb request the simulator run the slave programs in Multics mode instead of BAR mode. -no_canonicalize, -nocan, -no ASCII input file contains no tab characters, and the fields on all the card images are aligned in the columns required by GCOS. -parameter parameters, -pm parameters specifies that the remaining arguments in the command line are to be used to override the $PARAM card values. -raw converts punch files (both sysout and simulated card punch) from BCD to format suitable for punching in raw mode and delete the BCD copy. -smc path . specifies a directory to be used as the system master catalog. When -smc is given, the first field in catalog/filename descriptions is retained. 3-402 AG92-06 gcos -syot_dir path, -sd path puts GeOS format copies of print. punch. and sysout files in directory named "path" rather than working directory. (Default) -temp_dir path, -td path puts temporary acos files in directory named directory. (Def aul t) "path" rather than process -truncate, -tc discards ASCII input file lines longer than 80 characters (after canonicalization). If not given. the first line longer than 80 characters causes the job to be rejected. -userlib enables the use of GeOS slave software libraries supplied by you. NOTES Related facilities include the GeOS daemon, which provides batch processing for GCQS jobs under Multics, and appropriate commands, used to manipulate GeOS format files that reside in the Multics storage system. These commands. and the gcos command, are fully described in the Multics GCOS Environment Simulator Manual (AN05). EXAMPLES If no control arguments are given, the command gees path is equivalent to the command gees path -aei -dpo -dl -dpno "-dl -raw" -id -jd -bk 2800 Name: general_ready, gr SYNTAX AS A COMMAND gr {-eontrol_args} SYNTAX AS AN ACTIVE FUNCTION [gr {-eontrol_args}] 3-403 AG92-D6 FUNCTION prints a ready message containing specified values in a specified format. LIST OF PREFIX CONTROL ARGUMENTS You must use these control arguments prior to the format ones. They allow override the default formats for the contents of the ready message. y~u to -string allows you to specify the character string at the beginning of the ready message. The argument following -string is used instead of "rn at the beginning of the ready message. Since it is put into the ioa_ control string. you can use "A /". "AR". and "AB" to cause new lines, red ribbon shifts, and black ribbon shifts, respectively. -control allows you to specify the entire ioa_ control string used to· format the ready message. The string is passed to ioa_$nnl without change so it must contain specifications for each of the various values to be included in the ready message. The ioa_ control string formats for the various values that you can insert into the ready message are given below for each type of value (see "List of Format Control Arguments"). This control argument overrides any format arguments that would normally affect the format of the ready message; however, you must still give format keywords to indicate which values are to be output and the order in which these values correspond to the ioa_ control characters in the control string. LIST OF FORMAT CONTROL ARGUMENTS The format and content of the ready message are controlled by format control arguments. They include control arguments that identify values to be included in the ready message. optional precision numbers following some of these control arguments that control the number of digits after the decimal point in numeric values. and literal character strings that are inserted in the ready message. The format control arguments are combined in the order of their appearance in general_ready to form an ioa_ control string that controls the format of the ready message. You can use seven types of values in a ready message: 1. 2. 3. 4. 5. 6. 7. content values processor usage values (virtual CPU seconds) memory usage values (memory units) usage cost values (dollar charges) paging operations (and demand page faults) command processor (level numbers) date/time values (date, time of day, day of the week. etc.). 3-404 AG92-06 Both total usage values (total usage accrued during this process) and incremental usage values (usage accrued since the last ready message printed by general_ready) can be output in the same ready message. The values are selected for use in the ready message by format control arguments to general_ready. The format control arguments are listed below by type. Content values: -active_string STR, -astr STR expands the active string STR each time the ready message is printed. Processor usage values: -inc_rcpu {N} incremental real CPU value. -inc_vcpu {N} incremental virtual CPU value. -total_rcpu {N} total real CPU value. -total_vcpu {N} total virtual CPU value. where N can be a single numeric digit from 1 to 9, indicating the number of digits that should appear to the right of the decimal point in the number that is output. The default is three digits. The output format of the value can be described by the ioa_ control string "".Nf", where N is 3 by default. Memory usage values: -inc_mem_units {N} incremental units. -total_mem_units {N} total memory units. These control arguments are used in the same manner as the ones for processor usage values. Usage cost values: -inc_cost {N} incremental cost charges. 3-405 AG92-o6 general _ready general_ready -total_cost {N} is the cost charges. These control arguments are used in the same manner as the ones for processor usage values except that the default number of digits following the decimal point is two. The output format of the value can be described by the ioa_ control string " $" .Nf" where N is 2 by default Charges being accrued for devices (terminal, tape mounts, etc.) are not updated in the PIT where the user can see them. Therefore, general_ready estimates the dollar figure based on connect/ cpu time. Paging operations values: -inc_bf is the incremental bounds faults. -inc_pft is the incremental page faults. -inc_sf is the incremental segment faults. -inc_vr is the incremental VTOC reads. -inc_vw is the incremental VTDC writes. -total_bf is the bounds faults. -total_pft is the page f aul ts. -total_sf is the segment faults. -total_vr is the VTOC reads. -total_vw is the VTOC writes. These control arguments are output by the ioa_ control string ""d", where "d is the number of demand page faults. 11/87 3-406 AG92-06B Command processor values: -level, -lev specifies the number of command processor invocations to be included in the ready message. The level numbers are output by the ioa_ control string "Aa", but the printed format can be described by "level Ad". If· the command processor level is 1, the printed format is the null string. The number of digits is not settable. -frame, -fr specifies the number of stack frame level numbers to be included in the ready message. The level numbers are output by the ioa_ control string "Aa", but the printed format can be described by "frame Ad". If the command processor level is 1, the printed format is the null string. If you give both control arguments, the printed format can be described by "level Ad, Ad". Date/time values: -date is your default date format. Type "print_time_defaults date" to display the format and "gr -date" to display a sample date value. -date_time is your default date/time format. Type "print_time_defaults date_time" to display the format and "gr -date_time" to display a sample date/time value. -day is a two-digit day (dd). -day_name is a three-character day of the week (www). -hour is a two-digit hour (hh). -minute is a two-digit minute (mm) -month is a two-digit month (mmj. -time. -tm is your default time format. Type "print_time_defaults time" format and "gr -time" to display a sample value. to display the -time_format STR, -tfmt STR where STR is a time format control string defining a user-specified format for any of the various date values (see "Time Format" in Section 1). 11/86 3-407 AG92-06A -year is a two-digit year (yy) -zone is a three-character time zone (zzz). These values can be described by the ioa_ control string ""an except for the -day, -minute, and -year control arguments, which use the ioa_ control string ""a" (without a leading space). The number of digits is not settable. LIST OF OPERATION CONTROL ARGUMENTS The following control arguments affect the operation of gr, but do not change the format of ready messages. -call cmdline when used with -set, calls the command processor to execute cmdline after the completion of every command line. The argument cmdline is a single argument to gr; you must therefore enclose it in quotes if it contains any blanks. A frequent use of -call is "-call print_messages -brief"; cmdline is executed even if the printing of ready messages has been inhibited by executing ready _off. -reset resets incremental usage values to zero without printing a ready message. -revert makes the system ready procedure the current ready message procedure and resets any timer alarms to catch shift changes. -set establishes gr as the current ready message procedure and sets an alarm timer to catch shiH changes. The command processor then calls gr to print a ready message after each command line is complete. In addition, the ready, ready_on. and ready_off system cOlnmands determine the operation of gr. NOTES ON OPERATION CONTROL ARGUMENTS The -revert and -set control arguments are mutually exclusive. A gr command that includes -set does not print a ready message; instead it saves the ioa_ control string built from the format and prefix control arguments in the command and uses this ioa_ string to control the format of ready messages printed when command lines complete execution or when a ready command is issued. A gr command that includes -revert prints a single ready message only if format or prefix control arguments appear in the command with -revert; otherwise no ready message is printed. 11/86 3-408 AG92-o6A 11 you give nenner -revert nor -set, gr prints one ready message according to the format and prefix arguments given in the command. This command is designed to allow an almost arbitrary format at no additional cost (relative to the system's ready procedure) other than the one associated with gr, which sets up the ready message. Once a ready message is specified, the ready , ready_on, and ready_off commands control the printing of the ready message in the normal manner. 11/86 3-408.1 AG92-Q6A This page intentionally left blank. 11/86 AG92-06A The command builds up an ioa_ control string (see the the Subroutines manual) from the order of the keywords passed to it The keywords specify which values to output in the ready message. Virtual CPU usage and cost can be printed. Both incremental usage (usage accrued since the last ready message produced by general_ready) and total usage (usage accrued during this process) can be in the same ready message with the precision of the output (the number of decimal places to the right of the decimal point) you specified. As a command, you can use general_ready to either print a single ready message or define the contents of the ready message printed by the ready command (and after every command line if you execute ready_on); as an active function, the return value is the ready message. The values for total virtual CPU time and total memory units is valid across new processes. The value for cost is valid unless a shift change occurred during a previous process. When you invoke general_ready for the first time in a process, the cost of all usage in that process up to that time is computed at the rates then in effect. Due to the manner in which ready message procedures and procedures that set up alarm timers are invoked, such procedures should not be terminated (by the terminate and terminate_ref name commands). If you want to terminate general_ready, invoke it with -revert before it is terminated. EXAMPLES The following examples illustrate some of the facilities of general_ready: gr -string READY -date AxTIME -time AXVCPU -inc_vcpu -total_vcpu -set establishes general_ready as the current ready procedure since the -set keyword appeared. Each ready message has the format READY 01/15/83 TIME 1234.3 VCPU 3.456 23.349 If the -set keyword had not appeared, a single ready message having the above format is printed. The ioa_ control string that general_ready uses to generate the above ready message is: The command line gr -string READY -date -hour -total_vcpu 2 -minute "'xVCPUI A,,\lrOI IT AY"'I..,I results in a single ready message of the form READY 01/15/83 09:46 VCPUI 2.345 VCPUT 34.21 using the ioa_ control string 3-409 AG92-06 generate_pnotice "READY "'a "'a:AaAxVCPUI A.3f AxVCPUT A.2f 2/ A 11 You can specify the above ready message by the command line: gr -control "READY "'a Aa:Aa VCPUI A.3f VCPUT A.2f A2/" -date -hour -minute -inc_vcpu -total_vcpu Name: generate_pnotice SYNTAX AS A COMMAND generate_pnotice {-control_args} FUNCTION allows Multics source and object archives and executable software to be legally protected via copyright or trade secret notices and provides software identification via Software Technical Identifiers (STIs). CONTROL ARGUMENTS -id STR specifies the Marketing Identifier (MI) of t...lte product as derived from psp_info_. This control argument and -name are mutually exclusive. -name STR, -nm STR specifies the product's generic name found in psp_info_. -special used in cases where there may be no entry in psp_info_ for the software being protected. This likely occurs when you are protecting software in an experimental or development library. You are prompted for the information to be put into the PNOTICE segments. (See "Notes.") -sti STR specifies a valid 12-character STI. You can use it to override the STI found in psp_info_ when you give -name or -id. NOTES This command allows protection of software residing in a library other than the one specified in psp_info_ or of software not specified in psp_info_, via -special. The command generates ALM source and object segments with the names of "PNOTICE. .alm" and "PNOTICE. ", where comes from the psp_info_, data base or from -special. 3-410 AG92-{)6 generate_pnotice generate_pnotice These segments contain the text of one or more software protection notices and three 12-character STls. The segments are appended to a product's primary source and object archives, as defined in the psp_info_data base. If you select -special. you must provide these archive names. If PNOTICE segments with the same name exist in the archives, they are replaced. Order the archives such that these segments are the first components. The binding of the object archive places the protection notices and STIs into the qound segment as well. Make the bindfile "Order" statement indicate that the PNOTICE component be first. Don't retain the PNOTICE segment name in the bound segment. To find PNOTICE segments' information for installed products, issue the display_psp command. Unless you use -special, the source and object archives must be in your working directory, in which case you must have sma access to the directory as well as rw access to the archives; then you can specify archive pathnames to generate_pnotice. If you supply -special, access is checked, and if it is not sufficient it is forced; otherwise. access is not forced. The command asks you the following set of questions when you select -special. Have the requested information ready. Generic name? You supply a short «= 20 characters) name that is descriptive of the module(s) being protected. The name can be the same one contained in psp_info_ if the module is a newer version; otherwise, you can create the name. STI? This is the Software Technical Identifier. a 12-character identifier usPA by Honeywell to· provide information on released software products. It can be blank for non products. Include the notices from psp_info? The module(s) being protected have an entry in psp_inf 0_. whether the notices there are to be included. You are asked Source pnotice name? You are asked to provide primary names of notices, without the .pnotice suffix, for protection of source. When done, type "q". Use the list_pnotice_names command for available names. Object pnotice name? You are asked to provide primary names of notices. without the .pnotice suffix, for protection of object and executable. When done. type "q". Use the list_pnotice_names command for available names. Pathname of source archive? You are asked to provide an archive pathname of the source archive. ".archive" suffix is not required, but can be given. 3-411 The AG92-06 generate_pnotice Pathname of object archive? You are asked to provide an archive pathname of the object archive. suffix .archive is not required. but can be given. The These two archives need reside neither in the same directory nor in the working directory. * SYNTAX AS A COMMAND get_d i r _quota. {paths} {-contro l_arg} SYNTAX AS AN ACTIVE FUNCTION FUNCTION prints information about the directory quota and pages used by inferior directories. ARGUMENTS paths are pathnames of directories for which you want quota information. If one of the paths is -workins-directory (-wd), your working directory is used. If you don't supply paths, your working directory is assumed. The star convention is allowed.. CONTROL ARGUMENTS -long, -lg includes the cumulative time-page product for the current accounting period. The active function doesn't accept it. -quota returns the terminal quota on each directory. (Default: to return terminal quota and number of pages used) -records_left, -rec_left returns the number of available pages in each quota minus the pages used. If a directory . available pages are computed from the terminal nonzero terminal quota, minus the pages used terminal quota. 3-412 directory, equal to the terminal. has no terminal quota set, the quota on the lowest parent with under that parent with nonzero AG92-06 -records_used, -rec_used returns the number of pages used in each directory. ACCESS REQUIRED You require status perm1SS10n on each directory for which you want quota. Determining the value of -records_left may require access further up the hierarchy. If the requi~ed access is lacking, an error message is printed. NOTES The short form of output (the default) prints the number of pages of quota used by the segments in that directory and in any inferior directories charging against that quota. The output is prepared in tabular format, with a total, when you specify more than one pathname; when you give only one, a single line o( output is printed. The long form of output gives the quota and pages-used information provided in short output. In addition, it prints the logical volume identifier of segments, time-record product in units of record days, and the date you last updated number. Thus, you can see what secondary storage charges your accounts accumulating. If you have inferior directories with nonzero quotas, you need print product for aU these directories in order to obtain the charge. the the this are this NOTES ON ACTIVE FUNCTION Supply only one directory in the active function. The star convention is not allowed. You can specify any of -quota, -records_left, or -records_used; the default is -quota. Name: get_effective_access, gea SYIVTAX AS A CO.fL,11I1AND gea paths {-control_args} SYNTAX AS AN ACTIVE FUNCTION [gea paths {-control_args}] FUNCTION returns the specified user's effective access on the given path (see Section 6 of the Programmer's Reference Manual). 3-413 AG92-06 ARGUMENTS paths are the pathnames of segments or directories for which effective access is to be determined. You can use the star convention. CONTROL ARGUMENTS -in terpret_as_extended_entry , -inaee interprets the selected entries as extended entry types. -interpret_as_standard_entry, -inase interpret the selected entries as standard entry types. -ring RING gets the effective access assuming the user is in the specified ring. user's validation level) (Default: -user USER finds the effective access for USER. You can use the star convention. (Default: user's own User_id) SYNTAX AS A COMMAND FUNCTION prints the current state of the IPS mask for the calling process. CONTROL ARGUMENTS -brief, -bf prints the names of masked signals. nothing. If no IPS signals are masked, it prints -long, -lg prints a more descriptive message about the status of IPS signals, masked or unmasked. (Default) 3-414 AG92-06 NOTES If all undefined IPS signals are either masked or unmasked, they are not mentioned. If, however, some are masked and others are not, an octal list is printed. This can only happen when you have supplied an invalid (probably reinitialized) value in a call to set that mask. Name: get_library_segment, gls SYNTAX AS A COMMAND FUNCTION finds source or object segments in the Multics system libraries and copies them into your current working directory. You can specify which system libraries are to be searched and the order of the search. You can also search for user libraries that may not be organized like the Multics system libraries. (See "Operation" below.) This command has functionally been replaced by library_fetch. ARGUMENTS se&;..names are the nam~ of the segments to be found, including any language suffix. CONTROL ARGUMENTS -brief. -bf does not print pathnames. (Default) -control path. -ct path looks in the directory specified by path to find the control segments. The path argument can be -workin~directory (-wd) to specify the current working directory (see "Operation" below). If -control is not specified. the command looks in the directory >ldd to find its control segments. -long. -lg prints the pathname of the segment from which each segment is copied. -rename new_name, -rn new_name copies the immediately preceding se~name into your process directory and then into a segment in the working directory. Th~ new_name can be an equal name, in which case the equal convention is applied to the se~name; otherwise, the segment created in the working directory is named new_name. The new_name cannot be a pathname. 3-415 AG92-06 -sys lname uses the control segment "lname.control". NOTES If you don't give -sys, get_library_segment uses all the control segments specified in the root directory, whose default is >ldd. For a complete list of the control segments. type list -pn >ldd -all **.control hard standard unbundled auth_maint network languages tools You can give multiple -sys in the same command invocation. If so, all the control segments referenced by the lnames in these arguments are searched. The order in which the control segments are processed and searched is determined by the order in which the lnames appear in the command and the directores referenced by each lname appear in the lname control segment. Control arguments and segment names can be interspersed throughout the command invocation. NOTES ON USER LIBRARIES You can supply -control to extract segments from a user library, causing the command to use a control segment with the pathname path> .control. This allows you to search your own library structure, using your own search procedure or one of the Multics system library search procedures listed below. OPERATION If you don't select -control, gls searches for segments in one or more of the Multics system libraries. From each keyword given in a -sys, it constructs a pathname of the form >ldd> .control. It uses this as the pathname of a control segment. This control segment tells gIs which directories are to be searched and how to search them. Each control segment contains one or more lines of the form directory_path: search_procedure; where directory _path is the absolute pathname of a directory to be searched. 3-416 AG92-06 search_procedure is . the name of a procedure that searches the directory to find seK-name. This name can have the form or segment_name$entry_name For each directory_path specified in the control segment. gls initiates the search_procedure and calls it to search the directory. The calling sequence for search_procedure is declare search_procedure (char(*), char(*), char(*), fixed bin(35»; call search_procedure (directory_path, seg_name, containing_seg, code); where directory_path is the absolute pathname of a directory to be searched. (Input) selL-name is the name of the segment to be found, including any language suffix. (Input) con taininlLseg is the name of the segment in directory_path in which selLname is found. This name 'is either the same as selLname or the name of an archive containing selL-name. (Output) code is a standard storage system status code. (Output) o selL-name is found in directory_path>containinlL-seg 1 selL-name is not found. If code is 0 and the final eight nonblank characters of containinlL-seg are the archive suffix, gls issues the collLmand archive x directory_path>containing_seg seg_name to extract the segment into the current working directory. If you specify -rename for selL-name, the segment is extracted and given the new name. If code is 0 and the final eight nonblank characters of containinlLseg are not the archive suffix, gls calls coPy_selL to copy directory_path>selLname into the current directory, unless you have given a -rename, in which case the segment is copied into directory _path>new _name. 3-417 AG92-Q6 If code is 1, gls continues the search with the next directory _path in the current control segment. If the current control segment contains no more directory_paths. the search continues with the first directory_path in the next control segment you specify. If the segment has not been found after all control segments have been exhausted, gls prin ts an error message and begins searching for the next se~name. If search_procedure returns a code that is neither 0 nor 1, the error message corresponding to the error code is printed and search_procedure continues the search as if code were 1. The get_primary_name_ procedure is used to find segments in the Multics system libraries. If you don't give -sys, gls uses all the control segments in >ldd. EXAMPLES The command line gls abc.p11 -sys tools -sys sss random.alm copies abc.pll and random. aIm from the directories specified in >ldd>tools.control and >ldd>sss.control if they exist gls -sys lang xyz.pl1 -sys os -sys hard searches for xyz.pll in the directories specified by the set of control segments in >ldd. gls gorp.pl1 -rename glop.p11 searches the default group of directories for segment gorp.pll and copies it into your working directory with the name glop.pll. gls fortran_blast_ bound_parse_obind -sys 1ang.o searches for the segment fortran_blast_ and the bind segment bound_parse_.bind in the directories specified in >ldd> lang. o. control. You can use gls to extract a copy of the source program alpha.pll from a private library archive with the command gls -ct >udd>Project_id>Person_id -sys source alpha.pl1 if >udd>Project_id>Person_id>source.control contains the line if alpha.pll is a component of some archive and >udd>Project_id>Person_id>library, having alpha.pll as one of its names. 3-418 segment AG92-06 Name: get_mode SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION FUNCTION extracts the value of a mode from a mode string. ARGUMElviS MODE_STR is a mode string, as used with an I/O module. MODE_NAME is the name of a mode contained in the mode string. NOTES For a boolean mode, the value returned is "true" or "false", otherwise it is the character string value of the mode. Name: get_pathname, gpn SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION [gpn {-control_arg} argJ FUNCTION returns the absolute pathname of the segment designated by a specified reference name or segment number. If the reference name or segment number is not in use, an error message is printed. ARGUMENTS arg is a reference name or octal segment number known to this process. 3-419 AG92~ CONTROL ARGUMENTS -name, -nm indicates that arg (which happens to look like an octal segment number) is to be interpreted as a reference name. If this control argument is not specified, the system assumes arg is a reference name only if arg is not a valid octal number. SYNTAX AS A COMMAND gq {paths} {-control_arg} SYNTAX AS AN ACTIVE FUNCTION [gq {path} {-control_arg}] FUNCTION returns information about the secondary storage quota and pages used by segments. ARGUMENTS paths are pathnames of directories for which you want quota information. If one of the paths is -workin&-directory (-wd), your working directory is used. If you don't supply paths, your working directory is assumed. The star convention is allowed. CONTROL ARGUMENTS -long, -Ig includes the cumulative time-page product for the current accounting period and the corresponding price according to the rate structure of the current process. -nonzero, -nz lists directories with nonzero quota used only. -quota returns the terminal quota on each directory. (Default: to return terminal quota and number of pages used) 3-420 AG92-06 -records_left. -rec_Ieft returns the number of available pages in each quota minus the pages used. If a directory available pages are computed frQm the terminal nonzero terminal quota, minus the pages used terminal quota. directory, equal to the terminal has no terminal quota set, the quota on the lowest parent with under that parent with nonzero -records_used, -rec_used returns the number of pages used in each directory. -sort . sorts directories by the requested quota value or by records used if you request more than one value. The largest value is printed first -total, -tt returns, for quota used, the total quota used by the subtree. Master directories in a subtree are not included in its total. -zero lists directories with zero quota used only. ACCESS REQUIRED You require status permlsslOD on each directory for which you want quota. Determining the value of -records_left may require access further up the hierarchy. If the required access is lacking, an error message is printed. NOTES The short form of output (the default) prints the number of pages of quota used by the segments in that directory and in any inferior directories charging against that quota. The output is prepared in tabuiar format, with a totai, when you specify more than one pathname; when you give only one, a single line of output is printed. The long form of output gives the quota and pages-used information provided in the short output and prints the logical volume identifier of segments, the time-record product in units of record days, and the date you last updated this number; thus you can see what secondary storage charges your accounts are accumulating. If you have inferior directories with nonzero quotas, you need print this product for all these directories to obtain the charge. NOTES ON ACTIVE FUNCTION Supply only one directory in the active function. You can't use the star convention. The active function doesn't accept -long, -nonzero, -sort, and -zero. You can specify any of -quota, -records_left. or -records_used; the default is -quota. 3-421 AG92-{)6 greater SYNTAX AS A COMMAND gssr FUNCTION prints the definitions of set_search_rules command. site-defined search rule keywords acceptable to the NOTES This command prints a list of standard search rule keywords and directories, each one followed by one or more site-defined keywords. If you include a site-defined keyword in the search segment accepted by set_search_rules, the site-defined keyword expands into its definition in the order printed by get_system_search_rules. Name: greater SYfVTAX AS A COMMAND greater STRA STRB SYNTAX AS AN ACTIVE FUNCTION [greater STRA STRB] FUNCTION returns true if STRA is greater than STRB according to the ASCII collating seQuence, otherwise returns false. NOTES The strings are compared character by character according to their ASCII code value: if the first character in each string has the same ASCII code value, compare the second character; if their values are identical, compare the third character; etc. To make numeric comparisons of strings see the descriptions of ngreater and nless. 3-422 AG92-06 hash_table Name: hash_table, ht SYNTAX AS A COMMAND ht path nb FUNCTION used to create a hash table and to insert, delete, and search for entries in it It uses the hash_ subroutine. ARGUMENTS path specifies the name of a segment, which is an existing hash table. nb is the (optional) number of buckets with which the hash table is to be created. If you don't give nb or if it is out of range (0 < nb <= 6552), then a default is assigned to it LIST OF REQUESTS The command operates in response to the following -requests given by you. Each request code must be the first character of the line and followed by one or more arguments separated by any number of blanks (a blank before the first argument is optionaI). a d add delete q s quit search The a Request SYNTAX a namel valuel ••• nameN valueN FUNCTION inserts an entry into the hash table for namei and its corresponding valuei. ARGUMENTS namei is a character string less than, or equal to, 32 characters. 3-423 AG92-06 valuei is a decimal number you associate with namei to indicate its location in the corresponding data table. It can be array subscript The d Request SYNTAX d name 1 ••• nameN FUNCTION deletes the entry namei from the hash table and prints the value it was associated with. ARGUMENTS namei is a character string less than, or equal to, 32 characters. The q Request SYNTAX q FUNCTION returns control to command level. The s Request SYNTAX s namel ..• nameN FUNCTIO/y searches the hash table for namei and prints its corresponding value. You can then locate namei in your data table by using valuei. ARGUMENTS namei is a character string less than. or equal to. 32 characters. 3-424 AG92-06 hash_table NOTES If the hash table ever becomes full or inefficient, the number of buckets is doubled or assigned the maximum, the hash table is rehashed, and a message is printed. SYNTAX AS A COMMAND have_mail mbx_specification {-control_args} SYNTAX AS AN ACTIVE FUNCTION [have_mail {mbx_specification} {-control_args}] FUNCTION returns "true" if there is mail in the specified mailbox. ARGUMENTS mbx_specification specifies the mailbox to be examined. If not given, (>udd>Project_id>Person_id>Person_id.mbx) is used. your default mailbox LIST OF MBX SPECIFICATIONS -log specifies the user's logbox and is equivalent to -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx -mailbox path, -mbx path specifies the pathname of a mailbox. The suffix mbx is added if necessary. -save path, -sv path specifies the pathname of a savebox. The suffix sv.mbx is added if necessary. -user STR specifies either a user's default mailbox or an entry in the system mail table (see "Notes on Mailbox Selection by User" below). STR is any noncontrol argument and is first interpreted as -mailbox STR. If no mailbox is found, it is then interpreted as -save. If no savebox is found, it is then interpreted as -user STR. 3-425 AG92-06 CONTROL ARGUMENTS -interactive_messages, -im returns "true" if there are any interactive messages in the mailbox. (Default) -mail, -ml returns "true" if there is any mail in the mailbox. (Default) -no_in teractive_messages, -nim returns "true" only if there is mail in the mailbox, ignoring whether there are any interactive messages present -no_mail, -nml returns "true" only if there are interactive messages in the mailbox, ignoring whether there is any mail in the mailbox. NOTES ON MAILBOX SELECTION BY USER The user's default mailbox is specified in the form Person_id.Project_id. For an entry in the mail table, STR is usually in the form of Person_id (the mail table is fully described in the Extended Mail System User's Guide, CH23). If STR contains one period and no white space, it is interpreted as a User_id that specifies the user's default mailbox; otherwise, it is interpreted as the name of an entry in the mail table. For example, -user DBuxtehude.SiteSA is interpreted as a User_id that identifies a default mailbox. On the other hand, -user "George G. Byron" -user L.v.Beethoven -user Burns are all interpreted as the names of entries in the mail table: the first because it contains white space; the second because it contains more than one period; the third because it contains no period. «» When interpreted as a User_id, the STR cannot contain any angle brackets and must have the form Person_id.Project_id, where "Person_id" cannot exceed 28 characters and "Project_id" 32 characters. In this case, "-user STR" is equivalent to the mbx_specification -mailbox >udd>Project_id>Person_id>Person_id.mbx. When interpreted as the name of a mail table entry, STR cannot contain any commas, colons, semicolons, backslashes (\), parentheses, angle brackets, braces ({}), quotes, commercial at-signs (@), or white space other than spaces. The query of the mail table is performed in a case-insensitive manner. Use the display_mailin~address command to determine the actual address corresponding to the STR. The address in the mail table must identify a mailbox. 3-426 AG92-()6 ACCESS REQUIRED If you give either -no_interactive,....messages or -no_mail, you must have rs extended access to the mailbox; otherwise, you only need s extended access. EXAMPLES You can use the following statement in your start_up.ec to invoke read_mail only when there is mail present in your mailbox: &if [have_mail -no_interactive_messages] &then read_mail -list Name: have_messages SYNTAX AS A COMMAND have_messages mbx_specification {-control_args} SYNTAX AS AN ACTIVE FUNCTION [have_messages {mbx_specification} {-control args}] FUNCTION returns "true" if there are any interactive messages in the specified mailbox. ARGUMENTS mbx_specification specifies the mailbox to be examined. If not (>udd> Project_id> Person_id> Person_id.mbx) is i:lSed. given, your default mailbox LIST OF MBX SPECIFICATIONS -log specifies the user's logbox and is equivalent to -maiibox >udd>Project_id>Person_id>Person_id.sv.mbx -mailbox path, -mbx path specifies the pathname of a mailbox. The suffix mbx is added if necessary. -save path, -sv path specifies the pathname of a savebox. The suffix sv.mbx is added if necessary. 3-427 AG92-06 -user STR specifies either a user's default mailbox or an entry in the system mail table (see "Notes on Mailbox Selection by User" below). STR is any noncontrol argument and is first interpreted as -mailbox STR. If no mailbox is found, it is then interpreted as -save. If no savebox is found, it is then interpreted as -user STR. CONTROL ARGUMENTS -interactive_messages, -im returns "true" if there are any interactive messages in the mailbox. (Default) -mail, -ml returns "true" if there is any mail in the mailbox. (Default) -no_interactive_messages, -nim returns "true" only if there is mail in the mailbox, ignoring whether there are any interactive messages present. -no_mail, -nml returns "true" only if there are interactive messages in the mailbox, ignoring whether there is any mail in the mailbox. lVOTES ON MAILBOX SELECTION BY USEF? The user's default mailbox is specified in the form Person_id.Project_id. For an entry in the mail table, STR is U$ually in the form of Person_id (the mail table is fully described in the Extended Mail System User's Guide, CH23). If STR contains one period and no white space, it is interpreted as a User_id that specifies a user's default mailbox; otherwise, it is interpreted as the name of an entry in the mail table. For example, -user DBuxtehude.SiteSA is interpreted as a Usei_id that identifies a default mailbox. On the other hand, -user."George G. Byron ll -user L.v.Beethoven -user Burns are all interpreted as the names of entries in the mail table: the first because it contains white space; the second because it contains more than one period; the third because it contains no period. 3-428 AG92-06 «» When interpreted as a User_id, the STR cannot contain any angle brackets and must have the form Person_id.Project_id, where "Person_id" cannot exceed 28 characters and "Project_id" 32 characters. In this case, "-user STR" is equivalent to the mbx_specification -mailbox >udd> Project_id> Person_id> Person_id.mbx. When interpreted as the name of a mail table entry, STR cannot contain any commas, colons, semicolons, backslashes (\), parentheses; angle brackets, braces ({})t quotes, commercial at-signs (@), or white space other than spaces. The query of the mail table is performed in a case-insensitive manner. Use the display_mailin~address command to determine the actual address corresponding to the STR. The address in the mail table must identify a mailbox. ACCESS REQUIRED You must have rs extended access to the mailbox; however if you give-mail but give no -no_interactive_messages, you only need s extended access. SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION [have_queue_entries ms paths] FUNCTION returns "true" if there are messages in the specified queue message segments. ARGUJIIElvTS InS_paths are relative pathnames or star names for queue message segments to be examined. The suffix ms is added if not present You can use the star convention. ACCESS REQUIRED You need s extended access to the queue message segments. EXAMPLES returns "true" if there are any requests in queue 3 of the I/O daemon "x1200" request type. 3-429 AG92-D6 help [have queue entries >udd>idd>printer *] - - - returns "true" if there are any requests in any of the I/O daemon printer queues. Name: help SYNTAX AS A COMMAND he 1P {i nfo_names}' {-contro l_args} FUNCTION prints descriptions of system commands/active functions and subroutines, as well as miscellaneous information about system status, system changes, and general information. The command selects this information from segments maintained online, which are in a special format, called information segments (info segs). ARGUMENTS info_names specify the information to be printed. The suffix .info is assumed. If you supply a pathname, it identifies the info seg to be printed; otherwise help searches for segments matching an entryname using the info_segments search list For subroutines you can include an entry point name in the info_name (e.g., subroutine_Sentry_poind. You can use the star convention except when you specify an entry point name or when you give -entry_point (See "Notes on Star Convention" below.) If you select no info_names, help prints the default info seg (help_system. gi. info) , which gives a brief introduction to the help facility. If help fails to find an info seg corresponding to a given info_name, use list_help to find info segs that contain the specified info_name in their entrynames. LIST OF CONTROL ARGUMENTS BY FUNCTION The control arguments are arranged below functionally. Detailed descriptions follow the list, in the same order. 11/86 3-430 AG92-06A help help Information Selection -all, -a prints entire info without questions. -brief. -bf prints summary of command/active function or subroutine info. -brief_header, -bfhe prints brief heading with info. -control_arg STRs, -ca STRs prints only description of an argument -header, -he prints only a heading line. -list_entry-points, -lep prints entry points. -title prints section titles. Starting Paragraph -search STRs, {-case_sensitive} {-non_case_sensitive} , -srh STRs {-cs} {-ncs} selects by words in paragraph. -section STRs {-case_sensitive} {-non_case_sensitive} , -sen STRs {-cs} {-ncs} selects by section title. Paragraph Grouping -maxlines J sets maximum paragraph grouping size. -minlines I sets minimum paragraph size. Info-Seg Selection -en try_point, -ep selects main subroutine entry point -pathname path, -pn path selects an info segment CONTROL ARGUMENTS FOR INFORMATION SELECTION The following control arguments select the kind of information that help prints. If you specify no control arguments from this group, help prints a long heading line, followed by the first paragraph of info. At the end of each paragraph, help asks you if more help is needed. -all, -a prints the entire info or subroutine entry point 11/87 3-431 desc~iption without intervening questions. AG92-06B help help -brief, -bf prints a brief summary of a command/active function or subroutine info seg with no intervening questions. The summary includes the Syntax section and, for commands/active functions, a list of control arguments and/or other keywords used by the command. -brief_header, -bfhe prints a brief heading line (which consists of the heading and line count), followed by either information selected by the other information selection control arguments or by the first paragraph if you specify no other control arguments from this group. -case_sensitive, -cs when used with either -section or -search. performs the requested action in a case-sensitive manner. -control_arg STR, -ca STR prints only the descriptions of the control (or other) arguments whose names contain STR. STR must not include a leading minus sign (-). For example, help mail -ca brief match exclude prints descriptions of the -brief, -match and -exclude control arguments of the mail command. All arguments following -ca until the next control argument are treated as STR. -header, -he prints only a long heading line consisting of the pathname of the info seg, heading, and line count It conflicts with an other information selection control arguments. (Default) -list_entry_points, -lep lists the entry points in a subroutine info segment -non_case_sensitive, -ncs when used with either section or search, performs the requested action in a non-case-sensitive manner. This is the default -title lists the section titles used in the info seg (including section line counts), then asks if you Wish to see the first section. The -all, -brief, -control_arg, and -title control arguments are mutually exclusive. CONTROL ARGUMENTS FOR SELECTING A STARTING PARAGRAPH Normally, help begins printing the first info paragraph. The control arguments below can select a particular section and/or paragraph at which printing is to start 11/87 3-432 AG92-06B help help -seareh STRs {case_sensitive} {-non_ease_sensitive} • -srh STRs {-cs} {-ncs} begins printing with the first paragraph containing STRs. All the strings must appear in the selected paragraph, but they can appear in any order. You can type STRs in lowercase since case is ignored when matching, unless -es is specified. All arguments and control arguments following -srh are treated as STRs, so should be put -srh at the end of the command line. An exception is that if -cs or -ncs is the last argument of the string, it will be interpreted as a control argument and not one of the STRs. The search usually begins with the first paragraph, but when you also specify -scn it begins with the matching section and continues to the last paragraph (i.e.. without wraparound). -section STRs {-case_sensitive} {-non_ease_sensitive}, -sen STRe; {-cs} {-ncs} begins printing the section whose title contains STRs. The entire section title is not required. The first section whose title matches STRs is selected. You can put STRs in any order in the section title. You can type them in lowercase since case is ignored during matching operations, unless -cs is specified. All arguments following -sen until the next control argument are treated as STRs. When you supply =srh or -sen and no matching paragraph is found in any of the info segs selected by an info_name or info seg selection control argument, that info seg is passed over without comment Thus, the starting-paragraph control arguments serve as a secondary info selection mechanism. You can use the control arguments from this group with any of the information selection control arguments, but their effect differs depending upon which of them are used. When -srh or -sen is used with -he, help prints the heading lines, not the matching paragraph. for infos containing a matching paragraph. When you use them with -bf or -ca, help prints a heading line and then the information selected by -bf or -ca; the matching paragraph is not printed. \Vhen -srh or -sen is used with the -cs control argument, help will print only exact matches. If the -ncs control argument is used. help will match to both uppercase and lowercase values. The default is -nes. When you use -srh or -sen with -bfhe, help prints a brief heading line preceding the matching paragraph. When you use them with -title, help prints a heading line, then the list of section titles, and finally the matching paragraph. When you use them with -a, the entire info is printed for infos containing a matching paragraph. CONTROL ARGUMENTS FOR PARAGRAPH GROUPING The following control arguments determine how much information help prints before asking if you want to see more. -minlines I sets the minimum paragraph size to I lines. Paragraphs smaller than this size are printed with preceding paragraphs. (Default: 4) 11/87 3-432.1 AG92-o6B help help -maxlines J sets the maximum paragraph grouping size to J lines. (Default: 15) Paragraphs that you have seen are not grouped with unseen paragraphs. Paragraphs at the end of one section are not grouped with those beginning another section. Paragraphs are not grouped when you give -srh or -sen. CONTROL ARGUMENTS FOR SELECTING INFO SEGS -entry_poin t, -ep selects the info describing the main entry point of a subroutine. For example, help ioa_ -ep prints the info describing the ioa_$ioa_ subroutine entry point. When you omit -ep and specify no entry point name by an info_name identifying a subroutine info segment~ help prints the info describing the general purpose of the subroutine. -pathname path. -pn path specifies the pathname of a segment containing the info seg to be printed. It is useful when the info to be printed is in your working directory or when the pathname begins with a minus sign. For subroutines you can include an entry point name with the final entryname of path; f or example, A suffix of .info is assumed if you give none. You can use the star convention except when you give an entry point name or -ep. (See "Notes on Star Convention.") LIST OF RESPONSES The responses accepted when help questions you are given in the list below. Those responses that search the info seg or list section titles operate from the current paragraph to the end of the info seg. No wraparound feature is employed. prints "help" to identify the current interactive environment. .. command_line passes the remainder of the response to the Multics command processor as a command line. ? prints a list of available responses. brief, bf prints a summary of a command/active function or subroutine info seg, including the Syntax section and a list of control arguments. then repeats the previous question. 11/87 3-432.2 AG92-G6B help help control_arg SIR, ca SIR prints descriptions of control (or other) arguments whose names contain SIR, then repeats the previous question. entry_point {EP_NAME}. ep {EP_NAME} skips to the description of subroutine entry point EP_NAME. You can specify EP_NAME as entry_point_name or subroutine_$entry_point_name; if you omit it, help skips to the description of the subroutine_$subroutine_ entry point if one exists. header, he prints a long heading line to identify the current info seg. The line consists of the pathname of the info seg, heading, and line count. list_en try_points, lep lists the entry points in a subroutine info segment list_requests {STRs}, lr {STRs} prints information about available help requests. no, n exits from the current info seg, and begins printing the next info seg selected by inio_names given in the help command; returns from the help command if all selected info segs have been printed. quit, q causes the help command to return without printing the remaining info segs selected by the info_names. rest {-scn} {-all_entrypoints}, r {-sen} {-aep} prints the rest of the info seg without intervening questions. If you choose -sen, help prints only the rest of the current section without questions. When the section has been printed, help then asks whether you want to see the next section. If -all_entrypoints is specified, help will print the rest of the remaining entry points. search {STRs} {-top} {-case_sensitive} {-non_case_sensitive}, srh {STRs} {-tJ {-cs} {-ncs} skips to, and prints, the next paragraph containing STRs. Paragraph selection is performed as described above for -srh. If you give -t, searching starts at the beginning of the info seg. If the -cs argument is used, the search will be case-sensitive and find only exact matches. If -ncs is used, the search will match both uppercase and lowercase values. The default is -ncs. If STRs are omitted, help uses the strings from the previous search response or -srh. If the search fails, help prints the message: No matching paragraph found. and repeats the previous question. 11/87 3-432.3 AG92-06B help help section {STRs} {-top} {-case_sensitive} {-non_ease_sensitive} , sen {STRs} {-tJ {-cs} {-ncs} skips to the next section whose title contains STRs. Title matching is performed as described above for -sen. If you supply -t, title searching starts at the beginning of the info. If you omit STRs, help uses the search strings from the previous section response or -sen. If the -cs argument is used, the search will be case-sensitive 3.J."1d find only those section titles that are exact matches. If the -ncs argument is used, help will match both uppercase and lowercase values. The default is -ncs. If the search fails, help prints the message: No matching section found. and repeats the previous question. skip {-section} {-rest} {-seen} {-entry_point}, s {-sen} {-r} {-seen} {-ep} skips the next paragraph and asks whether you want to see the paragraph following it If you select -sen, help skips all paragraphs of the current section. If you supply -r or -ep, help skips the rest of this info seg or subroutine entry point description, continuing with the next. If you give -seen, help skips to the next paragraph that you haven't seen. You can use only one of these control arguments at a time. title {-top}, title {-t} lists titles and line counts of an sections remaining in the current info seg. If you specify -t, help lists all section titles. top, t skips to the beginning of the info seg, prints the heading line, and asks whether you want to see the first section. This is useful if you wish to review earlier parts of the info seg. yes, y prints the next paragraph of information, then asks whether you want more help. This command remembers which paragraphs you have seen and which you have skipped or not yet reached. It asks you to "Review" paragraphs seen before and asks if "More help" is needed for unseen paragraphs. It stops printing if you have seen all paragraphs when you reach the end of the info. If you skipped any paragraphs, however, help asks if you want to see them; if you answer "yes," the first unseen paragraph is printed. You can then answer "skip -seen" to view subsequent unseen paragraphs. The question/answer dialogue continues until all the information is printed or you reply "no." CONTENTS OF INFO SEGS Each segment contains one or more blocks of information that describe a particular command/active function, subroutine, or topic. To validate the format of info segs, use validate_inf 0 _seg. An info seg begins with a heading line, consisting of a date on which it was last modified and a brief title identifying it For command/active function info segs the program name, including any short name, is used as the title; for subroutine info segs the subroutine name is used. 11/87 3-432.4 AG92-06B help help Information in an info seg is divided into paragraphs, separated from one another by two blank lines. The help command uses this separation to determine where one paragraph ends and the next begins. Each paragraph contains a logically complete unit of information. Control arguments and responses are available to search for, and print, a particular paragraph. To avoid printing unnecessary information when you perform such searches, paragraphs are short (1 to 15 lines long) and deal with only a single subject. The paragraphs describing a given topic are grouped together into a section. The first paragraph of each section begins with a title that names the topic described in that section. Section titles are short, usually consisting of one or two words followed by a colon (:). Standard section titles are used in info segs provided with the MuItics system so that users can search for a particular information topic. For command/active function info segs the standard section titles in their proper order are: Syntax As a Command: shows how the program is invoked. Arguments are given a generic name (c.g., paths indicates that one or more pathnames are allowed). Optional arguments are shown in braces (e.g., {paths}). If the program allows control arguments, they are shown as -control_args in the syntax line. Function: gives a brief description of what the program does. Arguments: gives a brief description of each argument Control Arguments: gives a brief description of each control argument. Notes: gives comments, clarifications, or any special-case information. The descriptions of arguments and control arguments are formatted in a special way so that "help -bf" can print a list of all argument and control argument names (t.nd "help -ca" can find and print the description of an individual argument or control argument. Each description begins with a line naming the argument or control argument, including the short name, and any operands it requires. This naming line begins in column 1. The description continues on subsequent lines by defining the meaning and function of the argument or control argument. These lines are indented three spaces from the left margin. Subroutines are described by info segs containing a series of specially formatted information blocks, one describing each subroutine entry point The first block describes the general purpose of the subroutine and can include control information and notes common to all entry points. It includes the following sections: 11/87 3-432.5 AG92-06B help help Function: describes the overall function performed by the subroutine. The heading is optional, the description is not Entry points in SUBROUTINE: causes help to list the entry points definoo in the subroutine. Precede this line by two blank lines and make it the last line (followed by two blank lines) before the first entry point description. Entry point descriptions are separated from the first block and each other by the following line: :Entry: yyy: 12/07/86 SUBROUTINE_$ENTRYPOINT The date is the date-last-modified. Use of -ep causes help to search through these lines for a ENTRYPOINT matching STR. Always precede this line by two blank lines. Section titles in their standard order for subroutine entry point descriptions are as follows: Function: gives a brief description of what the entry point does. Usage: gives the PL/I declare and call statements fer the entry point A sample description from the cu_$arLcount entry point follows: Usage: declare cu_Sarg_count entry (fixed bin, fixed bin (35»; call cu_Sar9_count (nargs, code); Arguments: lists the arguments shown in the call statement along with a brief description of their functions. Notes: are general notes t.ltat apply to the entry point. To keep info segs concise, avoid tutorial notes and examples except in special cases. NOTES ON SEARCH LIST The help command uses the "info_segments" (or "info_segs" or "info") search list The default info seg directories contain info segs provided by your site and those supplied with the system. Type "print_search_paths info_segments" to see what the current info segments search list is. For more information about search lists, see the search facility commands, especially add_search_paths. 11/87 3-432.6 AG92-o6B help help NOTES ON STAR CONVENTION When you use the star convention, help performs the following steps: 1. The info segs whose entrynanles match any of the star names are alphabetized within their directory and scanned in that order. 2. When you give -srh and -scn help scans the matching info seg until the desired paragraph and/or section is found. If a matching paragraph is found, help prints it, then asks you whether to print remaining paragraphs. Any section and search responses given at this point scan only the current info seg. If a matching paragraph is not found in one of the info segs selected by a star name, that info seg is passed over without comment. Thus, it is possible to scan all info segs and print only those containing certain section titles or certain words. 3. When you supply no --srh and -sen, help begins printing the first paragraph of each info seg that matches any of the starnames. Then help asks you whether to print the remaining paragraphs. 4. The -a, -bf. -ca, and -title control arguments apply to each info seg selected by the starnames and -srh/-scn string matching. Section titles, a brief summary, or particular control argument descriptions are printed before the matching paragraph. When you combine -a with -srh or -sen, the entire info seg selected by the string matching is printed without questions. 5. The no, rest, skip, and yes responses operate on the next selected paragraph. This paragraph can be the first paragraph of the next selected info seg or even the first paragraph that matches the -srh and -sen cri teria in the next selected info seg. 6. If you issue a quit signal, you can use program_interrupt to reenter the interactive help environment The question asked prior to the quit is repeated. INFO SEG NAMING CONVENTIONS Info segs for .M:ultics commands/active functions and subroutines are given the name of the particular system module with a suffix of .info. For example, the info describing the PL/I compiler command is called pll.info. Information about changes made to a command/active function from one release to the next are given the name of the particular system module with a suffix of .changes.info. For example, changes to the FORTRAN compiler are described in fortran.changes.info. General information describing features or use of the system is included in info segs whose names end with a suffix of .gi.info. For example, acl_matching.gi.info describes how access control list entries are matched with User_ids in access control commands such as set_ac!. More than 800 info segs are available online. To find information about a particular area of the system, use list_help or -he with an entryname containing stars to list the names of available infos. 11/87 3-432.7 AG92-06B hexadecimal help USER-CREATED INFO SEGMENTS You can create info segs describing your own commands. exec_coms, and application programs. To create proper info segs see "Contents of Info Segs" above. N arne: hexadecimal, hex SYNTAX AS A COMMAND hex va1ues SYNTAX AS AN ACTIVE FUNCTION [hex va1ues] FUNCTION returns one or more values in hexadecimal. ARGUMENTS value is a value to be processed. The last character of the value indicates its type. Acceptable types are binary (b), quaternary (q), octal (0), hexadecimal (x). or un spec (u). Any valid PL/I real value is allowed. The absence of any specifier means decimal. The unspec value is limited to eight characters. EXAMPLES string [hex 3770J ff hex abcu 184c463 11/87 3-432.8 AG92-06B history _comment high Name: high SYNTAX AS A COMMAND high N SYNTAX AS AN ACTIVE FUNCTION [high N] FUNCTION returns a specified number of copies of the last (highest) character in the ASCII character set, the PAD character of 177 octal. Name: high9 SYNTAX AS A COMMAND high9 N SYNTAX AS AN ACTIVE FUNCTION [h i gh9 NJ FUNCTION returns a specified number of copies of the last (highest) 9-bit bit pattern, 777 octal. Name: history _comment, hcom SYNTAX AS A COMMAND hcom operation path {args} {-control_args} SYNTAX AS AN ACT IV E FUl'./CT I ON [hcom oper a t i on path {args} {-contra l_args} ] FUNCTION adds, checks. displays. formats. and updates software change history comments within a given source module. 11/87 3-432.9 AG92-06B history _comment history _comment ARGUMENTS operation designates the operation to be performed. path is the name of a source code program that requires history comments. Include the language suffix. args are optional arguments appropriate to the particular operation to be performed. CONTROL ARGUMENTS are optional control arguments that vary, depending on the particular operation to be performed. . HISTORY COMMENT FORMAT Following is a PL/I history comment example. Other languages will have different comment delimiters. I**A 1) 2) HISTORY COMMENTS: change(8S-0S-12, OOppenheimer), approve (8S-0S-2S, MCR23SS), audit (8S-0S-26, EBlau), install (85-05-30, MRll.0-3382): Increased size of test array to el iminate subscript error. change (8S-0S-28, MLee)~ approve (85-05-29 MCR2356), audi t (85-06-05, TYoffe) ~ install (85-06-10~ MRll.0-3384): Added the -brief and -long control arguments. END HISTORY COMMENTS I NOTE: To determine if prior history comments exist in the module, the source module is checked for a line containing the history comment block beginning, i.e., a line beginning with the appropriate comment delimiter and "HISTORY COMMENTS:". If found, the program then checks for the history comment block ending. i.e., a line containing "END HISTORY COMMENTS." LIST OF HISTORY COMMENT FIELDS The fields within a given history comment are identified as follows: NO) change (CHANGE DATE, CHANGE PERSON 10), approve (APPROVE_DATE, APPROVE_IO): audit (AUDIT DATE, AUDIT PERSON 10), instal 1 (INSTALL_DATE, INSTALL_TO): SUMMARY 11/87 3-432.10 AG92-06B history _comment history _comment The fields in a history comment are named as described below. The sample validation routine hcom_default_validate_ validates field formats used by the Multics Development Center as described below. Each site, however, can provide its own validation routines to tailor the contents of the user-settable field values. NO is the number of the history comment. Comments are numbered sequentially in chronological order, starting with 1. (Supplied by hcom) CHANGE_DA TE is the date (yy-mm-dd) on which the history comment was first added to the source module. (Supplied by hcom) CHANGE_PERSON_ID is the Person_id. of whoever added the history comment. (Supplied by hcom) APPROVE_DATE is the date (yy-mm-dd) on which an approval value was supplied for a history comment. (Supplied by hcom) APPROVE_ID is the identifier authorizing the change. The default validation routine expects an identifier in the form "TYPEnnnn" for Multics change requests (MCRs), post-installation bug fix (PBFs) associated with MCRnnnn, or Multics emergency change request (MECRs) (e.g., MCR6734, PBF6734, MECR0102). For critical fixes the identifier should be in the form of fix_nnnn or fix_nnnn.ds. The maximum length of this field is 24 characters. (Supplied by user) AUDIT_DATE is the date (yy-mm-dd) audit field added to the history comment. (Supplied by hcom) AUDIT_PERSON_ID is the Person_id of whoever audited the source module. (Supplied by hcom) INST ALL_DATE is the date (yy-mm-dd) install field added to the history comment. (Supplied by hcom) INSTALL_ID is the value identifying either a specific installaiion or the installer of a critical fix. The default validation routine expects an identifier in the form "MRrel-nnnnn", consisting of a release number and installation sequence count (e.g., MR12.0-00234). For a critical fix the validation routine expects a Person_id naming the person who installed the fix. The maximum length of this field is 24 characters. (Supplied by user) SUMMARY is a brief description of the change made to the module. This field contains text (up to 2000 characters) and is not validated. (Supplied by user) 11/87 3-432.11 AG92-Q6B history _comment history _comment NOTES The following is a typical usage pattern expected for the various operations of the command: • You make a change to the source module. You can add a new history comment by hand (perhaps using an Emacs extension to prompt for field values). Or, after adding the change, you can use the hcom add operation to add a new comment. A typical command line might be hcom add prog.pl1 • You may not have had approval for the change at the time the history comment was added. When approval is gained, you can use the hcom add_field operation to add the approve field. For example, hcom af prog.pll -approve MCR7235 • You can display the history comments in a program or even compare the comments in a modified version of a program with those in the library copy of the program. For example. hcom display prog.pll new -orig [lpn prog.pl1] displays the new history comments in the source module, while hcom compare prog.pii -orig [ipn prog.pii] displays the differences between the source module and the original module. • When the change is aUdited, the auditor uses the hcom add_field operation to supply an audit field for all new or incomplete history comments. For example. hcom af prog.pll -audit • When you are ready to submit the change for installation, you use the hcom check operation to ensure that all comment fields except the install field have been supplied in each changed module. Since you have a site-defined validation routine called hcom_site_validate_ in your object search rules. this routine is used to fully validate the fields of all comments. hcom check prog.pl1 -orig [lpn prog.pll] • When the installer receives the modules in an installation, he uses the hcom install operation to ensure that new history comments describing the changes are present. This operation also adds an identifier to each new comment. indicating in which installation it was installed. The installer can use a special library-defined validation routine to perform special field validations. Here, the library validation routine is called hcom_mdc_validate_: hcom install prog.pl1 -vdt hcom mdc validate -install MR12.0-0023 -orig [lpn prog.pl1]- 11/87 3-432.12 AG92-o6B history _comment history _comment VALIDATION ROUTINE CALLING SEQUENCE A site can define a site-wide history comment validation routine to validate the contents of the APPROVE_ID and INSTALL_ID fields of history comments. This routine is called hcom_site_validate_. If it is found in your object search rules. hcom uses this validation routine instead of using hcom_default_validate_. The -validate control argument allows use of a user-supplied validation subroutine, which can have any name, to validate the APPROVE_ID and INST ALL_ID fields. The calling sequence of both the hcom_site_ validate_ subroutine and user-written routines is shown below. dcl hcom site validate entry (charO var, charO var, char() var, bit(l)~charO var, charO var, char(100) var); call hcom site validate (caller, field name, input value, result_bit, canonical_value, field_type, error_msg); where: caller is the name of the calling program on whose behalf the validation routine should report' errors, ask questions, etc. (Input) iield_name is the name of the field being validated. It can have a value of either APPROV AL_FIELD_NAME or INST ALL_FIELD_NAME. These named constants are declared in hcom_field_names.incl.pll. (Input) input_value is the field value you supply. (Input) result_bit is either "l"b if the input value is valid or "O"b if the input value is invalid. (Output) canonical_ value is the canonical text form of the field_name and input_value. (Output) .... 1Al~ J. hrn.o. J."'U'~_"J t""' is the canonical text form of the field_name for use in error messages. (Output) error_msg is the text of the error message. (Output) 11/87 3-432.13 AG92-06B history _comment history _comment Operation: add SYNTAX AS A COMMAND hcom add path {-control_args} FUNCTION adds a new history comment to the requested module. The summary field is required; all other fields are optional. ARGUMENTS path is the name of a source code program that requires history comments. Include the language suffix. You can give an archive pathname. CONTROL ARGUMENTS FOR FIELD INPUT -approve APPROVE_ID, -apv APPROVE_ID specifies the APPROVE_ID field. The maximum length of this field is 24 characters. (See "List of History Comment Fields" above for a description of valid APPROVE_IDs.) -fill, -fi sets fill mode on for the summary field. In fill mode text, words are moved from line to line in such a way that the last word does not extend past the right margin. (Default) -input_approve, -iapv prompts for an APPROVE_ID. This is a single-line field value. (Default) -input_install, -iin prompts for the INSTALL_ID. This is a single-line field. -input_summary, -ism prompts you for the summary field. This is a multiline field. (See "Notes" below.) (Default) -install INST ALL_ID, -in INSTALL_ID specifies an identifier associated with installing the changed module into execution libraries. See "List of History Comment Fields" above for a description of valid INSTALL_IDs. The maximum length of this field is 24 characters. -no_approve, -napv specifies that an APPROVE_ID is not being entered. -nofill, -nfi sets the fill mode off for the summary field. 11/87 3-432.14 AG92-06B history_comment history_commen t -no_install. -nin suppresses the prompt for INSTALL_ID. (Default, since the installation ID is usually specified when the module is being installed rather than when the history comment is first added) -summary TEXT. -sm TEXT gives text describing the change. Enclose the text within quotes if it contains spaces. quotes, parentheses. etc. CONTROL ARGUMENTS -critical_fix. -cfix specifies that critical-fix history comments are allowed in the program. All comments following the first that contains critical-fix field values must also contain critical-fix field values. -validate RTN, -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint name acceptable to cv_entry _. If you give no -vdt, the default is to validate using the hcom_site_validate_ subroutine, if your site has provided it, or the hcom_default_ validate_ subroutine provided with hcom. NOTES For multiline fields all input is treated as text until reading a line with just a period. Input lines beginning with n •• " are treated as Multics command lines, rather than as part of the field value. After the command line is executed. you can continue answering the prompt or can replace input text typed so far with a new answer. Optional field values answered with a period omit the field from the history comment. For single-line fields, input ends when you type a carriage return. If the input line begins with .... ", the text that follows is treated as a Multics command line. After the command line is executed, you are prompted again for the question. Optional field values answered with a carriage return omit the field from the history comment. Operation: add_field, af SYl·.jTAX AS A COIIIIIIAND hcom af path {comment_specs} {-control_args} FUNCTION inserts missing fields in selected comments. 11/87 3-432.15 AG92-Q6B histo,ry _comment history _comment ARGUMENTS path is the name of a source code program that requires history comments. Include the language suffix. You can give an archive pathname. comment_specs specify which history comment(s) are to be updated. (See "List of Comment Specifiers" below.) (Default: to select comments that are missing the fields given by the "Control Arguments for Field Input") CONTROL ARGUMENTS FOR FIELD INPUT -approve APPROVE_ID. -apv APPROVE_ID inserts the missing APPROVE_ID field. The maximum length of this field is 24 characters. (See "List of History Comment Fields" above for a description of valid APPROVE_IDs.) -audi t, -aud inserts the user's Person_id in the AUDIT_PERSON_ID field. -input_approve, -iapv prompts for a new APPROVE_ID. This is a single-line field value. (Default, if you give no . field input control arguments) -input_install. -iin prompts for the INSTALL_ID. This is a single-line field. -install INSTALL_ID. -in INST ALL_ID specifies an identifier associated with installing the changed module into execution libraries. The maximum length of this field is 24 characters. (See "List of History Comment Fields" above for a description of valid INSTALL_IDs.) -no_approve. -napv does not replace the APPROVE_ID field nor prompts for missing approve fields. (Default, if you supply any field input control arguments) -no_aUdit, -naud does not add the AUDIT_PERSON_ID field. (Default) -no_install, -nin does not set the INST ALL_ID field nor prompts for missing install fields. (Default) CONTROL ARGUMENTS -critical_fix, -cfix specifies that critical-fix history comments are allowed in the program. All comments following the first that contains critical-fix field values must also contain critical-fix field values. 11/87 3-432.16 AG92-06B history_comment history_comment -validate RTN. -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint name acceptable to cv_entry_. If you give no -vdt, the default is to validate using the hcom_site_validate_ subroutine, if your site has provided it, or the hcom_default_validate_ subroutine provided with hcom. LIST OF COMMENT SPECIFIERS 1, I:J selects the comment(s) by a comment number or a range of numbers. You can use the keywords "first" (f) and "last" 0) to identify the first and last comments. all, a selects all comments. approved, apv selects comments that have an approve field. audi ted, aud selects comments that have an audit field. complete, cpt selects comments that include all fields. incomplete. icpt selects comments that are missing the approve, aUdit. or install field. installed, in selects comments that have an install field. new selects. when you give -original. comments that do not appear in the original (eailier) version of the program. old selects. when you give -original. comments that appear in both the original and new versions of the program. unapproved. unapv selects comments that do not have an approve field. unaudited. unaud selects comments that do not have an audit field. uninstalled. unin selects comments that do not have an install field. 11/87 3-432.17 AG92-06B history _ commen t history _comment NOTES If you provide no control args, the default is to print selected history comments and to prompt you for missing approve fields. Operation: check, ck SYNTAX AS A COMMAND hcom ck path {-control_args} SYNTAX AS AN ACTIVE FUNCTION [hcom ck path {-control_args}] FUNCTION looks for one or more incomplete (or new if you give -original) history comments and verifies that their summary, approve, and audit fields are given while the install field is missing. The active function returns true if the check succeeds (the history comments are ready for submission). false otherwise. ARGUMENTS path is the name of a source code program that has history comments. Include the language suffix. You can give an archive pathname. CONTROL ARGUMENTS -errors, -er displays history comments that failed check. (Default) -no_errors, -ner suppresses display of history comments that failed check. (Default, for the active function) -original oris-path, -orig oris-path specifies that the current version of the source program is to be cross-checked with an earlier version (given as oris-path) to ensure that there are new history comments in the current module. You can give an archive pathname and use the equal convention. (Default: to check for incomplete history comments in the given source program) -validate RTN, -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint name acceptable to cv_entry_. If you give no -vdt. the default is to validate using the hcom_site_validate_ subroutine, if your site has provided it, or the hcom_default_validate_ subroutine provided with hcom. 11/87 3-432.18 AG92-06B history_comment history_comment NOTES The presubmission check is run by developers to ensure that at least one history comment has been added to describe modifications to the source module. These history comments will be incomplete because they will not have an install field. Supply all other fields prior to submission. Operation: compare, cmp SYNTAX AS A COMMAND hcom cmp path -control_args SYNTAX AS AN ACTIVE FUNCTION [hcom cmp path -control_args] FUNCTION displays any diff erences between the source module and the original module. The active function returns true if the comments in the source and original modules are identical, false otherwise. ARGUMENTS is the name of a source code program that has history comments. Include the language suffix. You can give an archive pathname. CONTROL ARGUMENTS -original oriLpath, -orig oriLpath specifies the pathname of an earlier version of the module. You can give an archive pathname and use the equal convention. (Required) -validate RTN. -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint name acceptable to cv_entry_. If you give no -vdt. the default is to validate using the hcom_site_validate_ subroutine, if your site has provided it, or the hcom_default_validate_ subroutine provided with hcom. Operation: display, cis SYNTAX AS A COMMAND hcom ds path {comment_specs} {-control_args} 11/86 3-432.19 AG92-06A FUNCTION displays selected history comments. Optionally, compares history comments in a program with those in an earlier version of the program, displaying old comments (which appear in both versions) or new comments (which do not appear in the earlier version). ARGUMENTS path is the name of a source code program. Include the language suffix. You can give an archive patbname. comment_specs select which history comment(s) to display. (See "List of Comment Specifiers" under the add_field operation.) (Default to display new comments if you specify -original or all comments if you omit -original) CONTROL ARGUMENTS -original orilLpath, -orig orilLpath specifies the patbname of an earlier version of the module. archive patbname and use the equal convention. You can give an -validate RTN, -vdt RTN validates user-supplied fields in Lie history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint name acceptable to cv_entry_. If you give no -vdt, the default is to validate using the hcom_site_validate_ subroutine, if your site has provided it, or the hcom_default_validate_ subroutine provided with hcom. Operation: exists SYNTAX AS A COMMAND hcom exists path {comment_specs} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [hcom exists path {comment_specs} {-control_args} FUNCTION prints or returns true if any history comments matching all the comment_specs are found in every selected module, false otherwise. 11/86 3-432.20 AG92-06A history_comment ARGUMENTS path is the name of a source code program that has history comments. Include the language suffix. You can give an archive pathname. comment_specs select which history comment(s) to print (See "List of Comment Specifiers" under the add_field operation.) (Default: "all," to check whether any comments exist in the source module) CONTROL ARGUMENTS -original oris-path, -orig oriS-path specifies the pathname of an earlier version of the module. You can give an archive pathname and use the equal convention. -validate RTN, -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint name acceptable to cv_entry_. If you give no -vdt. the default is to validate using the hcom_site_validate_ subroutine, if your site has provided it, or the hcom_default_validate_ subroutine provided with hcom. Operation: format, fmt SYNTAX AS A COMMAND hcom fmt path {comment_specs} {-control_args} FUNCTION reformats selected history comments in a program, including putting date fields into standard "yy-mm-dd" format, filling lines of all COII'~1!lent entries to a 79-character width, validating field values, etc. ARGUMENTS path is the name of a source code program whose history comments are to be reformatted. Include the language suffix. You can give an archive pathname. comment_specs select which history comment(s) to reformat (See "List of Comment Specifiers" under the add_field operation.) (Default: "all," to check whether any comments exist in the source module) 11/86 3-432.21 AG92-D6A hist-Ory_comment history_comment CONTROL ARGUMENTS -fill, -fi sets fill mode on f or the summary field. In fill mode text, words are moved from line to line in such a way that the last word does not extend past the right margin. (Default) -nofill, -nfi sets the fill mode off for the summary field. -no_renumber, -nrnb . prints an error if history comment numbers are out of sequence. (Default) -renumber, -rnb specifies that the history comments within the current module can be renumbered if they are out of sequence. -validate RTN, -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint name acceptable to subroutine cv_entry_. If you give no -vdt, the default is to validate using the hcom_site_validate_ subroutine, if your site has provided it, or the hcom_default_validate_ subroutine provided with hcom. Operation: get SYNTAX AS A COMMAND hcom get path comment_specs -control_args SYNTAX AS AN ACTIVE FUNCTION [hcom get path comment_specs -control_args] FUNCTION prints or returns given field values from selected history comments. ARGUMENTS path is the name of the source code program whose history comments fields are to be returned. Include the language suffix. You can give an archive pathname. comment_specs specify from which history comment(s) field values are extracted. Give at least one specifier. (See "List of Comment Specifiers" under the add_field operation.) 11/86 3-432.22 AG92-06A history_comment history_comment CONTROL ARGUMENTS -field_name FIELDS, -fn FIELDS specify which fields from the selected history comments are to be returned or printed. All arguments following -fn up to the first argument that begins with a hyphen are considered field names. See "List of Field Names" below. (Default to return or print all fields of matching entries) -original ori~path, -orig ori~path specifies the pathname of an earlier version of the module. You can give an archive pathname and use the equal convention. -validate RTN, -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint name acceptable to cv_entry_. If you give no -vdt, the default is to validate using the hcom_site_validate_ subroutine, if your site has provided it, or the hcom_default_validate_ subroutine provided with hcom. LIST OF FIELD NAMES You can supply the following values with -fn to specify which field to return. approve_date, apvdt is the date on which the approve field was entered. approve_id, apvi is the identifier from the approve field. audit_date, auddt is the date on which the audit field was entered. audit_person_id. audpi is the Person_id of whoever audited the source module. change_date, edt is the date on which the history comment was first entered. change_person_id, cpi is the Person_id of whoever entered the history comment instaH_date, indt is the date on which the install field was entered. install_id, ini is the identifier from the install field. summary, sm is the summary field from the history comment 11/86 3-432.23 AG92-D6A NOTES If several history comments are selected, specified fields from the first selected comment are returned or printed, followed by fields from the second selected comment, etc. If the selected field is not present in a given history comment, then a null string is returned for that field Multiline field values are returned in a single line (with newline characters replaced by a space) as a quoted string. Operation: install SYNTAX AS A COMMAND hcom install path -control_args SYNTAX AS AN ACTIVE FUNCTION [hcom install path -control_args] FUNCTION performs a preinstallation check on modules being installed, as specified by system integration personnel. It performs a variety of steps, including checking that new history comments exist and are properly filled in. If the check succeeds, an installation 10 is placed in the comment The active function returns true if the check succeeds (the history comments are ready for installation), false otherwise. ARGUMENTS path is the name of a source code program that requires history comments. Include the language suffix. You can give an archive pathname. CONTROL ARGUMENTS FOR FIELD INPUT -approve APPROVE_IO, -apv APPROVE_IO specifies the APPROVE_IO field to be assigned to all history comments that are missing an approve field. An error occurs if you give -apv but no comments are missing the approve field. (See "List of History Comment Fields" above for valid APPROVE_IDs.) This control argument is used when only the installer knows what the approval identifier is; e.g., only he knows what the MECR number is because this number is assigned at installation time. The maximum length of this field is 24 characters. If the AUDIT_DATE and AUDIT_PERSON_IO fields are missing when you use -apv, an error message is issued but processing continues. -input_approve, -iapv prompts for an APPROVE_IO. This is a single-line field value. -input_install, -Un prompts for the installation identifier. (Default) 11/86 3-432.24 AG92-06A -install INSTALL_ID, -in INSTALL_ID specifies an identifier associated with installing the changed module into execution libraries. This identifier is placed in all history comments that are missing the install field. An error occurs if every comment has an install field. See "List of History Comment Fields" above for valid INSTALL_IDs. The maximum length of this field is 24 characters. -no_approve. -napv specifies that an APPROVE_ID is not being entered. (Default) CONTROL ARGUMENTS -critical_fix. -cfix specifies that critical-fix history comments are allowed in the program. All comments following the first that contains critical-fix field values must also contain critical-fix history comments. -errors. -er displays history comments that fail the installation checks. (Default) -no_errors. -ner suppresses display of failing history comments. (Default, for the active function) -original ori~path. -orig ori~path specifies the pathname of an earlier module copy that is already installed in the software library. This library copy is compared with the version being submitted (see "Notes" below). You can give an archive pathname and use the equal convention. -validate RTN. -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrypoint name acceptable to cv_entry_. If you give no -vdt, the default is to validate using the hcom_site_validate_ subroutine. if your site has provided it. or the hcom_default_validate_ subroutine provided with hcom. NOTES The install operation performs the following steps: 1. Make a working copy of history comments in the new module. 11/86 3-432.25 AG92-D6A history_comment history_comment 2. If -original is given, check comments in the original module against those in the working copy: a) check for comments in the original that do not appear in the working copy. This indicates changes that have been backed out If any are found, print an error and stop further checking. b) copy the install identifier from comments in the original module into corresponding comments in the working copy that are missing this identifier. This may occur when the developer makes changes to a modified version of the program before. that version is installed in the libraries. 3. If -approve or -input_approve is given, check for comments in the working copy that are missing the approve field. If none are found, report an error and stop further checking. If the AUDIT_DATE and AUDIT_PERSON_ID fields are missing, an error message is issued but processing continues. 4. If -install or -input_install is given, check for comments in the copy working that are missing the install field. If none are found, report an error and stop further checking. This indicates that the developer forgot to add a history comment when he modified the module. 5. Check for completeness of summary and audit fields in all history comments. If the AUDIT_DATE and AUDIT_PERSON_ID fields are missing, an error message is issued but processing continues. If incomplete or erroneous entries are found, report an error and stop further checking. 6. If -approve or -input_approve is given, place the approve identifier in the working copy's new history comments. If -install or -input_install is given, place the installation identifier in the working copy's new history comments. 7. Reformat the new history comments in the working copy. 8. If no error occurred, replace history comments in the new module with the working comments built by the install operation. Operation: replace_field, rpf SYNTAX AS A COMMAND hcom rpf path comment_specs -control_args FUNCTION replaces existing comment fields in selected history comments. 11/86 3-432.26 AG92-06A ARGUMENTS path is the name of a source code program that requires history comments. Include the language suffix. You can give an archive pathname. comment_specs specify which history comment(s) are to be updated. Specifiers" under the add_field operation.) (See "List of Comment CONTROL ARGUMENTS FOR FIELD INPUT Give at least one of the following control arguments: -approve -audit -input_approve -input-install -input_summary -install -summary -approve APPROVE_ID. -apv APPROVE_ID replaces the APPROVE_ID field. The maximum length of this field is 24 characters. (See "List of History Comment Fields" above for valid APPROVE_IDs') -audit, -aud puts the user's Person_id in the AUDIT_PERSON_ID field. -fill. -fi sets fill mode on f or the summary field. In fill mode text, words are moved from line to line in such a way that the last word does not extend past the right margin. (Default) -input_approve, -iapv prompts for a new APPROVE_ID. This is a single-line field value. -input_install, =iin prompts for the INSTALL_ID. This is a single-line field. -input_summary, -ism prompts you for a new summary field. This is a multiline field. -install INSTALL_ID, -in INSTALL_ID specifies an identifier associated with installing the changed module into execution libraries. (See "List of History Comment Fields" above for a description of valid INSTALL_IDs.) The maximum length of this field is 24 characters. -no_approve, -napv does not replace the APPROVE_ID field nor prompts for missing approve fields. (Default) 11/86 3-432.27 AG92-()6A -no_audit, -naud does not add the AUDIT_PERSON_ID field. (Default) -nofill, -nfi sets the fill mode off for the summary field. -no_install, -nin does not set the INSTALL_ID field nor prompts for missing install fields. (Default) -no_summary, -nsm does not replace the summary field. (Default) -summary TEXT, -sm TEXT replaces the text describing the change. parentheses, etc., enclose it within quotes. If the text contains spaces, quotes, CONTROL ARGUMENTS -critical_fix, -cfix specifies that critical-fix history comments are allowed in the program. All comments following the first that contains critical-fix field values must also contain critical-fix history comments. -original oriLpath, -orig oriLpath specifies the pathname of an earlier version of the module. You can give an archive pathname and use the equal convention. -validate RTN, -vdt RTN validates user-supplied fields in the history comment, using a user-supplied validation routine. RTN must be a virtual entrYJX>int name acceptable to cv_entry_. If you give no -vdt, the default is to validate using the hcom_site_validate_ subroutine, if your site has provided it, or the hcom_default_validate_ subroutine provided with hcom. NOTES If several history comments are selected, specified fields from the first selected comment are returned or printed. followed by fields from the second selected comment, etc. If the selected field is not present in a given history comment, then a null string is returned for that field. Multiline field values are returned in a single line (with newline characters replaced by a space) as a quoted string. 11/86 3-432.28 AG92-06A hour SYNTAX AS A COMMAND hd SYNTAX AS AN ACTIVE FUNCTION [hd] FUNCTION returns the patbname of your >user_dir_dir> Project_id> Person_idle home directory (usually of the form Name: hour SYNTAX AS A COMMAND hour {time_string} {-control_arg} SYNTAX AS AN ACTIVE FUNCTION [hour {time string} {-control_arg}] FUNCTION returns the one- or two-digit number of an hour of the day, from 0 to 23. The format string to produce this is "AZ9Hd". ARGUMENTS time_string indicates the hour about which information is desired. If you supply no time_string, the current hour is used. The time string is concatenated to form a single argument even if it contains spaces; you need not quote it. (See Section 1 for a description of valid time_string valUes.) CONTROL ARGUMENTS -zone STR STR specifies the zone that is to be used to express the result (Default: process default) 11/86 3-432.29 the AG92-D6A hour NOTES Use the print_time_defaults command to display the default zone. display_time_info command to display a list of all acceptable zone values. Use the Name: how_many_users, hmu SYNTAX AS A COMMAND hmu {-control_args} {optional_args} FUNCTION tells you how many users are currently logged in on the system. 11/86 3-432.30 AG92-06A CONTROL ARGUMENTS -absentee, -as prints load information on absentee users only, even if the absentee facility is not running. -brief, -bf suppresses the printing of the headers. optional arguments. Use it only together with one of the -long, -lg prints additional information including the name of the installation, the time the system was brought up, the time of the next scheduled shutdown, the time of the last shutdown or crash, and load information on absentee users. LIST OF OPTIONAL ARGUMENTS list only selected users and can be one of the following: Person_id lists a count of logged in users with the name Person_id. .Project_id lists a count of logged 'in users with the project name Project_id. Person_id.Project_id lists a count of logged in users with the name Person_id and the project name Project_id. NOTES In addition to how many users are currently logged in, hmu prints the name of the system, the current load on the system, the maximum load, and, if the absentee facility is running, the number of absentee users and the maximum number of absen tee users. If you invoke this command without any arguments, basic summary information is printed (see "Examples.") When you select hmu with optional arguments, absentee counts are denoted by an asterisk (*). You are permitted up to 20 classes of selected users. 3-433 AG92-06 hunt EXAMPLES To print summary information, type hmu Multics MR10.l, load 15.0/50.0; 15 users, 6 interactive, 9 daemons. To print summary information on absentee users, type hmu -as Absentee users 0/2 To print additional information, type hmu -lg Mu1tics 10.1: peQ, Phoenix, Az. Load = 13.0 out of 110.0 Units; users = 13, 4 interactive, 9 daemons. Absentee users = 0 background; Max background users = 2 System up since 02/02/83 0908.1 Last shutdown was at 01/31/83 02304.1 To print brief information about the SysDaemon project, type hmu -bf .SysDaemon .SysDaemon = 3 + 0* To print brief information about the user Smith, type hmu -bf Smith Sm i th = 1 + l)'c Name: hunt SYNTAX AS A COMMAND hunt name {path} {-c~ntrol_args} SYNTAX AS AN ACTIVE FUNCTION [hunt name {path} {-contro1_args}] 3-434 AG92-06 hunt hunt FUNCTION searches a specified subtree of the hierarchy for all occurrences of a namecj segment that is either freestanding or included in an archive file. ARGUMENTS name is the name of a segment for which hunt is to search. The star convention is allowed. path is the pathname of a directory to be interpreted as the root of the subtree in which to search for the specified segment(s). If you don't supply path. the subtree rooted at the current working directory is searched. CONTROL ARGUMENTS -all, -a reports on finding links. directories. and segmen~. -archive. -ac looks inside archives for components whose names match the name argument (Default) -first stops searching as soon as the first occurrence of the selected segment is found. (Default to return all occurrences) -no_archive, -nac does not look inside archives and is therefore faster. NOTES This command displays the type of entry found (segment, directory, or link), followed by the entry itself, and a total of the number of occurrences found. If archive components are being examined, the matching components are reported before added names on the archive segment NOTES ON ACTIVE FUNCTION As an active function, hunt returns a string of pathnames separated by spaces. Archive components are returned as archive_path::component_name. 3-435. AG92-06 SYNTAX AS A COMMAND hunt_dec {path} {-control_args} FUNCTION searches a specified subtree of the hierarchy for all PL/I object segments that are either freestanding or included in an archive file. ARGUMENTS path is the pathname of a directory to be interpreted as the root of the subtree in which to search and classify PL/I object segments. If you don't specify path, the working directory is assumed. CONTROL ARGUMENTS -aligned_decimal path, -ad path creates the ASCII segment listing the absolute pathnames of PL/I object segments and archive segments containing components classified as "aliS!1ed decimal"· with path suffixed with "hd". -unaligned_decimal path, -ud path creates the ASCII segment listing the absolute pathnames of PL/I object segments and archive segments containing components classified as "unaligned decimal" with path suffixed with "hd". NOTES Each PL/I object segment is classified according to its use of arithmetic decimal instructions and how these instructions access the data. The three classes are "no decimal", "aligned decimal", and "unaligned decimal". This command aids you when PL/I programs compiled using '~unaligned decimal" are to be recompiled using the newer PL/I compiler implementing packed decimal. which was part of Multics Release 8.0. This was an incompatible change because the layout of variables containing the unaligned and decimal attributes was changed. Therefore, find those PL/I programs that used "unaligned decimal" so that the appropriate program and data base changes can be made before recompiling the program using the new compiler. If you specify no control arguments, two ASCII segments are created in the working directory. One segment, aligned_decimal.hd, is a list of the absolute pathnames of PL/I object segmen~ and archive segments containing PL/I object segments classified as "aligned decimal". The absolute pathname of the archive segment is followed by a 3-436 AG92-o6 space, then by the name of the archive's component classified as "aligned decimal". This occurs for each component of the archive that is classified as such. Another segment, unaligned_decimal.hd, is created in the working directory for the class "unaligned decimal". No segment is created for the class "no decimal". This command uses the following algorithm to classify PL/I object segments. The text section is scanned for EIS decimal arithmetic instructions generated by the PL/I compiler. If none are found, the object segment is classified as "no decimal". If some are found, they and their descriptors are examined f or address modification and nonzero digit offsets. If either is present, the object segment is classified as "unaligned decimal"; otherwise, it is classified as "aligned decimal". The validity of the classification algorithm rests upon knowledge of how the PL/I compiler generates machine code. Below is a table listing the reliability of the algorithm for the different classifications. CLASSIFICATION RELIABILITY aligned decimal Always correct. unaligned decimal Fails when an unaligned decimal variable falls on a word boundary. For example, dcl 1 record aligned, 2 i tern 1 fixed bin (17) , 2 itern2 fixed dec (3) unaligned; The variable. item2, is unaligned decimal. But. since it is located one word from the beginning of the structure, the instruction accessing it appears to be accessing aligned decimal data. no decimal If fixed decimal variables are present in the source program but are never referenced or do not have the initial attiibute, no EIS fixed decimal instructions are generated by the compiler. Most of the time hunt_dec identifies correctly PL/I object segments that use unaligned decimal data while letting a few segments slip by misclassified as aligned decimal or no decimal. This command forces access to all segments in its search path. If unable to access a segment, it bypasses the segment without classifying it. 3-437 AG92-06 !J! if 11 Name: if SYNTAX AS A COMMAND if [E XPRJ - the n LIN E1 {- e 1s eLI NE2} SYNTAX AS AN ACTIVE FUNCTION [EXPR] -then STRl {-else STR2}] [if FUNCTION conditionally executes one of two command lines depending on the value of an active string. As an active function, returns one of two character strings to the command processor depending on the value of an active string. ARGUMENTS EXPR is the active string, which must evaluate to either "true" or "false". LINE! is the command line to execute if EXPR evaluates to "true". If the command line contains any command processor characters, enclose it in quotes. STRI is returned as the value of the if active function if the EXPR evaluates to "true". LINE2 is the command line to execute if EXPR evaluates to "false". If omitted and EXPR is "false", no additional command line is executed. If the command line contains any command processor characters, enclose it in quotes. STR2 is returned as the value of the if active function if the EXPR evaluates to "false". If omitted and the EXPR is "false", a null string is returned. 3-438 AG92-06 immediate_messages Name: immediate_messages, im SYNT AX AS A COMMAND im {mbx_specification} FUNCTION restores the immediate printing of interactive messages and notifications. ARGUMENTS mbx_specification specifies the mailbox on which the printing of messages is to be restored. If not given, the user's default mailbox (>udd>Project>Person>Person.mbx) is used. I LIST OF MBX SPECIFICATIONS -log specifies the user's logbox and is equivalent to -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx -mailbox path. -mbx path specifies the pathname of a mailbox. The suffix .mbx is added if necessary. -save path. -sv path specifies the pathname of a savebox. The suffix .sv.mbx is added if necessary. -user STR specifies either a user's default mailbox or an entry in the system mail table. SIR is any noncontrol argument and is first interpreted as -mailbox STR; if no mailbox is found, STR is then interpreted as -save STR; if no savebox is found. it is interpreted as -user STR. NOTES This command cancels defer_messages, but does not cancel any options that may have been specified by accept_messages (see accept_messages and print_messages). 11/86 3-439 AG92-06A indent indent Name: indent, ind SYNTAX AS A COMMAND ind oldpath {newpath} {-control_args} FUNCTION improves the readability of a PL/I source segment by indenting it according to a set of standard conventions described below. ARGUMENTS oldpath is the pathname of the input source segment Source segments with suffixes for PL/I, create_data_segment, and reductions are recognized. If the segment does not have a recognized suffix, indent uses a suffix of .pll, name. cds, or name.rd, in that order. newpath is the pathname of the output source segment. The output segment must have the same suffix as the input segment If you omit newpath, the indented copy of the program replaces the original one in oldpath. If errors are detected during indentation and you don't give newpath, however, the original copy is not replaced; instead, the pathname of the temporary file containing the indented CQpy is printed in an error message. CONTROL ARGUMENTS -brief, -bf suppresses warning comments on invalid or non-PL/I characters found outside of a string or comment; such characters are never removed. When you select -bf. those errors whose warning messages are suppressed do not prevent the original copy from being replaced. -comment STR, -cm STR sets the comment column to STR. Comments are lined up in this column unless they occur in the beginning of a line or are preceded by a blank line. (Default 61, if you omit -em) -indent STR. -ind STR sets indentation for each level to STR. Each do, begin, proc, and procedure statement indents additional STR spaces until the matching end statement is encountered. (Default: five, if you omit -ind) -lmargin STR, -1m STR sets the left margin (indentation for normal program statements) to STR. (Default: 11, if you omit -1m) 3-440 AG92-06 indent indent NOTES ON CONVElt/TIONS Declaration statements are indented five spaces for dcl declarations and 10 for declare declarations. Identifiers appearing on different lines of the same declare statement are lined up under the first identifier on the first line of the statement Structure declarations are indented according to level number; after level two, each additional level is indented two additional spaces. An additional level of indentation is also provided for the then clause of an if statement; else clauses are lined up with the corresponding if. Statements continuing over more than one line have an additional five spaces of indentation for the second line and all succeeding ones. Multiple spaces are replaced by a single space except within strings or for nonleading spaces and tabs in comments. Trailing spaces and tabs are removed from all lines. Spaces are inserted before left parentheses, after commas, and around the constructs =, ->, <=, >=, and "=. Spaces are deleted if they are found after a left parenthesis or before a right parenthesis. Tabs are used wherever possible to conserve storage in the output segment Parentheses are counted and balanced at every semicolon. If they do not balance or if the input segment ends in a string or comment, a warning message is printed. Language keywords (do, begin, end, etc.) are recognized only at parenthesis level zero, and most keywords are recognized only if they appear to begin a statement This command treats comments that begin with / ****" as unindentable. These comments are copied directly into the indented source program without reformatting or indentation. This follows the format_pll command convention for identifying comments that are not to be reformatted. NOTES ON RESTRICTIONS The only case in which indent splits a line is when lines are longer than 350 characters, since they overflow indent's buffer size. Labeled end statements do not close multiple open do statements. This command assumes that the identifiers begin, end, procedure, proc, declare, and del are reserved words when they appear at the beginning of a statement If the input contains a statement like do = do + 1; indent interprets it to mean that the statement delimits a do group and does not inden t correctly. Structure level numbers greater than 99 do not indent correctly. 11/86 3-441 AG92-Q6A index Name: index SYNTAX AS A COfv1MAND index STRA STRB SYNTAX AS AN ACTIVE FUNCTION [index STRA STRB] FUNCTION returns an integer representing the character position in STRA where STRB begins. If STRB does not occur in STRA, 0 is returned. EXAMPLES string [index abcdefhgij ef] 5 string [index "Now is the time" hte] o Name: index_set SYNTAX AS A COMMAND index_set {Fl} B1 {1l} ••• Fn Bn In SYNTAX AS AN ACTIVE FUNCTION [index_set {Fl} B1 {Il} •.. Fn Bn In] FUNCTION returns one or more integers, separated from each other by spaces. ARGUMENTS F is the first number of a set and must be an integer. This argument is optional (see "Examples"). B is a bound on the set and must be an integer. 3-442 AG92-06 I is the increment between the numbers of a set, either a positive or negative integer. If F > B, then I is assumed to be a negative integer. Otherwise. I is assumed to be positive. This argument is optional. NOTES If more than one F-B-I triple is specified. F, B, and I must be specified in each triple. If only one F-B-I triple is specified, I or both I and F can be omitted. I and F are assumed to be 1 if omitted. EXAMPLES The following interactions illustrate the index_set active function: string [index_set 1 2 345 6 string [index set 5 8 11 14 17 20 string [index_set o 246 string [index set 43210 string [index_set 6] 5 21 3] 0 6 2] 4 0] 0] 1 0 create fi1e_([picture 99 [index_set 5 21 3]]) listfile_* Segments r w w r w r w r w r w = 6. 0 r 0 0 0 0 0 Lengths = o. f 1e_20 f le_17 f le 14 f le- 11 f le::08 f le_05 The following interactions illustrate command usage: index set 4 9 14 19 Inaex set 4 9 14 19 index set 1 2 3-4 5 4 20 5 4 20 5 8 30 6 8 14 20 26 5 index set 5 2 5 4 3-2 3-443 AG92-()6 initiate initiate Name: initiate, in SYNTAX AS A COMMAND in path {ref_names} {-control_args} FUNCTION initiates segments or multisegment files (MSFs). ARGUMENTS path is the pathname of a segment or MSF. You can't use the star convention. ref_names are optional reference names by which to initiate the file. If you specify no ref_names, the file is initiated by the entryname portion of path. CONTROL ARGUMENTS -all, -a initiates the file by all its names. -brief, -bf does not print a message giving the segment number. (Default) -chase used with -a on a link pathname, initiates the target file by all the names on the target segment. (Def aul t) -force, -fc terminates each reference name first if it is already known. -long, -lg prints a message giving the segment number assigned. -no_chase used with -a on a link pathname, initiates the target file by all the names en the link. -no_force, -nf c prints an error message if a ref_name is already known. (Default) ACCESS REQUIRED Nonnull. 11/86 3-444 AG92-06A initiate initiate !vOiES When you use initiate to explicitly make known a segment by some reference name, the first reference to that name accesses the initiated segment instead of searching among the search directories for a segment by that name. (For a discussion of search rules, see the Programmer's Reference Manual.) If you give no ref_names, the segment is made known by the entryname part of the pathname; if you give ref _names, the entryname of the segment is not initiated, but the specified reference names are. If the pathname is a single-element name, the directory assumed is your working directory. Initiating a MSF involves initiating component 0 of the MSF with the reference names specified. 11/86 3-444.1 AG92~06A This page intentionally left blank. 11/86 AG92-06A initiate If you cannot initiate a ref_name, an error message is printed and the command continues initiating the other names. To make a segment known. you must have nonnull access to that segment EXAMPLES The command line in >udd>Demo>JKeats>gamma x y makes the segment >udd>Demo>JKeats>gamma known, initiating the names x and y. The command line in pop makes the segment pop in your working directory known arid initiates it with the ref erence name pop. The command line in xx u v -long makes the segment xx in your working directory known, initiates the reference names u and v, and prints out the assigned segment number. Name: io_call, io SYNTAX AS A COMMAND io operation switchname {args} SYNTAX AS AN ACTIVE FUNCTION [io operation switchname {args}] FUNCTION performs diverse operations on specified I/O switches and returns a result ARGUMENTS operation designates the operation to be performed. See "List of Operations" below for a description of each operation, its command syntax line, and specific application. 3-445 AG92-06 switchname is the name of the I/O switch through which the operation is performed. args can be one or more arguments, depending on the particular operation to be performed. LIST OF OPERATIONS Unless otherwise specified, if a control block for the I/O switch does not already exist, an error message is printed on error_output and the operation is not performed. If the requested operation is not supported for the switch's attachment and/or opening. an error message is printed on error_output Differences between command and active function invocation are described under the individual operations. The explanations of the operations cover only the main points of interest and, in general, treat only the cases where the I/O switch is attached to a file or device. For details see the descriptions of the iox_ subroutine and the I/O modules in the Subroutines manual, and the section on I/O facilities in the Programmer's Reference manual. Operation: attach SYNTAX AS A COMMAND io attach switchname attach_description FUNCTION attaches the I/O switch using the designated I/O module. If a control block for the I/O switch does not already exist, one is created. ARGUMENTS attach_description is the concatenation of modulename and args separated by blanks. It must conform to the requirements of the I/O module. If the I/O modulename is specified by a pathname, it is initiated with a reference name equal to the entryname. If the entryname or reference name does not contain a dollar sign, the attachment is made by calling modulename$modulenameattach. If you supply a $, the entry point specified is called. (See "Entry Point Names" in the Programmer's Reference manual.) * 3-446 AG92-()6 Operation: attach_desc SYNTAX AS A COMMAND io attach_desc switchname SYNTAX AS AN ACTIVE FUNCTION rio attach_desc switchname {-control_arg}] FUNCTION prints or returns the attach description of the switch, quoted unless you give -no_quote. CONTROL ARGUMENTS -no_quote, -nq does not enclose the returned data in quotes. Operation: attached SYNTAX AS A COMMAND io attached switchname SYNTAX AS AN ACTIVE FUNCTION rio attached switchname] FUNCTION prints or returns true if the switch is attached, false otherwise. Operation: close SYNTAX AS A COMMAND io close switchname FUNCTION closes the I/O switch. 3-447 AG92-06 Operation: close_file SYNTAX AS A COMMAND io close_file switchname {args} FUNCTION closes the I/O switch with the specified description. The close_file description is the concatenation of all arguments separated by blanks. It must conform to the requirements of the I/O module. ARGUMENTS args can be one or more arguments, depending on what is permitted by the particular I/O module. Operation: closed SYNTAX AS A COMMAND io closed switchname SYNTAX AS AN ACTIVE FUNCTION [io closed switchname] FUNCTION prints or returns true if the switch is closed, false otherwise. Operation: control SYNTAX AS A COMMAND io control switchname order {args} SYNTAX AS AN ACTIVE FUNCTION [io control switchname order {args}] 3-448 AG92-06 FUNCTION applies only when the I/O switch is attached via an I/O module that supports the control I/O operation. The exact format of the command line depends on the order being issued and the I/O module being used. For more details see "Control Operations from Command Level" in the appropriate I/O module. If the I/O module supports the control operation and the paragraph just referenced does not appear. assume that only control orders that do not require an info_structure can be performed with the io_call command. This is true because this command/active function uses a null info_ptr. (See the iox_$control entry. point in the Subroutines manual and "Performing Control Operations from Command Level" and the I/O module description in the Programmer's Reference Manual.) t The active function returns a value that depends on the I/O module and the order specified. ARGUMENTS order is one of the orders accepted by the I/O module used in the attachment of the I/O switch. args are additional arguments dependent upon the order being issued and the I/O module being used. Operation: delete_record, delete SYNTAX AS A COMMAND io delete switchname FUNCTION deletes the current record in the file to which the I/O switch is attached. The current record is determined as in rewrite_record. Operation: destroy_iocb SYNTAX AS A COMMAND io destroy_iocb switchname 3-449 AG92-06 FUNCTION destroys the I/O switch by deleting its control block. Be sure the switch is detached before using this command. Any pointers to the I/O switch become invalid. Operation: detach SYNTAX AS A COMMAND io detach switchname {args} FUNCTION detaches the I/O switch with the specified description. The detach description is the concatenation of all arguments separated by blanks. It must conform to the requirements of the I/O module. ARGUMENTS args can be one or more arguments, depending on what is permitted by the particular I/O module. NOTES If there are no arguments after switchname, this request is synonymous with the detach_iocb request. This means that if you supply no detach description on the command line, detach acts essentially as a short name for detach_iocb. Operation: detach_iocb SYNTAX AS A COMMAND io detach_iocb switchname FUNCTION detaches the I/O switch. Operation: detached SYNTAX AS A COMMAND io detached switchname 3-450 AG92-06 SYNTAX AS AN ACTIVE FUNCTION [io detached switchname] FUNCTION prints or returns true if the switch is detached, false otherwise. Operation: find_iocb SYNTAX AS A COMMAND io find_iocb switchname SYNTAX AS AN ACTIVE FUNCTION [io find_iocb switchname] FUNCTION prints or returns the location of the control block for the I/O switch. If it does not already exist, the control block is created. Operation: get_chars SYNTAX AS A COMMAND io get_chars switchname {N} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [io get_chars switchname {N} {-control_args}] FUNCTION reads the next N characters from the file or device to which the I/O switch is attached. ARGUMENTS N is a decimal number greater than zero specifying the number of characters to be read. 3-451 AG92-06 CONTROL ARGUMENTS -allow_newline, -alnl does not add to, nor delete from, the end of the line any newline character. (Default, when you select -segment) -append_newline, -apnl adds a newline character to the end of the line if one is not present (Default, when you don't choose -segment) -lines specifies that the offset, if given, is measured in lines rather than in characters. This control argument has meaning only if you also supply -segment; ~ou can't use it with the active function. -no_quote, -nq returns the data unquoted. (Default for active function only) -remove_newline, -rmnl deletes the newline character, if present, from the end of the line. (Default for active function) -segment path {offset}, -sm path {offset} specifies that the data read from the I/O switch is to be stored in the segment given by path. You can optionally describe the location at which to begin writing in path with the offset parameter. This is normally specified as a character offset (i.e., the number of characters to skip over before storing the new data in the segment). For example, an offset of 0 causes the new data to overwrite the entire file. When you also give -lines, then offset is a line offset (i.e., the number of lines to skip over before storing the new data in the segment). For example, an offset of 1 line begins storing data at the second line of the file. If you omit offset, new data is appended to the end of the segment You can't use this control argument with the active function. NOTES The characters read are written on user_output if you specify no -segment or stored in a segment if you specify -segment. The active function returns the data read as a quoted string, unless you specify -no_quote. A trailing newline character i~ deleted. If you don't specify the maximum number of characters N, the maximum segment size is assumed. Operation: get_line SYNTAX AS A COMMAND io get_line switchname {N} {-control_args} 11/86 3-452 AG92-06A SYNTAX AS AN ACTIVE FUNCTION [io get line switchname {N} {-control_args}] FUNCTION reads the next line from the file or device to which the I/O switch is attached. ARGUMENTS N is a decimal number greater than zero specifying the maximum number of characters to be read. CONTROL ARGUMENTS -allow_neWline, -alnl does not add to, nor delete from, the end of the line any newline character. (Default, when you select -segment) -append_newline, -apnl adds a newline character to the end of the line if one is not present (Default, when you choose no -segment) -lines specifies that the offset, if given, is measured in lines rather than in characters. This control argument has meaning only if you also supply -segment; you can't use it with the active function. -no_quote, -nq returns the data unquoted. (Default for active function only) -remove_newline, -rmnl deletes the newline character, if present, from the end of the line. (Default for active function) -segment path {offset}, -sm path {offset} specifies that the data read from the I/O switch is to be stored in the segment given by path. You can optionally describe the location at which to begin writing in path with the offset parameter. This is normally specified as a character offset (i.e., the number of characters to skip over before storing the new data in the segment). For example, an offset of 0 causes the new data to overwrite the entire file. When you also give -lines, then offset is a line offset (i.e., the number of lines to skip over before storing the new data in the segment). For example, an offset of 1 line begins storing data at the second line of the file. If you omit offset, new data is appended to the end of the segment You can't use this control argument with the active function. 11/86 3-453 AG92-06A NOTES If you give N and the line is longer than N, then only the first N characters are read. The active function returns the data read as a quoted string, unless you give -no_quote. A trailing newline character is deleted. If you don't give the maximum number of characters N, the maximum segment size is assumed. If you select no -segment, the line read is written onto the I/O switch user_output, with a newline character appended if one is not present and if you have selected neither -aInI nor -rmnl. If you select -segment, the line is stored in the segment specified by path; if this segment does not exist, it is created. The bit count of the segment is always updated to a point beyond the newly added data. If the segment contains a trailing newline and you haven't selected -rmnl, that newline remains; if the segment does not contain a trailing newline and you haven't selected -apnl, no newline is appended. Operation: io_module SYNTAX AS A COMMAND io i~_module switchname SYNTAX AS AN ACTIVE FUNCTION rio io_module switchname] FUNCTION prints or returns the name of the I/O module through which the switch is attached. Operation: look_iocb SYNTAX AS A COMMAND io look_iocb switchname SYNTAX AS AN ACTIVE FUNCTION [io look_iocb switchname] FUNCTION prints, on user_output, the location of the control block for the I/O switch; if this switch does not exist, an error is printed. The active function returns true if the specified iocb exists, false otherwise. 11/86 3-454 AG92-06A This page intentionally left blank. 11/86 AG92-06A Operation: modes SYNTAX AS A COMMAND io modes switchname {string} {-control_arg} 11/86 3-454.1 AG92-06A SYNTAX AS AN ACTIVE FUNCTION rio modes switchname {string}] FUNCTION sets only new modes specified in string and then prints the old modes on user_output; applies only when the I/O switch is attached via an I/O module that supports modes. The active function performs the specified modes operation and returns the old modes. ARGUMENTS string is a sequence of modes separated by commas. The string must not contain blanks. See the description of the I/O module attached to the switch for a list of acceptable modes. CONTROL ARGUMENTS -briet -bf suppresses printing of the old modes. NOTES If the switch name is user_i/o, the command refers to the modes controlling your terminal. Operation: move_attach SYNTAX AS A COMMAND io move_attach switchname switchname2 FUNCTION moves the attachment of the first I/O switch (switchname) to the second I/O switch (switchname2). The original I/O switch is left detached. ARGUMENTS switchname2 is the name of a second I/O switch. 3-455 AG92-06 Operation: open SYNTAX AS A COMMAND io open switchname mode FUNCTION opens the I/O switch with the specified opening mode. ARGUMENTS mode is one of the following opening modes: direct_input, di direct_output, do direct_update, du keyed_sequential_input, ksqi keyed_sequential_output, ksqo keyed_sequential_update, ksqu sequential_input, sqi Operation: sequential_output, sqo sequential_input_output, sqio sequential_update, squ stream_input, si stream_output, so stream_input_output, sio open_desc SYNTAX AS A COMMAND io open_desc switchname SYNTAX AS AN ACTIVE FUNCTION [io open_desc switchname] FUNCTION prints or returns the current open description (stream_input, etc.), quoted. Operation: open_file SYNTAX AS A COMMAND io open_file switchname mode {args} 3-456 AG92-o6 FUNCTION opens the I/O switch with the specified opening mode and description. The open_file description is the concatenation of all arguments separated by blanks. It must conform to the requirements of the I/O module. ARGUMENTS mode is one of the opening modes listed under open. args can be one or more arguments. depending on what is permitted by the particular I/O module. Operation: opened SYNTAX AS A COMMAND io opened switchname SYNTAX AS AN ACTIVE FUNCTION [io opened switchname] FUNCTiON prints or returns true if the switch is open, false otherwise. Operation: position SYNTAX AS A COMMAND io position switchname type SYNTAX AS AN ACTIVE FUNCTION [io pos:t:on sw:tchname type] FUNCTION positions the file to which the I/O switch is attached. 3-457 AG92-G6 ARGUMENTS type can be one of the following: bof sets position to beginning of file. eof sets position to end of file. forward N. fwd N. f N sets position forward N records or lines (same as reverse -N). reverse N, rev N, r N sets position back N records (same as forward -N records). You can give any other numeric argument or pair of numeric arguments, but its function depends on the I/O module being used and cannot be implemented for all I/O modules. reverse N, rev N, r N NOTES If type is bof, the file is positioned to its beginning, so that the next record is the first record (structured files) or the next byte is the first byte (unstructured files). If type is eof, the file is positioned to its end; the next record (or next byte) is at the end-of-file position. If type is forward or reverse, the file is positioned forwards or backwards over records (structured files) or lines (unstructured files). The number of records or lines skipped is determined by the absolute value of N. The active function returns true if it succeed, false otherwise. In the case of unstructured files, the next-byte position after the operation is at a byte immediately following a newline character (or at the first byte in the file or at the end of the file). The number of newline characters moved over is the absolute value of N. If the I/O switch is attached to a device, you are only allowed forward skips; this discards the next N lines input from the device. Operation: print_iocb SYNTAX AS A COMMAND io print_iocb switchname 3-458 AG92-Qt FUNCTION prints, on user_outpu~ all the data in the control block for the I/O switch, including all pointers and entry variables. Operation: put_chars SYNTAX AS A COMMAND io put_chars switchname {string} {-control_args} FUNCTION outputs a character string or an entire segment to a specified I/O switch. ARGUMENTS string can be any character string. CONTROL ARGUMENTS -allow_newline, -alnl does not add to, nor delete from, the end of the line any newline character. -append_newline; -apnl adds a newline character to the end of the line if one is not present (Default) -lines specifies that the offset and length operands of -segment are measured in lines rather than in characters. This control argument has meaning only if you also supply -segment -remove_newline, -rronl does not append a newline character to the end of the output string or segment even if one is not present at the end. -segment path {{offset} length}, -sm path {{offset} length} specifies that the data for the output operation is to be found in the segment specified by path. You can optionally describe the location and length of the data with offset and length parameters. These are normally specified as a character offset (i.e., 0 identifies the first character of the segment) and character length. When you also give -lines, they are specified as a line offset and line count If you give no offset, 0 is assumed. If you give no length and offse~ the entire segment is used. -string STR, -str STR specifies an output string that can have a leading hyphen. 11/86 3-459 AG92-06A NOTES The string argument and -segment are mutually exclusive. If you supply a string, the contents of the string are output to the I/O switch. If you supply -segment, the data is taken from the segment specified by path, at the offset and length given. If the I/O switch is attached to a device, io_call transmits the characters from the string or the segment to the device. If the I/O switch is attached to an unstructured file, the data is added to the end of the file. Operation: read_key SYNTAX AS A COMMAND io read_key switchname SYNTAX AS AN ACTIVE FUNCTION [io read key switchname {-control arg}] FUNCTION prints, on user_output, the key and record length of the next record in the indexed file to which the I/O switch is attached. The file's position is not changed. The active function returns the value of the key, quoted, unless you select -no_quote. CONTROL ARGUMENTS -no_quote, -nq does not enclose the returned data in quotes. Data containing spaces is quoted by default Operation: read_length SYNTAX AS A COMMAND io read_length switchname SYNTAX AS AN ACTIVE FUNCTION [io read_length switchname] FUNCTION prints, on user_output, the length of the next record in the structured file to which the I/O switch is attached. The file's position is not changed. The active function returns the length of the next record, in bytes. 11/86 3-460 AG92-06A Operation: read_record, read SYNTAX AS A COMMAND io read switchname {N} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [io read switchname {N} {-control_args}] FUNCTION reads the next record from the file to which the I/O switch is attached into a buffer of length N.. ARGUMENTS N is a decimal integer greater than zero specifying the size of the buffer to be be used. CONTROL ARGUMENTS -allow_newline, -alnl does not add to, nor delete from, the end of the line any newline character. (Default for command) -append_newline, -apnl adds a newline character to the end of the line if one is not present * -lines specifies that the offset, if given, is measured in lines rather than in characters. This control argument has meaning only if you also supply -segment; you can't use it with the active function. -no_quote, -nq returns the data unquoted. (Default for active function only) -remove_newline, -rmnl deletes the newline character, if present, from the end of the line. (Default for active function) 11/86 3-461 AG92-06A -segment path {offsetl9 -sm path {offset} specifies that the data read from the I/O switch is to be stored in the segment given by path. You can optionally describe the location at which to begin writing in path with the offset parameter. This is normally specified as a character offset (i.e., the number of characters to skip over before storing the new data in the segment). For example, an offset of 0 causes the new data to overwrite the entire file. When you also give -lines, then offset is a line offset (i.e. 9 the number of lines to skip over before storing the new data in the segment). For example, an offset of 1 line begins storing data at the second line of the file. If you omit offset, new data is appended to the end of the segment You can 9t use this control argument with the active function. NOTES The characters read are written on user_output if you specify no -segment or stored in a segment if you specify -segment The active function returns the data read as a quoted string, unless you give -no_quote. A trailing newline character is deleted. If you don9t give the maximum number of characters N. the maximum segment size is assumed. Operation: rewrite_record, rewrite SYNTAX AS A COMMAND io rewrite switchname {string} {-control_args} FUNCTION replaces the current record in the file to which the i/O switch is attached. ARGUMENTS string is any character string. CONTROL ARGUMENTS -allow_newline, -alnl does not add to, nor delete from. the end of the line any newline character. (Default, when you select -segment) -append_newline, -apnl adds a newline character to the end of the line if one is not present. 11/86 3-462 AG92-()6A -lines specifies that the offset and length operands of -segment are measured in lines· rather than in characters. This control argument has meaning only if you also supply -segment I I I -no_quote, -nq returns the data unquoted. (Active function usage only) -remove_newline, -rmnl deletes the newline character, if present, from the end of the line. (Default if you give no -segment) -segment path {{offset} length}, -sm path {{offset} length} specifies that the data for the output operation is to be found in the segment specified by path. You can optionally describe the location and length of the data with offset and length parameters. These are normally specified as a character offset (i.e., 0 identifies the first character of the segment) and character length. When you also give -lines, they are specified as a line offset and line count If you give no offset, 0 is assumed. If you give no length and offset, the entire segment is used. -string STR, -str STR specifies an output string that can have a leading hyphen. NOTES The string argument and -segment are mutually exclusive. If you supply a string, the contents of the string are output to the I/O switch. If you supply -segment, the data is taken from the segment specified by path, at the offset and length given. The current record must have been defined by a preceding read_record. seek_key, or position operation as follows: read_record the current record is the last rer-..,ord read. seek_key the current record is the record with the specified key. position the current record is the one preceding the record to which the file was positioned. Operation: seek_key SYNTAX AS A COMMAND io seek_key switchname key 11/86 3-463 AG92-06A SYIVTAX AS AN ACTIVE FUNCTION rio seek_key switchname key] FUNCTION positions the indexed file to which the I/O switch is attached to the record with the given key. The record's length is printed on user_output Trailing blanks in the key are ignored. The active function returns true if the key exists, false otherwise. ARGUMENTS key is a string of no more than 256 ASCII characters. You can use the null string ("") as a key. NOTES If the file does not contain a record with the specified key, it becomes the key for insertion. A following write_record operation adds a record with this key. Operation: test_mode SYNTAX AS A COMMAND io test_mode switchname mode SYNTAX AS AN ACTIVE FUNCTION [io test_mode switcnname mode] FUNCTION performs a modes operation and prints or returns true if mode appears in the mode string, false if "mode appears. Operation: valid_mode SYNTAX AS A COMMAND io valid_mode switchname mode SYNTAX AS AN ACTIVE FUNCTION rio valid_mode switchname mode] 11/86 3-464 AG92-()6A FUNCTION performs a modes operation and prints or returns true if either mode or I\mode appears in the mode string, false otherwise. Operation: valid_op SYNTAX AS A COMMAND io valid_op switchname operation SYNTAX AS AN ACTIVE FUNCTION [io valid_op switchname operation] FUNCTION prints or returns true if the operation is defined on the switch. List of Operations close control delete_record destroy_iocb detach_iocb find_iocb get_chars get_line look_iocb modes Operation: move_attach open position put_chars "A"'~ lTA'fr ~"",",,_A"'J read_length read_record rewrite_record seek_key write_record write_record, write SYNTAX AS A COMMAND io write switchname {string} {-control_args} FUNCTION adds a record to the file to which the I/O switch is attached. ARGUMENTS string is any character string. 11/86 3-465 AG92-06A CONTROL ARGUMENTS -allow_newline, -alnl does not add to, nor delete from, the end of the line any newline character. (Default when you select -segment) -append_newline, -apnl adds a newline character to the end of the line if one is not present -lines specifies that the offset and length operands of -segment are measured in lines rather than in characters. This control argument has meaning only if you also supply -segment -no_quote, -nq returns the data unquoted. (Active function usage only) -remove_newline, -rmnl deletes the newline character, if present, from the end of the line. (Default if you give no -segment) -segment path {{offset} length}, -sm path {{offset} length} specifies that the data for the output operation is to be found in the segment specified by path. You can optionally describe the location and length of the data with offset and length parameters. These are normally specified as a character offset (Le.• 0 identifies the first character of the segment) and character length. When you also give -lines. they are specified as a line offset and line count If you give no offset, 0 is assumed. If you give no length and offset, the entire segment is used. -string STR, -str STR specifies an output string that can have a leading hyphen. NOTES The string argument and -segment are mutually exclusive. If you supply a string, the contents of the string are output to the I/O switch. If you supply -segment, the data is taken from the segment specified by path, at the offset and length given. If the file is sequential, the record is added at the end of the file. If the file is indexed, the record's key must have been defined by a preceding seek_key operation. 11/86 3-466 AG92-06A Name: is_component_pathname, icpn SYNTAX AS A COMMAND icpn path SYNTAX AS AN ACTIVE FUNCTION [i cpn path] FUNCTION returns true if the path is a valid pathname that refers to an archive component (pathname). 11/86 3-466.1 AG92-()6A This page intentionally left blank. 11/86 AG92-06A kermit is_component_pathname EXAMPLES icpn >udd>Proj>Myname>start_up.ec false icpn >udd>Multics>Library>Source>bound_command_demos_.s::program.pll true Name: kermit SYNTAX AS A COMMAND kermit {-control_args} FUNCTION invokes the Multics implementation of the Kermit file transfer program. The Multics Kermit program provides the capability to transfer files between a Multics system and a remotely located system (e.g., a personal computer) using the KERMIT protocol. Once invoked, Multics Kermit prompts you for the various file transfer requests. Multics Kermit has been implemented with a server feature that permits you to login to Multics from a remote site and specify file transfer operations without having to escape back and forth between the Multics system and the remote system. CONTROL ARGUMENTS -abbrev, -ab enables abbreviation expansion of request lines. -io_switch STR. -iosw STR specifies that communication with the remote system be done over the I/O switch whose name is STR. If you omit it, the user_i/o switch is assumed. -no_abbrev, -nab does not enable abbreviation expansion of request lines. (Default) -no_prompt, =npmt suppresses the prompt for request lines in the request loop. -no_request_loop, -nrql does not enter the request loop after performing any operations given by -request -no_start_up, -nsu, -ns does not execute the start_up exec_com. 3-467 AG92-D6 kermit kermit -profile PATH. -pf PATH specifies the pathname of the profile to use for abbreviation expansion. The suffix "profile" is added to PATH if you don't include it explicitly on the command line. This control argument implies -abbrev. -prompt STR! -pmt STR sets the request loop prompt to STR. (Default: A/Multics-Kermit A[ (Ad)A] :A2x) -quit exits the Kermit program after performing any operations given by -request -request STR, -rq STR executes STR as a Kermit program request line before entering the request loop. -request_loop, -rql enters the Kermit program request loop after performing any operations given by -request (Def ault) -start_up, -su executes the Kermit program start_up exec_com start_up. kermit The users home directory, the project directory, and >site are searched, in that order, for the start_up. The exec_com is executed before the request_string and before entering the subsystem request_loop. (Default) LIST OF REQUESTS The following is a summary of requests used to respond to prompts from the Kermit program. In this summary "-ca" is used as shorthand for "-control_args". For a complete description of any request, issue the Kermit request: help request_name prints a line describing the current invocation of the Kermit program. ? prints a list of requests available in the Kermit program. abbrev {-ca} , ab {-ca} controls abbreviation processing of request lines. do rq_str {args}, [do rCLstr args] executes/returns a request line with argument substitution. exec_com ec_path {ec_args}, ec ec_path {ec_args} [exec_com ec_path {ec_args}], [ec ec_path {ec_args}] executes a file of Kermit program requests that can return a value. 3-468 AG92-06 kermit kermit execute cmd_Iine, e cmd_line [execute active_str]. [e active_str] executes a Multics command line or evaluates a Multics active string. finish sends a request to a remote server to shut down server operation and return the remote system to its request's loop. get remote_source_path {Iocal_destination_path} sends a request to a remote server requesting that the named file(s) be sent from the remote system. help {topics} {-ca} prints information about Kermit program requests and other topics. If you supply no topics, methods for getting help are listed. list_help {topics}, Ih {topics} displays the name of all Kermit program info segments on given topics. list_requests {STRs} {-ca}, Ir {STRs} {-ca} prints a brief description of selected Kermit program requests. You can use STR to specify that only specific requests be listed. log {PATH} {-ca} directs the Kermit program to start logging transactions. logout sends a request to the remote server directing it to log you out irom the remote system. quit, q exits the Kermit program. quit_log directs the Kermit program to stop logging transactions. receive {PATH}, r {PATH} receives a file or file group from the other system. send local_source_path {remote_destination_path} s local_source_path {remote_destination_path} sends a file or file group to the other system. server instructs the Kermit program to cease taking commands from the keyboard and to receive all further instruction in the form of Kermit packets. set mode {STR} establishes or modifies various modes for file transfers. 3-469 AG92--()6 kermit kermit show {modes} displays mode values. statistics, st shows statistics about the most recent file transfer. subsystem_name, [subsystem_name] prints/returns the name of this subsystem. subsystem_version, [subsystem_version] prints/returns the version number of this subsystem. The following list of modes are recognized by the Kermit program and the set and show Kermit requests. The values associated with each mode are also given. LIST OF MODES AFFECTING FILE STORAGE file_type STR indicates the type of file being transferred. STR can be either binary or ascii. file_warning STR indicates the action to be taken when an incoming file name has the same name as an existing file name in the default directory when receiving files. STR can be either on or off. If file_warning is on, the Kermit program renames the file to avoid overwriting the preexisting one; if file_warning is off, the incoming file replaces the preexisting one. If logging transactions, the log indicates the name of the file in which the data was stored. (Default: on) incomplete STR indicates the action to be taken if a file was not completely transferred. STR can be either keep or discard. If you specify keep, ali incomplete files are saved; if you give discard, incomplete files are discarded. (Default keep) LIST OF MODES AFFECTING FILE TRANSFER control_prefix CHR, cp CHR is the character to use for quoting of control characters, where eRR is any character in the range through > or ' through -, but difierent from eight_bit_prefix and repeat_prefix. (Default #) eight_bit_prefix CHR, ebp CHR is the ASCII character Multics Kermit program uses, when transmitting binary files via a 7-bit connection, to quote characters that have the 8th bit set. CHR is one of the following, but different from control_prefix and repeat_prefix: y characters with the 8th bit set are quoted if the remote system requests it. N characters with the 8th bit set are not quoted. 3-470 AG92-()6 kermit kermit & or any character in the range ! through > or ' through "'. Use the specified character for quoting characters with the Sth bit set If the Multics Kermit program's eight_bit_prefix character is different from the remote program's, then no 8th bit prefixing is done. The value of this mode is ignored if line_byte_size is 8. (Default &) end_of_packet CHR, eop CRR is the character the Multics Kermit program uses as a line terminator for incoming packets, where CHR is an ASCII character between SOH (001 octal) and US (037 octal) inclusive and different from the start_of_packet character. (Default: carriage return, 015 octal) line_byte_size N indicates whether data is being transmitted via a 7-bit or S-bit connection, where N can be either 7 or S. A 7-bit connection is desirable when transferring ASCII files or when the Sth bit of each transmitted byte is required for parity or changed by intervening communications equipment Use an S-bit connection for transferring binary files, as it decreases protocol overhead. If you can't use an S-bit connection for a binary file transfer, then you can use a 7-bit connection with the eight_bit_prefix mode enabled to transfer binary files. (Default: 7) pa,cket_Iength N, pI N . is the maximum packet length the Multics Kermit program can receive, where N is an integer between 20 and 94 (decimal). (Default SO) parity STR used for communicating with systems or networks that require the Sth bit for character parity. The parity used must be the same for Kermit programs on both the local and remote system. STR can be one of none eight data bits arid no parity. mark seven data bits with the parity bit set to 1. space seven data bits with the parity bit set to O. even seven data bits with the parity bit set to make the overall parity even. odd seven data bits with the parity bit set to 1 to make the overall parity odd. The value of the mode is ignored if line_byte_size is S. (Default none) 3-471 AG92-06 kermit kermit repeat_prefix CHR rp CHR is the character the Multics Kermit program uses to indicate a repeated character, where CHR can be any character in the range ! through > or ' through "", but different from the control_prefix and eight_bit_prefix. Space " " denotes no repeat count processing is to be done. If the Multics Kermit program repeat_prefix character is different from the remote system's, then no repeat prefixing is done. (Default: -). retry_threshold N, rt N specifies how many times to try sending or receIVIng a particular packet before giving uP. where N is an integer between 5 and 15 inclusive. (Default 5) start_of_packet CHR sop CHR is the character to be used f or the start of packet. where CHR is an ASCII character between NUL (000 octal) and US (037 octal) inclusive. The start_of_packet character must be the same for Kermit programs on both the local and remote system. but different from the end_of_packet character. (Default SOH. octal 001) timeout N specifies how many seconds the Multics Kermit program wants the remote system to wait for a packet from Multics before trying again, where N is an integer value between 5 and 20. (Default 15) NOTES ON KERMIT DEVELOPMENT The KERMIT protocol was developed at Columbia University, Many implementations of KERMIT are avaiable from the KERMIT group at Columbia. Direct inquiries about KERMIT to KERMIT Distribution Columbia University Center fer Computing Activities 7th Floor, Watson Laboratory 612 West 115th Street New York, New York 10025 NOTES ON REMOTE SYSTEMS The Multics Kermit program supports the transfer of 7-bit ASCII files and 8-bit binary files. You can transfer ASCII files between any two systems, whereas you can only transfer binary files between systems that are able to retain the original value of the data byte. For example. sending a Multics binary file in which all bits of the 9-bit byte are used to a system that uses 8-bit bytes results in the loss of the most significant bit (i.e., the transferred file on the remote system differs from the original file sent). However, a binary file received by the Multics Kermit program from a remote system that uses 8-bit bytes can then be sent by Multics Kermit to a second such remote system. The resulting file on the second system is identical to the original file sent 3-472 AG92-o6 kermit kermit NOTES ON FILE TRANSFER For transmission between systems, you must assign files to one of two categories--ASCII or binary. On systems with 8-bit bytes, ASCII files have the high-order bit of each byte set to zero, whereas binary files use the high-order bit of each byte for data, in which case its value can vary from byte to byte and must be preserved. Binary file transmission is permissible as long as the two Kermit programs involved can control the value of the 8th bit (Le., it is not being used for parity or changed by intervening communications equipment). In that case the 8th bit of a transmitted character matches that of the original data byte without any special 8th bit prefixing. For example, to send or receive a binary file of 8-bit bytes when an 8-bit connection is possible, set line_byte_size .to 8, set file_type to binary, and start the transfer. If an 8-bit connection is not possible, then you can send binary files via a 7-bit connection using the eight_bit_prefix. For example, set file_type to binary, set line_byte_size to 7. set parity to str, set eight_bit_prefixing to chr. and start the transfer. To send or receive an ASCII file, set file_type to ascii. set line_byte_size to 7. set any other desired modes. and start the transfer. The Multics Kermit program does not support the transfer of 9-bit bytes when the most significant bit is used for data. Thus sending a Multics binary file to a second Multics site results in the loss of the most significant bit of each byte. PROCEDURE FOR USING KERMIT: MULTICSIPERSONAL COMPUTER Use the following procedure to transfer files between Multics and a personal computer using Kermit 1. Start Kermit on the personal computer. 2. Set any desired modes. 3. Connect to Multics via the connect command. Multics banner is displayed. 4. Login to Multics. 5. Start Kermit on Multics. It responds with the prompt "Multics-Kermit". 6. Set any desired modes. 7. Execute either a send or receive request, specifying the file or file group. 8. Use the appropriate escape sequence to get back to Kermit command level on the personal computer. 9. Execute the corresponding request on the personal computer. For example, if you issue the send request on M ultics, execute the receive request on the personal computer or vice versa. 3-473 Once connected, the standard AG92-06 kermit kermit 10. File transfer begins. transfer. The personal computer displays the status of the file 11. To transfer more files, connect back to Multics Kermit and enter a carriage return to get the "Multics-Kermit:" prompt. Go to step 7. 12. Exit Multics Kermit by issuing the quit request and logout. 13. Use the appropriate escape sequence to get back to Kermit command level on the personal computer. PROCEDURE FOR USING KERMIT: MULTICS SERVER/PERSONAL COMPUTER Use the following procedure to transfer files between Multics and a personal computer using the Kermit server: 1. Start Kermit on the personal computer. 2. Set any desired modes. 3. Connect to Multics via the connect command. Multics banner is displayed. 4. Login to Multics. 5. Start Kermit on Multics. It responds with the prompt "Multics-Kermit:". 6. Set any desired modes. 7. Execute the server request. 8. Use the appropriate escape sequence to get back to Kermit command level on the personal computer. 9. Execute the Kermit server request on the personal computer f or sending or receiving files. 10. File transfer begins. transfer. Once connected, the standard The personal computer displays the status of the file 11. To transfer more files. go to step 9. 12. Exit Multics Kermit by issuing the Kermit server quit request on the personal computer. 13. Connect back to Multics and logout. 14. Use the appropriate escape sequence to get back to Kermit command level on the microcomputer. 3-474 AG92-()6 kermit kermit PROCEDURE FOR USING KERMIT: MULTICS/MULTICS Use the following procedure to transfer files between two Multics systems using Kermit: 1. Login to the local Multics. 2. Connect to the remote Multics via the dial_out command. 3. Login to the remote Multics. 4. Start Kermit on the remote Multics. 5. Set any desired modes. 6. Execute the server request. 7. Use the appropriate escape sequence to start up Kermit on the local Multics (e.g., e kermit -iosw [switch_name]) 8. Execute the Multics send request to send files to the remote system, or the get request to receive files from the remote system. 9. To transfer more files, go to step 8. 10. When done, execute the finish request to exit the remote server and quit from the local kermit to reconnect to the remote Multics, or execute the logout request to iogout from the remote Muitics and then quit the local Kermit. EXAMPLES r 14:24 3.546 25 dial_out e.h024.* p25 ••• Multics Ope System M••• I NCopernicus Multics Password: You are protected from ••• r 14:26 14.354 243 kermit -prompt ""/SysM-Kermit"[ ("d)"]: II SysM-Kermit: server e kermit -iosw [switch_name] Multics-Kermit: send x.pll test.pll Send i ng I f i 1e (s) ••• 3-475 AG92-06 kermit Transaction completed: 1 file(s) sent. Multics-Kermit: get test.pl1 x2.pl1 Receiving ••• Successfully received 1 file(s). Multics-Kermit: logout Multics-Kermit: q dial out: connection closed. r 14:32 53.659 863 SYNTAX AS A COMMAND FUNCTION allows a process to handle file transfer requests from a DPS 6 using the DPS 6 File Transfer Facility (FTF) protocol {referred to as L6 TRAN; see the DPS 6 & Level 6 to Level 66 File Transmission Facility User's Guide (CZ60). ARGUMENTS channel_name is the name of a polled VIP subchannel over which the file transfers take place. It must have the x prefix (i.e.. b.h217.xOl). CONTROL ARGUMENTS -long. -lg prints a line describing each file transfer as it starts and as it completes. (Default not to print this information) -target_dir -td restricts the pathnames of any files to be transferred to be relative to the target directory. You can specify the root as ">", which allows you to give absolute pathnames. (Default your working directory) 3-476 AG92-()6 ACCESS REQUIRED You must have rw access to the access control segment (ACS) of the specified channel name and the dialok attribute turned on in the project master file (PMF). The polled VIP subchannel must have the slave attribute in the channel master file (CMF). NOTES This command continues to listen for, and carry out, DPS 6 requests until you explicitly tell it to stop ("quit," "q") or the channel disconnects. You can type the quit request at any time, but it only takes effect before any file transfer has started or between two file transfers. You can only transfer sequential ASCII or sequential binary files to or from the DPS 6. ASCII files on Multics are assumed to be stream files when sending and are stored as stream files when receiving. Binary files on Multics have a special format. Interrupting and releasing a file transfer may result in aborting the operation inconsistently -and hanging the DPS 6 task. The polled VIP subchannel must be defined with a terminal type that assigns max_message_len to a value of 1009 in its additional_info statement. Blank lines in a DPS 6 file actually have some characters on them, usually a space or tab. These characters end up in the Multics file. The command transmits blank lines from Multics files to the DPS 6 by sending a line containing a single-space character. Each sequential binary record on Multics is assumed to have the following format dcl 1 binary record aligned based, 2 num_sextets fixed bin(35) aligned, 2 sextets (0 refer binary_record.num_sextets) fixed bin(6) unsigned unaligned; Each binary record is stored in a vfile_ record of size currentsize(binary_record) * 4. Name: last_message, 1m SYNTAX AS A COMMAND im {mbx_specification} SYNTAX AS AN ACTIVE FUNCTION [1m {mbx_specification}] 3-477 AG92-D6 FUNCTION returns the text of the last message received from send_message. See accept_messages, last_message_sender, last_message_time, and send_message. ARGUMENTS mbx_specification specifies the mailbox from which messages are to be displayed. If not given, the user's default mailbox (>udd>Project>Person>Person.mbx) is used. LIST OF MBX SPECIFICATIONS -log specifies the user's logbox and is equivalent to -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx -mailbox path, -mbx path specifies the pathname of a mailbox. The suffix .mbx is added if necessary. -save path, -sv path specifies the pathname of a savebox. The suffix .sv.mbx is added if necessary. -user STR specifies either a user's default mailbox or an entry in the system mail table. STR is any noncontrol argument and is first interpreted as -mailbox STR; if no mailbox is found, STR is then interpreted as -save STR; if no savebox is found, it is interpreted as -user STR. Name: last_Message_destination, lmds SYNTAX AS A COMMAND lmds {-control_arg} SYNTAX AS AN ACTIVE FUNCTION [lmds {-control_arg}] 11/86 3-478 AG92-06A FU.AJCTION returns the User_id of send_message. the last destination to which a message was sent by CONTROL ARGUMENTS -inhibit_error, -ihe prints/returns a null string if there is no last message destination. NOTES Name: last_message_sender, lms SYNTAX AS A COMMAND lms {mbx_specification} SYNTAX AS AN ACTIVE FUNCTION Elms {mbx_specification}] FUNCTION returns the sender of the last message received (from send_message) in the form "Person_id.Project_id" (e.g., GBShaw.Demo). ARGUMENTS mbx_specif ication specifies the mailbox of the sender of the last message. If not given. the user's default mailbox (>udd>Project>Person>Person.mbx) is used. LIST OF MBX SPECIFICATIONS -log specifies the user's logbox and is equivalent to -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx -mailbox path, -mbx path specifies the pathname of a mailbox. The suffix .mbx is added if necessary. 11/86 3-479 AG92-Q6A -save path. -sv path specifies the pathname of a savebox. The suffix .sv.mbx is added if necessary. -user STR specifies either a user's default mailbox or an entry in the system mail table. STR is any noncontrol argument and is first interpreted as -mailbox STR; if no mailbox is found, STR is then interpreted as -save STR; if no savebox is found, it is interpreted as -user STR. NOTES You are cautioned against using the active function when in polite mode. In this mode the system holds all messages until you finish typing a line (i.e.. until the carriage is at the left margin); therefore it is possible that while you are sending a message, your process receive another message from another user--a message not yet seen. By using the active function in this situation. you can inadvertently attribute a message to the wrong person. EXAMPLES Assume that a user has just received the following message: From AFrance.Demo 11/19/86 1231.7 mst Wed: Need access to xy A reply can be sent as follows: sm Elms] Sorry for the oversight. You have access now. SYNTAX AS A COMMAND lmt {mbx_specification} SYNTAX AS AN ACTIVE FUNCTION [lmt {mbx_specification}] FUNCTION returns the date and time the last message (from send_message) was received. 11/86 3-480 AG92-06A length ARGUMENTS m bx_specification specifies the mailbox from which the last message was received. If not given. the user's default mailbox (>udd>Project>Person>Person.mbx) is used. I LIST OF MBX SPECIFICATIONS -log specifies the user's logbox and is equivalent to -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx -mailbox path. -mbx path s?-..Cifies the pathna.'l1e of a mailbox. The suffix .mbx is added if necessary. -save path, -sv path specifies the pathname of a savebox. The suffix .sv.mbx is added if necessary. -user STR specifies either a user's default mailbox or an entry in the system mail table. STR is any noncontrol argument and is first interpreted as -mailbox STR; if no mailbox is found, STR is then interpreted as -save STR; if no savebox is found, it is interpreted as -user STR. NOTES Name: length, In SYNTAX AS A COMMAND In STR SYNTAX AS AN ACTIVE FUNCTION [1 n STR] FUNCTION returns an integer representing the number of characters in STR. 11/86 3-481 AG92-D6A length less ARGUMENTS STR string of alphanumeric characters. If STR contains blanks or other command language characters, enclose it in quotes. is any EXAMPLES string [In "A multiple-word string ll ] 22 The following example from an exec_com segment tests for a string that is greater than 27 characters. &if [nless [In &1] 27] &then &goto OK Sprint Entry name too long. &l.info &quit &label OK ec exec_com2 &l.info Name: less SYNTAX AS A COMMAND less STRA STRB SYNTAX AS AN ACTIVE FUNCTION [less STRA STRB] FUNCTION returns true if strA is less than strB according to the ASCII collating. sequence; otherwise it returns false. NOTES The strings are compared character by character according to their ASCII code value (i.e., if the first character in each string has the same ASCII code value, compare the second character; if their values are identical, compare the third character; etc.). See the descriptions of nless and ngreater for a way to compare numeric strings. 3-482 AG92-Q6 library_descriptor library_descriptor Name: library_descriptor, Ids SYNTAX AS A COMMAND lds key {arguments} SYNTAX AS AN ACTIVE FUNCTION [lds key {arguments}] FUNCTION prints or returns information about library descriptors and controls their use by the other library descriptor commands (see the It can print the pathname of the directory * or archive associated with a library root, can print detailed information about one or more library roots, can set and print the name of the default library descriptor used by the other library descriptor commands, and can print the default library and search names associated with each library descriptor command. A library descriptor is a data base that associates directories or archives in the Multics storage system with the roots of a logical library structure. LIST OF KEYS name, nm returns the name of the default library descriptor that is currently being used. Usage: lds name [lds name] set sets the name of the default library descriptor. Usage: lds set {desc_name} where desc_name is the pathname or reference name of the new default library descriptor. If you give a reference name, the descriptor is searched f or according to the search rules. If you omit desc_name, the default library descriptor is set as the descriptor for the Multics system libraries. 3-483 AG92-06 library_descriptor library_descriptor pathname, pn returns the pathname of the library root(s) that is identified by one or more library names. Using pathname, you can invoke the command as an active function. Usage: lds pathname library_names {-control_args} [lds pathname iibrary_names {-control_args}] where library_names are the names of the libraries whose pathnames are to be returned. You can use the star convention to identify a group of libraries, and you can give up to 30 library names. -descriptor desc name gives the pathname or ref erence name of the library descriptor defining the library roots whose pathnames are to be returned. If you don't choose -descriptor, the default library descriptor is used. -library library_name, -lb library_name identifies a library name that begins with a minus to distinguish the library name from a control argument There are no other differences between library_names and those given with -library. You can supply one or more -library control arguments. default, dft prints the default library name{s) and search name(s) associated with one or more of the library descriptor commands. Usage: lds default {command_names} {-control_arg} where command_names are the names of the library descriptor commands whose default library and search names are to be printed. If you select no command names, the defaults for all the library descriptor commands are printed. control_arg can be -descriptor desc_name gives the pathname or reference name of the library descriptor defining the library roots whose pathnames are to be returned. It can appear anywhere after the key. If you don't choose -descriptor, the default library descriptor is used. 3-484 AG92-06 library_descriptor root, rt prints detailed information about library roots, including the names on each library root, its pathname. and its type. Usage: lds root library_names {-control_args} where library_names are the names of the libraries whose pathnames are to be returned. You can use the star convention to identify a group of libraries, and you can give up to 30 library names. control_args select from the following: -descriptor desc_name gives the pathname or reference name of the library descriptor defining the library roots whose pathnames are to be returned. If you don't choose -descriptor, the default library descriptor is used. -library library_name, -lb library_name identifies a library name that begins with a minus to distinguish the library name from a control argument There are no other differences between library_names and those given with -library. You can supply one or more -library control arguments. -match prints all library root names that match any of the library names. (Default) -name, -nm prints all the names on each library root. -primary, ~pri prints the primary name on each library root. Name: library_retch, If SYNTAX AS A COMMAND If {search_names} {-control_args} 3-485 AG92-Q6 library_fetch FUNCTION fetches entries from a library. It functionally replaces get_library_segment You can fetch segments, archives, archive components, multisegment files (MSFs), and MSF components. ARGUMENTS search_names are star names identifying the library entries to be fetched. Defaults differ for each library descriptor. You can supply up to 1000 search names; if you give none, any default search names specified in the library descriptor are used. CONTROL ARGUMENTS -all, -a includes in the output file complete status information for fetched entries. -all_matches, -amch fetches all matching entries. (Default, if you supply more than one search name, any star names, or -component) -brief, -bf suppresses printing of information about fetched entries. (Default) -chase fetches through links. -components fetches library entries contained in, or -ail_matches. with, a matching entry; it implies -container fetches the library entry containing a matching library entry, rather than the matching entry itself. -default, -dft includes in the output file default status information for fetched entries. -entry, -et fetches matching library entries only. (Default) -descriptor desc_name specifies the descriptor defining the libraries to be searched. -first_match, -fmch fetches the first matching entry only. (Default, if you specify only one search name) 3-486 AG92-06 -into path fetches library entries into the specified pathname (absolute or relative). The directory portion of the pathname identifies the directory into which each library entry is copied; the final entry name of the pathname renames each library entryname being placed on the copy. You can give an equal name as the final entryname of the path. Use -into only once in a command line. If not given, matching entries are copied into your working directory and no renaming occurs. -library library_name, -lb library_name fetches entries in the specified library. You can use star names. You can supply up to 100 -library control arguments; if you give none, any default library names specified in the library descriptor are used. -long, -lg prints information about fetched entries. -match puts entrynames that match a search name on the fetched entry. (Default) -name, -nm puts all the entrynames on the fetched library entry. -no_chase does not fetch through links. (Default) -omit does not fetch library entries awaiting deletion. (Default) -output_file filename, -of filename appends status of fetched library entries to named file. -primary, -pri puts first entryname on fetched library entry. -retain, -ret fetches library entries awaiting deletion. -search_name search_name gives search_name that looks like a control argument You can supply one or more -search_name control arguments. NOTES This command uses a library descriptor and library search procedures, as described in the Mu/tics Li brary Mai ntenance SDN, (Order No. AN80). The initial default descriptor describes the Multics system libraries and allows library_fetch to extract source programs, object segments and bind files, include files and info segments, and compilation listings from the system libraries. (See the library_descriptor command.) 3-487 AG92-()6 library_fetch iibrary_fetch You can give any combination of the control arguments governing naming (-name. -primary, and -match). However, select only one from each· group of the following: -chase or -no_chase; -long or -brief; -container, -components, or -entry; -retain or -omit; and -all or -default You must use -output_file if you give -all or -default The particular status information recorded in the output file for -default is controled by the library search program. It includes the information deemed most important for the type of entry contained in the library. If the file given in -output_file does not exist, it is created by library_fetch; if it does, new status information is appended to the end of the file preserving any previously recorded status. This feature allows you to build a history of the entries copied out of a library. When using -into, ensure that the equal name included in the pathname can be applied to all names to be placed on each of the copied entries. Name duplications can easily result when more than one library entry matches the search names. The -container and -components control arguments facilitate copying all the library entries included in a given bound segment or related to a given subsystem. For example, by identifying a component of the source archive for a bound segment and using -container, the entire source archive is copied into your directory; similarly, by identifying a directory in the library containing all the component entries of a subsystem and using -components, each component is copied into your directory. \\T"ben you use =container, -components, or -chase, it may happen that none of the entrynames on a copied library entry matches any of the search names. Because you may have requested that only matching names be placed on the copies, the library search program places the first entryname on the copy when you select one of these control arguments, in addition to any names you requested. You are given re access to copied object segments and rw access to all other segments. EXAMPLES The command line If abbrev.pll -into >udd>Multics>user>new_=.= copies the source segment abbrev.pIl into the directory >udd >Multics >user , renaming the copy new_abbrev. pIl. If bound_qedx_.** -library online copies all the segments in the online libraries whose names begin with bound_qed x_ into your working directory. This might include the source archive, bindable object archive, bound object segment, and bind listing. If bound_qedx_.** -library online.source -components 3-488 AG92-o6 copies all the source components from the source archive for bound_qedx_ into your directory. 1f qedx. p 11 -componen ts copies all the source components in the archive containing qedx. pll into your working directory. 1f *.alm -lb network.source -into new_=.alm copies all ALM source segments from the network source library into your working directory and adds the prefix new_to the names placed on each segment If pll_status.info -nm -Ib infof copies the pll_status.info segment from the info segment libraries into your working directory, copying all entrynames from the library entry onto the copy. If **.ec -library online.?????? copies all exec_com segments from the online source and object libraries into your working directory. If -lb supervisor.bc bound_sss_wired_.* copies the 'bind segment from the bindable object archive called bound_sss_wired_.archive. Although the object archive itself matches the search name you gave, only the matching archive component is copied because you didn't supply -container. If -lb include stack_frame.incl.* copies the stack frame declaration include segments for all source languages from the include library into your working directory. Name: line_length, II SYNTAX AS A COMMAND i i {max i ength} SYNTAX AS AN ACTIVE FUNCTION [11 {max 1ength}] 3-489 AG92-()6 link FUNCTION allows you to control the maximum length of a line output to the device (usually your terminal) that your process is connected to through the user_output I/O switch. ARGUMENTS maxlength is a positive decimal number greater than four that specifies the maximum number of characters that can henceforth be printed on a single line using the I/O switch named user_output. If you don't give it, the current line length is printed. Output lines longer than maxlength are folded. NOTES As an active function, the current line length setting is returned and a new one set if you supply maxlength. Name: link, lk SYNTAX AS A COMMAND lk pathl {path2 ••• pathlN path2N} {-control_args} FUNCTION creates a storage system link with a specified name in a specified directory pointing to a specified segment, directory, or Hnk (for a discussion of links, see the Programmer's Reference ManuaI). ARGUMENTS path! specifies the pathname of the storage system entry to which path2N is to point The star convention is allowed. Give the pathnames in pairs. path2 specifies the pathname of the link to be created. If omitted' (in the final argument position of a command line only), a link to pathl is created in your working directory with the entryname portion of pathlN as its entryname. The equal convention is allowed. CONTROL ARGUMENTS -chase creates a link to the ultimate target of pathl if pathl is a link. The default is to create a link to pathl itself. 3-490 AG92-06 link link -check, -ck refuses to create a link if the target does not exist or if its existence cannot be determined due to access. -copy_names, -cpnm copies the names of the target to the link after creating it -name STR, -nm STR specifies an entryname STR (either as a path1 or a path2, depending on position) that begins with a minus to distinguish it from a control argument -no_chase creates a link directly to the target specified. (Default) -no_check, -nck creates a link whether or not the target exists. (Default) -no_copy_names, -ncpnm does not copy the names of the target (Default) ACCESS REQUIRED You must have append permission f or the directory in which the link is to be created. NOTES Entrynames must be unique within the directory. If the creation of a specified link introduces a duplication of names within the directory and if the old entry has only one name, you are asked whether to delete the entry with the old name. If you answer "no," the link is not created. If the old entry has multiple names, the conflicting name is removed and a message is issued to you. In either case. since the directory in which the link is to be created is being changed. you must have modify permission for that directory. See the create_dir and create commands for the creation of directories and segments. EXAMPLES The command line lk >my_dir>beta alpha >dictionary>grammar creates two links. alpha and grammar. in the working directory: the first points to the segment beta in the directory >my_dir, the second to the segment grammar in the directory >dictionary. 3-491 AG92-06 Name: linkage_editor, Ie SYNTAX AS A COMMAND ie paths {-control arguments} FUNCTION Joms a series of object segments into a single execution unit resolving external references to the explicitly named segment(s) within the named libraries. ARGUMENTS paths are specifications of the input binaries that are to be included in the output binary. Valid formats for a path specification are: Archive Library archives are unbound archives containing object segments that you can use to resolve external references. To specify a library archive, include the suffix .archive in the name. Directory You can specify library directories that contain loose object segments to which external references can be resolved. Any archives found in the directory are expanded and all the components included. Pathname You can specify pathnames to specific segments or archive components. Starname You can specify starnames specifying groups of loose segments within a directory or an archive component starname specifying a set of components within a particular archive. A starname that includes archives expands each archive. CONTROL ARGUMENTS -abort_severity severity, -asv severity specifies the error severity at which the execution should be terminated; it must be from 0 to 3 (see "Notes on Severity Values" below). Severity 0 errors generate the tables and attempt to resolve links, but stop before generating any output Severity 4 errors are terminated immediately. (Default: 3, if you give no -asv) -automatic_segnames, -asn specifies that entrypoint names are to be automatically added to the containing block as segnames, so that a reference to the entrypoint name alone resolves to the correct block. (Default) 11/86 3-492 AG92-06A -component_size pages, -compsz pages specifies the maximum number of pages that a single component of the output object should contain. This value is used to determine at what point the transition is made from single-segment to multisegment file (MSF) and the size of an individual MSF component (Default: 255, if you supply no -compsz) -delete {entrypointl, -dl {entrypointJ deletes the given entrypoint from the output binary. If you give no entrypoint name, all entrypoints are deleted except the "main_" definition and its associated segnames, if present You can remove this definition by using "-delete main_ft. -display_severity severity, -dsv severity sets the display severity to the given value. The display severity is the mmlDlum severity error that displays a message; it must be from 1 to 5. (Default: 1) -force, -fc suppresses the query before overwriting a nonobject segment or an object segment created by a translator. -library library_specification, -lb library_specification specifies one or more object library routines that the linkage editor uses to resolve external references; The library specification is in the same form. and is evaluated in the same manner, as the input path specification. -list, -Is creates a listing specifying what segments were involved in the creation of the linked segment, the disposition of each in.put component, and a list of the retained links and definitions. The name of the listing segment is the same as the output binary with a .list suffix appended. -map creates a map of the input components and where they were placed. The name of the listing segment is the same as the output binary with a .list suffix appended. -no_automatic_segnames, -nasn does not add entrypoint names to the containing block as segname definitions. This control argument has the same behavior as the binder, and requires that you reference entrypoints with the name of the containing module (i.e., segment$entrypoint), to be resolved internally. -no_force, -nfc queries before overwriting a nonobject segment or an object created by a translator. (Def aul!) -no_list, -nIs does not produce a listing segment. (Default) 11/86 3-4921 AG92-06A -no_version, -nvers does not print out the version of the linkage editor. -output_file pathname, -of pathname specifies the pathname of the output binary to be created. If you give no -of, the output binary is created in your working directory with the name a.out Before generating the output, linkage_editor checks to insure that the target either is nonexistent or was a bound object prior to overwriting. If the target is not an object, or was not created by linkage_editor, you are queried before it is overwritten unless you give -fc. -retain entrypoint, -ret entrypoint specifies an entrypoint that should be retained. The entrypoint is given in the form segname$entryname. The entrypoint is found by conventional methods, and that definition and all segname definitions for that block are retained in the final output If you give no -ret or -dl, all segnames and entrypoints are retained. If you give any -ret, all other entrypoint and segname definitions are deleted except the "main_" definition, which is always retained, along with its associated segnames, unless deleted by using "-delete main_". -version, -vers prints out the version of the linkage editor before linking. (Default) NOTES When specifying an entrypoint as a pair of starnames: one entrypoint name portion. Parts you supply -ret but no -dl. with -ret or -dl, the entrypoint name given is treated starname for the segname portion and one for the of the entrypoint not given are assumed to be **. If a global -dl is assumed; otherwise a global -ret is ass~ed. When determining which -ret or -dl to apply to any given definition, the most and least specific rules are applied: 1. The following list shows the order from the most specific to the least specific rule. The most specific rule is applied first. most specific: explicit segname and entrypoint star segname and explicit entrypoint any segname and explicit entrypoint explicit segname and star entrypoint star segname and entrypoint any segname and star entrypoint explicit segname and any entrypoint star segname and any entrypoint least specific: any segname and entrypoint 11/86 3-492.2 AG92-06A links where "any" name refers to a star name that matches any name, ;;starr. name refers to a star name that is ambiguous (i.e., contains * or ? characters) but does not match all names, and "explicit name refers to a name with no * or ? characters. tt 2. Entrypoint specs with the same class above are ordered based on the order they occurred in the input If two star names both match a given entrypoint, the first you give on the command line is used. Here are some examples: -retain -retain -retain -retain -retain = -retain bar$foo foo barS bar$foo **$foo - -retain bar$** = -reta in *'''$** = -retain b?1$** = -retain b??$ NOTES ON SEVERITY VALUES This command associates the following severity values to be used by the severity active function: Value Meaning o No error 1 2 .,'1 Warning 4 lJnrecoverab1e error Correctable error Name: links SYNTAX AS A COMMAND links star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [links star=names {-control~args}] FUNCTION returns the entrynames or absolute pathnames of links that match one or more star names. 11/86 3-492.3 AG92-06A list links ARGUMENTS star_names is a star name to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per link is returned; i.e., if a link has more than one name that matches star_name, only the first match found is returned. Since each entryname (or pathname) returned by links is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: list, Is SYNTAX AS A COMMAND Is {entrynames} {-control_args} FUNCTION prints information about entries contained in a single directory. There are five entry types supported by this command: segments, multisegment files (MSFs), data management (DM) files, directories, and links. Segments, DM files, and MSFs are referred to collectively as files; segments, MSFs. DM files, and directories are referred to collectively as branches. 11/86 3-492.4 AG92-06A list list ARGUMENTS entrynames are the names of entries to be listed. The star convention is allowed. If you specify entrynames. only entries having at least one name matching an entryname argument are listed; if you supply no entryname argument. all entries (of the types given by control arguments) in the directory are listed. You can specify a pathname instead of an entryname; in this case, entries matching the entryname portion of the pathname in the directory specified by the directory portion of the pathname are listed. (See "Control Arguments for Directory.") Except where otherwise noted in the descriptions of the control arguments, entrynames and control_args can appear anywhere on the command line. CONTROL ARGUMENTS Control arguments enable you to specify the directory to be listed, which entries are to be listed, the amount and kind of information 'to be printed for each entry, and the order in which the entries are to be listed. For convenience, control arguments have been arranged by function. directory -pathname path. -pn path columns -count, -ct -date_time_contents_modified. -dtcm -date_time_entry_modified, -dtem -date_time_used, -dtu -length, -In -link_path. -lp -mode, -md -name. -nm -record. -rec entry type -all. :"'a -branch, -br -data_management_file. -dmf -directory, -dr -file, -f -link. -lk -multisegment_file. -msf -segmen t, -sm totals/header line -no_header. =nhe -total. -tt entry exclusion -exclude entryname, -ex entryname -first N, -ft N -from D, -fm D -to D multiple-name entries -match -primary. -pri output format -brief. -bf -short, -sh entry order -reverse, -rv -sort XX, -sr XX CONTROL ARGUMENTS FOR DIRECTORY If you give no directory, your working directory is assumed. This command can list only one directory at a time. 3-493 AG92-06 list list -pathname path, -pn path lists entries in the directory specified by path. You can specify the directory to be listed by gIvIng a pathname instead of an entryname. The difference between the two methods is that the entire pathname after ..;.pathname is taken to be that of a directory whose entries are to be listed, while a pathname not preceded by -pathname is separated into its directory and entryname portions; the former specifies the directory, the latter the entries within it that are to be listed. CONTROL ARGUMENTS FOR ENTRY TYPE -all, -a lists information about all entry types in the following multisegment files, data management files, directories, and links. -branch, -br lists information about branches (i.e., segments, data_management_files, and directories, in that order). order: segments, multisegment files, -data_management_file, -dmf lists data management files. -directory, -dr lists information about directories. -file, -f lists information about files (i.e., segments, multisegment files, and data management files, in that order). (Default) -link, -Ik lists information about links. -multisegment_file. -msf lists information about multisegment files. -segment, -sm lists information about segments. CONTROL ARGUMENTS FOR COLUMNS -count, -ct prints the count column, which gives the total number of names for entries that have more than one name. -date_time_contents_modified, -dtcm prints the date and time the contents of the segment or directory were last modified. This control argument is inconsistent with and more expensive than -date_time_entry_modified. 3-494 AG92-()6 list list -date_time_entry_modified, -dtem prints the date and time the entry was last modified (e.g., by the changing of attributes such as names, ACL, or bit count). -date_time_used, -dtu prints the date and time the entry was last used. -length, -In prints the current length computed from the bit count. This control argument is inconsistent with and less expensive than -record. (Default) -link_path, -lp prints the link-path column. -mode. -md prints the access-mode column. -name, -nm prints the names column, giving the primary name and any additional names of each entry. The names column is printed in every invocation of the command except when you explicitly request only totals information. -record, -ree prints the records used. If you supply no control arguments from this category, the access-mode, length, and names columns (in that order) are printed for branches and the names and link-path columns (in that order) are printed for links. Vlhen you give -brief, -mode, -record, -length. or -name. only the names column plus those columns explicitly selected by control arguments is printed. CONTROL ARGUMENTS FOR TOTALS AND HEADER LlNE -no_header, -nh~ omits all heading lines. -total, -tt prints only the heading line (totals information) for each entry type specified; this line ~ves the total number of entries and the sum of their sizes. If you select neither -no_header nor -total, totals and detailed information are printed. CONTROL ARGUMENTS FOR MULTIPLE-NAME ENTRIES -match prints in the names column only those uimes that match one of the given entrynames. 3-495 AG92-06 list list -primary, -pri prints in the names column the primary name of each entry. not its secondary names. It does not suppress the printing of any other columns. These control arguments are applicable only to entries that have more than one name. If you give neither one, all the names of the specified entries are printed. CONTROL ARGUMENTS FOR ENTRY ORDER -reverse. -rv prints entries in the reverse order in which they are found in the directory. If you also supply -sort, the specified sort is reversed. -sort xx. -sr XX sorts entries within each entry type according to the sort column XX, where XX can be one of the following (see "Notes on Sorting" below): count, ct sort entries by number of names, the ones with the most names first date_time_contents_modified, dtcm sort entries by the date and time the contents of the entry were modif ied, the most recent ones first. This argumen t is inconsisten t -date_time_entry_modified. If you choose -date_time_contents_modified no key follows -sort, that control argument is implied as the default key. last wi th and sort date_time_entry_modified, dtem sort entries by the date and time the entry was last modified, the most recent ones first. This argument is inconsisten t with -date_time_contents_modified. If you supply -date_time_con ten ts_modified and no key follows -sort, that control argument is implied as the default sort key. date_time_used, dtu sort entries by the date and time used, the most recent ones first length. In sort entries by length computed from the bit count, the largest ones first. This argument is inconsistent with -record. mode, md sort entries by access mode in this order: nUll, r (or s), rw (or sm), re, rew (or sma). This order is the result of sorting by the internal representation of the mode. name, nm sort entries by primary name. according to the standard ASCII collating sequence. 3-496 AG92-o6 list list record, rec sort entries by records used. the largest ones first This argument is inconsistent with -length. If you specify record and the size column is being printed, the value printed in that column is records used, rather than length· If you use neither -reverse nor -sort, entries are printed in the order in which they are found in the directory. CONTROL ARGUMENTS FOR ENTRY EXCLUSION The following control arguments limit the amount of output produced by excluding entries according to either n.ame or date or by setting an upper limit on the number of entries listed. ' -exclude {entryname}, -ex {entryname} does not list entries having at least one name that matches the specified entryname. The star convention is allowed. The entryname specified in -exclude and any names specified in the entrynames argument to the command operate together to limit the entries that are listed. -first N, -ft N lists only the first N entries (after sorting, if specified) of each entry type being listed. The heading lines contain the totals figures for all entries that would have been listed had you not given -first The following two control arguments exclude entries according to date. The date used in this comparison is the modification-date value in all cases except when the only date column being printed or sorted on is the date-time-used column. If no date column is being printed, the date-time-entry-modified value is used. -from D, -fm D does not list any entries having a date value before the one specified by D. -to D does not list any entries having a date value after the one specified by D. The D value after -from or -to must be a string acceptable to convert_date_to_binary_, If the date-time string contains spaces, enclose the string in .quotes. The D value specifies both a date and a time; if you give only a date, convert_date_to_binary_ uses the current time as the default If you supply both -from and -to, the -from value must be earlier than the -to value. 3-497 AG92-06 list list CONTROL ARGUMENTS FOR OUTPUT FORMAT -brief, -bf if just totals information is being printed, -brief abbreviates and prints on a single line the totals information for all selected entry types; otherwise. it does not print the default columns when you don't explicitly name them in control arguments. For example, typing: ls -dtu -bf prints the names and date-time-used columns, but not the access-mode and length columns. -short, -sh prints link pathnames starting two spaces after their entrynames, instead of aligning them in column position 35. If you select neither -brief nor -short, the output format is not changed. NOTES The set of possible columns is different for branches and links. For branches the set (with column order from left to right) is modification date, date and time used, access mode, size, names, and number of names; for links: date and time entry modified, names, number of names, and link pathname. The modification-date column contains either the date and time the entry was modified or the date and time the contents were modified; the size column contains either records used or length (in records) computed from the bit count, as specified by control arguments. Unless otherwise specified by control arguments, these are the items printed for branches: access modes, length. and names; for links: names and link pathname. The obsolete name for a modification date (date_time_modified, dtm) is accepted. in both the control argument and sort key form, as a synonym for the date-time-entry-modified value. Links do not have a date-time-contents-modified value. If you are listing links and give either modification-date value for printing. sorting, or entry exclusion (using -from and -to), the date-time-entry-modified value of links is used. NOTES ON SORTING It is not necessary for a column to be printed in order to sort on it, but note the restrictions described earlier regarding sorting on and printing the modification-date and size columns. If you omit the sort column XX, the default sorting column is determined as follows: if no date column is being printed, sort by primary name; if only one of the date columns is being printed, sort by that date; if both the modification-date and date-time-used columns are being printed, sort by the modification-date column. 3-498 AG92-D6 list list You can only sort links by the name, modification-date, or count columns. If you specify sorting by any other column, links are printed in the order in which they are found in the directory, while branches (if also being listed) are sorted by the specified column. (See "Notes" above.) NOTES ON THE DEFAULT If you invoke the command without any arguments, it lists all segments and multisegment files in the working directory thus: access mode, length of each, and name(s). Segments and multisegment files are listed separately (segments first), each preceded by a line giving the total entries of that type and the sum of their lengths. Within each entry type, entries are listed in the order in which they are found in the directory. EXAMPLES The command line ls -pri -ct lists all files in your working directory (default); the names column contains only the primary names of all entries; the total number of names (for entries having more than one) is printed after the primary name; besides the names column. the access-mode and length columns are printed. The command line 1s -ex '1~.-.': lists all the files in your working directory having other than two-component names, printing the three default columns (access mode, length, and names). The command line ls -sm *.* -ex *.pll lists all the segments in your working directory having two-component names whose second component is not pU, printing the default columns. The command line ls -dtem -sr lists all files in your working directQry, sorted by the date-time-entry-modified column. The date-time-entry-modified and the default columns are printed. 3-499 AG92-Q6 list The command line ls -nm -sr dtm lists all files in your working directory, sorted by the date-time-entry-modified value. Only the names column is printed. The argument dtm is a synonym for dtem. The command line ls -sm -nm -pri -nhe lists only the primary name of each segment in your working directory without printing the heading line or any blank lines. This combination of arguments, together with the file_output command, is useful for generating a file that contains the primary names of a selected set of entries. The command line ls -md -pri lists the access mode and primary name of each file in your working directory. The command line ls -tt -to "7/1/84 000.0" -dtu -rec Prints the totals for all files that have not been used since the end of June 1984. The -dtu control argument is used to specify that the -to date refers to the date and time used. SYNTAX AS A COMMAND lar {path} {-control_args} FUNCTION lists requests in the absentee queues. ARGUMENTS path is the pathname of a request to be listed. The star convention is allowed. Only requests matching this pathname are selected. If you don't supply path. all pathnames are selected. This argument is incompatible with -entry. 3-500 AG92-()6 CONTROL ARGUMENTS -absolute_pathname, -absp prints the full pathname of each request selected, rather than the entryname. -admin {User_id}, -am {User_id} selects the requests of all users or of the user specified by User_ide If you don't choose -am, only your own requests are selected. (See "Notes.") -all, -a searches all queues and prints the totals for each nonempty queue whether or not any requests are selected from it If you specify no -a, nothing is printed for queues from which no requests are selected. This control argument is incompatible with -q. -brief. -bf does not print the state and comment of each request This control argument is incompatible with -lg and -tt -deferred_indefinitely, -dfi selects only requests that are deferred indefinitely. Such requests are not run until the operator releases them. -entry STR, -et STR selects only requests whose entrynames match STR. You can use the star convention. Directory portions of request pathnames are ignored when selecting requests. -foreground, -fg searches only the foreground queue and prints the totals for this queue whether or not any requests are selected from it (see -q). -id ID selects only requests whose identifier matches the specified ID. -immediate, -im selects only requests that can be run immediately upon reaching the heads of their respective queues. This excludes requests deferred indefinitely, requests deferred until a specific time. or requests that have reached the head of the queue and have been deferred by the system because their CPU time limits are higher than the maximum for the current shift; but it includes requests deferred because of load control or resource unavailability. because those conditions could change at any time. (See -psn.) -long, -lg prints all the information pertaining to an absentee request, including the long request identifier and the full pathname. If you omit -180 only the short request identifier. entryname. state, and any comment, are printed. 3-501 AG92-06 -lonLid, -lgid prints the long form of the request identifier. If you supply no -lgid, the short form of the request identifier is printed. -pathname, -pn prints the full pathname of each selected request, just as -absp does. -position, -psn prints the position within its queue of each selected request When used with -tt, it prints a list of all the positions of the selected requests. When used with -im, it considers only immediate requests when computing positions. -queue N, -q N searches only queue N and prints requests are selected from it If nothing is printed for queues convenience in writing exec_corns following -q is equivalent to -fg. the totals for that queue whether or not you give no -q, all queues are searched from which no requests are selected. and abbreviations, the word "foreground" any but For (fg) -resource {STR}. -rsc {STR} selects only requests having a resource requirement If you specify STR, only requests whose resource descriptions contain that string are chosen. This control argument also prints the resource descriptions of the selected requests, even when you supply no -lg. (See the reserve_resource command for details on resource description specification.) -restarted prints only requests that have been restarted by the system after a system crash (see "Notes"). -sender STR lists only requests from sender STR. You must specify one or more request identifiers. In most cases, the sender is an RJE station identifier. -total, -tt prints only the total number of selected requests and the total number of requests in the queue, plus a list of positions if you choose -psn. If the queue is empty, it is not listed. -truncate, -tc prints only the requests that have the -tc absout option (see "Notes"). -truncate_restarted. -tc_restarted prints only those requests that have the -tc absout option and that also have been restarted after a system crash (see "Notes"). -user User_id selects only requests entered by the specified user (see "Notes"). 11/86 3-502 AG92-()6A ACCESS REQUIRED You must have 0 access to the queue(s). You must have r extended access to the queue(s) to use -am, -psn. or -user, since it is necessary to read all requests in the queue(s) to select those entered by a specified user or to co~pute the positions of the chosen requests. NOTES All queues are searched for your requests. The request identification, entryname. state, and any comment of each request is printed. If you supply no arguments, only your own requests are selected. Nothing is printed for queues from which no requests are chosen. (See enter_abs_request) When you give a user name with -am or -user, a proxy request is chosen if either your name or the proxy user's one on whose behalf you entered the request matches the specified user name. The entry portion of the pathname argument, the entryname given with -et, and the RJE station name specified after -sender can be star names. The User_id arguments selected after -am or -userean have any of the following forms: Person_id.Project_id Person_id.* D.8 .... " .... I 'WI :..a "'''''11_1'''' *. Proj ect_i d .Project_id ,-c. * matches matches same as matches same as same as that user only that person on any project Peison_id.* any user on that project *.Project_id -am with no User_id following it Use "enter_abs_request -tc" if you want the absout file of an absentee request to be truncated before the job is run. Truncation occurs as the job starts up, unless a system crash has occurred. If the request is restarted, the truncation indicator is ignored and the output of the interrupted job is appended to the absout file. Name: list_accessible, lac SYNTAX AS A COMMAND lac {path {User_id}} {-control_args} FUNCTION scans a directory and lists segments, multisegment files (MSFs), and directories with a specified access for a given User_ide 11/86 3-503 AG92-06A ARGUMENTS path is the pathname of the directory to be scanned. If you omit it, or if you supply -workinLdirectory (-wd) , your working directory is scanned. User_id is an access name. If you omit it. the User_id of the calling process with a star tag is assumed. It can have null components. You can use the star convention for access names (see the set_acl command). CONTROL ARGUMENtS If you select no control arguments, all the segments and directories to which the named user(s) has nonnull access are listed. -dir_mode STR lists directories to which the named user(s) has any of the modes stated in STR, where STR can be any or all the letters sma. -ses-mode STR lists segments to which the named user(s) has any of the modes indicated in STR, where STR can be any or all the letters rew. ACCESS REQUIRED You must have s permission on the directory. NOTES You can't use User_id unless you have first suppiied a path. If there are more than one User_id (i.e., the specified User_id has null components), the modes for each matched User_id are listed on a per-entry basis. SYNTAX AS A COMMAND la {path} {User_ids} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [la {path} {User_ids} {-control_args}] 11/86 3-504 AG92-06A FUNCTION lists the access control lists (ACLs) of nonlink entries in a directory. ARGUMENTS path is the patbname of an entry. If it is -workins-directory (-wd). your working directory is assumed. You can use the star convention. 11/86 3-504.1 AG92-()6A This page intentionally left blank. 11/86 AG92-06A User_ids are access control names of the form Person_id.Project_id.tag. All ACL entries with matching names are listed. If you don't give User_ids. the entire ACL is listed. CONTROL ARGUMENTS -brief, -bf suppresses the message "User name not on ACL of path." If you invoke list_acl as an active function and User_id is not on the ACL, the null string is returned. -chase chases links matching a star name. Links are always chased when path is not a star name. -directory, -dr lists the ACLs of directories only (see "Notes" below). multisegment files, and directories) (Default: segments, -in terpret_as_extended_en try , -inaee interpret the selected entry as an extended entry type. -interpret_as_standard_entry, -inase interpret the selected entry as a standard entry type. -no_chase does not chase links. (Default) -rin~brackets, -rb lists the ring brackets. Not valid in the active function. -segment, -sm lists the ACLs of segments and multisegment files only. -select_entry_type STR, -slet STR affects only entries of the entry type selected by STR, which is a comma-delimited list of file system entry types. Use the list_entry_types command to obtain a list of valid entry type values. ACCESS REQUIRED You need status permission en t..~e directory. NOTES This command provides effective access information only when discretionary access control is being used (regulated by an ACL). If either nondiscretionary access control (regulated by the AIM) or intraprocess access control (regulated by the ring structure) is in operation, use the status command to determine actual access. 3-505 AG92-Q The -directory, -segment, and -select_entry_type control arguments are used to resolve an ambiguous choice that may occur when path is a star name. If you invoke list_acl with no arguments, it lists the entire ACL of your working directory. For a description of ACLs and ring brackets, see the Programmer's Reference Manual. For a description of the matching strategy, see set_acl. EXAMPLES The command line la notice.runoff .Faculty. Milton lists, from the ACL of notice.runoff, all entries with Project_id Faculty and the entry for Milton.*.*. The command line la ,'c.pll -rb lists the whole ACL and the ring brackets of every segment in the working directory that has a two-component name with a second component of pll. The command line la -wd -rb .Faculty. *.*.* lists access modes and ring brackets for all entries on the working directory's ACL whose middle component is Faculty and for the *.*.* entry. Name: list_daemon_requests, ldr SYNTAX AS A COMMAND ldr {path} {-control_args} FUNCTION lists requests in the I/O daemon queues. The request identifier and entryname of each request are printed. 3-506 AG92-06 • ARGUMENTS path is the pathname of a request to be listed. The star convention is allowed. Only requests matching this pathname are selected. If you give no path, all pathnames are selected. This argument is incompatible with -entry. CONTROL ARGUMENTS -absolute_pathname, -absp prints the full pathname of each selected request, rather than the just entryname. -admin {User_id}, -am {User_id} selects the requests of all users, or of the user specified by User_id. If you don't choose -admin, only your own requests are selected. This control argument is incompatible with -user. (See "Access Required" and "Notes" below.) -all, -a searches all queues and prints the totals for each non empty queue whether or not any requests are selected from it. If you supply no -all, the default queue is searched. This control argument is incompatible with -queue. -brief, -bf does not print the state and comment of each request. This control argument is incompatible with -long and -total. -entry STR. -et STR selects only requests whose entrynames match STR. The star convention is allowed. Directory portions of request pathnames are ignored when selecting requests. -id ID selects only requests whose identifier matches the specified ID. -immediate, -im selects only requests that can be the I/O daemon. r1L~ immediately and skips requests deferred by -long, -lg prints all the information about each selected request including the long request identifier and the full pathname. If you omit -long, only the short request identifier. entry name. and state are printed. -lon&-id. -lgid prints the long the request identifier. -position. -psn prints the position within its queue of each selected request When used with -total. it prints a list of all the positions of the selected requests. (See "Access Required" and "Notes. n) 3-507 AG92-()6 -queue N, -q N searches only queue N. If you don't select -queue, all queues are searched but nothing is printed for queues from which no requests are selected. -request_type STR, -rqt STR specifies that requests are to be found in the queue f or the request type identified by STR. If you give no -request_type, the default is ttprinter". List request types with print_request_types. -total, -tt prints only the total number of selected requests and the total number of requests in the queue plus a list of positions if you choose -position. If the queue is empty, it is not listed. -user User_id selects only requests entered by the specified user. (See "Access Required" and Notes.") ACCESS REQUIRED You must have 0 access to the queue(s). You must have r extended access to the queue(s) to use -admin, -position, or -user, since it is necessary to read all requests in the queue(s) to select those entered by a specified user or to compute the positions of the chosen requests. NOTES The User_id arguments specified after -admin or -user can have any of the following forms: Person_id.Project_id Person_id.* Person_id *.Project_id • Proj ect_ i d ,,:. * matches matches same as matches same as same as that usei only that person on any project Person id.* any user on that project *.Project_id -admin with no User_id following it. The state is printed only if it is deferred and you don't supply -brief. 3-508 AG92-o6 SYNTAX AS A COMMAND FUNCTION lists the contents of a directory information segment created by save_dir_info. ARGUMENTS path is the pathname of the directory information segment. If path does not end in the suffix dir_info. it is assumed. CONTROL ARGUMENTS -brief, -bf produces a short output. -long. -lg produces a long output NOTES If you provide neither -long nor -brief, an intermediate verbosity level is used. The output of this command is written on the user_output I/O switch. For each entry, a series of lines of the form item name: value is written. Entries are separated by a blank line. See the list_dir_info_ subroutine for information on the items printed for each verbosity level. 3-509 AG92-()6 SYNTAX AS A COMMAND FUNCTION produces a list of all known Emacs terminal types. or verifies the existence in your search rules of specified Emacs terminal controllers. ARGUMENTS terminal_type is a terminal type name. It can be a single starname. NOTES When given with no arguments, this command lists all Emacs terminal types. When given with the name of a terminal type as an argument, list_emacs_ctls either verifies the existence of any Emacs terminal controller in your search rules that matches the starname or prints the message "No Emacs terminal controllers found." Name: list_entry_types, lset SYNTAX AS A COMMAND lset SYNTAX AS AN ACTIVE FUNCTION [1 set] FUNCTION prints or returns a list of all the file system entry types that can be found using your search rules. 3-510 AG92-06 Name: list_external_variables, lev SYNTAX AS A COMMAND lev names {-control_args} FUNCTION prints information about variables managed by the system for the user, including FORTRAN common and PL/I external static variables whose names do not contain dollar signs. The default information is the location and size of each specified variable. ARGUMENTS names are names of external variables, separated by spaces. CONTROL ARGUMENTS -all. -a prints information for each variable the system is managing. -lon~ -lg prints how and when the variables were allocated. -no_header, -nhe suppresses the header. -unlabeled_common, -uc is the name for unlabeled (or blank) common. Name: list_fort ran_storage, Ifs SYNTAX AS A COMMAND lfs FUNCTION lists the extended storage segments assigned to the process, grouped according to the storage to which they are extensions. 3-511 AG92-06 Name: list_heap_variables, lhv SYNTAX AS A COMMAND Ihv names {-control_args} FUNCTION prints information concerning heap variables. Only variables at the specified execution level(s) are printed. The default information is the location and size of each specified variable. A level description is printed for each execution level specified. The heap variables are displayed starting at the lowest execution level specified. ARGUMENTS names are names of external variables. separated by spaces. CONTROL ARGUMENTS -all. -a prints information for all heap levels. Starting at execution level 0 and ending with the current execution level. -brief. -bf prints out the variable name. size, and where it is allocated. (Default) -from level specifies 'what execution level to start printing variables at execution level 0 is assumed, If not present, -header. ~he prints the header. (Default) -long. -lg prints how and when the variables were allocated. -no_header. -nhe suppresses printing of the header. -to level specifies what execution level to stop printing variables at If not present. the current execution level is assumed. NOTES Use -from and -to together to specify a range of execution levels to be printed. If you give none, the current execution level is assumed. 11/86 3-512 AG92-o6A Name: list_help, lh SYNTAX AS A COMAIJAND Ih topics {-control_args} SYNTAX AS AN ACTIVE FUNCTION [lh topics {-control args}] FUNCTION displays the names of all info segments (info segs) pertaining to a given topic. ARGUMENTS topics are strings to be searched for in info seg names. CONTROL ARGUMENTS -absolute_pathname, -absp prints or returns full pathnames of info segs. rather than entrynames. -all, -a displays the names of all info segs. (Default: to display the names of only those info segs whose names match the topics specified) -brief, -bf does not display the alternate names of the info segs. You can t use -brief in the active function. (Default: to display them) 9 -no_sort does not sort the output (Default) -pathname path, -pn path specifies the pathname of a directory to search for applicable segments. Multiple -pathname control arguments are allowed. (See "Notes.") (Default: to search the directories in the info_segments search list) -sort sorts the output in ascending alphabetic order using as key the primary nam.e of the info segs. If you give -absoiute_pathname. -sort uses the entry name part of it as primary name. NOTES An info seg is considered to pertain to a given topic if the topic name appears in (i.e.. is a substring of) the inf 0 seg name. The active function returns the selected names separated by spaces. For information on info segs, see the help command. 11/86 3-512.1 AG92-06A This page intentionally left blank. 11/86 AG92-06A The default info seg directories contain info segs provided by the site and those supplied with the system. Type "print_search_patbs info_segments" to see what the current info segs search list is. For information about search lists. see the search facility commands--add_search_paths. in particular. SYNTAX AS A COMMAND lid {path} {User_ids} {-control_args} SYNTAX AS AN ACTIVE FUNCTIOIV [lid {path} {User_ids} {-control args}] FUNCTION lists some or all the entries on a directory initial access control list (initial ACL) of a specified directory. ARGUMENTS path specifies the directory in which the directory initial ACL should be listed. If path is -workin~directory (-wd) or omitted, your working directory is assumed; if omitted, you cannot specify User_ids. The star convention is allowed. User_ids are access control names of the form Person_id.Project_id. tag. All access names matching the given User_ids are listed. If you don't give User_id. the entire initial ACL is listed. CONTROL ARGUMENTS -brief, -bf suppresses the message "User name not on ACL of path." If you invoke lid as an active function and User_id is not on the initial ACL, the null string is returned. -chase chases links matching a star name. (Default: to chase a link only when specified by a nonstarred pathname) -no_chase does not chase links. 3-513 AG92-()6 -ring N, -rg N identifies the ring number whose directory initial ACL is to be listed. It can appear anywhere on the line and affects the whole line. If present. follow it by N (where 0 <= N <= 7). If omitted, your ring is assumed. ACCESS REQUIRED You require status permission on the containing directory. NOTES If you invoke list_iacl_dir without any arguments, the entire initial ACL for your working directory is listed. A directory initial ACL contains the ACL entries to be placed on directories created in the specified directory. For information on initial ACLs. see the Programmer's Reference Manual. description of the matching strategy for User_ids, see the set_acl command. For a EXAMPLES The command line lid all runoff .Faculty Erasmus .• lists, from the directory initial ACL of the all_runoff directory, all entries ending in Faculty.* and all entries with the Person_id Erasmus. The command line 1 i d -wd -rg 5 lists entries in the ring 5 directory initial ACL of the working directory. SYNT AX AS A COMMAND lis {path} {User_ids} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [lis {path} {User_ids} {-control_args}] 3-514 AG92-06 FUNCTION lists some or all the entries on a segment initial access control list (initial ACL) in a specified directory. ARGUMENTS path specifies the directory in which the directory initial ACL should be listed. If path is -workins-directory (-wd) or omitted, then your working directory is assumed. If omitted, you can't specify User_ids. The star convention is allowed. User_ids are access control names of the form Person_id.Project_id.tag. All access names matching the given User_ids are listed. If you don't give User_id, the entire initial ACL is listed. CONTROL ARGUMENTS -brief, -bf suppresses the message "User name not on ACL of path." If you invoke lid as an active function and User_id is not on the initial ACL. the null string is returned. -chase chases links matching a star name. (Default: to chase a link only when specified by a nonstarred pathname) -no_chase does not chase links. -ring N, -rg N identifies the ring number whose directory initial ACL is to be listed. It can appear anywhere on the line and affects the whole line. If present, follow it by N (where 0 <= N <= 7). If omitted, your ring is aSsumed. ACCESS REQUIRED You need status permission on the containing directory. NOTES ii you invoke list_iacl_seg without any argw-nents, the entire initial ACL for your working directory is listed. A segment initial ACL contains the ACL entries to be placed on segments created in the specified directory. For information on initial ACLs, see the Programmer's Reference Manual. description of the matching strategy for User_ids, see the set_acl command. 3-515 For a AG92-D6 EXAMPLES The command line lis all_runoff .Faculty. Whitehead lists, from the segment initial ACL of the all_runoff directory, all entries with the Project_id Faculty and the entry for Whitehead.*.*. The command line lis -wd -rg 5 lists entries in the ring 5 segment initial ACL of the working directory. Name: list_mdir, Imd SYNTAX AS A COMMAND lmd volume_names {-control_args} FUNCTION prints logical volume and master directory quotas. ARGUMENTS volume_names are the names of the logical volumes. CONTROL ARGUMENTS -account User_ids specifies a list of quota account names for which information is desired, where each User_id is of the form Person_id.Project_id. You can't use asterisks when specifying quota account names. Asterisks in account names only match quota account names that contain asterisks. -all, -a prints information about all users of the logical volume. -brief, -bf suppresses header and shortens the output lines. -directory, -dr prints only master directory information. 3-516 AG92-()6 -long, -lg prints additional information, including the quota. account for each directory. -owner User_ids specifies a list of directory owners for which information is desired, where each User_id is of the form Person_id.Project_id. You can use an asterisk when specifying either component of an owner name. If you omit -owner, information is printed only for directories owned by you. -quota. prints only quota information. ACCESS REQUIRED You must have e access to the logical volume to use -account, -all. and -owner= The volume need not be mounted. NOTES If you specify neither -quota. nor -directory, information about both quotas and directories is printed. If you give -all, you can't supply -owner and -account If you use both -owner and -account, information is printed only for directories that match both conditions. EXAMPLES In the example below, the user with Person_id Jones on the Fed project requests information on the logical volume named work. The system responds with information about Jones's master directories. 1md work QUOTA PATHNAME 100 >udd>Fed>Jones>sub 250 >udd>Fed>Jones>subl>sub2 350 records of quota assigned, 500 available. In the example below, Jones requests brief information on the logical volume named work. The system responds with information about Jones' master directories. 1md work -bf >udd>Fed>Jones>sub >udd>Fed>Jones>subl>sub2 Quota=500, used=350. In the example below, Jones requests brief, quota information about the logical volume named work. lmd work -quota -bf Quota=500, used=350. 3-517 AG92-06 In the example below, Jones requests information about all users of the logical volume named work. The use of the -all control argument requires "e" access on the logical volume. lmd work -all OWNER QUOTA PATHNAME Jones.Fed Jones.Fed Smi tho Fed 100 250 900 >udd>Fed>Jones>sub >udd>Fed>Jones>sub1>sub2 >udd>Fed>Smith>work ACCOUNT Smi th. Fed *. Fed 900 USED VOLUME QUOTA 1000 350 500 Total volume quota: 1500 Total quota used: 1250 Name: list_not_accessible, lnac SYNTAX AS A COMMAND FUNCTION scans a directory and lists segments and directories to which a specified User_id does not have a given access condition. ARGUMENTS path is the pathname of the directory to be scanned. If you omit path or give -workinLdirectory (-wd) , your working directory is scanned. User_id is an access name that can have null components. If you omit it, your process's User_id is assumed. The star convention for access names is allowed. (See the set_acl command.) CONTROL ARGUMENTS If you select no control arguments, all segments and directories to which the named user(s) has null access are listed. -(iir_mode STR lists directories to which the named user(s) does not have any of the modes specified in STR, where SIR can be any or all of the letters sma. 3-518 AG92-()6 -se~mode STR lists segments to which the named user(s) does not have any of the modes specified in STR, where STR can be any or all of the letters rew. ACCESS REQUIRED You must have status permission on the directory_ EXAMPLES lnac >udd>work>Smith null Smith.mbx lnac >udd>work>Smith -di r _mode m index s nu 11 Smith.mbx newindex s garyl s stuff s SYNTAX AS A COMMAND lor {request_identifier} {-control_args} FUNCTION lists requests in the I/O daemon queue. ARGUl'if1E"'ITS request_identifier choose it from the following. If you specify no request_identifier, all requests are listed. path is the relative pathname of one or more requests to be listed. convention is allowed. The star -entry STR. -et STR selects only requests whose entry names match STR. The star convention is allowed. Directory portions of request pathnames are not used for selecting requests. 3-519 AG92-06 -id ID selects only requests whose request_ids match ID. CONTROL ARGUMENTS -absolute_pathname, -absp prints the full pathname. -admin {User_id}, -am {User_id} selects requests of all users or of the specified user. It requires r extended access to the queue{s) to read other users' requests. (Default: to list your own requests)' -all, -a searches all queues. -brief, -bf does not print the request state in normal (not -long) mode. It is incompatible with -long and -total. -immediate, -im selects only I/O requests that are not deferred. deferred requests when computing position. With -position, it ignores -long. -lg prints all information about each selected request. including the long request_id and full pathname (see "Notes"), (Default: to print the short request_id and entryname) -lon~id. -lgid prin ts the long request_id. -position, -psn prints queue positions of each selected request. With -total. it prints a list of queue positions. It requires r extended access to the queue(s) to read other users' requests. -queue N, -q N searches only queue N. If you supply no -queue. all queues are searched but nothing is printed for queues from which no requests are selected. -print, -pr specifies that the requests listed are found in the queue(s) associated with the default printer request type (see "Notes.") -punch. -pch specifies that the requests listed are found in the queue(s) associated with the default punch request type (see "Notes. n) 3-520 AG92-06 -plot specifies that the requests listed are found in the queue(s) associated with the default plotter request type (see "Notes.") -request_type STR. -rqt STR searches the 110 daemon queues belonging to the specified request type (see "Notes.") -total, -tt prints only the total number of selected requests and the total number in the queue. -user User_id selects only requests of the specified user. It requires r extended access to the queue(s). NOTES You can only choose printer. punch. or plotter generic request types with -request_type when you give -long. The print_request_types command gives you a list of these request types. The -print, -punch, -plot, and -request_type control arguments are .mutually exciusive. If you give none, lor lists the default request type used by eor -print (as displayed by prin t_request_types). SYNTAX AS A COMMAND FUNCTION displays the primary names of all protection notice templates. CONTROL ARGUMENTS -aU, -a specifies that the entire pnotice search list is to be processed and all templates, including duplicates, are to be listed. -check, -ck specifies that the entire pnotice search list is to be processed and that all templates, including duplicates, are to be listed. Checks are also made to the text of each template. and any errors encountered are reported. 3-521 AG92-06 list~ref ~names NOTES Default copyright and trade secret notices are indicated. Names displayed by this command are shown as they should be input to the add_pnotice and generate_pnotice commands. If no control arguments are used, names are output in search list order, omitting duplicates. SYNT AX AS A COMMAND lrn paths {-control_args} FUNCTION lists the reference names associated with a given segment. You can specify segments by either pathname or segment number. ARGUMENTS paths are the segment numbers and pathnames of segments known in your process. They can be "-name STR" ("-nm STR") to specify a pathname that begins with a minus sign or looks like a segment number. If you supply no paths, information for all segments known in your process is printed, excluding those known in ring o. CONTROL ARGUMENTS -all. -a prints information for all known segments. including ring 0 segments. equi valen t to -from O. It is -brief. -bf suppresses printing of the reference names for the entire execution of the command. -from N, -fm N allows you to specify a range of segment numbers. You can use it with -to; information for the segment numbers in this range is printed. If you don't select -to. the highest used segment number is assumed. -to allows you to specify a range of segment numbers. If you supply no -from. the segment number of the first segment not in ring 0 is assumed. 3-522 AG92-06 NOTES You can mixed all the above arguments (segment specifiers and control For example. in the command line 1rn a~guments). 156 -from 230 path_one information is printed for segment 156. all segments from 230 on. and the segment whose pathname is path_one. In the default condition. when called with no arguments, list_ref_names prints information on all segments that are not in ring O. Name: list_resource_types, irt SYNTAX AS A COMMAND 1rt {type1 •.. typeN} {-contro1_args} FUNCTION prints a list of all resource types described in a resource type description table (RTDT). ARGUMENTS ~~ is the resource type defined in the RTDT for which information is to be listed. If you give no type. all known resource types are listed. I CONTROL ARGUMENTS -long. -lg lists the defined attributes for each resource type. -no_header, -nhe omits the column headers. -pathname path. -pn path lists resource types defined in the RTDT specified by path. -pathname, the RTDT residing in >system_control_1 is used. If you give no NOTES See also the list_resources command. which lists groups of resources according to specified criteria. For example. list_resources can list all resources known by the Resource Control Package (Rep) or those owned by a given user and/or project 3-523 AG92-()6 Name: list_resources, lr SYNTAX AS A COMMAND lr {-control_args} SYNTAX AS AN ACTIVE FUNCTION [lr {-control_args}] FUNCTION lists groups of resources managed by the Resource Control Package (RCP) , selected according to the criteria specified by you. CONTROL ARGUMENTS -acquisitions, -acq lists resources acquired by you specified by -user. If you supply -acquisitions, you must also give -type. -assignments, -asm lists resource assignments. -awaitinLclear lists those resources awaiting manual clearing. -device STR. -dv STR lists only device resources with the name STR. -logical_volume, -Iv lists logical volumes that are currently attached. -long, -lg prints all the information known about each resource listed. If you don't supply it. only the name for each resource listed is printed. It has no effect if you select -acquisitions. -mounts. -mts lists resources currently mounted by the process. -reservations, -resv lists only device and volume reservations. -type STR. -tp STR lists resources of the type STR. See list_resource_types for inf ormation on obtaining the names of resource types. -user User_id selects a particular user or group of users for whom resource information is to be 3-524 AG92-Q6 list_retrieval_requests printed. If you select no -user, your User_id is assumed. You can use -user only in conjunction with -acquisitions. User_id can be any oi the following: Person. Project specifies a particular Person_id and Project_id combination. *.Project specifies all users on a given project project *.* specifies all users (i.e.. all acquired resources are listed). free specifies all resources in the free pool. system specifies all resources in the system pool. ** specifies all users plus the free and system pools (Le., all registered resources are listed). NOTES ON ACCESS RESTRICTIONS You require access to rcp_admin_ to obtain information on other users and read access to the Project Definition Table (PDT) of a given project to obtain information for that project NOTES If you invoke list_resources without any arguments, all resources assigned and devices attached to the calling proc.ess are liste-d. You cannot use the -assignments, -device, -logical_volume, -long, -mounts, -reservations control arguments with the active function. and SYNTAX AS A COMMAND lrr {path} {-control_args} FUNCTION lists retrieval requests in the retrieval daemon queues. entryname of each request are printed. 3-525 The request identifier and AG92-06 list_retrieval_requests ARGUMENTS path is the pathname of a request to be listed. The star convention is allowed. Only requests matching this pathname are selected. If you give no path, all pathnames are selected. This argument is incompatible with -entry. CONTROL ARGUMENTS -absolute_pathname, -absp prints the full pathname of each selected request, rather than the just entryname. -admin {User_id}, -am {User_id} selects the requests of all users, or of the user specified by User_id. If you don't choose -admin, only your own requests are selected. This control argument is incompatible with -user. (See "Access Required" below.) -all, -a searches all queues and prints the totals for each nonempty queue whether or not any requests are selected from it. This control argument is incompatible with -queue. -brief, -bf does not print the state and comment of each request. This control argument is incompatible with -long and -total. -entry STR, -et STR selects only requests whose entrynames match STR. The star convention is allowed. Directory portions of request pathnames are ignored when selecting requests. -id ID selects only requests whose identifiers match the specified 1D. -long, -lg prints all the information pertaining to a retrieval request If you omit -long, only the full pathname of the object or subtree to be retrieved is printed. -lontLid, -lgid prints the long the request identifier. -posi tion, -psn prints the position within its queue of each selected request. When used with -total, it prints a list of all the positions of the selected requests. (See "Access Required. ") -queue N, -q N searches only queue N. If you don't select -queue, all queues are searched but nothing is printed for queues from which no requests are selected. 3-526 AG92-06 -total. -tt prints only the total number of selected requests and the total number of requests in the queue plus a list of positions if you choose -psn. If the queue is empty, it is not listed. -user User_id selects only requests entered by the specified user (see "Access Required"). ACCESS REQUIRED You must have 0 access to the queue(s). You must have r extended access to the queue(s) to use -am, -psn, or -user, since it is necessary to read all requests in the queue(s) to select those entered by a specified user. NOTES The default is to list only pathnames for the default queue. . The User_id arguments specified after -am or -user can have any of the following forms: Person_id.Project_id Person_id.* Person_id )·c. Proj ect_ i d • Proj ect_i d ..'... ......'," ,'\ matches matches same as matches same as same as that user only that person on any project Person_id.* any user on that project *.Project_id -admin with no User_id following it • If you select no arguments, only your own requests are selected for listing (see en ter_retrieval_request). SYNTAX AS A COMMAND 1st {pathnames} {-control_args} FUNCTION lists the segments in a specified subtree of the hierarchy. The complete subtree is listed unless you supply -dh. ARGUMENTS pathname is the relative pathnarne of the subtree to be searched. If you specify more than one pathname, only the last one is listed. If you specify no pathnarne. your working directory is assumed. 11/86 3-527 AG92-o6A CONTROL ARGUMENTS -all, -a prints all the names of a segment. (Default: to print only the primary names) -depth NNN, -dh NNN scans the hierarchy to the depth indicated by NNN. The depth is relative to the base of the given subtree and must be specified by a decimal integer. NOTES For each level listed in the hierarchy, the names are indented three more spaces to indicate the depth of the segments. Each segment printed includes the number of records used by the segment Name: list_tape_contents, ltc SYNTAX AS A COMMAND ltc voll {-comment comment string} .•• volN {-comment comment_string} {-attach_args} {-control_args} FUNCTION prints information about files recorded on 9-track magnetic tape in either ANSI standard labeled or IBM standard labeled format ARGUMENTS voI(s) {-comment comment_string} specifies the name of the tape volume set to be listed (see "Notes on Volume Selection" below). CONTROL ARGUMENTS -attach_args makes mtape_ attach control arguments (see "Notes on Attachment" below). -brief, -bf prints the identifier and sequence number of each file selected from the volume set -comment comment_string. -com comment_string displays comment_string on the operator's console immediately preceding -comment is mounted. 11/86 3-528 when the volume name AG92-o6A -from N starts output of information with file number N, where 0 < N < 10000. -lon~ -lg prints detailed information about each file selected from the volume set. -to N stops processing the volume set after file number N, where 0 < N < 10000. -volume_type type, -vt type specifies the format type of the volume set being processed, where "type" can be "ibm" or "ansi." (Default: ansi, if you omit -vt) NOTES ON VOLUME SELECTION When you specify the volume identifier, use -vt before any volume identifier beginning with a hyphen. If the volume set to be listed was created on Multics, give only the first volume identifier of the set; the command retrieves the remainder of the identifiers. If it was not created on Multics, give each volume identifer. Up to 64 volumes can be selected. NOTES ON VOLUME SET INFORMATION The information ltc prints is extracted from the tape labels and printed in various amounts according to the control arguments you supplied. The information available for each level of control is shown below. Where information is not obtainable from th~ 1fI.LI, ...... 1~~~1 """",v...,.&., th~ ..,.&..&.W V~l11~ .. 'IIWr.&. ..... .., n• •••" • - _. 1e! .&,tOJ' 1·,,·1nt~r1 t',£..&..&..1. ...~ Ole! ~ th~ ......l..., 1t~"" .a. ......,~ ~nt1"V .LJ. W.l..& ... Information printed by list_tape_contents Id: Number: Format: Blksize: Lrec 1 : Mode: Created: Expires: Section: Version: Generation: 11/86 -brief -bf 3-529 (defau 1t) -long -lg AG92-06A 1ist~tape=contents NOTES ON ATTACHMENT A complete attach description is created for processing the volume set It is composed of the string Ilmtape_ -vo 1ume_ type ans i -no_d i sp 1ay -dens i ty 1600 -track 9 -error -device 1 -label -no_system -no_wait II or "mtape_ -volume_type ibm -no_display -density 1600 -track 9 -error -device 1 -label -no_system -no_wait II Any mtape_ attach control arguments you give to ltc are added to the end of the attach description and passed to mtape_ (see the mtape_ I/O module in the Subroutines manual). NOTES ON mtape_ ARGUMENT DEFAULTS To avoid unexpected resUlts, ltc supplies complete open, close, and detach descriptions to mtape_. These arguments override any default values that may have been established by the mtape_set_defaults command. EXAMPLES The command ltc m9999 produces Mounting volume IIm9999 11 with no write ring Mounted ANSI volume "m9999" (recorded at 1600 BPI) 10 FILEOOOl FILE0002 11/86 Number Format 1 5B 2 SB Blksize 8192 2048 Lrecl 1044480 1044480 3-530 t on device tapa_07 Mode Created Expires BINARY BINARY 09/30/85 09/30/85 12/31/99 12/31/99 AG92-06A The command Itc m9999 -bf -from 2 -to 4 -vt ansi produces Mounting volume "m9999" with no write ring Mounted ANSI volume IIm9999" (recorded at 1600 BPI), on device tapa_07 Number 10 FILE0002 FILE0003 FILE0004 2 3 4 The command Itc m9999 -Ig produces Mounting volume "m9999 11 with no write ring Mounted ANSI volume "m9999" (recorded at 1600 BPI), on device tapa_03 10: ATTRIBUTEFILEOOOl Created: 10/21/85 Expires: 12/31/99 Format: SB Mode: BINARY Number: 1 Section: Generation: 1 Version: 0 Blksize: 8192 Lrec 1: 1044480 ! D: ATTR!BUTEF!LEOOO2 Number: ... 10: ATTRIBUTEFILEOO03 Number: 3 ") Oisp1ayed characteristics for the last 3 files are identical. The command ltc m9999 -long -comment "message to console" -vt ibm 11/86 3-530.1 AG92-D6A This page intentionally left blank. 11/86 AG92-06A SYNTAX AS A COMMAND list_temp_segments {names} {-control_arg} FUNCTION lists the segments currently in the temporary segment pool associated with your process. This pool is managed by the get_temp_segments_ and release_temp_segments_ subroutines. ARGUMENTS names is a list of names identifying the programs whose temporary segments are to be listed. It cannot be used with -all. CONTROL ARGUMENTS -all, -a lists all temporary segments. including free ones. If the command is issued with no arguments (the default invocation). it lists only those temporary segments currently assigned to programs (i.e.. free temporary segments are not listed). This control argument is incompatible with the names argument. EXAMPLES To list all the segments currently in the pool. type 5 Segments, 2 Free !BBBCdfghgffkkkl.temp.0246 !BBBCdffddfdffkl.temp.0247 !BBBCddffdfffhhh.temp.0253 !BBBCdgdgfhfgfsf.temp.0254 !BBBCvdvfgvdgvvv.temp.0321 work work (free) (free) editor To list the segments currently in use. type 3 Segments !BBBCdfghgffkkkl.temp.0246 !BBBCdffddfdffkl.temp.0247 !BBBCvdvfgvdgvvv.temp.0321 work work editor 3-531 AG92-D6 To list segments used by the program named "editor", type segment BBBCvdvfgvdgvvv.temp.0321 editor SYNTAX AS A COMMAND login_args {argument_number} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [login_args {argument_number} {-control_args}] FUNCTION prints or returns information about selected login arguments. You can supply login arguments on the command line that creates the process. For interactive processes, this is the login and enter or enterp preaccess requests; for absentee processes, en ter_abs_request. ARGUMENTS argument_num ber selects a single login argument CONTROL ARGUMENTS -count, -ct prints or returns the number of login arguments you gave when you entered the process creation command. You can't use -count in combination with either argument_number or the other control arguments. -from argument_number, -fm argument_number selects all login arguments from argument_number through the last login argument. -no_requote does not requote arguments in the string that is returned or printed. -quote doubles embedded quotes of each selected argument before it is returned or printed. 3-532 AG92-o6 -requote requotes each selected argument before it is returned or printed. (Default) NOTES If you supply no argument_number and no -count, the default is -from 1. If no login arguments exist for the process, login_args prints "There are no login arguments." The active function returns the empty string. If argument_number exceeds the number of login arguments for the process, login_args prints "Argument number N exceeds the number of login arguments (NN)." The active function returns the empty string. If -from is in force, explicitly or by deiauit. iogin_args prints each argument on a separate line, prefixed by its number, a right parenthesis, and a space; for example, The active function separates multiple the fourth argument is preceded by "4) arguments by a single space in the return string. which is not itself embedded in quotation marks, and inserts no argument number in the return string. ft. The -from, -no_requote, -quote and -requote control arguments allow you to obtain return strings that are equivalent to exec_com argument substitution forms. no control arguments argument_number -from argument_number -no_requote argument_number -no_requote -from argument_number -no_requote -quote argument_number -quote -from argument_number -quote -count &rfl &r(argument_number) &rf(argument_number) &fl &(argumen t_num ber) &f(argument_number) &qfl &q(argument_number) &qf(argument_number) &n The active function cannot duplicate some exec_com argument forms. The exec_com interpreter has information about surrounding context and produces different results for &ql and "&ql". 3-533 AG92-06 iogout logout Name: logout SYNTAX AS A COMMAND logout {-control_args} FUNCTION terminates your session and ends communication with the Multics system. It signals the finish condition for the process and, after the default on unit for the finish condition returns, closes all open files and destroys the process. CONTROL ARGUMENTS -brief, -bf prints neither the logout message nor, if you give -hold, the login message. -hold, -hd terminates your session but not communication immediately log in without redialing. with the system: you can NOTES If your site is security conscious, it may have disabled "logout -hold"; in this case if you wish to change authorization, do this: 1. log out 2. verify, using terminal/modem indications, that the terminal has dropped OrR and that the system acknowledged by dropping DSR 3. log in at the new authorization. This procedure is the only way to guarantee that you are communicating with the answering service and not with a Trojan horse. DTR and DSR are EIA RS232 control signals that are part of the interface between your terminal and the system. 3-534 AG92-06 lon~date lon~date Name: lon~date SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION FUNCTION returns a month name, a day number, and a year as a single string in the form "month day, year" (e.g., November 2, 1985). The format string to produce this is ;;Amn Adm, A9999yc". ARGUMENTS time_string indicates the date about which information. is desired. If you supply no time_string, the current date is used. The time string is concatenated to form a single argument even if it contains spaces; you need not quote it. (See Section 1 for a description of valid time_string values.) CONTROL ARGUMENTS -language STR -lang STR STR specifies the language in which month name, day names, and zone names are to be expressed. (Default the process default) j -zone STR STR specifies the zone that is to be used to express the result process default) (Default: the NOTES Use the print_time_defaults command to display the default language and zone. Use the display_time_info command to display a list of all acceptable language and zone values. 3-535 AG92-()6 low lonuear Name: long,....year SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION FUNCTION returns the four-digit number of a year in the clock from 0001 through 9999. The format string to produce this is "A 9999yc". ARGUMENTS time_string indicates the date about which information is desired. If you supply no time_string, the current date is used. The time string is concatenated to form a single argument even if it contains spaces; you need not quote it (See Section 1 for a description of valid time_string values.) CONTROL ARGUMENTS -zone STR STR specifies the zone that is to be used to express the result. process default) (Default: the NOTES Use the print_time_defaults command to display the default zone. display _time_info command to display a list of all acceptabie zone values. Use the Name: low SYNTAX AS A COMMAND low N SYNTAX AS AN ACTIVE FUNCTION [low N] 3-536 AG92-06 low FUNCTION returns a specified number N of copies of the first (lowest) character in the ASCII character set (NUL or OOOoctaI). NOTES See the description of the high command. Name: lower_case, lowercase SY,"'JTAX AS A COMMAND lowercase strings SYNTAX AS AN ACTIVE FUNCTION [lowercase strings] FUNCTION returns strings with all uppercase alphabetic characters translated to lowercase. ARGUMENTS strings is one or more character strings. NOTES Returned strings are separated from each other by a space. See the description of the upper_case c.ommand. EXAMPLES The following interactions illustrate use of lower_case as an active function: ioa_ [lower_case liThe time zone is EST."] the time zone is est. The following interactions illustrate use of lower_case as a command: lower_case It is winter in Boston. The time zone is EST. it is winter in boston. the time zone is est. 3-537 AG92-OC Itrim Name: Itrim SYNTAX AS A COMMAND ltrim STRA STRB SYNTAX AS AN ACTIVE FUNCTION [ltrim STRA STRB] FUNCTION returns a character string trimmed of specified characters on the left NOTES The ltrim command, or active function, finds the first character of strA not in strB. trims the characters from strA preceding this character, and returns the trimmed result Space characters are trimmed if strB is omitted. EXAMPLES string [ltrim 000305.000 0] 305·000 s tr i ng [1 tr i m" Th is is it. Th is is it. II] Name: Iv_attached SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION FUNCTION returns true if the volume specified (Le., the lv_name argument) is attached to the user's process or if the volume is a public logical volume; otherwise it returns false. ARGUMENTS lv_name is the name of the logical volume. 3-538 AG92-06 mail NOTES See the related commands attach_Iv and detach_Iv. Name: mail, ml SYNTAX AS A COMMAND ml path Userl ••. {UserN} {-control_args} ml {destination} {-control_args} FUNCTION sends a message to another user or prints messages in any mailbox to which you have sufficient access. ARGUMENTS path is the patbname of a segment to be sent or is an asterisk (*) to indicate that you wish to type a message to be sent (see "Notes on Composing Mail" below). User_1 is the User_id of a person to whom mail is to be sent. Mail is sent to the mailbox >udd>Project_id>Person_id>Person_id.mbx fer each Person_id.Project_id (User_id) argument in the command line. destination can be User_id to specify a mailbox. If destination contains a < or >, it is the pathname oj a mailbox. The mbx suffix is assumed in this case. You cannot use destination with -pathname. (Default your default mailbox) CONTROL ARGUMENTS -acknowledge, -ack requests acknowledgement of the pieces of mail. The acknowledgement consists of the string: "Acknowledge message of 1I and is sent as an interactive message when you invoke this command to print mail. -brief, -bf prints the total number of messages in the mailbox. If the mailbox is empty, nothing is printed. 11/87 3-539 AG92-06B mail mail -exclude STR, -ex STR ignores messages sent by users whose User_id matches the User_id specified in STR. The star convention is allowed. If you supplied -match. exclusion is performed before matching. -header, -he prints only the header line for each message. No messages are deleted. -match STR prints messages sent by users whose User_id matches the User_id specified in STR. The star convention is allowed. If you gave -exclude, exclusion is performed before matching. -no_notify, -nnt suppresses the sending of an interactive "You have mail" notification. -pathname path, -pn path specifies a mailbox by pathname. The mbx suffix is assumed. NOTES The extended access used on mailboxes (which are ring 1 segments) permits you to control other users' access to it. Adding, reading, and deleting messages are independent privileges under extended access; for example, you can give a user access to only add messages, to other user access to add messages and to read and delete only the messages he or she has added. Mail and interactive messages sent to a user are placed in the mailbox >udd>Project_id>Person_id>Person_id.mbx. If you are accepting interactive messages, you receive an immediate notification of the form: You have mail from Person_id.Project_id. Segments to be mailed have a maximum length of one record (4096 ASCII characters). NOTES ON COMPOSING MAIL If path is *, mail responds with "Input" and accepts lines from the terminal until you type a period on a line by itself. The typed lines are then sent to the specified user(s). 3-540 AG92-()6 mail mail NOTES ON PRINTING MAIL When the contents of the mailbox named by path are printed, they are preceded by a line of the form: N messages. Each message is preceded by a line of the form: i) From: Person_id.Project_id (sent_from) date time (N lines) where: is the incremental number of the message. The messages are printed in ascending numerical order; the oldest one is numbered 1. Person_id is your registered person identifier. Project_id is the name of the project on which you were logged in when you sent the message. sent_from is an optional field that further identifies you, e.g., your anonymous log-in name. date is the date you sent the message, of the form mm/dd/yy to indicate the month, day, and year. time is the time you sent the message, of the form hhmm.m zzz www to indicate the hours, minutes, and tenths of minutes in 24-hour time followed by the time zone and day of the week. N lines is the number of lines in the message. After printing all messages, this command asks whether you want them deleted. If yes, all messages are deleted; if no, no messages are deleted. In either case, your return to command level. If you quit while the messages are being printed and then issue program_interrupt, the command stops printing and asks whether to delete all messages, including those that were not printed. 3-541 AG92-()6 mail NOTES ON CREATING A MAILBOX A default mailbox is created the first time print_mail, read_mail, or accept_messages is used. The default mailbox is >udd>Project_id>Person_id>Person_id.mbx NOTES ON EXTENDED ACCESS Access on a newly created mailbox is set to adrosw for you, aow for *.SysDaemon.*, and aow for *.*.*. The types of extended access for mailboxes are: add, a adds a message. delete, d deletes any message. read, r reads any message. own, 0 reads or delete only your own messages, i.e.. those sent by you. status, s finds out how many messages are in the mailbox. wakeup. w sends a wakeup when adding a message (used by send_message). The modes n, nUll. and "" indicate null access. The mode u indicates that the user has access to send "urgent" messages to the user accepting messages on the mailbox. However, urgent messages are not currently implemented. SYNTAX AS A COMMAND mvp key {args} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [mvp key {args} {-control_args}] 11/87 3-542 AG92-06B FUNCTION allows a user or a group of users (tape reels, etc.). The concept of also supported. The default volume and exists in your home directory. below. to regulate the use of a predefined set of volumes volume sets as used with tape_ansi_/tape_ibm_ is pool for each user pool is named Person_id.volumes This default can be reset via the use key described ARGUMENTS key can be any of the tokens (see "List of Keys"): add (a) allocate (alloe) append_volume_set (appvs) delete (d}) free list (Is) print (pr, p) pv_expire (pvexp) remove_volume_set (rmvs) reserve (rsv) reuse set test use args are optional arguments associated with the various keywords. They can be volume names of volumes to be acted upon according to the key given. CONTROL ARGUMENTS are optional control arguments associated with the various keywords. LIST OF KEYS add, a Usage: mvp a vol_names {-control_args} adds the selected volumes to your volllIile pool. Each volume added is considered a volume set of size one. Control Arguments: -force, -fc adds the volumes it can without aborting the entire request or querying you (see "Notes on Querying" below). -pv_expire DATE, -pvexp DATE sets the expiration date of all given physical volumes to DATE. DATE must be acceptable to convert_date_to_binary_" (See "Notes on Expiration Dates" below.) Failure can occur when the volume to be added already exists in the volume pool. 3-543 AG92-()6 As an active function, "true" is returned if all volumes were successfully added (see "Notes on Active Function" below). allocate, alloc Usage: mvp alloe {vol_names} {-eontrol_args} ailocates the suppiied free or reserved volume sets. Tne vol_names argument can be primary or secondary volumes of a set Control Arguments: -comment STR, -com STR designates STR as the comment to be associated with the vol_names chosen. -expire DATE, -exp DATE sets the expiration date associated with the data on the allocated vol_names. DATE must be acceptable to convert_date_to_binary_. (See "Notes on Expiration Dates" below.) -first {N}, -ft {N} allocates the first N free volume sets in the pool; "first" is defined as the volume sets that have been most recently freed (i.e., volume sets that have the most recent state change date associated with them). (Default I, if you give no N) -force. -fc assigns the volume sets it can without aborting the entire request or querying you (see "Notes on Querying"). -last {N}, -It {N} allocates the last N free Yolu..'D.e sets in the pool; "last" is defined as the volume sets that have been in the free state the longest (i.e., volume sets that have the oldest state change date associated with them). (Default 1, if you supply no N) -volume_size {N}, -vs {N} allocates a volume set of size N. If more than one volume set of size N exists and neither -first nor -last is used, then the last free (least recently freed) volume set of size N is assigned. If there are no volume sets of size N, an error message occurs. The test key can be used to avoid such errors. (Default 1, if you supply no N) The use of vol_names and -ft, -It, or -vs are mutually exclusive. If -vs is not selected, the default action is to consider all volume sets of any size in the pool. Reserved volume sets to be allocated can occur if the volume sets to be they are not in the free or reserve and only N-l free volume sets exist must be specified by their vol_name. Failure allocated do not exist in the volume pool, if state, or if N free volume sets are requested in the pool. 3-544 AG92-06 As an active function the allocated vol_names are returned. 9 append_volume_set, appvs Usage: mvp appvs primary_vol_name {vol_names} {-control_args} appends the vol_names to the volume set specified by the primary_vol_name. The vol_names cannot be secondary volumes of another existing volume set The pv_expire date of each vol_name is checked before appending; if this date is passed (i.e, less than the current date), the state of the volume becomes expired, a message to that effect is printed, and the volume is not appended. Control Arguments: If no vol_names are given, acceptable control arguments are -first {N}, -ft {N} appends the first N free volume sets to the new set; "first" is defined as the volume sets that have been most recently freed. (Default: 1, if you give no N) -force, -fc appends the volumes it can without aborting the entire request or querying you (see "Notes on Queryingfl). -last {N}. -It {N} appends the last N free volume sets to the new set; "last" is defined as the volume sets that have been in the free state the longest (Default: 1. if you supply no N) -volume_size {N}, -vs {N} appends a volume set of size N. If more exists, and neither -first nor -last is used, size N is appended to the new set If no error message occurs. The test key can (Default 1. if you supply no N) than one volume set of size N then the last free volume set of volume set of size N exists. an be used to avoid such errors. The vol_names argument and -ft. -It, or -vs are mutually exclusive. If -vs is not chosen, the default action is to consider volume sets of any size in the pool. Failure can occur when a given volume set does not exist or when a volume to be appended is not free. an active function, the volume names that were appended to the volume set are returned. If a multiple volume set is appended, all the volumes in the set are returned (see "Notes on Active Function"). As delete, dl Usage: mvp dl vol_names {-control_arg} deletes the specified physical volume sets from your volume pool. Volume sets 3-545 AG92-06 manage~ volume~pool must be in the free, reserve, or pv_expire state to be deleted. If vol_name is a multiple volume set. all volumes in the set are deleted from the pool; if it is a secondary_vol_name, the volume set to which the secondary volume belongs to is deleted. Control Argument: -force, -fc deletes the volume sets it can without aborting the entire request or querying you (see "Notes on Querying"). As an active function, a successful delete returns "true," "false" otherwise (see "Notes on Active Function"). free Usage: mvp free {vol_names} {-control_args} frees the selected volume sets in your volume pool by changing the state to "free." Upon freeing a volume set, the pv_expire date of each volume in the set is checked; if one of these dates is passed, the state of the volume set becomes pv_expired and a message to that effect is printed. In the case of an allocated volume to be freed, the -expire date is checked first; if this date has not passed yet, the volume set is not freed and a message to that effect is printed. If vol_name is a secondary_vol_name, the state of the volume set to which the secondary volume belongs to becomes free. Control Arguments: -brief, -bf suppresses the pv_expire appropriate. message or the allocate expire message when -expire, -exp frees all allocated volume sets for which the respective expiration date has been passed. -force, -fc frees the volume sets it can without aborting the entire request or querying you (see "Notes on Querying"). -force_expire, -fexp overrides the checking of the -expire date, freeing allocated volume sets with an unexpired expiration date. -match STR frees only those volume sets whose comment contains STR as a substring. The volume sets can be in the allocate, reserve, or pv_expire state. Both expirations dates are first checked before freeing the volume sets. The vol_names argument and -exp, -fc, or -match are mutually exclusive. 3-546 AG92-()6 As an active function. a successful free returns "true," otherwise "false" is returned (see "Notes on Active Function"). list, Is Usage: mvp 1s {vol_names} {-contro1_args} lists information about the specified volume sets or about all volume sets in the pool if no arguments are supplied. The list is printed in state change date order with the volumes whose states changed most recently listed first Control Arguments: -header, -he prints the header information of the list display. (Default) -no_header, -nhe suppresses printing of the header. -total. -tt prints the total number of volume sets in the pool. Control Arguments for Field Selection: These control arguments determine which fields are displayed by list -comment, -com lists only the comment field of the designated volumes. -default_format, -dfmt lists the name, state date, state, and comments fields, as illustrated below. This is the default list format if no other field control arguments are chosen. Name 1234567890 1000 State Change 06/05/83 1316.1 mst 01/23/83 0645.0 mst State ALOC FREE Comment This is a comment Multiple volume set 1001 1002 -expire_date. -edt lists the expiration date field of the given allocated volume sets. -name, -nm lists the volume name field of the selected volume sets. -pv_expire_date, -pvedt lists the physical expiration date field of the supplied physical volume sets. -state lists only the state field of the indicated volume sets. 3-547 AG92-()6 -state_date, -sdt lists only the state change date field of the designated volume sets. If you want to list the expiration dates, you have to use -edt and/or -pvedt Control Arguments for Volume State Selection: Volume sets can be listed according to what state they are in: allocate, free, pv_expire, or reserve. The default format is displayed unless field control arguments are also selected. The specified vol_names and the control arguments listed below are mutually exclusive. -all_states, -ast lists all volume sets in the pool. (Default, when you invoke list with no arguments) -allocate, -alloc lists only those volume sets that are allocated. -free lists only those volume sets that are free. -pv_expire, -pvexp lists only those volume sets that are in the pv_expire state. -reserve, -!SV lists only those volume sets that are reserved. Additional Selection Control Arguments: These control arguments allow one to list volume sets by criteria other than the volume state or in combination with the volume state control arguments. The default format display is used unless field arguments are given. The indicated vol_names are incompatible with these control arguments: -expire, -exp lists all allocated volume sets for which the respective expiration date has been passed. -first {N}, -ft IN} lists the first N volume sets in state change date order: "first" is defined as the volume sets that have the most recently changed state. (Default: 1, if you give no N) -last IN}, -It {N} lists the last N volume sets; "last" is defined as the volume sets that have the least recently changed state. (Default: 1, if you supply no N) -match STR lists only those volume sets whose comment contains STR as a substring. 3-548 AG92-06 -volume_size {N} -vs {N} lists only the volume sets in the data base of size N. If -vs is not given~ all volume sets of any size are listed. (Default: 1, if you supply no N). The volume sets have the following format: t Volume 4123 1000 3400 State Change 12/11/83 1022.9 mst State RESV Comment backup where vol_name 4123 is the primary volume of the volume set and 1000 and 3400 are the secondary volumes. As an active function, list with no control arguments returns a list of the primary volume names of all volume sets; otherwise, the control arguments chosen determine what is returned for each selected volume. Examples: Given the pool: Volume 500 1000 5000 200 457 6500 4100 374 State Change 10/23/83 1042.9 mst 10/23/83 0853.1 mst 09/11/83 1022.9 mst State FREE ALOC RESV 06/28/83 1134.1 mst 06/28/83 1132.8 mst 03/27/83 0740.0 mst ALOC ALOC RESV Comment acct backup test1 testl mvp" ls -alloc -It 2 -dmft -edt Volume 6500 4100 State Change 06/28/83 1134.1 mst 06/28/83 1132.8 mst State ALOC ALOC Expi res 01/31/84 2100.0 mst 01/31/84 2100.0 mst Comment test1 test1 mvp ls -al1oc -match ac -state date -name Volume 1000 State Change 10/23/83 0853.1 mst mvp ls -It 2 -name -sdt -pv_expire_date Volume 4100 374 State Change 06/28/83 1132.8 mst 03/27/83 0740.0 mst Volume Expires 06/30/85 2100.0 mst where volume 374 has no physical volume expiration date. 3-549 AG92-06 print, pr, p prints the pathname of the current volume pool segment As an active function, the pathname is returned. pv_expire, pvexp Usage: mvp pvexp vol_names {-control_arg} designates the specified volume sets and their secondary volumes as expired by changing the state to pv_expire. The set key can be used to reset the physical volume expiration date. Volume sets cannot be in the allocate state. If vol_name is a secondary_vol_name, the state of the volume set to which the secondary volume belongs to becomes pv_expire. As an active function, "true" is returned when all indicated vol_names are successfully expired, otherwise "false" is returned (see "Notes on Active Function"). Control Argument: -force. -fc expires the volume sets it can without aborting the entire request or querying you (see "Notes on Querying"). remove_volume_set, rmvs Usage: mvp rmvs primary_vol_name {secondary_vol_names} {-control_args} removes the secondary_vol_names from the volume set as specified by primary_vol_name. The volumes removed are placed in the pool as volume sets of size 1 in the free state. The primary volume of a volume set cannot be removed unless -all is used. If the volume set supplied is in the allocate state, the -expire date is checked first If this date has not passed yet, the request is aborted and a message is printed. Upon freeing each volume, its pv_expire date is checked; if this date is passed, the state of the volume becomes expired and a message to that effect is printed. Control Arguments: -all. -a breaks the volume set into individual volume sets of size 1, each with a state of free (or pv_expire. as explained above); this includes freeing the primary volume. -brief. -bf suppresses the pv_expire message or the volume-not-removed message when appropriate. -force. -fc removes the volumes it can without aborting the entire request or querying you (see "Notes on Querying"). 3-550 AG92-06 -force_expire. -fexp overrides the checking of the -expire date. freeing allocated volume sets with an unexpired expiration date. -pv_expire, -pvexp removes all volumes of the designated volume set whose pv_exire date has been passed and puts them in the pool with the pv_expire state. The specified secondary_vol_names and -all and -pvexp are mutually exclusive. Failure can occur when the volumes to be removed do not exist in the volume set. As an active function. the vol_names removed from the volume set are returned (see "Notes on Active Function;;). reserve, rsv Usage: mvp rsv {vol_names} {-control_args} reserves the indicated free volume sets. If vol_name is a secondary volume name of a volume set, this volume set is reserved. Only a free volume set can be reserved and used by a person. so long as her or his process is active. When the reserved volume is referenced, a check is made to see if one's process is still active; if not, the volume can be used as requested. When reserving, the pv_expire date is checked; if this date is passed, the state of the volume set becomes pv_expire and a message is printed. Control Arguments: -comment Sm. -com STR states that STR be the comment associated with the given volume sets reserved. -first {N}. -ft {N} reserves the first N free volume sets; "first" is defined as the volunle sets that have been most recently freed. (Default: 1. if you give no N) -force, -fc reserves the volumes it can without aborting the entire request or querying you (see "Notes on Querying"). -last {N}, -It {N} reserves the last N free volume sets; "last" is defined as the volume sets that have been in the free state the longest. (Default 1, if you supply no N) -volume_size {N}, -vs {N} reserves a volume set of size N. If more than one volume set of size N 3-551 AG92-()6 exists and neither -first nor -last is given. then the last free volume set of size N is reserved. If no volume set of size N exists. an error message occurs. The test key can be used to avoid such errors. (Default: 1, if you supply no N) The vol_names argument and -ft. -It. or -vs are mutually exclusive. If -vs is not given, the default action is to consider volume sets of any size in the pool. Failure can occur if the specified vol_names to be reserved do not exist, if they are not in the free state, if no volume set of size N exists, or if there are only N free volumes in the pool and N+ 1 volumes are selected to be reserved. As an active function, a list of the volume set names reserved is returned (see "Notes on Active Function"). reuse Usage: mvp reuse {vol_names} {-control_args} allows one to free and reallocate a designated number of allocated volume sets. without needing to know the volume names. Before this operation is performed, the -expire date is checked; if this date has not passed yet, the request is not performed and a message with that purport is printed. Control Arguments: -brief. -bf suppresses the reuse request message not performed. -first {N}, -ft {N} reallocates the first N allocated volume sets; "first" is defined as the volume sets that have been most Tecently allocated. Failure can occur when N volume sets are requested and only N -1 volume sets are in the pool. (Default: 1, if you give no N) -force, -fc reuses the volume sets it can without aborting the entire request or querying you (see "Notes on Querying"). -force_expire, -fexp overrides the checking of the -expire date and reallocates the specified volume sets with an unexpired expiration date. -last {N}. -It {N} reallocates the last N allocated volume sets; "last" is defined as the volume sets that have been in the allocated state the longest. Failure can occur when N volume sets are requested and only N-1 volume sets are in the pool. (Default: 1, if you supply no N) -match STR reallocates all volume sets whose comment contains the substring STR. 3-552 AG92-o6 -volume_size {N}, -vs {N} reallocates a volume set of size N. If more than one volume set of size N exists and neither -first nor -last is given, then the last allocated volume set of size N is reallocated. If no volume set of size N exists. an error message occurs. The test key can be used to avoid such errors. (Default: 1, if you supply no N) The vol_names argument and -ft, -fc, -It, -match, or -vs are mutually exclusive. If -vs is not supplied, the default action is to consider all allocated volume sets of any size in the pool. As an active function, the primary names of the volume sets that were reused are returned (see "Notes on Active Function"). set Usage: mvp set vol_names -control_args sets the comment or expiration date fields of the specified volume sets. Control Arguments: -comment STR, -com STR sets the comment field of the designated vol_names to STR. If the volume name is secondary. the comment field of the volume set to which it belongs is changed. -expire DATE. -exp DATE sets the expiration date associated with allocated vol_names selected. The vol_names argument must be in the allocated state, otherwise a message is printed to that effect If the volume name is secondary, the expire date of the allocated volume set to which the secondary volume belongs is changed. DATE must be acceptable to convert_date_to_binary_. (See "Notes on Expiration Dates. tt) -pv_expire DATE; -pvexp DATE sets the physical volume expiration date of the specified vol_names to DATE. The volume set state does not become pv_expire until the next time the volume set state is changed (via the alloc, free, and rsv keys), after the date is reached. If the volume name is primary, the expiration date is reset to DATE for only the primary volumes unless followed by -secondary_volumes. Secondary volumes of a volume set can be selected individually to set their pv_expire date. DATE must be acceptable to convert_date_to_binary_. (See "Notes on Expiration Dates. n) -secondary_volumes, -svol is used in conjunction with -pvexp to indicate that the secondary volumes of the primary volume name preceeding -svol should also be set to the given pv_expire date. 3-553 AG92-()6 As an active function, "true" is returned when the date and/or comment has been successfuly changed for all designated vol_names (see "Notes on Active Function"). test Usage: mvp test {vol_names} {-control_args} tests what state the specified volume sets are in. If the vol_name supplied is a secondary volume, the attributes of the set to which it belongs to are tested. Control Arguments: -allocate, -alloc tests whether any volume sets or vol_names selected are in the allocate state. -first {N}, -ft {N} tests the first N volume sets; "first" is defined as the volume sets that have been most recently allocated. (Default: I, if you give no N) -free tests whether any volume sets or vol_names given are in the free state. (Default) -last {N}, -It {N} tests the last N volume sets; "last" is defined as the volume sets that have been in the allocated state the longest Failure can occur when N volume sets are requested and only N-l volume sets are in the pool. (Default: 1. if you supply no N) -match STR tests all volume sets whose comment contains the substring STR. -pv_expire, -pvexp tests whether any volume sets or vol_names specified are in the expire state. -reserve, -rsv tests whether any volume sets or vol_names selected are in the reserve state. -volume_size {N}, -vs {N} tests whether volume sets of size N are in one of the specified states. If more than one volume set of size N exists and neither -first nor -last is given. then the last free, reserved, and so on (as indicated by the state control arguments) volume set of size N is tested. If no volume set of size N exists, an error message is returned. (Default: I, if you supply no N) The vol_names argument and -ft, -It, -match, or -vs are mutually exclusive. If -vs is not given, the default action is to consider all volume sets of any size in the pool. As an active function, "true" is returned if a volume set with the state specified is found in the pool. 3-554 AG92-G6 use; u Usage: mvp u {path} specifies the pathname of the mvp segment to be used by future invocations of mvp in this process.· - The volumes suffix is asSUmed. If you omit path, your default volume segment is used. If the segment specified by path does not exist, mvp creates it As an active function, the pathname is returned. NOTES Normally a tape reel or disk pack is a volume, but any other set of objects, such as library books or portable terminals, could just as easily be regulated. The default volume pool for each user pool is named Person_id. volumes and exists in your home directory; you can reset this default using this key. You can add objects to, or delete objects from, the pool. An object can have one of four states: allocate, free, pv_expire, or reserve. Associated with each object in the pool is a state, a slate change date, a comment, and two optional expiration dates. The comment field can be any ASCII string of up to 64 characters. The comment is intended to describe the contents of the volume, but can easily describe the attach description that creates the volume, etc. NOTES ON ACTIVE FUNCTION As an active function, mvp returns "true, " a list of volume names, or pathnames, depending on the actual key request. In the case of a partial success when an attempt to query you is made, active_fnc_err_ is called; however, its action is overridden when you give -force or -fexp. This results in returning "true" or the partial list of volume names successfully acted upon. NOTES ON EXPIRATION DATES There are two kinds of expiration dates. One is associated with the physical volume and is referenced with -pv_expire. The state pv_expire is associated with the physical volume also. The pv_expire date is checked whenever the volume state is changed to free, allocate, or reserve or when a volume is removed from, or appended to, another volume set. When a 8eC.ondary volume within a volume set expires, the next time that volume set state is changed the state of the volume set changes to pv_expire and you are notified. The date is not checked when you use the reuse key. When the physical expiration date of a volume set is reached, the state changes to pv_expire and a message is printed. You can only delete or free expired volume sets from the volume pool; if you free them, you can reset the expiration date using the set key. Physical volume expiration dates are useful for keeping track of old and bad tapes. 3-555 AG92-06 master_directories The other optional expiration date applies only to allocated volume sets. It is referenced by -expire and refers to the time when the information on the volume set is considered no longer relevant You can set this date at allocation time. When the volume set is f reed. the expire date field is cleared. This expire date is useful for keeping track of recycling volume sets. There is no state associated with this expire date. Both kinds of expiration dates have to be explicitly set by you using control argu..'D.ents or the set key. If not set. the default is for volume sets never to expire. NOTES ON QUERYING You are queried on whether to continue a requested action (allocate, reserve, etc.) when the action can only be performed on some but not all volume names specified. You can use -force to override the query. If you answer "no," the entire request is aborted and no action is taken. If you answer "yes" to the query or use -force, the request is performed on the volume sets eligible and a message is printed listing the volume sets on which no action was taken. NOTES ON VOLUME SETS The volume pool is made up of volume sets. A volume set consists of a primary volume and, optionally, a group of secondary volumes. The set is referenced by the primary volume name. The size of a volume set can range from 1 to N volumes. Therefore a single volume A is a volume set of size one; it is a primary volume with no associated secondary volumes. A volume set grows and shrinks by the appvs and rmvs keywords. For example, three volume sets, A, B, C, each of size one, can be "bound" together into one volume set thus: "mvp appvs ABC". The primary volume name to reference this set is A with two secondary volumes, Band C, associated with it The state of a volume set is changed by the allocate, free, reserve, and pv_expire keys, given the primary volume name or the -volume_size and any optional control arguments. Name: master_directories, mdirs SYNTAX AS A COMMAND mdirs star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [mdirs star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of master directories that match one or more star names. 11/86 3-556 AG92-o6A master_directories master_directories ARGUMENTS star_names are star names to be used in selecting the names t-o be returned. CONTROL ARGUMENTS -absolute_pathname. -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star=name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error. -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per directory is returned; Le.. if a master directory has raore than one name that matches star_name, only the first match iound is returned. Since each entryname (or pathname) returned by master_directories is enclosed in quotes. the command processor treats each name as a single argument regardless of the presence of special characters in the name. EXAMPLES The following interaction illustrates the use of the mdirs active function. string [mdirs >udd>**] Multics SysMaint 11/86 3-557 AG92-06A max Name: max SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION [max num_args] FUNCTION returns the maximum of the numeric arguments passed to it EXAMPLES string [max 3.6 le-3] 3.6 Name: mbx_create, mbcr SYNTAX AS A COMMAND mbcr paths FUNCTION creates a mailbox with a given name in a specified directory. ARGUMENTS paths are pathnames of mailboxes to be created. You need not give the mbx suffix. ACCESS REQUIRED Modify and append permissions are required on the parent directory. NOTES Name duplication is handled this way: If the old segment with that name has other names, the conflicting name is removed and you are notified; otherwise you are asked whether to delete the old segment The extended access placed on a new mailbox is adrosw aow aow 11/86 Person.*.* *.SysDaemon.* *. 'I:. 'Ie 3-558 AG92-o6A memo For more informaiion on exiended access, see the mail command. * EXAMPLES The command line mbcr JBentham RAmundsen.home >udd>Multics>LAriosto>LAriosto creates the mailboxes JBentham.mbx and RAmundsen.home.mbx in the working directory and creates the mailbox LAriosto.mbx in the directory >udd>Multics>LAriosto. Name: memo SYNTAX AS A COMMAND memo {-memo_options} memo_text memo {-action_args} {-memo_options} {-selection_args} SYNTAX AS AN ACTIVE FUNCTION [memo memo_text] [memo -list {-totals}] FUNCTION maintains a user-created reminder list in a memo segment, which is normally Person_ID.memo, in your home directory. ARGUMENTS memo_text is the text of the memo being set It cannot be longer than 132 characters. You can specify it in one of two forms: STR is the string without an initial hyphen that begins the memo text No further arguments are accepted. -memo STRs treats all succeeding STRs as part of the memo text. whether or not they begin with hyphens. LIST OF MEMO OPTIONS Use these control arguments to control various options of the memo being set or to select memos being otherwise processed. 11/86 3-559 AG92-06A memo memo -alarm, -al specifies that the memo is to be an alarm. An alarm memo is printed, or executed if set with -call, when its timer goes off, if timers are enabled, rather than being explicitly processed. It is deleted immediately after it reaches maturity, unless you supplied -retain. -can passes the memo text to the command processor as a command line when the memo matures, rather than printing it -date DT, -dt DT identifies a date for the memo to mature. DT is truncated to the midnight preceding the date in which DT falls. (See "Notes. ") -expires DT, -exp DT identifies the expiring time of the memo; this is treated as a delta from the maturity time (which it must be greater than) so that repeating memos with expiration times work properly. When used as a selection argument, all expiring memos are selected, regardless of the expiration dates. (See "Notes" and "Notes on Expiring Memos. tt) -invisible, -iv specifies that the memo never be mature and never be printed during a normal memo print -no_retain, -nret processes the memo only once and then deletes it. (Default for alarm memos) -repeat DT, -rpt DT identifies the repeat interval of the memo. where DT must be greater than or equal to one minute. When the memo is reset. the new maturity time is the next successive interval that matures in the future. When used as a selection argument, all repeating memos are selected, regardless of the repeat intervals given. (See "Notes" and "Notes on Repeating Memos.") -repeat_when_processed. -rwp specifies that the repeat time of a repeating memo be applied from the time the memo is processed, rather than from the maturity time. This is useful for memos that are only significant within a single process. -retain, -ret keeps an alarm memo as an ordinary printing (or executing if set with .-call) memo after it matures, rather than being deleted. (Default for nonalarm memos) 11/86 3-560 AG92-06A memo memo -time DT, -tm DT identifies a time for the memo to mature (see "Notes"). LIST OF ACTION ARGUMENTS These control arguments Control various memo options. The -delete, -list, -postpone, * -print, and -process actions are mutually exclusive. -brief, -bf does not print message "No memos." if no memos are found. 11/86 3-560.1 AG92-()6A This page intentionally left blank. 11/86 AG92-06A memo memo -delete {-foree} , -dl {-fc} deletes all memos selected by the optional arguments. You must explicitly supply at least one memo. It queries you before deleting nonmature memos; however. with -foree, it deletes memos-without querying you--even if they are not yet mature. -list, -Is prints text and control information of selected memos; no memos are executed. If you don't explicitly select memos, all memos are listed. If you also give -totals, only the total number of selected memos is printed. -off suppresses all memo alarms until the next memo command with no explicitly specified action. You can combine -on and -off with other actions. -on enables memo alarms without printing or executing nonalarm memos. -pathname -default, -pn -dft resets the default memo segment to Person.ID.memo in your home directory. -pathname path, -pn path changes the default memo segment to path if specified with no other action; otherwise the memo segment specified by path is used for the execution only of the current memo command. If you supply -pathname along with -on or -off, the default memo segment is changed and alarms are turned on or off. as appropriate. for the new segment You need not give the suffix .memo. -postpone DT, -pp DT reschedules the maturity of the selected memos to the time specified by DT, if DT is later than the current maturity time. You must explicitly provide at least one memo. (See "Notes.") -print, -pr prints text of all selected memes; No memes are executed. If you don't explicitly select memos, only mature memos are printed. -process causes all mature memos to be processed. and alarms to be turned on. if not otherwise specified. This is equivalent to explicitly specifying no action. -status, -st prints information about the current default memo segment If you specify it. it must be the only argument. -totals, -tt you can only use it together with -list. When you give it, the total number of memos selected is printed, rather than listing each of the memos. 3-561 AG92-()6 memo memo LIST OF SELECTION ARGS These arguments are used to select memos to be listed, printed, deleated, or postponed. You can also use some memo_options to specify types of memos to be selected (see "Notes"). When you supply more than one selection_args, only those memos that match all the selection criteria are chosen. memo_number is either a positive decimal number specifying a single memo (e.g., 32) or two such numbers separated by a colon, specifying a range of memos (e.g.• 12:16). -from DT. -fm Dr selects all memos that mature on. or after. DT. You can combine it with -to, but specify each only once. It is incompatible with -date and -time. (See "Notes. tt) -match STR specifies a string against which memo texts are matched to select memos. STR cannot be longer than 32 characters. You can supply up to 40 STRs; all memos that match at least one are selected. -to DT selects all memos that mature on, or before, DT. incompatible with -date and -time. (See "Notes.") This control argument is NOTES See Section 1 for a description of valid DT values. No more than 5082 memos can be contained in a single memo segment An individual memo can be no more than 132 characters long. If you explicitly specify no action and set no memo, all mature memos are processed (printed or executed) and the alarm timer is turned on, enabling the processing of alarm memos. You can use the memo_options to specify types of memos to be selected; those that take a date/time interval (-repeat. -expires, but not -date or -time) cause the selection of all repeating or expiring memos, as the time interval (which you must specify) is ignored. NOTES ON DEFAULT MEMO SEGMENT The memo command operates on the default memo segment (unless -pathname is specified with one of the actions -delete, -list, -postpone. -print or -process). This default memo segment is also used when processing alarm timers. to find the memos which should be processed for the alarm. If the default memo segment has never been explicitly specified (by using -pathname without any other actions), it is the segment Person_ID.memo in the user's home directory. 3-562 AG92-G6 memo The default memo segment is created if it does not already exist If the default memo segment is changed. alarms are turned off for the old memo segment. and then turned on for the new one (if requested). Thus, only one memo segment can have alarms active at a time. NOTES ON REPEATING MEMOS A repeating memo repeats by setting a new memo that is identical to the original one, and then turning off the repeat specification in the original memo. Thus the actual repeating memo, rather than its visible consequences, gets a new number each time it repeats. Since the repeat specification is turned off in the original memo, it never repeats again. but remains until deleted. unless it has an expiration date or was set with -no_retain. An alarm memo that repeats will mature once, and then be automatically deleted, unless it was set with -retain, in which case it is turned into an ordinary, non-alarm memo and lasts un til it expires or is deleted. NOTES ON EXPIRING MEMOS Expired memos are deleted without being reprinted or executed. However, if they are repeating memos, they are repeated before being deleted. This is useful for cases such as a reminder of a weekly meeting, where the reminder of this week's meeting should always be set, but the reminder of this week's meeting should not be printed if the current time is after the end of this week's meeting. A sequence of repeating memos must be terminated manually (by deleting the current memo); the -expires control argument is not useful for this purpose. NOTES ON ACTIVE FUNCTION The memo active function can only be used to set and list memos. When a memo is set, the number assigned to the newly set memo is returned. When memos are listed, a string consisting of the memo numbers selected, separated by spaces, is returned; if -totals is specified, the total count is returned. Name: menu_create SYNTAX AS A COMMAND menu_create menu name {-control_args} FUNCTION creates a menu description, assigns it a specified name, and stores it in a segment The menu description can be used with other menu commands, active functions, and subroutines. 3-563 AG92-06 ARGUMENTS menu_name is the name assigned to the menu when it is stored. CONTROL ARGUMENTS -brief, -bf creates the segment given by -pathname without querying you. -header STR. -he STR specifies a line of header. All header lines supplied appear in the menu in the order given. Quote STR if it contains blanks or special characters. -option STR, -opt STR specifies a menu option. The options appear in the menu in the order given. Supply at least one option. Quote STR if it contains blanks or special characters. -pathname PATH. -pn PATH is the pathname of the value segment in which the menu is stored. The value suffix is assumed. If the value segment selected does not exist, you are asked if you want to create it (unless you have used -brief). If you omit -path name, your default value segment (>udd>Project_id>Person_id>Person_id.value) is used to store the menu. -trailer STR, -tr STR specifies a trailer line. All trailers appear in the menu in the order given. Quote STR if it contains blanks or special characters. LIST OF FORMAT CONTROL ARGUMENTS The following control arguments manipulate the format of the menu: -center_headers. -ceh cen ters all header lines. -center_trailers, -cet cen ters all trailer lines. -columns N, -col N sets the number of columns in the menu to N, where N is a positive decimal integer. (Default: one column) -line_length N, -11 N specifies the line length for the menu, where N is a positive decimal integer. If not supplied, the line length is your terminal's line length at the time you invoke menu_create. -no_center_headers. -nceh left-flushes header lines. (Def ault) 3-564 AG92-06 -no_center_trailers, -ncet left-flushes trailer lines. (Default) -option_keys STR, -okeys STR specifies the keystrokes to be associated with each option. Each character in STR is associated with the corresponding option, so that if it is typed, the corresponding option is selected. There must be at least as many characters in STR as there are options. If you give no -option_keys, the string "123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ" is used. -pad C specifies the padding character to be used for centering headers and trailers, where C is one character. (Default: space character) ACCESS REQUIRED You must have rw access on the value segment EXAMPLES The following example sets up a small menu named compile: menu_create comp i 1e -pn [pd] >temp -pad = -he iiSAMPLE MENU 'i -tr = -ceh -cet -columns 2 -11 78 -opt "Compile with No Options" -opt "Symbol Table" -opt "Profile Info" The menu looks like this: =================================SAMPLE MENU================================== (3) Profile Info (1) Compile with No Options (2) Symbo 1 Tab 1e ============================================================================== 3-565 AG92-o6 Name: menll.-delete SYNTAX AS A COMMAND FUNCTION deletes a menu description from a specified value segment ARGUMENTS menu_name is the name that was assigned to the menu when it was stored. CONTROL ARGUMENTS -pathname PATH, -pn PATH is the patbname of the value segment in which the menu is stored. The value suffix is assumed. If you don't give it. your default value segment (>udd>Project_id>Person_id>Person_id.value) is searched for the menu. Name: men~describe SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION [menu_describe menu_name -control args] FUNCTION prints or returns information about a menu. ARGUMENTS menu_name is the name that was assigned to the menu when it was stored. CONTROL ARGUMENTS -count, -ct returns the number of options defined in the menu. 3-566 AG92-()6 -height returns the height of the menu. -pathname PATH, -pn PATH is the pathname of the value segment in which the menu is stored. The value suffix is assumed. If you don't give it, your default value segment (>udd>Project_id>Person_id>Person_id.value) is searched for the menu. -width returns the width of the menu. NOTES As a command, any number of control arguments is allowed. If none are given, all attributes are displayed. As an active function, one of -count, -height, or -width must be given. Name: menu=display SYNTAX AS A COMMAND FUNCTION displays a menu in a window. ARGUMENTS menu_name is the name that was assigned to the menu when it was stored. CONTROL ARGUMENTS -io_switch STR, -is STR specifies the name of an I/O switch for a window. This serves to identify a window. (Default: user_i/o) -pathname PATH, -pn PATH is the pathname of the value segment in which the menu is stored. The value suffix is assumed. If not given, your default value segment (>udd>Project_id>Person_id>Person_id.value) is searched for the menu. 3-567 AG92-06 Name: men~et_choice SYNTAX AS A COMMAND SYNTAX AS AN ACTiVE FUNCTION FUNCTION gets a menu choice from you and prints or returns it ARGUMENTS menu_name is the name assigned to the menu when it is stored. CONTROL ARGUMENTS -default_fkeys STR. -dfkeys STR specifies the keys to be used if the terminal does not have function keys or the proper set of function keys. (See "Notes on Function Keys" below.) -function_keys STR, -fkeys STR specifies the keys to be used to simulate function keys. This control overrides any function key definitions already established for the terminal. (See "Notes on Function Keys.!!) -io_switch STR. -is 'STR specifies the name of an I/O switch for a window. (Default: user_i/o) -pathname PATH, -pn PATH is the pathname of the value segment in which the menu is stored. The value suffix is assumed. If not given, your default value segment (>udd>Project_id>Person_id>Person_id.value) is searched for the menu. NOTES Many terminals have function keys. On many of these terminals (such as the Honeywell VIP780l), they are labeled "FIn, "F2", etc. If you type one of these function keys, menuJet_choice returns the string "F*", where * is a one- or two-digit number signifying which function key is pressed. It is possible to specify your own set of keystrokes to be used instead of the terminal's function keys (-function_keys), or to specify a set of keystrokes to be used if the terminal does not have enough function keys (-default_fkeys). Each character in the string simulates a function key: The first one simulates function key 0, the next, function key 1, etc. To simulate a given function key, type esc-C, where C is the character corresponding to the function key; thus, if the string is "0123456789", typing esc-2 returns F2. 3-568 AG92-06 Supply -function_keys to specify keystrokes to be used instead of any that might be defined for the terminal; if given. the simulation of function keys always takes place. Give -default_fkeys if you want to use the terminal-defined function keys when possible. but wish to specify key sequences to be used to simulate function keys if necessary. Each character in the string following -default_fkeys corresponds to one function key_ If the character is a space. it means it makes no difference if the terminal has a function key corresponding to that position. If the character is not a space, that character is employed to simulate a function key if necessary. If the terminal does not have a function key for every nonspace character in the string, then STR is used to simulate function keys. Thus, the string II ?p q" means that you do not care whether the terminal has a function key 0 or a function key 3, but you wish to use function keys 1, 2. and 4. If any of these three function keys is not present on the terminal. then esc-? substitutes for Pl, esc-p substitutes for F2. and esc-q substitutes for F4. SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION [menu_list {menu_starname} {-control_arg}] FUNCTION lists the names of the menu descriptions stored in a value segment ARGUMENTS menu_stamame is a stamame used to search for menu descriptions. If omitted. the default is **. CONTROL ARGUMENTS -pathname PATH, -pn PATH is the pathname of the value segment in which the menu is stored. The value is assumed. If not given, your default value segment suffix (>udd>Project_id>Person_id>Person_id.value) is searched for the menu. 3-569 AG92-()6 Name: merge_ascii, ma SYNTAX AS A COMMAND rna paths {-control_args} FUNCTION merges two or more related ASCII text segments. ARGUMENTS paths are pathnames of segments to be merged as automatically as possible. The equal and archive component pathname conventions are allowed. You can merge up to six segments. including those preceded by -edit. CONTROL ARGUMENTS -edit path merges the segment named path in a nonautomatic manner. Edit mode is entered each time a modification is found in the specified segment -minchars N specifies the minimum number of characters that must be identical for merge_ascii to assume blocks of text in different segments are identical. (Default: 25) -minlines N specifies the mInImum number of lines that must be identical for merge_ascii to assume blocks of text in different segments are identical. (Default: 2) -old_original path. -old_orig path identifies path as the pathname of a segment antecedent to the most recent common ancestor of the texts being merged and allows the automatic picking up of identical changes present in all the texts being merged. -original path, -orig path identifies path as the pathname of a segment containing the original version of the text The proper original is the most recent common ancestor of the texts being merged. Overlapping changes, even if identical, enter edit mode. -output_file path, -of path puts the merged output text in the segment named path. The archive component pathname convention is not allowed. 3-570 AG92-()6 NOTES This command is typically used to merge texts that have been independently modified by several users. If an original version of the text is available. and if you desire, merge_ascii performs the merge automatically, requiring your intervention only when it detects overlapping modifications. When your intervention is required, merge_ascii displays line-numbered blocks of text and then enters edit mode allowing you to choose lines from any text or insert new ones. When blocks of text are displayed, each line is preceded by a text identifier and a line number. The text identifier A is reserved for the original. whether supplied or not The identifiers B-G are assigned to the texts being merged in the order in which their pathnames are encountered on the command line. The identifier M is used for the merged output if printed while in edit mode. You can use either -original or -old_original to enable automatic merging. If you supply neither. edit mode is entered each time differences are found in the segments being merged. Use -old_original judiciously, only if appropriate and when you fully understand the relationships between the texts being merged. LIST OF EDIT REQUESTS In the syntax of the edit requests. is the lowercase letter corresponding to the text identifier used by merge_ascii and, < 1 i ne_no> is a line number in the text segment You can specify line numbers as 11<" to address the first line or as 11>11 to specify the last line of a current block. k copy current block from specified text (e.g., bk copies current block from text B). k copy specified line from specified text (e.g., b5k copies line 5 from text B). , k copy specified lines from specified text (e.g., b4,7k copies lines 4 through 7 from text B). p print current block from specified text (e.g., bp prints current block from text B). p print specified line from specified text (e.g., b6p prints line 6 from text B). , p print specified lines from specified text (e.g.. b12.16p prints lines 12 through 16 from text B). 3-571 AG92-()6 d delete the current block in specified text (e.g., md deletes the current block in text M). input enter input mode. return from input mode to edit mode. go exit editor and continue comparison. quit abort merge and return to command level. If you give this request during a merging procedure, all work is lost; work is not saved unless merging is done from the beginning to the end of the segments. e execute rest of line as a Multics command line. x display identifiers, current line numbers, and pathnames of each text help print a list of the edit requests and a brief explanation of each one. NOTES ON EDIT REQUESTS In any invocation of edit mode the current block in each text is just the block of lines previously displayed. The current block in text M is initially empty and grows as you select or input lines (see "Examples" below). The print (p) and copy (k) requests can address any lines in any text (A to M) known to merge_ascii. The delete (d) request can only be applied to the current block in text M and has the effect of undoing all edit requests made since changes were last displayed. You can give multiple edit requests, delimited by blanks, on a single request line; however, quit, go, input, and e must not be followed by other requests. EXAMPLES The command line rna -orig pathA pathS pathC -of pathM automatically merges the contents of pathB and pathC into pathM. Because you supplied an original version (pathA), all nonoverlapping changes in pathB and pathC are placed in pathM. 3-572 AG92-06 The command line rna pathS pathC -of pathM performs a nonautomatic merge on the contents of pathB and pathC, displays all differences. and enters edit mode. This type of merging is typically used when there is no original segment The command line rna -orig pathA -edit pathB -edit pathC -of pathM performs a nonautomatic merge, but gives you information about the contents of the original text In this case, although an original segment exists, you want complete control over what goes into the output segment The command line rna -original pathA pathB -edit pathC -of pathM performs a merge in which changes found in pathe enter edit mode. Nonoverlapping changes in pathB are picked up and automatically placed in the output segment This combination of control arguments is useful when you are familiar with the changes present in pathB but wishes to review changes present in pathC before picking them up. The command line rna -old_orig pathA pathB pathe -of pathM merges pathB and pathC automatically assuming that pathA is an earlier version of the text than the most recent common ancestor of pathB and pathC. Changes present in both pathB and pathC are picked up automatically. You can use -old_original to obtain an automatic merge if pathA is a true original but some changes have been applied to both pathB and pathC. If you give -old_original and pathA contains changes not present in both pathB and pathC, then the resulting output segment is nearly always useless to you. 3-573 AG92-06 Name: message_status, msgst SYNTAX AS A COMMAND msgst {mbx_specification} {-control_arg}} SYNTAX AS AN ACTIVE FUNCTION [msgst {mbx_specification}] FUNCTION prints information about mailboxes on which messages are being accepted. ARGUMENTS mbx_specification specifies the mailbox on which messages are being accepted. If not given. the user's default mailbox (>udd>Project>Person>Person.mbx) is used. CONTROL ARGUMENTS -all, -a prints information for all mailboxes on which the user is accepting or deferring messages. LIST OF MBX SPECIFICATIONS -log specifies the user's logbox and is equivalent to -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx -mailbox path, -mbx path specifies the pathname of a mailbox. The suffix .mbx is added if necessary. -save path. -sv path specifies the pathname of a savebox. The suffix .sv.mbx is added if necessary. -user STR specifies either a user's default mailbox or an entry in the system mail table. STR is any noncontrol argument and is first interpreted as -mailbox STR; if no mailbox is found, STR is then interpreted as -save STR; if no savebox is found, it is interpreted as -user STR. 11/86 3-574 AG92-06A NOTES As an active function, msgst returns the command string that you can use to set the message acceptance state on the specified mailbox to the current state. Thus you can push and pop multiple acceptance states using the value segment: value_set old_state II[msgst] -push dm value_set old_state II[msgst] -push am -call !l ec message_handler" [value_get old_state -pop] [value_get old_state -pop]. (" II" means the returned string is not to be rescanned for command language special characters; the returned value is a single token.) 11/86 3-574.1 AG92-06A This page intentionally left blank. 11/86 AG92-o6A micro_transf er micro_transfer Name: micro_transfer, mt SYNTAX AS A COMMAND mt path {-control_args} FUNCTION transfers files between a Multics system and a remote microcomputer (personal computer) using either 1) the xmodem protocol or 2) the IBM PC-to-Host protocol. Your terminal must be connected to the system through the tty_ I/O module. (This is the usual method of connecting terminal to the Multics system.) ARGUMENTS path can be one of the following: 1) is the pathname of the source segment on Multics when transferring files from Multics to a microcomputer. 2) is the pathname of the target segment on Multics when transferring files to Multics from a microcomputer. CONTROL ARGUMENTS -attach_description STR, -atd STR specifies the I/O module to be used to implement the file transfer, where STR specifies the I/O module to be used and the I/O switch to which the module is to be attached. Enclose STR in quotation marks if it contains spaces or other command language characters. STR can be one of the following: xmodem_io_ user_i/o specifies the XMODEM protocol is to be used. (Default) ibm_pc_io_ user_i/o specifies the IBM PC-to_Host protocol is to be used. 3-575 AG92-D6 micro_transf er micro_transfer -eof STR specifies the end-of-file sequence for the microcomputer, where STR is the end-of-file character. STR can be a printable ASCII character or a control character; you must express the latter type in the octal equivalent and surround it by quotation marks. When transmitting a file to a microcomputer the end-of -file character is transmitted as STR; when receiving a file from a microcomputer the occurrence of STR indicates the end-of-file to Multics. -eol STR specifies the end-of-line sequence for the microcomputer, where STR is the end-of-line character. STR can be a printable ASCII character or a control character; you must express the latter type in the octal equivalent and surround it by quotation marks. When transmitting files to a microcomputer, each linefeed character is translated to STR; when receiving files from a microcomputer, each occurrence of STR is translated to a linefeed character. -modes STR sets the modes for file transfer according to STR, which is a string of mode names separated by commas. You can optionally precede many modes by A to turn the specified mode off. Modes not specified in STR are left unchanged. Modes are restored to their original value after the file transfer is complete. (See set_tty for a list of valid modes; see "Notes on Data Transfer I/O Modules" for the defaul t modes.) -receive receives data from the microcomputer. Give either -receive or -send. -send sends data to the microcomputer. NOTES ON DATA TRANSFER liD MODULES The micro_transfer command provides an interface between the Multics file system and a data transfer protocol. The data transfer protocol is implemented as an 110 module. Such I/O modules must specify a target 110 switch, and they must support the stream_input and stream_output opening modes. The switch identified by the switch argument must be open for stream_in put_output. The following I/O modules are currently available for use with micro_transfer: 3-576 AG92-06 micro transfer micro transfer xmodern_io_ uses the XMODEM data transfer protocol. The default mode string used by micro_transfer for file transfer is: "no_outp,8bit, breakall. "echoplex,rawi, "crecho," Ifecho," tabecho,rawo" ibm_pc_io_ uses the IBM PC-to-Host data transfer protocol. This protocol does not transfer binary data or check for errors. The default mode string used by micro_transfer for file transfer is: ""8bit,breakall, " echoplex.rawi, "crecho, " lfecho, " tabecho,rawo" Users writing their own data transfer protocol I/O modules with micro_transfer may do so. Its descriptions would be: xxx uses the user-specified data transfer protocol for the file transfer. The default mode string by micro_transfer for file transfer is: "no_outp,8bit, breakall, "echoplex,rawi, "crecho," Ifecho, "tabecho,rawo" used NOTES ON FILE TRANSFER SPEED There is no guarantee of any particular line speed when transferring files between Multics and a microcomputer. Line speed is dependent on the microcomputer and the load of the FNP and communication system for Multics. Due to the nature of the XMODEM and IBM PC-to-Host protocols, files may not be successfully transferred to Multics over high-speed lines. The actual limit depends on the site configuration and current load. The Video System sheld net be used when using micro_transfer. PROCEDURE FOR USING ,MICRO TRANSFER Use the following procedure to transfer files between Multics and a microcomputer with micro_transfer: 1. 11/87 Invoke the control program on the microcomputer. This program is a terminal emulator and file transfer program. 3-577 AG92-D6B micro_ transf er micro_transfer 2. Connect to Multics by issuing the appropriate command to the microcomputer. To find out which command to use, refer to the manual that documents the microcomputer's file transfer protocol. Once connected, the standard Multics ~9).ner is displayed. 3. Login to Multics. 4. Issue micro_transfer on Multics specifying the pathname on Multics and the applicable control arguments. 5. Escape now back to the microcomputer. The escape sequence used depends on the microcomputer. To find out which escape sequence to use, refer to the manual that documents the microcomputer's file transfer protocol. Upon return to the microcomputer, enter the type and direction of the file transfer and the microcomputer file name. This must correspond to the type and direction specified on Multics. For example, if you used micro_transfer -send, the command used for receiving a file transfer must be executed on the microcomputer. 6. The file transfer begins. A display indicating the status of the transfer mayor may not occur, depending on the communications package residing on the microcomputer. 7. At the end of the transfer, the microcomputer returns to the communications command level. EXAMPLES micro_transfer foobar.foo -send -atd "ibm_pc_io_ user_i/o" -eo1 "\015" 3-578 AG92-D6 minus min Name: min SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION [m in num_args] FUNCTION returns the minimum of the numeric arguments passed to it EXAlIIPLES string [min 3 -4] -4 Name: minus SYNTAX AS A COMMAND minus {numA {numB}} SYNTAX AS AN ACTIVE FUNCTION [minus {numA {numB}}] FUNCTION returns the result of numA minus numB. If numB is not specified, the negative of numB is returned. If you give no arguments, returns O. EXAMPLES string [minus 3.5 3] 0·5 minus 5 -5 minus -6 6 minus 0 3-579 AG92-06 minute mod Name: minute SYNTAX AS A COMMAND minute {time_string} {-control_arg} SYNTAX AS AN ACTIVE FUNCTION [minute {time_string} {-control_arg}] FUNCTION returns the one- or two-digit number of a minute of the hour, from 0 to 59. The format string to produce this is ""Z9MH". ARGUMENTS time_string indicates the minute about which information is desired. If you supply no time_string, the current minute is used. The time string is concatenated to form a single argument even if it contains spaces; you need not quote it (See Section 1 for a description of valid time_string valUes.) CONTROL ARGUMENTS -zone STR STR specifies the zone that is to be used to express the result process default) (Default: the NOTES Use the print_time_defaults command to display the default zone. display_time_info command to display a list of all acceptable zone values. Use the Name: mod SYNTAX AS A COMMAND mod numA numB SYNTAX AS AN ACTIVE FUNCTION [mod numA numB] FUNCTION returns the remainder of numA divided by numB (numA modulo numB). 3-580 AG92-06 mod EXAMPLES string [mod 4. 3] 1 string [mod 4.5 3.5] 1 Name: monitor_quota SYNTAX AS A CO'A'IIAND monitor_quota {-control_arguments} FUNCTION calculates storage of a directory and sends a warning message when approaching a record quota overflow condition. CONTROL ARGUMENTS -call STR {N} passes STR to the command processor as a command when a directory's segment quota used is found to be greater than 90 percent (default) of the quota assigned. If you give N, the default is overridden. (See "Notes" below.) -console {N} sends a warning of an approaching record quota overflow condition to the system console. You require access to the phcs_ gate to issue warnings on the system console. If you specify N, the default percent value at which the warning is to be issued (as given in the functional description) is overridden. -off turns off all monitoring in the current process. You cannot use -off with any other control arguments. -pathname. -pn IS the pathname of" the directory to be monitored. You can give only one path. (Default your working directory) -repeat DT, -rpt DT identifies the interval for setting the monitor time. It overrides the default time calculation. DT is a relative time >= 1 minute and acceptable to convert_date_to_binary_ (e.g., 10min, 1hr). 3-581 AG92-06 month -warn Person_id.Project_id {Person_id.Project_id... } {N} sends the warning message to Person_id.Project_id. You can list up to 10 users. You get a message by default if you omit -warn and -console. If you give N, the default percent value at which the warning is to be issued is overridden. NOTES You can use monitor_quota several times in a process to monitor different directories. The number of records given with -call, -console, and -warn must be less than the quota assigned to the directory. The default interval when you invoke monitor_quota without -repeat is set with a time interval dependent on storage availability: if the directory is 50 percent full, an alarm is set to trigger in 30 minutes to check again; if 80 percent full, a message is sent and an alarm time of two minutes is set; if 90 percent, a warning is sent every minute, and if you provide -call the specified string is passed to the command processor. Name: month SYNTAX AS A COMMAND month {time_string} {-control_arg} SYNTAX AS AN ACTIVE FUNCTION [month {time string} {-control_arg}] FUlVCTION returns the one- or two-digit number of a month of the year, from 1 to 12. The format string to produce this is "AZ9my". ARGUMENTS time_string indicates the month about which information is desired. If you supply no time_string, the current month is used. The time string is concatenated to form a single argument even if it contains spaces; you need not quote it. (See Section 1 f or a description of valid time_string valUes.) CONTROL ARGUMENTS -zone STR STR specifies the zone that is to be used to express the result (Default: the process default) 3-582 AG92-06 month NOTES Use the print_time_defaults command to display the default zone. display_time_info command to display a list of all acceptable zone values. Use I I the * Name: month_name SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION FUNCTION returns the full name of a month of the year (e.g., "June"). The format string to produce this is "Amo". ARGUMENTS time_string indicates the month about which information is desired. If you supply no time_string, the current month is used. The time string is concatenated to form a single argument even if it contains spaces; you need not quote it (See Section 1 for a description of valid time_string valUes.) CONTROL ARGUMENTS -language SIR, -lang STR STR specifies the language in which month name, day names, and zone names are to be expressed. (Default: the process default) -zone STR STR specifies the zone that is to be used to express the result (Default: the procesS default) NOTES Use the print_time_defaults command to display the default language and zone. Use the display_time_info command to display a list of all acceptable language and zone values. * 3-583 AG92-()6 move move Name: move, mv SYNTAX AS A COMMAND mv move path1 {path2 •.• path1N path2N} {-control_arg} FUIl/CTION moves a specified segment or multisegment file (along with its access control list and all names) to a new position in the storage system hierarchy. ARGUMENTS pathl is the pathname of a segment or multisegment file to be moved. convention is allowed. The star path2 is the pathname to which pathl is to be moved. The equal convention is allowed. If you don't give the last path2 segment, pathl is moved to your working directory and given the entryname pathl. CONTROL ARGUMENTS -acl copies the ACL. (Default> -all, -a copies multiple names and ACLs. -brief, -bf suppresses the messages "Bit count inconsistent with current length... " and "Current length is not the same as records used.... n -chase copies the targets of links that match pathl (see "Notes"). -long prints warning messages as necessary. (Default) -name, -nm copies multiple names. (Default) -no_acl does not copy the ACL. The segment is given the IACL of the target directory. -no_chase does not copy the targets of links that match pathl. (See "Notes. ") 3-584 AG92-o6 move -no_name, -nnm does not copy the multiple names. ACCESS REQUIRED You need read access for pathl, status and modify permISSIon for the directory containing path!, and status, modify, and append permission for the directory containing path2. NOTES The default for chasing links depends on pathl: if it is a star name, links are not chased by default; if it is not, links are chased. If the primary name of path1 is the only one, it is added as a secondary name to path2. If' an entry with the entryname pathl already exists in the target directory, you are asked whether the already-existing entry should be deleted. If you answer "no," the move does not take place. If pathl is protected by the safety switch, you are asked whether you want to delete pathl after it has been moved. EXAMPLES The command line move alpha >Verdi>= >Verdi>beta b moves alpha from the current working directory to the directory >Verdi, keeping the name alpha. and moves beta from the directory >Verdi to the current working directory with the names b and beta. SYNTAX AS A COMMAND mar request_identifiers {-control_args} FUNCTION moves a request from one absentee queue to another. The request is always placed at the end of the target queue. 3-585 AG92-()6 ARGUMENTS request_identifiers you can specify them in one of the following forms: path is the full or relative pathname for the absentee input segment of requests to be moved. The star convention is allowed. -entry STR, -et STR identifies requests to be moved by STR, the entryname portion of the absentee input segment pathname. The star convention is allowed. -id ID identifies one or more requests to be moved by request_identifier. You can use this identifier to further define any path or -entry identifier (see "Notes"). CONTROL ARGUMENTS -all. -a searches all queues f or the requests to be moved. The target queue is not searched by -all if the source and target request types are identical. This control argument is incompatible with -queue. -brief. -bf suppresses messages telling that a particular request_id was not found or which requests were moved when using star names or -all. -foreground, -fg moves the requests contained in the foreground queue. -queue N, -q N specifies that queue N for the given request type contains the request to be moved, where N is an integer specifying the number for the queue. If you omit -queue, all the queues are searched. -sender STR moves only requests from sender STR. identifiers. You must give one or more request -to_queue N. -tq N specifies which queue to move the request to. (Required) 3-586 AG92-06 -user User_id is a character string giving the name of the submitter of the request if not equal to the group ID of the process. This control argument is primarily for operators and administrators. User_id can be Person_id.Project_id, Person_id, or .Project_id. You need both rand d extended access to the queue. This control argument causes the command to use privileged message segment primitives that preserve the original identity of the submitter. You need the AIM rin~l privilege to preserve the original AIM attributes. If rin~l privilege is not present, your AIM attributes are used. (Default: only requests entered by you are moved) ACCESS REQUIRED You must have 0 extended access to the queue from which the request is being taken, and a access to the queue to which the request is being moved. You must have rand d extended access to move a request owned by another. NOTES If you give any path or -entry, only one -id is accepted and it must match any requests selected by path or -entry. You can supply multiple -id identifiers in a single invocation only if you give no path or -entry. When you use no star names and a single request identifier matches more than one request in the queue(s) searched, none of the requests are moved; however, a message is printed telling how many matching requests there are. If the request is already running, it is not moved and a message is printed. Name: move_daemon_request, mdr SYNTAX AS A COMMAND mdr request_identifiers {-control_args} FUNCTION moves a request from one l/U aaemon queue to another. The move can be within the same request type or from one request type to another. The request is always placed at the end of the target queue. ARGUMENTS request_iden tifiers Can be specified in one of the following forms: 3-587 AG92-06 move~daemon~request path identifies a request to be moved by the full or relative pathname of the input data segment The star convention is allowed. -entry STR, -et STR identifies a request to be moved by STR, the entryname portion of the input data segment pathname. The star convention is allowed. -id ID iden tif ies one or more requests to be moved by request iden tif ier. You can use this identifier to further define any path or -entry identifier (see "Notes"). CONTROL ARGUMENTS -all, -a searches all queues f or the requests to be moved. The target queue is not searched by -all if the source and target request types are identical. This control argument is incompatible with -queue. -brief, -bf suppresses messages telling you that a particular request identifier was not found or that requests were moved when using star names or the -all control argument -queue N, -q N specifies that queue N for the given request type contains the request to be moved, where N is an integer specifying the number for the queue. If you omit -queue, all the queues are searched. -request_type STR, -rqt STR specifies that the request moved is found in the queue(s) for the request type identified by STR. If this control argument is not specified, the default request type is "printer". Request types can be listed by the print_request_types command. -to_QUeue N, -tq N specifies which queue to move the request to. If not given, the default queue of the target request type is used. -to_request_type STR. -to_rqt STR specifies that the request should be moved to request type STR. If this control argument is not specified, the original request type is used. The target request types must be of the same generic type as the original request type. 3-588 AG92-D6 -user User_id specifies the name of the submitter of the requests to be moved. The default is to move only requests entered by the user executing the command. The User_id can be Person_id.Project_id, Person_id, or .Project_id. This control argument is primarily for the operator and administrators. Both rand d extended access to the queue are required. This control argument causes the command to use privileged message segment primitives that preserve the original identity of the submitter. If the process has access isolation mechanism (AIM) ring one privilege, the AIM attributes of the original submitter are preserved. Otherwise, the AIM attributes of the current process are used. ACCESS REQUIRED You must have 0 extended access to the queue from which the request is being taken and a access to the queue to which the request is being moved. You must have rand d extended access to move a request owned by another user (see -user). NOTES If any path or -entry STR request identifiers are given, only one -id ID request identifier will be accepted and it must match any requests selected by path or entryname. Multiple -id ID identifiers can be specified in a single command invocation only if no path or entry request identifiers are given. When star names are not used and a single request identifier matches more than one request in the queue(s) searched, none of the requests are moved. However, a message is printed telling how many matching requests are found. If the request is already running, it is not moved and a message is printed. EXAMPLES To move from every queue, to queue 1, in the default request_type an requests where the last component of the pathname matches "list", type mdr -et *.list -tq 1 -all Daemon request mydir.list moved from queue 2 to queue 1. Daemon request myseg.list moved from queue 3 to queue 1. 3-589 AG92-Q6 Name: move_dir, mvd SYNT AX AS A COMMAND FUNCTION moves a directory and its subtree, including all of the associated attributes. to another poin t in the hierarchy. ARGUMENTS source_dir is the pathname of the directory to be moved. The star convention is allowed to match directory names. Matching names associated with other storage types are ignored. The source_dir cannot be contained in target_dir. target_dir is the new pathname for source_dir. If the entryname is different from one already on source_dir, it is added to the existing names. If target_dir is not specified, source_dir is moved to the working directory and given the same entryname. The equal convention is allowed. CONTROL ARGUMENTS -brief. -bf suppresses the printing of warning messages such as "Bit count inconsistent with current length" and "Current length is not the same as records used tt • -force continues execution when target_dir already exists. without asking you. don't supply -force. you are queried. If you -replace, -rp deletes the contents of target_dir existing before the copying begins. If target_dir is non-existent or empty, this control argument has no effect The default is to append the contents of the source directory to the target directory if it already exists. LIST OF ENTRY TYPE KEYS - - These keys control what type of storage system entry is moved. The default is to move all entries. The keys are -branch, -br -directory, -dr -file, -f -link, -lk -multisegment_file, -msf 3-590 AG92-06 -non_null_link, -nnlk -segment, -srn If one or more entry_type_keys are specified, but not the -directory key, the subtree of source_dir will not be followed. ACCESS REQUIRED Status and modify permission are required for source_dir and all of the directories in its tree, and its containing directory_ If target_dir does not exist, append permission is required for its containing directory. If it does exist, modify and append permission for target_dir are required. This command does not force access. The access control list associated with source_dir is moved to target_dire NOTES If target_dir is contained in source_dir, an appropriate error message is printoo and control is returned to command level. If name duplication occurs while appending the source_dir to the target_dir and the name duplication occurs between directories, you are queried whether processing should continue. If you answer yes. the contents of the directory are moved (appended) to target_dirt but none of the attributes of that directory are moved. If the answer is no, the directory and its subtree is skipped. If name duplication should occur between segments, you are asked whether to delete the existing one in target_dire (See the ft\nv"," ......... , , " . . . . ,."nUTI!H,ti \ ...,,,......... .I..L ... ..... , ~ Links are translated; that is, if there are references to a source directory in a link pathname, the link pathname is changed to refer to the target directory. If part of the tree is not moved, problems with link translation may occur. If the target of the link in the source_dir tree was in the part of the tree not moved, there may be no corresponding entry in the target_dir tree. Hence, translation of the link (presumably originally nonnull) win cause the link to become nuli. See also the copy. move. and copy_dir commands. EXAMPLES If the working directory is >udd>Project>Smi th, the command line mvd source_dir new>target_dir -rp moves the directory named >udd>Proj ect>Sm i th>source_d i r and its subtree to >udd>Proj ect>Sm i th>new>target_d i r replacing its contents with the contents of source_dire 3-591 AG92-()6 Name: move_names SYNTAX AS A COMMAND FUNCTION moves all the names but the one used to designate the entry from one entry (directory, segment, multisegment file, data management file, extended entry, or link) to another. To copy the alternate names, see copy_names. ARGUMENTS from_pathi is the pathname of the entry whose names are to be moved. The star convention is not allowed. to_pathi is the pathname of the entry to which names on from_pathi are to be moved. The equal convention is allowed. If you omit the last to_path, the entry with the same name as from_path in your working directory is assumed. Name: move_output_request, mor SYNTAX AS A COMMAND mor request_identifiers {-control_args} FUNCTION moves a request from one I/O daemon queue to another. The move can be within the same request type or from one request type to another. The request is always placed at the end of the target queue. ARGUMENTS request_iden tifiers can be chosen from the following: path identifies a request to be moved by the full or relative pathname of the input data segment The star convention is allowed. -entry STR, -et SIR identifies a request to be moved by SIR, the entryname portion of the input data segment pathname. The star convention is allowed. 3-592 AG92-06 -id ID identifies one or more requests to be moved by request identifier. This identifier may be used to further define any path or -entry identifier (see "Notes"). CONTROL ARGUMENTS -all, -a searches all queues for the requests to be moved. The target queue is not searched by -all if the source and target request types are identical. This control argument is incompatible with -queue. --brief, -bf suppresses messages telling the user that a particular request identifier was not found or that requests were moved when using star names or the -all control argument -queue N, -q N specifies that queue N for the given request type contains the request to be moved, where N is an integer specifying the number for the queue. If you omit -queue, all the queues are searched. -print. -pr specifies that the request moved is found in the queue(s) associated with the default printer request type (see "Notes"). -punch, -pch specifies that the request moved is found in the queue(s) associated with the default punch request type (see "Notes"). -plot specifies that the request moved is found in the queue(s) associated with the default plotter request type (see "Notes"). -request_type STR. -rqt STR specifies that the request moved is found in the queue(s) f or the request type identified by STR. Use the print_request_types command to list request types. (See "Notes. ") -to_queue N, -tq N specifies which queue to move the request to. If not given. the default queue of the target request type is used. -to_request_type STR. -to_rqt STR specifies that the request should be moved to request type STR. If you don't give -to_request_type, the original request type is used. The target request types must be of the same generic type as the original request type. -user User_id specifies the name of the submitter of the requests to be moved. The User_id 3-593 AG92-()6 can be Person_id.Project_id. Person_id, or .Project_id. This control argument is primarily for the operator and administrators. Both rand d extended access to the queue are required. This control argument causes the command to use privileged message segment primitives that preserve the original identity of the submitter. If the process has access isolation mechanism (AIM) ring 1 privilege, the AIM attributes of the original submitter are preserved; otherwise the AIM attributes of the current process are used. (Default: to move only requests entered by the user executing the command) ACCESS REQUIRED You must have 0 extended access to the queue from which the request is being taken and a access to the queue to which the request is being moved. You must have rand d extended access to move a request owned by another user (see -user). NOTES The control arguments -print, -punch, -plot. and -request_type are mutually exclusive. If you use none, the default request type for enter_output_request -print (as displayed by print_request_types) is assumed. If you supply any path or -entry STR request identifiers. only one -id ID request identifier are accepted and it must match any requests selected by path or entryname. You can specify multiple -id ID identifiers in a single command invocation only if you give no path or entry request identifiers. When you use no star names and a single request identifier matches more than one request in the queue(s) searched, none of the requests are moved. However, a message is printed telling how many matching requests are found. If the request is already running. it is not moved and a message is printed. See the Programmer's Reference Manual for a description of request identifiers. Name: move_quota, mq SYNTAX AS A COMMAND mq pathl quota_changel ••• {pathN quota_changeN} FUNCTION allows you to move records of quota between two directories, one immediately inferior to (contained in) the other. 3-594 AG92-06 ARGUMENTS pathi is the pathname of a directory. The quota change. occurs between this branch and its containing directory. A pathi of -workinLdirectory (-wd) specifies your working directory. You can't use the star convention. quota_changei is the numbers of (containing) directory positive or negative. directory to pathi; if records to be moved between the immediately superior quota and the pathi quota. This argument can be either If it is positive, the quota is moved from the containing negative, the move is from pathi to the containing directory. ACCESS REQUIRED You must have modify permission on both directories. NOTES After the change, the quota on pathi must be greater than or equal to the number of records used in pathi unless the change makes the quota zero. If the change makes the quota on pathi zero, there must be no immediately inferior directory with nonzero quota and the records used and the rec.ord-time product for pathi are reflected up to the superior directory. If pathi is an upgraded directory (its access class is greater than the one of its containing directory), quota_changei must be positive. You can move quota back to the containing directory of an upgiaded directory only by deleting the latter. You can't move quota between a master directory and its containing directory. EXAMPLES The command line mq >udd>m>WShakespeare>subi_dir ieee adds 1000 records to the quota on >udd>m>WShakespeare>subl_dir and subtracts 1000 records from the quota on >udd>m>WShakespeare. The command line mq >udd>m>JJoyce>subl_dir>sub2_dir -50 subtracts 50 records from the quota on >udd>m>JJoyce>sub1_dir>sub2_dir and adds 50 records to the quota on >udd>m>JJoyce>subl_dir. 3-595 AG92-06 msfs msfs Name: msfs SYNTAX AS A COMMAND msfs star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [msfs star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of multisegment files (MSFs) that match one or more star names. ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per MSF is returned; i.e., if a MSF has more than one name that matches star_name, only the first match found is returned. Since each entryname (or pathname) returned by msfs is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. 11/86 3-596 AG92-06A SYNTAX AS A COMMAND mtape_delete_defaults OPN {-control_args} FUNCTION deletes default arguments set by the mtape_set_defaults command. It deletes the default arguments, from a specified value segment, that are associated with a given volume type and tape-processing operation. ARGUMENTS OPN is the type of tape operation (attach, open, close, or detach) that uses the default arguments. CONTROL ARGUMENTS -pathname path, -pn path specifies the pathname of a value segment to be searched for default arguments. If you omit it, the value segment >udd> [user project] > [user name] > [user name] .value is used. -volume_type VI, -vt VI specifies the volume type (ansi or ibm) used by mtape_ to select the per-format module for tape processing. Give -vt when you supply either the open or close operations; emit it when yeu supply either the attach or detach operations. EXAMPLES Suppose you want to delete all defaults in the value segment >udd> [user project> [user name] > [user name] .value that apply to the close operation for ANSI tapes: mtape_delete_defaults close -vt ansi Now you want to delete all the defaults in the value segment >udd>m>slk>defaults. value that pertain to the detach operation: mtape_delete_defaults detach -pn >udd>m>slk>defaults.value In this case you must give the pathname. The volume type is not given bP...cause attach and detach are general operations that are applicable to all volume types, 11/86 3-597 AG92-06A Name: mtape~et_defaults SYNTAX AS A COMMAND FUNCTION prints default arguments set by the mtape_set_defaults command. It prints the default arguments, stored in a specified value segment, that are associated with a given volume type and tape-processing operation. ARGUMENTS OPN is the type of tape operation (attach, open, close, or detach) that uses the default arguments. CONTROL ARGUMENTS -pathname path, -pn path specifies the pathname of a value segment to be searched for default arguments. It is incompatible with -usl. -use_search_list, -usl specifies that each value segment in the mtape_arguments search list is to be searched for default arguments and that the final default linear form that the mtape_ argument-processing subroutine uses is to be printed. (Defauit) -volume_type VI, -vt VT specifies the volume type (ansi or ibm) used by mtape_ to select the per-format module for tape processing. Give -vt when you use either the open or close operations; omit it when you use either the attach or detach operations. EXAMPLES Suppose you want to print out the final form of all defaults that affect the open operation for IBM tapes, then mtape_get_defaults open -vt ibm -us1 prints out the default linear form associated with the open operation for IBM tapes. If you. then want to print out the defaults found in a particular value segment that for IBM tapes, the value segment being affect the open operation >udd>m>slk>defaults. value, type: mtape_get_defaults open -vt ibm -pn >udd>m>s1k>defaults.value 11/86 3-598 AG92-06A Now you want to piint out the defaults contained in the value segment >udd> [user project] > [user name] > [user name] .value that affect all tape attachments: mtape_get_defaults attach -pn >udd>[user project]>[user name]>[user name].value The volume type is not given because attach and detach are general operations that are applicable to all volume types. You must specify the pathname because the default operation is -usl. Finally, if you want to scan all the value segments in your mtape_arguments search list for default arguments associated with the detach option, type: mtape_get_defaults detach -pn ([psp mtape_args]) Since the print_search_paths active function returns ali pathnames in the search list, the default arguments associated with the detach operation in each value segment in the mtape_arguments search list are printed. SYNTAX AS A COMMAND FUNCTION sets default arguments used by the mtape_ I/O module. ARGUMENTS OPN is tb.e type of tape operation (attach, open, close, or detach) that uses the default arguments. CONTROL ARGUMENTS -arguments ARGS, -argument, -ag ARGS are the arguments appropriate to the specified operation and tape formal They must be syntactically correct and appropriate to the conditions under which they are applied. (Required; it must be the last one specified on the command line) -pathname path, -pn path is the name of the value segment in which the requested default values are stored. If you omit it, the value segment >udd> [user project] > [user name] > [user name] .value is used. 11/86 3-599 AG92-06A -volume_type VT, -vt VT specifies the volume type (ansi or ibm) used by mtape_ to select the per-format module for tape processing. Give -vt when you specify either the open or close operations; omit it when you supply either the attach or detach operations. This control argument, along with -operation, defines restrictions on the specification of the default arguments (see the mtape_ I/O module in the Subroutines manuaI). NOTES The command sets the default arguments associated with a given volume type and tape-processing operation. These default arguments are eventually used to complete attach, open, close, and detach descriptions when you have not explicitly supplied all the necessary information. The default arguments specified in the command line are processed by the mtape_ argument-processing subroutine to assure that they follow all the restrictions imposed by their intended future usage. The result of this processing is then converted to a character string and is stored in the data space of a specified value segment The stored value is later located and used as default information for argument processing when tapes are being processed by the mtape_ I/O module (see the Programmer's Reference Manual for tape processing). NOTES ON USING DEFAULT ARGUMENTS When it is necessary to use default arguments in a particular application, they are located by the mtape_ argument-processing routine using the mtape_arguments search list The default mtape~arguments (mtape_args) search list, is as follows: mtape_arguments mtape args >udd>[user project]>[user name]>[user name].value >site>mtape_orguments.value >sss>mtape_arguments.value You can add or delete search paths as necessary using the search paths commands. In locating default arguments, the mtape_ argument-processing routine looks in every value segment in the search list and takes the appropriate default arguments from each (if it finds them). Whether a group of default arguments is determined to be appropriate for an application depends on the volume type and tape-processing operation for which is intended. Default arguments from value segments at the top of the search list take precedence over those from value segments at the bottom. Equivalently arguments on the right side of an argument list take precedence over arguments on the left This means that after all default arguments for a particular application have been gathered from the search list, if an argument occurs more than once, the argument with the highest precedence is retained and the others are excluded. The result is called the default linear form. 11/86 3-600 AG92-06A nequal EXAMPLES Suppose you want to set some defaults (using mtape-> for attaching tapes: mtape_set_defaults attach -ag -track 9 -density 6250 -ring -display Assuming that you have retained the default mtape_arguments search paths (as described above), these default arguments have the highest level of precedence for the attach operation. Now suppose that the >site and >sss mtape_arguments. value segments contain defaults for the attach operation as follows: >site contains "-density 800 -track 7 -no_ring" >sss contains "-density 1600 -track 9 -no_system -no_ring" Using the precedence rules, the default linear form that results is -no_system -track 9 -density 6250 -ring -display The control argument -no_ring does not appear in the linear form because it has been excluded by -ring. If you specify the following mtape_ attach description: mtape_ volume_name -vt ansi the default linear form is used intact (as previously specified). You can, however, override anything in the default linear form by respecifying it in the attach description. For example, if you want to override the default density of 6250 with a density of 1600~ you specify it in the attach description this way: mtape_ volume_name -vt ansi -density 1600 Arguments actually specified by you in an attach, open, close, or detach description always override those in the default linear form. Name: nequal SYNTAX AS A COMMAND nequal numA numB SYNTAX AS AN ACTIVE FUNCTION [nequal numA numB] FUNCTION returns true if numA is numerically equal to numB, false otherwise. 11/86 3-601 AG92-06A nequal EXAMPLES string [nequal 5 5.0] true string [nequal 001 1] true string [nequal one 1] Error Name: network_request, nr SYNTAX AS A COMMAND FUNCTION allows you to interactively transfer files to or from a DPS 6 X.25 Satellite. ARGUMENTS source_path specifies the source file to be used for the transfer: {-name} file_name {-at net_address} • Precede file_name by -name (-nm) if it begins with a hyphen, enclose it in quotes if it contains spaces or special characters, and follow it by "-at net_address" if the file does not reside on the local host Supply the file name in a syntax acceptable to the host on which the file resides. The net_address consists of the address of the DPS 6 on the X.25 connection (as specified in the DPS 6 CLM_USER file) followed by the end-task-ID of the DPS 6 Listener (as specified in the DPS 6 eLM file) in the X.25 directive. If the file resides on Multics, you can use an arbitrary star name; if it resides on a DPS 6, you can give the name n • • " to transfer all the files in a directory on the Level 6. destination_path specifies the destination file to be used for the transfer: {-name} file_name {-at net_address} It has the same syntax and restrictions as source_path. You can use the equal convention. 11/86 3-602 AG92-06A network_request CONTROL ARGUMENTS -attended. -att specifies that the DPS 6 already has a server running and no login dialogue is needed. -brief. -bf does not print messages as the command executes. -data_type ascii -data_type binary -data_type bed specifies the data type of the Multics file. If binary. then the Multics file must be sequential or blocked; it can not be unstructured. (Default: ascii) -long, -lg prints a message when the transfer starts and when it is finished, giving the pathnames. records transfered, etc. (Default) -network_name channel_name, -net channel_name specifies the channel name of the X.25 channel (i.e., the network "name") to be used for the transfer. (Required) -not_attended. -natt specifies that a login dialogue is needed with the DPS 6 to initiate the transfer. (Default) -password STR, -pw STR specifies the password used by the remote host to authenticate the file transfer. If the remote host requires a password and none is given. you are prompted for one with a mask. (Default none) -user STR STR specifies the user wishing the transf er. This can be used by the remote host for authentication of the file transfer. (Default: the Multics User_id of the user who submitted the request) ACCESS REQUIRED You must have the "dialok" attribute and have rw access to the X.25 channel specified by -nel NOTES Either the source file or the destination file must be on the local host (i.e.. both must not use the -at argument); thus third-party transfers are not allowed. 3-603 . AG92-()6 network_request EXAMPLES where mult_file is the source on Multics. 16_file is the destination file on the DPS 6, and the connection between the DPS 6 and Multics is on channel g.hl02. This example transfers mult_file to 16_file. SYNTAX AS A COMMAND FUNCTION destroys your current process and creates a new one, using the control arguments given initially with login and -authorization. CONTROL ARGUMENTS -authorization STR, -auth STR creates the new process at authorization STR, where STR is any authorization acceptable to the convert_authorization_ subroutine. The authorization must be less than. or equal to, both the maximum authorization of the process and the access class of the terminal. (Default to create the new process at the same authorization) NOTES Just before the old process is destroyed, the "finish" condition is signaled. After the default on unit returns, all open files are closed. The search rules, I/O attachments, and working directory for the new process are as if you had just logged in. If your initiai working directory contains the segment start_up.ec and you did not log in with -no_start_up. new _proc automatically issues the command line "exec_com start_up new_proc interactive" in the new process. If your site is security conscious, it may have disabled "new_proc -auth"; in this case if you wish to change authorization, do this: 1. log out 2. verify, using terminal/modem indications. that the terminal has dropped DTR and that the system acknowledged by dropping DSR 3. log in at the new authorization. 3-604 AG92-06 nless This procedure is the only way to guarantee that you are communicating with the answering service and not with a Trojan horse. DTR and DSR are EIA RS232 control signals that are part of the interface between your terminal and the system. Name: ngreater SYNTAX AS A COMMAND ngreater numA numB SYNTAX AS AN ACTiVE FUNCTiON [ngreater numA numB] FUNCTION returns true if numA is numerically greater than numB, false otherwise. EXAMPLES string [ngreater 5 8] false string [ngreater 9 4] true Name: nless SYNTAX AS A COIl//MAND nless numA numB SYNTAX AS AN ACTIVE FUNCTION [nless numA numB] FUNCTION returns true if numA is numerically less than numB; otherwise it returns false. 3-605 AG92-06 nonbranches nless EXAMPLES string [nless 8 4] false string [nless 4 8] true string [nless -5 -3] true SYNTAX AS A COMMAND FUNCTION disables process preservation across hangups in your process, causing the process to log itself out automatically if its terminal channel hangs up. NOTES This command is meaningful only if process preservation was in effect for the process at login time, either by default or because you gave -save_on_disconnect on the login command line. Name: nonbranches SYNTAX AS A COMMAND nonbranches star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [nonbranches star_names {-control args}] FUlvCTION returns the entrynames or absolute pathnames of nonbranches that match one or more star names. ARGUMENTS star_names is a star name to be used in selecting the names to be returned. 11/86 3-606 AG92-06A nonbranches nondirectories CONTROL ARGUMENTS .-absolute_pathname, -absp returns absolute patbnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per nonbranch is returned; i.e., if a nonbranch has more than one name that matches star_name, only the first match found is returned. Since each entryname (or pathname) returned by nonbranches is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: nondirectories, nondirs SYNTAX AS A COMMAND nondirs star_names {-control~args} SYNTAX AS AN ACTIVE FUNCTION [nondirs star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of segments, multisegment files (MSFs), and links that match one or more star names. 11/86 3-607 AG92-06A nondirectories nonfiles ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error. -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per entry is returned; i.e., if a segment, MSF, or link has more than one name that matches star_name, only the first match found is returned. Since each entryname (or pathname) returned by nondirectories is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: nonfiles SYNTAX AS A COMMAND nonfiles star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [nonfiles star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of directories and links that match one or more star names. 11/86 3-608 AG92-06A non links nonfiles ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, =absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per entry is returned; i.e.• if a directory or link has more than one name that matches star_na...'lle, only the first match found is returned. Since each entryname (or pathname) returned by nonfiles is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: nonlinks SYNTAX AS A COMMAND nonlinks star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [nonlinks star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of segments, directories. and multisegment files (MSFs) that match one or more star names. 11/86 3-609 AG92-06A nonlinks nonmaster_directories ARGUMENTS star_name is a star name to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. (Default: to return entrynames) -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per nonlink is returned; i.e.. if a nonlink has more than one name that matches star_name. only the first match found is returned. Since each entryname (or pathname) returned by nonlinks is enclosed in quotes. the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: nonmaster_directories, nmdirs SYNTAX AS A COMMAND nmdirs star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [nmdirs star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of directories that are not master directories that match one or more star names. 11/86 3-610 AG92-06A nonmsfs nonmaster_directories ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absoiute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a stamame. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per directory is returned; i.e., if a directory has more than one name that matches sLar_name, only the first match found is returned. Since each entryname (or pathname) returned by nonmaster_directories is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: nonmsfs SYNTAX AS A COMMAND nonmsfs star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [nonmsfs star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of segments, directories, and links that match one or more star names. 11/86 3-611 AG92-06A nonmsfs ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absoiute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per entry is returned; Le~i if a segment, directory; or link has more than one name that matches star_name, only the first match found is returned. Since each entryname (or pathname) returned by nonmsfs is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: nonnull_links, nnlinks SYNTAX AS A COMMAND nnlinks star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [nnlinks star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of links for which the target entry exists that match one or more star names. 11/86 3-612 AG92-06A ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL .ARGUMENTS -absolute_pathname. -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error. -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per link is returned; i.e.. if a link has more than one name that matches star~name! only the first match found is returned. Since each entryname (or pathname) returned by nnlinks is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: non object_files, nobfiles SYNTAX AS A COMMAND nobfiles star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [nobfiles star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of files that are not executable object files and that match one or more star names. 11/86 3-613 AG92-06A ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per iiie is returned; i.e., ii a HIe has more than one name that matches star_name, only the first match found is returned. Since each entryname (or pathname) returned by nobfiles is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Segments and MSFs that you do not have at least r access to are ignored, since r access is needed to determine if the file is an object file. Name: nonobject_msfs, nobmsfs SYNT AX AS A COMMAND nobmsfs star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [nobmsfs star names {-control_args}] 11/86 3-614 AG92-06A FUNCTION returns the entrynames or absolute pathnames of multisegment files (MSFs) that are not object MSFs and that match one or more star names. ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid nanle or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per msf is returned; i.e., if an MSF has more than one name that matches star_name. only the first match found is returned. Since each entryname (or pathname) returned by nobmsfs is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. MSFs that you do not have at least r access to are ignored, since r access is needed to determine if the file is an object MSF. 11/86 3-615 AG92-06A nonobject_segments nonobject_segments Name: nonobject_segments, nobsegs SYNTAX AS A COMMAND nobsegs star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [nobsegs star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of segments that are not executable object segments, and that match one or more star names. ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entrts existence is lacking. (Default) ACCESS REQUIRED You need at least r access to the segments. NOTES Only one name per segment is returned; i.e., if a segment has more than one name that matches star_name, only the first match found is returned. 11/86 3-616 AG92-06A nonsegmen ts non object_segments Since each entryname (or pathname) returned by nobsegs is enclosea In quoies, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: nonsegments nonsegs j SYNTAX AS A COMMA,VD nonsegs star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [nonsegs star_names {-controi_args}] FUNCTION returns the entrynames or absolute pathnames of directories, multisegment files (MSFs), or links that match one or more star names. ARGUMENTS star_names are star names to be used in selecting the names 10 be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a stamame. =inhibit_error, -ihe returns false if star name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per entry is returned; i.e., if a directory, MSF, or link has more than one name that matches star_name, only the first match found is returned. 11/86 3-616.1 AG92-06A nonsegments Since each entryname (or pathname) returned by nonsegs is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: nonzero_files, nzfiles SYNTAX AS A COMMAND nzfiles star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [nzfiles star_names {-control_arg}s] FUNCTION returns the entrynames or absolute pathnames of files--segments and multisegment files (MSFs)-with a nonzero-bit count that match one or more star names. ARGUMENTS staT_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per file is returned; i.e., if a file has more than one name that matches star_name, only the first match found is returned. 11/86 3-616.2 AG92-06A Since each entryname (or pathname) returned by nzfiles is enclosed in quotes! the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: nonzero_msfs, nzmsfs SYNTAX AS A COMMAND nzmsfs star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [nzmsfs star_names {-control args}] FUNCTION returns the entrynames or absolute pathnames of multisegment files (MSFs) with a nonzero-bit count that match one or more star names. ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -nc_inhibit_error. -nme signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per MSF is returned; i.e., if a MSF has more than one name that matches star_name, only the first match found is returned. 11/86 3-616.3 AG92-06A nonzero_segments Since each entryname (or pathname) returned by nzmsfs is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: nonzero_segments, nzsegs SYNTAX AS A COMMAND nzsegs star_names .{-control_args} SYNTAX AS AN ACTIVE FUNCTION [nzsegs star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of segments with a nonzero-bit count that match one or more star names. ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starnarne. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per segment is returned; i.e., if a segment has more than one name that matches star_name, only the first match found is returned. 11/86 3-616.4 AG92-06A nothing nonzero_segments ~mce each entryname (or pathname) returnee by nzsegs is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Name: not SYNTAX AS A COMMAND not STR SYNTAX AS AN ACTIVE FUNCTION [not STR] FUNCTION returns false if STR is equal to true; true if STR is equal to false; otherwise prints an error message. Name: nothing, nt SYNTAX AS A COMMAND nt {optional_args} FUNCTION performs a return to its caller and does nothing. ARGU}IIEftlTS optional_args are optional arguments, which can have any value and are ignored. NOTES This command uses a special feature in the Multics linking mechanism that allows it to be executed by any reference name; thus you can use it as a "stub" procedure for testing the development of programs. To do this, initiate it with the reference name of the program it is supposed to replace. You can't use it in this fashion if the entrypoint name is different from the reference name. 11/86 3-616.5 AG92-()6A Name: null_links, nlinks SYNTAX AS A COMMAND nlinks star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [nlinks star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of links for which the target does not exist that match one or more star names. ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a stamame. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per link is returned; i.e., if a link has more than one name that matches star_name, only the first match if returned. Since each entryname (or pathname) returned by nlinks is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. 11/86 3-616.6 AG92-06A Name: object_files, obfiles SYNTAX AS A COMMAND obfiles star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [obfiles star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of files that are executable object files and that match one or more star names. ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error. -ihe returns false if star name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error. -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Def aul t) NOTES Only one name per file is returned; i.e., if a file has more than one name that matches star_name, only the first match found is returned. Since each entryname (or pathname) returned by obfiles is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. Files that you do not have at least r access to are ignored, since r access is needed to determine if the file is an object file. 11/86 3-616.7 AG92-D6A Name: object_msfs, obmsfs SYNT AX AS A COMMAND obmsfs star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [obmsfs star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of multisegment files (MSFs) that are executable object MSFs and that match one or more star names. ARGUMENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase proces...~ the targets of links when you specify a starname~ -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error, -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) NOTES Only one name per MSF is returned; i.e.. if a MSF has more than one name that matches star_name, only the first match found is returned. Since each entryname (or pathname) returned by obmsfs is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of spe.cial characters in the name. MSFs that you do not have at least r access to are ignored, since r access is needed to determine if the file is an object MSF. 11/86 3-616.8 AG92-06A Name: object_segments, osegs SYNTAX AS A COMMAND osegs star_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [osegs star_names {-control_args}] FUNCTION returns the entrynames or absolute pathnames of segments that are executable object segments and that match one or more star names. ARGUtv'! ENTS star_names are star names to be used in selecting the names to be returned. CONTROL ARGUMENTS -absolute_pathname, -absp returns absolute pathnames rather than entrynames. -chase processes the targets of links when you specify a starname. -inhibit_error, -ihe returns false if star_name is an invalid name or if access to tell of an entry's existence is lacking. -no_chase does not process the targets of links when you specify a starname. (Default) -no_inhibit_error. -nihe signals an error if star_name is an invalid name or if access to tell of an entry's existence is lacking. (Default) ACCESS REQUIRED You need at least r access to the object segments. NOTES Only one name per segment is returned; i.e., if a segment has more than one name that matches star_name, only the first match found is returned. Since each entryname (or pathname) returned by osegs is enclosed in quotes, the command processor treats each name as a single argument regardless of the presence of special characters in the name. 11/86 3-616.9 AG92-06A octal on Name: octal, oct SYNTAX AS A COMMAND oct values SYNTAX AS AN ACTIVE FUNCTION [oct values] FUNCTION returns one or more values in octal. ARGUMENTS value is a value to be processed. NOTES The last character of the value indicates its type. Acceptable types are binary (b), quaternary (q), octal (0), hexadecimal (x), or unspec (u). Any valid PL/I real value is allowed. The absence of any specifier means decimal. The unspec value is limited to eigh t characters. EXAMPLES string [octal 1024] 2000 string [octal abcu] 141142143 Name: on SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION 11/86 3-616.10 AG92-06A on on FUNCTION establishes a handler for a specified set of conditions. executes an embedded command line with this handler in effect, and then reverts the handler. The handler is another embedded command line to be executed if the condition is signaled. ARGUMENTS conditions is a list of condition names separated by commas to be trapped by the command. handler_corn_line is the command line to be executed when one of the conditions contained in the list of condition names is raised. If handler_corn_line contains spaces or other command language characters. enclose it in quotes. If no command is to be executed when a condition is raised. give handler_corn_line as "". subject_corn_line is the command line to be executed under the control of on; it consists of the remaining arguments. Quote it if it contains parentheses, brackets, quotes, or semicolons. CONTROL ARGUMENTS -brief. -bf suppresses the comment printed when a condition occurs. 11/86 3-616.11 AG92-06A This page intentionally left blank. 11/86 AG92-06A on on -cl establishes a new command level after the execution of handler_com_line. You cannot use it in the active function. The state of subject_corn_line is preserved. If you issue the start command, the same action is taken as would have -been had you not specified -cl. -exclude STR, -ex STR prevents on from trapping the conditions given in STR. If you list more than one condition, separate condition names by commas. This control argument is useful when handling the any_other condition. -long, -lg prints a detailed message describing the condition raised if one is available. This message is the same as the one printed by the reprint_error command. -restart, -rt continues execution of the subject_corn_line after execution of handler_corn_line or, if you also selected -cl, after execution of start It is incompatible with -retry_command_line. -retry_command_line, -rcl aborts and executes over again subject_corn_line after executing handler_corn_line. NOTES The default action after executing handler_corn_line is to abort the execution of subject_corn_line. If a condition is raised and trapped by on while executing the handler_corn_line, it is considered a recursive signal and the entire invocation is aborted. See the Programmer's Reference Manual for a list of standard system conditions. NOTES ON ACTIVE FUNCTION The active function returns "true" if any of the specified conditions are signaled during the execution of subject_corn_line, "false" otherwise. EXAMPLES The command line on command_error "pwd;ls" -bf ws node la does a walk_subtree starting at the node directory, listing the access of the working directory. If the list_ac1 (Ia) command fails because of insufficient access, for example, the pathname and contents of the working directory are printed and you are returned to command level since you didn't select -restart 3-617 ACT92-06 on or The command line on any_other -ex quit,program_interrupt,mme2 "ec dump" -lg myprog executes the myprog command. If any condition except quit, program_interrupt, and mrne2 is raised, on executes nec dump", after printing a detailed explanation of the condi tion raised. The command line on quit,mme2 db -bf -rt testcom executes the testcom command, but responds to quits and breaks set in testcom by invoking debug; -rt continues execution of testcom after you quit out of debug; and -bf suppresses a warning message when one of the specified conditions is signaled. In an exec_corn, the command line on linkage_error "ec linkerr" ec recurse calls a recursive entry point in the exec_com to continue execution, but with a linkage_error handler in effect. When linkage_error is signaled during the course of running recurse.ec, that exec_corn is aborted and linkerr.ec is run. The exec_com &if control line &if &[on command_er ror &then &quit 1111 -bf -r t command_name] executes the command command_name. If the command_error condition is raised, the exec_com being executed is terminated after compieting the execution of the command. The on command does not print any message in this example; restarting the command_error condition prints a message. Name: or SYNTAX AS A COMMAND SYNTAX AS AN ACTIVE FUNCTION [or {tf_args}] 3-618 AG92-06 overlay or FUNCTION returns true if any tf_arg is equal to true; otherwise it returns false. If there are no tf_args, it returns the or-identity "false". If any tf_arg has a value other than true or false, an error message is printed. ARGUMENTS tf_args are any active functions that return either "true" or "false". EXAMPLES The command line or [equal ([st -mode ([segs 1:*])]) rew] returns true if there is at least one segment in the working directory to which you have rew access. It returns false if there are no segments in the working directory. The active function [or [equa 1 (&r 1 &r 2 &r 3) tape 1JJ inside an exec_com returns true if either the first, second, or third argument to ec is "tapel". Name: overlay, ov SYNTAX AS A COMMAND ov paths {-control=args} FUNCTION reads several ASCII segments and writes the result of superimposing print positions from each segment on the user_output I/O switch output ARGUlv1ENTS paths are the pathnames of input segments. The archive convention is allowed. 3-619 AG92-()6 page_trace overlay CONTROL ARGUMENTS -indent N, -ind N indents the print positions of an input segment N columns on output. It only affects the path immediately preceding it If you don't give it, an indent of 0 is used. -page_length N, -pI N sets the page length of the output If you don't supply it, a page length of 60 is used. NOTES Because the overlay command uses the printer conversion programs, control characters are removed from input files except for newline (NL), backspace (BS), vertical tab (VT), and formfeed (FF). If identical print positions containing the same characters are superimposed, a boldface type results. By following input segments with -indent, you create output containing columns of text Name: page_trace, pgt SYNTAX AS A COMMAND pgt {N} {-control_args} FUNCTION prints a recent history of page faults and other system events within the calling process. ARGUMENTS N prints the last N system events (mostly page faults) recorded for the calling process. If you give no N, all the entries in the system trace list for the calling process are printed. Currently, there is room for approximately 300 entries in the system trace array. CONTROL ARGUMENTS -from STR, -fm STR searches the trace array for a user marker matching STR. If one is found, printing begins with it; otherwise, printing begins with the first element in the array. 3-620 AG92-06 -long, -lg prints full pathnames where appropriate. (Default: to print only entrynames) -no_header, -nhe suppresses the header that names each column. (Default: to print the header) -output_switch swname, -osw swname writes all output on the I/O switch named swname, which must already be attached and open for stream_output (Default: to write all output on the user_output I/O switch) -to STR stops printing if a user marker matching STR is found. If you specify both -from and -to. the "from" marker is assumed to occur before the "to" marker. (Default: to print until the end of the array) NOTES You can't give a count value (N) and either -from or -to in the same invocation. If you give -long. page_trace prints two lines of information for each page fault first indicates the page on which the fault occurred; the second. the location of instruction that caused the fault (i.e., the instruction that referenced the page in first line). This second line is printed only if the system administrator has enabled collection of this data. the the the the Since it is possible for segment numbers to be reused within a process and since only segment numbers (not entrynames or pathnames) are kept in the trace array, the entrynames and pathnames associated with a trace entry may be for previous uses of the segment numbers. not the latest ones. In fact. the entry and pathnames printed are the current ones appropriate for the given segment number. For completeness. events occurring while inside the supervisor are also listed in the trace. The interpretation of these events sometimes requires detailed knowledge of the system structure; in particular they may depend on activities of other users. For many purposes you will find it appropriate to identify the points at which the supervisor was entered and exited and ignore the events in between. Typically any single invocation of a program does not induce a page fault on every page touched by the program. since some pages may still be in primary memory from previous uses or used by another process. It may be necessary to obtain several traces to identify fully the extent of pages used. 3-621 AG92-06 pascal NOTES ON OUTPUT FORMAT The first column of output describes the type of trace entry; an empty column indicates that the entry is for a page fault. The second column is the real time, in milliseconds, since the previous entry's event occurred. The third (printed for page faults only) is the ring number in which the page fault occurred. The fourth contains the page number for entries, where appropriate. Tne fifth gives the segment number for entries, where appropriate. The last is the entryname (or pathname) of the segment for entries, where appropriate. Name: pascal, pas SYNTAX AS A COMMAND pas path {-control_args} FUNCTION invokes the Pascal compiler which compiles a source program written in Pascal and produces a Multics executable object segment. t ARGUMENTS path is the pathname of the source segment. The suffix .pascal is assumed. CONTROL ARGUMENTS -add_exportable_names, -aen adds names of exported variables and procedures to the object segment. -brief_map, -bfm produces a compilation listing containing source, error messages, and a statement map. -brief_table, -bftb generates a partial symbol table consisting of only a statement table that gives the correspondence between source line numbers and object locations for use by symbolic debuggers. The table appears in the symbol section of the object segment. This control argument does not significantly increase the size of the object segment -compilation_warnings, -cw prints compilation warnings for minor errors. (Default) 11/86 3-622 AG92-06A pascal pascal -conditional_execution VAR_NAME true/false, -cond VAR_NAME true/false forces the value of the conditional compilation variable VAR_NAME to either true or false. It overrides any assignments of V AR_NAME in the text of the program. -debug, -db generates code to check for references outside of array bounds, invalid assignments. values that are out of range, and a variety of other potential errors. Also initializes program storage to blanks (\040) so that a reference through an uninitialized pointer causes a fault_taLl condition. (Default) -english assumes that Pascal reserved words are in English. (Default) -error_messages, -em prints error messages on user_output and includes them in the listing segment (Default) cbn A -extended_character_code, -ecc extends internal code allowed for characters to 255 (decimal). -french accepts Pascal reserved words in French. Type "help pascal_french_keywords.gi" f or the correspondence between French and English reserved words. -full_extensions, -full uses an nonstandard extensions defined for ivlultics Pascal. (Default) -interactive, -int allows text files to operate in interactive mode. On reset or readln, "get" of next character is deferred until the next reference to the file or to one of the variables attached to the file, such as eof, eoln. and file A• (Default) -io_warnings, -iow allows warnings to be printed by I/O procedures called by the compiled program. (Default) -list produces a compilation listing including source. error messages, map and cross-reference of symbols, statement map, and generated code in symbolic ALM. -lonK-profile, -lpf generates additional code that records the virtual CPU time and number of page faults for each source statement It is incompatible with -pf. The profile command can handle both regular and long profiles. This feature adds considerable CPU overhead to heavily executed code. The extra CPU time is subtracted out so that it does not appear in the report printed by profile. 11/86 3-623 AG92-06A pascal pascal -map produces a compilation listing including source, error messages, map and cross-reference of symbols, and statement map. -no_compilation_warnings, -ncw does not print compilation warnings. -no_debug does not generate code to test for references outside of array bounds, values out of range, or other errors, and does not initialize storage to blanks. -no_error_messages, ':'nem does not print error messages on user_output. listing segment. They are still included in the -no_extended_character_code, -necc allows internal code range of 0.. 127 for characters, as required by the standard. (Default) -no_interactive, -nint does not allow text files to operate in interactive mode. -no_io_warnings, -niow does not print I/O warnings if a nonfatal error occurs in I/O procedures called by this program. -no_list does not produce a compilation listing. (Default) -no_lonLprofile, -nlpf does not generate additional code to record the virtual CPU time and number of page faults for each source segment. (Default) -no_private_storage, -nps dynamically allocates exported variables in external static. (Default) -no_profile, -npf does not generate code to meter the execution of source statements. (Default) -nonrelocatable, -nrlc generates an object segment that cannot be bound, thus saving from 10 to 20 percent of compilation time. -no_table, -ntb does not generate a symbol table in the object segment. -page_length N, -pI N specifies a page length for the listing segment (Default: 59 lines) 11/86 3-624 AG92-o6A pascal pascal -private_storage. -ps allocates all exported variables in a segment in the process directory named progname.defs, where progname is the entryname of the path argument. without the .pascal suffix. This segment is created if it does not exist -profile, -pf generates additional code to meter the execution of individual statements. Each statement in the object program contains an additional instruction to increment an internal counter associated with that statement. After a program has been executed, you can use the profile command to print the execution counts. -reference_table -rftb generates a full symbol table (see -table) and adds for each variable a table of statements where this variable is referenced or modified. This feature, used by pascal_cross_reference, is experimental. -relocatable, -rIc generates an object segment that can be bound. (Default) -sol_extensions, -sol allows only French SOL extensions to be used (type "help pascal_extensions.gi" for their lis!). -standard allows only standard (ISO) Pascal to be used. (Default: -full) -table, -tb generates a full symbol table for use by symbolic debuggers. The symbol table is part of the symbol section of the object segment and consists of two parts: a statement table that gives the correspondence between source line numbers and object locations, and an identifier table containing information about every identifier actually referenced by the source program. This control argument usually lengthens the object segment significantly. (Default) NOTES If compilation errors are encountered, error messages are printed on user_output. If you supply incompatible control arguments, the rightmost one is used. Multics Pascal is case insensitive. All identifier names are mapped to lowercase in the progranl and its symbol table. As a result, the Pascal program header program: Foo; produces a segment entry point with the name "foo." For information on Pascal see the Multics Pascal User's Guide (GB62). 11/86 3-625 AG92-06A pascal NOTES ON LISTING The Pascal compilation listing contains the following sections in this order: 1. Header: gives the full pathname of the source segment, the Multics site indentification, the date and time of compilation, and the compiler indentification. 2. Source: with lines numbered sequentially. precedes the line number. 3. Any error messages. 4. Storage requirements for the object segment 5. List of source files used. 6. Complete map and cross-reference for symbols declared and used, symbols declared and never used, and symbols declared by default 7. Displacement for fields given in octal (bytes). locations for variables given in octal (words), and sizes given in octal (bytes). 8. "DEF:" followed by the number of the line where the symbol is defined. "REF:" followed by the number of the line(s) where the symbol is referenced. An asterisk is printed for each reference where the variable or field is set or passed by reference ("var" parameter) to a subroutine. 9. Complete map and cross-reference of labels. "DEF:" is followed by number of the line where the label is defined "DeL:" is followed by number of the line where the label is declared. "REF:" is followed by number of the lines where the label is referenced in a GOTO statement asterisk is printed where the GOTO statement exits the current procedure. In include files, file number the the the An 10. Statement map: gives the octal location of the first instruction of each statement of the source program. SYNTAX AS A COMMAND pascal_area_status {names} {-control_args} FUNCTION displays and sets attributes of specified Pascal areas. 11/86 3-626 AG92-o6A ARGUMENTS names are relative pathnames of Pascal object segments that have their own private areas (see pascal_create_area). CONTROL ARGUMENTS -all, -a operates on all private Pascal areas as well as on the default Pascal area. -brief, -bf does not print a dump of each allocated block. (Default) -default specifies the default area used by Pascal to allocate storage. -dump prints a comprehensive, unformatted dump of the area(s). To be used by the maintainers of the Pascal compiler and related software. -long, -lg prints a dump of each allocated block. -no_dump does not print a comprehensive dump of the area(s). (Default) -no_status. -nst does not print status information. -no_trace does not print the address and length of each block. (Default) -status, -st prints the maximum size, the size occupied by allocated blocks, and the maximum possible size for a new allocation. -trace prints the address and length of each block and, if you give -lg. an octal dump of each block. NOTES The Pascal areas are temporary segments. Allocation is performed by the Pascal "new" statement, deallocation by the the "dispose" and "reset" statements. You can give names and control arguments in any order. 11/86 3-627 AG92-()6A If you specify no areas, -default is assumed. If you specify no actions, -st is assumed. If you specify more than one action, the operations are performed in this order: -st -dump -trace For information on Pascal see the Multics Pascal User's Guide (GB62). SYNTAX AS A COMMAND pascal_create_area names {-control_args} FUNCTION creates temporary, private areas in the process directory for the specified Pascal object segments. ARGUMENTS names are relative pathnames of Pascal object segments that are to have their own private areas. An error' occurs for each object segment for which a private area has already been created. CONTROL ARGUMENTS ~brief, ~bf suppresses the error message that is printed when the private area for a specified program already exists. -long, -lg allows the error message that is printed when the private area for a specified program already exists. (Default) -size N sets the maximum size of each area to N pages. (Default: 225 records) NOTES All Pascal "new" operations executed by the object segments use the associated private areas. By default, the new operation uses the default Pascal area in the process directory. You can examine this area, and any that are created, using pascal_area_status. 11/86 3-628 AG92-06A pascal_create_area For information on Pascal see the Multics Pascal User's Guide (GB62). SYNTAX AS A COMMAND pascal_cref pathnames {-control_args} FUNCTION examines a set of Pascal object segments that import variables a.lld procedures. ARGUMENTS pathnames are absolute or relative pathnames of Pascal object segments. been compiled with -table. They must have CONTROL ARGUMENTS -external_references, -ext_refs includes line numbers of statements where external (i.e., imported or exported) variables and procedures are referenced or set. The modules must have been compiled with -reference_table to include this information. -in ternal_ref erences, -int_ref s includes a list of internal variables or procedures and line numbers of statements where they are referenced or modified. The modules must have been compiled with -reference_table to include this information. -no_external_references, -no_ext_refs excludes line numbers of statements where external variables and procedures are referenced. (Default) -no_in ternal_ref erences. -no_int_refs excludes a list of internal variables and procedures. (Default) -output_file path, -of path produces a listing named path. x_map. If you use no .x_map suffix as part of the pathname, it is assumed. You must specify -of to get a cross-reference list including include files used and error reporting; otherwise the command writes any error or warning messages on error_output 11/86 3-629 AG92-06A NOTES The modules must have been compiled with -table. The cross-referencer checks declarations of shared variables and procedures, producing an error list of differences between modules. It also notes if the difference may have undesirable results, for exampie, destruction of data outside the program, such as may occur when sizes of shared objects do not match.' Warnings are printed if types do not match but object sizes do. Unlike the cross_reference command, pascal_cref includes no declarations of variables and procedures in the listing, nor does it compare types. It accepts no modules generated by other translators. SYNTAX AS A COMMAND pascal_delete_area names {-control_args} FUNCTION deletes the private areas associated with the specified Pascal object segments. information on Pascal see the Multics Pascal User's Guide (GB62). For ARGUMENTS na.rne5 are relative pathnames of Pascal object segments whose private areas are to be deleted. CONTROL ARGUMENTS -brief, -bf suppresses the message that is printed when a specified program is active on the Mul tics stack. -long. -lg allows the message that is printed when a specified program is active on the stack. (Default) 11/86 3-630 AG92-06A Name: pascal_display SYNTAX AS A COMMAND pascal_display {entry_names} FUNCTION traces the Multics stack and displays on user_output contents of variables declared in all procedures active in the stack. ARGUMENTS {entry_names} are Pascal entry names. If you give entry~names, only the variables of named procedures that are currently active are displayed; if you give no entry_names, variables of all active Pascal procedures are displayed. NOTES If you compile programs with -table, the contents of variables are symbolic and are displayed as they would be using the value request under probe. Without symbol tables, octal and ASCII dumps of the variables are provided. Dump location counters have the values of location counters available on the compilation listing. This command_is particularly useful with absentee executions. You can use it in an on condition, as follows: on pascal_error pascal_display program_name 11/86 3-631 AG92-06A pascal_display EXAMPLES PROGRAM test_display (input, output) TYPE charac8 = string (8) ptbox = ""'box ; box = RECORD name : charac8 value: real next : ptbox ; END ; VAR str first ptbox vf 1 : rea 1 ; charac8; PROCEDURE build (name charac8 val rea 1) VAR newbox : ptbox BEGIN new (newbox) ; newboxA.name := name; newboxA.value := val ; newboxA.next := first first := newbox ; END BEGIN first := NIL; WHILE true DO BEGIN str := I I ; wr i te (I name : I) ; readln (str) ; wr i te (I va 1ue : I) readln (vfl) ; build (str, vfl) ; END ; END. 11/86 3-632 AG92-06A pascal test_display Pascal 8.03 on pascal_error pascal_display -long test_display name: ?Blaise value: ?134 name : ?Deryl value: ?123.56 name : ?Amy value: ?xx on: Condition "pascal error" raised. pascal_io_$READ_text: Error during READ at line 6 of Pascal file input pascal error condition by >user=dir_dir>PASCAL>JMAthane>v803>info>test_diSPlayI133 (line 36) (actually by support procedure pascal io $READ text 17422 (line 2907) (>user_dir_dir>PASCAL>JMAthane>v8 0 3>e>bound_pascal_runtime_i 4350 6» input chain has a bad real format pascal_io_$READ_text: Error during READ at line 6 of Pascal file input Active procedures in the Multics stack are 234146600 command_processor_$command_processor_1 245 (bound_mu 1t i cS_bce_1245) (PL/ I) 234146120 abbrev$abbrev_processorI1307 (bound_command_loop_l10111) (PL/ I) 234 43540 on$handlerl1505 (bound_command_env_116331) (PL/I) 234 43200 signal_$signal_152 (bound_l ibrarY_1_175l2) (PL/I) 234 40320 pascal~io_$READ_textI6614 (bound_pascal_runtime_132700) (PL/ I) (1 i ne 2907) 234140140 test_display$test_displayI46 (PASCAL) (line 36) - main 23 4 1373 00 command_processor_$command_processor_1 245 (bound_mu 1t i cS_bce_1245) (PL/ I) 234136620 abbrev$abbrev_processor/1307 (bound_command_loop_110111) (PL/! ) 234136160 on$on 1220 (bound_command_env_115044) (PL/ I) 234 35320 command_processor_$command_processor_1 245 (bound_mu 1t i cS_bce_1245) (PL/ I) 234134640 abbrev$abbrev_processorI1307 (bound_command_loop_110111) (PL/ I) 23 4 13 4340 1 isten_$re~ease_stackI72 (bound_command_loop_!23444) (PL/I) 23 4 1337 40 get_to_cl_Sunc1aimed_signal 177 (bound_command_loop_1 25025) (PL/ I) 234131200 default_error_hand1er_$wa11 1377 (bound_error_handlers_1377) (PL/ I ) 234131100 in it i ali ze_process_$any_other. 21431 (bound_process_i n i t_1431) (PL/ I) 234130540 signal_$signal_152 (bound_l ibrary_l_17512) (PL/I) 234 27660 ipc_fast_$ipc_fast_$blockI12 (bound_ipc_154) (PL/I) 11/86 3-632.1 AG92-o6A 234126220 tty_io_$tty_io_$get_1ineI3202 (bound_command_loop_13202) (PL/I) 234 20060 aUdit_$audit_get_lineI5702 (b,ound_audit_ 157 02) (PL/I) 234 16500 tedut i 1_$ tedread_ptr _ 2041 (bound_ ted_16 7331) (PL/ I) 234 7400 ted_$ted_13177 (bound_ted_16425) (PL/I) 234 5660 ted_command_$ted 1543 (bo~~d_te~_J 1~33) ~PL/I). 234 5220 command_processor_$read_listi511b \bouna_multlcs_bce_15116) (PL/ I) 23414240 command_processor_$comp1ex_command_processorI1741 (bound_mu1 t i cS_bce_11740 (PL/ I) 23 4 13 400 command_processor_$command_processor_1 245 (bound_mu 1t i cS_bce_1245) (PL/ I) abbrev$abbrev_processorI1307 (bound_command_loop_110ll1) (PL/ I) 1 isten_$l isten_150 (bound_command_loo p_12 3422) (PL/I) initial ize_process_$initial ize_process_ 241 (bound_process_i n i t_1240 (PL/ I) 23 4 12700 23412400 234 2000 globals for >user_dir_dir>PASCAL>JMAthane>v803>info>test_display are str IIAmy" vfl = 123.56 first = 5221116 [pd]> BBBJQWPnghPmKg.temp.0522 input = - Multics io switch: syn_ user_input stream_input_output - Pascal file status: text file input interactive input"" IXI output := - Mu1tics io switch syn_ user_output stream_input_output - Pascal file status: text file output interactive eof output"" = I I I: I: item at 5221116 [pd]> BBBJQWPnghPmKg.temp.0522 (box) name "Deryl" value = 123.56 next = 5221102 [pd]> BBBJQWPnghPmKg.temp.0522 I: I: 11/86 3-632.2 AG92-06A item at 5221102 [pd]> BBBJQWPnghPmKg.temp.0522 (box) = name = "Blaise" value = 134. next = null SYNTAX AS A COMMAND FUNCTION displays information on the status of all standard Pascal files currently in use and all files of active Pascal procedures in the Multics stack. For information on Pascal see the Multics Pascal Users Guide (GB62). Name: pascal_indent SYNTAX AS A COMMAND FUNCTION indents a Pascal source program according to a standard set of conventions described below. For information on Pascal see the Multics Pascal User's Guide (GB62). ARGUMENTS old_path is the pathname of the source segment to be indented. The .pascal suffix is assumed. new_path is the optional pathname of the indented result. The .pascal suffix is assumed. If you omit new_path. the indented copy replaces the original segment. If errors are detected in the source, however, a temporary indented copy is created instead and its patbname is printed in an error message. 11/86 3-632.3 AG92-06A CONTROL ARGUMENTS -brief, -bf suppresses warning messages for invalid or non-Pascal characters found outside a string or comment. Errors corresponding to suppressed messages do not prevent the original source segment from being replaced. -comment N. -com N indents comments at column number N. Comments are lined up at this column unless they occur at the beginning of a line and are preceded by a blank line. (Default: column 61) -english assumes that the source program is written in English. (Default) -french assumes that the source program is written in French. -highlight, -hI translates reserved symbols of the Pascal language to lowercase if you provide -uc; to uppercase otherwise so that they stand out from the rest of the text -indent N, -in N indents each level an additional N spaces. (Default 5 spaces) -1 margin N, -1m N sets the left margin for top-level program statements after the Nth column. (Default: 10> -long, -lg allows warning messages for invalid or non-Pascal characters. (Default) -lower_case, -lc translates all uppercase letters outside of strings and comments to lowercase. no_case_translation, nct does not translate letters outside strings and comments to uppercase or lowercase. (Default) -no_highligh t, -nhl does not translate Pascal reserved symbols to lowercase or uppercase. (Default) -upper_case, -uc translates all lowercase letters outside of strings and comments to uppercase. 11/86 3-632.4 AG92-Q6A NOTES ON INDENTING STYLE Multiple spaces are replaced by single spaces. except inside strings and for nonleading spaces and tabs in comnlents. Trailing spaces and tabs are removed from all lines before indenting. Spaces are inserted before left parentheses. brackets, and braces, and removed after them. Spaces are inserted after right parentheses, brackets, and braces, and removed before them. Spaces are inserted around the constructs =. 1\=. <>, <=, >=. :=. ;, and : and operators in expressions. Parentheses, brackets, and braces must balance. The keywords "begin," "case," and "repeat" must balance with their corresponding "end" statements; likewise for "repeat" and "until" constructs. SYNTAX AS A COMMAND FUNCTION frees all blocks in the specified areas. For information on Pascal see the Multics Pascal User's Guide (GB62). ARGUMENTS names are relative pathnames of Pascal object segments that have their own private areas. If you supply no names, the default Pascal area is reset (See pascal_create_area.) CONTROL ARGUMENTS -size N sets the maximum size of each specified area to N records after resetting the area. (Default: 255 records) 11/86 3-632.5 AG92-06A path SYNTAX AS A COMMAND FUNCTION sets the prompt string used by Pascal programs in interactive mode. pascal_terminal_ion for a description of the interactive mode. Type "help ARGUMENTS string specifies the prompt string. CONTROL ARGUMENTS -no_prompt, -npmt prints nothing for a prompt NOTES If you provide no arguments. the default prompt "1" is restored. For information on Pascai see the Muitics Pascai User's Guide (GB62). Name: path SYNTAX AS A COMMAND path path {entry {component}} SYNTAX AS AN ACTIVE FUNCTION [path path {entry {component}}] FUNCTION returns the absolute pathname represented by the argument if you supply one argument; returns the absolute pathname of the archive component (if you give component) of the entry in the directory specified by path if you specify two or three arguments. 11/86 3-632.6 AG92-06A path pause ARGUMENTS path If you don't give entry, this is the pathname to be expanded and returned; otherwise it is the pathname of the directory to be used in the returned pathname. entry is the optional entryname to be used in the returned pathname. component is the optional archive component name to be used in the returned pathname. NOTES Since the pathname is returned in quotes, the command processor treats it as a single argument regardless of special characters in the name. EXAMPLES Assume that the user's working directory is >udd>Proj>Myname. path start_up.ec >udd>Proj>Myname>start_up.ec path >udd>Multics>Library>Source>bound_command_demos_.s::program.pll >udd>Mu 1t i cs>L i brary>Source>bound_command_demos_. s: :'program. p 11 path bound_expand_path_.s.archive >udd>Proj>s>bound_expand_path_.s.archive path [hd] my_exec_coms.archive start_up.ec >udd>Proj>Myname>my_exec_coms::start_up.ec Name: pause SYNTAX AS A COMMAND pause {t i me} FUNCTION interfaces the timer_manager_$sleep entry point, which allows the caller to "sleep" for a given number of seconds. 3-633 AG92-{)6 peruse_cros.sref pause ARGUMENTS time is the number of seconds (decimal integer) to sleep. If you specify no time. 10 seconds is used. Name: peruse_crossref, pcref SYNTAX AS A COMMAND pcref {cref_path} search_names {-control_args} SYNTAX AS AN ACTIVE FUNCTION [pcref {cref_path} search_names] FUNCTION prints or returns information extracted cross_ref erence command. from the output file generated by the ARGUMENTS cref_path is the pathname of the crossref output file to search. It can be a multisegment file (MSF). It must contain a > or < character to distinguish it from a search_name. If you supply no cref_path, the total system cross-reference (>ldd>crossref>totaLcrossref) is used. To specify a cross-reference in your working directory, use -pathname. search_names are one or more names to search f or ref erences to in the crossref. They can be either symbolic linker references or include file names and can have any of the following forms: segname segname$entryname XXX. i nc 1 • YYY Any component of a search name can be a star name, except that neither a segname nor an include file name can begin with a star name character and the string ".incl" must appear in toto. If you specify no entryname with the segname, all references to any entry points in the segment are listed. XXX.incl is accepted as an abbreviation for XXX.incl.*. Don't use > and < in a search name. 3-634 AG92-06 CONTROL ARGUMENTS -brief, -bf does riot print any information for selected cross-reference items that have no entries (callers). (Default) -brief_errors, -bfe suppreses any error messages due to entrypoints or include files that are not found in the crossref. -long, -lg print selected cross-reference items that have no entries. -lon~errors, -lge prints an error message if one or more entrypoints or include files given on the command line are not found in the crossref. (Default) -I I I -pathname crossref path, -pn crossref path specifies crossref path as the crossref to search. NOTES This command uses a Dlnary search to locate the desired information and thus is quite inexpensive, even when searching the total system crossref. Average cost for a single search of the system crossref is about 45 page faults and 0.5 CPU seconds, or roughly 30 times cheaper and far more convenient than using an editor. No attempt is made to combine the results of the search names--if you ask for something twice, it gets printed twice. This command does not perform any significant validation on the input filen and is likely to either take faults or signal the logic_error condition if asked to search something other than a crossref output file. There is no support f or synonyms: a search name must be the primary name of a segment and not a synonym established in a bindfile or the hardcore header. There is no way to select specific types of things, such as all the unresolvable ref erences in the crossref. EXAMPLES pcref pcref pcref phcs hphcs_S*acl >ldd>crossref>total.crossref stack_frame.incl OUTPUT EXAMPLE References to objects matching search names are displayed as follows: 3-635 AG92-()6 picture References to phcs_Srin&-O_peek: (STAND-AWNE in HARDCORE) as_meter_, copy_salvager_output, display_branch, namef_, ring_zero_peek_, sweep_pv, vpn_cv_uid_path_ If a matching object is not referenced by anything, it is identified as such. If a search name does not match anything found in the crossref, a diagnostic is displayed. The listing is a maximum of 72 characters wide. Name: picture, pic SYNTAX AS A COMMAND pic pic_string values {-control_arg} SYNTAX AS AN ACTIVE FUNCTION [pic pic_string values {-control_arg}] FUNCTION returns one or more values processed through a specified PL/I picture. ARGUMENTS pic_string is a valid PL/I picture as defined in the PL/I Reference Manual and the PL/I Language Specification. values are strings having data appropriate for editing into the picture. Each value must be convertible to the type implied by the picture specified. If multiple values are presented, the results are separated by single spaces. Any resulting value that contains a space is quoted. CONTROL ARGUMENTS -strip removes leading spaces from edited picture values; removes trailing zeros following a decimal point; removes a decimal point if it would have been the last character of a returned value. NOTES For more information on PL/I picture and picture strings. see the PL/ I Reference Manual (AM83) or the PL/ I Language Specification (AG94). 3-636 AG92-06 picture pll EXAMPLES create file_([pic 999 [index_set 8 14]]) 1 ist fi le_'" = 7, Lengths = Segments r r r r r r r w w w w w w w file_Ol4 fi1e_Ol3 file_Ol2 file_Oll file 010 file_009 f i 1e 008 ° °° °°° °° string [pic zzzzz9v.9999 000305.000] 305.0000 string [pic zzzzz9v.9999 000305.000 -strip] 305 Name: pll SYNTAX AS A COMMAND pI1 path {-control_args} FUNCTION invokes the PL/I compiler to translate a segment containing the text of a PL/I source program into a Multics object segment. You cannot call it recursively. ARGUMENTS path is the pathname of a PL/I source segment that is to be translated by the PL/I compiler. If path does not have a suffix of pU. one is assumed; it must be the last component of the source segment's name. CONTROL ARGUMENTS -brief. -bf produces error messages written onto the user_output I/O switch containing only an error number, a statement identification, and, when appropriate, the identifier or constantin error. 3-637 AG92-()6 pll pll -brief_table, -bftb generates a partial symbol table consisting of only a statement table that gives the correspondence between source line numbers and object locations for use by symbolic debuggers. The table appears in the symbol section of the object segment This control argument does not significantly increase the size of the object program. -check. -ck does a syntactic and semantic checking of a PL/I program. Only the first three phases of the compiler are executed. Code generation and the manipulation of the working segments used by the code generator are skipped. -check_ansi generates a severity 1 error message for each construct the compiler detects that is allowed by Multics PL/I but not by the ANSI standard X3.53-1976. -list. -Is produces a source program listing with symbols. followed by an assembly-like listing of the compiled object program. It significantly increases compilation time; avoid it whenever possible by using' -lnap. -long, -lg .produces error messages written onto the user_output I/O switch contaInIng an error number. statement identification, wh~n appropriate. the identifier or constant in error, an explanatory message of one or more sentences, and. in most cases. the text of the erroneous statement Onc.e a given error message is printed in the long form, all further instances of it are printed in the brief form. (Default) -Ions-profile, -lpf generates additional code that records the virtual CPU time and number of page faults for each source statement It is incompatible with -profile. The profile command can handle both regular and long profiles. Use of this feature adds considerable CPU overhead to heavily executed code. The extra CPU time is subtracted out, so that it does not appear in the report generated by profile. -map produces a source program listing with symbols, followed by a map of the object code generated by the compilation. It gives sufficient information to allow you to debug most problems online. -no_check, -nck generates an object segment (Default) -no_check_ansi does not generate an error message for Multics-dependent PL/I constructs. (Default) -no_list. -nls does not produce a listing segment (Default) 3-638 AG92-06 pll pll -no_optimize, -not does not invoke the extra compiler phase. (Default) -no_profile, -npf does not generate code to meter the execution of source statements. (Default) -no_separate_static. -nss places internal static variables in the linkage section of the object segment (Default) -no_table, -ntb does not generate a symbol table in the object segment (Default, if you supply -optimize) -optimize, -ot invokes an extra compiler phase just before code generation to perform certain optimizations, such as the removal of common subexpressions, which reduces the size and execution time of the object segment Use of this control argument adds 10 to 20 percent to the compilation time. -prefix SIR if STR is not nUll, compiles the program as if it were preceded by the condition prefix n(STR):". SIR is a list of one or more PL/I enabled or disabled computational condition names separated by commas and optional horizontal white space. Since the program is compiled as if "(STR):" was inserted before the first line of the source segment, -prefix does not override condition prefixes given in the source segment If STR is nUll, no additional condition prefix is used. The enabled computational condition names are: conversion (conv), fixedoverflow (fofI), overflow (ofl) , size, stringrange (strg) , stringsize (strz), subscriptrange (subrg), underflow (ufI) , and zerodivide (zdiv). The disabled computational condition names are: noconversion (noconv), nofixedoverflow (nofof)), nooverflow (noofl). nosize. nostringrange (nostrg), nostringsize (nostrz), nosubscriptrange (nosubrg). nounderflow (noufl), and nozerodivide (nozdiv). STR cannot contain an enabled condition name and a disabled condition name that identify the same condition. I I -profile. -pf generates additional code to meter the execution of individual statements. Each statement in the object program contains an additional instruction to increment an internal counter associated with that statement After a program has been executed, you can use the profile command to print the execution counts. -separate_static, -ss generates separate sections in the object segment created for the linkage information and the internal static variables. The default is to place internal static variables in the linkage section since both types of data are per process and writable. This control argument is useful primarily for programs that are prelinked and can therefore share the linkage section with other users. 3-639 AG92-06 pll pll -severityN t -svN writes error messages whose severity is less than N (where N is t 2t 3t -or 4) into the user_output switch although all errors are written into the listing. If you dontt select this control argumentt a severity level of 1 is assumed (see "Notes on Error Diagnostics" below). -single_symbol_list, -ssl produces a source program listing with symbols. The symbols are listed in onet single, alphabetized list If you don't give -single_symbol_list but specify -list, -map, or -symbols, the symbols are separated into four lists, arranged by declaration type. -source, -sc produces a source program listing. -symbols, -sb produces a source program listing with symbols. -table, -tb generates a full symbol table for use by symbolic debuggers. The symbol table is part of the symbol section of the object program and consists of two parts: a statement table that gives the correspondence between source line numbers and object locations and an identifier table containing information about every identifier actually referenced by the source program. This control argument usually lengthens the object segment significantly. (Default, unless you supplied -optimize) LIST OF ADDITIONAL CONTROL ARGUMENTS The following control arguments, while available, are probably not of interest to you. -debug, -db leaves the list-structured internal representation of the source programs intact after a compilation. This control argument is used for debugging the compiler. You can use the command pU$clean_up to discard the list structure. -no_debug, -ndb deletes the internal representation after compiling a program. (Default) -no_time, -ntm does not print a table of the time used by each phase of the compiler after the compilation. (Default) -time, -tm prints a table after compilation, a table giving the time (in seconds), the number of page faults, and the amount of free storage used by each of the phases of the compiler. This information is also available from the command pl1$times invoked immediately after a compilation. 3-640 AG92-06 pU pU NOTES If you invoke this command without control arguments, it generates an object segment If you give both a control argument and an incompatible alternative on the same command line, the rightmost one is used. For example: pll prog -brief_table -map -no_list -table is equivalent to pll prog -table A successful compilation produces an object segment and leaves it in your working directory. If an entry with that name already exists in the directory, its access control list (ACL) is saved and given to the new copy; otherwise, you are given re access to the segment with ring brackets v,v,v, where v is your process's validation level. If you specify -map, -list, -source, -symbols, or -single_symbol_list, the command creates a listing segment in your working directory and gives it a name consisting of the entry name portion of the source segment with a suffix of list rather than pU (e.g., a source segment named valid.pll has a listing segment named valid.list). The ACL is as described for the object segment except that you are given rw access to the newly created segment Previous copies of the object segment and the listing segment are replaced by the new segments created by the compilation. See the Multics PLII Language Specification Manual (AG94) and the Multics PL/I Reference Manual (AM83). NOTES ON SEARCH LIST The PL/I compiler uses the translator search list, which has the synonym trans. For more information on search lists, see the search facility commands--add_search_paths. in particular. NOTES ON ERROR DIAGNOSTICS The PL/I compiler can diagnose and issue messages for about 350 errors. messages are graded in severity as follows: These 1 Warning only. Compilation continues without ill effect 2 Correctable error. The compiler remedies the situation and continues, probably without ill effect For example, a mISSIng end statement can be corrected by appending the string ";end;" to the source. This action does not, however, guarantee the correct results. 3-641 AG92-06 pll 3 An uncorrectable but recoverable error. That is, the program is definitely in error and cannot be corrected, but the compiler can and does continue executing up to just before code is generated. Thus, any further errors are diagnosed. If the error is detected during code generation, code generation is completed although the code generated is not correct After the compilation, a message is printed to the error_output I/O switch to inform you that a severity 3 error has occurred. 4 An unrecoverable error. The compiler cannot continue beyond this error. The message is printed and then control is returned to the pll command unwinding the compiler. The command writes an abort message into the error_output I/O switch and returns to its caller. Error messages are written into the user_output I/O switch as they occur; thus, you can quit the compilation immediately when an error message is printed. You can specify -brief so that the messages are shorter. Here is an example of a long error message: ERROR 158, SEVERITY 2 ON LINE 30 A constant immediately follows the identifier " z ilch ll • SOURCE: a = zilch 4; If you choose -brief, you see instead: ERROR 158, SEVERITY 2 ON LINE 30 "zilch" Once a given error message is printed on your terminal in the long form, all further instances of it are printed in the short form. If a listing is being produced, the error messages are also written into the listing segment They appear, sorted by line number, after the listing of the source program. No more than 100 messages are printed. NOTES ON SEVERITY VALUES This command associates the following severity values to be used by the severity active function: Value o 1 2 3 4 5 Meaning No compilation yet or no error Warning Correctable error Fatal error lJnrecoverable error Could not find source. 3-642 AG92-06 pll pll NOTES ON LISTING The listing created by the pll command begins with a line-numbered image of the source segment. If you specify -symbols, -single_symbol_list, -map, or -list, this is followed by a table of all the names declared within the program. The names are categorized by declaration type as follows: 1. declared by declare statement 2. declared by declare statement and never referenced 3. declared by explicit context (labels and entries) 4. declared by implicit context or implication. Within these categories, the symbols are sorted alphabetically and then listed with their location; storage class; data type; size or precision; level; attributes such as initial, array, internal, external, aligned, and unaligned; and a cross-reference list If you give -single_symbol_list, these four categories are combined into one alphabetized list Next is a table of the program's storage requirements and the reasons why a block is nonquick. Next is a listing of any internal static variables, sorted by offset, and a listing of any automatic variables, sorted by block and offset. Next is a listing of external operators used, external entries called, and external variables referenced by the program. The symbol listing is followed by any error messages. If you select -map, the object code map follows the list of error messages. This table gives the starting location in the text segment of the instructions generated for statements starting on a given line. The table is sorted by ascending storage iocations. Finally, the listing contains the assembly-like listing of the object segment produced (if you specify -list). The executable instructions are grouped under an identifying header that contains the source statement that produced the instruction. Operation code, base register, and modifier mnemonics are printed beside the octal instruction. If the address field of the instruction uses the Ie (self-relative) modifier, the absolute text location corresponding to the relative address is printed on the remarks field of the line. If the reference is to a constant, the octal value of the constant's first word is also printed. If the address field of the instruction references a symbol declared by you, its name appears in the remarks field of the line. EXAMPLES The following command line compiles the segment prog.pll debugging: options facilitate pll prog -table -prefix size,strz,strg,subrg The default action for the stringsize condition returns to the point where the condition is signaled without printing a message. All computational conditions except size, stringsize, stringrange, and subscriptrange are enabled by default 3-643 AG92-()6 Name: pll_abs, pa SYNTAX AS A COMMAND pa paths {-pll_args} {-dp_args} {-control_args} FUNCTION submits an absentee request to perform PL/I compilations. ARGUMENTS paths are the pathnames of segments to be compiled. pll_args are one or more control arguments accepted by the pll command. dp_args are one or more control arguments (except -delete) accepted by the dprint command. CONTROL ARGUMENTS -queue N, -q N is the priority queue of the request site) (See "Notes:') (Default defined by your -hold. -hd specifies that pll_abs should not dprint or delete the listing segment. -limit N, -Ii N specifies a time limit in seconds for the absentee job. (Default defined by your site) -output_file path, -of path specifies that absentee output is to go to the segment whose patbname is path. NOTES The absentee process for which pll_abs submits a request compiles the segments named and dprints and deletes the listing segments. If you don't supply -output_file, an output segment (path.absout) is created in your working directory; if you specify more than one path, only the first is used. If none of the segments to be compiled can be found, no absentee request is submitted. Control arguments and segment pathnames can be mixed freely and can appear anywhere on the command line. All control arguments apply to all segment pathnames. If you give an unrecognizable control argument, the absentee request is not submitted. 3-644 AG92-06 Unpredictable results may occur if two absentee requests are submitted that could simultaneously attempt to compile the same segment or write into the same absout segment When doing several compilations, it is more efficient to give several segment pathnames in one command rather than several commands. With one command, only one process is set up_ Thus the dynamic intersegment links that need to be snapped when setting up a process and when invoking the compiler need be snapped only once. If you give no -queue, the request is submitted into the default absentee priority queue defined by your site and, if requested. the output files are dprinted in the default queue of the request type specified on the command line. If you don't specify request type, the "printer" request type is used. If you supply no -queue, the output files is dprinted in the same number queue as the absentee request. If the request type specified for dprinting does not have that queue, the highest numbered queue available for the request type is used and a warning is issued. Name: pll_macro, pmac SYNTAX AS A COMMAND FUNCTION invokes the stand-alone pll macro processor to translate a segment in accordance with the defined pll macro language. ARGUMENTS in_path is the pathname of the source segment. The source segment name must have at least three components, a suffix of "pmac", and a penultimate component of "pll" or "cds" or "rd". If you don't supply the suffix, it is assumed. The star convention is not supported. out_path is the pathname of the macro processed output segment If you haven't used -print or -process_dir, then the name of the inpath less the suffix is assumed if . not given. The outpath cannot be the same segment as the inpath. The equal convention is not supported. This argument is incompatible with -print and -process_dire 3-645 AG92-()6 CONTROL ARGUMENTS -arguments STRs, -ag STRs passes the strings as command line arguments. It must be the last control argument, and at least one STR must follow. These arguments are used in conjuntion with the %isarg macro construct (see "Command Line Argument Testing" below). -call STR calls STR as a command after the translation is complete if the macro processor does not discover an error. -no_version, -nver does not print the version of pll_macro. -parameter IDENTIFIER VALUE, -pm IDENTIFIER VALUE sets the value of macro replacement identifiers on the command line. IDENTIFIER must be a pll identifier; VALUE, a decimal integer, a bit string constant, a character constant, or an identifier. (See "Command Line Constants and Their Defaul ts. ") -print, -pr prints the macro processed output on user_output rather than place it in a segment. -process_dirt -pci places the macro processed output in the process directory rather than in your working directory. -target STR. -tgt STR makes the macro processor interpret STR as a target machine and sets the %target builtin (see "Code for Different Target Machines"). -version, -ver prints the version of pll_macro. (Default) BASIC REPLACEMENT CONSTRUCT To facilitate the use of named constants in places where internal static options (constant) don't work (e.g., label arrays and functions of named constant), there are three ways of defining replacement identifiers--pll_identifiers that are transformed at lex level to their defined values--by the %replace statement, by the %set statement, and, on the command line, by the %default statement. Macro Time Constants %replaceby 3-646 AG92-06 where is an expression whose operands are either constants or identifiers previously defined in other statements or on the command line. The valid operators are the arithmetic ones (+, -, *, and /) the concatenation operator (II), the logical operators (I\ &, and I), and the relational operators (=, 1\=, <, <=, >, >=, 1\>, and 1\<). Arithmetic values are represented internally as fixed binary (71). Parentheses can be in all expressions. The usual semantics of expression evaluation apply, and pll-like conversions are not done implicitly. Semantic Rules 1. All replacement identifiers must be lexically declared by a replace statement prior to use. 2. A replacement identifier may not appear lexically prior to its declaration in a replace statement This is to insure that its meaning remains constant throught the compilation unit 3. Once declared, a replacement identifier may not be redefined to have a different value by a replace statement, nor is there any way to "undefine" a replacement identifier; however, to facilitate replacement' identifiers being used in a variety of include files, redeclaration to the same value is permitted. 4. After its. declaration, the replacement identifier is replaced where it appears as a token in the lexed source by the value defined in ~he replace statement 5. Replacement identifiers have four data types: arithmetic, bit, character, and identifier. For all data types, operands must agree with their operators. The identifier data type is associated with no operator except the = and 1\= comparison. Macro Time Variables %set to The %set statement is like the %replace statement in the way it deals with replacement activity and constant expression evaluation, conflicts with parameters. etc. The only diff erence is that the placement identifier declared in an %set statement may appear in another %set statement with a different value. Its replacement rule is that it uses the value set in the last %Set statement (in the lexical sense). The use of variables in any two of %default. %replace, and %Set statements is not allowed. Command Line Constants and Their Defaults The -parameter control argument allows the virtual equivalent of a replacement identifier declaration on the command line. 3-647 AG92-{)6 The macro processor uses the replacement identifiers as though they had been declared in %replace statements, with two important differences: (1) these parameters must not be declared in the source in a %replace statement, even to the same value; (2) they must be declared in a %default statement If the same identifier appears in more than one instance of a "-pm IDENTIFIER VALUE" triplet, the last such triplet takes effect %default to ; If the identifier has been used in a parameter statement, this statement is ignored except to check that the data type of the constant given in the command line and the data type of the expression in the statement agree; otherwise, this statement causes the same substitution behavior as a %replace statement Macro Variable Declaration Builtin %isdef «identifier» is a macro builtin function that returns a value of data type bit (1). Its value is true only if the argument is a macro replacement identifier that you have lexically declared either in a %default, %set, or %replace construct prior to using %isdef or as a command line parameter. Command Line Argument Testing %isarg «pll-token» %isarg «char_string» is a macro builtin function that returns a value of data type bit (1). Its value is true only if the argument is one of the character strings following -arguments on the command line. The character string form of the argument is necessary if a command line argument is a string according to the command processor, but is not a pU token (e.g., 34xy). If the argument to %isarg is a character string, it is dequoted and the dequoted value is used in the test; for example, if the command line has -ag 34xy, the test in the source must be phrased as %isarg ("34xy"), rather than %isarg (34xy) because the macro processor works on pll tokens. So use only identifiers as command line arguments. to facilitate more reasonable-looking code. Conditional Compilation SYNTAX %if %then [%elseif %then ] ..• [%else ] %endif where is a possibly null string of tokens and the 's must evaluate to a bit_string constant 3-648 AG92-()6 Semantic Rules 1. The usual semantics of if-then-elseif-then-else statements apply. If the boolean expression in the test clause equals ~, then the condition is false, otherwise it is true. The %elseif and %else terms are optional. but the %then and %endif keywords are required. 2. The conditional compilation construct is invalid if all the constant expressions do not evaluate to proper logical values. 3. There is no restriction on what may appear as the object token-string of a then or else clause. In particular it may be standard pll tokens or further macro constructs such as %replace, %include, etc. 4. In order to facilitate the maintainabilirJ of code, use the conditional compilation facility to construct token strings that comprise entire pll statments, rather than code fragments. Code for Different Target Machines There is a strategy for informing translators which machine they should generate code for. The macro processor also uses this same strategy for use in conditional compilation. %target «identifier» is a replacement identifier of data type bit (1) whose value is true only if the value of the is equal to the value of the identifier given as the argument of -target on the command line. If you use %target without -target. a default value is supplied and an error of severity 2 indicated. If you don't use %target, then you need supply no information on the command line about the target machine. There are currently two flavors of target machines. The names 168, 6180, and dps8 are cannonically equivalent and refer to the standard Multics cpu·s. Expansion Time Include Files %INCLUDE ; %INCLUDE ; provides an expansion time include file feature. Include files are found through the transiator search ruies and have the same naming conventions as compiie time inciude files. You are permitted a maximum of 255 include files in one expansion, and you can nest them 64 deep. This differs from %include in that the macro processor merely checks to see that the %include statement is syntactically correct and outputs the statement 3-649 AG92-()6 User-Generated Messages %print ; %warn ; terror ; %abort ; The macro processor sets a severity, an external fixed binary (35) variable, called pll_macro_severity_. These four constructs allow you to send messages to user_output at macro time and set the minimum value of pll_macro_severity_ to zero, one, three, and four respectively. The %abort construct immediately aborts the macro_processor. The char_string can be generated as a result of macro time activity. Skip and Page Macros These are features that the pll compiler accepts. The macro processor checks them for syntactic correctness and passes the statement through. EXAMPLES pmac pc.p11.macro -call "p11 pc -ot -map" -target L68 -pm VERSION 1 -ag PTE The example %set FOO to 1; first = FOO; %set FOa to 2; second = FOO; %set FOO to (FOD + 3)**2; third = FOO; assigns the values 1, 2, and 25 to first, second, and third, respectively. With no -parameter triplet to declare FRED on the command line, the statement %defau1t FRED to 2345; replaces all future references of FRED with 2345. If, however, the command line contains the triplet -pm FRED 123 all references to FRED are replaced by 123. If the command line contains the triplet -pm FRED foo an error of incompatible data types occurs. 3-650 AG92-()6 plus Examples of the $isdef macro builtin function are: %if A %isdef (fred) %then terror liThe replacement identifier IlIlfred llll has not been defined."; %replace paradise by %isdef (adam) & %isdef (eve) & A %isdef (snake); An example of good style in conditional compilation can be: %if %target (168) %then call x (2); %else call y (22); z = z + foo; %endif An example of bad style can be: ca 11 %if %target (6180) %then x (2); %else y (22); z = z + foo; %endif Examples of the %target replacement identifier can be: %if %target (dpsB) %then %include sdw.t3; %else %incl~de sdw.tl; %endif %if %target (168) %then call foo$bar (carrot~uice, fruit_salad, code); %endif Here are some examples of user-generated messages: %default NAME to "6180"; %print, "NAME has been set to II II NAME; %if A $isdef (FRED) %then terror, "You forgot to define II"FRED"II."; %endif %if %isarg (PTE) & %isarg (NOPTE) %then %abort, "PTE and NOPTE cannot both be arguments"; %endif. Name: plus SYNTAX AS A COMMAND plus {num_args} 3-651 AG92-06 plus print SYNTAX AS AN ACTIVE FUNCTION [plus {num_args}] FUNCTION returns the sum of num_args. If you provide no num_args, 0 (the additive identity) is returned. EXAMPLES plus 3.5 3 6.5 plus -5 -5 Name: print, pr SYNTAX AS A COMMAND pr paths {-control=args} FUNCTION prints ASCII segments and multisegment files on user_output ARGUMENTS paths are the pathnames of the segments and multisegment files to be printed. The star and archive component pathname conventions are accepted. CONTROL ARGUMENTS -archive, -ac treats each archive component as a new file for heading and line numbering. If any lines are printed from an archive component and if you supplied -header, prints a header identifying the archive component name and the date of modification of the archive component, in the format ARCHIVE::COMPONENT date time where date and time are those stored in the archive. This control argument is the default if archive components were named with the :: convention or if the entryname of the segment ends in .archive, unless you give -no_archive. 3-652 AG92-06 print print -chase includes links in the search if a starname is specified, and does not complain about missing link targets for starnames. -exclude STRING, -ex STRING does not print lines containing STRING. Exclusion is done after matching. Thus, "-match A -exclude B" prints all lines with an A except those with a B. -exclude IREGEXP I. -ex IREGEXP I does not print lines containing a string matching the regular expression REGEXP. (See the qedx command for the definition of regular expressions.) -for N prints N lines from the file, including the first line. If you also use -to, printing stops when the first control argument is satisfied. (Default: to print the whole file) -from X, -fm X begins printing from the Xth incompatible. (Default line 1) line. This control argument and -last are -from IREGEXP I, -fm /REGEXP / begins with first line matching the regular expression REGEXP. -from_page P starts printing with the Pth page, counting the first page as 1. (Default to start with page 1) -header, -he prints a header of the form NAME date time before each segment If you choose -archive, the header is printed before each archive component lIiStead of before each segment This control argument is the default if you give no other control argument or if you use the star convention or multiple pathnames. -indent N. -ind N indents the printed output N columns. (Default: no indentation) -last N, -It N print the last N lines from the file. or the last N lines of the region selected by -to. -left_col N, -lc N does not print columns 1 to N-1. It truncates on the left, printing each line of the file starting with column N. If a line has fewer than N columns, a blank line is printed. (Default: to print starting with column 1) 3-653 AG92-Q6 print print -line_length Nt -11 N formats the page with a maximum physical line length of N characters. Space generated by -indent and -number is not counted. If more than N characters are in an output line! the line is split and continued on the next line. The default maximum line length is 1024 characters although you can give larger values. -match STRING prints only lines containing the character string STRING. -match /REGEXP / prints only lines containing a string matching the regular expression REGEXP. -name NAME, -nm NAME takes NAME literally! even if it is all numeric or begins with "-". -no_archive, -nac does not print headings for individual archive components (even if the file being printed is an archive) and treats the file being printed as a single segment for line numbering and heading. -no_chase does not include links when processing starnames. (Default) -no_header, -nhe suppresses the header before segments or archive components. This is the default if you give only one pathn3.t~e and other control arguments. -no_vertsp simulates formfeed and vertical-tab characters by outputting newline characters. -number t -nb prints line numbers before each line. The line number and the spaces separating it from the line take up 10 spaces. -output_switch SWITCH_NAME! -osw SWITCH_NAME directs the output to an attached and open (f or stream output or stream input/output) I/O switch. If not supplied, the output is directed to the user_output switch. -page_length N, -pI N starts a new page by inserting a formfeed character after every N lines of the file are printed (see "Notes"). (Default: no pagination) -phys_page_Iength N, -ppl N determines how many newline characters should be inserted between pages when you specify -no_vertsp. N, whose default value is 66, is the number of lines on a whole page of paper. (See "Notes.") -right_col N, -rc N does not print columns past N. Lines extending past column N are truncated on 3-654 AG92-()6 print print the right (Default to print all columns) -stop, -sp pauses before the first page and after each successive page until you type a newline. -to N stops printing with line number N. (Default to print all lines) -to /REGEXP / stops printing with the first line matching the regular expression REGEXP. The search for REGEXP begins after the first line printed. -to_page N stops printing after the Nth page. -vertsp sends formfeed and vertical-tab characters to the terminal. (Default) -wait, -wt pauses before the first page until you type a newline. NOTES The -page_length control argument works with -phys_page_Iength to eject the proper amount of spacing between pages. For example: pr test_file -pl 40 -no_vertsp prints 40 lines of the segment test_file and uses the default value for -phys_page_Iength of 66 to emit 26 blank lines before the next 40 lines are printed. If you position the printer paper so that text begins printing on the 13th line, then there are even amounts of leading and trailing space on each page. If you select any of -line_length, -page_length, -phys_page_lengtb, or -right_color -left_col is > 1, printing is done via the printer conversion software: overstrikes are replaced by multiple lines separated by CR (015) characters, and other control characters are ignored. Numeric arguments are processed specially for compatibility with previous versions of print If no file name has been found, a number is interpreted as a file name; other numeric arguments are interpreted as -from and -to, in that order. You can use -name to indicate that a number is intended as a pathname. You can supply· more than one -match and more than one -exclude; a line is printed if any -match selects it unless one -exclude prevents it from being printed. 3-655 AG92-06 print EXAMPLES The command line print xyz prints the segment or multisegment file "xyz" with a header. The command line print **.archive -match "/bit (fixed/" -nb -he scans all archive segments in your working directory for lines matching the regular expression /bit *(fixed/. Those lines are printed, with a line number giving the position in the archive component Each new archive component is preceded by a header that names the component and gives its date of modification. The command line print abc::** prints all components of abc. archive. Headers are printed for each component. SYNTAX ASA COMMAND pat {switch_names} {-control_argsl SYNTAX AS AN ACTIVE FUNCTION [pat {switch_names} {-control_args}] FUNCTION prints information on your terminal about the I/O switch name associations created by attach calls in your current ring. As an active function, returns the switch names selected by switch_names and control arguments. ARGUMENTS switch_names are the names of I/O switches. The star convention is allowed. You can use -name to inhibit star name processing or to supply a switch name that appears to be a control argument Information about only the specified switches is printed. If a given switch is not currently attached, a message is printed on your terminal. 3-656 AG92-o6 CONTROL ARGUMENTS -all, -a prints the state of all the selected switches that match the star names, whether they are attached or not Specify only one of -all, -attached, or -open. -attached, -att prints the state of those switches that match the star names only if they are currently attached. (Default) -brief, -bf does not print information for the four standard switch_names (user_i/o, user_input, user_output, and error_output) even if they match a star name. switch_name, -nm switch_name interprets the switch_name literally, even if it looks like a star name or a control argument ~name -open prints the state of those switches that match the starnames only if they are attached and open. NOTES If you invoke it as a command, the attach and open descriptions associated with the indicated switch names are printed. If you supply no arguments, the information for all switches currently attached is printed. See the io_call command. SYNTAX AS A COMMAND pan {-control_args} FUNCTiON prints the names of the sensitivity levels and access categories defined for the installation. CONTROL ARGUMENTS -all, -a lists all possible names (above system high). 3-657 AG92-()6 -brief, -bf suppresses the title and headings. -category, -cat lists only the access categories. -level lists only the sensitivity levels. NOTES Only the names that can be used to describe an access class or access authorization between system low and system high are printed. unless you give -all. This command lists the names that are acceptable to convert_authorization_ (see the Subroutines manual) to define an access class or access authorization. (All commands and system interfaces that use a character string to describe an access class use this subroutine.) Both the long and short names are printed. SYNTAX AS A COMMAND pbm path {components} {-control_args} FUNCTION displays all or part of the bind map of an object segment generated by version 4 or subsequent versions of the binder. ARGUMENTS path is the pathname of a bound object segment. components are the optional names of one or more components of this bound object and/or the bindfile name. Only the lines corresponding to these components are displayed. A component name must contain one or more nonnumeric characters. If it is purely numerical, it is assumed to be an octal offset within the bound segment, and the lines corresponding to the component residing at that offset are displayed. A numerical component name can be specified by preceding it with -name. If no component names are supplied, the entire bind map is displayed. 3-658 AG92-06 CONTROL ARGUMENTS -long, -lg prints the components' relocation values (also printed in the default brief mode), compilation times, and source languages. -name S1R -nm STR is used to indicate that STR is really a component name, even though it appears to be an octal offset -no_header, -nhe omits all headers, printing only lines concerning the components themselves. -page_offset, -pgofs prints as an octal number the page number of the first word of the text section of each component, which is the format used by the cumulative_page_trace command. If the component crosses at least one page boundary, a plus (+) character follows the page number. Name: print_configuration_deck, pcd SYNTAX AS A COMMAND pcd {card_names} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [pcd {card_names} {-control_args}] FUNCTION displays the contents of the Multics configuration deck. The data is kept up-to-date by the reconfiguration commands and, hence. reflects the current configuration being used. The active function returns the selected cards in quotes, separated by a single space. ARGUMENTS card_names are the names of the particular configuration cards to be diSplayed. You can give up to 32 card names (see the Multics System Maintenance Procedures Manual, AM81, f or the names of the configuration cards). 11/86 3-659 AG92-06A print_configuration_deck prin t_conf iguration_deck CONTROL ARGUMENTS -exclude FIELD_SPECIFIERS, -ex FIELD_SPECIFIERS excludes particular cards or card types from being displayed. You can supply one to 14 field specifiers with each -exclude and up to 16 -exclude control arguments. To be eligible for exclusion a card must contain fields that match all field specifiers selected with any -exclude. -label, -lbl displays cards with mnemonic labels for each field. * -match FIELD_SPECIFIERS selects particular 'cards or card types to be displayed. You can give one to 14 field specifiers with each -match and up to 16 -match control arguments. To be eligible for selection a card must contain fields that match all field specifiers supplied with any -match. -no_label, -nlbl does not display field labels. (Default) -pathname PATH, -pn PATH displays the configuration deck in the segment specified by PATH, rather than the configuration deck of the live system. NOTES Field specifiers can consist of a complete card field or a partial field and an asterisk. An asterisk matches any part of any field; for example, the field specifier "dsk*" matches any card containing a field beginning with the characters "dsk". You can give specifiers for numeric fields in octal or decimal, but if decimal they must contain a decimal point. You can't use asterisks in numeric field specifiers. All numeric field specifiers are converted to decimal and matched against numeric card fields. which are also converted to decimal. Hence, the field specifier "1024." matches a card containing the octal field 2000, and the field specifier "1000" matches a card containing the decimal field 512. Selection is performed as follows. If you give no card names. all cards are selected; if you supply any card names, only the cards matching those names are selected; and if more than one card exists with a specified name, all such cards are displayed. If * you request a nonexistent card, an error message is displayed. If you give any -match arguments, those eligible cards are matched against all field specifiers of each -match argument group; however, at least one -match group must have all its field specifiers match some field on the card to make that card eligible. A similar algorithm is used for any -exclude argument groups. So, if a card is eligible and you supply -exclude arguments, then at least one -exclude group must have all its field specifiers match some field on the card to make that card ineligible. If no match for a given card name or -match group is found in the configuration deck, nothing is displayed for that name or group and no error is displayed. If you give no arguments, the complete configuration deck is displayed. 11/86 3-660 AG92-06A Specify all card names before the first -match or -exclude argument Field specifiers following a -match or -exclude argument include all arguments until the next -match or -exclude argument No action is taken for misspelled arguments or valid arguments for which there are no corresponding configuration cards. EXAMPLES pcd cpu cpu a 7 cpu b 6 cpu c 5 168 80. 168 80. 168 80. on on off (For the configuration deck dispiayed above.) pcd cpu -match on cpu a 7 168 80. cpu b 6 168 80. on on pcd -match 16 -ex off -ex b cpu a 7 168 80. on SYNTAX AS A COMMAND pdwd FUNCTION prints out the pathname of the current default working directory on the user's terminal. NOTES 3-661 AG92-()6 SYNTAX AS A COMMAND pem code SYNTAX AS AN ACTIVE FUNCTION [pem code] FUNCTION prints out the standard Multics (error_table.J interpretation of a specified error code. The various entries given below allow you to specify the error code in either decimal or octal and have the output come out in either the short or long error_table_ form. The active function returns, as a single quoted string, what the command prints. ARGUMENTS code is the decimal integer to be interpreted. The short form of the error message is printed. Entry: pel This entry is the same as pem except that the long form of the error message is printed or returned as a single quoted string. SYNTAX AS A COMMAND pel code SYNTAX AS AN ACTIVE FUNCTION [pel code] Entry: peo This entry is the same as pem except that the input code is assumed to be octal. SYNTAX AS A COMMAND peo octal_code SYNTAX AS AN ACTIVE FUNCTION [peo octal_code] 3-662 AG92-06 Entry: peol This entry is the same as pel except that the input code is assumed to be octal. SYNTAX AS A COMMAND peol octal_code SYNTAX AS AN ACTIVE FUNCTION [peol octal_code] SYNTAX AS A COMMAND pli paths {-control_args} FUNCTION prints selected items of information for the specified object segments. ARGUMENTS paths are the pathnames of object files. You can use the archive component pathname convention (::). I CONTROL ARGUMENTS -entry. -et prints a listing of pathi external definitions. giving their symbolic names and their relative addresses within the segment If pathi is an object multisegment fBe (MSF), the external definitions in each of the executable components are listed. -header. -he prints the header. which is not printed by default if you select -entry. -length. or -link. -length, -In prints the lengths of the sections in pathi. If pathi is an object MSF. the lengths of the sections for each executable component are printed. 11/86 3-663 AG92-06A -link, -lk prints an alphabetically sorted listing of all external symbols referenced by pathi. If pathi is an object MSF, the list of external links in each executable component is printed. If you use a link in more than one component, the link is listed more than once. -long prints additional information when the header is printed. This information includes a listing of source programs used to generate the object segment, the contents of the "comment" field of the symbol header (often containing compiler options), and any unusual values in the symbol header. -no_header suppresses printing of the header. NOTES If you select no control arguments, -et, -he, -In, and -lk are assumed. If a path given is an object MSF, the information for each of the executable components is printed. 11/86 3-664 AG92-06A EXAMPLES pli program -long -length copy OS/27/83 1126.7 edt Fri Object Segment >user_dir_dir>MPM>user_documents>commands>copy Created on 12/23/82 1205.4 edt Thu by Moore.SysLib.m using Mu1tics PL/I Compiler, Release 27d, of September 28, 1982 Translator: Comment: Source: 12/23/82 11/16/82 OS/25/82 Attributes: PL/I optimize map sing1e_symbo1_1ist >ldd>oi>2873dir>copy.p11 1205.5 edt Thu >ldd>inc1ude>status_structures.inc1.pl1 1554.7 edt Tue 1715.1 edt Tue >ldd>inc1ude>star_structures.incl.pl1 relocatable, procedure, standard Object Start Length Text o o 7036 5510 Defs 5510 576 Link 6306 152 Symb 6460 342 Static 6316 o Also printed is Severity, if it is nonzero. Entrybound, if it is nonzero. Text Boundary, if it is not 2. Static Boundary, if it is not 2. 11/86 3-664.1 AG92-o6A This page intentionally left blank. 11/86 AG92-G6A SYNTAX AS A COMMAND plu FUNCTION lists the locations and size of linkage and static sections allocated for the current ring. This information is useful for debugging purposes or for analysis of how a process uses its linkage segments. NOTES A linkage section is associated with every procedure segment and every data segment that has definitions. For standard-procedure segments, the information printed includes the name of the segment, its segment number, the offset of its linkage section, and the size (in words) of both its linkage section and its internal static storage. Name: print_mail, prm SYNTAX AS A COMMAND prm {mbx_specification} {-control_args} FUNCTION prints the messages in a mailbox, querying you whether to delete each one after it is printed. ARGUMENTS mbx_specif ication specifies the mailbox from which messages are to be printed. If not given, the user's default mailbox (>udd>Project_id>Person_id>Person_id.mbx) is used. I CONTROL ARGUMENTS -accessible, -ace selects only those messages in the mailbox that you are permitted to read. If you have read (r) extended access on themailbox.print_mail selects all messages in the mailbox; if you have own (0) extended access on the mailbox, it selects only those messages that you sent to the mailbox. (Default) 11/86 3-665 AG92-06A -acknowledge, -ack acknowledges messages that request acknowledgement (Default) -all, -a selects all messages in the mailbox regardless of who sent them. It requires read (r) extended access on the mailbox. -brief, -bf shortens the greeting message. This message indicates the number of messages in the mailbox. -brief_header, -bfhe displays the minimal amount of information from the message header. The date and authors are always displayed; the subject is displayed if it is not blank; the number of recipients is displayed either if there is more than one recipient or if you are not the sole recipient of the message; if the message is forwarded with comments, they are also displayed. -count, -ct displays the number of messages read from the mailbox before printing the first message. (Default) -debug, -db enables print_mail's debugging facilities. It is not recommended for normal users of print_mail. -header, -he displays all information from the message header, including user-defined fields and excluding the message trace and redundant information. (Default) -in teractive_messages -im includes interactive messages (as sent by the send_message command) along with regular mail. (Def aul t) t -list, -Is prints a summary of all the messages before printing the first message. summary is identical to that produced by the read_mail list request This -long, -lg prints the long form of the greeting message. (Default) -Ions-header, -lghe displays all information from the message header, including network-tracing information, even if some of it is redundant (e.g., if the From, Sender, and Delivery-By fields are all equal, -Ions-header forces print_mail to display them when it prints the message). -mail, -ml prints ordinary messages in the mailbox. (Default) 3-666 AG92-06 -no_acknowledge. -!laCK does not acknowledge messages that request acknowledgement -no_count. -nct does not display the message count -no_debug. -ndb disables print_mail's debugging facilities. (Default) -no_header, -nhe displays no information from the message header. Only the message number. message body line count, and message body are displayed. -no_interactive_messages. -nim does not include interactive messages. It is incompatible with -no_mail. -no_list, -nIs does not print a summary of the messages. (Default) -no_mail. -nml does not print ordinary messages. -no_reverse, -nrv prints the messages in ascending numeric order. (Default) -not_own selects only those messages in the mailbox that were not sent by you. It requires read (r) extended access on the mailbox. -own selects only those messages in the mailbox that you sent to the mailbox. requires own (0) extended access on the mailbox. It -reverse, -rv prints the messages in descending numeric order. LIST OF MBX SPECIFICATIONS -log specifies the user's logbox and is equivalent to -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx -mailbox path, -mbx path specifies the pathname of a mailbox. The suffix mbx is added if necessary. -save path, -sv path specifies the pathname of a savebox. The suffix sv.mbx is added if necessary. 11/86 3-667 AG92-06A -user STR specifies either a user's default mailbox or an entry in the system mail table (see "Notes on Mailbox Selection by User" below). STR is any noncontrol argument and is first interpreted as -mailbox STR; if no mailbox is found, STR is then interpreted as -save STR; if no savebox is found, it is interpreted as -user STR. LIST OF QUERY RESPONSES After printing each message, print_mail asks the question print_mail: Delete IN? The acceptable answers are '1 prints the list of acceptable answers. abort exits print_mail without deleting any messages. no, n does not delete this message. ,."".:+ ,.. 'fUlL, 'i deletes the indicated messages and exits print_mail; the message just printed is not deleted (see "Notes"). reprint, print, pr, p prints the message and asks the question again. yes, y deletes this message (see "Notes"). NOTES Answering "yes" to the query after a message is printed does not delete the message immediately but marks it as one for deletion. Messages are actually deleted either after you answered the query for the last message (unless you typed "abort") or after you answered any query with "quit" 3-668 AG92-06 prine.mail lVOTES a/v iv7AiLBOX SELECTiON BY USER A user's default mailbox is specified in the form Person_id.Project_id. For an entry in the mail table, STR is usually in the form of Person_id. The mail table permits you to address mail by Person_id without knowing the Project_id of the recipient. The mail table is described in the Extended Mail System User's Guide (CH23) and the Multics System Administration Procedures (AK50) manuals. If STR contains one period and no white space, it is interpreted as a User_id that specifies a user's default mailbox; otherwise it is interpreted as the name of an entry in the mail table. For example, -user DBuxtehude.SiteSA is interpreted as a User_id that identifies a default mailbox. On the other hand, -user "George G. Byron" -user L.v.Beethoven -user Burns are all interpreted as the names of entries in the mail table: the first because it contains white space; the second because it contains more than one period; the third because it contains no period. When interpreted as a User_id, STR cannot contain any angle brackets «» and must have the form Person_id.Proje-et_id, where "Person_id" cannot exceed 28 characters and "Project_id" 32 characters. In this case, "-user STR" is equivalent to the mbx_specification "-mailbox >udd> Project_id> Person_id> Person_id.mbx." When interpreted as the name of a mail table entry, STR cannot contain any commas, colons, semicolons, backslashes (\), parentheses, angle brackets, braces ({}), quotes, commercial at-signs (@), or white space other than spaces. The query of the mail table is performed in a case-insensitive manner. Use the display_mailing_address command to determine the actual address corresponding to STR. The address in the mail table must identify a mailbox. 3-669 AG92-06 Name: print_messages, pm SYNTAX AS A COMMAND pm msg_specs {mbx_specification} {-controJ_args} FUNCTION prints any interprocess messages that were received (and saved in the user's mailbox) while the user was not accepting messages, not logged in, or "accept_messages -hold_messages" was in effect ARGUMENTS ms8-specs are one or more numbers or ranges. Numbers are as printed next to each message when accept_messages -hold_messages is in effect Ranges are of the form N:M, where N<=M and both Nand M are valid message numbers. You can use the keywords "first" (f) and "last" 0) as message numbers and the keyword "all" (a) as a range (equivalent to "f:l"). mbx_specification specifies the mailbox from which messages are to be printed. If not given, the user's default mailbox (>udd>Project>Person>Person.mbx) is used. CONTROL ARGUMENTS -after DATE_TIME prints messages sent after DATE_TIME only. -all, -a prints all messages, including those held by the -hoid_messages mode (see accept_messages). (Def aul 1) -before DATE_TIME prints messages sent before DATE_TIME only. -brief, -bf suppresses an error message when no matching messages are found. -call cmdline calls the command processor with a string of the form: cmdline number sender time message {path} where: cmdline is any Multics command line; enclose it in quotes if it contains blanks or other command language characters. 11/86 3-670 AG92-06A number is the sequence number of the message, assigned when you use -hold; otherwise it is O. sender is the User_id of the person who sent the message. time is the date-time the message was sent message is the message sent path is the pathname of the mailbox to which the message was sent message was sent to the default mailbox, path is omitted. If the -comment STR, -corn STR prints messages with comment fields containing STR only. -exclude STR prints messages with text not containing STR only. -from STR, -fm STR prints messages sent from STR only. STR can be of the form Person. Project, Person, or .Project -last, -It prints only the latest message receiVed. message selection arguments. You can't use it with any other -long, -lg prints the sender and date-time of every message, even when the same for two consecutive messages. It overrides -brief. -match STR prints messages with text containing STR only. -messages, -rnsg prints regular messages (nonnotifications) only. -no_messages, -nmsg suppresses -messages. -no_notifications. -nnt nullifies -notifications. -notifications, -nt deletes notifications only. 3-671 AG92-06 -new when accept_messages -hold is in effec~ prints only those messages that have not been printed before. (Default: to print all held messages) -short, -sh precedes consecutive messages from the same sender by "=" instead of the Person_id and Project_id, and does not print the date-time string, but only if less than five minutes have passed since the previous message. It omits the date if the current message and the previous one are received on the same date. (Def aul t) LIST OF MBX SPECIFICATIONS -log specifies the user's logbox and is equivalent to -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx -mailbox path, -mbx path specifies the pathname of a mailbox. The suffix .mbx is added if necessary. -save path, -sv path specifies the pathname of a savebox. The suffix .sv.mbx is added if necessary. -user STR specifies either a user's default mailbox or an entry in the system mail table. STR is any noncontrol argument and is first interpreted as -mailbox STR; if no mailbox is found, STR is then interpreted as -save STR; if no savebox is found. it is interpreted as -user STR. NOTES A default mailbox is created the first time you issue print_mail, read_mail, or accept_messages. The default mailbox is: >udd>Project_id>Person_id>Person_id.mbx Messages are deleted after they are printed unless accept_messages -hold_messages is in effect); however, the last message remains available for the life of the process or until replaced by a new message. (See also last_message, last_message_sender, and last_message_time.> If you are deferring messages, it is a good practice to use the print_messages command periodically to print out pending messages. 3-672 AG92-()6 Name: print_motd, pmotd SYNTAX AS A COMMAND pmotd {control_arguments} FUfo/CTION prints out changes to the message of the day. The default is to print changes to the system and user_project message_of_the_day segments since the last time the command was called. CONTROL ARGUMENTS -all_ text, -all, -a specifies that the entire contents of the system and/ or project message_of_the_day segment will be displayed, regardless of whether or not any of the messages in the segment have been previously seen. -current_project, -cpj prints lines from Ll}e message of the day for the project on which the user is logged in. If the project administrator has not created a message for your project, nothing is printed. (default) -new specifies that only unseen messages in the system and/or project message_of_the_day segment will be displayed. (default) -project projects, -pj projects prints new or changed lines in the message of the day for the named projects. A warning is printed if there is no message for one or more of the projects. -system, -sys prints lines from the message of the day created by the system administrator. (default) NOTES If -system. -current_project and -project are not specified, print_motd prints lines from the system message and from the message for the current project If one or more of these arguments are given, print_motd prints lines only from those messages~ 11/87 3-673 AG92-06B For comparison purposes, copies of project motds are stored in the default value segment with the name project_motd.PROJECT._ where PROJECT is the default user project or a project specified by the -project control argument. Project motds will be created by a project administrator and placed in the project directory with the name >udd>PROJECT>PROJECT.motd with an addname of >udd>PROJECT>PROJECT.info. The first time that print_motd is used for a specific project, it will print the entire contents of the message-of -the-day segment. Subsequent uses will default to print those lines which have been modified or added to the message-of -tbe-day since the last use of the command unless the user specifies the -all_text control argument. Since a copy of each motd segment is stored in the user's value segment, project administrators should keep the size of the project motd segments to a minimum by deleting older messages as they expire. SYNTAX AS A COMMAND ppa {-control_args} FUNCTION prints the access authorization of the current process and any current system privileges. CONTROL ARGUMENTS -all, -a prints the maximum access authorization of this process. -long, -lg prints the site-defined long names (up to 32 characters) for the sensitivity levels and categories. 11/87 3-673.1 AG92-06B NOTES If you supply no -long, the site-defined short names (eight characters or less) for sensitivity levels and categories are printed. The maximum authorization printed by -all is the one that this process could have been given at login and corresponds to the maximum access class of upgraded directories that can be created by this process. Name: print_request_types, prt SYNTAX AS A COMMAND prt {rqt_names} {-control_args} SYNTAX AS AN ACTIVE FUNCTION [prt {rqt names} {-contro 1 args}] FUNCTION prints information about request types handled by I/O Daemons. As an active function. returns the names of the selected request types that would have been printed. ARGUMENTS rqt_names are the names of request types to be printed. The star convention is allowed. CONTROL ARGUMENTS -access_name User_id. -an User_id prints information about request types serviced by identified by User_id (see "Notes"). the I/O driver process -brief, -bf does not print heading line. -directory PATH. -dr PATH specifies the pathname of a test directory to be used in place of the 10 Daemon Directory (>ddd>idd). This command looks for an iod_workins-tables segment in this directory. -generic_type STR, -gt SIR lists request types of generic type STR. You can use it to support site-defined generic types. 3-674 AG92-06 1I/"'T"~"" IVVI C';:' You can select only one control argument The relocation bits are interpreted one word at a time. Each line contains symbolic relocation information for two half words. Printing of duplicate lines is suppressed and indicated by the string "(repeats)". EXAMPLES pri >udd>Project>Person>a 100 100 (repeats) 103 104 (repeats) 110 111 112 113 (repeats) 20 absolute absolute 1 ink ptr 15 absolute absolute absolute int static absolute int static absolute 15 15 absolute absolute absolute absolute SYNTAX AS A COMMAND prt {rqt_names} {-control_args} SYNTAX AS AN ACTIVE FUNCTION FUNCTION prints information about request types handled by I/O Daemons. As an active function, returns the names of the selected request types that would have been printed. ARGUMENTS rqt_names are the names of request types to be printed. You can use the star convention. 11/86 3-674.1 AG92-06A CONTROL ARGUMENTS -access_name User_id, -an User_id prints information about request types serviced by the I/O driver process identified by User_id (see "Notes"). -brief, -bf does not print heading line. -directory path, -dr path specifies the pathname of a test directory to be used in place of the I/O Daemon Directory (>ddd>idd). This command looks for an iod_workinLtables segment in this directory. -generic_type STR, -gt STR lists request types of generic type STR. You can use it to support site-defined generic types. 11/86 3-674.2 AG92-06A -plot prints information about request types associated with the plotter generic type. -print, -pr prints information about request types associated with the printer generic type. -punch. -pch prints information about request types associated with the punch generic type. -user_defined, -udf prints information about request types for which user-defined output control argument settings have been defined using enter_output_request The printed output includes both the user-defined request type name and its target request type name. As an active function, only the user-defined request type name is returned. NOTES The User_id argument specified after -access_name can have any of the following forms: Person_id.Project_id Person_ide * Person_id *.Project_id .Project_id matches matches same as matches same as that user only. that person on any project Person_ide *. any user on that project *.Project_id. The enter_output_request command allows you to define named groups of default control argument settings. The names of these groups can be referenced as if they were user-defined request types. These names are shown in the output of print_request_types, indented under the request type to which they apply. The active function returns the names of any user-defined request types that match the selection criteria. SYNTAX AS A COMMAND FUNCTION interprets the three data segments produced by the sample_refs command, and produces a printable output segment that 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.) 3-675 AG92-()6 ARGUMENTS name specifies the names of the data segments to be interpreted, as well as the name of the output segment to be produced. This argument can be either an absolute or relative pathname. If name does not end with the suffix srf, it is assumed. The appropriate directory is searched for three segments with entrynames as follows: (entry portion of) name.srf1 (entry portion of) name.srf2 (entry portion of) name.srf3 The output segment is placed in the user's working directory with the entryname: (entry portion of) name.list CONTROL ARGUMENTS -brief, -bf specifies that the detailed trace of segment references is not to be generated. 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. EXAMPLES (1) (2) 234 6542 234 2104 234 6160 >udd>user>bound_alpha_1 6542 >udd>user>max35 1512 >system_library_1anguages>assign_16160 The occurrence of the above three lines in the detailed trace indicates the following: 1. 2. 3. 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. 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. 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. 3-676 AG92-06 The appearance of a segment number suffix (Le.. 1. 29 etc.) indicates a component of a bound segment 310 310. 1 310.2 >system_1ibrary_standard>bound_ti_term_ tssi_ trans1ator_info_ The appearance of the above lines in the segment number to path name 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. SYNTAX AS A COMMAND psp {search_lists} {-control_arg} FUNCTION prints the search paths in the specified search lists. ARGUMENTS search_lists is the name of a search list. If you specify no search lists. all search lists referenced in this process are printed. CONTROL ARGUMENTS -expanded. -exp prints all keyword search paths, except paths as absolute pathnames. -referencin~dir. and all unexpanded search NOTES All synonyms of a search list name are printed if you give no search lists. For a complete list of the search facility commands, see add_search_paths. 3-677 AG92-06 SYNTAX AS A COMMAND psr FUNCTION prints the object segment search rules currently in use. NOTES See also the descriptions of the add_search_rules, delete_search_rules, and set_search_rules commands. The standard search rules are described in the Programmer's Reference Manual (Section 4, under "Search Rules"). SYNTAX AS A COMMAND ptt {path} FUNCTION prints the names of all terminal types defined in the terminal type table (TIT) currently in use. If the TIT being used is not the system default 'ITT, the command prints the current TIT's pathname at the head of the list of terminal names. ARGUMENTS path specifies the pathname of the TIT. If omitted, the current TIT is used. Name: print_time_defaults, ptd SYNTAX AS A COMMAND ptd {keys} {-control_arg} SYNTAX AS AN ACTIVE FUNCTION [ptd key {-control_arg}] 3-678 AG92-G6 FUNCTION displays system or process time-related defaults. ARGUMENTS key selects which default value is to be displayed. CONTROL ARGUMENTS -system, -sys requests that the system defaults be displayed instead of the process defaults. LIST OF KEYS date displays the default date format A date format shows the year, month, and day in month. date_time displays the default date/time format. This combines both date and time. debug, db displays the default status of debugging in the date/time system. language, lang displays the default language. Any time words in output time strings are in language. time displays the default time format. (optionally) seconds. A time format shows the hour, minutes. and zone displays the default time zone name. Unless explicitly specified, aU input time strings are interpreted relative to this zone and all output time values are expressed in this zone. NOTES If set_time_default has pushed any values, these are also shown. The keys specify which defaults to print. When called with no keys, all time-related defaults are displayed, except for the debugging switch, which is shown only if it is on. As an active function, it returns the current value of one of the defaults. The debugging switch is returned as "true" if debugging is on, "false" otherwise. The values displayed are in this order: debug. 11/86 date. date_time, time, language, zone, and 3-679 AG92-06A probe SYNTAX AS A COMMAND FUNCTION prints the name of the terminal type table (TIT) segment currently in use. This is the path name last set by a set_ttt_path command or the pathname of the default system TIT. Name: print_wdir, pwd SYNTAX AS A COMMAND pwd FUNCTION prints the pathname of your current working directory. NOTES A working directory is a directory in which your activity is centered. Its pathname is remembered by the system so that you need not type the absolute pathname of segments inferior to that directory. See the change_wdir, change_defauit_wdir, and worKm~dir commands. "Search Rules" and "Pathnames" in the Programmer's Reference Manual. See also Name: probe, pb SYNTAX AS A COMMAND pb {procedure_name} {-control_args} 3-680 AG92-()6 probe probe FUNCTION provides symbolic, interactive debugging facilities for programs compiled with PL/I. FORTRAN, Pascal. COBOL, or ALGOL-68. Its features permit you to interrupt a running program at a particular statement, examine and modify program variables in their initial state or during execution, examine the stack of block invocations, and list portions of the source program. You can invoke external subroutines and functions, with arguments as required, for execution under probe control. You can call probe recursively. ARGUMENTS procedure_name is the pathname or reference name of an initiated program. If you don't give it, the procedure owning the frame in which the last condition was raised is assumed. CONTROL ARGUMENTS -handle_condi tions sets up a handler for any conditions signaled while in probe that prints an appropriate message and prevents faulting. (Default) -no_handle_conditions does not set up the handler. OVERVIEW OF PROCESSING When you invoke probe, it accepts requests from you. A probe request consists of a keyword (or its abbreviation) that specifies the desired function and any arguments required by the particular request. Requests are separated from each other by newlines or semicolons. You can give a series of requests in the form of a request list. This is used in breakpoint request lists and conditional execution lists. Here. each request is separated by semicolons; for example: value a; v b; continue Probe at all times has a "current language." It communicates with you in terms appropriate to the language of the procedure being examined. The syntax of an expression and the form of probe's output vary from language to language. To use probe to the fullest. you must compile a program so that the object segment produced has both a symbol table and a statement map (see "List of Probe Terms" below). A symbol table and statement map are produced for the languages supported if you give -table to the compiler. You can also compile a program with -brief _table, which produces only a statement map. In this case you can retrieve information about source statements and where the program was interrupted and can set breakpoints, but can do little else. 3-681 AG92-06 probe probe Don't compile with -optImIze the program being probed because compiler optimization can cause program variables to appear different than they actually are and thus cause program statements to behave unpredicatably. NOTES ON COBOL Probe uses a COBOL-like syntax when the current language is COBOL. The current language is COBOL whenever the current source line is in a COBOL program. You can use the hyphen to form names, as it is in COBOL. You can qualify aggregate names in the COBOL manner (c of b of a) as well as in the PL/I manner (a.b.c). An aggregate is expressed by displaying the values of each of its members. NOTES ON FORTRAN When the current source line is a FORTRAN statement, probe is in fortran mode, where logical variables are displayed as n.true." or ".false." instead of as "I"b or "O"b. Case is ignored if you compiled the program with -card or -fold. You can use the relational -operators ole" .It, .«1., .nc., .gt., and.g.e•. NOTES ON PASCAL Invoked on a Pascal program, probe understands all the Pascal data types, including enumerated types, typed pointers, sets, records, files, and user-defined types, as well as the Pascal built-in functions chr, eof, eoln, false, nil, ord, and true. Array indices are enclosed in brackets, e.g., "a [i,j] n. Cross-section ranges are written with ".. ", as in Ita [first.last] ". References to record fields must specify all levels; impiicit level names are not allowed; for example. you can't abbreviate "a. b.c.d n as "a.d" as you can sometimes do with PL/I structure elements. Pointer values are written with a circumflex (t.) as the up-arrow, for example "pt." to indicate the value that p points to. String constants are enclosed in apostrophes: 'This is a string'. The two boolean values are "true" and "false". The notation denotes a value of type type_id located at p, where p can be any Pascal-typed. pointer, probe pointer variable, or pointer constant. The probe statement let pl = p2 is allowed for pI and p2 being any kind of pointer value, i.e., Pascal-typed pointer, pointer constant (for p2 only), or probe pointer variable. 11/86 3-682 AG92-06A probe probe These extensions have been implemented so that you can write. for example. del p ptr let p = first wh i 1e p <> nil (v p -> data; let p =p -> data.next) which can be useful if you want to display a list of records of type "data," chained by their field "next." PROBE POINTERS Two internal "pointers" are used by probe to keep track of the program's state: the "source" pointer, which indicates the current source program statement, and the "control" pointer. which indicates the current control point. The values of these pointers can be obtained by using the "where" request. The source pointer is set by using the "position" or "use" request. The control pointer is set when you enter probe. The source pointer always indicates some location active, then the source pointer also indicates a program. If you compile the object segment with line number is available; otherwise, the location is the base of the segment to an instruction. 11/86 3-682.1 in a program. If the program is stack frame associated with the the "table" options. then a source indicated by an octal offset from AG92-06A This page· intentionally left blank. 11/86 AG92-06A probe probe If you compile the program with a "table" option, probe obtains the text of source lines from the program's source segment (NAME.pU, NAME. fortran, etc.). This is either the segment from which the program was originally compiled, if it exists, or the first segment with the appropriate name found using the "probe" search paths. If no source segment can be found, the position and source requests are unable to print source lines. The language of the source line is the one probe uses with you. The meaning of a block depends on the language: for a PL/I program it specifies the smallest begin block or procedure that contains the source line; for a FORTRAN program it specifies the program or subprogram on which the statement occurs; for a COBOL program it indicates the program-id of the containing program. The frame specifies a stack frame associated with the block. When there are several invocations of the same block on the stack, the frame distinguishes between them. If there is no activation of the block, the frame portion of the source pointer is nun; in this case, Certain types of storage (i.e., PL/I automatic) are not defined. The control pointer indicates the last location executed in the procedure first examined and whether it took a fault or was called out (unless it was inactive, in which case it is the location of the entry statement). If you invoked probe by a breakpoint, the control pointer indicates the statement where the break occurred. 1. If you invoke probe from a breakpoint, the control pointer is set to the line where the break occurred. 2. If you invoke probe from the command line and specify a procedure_name, then if the procedure is active the control pointer is set to the last line executed in the most recent invocation of that procedure. 3. If the procedure in the command line is not active, the control pointer is set to the entry statement for the procedure. 4. If you supply no procedure_name and there is a QUIT signal or condition frame on the stack, the control pointer is set to the location being executed when the condition was signaled. 5. If you give no procedure_name and there are no condition frames on the stack, the last line executed in the most recent frame is used (this is usually the command processor). Information about programs being debugged is stored by probe in your home directory in a segment called Person_id.probe, where Person_id is your log-in name. This segment is created automatically when needed. Don't delete it because probe will be unable to reset any breaks it has set 3-683 AG92-()6 probe probe RESTRICTIONS ON INPUT LINES A probe input line cannot contain unbalanced parenthesis or quotes. This means that a request or request list must fit on one line. It cannot contain a newline character. If a long line must be typed, the Multics escape convention of placing a backslash before the newline can be useci If the newline character is needed (in a character string constant, for example), the escape sequence (\012) can be entered instead. PROBE REQUESTS The following pages present the format and function of each probe request. gtVtng the name of the request, any abbreviated form. and its arguments (required and optional). Optional material is enclosed in braces. Each request that takes arguments is shown with examples of its use. Examples may be in the syntax used for PL/I, FORTRAN. or COBOL. If an example does not make sense to you. it may be in another language. The following items are used throughout the requests section: CROSS-SECTION Probe provides cross-sections to allow reference to more than one element of an array at a time. To reference the ith through jth elements of an array, the cross-section reference is i:j (for Pascal, Lj). The asterisk (*) is used to reference all elements of an array. EXPRESSION Probe expressions are made up using the arithmetic operators + (addition), (subtraction). * (multiplication), and / (division). Precedence of * and / over + and - is used in evaluating, and parentheses are used to alter the order of evaluation. COBOL "abbreviated" expressions are not supported. LINE identifies a location in an object segment and possibly the source line associated with that location. A LINE can be a label known in the current procedure, the name of an external entry. a line number in the source file for the current procedure, $b (which denotes the current break), or $c (which denotes the current line). Source line numbers consist of a source file number and a line number. The file number is optional; if not specified, the main file (file 0) is used. You can find file numbers by examining the compilation listing. The first include file is file number 1. and so 00. The second part of a source line number is the actual line in the file. This number is found printed on the left edge of a compiler listing. It is also the number you would use with an editor. 3-684 AG92-o6 probe probe Note: Since FORTRAN labels are numbers, which probe also uses to specify line numbers, FORTRAN labels must be preceded by a dollar sign; for example, "100" is a reference to line number 100, but "Sl00" is a reference to the line whose label is 100. COBOL allows the use of labels that look like numbers. When a number is used for a LINE, it refers to a source statement line number, not a label. But if the number is preceded by a dollar sign, it is treated as the name of a paragraph label. N, M are positive, unsigned integers. OBJECT is a path name or reference name of an entry point into some object segment PATH Some probe requests accept a Multics pathname as an argument If a PATH contains characters other than the letters of the alphabet, the digits 0-9, or the characters ">", "<", ".", ",", "-", "_", "$", "I", it must be enclosed in quotes. REGEXP is a qedx regular expression. For details, see the qedx command. REQUEST is any probe request (or list of requests). STRING Probe recognizes character strings and bit strings. You can use the quote character and the apostrophe (for FORTRAN and Pascal) to delimit the string. The maximum length of a string is 256 characters. Strings can contain any character. To enclose the quote character in a string, double it; for example, "a""b" represents the string a"b containing a single embedded quote character. LISi OF BASIC REQUESiS arguments, args Usage: args args N args OBJECT displays the names and values of the arguments to the current procedure or a specified procedure invocation. If you supply N, stack level N is used. If you give OBJECT, the last stack frame for the procedure OBJECT is used. 3-685 AG92-()6 probe probe handlers Usage: - handlers handlers N handlers ORTECT displays the condition names and actions of the condition handlers established by the current procedure or a specified procedure invocation. If you give no N, stack level N is used. If you supply OBJECT, the last stack frame for the procedure OBJECT is used. Information about a handler is printed in the following format on CONDITION_NAME {(FILENAME)} {snap} ACTION where ACTION is one of the following: call PROCEDURE~NAME begin block at line N system help {TOPIC} Usage: help help * help TOPIC prints information about probe. If you invoke it with no argument, it prints general information about probe; if the argument is an asterisk, it prints a list of all topics for which info exists; otherwise it prints information about TOPIC. 1et, 1 Usage: I VARIABLE = EXPRESSION I CROSS-SECTION = EXPRESSION sets the specified variable or cross-section of array elements to the value of the expression (see "Syntax of a Variable" below). If the variable and expression are of different types, conversion is performed according to the rules of PL/I. Array cross-sections are expressed as in the value request. One array cross-section cannot be assigned to another nor can structures be assigned to as a whole. Certain data types cannot be assigned to any type other than their own (e.g., area, file). Note that because of unpredictable compiler optimization, the change sometimes may not take effect, even though the value request shows that the variable has been altered. list_builtins, lb prints a summary of ali buiitins and their meanings (see ;;Probe Buiitinsn below). 3-686 AG92-06 probe probe 1 is t_he 1p, 1h prints a summary of all probe topics for which there is an info. list_requests, lr prints a summary of all probe requests. list_variables {NAME}, lsv {NAMES} lists all variables that have been declared by the "declare" request in the current invocation of probe, along with their types and values. If you supply one or more NAMEs, only those variables are listed; otherwise, all defined variables are listed. quit, q returns the current level of probe. If there is more than one invocation of probe on the stack, you may still be in probe, although at a lower level; if there is only one, quit returns to command level. stack, sk Usage: sk {{M ,} N} {all} {Iong} displays your stack, showing block names and line numbers (if known) last executed in each frame, and conditions raised. Each fra.rne is displayed with a number, which is the "level number," and used in various requests to indicate a stack frame. This request traces the stack backwards and displays the first N frames. If you don't supply ~Y1, the highest numbered frame is the first frame displayed, otherwise the Mth frame is the first displayed. If you don't give N, all frames are displayed and you can't specify M. If you supply long. the following information is printed for each frame: block name, offset within the component, line number (if known), segment pathname, and offset within the segment. If you don't give long, only the block name and the line number (if known) are printed. If you specify all, "support" frames are included in the trace; they are skipped by default (See "Notes on Support Frames" below.) Examples: sk sk 3 displays the whole stack. displays three frames starting with the current one. symbol VARIABLE {long}, sb VARIABLE {long} displays the attributes of the variable specified and the name of the block in which it is declared. If the size or dimensions of the variable are not constant, an attempt is made to evaluate the size or extent expression; if the value cannot be determined, an asterisk is displayed instead. If "long" appears after the name of the identifier and if the identifier is a PL/I structure or COBOL record, the attributes of all members of the structure or record are displayed as well. 3-637 AG92-D6 probe probe value, v Usage: v EXPRESSION v CROSS-SECfION displays the value of the given EXPRESSION or the array elements specified by CROSS-SECfION. EXPRESSION can be a simple variable name or a more complex expression. You speciiy a CROSS-SEeltON by gIVIng me upper ana lower bounds oi one or more subscripts. You can use an asterisk, which is equivalent to a cross-section from the lowest to highest subscript of an array. For example: value value value value arr (1:5, 3:7) p -> a.b(j) a of b of lrec ijptr ()'(,3) You can use the value request with PL/I structures-but not areas--or COBOL records, in which case the value of every component is displayed as well. You can call external functions with the value request The argument list can involve arbitrary expressions, and the arguments are converted to the proper type if the called function specifies what type of arguments are expected. Under your control, the value request can print identifier names in short or long form (see the modes request). This request causes probe to identify itself by printing "probe" and the current version number on the terminal. It may be used, for example, to determine if a called routine has returned. If the current invocation of probe is not the first invocation of probe on the stack, the recursive depth is also printed. The version number is useful for determining whether the version of probe being used has certain features or bug-fixes. It should always be included in any trouble report about probe. COMMAND_LINE This request passes the COMMAND_LINE directly to the Multics command processor. It can never be used in a break request list or a conditional execution list. When used, it must be the only request on the line. NOTES ON SUPPORT FRAMES Support frames are frames that belong to a support procedure. A support procedure is a system utility that performs action directly related to the compiled user code (for example, allocation) and in which there is a high probability that any errors that arise are due to improper use by the user (allocating in a full area). When conditions arise in support frames, the standard Multics error handler attributes the error to the user ..... _ri,... ...,vu~ +1.... .... + LHaL ...... n 11 ...... ri ,-au,""", +"'" '" ;'UpPVl ""' .........""',.... ... +I. LU~ ....,.... "',...b.,:I'I1I ... .ft PIV\,f\A4Ul'-, ... ""+ ...... ,..... lal..U\.fl 3-688 ...""..,..... I..uau ... ...... " LU'- .... 'I'I ...... ~_.. "'UpPUl L. "',.,I"JI,.,\I" ..... ,., PIV\.f",,",Ul\.f. ........ AG92-o6 probe probe The probe "stack" request does not display support frames unless invoked as "stack all." Support frames are given incremental numbers between those of the surrounding frames (6.1. 6.2•...• 6.11, .. .). LIST OF SOURCE REQUESTS The source pointer is used to indicate a block in a program (to resolve variable name conflicts), a stack frame (to resolve separate invocations of a block). and a statement (to be printed). You can display its value with the where request. can change the value with the position or use request. and can print the source line pointed to with the source request. position. ps sets the source pointer to the statement specified, and prints the statement (see the use request). source, sc Usage: sc {N} sc path PATH The first form prints source lines of the current procedure, beginning with the current source line. If you omit N, then one statement is printed. The source pointer remains unchanged. A statement can take up many lines, and there may be blank lines (or nonexecutable source lines, such as comments or declarations) between statements. Although you can set the source pointer only to a line for which code is generated, you can display these extra lines along with the statements. If N statements are displayed, any nonexecutable lines between the first and the last are also displayed. The second form gives the pathname of the source segment for the current procedure. Multics object segments contain within them the absolute pathnames of the source segments used to compile them. Sometimes these segments have been moved by the time the object segment is being debugged, and when probe wants to locate them, it fails. When it does, it informs you that the source cannot be located; in that case, give the path of the source after the path argument. If you give no PATH, the source segment used is either the one you originally compiled the program from or the first segment with the appropriate name (NAME.pll, NAME. fortran, etc,) found using the probe search paths. If no source segment can be found, probe is unable to print source lines. use sets the SO'jrce pointer to the statement specified. Unlike the position request, use does not prints the source line positioned to. You can use this request in any of the following forms: 11/86 3-689 AG92-06A probe probe use with no argument, source pointer is reset to initial value (same as control pointer). use LINE specifies a line in the current procedure. use +N specifies the statement N statements after the current one. use -N specifies the statement N statements before the current one. use line +N specifies the statement N lines after the current one. use line -N specifies the statement N lines before the current one. use level N specifies the last line executed in the block at stack level N. use level +N specifies the last line executed for stack level (this + N). use level -N specifies the last line executed for stack level (this - N). use OBJECI specifies the last line executed in the most recent invocation of OBJECT. use STRING specifies the next statement containing the literal string. use /REGEXP / specifies the REGEXP. next statement that matches the qedx regular expression It is possible to set the source pointer only to an executable statement Every language has nonexecutable statements, for example, blank lines, comments. and declarations. (See the where request and "LINE. n) 3-690 AG92-Q6 probe probe In PL/I, names, including labels, are not known (available for probe) when the source pointer is outside the block in which they are declared. This means that probe cannot find a label in an internal procedure or begin block unless that block is now the "current block". The label can still be found by a search for a character string that appears in the labeled line, for example, "label". The source segment used is either the one you originally compiled the program from or the first segment with the appropriate name (NAME.pll. NAME. fortran. etc.) found using the "probe" search paths. If no source segment can be found. probe is unable to print source lines. where, wh displays the values of the probe pointers. If invoked with no arguments, it displays the values of the source and control pointers. The following are also allowed: wh source, wh sc prints the value of the source pointer. wh source path, wh sc path prints the pathname of, the segment referenced by the source pointer (i.e.• the source segment currently in use). wh control, wh ctl wh object prints the value of the control pointer. wh control path. wh ctl path wh object path prints the pathname oi the segment reierenced by the control pointer (i.e.• the current object segment). wh path prints pathnames of segments referenced by the source and control pointers. NOTES ON BREAKPOINTS A breakpoint is a list of one or more probe requests associated with a source statement. When the statement of a breakpoint is executed. the user program is suspended and probe executes the requests associated with the breakpoint. When the requests of the breakpoint have executed. the program resumes (unless one of the requests is a "quit". "halt" or "goto"). A breakpoint can be set "before" or "after" a given iine. The difference is that a break before a line is executed immediately before the line is executed. and a break after a line is executed after the line has been executed. Theref ore if a transf er is made at line X of a program. a break before line X is executed. but a break after line X is not. If a transfer is made to the statement on line X. a break set before line X is executed. but one set after line X-I is not If statement X assigns a new value to a variable. a break set before X is executed before the variable changes. but one after X takes effect after the variable has been changed. 3-691 AG92~ probe probe No breaks can be set after any COBOL statement due to restrictions of the compiler. Multiple requests in a breakpoint request list are separated by semicolons. A breakpoint list of more than one request must be enclosed in parentheses; for example: b 495: (v x (1) ; v y (1) ; stack 3) which invokes the "before" ("b") request to set a break at line 495 consisting of the three requests "v x(1)", "v y(1)", and "stack 3". Note that the "if" request for writing .......... _~~+; __ .. 1 l........ 1, C1 b '-'VIIUl"lUllC11 495: if Ul'-'CLA ~""~ "'~ ... "",. llV," x (1) work r reset every break probe can find. reset the break after the first statement after the line labelled "259". reset all breaks in the current procedure. reset all breaks in procedure named. st displays line numbers of breaks and optionally the break request list. You can use it in one of the following forms: status~ st displays all breaks in the current procedure. st LINE displays break at LINE in current procedure. st OBJECT displays all breaks in procedure OBJECf. s t -all displays all breaks set by you in all procedures. st 1< displays the pathnames of all procedures with breaks set by the you. The break request list of the break is displayed by default for status LINE and omitted for all other forms. The -long control argument prints the break list; -brief suppresses it. As for "reset," you can distinguish a break before a line from a break after a line by prefacing the LINE with "before" or "after." Examples: st st st st >udd>m>my_seg 35 -lg b 7 -all lists all breaks in my _seg. prints the list of breaks before and after line 35. lists only the break before line 7. lists all segments in which breaks have been set. REQUESTS USEFUL IN BREAKPOINT REQUEST LISTS halt, h invokes a new probe command level, with the control and source pointers set to the line of the breakpoint. This is the default break request After a subsequent continuation, probe resumes interpreting the break request list that contains the halt When the list is empty, your program is resumed. This request has no effect when typed at probe command level. If a break is set with no break request list supplied by you, halt is assumed. 3-694 AG92-()6 probe probe Example: b12:if K>O:h (va; h; v a) this breakpoint stops if K>O. this list displays the value of a before and after stopping. pause, p is like halt in that it suspends execution of the breakpoint request list and causes probe to read from the terminal; unlike halt, when the breakpoint is continued (by the continue request), the break is immediately reset The effect is a one-time-only temporary break. This request is used to implement the step and continue_to requests. FLOW OF CONTROL REQUESTS Requests are provided for selected execution of program statements. The user can resume execution after a break, call external procedures, or perform explicit "goto"s. continue, c restarts a program that has been suspended by a probe breakpoint If this request is used in any other context, probe returns to its caller, which is usually command level. continue_to LINE, ct LINE inserts a temporary breakpoint before the LINE specified. then continues. effect is as if the user had typed the following: The before LINE: pause continue When the user resumes after a temporary break, it is automatically reset call OBJECT (ARGUMENTS), cl OBJECT (ARGUMENTS) calls the external procedure named with the arguments given. ARGUMENTS should be a list of arguments to the called procedure, separated by commas. If the procedure expects arguments of a certain type, those given are converted to the expected type. The value request (see above) can be used to invoke a function, with the same sort of conversion occurring. If the procedure has no arguments, an empty argument list "0" must be given. Examples: PLl: call sub ("abcd ll , p -> p2 -> by, 250, addr(k» COBOL: call eat-master (a of b of new-unit, REC-LEVEL) FORTRAN: call gamma (43, marigold (i), substr (cs,3» goto LINE, g LINE leaves probe and resumes execution of your program at LINE. 3-695 Don't use this AG92-()6 probe probe request if the LINE is in a program that is not active. Because of unpredictable compiler optimizations, this request may be dangerous if you compile the program with -optimize. Examples: 9 label var 9 action (4) transfer to value of label variables. transfer to value of label constant 9 110 9 $110 9 $c, 1 transfer to line with label 110. transfer to the statement after the current one. step s tries to step through the current program one statement at a time. If the program has been stopped before line N, a break is set before line N+1. If you are stopped after line N, the break is set before line N+2. These breaks contain "~~~' _ as tq~jrS9le _ _ request _listancjthus are self ..resetting. If _the statements being stepped do no{- execute iOn sequence, --thestepPlngmay---be unsuccessfuL----PL./I and FORTRAN do-loops and conditional statements in all languages do not execute sequentially. CONDITIONAL REQUESTS if PREDICATE: REQUEST evaluates its PREDICATE argument If the result is true, REQUEST is executed, otherwise it is skipped. This request is useful in break request lists, where you can use it to cause conditional breakpoints; for example. to stop whenever the variable "odin" equals I, the break request list can include "if odin = l:halt". while PREDICATE: REQUEST repeatedly executes REQUEST, testing the conditional expression PREDICATE before each execution. REQUEST can be a single request, or several probe requests, enclosed in parentheses and separated by semicolons. REQUESTS TO CONTROL PROBE You can manipulate probe's behavior in a few ways: you can control the length of error messages and the amount of printing done by breaks and by the value request; you can specify explicitly the current language; you can control the streams used by probe for input and output. Unlike other requests, the effects of input_switch, output_switch, input_description and output_description are static to the process and remain from one probe invocation to the next until reverted. 3-696 AG92-G6 probe probe input_description, ids takes an attach description and creates an loeB. then makes probe read all its input from this IOCB until further notice. The IOCB is destroyed the next time input_description or input_switch is invoked. Example: ids tty_ stereo_console causes further input to be read from the device stereo_console. input_switch {SWITCH}, isw {SWITCH} causes probe to take all further command input from the switch named. SWITCH is the name of an already-attached IOCB. If you supply no SWITCH, user_input is used. If there are any other requests in the input line or break request list that contain this request, they are ignored without comment Input is read from the switch until either a new input_switch request is read or all available characters are processed, in which case a message is printed and input is reset to user_input. If any errors occur, input is reset to user_input. SWITCH must be attached and open before you give this request language {LANG}, lng {LANG} given the name of one of the languages supported by probe, sets the current language mode; otherwise displays the name of the current language mode. Names accepted are: pll, fortran. ft, cobol, and algol-68. modes {MODE VALUE}, mode {MODE VALUE} sets various modes internal to probe that change the way it functions, where MODE is the name of the mode to set. and V ALUE is the new value. A mode is a probe variable that specifies how a particular function behaves. The values of all modes can be displayed by using "modes" with no arguments. If you set conflicting modes, the last one in the request determines the setting of the mode. If you give no arguments, the current modes are printed. Most modes can be set to a value that is either a LENGTH or a BOOLEAN. A LENGTH is "long" (Ig). "short" (sh) or intermediate, or "brief" (bf) and is used to specify the amount of printing to be done by probe; in some cases, "short" is synonymous with "brief". A BOOLEAN is used to turn a feature on or off and can be "yes", "on", or "true" or "no", "off", or "false". MODES can be any combination of the following: error_messages LENGTH, em LENGTH controls the length of the text used for an error message. (Default: long) 3-697 AG92-{)6 probe probe meter controls the printing of meter values when breaks are hit. The meter values are the number of minutes and seconds of real time ("TIME"). the number of seconds of virtual CPU time ("VCPU"). and the number of page faults ("PAGE FAULTS") since the last break was restarted or since "mode meter on." These values do not include any overhead from probe itself. Example: Stopped after line 37 of test_program Time = 3 min 42 sec, Vcpu = .057 sec, Page faults = 103 These values do no include any overhead from probe itself. output_description, ods takes an attach description and creates an IOCB. then causes probe to write all its output on this IOCB until further notice. The IOCB is destroyed the next time you invoke output_description or output_switch. Example: ods vfi1e_ probe_trace.output writes further output to the segment probe_trace. output output_switch {SWITCH}, osw {SWITCH} with no argument, writes probe output (except for error output) on the default switch. user_output; otherwise. writes nonerror output on a specified switch. SWITCH is the name of an already-attached IOCB. prompt BOOLEAN controls whether or not probe prints a prompting string on your terminal when it is listening for a request (see "prompt_string"). (Default off) prompt_string STRING specifies the string to be used "probel'l [(!"d)I\] ". STRING is used argument is a bit (1) that is on recursive and the second argument is for prompting. The initial value is in a call to ioa_$nnl, where the first if the current invocation of probe is the current probe depth. qualification LENGTH, qf LENGTH controls the format of variables names as printed by "value": for brief. prints only the last name of a structure (default); for long, prints names with full qualification. COBOL and FORTRAN are always printed briefly. regardless of the value of this mode. truncate_strings truncates character and bit string values to 200 characters or bits. printing " " at the end if the string is longer than 200. (Default on) value_print LENGTH, vp LENGTH controls whether or not the value request prints the name of a variable: for brief. names are never printed; for short, names of array and structure elements are printed (default); for long, names are always printed. 3-698 AG92-o6 probe probe value_separator STRING, vs STRING controls the string printed by the value request between the name of a variable and its value. Only the first 32 characters of STRING are used. (Default: "=") MISCELLANEOUS REQUESTS declare, del Usage: del NAME TYPE {-force} {external} {defined EXPR} creates new probe variables and declares external variables. NAME is the name of a new variable to be created or the name of an external variable if you supply external (ext). TYPE is a keyword specifying the type of the variable. If you don't give external and a variable named NAME already exists, you are queried whether to delete the old one. The -force (-ic) control argument deletes the old one in this case without a query. There are four possible values for TYPE: The first is equivalent to PL/I fixed bin (35), Fortran or Pascal integer, and COBOL comp-6; it can be referred to as fixed, integer. int, or comp-6. The second is equivalent to PL/I float bin (27) or Fortran real; it can be referred to as float or real. The third is equivalent to PL/I aligned pointer (Multics ITS ptr); it can be referred to as pointer or ptr. The fourth is PL/I unaligned (packed) pointer; it can be referred to as "pointer unaligned" or "ptr unal". If you give "defined EXPR". where EXPR is a variable expression designating a region of storage having one of the above TYPEs, NAME becomes a synonym for that region. This feature allows you to use a short name in place of a complicated expression. You are warned about a name conflict if a program variable of the given NAME is known in the current block when the variable is declared. If this warning is given, you must refer to the variable with a percent sign before its name to distinguish it from the program variable. Examples: del del del del gravel eomp-6 clover ptr -force sys_info$max_seg_size fixed -ext axi fixed defined info_ptr -> aregs (i) .x.index 3-699 AG92-06 probe probe display, ds Usage: ds {*} ADDRESS {FORMAT} {COUNT} displays an arbitrary location in a selected formal The location displayed depends on the type of ADDRESS supplied. If ADDRESS is a reference to a VARIABLE, the address of the V ARIABLE is the location displayed. Otherwise, ADDRESS must be an expression that evaluates to a pointer; the value of the expression gives the location to be displayed. If an asterisk appears before a pointer VARIABLE, data pointed 10 by L~e pointer's value is displayed. FORMAT can be one of the following: ascii, character, ch N is the number of characters dumped. A non-printable character is printed as "" binary, bin, binary35, bin35 N is the number of fixed binary (up to 35) values dumped. binary71, bin71 N is the number of fixed binary (36 to 71) values dumped. bit, b N is the number of bit strings dumped. code prints the error message associated with a status code. float, f, float27, f27 N is the number of float binary (up to 27) values dumped. float63, f63 N is the number of float binary (28 to 63) values dumped. instruction, i N is the num ber of instructions dumped. If the instruction has descriptors, they are dumped with the instiuction. octal, 0 N is the number of (36 bit) words dumped. po inter, ptr, its N is the number of ITS pointers displayed. COUNT is the number of elements displayed; the default is one. The size of an element depends on the format displayed. One pointer is 72 bits (two words), and one instruction can be as many as four words (for an EIS instruction). 3-700 AG92-o6 probe probe Examples: ds * 2531 100 octal 20 ds foo asci i 64 ds iplO i ds error_code code dump 20 words in octal, pointed to by 2531100. display the first 64 characters of foo. dump current instruction. displays error message for status code value assigned to error_code variable. execute STRING, e STRING passes the quoted STRING to the Multics command processor. It is useful in break request lists because the more convenient "" escape to the Multics command processor is not available there. Example: e IIjoa_ IIlIstopped at a break 111111 object {N}, obj {N} displays the assembly instructions for the current source line. or for the next N source lines. SYNTAX OF A VARIABLE Variables can be simple identifiers, subscripted references, structure qualified references, and locator qualified references. Subscripts can also be expressions. Spaces are significant in the names of FORTRAN and COBOL names. A FORTRAN name cannot contain embedded spaces. Case is insignificant in COBOL names in FORTRAN names when the object segment was compiled with either "-fold" or "-card". Examples: COBOL: data-elem log-type of gen-record (3) gen-record.log-type(3) PL1: ignat2 (p -> lemma - 3) PASCAL: arraypA.first [6,2] The block in which a variable reference is resolved is normally determined by the source pointer, but can be altered by providing a different block in brackets after the variable name. A block can be specified in the following ways: 3-701 AG92-D6 probe probe Example: level N the block and frame at level N. the Nth previous invocation of the current block. -N LINE the block that contains LINE, in its most recent invocation. the block named. It can be internal to the current proce.dure or externaL OBJECT WARNING: Specifying a block explicitly does not change probe's "current language". It is possible that the block named is in another language than the current block. Even if this is so, data is referenced in terms of the current language. SYNTAX OF A CONSTANT The attributes of a constant are determined by the appearance of the constant Probe reeogniies arithmetic constants (fixed or floating point, binary of decimaI). string constants (character or bit), and pointer constants. The maximum length of a string constant is 256 characters. You can enter bit constants in any radix from binary to hex. You can enter integers in octal by following them with a lower case "0". FORTRAN double-precision constants are not implemented. Probe pointer constants are of the form SSS IWWW or SSS IWWW{bbb), where SSS is the segment number in octal, WWW is the word offset in octal, and bbb is the bit offset (optional) in decimal. You can replace SSS with a two-letter code to specify a pointer relative to the current stack frame (sp). linkage section Up), text segment (tp) , or instruction (ip). Examples: -123 lOb 45.37 4.73elO 4.2lflO 2.1-0.3i 123456700 "abc" "quote"llinstring" 11010"b IFA07"b4 11222"b2 25611200 232 7413 (9) true 'Nix Olympia' 1230 fixed dec (3) fixed bin (2) fixed dec (4,2) float dec (3) fixed dec (3, -8) comp 1ex dec i ma 1 (2, 1) fixed bin (24) entered in octal character string character string with embedded quote binary bit string hexadecimal bit string quatenary bit string pointer pointer with bit offset FORTRAN logical constant FORTRAN string constant fixed bin (35), octal integer, value is 83 decimal 3-702 AG92-06 probe probe Specify the segment number and word offset of a pointer in octal, but any bit offset in decimal. PROBE BUILT-INS Many built-in functions are provided. They can be referenced as if they were external functions. but if no argument is needed. then you can omit the argument list You can use substr and unspec as pseudo-variables. addr (A) addre 1 (p, N) baseptr (N) 1ength (5) max 1ength (5) null 0 octa 1 (N) ptr (P, N) re 1 (P) segno (P) subs tr (5, N) unspec (A) A stands for any reference to storage. N for any expression that yields a number, P for any expression that yields a pointer value, and S for any expression that yields a string. All probe built-ins, except "segno" and "ptr", are equivalent to the Multics PL/I built-ins. The ptr built-in is like the Multics PL/I ptr built-in, but you can also supply it with a bit offset after the word offset The segno built-in is like the Multics PL/I baseno built-in, but its result is an integer instead of a, bit string. The probe command reads numbers in decimal, so a reference to "baseptr(64)" is the same as "baseptr(1000)". You can preface built-ins with the dollar sign to distinguish them from program variables of the same name. Assume that the following declarations are more or less equivalent, that cs has the value "abcdef ", and that i is 2: PL 1 : dcl i fixed bin; dc 1 cs char (8); FORTRAN: integer i char~(8 cs COBOL: 77 i usage is comp-6. 77 cs pic a (8) • 3-703 AG92-()6 probe probe addr (j) v substr (cs, i, 3) let substr (cs, 4, 1) v length (cs) value maxlength(cs) v baseptr (2540) = II the address of i. displays "bed". sets cs to "abc efn. displays 8. also displays 8. displays 2541 o. II LIST OF PROBE TERMS active a procedure is said to be active if its execution is ongoing or suspended by an error, quit signal. breakpoint. or call. An active procedure is distinguished from one that has never been run. has completed execution or has been interrupted and aborted by a Multics release command, in that an active procedure has at least one stack frame associated with it automatic storage a·· ·storage-·'class for which-· space·· is allOcated dyriiriiically in ·a· stack . frame upOn··· block invocation. As a result, variables of this class only have storage assigned to them, and hence a legitimate address and value, when the block in which they are declared is active. PL/I variables, by default, belong to this class. FORTRAN variables must appear in an "automatic" statement in order to belong to this class. block corresponds to a PL/I procedure or begin block or FORTRAN program or subroutine. and identifies a particular group of variable declarations. breakpoint a point at which program execution is temporarily interrupted and probe requests executed. invocation when a procedure is called recursively, it appears on the stack two or more times. and has storage allocated for it the same number of times. Each instance of the procedure on the stack is considered a separate and distinguishable invocation of the block. The values of automatic variables can be different in different invocations of the same block. The most recent invocation is the topmost in stack trace. level number an integer used by probe to uniquely designate each block invocation (i.e., each entry in a stack trace). Level one is the first (least recent) procedure invoked. Level number is NOT necessarily the same as either of the numbers given after the word "level" in a ready message. The first of this pair gives the count of command levels in effect and gives the value N+ 1, where N is the number of programs (or groups of programs) whose execution has been suspended, the second gives the number of stack frames in existence and since the probe stack includes quick blocks. this number is less than or equal to the level number of the last command level in the stack trace. 3-704 AG92-()6 probe ,robe quick block internal procedures and begin blocks that satisfy certain requirements (e.g.• are not called recursively, do not contain on. signal, or revert statements, etc.) have their automatic storage allocated by the blocks that call them. Hence. they do not actually have their own stack frames, but share the one of the caller. Certain system commands. such as trace_stack. ignore these blocks. The probe command, however, includes them in a stack trace and treats them as if they were the same as any other blocks. You can determine the quickness of a block from a program listing containing information about the storage requirement of the program (produced with the -list, -map, or -symbols control arguments). For example, procedure "quick" shares stack frame of external procedure "main." stack if a procedure A calls another procedure B, the execution of A is suspended until B returns. If B in turn calls C, this is an ordered list of procedure or subroutine calls indicating which program called which other program, and which returns to which. This ordered list is called the "stack. n In probe, you can display a trace of the stack with the stack request. The list is given in top-down fashion with the most recently called procedure listed first. 3 c 2 1 B A The numbers are level numbers. stack frame when a block is invoked (that is, a procedure is called or a begin block is entered), storage is allocated for its automatic variables. The area allocated is called a stack frame, and logically corresponds to each en try in the stack. statement map a table in the symbol section of an object segment that relates locations in the text section (executable mode) to source line numbers. This table is produced by a language translator when you specify -table or -brief_table. static storage a storage class for which space is allocated time the procedure is first referenced. As a have a legitimate address and value. Regular common block, have static storage. You must once per process, effectively at the result, variables of this class always FORTRAN variables, and those in a explicitly declare PL/I variables. support procedure a system utility routine that provides runtime support for other procedures (e.g., the procedure that allocates storage as requested by a PL/I allocate statement). symbol table a table in the symbol section of an object segment that contains information about the variables (symbols) used in the program. A symbol table is produced by a language translator when you give the -table control argument. 3-705 AG92-06 probe probe SUMMARY OF REQUESTS 11/86 Request Abbrev Function after arguments before call continue continue_to declare a args b cl c ct dcl display execute goto halt handlers help if- ds e g h input_description ids input_switch language let list_ buil tins list_help list_requests list_variables isw lng sets a break after a statement. prints arguments to current procedure. sets a break before a statement. calls an external procedure. restarts after a breakpoint. inserts a temporary break and continues. creates probe variables, declares external variables. displays storage in a selected format. passes string to the command processor. transfers control to a statement. in break text, establishes a probe level. displays condition handler information. prints information about probe. executes probe requestsi-f- condition is true. creates an IOCB and causes probe to read all its input from it. reads probe requests from switch. sets probe language. assigns a value to a variable. prints a summary of probe builtins. lists probe topics for which there is info. prints a summary of probe requests. lists all variables that have been deciared by the "declare" request. controls probe's behavior. displays assembly instructions. creates an IOCB and causes probe to write all its output on it. directs probe output to a switch. stops a program once. sets the source pointer. returns from current probe invocation. deletes breaks. prin ts source lines. traces the stack. lists breakpoints. advances one statement and halts. displays attributes of a variable. sets source pointer. displays value of an expression. displays value of probe pointers. executes commands while condition is true. causes probe to identify itself. escapes to command processor. I lb lh lr Isv modes object ou tpu t_description mode obj ods output_switch pause position quit reset source stack status step symbol use value where while osw pa ps q r sc sk st s sb u v wh wI 3-706 AG92-06A Name: process_dir, pd SYNTAX AS A COMMAND pd SYNTAX AS AN ACTIVE FUNCTION [pd] FUNCTION returns the pathname of the process directory of the process in which you invoke it Name: process_switch_off, pswf SYNTAX AS A COMMAND pswf switch_names FUNCTION turns off specified per-process switches. ARGUMENTS switch_names are the names of per-process switches. LIST OF SWITCHES 256k_switch, 256ksw, 256k allows 256K segments, currently used by FORTRAN programs, to hold very large arrays. 3-707 AG92-()6 profile SYNTAX AS A COMMAND pswn switch names FUNCTION ARGUMENTS switch_names are the names of per-process switches. LIST OF SWITCHES 256k_switch. 256ksw, 256k allows 256K segments, currently used by FORTRAN programs, to hold very large arrays. Name: profile, pf SYNTAX AS A COMMAND pf {program_names} {-control_args} FUNCiiON analyzes the time spent executing each source statement of a program, along with other parameters of interest, after the program is run. ARGUMENTS program_names are pathnames or ref erence names of programs to be analyzed. Any program name that does not include "<" or ">" characters is assumed to be a reference name. You need not specify them if you use -input_file. CONTROL ARGUMENTS Apply to all programs specified and can be given in any order. -brief, -bf use it with -print to exclude from the output all information for statements that have never been executed. (Def ault) 3-708 AG92-06 profile profile -comment STR, -com STR use it with -output_file to include STR with the stored profile data as a comment Yo~ can a® use it with -plot Enclose STR in quotes if it contains blanks or other special characters. STR can be up to 128 characters long. -first N, -ft N use it with -sort to print only the first N values. -from N, -fm N use it with -print or -plot to begin the output with the data for line number N. (Default: 1) -hardcore. -hard indicates that the specified programs are supervisor (hardcore) segments. The current (internal static) profile data for such programs is retrieved from the address space of the supervisor. Install hardcore programs compiled with -profile or -lonLprofile by generating a Multics system tape and rebooting Multics (see generate_mst). You cannot reset (zero) the current profile data for hard core programs. This control argument and -reset are mutually exclusive. -input_file path, -if path retrieves the profile data from the profile data file (pfd) specified by path. This control argument ignores any current profile data. The pfd suffix is appended to path if it is not already present If you supply any program_names, they select a subset of the stored data for analysis; if you give none, all data stored in the profile data file is used. This control argument is inconsistent with -output_file and -reset -line_length N, -11 N use it with -list to specify an output width of N characters. (Default: 132) -list. -Is creates a profile listing for all specified programs. The profile listing file (pfl) is given a name consisting of the first program name with the language suffix replaced by the pfl suffix. It is placed in your working directory. The information described for -print is placed in columns to the left of each source line in the profile listing. -long. -lg use it with -print to include in the output information for statements that have never been executed. -max_points N. -mp N use it with -plot to specify the maximum number of points (line numbers) to be plotted (the graphics resolution). The Multics graphics system is capable of plotting up to 1024 points. (Default: 250) -no_header. -nhe use it with -print to suppress column headings. 3-709 AG92-06 profile profile -output_file path. -of path stores the profile data for the given program_names in the pfd specified by path. The file is created if it does not already exist and is overwritten if it does. The pfd suffix is added to path if it is not already present The profile data is stored in a format acceptable to -input_file. The format of pfd data files is described by the PL/I include file pfd_formatincl.pll. The stored data is determined by -comment, the program_names specified, and whether you did the compilation using -profile or -lonK-profile. The compiling program name is saved in the profile data file. If program_name slY'-eifies a bound object segment, profile data about each component of the bound object segment is saved. -plot STR plots a bar graph, on any supported graphics terminal, of the values of the specified field STR. STR can be any of the fields in the "List of Fields" section below. This control argument requires that your site has installed the Multics Graphics System and that you have executed the setup~aphics command. (See the Multics Graphics System, Order No. AS40.) -print, -pr prints the following information for each statement in the specified program(s): 1. Line Number 2. Statement Number if more than one statement on the line. 3. Count the number of times the statement was executed. 4. Cost an approximation to the accumulated execution time for the statement. Equal to the number of instructions executed plus 10 times the number of external operators called. 5. Stars (asterisks) an indication of the percentage of total cost (or time, for 10nK-profile data) used in the statement The number of stars is selected according to the following table: 4 stars: 3 stars: 2 stars: 1 star: no stars: one period: 20% to 100% 10% to 20% 5% to 10% 2.5% to 5% 0% to 2.5% Statement was not executed. 6. Names of all external operators called by the statement. 3-710 AG92-06 profile profile For -lon&-profile (actual accumulated time) data, item 4 is changed to the following: 4a. Time actual execution time for the statement in virtual CPU microseconds, including all time spent in any operators or subroutines invoked by the statement 4b. Average Time Time divided by Count (the average execution time for one execution of the statement). 4c. Page Faults page faults incurred in executing the statement -reset, -rs resets all current profile data for the named program (s). When specified, the resetting is done last if -print, -list, -plot, or -output_file is also given. -search~dir path, -srhd path use it with -hardcore to add path to an internal search list of hardcore object directories. You can supply up to eight directories. If you give no search list, >ldd>hard>o is searched for copies of the specified program(s). -sort STR use it with -print to sort in descending order profile information of the specified field STR. which can be any of the fields in "List of Fields." -source_dir path, -sed path use it with -list when the source segments to be listed have been moved from the directories in which they were compiled. If given, only the directory specified by path is searched f or source segments. -to N use it with -print or ~plot to end the output with the data for line number N. (Default: line number of the last executable statement) LIST OF FIELDS count the number of times the statement was executed. time the vpcu time of the statement (available if you compile the program with -lonLprofile). cost the approximate cost of the statement (available if you compile the program with -profile). 3-711 AG92-D6 profile profile page_faults (pfs) page faults taken during the statement (available if you compile the program with -lonlLprofile). NOTES If you supply no control arguments, the default ones are -print and -brief. Object 5eoIuents that of statement time. 19 hours Compile the program using cobol, fortran, and pU commands' -profile, or using pU's -Ions-profile. The latter is used to acquire exact elapsed time statistics and is much more expensive than -profile. When analyzing several runs of the same program(s) on various test cases, select ~reset. If y01Jgiv~no -reset, the _c~ITent profile data is accumulated (added) for all runs. If you supply several identical control arguments, only the last one is used, except for -search_dir. The current data acquired by programs compiled with -Ions-profile may have small perturbations due to asynchronous events outside the control of the data acquisition mechanism. Therefore. -lon~profile results are most reliable when obtained from long-executing programs or from multiple executions of the same program. The execution time for -Ions-profile programs can be up to 10 times as long as normal due to the overhead of acquiring CPU time and paging data from the supervisor. This overhead is subtracted from the current profile data before any further processing is done. There are two forms of profile data: current and stored. Current data is in a form suitable for direct incrementing by the program(s) being analyzed and is stored using the pU internal static storage class. Current profile data (except for hardcore programs) can be zeroed by -reset. Stored profile data is permanent data as stored by -output_file. The pfl's and pfd's are automatically stored as multisegment files if they are too large to fit into a single segment. This feature allows very-large bound object segments to be analyzed and very-large source segments to be listed. Profile data generated from statements in include files are printed only if you specify no -from or -to. Include file profile data cannot be plotted. Include files that generated profile data are listed after the main source program. If you give -source_dir, include files are searched for first in the specified source directory and then in the directory in which they are found when the program is compiled. 3-712 AG92-Q6 profile profile EXAMPLES The following command lines compile a PL/I program with -profile. execute the program once to acquire current profile data, and print the five most expensive statements. pl1 factorial -profile PL/I 24c factorial n n! 1 1 2 3 4 2 6 24 120 720 5040 40320 362880 3628800 5 6 7 8 9 10 profile factorial -sort cost -first 5 Program: factorial LiNE STMT COUNT 20 45 10 10 18 18 11 55 10 10 ------Totals: 144 COST STARS 1710 **'1dc 440 ,b'c* 220 *,'c 120 'Ie 50 OPERATORS call_int_other, return ca 11_i nt_th is caii_ext_out_desc return 2604 The following command line saves the current profile data in factorial.pfd. profile factorial -of factorial The following command line creates a profile listing in factorial.pfl from the source segment factorial.pll and the profile data file factoria1.pfd. The listing is prepared for a printer with only 50 columns. profile -if factorial -ls -11 50 The contents of the profile listing segment factorial.pfl is shown below. Profile information for a then clause has the same line number and statement number as the if statement. 3-713 AG92-()6 program_interrupt profile Profile listing of >udd>Work>Mann>r>faetoriai.pil Profile data file >udd>Work>Mann>r>factorial.pfd Created by Mann.Work.a on 12/11/84 1547.5 edt Tues Date: 12/11/84 1548.3 edt Tues Total count: 144 Total cost: 2604 COUNT COST STARS LINE SOURCE 1 /* Program to print a table of the first 10 factorials. */ 2 3 factorial: procedure; 5 declare n fixed binary (35); 6 declare ioa_ entry options (variable); 4 7 1 19 8 1 2 9 11 10 10 1 33 440 **'1, 50 10 55 220 10 120 10; 10 11 1710 ca 11 i oa_ ("AdA_Ad", n , fact (n»; end; return; ** 12 13 14 fact: 15 procedure (n) returns (f i xed binary (35»; 16 declare n fixed binary (35); 17 18 if n <= **** 20 * 19 45 ca 1 1 i oa (IInA- n ! ") ; do n = 1 to 21 then return (1); else return (n 'Ie fact (n - 1); end fact; 22 23 end factorial; Name: program_interrupt, pi SYNTAX AS A COMMAND pi FUNCTION informs a suspended invocation of an interactive subsystem that you wish to abort a subsystem request and reenter the subsystem. 3-714 AG92-D6 progress program_interrupt NOTES To abort a subsystem request, use the quit (break) key to interrupt execution and then issue program_interrupt If the subsystem supports the use of this command, it aborts the interrupted request and asks you for a new one; if it does not, the command prints an error message. You can then either restart the interrupted operation with the start command or abort the entire subsystem invocation with the release command. If there is more than one suspended command in your stack, the stack is searched for a program that supports program_interrupt and any intervening programs are released. Name: progress, pg SYNTAX AS A COMMAND pg {command_l ine} {-control_arg} FUNCTION executes a specified command line and prints information about how its execution is progressing in terms of CPU time, real time, and page faults. ARGUMENTS command_line is any string that is executable as a command line. If given, no control arguments to progress can appear on the same line except for -brief. * CONTROL ARGUMENTS * you can supply only one control argument -brief command_line. ~bf command_line prints only the message at completion of the specified command_line. -cput N prints incremental messages every N seconds of virtual CPU time. (Default: 10) -off suppresses the incremental messages printed during execution of a command line previously initiated, but does not suppress the message printed when that command line is finished (see "Notes on Output Messages" below). You can use -off to suppress messages while debugging. -on restores the printing of incremental messages during execution of the command line. 3-715 AG92-()6 progress progress -output_switch name, -os name directs output from the progress command to be printed on the I/O switch named name. (Default user_i/o) -realt N prints incremental messages every N seconds of real time instead of virtuai CPU time. NOTES ON OUTPUT MESSAGES After every 10 seconds of virtual CPU time (assuming the default triggering value is used), progress prints out a message of the form: ct/rt = pt%, ci/ri = pi% (pfi) where: ct is the number of virtual CPU seconds used by the command line so far. rt is the total real seconds used so far. pt is the ratio of virtual to real time used by the command so far. ci is the incremental virtual CPU time (since the last message). ri is the incremental real time. pi is ci expressed as a percentage of rio pfi is the number of page faults per second of virtual CPU time (since the last message). When the command line finishes, progress prints the following message: finished: ct/rt = pt% (pft) where: pft is the number of page fauits per second of virtual CPU time for the execution of the entire command. 3-716 AG92-06 qedx progress EXAMPLES In the following example, you want to see how execution is progressing for the compilation of a PL/I source program (named newseg.pll) using -list to the pll command. progress pl1 newseg -list PL/I 10/30 = 33%, 10/30 = 33% (26) 20/50 = 40%, 10/20 = 50% (17) 30/123 = 24%, 10/73 = 13% (20) finished: 33/150 = 22% (22) Name: qedx, qx SYNTAX AS A COMMAND FUNCTION The qedx editor is used to create and edit ASCII segments. This description * summarizes the editing requests and addressing features provided by qedx. Complete tutorial information on qedx is available in the qedx Text Editor User's Guide (CG40). ARGUMENTS macro_path specifies the pathname of a segment from which the editor is to take its initial instructions. Such a set of instructions is commonly ref erred to :;!~ a macro. The editor automatically concatenates the suffix "qedx" to macro_path to obtain the complete pathname of the segment containing the qedx instructions. The editor executes the qedx requests contained in the segment given and then waits for you to type further requests. If macro_path is omitted, the editor waits for you to type a qedx request. The archive component pathname convention (::) is accepted. macro_args are optional arguments that are appended, each as a separate line, to the buffer named "args" (the first optional argument becomes the first line in the buffer and the last optional argument becomes the last line). Arguments are used in conjunction with a macro specified by the macro_path argument. The editor executes the qedx requests contained in the segment selected and then waits for you to type further requests. If macro_path is omitted, the editor waits for you to type a qedx request 3-717 AG92-o6 qedx qedx CONTROL ARGUMENTS -no_rw_path prevents you from making read (r) or write (w) requests with a pathname. All read and write requests for buffer 0 affect the pathname specified supplied by -pathname. This control argument must precede macro_path and is intended to be used within exec_corns that are providing a limited environment; you are prevented from examining or altering segments other than the one used with -n!lthn!ltnP r .....&&&& ...& & & - · -pathname path, -pn path causes qedx to read the segment given by path into buffer 0, simulating "r path," before executing a macro (see macro_path). This control argument must precede macro_path. If no macro is given. you are placed immediately in the editor request loop. The archive component pathname convention (::) is accepted. NOTES Once the qedx editor is invoked, you can immediately begin to issue qedx requests from the terminal. Requests fall into one of two general categories: input requests and edit requests. Input requests place the editor into input mode and allow you to enter new ASCII text from the terminal until an appropriate escape character sequence is typed to switch the editor back to edit mode. Edit requests allow you to read and ~rite ASCII segments and perform various editing functions on ASCII data. Input and editing operations are not performed directly on the target segments but in a temporary workspace known as a buffer. You can create and edit any number of segments with a single invocation of the editor as long as the contents of the buffer are deleted before work is started on each new segment NOTES ON ADDRESSING Most editing requests are preceded by an address indicating the line or lines in the buffer on which the request is to operate. Lines in the buffer can be addressed by absolute line number; relative line number. i.e., relative to the "current" line (+2 means the line that is two lines ahead of the current line; - 2 means the line that is two lines behind); and context (locate the line containing /any s tr i ng between these s 1ashes/). The current line is denoted by a period (.); the last line of the buffer, by a dollar sign ($). An address can be formed using a combination of techniques (/foo/+5 means the line that is 5 lines ahead of the first line that contains the string "foo"). To designate a series of lines, two adresses must be given in the following general form: ADR1,ADR2 The pair of addresses specifies the series of lines starting with the line addressed by ADR1 through the lines addressed by ADR2, inclusive. When a comma is used to separate addresses, the address computation of the second address is unaffected by the 3-718 AG92-06 qedx qedx computation of the first (Le., the value of "." is not changed by the evaluation of the first address). However, if a semicolon is used to separate addresses instead of a comma, the value of n." is set to the line addressed by ADR1 before the evaluation of ADR2 begins. For example, the address pair label; .+10 is equivalent to the address pair /abe/,/abe/+10 NOTES ON REGULAR EXPRESSIONS The following characters have specialized meanings when used in a regular expression. A regular expression is the character string between delimiters, such as in a substitute request or a search string. You can reinvoke the last-used regular expression by giving a null regular expression (f f). signifies any number (or none) of the preceding character. when used as the first character of a regular expression signifies the (imaginary) character preceding the first character on a line. $ when used as the last character of a regular expression signifies the (imaginary) character following the last character on a line. matches any character on a line. LIST OF ESCAPE SEQUENCE REQUESTS \f exits from input mode, terminates the input request, and returns you to edit mode. It is used constantly when editing a document, and is the key to understanding the difference between the input and edit modes. \e suppresses the meaning of the escape sequence or special character following it. \b (X) redirects editor stream to read subsequent input from buffer X. \r temporarily redirects the input stream to read a single line from your terminal. 3-719 AG92-06 qedx qedx NOTES ON CURRENT LINE All editor requests that alter the contents of the buffer or cause information to be output on your terminal change the value of the current line (.). Usually, the value of "." is set to the last address used (either explicitly or by default) in the editor request The one major exception to this rule is the delete request, which sets "." to the line after the last line deleted. (If the line deleted was the last one in the buffer. then fl." is set to II $+ 1".) NOTES ON REQUESTS In the list given below, editor requests are divided into four categories: input requests, basic edit requests, extended edit requests, and buffer requests. The input requests and basic edit requests are sufficient to allow a user to create and edit segments. The extended requests give you the ability to execute commands in the Multics system without leaving the editor and also to effect global changes. You should learn the input and basic edit requests before the extended requests. The buffer requests require aknowledge-ofauxiliary---buffers~ - -(Since-the nothing- and comment requests are generally used in macros, they are included with the buffer requests.) The buffer requests, used with any of, the other requests, and special escape sequences allow you to make qedx function as an interpretive programming language through the use of macros. The following request descriptions contain a brief function. the request format, the default if no ADR is given. and the value of "." after the request is given. For the value of ADR, see "Notes on Addressing" above; for the value of regexp, see "Notes on Regular Expressions" above. LIST OF INPUT REQUESTS The editor can be placed in input mode with the use of the following input requests. The input request is followed by the literal text to be input in the buffer and can contain any number of ASCII lines. To exit from input mode and terminate the input request. the escape sequence \ f is typed, usually as the first characters of a new line. The \ f sequence can be followed immediately with other editor requests on the same line. append (a) appends lines typed from the terminal after a designated line. ADRa TEXT Format \f .a Default Value of " ft. Set to last line appended. 3-720 AG92-06 qedx qedx change (c) replaces the indicated line or lines with lines typed from the terminal. Format: ADR1,ADR2c TEXT \f Default: • , •c Value of " ft. Set to last line entered f rom the terminal. insert (i) inserts lines typed from the terminal before a specified line. Format: ADRi TEXT \f Default: ·i Value of " ft. Set to last line inserted. LIST OF BASIC EDIT REQUESTS delete (d) deletes specified line or lines from the buffer. Format: ADR1,ADR2d Default: • , •d Value of " n. Set to line immediately following the last line deleted. print (p) prints designated Hne or Hnes on the terminal; special-case print needs address only. Format: ADR1,ADR2p Default: • , •p Value of " ft. Set to last line addressed by the print request (i.e., the last line to be printed.) 3-721 AG92-()6 qedx qedx print line number (=) prints the line number of specified line. ADR= Format = Defauit: Value of t1 tf. Set to line addressed by request. quit (q) exits the editor but first checks for modified buffers. If allY modified buffers are present, qedx displays their status and asks for permission to exit. If permission is granted. all changes made to those buffers since they were last written are lost. The quit request does not itself save the results of any editing that might have been _.done. If. the contents of a modified bMffer ar~. to be~y~cl, the .write request (w) must be issUed. q Format Note: The quit request must be followed immediately by a newline character. quit force (qf) (Q) exits the editor without checking for modified buffers. If any modified buffers are present, all changes made to those buffers since they were last written are lost qf or Q Format read (r) appends the contents of the segment named "path" after the given line. The archive component pathname convention (::) is accepted. If path is omitted, a default pathname is used if possible. (See "Notes on Default Pathnames" below.) Format ADRr path Default: $i path Value of " ft. Set to the last line read from the segment. Note: The request "Or path" is used to insert the contents of a segment before line 1 of the buffer. substitute (s) modifies the contents of the addressed line or set of lines by replacing all strings that match a given regular expression with a supplied character string. 3-722 AG92-()6 qedx qedx Format ADR1,ADR2s/regexp/string/ Default: .,.s/regexp/string/ Note: If string contains the special character "&", each "&" is replaced by the characters that matched regexp. The special meaning of II &II can be suppressed by preceding it with the escape sequence \c. The escape sequence can also be used in a substitute request to insert a newline, by preceding the newline character (\012), or any ASCII character (such as "$11, ".11, 1111, or "\"), with \c. The first character after s is the delimiter; it can be any character not appearing in either regexp or string. Strings matching regexp do not overlap, and the result of substitution is not rescanned. write (w) writes the specified lines of the buffer into the segment named "path". The archive component pathname convention (::) is not accepted. If path is omitted, a default pathname is used if possible; however, if the default pathname identifies an archive component, an error message is printed. (See "Notes on Default Pathnames" below.) Format: ADR1,ADR2w {path} Default: l,$w path Note: path is the pathname of the segment whose contents are to be the addressed lines in the buffer. LIST OF EXTENDED EDIT REQUESTS execute (e) invokes the Multics command processor without leaving the qedx editor. The remaining characters in the request line are passed to the command processor. Format: e Note: If you wish to abort a command line invoked with the execute request by issuing the QUIT signal, program_interrupt aborts the command line and restores control to qedx. global (g) prints, deletes, or prints line numbers of all addressed lines that contain a match for a specified regular expression. Format ADR1,ADR2gX/regexp/ Where X must be one of the following: d p delete lines containing regexp. print lines containing regexp. 3-723 AG92-G6 qedx qedx print line numbers of lines containing regexp. 1,$gX/regexp/ Default: Value of " ft. Set to ADR2 of request Note: The character immediately following the request X is taken to be the regular expression delimiter and can be any character not appearing in regexp. exclude (v) prints, deletes, or prints line numbers of all addressed lines that do not contain a match f or a designated regular expression. ADR1,ADR2vX/regexp/ Format: Where X must be one of the following: d p 1.$vX/regexp/ Default: Value of delete lines not containing regexp. print lines not containing regexp. print line numbers of lines not containing regexp. " ft. Set to ADR2 of request Note: The character immediately following the request X is taken to be the regular expression delimiter and can be any character not appearing in regexp. LIST OF BUFFER REQUESTS change buffer (b) designates an auxiliary buffer as the current buffer. current buffer becomes an auxiliary buffer. The previously designated b (X) Format: where X is the name of the buffer that is to become the current buiier. A singie-character buffer name need not be enclosed in parentheses. Value of " ft. Restored to the value of "." when buffer X was last used as the current buffer (i.e., the value of "." is maintained separately for each buffer and saved as part of the buffer status). If X is a new buffer. then "." is set to line O. 3-724 AG92-G6 qedx qedx move (m) moves line(s) from the current buffer to a chosen auxiliary buffer. The addressed lines are deleted from the current buffer and replace the previous contents (if any) of the auxiliary buffer. Format ADR 1 , ADR2m (X) Default .,.m(X) where X is the name of the auxiliary buffer to which the lines are to be moved. A single-character buffer name need not be enclosed in parentheses. Value of " ft. Set to the line after the last line moved in the current buffer. Set to line 0 in the specified auxiliary buffer. buffer status (x) prints a summary status of all buffers currently in use. x Format Value of 't ". Unchanged. If you have created the additional buffers alpha and beta and have designated alpha as the current buffer, the output from the buffer status request might be as follows: Example: 157 32 53 (0) demo. r unof f -> (a 1pha) (beta) This output indicates 157 lines in buffer 0 (the initial buffer), 32 lines in alpha (the current buffer), and 53 lines in beta. It also indicates that the default pathname for buffer 0 is demoorunoff (in your working directory) and that buffers alpha and beta have no default pathnames. nothing (n) addresses a line in the segment (i.e., set the value of "" to a particular line). No other action is taken. Format: ADRn Default: .n Value of " ft. Set to line addressed by request 3-725 AG92-()6 qedx qedx comment (") the editor ignores the remainder of this request line. This request is generally used to annotate qedx macros and can also be used to annotate online work. Format: Default: ADR" II Set to line addressed by ADR. NOTES ON DEFAULT PATHNAMES The qedx editor maintains a default pathname for each buffer. This default pathname is used whenever a read (r) or write (w) request is given without a pathname. Initially, the default pathname for a buffer is null; i.e., any attempt to read or write read reqllest is issued with a pathname and the buffer is empty, qedx saveS that" Pathnameas-ihe- deraulCfoithe buffer. Whenever a write request is issued with a pathname that writes the entire contents of the buffer (i.e., no address range is given), qedx saves that pathname as the default for the buffer. "without"apathnam~_"J~l1lt£_jn an~rr()rJl:1~g~.Whenevera If a read request is given when the buffer is not empty or a write request is given that does not write the entire buffer, qedx considers the default pathname of that buffer to be no longer trustworthy. The next use of the read or write request without a pathname in that buffer causes qedx to ask for permission to use the default pathname. If permission is given. qedx once again considers the pathname to be dependable. For example, given the following sequence: qedx r first r second w qedx asks for permISSIon to write the buffer to the segment named "first" because the 'Or second" request was issued when the buffer was not empty. 3-726 AG92-06 qedx qedx On the other hand, given the following sequence: qedx r first 1, $d r second w qedx writes the buffer to the segment named "second" without asking permission because the buffer was empty when the nr second" request was given. NOTES ON SPACING The following rules govern the use of spaces in editor requests. 1. Spaces are taken as literal text when appearing inside of regular expressions. Thus, /the n/ is not the same as /then/. 2. Spaces cannot appear in numbers; e.g., if 13 is written as 1 3, it is interpreted as 1+3, or 4. 3. Spaces within addresses except as indicated above are ignored. 4. The treatment of spaces in the body of an editor request depends on the nature of the request. RESPONSES FROM THE EDITOR In general, the editor does not respond with output on the terminal unless explicitly requested to do so (e.g., with a print or print-line-number request). The editor does not comment when you enter or exit from the editor or change to and from input and edit modes. The use of frequent print requests is recommended for new users of the qedx editor. If you inadvertently request a large 3...'TIount of terminal output from the editor and wish to abort the output without abandoning all previous editing, you can issue the quit signal (by pressing the proper key on your terminal, e.g., BRK, ATIN, INTERRUPT), and, after the quit response, you can reenter the editor by invoking program_interrupt. This action causes the editor to abandon its printout, but leaves the value of n. as if the printout had gone to completion. t1 If an error is encountered by the editor, an error message is printed on your terminai and any editor requests already input (i.e., read ahead from the terminal) are discarded. 3-727 AG92-06 query qedx If you interrupt an invocation of qedx (e.g.. via use of the quit signal) and invoke qedx again before using the start, program_interrupt. or release commands, qedx informs you that you have one or more suspended invocations and asks if you wish to continue. If you answer "1" to this query, qedx prints an explanation of the implications of answering "yes" to this query along with our recommendation of the proper response to this situation. NOTES ON MACRO USAGE You can place elaborate editor request sequences (called macros) into auxiliary buffers and then use the editor as an interpretive language. This use of qedx requires a fairly detailed understanding of the editor. To invoke a qedx macro from command level. you merely place your macro in a segment that has the letters "qedx" as the last component of its name, then type: NOTES ON I/O SWITCHES While most users interact with the qedx editor through a terminal, the editor is designed to accept input through the user_input I/O switch and transmit output through the user_output I/O switch. These switches can be controlled (using the iox_ subroutine) to interface with other devices/files in addition to your terminal. For convenience, the qedx editor description assumes that your input/output device is a terminal. Name: query SYNTAX AS A COMMAND query arg {-control_args} SYNTAX AS AN ACTIVE FUNCTION [query arg {-contro1 args}] FUNCTION asks you a question and prints or returns the value "true" if your answer is "yes" or "false" if your answer is "no"; if you type anything else, the active function asks for a "yes" or "no" answer. 3-728 AG92-Q6 query query ARGUMENTS arg is the question to be asked. Enclose the question in quotes if it contains spaces or other command language characters. CONTROL ARGUMENTS -brief, -bf suppresses extra spacing and newlines when asking questions. -disable_cp_escape, -dcpe disables the ability to escape to the command processor via the " " response (see "Notes on Command Processor Escape" below). -enable_cp_escape, -ecpe enables the ability to escape to the command processor via the ".. " response. -input_switch STR -isw STR specifies the I/O switch to use for input of your response. (Default user_input) -long, -lg adds a leading newline and three trailing spaces to the question. (Default) -output_switch STR, -osw STR specifies the I/O switch to use for output of the question to you. (Default: user_output) -repeat DT, -rp DT repeats the question every DT if you have not responded, where DT must be in a form suitable for input to convert_date_to_binary_. NOTES You can use the format_line active function to insert other active function values into the question. NOTES ON COMMAND PROCESSOR ESCAPE The -disable_cp_escape and -enable_cp_escape control arguments override the system or subsystem default. The system default is "enabled". Subsystems can define the default to be either "enable" or "disable". (See the command_query_ subroutine.) 3-729 AG92-06 query quotient EXAMPLES The following lines from an exec_com segment allow you to control the continued execution of the exec_com. &if &[query &then &else &quit 1100 you wish to continue? &if &[query [format_line &then &else &quit 1100 II] you want the default date of "'a?1I [date]]] Name: quotient SYNTAX AS A COMMAND quotient numA numB SYNTAX AS AN ACTIVE FUNCTION [quotient numA numB] FUNCTION returns the result of numA divided by numB. NOTES See the description of divide, which returns only the integer portion of quotient, in this manual. EXAMPLES The following interaction illustrates the quotient active function. string [quotient 5 4] 1.25 string [quotient 1 3] 0.33333333333333333333333333333333333333333333333333333333 string [quotient 5 2] 2.5 3-730 AG92-Q6 rank Name: rank SYNT AX AS A COMMAND rank CHAR {-control_arg} SYNTAX AS AN ACTIVE FUNCTION [rank CHAR {-control_arg}] FUNCTION Prints or returns the position of a character in the Multics ASCII collating sequence. The null (NUL) character is at rank O. ARGUMENTS CHAR is a single character whose rank is to be returned. If it is a special character to the command processor (i.e.• space, tab, semicolon, etc.). enclose it in quotes. CONTROL ARGUMENTS -decimal, -dec returns the rank as a decimal number. (Default) -octal, -oc returns the rank as an octal number. Name: read_mail, rdm SYNTAX AS A COMMAND rdm {mbx_specification} {-control_args} FUNCTION selectively lists. prints, deletes. saves and forwards messages and mail sent to a mailbox. ARGUMENTS mbx_specification specifies the mailbox to be manipulated. If not given. the user's default mailbox (> udd >Project> Person> Person.mbx) is used. 11/86 3-731 I AG92-Q6A LIST OF MBX SPECIFICATIONS -log specifies the user's logbox and is equivalent to -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx -mailbox path, -mbx path specifies the pathname of a mailbox. Ihe suffix "mbx" is added if necessary. -save path, -sv path specifies the pathname of a savebox. Ihe suffix "sv.mbx" is added if necessary. -user SIR specifies either a user's default mailbox or an entry in the system mail table (see "Notes on Mailbox Selection by User" below). STR is any noncontrol argument and is first interpreted as -mailbox SIR; if no mailbox is found, SIR is then interpreted as -save SIR; if no savebox is found, it is interpreted as -user SIR. CONTROL ARGUMENTS -abbrev, -ab enables abbreviation expansion of request lines. -accessible, -ace selects only those messages in the mailbox that you are permitted to read. If you have read (r) extended access on the mailbox, read_mail selects all messages in the mailbox; if you have own (0) extended access on 'the mailbox, read_mail selects only those messages that you sent to the mailbox. (Default) -acknowledge. -ack acknowledges messages which request acknowledgement. (Default) -all, -a selects all messages in the mailbox regardless of who sent them. It requires read (r) extended access on the maiibox. -brief, -bf shortens some informative messages and suppresses others. -count, -ct prints the number of messages being read before entering the request loop. (Default) -debug, -db enables read_mail's debugging facilities. Use of this control argument is not recommended for normal users of read_mail. 11/86 3-732 AG92-06A read_mail -interactive_messages, -im includes interactive messages in the mailbox in addition to ordinary mail as the messages that you can manipulate. -list. -Is lists the messages in the mailbox before entering the request loop. -long, -lg prints the long form of all informative messages. (Default) -mail, -ml includes only ordinary messages in the mailbox. (Default) -no_abbrev, -nab does not enable abbreviation expansion of request lines. (Default) -no_acknowledge, -nack does not acknowledge messages which request acknowledgement. -no_count, -nct does not print the message count. -no_debug. -ndb disables read_mail's debugging facilities. (Default) -no_interactive_messages, -nim includes only mail in the mailbox. (Default) -no_list, -nls does not list the messages before entering request loop. (Default) -no_mail, -nml does not include ordinary messages. It is incompatible with -nim. -no_print, -npr does not the print messages before entering request loop. (Default) -no_prompt suppresses the prompt for request lines in the request loop. -no_request_loop. -nrql does not enter the request loop if there are no messages in the mailbox. (Default -not_own selects only those messages in the mailbox that were not sent by you. It requires read (r) extended access on the mailbox. -own selects only those messages in the mailbox that you sent to the mailbox. control argument requires own (0) extended access on the mailbox. 11/86 3-733 This AG92-06A -print, -pr prints all messages in the mailbox before entering the request loop. -profile path, -pf path specifies the pathname of the profile to use for abbreviation expansion. suffix "profile" is added if necessary. This control argument implies -abbrev. The -prompt STR sets the request loop prompt to STR. The default is A/read_mailA[ (Ad)A]:A2x -quit exits read_mail after performing any operations given by the -list, -print, or -request control arguments; this control argument must be given in combination wi th one of those. -request STR, -rq STR executes STR as a read_mail request line before entering the request loop. -request_loop, -rql enters the read_mail request loop even if there are no messages in the mailbox. -totals, -tt prints the number of the messages in the mailbox and exits without entering the request loop. This control argument is incompatible with -print, -list, -request, and -quit. NOTES ON MAILBOX SELECTION BY USER A user's default mailbox is specified in the form Person_id.Project_id. For an entry in the mail table, STR is usually in the form of Person_ide The mail table permits you to address mail by Person_id without knowing the Project_id of the recipient. The mail table is described in the The mail table is described in the Extended Mail System User's Guide (CH23) and the Multics System Administration Procedures (AK50) manuals. If STR contains one period and no white space, it is interpreted as a User_id that specifies a user's default mailbox; otherwise it is interpreted as the name of an entry in the mail table. 11/86 3-734 AG92-06A For example: -user DBuxtehude.SiteSA is interpreted as a User_id that identifies a default mailbox. On the other hand, -user IIGeorge G. Byron" -user L.v.Beethoven -user Burns are all interpreted as the names of entries in the mail table: the first because it contains white space; the second because it contains more than one period; the third because it contains no period. «» When interpreted as a User_id. the SIR cannot contain any angle brackets and must have the form Person_id.Project_id. where "Person_id" cannot exceed 28 characters in length and "Project_id" is limited to 32 characters. In this case. "-user STR" is equivalent to the mbx_specification "-mailbox >udd>Project_id>Person_id>Person_id.mbx." When interpreted as the name of a mail table entry. STR cannot contain any commas. colons. semicolons, backslashes (\). parentheses, angle brackets, braces ({}). quotes. commercial at-signs (@). or white space other than spaces. The query of the mail table is performed in a case-insensitive manner. The display_mailins-address command can be used to determine the actual address corresponding to the STR. The address in the mail table must identify a mailbox. NOTES ON CONTROL ARGUMENTS AFFECTING INDIVIDUAL REQUESTS Control arguments can be specified on the read_mail command line to change the default beavior of individual requests. Use of these control arguments on the command line is identical to specifying them for each use of the particular request. Of course. the modified default behavior of a request can be overriden for individual uses of the request by use of the appropriate control argument. Type: help request_name within read_mail for more detail on the effect of the following control arguments. LIST OF CONTROL ARGUMENTS AFFECTING THE FORWARD REQUEST -acknowledge, -ack specifies that each recipient of your forwarded message will send an acknowledgement to you after they have read the message. -no_acknowledge, -nack specifies that you do not want to receive acknowledgements. (Default) 3-735 AG92-()6 -add_comments adds a comment to a message before forwarding the message. You are prompted for the text of the comment, which can be edited in the same way that the message created by send_mail is edited before transmission. The text of the comment is placed in the new "Redistributed-COmment" field that is added by this request in addition to the standard redistribution header fields. The original copy of the message is not modified by this operation. -log places a copy of the forwarded message in your logbox. If the logbox does not exist, it is created and a message to that effect is displayed. -notify, -nt sends a "You have mail." notification to each recipient of the message. (Default) -no_notify, -nnt does not send notification messages. -save path, -sv path places a copy of the forwarded message into the savebox with the specified pathname. The suffix "sv.mbx" is added if necessary. If the savebox does not exist, you are queried for permission to create the savebox. If you refuse to give permission, the forward request is aborted without actually sending the message to any of the recipients. LIST OF CONTROL ARGUMENTS AFFECTING THE PRINT REQUEST -header, -he displays all information from the message header including user-defined fields while excluding the message trace and redundant information. (Default) -brief _header, -bfhe displays the minimal amount of information from the message header. The date and authors are always displayed; the subject is displayed if it is not blank; the number of recipients is displayed either if there is more than one recipient or if you are not the sole recipient of the message; if the message was forwarded with comments, these comments are also displayed. -lon~header, -lghe displays all information from the message header including network-tracing information even if some of the information is redundant (i.e.. if the "From:", "Sender:", and "Delivery-By:" fields are all equal, this option forces the print request to display all three fields when it prints the message). -no_header. -nhe displays no information from the message header. Only the message number. message body line count. and message body are displayed. 3-736 AG92-06 LIST OF CONTROL ARGUMENTS AFFECTING THE PRINT HEADER REQUEST -default displays all information from the message header including user-defined fields while excluding the message trace and redundant information. (Default) -brief. -bf displays the minimal amount of information from the message header (see -brief _header above). -long, -lg displays all information from the message header (see -lon~header above). LIST OF CONTROL ARGUMENTS AFFECTING THE REPLY REQUEST -include_authors. -iat includes the author(s) of the message as recipients of the reply. (Default) -no_include_authors, -niat does not include the author(s) of the message as recipients of the reply. -include_recipients, -irc includes the recipients of the message as recipients of the reply. -no_include_recipients, -nirc does not include the recipients of the message as recipients of the reply. (Default) -include_self, -is allows you to be a recipient of the reply without explicit use of -to or -cc. -no_include_self, -nis does not include you as a recipient of the reply unless explicitly requested via -to or -cc. (Default) -include_original, -io includes the original message as part of the text of the reply. -no_include_original, -nio does not put the original message into the reply's text. (Default) -inden tN, -ind N indents the original message when -include_original is specified. (Default: 4) -fill, -fi causes the reply message to be filled before transmission. (Default for -terminal_input) -no_fill, -nfi causes the reply message to not be filled before transmission. -input_file) 3-737 (Default for AG92-D6 -line_length N, -11 N specifies the line length used when filling the reply message. (Default: 72) -notify, -nt sends a "You have mail." notification to each recipient of the message. (Default) -no_notify, -nnt does not send notification messages. NOTES Messages are not actually deleted until read_mail is exited via the quit request. While within read_mail, messages which are accidently marked for deletion can be restored by using the retrieve request For a description of the message specifiers, selection control arguments, and addresses used by. the. individual. read_mail_.requests~ type: help message_specifiers.gi help selection_control_args.gi help addresses'.gi within the read_mail request loop. Lf ST OF REQUESTS In the following summary of read_mail requests. "spec" is used as shorthand for "message_specifier", "-selca" is used as shorthand for "-selection_args" and "-ca" is used as shorthand for "-control_args". For a complete description of any request, issue the read_mail request: help request_name prints a line describing the current invocation of read_mail. ? prints a list of requests available in read_mail. abbrev {-cal, ab {-cal controls abbreviation processing of request lines. all -ca, [all -ca] prints/returns the message numbers of all messages of the specified type in the mailbox. answer STR -ca request_line provides preset answers to questions asked by another request 3-738 AG92-06 append {specs} path -ca, app {specs} path -ca writes the ASCII representation of the specified messages to the end of a segment apply {specs} {-cal cmd_l ine, ap {specs} {-cal cmd_line executes a Multics command line on the ASCII form of the messages. copy {specs} path {-cal copies the specified messages into another mailbox. current, c, [current], [c] prints/returns the current message number. debug_mode {-cal enables/disables read_mail's debugging facilities. delete {specs} {-cal {-selca}, d 1 {specs} {-ca} {-se 1cal , d {specs} {-ca} {-se 1cal deletes the specified messages. do rq_str {args}, [do rq_str args] executes/returns a request line with argument substitution. exec com ec Dath {ec arasl, ec ec_path {~c_args}: [exec com ec path {ec args}], [ec ec_path {ec_args}] executes a file of read_mail requests which can return a value. execute cmd_line, e cmd line, rex~r-utc ~r+i·v..... .,.. ... "'"' - a.... ;. ~~rl _ .... L ~ j [e active_str] executes a Multics command line/evaluates a Multics active string. first -ca, f -ca, [first -ca] , [f -ca] prints/returns the message number of the first message of the specified type in the mailbox. forward {spec} {addresses} {-cal, fwd {spec} {addresses} {-cal, for {spec} {addresses} {-ca} forwards the specified message to the specified recipients. help {topics} {-cal prints information about read_mail requests and other topics. 3-739 AG92-()6 if expr -then linel {-else line2}, [if expr -then STRl {-else STR2}] conditionally executes/returns one of two request lines. last {-ca}, 1 {-cal, [last {-ca}], [1 {-ca}] prints/returns the message number of the last message of the specified type in the mailbox. last_seen, [last_seen] prints or returns the message number of the last nondeleted message that has been printed with the print request by a user having d extended access to the mailbox. last_unseen, [last_unseen], lu, [lu] prints or returns the message number of the last nondeleted message that has not been printed with the print request by a user having d extended access to the mailbox. 1 i Sot {s-pe-c-s} {-ca} {--s-el cal t 1s {specs} {-cal {-selca}, [1 ist {specs} {-cal {-se1ca}], [ls {specs} {-cal {-se1ca}] displays a summary of the selected messages or returns their message numbers. list_help {topics}, Ih {topics} displays the name of all read_mail info segments on given topics. list_requests {STRs} {-ca}, lr {STRs} {-cal prints a brief description of selected read_mail requests. log {specs} {-cal places a copy of the specified messages into your logbox. mailbox, mbx, [mailbox] [mbx] prints or returns the absolute pathname of the mailbox being read. t next {-ca} , [next {-cal] prints or returns the message number of the first message of the specified type after the current message. new, [new] prints or returns the message number of all nondeleted messages since the last one that have been printed with the print request by a user having d extended access to the mailbox. next_seen {specs}, [next_seen {specs}], ns {specs}, [ns {specs}] prints or returns the message number of the first nondeleted message after the specified message (or after the current message by default) that has been printed with the print request by a user baving d extended access to the mailbox. 11/87 3-740 AG92-06B read_mail next_unseen {specs}, [next_unseen {specs}], nu {specs}, [nu {specs}] prints or returns the message number of the first nondeleted message after the specified message (or after the current message by default) that has not been printed with the print request by a user having d extended access to the mailbox. preface {specs} pathname {-ca}, prf {specs} pathname {-cal writes the ASCII representations of the specified messages to the beginning of a segment. previous {-ca} , [previous {-cal] prints or returns the message number of the last message of the specified type before the curren t message. previous_seen {specs}, [previous_seen {specs}], ps {specs}, Cps {specs}] prints or returns the message number of the last nondeleted message before the specified message (or before the current message by default) that has been printed with the print request by a user having d extended access to the mailbox. previous_unseen {specs}, [previous_unseen {specs}], pu {specs}, Cpu {specs}] prints or returns the message number of the last nondeleted message before the specified message (or before the current message by default) that has not been printed with the print request by a user having d extended access to the mailbox. pr i nt {specs} {-ca} {-se 1cal , pr {specs} {-cal {-se 1cal , p {specs} {-ca} {-se 1cal prints the specified messages. print_header {specs} {-ca} {-selca}, prhe {specs} {-ca} {-selca} prin ts the specified messages' headers. quit {-ca}, q {-cal exi ts read_mail. ready, rdy prints a Multics ready message. ready_off. rdf disables printing of a ready message after each request line. ready_on, rdn enables printing of a ready message after each request line. reply {specs} {-ca} {addresses}, rp {specs} {-ca} {addresses} creates a send_mail invocation to answer the specified messages. 11/87 3-740.1 AG92-o6B retrieve {specs} {-selca}, rt {specs} {-selca} retrieves the specified deleted messages. save {specs} path {-ca} , sv {specs} path {-ca} places a copy of the specified messages into a save mailbox. seen, [seen] prints or returns the message number of all nondeleted messages that have been printed with the print request by a user having d extended access to the mailbox. subsystem_name, [subsystem_name] prints or returns the name of this subsystem subystem_version, [subsystem_version] prints or returns the version number of this subsystem. switch_off switch_name {specs}, swf switch_name {specs} turns off a specified switch for each selected message. switch_on switch_name {specs}, swn switch_name {specs} turns on a specified switch for each selected message. unseen, [unseen] prints or returns the message number of all nondeleted messages that have not been printed with the print request by a user having d extended access to the mailbox. write {specs} path {-ca}, w {specs} path {-cal writes the ASCII representation of the specified messages to the end of a segment. l1i8i 3-740.2 AG92-o6B SYNTAX AS A COMMAND read_tape_and_query volume id {-control args}, - rtq vOlume_ld {-control_args} FUNCTION allows the user to interactively inspect and determine the contents of a magnetic tape. Physical tape file processing capabilities are also provided. Note that once the command is invoked. the user is placed in the read_tape_and_query subsystem where the user may use the read_tape_and_query requests. The read_tape_and_query requests are listed below under "List of requests" . ARGUMENTS volume_id is the local tape library designation of the requested tape volume. CONTROL ARGUMENTS -abbrev, -ab enables abbreviation processing within read_tape_and_query. If this argument is specified and the -profile control argument is not given, the user's default profile segment (> udd> Project_id> Person_id> Person_id. profile) is used. -block N. -bk N specifies the maximum physical record size to be processed. where N is the number of bytes. The default is 11200 bytes (2800 36-bit words). -comment STR. -com STR displays STR as a message on the operators console at the time that tape volume is mounted. If SIR contains spaces. tabs or special characters. the entire SIR must be enclosed in quotes. -density N. -den N specifies the initial density setting for tape attachment. where N is the number of bits per inch (bpi). The default is 800 bpi. Although the density is automatically determined (see "Notes"' below). some tape subsystems may not have tape drives capable of handling the default density. -no_abbrev, -nab specifies that abbreviation processing is not to be done by the read_tape_and_query request processor. (Default) -no_prompt suppresses printing of the prompt character string (IIHa: >") for read_tape_and_query requests. 11/87 3-741 AG92-{)6B -no_request_loop, nrql does not enter the read_tape_and_query request loop. -profile PATH, -pf PATH specifies that abbreviation processing is to be done using PATH. The suffix ".profile" need not be given; however, ".profile" must be the last component of PATH. If this control argument is given; the "-abbrev" control argument need not be given. -prompt STR changes the prompt for the read_tape_and_query request loop to STR. If STR is a null string, "", no prompt is given. (Default is to prompt with "rtq:"). -quit exits after performing any operations specified by control arguments. (Default is to enter the read_tape_and_query request loop). -request STR, -rq STR specifies that an initial request line of STR is to be executed before entering the read_tape_and_query request loop. -request_loop, -rql specifies that the read_tape_and_query request loop be entered. (Default). -ring. -rg specifies that the tape is to be mounted with a write ring. This allows a tape that is already mounted with a write ring to be attached without operator intervention. The default is to mount the tape with no write ring. -track N, -tk N where N is 7 or 9 for 7 or 9 track tapes. If this control argument is not specified, 9 track is assumed. NOTES The read_tape_and_query command requests the specified tape volume to be mounted. After the mount request has been satisfied, read_tape_and_query automatically determines the tape density and checks for a recorded tape label. If the density can be determined, an informative message is displayed that includes the density. If the tape has a standard Multics, GCOS, IBM, ANSI or CPS tape label, an informative message is displayed that includes the standard label type and the recorded volume name. If the tape contains a valid IBM or ANSI label, a second message is displayed informing the user of the physical block size and logical record length (in bytes) of the first data file. For all standard labeled tape volumes, the tape is then positioned to the beginning of the first data file. If the tape label is not recognized as one of the five standard types mentioned above, it is designated as unlabeled and the tape volume is repositioned to the beginning of the tape. 11/87 3-742 AG92-06B The read_tape_and_query command then goes into a request loop whose requests are listed below. LIST OF REQUESTS The rtq request loop displays the prompt character stri.'1g "rtq:" unless "-no_prompt" control argument has been specified. Some requests acceptable to read_tape_and_query take arguments that are optional. These optional arguments are enclosed in braces. The valid user responses while in this request loop are as follows: ? lists the available read_tape_and_query requests and active requests. abbrev {-off I -on I -profile PATH}. ab {-off I -profile PATH} turns abbreviation processor on or off and changes profile segments. As an active request, [ab] , returns "true" if abbreviation expansion of request lines is currently enabled within the subsystem and "false" otherwise. passes to the command processor for execution as a Multics command. displays the command name read_tape_and_query with its short name (rtq) in parentheses. I -caB STR i-match STR i-exclude STR, -ex STR I -query I -then STR I -times N} request_line provides preset answers to questions asked by another request. where STR is the desired answer to any question and request_line is any subsystem request line. answer STR {-brief, (bi) bof positions to the beginning of the current physical tape file. bsf {N} backspaces N files. If N is not specified, 1 is assumed. bsr {N} backspaces N records. If N is not specified, 1 is assumed. bsr will not cross backward to the previous file. density N, den N sets the tape density to N bits per inch (bpi), where N can be 6250, 1600, 800, 556, or 200. Density requests must be issued while the tape is positioned at the BOT marker or a request reject status results. Normally the tape density need not be set as it is automatically set by read_tape_and_query before the request loop is entered. 11/87 3-743 AG92-06B do request_string {args} or: do -long, -lg I -brief, -bf I -nogo I -go I -absentee I -interactive expands a request line by substituting the supplied arguments into the line before execution. The request_string is a request line in quotes and args are character string arguments that replace parameters in request_string. As an active request, [do "request_string" args] returns the expanded request_string rather than executing it dump {offset} in_words} {char_types} displays the contents of the record buffer (filled with the read_record request) on the users terminal. If no arguments are specified, the contents of the entire tape buffer are displayed in octal format If the n_words argument is specified. it must follow offset However, these arguments may .Q~ p<>~itJ()n~b~f Qre QJ a.fter any char_type arguments that may be specified.- The offset and n_words arguments must be specified in octal. If offset is specified without being followed by n_words, then the tape buffer is dumped starting with the th word and ending with the last word in the tape buffer. The char_type optional arguments allow interpretation of the data contained in the tape buffer in various character formats. If more than one char_type argument is specified, then the tape buffer is dumped with the first character interpretation, followed by the next character interpretation, and so on until all requested data formats have been dumped. The value of char_type can be selected from the following: -ascii displays the contents of the record buffer in octal with an ASCII interpretation of the data on the right side. -bed displays the contents of the record buffer in octai with a BCD interpretation of the data on the right side -ebcdic displays the contents of the record buffer in octal with an EBCDIC interpretation of the data on the right side. -hex displays the record buffer in hexadecimal format exec_com ec_path {ec_args}, ec ec_path {ec_args} executes a program written in the exec_corn language which is used to pass request lines to the rtq subsystem and to pass input lines to read_tape_and_query requests which read input ec_path is the pathname of an exec_com program. The suffix ".rtq" is assumed if not specified. ec_args are optional and are substituted for parameter references in the program such as &1. As an active request, [ec ec_path {ec_args}], the exec_com program specifies a return value of the exec_com request by use of the &return statement. 11/87 3-744 AG92-()6B execute LINE~ e UNE executes the supplied line as a Multics command line. As an active request, [e LINE], evaluates a Multics active string and returns the result to the subsystem request processor. LINE is the Multics command line to be executed or the Multics active string to be evaluated. It need not be enclosed in quotes. execute_string {-control_args} {control_string {args}} [exs {-control_args} control_string {args} substitutes arguments into a control string. The expanded control string is then passed to the command processor or the rtq subsystem request processor f or execution. where control_string is a character string whjch may contain substitution constructs and args are zero or more character string arguments. Any argument supplied but not referenced by an argument substitution designator is ignored. As an active function, eof positions to the end of the current physical tape file, after the last record. fsf {N} forward spaces N files. If N is not specified, 1 is assumed. fsr {N} forward spaces N records. If N is not specified, 1 is assumed. hpln ............ r ftnn;r-c:.!l \. """.t"'~"'U'~ [_~'.:Il l ...,.... J prints information about request names or topics, where topics are the topics on which information is to be printed. if EXPR -then LINE1 {-else LINE2} conditionally executes one of two request lines depending on the value of an active string. EXPR is the active string which must evaluate to either "true" or "false". LINE1 is the subsystem request line to execute if EXPR evaluates to "true" and LINE2 is the subsystem request line to execute if EXPR evaluates to "falsen • If LINE2 is omitted and EXPR is "false", no additional request line is executed. As an active request, returns one of two character strings to the subsystem request processor depending on the value of an active string. list_help {topics}, lh {topics} displays the names of all subsystem info segments pertaining to a g1Yen set of list_requests {STRs} {-all, -a I -exact}, lr {STRs} {-all, -a I -exact} prints a brief description of selected subsystem requests, where STRs specifies the requests to be listed. 11/87 3-745 AG92-06B list_tape_contents {-long} {-label}. ltc {-lg} {-Ibn displays information about each record on the tape. The tape is positioned to BOT and each record is read in. If the tape is one of the five known standard types, the current record is inspected to determine if it is a valid label or trailer record; if so, information pertinent to that particular label or traiier record is displayed, in interpreted format. If the -long argument is used, the contents of the label record is displayed (in ASCII) as well. Otherwise. the length of the current record is compared to the length of the last record read. If the lengths are the same, a tally of the number of records with the same length is incremented. If the length of the current record is different from that of the last record, or if an end of file mark is detected, a message is displayed that includes: the number of records of equal length, and the record length in hits, words, 8-bit bytes. 9-bit bytes, and 6-bit characters. This display of record lengths can be circumvented by using the -label argument. which only displays the label records. 'Fhis-operationcontinnesuntilthe-togicat-endof tape is rea-ched (two end of file marks in succession or an end of volume trailer record, followed by an end of file mark). The tape is repositioned to BOT after the list_tape_contents request is complete. Use of the -label argument with unlabeled tapes is treated as an error. mode SIR sets the hardware mode for reading tape to STR, which can be one of the following modes: bin eight bit bytes are read in and packed (nine eight bit bytes per memory double word). This is the default mode. bed reads in tape that was originally written in binary coded decimal (BCD): The hardware performs input character conversion. nine eight bit bytes are read in and converted to nine bit bytes by forcing the most significant bit of each nine bit byte to "O"b. position, pos displays the current physical tape file and record position for the user. quit, q detaches the tape and returns control to the current command processor. read_file {args} , rdfile {args} reads the current tape file into the segment described by args. The default action of this request with no arguments queries the user as to the segment name he wishes the tape file to be read into and then issues a warning telling the user that the current tape file will be read in as a stream file with no conversion. The user is asked if he wishes to continue. If he answers yes, then the tape file is read into the designated segment and a newline character is appended to each physical record. If the user answers no, then control is returned to the 11/87 3-745.1 AG92-06B request loop. If the tape is one of the five standard types, each record is checked to determine if it is a valid label or trailer record. If it is, pertinent information about the record is displayed and the record is not written to the output segment. The optional arguments associated with the read_file request are: -output_file {STR}, -of {STR} where STR specifies the segment name for the tape file to be read into. If SIR is omitted, the user is queried for the segment name. 11/87 3-745.2 AG92-06B -count N, .-ct N allows reading up to N files, or until logical end of tape is encountered. After the first file is read in, the -count iteration count is appended to the end of the user-designated output file name as a second component For example: rdfi1e -ct 3 -of fi1e1 names the first output file filel, the second filel.2, and the third file1.3. -multics, -mult specifies that the input tape file is in Multics standard system format. The data portion of each unrepeated record is written to the specified stream output file. No attempt is made to separate the contents of the physical record into a logical format. Since standard Multics tape format specifies that an EOP mark be written every 128 records, the "-extend" and "-count" arguments should be used to ensure that all of the data is recovered. -gcos, -gc specifies that the input tape file is in GCOS standard system format. That is, each record has a block control word and several record control words dividing the physical record into logical records. Each record is processed accordingly. BCD records are converted to ASCII. ASCII records are copied directly. Binary compressed deck card images are decompressed and converted to ASCII. If a BCD card image is identified as a "$ object" card, this card image and all successive binary card images, until a "$ dkend" card image is identified, are copied to a separate file whose name is formed from columns 73 - 76 of the $ object card with a suffix of ".obj". If a BCD card image is identified as a "$ snumb" card, this ·card and all following card images, until another $ snumb card or end of file, are copied into a file whose name is formed from columns 16 - 21 of the $ snumb card with a suffix of ".imcv". If a BCD card image is identified as a "$ < 1anguage>" card, this card and all following card images, until another $ < 1anguage> card or end of file, are copied into a file whose name is formed from columns 73 - 76 of the $ <1 anguage> card with a suffix of ".ascii". This file is also surrounded by sufficient GCOS "JCL cards" so that the completed "deck" can be assembled using the Multics GCOS Environment Simulator. If columns 73 - 76 of the $ card are blank, the $f card image is displayed and the user is queried for the filename. -cp5 specifies that the input tape file is in CP5 standard system format, which consists of variable length records. recorded in EBCDIC. Each variable length logical record is written to the specified stream file, with a newline character appended to the end. The data read from the tape is automatically converted from EBCDIC to ASCII. -dec specifies that the input tape file is in Digital Equipment Corporation (DEC) standard system format Each DEC word is 40 bits long, of which the first 3-746 AG92-06 32 bits and the last four bits are concatenated to form one 36-bit word. The other four bits are discarded. The converted data is then written onto the specified file in raw format. -ibm_vb {STR} specifies that the input tape file has standard IBM VB-formatted variable-length records with embedded block and control words. STR can be ebcdic. ascii. or binary (bin). (Default: ebcdic) -ansi_db {SIR} specifies that the input tape file has ANSI-standard DB-formatted variable-length records with embedded record control words. STR can be ascii. ebcdic. or binary (or bin). (Default ascii) -output_description, -ods allows you to specify a standard Multics I/O attach description to receive the tape file data. User queries ask you to input the attach description and the opening mode. You can express opening modes in long form or in abbreviation form (e.g., sequential_output, sqo). -extend allows you to concatenate the contents of several tape files into one output file. This control argument has meaning only if you also specify -count -nn1 allows escape from the read_file default of appending a new line character to the end of each physical record. when you give no other format specification. -truncate N. -tc N allows you to truncate each physical record to a length of N characters. -skip N allows you to skip N characters (e.g.. a record or block control word) at the beginning of the physical tape record. It is useful when you are processing tapes of an unfamiliar format. -logica1_record_Iength N, -irl N allows you to divide each physical tape record into several logical records of length N. Each logical record is written to the specified file with a new line character appended to the end. Logical records cannot span physical blocks. -convert STR, -conv STR allows you to convert the data format of each tape record, where STR can be one of the following: 11/86 3-747 AG92-06A ebcdic_to_ascii. ebcdic converts input EBCDIC data to ASCII. bcd_to_ascii. bcd converts input BCD data to ASCII. comp8_to_ascii. comp8 converts inpui compS (four-bii-packed decimal) dam io iis equivaieni ASCii represen tation. read_record {-count N}. rdrec {-ct N} reads the current record into a temporary buffer. If the tape is one of the five known standard labeled tapes, the record is checked to determine if it is a label or trailer record; if it is. information pertinent to that particular record type is displayed. Otherwise. information pertaining to the physical record length in bits. words. 8-bitbytes. 9~bit bytes. and 6-bit characters is displayed. When the -count argument is specified, N records are read, overlaying each other in the temporary buffer. Note that when read_record encounters a tape mark, it leaves you positioned at the beginning of the next file. records_in_file, rif displays the total number of records in the current physical tape file. This operation reads each of the records in the file. repositions the tape to its original position, prior to this operation, and displays the count of records read. rewind, rew issues a rewind command and positions the tape to the beginning of tape (BOT) marker. substitute_arguments {-control_args} {control_string {args}} [sbag control_string {args}] substitutes arguments into a control string and prints the result on user_output. As an active function, the result is returned. Tape Positioning: When inspecting multifile tape reels, you may find the action of various positioning requests confusing. The table below illustrates the starting and ending position when using various tape positioning requests: Start Ibsition file 6, record file 6, record file 6, record file 6, record file 6, record file 6, record file 6, record ~~1"" 111'-' t:.. V, .. ,..,,."" .... ~ 1 \A.lVIU 7 7 7 7 7 7 7 "7 I file 6, record 1 11/87 Operation End Position rewind file 1, record 1 bof file 6. record 1 bsf f He 5, record 1 fsf file 7, record 1 bsr file 6. record 6 fsr file 6, record 8 bsf 8 (1) file 1. record 1 ..... t:.. 1 .. "'I'II . . . . -~ J. bsr 10 (2) 1 V, J IIAIUJ U read_file -count 3 file 9, record 1 ~~1 U~ 3-748 AG92-06B Note 1: This causes a rewind operation to occur. since the resultant file number would be less than one. Note 2: This causes a bof operation to occur, since the resultant record number would be less than one. Examples: A typical example of a read_tape_and_query invocation follows. including the initial information displayed for a labeled tape. read_tape_and_query usertl Tape usertl,blk=2800 will be mounted with no write ring. Tape usertl,blk=2800 mounted on drive tape_02 with no write ring. Tape density is 1600 bpi Tape usertl is a labeled ANSI tape Volume name recorded on tape label is USERT1 Setting tape dim to read in nine mode First data file format: ANSI HDR2 label record. Next file format: Record format DB; Block length 4000; Record length 4000: Mode ASCII; Positioning to beginning of physical tape file # 2, (logical file # 1) rtq: 11/87 3-748.1 AG92-()6B ready Name: ready, rely SYNTAX AS A COMMAND rdy FUNCTION prints an up-to-date ready message whose format is optionally set by the general_ready command. The default ready message if general_ready is not used gives the time of day and the amount of CPU time and page faults used since the last ready message was typed. If the user is not at the first command level, i.e., if some computation has been suspended and the stack frames involved not released, the default ready message also contains the number of the current command level. NOTES See the descriptions of the ready_on, ready_off, and general_ready commands. EXAMPLES r 9:47 3.61 29 r 15:03 .47 12 Level 2 Name: ready_off, rdf SYNTAX AS A COMMAND rdf FUNCTION turns off the ready message typed on the terminal after the processing of each command line. Automatic typing of the message is suspended until a ready_on command. is given. NOTES See the descriptions of the ready, ready_on, and general_ready commands. 3-749 AG92-G6 ready_on rebuild_dir Name: ready_on, rdn SYNTAX AS A COMMAND rdn FUNCTION types a ready message on your terminal after each command line has been processed. NOTES Since automatic printing of the ready message is in effect until you invoke ready_off, ready_on is generally used only to "cancel" ready_off. See the ready , ready_off, and general_ready commands. Name: rebuild_dir SYNTAX AS A COMMAND rebuild_dir path {-control_arg} FUNCTION compares a saved directory. information segment created by the save_dir_info command with the current version of the directory in the storage system. If any subdirectories are missing, rebuild_dir recreates them; if any links are missing, it relinks them; if any segments are missing, it prints a comment. ARGUMENTS path is the pathname of a directory information segment. If path does not have the dir_info suffix, it is assumed. CONTROL ARGUMENTS -brief, -bf suppresses the comments "creating directory X" and "appending link X". -long, -lg prints full information about any missing segments. -priv sets quotas and the sons' logical volume identifier, You need acce.s.s to the hphcs_ gate here. 3-750 AG92-06 reconnect_ec_disable Name: reconnect_ec_disable SYNTAX AS A COMMAND reconnect ec disable FUNCTION reverses the effect of the reconnect_ec_enable command. Following reconnection to a disconnected process, no attempt is made to find or invoke the exec_com "reconnect.ec". If a standard process overseer (e.g., process_overseer_ or project_start_up) is in use (the normal case), reconnect_ec_enable is in effect by default SYNTAX AS A COMMAND reconnect ec enable FUNCTION reverses the effect of the reconnect_ec_disable command. When the user. reconnects to a disconnected process, an attempt is made to find the segment reconnect.ec. First the user's home directorY. then the user's oroiect directory (>user _ d i r d i r>Proj ect_name) . then >system_coniro l_d i r will be ·searched. At the first i'uccess, the command "exec_com >Di rectory_name>reconnect.ec" will be executed. NOTES The use of reconnect.ec is enabled automatically by the standard process overseer process_overseer_. The current command processor is used to execute the command. Thus, if the user is using the abbrev command processor, any applicable abbreviation will be expanded. Invocation of the reconnect.ec is not automatically enabled by the project_start_up_ process overseer. Thus, when using project_start_up_. the project administrator may enable the invocation of reconnect.ec at any point in the project_start_up.ec. 3-751 AG92-()6 reductions reductions Name: reductions, rdc SYNTAX AS A COMMAND rdc path {-control_args} FUNCTION * generates language translators. It compiles a segment containing reductions and action routines into a PL/I source segment; it then invokes the pU compiler to compile the PL/I source. The reductions specify the syntax and semantics of a new language; the action routines perform the basic operations (e.g, generating code) required to translate the language. ARGUMENTS path is the pathname of a translator source Segment that is to be compiled by rdc. If path does not have a suffix of rd, one is assumed; however the rd suffix must be the last component of the name of the source segment CONTROL ARGUMENTS -brief. -bf prints all error messages with only a brief summary of the error that has occurred. -long, -lg prints all error messages with a detailed description of the error that has occurred. -trace {STR} adds a tracing facility to the generated translator. STR defines whether tracing is enabled or disabled by default It can be "on" (default) or "off." (See "Notes on Tracing" below.) -no_trace generates a translator without the tracing facility. (Default) In addition, you can give any control argument accepted by the pH command. NOTES Reductions are expressed in a highly compact form that emphasizes the syntax and semantics of the new language. This command compiles these reductions into tables that drive an rdc-provided semantic analyzer for the language. This analyzer compares the tokens (basic units) of a program written in the new language with the valid token phrases defined in the reductions. When a valid phrase is found. the action routines defined by the reduction are invoked to translate the phrase. 3-752 AG92-o6 reductions reductions Translators generated by the command can be written more quickly than hand-programmed translators because rdc provides the semantic analyzer for the language. They are easier to understand and to maintain because the all-important language syntax and semantics is concentrated in the r-eduetions, rather than being spread throughout the seman tic analyzer. This command can generate translators for the simplest type of language. a right-linear (finite state automaton) language. Often such languages are composed of keywords with operands, such as the control language of the bind command. The organization of an rdc translator, the translation process, and the reduction language are described below. If you supply neither -brief nor -long. a detailed description is printed the first time an error occurs in a given compilation and a brief description is printed in subsequent occurrences of that error. NOTES ON SEVERITY VALUES The following severity values are returned by the severity active function when the "reductions" keyword is used: VALUE o 2 4 MEANING No compilation yet, or no error. Correctable error. This error has been bypassed, but may result in other, more severe errors. Fatal error, but rae translation continues to report other errors. Unrecoverable error. Translation stops. In addition, the severity value can be any of those associated with compilation of the resultant PL/I source segment by the pll command. NOTES ON TRACING The tracing facility helps in debugging the reductions for a new translator by showing which reductions are being applied, along with the source tokens of the language being compiled that match each reduction. This gives you a running view of the flow of control through the reductions and of the processing of tokens. Because the tracing facilit;T generates l~rge amounts of output, it can be selective1]' turned on and off during debugging by setting a variable declared as follows: del TRACING bitO) aligned int static init("l"b); A value of "1 fIb turns tracing on; "O"b turns it off. The initial value is set by the operand of -trace. 3-753 AG92-()6 reductions reductions The translator can accept a control argument to turn TRACING on or off, or it can have a debugging entry point to set the switch, or the switch can be set at a particular probe breakpoint. For example, to trace from the 28th through the 40th reductions, you can use the following set of probe requests: probe translator ps "RD_ACTION(NRED)" go to RD_ACTION(NRED); b: if NRED = 28: halt When halted, type: let TRACING = "l"b reset b: if NRED = 40: h ! c And when the 40th reduction was reached, type: let TRACING reset = "O"b ! c OVERVIEW OF THE TRANSLATION PROCESS A translator for a given language must perform three steps to translate a source string written in, the language: 1. Parse the source string into a list of tokens. These tokens are the basic units of the language being translated. They are character strings in the source that are separated from one another by language-defined delimiter characters. 2. Analyze the syntax of the tokens to identify groups of tokens (token phrases) that are valid or invalid in the language. 3. Assign some semantic meaning to each valid token phrase by performing a translation action. Print error messages diagnosing invalid token phrases. Parsing the source string into tokens is a process that depends upon the types of units that make up the language, the delimiter characters defined by the language, and other language characteristics. For most languages, the lex_strin~ subroutine provides facilities that are sufficient to parse the language. However, some languages have syntax characteristics that cannot be handled by lex_strin~; your must code a special parsing routine for such languages (see "Parsing the Source into Tokens" below). See lex_strin~ in the Subroutines manual for more information about its parsing capabilities. 3-754 AG92-06 reductions reductions Once the source string is parsed into a list of tokens, these tokens are analyzed by a semantic analysis procedure that is generated by the reductions command from the reductions specified in the translator source segment The procedure contains tables generated from- the reductIons,tables tha( define an of the - valid tOKen phrases accepted by the lan.guage. For each valid token phrase. the semantic analyzer invokes the programmer-supplied action routines given in the reductions to translate the phrase. For invalid phrases. the reductions command provides - a mechanism for diagnosing the errors in printed error messages. CONTENTS OF A TRANSLATOR The source segment for a translator to be compiled by the reductions command contains the following items. which ale organized as shown in Figure 3-1. 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. An optional copyright notice and other PL/I comments. A set of reductions consisting of reduction attribute declarations and reduction statements. The delimiters / *++ and ++* / open and close the set of reductions. A PL/I procedure statement for the main procedure of the translator. PL/I declarations for the translator'S variables. An optional PL/I declaration for an error_control_table, which defines the text of error messages to be generated by the translator. This error_control_table is used by -the error-reporting mechanism provided by the. reductions command. Code to parse source strings of the new language into tokens. This is shown in Figure 3-1 as a call to lex_strin~. but programmer-supplied code could be used here instead. A PL/I call statement invoking SEMANTIC_ANALYSIS. the semantic analyzer procedure generated by the reductions command from the reductions. A PL/I return statement to return after the translation process is complete. One or more optional PL/I function subprograms (relative syntax functions) that are used to define the syntax of valid token phrases. One or more PL/I subroutines (action routines) that are invoked to translate valid token phrases. 3-755 AG92-06 reductions reductions /* ******************** * c Copyright ••• * ******************** */ 1*++ MAX_DEPTH 5 \ BEGIN / / \ / / RETURN \ / / copyright notice reduction statements and attribute declarations _ ++*/ translator: procedure; dcl . ... .. .. , , translator's declarations dcl error_control_table ••• ; call lex_string_Slex( .• )~ Pthis token = ... ; call SEMANTIC_ANALYSIS(); return; calls to parse translator input into tokens, translate these tokens, & return fcn: procedure returns (bit(l) aligned); end fcn; relative syntax functions act ion: proc ( ••. ) ; action subroutines end action; Figure 3-1. Organization of a Translator 3-756 AG92-06 reductions reductions The definition of the reductions. the error-reporting mechanism. the parsing routine. relative syntax functions, and action routines are described further below. No PL/I end statement is included for the main procedure of the translator in the translator source segment The reductions command appends code for the SEMANTIC_ANALYSIS subroutine and for other utility programs to the contents of the translator source segment It then appends the end statement for the translator's main procedure. Therefore, when coding the translator source segment, make sure that all the relative syntax functions and action routines are ended correctly, and that no end statement is included for the main procedure of the translator. COMPILING THE TRANSLATOR A typical translator source segment, translator.rd, is compiled by a two-step process as shown in Figure 3-2. First, the reductions command compiles translator.rd into a PL/I source segment. translator.pU, which it creates in your' working directory. Second, rdc invokes the pll command to compile the translator.pll into an object segment caned translator. The translator object segment is placed in your working directory. 3-757 AG92-06 reductions reductions translator.pll ___________ /* * * * * * * * * */ ******* * */ /* heading /* translator.rd ____________ I /* *************** ,'c C Copyr i ght /* * /*++ *************** ,'c C *************** */ */ Copyr i ght * *************** */ reductions ++*/ /*++ reductions ++*/ 1. rdc translator: proc( •.• ); -------> translator: proc( ••• ); dc 1 ••• , error_control_table ••• ; dc 1 ••• , error_control_table ••• ; call lex_string_$lex .. ; call SEMANTIC_ANALYSIS; return; call lex_string_$lex .• ; call SEMANTIC_ANALYSIS; return; fen: proc returns (b i t (1 ) ali 9 ned) ; fcn: proc returns (b i t (1) ali gned) ; end fcn; end fcn; ac t i on: proc ( ••• ) ; action: proc( ..... ); end action; end action; SEMANTIC ANALYSIS: procedure 0 ; translator end SEMANTIC_ANALYSIS; 2. pll %include rdc_lex_; <------- %include rdc_error_; %include rdc_delete_; end translator; Figure 3-2. Two Steps of Compiling The output of the reductions command is a PL/I source segment that contains 1. A heading that identifies the translator source segment, the version of the reductions command used to compile the translator source segment into the PL/I source segment, and the date and time of compilation. 3-758 AG92-06 reductions reductions 2. The contents of the translator source segment 3. The SEMANTIC_ANALYSIS procedure generated by the reductions command from the reductions·· in··· the -translator -source segment 4. PL/I %include statements for utility procedures used in SEMANTIC_ANALYSIS and perhaps in the action routines to perform various functions. 5. A PL/I end statement for the main procedure of the translator. This is provided by the reductions command. THE TRANSLATION PROCESS The next few paragraphs describe the process of translating a language source string. It is important to understand how these steps are performed in rdc-generated translators. The reductions command or the lex_strin~ subroutine provide code to perform many of these steps. For others, the programmer must supply a procedure to perform the steps. PARSING THE SOURCE INTO TOKENS As mentioned above, the first step of the translation process is for a translator to parse its input source string into a list of tokens. These tokens are the basic units of the language. For many languages, the lex_strin~ subroutine provides sufficient facilities to parse the language. However, some languages may have a syntax that requires the special parsing facilities of a programmer-supplied parsing routine. The lex_strins- subroutine or the supplied parsing routine must generate a chained list oi token descriptors, as shown in Figure 3-3. Each descriptor describes one of the tokens in the source string. The token descriptors are chained together (f orward and backward) in the order in which their respective tokens appear in the source string. Volume: 70092; Write; F i 1e 4; might be -->1 1-->1 1-->1 1-->1 1-->1 1-->1 1-->1 1-->1 1-->1 1 <-<-<-<-<-<-<-<-I-I I v Volume I-I I v I-I I v 70092 Figure 3-3. I-I I v I-I I v Write I-I I v I-I I v F i 1e I-I I v I-I I v 4 Input Tokens and Their Descriptors 3-759 AG92-06 reductions reductions Languages whose syntaJ( includes statements separated by explicit statement delimiters can use a statement descriptor to identify the group of tokens forming each statement The statement descriptor points to the descriptors for the first and last tokens in the statement In turn. each token descriptor points to its respective statement descriptor. The statement descriptors are chained together (forward and backward) to create an ordered list of the statements appearing in the source string. as shown in Figure 3-4. -------> ------------> <------------ --------------> <-------------- <------- <--- v --> v v --> --> --> --> <-- <-- <-- <-- - v v --> --> <-- <-- ---> <---- - --> --> <-- <-- v -I -I -I -I -I -I -I -I -I v v v v v v v v v Volume Figure 3-4. 70092 Write F i 1e 4 Tokens, Token Descriptors, and Statement Descriptors There are no special requirements for a programmer-supplied parsing routine other than that it create a list of token descriptors and optional statement descriptors. The format of these descriptors is defined in the description for the lex_strinL subroutine. Refer to this description for more information about descriptors, as well as for information on the use of the lex_strin8- subroutine. Figure 3-5 shows the lex_strin8subroutine being invoked first to initialize the lex_delims and lex_control_chars break definition strings, and then to parse the translator'S source string (described by Pinput and Linpud into tokens. In this example: a double quote (n) character is used to open and close quoted strings; the characters /* open comments, which are closed by */; a semicolon (;) is the statement delimiter; and the colon (:). comma (.), space ( ), and all of the ASCII control characters including the PAD character operate as delimiters. The space character and all control characters except backspace are ignored delimiters that are not returned as tokens themselves, even though they separate tokens. Both token descriptors and statement descriptors are generated by the lex_string_ subroutine in this example. No descriptors are generated for the double quotes that enclose quoted strings. although descriptors are generated for the quoted strings themselves. 3-760 AG92-o6 reductions reductions breaks = substr(collate,1,33) 11 11 :,11 II substr(collate,128,l); ignored_breaks = substr (collate, 1 ,8) I substr (collate, 10,24) II substr(col1ate,128,1); ca 11 1ex_str i ng_$ i n i t_l ex_de 1 ims (..... m, .. " .... , "/*ll, 11*/11, .. ; II, 1I10ub, breaks, ignored_breaks, lex_delims, lex_control_chars); call lex_string_$lex(Pinput, Linput, Linput_ignore, Psegment, IIIOOllb, 11111111, 11111111, 11/*11, 11*/11, 11;11, breaks, ignored_breaks, lex_delims, lex_control_chars, Pfirst_stmt_descriptor, Pfirst_token_descriptor, code); Pthis token = Pfirst token descriptor; call SEMANTIC_ANALYSTS(); return; Figure 3-5. Parsing Translator Input Into Tokens, Semantically Analyzing Those Tokens, and Returning ANALYZING AND TRANSLATING THE TOKENS Once the source string has been parsed into tokens, the translation continues by analyzing the syntax of the source tokens. The syntax specifications of the language are used to identify groups of tokens (token phrases). Valid token phrases are translated according to the language semantics (translation action specifications). and invalid token phrases are diagnosed to you. The language syntax and translation action specifications are coded in the set of reductions contained in the translator source segment The reductions command uses these reductions to generate a SEMANTIC_ANALYSIS internal procedure that is appended to the translator when it is compiled. When the SEMANTIC_ANALYSIS procedure is invoked as shown in Figure 3-5, it compares token phrases found in the list of source tokens with the syntax specifications defined in the reductions. If a token phrase matches the syntax specifications of a given reduction, the translation action routines associated with the reduction are invoked to translate the phrase. Then action routines are invoked to move on to the next token phrase, which is translated in a similar manner. The translation is complete when each of the token phrases in the list of source tokens has been identified as a valid token phrase and translated, or has been diagnosed as an in vaiid Loken phrase. REDUCTION LANGUAGE The reductions that define the syntax and semantics of a language to be translated are written in the reduction language. This translator generation language consists of two kinds of statements: reduction statements and attribute declarations. 3-761 AG92-06 reductions reductions Reduction statements specify the syntax of token phrases in the language being translated. They also name action routines that are invoked to translate valid phrases and to diagnose invalid token phrases. Attribute declarations control the size of some fixed-length tables that the generated translator uses and cause translation action routines provided by the reductions command to be included in the translator. They are described below under "Attribute Declarations. " THE SYNTAX OF REDUCTION STATEMENTS All reduction statements contain four parts: a reduction label field, a syntax specification field, an action specification field, and a next-reduction field. A reduction statement has the form labels / syntax specifications / action routines / next-reduction label \ All of the fields must appear in each reduction, in the order shown above. The fields are separated from one another by a right slant (/) character. and the next-reduction field is terminated by a left-slant (\) statement delimiter. The fields of a reduction statement can span any number of lines in the translator source segment. The syntax specifications, action routines, and other items that appear in a reduction statement are separated from one another by one or more of the delimiters shown in Table 3-1 below. When these delimiter characters are used, they are treated as part of the reduction. The meaning of left and right slant was described above. The double quote (") character is used as a quoting character to delimit quoted character strings in the PL/I convention. When any of the delimiter characters appears in a quoted string, it is treated as a regular character rather than as a delimiter. The use of the other delimiters is described in more detail as each field of the reduction statement is described below. Table 3-1. DELIMITING CHARACTERS USED BY rdc / separates fields of a reduction statement. \ ends each reduction statement or attribute declaration. < > delimits a syntax function in the syntax field of a reduction. For example, .. [ ] delimits a PL/I statement in the action field of a reduction. For example, [file_no = token.Nvalue] . separates PL/I statements in the action field of a reduction when more than one statement is given between [ ] delimiters. For example, [a=b; c=dJ • ( ) delimits the argument list of a PL/I subroutine call in the action field of a reduction. For example, perform_io (volume, file_no) . 3-762 AG92-06 reductions reductions separates arguments in the argument list of a PL/I subroutine call given in the action field of a reduction. begins and ends quoted strings within a reduction statement. Inside a quoted string, a double quote (tt) character is expressed by two double quotes ('m). used to detect the special PL/I character sequence, -> • which can appear in an action specification. used to detect the special PL/I character sequences, A= <= >= , which can· appear in an action specification. /I. used to detect the special PL/I character sequences, A= A< A> • which can appear in an action specification. (backspace) used in the syntax field of a reduction to detect an underlined delimiter character. The special meaning of such a character is ignored, and the character is treated as a syntax specification character. begins a comment in a reduction statement The comment ends with the next newline character. There are also five delimiters that delimit items in a reduction but are ignored by the reductions command unless enclosed in a quoted string. These characters have no meaning in the reduction language but serve mainly to separate the specifications in a reduction statement \" space newline horizontal tab vertical tab newpage SEMANTICS OF REDUCTION STATEMENTS The most important part of any set of reductions are the syntax fields given in the reduction statements. These fields describe the syntax of the valid and invalid token phrases in the -language to be translated. The syntax specifications can require a token in a particular phrase to have a specific character string value, or to have a value that meets some general list of requirements defined in a syntax function (a PL/I function subprogram). When a token phrase does not match the syntax requirements of a reduction it is compared with, H is compared with the syntax requirements of the reduction that follows. This process continues until the syntax requirements of some reduction are matched. 3-763 AG92-()6 reductions reductions When a token phrase matches the syntax specifications of a particular reduction, the phrase is translated by invoking the action routines given in the action field of that reduction. Action routines can be simple PL/I statements or calls to PL/I subroutines with arguments. The routines can perform some constant translation operation, or an operation that depends on the values of one or more tokens in the matching token phrase. They can also skip over one or more of the tokens in the matching token phrase to permit the next token phrase to be examined. After the action routines have been invoked, the next-reduction field of the matched reduction controls which reduction syntax field the next token phrase is compared with. The next reduction can be identified by label, using one of the reduction labels given in a label field. Also, the reduction following the matched reduction can be used next In addition, special next-reduction operations are provided to return from the SEMANTIC_ANALYSIS procedure, and to return from a group of reduction statements used as a reduction subroutine. LABEL FIELD OF A REDUCTION STATEMENT One or more labels can be specified in the label field of a reduction statement to identify the reduction. A label is a character string that begins with an alphabetic character, and contains 32 or fewer alphanumeric or underline U characters. The labels on a reduction statement can be referenced in the next-reduction field of reduction statements to direct the order in which tokens are compared with the reduction syntax specifications. To prevent any ambiguities in these references, each of the labels defined in a set of reductions must be unique. In every set of reductions, any attribute declarations that are given must appear before all of the reduction statements. To distinguish between the attribute declarations and reduction statements. the first reduction statement must have a special first label called BEGIN. The BEGIN label acts as a keyword that separates the attribute declarations from reduction statements. It also identifies the first reduction with which token phrases compared. Thus, the comparison of token phrases with reductions starts with beginning reduction, the first reduction following the attribute declarations, reduction with the BEGIN label. the are this the With the exception of the BEGIN label on the first reduction statement, no labels are required on any reduction statement Their use is optional, and is intended to facilitate the division of the set of reductions into groups of reduction statements or reduction subroutines. However, every reduction statement must have a label field even if it consists of an empty label field with a field delimiter (I). All four of the fields mentioned above must appear in every reduction statement. Use of reduction labels is discussed further in the description of "The Next-Reduction Field" below. 3-764 AG92-06 reductions reductions SYNTAX FIELD OF A REDUCTION STATEMENT The syntax field of a reduction statement defines the syntax of one token phrase in the language· being tiiIiSla:teiL - The· tokens iIi lhe -input Ust are ·compared with· the syntax fields of one or more reductions. When the tokens match the syntax field of a reduction, then the action field of that reduction is invoked to perform a translation action. If the reduction specifies the syntax for a valid token phrase, the translation action can compile code to implement the semantic meaning of the phrase or it can immediately interpret the phrase or store a value in a table or perform any other translation action. If the reduction specifies the syntax for an invalid token phrase, then the translation action can diagnose the error in an error message. CURRENT TOKEN PHRASE Before learning how syntax specifications are defined, some terminology for dealing with the tokens in the token list must be developed. In Figure 3-3 above, a list of tokens is described by token descriptors that are chained together. The reductions command declares a pointer in the main procedure of the translator that points to the particular tokens being compared with reductions at any given time. This pointer is called Pthis_token, and it points to the descriptor of the "current token." The current token and those tokens that follow it in the list of tokens are the tokens being compared with the reduction syntax specifications. This group of tokens is called the "current token phrase." These relationships are shown in Figure 3-6 below. Notice that the current token phrase does not contain a fixed number of tokens. Instead, the number of tokens varies to accommodate the number of syntax specifications in the reduction being examined. Of course, if there are fewer tokens remaining to be translated than syntax specifications in a reduction, the current token phrase cannot match that reduction. At any point in time, one of the tokens in the current token phrase is being compared with its corresponding syntax specification in a reduction. The descriptor for this token is pointed to by Ptoken, another pointer variable declared by the reductions command in the main procedure of the translator. 3-765 AG92-Q6 reductions reductions Ptoken Pthis token --> - - I v I --> --> <-- <-- '-1' v ~I . -v --> --> --> <-- <-- <-- '=1 . Volume .=, . v v v .=,. 70092 v Write --> <-- --> <-- --> <-- '=, ' '-I '-1-' v v v Fi 1e '-1 · v 4 A A TOKEN BEING EXAMINED CURRENT TOKEN I_CURRENT TOKEN PHRASE_I Figure 3-6. The Current Token Phrase Used by Reductions SYNTAX SPECIFICATIONS The tokens in the current token phrase are compared consecutively with the syntax specifications in a reduction syntax field to identify valid and invalid token phrases. The syntax specifications place requirements on the tokens in the current token phrase. If each token in the phrase meets the requirements of its corresponding syntax specification in the reduction. the entire phrase matches the reduction, and the reduction action field is invoked. Three types of syntax specifications are allowed by the reduction language: absolute syntax specifications, relative syntax functions, and built-in syntax functions. ABSOLUTE SYNTAX SPECIFICATIONS Absolute particular reduction statement syntax specifications require that their corresponding character string. Absolute specifications are defined in statement by using their character string value. For that would identify the first two tokens in Figure 3-6 vol_stmt / Volume : / input token equal a the syntax field of a example, a reduction might be / \ If reductions were written to translate all of the tokens in Figure 3-6 then "Volume," "Write," "File," n:". and ";" would probably be specified as absolute syntax specifications. 3-766 AG92-06 reductions reductions The delimiter characters used in the reduction language (see Table 3-1 above) can be used in an absolute specification by enclosing the entire specification in quotes. For example. II and/ or ", ">udd>Proj ec t_ i d>prog", 11111111, II ( " , and II, II. In addition. the delimiters- -that-have a special-mea-ningwithin the syntax field (/ < » can be used as one-character absolute specifications by underlining the delimiter character. and thus are treated as single-character absolute syntax specifications. RELATIVE SYNTAX FUNCTIONS Relative syntax functions are a second type of syntax specification. A relative syntax function requires that its corresponding input token meet some special requirements that are defined by a PL/I function subprogram. The requirements defined by such functions can be quite specific or very general in nature. A relative syntax function is defined as a specification in the syntax field of a reduction by enclosing the name of the function in angle brackets (i.e.. ; / / \ Other examples of relative syntax functions might be a function that requires that a token be a relative pathname. and that calls the absolute_pathname_ subroutine to associate an absolute pathname as the semantic value of this pathname token; a function that requires that the token be a character string representation of a positive integer; and that requires a token that is acceptable as input to the convert_date_to_binary_ subroutine. Relative syntax functions must be coded by the programmer and included in the main procedure of the translator source segment. Their calling sequence is shown below. declare function_name entry returns (bit(l) aligned); token_meets_requirements = function_name 0 ; where the function returns a value of "1"b if the input token meets the requirements of the function. and "O"b otherwise. The function can have any valid PL/I function name that is 32 or fewer alphanumeric or underline characters in length. and that contains at least one lowercase alphabetic character. The lowercase letter is required to avoid naming conflicts with variables and procedures declared by rdc for use in the SEMANTIC_.-A~~ ..Aa.LYSIS prccedure. Relative syntax functions must be internal procedures of the main procedure of the translator so that they can reference the token to be examined. Ptoken points to the descriptor for this token as shown in Figure 3-6. The token descriptor itself is a structure variable named token that is based on Ptoken. as described in the lex_strin8subroutine description. The character string value of the token can be referenced by way of the token_value variable. Ptoken. the token structure. and token_value are variables declared by the reductions command in the main procedure of the translator. 3-767 AG92-06 reductions reductions A relative syntax function can associate a semantic value with the token being examined in one of three ways. It can set a variable that has been declared in the main procedure of the translator. It can set token.Nvalue to some integer semantic value. such as the numeric value of a token that matches the function. Or it can allocate a semantic value structure in the temporary segment used for token descriptors. and chain t..ltis structure onto the token descriptor using the token. Psemant pointer. Refer to the description of the lex_strin&- subroutine for a complete declaration of the token structure. LIST OF BUILT-IN SYNTAX FUNCTIONS The third type of syntax specification that can be used in a reduction syntax field is the built-in syntax function. These are relative syntax functions that have been predefined by the reductions command. Although several of these built-in syntax functions make requirements on the input token string that would be difficult to implement directly as relative syntax functions. most of the built-in syntax functions are defined merely to facilitate the implementation of the reductions command itself. Below is a list of the built-in syntax functions and the requirements they place on the input tokens. requires that no corresponding token exists in the current token phrase, that the list of input tokens -is exhausted, and that no more tokens remain to be translated. It differs from other syntax functions that require the existence of a corresponding token in the token phrase. It is used to determine when the translation is complete. requires that a corresponding token exist in the current token phrase. It places no other requirements on the token. It is used when any token value is acceptable in the language being translated. requires that a corresponding token exist in the current token phrase, and that the token is a character string that begins with an alphabetic character and contains 32 or fewer alphanumeric, underline U. or dollar sign ($) characters. requires that a corresponding token exist in the current token phrase, and that the token is a valid, optionally signed decimal integer (as defined by the cv_dec_check_ subroutine). The numeric value of the token is stored as its semantic value in the token.Nvalue element of the token descriptor. requires that a corresponding token.S.quoted_string bit is lex_strin&- subroutine turns delimiters when the input to token exist in the current token phrase, and that the turned on in the descriptor of the token. The on this bit if the token is enclosed within quoting the translator is parsed. 3-768 AG92-06 reductions reductions <85> requires that a corresponding token exist in the current token phrase, and that the token is a single backspace character. It is used as a convenience for defining -syntax--specifications--- Iot----one~natacter, underlinea---rolens.------- ---- --- -COMPLETENESS OF THE SYNTAX SPECIFICATIONS One of the most difficult aspects of writing a translator is identifying all possible invalid token phrases that could be received as input so that error messages can be issued. This problem must be addressed in each set of reductions, and in each group of reductions within a set as well, if the translator is to operate deterministically and to perform the expected translation. A typical solution for the problem is to have a group of reductions that identify all possible valid token phrases. followed by one or more reductions that use the built-in syntax function or an empty syntax field to identify all other invalid token phrases. For example, if the language for the tokens in Figure 3-6 requires that a colon. volume identifier, and semicolon always follow the Volume keyword, then the following group of reductions might be used to diagnose an error. vol stmt - / Volume: ; / / / Voiume : ; / / \It check for bad volume identifier. / Volume / / \" check for bad volume statement. / / / \" check for unknown or unexpected statement. \ \ \ \ THE NEXT-REDUCTION FIELD OF A REDUCTION STATEMENT The next-reduction field governs the flow of control between reductions. When the translator calls the SEMANTIC_ANALYSIS procedure, control passes to the reduction whose label is BEGIN. The first of the current token phrases is compared with this beginning reduction and those that follow until it matches the syntax requirements of one of the reductions. The action field of that reduction is then invoked to translate to the current token phrase, and to make the next token phrase current. The next-reduction field of the matched reduction controls which reduction the new current token phrase is compared with. The next-reduction field can be blank, or it can contain a reduction label. If it is blank, the reduction immediately following the matched reduction is used in the next comparison. If a reduction label is specified, then the reduction identified by that label is used in the next comparison. In either case, comparison of the new current token phrase with reductions continues until a matching reduction is found. 3-769 AG92-06 reductions reductions This process of analyzing token phrases continues until all of the input tokens have been translated. Each set of reductions must contain one or more reductions that use the built-in syntax function to detect when all the input tokens have been translated. When such a reduction is invoked, its next-reduction field usually contains the RETURN keyword, instead of a reduction label, to specify that the flow of control should return to the caner of the SEMANTIC_ANALYSIS procedure. On return from SEMANTIC_ANALYSIS, the translation is complete. Often if several reductions appear in a set of reductions, a reduction label is used in their next-reduction field (rather than a RETURN keyword) to branch to a final · reduction that performs epilogue actions and then returns via a RETURN keyword. Having only one of the reductions perform the epilogue actions reduces the amount of translation code generated by rdc. SAMPLE REDUCTIONS Figure 3-7 shows the Backus-Naur Form (BNF) for the syntax of a language that identifies records to be read or written from a tape file on a particular volume, using a given record format Several examples below employ this language to illustrate the use of reductions. ::= Volume: [,{gtrackI7track}] {ReadIWrite} ; File ; Records: [, ] •.. Format: {FIFBIFBSIVIVBIVBSIU} ; Figure 3-7. BNF Syntax for a Tape Language 3-770 AG92-Q6 reductions reductions Figure 3-8 shows how reduction statements can be used to define the syntax of the tape language (see "Relative Syntax Functions" above.) Note_thatJ'ed:u~tiQn~ CQn~i:nJJ;lg_QnlYJln or SYl1ta~ specificaJiQn are included in each group of reductions to detect errors. The reduction matches any token phrase except the empty token phrase (a phrase containing no tokens because all of the input tokens have been translated). The reduction matches empty token phrases. BEGIN stmt vol / / / / / / / / Volume: Read ; Write; File Records : Format : / / / / / / / / vol stmt stmt stmt / numbers / format / stmt / RETURN / / / / / , 9track ; , 7track ; / / / / / / / / / / / / / \ \ \ \ \ \ \ \ stmt tmt stmt stmt \ \ \ \ / RETURN \ numbers / / / I / / / punct / punct \ \ / RETURN \ punct / / / / / numbers \ / stmt \ / numbers \ / RETURN \ / / / / / / / / / / / / / / / / / stmt stmt stmt stmt stmt stmt stmt stmt \ \ \ \ \ \ \ \ / RETURN \ / / / / format / F ; / FB ; / FBS ; / V; / VB ; / VBS ; / U; / / Figure 3-8. Reductions for the Tape Language 3-771 AG92-06 reductions reductions ACTION FIELD OF A REDUCTION STATEMENT When a valid token phrase matches the syntax specifications of a reduction statement, the phrase must be translated according to the semantics of the source language. The translator does this by invoking the action routines specified in the action field of the matched reduction. These routines are invoked in the order of their appearance in the action field. There are two types of action routines: those that perform some translation action on the current token phrase, and those that perform a lexing action to make another token the current token so that a new token phrase can be translated. Translation action routines are described below, and lexing routines are described under "Lexing Action Routines," which follows. TRANSLATION ACTION ROUTINES Translation action routines translate token phrases that match reductions according to the semantics of the source language. For example, they can construct tables; build compilation trees; generate object code, ALM statements, or PL/I statements; or perform any other type of translation function that can be expressed in the PL/I language. There are two kinds of translation action routines: action subroutines. action statements and calls to ACTION STATEMENTS An action statement is a PL/I statement that appears in the action field of a reduction, enclosed in square brackets without its semicolon statement delimiter. For example, a tape language source string of Write; might be translated by setting a mode variable as follows: [mode = "W"] Action statements can be used to perform the simplest translation operations, such as turning on a bit or assigning a particular value to a variable. Such simple operations occur frequently in translators, and are most clearly and easily expressed as a PL/I statement Action statements can use the token_value variable, just as relative syntax functions do, to reference the character string value of the current token. For example, the tape language string Volume: 70092; might be translated by making 70092 the current token, and then invoking an action statement like [volume = token_value] 3-772 AG92-06 reductions reductions Action statements can also use the token structure to reference the descriptor of the current token or a semantic value structure chained to the descriptor. For example, the tape- language sourCe string File 4; might be translated by a reduction of the form / File ; / LEX [file no=token.Nvalue] LEX12) / \ where LEX and LEX(2) are a lexing action routines that make the next, or second next, token be the current token. Notice that. in the reduction above, the relative syntax function sets token.Nvalue when it validates the syntax of the "4" token. More than one PL/I statement can be used as an action statement if the PL/I statements are separated by a semicolon (;). This allows compound PL/I statements to be used as action statements. For example. the action statement [if token_value = "SCRATCH" then volume = "scratch"; else volume = token_value] checks for the special tape volume name SCRATCH and uses scratch in its place if found; otherwise. the token value given in the source string is used as the volume name. ACTION SUBROUTINES An action subroutine is a PL/I subroutine that performs some translation operation. It appears in the action field of a reduction as a PL/I call statement, without the call keyword or the semicolon statement delimiter. For example. the subroutine call perform_io ("tape_input", volume, file_no, mode, "l"b); appears in the action field as: A subroutine with no arguments, such as: call set_record_no(); appears as: An example of a reduction containing action subroutines is 3-773 AG92-()6 reductions reductions / / perform_io("tape_input", volume, file_no, mode, "1"b)/ \ The programmer must supply these action subroutines as part of the translator. Usually they are internal procedures defined in the main procedure of the translator. This facilitates references to the tokens being translated and to other data declared in the translator. However, an external procedure can be used as an action subroutine by calling it with arguments to pass any required information. NAMING REQUIREMENTS FOR ACTION ROUTINES Several facts must be considered when defining action subroutines and other variables used in the action field of a reduction. First, action statements and subroutines are executed within the SEMANTIC_ANALYSIS procedure. Therefore, all variables used in action statements or as arguments to action subroutines must be declared in the main procedure of the translator. Similarly, internal action subroutines must be defined in this main translator procedure, and external action subroutines must be declared there. Figure 3-2 illustrates the relationship between the main translator procedure and the SEMANTIC_ANALYSIS procedure. Second, care must be taken to avoid naming conflicts between the variables declared by SEMANTIC_ANALYSIS and the variables and subroutines used in the action field. With only a few exceptions, the variables used by SEMANTIC_ANALYSIS have uppercase names. Therefore, the programmer can avoid name conflicts by using names with one or more lowercase letters or digits. There are three classes of exceptions to the uppercase naming rules used in SEMANTIC_ANALYSIS. First, SEMANTIC_ANALYSIS has declared the following PL/I built-in functions: addr, max. nUll, search. substr. and verify. Second. SEMANTIC_ANALYSIS has declared the cv_dec_check_ subroutine to implement the built-in syntax function. Third, the variables and structures required to reference tokens and their descriptors are declared by the reductions command in the main procedure of the translator. SEMANTIC_ANALYSIS assumes the existence of these declarations. which have lowercase names. (Refer to the description of the lex_strinL subroutine for a complete declaration of these variables.) All three classes of exceptions must be avoided when naming variables and action subroutines. LIST OF LEXING ACTION ROUTINES Lexing action routines are useful in two ways. They can skip over a token phrase once it has been translated so that the next token phrase can be analyzed. Also, they can skip from the first token of a phrase to another of its tokens so that a translation action routine can reference that token. By default, the first token of the phrase that matches the reduction syntax field is the current token when the routines in the action field are invoked. 3-774 AG92-()6 reductions reductions The following lexing action routines are provided by the reductions command. LEX(N) makes the Nth taken the new current token, where N is the token number relative to the existing current token. The current token has a relative token number of O. Positive relative token numbers denote tokens following the current token, while negative numbers denote tokens preceding the current token. Thus, LEX(3) makes the third token following the current token the new current token. LEX is equivalent to LEX(1). NEXT_STMT makes the first token of the next statement (the statement following the statement that contains the current token) the new current token. This lexing routine can only be used when the tokens have been parsed with statement descriptors. NEXT_STMT is most useful to skip over the remaining tokens of a statement when an unrecoverable error has been detected in the statement DELETE(M.N) un threads tokens from the token list so that they are not scanned by subsequent reductions. Tokens are unthreaded (deleted) from the Mth token relative to the current token through the Nth relative token. Thus. DELETE(2,3) deletes the second and third tokens following the current token. When the current token is one of those being deleted. the next token following those deleted becomes the current token. Thus, DELETE(-l,+l) deletes the token preceding the current token, the current token, and the token following the current .token, and makes the second token following the current token the new current token. DELETE(N) is equivalent to DELETE(N,N). DELETE is equivalent to DELETE(O.O). DELETE_STMT deletes all tokens of the current statement. making the first token of the next statement the new current token. The current statement is the statement containing the current tokens. DELETE_STMI can only be used when the tokens have been parsed with statemen~ descriptors. USING LEX!NG ROUT!NES !N TRANSLAT!OlV SUBROUT!NES Lexing action routines can be invoked from translation action subroutines if it is necessary for the subroutine to examine more than one token in the current token phrase. However, use of lexing routines from translation subroutines can obscure the translation process because the lexing is perf ormed unexpectedly by a translation subroutine, rather than in the action field of a reduction where it is highly visible. If a translation routine examines only one token, it is best to place a LEX operation in the action field to make the desired token current before the translation routine is 3-775 AG92-()6 reductions reductions invoked. If the routine must examine several tokens, it is best to position to the first of these tokens before the routine is invoked and to include the number of tokens skipped over by the routine in its subroutine name (e.g., process_names_and_LEX2). Such naming makes the lexing action of the translation routine more visible when reading the reductions. A translation subroutine can call the internal procedures that rdc defines in a translator to perform the lexing actions. These internal procedures have the following calling sequences. declare LEX entry (fixed bin); call LEX (N) ; where N is the token number relative to the existing current token. declare NEXT_STMT entry; call NEXT_STMT(); declare DELETE entry (fixed bin, fixed bin); call DELETE (M, N); where tokens are un threaded (deleted) from the Mth token relative to the current token through the Nth relative token. declare DELETE_STMT entry; call DELETE_STMTO; Notice that only the two-argument version of DELETE and the one-argument version of LEX can be used from translation routines. If the particular routine to be called has not been used in any reduction, it must be explicitly included in the translator by using an INCLUDE attribute declaration statement, as described below under "Attribute Declarations. " SAMPLE REDUCTIONS Figure 3-9 shows the reductions for our tape language, with the action fields filled in. Notice that only one of the reductions performs epilogue functions, and that this reduction receives control from all other reductions. The action field of reductions that identify invalid phrases have not, as yet, been specified. 3-776 AG92-D6 reductions BEGIN stmt reductions / Volume I-Read; / Write; I File vol I I I I Records : Format : I I I I I , 9track ; , 7track ; numbers I I I I LEX(2) [volume=token value] [track = 9] LEX I vol \ I LEX (2) [mode=lIr"] I stmt \ I LEX (2) [mode="w"] I s tmt \ I LEX [file no=token.Nvalue] LEX(2) / stmt \ I LEX(2) I numbers\ I LEX(2) I format \ I NEXT STMT I stmt \ I perform_io("tape_input ll , volume, file no, mode, II 1lib) / end \ I I I I I LEX I stmt LEX (3) / stmt [track = 7] LEX(3)/ stmt NEXT STMT I stmt I end \ \ \ \ \ I set_record_no LEX / punct I LEX / punct / / end \ \ \ punct I, I I I / LEX I LEX / LEX / format IF; I FB ; / / / / / / / / / / FBS ; V ; I I / I I I end VB ; VBS ; U ; / I LEX (2) format LEX (2) format LEX (2) format LEX (2) format LEX (2) format LEX (2) format LEX (2) format NEXT_STMT (1) (2) (3) (4) (5) (6) (7) / epi logue / epilogue / / / / numbers\ stmt \ numbers\ end \ / / / / / I / / / stmt stmt stmt stmt stmt stmt stmt stmt \ \ \ \ \ \ \ \ \ / RETURN \ / RETURN \ Figure 3-9. Reductions for the Tape Language (Error-Diagnosing Actions Omitted) 3-777 AG92-06 reductions reductions ERROR-DIAGNOSING ACTION ROUTINES Translators must identify and translate all valid token phrases in the source string, and must identify and diagnose all invalid token phrases to aid in their correction. Invalid token phrases can be detected in several ways. 1. Following a series of reductions that identify the valid token phrases for a given language construct, a reduction with an syntax specification can be used to match all other invalid token phrases. 2. Specific reductions can identify predictable errors, such as tokens that do not match the specifications of the relative syntax function in a preceding reduction, or token phrases that have missing or invalid punctuation, misspelled or invalid keywords, and the like. 3. A reduction with a syntax specification can be used to detect a premature end of the source string. 4. Action routines can detect an inconsistency in the seman tic meaning of the source string and can diagnose the error. When an error is detected. the translator must notify you of the type and location of the error. The reductions command provides two facilities for printing error messages: the ERROR action subroutine and the lex_error_ external subroutine. THE ERROR ACTION SUBROUTINE The ERROR action subroutine is an internal procedure provided by the reductions command to print error messages. It can be called as follows: declare ERROR entry (fixed bin(17»; call ERROR (error_number); The error_number can be an arithmetic constant or the name of a PL/I variable that can be converted to a fixed binary number. For example, ca 1 1 ERROR (5); or declare missing_semicolon_error fixed bin(l7) internal static opt ions (cons tant) in it (5) ; ca 11 ERROR (m iss i ng_sem i co lon_error) ; ERROR can be used in the action field of a reduction that identifies invalid token phrases. For example, / / ERROR(l) NEXT_STMT / stmt \ 3-778 AG92-06 reductions reductions or it can be called from an action subroutine to diagnose a semantic inconsistency. ERROR prints messages that have the following form: prefix error_number, SEVERITY severity_no IN STATEMENT k OF LINE 1. error_message_text SOURCE: statement_containing_current_token_phrase For example. ERROR 7, SEVERITY 2 IN STATEMENT 2 OF LINE 2. A bad track specification was given in a Volume statement. 9track has been assumed. SOURCE: Volume: 70082, 8track; ERROR prints the error messages declared in an error_control_table structure array variable that the programmer declares in the main procedure of the translator. Each structure element in the array defines an error message, and the error_number is the array index of the desired error message. The structure contains a severity level associated with the error, a switch that controls the printing of the current statement as part of the error message, a long form of the error message text, and a brief form of the error message text. The error_control_table must be declared as a one-dimensional array of structures, with a lower bound of one, and an upper bound equal to the highest error_number that can be used. Figure 3-10 below shows a typical error_control_table declaration. 3-779 AG92-{)6 reductions reductions dell error control table (7) internal static options (constant) t 2 sever i -ty fixed bin (17) una 1 i gned i nit (3, 2, 3, 2, 3, 2, 2), 2 Soutput_stmt bit(l) unaligned init ("l"b, "l"b, "Ollb, "l"b, 1I1"b, 1I1"b, II 1lib) , 2 message char (70) varying init( "An unknown statement has been encountered.!!, II IAa lis an i nva 1 i d record number. ", IITranslator input ends with an incomplete statement.", IIIAa l is invalid punctuation in a list of record numbers.", IIIAal is an inval id record format.", "Input follows the end of the tape file specification.", IIA bad track specification was given in a Volume statement. 9track has been assumed.") , 2 brief message char (28) varying init( "Unknown statement.", "Bad record number IAal.", "Incomplete statement. lI , "Inval id punctuation lA.a l • ll , III nva 1 i d record format I A. a I .11, "Too much input.", "Bad track in Volume."); Figure 3-10. error_control_table for the Tape Language The severity_no associated with an error controls the prefix that is placed in the error message, as shown in Table 3-2 below. Table 3-2. RELATIONSHIP OF error_control_table. severity_no TO ERROR MESSAGE PREFIX PREFIX EXPLANATION o COMMENT Comment. The error message is a comment, which does not indicate that an error has occurred, but merely provides information for you. 1 WARNING Warning only. The error message warns of a statement that mayor may not be in error, but compilation continues without ill effect. 2 ERROR Correctable error. The message diagnoses an error that the translator can correct, probably without ill effect. Compilation continues, but correct results cannot be guaranteed. SEVERITY 3-780 AG92-06 reductions reductions 3 FATAL ERROR An uncorrectable but recoverable error. The translator has detected an error that it cannot correct Translation continues in an attempt to diagnose further errors~ . . -but no- output is produced by the translation. 4 TRANSLATOR ERROR An unrecoverable error. The translator cannot continue beyond this error. The translation is aborted after the error message is printed. The statement and line numbers in the printed message are obtained from the descriptor of the current statement. if statement descriptors are available, or from the descriptor of the current token. The phrase "IN STATEMENT k OF LINE I" appears if statement descriptors are available. Line I is the line number on which the statement containing the current token begins. Statement k identifies which statement in line I is in error. if more than one statement appears in line 1. "STATEMENT k OF" is omitted from the message if only one statement appears in Line 1. If no statement descriptors are available, the phrase "STATEMENT k OF" is omitted from the message. Line I is the line number on which the current token appears. If Pthis_token is nUll, the phrase "IN STATEMENT k OF LINE I" is omitted altogether. since there is no current statement and no current token. \Vhen the output_stmt_sw of an error is on, the current statement is included in the printed error message. The stmt.output_in_err_msg switch is turned on in the statement descriptor to prevent the source statement from being reprinted in subsequent error messages. Since the current statement is obtained from its statement descriptor, the translator must parse its source string with statement descriptors. If statement descriptors are not present, error_control_table.output_stmt_sw has no effect. Refer to the description of the lex_strin~ subroutine for information about the structure, contents, and generation of statement descriptors. The printed error message contains either the error_message_text or the brief_message_text. depending upon the value of the SERROR_CONTROL variable. This variable is declared by the reductions command, in the main procedure of the translator, as follows: de 1 SERROR_CONTROL bit (2) in it i a 1 ("OOllb); Table 3-4 below shows how the setting of these bits controis the r_message_text in the printed error message. 3-781 AG92-()6 reductions reductions SERROR_CONTROL BITS CONTROL THE error_message_text Table 3-3. SERROR_CONTROL INTERPRETATION "OO"b The printed error contains the error_message_text the first time the error occurs and the brief_message_text for subsequent occurrences of that error during a given translation. "10"b The printed error always contains the error_message_text. "11"b The printed error always contains the error_message_text. "OI"b The printed error always contains the brief:...message_text. The reductions command declares the SERROR_PRINTED variable in procedure of the translator as follows: the main dcl SERROR PRINTED (dimension(error control table), 1) bit(l) unaligned initial(dimension(error_control_table, l)(l)1I0Ilb); The ERROR routine turns on SERROR_PRINTED(error_number) whenever an error message is printed, and uses the current value of SERROR_PRINTED to control the printing of the error_message_text or brief_message_text when SERROR_CONTROL equals "OO"b. The translator can be implemented with control arguments to alter the use of error_message_text or brief_message_text in error messages. For example, the reductions command uses the normal value ("OO"b) by default, but implements the -brief (-bf) control argument to set a brief value ("01 "b) and the -long (-lg) control argument to set a long value ("10"b). The error_message_text and brief_message_text of an error are defined as ioa_ control strings that can contain up to three occurrences of the Aa control code. Each occurrence of Aa is replaced by the token_value character string value of the current token. In addition, any number of the following ioa_ control codes that do not require an input argument can be used in the error_message_text and brief_message_text strings: A/, I, AX, and The ioa_ subroutine imposes a maximum length of 256 characters on the errof_message_text and on the brief_message_text after all ioa_ substitutions have been performed. A_, A AA. The ERROR routine maintains the severity of the highest severity error encountered during a translation in the variable dcl MERROR_SEVERITY fixed bin(17) initial (0); which the reductions command declares in the main procedure of the translator. The translator can reference the value of this variable to determine whether an uncorrectable error has occurred or to determine when to abort the translation due to 3-782 AG92-()6 reductions reductions The ERROR routine is also controlled by the values of MIN_PRINT_SEVERITY and PRINT_SEVERITY_CONTROL. These variables are declared by the rdc command. in the main procedure of the translator. as follows: del MIN PRINT SEVERITY fixed bin initial (0); del PRINT_SEVERITY_CONTROL bit (2) aligned init ("l 1lib) ; MIN_PRINT_SEVERITY defines the minimum severity of error that is printed; that is. all calls to ERROR having error_control_table (error_number). severity_no greater or equal to MIN_PRINT_SEVERITY results in calls to lex_error_. The lex_error_ subroutine operates on the values of MERROR_SEVERITY and SERROR_PRINTED as part of its function. If the severity associated with the error is less than MIN_PRINT_SEVERITY. the ERROR routine does not call lex_error_; however. according to the value of PRINT_SEVERITY_CONTROL, it manipulates the values of MERROR_SEVERITY and SERROR_PRINTED. Table 3-4 shows this interaction. Table 3-4. PRINT_SEVERITY_CONTROL Bits Control the Values of MERROR_SEVERITY and SERROR_PRINTED PRINT_SEVERITY_CONTROL INTERPRET ATION "OO"b Neither MERROR_SEVERITY nor SERROR_PRINTED are changed. "01 "b SERROR_PRINTED is updated as though the error had been printed. "10"b MERROR_SEVERITY is updated as though the error had been printed. "11"b MERROR_SEVERITY and SERROR_PRINTED are both updated as though the error had been printed. The ERROR action routine and declarations for SERROR_CONTROL. SERROR_PRINTED, and MERROR_SEVERITY are automatically included in the main procedure of the translation when ERROR is used in the action field of one or more reductions. An INCLUDE attribute declaration can be used to include these error diagnostic facilities when the ERROR routine is used only by other action routines, and does not appear in any reductions. Refer to "Attribute Declarations" below for more information. THE lex_error_ SUBROUTINE The ERROR action routine is a very simple diagnostic tool, but this simplicity is possible only because ERROR does not generate highly specific error messages containing several different variable information fields. ERROR only allows the character string value of the current token to be included in the message. 3-783 AG92-{)6 reductions reductions ERROR uses lex_error_ to print its error messages. The translator can call lex_error_ directly to produce more flexible error messages. In this way. error messages containing more than one token value, or containing variables defined by the translator. can be printed using a standard mechanism. (See the lex_error_ subroutine.) SAMPLE REDUCTIONS--COMPLETE Figure 3-11 shows the reductions for the tape language with errors being diagnosed by the ERROR action routine. BEGIN stmt / Volume / Read ; / Write; / File / / / / vol /. / / / / numbers / / / punct / format end / / / / / / / / / / / / / / Records : Format : ., , 9track ; 7track ; , F ; FB ; FBS ; V ; VB ; VBS ; U ; Figure 3-1l. / LEX (2) [volume=token_value] [track = 9] LEX / vol \ / LEX (2) [mode=" r "] / stmt \ / LEX (2) [mode="w"] / stmt \ / LEX [file_no=token.Nvalue] LEX (2) / stmt \ / LEX (2) / numbers\ / LEX (2) / format \ / (ERROR (1) NEXT STMT / stmt \ / perform_io("tape_input", volume, f i 1e_no, mode, II 1lib) / end \ / LEX / stmt \ / LEX 0) / stmt \ / [track = 7] LEX 0) / stmt \ / ERROR (7) NEXT_STMT / stmt \ / ERROR (3) / end \ / / / / / / / / / / / / / / / / / / set record no LEX ERROR (2) LEX ERROR (3) LEX LEX ERROR (4) LEX ERROR (3) LEX (2) format (1) LEX (2) format (2) LEX (2) format 0) LEX (2) format (4) LEX (2) format (5) LEX (2) format (6) LEX (2) format (7) ERROR (5) NEXT_STMT ERROR (3) ERROR (6) epilogue epi logue / / / / / / / / / / / / / / / / / / punct \ punct \ end \ numbers\ stmt \ numbers\ end \ stmt \ stmt \ stmt \ stmt \ stmt \ stmt \ stmt \ stmt \ \ RETURN \ RETURN \ Compleie Reduciions for ihe Tape Language 3-784 AG92-06 reductions reductions REDUCTION SUBROUTINES Often a new language contains phrases that are similar in form but that differ in their use of· keywords, types of keyword operand values expected, or in other minor ways. As an example, the value language specified in Figure 3-12 below includes three types of statements, each of which begins with a keyword followed by a punctuated list of keyword operand values. ::= Name: [, ] •.• ; Attribute: [, ] ••• Value: [, ] ••• I : := is the name of a variable. : := fixed ::= Figure 3-12. I float I decimal I binary is a numeric value to be assigned to a variable. BNF Specification for the Value Language Since all the punctuated lists used in each statement have the same form, a single group of reductions can be written to translate the punctuation for all three types of statements. This sharing of reductions reduces the total number of reductions needed to translate the value language. Reduction subroutines provide the facility for shared reductions. A reduction subroutine is a group of reductions. As with a PL/I subroutine, a reduction subroutine has a primary entry point named by the label given in the label field of its first reduction. Alternate entry points are identified by the labels on other reductions in the subroutine. For example, the following reduction subroutine has a primary entry point of punct and an alternate entry of punct_no_comma. punct / , punct_no_comma / / / / LEX / STACK_POP\ / LEX / ERROR (7) NEXT STMT / ERROR (4) / STACK POP\ / stmt - \ / RETURN \ A reduction calls a reduction subroutine by storing a return label in a label stack (a pushdown stack of label values), and then giving the subroutine entry point name in the next-rcGuctioli field. The 5ubrouthit: reduction labeled by thaI enlry point name is then the next reduction that is compared with the current token phrase. When the reduction subroutine has completed its translation of input tokens, it returns to the calling reduction (or group of reductions) at a label that the caller stores in a label stack prior to the call. For example, the punct subroutine shown above is called by each reduction in the group shown below. 3-785 AG92-()6 reductions reductions attr / fixed / float / / LEX attr (1) PUSH (attr) / LEX attr(2) PUSH (attr) / ERROR (5) LEX PUSH (attr) / punct / punct / punct \ \ \ The label stack performs the same function as the activation stack for PL/I subroutines. A caller stores the desired return point label on the top of the stack by giving that return point label in the PUSH label stacking action routine. The caller then transfers to the desired subroutine entry point by giving that entry point label in its next-reduction field. The called subroutine returns by using the ST ACK_POP keyword in the next-reduction field of one or more of its reductions. STACK_POP causes a transfer to the label on top of the label stack as it removes that label from the stack. The next few paragraphs describe more fully the facilities for writing and calling reduction subroutines. A set of reductions for translating the value language follows this description. LABEL STACK ACTION ROUTINES Two action routines manipulate the label stack used by reduction subroutines: PUSH and POP. PUSH pushes the named label onto the top of the stack. Up to 10 labels can be stored in the stack by default POP pops the top label off the top of the label stack. The label below the popped label becomes the new top of the stack. If the popped label is the only label· in the stack, the stack becomes empty. If no labels are on the stack before popping, the POP is ignored. If a PUSH would cause the label stack to overflow, then PUSH calls the lex_error_ subroutine to report a severity 4 error and then calls the cu_$cl entry point to return to command level. A start command cannot be given, but translator maintenance personnel can perform debugging operations to determine why the stack has overflowed. By default, only 10 labels can be stored in the stack. This number can be increased by use of the MAX_DEPTH attribute declaration. See "Attribute Declarations" below for more information. POP is useful for reduction subroutines that are called by stacking two return labels, a normal return label, and an error return label, before transferring to the subroutine. The following example illustrates this usage. 3-786 AG92-06 reductions reductions attr / LEX attr (1) PUSH (attr) PUSH (syntax_err) / LEX attr (2) PUSH (attr) / float -PUSl1 tsyntax_ err-) / / ERROR (5) LEX PUSH (attr) PUSH (syntax_err) / fixed / punct \ / punct-- \ / punct \ / stmt \ syntax_err / punct / ERROR (6) POP NEXT_STMT / , / LEX POP / / LEX POP / / / STACK POP\ / STACK-POP\ / STACK=POP\ The label stack is implemented as an array of fixed binary integers. The reductions command converts all labels appearing in a PUSH action routine to a reduction number that is passed as an argument to a PUSH internal procedure provided by the reductions command. The PUSH procedure increments a STACK_DEPTH variable that records the array index of the top stack element, and then stores its input reduction number in the new top-of-label-stack element. POP pops the top label from the stack by decrementing STACK_DEPTH. It is sometimes useful to clear the label stack when an error occurs. This can be done by an action statement that sets STACK_DEPTH to zero. LABEL STACK NEXT-REDUCTION KEYWORDS Two keywords can be given in the next reduction field of a reduction to perform reduction subroutine return operations: STACK and STACK_POP. STACK transfers to the label stored on top of the label stack. If the label stack is empty, then no STACK operation occurs, and a transf er occurs to the next reduction (the reduction following the one that used the STACK keyword) just as if an empty next-reduction field had been given. STACK_POP performs a STACK operation followed by a POP operation. This implements the typical subroutine return operation. SAMPLE REDUCTIONS USING REDUCTION SUBROUTINES Figure 3-13 below shows the reductions required to translate the value language described in Figure 3-10. The punct reduction subroutine is caiied to process the iisi. punctuation symbols by the names, attr, and values reduction groups. These groups in turn are reduction subroutines that are called to process statement operands by the stmt group of reductions. 3-787 AG92-()6 reductions reductions The error messages used below can be summarized as follows: ERROR(1)--severity 2, unrecognized statement; ERROR(2)-severity 2, unexpected 'Aa' punctuation mark in a name list; ERROR(3)--severity 2, invalid name 'Aa' in a Name list; ERROR(4)--severity 3, incomplete statement; ERROR(5)-severity 2, invalid attribute 'Aa' in an Attribute list; ERROR(6)--severity 2, invalid number 'Aa' in a Value list; and ERROR(7)--severity 3, unexpected I Aa I when a punctuation mark was expected in a name list MAX_DEPTH 2 \ BEGIN stmt / Name / Attribute / Value: /