1 10/21/86  object_lib_
  2 
  3 The object_lib_ subroutine provides utilities for dealing with
  4 object segments and multisegment files in a consistent manner.
  5 
  6 
  7 Entry points in object_lib_:
  8    (List is generated by the help command)
  9 
 10 
 11 :Entry:  initiate:  10/21/86 object_lib_$initiate
 12 
 13 
 14 Function:  Initiates the executable binary specified, with the
 15 given refname, terminating the refname as required and returning
 16 a pointer and bit count.  The target is optionally checked to
 17 insure that it is actually an object segment or MSF, and that
 18 its status as an object MSF is consistent.
 19 
 20 
 21 Syntax:
 22 dcl object_lib_$initiate entry (char(*), char(*), char(*),
 23      bit (1), ptr, fixed bin (24), bit (1), fixed bin (35));
 24 call object_lib_$initiate (dirname, entryname, refname,
 25      validate_sw, seg_ptr, bit_count, msf_sw, code);
 26 
 27 
 28 Arguments:
 29 dirname
 30    is the directory name of the object to be initiated.  (Input)
 31 entryname
 32    is the entry name of the object to be initiated.  (Input)
 33 refname
 34    is the reference name to be placed on the object when it is
 35    initiated.  If the object is an object MSF, the reference name will
 36    be placed on component 0.  (Input)
 37 validate_sw
 38    is a switch to select whether of not the target segment or MSF is
 39    checked to see if it is a valid executable binary.  (Input)
 40 
 41 
 42 seg_ptr
 43    is a pointer to the object.  If the object is an object MSF, a
 44    pointer to component 0 will be returned.  (Output)
 45 bit_count
 46    is the bit_count of the segment pointed to by seg_ptr.  If the
 47    target is an MSF, it is the bit count of component 0.  (Output)
 48 msf_sw
 49    is a flag indicating whether the object specified is an object MSF.
 50    (Output)
 51 code
 52    is a standard status code. (Output)
 53 
 54 
 55 :Entry:  init_no_clear:  10/21/86 object_lib_$init_no_clear
 56 
 57 
 58 Function:  Initiates the executable binary specified, with the
 59 given refname, terminating the refname as required and returning
 60 a pointer.  If the refname is already in use, term_$no_clear is
 61 called rather than term_$single_refname.  This entrypoint is
 62 intended for use only by find_command_ since it will not clear
 63 find_command_'s associative memory of entrypoints which is
 64 assumed to be managed manually by find_command_.  The target is
 65 optionally checked to insure that it is actually an object
 66 segment or MSF, and that its status as an object MSF is
 67 consistent.
 68 
 69 
 70 Syntax:
 71 dcl object_lib_$init_no_clear entry (char(*), char(*), char(*),
 72           bit (1), ptr, fixed bin (24), bit (1), fixed bin (35));
 73 call object_lib_$init_no_clear (dirname, entryname, refname,
 74           validate_sw, seg_ptr, bit_count, msf_sw, code);
 75 
 76 
 77 Arguments:
 78 dirname
 79    is the directory name of the object to be initiated.  (Input)
 80 entryname
 81    is the entry name of the object to be initiated.  (Input)
 82 refname
 83    is the reference name to be placed on the object when it is
 84    initiated.  If the object is an object MSF, the reference name will
 85    be placed on component 0.  (Input)
 86 validate_sw
 87    is a switch to select whether of not the target segment or MSF is
 88    checked to see if it is a valid executable binary.  (Input)
 89 
 90 
 91 seg_ptr
 92    is a pointer to the object.  If the object is an object MSF, a
 93    pointer to component 0 will be returned.  (Output)
 94 bit_count
 95    is the bit count of the segment pointed to by seg_ptr.  If the
 96    target is an MSF, it is the bit count of component 0.  (Output)
 97 msf_sw
 98    is a flag indicating whether the object specified is a MSF.
 99    (Output)
