08/07/86 ocu_ The ocu_ subroutine allows generation of standard format object segments and multi-segment files. The information is emitted via calls to ocu_ entrypoints and stored in internal tables until the invocation is closed, at which time the object is created and the sections assembled and linked together properly. Entry points in ocu_: (List is generated by the help command) :Entry: backpatch: 02/10/86 ocu_$backpatch Function: It is often necessary in the creation of an object segment to generate a reference to something which has not been emitted yet. This entrypoint allows changes to be made in a word which has already been emitted. Since many sections of the object segment are being synthesized by ocu_ from other information, it is not practical to patch them. (eg. the definition section contains type_pairs, expression_words, init_info, and ACC_strings generated as byproducts of link generation. The offsets of these items are not known until the object is closed.) This entry is primarily for patching sections which were emitted as blocks of words. (ie. text, static, and symbol sections.) Syntax: dcl ocu_$backpatch entry (ptr, char (*), fixed bin (18) unsigned, char (*), fixed bin (35); call ocu_$backpatch (ocu_datap, section, offset, side, new_value); Arguments: ocu_datap is a pointer returned by ocu_$open. This identifies all the data structures needed to create the object segment. (Input) section is a character identifying the section to be patched. (Input) Valid values for this argument are: "text" - to patch the text section. "static" - to patch the static section. "symbol" - to patch the symbol section. offset is the word offset within the given section of the halfword to be patched. (Input) side is a string indicating what portion of the specified word is to be patched. (Input) Valid values depend on the section being patched and correspond to the valid types of relocation allowed for that section. - Text section "left 15 unsigned" "left 15 signed" "left 18 unsigned" "left 18 signed" "right 18 unsigned" "right 18 unsigned" - Static section "left 18 unsigned" "left 18 signed" "right 18 unsigned" "right 18 signed" - Symbol section "left 18 unsigned" "left 18 signed" "right 18 unsigned" "right 18 signed" new_value is the new value to be patched into the specified portion of the word. (Input) :Entry: close: 02/10/86 ocu_$close Function: takes the information provided by previous calls to ocu_ and assembles the final object segment. The relocation information, object_map, linkage header, definition string map, hash table, and header are synthesized at this point. Syntax: dcl ocu_$close entry (ptr, fixed bin (35)); call ocu_$close (ocu_datap, code); Arguments: ocu_datap is a pointer returned by ocu_$open. This identifies all the data structures needed to create the object segment. (Input) code is a standard status code. (Output) :Entry: create_msf: 08/07/86 ocu_$create_msf Function: Creates component 0 of an object MSF. Given an array of pointers to all of the components of a MSF (excepting component 0), generates component 0, copying the external definitions, and building the first reference trap. Syntax: dcl ocu_$create_msf entry (ptr, fixed bin (15) unsigned, ptr, fixed bin (35)); call ocu_$create_msf (component_listp, component_count, gen_infop, code); Arguments: component_listp is a pointer to an array of pointers of dimension (1:component_count-1). (Input) Each pointer points to one component of the MSF. Each of the pointers points to a completed object segment. It is assumed that each of the components already has it's linkage section built as a MSF (ie. containing appropriate partially-snapped links) and that the msf_map is present in the definition section. component_count is the number of components in the final MSF not counting component 0. (Input) gen_infop is a pointer to the gen_info structure used to set the generator_info in the symbol header of component 0. (Input) The gen_info structure is declared in the include file ocu_dcls.incl.pl1. dcl 01 gen_info aligned based, 02 gen_created fixed bin (71), 02 generator char (8), 02 gen_number fixed bin, 02 gen_version char (512) varying; gen_created is the clock time that the generator was created. generator is the name of the generator (eg. PL/I, binder, etc.). gen_number is the version number of the generator. This value must the version number if the gen_version string. gen_version is a version string giving the name, version, and date of the generator (eg. Multics PL/I Compiler, Release 28e, of February 14, 1985) code is a standard status code. (Output) :Entry: emit_definition: 02/10/86 ocu_$emit_definition Function: Emits a single non-class-3 definition, and threads it into the definition list. Definitions are threaded in the order of the calls to ocu_$emit_definition and ocu_$emit_segname. Successive calls to emit_segname generate multiple segnames in a single block. Calls to emit_segname with intervening calls to emit_definition create a new block. Syntax: dcl ocu_$emit_definition entry (ptr, char (*) varying, fixed bin (3), fixed bin (18) unsigned, bit (*)) returns (fixed bin (18) unsigned); def_relp = ocu_$emit_definition (ocu_datap, name, section, offset, flags); Arguments: ocu_datap is a pointer returned by ocu_$open. This identifies all the data structures needed to create the object segment. (Input) name is the name of the definition. (Input) section is the section that the definition refers to. (Input) Constants for the sections can be found in definition_dcls.incl.pl1. Valid sections for this subroutine are: SECTION_TEXT = 0 SECTION_LINK = 1 SECTION_SYMBOL = 2 SECTION_STATIC = 4 offset is the offset of the target of the definition within the given section. (Input) flags is a bit string representing the flags to be set in the definition. (Input) Constants definition the values can be found in ocu_dcls.incl.pl1. DEFINITION_FLAGS_IGNORE = "1000"b DEFINITION_FLAGS_ENTRY = "0100"b DEFINITION_FLAGS_RETAIN = "0010"b DEFINITION_FLAGS_INDIRECT = "0001"b def_relp is an offset to the generated definition relative to the base of the definition section. (Output) :Entry: emit_firstref_trap: 02/10/86 ocu_$emit_firstref_trap Function: Adds a firstref trap to the first reference trap block in the linkage section. The links reference by the call_relp and info_relp must have already been emitted. Errors encountered are reported using the sub_err_ subroutine. Syntax: dcl ocu_$emit_firstref_trap entry (ptr, fixed bin (18) unsigned, fixed bin (18) unsigned); call ocu_$emit_firstref_trap (ocu_datap, call_relp, info_relp); Arguments: ocu_datap is a pointer returned by ocu_$open. This identifies all the data structures needed to create the object segment. (Input) call_relp is the offset relative to the base of the linkage section of a link to be used to call the trap procedure. (Input) info_relp is the offset relative to the base of the linkage section of a link to be passed to the trap procedure. If this value is 0, no parameter will be passed to the trap procedure. (Input) :Entry: emit_link: 02/10/86 ocu_$emit_link Function: Creates a single external link. The expression word, type_pair, segname and offsetname strings, and any trap_words or external initialization information in the definition section are also generated as required. Errors encountered are reported using the sub_err_ subroutine. Syntax: dcl ocu_$emit_link entry (ptr, fixed bin (3), fixed bin (3), char (*) var, char (*) var, fixed bin, bit (6), ptr) returns (fixed bin (18) unsigned); link_relp = ocu_$emit_link (ocu_datap, type, class, segname, offsetname, expression, modifier, init_infop); Arguments: ocu_datap is a pointer returned by ocu_$open. This identifies all the data structures needed to create the object segment. (Input) type is the type of the link. Constants for the valid link types can be found in definition_dcls.incl.pl1. Valid valued are: LINK_SELF_BASE = 1 LINK_REFNAME_BASE = 3 LINK_REFNAME_OFFSETNAME = 4 LINK_SELF_OFFSETNAME = 5 class is the class of the link for type 1 (link self base) and type 5 (link self offsetname). This indicates what section of the object segment the expression value is relative to. It is used only if the type is 1 or 5. Constants usable for this value are declared in definition_dcls.incl.pl1. Valid values are: CLASS_TEXT = 0 CLASS_LINKAGE = 1 CLASS_SYMBOL = 2 CLASS_STATIC = 4 CLASS_SYSTEM = 5 CLASS_HEAP = 6 segname is the segname of the link target. This field is only used if the type of the link is type 3 (link-refname-base) or type 4 (link-refname-offsetname). This is the refname that will be used to search for the segment when the link is snapped. (Input) offsetname is the name of the definition to be searched for when the link is snapped. This field is only used if the link type is type 4 (link-refname-offsetname) or type 5 (link-self-offsetname). (Input) expression is a word offset to be added to the offset derived from the section and offsetname values. (Input) modifier is the modifier of the link. This is the modifier that will be present in the pointer representing the snapped link. Generally a null modifier (""b) is used. (Input) init_infop is a pointer to the initialization info, or to a trap_pair. (Input) If the link is a type 5, class 5 link (a *system or external link) or a type 5, class 6 link (a *heap link), this points to an initialization info block which will be placed into the definition section. This can point to any type of standard initialization info (INIT_NO_INIT, INIT_COPY_INFO, INIT_DEFINE_AREA, INIT_LIST_TEMPLATE, or INIT_DEFERRED if the object segment being created is an MSF component.) If the link is not a *system or *heap link, a non-null value will be assumed to point to a trap-pair representing a trap-before-link. Since trap-before-links are generally obsolete, this should only be non-null when supplying initialization_info for *system or *heap links. link_relp is the offset of this link relative to the base of the linkage section. Note that the link offset returned is the location of the link assuming there is no linkage-resident static section. When the object is closed (via a call to ocu_$close) all link references will be relocated to account for the presence of a static section. If you plan to use this returned link offset for purposes other than to store in one of the other object sections, you will have to adjust for the static section manually. :Entry: emit_partial_link: 02/10/86 ocu_$emit_partial_link Function: Emits an MSF partially snapped link. A partially snapped link uses no information in the definition section, and is snapped before entry by a first reference trap. This entrypoint should ONLY be called when generating a MSF component. Errors are reported using the sub_err_ subroutine. Syntax: dcl ocu_$emit_partial_link entry (ptr, fixed bin (15) unsigned, fixed bin (3), fixed bin (18) unsigned, bit (6)) returns (fixed bin (18) unsigned); link_relp = ocu_$emit_link (ocu_datap, component, section, offset, modifier); Arguments: ocu_datap is a pointer returned by ocu_$open. This identifies all the data structures needed to create the object segment. (Input) component is the component number of the target component within the MSF. Generally this will be in the range 1 to the maximum component number. (Input) section is the target section of the link within the target MSF component. (Input) Constants for these values can be found in definition_dcls.incl.pl1. Valid values are: SECTION_TEXT = 0 SECTION_LINKAGE = 1 SECTION_SYMBOL = 2 SECTION_STATIC = 4 offset is the offset of the pointer. This value is relative to the base of the section specified by the section parameter. (Input) modifier is the modifier of the link. This will also be the modifier of the pointer generated by snapping the link. The null modifier (""b) is generally used. (Input) link_relp is the offset of the generated link relative to the base of the linkage section. Note that this value is calculated as if there were no static section resident in the linkage section. When the object is closed (via a call to ocu_$close) all linkage references are relocated to adjust for the presence of a static section. If the caller wishes to use this value for other purposes that to include in another call to ocu_, it will have to be adjusted for the presence of the static section manually. (Output) :Entry: emit_segname: 02/10/86 ocu_$emit_segname Function: Emits a single class-3 (segname) definition, and threads it into the definition list. The definitions are chained in the order of calls to ocu_$emit_definition and ocu_$emit_segname. Sequential calls to emit_segname generate multiple segnames in a single block. A call to emit_segname after calls to emit_definition starts a new block. It is invalid to call emit_definition without calling emit_segname at least once. Syntax: dcl ocu_$emit_segname entry (ptr, char (*) varying, bit (*)) returns (fixed bin (18) unsigned); def_relp = ocu_$emit_segname (ocu_datap, name, flags); Arguments: ocu_datap is a pointer returned by ocu_$open. This identifies all the data structures needed to create the object segment. (Input) name is the name of this segname definition. (Input) flags is a bit string representing the flags to be set in the definition. (Input) Constants definition the values can be found in ocu_dcls.incl.pl1. DEFINITION_FLAGS_IGNORE = "1000"b DEFINITION_FLAGS_ENTRY = "0100"b DEFINITION_FLAGS_RETAIN = "0010"b DEFINITION_FLAGS_INDIRECT = "0001"b def_relp is an offset to the generated definition relative to the base of the definition section. (Output) :Entry: emit_static: 02/10/86 ocu_$emit_static Function: Emits a block of words which are appended to the static section. Since there is no relocation info for the static section (and it is forced to be absolute if it is contained in the linkage section), no relocation information is required. Note that even if the static section is to be contained in the linkage section, references to the static section should be made with static relocation info and not attempt to adjust the offsets for the presence of the linkage header. when the new object is closed, all static references will be mapped into the appropriate linkage references. Error encountered are reported using the sub_err_ subroutine. Syntax: dcl ocu_$emit_static entry (ptr, ptr, fixed bin (18) unsigned, returns (fixed bin (18) unsigned); static_relp = ocu_$emit_static (ocu_datap, staticp, word_count); Arguments: ocu_datap is a pointer returned by ocu_$open. This identifies all the data structures needed to create the object segment. (Input) staticp is a pointer to an array or words of dimension (word_count) to be appended to the static section. (Input) word_count is the number of words to be appended to the static section. (Input) static_relp is the offset of the block or words relative to the base of the static section :Entry: emit_symbol: 02/10/86 ocu_$emit_symbol Function: Emits a block of symbol words and appends them to the symbol section. Errors encountered are reported using the sub_err_ subroutine. Syntax: dcl ocu_$emit_symbol entry (ptr, ptr, ptr, fixed bin (18) unsigned) returns (fixed bin (18) unsigned); symbol_relp = ocu_$emit_symbol (ocu_datap, symbolp, relocationp, word_count); Arguments: ocu_datap is a pointer returned by ocu_$open. This identifies all the data structures needed to create the object segment. (Input) symbolp is a pointer to an array symbol section words of dimension (word_count) to be appended to the symbol section. (Input) relocationp is a pointer to a character string of length (2*word_count) representing the relocation information for the accompanying block of words. (Input) The relocation characters are taken from the set of standard characters used by language translators (see the Multics Programmers Reference Manual). The relocation string is required even if the object to be generated is not relocatables since the relocation information is used to locate static and linkage references which will have to be relocated if the static section is linkage resident. word_count is the number of symbol words to be emitted. (Input) symbol_relp is the offset of this block of words relative to the base of the symbol section. (Output) :Entry: emit_text: 02/10/86 ocu_$emit_text Function: emits a block of text words, appending them to the end of the text section and returning the offset within the text section. Errors encountered are reported using the sub_err_ subroutine. Syntax: dcl ocu_$emit_text entry (ptr, ptr, ptr, fixed bin (18) unsigned) returns (fixed bin (18) unsigned); text_relp = ocu_$emit_text (ocu_datap, textp, relocationp, word_count); Arguments: ocu_datap is a pointer returned by ocu_$open. This identifies all the data structures needed to create the object segment. (Input) textp is a pointer to an array of text words of dimension (word_count) to be appended to the text section. (Input) relocationp is a pointer to a character string of length (2*word_count) representing the relocation information associated with the text array. (Input) The characters used are the standard character relocation codes used by the translators. (see the Multics Programmers Reference Manual). This string is required regardless of whether the output object is to be relocatable since it is used to relocate linkage and static references if the static section is not separate. word_count is the number of words of text to be emitted. (Input) text_relp is an offset to this block of words relative to the base of the section. (Output) :Entry: emit_msf_map: 08/07/86 ocu_$emit_msf_map Function: Emits the msf_map in the definition section of the new object. This entrypoint should ONLY be called if the object segment being generated is an MSF component. Errors encountered are reported using calls to the sub_err_ subroutine. Syntax: dcl ocu_$emit_msf_map (ptr, fixed bin (15) unsigned, fixed bin (15) unsigned); call ocu_$emit_msf_map (ocu_datap, component_count, my_component); Arguments: ocu_datap is a pointer returned by ocu_$open. This identifies all the data structures needed to create the object segment. (Input) component_count is the number of components in the MSF, including component 0. (Input) my_component is the number of the component being generated in the range 0 to component_count - 1. (Input) :Entry: open: 02/10/86 ocu_$open Function: Allocates and initializes the data structures used to create the object segment and returns a pointer used to locate the structures. Syntax: dcl ocu_$open entry (char (*), char (*), bit (*), ptr, fixed bin (35)); call ocu_$open (dir_name, entry_name, flags, ocu_datap, code); Arguments: dir_name is the name of the directory in which the final object will be created. (Input) entry_name is the entry name of the output object segment. (Input) flags is a bit string indicating various options to be used in the creation of the object segment. (Input) The following values may be used to derive the desired flag value. (found in ocu_dcls.incl.pl1) OPEN_FLAGS_BOUND = "100000"b The object being created will have the format of a bound object (ie. one containing multiple translator produced objects) and is formatted according to the standards for bound objects. This format is not enforced by ocu_ and it is the responsibility of the caller to set up the object properly. OPEN_FLAGS_RELOCATABLE = "010000"b The object being created has relocation information and can be used as input to the binder or linkage editor. This flag is used by ocu_ to determine whether or not to add the relocation information to the linkage section of the object segment when the object is closed. OPEN_FLAGS_PROCEDURE = "001000"b The object contains executable code. OPEN_FLAGS_SEPARATE_STATIC = "000100"b The object segment is to contain a static section rather than have the static section included in the linkage section. This flag is examined by ocu_ when closing the object segment to determine relocation of static and linkage section references and to generate the sections properly. OPEN_FLAGS_PERPROCESS_STATIC = "000010"b The static section of this object segment is not to be duplicated when called from within a run unit. OPEN_FLAGS_NO_HASHTABLE = "000001"b Do not create a definition section hash table for this object segment. This is primarily used when creating either MSF components (which are never searched) or objects with very few entrypoints. ocu_datap is a pointer to the ocu data structures used by the other calls. (Output) code is a standard status code. (Output) :Entry: release: 02/10/86 ocu_$release Function: Releases table storage used by ocu_ when an invocation is aborted. Syntax: dcl ocu_$release entry (ptr); call ocu_$release (ocu_datap); Arguments: ocu_datap is a pointer returned by ocu_$open. This identifies all the data structures to be released. (Input) ----------------------------------------------------------- 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