Overview

The binder provides low level functions normally associated with linkers and loaders and several others as well.

The high level functions of the binder are: relocation of code, resolution of external symbols, sharing of storage, planning and building Gnosis address segments. The binder also allows control sufficient to segregate classes of CSECT's into their own segments for a variety of purposes.

As input, the binder accepts the output of IBM compilers and assemblers. The binder produces address segment factories that may serve as factory components.

Most binders have a special relationship to an older binder called its parent. Binders with the same parent share physical resources with each other and the address segments that they produce may share sub-segments. Write access to such shared segments may be made available at the leaves of the sub-tree.

This relationship forms a tree of binders. Binders near the root of the tree may provide segments available for sharing at the leaves of the subtree. They may also provide subroutine libraries available at the leaves.

.allocated - state of a blocklist

.destination - The bit location & bit length in the .string to be relocated

.gravid - state of a blocklist; ready to produce a copy

.length - The number of bytes in the .string

.location - The alignment and offset from alignment required

.nascent - state of a blocklist

.starting-point - Initial entry point

.string - That which appears in the executable segment

.symbol - External symbols in Assembler

.symbol-table - Internal symbols for DDT etc.

A blocklist is an ordered {nonempty} collection of blocks and a .location. A blocklist has a .state.
{In any segment produced by the binder, the blocks in a blocklist are either all loaded contiguously or none loaded.}

A block consists of a data part, a set of SD's {.symbol definitions} one of which may be called the naming SD, an integer .length, and a {possibly nil} reference to a .symbol-table. {A block models a CSECT.}

The data part is either a .string and a set of SU's {.symbol uses}, or a key, or a ref key (a place to store a key).
A .string is an array of 8-bit integers {bytes}. If the block's blocklist is .allocated, the .string represents storage for such an array; otherwise, the array is pure data that cannot change.
The length of the array is less than or equal to the .length of the block. {The rest of the block is uninitialized. For example, in the case of common blocks, the .string may be of length zero.}

Design note: We do not allow .strings with "holes" {uninitialized portions before the end}. We hope they aren't necessary.

There is an implementation limit of something less than 2**23 on the length of a .string.

An SU consists of a .source, a .destination, and a sign.
The .source is either:
(1) a .symbol and a Boolean called "required",

(2) the name of an external dummy section,

(3) a CXD.

The value of the .source is respectively:
1. The integer of the SD {in the binder} with the same .symbol, plus the address of the block containing that SD. The log base 2 of modulus of the .location of that block's blocklist must be at least the bit length of the .destination of this SU. {This means the resulting address must fill the field to be relocated.} If "required" is false and the .source cannot be evaluated as above, the value is zero.
2. The offset, if any, of that external dummy section. {The external dummy sections of the binder must be frozen.}
3. The total length of the external dummy sections that have offsets {including any padding for alignment}. The external dummy sections of the binder must be frozen.
The .destination is a bit pointer and a bit length.
The bit pointer is a positive integer that is less than or equal to the number of bits in the .string. The bit pointer is greater than or equal to the bit length.

The bit length is at most 48.

{A bit length of zero is used where there is a requirement for a block but no need for the address of the block.}

An SU in a binder is said to be satisfied when its .source can be evaluated.

Applying a {satisfied} SU means the value of the .source is added to or subtracted from {according to the sign of the SU} a portion of the .string. If the bit pointer is p and the bit length is l, the p'th bit of the string will be the low-order bit and the (p-l+1)th bit will be the high-order bit of the portion. Other bits of the .string are unaffected, and overflow and carries from the addition or subtraction are ignored.

SU's are applied only by the Make Loadable operation ((make-loadable)). {That is significant for SU's with "required" false.}

{An SU with "required" false is analogous to the WXTRN facility of other S/370 loaders.}

{Other S/370 loaders allow moduli of 2**32, 2**24, and 2**16. We consider moduli of 2**12 and 2**4 to be useful also.}

If the data part of the block is a key or a ref key, the .length is a power of 16 greater than or equal to 4096. The modulus of the .location of the block's blocklist must be at least the .length. The address of the block modulo the .length must be zero. {Each address in the address set must be zero modulo the .length.}
{The key will be responsible for defining the meaning of those addresses. If the data part is a ref key, different keys can be stored into it at run time.}

