MZSTOR - initialize a dynamic store

A call to MZSTOR is required to initialize the dynamic store before any operation using this store.

ZEBRA can handle up to 16 different dynamic stores. Each such store must reside in a Common block, not in a local vector. Each store must be intialized by calling MZSTOR once, and once only for this store. The first store initialized is the primary store, its store-index IXSTOR will be zero. Further secondary stores may be initialized, their IXSTOR will be allocated non-zero values by MZSTOR.

In the call to MZSTOR the user specifies the first and the last word of his dynamic store, he indicates the number and kinds of permanent links contained at the beginning of the store, and he communicates the Fortran name of the common block he is using for this store for printing purposes. A "fence" region of at least one word must be reserved preceding the store to allow catching errors due to using L=0.

MZSTOR initializes the store with 3 divisions: the forward "working space" division 1 followed by the reverse division 2, which is the default division in many instances, and the reverse "system" division at the end of the store.

For each secondary store, the system needs an area of about 400 words to hold the system tables for this store. This area is allocated by MZSTOR on the last words of the dynamic store itself.

The use of several dynamic stores introduces an execution time overhead proportional to the number of times that ZEBRA has to operate in a store other than the "current" one. All ZEBRA routines check on the current store being the right one; if not, a call to MZSDIV changes the "environment". A normal application uses only one store, the primary store. Apart from allowing to point from any data to any other, this also saves having to carry the store index, which is simply zero.

A given dynamic store is initialized by

CALL MZSTOR (IXSTOR*, chNAME, chOPT, FENCE, LQ(1), LQ(LR), LQ(LW), LQ(LIM2), LQ(LAST))

with

IXSTOR* returns the index of the store, to be used when specifying this store in
subsequent calls to the ZEBRA system.  The indices for the divisions 1 + 2
created by MZSTOR are: for division 1: IXDIV = IXSTOR + 1 2: IXDIV = IXSTOR + 2

              IXSTOR will be set to zero for the primary store.

      chNAME  name of the store for printing purposes,
              8 characters maximum

      chOPT  character string of options:

            log:      set log level to the default set up by MZEBRA
                   Q  quiet, set log level to -2

       FENCE  safety area immediately in front of the store to
              protect against illegal use of LQ(0), LQ(-1), etc.
              The fence extends from FENCE(1) to LQ(0).

       LQ(1)  first word of the dynamic store

      LQ(LR)  first permanent reference link, if any

      LQ(LW)  first word in the store after the permanent links,
              this is the first word available to the working space,
              or to division 1. The following words are allocated
              as permanent user links, if any:

                LQ(1)  to LQ(LR-1)  structural links, if any
                LQ(LR) to LQ(LW-1)   reference links, if any

    LQ(LIM2)  lowest position of the end of division 2,
              to protect divisions 1 and 2 from being squeezed out
              of existence by other divisions created later.

    LQ(LAST)  last word of the dynamic store.

Required:

  -  the fence must have one word at least, but at most 1000 words.
  -  the data region of the store (ie. the total store minus
     the permanent links) must not be less than 2000 words.

The store is allocated by MZSTOR as follows:

 _________________________________________________________________ _ _ _ _ 
|       |        permanent       | div |         | div | division |
| fence | structural | reference | 1   | reserve | 2   |  system  | 
|       |          links         | --> | area    | <-- |    <---- | [table]
|_______|____________|___________|_____|_________|_____|__________|_ _ _ _ 
|       |(1)         |(LR)       |(LW) |         |     |    (LAST)| 
 FENCE   LQ                                                       [or LAST]

The fence region is preset to contain IQNIL in every word, this must never be changed; the debug aids will check for over-writing. The permanent links are cleared to zero; the rest of the store is not touched.

The use of division 1 is somewhat special as explained in section for MZWORK.

Examples:

for a normal primary store:

      PARAMETER   (LIM2Q=40000)
      PARAMETER   (NNQ=120000)
      DIMENSION    LQ(NNQ), IQ(NNQ), Q(NNQ)
      EQUIVALENCE (LSAFE,LQ(1)), (Q(1),IQ(1),LQ(9))

      COMMON //    IXDIV1, ...            division indices
     +,            FENCE(16),LSAFE(10)    ten unused links for safety
     +,            LMAIN, ...             more structural links
     +,            L1, ...                more reference  links
     +,            DIV12(99)

      CALL MZSTOR (0,'//','.',FENCE,LQ,L1,DIV12,Q(LIM2Q),Q(NNQ))

for a secondary store without permanent links:

      DIMENSION    LZ(40000), IZ(40000), Z(40000)
      EQUIVALENCE (Z(1),IZ(1),LZ(9))

      COMMON /ZDYN/IXSTZ,IXDV1,IXDV2,IXHIT
     +,            FENDZ(16),LZ,LASTZ

      CALL MZSTOR (IXSTZ,'/ZDYN/','.',FENDZ,LZ,LZ,LZ,LZ(30000),LASTZ)
      IXDV1 = IXSTZ + 1
      IXDV2 = IXSTZ + 2

Note:

To ease the use of double-precision variables in the working space, the number of words in the fence, more generally: the number of words in the Common block preceding the dynamic store, as well as the number of permanent links, should be even.

MZSTOR prints at log level -1 or above an initialization message on unit IQLOG, showing the whereabouts and the sizes of the store.