Understanding binder programming concepts

Before you begin designing programs for the binder application programming interface, you should understand several of its programming concepts.

dialog

A programmed session with the binder is called a binder dialog. You begin the session with a request to start a dialog. This request establishes the environment for binder processing during that dialog, including obtaining work space, initializing control blocks, and specifying DD names for the standard data sets to be used.

Your program can start more than one dialog and maintain more than one dialog at the same time. The dialogs are independent. You can perform operations on more than one dialog concurrently, but you cannot pass binder data directly from one dialog to another.

When any dialog is ended, all buffers and control information relating to that dialog are deleted.

dialog token

Each dialog is identified by a unique dialog token. The dialog token is created when you request a new dialog. You use the token corresponding to a specific dialog when you request services, so the binder can perform the services on the correct input and return the desired results to the correct dialog. The token is invalidated when the dialog is ended.

workmod

An area of working storage used to create or operate on a program module is called a workmod. After a dialog has been established, your program issues requests to create a workmod, to reset a workmod to the null state, or to delete a workmod. At least one workmod must be created before any module operations can be requested.

A dialog can have many workmods associated with it, but each workmod is associated with only one dialog. Binder-generated data cannot be passed between workmods. Ending a dialog causes any remaining workmods associated with it to be deleted.

workmod token

Each workmod is identified by a unique workmod token. The workmod token is created when the request for a new workmod is made. The workmod token associates the workmod with a particular dialog. Your program must pass the token as a parameter on all requests involving that workmod. The token is invalidated when either the workmod is deleted or the dialog is ended.

processing intent

Processing intent specifies the range of binder services that may be requested for a workmod. The processing intent is set to either bind or access when the workmod is created. Bind allows editing of the modules; access does not. See Processing intents for detailed information.

element

An element is a named portion of module data in a workmod that is directly addressable by the binder. Program modules logically consist of elements. Each element is identified by its data class identifier and, optionally, a section name.

class

A class identifier is a required descriptor for each element. It identifies the type and the format of the data element and determines the operations that can be performed on it. The following binder-defined classes are valid:

B_TEXT: Relocatable text, including executable machine instructions, constants, and, in the case of the nonreentrant programs, data areas defined within the program. See also B_TEXT24 and B_TEXT31.
B_PRV: Pseudoregister vector (a data area shared across compile units) that is used by high-level languages and assembler code using DXD and CXD instructions.
B_ESD: External Symbol Dictionary, a catalog containing all symbols that are available to the binder. These symbols include section and class names, as well as ordinary symbol definitions and references.
B_RLD: Relocation dictionary, containing information used to adjust addresses within the code based on where the module is loaded.
B_IDRB: Binder identification record, indicating the binder version, size, and how and when the program object was created.
B_IDRL: Language processor identification record, indicating the compilers that created the binder input, the date of compilation, and the binder size.
B_IDRU: User-specified identification record, containing data provided on an IDENTIFY control statement.
B_IDRZ: AMASPZAP identification record, for programs that have been modified at the object level.
B_SYM: Internal symbol table records
B_MAP: Module map
B_TEXT24: Relocatable text loaded below the 16-meg line and used in place of B_TEXT if RMODE=SPLIT is specified.
B_TEXT31: Relocatable text loaded above the 16-meg line and used in place of B_TEXT if RMODE=SPLIT was specified.
B_LIT: Load information table, containing data generated by the binder and used by the Language Environment® run time. For more information, see Accessing program object class information.
B_IMPEXP: IMPORT/EXPORT table, containing data generated by the binder and used by the Language Environment run time to support DLLs and DLL applications.
B_PARTINIT: Part initializers, containing the initial data for parts in merge classes. During bind processing, merge classes are mapped at the module level and the initial data moved from B_PARTINIT to the owning merge class.
B_DESCR: Linkage descriptors built by the binder for XPLINK support (Linkage Descriptors may also exist in compiler-defined classes).

In addition to the binder defined classes shown above, compiler-defined class names and class names that are defined by you (or your system programmer) can be specified on all calls. Class names are limited to 16 characters. Class names beginning with C_ should be used only for Language Environment-enabled applications.

section

A section name is a programmer-, assembler-, or compiler-assigned name of a collection of one or more elements, where each element belongs to a specified class. All binder actions referring to sections affect all the elements in that section. For control and common sections, the section name is the CSECT or common section name.

Some elements do not relate directly to any particular section (for example, the binder identification records). The binder assigns these elements unique section names.

Unnamed sections (sections with names consisting of all blanks), and sections whose names the user has designated as not visible to the other sections in the module ('section scope'), are given unique binder–generated names. Binder–generated names are fullword integers. They are printed in binder listings as $PRIVxxxxxx, where xxxxxx is the printable representation of the integer. The one exception is 'blank common' whose name is retained as a one-character blank.

Section names may be assigned by the user or by the binder. For each of the binder-defined classes just described, the sources of the definitions for the section names are shown in the following table:

Table 1. Section names
Class Name	Section Name
B_TEXT	User specified
B_PRV	User specified; binder retains them in binder-created section X'00000003'
B_ESD	User specified
B_RLD	User specified
B_IDRB	Binder-created class name, in binder-created section X'00000001'
B_IDRL	User specified
B_IDRU	User specified
B_IDRZ	User specified
B_SYM	User specified
B_MAP	Binder-created class name, in binder-created section X'00000001'
B_TEXT24	User specified or binder-created
B_TEXT31	User specified or binder-created
B_LIT	Binder-created class name, in binder-created section IEWBLIT
B_IMPEXP	Binder-created class name, in binder-created section IEWBCIE
B_PARTINIT	User specified
B_DESCR	Binder-created class name, in binder-created section X'00000003'

A program module can be visualized as a two-dimensional grid with the class type on one axis and the section name on the other, as shown in Figure 1. Any class type can appear in more than one section, and any section can contain elements in multiple classes. Some elements relate to the entire module, not to any particular section, and do not have a section name.

Figure 1. Data items. The workmod shown in this example contains three sections, MAIN, SUBA, and SUBB. The B_IDRB item shown does not relate to a particular section. Note that items do not need to exist for all class and section combinations. ieab2u01