If the data part of a block is a ref key, a slot key will be provided that grants access to the slot. This slot key is provided when binder factories produce factories {(refkey1)} or when l-segs factories produce l-segs {(refkey)}. Ref Key blocks arise thru the logic at (mrk).

The rule for knowing what else is in the node with your key or ref key is complicated and unpublished. So is the rule for knowing what background key is in effect. So use of window keys is unsupported, discouraged, but not currently prevented. It might be useful to publish the rules.

An SD consists of a .symbol and a 48-bit integer.
{The SD <ZOT,40> means that "ZOT" is the name of byte 40 of the block. (But the integer need not be less than the .length of the block.)}

{We may need to allow for negative integers here.}

The .symbol of the naming SD is the name of the block.

The .length of a block is an integer from 0 to 2**48 inclusive.

The address of a block is defined to be the address of its blocklist plus the .lengths of all its predecessors. The address set of a block is similarly defined.

A .symbol-table is a string, a .starting-point, and a name which is up to 63 characters.

A .starting-point is either
a reference to a block and an offset within that block,

a .symbol,

or nil.

The string is copied, byte by byte, from the SYM cards of a text deck.

{Once created, .symbol-tables never change.}

All .symbol-tables referenced by blocks in a binder must have different names.

A .symbol is either a string of up to 63 characters, or is .bound.
.Symbols arise from the external and entry symbols in text decks. In this case the .symbol is the string of characters from the text deck. {Other S/370 loaders restrict .symbols to 8 characters.}

Two .bound .symbols may or may not be the same.

{When an unnamed control section is encountered in a text deck, symbols that refer to it are .bound.}

A vacuous block is one with no SD's and a nil reference to .symbol-table. If its .length is less than 4096, its data part is a null .string and no SU's. If its .length is greater than or equal to 4096, its data part is DK(0) {and its .length is a power of 16}.

.States of a blocklist: A blocklist is just one of these:
.Nascent - the initial state of a blocklist. Make Loadable {(make-loadable)} changes it to the .loadable .state.

.Loadable - the blocklist can be loaded into pages in its final form. Each of its SU's has been applied. Make Gravid changes it to .gravid and Make Allocated changes it to .allocated RO.

.Gravid - will be changed to .allocated RW by creating a binder or segment from a factory. The only source of .gravid lists is from from a .loadable list via (make-gravid).

.Allocated RW - the blocklist is represented by real storage. Segments built from it will allow write access.

.Allocated RO - the blocklist is represented by real storage. Segments built from it will not allow write access. The only source of RO lists is .loadable and RW lists via binder__make_ro {(mblro)}.

Transitions between States
From .Nascent: to .nascent (blconcat), to .loadable (make-loadable)

From .Loadable: to .gravid (make-gravid), to .allocated RO (mblro)

From .Gravid: to .allocated RW ((bs-allocate) & (new-blok))

From .Allocated RW: to allocated RO (mblro), to real seg (mlseg)

From .Allocated RO: to real seg (mlseg)

To .Nascent: new (nas1), from text (nas), from nascent (blconcat)

To .Loadable: from .nascent (make-loadable)

To .Gravid: from .loadable (make-gravid)

To .Allocated RW: from .gravid ((bs-allocate) & (new-blok))

To .Allocated RO: from .loadable or .allocated RW (mblro)

A .location consists of a modulus and an address.
These are both integers. The modulus is a power of 2 up to 2**48 and the address is less than the modulus but not less than zero.

The address set of a blocklist is the set of integers (less than 2**48) that are equivalent to the address of the .location modulo the modulus.

The address at which the blocklist will eventually be loaded is a member of the address set.

{The .location determines the low n bits of the eventual address of the beginning of the blocklist, where the modulus is 2**n.}

Blocklist x is said to require blocklist y {being in the same binder} iff an SU of a block of x has the same .symbol as an SD of a block of y.

We define the closure C of blocklist A to be the smallest set of blocklists which includes A and each blocklist required by a blocklist in C.

An external dummy section consists of:
a name which is a character string,

a length (up to 2**24),

and an alignment factor which is either byte, halfword, fullword, or doubleword.

In addition, {if the external dummy sections are frozen,} it may have an offset (up to 2**24).

The names of the external dummy sections in a binder are all different.

No .symbol may appear in more than one SD in the blocks of the binder.

A binder is constant iff a factory has been produced from it. A constant binder will never use its space bank.

