Binder dialogs

Your program conducts a dialog with the binder using either the IEWBIND and IEWBUFF assembler macros or the equivalent definitions and statements for other programming languages.

Assembler coding summaries of the IEWBIND and IEWBUFF macros are provided in IEWBIND function summary and Figure 1. Certain function calls are required to establish and terminate the dialog, workmod, and buffers. You select among the remaining calls according to the needs of your program. The following sequence of function calls is recommended:
  1. Use STARTD to begin the dialog and to establish a processing environment. A dialog token is returned.
  2. Use CREATEW to create a workmod and associate it with the dialog. You pass the dialog token received from the STARTD call and receive a workmod token in return. You specify processing intent on CREATEW as either ACCESS or BIND.
  3. Use SETO for setting options and module attributes. You pass either the dialog token or the workmod token. If a dialog token is passed, the options and attributes become the defaults for all workmods attached to that dialog. If a workmod token is specified, any specified options apply only to that workmod.
  4. Use INCLUDE to bring one or more modules into the workmod. All control statements and object and program modules are brought into a workmod via the INCLUDE call. If INTENT=ACCESS, one and only one program module can be included in the workmod at a time. Before including another program module, the workmod must be reset.
  5. Use ALTERW to make selective changes to symbols or sections in modules already in the workmod or yet to be included. By choosing either the IMMED or NEXT mode of operation, you indicate whether the alteration is applied globally to all modules in the workmod or only to the next module included into the workmod.
  6. Several of the function calls do not take place immediately, but are deferred until later in the processing cycle. ALIGNT, INSERTS, ORDERS, and STARTS affect the overall structure of the module and are deferred until BINDW. ADDA provides for specification of aliases and is deferred until SAVEW. You can request these functions in any order, but they must be received prior to the BINDW call.
  7. Use the GETC or GETN function calls to get a list of sections or classes for use in subsequent calls. Use the GETD or GETE function calls to extract data from a program module, or use the PUTD function call to add data to it. Before you can use these function calls, your program must define and allocate buffers. Use the GETBUF and INITBUF functions of the IEWBUFF macro to allocate and initialize storage areas to contain the data. Use the MAPBUF function to define DSECT mappings of the areas.
  8. Use the BINDW function to instruct the binder to resolve all external references and calculate relocatable address constants. Automatic library call resolves any unresolved external references. Text alignment, ordering, and overlay segmentation are all done at this time.

    Use SETL to specify special call libraries for resolving external references or to indicate that certain references are not to be resolved. SETL requests must precede BINDW.

    If INTENT=BIND, you may issue the BINDW request before any LOADW or SAVEW for a module. LOADW and SAVEW automatically perform bind processing if you did not issue a separate BINDW call previously. If INTENT=ACCESS, a BINDW request is rejected. Binding is required if more than one module has been included, or if other changes have taken place that would affect the size or structure of the module, such as reordering sections.

    Once binding has taken place, no further modifications to the workmod are allowed.

  9. Use LOADW or SAVEW to dispose of the module in workmod. LOADW requests that the module be loaded into virtual storage in a format suitable for execution. SAVEW requests that the module be saved in a data set. You can issue both requests for a module in either order.
  10. Use DELETEW to delete the workmod and free all associated resources. Use RESETW to free all of the module data in the designated workmod, but to retain the workmod structure. RESETW is functionally equivalent to issuing DELETEW and CREATEW requests in sequence.

    Delete and reset requests are rejected if the workmod is in an altered state. You can force the deletion of an altered workmod by specifying PROTECT=NO on the DELETEW request.

  11. When your program is finished processing all of the data obtained from the workmod, use the IEWBUFF FREEBUF function to free the storage for the data.
  12. Use ENDD to end the dialog and to free all remaining resources. An ENDD request is rejected if any modified workmods remain, but can be forced by specifying PROTECT=NO.

See Programming examples for binder APIs for a typical assembler language application of the binder APIs.