1 :Info: bind: bd:  2019-06-01 bind, bd
  2 
  3 Syntax as a command:  bd path_specs {-control_args}
  4 
  5 
  6 Function:  produces a single bound object segment from one or more
  7 unbound object segments, which are called the components of the bound
  8 segment.  You can use archive segments or unarchived segments to
  9 specify pathnames of object components.
 10 
 11 
 12 Arguments:
 13 path_specs
 14    can be one or more of the following logically concatenated in a
 15    left-to-right order to produce a single sequence of input component
 16    object segments.
 17    -archive PATHs, -ac PATHs
 18       indicates that each PATH is the pathname of an archive segment
 19       containing one or more object segments.  If the .archive suffix
 20       does not exist, it is assumed.  (All arguments following -archive
 21       but preceding the next control argument are considered to be
 22       pathnames.)
 23 
 24 
 25    -segment PATHs, -sm PATHs
 26       indicates that each PATH is the pathname of a stand-alone
 27       segment.  The pathname is tried as given, i.e., no suffixes are
 28       assumed.  (All arguments following -segment but preceding the
 29       next control argument are considered to be pathnames.)
 30    PATHs
 31       functions exactly as -archive PATHs.
 32 
 33 
 34 Control arguments:
 35 -bindfile path, -bdf path
 36    specifies the name (not pathname) of the bindfile to be used to
 37    control the binding process.  The suffix .bind is assumed.  (See
 38    "Notes on bindfile" below.)
 39 -brief, -bf
 40    suppresses printing of warning messages.
 41 -force_order, -fco
 42    is equivalent to including a Force_Order statement in the bindfile.
 43    Since the need to use Force_Order is often temporary and caused by
 44    update archives that have had components deleted, this is preferable
 45    to using the Force_Order statement because you need only use it
 46    while the temporary condition exists.
 47 
 48 
 49 -force_update path_specs, -fud path_specs
 50    is similar in function to -update except that the path_specs (see
 51    the path_specs argument above) specified following -force_update
 52    need not exist.  Any path that exists is treated the same way as for
 53    -update and any that doesn't is simply ignored.  This is useful for
 54    constructing abbreviations used for binding objects that may or may
 55    not have update paths in various locations.
 56 -list, -ls
 57    produces a listing segment whose name is derived from the name of
 58    the bound object segment plus a suffix of list.  The listing segment
 59    is generated to dprint; it contains the bound segment's bind control
 60    segment (see "Notes on bindfile"), its bind map, and that
 61    information from the bound object segment printed by the
 62    print_link_info command.  You can't invoke -list with -map.  In the
 63    absence of -list or -map, no listing segment is generated.
 64 
 65 
 66 -map
 67    produces a listing segment (with the suffixes list and map) that
 68    contains only the bind map information.  It is incompatible with
 69    -list.  In the absence of -list or -map, no listing segment is
 70    generated.
 71 -update path_specs, -ud path_specs
 72    indicates that the following list of path_specs (see the path_specs
 73    argument above) specifies update rather than input object segments.
 74    The update object segments are matched against the input object
 75    segments by object segment name.  Matching update object segments
 76    replace the corresponding input object segments; unmatched ones are
 77    appended to the sequence of input object segments.  If several
 78    update object segments have the same name, only the last one
 79    encountered is bound into the bound segment.
 80 
 81 
 82 Notes on bindfile selection:  As the binder is examining the archive
 83 components and loose segments, it is also looking for a bindfile.  Any
 84 segment whose name ends with the suffix "bind" is considered a
 85 bindfile.  If you specify -bindfile, only bindfiles by that name are
 86 considered and the last one by that name is selected; otherwise the
 87 first bindfile found among the input segments and all bindfiles among
 88 the update segments are considered and the last one is selected.  If
 89 more than one bindfile is found among the input segments, the second
 90 through last are ignored and generate a warning.
 91 
 92 
 93 Notes on bindfile:  The bindfile is a segment containing symbolic
 94 instructions that control the operation of the binder.  The syntax of
 95 the bindfile statements consist of a keyword followed by zero or more
 96 parameters and then delimited by a statement delimiter.  Master
 97 statements pertain to the entire bound object segment; normal
 98 statements pertain to a single component object within the bound
 99 segment.  Master statements are identified by master keywords that