A block will be read-only if its blocklist is .allocated RO and read-write if its blocklist is .allocated RW.

LSEG(13; ==> 0;ASEG) returns a memory key ASEG which contains all the information in the binder that produced the LSEG. See the binder code for more information. Given an address, you can find the block that covers that address, the nearest preceding SD, and find the block's .symbol-table.

LSEG(14; ==> 0;K) returns K which is DK(i*2**32 + headers_offset) where i is the number of the l-segment relative to the l-segment factory that produced this LSEG, and headers_offset is described in the binder code and to be used in interpreting ASEG above.

{ni}LSEG(kt;==>X'30F0D';)

Today, LSEG(kt; ==> 3;).

See (p3,inf) for an idea to transmit l-segs.

BF(0;PSB,M,SB ==> c,grkb_strings,(2, X'FFFF'); BNDR,grkb_keys) "Make a binder"
Makes a new binder which is a copy of the {now constant} {old} binder of BF. All blocklists that were .allocated are shared between the binders.

This call returns using the extended jump protocol {(p3,ejp)}.

.Gravid blocklists become .allocated RW.

{Blocklists that are .gravid in BF's binder are .allocated RW in BNDR.}

For each .string in the old blocklist, the new blocklist will have a newly allocated array whose initial contents are the same as that of the old .string.

Key blocks are unaffected.

For each ref key block in a .gravid blocklist, a node key {to a newly allocated node} and a string are returned.

The keys are returned as "grkb_keys" in the description of the call. The strings are returned as "grkb_strings" in the description of the call, in the same order as the keys. {The X'FFFF' marks the end of the returned string and serves to identify the number of ref key blocks reported.} The string associated with a key is returned in the same jump as the key.

The string for each ref key block has the following data:

s(2, slotno) ^^ s(2, Length(name)) ^^ Char(name)

Name is the name of the ref key block. Length(name) will be 0 if the block has no name, has a .bound name, or has a null name.

Slot number slotno in the returned node is the ref key slot. No other slots of the node should be disturbed.

We plan to change the binder so as to return the slot number information in the databyte as we do in the l-seg calls described at (refkey).

{New storage is authorized by this operation. However, the new storage might not be acquired until someone has tried to store into a segment in which this .string appears. This uses the Virtual Copy Segment Keeper.}

The variable copy may only work as long as its constant parent exists.

The block array is initially empty.

Return codes:

c=0 if all is well.

c=1 if PSB is not an official prompt space bank.

c=2 if there is not enough space in PSB.

c=3 if SB is not an official space bank.

There is a generally available key to a binder factory which produces variable binders with no blocklists and no external dummy sections. The external dummy sections are not frozen. Such a binder factory may be found at SYS.BINDF.

BINDF(kt;==> X'F0D';).

General Points:
The only valid operation on a constant binder is (bind-query).

The first section within each ordercode description is the form of the call from the PL/I program using the facilities described in (p3,pli).

A symbol-spec, or specification of a .symbol that isn't .bound, has the following format:

s(2, Length(string)) ^^ string

A block is designated by a block_spec, which has either of the following forms (using (p3,pli)):
a named {(p2,bn)} block: symbol_spec
A block whose name is a .bound .symbol cannot be designated this way.

Block array element n: s(2,-n)
Implementation note: Today the block array is actually implemented as a linked list, so referencing high numbered elements is a bit inefficient.

A blocklist_spec has the same format as a block_spec, but specifies the blocklist containing the specified block.

A subset of blocklists is specified by specifying a blocklist and taking its closure {(p2,bsclosure)}. {Any desired subset can be specified by making a blocklist with a single block with .length zero and SU's to the desired blocklists with zero bit length.}

Binder operations which give rise to new blocks cause the block reference array to refer to those new blocks.

Ingest a text deck.
KALL(B,binder__ingest_deck{=4}) Keysfrom(text_deck_producer, error_message_consumer) Stringfrom(Char(t_name)) RCTO(rc) STRINGTO(/* receives 2 byte block count */);

text_deck_producer is a key that produces 80-byte records in the format that we believe to be a standard TEXT deck. It is read using QSAM, so any of the conventions in (p3,osfile) will work. The binder finishes with text_deck_producer before it returns.

Each executable control section {CSECT} of the text deck gives rise to a new .nascent blocklist with a single block. {But see below about Common.} These blocks have data parts which are .strings. The .locations of the blocklists have modulus 8 and address 0 {doubleword alignment}. The .length of the block is the length of the CSECT. {The length of the .string may be smaller.}

The name of the CSECT will be the name of the block, and any external entries give rise to other SD's.

A private code section {unnamed CSECT} gives rise to a block whose name is a .bound .symbol. {This .symbol is used in an SD for the CSECT and in SU's in the blocks from other sections from the text deck.}

Common control sections are handled according to the usual rules, viz.:
If the TEXT deck has a common control section and there is no block with that name, one is created, as for a CSECT, except the block's .string is of length 0, and the .length of the block is the length of the common control section. If there is already a block with that name, its .length will be increased if necessary to the length of the common section. The unnamed common section is considered to have the null string as a name.
Note that if a new block is created, it has a string data part. If you want a common control section to refer to a key or ref key block, the latter must be put into the binder before the deck with the common control section.

It is an error if a common control section calls for a change in the .length of a block which either has a successor or is in a blocklist that isn't .nascent.

If a CSECT is encountered and there is already a block with that name, if the block has a .string of length zero then it is assumed to be a common block and the CSECT is merged with it. Because there is no new block, the CSECT does not result in a block in the block array. If the block doesn't have a .string of length zero, the {second} CSECT is ignored and an error message is generated.

If a block is encountered more than once as a common block and/or CSECT, the block's .symbol-table will be from the first text deck that defined the block. {The block's .string will be from the first CSECT, if any.}

External dummy sections are handled according to the usual rules, viz.:
If there is more than one definition of an external dummy section, the external dummy section will be defined with the largest length and the most restrictive alignment.

It is an error if the TEXT deck requires a change to an external dummy section with an offset.

A new .symbol-table is formed whose name is t_name and whose string is the information from the SYM cards of the TEXT deck. The .starting-point is from the END card.
Design Note:
Some method is needed to cause a block's .symbol-table reference to be nil. This might depend on whether there are symbol tables within the ingested deck and also on whether the caller wants to keep the .symbol-table. It is not clear whether we should support non-nil references to empty .symbol-tables.

One possible strategy is the following variants on the "ingest deck" order code:

Create the .symbol-table only if there are SYM cards.

Don't create any .symbol-table.

Create the .symbol-table even if there are no SYM cards.

Another issue is that the caller may not be in a position to conveniently know what to name the .symbol-table. He might like to derive the name from information within the deck.

Yet another issue is whether we need .symbol-table names. Do they influence the behavior of binders in ways beyond that described in (stn)?

The block array is set to refer to the new blocks (in no particular order).

The return code rc is:

-1 if the binder is constant. No string is returned.

0 if there were no errors.

16 if t_name is already the name of a .symbol-table. Text_deck_producer and error_message_consumer are unused. The binder is unchanged and no string is returned.

17 if text_deck_producer couldn't be opened. The binder is unchanged and no string is returned.

18 if error_message_consumer couldn't be opened. The binder is unchanged and no string is returned.

19 if text_deck_producer indicated a PL/I transmit condition (I/O error) while being read.

20 if error_message_consumer indicated a PL/I transmit condition (I/O error) while being written.

Otherwise error messages in EBCDIC English are produced on error_message_consumer which can be any os sequential file, and rc is the severity of the most severe error:

Severity 1: The TEXT deck contained duplicate CSECT's which were ignored.

Severity 2: all errors not of severity 1 or 3.

Severity 3: An error in the format of the TEXT deck. The entire TEXT deck may not have been processed.

Note that if a text deck is ingested into an empty binder, no useful information from the text deck is lost, so the text deck is not needed after this operation. The exception is that the distinction between X and Y in the following example is lost (Y is supposed to be used only as the target of a branch):
EXTRN X DC A(X),V(Y)

Create blocklist with block with key data part.
KALL(B, binder__make_key_block{=14}) Stringfrom(s(2, log_modulus)) Keysfrom (K) Rcto(rc);

A new blocklist with a single block is created. Key K is the data part of the block. The length of the block is 2**log_modulus, as is the modulus of the blocklist. The address of the blocklist is 0 and the blocklist is .nascent. The block has no SD's (so you may want to use (binder-name-block)). The block array is set to contain the new block.

The return code rc is:

-1 if the binder is constant

0 if ok

1 if log_modulus is < 12 or > 48

Create blocklist with block with ref key data part.
KALL(B, binder__make_ref_key_block{=15}) Stringfrom(s(2, log_modulus)) Keysfrom (K) Rcto(rc);

Same as above, except the data part of the block is a new ref key whose initial value is K.

Set more bits of location.
KALL (B,binder__set_location{=5}) RCTO(rc)
STRINGFROM(S(2,log_modulus) ^^ S(6,address) ^^ blocklist_spec);

The modulus of the specified blocklist is increased to 2**log_modulus, and the address is set to address.

The return code rc is:

-1 if binder is constant

0 if ok, the change is made

1 if no such blocklist

2 if the new address is not less than the new modulus

3 if the difference between the old and new addresses is not a multiple of the old modulus

4 if the new modulus is smaller than the old

{The new address set is a subset of the old address set.}

Two blocklists in a binder may be concatenated.
KALL(B,binder__concat{=6}) RCTO(rc)
STRINGFROM(blocklist_spec_1 ^^ blocklist_spec_2);

The blocklists must both be .nascent.

The result is a .nascent blocklist consisting of the blocks of the first blocklist, perhaps followed by vacuous padding blocks, followed by the blocks of the second blocklist. At the conclusion of the operation the two input blocklists are not in the binder, but the resultant blocklist is.

The .location of the resultant blocklist and the .length of the padding blocks are chosen {uniquely} to ensure that nothing is added to the address sets of the blocks and the total .length of the padding blocks is minimized. To do this:

The modulus of the resultant blocklist is the maximum of the moduli of the input blocklists.

Vacuous padding blocks are created whose total length is just enough so as to make the distance between the beginnings of the old blocklists a multiple of the smaller of the moduli of the two blocks.

The address of the resultant blocklist is chosen {uniquely} to leave the effective address of the blocklist with the larger modulus unchanged.

The return code rc will be one of the following:
-1: binder is constant

0: all is well

1: blocklist_spec_1 cannot be resolved

2: blocklist_spec_2 cannot be resolved

3: blocklist 1 is not .nascent

4: blocklist 2 is not .nascent

5: blocklist_spec_1 specifies the same blocklist as blocklist_spec_2

Pad a blocklist
KALL(B,binder__pad{=7}) RCTO(rc) STRINGFROM(S(2,log_modulus) ^^ blocklist_spec);

Vacuous blocks {(vacu-block)} are concatenated to the beginning and end of a blocklist if necessary to make the addresses of the beginning and end of the blocklist be multiples of 2**log_modulus.

The modulus of the .location of the blocklist is increased if necessary to 2**log_modulus.

The blocklist must be .nascent.

Log_modulus must be at least 12. Values of 16, 20, etc. are also useful to facilitate sharing.

Return codes:

-1: binder is constant

0: all is well.

1: no such blocklist.

2: log_modulus is invalid.

3: blocklist is not .nascent.

Make a .nascent blocklist .loadable.
KALL(B,binder__make_loadable{=8}) RCTO(rc)
STRINGFROM(blocklist_spec) STRINGTO(sv);

The blocklist is padded (bspad) to a modulus of 2**12.

All the SU's of the blocklist must be satisfied {(susatisfied)}. They are applied. Any SU's which are satisfied only because they have "required" false {i.e., unresolved WXTRN's} are deleted.

Return codes:

-1: binder is constant

0: all is well. The blocklist is loadable.

1: no such blocklist.

2: blocklist isn't .nascent

3: there are unsatisfied SU's. Sv is set to up to 4094 bytes of information about the unsatisfied SU's as a sequence of items in the following format:

S(1,type) ^^ S(1,Length(name)) ^^ name

where if type is 0, there are one or more unsatisfied SU's whose .source is a .symbol whose string is name,

and if type is 1, there are one or more unsatisfied SU's whose .source is an external dummy section of name name.

Unsatisfied SU's whose .source is a .bound .symbol or a CXD are not reported.

Make a .loadable blocklist .gravid.
KALL(B,binder__make_gravid{=9}) RCTO(rc)
STRINGFROM(blocklist_spec);

For every block in the blocklist whose data part is a ref key, one less node may be used if the following conditions are met, where the .length of the block is 16**x and its address is y. Let z be y-Mod(y, 16**(x+1)). (bspad) can cause these conditions to be satisfied.