s7.stan.compin 08/01/83 1159.5rew 08/01/83 1004.8 27252 .ifi init_mpm "AN82-00" .srv section 7 .srv draft "" .srv draft_date "" .ifi l0h "Include File Format and Constraints" .ifi l1h "Include File Format" .ifi hit "K|include files" .ifi hit "K|include files~format" The include files used in the Multics Operating System should be in the following form: .spb .inl 10 .unl 5 1. Header lines (in comments) giving the date the include file was created, dates when it was modified, as well as why, how, and by whom. The header should begin with: .spb BEGIN INCLUDE FILE xxx.incl.lang .spb where xxx and lang are filled in appropriately. .spb .unl 5 2. The body of the include file giving declarations (or whatever). All declared variables must be commented. Any strange constructs should be clearly described. .spb .unl 5 3. The last line of an include file should be of the form: .spb END INCLUDE FILE xxx.incl.lang .spb commented appropriately. .spb .unl 5 .inl 0 .spb The following constraints apply to the variables and structure of include files: .spb .inl 10 .unl 5 1. Structures in include files should be based. .spb .unl 5 2. If a structure in an include file is based on a particular pointer, that pointer should be declared (without explicit storage class) in the include file. .spb .unl 5 3. Include files should not contain partial PL/I statements. .spb .unl 5 4. Include files should be formatted in a manner consistent with the system standards for the language in which they are written. .inl 0 .ifi l1h "Use of Include Files" .ifi hit "K|include files~use of" An include file should be used whenever more than one program references structured data. Include files can also be used to guarantee identical assumptions about naming conventions and systems of encoded values. Include files should not be used to include code that can be referenced by a subroutine call. .spb 2 If an include file exists that describes a given data structure, that include file should be used rather than creating a slightly different one describing the same structure. .ifi l1h "Naming Include Files" .ifi hit "K|include files~naming" The name of an include file is simply: .spb xxxxx.incl.lang .spb where xxxxx is the name used in the "include" statement and lang is the name of the language for which the include file applies. The primary name of the include file (xxxxx) should end in an underscore for externally advertised include files. .spb 2 Include files used by (or supporting use of) a particular subsystem should have names beginning with a prefix which identifies the subsystem. For example: .spb .inl 5 .fif iox_modes.incl.pl1 pl1_stack_frame.incl.pl1 mrds_users.incl.pl1 .fin .inl 0 .brf .ifi l1h "PL/I and ALM Include Files" .ifi hit "K|include files~ALM" .ifi hit "K|include files~PL/I" When a structure or data base is described in both PL/I and ALM include files, the include files are to make reference to each other. Also, the variable names should correspond exactly. .brp .fin .inl 0  s8.stana.compin 08/01/83 1159.5rew 08/01/83 1004.8 239022 .ifi init_mpm "AN82-00" .srv section 8 .ifi l0h "PL/I Language Conventions" .ifi hit "K|PL/I language" This section highlights the coding rules for system programs that are to be written in the PL/I language. Recommendations for generating efficient code are included. The rules are to be taken as guidelines; there will be rare programs that follow every rule. Refer to "Efficient PL/I Constructs" below. .spb 2 PL/I is the Multics Operating System programming language. However, there are several features in the language which should be avoided either because they are inefficient, they are not implemented well by our compiler, or they lead to complex coding constructs. The following language features should be avoided by subsystem programs: .spb .inl 10 .unl 5 1. use of PL/I input/output statements .spb .unl 5 2. aggregate expressions (except for assignment) .spb .unl 5 3. condition prefixes .spb .unl 5 4. use of "returns (char (*))" .spb .unl 5 5. use of the built-in function decat .inl 0 .ifi l1h "Constraints" .ifi hit "K|PL/I language~constraints" The following list describes some general restrictions and requirements: .spb .inl 10 .unl 5 1. all variable names have to be declared in a declare statement .spb .unl 5 2. each reference to a member of a structure must be qualified by the name of the level-one containing structure .spb .unl 5 3. no compilation warning messages or error messages are allowed .spb .unl 5 4. implicit conversions should not be used .spb .unl 5 5. multiple block closures by an end statement should not be used .spb .unl 5 6. the default statement should not be used .spb .unl 5 7. executable statements should be used to initialize automatic variables to make the action more explicit, rather than the initial attribute. .spb .unl 5 8. no variable names should be the same as keywords in the PL/I language. .inl 0 .brp .ifi l1h "Efficient PL/I Constructs" .ifi hit "K|PL/I language~constructs" This subsection is an informal guide to efficient use of the Multics PL/I compiler. It provides advice on how to take advantage of the good features of the compiler while avoiding its weaknesses. Emphasis is placed on constructs which produce more efficient code than others. The reader is assumed to be familiar with PL/I. .spb 2 For a semiformal definition of the language supported by the Multics PL/I compiler, see the M__u_l_t_i_c_s P_L_/_I_ L__a_n_g_u_a_g_e S__p_e_c_i_f_i_c_a_t_i_o_n, Order No. AG94. .ifi l2h "The Alignment Attributes" .ifi hit "K|PL/I language~alignment attributes" The use of the aligned attribute and the unaligned attribute can have a great effect on the speed of a program and the size of its data base. Unaligned items can start on a bit boundary (character boundary for character strings, pictures, and decimal variables), aligned items must start on at least a fullword boundary and occupy an integral number of fullwords. If a value requires 72 bits or less of storage to represent it, access of the value will be faster if its generation of storage is aligned because it can be directly loaded into the aq registers. .inl 0 .ifi l3h "Attributes with Arithmetic and Pointer Variables" .ifi hit "K|PL/I language~attributes with arithmetic and pointer variables" Access of aligned binary and pointer variables is usually faster than that of unaligned variables. The only exception to the above is that unaligned pointers that the compiler recognizes as aligned are accessed at speeds comparable to that of aligned pointers, but the former cannot be indirected through. You should use aligned binary and pointer variables for local scalar variables, and only use unaligned binary and pointer variables in large data structures where size is important, but speed of access is not. .spb 2 The alignment attribute has no effect on the access time of decimal variables or varying strings. .ifi l3h "Use of the Alignment Attributes with Short Strings" .ifi hit "K|PL/I language~attributes with short strings" A short string is defined to be a nonvarying string with constant extents whose length is less than or equal to 72 bits (eight characters). Access of aligned short strings is usually much faster than that of unaligned short strings. Thus, it is recommended that one use aligned short strings for local scalar variables, and restrict the use of unaligned short strings to large data structures where space is important. .ifi l3h "Use of the Alignment Attribute with Long Strings" .ifi hit "K|PL/I language~attributes with long strings" All nonvarying strings that are not short are considered to be long. Because these strings are too long to fit into the aq registers or their length is not known at compile time, the use of the aligned attribute does not speed up their access. It is recommended that one use the default alignment attribute--unaligned. .brp 8-3 .*.srv add_date "?" .*.srv add_letter "A" .ifi l3h "Use of Unaligned Short Variables in Arrays and Structures" .ifi hit "K|PL/I language~use of~unaligned short variables in arrays" .ifi hit "K|PL/I language~use of~unaligned short variables in structures" For the purposes of this discussion, short variables are those variables which occupy no more than 72 bits (eight characters) of storage and are declared with constant extents. .spb 2 When accessing an element of an array of short unaligned variables, the access code is quicker if a constant subscript is used, because the compiler uses an EIS (Extended Instruction Set) instruction, when the subscript is not constant, in accessing the variable. If an unaligned short variable is contained in an array of structures, and the variable is accessed with a nonconstant subscript, access code is faster if the array is declared aligned, because the use of an EIS instruction is avoided. .ifi l2h "Use of the Precision Attribute in Offset and Length Expressions" .ifi hit "K|PL/I language~use of~precision attribute in offset and length expressions" Because the Multics CPU's index registers can only hold 18 bits of information, while up to 24 bits may be needed to express the offset or length of a string for use in an EIS instruction, the compiler must make use of the precision attribute in deciding which register to use. If a subscript expression, the second or third argument of the substr builtin, or the declared length of a string has a precision of 18 or less, it can be kept in an index register, whereas if the precision is more than 18, it must be kept in the a or q register. This means, for example, that if a user knows that he wants a substring that may be more than 262,143 items long, then the precision of the third argument of substr should reflect that fact (otherwise the high-order bits of the length may be lost). Conversely, if the user knows that a string is less than 262,144 items long, he should reflect that knowledge in the precision used for subscripts and arguments to substr. (Besides looking at the precision of the length and offset expressions, the compiler also makes use of the declared string size in cases of constant extents to determine where the offset or length may be kept.) .spb 2 The general guideline is to always declare variables with the correct precision. The following precisions are guidelines when a user is not sure a smaller precision will suffice. A word offset into a segment should be declared fixed bin(18). A number of words on a segment should be declared fixed bin(19). Character string indexes and lengths should be declared fixed bin(21). Bit string indexes and lengths should be declared fixed bin(24). .inl 0 .ifi l2h "The Use of Internal Static to Simulate Named Constants" .ifi hit "K|PL/I language~use of~internal static to simulate named constants" If a variable is declared to be internal static with an initial attribute and is never set within a program, the compiler will treat it as if it were a constant. (A variable is considered set if it appears .cbn in a context in which its value could change.) .cbf Converting an internal static variable to a constant means that more efficient code will often be generated to use the variable, sometimes avoiding storage references, and that the variable will not have to be copied into the combined linkage section upon initiation of the segment. Since passing a variable as an argument .cbn by reference is a set context, .cbf one must enclose the variable in parentheses if it is to appear in an argument list. This will make the variable be passed by value and force a copy to be made at call time. The options(constant) attribute may be used to tell the compiler that the variable is not set even if passed as an argument. Making sure that such an internal static variable, which the user intends to use as a constant, is considered by the compiler to be a constant is worthwhile if the variable is not a long string which is only used in a few calls. This feature of the compiler is a good substitute for named constants which the PL/I language generally does not provide. .brp .*.srv add_date "" .*.srv add_letter "" .spf 2 When "options(constant)" is added to the declaration of an internal static initialed variable, the variable is allocated in the text section whether or not it is set or passed as an argument. The user is responsible for ensuring that the variable is not actually set, however, as this would cause faults or other errors. .ifi l2h "Use of the Initial Attribute" .ifi hit "K|PL/I language~use of~initial attribute" The compiler's implementation of the initial attribute for automatic, based, and controlled arrays is inefficient compared with the code the user can get from explicit assignment statements. Therefore, using the initial attribute in the above cases is discouraged. Since the use of the initial attribute does not generate code for static variables, the above statement does not apply in that case. Users are warned, however, that use of the initial attribute can make a program more difficult to read in some cases, and that initialization of large external static arrays this way can cause creation of a larger object segment than intended. .ifi l2h "The Assignment Operation" .ifi l3h "The Multiple Assignment Statement" .ifi hit "K|PL/I language~assignment operation" .ifi hit "K|PL/I language~multiple assignment statement" In deciding whether or not to use a multiple assignment statement rather than separate assignment statements, it is useful to know under which circumstances multiple assignment statements produce inefficient code. A multiple assignment statement of the form: .spb T1, T2, ---, Tn = E; .spb where E is not a constant, is semantically equivalent to the separate statements: .spb .fif .inl 5 V = E; .spb T1 = V; .spb T2 = V; .spb . .spb . .spb . .spb Tn = V; .inl 0 .spb .fin If the temporary represented by V can be kept in a machine register throughout the assignment, then the multiple assignment statement is efficient. Clearly, this implies that if E is longer than two words, the multiple assignment statement will _n_o_t be efficient, since E cannot fit in a register. Thus, multiple assignment statements are not efficient when the right hand side is a long string, a varying string, an entry value, a label value, a file value, a format value, an area, a decimal value, a complex value, or an aggregate. .brp .ifi l3h "Conversions" .ifi hit "K|PL/I language~conversions" All of the PL/I conversions are efficient, many of them producing inline code, while the others produce calls to any_to_any_. Inline code is produced for all cases where neither the source nor target are complex, decimal, character string, or picture (see the discussion of pictures below). Of the other cases, the following produces inline code: .spb .fif .inl 5 complex_float binary (precision<_27) = real binary; .spb real binary = complex_float binary (precision<_27); .spb real decimal = real decimal; .spb complex decimal = complex decimal; .spb real binary integer = real decimal; .spb real decimal = real binary integer; .spb character = real fixed decimal; .spb character = real binary integer; .spb .inl 0 .fin All other cases produce calls to any_to_any_. .spb 2 The convert builtin function can be used to effect conversion between character and binary and to avoid intermediate conversions that other builtins might cause. .ifi l3h "Pictures" .ifi hit "K|PL/I language~pictures" The use of pictures provides a convenient way to get efficient controlled conversion between arithmetic and character. When using pictures, the user can avoid PL/I's inconvenient conversion rules by specifying the desired format. .spb 2 While picture unpacking (going from character to arithmetic form) is done by pl1_operators_, the most common cases of picture editing (going from arithmetic to character form) are done inline. Inline code is generated for the majority of cases of editing into real fixed pictures. The cases of editing into real fixed pictures that is done by pl1_operators_ are any of the following: .spb .bba .inl 10 .unl 5 o1 the absolute value of the number's scale is greater than 31 .spb .unl 5 o1 a "y" picture character appears in a drifting field picture (e.g., $$$y99) .spb .unl 5 o1 a zero suppression character or drifting character appears to the right of the "v" picture character .spb .unl 5 o1 the inline sequence requires more than 63 micro-ops for the MVNE instruction .bea .inl 0 .brp .ifi l1h "Arithmetic Operations" .ifi hit "K|PL/I language~arithmetic operations" Most arithmetic operations are implemented with fast inline code. The one general exception is the power operator (e.g. **) which is sometimes implemented by pl1_operators_ or subroutine calls. Users are cautioned against using the "/" operator with fixed point operands as the PL/I precision rules may cause unexpected results. Use the divide builtin function instead. .ifi l3h "Binary Operations" .ifi hit "K|PL/I language~binary operations" Most binary arithmetic operations produce inline code. Multiplication of fixed binary (precision>_36) numbers utilizes pl1_operators_ references, all fixed binary division invoked by the "/" operator causes references to slow pl1_operators_ routines. .spb 2 The "**" operation generates pl1_operators_ calls for real operands and full subroutine calls for complex operands. If the operands are both real, and the second operand is a positive integer constant that could be represented as a fixed bin(35) value, inline code will be generated to do the power operation as repeated multiplications. .ifi l3h "Decimal Operations" .ifi hit "K|PL/I language~decimal operations" Most decimal arithmetic operations cause efficient inline code to be generated. The major exception is the case of one or both of the operands having a scale greater than 32 or less than -31. This case will often cause additional assignments or multiplications to be generated since the 6180 hardware only handles scales within the range -31 to 32. .spb 2 If the power operator has decimal operands, a conversion to and from binary and/or a subroutine call will be generated. .ifi l2h "String Operations" .ifi hit "K|PL/I language~string operations" All string operations (as opposed to builtins) cause inline code to be generated. In addition, some special cases cause better than usual code to be generated. .ifi l3h "Special Case of Concatenation" Concatenation is often used in constructing varying strings. A normal concatenation of the form: .spb a = b || c; .spb results in three (3) moves -- b and c are moved into a temporary, and the result is moved into a. However, a concatenation of the form: .spb vs = vs || c; .spb .brp where vs is a varying string, results in just one move -- c is moved to the end of vs. The latter special case can be used to great advantage in building varying strings. Consider the following example: .spb vs = a || b || c; .spb results in four moves and perhaps some instructions to allocate temporaries, while: .spb .fif .inl 5 vs = a; .spb vs = vs || b; .spb vs = vs || c; .spb .fin .inl 0 results in three moves with no temporaries allocated. .ifi l3h "Operations on Long Strings" .ifi hit "K|PL/I language~operations on long strings" Most statements of the form: .spb .inl 5 .fif a = b c; .spb a = translate (b,...); .spb a = bool (b,c,); .spb .inl 0 .fin where a, b, and c are long nonvarying strings, cause code to be generated that performs the operation in a temporary and then moves the result into a. However, if a is the same length as the temporary would be, and if the compiler believes that a could not possibly overlap with b or c, then the operation will be performed directly in a and no temporary will be allocated. .spf In a statement of the form: .fif .spb if a b ... .spb or .spb if bool (a, b, ) ... .spb .fin where a and b are long strings, the compiler will attempt to do the operation without allocating a temporary, by using an SZTL instruction if the value is not needed elsewhere. .ifi l3h "Aggregate Operations" .ifi hit "K|PL/I language~aggregate operations" Most aggregate operations, other than simple assignment and the use of the string and unspec builtins and pseudovariables, are relatively inefficient in the present Multics PL/I implementation and should be avoided. By simple, assignment, we mean assignment statements of the form: .spb p -> aggregate = q -> aggregate; .ifi l2h "Use of the Builtin Functions" .ifi hit "K|PL/I language~builtin functions" Most of the standard PL/I builtin functions and pseudovariables are implemented efficiently in the Multics compiler. However, there are exceptions and special cases. .ifi l3h "Arithmetic Builtins" .ifi hit "K|PL/I language~arithmetic builtins" With the exception of the divide builtin, all the arithmetic builtins cause efficient code to be generated. The divide builtin is inefficient only for some cases in which a fixed binary result is produced. If a fixed binary result is produced, a reference to a very slow pl1_operators_ divide routine is generated unless the result and both operands are unscaled with a precision less than or equal to 35. .ifi l3h "String Builtins" .ifi hit "K|PL/I language~string builtins" Efficient inline or out-of-line code is generated for all but one string builtin, decat. Execution of the decat builtin is about 50 times slower than might be expected. .spb 2 There are special cases of some of the other string builtins that cause more efficient code to be generated than is normally generated for the general case. These are: .spb .fif .inl 5 index (, ) .spb index (, ) .spb index (reverse(), ) .spb index (reverse(), ) .spb index (reverse(), reverse()) .spb search (, ) .spb verify (, ) .spb search (, ) .spb verify (, ) .spb search (reverse(), ) .spb verify (reverse(), ) .spb translate (, [,]) .spb before (, ) .spb before (, ) .spb after (, ) .spb after (, ) .spb ltrim (, ) .spb rtrim (, ) .spb copy (, expression) .fin .inl 0 .brp .ifi l3h "Mathematical Builtins" .ifi hit "K|PL/I language~mathematical builtins" References to the mathematical builtin functions are compiled either into fast references to pl1_operators_ or into slower subroutine calls. The following math builtins are implemented in pl1_operators_ if they have real arguments: .spb .inl 5 .fif atan exp sin tand .spb atand log sind .spb cos log10 sqrt .spb cosd log2 tan .spb .inl 0 .fin All other cases produce subroutine calls. .ifi l2h "The Call Statement and Function References" .ifi hit "K|PL/I language~function references" .ifi hit "K|PL/I language~call statement" When a call statement or function reference is executed, in the general case, an argument list must be constructed which takes 3 + 2*number_of_arguments words. When the new procedure block is entered, a new stack frame is established by a pl1_operators_ routine that takes around 30 instructions. This is a high overhead to have when using an important feature of PL/I that is necessary for good programming practice. The Multics system PL/I compiler has two optimizations which can greatly reduce this overhead. First, it can decide that an internal procedure or begin block may share the stack frame of another block rather than obtaining its own. A block that does not obtain its own stack frame is called a "quick" block or procedure. Second, the compiler can build argument lists to quick procedures at compile time, if the arguments have constant addresses known at compile time. These two optimizations greatly reduce the cost of call statements and function references. .ifi l3h "Determining the 'Quickness' of a Block" .ifi hit "K|PL/I language~quickness of blocks" The Multics PL/I compiler goes through a two stage process to determine which (procedure or begin) blocks can be quick, that is, which ones need not obtain stack frames. The first stage excludes blocks from being quick because of their properties. The following properties can make a block non-quick. .spb .bba .inl 10 .unl 5 o1 it is the external procedure block .spb .unl 5 o1 it is an ON-unit .spb .unl 5 o1 it has I/O statements .spb .unl 5 o1 it has format statements .spb .unl 5 o1 it has ON, or revert statements .spb .unl 5 o1 it has automatic variables with expression extents .spb .unl 5 o1 it has an entry that is assigned to an entry variable or passed as an argument .spb .unl 5 o1 it has an entry with a star-extent return value .spb .unl 5 o1 it has an entry with a star-extent parameter that is called with the corresponding argument being an expression whose length is non-constant .spb .unl 5 o1 it has an entry that is referenced in the argument list of such a call after the aforementioned argument .bea .spb 2 .inl 0 In the second stage, the compiler uses a graph of the calls between blocks, to determine which of the remaining eligible blocks can be quick. The algorithm used in this stage is an iterative one based on the constraint that a quick block may use the stack frame of one and only one non-quick block and thus may effectively be invoked from only one non-quick block. In fact, the algorithm states that a quick block may be invoked from only one stack frame, and an invocation from a quick block is considered an invocation from its owner's stack frame. .spb 2 A user can determine which blocks have been made quick by examining the symbols listing produced by the compiler. In the section marked, "STORAGE REQUIREMENTS FOR THIS PROGRAM" is a list of all the blocks in the program. If the line for a particular block contains the words, "shares stack frame of", that block is quick. .ifi l3h "Using Constant Argument Lists" .ifi hit "K|PL/I language~constant argument lists" In generating a quick procedure call, the Multics PL/I compiler can often generate a constant argument list if the addresses of the arguments are known at compile time. This saves the cost of executing instructions to set up the argument list at runtime. At this time the following constraints must be satisfied for the compiler to generate a constant argument list: .bba .spb .inl 10 .unl 5 o1 the quick procedure must contain no non-quick blocks .spb .unl 5 o1 the stack frame of the caller must be smaller than 16,384 words .spb .unl 5 o1 the arguments must be constants, expressions with operators, builtin references, function references, or automatic variables .spb .unl 5 o1 all automatic arguments must be allocated in the stack frame of the caller .spb .unl 5 o1 all automatic arguments must have constant extents .spb .unl 5 o1 all subscripted arguments must have constant subscripts .bea .inl 0 .ifi l2h "Using If Statements" .ifi hit "K|PL/I language~use of~if statements" In handling if statements containing logical operators, such as: .spb .fif if x = 0 | p ^= null | x + 33 & q = null & loaded then call b; .spb .inl 0 .fin the Multics system PL/I compiler (as of MR4.0) attempts to generate code that uses the minimum number of operations to decide the result. This is a change from previous releases of the compiler that always evaluated the complete expression in the if statement. In order for this optimization to take place, the user must specify the -optimize control argument for the compilation, there must be no irreducible function references in the expression, and the expression must evaluate to a bit(1) value. Thus a user should feel free to use logical operators in if statements without worrying about their efficiency. .spf .brp .inl 12 .unl 7 NOTE: no program may depend on the order of evaluation of operands in the expression of an if statement. Thus, the statement: .spf if p ^= null .brf & p -> q = 0 then ... .brf is illegal .spb .inl 0 Any program that _d_e_p_e_n_d_s on complete or incomplete evaluation of such an expression is in error, unless the expression contains irreducible function references, in which case complete evaluation takes place. .ifi l2h "Optimization of Comparisons" .ifi hit "K|PL/I language~optimization of comparisons" The Multics system PL/I compiler (as of MR4.0) remembers in its abstract machine state model the most recent comparison or indicator setting operation at any particular point in time in generating object code. This enables it to remove redundant comparisons in constructs such as the following: .spb .inl 5 .fif if a|[offset]) .spb .unl 5 5. avoid VFD pseudo-ops if ALM has a cleaner way to define the data, .spb .unl 5 6. use new pages for subroutines, .spb .unl 5 7. "declarations" (equ's, temp's etc.) should be at the beginning, .spb .unl 5 8. the "push" pseudo-op should not be used with an argument, and .spb .unl 5 9. no IC references should be made when the value is greater than 2. For example, .spb .inl 15 *+3 .brf 3,ic .spb .inl 10 are both invalid. .brp .fin .inl 0  appd.stan.compin 08/01/83 1159.5rew 08/01/83 1004.8 11943 .ifi init_mpm "AN82-00" .srv section "D" .srv draft "" .srv draft_date "" .ifi l0h "Registered Condition Names" .ifi hit "K|registered condition names" This section lists all registered condition names. .ifi l1h "List of Condition Names" .fif .inl 5 active_function_error alrm any_other area bad_area_assignment bad_area_format bad_area_initialization bad_dir_ bad_outward_call cleanup command_abort command_error command_query_error command_question conversion cput cross_ring_transfer db_conversion derail endfile endpage error fault_tag_1 fault_tag_3 finish fixedoverflow gate_error illegal_modifier illegal_opcode illegal_procedure illegal_return io_error ioa_error isot_fault key linkage_error listing_overflow lockup lot_fault message_segment error mme1 mme2 mme3 mme4 name no_execute_permission no_read_permission no_write_permission not_a_gate not_in_call_bracket not_in_execute_bracket not_in_read_bracket not_in_write_bracket op_not_complete out_of_bounds overflow page_fault_error parity program_interrupt quit record record_quota_overflow return_conversion_error seg_fault_error simfault_nnnnnn size stack storage store stop_run stringrange stringsize sub_error_ subscriptrange sus_ timer_manager_err trm_ transmit truncation unclaimed_signal undefinedfile underflow unwinder_error zerodivide .brp .fin .inl 0  s10.stan.compin 08/01/83 1159.5rew 08/01/83 1004.9 14877 .ifi init_mpm "AN82-00" .srv section 10 .srv draft "" .srv draft_date "" .ifi l0h "Documentation Standards" .ifi hit "K|documentation" There are two forms of documentation for the Multics system. The primary form is published manuals distributed through the marketing organization, and must conform to Honeywell Documentation Standards. This set of documents includes the Multics Programmer's Manual, the Language Manuals, the System Designer Notebooks, the Administrator Manuals, and the Program Logic Manuals. .spb 2 The second form of documentation is online information that can be read with the help command or printed. This documentation is distributed with each release of the Multics system, and must also conform to Honeywell Documentation Standards. .ifi l1h "Location of Documents" .ifi hit "K|documentation~location" Every command must have a module description in standard MPM form. The placement of this module description is determined by the nature of the command. If the command is for the general user, the description is included in the MPM itself. If it is for Administrators, Operators, or Field Engineers, it is included in the manual provided for that class of user. .spb 2 Every subroutine whose name and entrypoint are retained, and thus is externally available, has a subroutine module description prepared in the standard MPM format. The document location is determined on the same basis as for commands. .spb 2 Each available command or subroutine has an info segment that describes its use. The info segment conforms to the info segment standard described in this document. .brp .fin .inl 0  appc.stan.compin 08/01/83 1159.5rew 08/01/83 1004.9 15867 .ifi init_mpm "AN82-00" .srv section "C" .srv draft "" .srv draft_date "" .trf !! .ifi l0h "Registered I/O Switch Names" .ifi hit "K|registered I/O switch names" This section lists the names and meanings of all I/O switches that are used by system programs. .ifi l1h "List of I/O Switch Names" .ifi hit "K|registered I/O switch names~list of" .inl 25 .spf .unl 20 audit_i/o.HHMM.T switch used bu audit facility, where HHMM.T is the time switch was attached .spf .unl 20 debug_input switch from which the debug command takes its input requests .spf .unl 20 debug_output switch onto which the debug command writes its output .spf .unl 20 ec_switch_nn switch associated with the nn switch attached by the exec_com command .spf .unl 20 error_output switch onto which commands write their error messages .spf .unl 20 filenn switch associated with unitnn in FORTRAN programs .spf .unl 20 fo_!uniquename switch attached by file_output command .spf .unl 20 fo_save_!uniquename switch used by file_output to save previous attachment .spf .unl 20 graphic_input switch used for graphics input .spf .unl 20 graphic_output switch used for graphics output .spf .unl 20 lib_map_ switch used by library_map command .spf .unl 20 lib_print_ switch used by library_print command .spf .unl 20 user_i/o switch attached to interactive users primary I/O device .spf .unl 20 user_input switch from which commands and the command processor take their input .spf .unl 20 user_output switch onto which commands write their normal output .spf .unl 20 !uniquename.lila switch name used by LINUS .spf .unl 20 !uniquename.rel switch name used by LINUS .spf .unl 20 !uniquename.res switch name used by LINUS .brp .inl 0 .fin  s11.stana.compin 08/01/83 1159.6rew 08/01/83 1004.9 65727 .ifi init_mpm "AN82-00" .srv section 11 .*.srv add_date "?" .*.srv add_letter "A" .ifi l0h "Info Segments" .ifi l1h "Style" .ifi hit "K|info segments" .ifi hit "K|info segments~style" Info segments are provided to help the user. They are not intended to offer instruction in the use of Multics. When writing an info segment, use the following guidelines: .spb .inl 10 .unl 5 1. Be brief, concise, and terse. .spb .unl 5 2. Minimize words; minimize white space. .spb .unl 5 3. Assume some knowledge and experience on the part of the reader. .spb .unl 5 4. Use active verbs in the present tense. .spb .unl 5 5. Provide only essential facts; reference manuals for complex detail. .spb .unl 5 6. Remember that info segments do not replace, but rather supplement the manuals. .inl 0 .ifi l1h "Physical Appearance" .ifi hit "K|info segments~physical appearance" Info segments must be readable on all terminals supported by Multics. Therefore: .spb .inl 10 .unl 5 1. Employ a maximum line length of 71 characters. .spb .unl 5 2. Avoid tabs and needless spacing -- they slow output. Keep indentation to a minimum. .spb .unl 5 3. Avoid underlining. Underlined text is illegible on many terminals. .spb .unl 5 4. Avoid control characters; they may not be transparent when the system is accessed via certain terminals. .brf .cbd .spb .unl 5 5. Do not put the string "(END)" at the end. .spb .unl 5 6. Use MPM conventions regarding punctuation, capitalization, etc. (Described in this manual). .inl 0 .brp .ifi l1h "Naming Conventions" .ifi hit "K|info segments~naming conventions" The help command respects the star convention for segment names. Therefore, the following naming conventions should be followed: .spb .inl 10 .unl 5 1. XXX.info for command XXX, subroutine XXX, or topic XXX; e.g., help.info, random_.info, .cbn new_rates.gi.info. .cbf .spb .unl 5 2. XXX.changes.info for changes to XXX; e.g., random.changes.info. .spb .unl 5 3. XXX.status.info for status of bug fixes to XXX; e.g., basic.status.info. .spb .unl 5 4. XXX.gi.info for text info segments on general information; e.g., master_directories.gi.info. .spb .unl 5 5. MRn-n.gi.info for system release summary info segments; e.g.,MR4-0.gi.info. .inl 0 .ifi l1h "Syntax of Info Segments" .ifi hit "K|info segments~syntax" There are three kinds of info segments: command descriptions, subroutine descriptions, and all others. Rules for the first two types are strict so that the user can search efficiently for particular items. .ifi l2h "Title" .ifi hit "K|info segments~title" Some rules apply to all three types of info segments. The first line in every info segment must be a brief title line, beginning with the date of last modification. This line should be appropriate for a table of contents; for command or subroutine descriptions it will give the name(s) of the program, including abbreviations. .spb Examples of title lines: .inl 10 .spb .fif 05/13/76 announcements of future changes 06/21/76 qedx, qx 06/22/76 random_ .inl 0 .fin .ifi l2h "Paragraphs" .ifi hit "K|info segments~syntax~paragraphs" Info segments consist of a series of _p_a_r_a_g_r_a_p_h_s separated by two blank lines. The help command pauses at the end of every paragraph and asks, "More help?" so paragraphs should be neither too long, nor too short. Ten lines is the recommended maximum length for most paragraphs. .ifi l2h "Sections" .ifi hit "K|info segments~syntax~sections" A _s_e_c_t_i_o_n of an info segment consists of one or more paragraphs grouped under a title. The title is on the first line of the section; it ends with a colon, and is followed by the rest of the first paragraph. Subsequent paragraphs in the section have no titles, (i.e. their first line has no colon). The help command allows the user to print only a specified section of an info segment, or to obtain a list of the section titles in an info segment. .brp .*.srv add_date "" .*.srv add_letter "" .ifi l2h "Command Descriptions" .ifi hit "K|info segments~syntax~command descriptions" For command descriptions, the following sections must be present: .spb .inl 5 .brf Syntax .brf Function .inl 0 .spb If the command has arguments or control arguments then the following sections are required: .spb .inl 5 Arguments .brf Control arguments .inl 0 .spb If other sections are necessary they may be provided. The following names may be used: .spb .inl 5 Access requirements .brf Notes .brf Examples .inl 0 .spb 2 Other section names may be used only with the permission of the info segment censor. .spb 2 The "Syntax" section gives a sample invocation of the command. For example: .spb Syntax: list_iacl_dir {path} {User_ids} {-control_args} .spb 2 In the syntax line, optional arguments are enclosed in braces. .spb 2 The "Function" section should be a terse one- or two-line description of what the command does. Since one mode of the help command allows the user to search for paragraphs containing a specified string, it is desirable to describe the function of the command using terms that a user may be searching for; but only if this can be done concisely. .spb 2 The "Arguments" section gives a one-line description for each argument to the command. The "Control arguments" section gives a one-line description of each control argument. These section titles are plural even if only one item is described. For control arguments, default values should be indicated by the string "(default)". If an argument is too complicated to explain completely on one line, or if the command takes many interrelated control arguments, it should cross reference a longer section identified by section name at the bottom of the segment. .inl 0 .ifi l2h "Subroutine Descriptions" .ifi hit "K|info segments~syntax~subroutine descriptions" For subroutines, the following sections are required: .spb .inl 5 Function .brf Syntax per-entry .brf Arguments per-entry .brf .inl 0 .spb 2 The "Syntax" section should have an example of the declaration and invocation of the subroutine in the PL/I language unless the subroutine cannot be used from PL/I. .spb 2 The "Arguments" section is like the MPM description of the argument, but should be kept to one line per argument, with a reference to further info if necessary. .spb 2 Multiple entry procedures have multiple Syntax and Arguments sections, one for each entry point. .inl 0 .ifi l2h "Other Info Segments" For info segments describing other topics, the only explicit syntax rules are that the title be in standard form, and that paragraphs be of reasonable size. Section titles, when used, should not be fanciful. For segments like Installations.info, the section title should be the date; for pending_changes.info, it should be the date and the name of the program or function being changed. The name of info segments that contain general information should be topic.gi.info. .spb 2 See info_seg_format.info and the documentation for input_info_seg and validate_info_seg_ for detailed descriptions of info segment syntax. Also, see list.info, io_call.info, and convert_date_to_binary.info for examples of command and subroutine info segments. .brp .fin .inl  s4.stan.compin 08/01/83 1159.6rew 08/01/83 1004.9 43821 .ifi init_mpm "AN82-00" .srv section 4 .srv draft "" .srv draft_date "" .ifi l0h "Modularity" .ifi hit "K|modularity" The Multics Operating System is modularized to simplify debugging and modification and to increase reliability. In the following section, the issues and modularity which are important to designers and implementors are discussed. .ifi l1h "Program Structure" .ifi hit "K|program structure" Overall structure of each program component is to be designed with the newest techniques. Small parts of programs are to be as understandable as the total program. Using PL/I internal procedures is encouraged because they are almost as efficient as in-line code. .ifi l1h "Compilable Unit Size" .ifi hit "K|compilable unit size" Programs are recommended to be no longer than a few hundred lines of executable code. Try not to combine small components into one very large program, unless performance is affected. .inl 0 .ifi l1h "Generality of Mechanism" .ifi hit "K|mechanism~generality" Much of the uniformity of mechanism and function in the Multics system has been attained by attempting to generalize mechanisms so that they can be shared. This eliminates the need for similar facilities in distinct parts of the system that are likely to produce incompatible effects or later require unwieldy simultaneous extension. Do not generalize a mechanism if it is not justifiable, however. .inl 0 .ifi l1h "External Availability of Mechanism" .ifi hit "K|mechanism~external availability" Make each designed mechanism externally available to the rest of the system only if it is useful and there is a demand for it. Making a mechanism externally available has implications to future changes, as compatibility must then be maintained. As a result, the designer should lean towards not making it available. .inl 0 .brp .ifi l1h "Binding and Bindfiles" .ifi hit "K|binding" .ifi hit "K|bindfiles" The individual program components of the Multics system are usually bound together by the Multics binder. This is done to reduce the number of separate components visible in the system, to make internal interfaces unavailable, to conserve segment numbers, and to minimize the number of linkage faults. .ifi l2h "Contents of Bound Segments" .ifi hit "K|bound segments~contents" Programs that are logically related should be bound together and placed in an order chosen to minimize the number of page faults taken when various subsets and usage patterns of the components within are used. .ifi l2h "Names of Bound Segments" .ifi hit "K|bound segments~names" Every bound segment is named with a functionally related name starting with the string "bound_" and terminating with an underscore. The bindfile is named bound_segment_name_.bind. The bindfile and all of its components are stored in a single archive segment whose name is bound_segment_name_.archive. .ifi l2h "Bindfile Contents" .ifi hit "K|bindfile~contents" The contents of the bindfile should abide by the following conventions: .spb .inl +10 .unl 5 1. The order statement is required to specify binding order. .spb .unl 5 2. An objectname statement is required to state the name of the bound segment. .spb .unl 5 3. A global: delete; statement is required to ensure that extraneous definitions are deleted. .spb .unl 5 4. An addname statement is required to specify all names that are to be known externally. .spb .unl 5 5. Statements used only for debugging purposes are not to be used (e.g., No_link, Force_Order). .spb .unl 5 6. An objectname statement should be included for each component that has other attributes specified. Components with no attributes specified should not have a corresponding objectname statement since they will already have been named in the Order statement. .spb .unl 5 7. The retain statement is to be used only for those definitions that must be retained because they are externally available interfaces. .spb .unl 5 8. The synonym keyword is to be used to specify all synonyms for each component. .inl 0 .brp .ifi l2h "Bindfile Formatting" .ifi hit "K|bindfile~formatting" The following formatting rules are to be used for ease of reading of the bindfile: .spb .inl +10 .unl 5 1. Tabs should be used to separate keywords from their arguments. .spb .unl 5 2. Each objectname statement should be preceded by one blank line. .spb .unl 5 3. Synonym, delete, retain, and global statements should be indented one space with arguments lined up under the arguments of the objectname statement. .spb .unl 5 4. Comments should be included at the beginning of the bindfile that give the logical relationship of bound components, and that state the date, author and reason for each change. .spb .unl 5 5. A comment containing the word END should be placed at the end of the bindfile. .brp .fin .inl 0  s12.stan.compin 08/01/83 1159.6rew 08/01/83 1004.9 40770 .ifi init_mpm "AN82-00" .srv section 12 .srv draft "" .srv draft_date "" .ifi l0h "Rules for Translator Writers" .ifi hit "K|translator writer rules" .ifi hit "K|translator writer rules~command program" .ifi l1h "The Command Program" The command program that invokes the translator should expect to find a source program with the suffix .__l_a_n_g if lang is the name of the command. .spb 2 The command program should establish a cleanup handler to clean up any temporary storage being used by the translator in case of an abnormal termination. .spb 2 The command program should establish an any_other handler to trap all unexpected faults. All system conditions should be passed on to the system default handler. .spb 2 The command program should detect that it is being invoked reentrantly (i.e., with a suspended invocation dormant in the process) and, if the translator can not be used in this fashion, should ask the user if he wishes to continue and act accordingly. .inl 0 .ifi l1h "The Object Segment Created" .ifi hit "K|translator writer rules~object segment created" Translators should create Multics standard object segments. The object segments should not make reference to any system data bases other than the stack segment header. No assumptions should be made about the call/push/return conventions and the format of a stack frame header. The first 32 words of a stack frame header are reserved for system use and should not be referenced by the object code. .spf 2 An operator segment, containing code and necessary references to system data bases, should be used to guarantee compatibility from one system release to another. The operator segment should be found (by the object code) by means of the operator_pointers_ mechanism in the stack header. .spb 2 As many code sequences as possible should be placed in the operator segment to minimize the size of the object segment. .spb 2 The operator segment should contain all of the system dependent code used by the object segment (e.g., references to system data bases). .spb 2 A standard table giving names of the operators should be provided. This table should be called lang_operator_names_ where lang is the name of the translator command. .ifi l1h "Listing Output" .ifi hit "K|translator writer rules~listing output" The translator should create an optional listing of the translation. This listing should be created whenever the control arguments -list, -map, -symbols, or -source are specified. The -map control argument should cause the translator to generate the "most commonly wanted" form of output. .spb 2 The output listing, which must allow for multisegment files, should contain the following: .spb .inl 10 .unl 5 1. descriptive lines indicating when the program was compiled, by which version of the translator, and with what control arguments .spb .unl 5 2. a line-numbered listing of the source used, include file source should be distinguishable from top-level source .spb .unl 5 3. pathnames of all source segments used including include files .spb .unl 5 4. a list of externally referenced names .spb .unl 5 5. a list of operators used .spb .unl 5 6. a list of variables used giving storage attributes and where the variables were referenced .spb .unl 5 7. a table of the storage requirements used by the compiled program. .spb 2 .inl 0 If the -list control argument is specified, the following should also be included: .spb .inl 10 .unl 5 1. a listing of all constants and literals used by the program .spb .unl 5 2. a listing of the source lines that generated the object code interspersed with the object listing appropriately .sp .unl 5 3. "comments" in the object listing indicating which variable is being referenced, which operator is being used, etc. .spb .unl 5 4. relocation information with each word of generated code .spb .unl 5 5. appropriate interpretation of noninstruction data (e.g., ASCII data should be printed out in ASCII as well as octal) .inl 0 .ifi l1h "Miscellaneous Requirements" .ifi hit "K|translator writer rules~miscellaneous requirements" The translator should use the standard search path facility to locate any include files (or analogous constructs) used by the program being translated. .spb 2 The subroutine tssi_ should be used to create object segments and listing files. .spb 2 The ACL on an object segment should be left after translation just as it was before translation. .brp .fin .inl 0  book.stana.compin 08/01/83 1159.6rew 08/01/83 1015.0 4806 .ifi init_mpm "AN82-00" .srv Charsw -1 .ifi toc_on .ifi tab_on .srv draft "" .srv draft_date "" .ifi tp.stana.compin .ifi pf.stana.compin .ifi s1.stan.compin .ifi s2.stana.compin .ifi s3.stan.compin .ifi s4.stan.compin .ifi s5.stan.compin .ifi s6.stan.compin .ifi s7.stan.compin .ifi s8.stana.compin .ifi s9.stana.compin .ifi s10.stan.compin .ifi s11.stana.compin .ifi s12.stan.compin .ifi appa.stana.compin .ifi appb.stana.compin .ifi appc.stan.compin .ifi appd.stan.compin .brp .ifi book.stana.toc.compin .ifi book.stana.tab.compin  s5.stan.compin 08/01/83 1159.6rew 08/01/83 1005.0 42147 .ifi init_mpm "AN82-00" .srv section 5 .srv draft "" .srv draft_date "" .ifi l0h "Environment Independence" .ifi hit "K|environment independence" Subsystems, commands, and subroutines should be implemented so that they may be used in a variety of environments without other portions of the environment affecting them and without their affecting other components of the environment. This is referred to as the principle of surroundability. Surroundability is important because it makes it possible for users and subsystem designers to integrate many portions of the Multics system to compose a new subsystem without having to change any of the components they are integrating. .ifi l1h "Reentrancy" .ifi hit "K|reentrancy" .ifi hit "K|programming standards~reentrancy" .ifi hit "K|environment independence~reentrancy" Components of the Multics Operating System should be reentrant. This is accomplished by proper use of pure procedures, the recursive nature of the PL/I language and its implementation, and careful use of static storage. If making a subsystem reentrant results in performance degradation or implemention problems, it is permissible for the subsystem to not be reentrant. In this case, checks are to be implemented to detect possible misuses of the subsystem and are to either prevent the misuse or warn the user of the possible conflict. .ifi l1h "Transparency" .ifi hit "K|transparency" .ifi hit "K|environment independence~transparency" .ifi hit "K|programming standards~reentrancy" The operation of a program should be transparent to the environment. This is accomplished by correct storage management techniques, programs cleaning up any temporary environment changes, naming conventions, I/O attachments, and avoiding other static effects on the environment. For example, if a program changed the working directory without that being a specified property of that program, then subsequent programs would behave differently than expected. .ifi l1h "Interruptibility" .ifi hit "K|interruptability" .ifi hit "K|programming standards~interruptability" .ifi hit "K|environment independence~interruptability" Programs are to be implemented so their operation can be interrupted and resumed at a later time. Programs must take precautions while they are making critical modifications to the environment. They should either prevent interrupts or be prepared to recover properly if interrupted and not resumed until after other operations that also affect the environment have been performed. For example, the I/O system should mask IPS signals when modifying IOCBs so that the quit handler will not be invoked to write a message at a time when the I/O system will not work correctly. .ifi l1h "Condition Handling" .ifi hit "K|condition handling" .ifi hit "K|programming standards~condition handling" .ifi hit "K|environment independence~condition handling" Programs should handle conditions that may be signalled because of their operation and pass on all other conditions that they cannot handle better than the default handler. .ifi l1h "Access Assumptions" Programs should execute properly under a wide range of access conditions. Access checking and condition handlers can achieve this. Programs using privileged entry points for some functions, but that are also usable by the general user, should be prepared to handle a call by a user with insufficient access. .ifi l1h "Use of Standard Mechanisms" .ifi hit "K|standard mechanism" .ifi hit "K|programming standards~standard mechanism" .ifi hit "K|environment independence~standard mechanism" Programs ought to use the standard mechanisms that are available in the system, not their own. This is important since these mechanisms are provided to permit surroundability and modularity. For example, if a subsystem needs to use a number of temporary segments, it should use the system-provided temporary segment manager, not any other. .ifi l1h "Pathnames and Search Rules" .ifi hit "K|programming standards~pathnames~search rules" .ifi hit "K|pathnames" .ifi hit "K|search rules" .ifi hit "K|environment independence~pathnames" .ifi hit "K|environment independence~search rules" .ifi hit "K|programming standards~pathnames" .ifi hit "K|programming standards~search rules" Programs should not have pathnames built into them. The standard search rule mechanism should be used to find other programs and data bases, found through the linker. Commands or subsystems for data segments should use the standard search path facility. The default search paths for a subsystem should be chosen with the general user in mind and for a specific application. .brp .fin .inl 0  pf.stana.compin 08/01/83 1159.6rew 08/01/83 1015.0 11205 .ifi init_mpm "AN82-00" .srv file_no "1L13" .srv draft "" .srv draft_date "" .ifi preface "1980" Multics System Designers' Notebooks (SDNs) are intended for use by Multics system maintenance personnel, development personnel, and others who are thoroughly familiar with Multics internal system operation, and also can be used by application programmers or subsystem writers. .spb 2 Since internal interfaces are added, deleted, and modified as design improvements are introduced, Honeywell does not ensure that the internal functions and internal module interfaces will remain compatible with previous versions. .spb 2 This SDN describes the standards, conventions, and guidelines used in the development of all Multics software and documentation. .spb 2 Throughout this manual, the term Multics refers to the Multics Operating System. .spb 2 It is important that the standards in this manual be followed to consistently maintain and support the development of the Multics Operating System. If you are a system programmer, permission should be obtained from your Technical advisor to deviate from the standards; if you are not working for Multics System Development, you can deviate from the standards. .fin .inl 0 .brp  tp.stana.compin 08/01/83 1159.6rew 08/01/83 1005.0 3996 .ifi init_mpm "" .hla 1 |||SERIES 60 LEVEL(68)| .hla 2 |||STANDARDS| .hla 3 |||SYSTEM DESIGNERS' NOTEBOOK| .trf ! .inl 5 .unl 5 .spb 7 SUBJECT: .spb Description of the Standards, Conventions, and Guidelines Used in the Software and Documentation of the Multics Operating System .spb 2 .unl 5 SOFTWARE SUPPORTED: .spb Multics Software Release 8.0 .spb 2 .unl 5 DATE: .spb June 1980 .spb 2 .unl 5 ORDER NUMBER: .spb AN82-00 .inl 0 .fin .brp .hla  appa.stana.compin 08/01/83 1159.6rew 08/01/83 1005.0 73215 .ifi init_mpm "AN82-00" .srv section "A" .srv draft "" .srv draft_date "" .ifi l0h "Registered Control Arguments" .ifi hit "K|registered control arguments" This section lists all approved control arguments and their abbreviations. Only these control arguments should be documented and accepted by commands. This applies to all commands whether they are standard user accessible commands or special tools for a particular class of users. .spb 2 For reasons of compatibility with the past, many commands are permitted to accept control arguments that have been previously documented. An exception is made for commands that are of very limited interest that accept a large number of potentially obscure control arguments; these commands may have nonstandard control arguments. If these commands are upgraded for more general use, their control arguments will have to be modified. .spb 2 If a command needs a control argument that is not registered in this list, it and its abbreviation should be defined. If the command is a special purpose tool and the control argument itself is not of general interest, no abbreviation should be defined. .spb 2 Two different lists of control arguments are presented. Table A-1 consists of general purpose control arguments, which are already used by system commands and may be expected to cover most situations. System programmers should use items from this list whenever possible. Table A-2 consists of more specialized control arguments, which cover a more limited range of situations. .brf .inl 0 .ifi tab "Approved Standard Control Arguments" .ifi hit "K|registered control arguments~approved standard" .spb 2 .fif .inl 15 -absentee -as -absolute_pathname -absp -access -ac -access_class -acc -access_name -an -account -acknowledge -ack -acl -address -addr -admin -am -after -af -alarm -al -all -a -arguments, -argument -ag -ascending -asc -ascii -assignments -asm -attributes -attr -author -at -authorization -auth -bcd .brp .*.srv add_date "?" .*.srv add_letter "A" -before -be -bit_count -bc -bit_count_author -bca -block -bk -branch -br -brief -bf -brief_table -bftb -call -category -cat -character -ch -chase -check -ck -comment -com .brf .cbd .brf -copy -cp -copy_switch -csw -count -ct -current_length -cl -date -dt -date_time_contents_modified -dtcm -date_time_dumped -dtd -date_time_entry_modified -dtem -date_time_used -dtu -date_time_volume_dumped -dtvd -debug -db -decimal -dc -default -delete -dl -delimiter -dm -density -den -depth -dh -descending -dsc -destination -ds -device -dv -directory -dr -else -entry -et -every -ev -exclude -ex -execute -extend -field -fl -file -f -fill -fi -first -ft -force -fc -from -fm -gen_type -gt -header -he -hold -hd -home_dir -hdr -id -indent -ind -input_file -if -input_switch -isw -io_switch -iosw -label -lbl -last -lt -length -ln -level -lev -limit, -limits -li -line_length -ll -lines -link -lk -link_path -lp -list -ls -logical_volume -lv -long -lg -map .brp .*.srv add_date "" .*.srv add_letter "" -mask -match -max_length -ml -maxlines -minchars -minlines -mode -md -model -modes -multisegment_file -msf -name -nm -next -nl -nnl -no_acknowledge -nack -no_address -naddr -no_header -nhe -no_offset -nofs -no_fill -nfi -no_link_translation -nlt -no_list -nls -no_notify -nnt -no_numbers, -no_number -nnb -no_pagination -npgn -no_print -npr -no_quote -nq -no_restore -nr -no_totals, -no_total -ntt -no_update -nud -non_null_link -nnlk -notify -nt -number -nb -octal -oc -off -offset -ofs -on -optimize -ot -ordered_field -ofl -outer_module -om -output_file -of -output_switch -osw -owner -ow -page -pg -page_length -pl -parameter -pm -pass -pathname -pn -position -psn -previous -prev -primary -pri -print -pr -profile -pf -project -pj -query -queue -q -quit -quota -record -rec -records_used -ru -repeat -rpt -replace -rp -request -request_type -rqt -reservation -resr -reset -rs -resource -rsc -restart -rt -reverse -rv -revert -ring -rg -ring_brackets -rb -safety_switch -ssw -search -srh -section -scn -segment -sm -sender -severity -sv -short -sh -sort -source -sc -start -sr -stop -sp -string -str -subscriptrange -subrg -subsystem -ss -switch -symbols, -symbol -sb -system -sys -table -tb -tab -target -terminal_input -ti -terminal_type -ttp -then -time -tm -title -to -total, -totals -tt -times -track -tk -truncate -tc -type -tp -unique -uq -unique_id -uid -update -ud -user -volume -vol -wait -wt -working_dir -wd .hla .brp .inl 0 .fin .ifi tab "Approved Special Control Arguments" .ifi hit "K|registered control arguments~approved special control arguments" .spb 2 .fif .inl 15 -4bit -7punch -7p -abort -accept -access_label -albl -action -age -append -app -attached -att -attachments -atm -ball -bl -bottom_label -blbl -bottom_up -bu -brief_header -bfhe -cancel -card -cc -change_default_auth -cda -change_default_project -cdp -change_password -cpw -check_ansi -chpass -cl -class -class_indentifiers -cli -cmf -cobol_switch -cs -collection, -coll -col -compile -complete -comp -comp_volume_dump_switch -cvds -copy_release_names -crn -continue -ctu -control -ct -control_arg -ca -convert -cput -date_time -day -day_name -debug_cg -deferred_indefinitely -dfi -definition -def -defs -delay -dly -detach -det -dir_mode -dont_free -dprint -dp -dpunch -dpn -ebcdic8 -ebcdic9 -edit -ed -entry_numbers -etn -entry_point -ep -exec_com -ec -expand -expanded -files -file_input -fi -flush -fnp -fold -format -fmt -foreground -fg -free -fw -generate_password -gpw -go -govern -gv -hex8 -hex9 -hyphenate -hph -immediate -in -incremental -inccost -inc_pf -inc_volume_dump_switch -ivds -inc_vcpu -in_reply_to -irt -initial_string -istr -inout -input_description -ids -interactive -ia -interactive_message -im -interrupt -int -invisible -iv -keyed -library -lib -line_numbers -ln -lmargin -lm -log -loop -long_id -lgid -lower_case -lc -mailbox -mbx -mcc -message_id -mid -meter, -metering -mt -min -minute -month -no_abort -no_canonicalize -ncan -no_endpage -nep -no_exec_com -nec -no_freeing -no_hold -nhd -no_interactive_message -nim -no_label -nlbl -no_log -no_message_id -nmid -no_null -no_orginal -no_orig -no_preempt -np -no_print_off -nprf -no_prompt -no_request_loop -nrql -no_stop_run -nsr -no_start_up -ns -no_subject -nsj -no_symbols, -no_symbol -nsb -no_warning -nw -non_edited -ned -nogo -notape -old_original -old_orig -open -original -orig -original_path -orig_path -out -output -output_description -ods -own -pdd -prefix -print_delay -pr_dly -print_edit -pr_edit -print_linkage_fault -print_new_lines -pnl .cbn -print_off -pf .cbf -process_overseer -po -prompt -proxy -raw -realt -relocatable -rlc -remove -rm -rename -rn -reply_to -rpt -report_reset -rr -request_loop -rql -retain -ret -retain_data -retd -return_value -rtv -runtime_check -rck -safe_optimize -safe_ot -save -sv -secondary -seg -seg_mode -separate_static -ss -set -set_bc -set_nl -single -sg -single_name -snm -size -skip -sk -sleep -sort_dir -sd -sort_file_size -sfs -source_switch -ssw -static -status -st -stop_proc -spp -stt -subject -sj -subtotal -stt -subtree -subt -sys -sys_id -sysid -tape -tape7 -tape9 -temp_dir -td -template -tmp -text -tx -time_ot -timers -top_label -tlbl -total_cost -total_mem_units -total_pf -total_vcpu -to_queue -to_q -to_request -to_rqt -trace -trace_linkage_faults -train -tn -unlabeled_common -uc -upper_case -uc -use_bc -use_count -use -use_nl -verbose -vb -warn -watch -year -zero_on_alloc -zero_on_free -zone .brp .inl 0 .fin  s2.stana.compin 08/01/83 1159.6rew 08/01/83 1005.0 138690 .ifi init_mpm "AN82-00" .srv section 2 .ifi l0h "Interface Standards" .ifi l1h "Command Interfaces" .ifi hit "K|interface standards" .ifi hit "K|command interfaces" Commands are a special class of programs designed with the terminal user in mind. They serve as the principal interface between the system and all of its users. Since many commands are used by both naive and sophisticated users, they must be designed with a two-fold purpose. The naive user should not be burdened with information he doesn't understand; the sophisticated user must not be denied the facilities that he needs. .spb 2 Commands should not be too powerful. The result of a typing error should not be a disaster for the user. .spb 2 Commands should be recursive, i.e., they should be able to be interrupted in midstream and invoked again. If it is inappropriate for a particular command to be used in this way, protection should be built into the command to query or inform the user. .spb 2 Commands should not retain information from one invocation to the next in such a way that behavior of the second invocation is affected by some hidden implication of the first. For example, the use of the -brief control argument in one invocation should not make all future output be in -brief form. On the other hand, a metering command that accumulates data should have a -reset option to reset the accumulated values. .ifi l2h "Storage System Conventions" .ifi hit "K|command interfaces~storage system conventions" In general, commands should deal with multisegment files as well as segments, unless inappropriate. .spb 2 Commands should not perform write operations on the components of archive segments, except for the archive, archive_sort, and reorder_archive commands. Commands should have no knowledge of the structure of archive segments, except for the commands mentioned above and the bind command. .spb 2 Generally, commands should chase links, i.e., they should perform the operation on the storage system entry to which a link points. However, there are two exceptions. Links should not be chased when the command can manipulate the attributes of the link, for example, the rename command. Links should also not be chased by default when a starname is given. The -chase control argument should be used to explicitly cause chasing of links. Refer to the copy command in the M_P_M_ C__o_m_m_a_n_d_s _a_n_d A__c_t_i_v_e F__u_n_c_t_i_o_n_s, Order No. AG92. .spb 2 A command name generally starts with a verb. Multiword names should have each word separated with an underscore. A command name should consist only of lowercase letters and the underscore character. The pl1 command is an obvious exception, but doesn't invalidate the rule. Its name was chosen by another guideline for constructing names. .spb 2 A command name should be short enough so that it may be conveniently typed. A two to four letter abbreviation should be selected using the first letter of the words or syllables of the name. If the command is in the tools library, it should not be supplied with an abbreviation. The system libraries should be checked to ensure that there are no conflicts with other installed command names and abbreviations. .spb 2 New command names should be chosen with the following distinction in mind. Commands whose names start with print should have no knowledge of the structure of the input and deal with ASCII data. Commands whose names start with display should know about the data structure of the input and produce highly structured output. Commands whose names start with dump should have little knowledge of the contents of the data, may produce octal output, and may format the output in blocks. .spb 2 Commands that are part of a subsystem should have the subsystem name or an abbreviation as a leading name. .spb 2 In general, the _s_u_f_f_i_x command should be the principal command that processes a segment whose name ends in .s__u_f_f_i_x. This is particularly true for language translators, for example, the pl1 command. .ifi l2h "Command Arguments" .ifi hit "K|command interfaces~control arguments" Commands should check carefully for argument validity and warn users of possible misunderstandings. They should be consistent in behavior and interface with other commands. .spb 2 Commands that always require arguments should print a usage line when invoked with no arguments. Commands that require no arguments should print a usage line if arguments were given. .spb 2 Command arguments should be order independent unless the order dependency serves a useful purpose (e.g., -update of the bind command). .spb 2 Commands whose interface is simple (such as the add_name command) should accept multiple arguments if appropriate. .spb 2 Commands that deal with segments whose names have a fixed suffix should not force the user to type the suffix; however, they should permit the user to include the suffix as part of the name. The expand_pathname_$add_suffix subroutine performs suffix handling for such commands. .spb 2 A series of related commands should have a similar or parallel syntax and control arguments. .spb 2 Arguments for which sensible defaults exist should be allowed to be omitted, i.e., the last access name to set_acl and the working directory as a default pathname to many commands. .spb 2 .brp 2-3 .*.srv add_date "?" .*.srv add_letter "A" It is desirable to check the validity of all arguments before beginning its execution or before terminating the command. .spb 2 Command arguments should be used, whenever appropriate, to inform the command what to do. The user should not have to type additional lines of input to control the behavior of the command. For cases where there is a great deal of input it should be possible to put the input in a control segment and to specify the pathname of the control segment as an argument to the command. .spb 2 The use of octal numbers is discouraged. An exception is the use of octal numbers to represent a segment number or segment offset, and in such cases it may be more appropriate to use a virtual pointer (as interpreted by the cv_ptr_ subroutine) or a virtual entry (as interpreted by the cv_entry_ subroutine). .ifi l2h "Pathname Conventions" .ifi hit "K|command interfaces~pathname conventions" Commands that accept pathnames as arguments should accept relative pathnames or absolute pathnames as interpreted by the procedures expand_pathname_ and absolute_pathname_. .spb 2 Commands that accept pathnames should honor the star convention whenever appropriate. Careful consideration of the interaction between the star convention and links must be given. Links are not chased by default when given a starname as an input argument. .cbd .spf 2 .cbn Commands that operate on branches accept the -chase and the -no_chase control arguments. -chase, when invoked with a starname, performs the desired operation(s) on the targets of any links which match the starname as well as those branches which match the starname. -no_chase, when invoked with a non-starname, indicates that the command should not perform the desired operation(s) if the non-starname specifies a link. The opposite control arguments may also be used (-chase with a non-starname, -no_chase with a starname). The defaults are: -chase if a non-starname is given; -no_chase if a starname is present. For example; .spf move ** === -chase .spf moves all the segments from the working directory to the directory , and also moves all segments referenced by any links in the working directory. .cbf .spf 2 Commands that accept pairs of pathnames should honor the equal convention, for example, the compare_ascii command. .spb 2 Commands that take segment names as arguments should accept pathnames and not reference names unless the command is dealing with reference names explicitly, such as the where command. .spb 2 The -name control argument should be used by commands that normally take a segment number as an argument to indicate that the argument looks like a segment number but really is a pathname. The -pathname control argument should be used by commands that normally take a pathname to distinguish pathnames beginning with a minus (-) from control arguments. .ifi dot_page "A" .ifi l2h "Control Argument Conventions" .ifi hit "K|command interfaces~control argument conventions" Commands should accept control arguments that are appropriately named and that specify needed options. Similar commands should accept the same control arguments, for example, the copy and move commands. Commands that produce output should accept the control arguments -brief, -no_header, -long, and -totals, if appropriate. .spf 2 .ifi dot_page_off Invalid or inappropriate control arguments should be diagnosed and the operation of the command terminated. .spb 2 Entry names beginning with minus signs should be considered invalid by most commands. Any unrecognized string beginning with a minus sign should be diagnosed as an invalid control argument, rather than being treated as an entry name (even by commands that do not take control arguments). If there is a need to accept entry names with a leading minus sign, the -pathname control argument may be used. .spb 2 New control arguments should not be invented when there are existing ones that serve the purpose. All control arguments should be registered. (See Appendix A for a list of registered control arguments.) .spb 2 Control arguments that are used only by commands in the tools library should not have abbreviations. .spb 2 Control arguments that take arguments should do so uniformly (from one command to another) and should always take the same type of argument. .ifi l2h "Output Conventions" .ifi hit "K|command interfaces~output conventions" Unless the purpose of a command is to produce output, it should not produce terminal output during its normal operation. The success of a command doing its job is indicated by the absence of output. However, a command that takes a long time to execute should print a short message to reassure the user that it has started, for example, the pl1 command. .spb 2 Normal output from a command should be written to the I/O switch user_output. .spb 2 Error output by a command should be printed by the com_err_ subroutine. The long name of the command should be included in the com_err_ message. The com_err_ message should give additional information to resolve possible ambiguity about the source of the error. The user's argument that is in error should always be included in the call to com_err_. Calls to com_err_ should include the appropriate nonzero status code. The subroutine active_fnc_err_ should be used in a similar fashion for error reporting by active function procedures. .spb 2 Error messages about storage system entries should include the absolute pathname of the entry in error. Those messages concerning input arguments should include the argument as given by the user. .spb 2 Frivolous use of com_err_ should be avoided. It should not be used unless an error has actually occurred, as the condition command_error is signalled. .spb 2 Other output should be done by means of iox_$put_chars or ioa_. .spb 2 Red shift should not be used, since few .cbn terminals handle .cbf this mode properly. Messages with underlining should be avoided. .spb 2 Commands that produce a large amount of output (e.g., the PL/I compiler issuing diagnostics) should write all the messages on user_output and write a single error message with com_err_ indicating that there were errors. .brp .*.srv add_date "" .*.srv add_letter "" .spf 2 Commands should not write terminal-directed output to I/O switches other than user_output except when specified by control arguments. .spb 2 Commands that produce only one line of output should not emit blank lines. .ifi l2h "User Interaction Conventions" .ifi hit "K|command interfaces~user interaction conventions" When a command that interacts with the typist produces an error message that the typist does not expect, it should perform a resetread operation on user_input so that the user can modify his subsequent input. .spb 2 Commands normally should not handle the quit condition. .spb 2 Commands that interact with the typist should be prepared to handle the program_interrupt condition signalled by the program_interrupt command. This is particularly important for commands that produce a large amount of output that the user might want to abort. .spb 2 Commands that ask questions should do so by means of the subroutine command_query_ so that the command_question condition is signalled. .inl 0 .ifi l1h "Subroutine Interface Standards" .ifi l2h "Subroutine Names" .ifi hit "K|subroutine interfaces" .ifi hit "K|subroutine interfaces~subroutine names" Names of subroutines or data bases should be descriptive of the function they perform. The name should not be so long as to be inconvenient to use. .spb 2 Names of segments created by system programs that are to remain as segment names in a directory should end in underscore, to avoid naming conflicts with user-defined names. .spb 2 Names should consist only of lowercase letters, the underscore character, and the dollar sign. Subroutine names which will appear as names on segments in the system libraries should end in an underscore to avoid conflicts with user program names. .spb 2 Total length of subroutine names of the form a$b should not exceed 32 characters; the entry point portion of such a name should not end in an underscore. .spb 2 Names of subroutines or data bases belonging to a subsystem should start with the name of the subsystem or a consistent abbreviation. .brp .ifi l2h "Argument Standards" .ifi hit "K|subroutine interfaces~argument standards" Standard status codes should always be returned if the subroutine returns an error code. Either codes in the system data base error_table_ or a registered subsystem error table should be used. .spf 2 The status code should be the last argument to a subroutine. .spb 2 Arguments in a calling sequence should be grouped: Input, Input, ..., Output, Output. Arguments that are both input and output should be avoided. .spb 2 Arguments that are used for many subroutines should be declared in the same way for all such uses. .spb 2 Subroutines that return more than one argument or that have side effects should not be called as functions. .spb 2 The type of each argument should be chosen with the use and meaning of the argument in mind. .spb 2 Subroutines should not check the number or type of input arguments, but assume they have been called correctly. Subroutines should not validate the correctness of their input arguments, unless it is part of their intended operation. However, subroutines which accept structure arguments should check the input structure version number for validity. .spb 2 Character string arguments should be passed instead of a ptr to a string and its length. They should be declared unaligned and usually declared char(*) unless the length is fixed. .brp .fin .inl 0  s3.stan.compin 08/01/83 1159.6rew 08/01/83 1005.0 58041 .ifi init_mpm "AN82-00" .srv section 3 .srv draft "" .srv draft_date "" .ifi l0h "General Programming Standards" .ifi hit "K|programming standards" This section documents conventions (to be used by system programs) that are of a general nature and do not fall within the province of the other sections of this document. .ifi l1h "Command Standards" .ifi hit "K|programming standards~command standards" Commands should not call other commands. .spb 2 Commands that perform general purpose service functions used by other commands or subsystems should be modularized into a command and a subroutine interface that implement the service function. The subroutine usually should not print messages but should return a standard status code to indicate an error condition. .spb 2 Commands that accept arguments should accept a variable number of arguments and should not explicitly declare a fixed number of arguments. The subroutine cu_$arg_ptr should be used to obtain each argument and the subroutine cu_$arg_count should be used to obtain the number of arguments. .spb 2 Commands should invoke standard approved general purpose subroutines and internal interfaces developed specifically for the command or subsystem. They should not call internal interfaces of other commands or subsystems. .spb 2 Commands that are also active functions should print the results that would be returned by the active function. .spb 2 Active functions that would be meaningful commands should also be invokable as commands. .ifi l1h "Naming Standards" .ifi hit "K|programming standards~naming standards" Programs that produce output in a file should name the output file in a sensible fashion. Listing output from the processing of segment xxx.suffix should be placed in xxx.list. .spb 2 The names of all new condition names should end in an underscore to avoid naming conflicts with user-defined names. Unless an I/O switch name is an input argument, the names of all I/O switches created for use by the program should identify the program subsystem to provide meaningful output from print_attach_table. Also, the names should include a unique string to differentiate switches used by recursive invocations of the program or subsystem. .ifi l1h "Storage System Conventions" .ifi hit "K|programming standards~storage system conventions" Programs that require temporary segments should use the subroutines get_temp_segment_ and get_temp_segments_ to obtain them and should call release_temp_segment_ or release_temp_segments_ when they are finished. .spb 2 Programs should terminate any reference names that they associate with a segment. Programs generally should initiate a segment with a null reference name. .spb 2 System programs should not allocate storage in the user free storage area. Storage is allocated in the user free area unless an is given in the PL/I and . Therefore, s must be used. Such programs should use the area obtained by calling get_system_free_area_. .spb 2 Programs should have a cleanup condition handler to free allocated storage and temporary segments. .spb 2 The duplicate name convention implemented by the subroutine nd_handler_ should be honored by user ring programs. .spb 2 Programs should use the subroutine delete_ for deleting storage system entries. If a nonzero error code is returned, the subroutine dl_handler_ should be used to resolve the error. Programs should use the subroutine term_ for terminating segments that may have nonnull reference names associated with them or that may have links snapped to them. .ifi l2h "Output Conventions" .ifi hit "K|programming standards~output conventions" Programs other than commands generally should not produce output or print error messages except for those subroutines whose explicit purpose is to perform these functions. The exact nature of the output should be documented in the interface description. .spb 2 If a subroutine prints an error message, it should use the com_err_ subroutine (if printing a fatal error on the caller's behalf where the caller has too little information to print a meaningful message), or the sub_err_ subroutine (if printing a nonfatal error which can be restarted selectively under control of the caller or the user). The name of the command invoking the subroutine should be given in such error messages, implying that this name must be an input argument to the subroutine. .ifi l2h "Use of On Units for the Cleanup Condition" .ifi hit "K|programming standards~on unit for cleanup condition" The on unit for the cleanup condition must not be a goto statement, and the on unit (or any procedure or block invoked from the on unit) must not contain a nonlocal goto statement, as this will interfere with the nonlocal transfer that originally signalled the condition. .spb 2 Cleanup tasks include freeing allocated storage and releasing temporary segments. .spb 2 Cleanup handlers should never print anything. .ifi l2h "Coding Conventions" .ifi hit "K|programming standards~coding conventions" Programs should only be written in the PL/I language, except with explicit permission. Exceptions usually are made when performance is an issue. .spf 2 All variables should be declared. .spb 2 All parameter lists for external entries should be fully declared, except for those entries accepting a variable number of arguments. These should be declared as options (variable). .spb 2 Declarations should be grouped in a readable fashion. .spb 2 All pad fields in data structures should be explicitly declared, i.e., there should be no gaps. .spb 2 All pad fields that are documented to be zero should be set to zero explicitly. This operation allows for future expansion of a data item. A name such as mbz1 should be used to declare pad fields to make it clear that the caller must zero such fields. .spb 2 Whenever possible, avoid including system parameters as constants in a program. For example, if the maximum number of words for a segment is required, the external variable sys_info$max_seg_size should be referenced. .spb 2 Programs should not use external state variables to pass data values between external programs. This obscures the operation of such programs. Instead, the data should be passed as arguments. .brp .fin .inl 0  s1.stan.compin 08/01/83 1159.7rew 08/01/83 1005.0 24615 .ifi init_mpm "AN82-00" .srv section 1 .srv draft "" .srv draft_date "" .ifi l0h "Introduction" .ifi l1h "How to Use This Document" .ifi hit "K|introduction" .ifi hit "K|introduction~usage of this manual" This document should be read in its entirety in order to understand its contents. It should then be used as a reference document whenever relevant to the work being done. .ifi l1h "Volatility of Contents" The information in this document will be updated. Because the standards change as the system evolves, much of the system will not completely conform to the standards. As part of the development effort, software should be upgraded to meet the requirements of the new or changed standards whenever this is possible. .ifi l1h "General Issues" .ifi hit "K|introduction~general issues" To expound upon the general issues that comprise the design goals of the Multics Operating System is beyond the scope of this document. However, it is useful to remind the reader of some of the most important issues. Multics interfaces are designed with the average user in mind. As a result the needs of the very inexperienced or the very sophisticated user may be slighted. Consistency among all parts of the system is stressed in order to make this very complicated system possible to use and to allow different subsystems to be combined in ways not originally planned. .spb 2 The issue of general style has always been considered important. For example, minimal use of jargon and the use of correct English is considered to be very important for both the documentation and the system interfaces themselves. Thus, diagnostic messages are sentences that begin with an upper case letter and end with a period. .brp .inl 0 .ifi l1h "Registered Names" .ifi hit "K|introduction~registered names" One of the most important parts of the user interface that must be kept consistent is that of the several classes of names used by commands and subroutines. This manual contains a number of appendices that register these names. Only those names registered here may be used; if new names are required they must be registered. .spb 2 .inl 5 .fif Appendix A lists control arguments. Appendix B lists suffixes. Appendix C lists I/O switch names. Appendix D lists condition names. .fin .inl 0 .ifi l1h "Topics" .ifi hit "K|introduction~main topics" Main topics included in this manual are interface standards (including both commands and subroutines), programming standards, modularity, environment independence, program format, include file format, PL/I language conventions, storage management, use of the storage system, documentation standards, info segments, and rules for translator writers. .brp .fin .inl 0  appb.stana.compin 08/01/83 1159.7r w 08/01/83 1005.0 46125 .ifi init_mpm "AN82-00" .srv section "B" .inl 0 .ifi l0h "Registered Suffixes" .ifi hit "K|registered suffixes" .ifi hit "K|registered suffixes~list of" This section lists all registered entryname suffixes and their general meaning. Programs should follow the conventions implied by these suffixes. .ifi l1h "List of Suffixes" .inl 20 .spf .unl 15 absin absentee input segment .spf .unl 15 absout absentee output segment .spf .unl 15 alm ALM source program statements .spf .unl 15 apl APL saved workspace .spf .unl 15 archive archive segment .spf .unl 15 basic BASIC source program statements .spf .unl 15 bcpl BCPL source program statements .spf .unl 15 bind bindfile for the bind command .spf .unl 15 breaks break segment for the debug command .spf .unl 15 cds cds source program statements .spf .unl 15 chars auxiliary output file produced by runoff and compose .spf .unl 15 ckrout output segment form the check_mst command .spf .unl 15 cmdb data model source segment for the create_mrds_dv command .spf .unl 15 cmdsm data submodel source segment for the create_mrds_dsm command .spf .unl 15 cobol COBOL source program statements .spf .unl 15 code enciphered segment produced by the encode command .spf .unl 15 compin compose source statements .spf .unl 15 compout primary output file produced by compose .spf .unl 15 control control file for miscellaneous commands .spf .unl 15 crl control segment for the cross_reference command .spf .unl 15 crlout output file of the cross_reference command .spf .unl 15 dict dictionary segment used by dictionary commands .spf .brp .*.srv add_date "?" .*.srv add_letter "A" .unl 15 dir_info directory information segment output by the save_dir_info command .spf .unl 15 dsm output file produced by the create_mrds_dsm command .spf .unl 15 ec segment containing exec_com lines .spf .unl 15 fortran FORTRAN source program statements .spf .unl 15 gcos file in GCOS Standard System Format .spf .unl 15 gdt graphics device table source segment input to the compile_gdt command .spf .unl 15 ge input segment to the graphics_editor command .spf .cbn .unl 15 graphics suffix added to the segment created when invoking the -output_file control argument to the setup_graphics command .cbf .spf .unl 15 header header file for MST generator .spf .unl 15 incl.alm ALM include files .spf .unl 15 incl.bcpl BCPL include files .spf .unl 15 incl.cobol COBOL include files .spf .unl 15 incl.fortran FORTRAN include files .spf .unl 15 incl.lisp LISP include files .spf .unl 15 incl.pl1 PL/I include files .spf .unl 15 info segments formatted according to help command conventions .spf .unl 15 ld source for the library descriptor command .spf .unl 15 lisp LISP source program statements .spf .unl 15 list listing file produced by a compiler assembler or binder .spf .unl 15 lister data base used by lister commands .spf .unl 15 listform control segment defining document format used by process_list command .spf .unl 15 listin segment used by create_list command to input or update a lister file .spf .cbn .unl 15 mail segment containing message suitable for dprinting created by the read_mail and send_mail commands .cbf .spf .unl 15 map map segment produced by binder or library_ map .spf .unl 15 mbx ring 1 mailbox .spf .unl 15 memo database used by memo command .spf .unl 15 mexp mexp source program statements .spf .unl 15 motd database for the print_motd command .spf .unl 15 ms ring 1 message segment .spf .unl 15 order control segment for the reorder_archive command .spb .unl 15 .cbn pgs specifies permanent graphic segments cpntaining structured graphic objects used by the graphic_manipulator_ subroutine .cbf .spf .unl 15 pfd output file created by the profile command .spf .unl 15 pfl listing file used by the profile command .spf .unl 15 pl1 PL/I source program statements .spf .unl 15 print output of the library_print command .spf .unl 15 probe break segment for the probe command .spf .unl 15 profile user profile used by abbrev and check_info_segs .spf .unl 15 qedx qedx macro .spf .unl 15 rd reduction compiler source statements .spf .unl 15 runoff runoff source statements .spf .unl 15 runout primary output file produced by runoff .spf .unl 15 search search directories for MST generator .spf .unl 15 symbols symbol dictionary used by the Speedtype commands .spf .cbn .unl 15 ta table of contents segment created and used by the tape_archive command .cbf .spf .unl 15 teco teco macro .spf .unl 15 volumes output segment of the manage_volumes_pool command .spf .unl 15 wl wordlist segment used by the wordlist commands .brp .fin .inl 0 .*.srv add_date "" .*.srv add_letter "" ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved