1 08/07/86 ocu_
2
3
4 The ocu_ subroutine allows generation of standard format object
5 segments and multi-segment files. The information is emitted via
6 calls to ocu_ entrypoints and stored in internal tables until the
7 invocation is closed, at which time the object is created and the
8 sections assembled and linked together properly.
9
10
11 Entry points in ocu_:
12 List is generated by the help command
13
14
15 :Entry: backpatch: 02/10/86 ocu_$backpatch
16
17
18 Function:
19 It is often necessary in the creation of an object segment
20 to generate a reference to something which has not been
21 emitted yet. This entrypoint allows changes to be made in a
22 word which has already been emitted. Since many sections of
23 the object segment are being synthesized by ocu_ from other
24 information, it is not practical to patch them. eg. the
25 definition section contains type_pairs expression_words
26 init_info and ACC_strings generated as byproducts of link
27 generation. The offsets of these items are not known until
28 the object is closed. This entry is primarily for patching
29 sections which were emitted as blocks of words. ie. text
30 static and symbol sections.
31
32
33 Syntax:
34 dcl ocu_$backpatch entry ptr char *
35 fixed bin 18 unsigned char * fixed bin 35;
36 call ocu_$backpatch ocu_datap section offset side
37 new_value;
38
39
40 Arguments:
41
42 ocu_datap
43 is a pointer returned by ocu_$open. This identifies all the
44 data structures needed to create the object segment. Input
45
46 section
47 is a character identifying the section to be patched.
48 Input
49 Valid values for this argument are:
50 "text" - to patch the text section.
51 "static" - to patch the static section.
52 "symbol" - to patch the symbol section.
53
54
55 offset
56 is the word offset within the given section of the halfword
57 to be patched. Input
58
59 side
60 is a string indicating what portion of the specified word is
61 to be patched. Input
62 Valid values depend on the section being patched and
63 correspond to the valid types of relocation allowed for that
64 section.
65
66 - Text section
67 "left 15 unsigned"
68 "left 15 signed"
69 "left 18 unsigned"
70 "left 18 signed"
71 "right 18 unsigned"
72 "right 18 unsigned"
73
74
75 - Static section
76 "left 18 unsigned"
77 "left 18 signed"
78 "right 18 unsigned"
79 "right 18 signed"
80 - Symbol section
81 "left 18 unsigned"
82 "left 18 signed"
83 "right 18 unsigned"
84 "right 18 signed"
85
86
87 new_value
88 is the new value to be patched into the specified portion of
89 the word. Input
90
91
92 :Entry: close: 02/10/86 ocu_$close
93
94
95 Function:
96 takes the information provided by previous calls to ocu_ and
97 assembles the final object segment. The relocation
98 information object_map linkage header definition string
99 map hash table and header are synthesized at this point.
100
101
102 Syntax:
103 dcl ocu_$close entry ptr fixed bin 35;
104 call ocu_$close ocu_datap code;
105
106
107 Arguments:
108
109 ocu_datap
110 is a pointer returned by ocu_$open. This identifies all the
111 data structures needed to create the object segment. Input
112
113 code
114 is a standard status code. Output
115
116
117 :Entry: create_msf: 08/07/86 ocu_$create_msf
118
119
120 Function:
121 Creates component 0 of an object MSF. Given an array of
122 pointers to all of the components of a MSF excepting
123 component 0 generates component 0 copying the external
124 definitions and building the first reference trap.
125
126
127 Syntax:
128 dcl ocu_$create_msf entry ptr fixed bin 15 unsigned
129 ptr fixed bin 35;
130 call ocu_$create_msf component_listp component_count
131 gen_infop code;
132
133
134 Arguments:
135
136 component_listp
137 is a pointer to an array of pointers of dimension
138 1:component_count-1. Input
139 Each pointer points to one component of the MSF. Each of
140 the pointers points to a completed object segment. It is
141 assumed that each of the components already has it's linkage
142 section built as a MSF ie. containing appropriate
143 partially-snapped links and that the msf_map is present in
144 the definition section.
145
146 component_count
147 is the number of components in the final MSF not counting
148 component 0. Input
149
150
151 gen_infop
152 is a pointer to the gen_info structure used to set the
153 generator_info in the symbol header of component 0. Input
154 The gen_info structure is declared in the include file
155 ocu_dcls.incl.pl1.
156
157 dcl 01 gen_info aligned based
158 02 gen_created fixed bin 71
159 02 generator char 8
160 02 gen_number fixed bin
161 02 gen_version char 512 varying;
162
163
164 gen_created
165 is the clock time that the generator was created.
166
167 generator
168 is the name of the generator eg. PL/I binder etc..
169
170 gen_number
171 is the version number of the generator. This value
172 must the version number if the gen_version string.
173
174
175 gen_version
176 is a version string giving the name version and date
177 of the generator eg. Multics PL/I Compiler Release
178 28e of February 14 1985
179
180 code
181 is a standard status code. Output
182
183
184 :Entry: emit_definition: 02/10/86 ocu_$emit_definition
185
186
187 Function:
188 Emits a single non-class-3 definition and threads it into
189 the definition list. Definitions are threaded in the order
190 of the calls to ocu_$emit_definition and ocu_$emit_segname.
191 Successive calls to emit_segname generate multiple segnames
192 in a single block. Calls to emit_segname with intervening
193 calls to emit_definition create a new block.
194
195
196 Syntax:
197 dcl ocu_$emit_definition entry ptr char * varying
198 fixed bin 3 fixed bin 18 unsigned
199 bit * returns fixed bin 18 unsigned;
200 def_relp = ocu_$emit_definition ocu_datap name section
201 offset flags;
202
203
204 Arguments:
205
206 ocu_datap
207 is a pointer returned by ocu_$open. This identifies all the
208 data structures needed to create the object segment. Input
209
210 name
211 is the name of the definition. Input
212
213
214 section
215 is the section that the definition refers to. Input
216 Constants for the sections can be found in
217 definition_dcls.incl.pl1. Valid sections for this
218 subroutine are:
219
220 SECTION_TEXT = 0
221 SECTION_LINK = 1
222 SECTION_SYMBOL = 2
223 SECTION_STATIC = 4
224
225 offset
226 is the offset of the target of the definition within the
227 given section. Input
228
229
230 flags
231 is a bit string representing the flags to be set in the
232 definition. Input
233 Constants definition the values can be found in
234 ocu_dcls.incl.pl1.
235
236 DEFINITION_FLAGS_IGNORE = "1000"b
237 DEFINITION_FLAGS_ENTRY = "0100"b
238 DEFINITION_FLAGS_RETAIN = "0010"b
239 DEFINITION_FLAGS_INDIRECT = "0001"b
240
241 def_relp
242 is an offset to the generated definition relative to the
243 base of the definition section. Output
244
245
246 :Entry: emit_firstref_trap: 02/10/86 ocu_$emit_firstref_trap
247
248
249 Function:
250 Adds a firstref trap to the first reference trap block in
251 the linkage section. The links reference by the call_relp
252 and info_relp must have already been emitted. Errors
253 encountered are reported using the sub_err_ subroutine.
254
255
256 Syntax:
257 dcl ocu_$emit_firstref_trap entry ptr fixed bin 18 unsigned
258 fixed bin 18 unsigned;
259 call ocu_$emit_firstref_trap ocu_datap call_relp info_relp;
260
261
262 Arguments:
263
264 ocu_datap
265 is a pointer returned by ocu_$open. This identifies all the
266 data structures needed to create the object segment. Input
267
268 call_relp
269 is the offset relative to the base of the linkage section of
270 a link to be used to call the trap procedure. Input
271
272 info_relp
273 is the offset relative to the base of the linkage section of
274 a link to be passed to the trap procedure. If this value is
275 0 no parameter will be passed to the trap procedure.
276 Input
277
278
279 :Entry: emit_link: 02/10/86 ocu_$emit_link
280
281
282 Function:
283 Creates a single external link. The expression word
284 type_pair segname and offsetname strings and any
285 trap_words or external initialization information in the
286 definition section are also generated as required. Errors
287 encountered are reported using the sub_err_ subroutine.
288
289
290 Syntax:
291 dcl ocu_$emit_link entry ptr fixed bin 3 fixed bin 3
292 char * var char * var fixed bin bit 6 ptr
293 returns fixed bin 18 unsigned;
294 link_relp = ocu_$emit_link ocu_datap type class segname
295 offsetname expression modifier init_infop;
296
297
298 Arguments:
299
300 ocu_datap
301 is a pointer returned by ocu_$open. This identifies all the
302 data structures needed to create the object segment. Input
303
304 type
305 is the type of the link. Constants for the valid link types
306 can be found in definition_dcls.incl.pl1. Valid valued are:
307
308 LINK_SELF_BASE = 1
309 LINK_REFNAME_BASE = 3
310 LINK_REFNAME_OFFSETNAME = 4
311 LINK_SELF_OFFSETNAME = 5
312
313
314 class
315 is the class of the link for type 1 link self base and
316 type 5 link self offsetname. This indicates what section
317 of the object segment the expression value is relative to.
318 It is used only if the type is 1 or 5. Constants usable for
319 this value are declared in definition_dcls.incl.pl1. Valid
320 values are:
321
322 CLASS_TEXT = 0
323 CLASS_LINKAGE = 1
324 CLASS_SYMBOL = 2
325 CLASS_STATIC = 4
326 CLASS_SYSTEM = 5
327 CLASS_HEAP = 6
328
329
330 segname
331 is the segname of the link target. This field is only used
332 if the type of the link is type 3 link-refname-base or
333 type 4 link-refname-offsetname. This is the refname that
334 will be used to search for the segment when the link is
335 snapped. Input
336
337 offsetname
338 is the name of the definition to be searched for when the
339 link is snapped. This field is only used if the link type
340 is type 4 link-refname-offsetname or type 5
341 link-self-offsetname. Input
342
343
344 expression
345 is a word offset to be added to the offset derived from the
346 section and offsetname values. Input
347
348 modifier
349 is the modifier of the link. This is the modifier that will
350 be present in the pointer representing the snapped link.
351 Generally a null modifier ""b is used. Input
352
353
354 init_infop
355 is a pointer to the initialization info or to a trap_pair.
356 Input
357 If the link is a type 5 class 5 link a *system or external
358 link or a type 5 class 6 link a *heap link this points
359 to an initialization info block which will be placed into
360 the definition section. This can point to any type of
361 standard initialization info INIT_NO_INIT INIT_COPY_INFO
362 INIT_DEFINE_AREA INIT_LIST_TEMPLATE or INIT_DEFERRED if
363 the object segment being created is an MSF component. If
364 the link is not a *system or *heap link a non-null value
365 will be assumed to point to a trap-pair representing a
366 trap-before-link. Since trap-before-links are generally
367 obsolete this should only be non-null when supplying
368 initialization_info for *system or *heap links.
369
370
371 link_relp
372 is the offset of this link relative to the base of the
373 linkage section. Note that the link offset returned is the
374 location of the link assuming there is no linkage-resident
375 static section. When the object is closed via a call to
376 ocu_$close all link references will be relocated to account
377 for the presence of a static section. If you plan to use
378 this returned link offset for purposes other than to store
379 in one of the other object sections you will have to adjust
380 for the static section manually.
381
382
383 :Entry: emit_partial_link: 02/10/86 ocu_$emit_partial_link
384
385
386 Function:
387 Emits an MSF partially snapped link. A partially snapped
388 link uses no information in the definition section and is
389 snapped before entry by a first reference trap. This
390 entrypoint should ONLY be called when generating a MSF
391 component. Errors are reported using the sub_err_
392 subroutine.
393
394
395 Syntax:
396 dcl ocu_$emit_partial_link entry ptr fixed bin 15 unsigned
397 fixed bin 3 fixed bin 18 unsigned bit 6
398 returns fixed bin 18 unsigned;
399 link_relp = ocu_$emit_link ocu_datap component section
400 offset modifier;
401
402
403 Arguments:
404
405 ocu_datap
406 is a pointer returned by ocu_$open. This identifies all the
407 data structures needed to create the object segment. Input
408
409 component
410 is the component number of the target component within the
411 MSF. Generally this will be in the range 1 to the maximum
412 component number. Input
413
414
415 section
416 is the target section of the link within the target MSF
417 component. Input Constants for these values can be found
418 in definition_dcls.incl.pl1. Valid values are:
419
420 SECTION_TEXT = 0
421 SECTION_LINKAGE = 1
422 SECTION_SYMBOL = 2
423 SECTION_STATIC = 4
424
425 offset
426 is the offset of the pointer. This value is relative to the
427 base of the section specified by the section parameter.
428 Input
429
430
431 modifier
432 is the modifier of the link. This will also be the modifier
433 of the pointer generated by snapping the link. The null
434 modifier ""b is generally used. Input
435
436 link_relp
437 is the offset of the generated link relative to the base of
438 the linkage section. Note that this value is calculated as
439 if there were no static section resident in the linkage
440 section. When the object is closed via a call to
441 ocu_$close all linkage references are relocated to adjust
442 for the presence of a static section. If the caller wishes
443 to use this value for other purposes that to include in
444 another call to ocu_ it will have to be adjusted for the
445 presence of the static section manually. Output
446
447
448 :Entry: emit_segname: 02/10/86 ocu_$emit_segname
449
450
451 Function:
452 Emits a single class-3 segname definition and threads it
453 into the definition list. The definitions are chained in
454 the order of calls to ocu_$emit_definition and
455 ocu_$emit_segname. Sequential calls to emit_segname
456 generate multiple segnames in a single block. A call to
457 emit_segname after calls to emit_definition starts a new
458 block. It is invalid to call emit_definition without
459 calling emit_segname at least once.
460
461
462 Syntax:
463 dcl ocu_$emit_segname entry ptr char * varying bit *
464 returns fixed bin 18 unsigned;
465 def_relp = ocu_$emit_segname ocu_datap name flags;
466
467
468 Arguments:
469
470 ocu_datap
471 is a pointer returned by ocu_$open. This identifies all the
472 data structures needed to create the object segment. Input
473
474 name
475 is the name of this segname definition. Input
476
477
478 flags
479 is a bit string representing the flags to be set in the
480 definition. Input
481 Constants definition the values can be found in
482 ocu_dcls.incl.pl1.
483
484 DEFINITION_FLAGS_IGNORE = "1000"b
485 DEFINITION_FLAGS_ENTRY = "0100"b
486 DEFINITION_FLAGS_RETAIN = "0010"b
487 DEFINITION_FLAGS_INDIRECT = "0001"b
488
489 def_relp
490 is an offset to the generated definition relative to the
491 base of the definition section. Output
492
493
494 :Entry: emit_static: 02/10/86 ocu_$emit_static
495
496
497 Function:
498 Emits a block of words which are appended to the static
499 section. Since there is no relocation info for the static
500 section and it is forced to be absolute if it is contained
501 in the linkage section no relocation information is
502 required. Note that even if the static section is to be
503 contained in the linkage section references to the static
504 section should be made with static relocation info and not
505 attempt to adjust the offsets for the presence of the
506 linkage header. when the new object is closed all static
507 references will be mapped into the appropriate linkage
508 references.
509 Error encountered are reported using the sub_err_
510 subroutine.
511
512
513 Syntax:
514 dcl ocu_$emit_static entry ptr ptr fixed bin 18 unsigned
515 returns fixed bin 18 unsigned;
516 static_relp = ocu_$emit_static ocu_datap staticp word_count;
517
518
519 Arguments:
520
521 ocu_datap
522 is a pointer returned by ocu_$open. This identifies all the
523 data structures needed to create the object segment. Input
524
525 staticp
526 is a pointer to an array or words of dimension word_count
527 to be appended to the static section. Input
528
529
530 word_count
531 is the number of words to be appended to the static section.
532 Input
533
534 static_relp
535 is the offset of the block or words relative to the base of
536 the static section
537
538
539 :Entry: emit_symbol: 02/10/86 ocu_$emit_symbol
540
541
542 Function:
543 Emits a block of symbol words and appends them to the symbol
544 section. Errors encountered are reported using the sub_err_
545 subroutine.
546
547
548 Syntax:
549 dcl ocu_$emit_symbol entry ptr ptr ptr
550 fixed bin 18 unsigned
551 returns fixed bin 18 unsigned;
552 symbol_relp = ocu_$emit_symbol ocu_datap symbolp
553 relocationp word_count;
554
555
556 Arguments:
557
558 ocu_datap
559 is a pointer returned by ocu_$open. This identifies all the
560 data structures needed to create the object segment. Input
561
562 symbolp
563 is a pointer to an array symbol section words of dimension
564 word_count to be appended to the symbol section. Input
565
566
567 relocationp
568 is a pointer to a character string of length 2*word_count
569 representing the relocation information for the accompanying
570 block of words. Input
571 The relocation characters are taken from the set of standard
572 characters used by language translators see the Multics
573 Programmers Reference Manual. The relocation string is
574 required even if the object to be generated is not
575 relocatables since the relocation information is used to
576 locate static and linkage references which will have to be
577 relocated if the static section is linkage resident.
578
579 word_count
580 is the number of symbol words to be emitted. Input
581
582 symbol_relp
583 is the offset of this block of words relative to the base of
584 the symbol section. Output
585
586
587 :Entry: emit_text: 02/10/86 ocu_$emit_text
588
589
590 Function:
591 emits a block of text words appending them to the end of
592 the text section and returning the offset within the text
593 section. Errors encountered are reported using the sub_err_
594 subroutine.
595
596
597 Syntax:
598 dcl ocu_$emit_text entry ptr ptr ptr fixed bin 18 unsigned
599 returns fixed bin 18 unsigned;
600 text_relp = ocu_$emit_text ocu_datap textp relocationp
601 word_count;
602
603
604 Arguments:
605
606 ocu_datap
607 is a pointer returned by ocu_$open. This identifies all the
608 data structures needed to create the object segment. Input
609
610 textp
611 is a pointer to an array of text words of dimension
612 word_count to be appended to the text section. Input
613
614
615 relocationp
616 is a pointer to a character string of length 2*word_count
617 representing the relocation information associated with the
618 text array. Input
619 The characters used are the standard character relocation
620 codes used by the translators. see the Multics Programmers
621 Reference Manual. This string is required regardless of
622 whether the output object is to be relocatable since it is
623 used to relocate linkage and static references if the static
624 section is not separate.
625
626 word_count
627 is the number of words of text to be emitted. Input
628
629 text_relp
630 is an offset to this block of words relative to the base of
631 the section. Output
632
633
634 :Entry: emit_msf_map: 08/07/86 ocu_$emit_msf_map
635
636
637 Function:
638 Emits the msf_map in the definition section of the new
639 object. This entrypoint should ONLY be called if the object
640 segment being generated is an MSF component. Errors
641 encountered are reported using calls to the sub_err_
642 subroutine.
643
644
645 Syntax:
646 dcl ocu_$emit_msf_map ptr fixed bin 15 unsigned
647 fixed bin 15 unsigned;
648 call ocu_$emit_msf_map ocu_datap component_count
649 my_component;
650
651
652 Arguments:
653
654 ocu_datap
655 is a pointer returned by ocu_$open. This identifies all the
656 data structures needed to create the object segment. Input
657
658 component_count
659 is the number of components in the MSF including component
660 0. Input
661
662 my_component
663 is the number of the component being generated in the range
664 0 to component_count - 1. Input
665
666
667 :Entry: open: 02/10/86 ocu_$open
668
669
670 Function:
671 Allocates and initializes the data structures used to create
672 the object segment and returns a pointer used to locate the
673 structures.
674
675
676 Syntax:
677 dcl ocu_$open entry char * char * bit * ptr
678 fixed bin 35;
679 call ocu_$open dir_name entry_name flags ocu_datap code;
680
681
682 Arguments:
683
684 dir_name
685 is the name of the directory in which the final object will
686 be created. Input
687
688 entry_name
689 is the entry name of the output object segment. Input
690
691
692 flags
693 is a bit string indicating various options to be used in the
694 creation of the object segment. Input
695 The following values may be used to derive the desired flag
696 value. found in ocu_dcls.incl.pl1
697
698
699 OPEN_FLAGS_BOUND = "100000"b
700 The object being created will have the format of a
701 bound object ie. one containing multiple
702 translator produced objects and is formatted
703 according to the standards for bound objects.
704 This format is not enforced by ocu_ and it is the
705 responsibility of the caller to set up the object
706 properly.
707
708
709 OPEN_FLAGS_RELOCATABLE = "010000"b
710 The object being created has relocation
711 information and can be used as input to the binder
712 or linkage editor. This flag is used by ocu_ to
713 determine whether or not to add the relocation
714 information to the linkage section of the object
715 segment when the object is closed.
716
717
718 OPEN_FLAGS_PROCEDURE = "001000"b
719 The object contains executable code.
720 OPEN_FLAGS_SEPARATE_STATIC = "000100"b
721 The object segment is to contain a static section
722 rather than have the static section included in
723 the linkage section. This flag is examined by
724 ocu_ when closing the object segment to determine
725 relocation of static and linkage section
726 references and to generate the sections properly.
727
728
729 OPEN_FLAGS_PERPROCESS_STATIC = "000010"b
730 The static section of this object segment is not
731 to be duplicated when called from within a run
732 unit.
733 OPEN_FLAGS_NO_HASHTABLE = "000001"b
734 Do not create a definition section hash table for
735 this object segment. This is primarily used when
736 creating either MSF components which are never
737 searched or objects with very few entrypoints.
738
739
740 ocu_datap
741 is a pointer to the ocu data structures used by the other
742 calls. Output
743
744 code
745 is a standard status code. Output
746
747
748 :Entry: release: 02/10/86 ocu_$release
749
750
751 Function:
752 Releases table storage used by ocu_ when an invocation is
753 aborted.
754
755
756 Syntax:
757 dcl ocu_$release entry ptr;
758 call ocu_$release ocu_datap;
759
760
761 Arguments:
762
763 ocu_datap
764 is a pointer returned by ocu_$open. This identifies all the
765 data structures to be released. Input