MZBOOK and MZLIFT may cause garbage collection.
A bank may be lifted with either
CALL MZBOOK (IXDIV,!L*,!LSUP,JB, chID,NL,NS,ND,IOD,NZERO)
or
CALL MZLIFT (IXDIV,!L*,!LSUP,JB, NAME, NZERO)
with
IXDIV index of the division in which the bank is to be lifted
= 0 use default in primary store
[= IXSTOR use default in secondary store ]
see below for details
!L* returns the address of the bank created
!LSUP if JB < 0: address of the supporting up bank
if JB = 0: address of the supporting previous bank
if JB = 1: supporting link*
if JB = 2: LSUP not used
JB if JB < 1: link bias in the supporting bank
(must be a structural link)
if JB = 1: create top-level bank
if JB = 2: create stand-alone bank
NAME specifies the properties of the bank:
NAME(1) = ID: 4-character bank identifier, alphanumeric,
MZBOOK: variable of type CHARACTER
MZLIFT: Hollerith string of the form 4Hxxxx
(2) = NL: total number of links, NL < 64k
(3) = NS: number of structural links, NS <= NL
(not counting the 3 links next, up, origin)
(4) = ND: number of data words, ND < 1 Mwords
(5) = IOD: I/O descriptor for the data words, which may be:
- result from MZFORM, 1 word, I/O index
- result from MZIOBK, 1 or more words, I/O characteristic
- immediate, the whole bank is of the same type:
IOD = 0 undefined, bank cannot be transported
1 32-bit unsigned integer
2 signed integer
3 floating 4 double-precision
5 Hollerith 7 self-descriptive
- requests:
IOD = 9 retrieve I/O characteristic by IDH,
stored in the system by MZFORM
11 take the I/O characteristic from any
bank in the target linear structure,
if this is empty act as for 9
NZERO controls whether and how much of the data-part
of the bank is preset to zero:
N = -1: no presetting
N = 0: the whole bank is cleared
N > 0: the first N words are cleared
The links of the bank are always cleared to zero.
In what follows we will need the parameter LNEXT,
which is the address of the successor bank to the bank to be lifted;
its address will be stored into link 0 of the new bank,
ie. into its 'next' link.
LNEXT is obtained as follows:
if JB < 1: LNEXT = LQ(LSUP+JB)
JB = 1: LNEXT = LSUP
JB = 2: LNEXT = 0
The division [ and the store ] into which the bank
is to be lifted is selected by the parameter IXDIV.
If a definite division is specified, this is used,
but it must be compatible with LNEXT;
a linear structure must be contained within one and the same
division !
If 'default division' is specified, by giving zero [ or IXSTOR ] for IXDIV, the bank will be created in the division holding the logically nearest bank of the data structure into which the new bank will be inserted, in this order of priority:
LNEXT is non-zero, or if JB=0,
use the division holding this linear structure;
JB < 0 use the division holding the supporting up bank at LSUP;
The numeric bank identifier IDN serves to readily identify
a particular bank within a linear structure for interactive work.
Normally the Hollerith identifiers IDH in a linear structure are
all identical;
it is desirable that the IDN's are all different.
In principle the user can set any positive integer into IQ(L-5) after
the bank has been created, but MZLIFT/MZBOOK will store a default
value in this order of priority:
- if LNEXT is non-zero: use IDN+1 of the bank at LNEXT; - if JB = 0: use IDN+1 of the bank at LSUP; - if JB < 0: use the value IDN = -JB; - IDN = 1 will be set.
The bank being lifted is inserted into an existing data-structure according to LSUP under control of the parameter JB:
--- case 1: JB < 0 insert as dependent of the bank at LSUP
ex.: CALL MZLIFT (0,L,LSUP,-4,NAME,0)
_______
| |
__| SUP | <-------------------------.------ ...
| | | <---------. |
link | |_______| | |
JB= -4 | | |
| | |
| up | up |
| ________ ________
| | | | |
`---------------> | lift | ---> | NEXT | ---> ...
|________| |________|
SUP is the supporting bank whose address is LSUP
lift is the new bank being lifted
NEXT is the first bank of the linear structure in front of which
the bank 'lift' is inserted, ie. the initial content of
link JB in bank SUP was LNEXT = LQ(LSUP+JB).
The up-link and the origin-link in the bank lifted are set as
up-link <-- LSUP
origin-link <-- LSUP+JB
--- case 2: JB = 0 insert inside a linear structure
ex.: CALL MZLIFT (0,L,LSUP,0,NAME,0)
______
| |
__| UP | <------------------------------------------.---- ...
| | | <------------. |
| |______| | |
| |<-------------. |
| | | |
| up | up | up |
| ____ ________ ________ ________
| | | | | | | | |
`---> | | -...-> | SUP | --> | lift | --> | NEXT | --> ...
|____| |________| |________| |________|
The up-link and the origin-link in the bank lifted are set as
up-link <-- copy of the up-link in bank SUP
origin-link <-- LSUP
SUP, lift, NEXT have the same significance as in case 1.
UP is the bank pointed to by the up-link in bank SUP,
which link might be zero.
If bank NEXT does not exist, ie. if LNEXT = LQ(LSUP) is zero,
the bank 'lift' is added at the end of the linear structure.
--- case 3: JB = +1 create new top-level bank
ex.: CALL MZLIFT (0,L,LSUP,1,NAME,0)
usually: zero <------------------.
|
|
-------------->|
| |
up | up |
________ ________
| | | |
result LSUP and L ----> | lift | ---> | NEXT | ---> ...
|________| .--> |________|
|
input LSUP -----------------------^
For JB=+1 the origin-link and the up-link are taken from
the bank NEXT pointed to by LSUP on input;
the first time round, when NEXT does not exist,
ie. when LSUP=0,
the up-link is set to zero and the origin-link is made to point
to the location containing LSUP.
The location pointed to by the origin-link is filled with the address of the bank created, unless the origin-link is zero.
--- case 4: JB = +2 no inserting at all
ex.: CALL MZLIFT (0,L,0,2,NAME,0)
For JB=2 the bank is lifted without being linked into a structure;
both the origin-link and the up-link in the bank are set to zero.
because structural links are used to connect banks as illustrated by these examples, and are hence manipulated by the system, they must never contain anything but valid bank addresses, or zero.
MZLIFT and MZBOOK print a monitor log message at level 2.