100 begin with a capital letter; normal keywords begin with a lowercase
101 letter.  A keyword designates a certain action to be undertaken by the
102 binder pertaining to parameters following the keyword.
103 
104 
105 List of master keywords:
106 Objectname
107    the parameter is the segment name of the new bound object.
108 Order
109    the parameters are a list of objectnames in the desired binding
110    order.  In the absence of an order statement, binding is done in the
111    order of the input sequence.  If an Order statement is present in
112    the bindfile, every object segment being bound must be mentioned in
113    its parameter list.
114 Force_Order
115    same as Order except that the list of parameters can be a subset of
116    the input sequence, allowing the archive segments to contain
117    additional segments that are not to be bound (e.g., source
118    programs).  However, the parameter list must include all segments
119    mentioned in objectname statements.
120 
121 
122 Partial_Order
123    same as Order except that the list of parameters can be a subset of
124    the input sequence; the named objectnames are placed in the bound
125    output segment in the order specified and the remaining objects are
126    placed after those named, in the order of the input sequence.
127 Ignore
128    the parameters can be a subset of the input sequence, indicating
129    objects not to be included in the bound output segment.  The ignored
130    objects are still mentioned in the bound segment's source map.
131 
132 
133 Global
134    the single parameter can be retain, delete, or no_link.  The
135    parameter selected pertains to all component object segments within
136    the bound segment.  A global or explicit statement concerning a
137    single component object or a single external symbol of a component
138    object overrides the Global statement for that component object or
139    symbol.
140 Addname
141    the parameters are the symbolic names to be added to the bound
142    segment.  If Addname has no parameters, it adds to the bound segment
143    the segment names and synonyms of those component objects for which
144    at least a single entrypoint was retained.
145 
146 
147 No_Table
148    does not require parameters.  It omits from the bound segment the
149    symbol tables from all the component symbol sections containing
150    symbol tables.  If you don't give this keyword, all symbol tables
151    are kept.
152 Perprocess_Static
153    does not require parameters.  It turns on the perprocess_static flag
154    of the bound segment, which prevents the internal static storage
155    from being reset during a run unit.
156 
157 
158    The Order, Force_Order, and Partial_Order statements are mutually
159    contradictory; only one of these can be present in any bindfile.
160 
161    If you supply no bindfile, the binder assumes default parameters
162    corresponding to the following:
163       Objectname: segment name of the first input archive file.
164       Global: retain; /*regenerate all definitions*/
165 
166 
167 List of normal keywords:
168 objectname
169    the single parameter is the name of a component object as it appears
170    in the archive segment.  The objectname statement indicates that all
171    following normal statements (up to but not including the next
172    objectname statement) pertain to the component object whose name is
173    the parameter of the objectname statement.
174 
175 
176 synonym
177    the parameters are symbolic segment names declared to be synonymous
178    to the component object's objectname.  When b is declared to be a
179    synonym for a, references (in the bound components) of the form b or
180    b$x (any x) are resolved during binding by searching for a
181    definition of b or x in component a.  You must give the synonym
182    instruction if such references are to be prelinked.  The synonym
183    instruction also affects dynamic linking so that if b is a reference
184    name for the bound segment, then references of the form b or b$x are
185    resolved by searching component a.  In this case the synonym
186    instruction may reduce the cost of dynamic linking, and it avoids
187    possible ambiguities when two components contain definitions for the
188    symbol b.  Take care to state explicitly in a synonym statement all
189    the normally used segment names of a component object.
190 
191 
192    For example, the create and create_dir commands are implemented
193    in one procedure, and both have abbreviations; thus a bindfile for
194    the bound segment in which this procedure resides contains
195       objectname: create;
196       synonym: create, cr, create_dir, cd;
197    Failure to state segment names results in inefficient linker
198    performance.
199 retain
200    the parameters are the names of entrypoints defined within the
201    component object segment that you wish to retain as entrypoints of
202    the bound object segment.
203 
204 
205 delete
206    the parameters are the names of entrypoints defined within the
207    component object segment that you don't wish to be retained as
208    entrypoints of the new bound segment.
209 no_link
210    the parameters are the names of entrypoints that are not to be
211    prelinked during binding.  This statement implies that the
212    specified names be retained.
213       The retain, delete, and no_link statements are considered
214    exclusive.  An error message is displayed if the binder recognizes
215    that two or more such statements were made regarding any single
216    entrypoint.
217 
218 
219 global
220    the single parameter can be retain, delete, or no_link.  The
221    parameter selected becomes effective for all entrypoints of the
222    component object.  An explicit retain, delete, or no_link statement
223    concerning a given entrypoint of the component object overrides the
224    global statement for that specific entrypoint.  A global no_link
225    causes all external references to the component object to be
226    regenerated as links to entrypoints; this allows execution time
227    substitution of such a component by a free-standing version of it,
228    for example, for debugging purposes.
229 table
230    does not require parameters.  It retains the symbol table for the
231    component and is needed to override the No_Table master keyword.
232 
233 
234 List of bindfile delimiters:
235 :
236    keyword delimiter used to identify a keyword followed by one or
237    parameters.  A keyword that is followed by no parameters is
238    delimited by a statement delimiter.
239 ;
240    statement delimiter.
241 ,
242    parameter delimiter.  The last parameter is delimited by a statement
243    delimiter.
244 /*
245    begin comment.
246 */
247    end comment.
248 
249 
250 :Internal: history_comment.gi: 2019-06-01  history_comment
251 
252 /****^  HISTORY COMMENTS:
253   1) change(2019-06-01,Swenson), approve(2019-06-01,MCR10058),
254      audit(2019-06-01,GDixon), install(2019-06-01,MR12.6g-0022):
255      Fixed typo in bind example.
256                                                    END HISTORY COMMENTS */
257