next up previous contents index
Next: MZPUSH - alter Up: Memory management Previous: MZWORK - allocate

MZLIFT / MZBOOK - bank creation

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:

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.

Note:

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.



next up previous contents index
Next: MZPUSH - alter Up: Memory management Previous: MZWORK - allocate


Janne Saarela
Mon May 15 08:34:47 METDST 1995