TZUSER - editing title banks during input

Sometimes it is inconvenient to have to prepare a given title on the input file in just the way in which it is expected by the program. Therefore TZINIT allows for a transformation of the data read, to be done by the user routine TZUSER at the level of individual titles.

This transformation by TZUSER is requested either globally for all titles by the control-line *USER (see section ) or individually for particular titles by giving option -U or -Un on the header line for the title bank. This causes TZINIT to transfer control to TZUSER as soon as the input of the data for the particular title is complete, and before starting to handle the next title.

Communication between TZINIT and TZUSER is as follows:

CALL TZUSER (!LOLD)

!LOLD

address of the original bank filled with the input data

      COMMON /TZUC/ JSTOR, IXTITL, NPARA, LNEW, NWOCC, NAME(20)

JSTOR

the number of the store = 0, 1, 2, ... currently being used, in case TZUSER has to cope with several structures,

IXTITL

the index of the title division for convenience,

NPARA

the value "n" from option -Un,zero if n not given,

LNEW*

adr of the replacement bank lifted by the user, if any,
initialized to zero by TZINIT;
-1: skip this title bank
-99: kill this run

*NWOCC*

number of useful words available in the bank at LOLD; this may be reduced or increased by TZUSER, but not above NAME(4). (TZINIT lifted the bank with NAME(4) words and has read NWOCC words into it.)

NAME

the ``namé' used by TZINIT to lift the bank at LOLD:

NAME(1)

Hollerith identifier

NAME(2/3)

NL / NS - number of links = 0

NAME(4)

ND - maximum number of data words

NAME(5->)

I/O characteristic

By programming TZUSER, the user may do one of four things:

1. change the information and the size of the original bank;
2. create a new bank to replace the old one;
3. simply suppress this title altogether by setting LNEW=-1;
4. kill the run by setting LNEW=-99.

Change the information

Modify the data as necessary, set NWOCC to the number of useful words in the bank if this has changed (without exceeding NAME(4)!), and return.

When control returns to TZINIT it will take the appropriate action according to the content of LNEW and maybe NWOCC.

Lift a replacement bank

To avoid problems in case of garbage collection, get the address of the original bank as follows:

      SUBROUTINE TZUSER (LPARA)
      DIMENSION    LPARA(9)
      LOLD = LPARA(1)

      CALL MZLIFT (IXTITL,LNEW,LPARA,0,NAME,-1)
      LOLD = LPARA(1)

TZINIT relies on the replacement bank having been linked as the ``next'' bank to the original.

Kill execution

If TZUSER discovers problems it can signal to TZINIT that the job should be killed by setting -99 into LNEW. TZINIT will still read to the end of the file to find other problems, maybe, and then call ZFATAL.

Loading TZUSER

As always with user routines called from a general library routine, there is the problem of getting the right TZUSER loaded. If it is sent through the compiler to the linker there is no problem. But if it is compiled and then put onto a user library one must force its loading from this library, either by loader directives, if available, or more simply by having a CALL TZUSER in one's MAIN program. In this latter case this must be a conditional call which will never be executed.

For the applications which do not need TZUSER there is a dummy version on the Zebra library. It will cause the job to fail in case it is reached by accident.