MZCOPY allows one to copy a data-structure from memory to memory.
The source memory may be
either (case 1) one or several divisions in some store F;
or (case 2) ordinary stand-alone memory,
called 'flat memory' below.
The target memory may be
either (case 3) one particular division in a store T, which may
or may not be the same as store F;
or (case 4) ordinary stand-alone memory.
For case 1, the data-structure may be identified in the usual way as the collection of banks which depend structurally from the header bank. This (option D not selected) requires a logical walk through the structure, marking each bank which belongs to it by setting a system bit in the status word. A sequential scan over the memory between the first and the last bank involved constructs then the table of the material to be copied. (This way of identifying the d/s must not be used with a read-only store.)
Alternatively, the d/s may be identified as the contents of one or several divisions, in which case the user has to be certain that the complete contents of this division(s) belong to one single d/s. This (option D selected) does not require the logical walk, and is by that much faster. Moreover, the copy may or may not be immediate (option I): if yes (option DI ) dead banks present in the division(s) are also copied, if not (option D without I ) a sequential scan over the division(s) concerned constructs a more detailed table of all the sectors of contiguous live banks in the division(s). Thus, if the user knows a priori that the amount of dead material is negligeable he should select option DI for speed, saving the sequential scan. However, if the amount of dead material is significant, he should select option D only, again for speed saving the time to copy the useless material.
Cases 2 and 4 (flat memory) are intendend for use in communication between separate processes running on the same computer through shareable Common blocks: the sending process places a d/s into a flat memory area, the receiving process copies it from there into its Zebra store. Again, the data must all belong to one single d/s.
If the No-link option is selected the copied result is a simple collection of banks, with all links except link 0 reset to zero, connected to be a linear structure; the entry address returned is the address of the physically first bank.
CALL MZCOPY (IXDVFR,!LENTRY, IXDVTO,*!LSUP*,JBIAS, chOPT)
with
IXDVFR: index of division(s) to be copied from
may be zero [or IXSTOR] if the D option is not selected
may be a compound index if the D option is selected
!LENTRY: entry address of the d/s
IXDVTO: index of the division to be copied to;
this must be the index of one particular division
The d/s copied is linked into a pre-existing d/s
as directed by LSUP and JBIAS, which have the same
significance as for MZLIFT:
!LSUP: if JBIAS < 1: LSUP is the supporting bank,
JBIAS: connection to link LQ(LSUP-JBIAS)
if JBIAS = 1: LSUP is the supporting link,
connection to LSUP (top-level d/s)
LSUP* returns the entry adr to the d/s
if JBIAS = 2: stand-alone d/s, no connection
LSUP* returns the entry adr to the d/s
chOPT: character string,
individual characters select options:
d/s: by default the d/s supported by the bank at
LENTRY is copied (link 0 not followed)
L copy the d/s supported by the linear structure
at LENTRY (link 0 followed)
M copy the banks pre-marked by the user,
see section{sec:MZFLAG} for details
(also: section~\ref{sec:FZmarking}, User marking ...)
D copy complete division(s)
default: dead banks are squeezed out
(slower but maybe more economic than DI)
DI immediate dump of division(s),
dead banks, if any, are also copied
S copy the single bank at LENTRY
see separate descriptions below for
F copy from flat memory
T copy to flat memory
others: N no links, ie. linkless handling,
default: links are significant
P permit error returns
default: error exit is with CALL ZTELL (15,1)
Z zero all links pointing outside the d/s
(this is implied if store T is not store F)
IQUEST(1) = NWFR: number of words
IQUEST(2) = JOFFFR: link relocation off-set, usually zero
CALL MZCOPY (MEMFR,!LENTRY, IXDVTO,*!LSUP*,JBIAS, chOPT)
with
MEMFR: the words MEMFR(1:NWFR) hold the d/s to be copied,
links in the d/s, if any, assume addressing such that
MEMFR(L) corresponds to LQ(L+JOFFFR)
In this case options L, D, I, S are irrelevant.
IQUEST(3) = NWMXTO: maximum # of words, ie. capacity of MEMTO
IQUEST(4) = JOFFTO: link relocation off-set, usually zero
CALL MZCOPY (IXDVFR,!LENTRY, MEMTO*,LENTO*,NWTO*, chOPT)
with
MEMTO*: the words MEMTO(1:NWTO) receive the d/s copied,
NWTO is not allowed to exceed NWMXTO,
links in the d/s, if any, will be relocated such that
MEMTO(L) corresponds to LQ(L+JOFFTO)
!LENTO* is the entry address into the copied d/s.
IQUEST(1/2) will signal on return the status of the copy:
= 0: all is well, IQUEST(2) = number of words
and if option P given:
= 1: LENTRY invalid
= 2: bank chaining clobbered found in the input d/s
= 3: not enough space to construct the relocation table
= 4: d/s larger than the target space
= 5: d/s to be copied is empty
= 6: bank chaining clobbered found in the copied d/s