CERN Program Library Long Writeups Q100/Q101 Overview of the ZEBRA System MZ – Memory Management FZ – Sequential Input/Output RZ – Random-access Input/Output DZ – Debugging Tools DZDOC – Bank documentation tools TZ – Title Handling JZ91 – Processor Support Error Diagnostics CERN Geneva, Switzerland Copyright Notice CERN Program Library entries Q100 and Q101 The ZEBRA system ⃝c Copyright CERN, Geneva 1995 Copyright and any other appropriate legal protection of these computer programs and associated documentation reserved in all countries of the world. These programs or documentation may not be reproduced by any method without prior written con- sent of the Director-General of CERN or his delegate. Permission for the usage of any programs described herein is granted apriori to those scientific institutes associated with the CERN experimental program or with whom CERN has concluded a scientific collaboration agreement. Requests for information should be addressed to: CERN Program Library Office CERN-CN Division CH-1211 Geneva 23 Switzerland Tel. +41 22 767 4951 Fax. +41 22 767 8630 Internet: [email protected] Trademark notice: All trademarks appearing in this guide are acknowledged as such. Contact Persons: general Jamie Shiers /CN ([email protected]) : FZ, MZ, TZ, JZ91 Julius Zoll /ECP ([email protected]) : DZDOC Otto Schaile/PPE-Opal ([email protected]) Technical Realization: Michel Goossens /CN ([email protected]) Edition – February 1995 i Preliminary remarks This manual consists of several parts: • An overview of the ZEBRA system. • A reference section with a description of the DZ, MZ, FZ, JZ91, RZ and TZ packages. • An example program showing how to use the MZ and DZ routines of ZEBRA. • A description of the DZDOC documentation system. • A list of the diagnostics messages generated by the FZ and MZ parts of the ZEBRA system. Conventions In this manual examples are in monotype face and strings to be input by the user are underlined. In the index the page where a routine is defined is in bold, page numbers where a routine is referenced are in normal type. This manual flags output parameters in subroutine calls, i.e. parameters which return values tothe caller, by an asterisk "*" following the argument’s name. If the input value of such a parameter is also significant this is marked by prefixing a second asterisk. A parameter which is a link ismarkedbyan exclamation mark "!". The types of variables follow from the Fortran default typing convention, except that variables beginning with the letters ”ch” are of type CHARACTER. The Fortran labelled COMMON /QUEST/IQUEST(100) serves for communication between the Zebra sys- tem and the user, and also as scratch area in Zebra. This document has been produced using LATEX [1] with the cernman style option, developed at CERN. A gzipped compressed PostScript file zebra.ps.gz, containing a complete printable version of this man- ual, can be obtained by anonymous ftp as follows (commands to be typed by the user are underlined)1: ftp asisftp.cern.ch Trying 128.141.201.136... Connected to asis01.cern.ch. 220 asis01 FTP server (Version 6.10 ...) ready. Name (asis01:username): anonymous Password: your_mailaddress 230 Guest login ok, access restrictions apply. ftp> cd cernlib/doc/ps.dir ftp> binary ftp> get zebra.ps.gz ftp> quit 1If you do not have the gnu gunzip utility on your system you can get the uncompressed PostScript version by typing the command get zebra.ps, without the gz suffix. In order to save Internet bandwidth, you are, however, strongly urged totry and install the gunzip utility since gzipped files are about three times smaller than their unzipped equivalents. ii Table of Contents I An Introduction to the ZEBRA system 1 1 ZEBRA - An overview 2 1.1 Why ZEBRA? . .2 1.2 Logical Data Structures . .2 1.2.1 The bank . .2 1.2.2 The linear structure . .3 1.2.3 The general data structure . .4 1.2.4 Reverse links . .5 1.2.5 Reference links . .5 1.3 Physical Storage . .5 1.3.1 Divisions . .8 1.3.2 Link areas . .8 1.3.3 Working space . .8 1.4 Dropping banks and garbage collection . .9 1.5 Wiping divisions . 11 1.6 Input/Output . 11 1.7 Debugging problems . 12 1.7.1 The debugging and documentation package . 12 1.7.2 The user communication array IQUEST ...................... 12 1.8 Some conventions . 12 1.9 Summary . 12 II MZ – Memory Management 13 2 Memory management 14 2.1 ZEBRA bank format . 14 2.2 MZEBRA - initialize the ZEBRA system . 15 2.3 MZLOGL - change the MZ logging level . 17 2.4 MZSTOR - initialize a dynamic store . 18 2.5 MZDIV - create a new division . 21 2.6 MZLINK / MZLINT - initialize a link area . 23 2.7 MZWORK - allocate working space . 26 2.8 MZLIFT / MZBOOK - bank creation . 28 2.9 MZPUSH - alter the size of a bank . 32 2.10 MZREPL - connect replacement banks . 33 2.11 MZDROP - drop a bank and its dependents . 35 iii 2.12 MZWIPE - reset complete divisions to empty . 36 2.13 MZGARB - garbage collection requested by the user . 37 2.14 MZXREF - set cross-reference between divisions . 38 2.15 MZIXCO - create compound division index . 40 2.16 MZFORM et al. - handle the I/O characteristic . 41 3 Data structure utilities 49 3.1 MZFLAG et al. - logical walk through a data-structure . 49 3.2 LZHEAD - find the first bank of a linear structure . 51 3.3 ZSHUNT - change structural relation . 52 3.4 ZSORT - utility to sort the banks of a linear structure . 56 3.5 ZTOPSY et al. - utilities to operate on linear structures . 57 3.6 LZFIND et al. - utilities to interrogate linear structures . 58 3.7 LZFID et al. - utilities to find a bank by sequential scan . 59 4 Global operational aids 60 4.1 ZPHASE - set program phase . 60 4.2 ZEND - normal program end . 61 4.3 ZABEND - abnormal program end through ZFATAL . 61 4.4 ZTELL - recover trouble through ZTELL-ZTELUS . 62 4.5 ZVERIF - check logical integrity of Zebra stores . 65 4.6 ZVAUTO - running with automatic verification . 66 5 MZ routines for special applications 69 5.1 MZCOPY - copy a data-structure . 69 5.2 MZNEED - calculate free space in division . 71 5.3 MZINQS - inquiry to get the parameters of a store . 72 5.4 MZINQD - inquiry to get the parameters of a division . 74 5.5 MZDRED - reduce the space reserved to a division . 74 6 Internal technical details for ZEBRA MZ 75 6.1 Master Tables . 75 6.2 Relocation Tables . 79 6.3 MZFORM data structure . 84 III FZ – Sequential Input/Output 86 7 Principles 87 iv 8 User specifications for the FZ package 89 8.1 Representation of a data-structure . 89 8.2 Events, Runs, and Files . 89 8.3 Outline of usage for medium Disk or Tape . 90 8.4 FZFILE - initialize a ZEBRA file . 94 8.5 FZLOGL - change the logging level of a file . 100 8.6 FZMEMO - connect user memory area for medium Memory . 100 8.7 FZHOOK - connect user routine for medium Channel . 101 8.8 FZLIMI - limit the size of an output file . 101 8.9 FZODAT - storing and recovering the direct access table . 102 8.10 FZRUN - write a RUN record . 103 8.11 FZOUT - write one data-structure . 103 8.12 FZIN - read one data-structure . 106 8.13 FZIN - read one data-structure by segments . 109 8.14 FZINXT - reset the read point on a direct access file . 110 8.15 FZCOPY - copy one data-structure from input to output . 110 8.16 FZENDO - output file termination . 113 8.17 FZENDI - input file termination . 114 8.18 Usage for random access . 115 8.19 Usage for medium Memory . 117 8.20 Usage for medium Channel . 120 8.21 User marking of data-structures for FZOUT . 121 8.22 Suppress loading of unused parts of FZ . 122 8.23 FZ installation options . 123 9 Usage of FZ files in exchange mode 125 9.1 Exchange file format representation . 125 9.2 Tape file, Fortran . 125 9.3 Tape file, C Library . 129 9.4 Disk file, Fortran sequential . 129 9.5 Disk file, Fortran direct-access . ..