SLOAD Overview

SLOAD uses the Binder {(binder)} and normally shields the user from having to understand the Binder. The Binder, in turn, hides details of the Gnosis segment structure. SLOAD produces an "l-seg factory" which is an object specifically designed to serve as the .program of a factory which will produce objects obeying a program loaded by SLOAD.

SLOAD divides the CSECT's of your program into two kinds, namely those which will be writable and those which will be read-only. The objects produced by the factory will share pages holding the loaded CSECT's that are believed by SLOAD to be read only {code sections}.

Data loaded into a writable private section will even be shared until the program stores into that data, whereupon a really private page will be produced that is private to the domain that did the store.

At the moment the above is true, but SLOAD may soon allocate the pages when the segment is created, in some circumstances.

An important feature of the Gnosis segment structure supports mapping segments into your address space. If you have a memory key to a segment when you call SLOAD, the command "Define key block" (64 + n) may be used to cause that segment to be accessible to the loaded program. {"n" indicates the size of the segment. (kbsd)} If the key won't be available until after the program is running, the SLOAD command "Define ref key block" (128 + n) may be used to direct SLOAD to provide the running program with authority {(sac)} to place the memory key so that the segment will appear at an address accessible to the program. SLOAD chooses the address and conveys it to the program by the mechanism described at (bnd).
We haven't quite hidden the segment structure here because n must indicate a power of 16. Someday this may get better.

See (osload) about an extension of SLOAD to specifically support programs to run in the OS environment. See (p3,pliload) about an extension to support PL/I programs.

SLOAD supports DDT's knowledge of the Binder's symbol table conventions. See (symb-tab).

SLOAD will accept one or more TEXT decks and zero or more key or ref key blocks. All the code sections will be loaded read-only starting at zero. All the private sections will be loaded somewhat after that. The sections will be in no particular order.

The result is an l-segment factory {(lseg-fact)} which can be used as the .program of a factory. When the requestor's key is called, the new domain will have private read-write storage for the private sections.

The starting address of the program is taken from the first TEXT deck if possible.

The read-write storage is in the form of a VCSK segment, so you must store into it before using it to receive a parameter string.

When the new domain wants to destroy itself, it should use the procedure in (l-seg-destroy).

Be aware that currently binders cannot be explicitly destroyed.

The calling sequence is:

SLOAD(0;PSB,M,SB ==> c1;CO)
(An older calling sequence that is provided for compatibility only is: SLOAD(kt+5;PSB,M,SB ==> c1;,,,CO) )

Outcomes:

c1 = 0: CO is a key that can be called as follows.

c1 = 1 or 2: see (p3,fact-ret-codes)

c1 = 3: SB not an official space bank

c1 = 4: SB couldn't supply enough space

See (endsl) about another use of order code 0 to SLOAD.

In the following calls, CO is returned as the last key parameter only for compatibility with an older calling sequence.

CO(0,(deck_name);DECK,SYSP ==> c2;,,,CO1) "Ingest Deck"

DECK, SYSP, and deck_name are as in the operation binder__ingest {(ingest)}. {If deck_name is upper case EBCDIC, then deck_name;T to DDT will get the symbols from that deck.} SYSP can come from SYSPC {(sysp)}.

Outcomes:

c2 = 0: It worked. CO1 = CO.

c2 = 1, 2, 3, 16, 17, or 18: c2 is the return code from binder__ingest {(birc)}. CO1 = CO.

c2 = 5: deck_name has more than 55 characters. CO1 = CO.

c2 = 6: An implementation limit on the number of csects, key blocks, and locators was exceeded. CO becomes DK(0).

CO(64 + n, (2,lbn), (lbn,block_name); KEY ==> c3;,,,CO1) where (n=12 or n=16 or n=20) "Define key block"
A portion of virtual memory of size 2**n is allocated. Access to this portion results in a reference to memory key KEY.