100 code
101    is a standard status code.  (Output)
102 
103 
104 :Entry:  get_component_info:  10/21/86 object_lib_$get_component_info
105 
106 
107 Function:  Returns structural and identifying information about
108 an object segment or MSF.  Varying amounts of information may be
109 returned depending on the value of the oi_type parameter.
110 
111 
112 Syntax:
113 dcl object_lib_$get_component_info entry (ptr, ptr, char(8),
114           char(*), ptr, fixed bin(35));
115 call object_lib_$get_component_info (segp, areap, version_reqd,
116           oi_type, infop, code);
117 
118 
119 Arguments:
120 segp
121    is a pointer to the segment to be examined.  This may be a single
122    segment or a component of an object MSF.  If it is a component of an
123    object MSF info is returned for all of the components.  (Input)
124 areap
125    is a pointer to an area in which the output structure is to be
126    allocated.  If this pointer is null, the system_free_area is used.
127    (Input)
128 version_reqd
129    is the version of the output structure desired.  Currently only one
130    version is supported.  This value should be component_info_version_1
131    (declared in object_lib_defs.incl.pl1) (Input)
132 
133 
134 oi_type
135    is  the type  of object  info desired  by the  caller.  Four
136    values are supported, described under "List of oi_types" below.
137    (Input)
138 infop
139    is a pointer to a component_info structure allocated by
140    object_lib_$get_component_info.  (Output)
141 code
142    is a standard status code.  (Output)
143 
144 
145 List of oi_types:
146 none
147    No object info is filled into the structure.  Only the segment
148    pointers, bit_count, and terminate flag is set.
149 brief
150    Object info is filled in for each component by calling
151    object_info_$brief for each component.
152 display
153    Object info is filled in for each component by calling
154    object_info_$display for each component.
155 long
156    Object info is filled in for each component by calling
157    object_info_$long for each component.
158 
159 
160 List of component_info elements:
161    The component info structure returned has the following definition
162    (declared in object_lib_defs.incl.pl1):
163 
164    dcl 01 component_info       aligned based (comp_infop),
165         02 version             char (8),
166         02 flags               aligned,
167          03 msf                bit (1) unaligned,
168          03 mbz                bit (35) unaligned,
169         02 max                 fixed bin,
170         02 comp                (0:max_component
171                                refer (component_info.max)),
172          03 segp               ptr,
173          03 bc                 fixed bin (24),
174          03 mbz                bit (36) aligned,
175          03 info               like object_info;
176 
177 
178 version
179    is the version number of the structure.  It is currently "cinfo1.0".
180    The named constant for this value component_info_version_1 is
181    declared in object_lib_defs.incl.pl1.
182 msf
183    is a flag indicating that the object in question is an object MSF.
184 max
185    is the number of the largest component in the file.
186 comp
187    contains the per-component information.
188 
189 
190 segp
191    is a pointer to the N'th component of the file.
192 bc
193    is the bit_count of the N'th component of the file.
194 info
195    is identical to the structure object_info (declared in
196    object_info.incl.pl1) for a description of the fields in this
197    section see object_info_.
198 
199 
200 :Entry:  get_def_target:  10/21/86 object_lib_$get_def_target
201 
202 
203 Function:  Searches the segment specified by segp for a
204 definition matching segname and offsetname and returns a pointer
205 to the target of the definition.  If the segment specified is
206 component 0 of an object MSF, the target pointer return points
207 to the eventual target of the definition (in some component
208 other than component 0).  If live_sw is "1"b, and the definition
209 found refers to the static or linkage section, the targetp value
210 returned will be in the live copy of the linkage or static
211 section, respectively.  If it is "0"b, the value returned will
212 point to the template in the object segment.
213 
214 
215 Syntax:
216 dcl object_lib_$get_def_target entry (ptr, fixed bin(24), char(*),
217           char(*), bit(1), ptr, fixed bin(35));
218 call object_lib_$get_def_target (segp, bc, segname, offsetname,
219           live_sw, targetp, code);
220 
221 
222 Arguments:
223 segp
224    is a pointer to the segment to search.  (Input)
225 bc
226    is the bit_count of the segment to search.  (Input)
227 segname
228    is the segname to search for.  (Input)
229 offsetname
230    is the name of the definition to search for.  (Input)
231 
232 
233 live_sw
234    specified whether definitions which reference the static or linkage
235    section of the object should return a pointer relative to the live
236    copy pointed to by the LOT/ISOT or to the static template stored in
237    the object segment itself.  (Input)
238 targetp
239    is a pointer to the eventual target of the definition.  (Output)
240 code
241    is a standard status code.  (Output)