Block_name will be defined as an external symbol equal to the address of the first byte of the portion.

The memory portion will be read/write or read-only according to the above convention about whether block_name ends in "1".

Outcomes:

c3 = 0: It worked. CO1 = CO.

c3 = 4: block_name is already defined. CO1 = CO.

c3 = 5: error in string, or block_name has more than 63 characters. CO1 = CO.

c3 = 6: as in "ingest deck" {(too-cs)}

See (matchn) about making block_name match up with PL/I external variables.

CO(128 + n, (2,lbn), (lbn,block_name), (2,lln), (lln,locator_name); KEY ==> c3;,,,CO1) where (n=12 or n=16 or n=20) "Define ref key block"
A portion of virtual memory of size 2**n is allocated. Access to this portion results in a reference to the memory key most recently stored in a certain slot. The slot holds KEY initially.

Block_name will be defined as an external symbol equal to the address of the first byte of the portion.

The memory portion will be read/write. Someday we may apply the above convention about whether block_name ends in "1".

Access to the slot is by means of a node key which is provided when the program first begins to run. This node is created after the factory requestor's key is called and before your program runs. Access to this node key is via your slot 15 as your program begins to run. The databyte of the node key is the index of the slot in the node. {See (p2,refkey) concerning logic of this key.}

Locator_name will be defined as an external symbol equal to the address of a halfword in read/write memory. (Someday we may apply the above convention about whether locator_name ends in "1".) The contents of the halfword tells where to find the above node key when the program starts, as follows:

-1: the key is in slot 15

i where 0 <= i <= 15: the key is in slot i of a node, a key to which is in slot 15.

Outcomes:
c3 = 0: The block is added. CO1 = CO.

c3 = 4: block_name is already defined. CO1 = CO.

c3 = 5: error in string, or block_name has more than 63 characters, or locator_name has more than 8 characters. CO1 = CO.

c3 = 6: as in "ingest deck"

c3 = 7: there are already 16 ref key blocks. CO1 = CO.

See (matchn) about making block_name match up with PL/I external variables.

CO(1; SYSP ==> c4,(str);LSF,BINDER,,CO1) "Finish loading"
SYSP will receive any error messages from certain binder__ingest operations. For example, if your locator_names are defined more than once, the message may come out here.

Outcomes:

c4 = 0: LSF is an l-segment {(lseg-fact)} factory. For convenience, BINDER is a key to the constant binder it came from. After this outcome, call CO(0; ==> 0;) to complete the calling sequence; it will return when the storage no longer needed has been returned to its bank. CO1 = CO.

c4 = 2: bank SB has insufficient space. No parameters are returned.

c4 = 3: There were unresolved symbols. str has the string returned from a binder__make_loadable operation {(make-loadable)}. No parameters are returned. After this outcome, call CO(0; ==> 0;) to complete the calling sequence; it will return when the storage no longer needed has been returned to its bank. CO1 = CO.

c4 = 4: No csects or key blocks were supplied. No parameters are returned.

c4 = 5: An error was reported to SYSP. No parameters are returned.

c4 = 8: The loaded output would take up more than 2**24 bytes. No parameters are returned.

c4 = 10: No TEXT deck was supplied. (One is needed to specify the starting point.) No parameters are returned.

CO(kt; ==> kt+2;)
{arcane}LOOSE END: --for now.

To delete the structures that are built in response to a call on the requestor's key the following must be done:
Restore slots 1, 4, 6, 14 and 15 to the keys they held when your program gained control.

In slot 2, place the key to whom a message should be sent when the deletion is complete.

Place the return code for the above message in R7.

Put 8 in R5 and 0 in R6.

Do "KC 14,13,,(,0)" and "KC 3,74,((=A(16),4),0)" where TS names some slot different from those above.

When the structure has been deleted a message with ordercode from R7 is sent to the key in slot 2.

The information in this plex is derived from sections (l-seg-destroy) and (getseg).