To get a printout of this manual on the printer h01ps4 please issue the following command asa /h1/man/cat1/look.1 | a2ps -p -1 -ns -nL -nH -F8.4 -Ph01ps4 Interactive access to the manual: unix: man look WWW : LOOK home page : http://www-h1.desy.de/h1/iww/icas/imanuals/look/home.html (H1 Home Page -> Software -> Software Manuals -> LOOK) -> MANUAL OOOO OOOOO OOOOO OOOO OOO OOOO OOOOOOOOO OOOOOOOOO OOOO OOOO OOO OOOO OOOO OOOO OOOO OOO OOO OOO OOO OOO OOO OOO OOO OOO OOO OOO OOO OOO OOO OOOOOO OOO OOO OOO OOO OOO OOOOOO OOO OOO OOO OOO OOO OOO OOO OOO OOOO OOOO OOOO OOOO OOO OOO OOOOOOOOOO OOOOOOOOO OOOOOOOOO OOOO OOOOO OOOOOOOOOO OOOOO OOOOO OOOO OOOO LOOK - a system for data analysis Version 2.12/00 (C) V.B. 1990 04. Nov 1999 The Official Manual for the LOOK Kernel INTRODUCTION DISTRIBUTIONS EXECUTION OF INTERACTIVE PROGRAMS GUIDE TO USER GRAPHICS PROGRAMS APPENDIX 1 Author of the system: Volker Blobel (II. Institut fuer Experimentalphysik der Universitaet Hamburg) with contributions by: Sergey Levonian (Lebedev Physical Institute, Moscow) Ruten Gurin (Institute of Theor. and Exp. Physics, Moscow) and Ursula Berthon (Ecole Polytechnique LPNHE, Palaiseau) Alexander Fedotov (Institute of Theor. and Exp. Physics, Moscow) Ralf Gerhards (Deutsches Elektronensychrotron, DESY) Chris Jacobsson (Physics Department, Lund University) Morten Nyberg (Physics Department, Lund University) Thomas Naumann (Institut fuer Hochenergiephysik, Berlin-Zeuthen) Antoine Perus (LAL, Orsay) Zbigniew Szkutnik (University of Cracow) +------------------------------------------------------------+ | | | LOOK - a program system for data analysis | | | | Copyright Volker Blobel, Hamburg 1990 | | | | Copyright and any other appropriate legal protection | | of these computer programs and associated | | documentation reserved in all countries of the world. | | | | These programs may not be used or reproduced without | | prior consent of the author or his delegate. | | | | Permission for the usage of any programs described | | herein is granted a priori to those scientific | | institutes associated with the authors scientific | | program or with whom the author has concluded a | | scientific collaboration agreement. | | | +------------------------------------------------------------+ The Official source code of LOOK is managed with the advanced, interactive, fast, self-documenting, customizable and PATCHY compatible source code management system CMZ . Official source files reside under AFS in /afs/desy.de/group/h1/look . /h1/look/look.cmz -- Master CMZ file ======================================= This Manual is a part of it kept in the deck //LOOK/MANUAL/MANUAL H1 Work Group Servers ~~~~~~~~~~~~~~~~~~~~~ The INTERACTIVE LOOK executable module is invoked on H1 WGSs by typing look (except SUNs) (4 Mb internal LOOK data base) or by one of the commands look_XXmb , (any platform) where XX may be 04,16,... where this number specifies the size of LOOK data base in units of Mb . The LIBRARY (4Mb version only) is accessible via the link set in /h1/lib directory: liblook.a The names above correspond to a "production" version, while a "new" version is referred to via loooknew, looknew_XXmb (executables) , liblooknew.a (library) Type ls /h1/bin/look* to see the full list of executables (production/new, different versions,...). To see the list of LIBRARIES type ls /h1/bin/liblook*. 1 Review Pages - i - Contents ________________________________________________________________________ C O N T E N T S Page REVIEW PAGES . . . . . . . . . . . . . . . . . . . . . . . . . . i-x Contents . . . . . . . . . . . . . . . . . . . . . . . . i-ii What's new in the Manual . . . . . . . . . . . . . . . . iii-iv Index of Batch Routines . . . . . . . . . . . . . . . . . v-vi Index of Interactive Commands . . . . . . . . . . . . . . . vii-x INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Part 1 DISTRIBUTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introductory remarks . . . . . . . . . . . . . . . . . . . 3 2. Booking and filling . . . . . . . . . . . . . . . . . . . 5 2.1 Histograms . . . . . . . . . . . . . . . . . . . . 5 Statistical considerations . . . . . . . . . . . . 6 2.2 Vectors . . . . . . . . . . . . . . . . . . . . 7 3. Areas in the LOOK data base . . . . . . . . . . . . . . . . 9 4. Text and graphical representation . . . . . . . . . . . . . 10 Text . . . . . . . . . . . . . . . . . . . . . 10 Graphical representation . . . . . . . . . . . . . . 10 5. Printout on line printers . . . . . . . . . . . . . . . . . 13 6. Access to the data . . . . . . . . . . . . . . . . . . . 15 6.1 Steering parameters and statistical data . . . . . . 15 6.2 Content . . . . . . . . . . . . . . . . . . . . 16 (a) Histograms . . . . . . . . . . . . . . . . . . 16 (b) Vectors . . . . . . . . . . . . . . . . . . . 17 7. Global filling . . . . . . . . . . . . . . . . . . . . . 19 7.1 Purging (deleting) and resetting figures. . . . . . . 19 7.2 Global filling of histograms . . . . . . . . . . . . 20 7.3 Global filling of vectors . . . . . . . . . . . . . . 20 7.4 Copying figures . . . . . . . . . . . . . . . . . . 20 8. Other operations with figures. . . . . . . . . . . . . . . . 20a 8.1 Operations with histograms . . . . . . . . . . . . . 21 (1) normalisation (2) projection (3) arithmetics (4) integration (5) creation of profiles (6) rebinning (7) merging (8) peak finding 8.2 Target area . . . . . . . . . . . . . . . . . . . . . 22 8.3 Vectorisation of non-vector objects . . . . . . . . . 23 9. Fitting . . . . . . . . . . . . . . . . . . . . . 24 10. LOOK random number generator . . . . . . . . . . . . . . . 26 11. Input/output of distributions . . . . . . . . . . . . . . . 26 12. Memory and initialisation . . . . . . . . . . . . . . . . . 28 Part 2 EXECUTION OF INTERACTIVE PROGRAMS . . . . . . . . . . . . . . . . 30 1. Program structure . . . . . . . . . . . . . . . . . . . . . 30 2. Display modes . . . . . . . . . . . . . . . . . . . . . . . 31 3. Start of LOOK-programs . . . . . . . . . . . . . . . . . . 32 3.1 Central IBM (MVS) at DESY . . . . . . . . . . . . . . 32 3.2 Apollo workstations at DESY . . . . . . . . . . . . . 32 3.3 Work Group Servers at DESY . . . . . . . . . . . . . 33 4. Commands and keywords . . . . . . . . . . . . . . . . . . 34 4.1 Keyword steering . . . . . . . . . . . . . . . . . . 34 4.2 Keywords and their parameters . . . . . . . . . . . . 34 4.3 Keywords and actions . . . . . . . . . . . . . . . . 35 4.4 Complex commands with multiple keywords . . . . . . . 35 4.5 Multiple commands . . . . . . . . . . . . . . . . . 35 4.6 User-defined keywords . . . . . . . . . . . . . . . . 36 4.7 Continuation of command lines . . . . . . . . . . . . 36 4.8 Execution of command macro-files LOOK login macro . . . . . . . . . . . . . . . . . 36 1 Review Pages - ii - Contents ________________________________________________________________________ 5. Standard LOOK keywords . . . . . . . . . . . . . . . . . . 38 5.1 HELP commands . . . . . . . . . . . . . . . . . . . 38 5.2 Control commands . . . . . . . . . . . . . . . . . . 38 5.3 Display modes . . . . . . . . . . . . . . . . . . . 38 5.4 Keyword handling . . . . . . . . . . . . . . . . . . 41 5.5 Commands for text . . . . . . . . . . . . . . . . . . 41 5.6 Commands for graphics . . . . . . . . . . . . . . . . 42 5.7 Operations with histograms . . . . . . . . . . . . . 43 5.8 Area handling . . . . . . . . . . . . . . . . . . . 44 5.9a Deletion and resetting of LOOK objects . . . . . . . 45 5.9b Creation of new LOOK objects . . . . . . . . . . . . 45 5.10 N-tuples (Vectors) . . . . . . . . . . . . . . . . . 46 5.11 Files (Datasets) . . . . . . . . . . . . . . . . . . 48 5.12 Hardcopies . . . . . . . . . . . . . . . . . . . . . 48 5.13 Input/output operations . . . . . . . . . . . . . . 48 5.14 Display options . . . . . . . . . . . . . . . . . . 50 5.15 Inquiry functions . . . . . . . . . . . . . . . . . 51 5.16 BOS related commands . . . . . . . . . . . . . . . . 52 5.17 Commands for LOOK macros. Debugging macros . . . . . 53a 6. Interactive interpreter YY . . . . . . . . . . . . . . . . 54 6.1 DO command: creating new LOOK objects . . . . . . . . 54 6.2 DO command: using YY-conditions . . . . . . . . . . . 56 6.3 DO command: YY-macro facility . . . . . . . . . . . . 57 6.4 YY programs and LOAD command . . . . . . . . . . . . 58 6.5 LOOK extension of YY fortran. Equivalence of DO and LOAD . . . . . . . . . . . . . . . . . . 60 6.6 Interface between YY and standard FORTRAN . . . . . . 62 6.7 Fitting . . . . . . . . . . . . . . . . . . . . . . . 63 7. Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Part 3 GUIDE TO USER GRAPHICS PROGRAMS . . . . . . . . . . . . . . . . . 71 1. Principles of LOOK . . . . . . . . . . . . . . . . . . . . . 71 2. Keyword steering . . . . . . . . . . . . . . . . . . . . . 73 2.1 Definition of a keyword . . . . . . . . . . . . . . . 73 2.2 Test of the presence of a keyword . . . . . . . . . . 74 2.3 Parameters of a keyword . . . . . . . . . . . . . . . 74 3. Graphical displays . . . . . . . . . . . . . . . . . . . . 75 3.1 Display parameters . . . . . . . . . . . . . . . . . 75 a) Display style . . . . . . . . . . . . . . . . 75 b) Zone and subzone . . . . . . . . . . . . . . 76 c) Limits of world coordinates . . . . . . . . . 76 3.2 LOOK transformations . . . . . . . . . . . . . . . . 77 a.) Two-dimensional displays (2D) . . . . . . . . 78 b.) Three-dimensional displays (3D) . . . . . . . 78 3.3 Initialization of a display . . . . . . . . . . . . . 79 a.) Simplified initialization by one call . . . . 79 a'.) Simplified initialization using keyword . . . 79 b.) Initialization with detailed definition of display parameters . . . . . . . . . . . . . 80 1) Basic initialization and selection of display style . . . . . . . . . . . . . 80 2) Subdivision of the zone . . . . . . . . 80 3) Definition of limits in x, y (and z). . 82 4) Final call to initialization. . . . . . 82 3.4 The GKS drawing primitives . . . . . . . . . . . . . 82 1) Polylines . . . . . . . . . . . . . . . . . . 83 1a) Curves . . . . . . . . . . . . . . . . . . . 84 2) Polymarker. . . . . . . . . . . . . . . . . . 84 3) Text . . . . . . . . . . . . . . . . . . . . 84 4) Fill area . . . . . . . . . . . . . . . . . . 85 3.5 Text in the graphics display . . . . . . . . . . . . 85 4. Text displays . . . . . . . . . . . . . . . . . . . . . . . 86 5. Dialogue, messages and alerts . . . . . . . . . . . . . . . 87 6. Main program and memory size . . . . . . . . . . . . . . . . 88a APPENDIX . . . . . . . . . . . . . . . . . . . . . . . 89 1. Installation . . . . . . . . . . . . . . . . . . . . . . . . 89 2. Bank layout for distributions . . . . . . . . . . . . . . . 92 3. The LOOK command processor . . . . . . . . . . . . . . . . . 93 4. Creation of LOOK executable at DESY IBM . . . . . . . . . . 97 5. GKS and PS encodings for Greek letters . . . . . . . . . . . 98 6. PostScript output at DESY IBM . . . . . . . . . . . . . . . 99 1 Review Pages - iii - What's new in the Manual _______________________________________________________________________ What's new in the Manual ======================== 03.11.99 for vs 2.12/00 New keyword SHELL (alias SH). New unix-like, easier-to-memorize, aliases (for old keywords): MAN (HELP/H), Q (QQ), CP (COPYFG), CP1 (COPYDF), CPT (COPYTX), RM (PURGEF), RM1 (PURGDF), RMA (PURGALL), RMT (PURGET), LS (FIGURES/FS), LL (HISTOS). 11.05.98 for vs 2.11/00 New keywords GREEK,GKSCOR. Keyword USERFACT extended by 3 new parameters. Sect.4.8: looklogi.macro may be in HOME directory. Tables of Greek encodings updated (App.5). New routine KEYWG1V (App.3). 29.01.97 for vs 2.09/01 Batch routine INITLB to initialise LOOK memory; part1, sect."Memory and initialisation"; part3, sect."Main program and memory size"; part2, sect."Start of LOOK on WGSs at DESY". Deleted are obsolete contents sections in al parts, index of batch routines (pt2),keywd summary(pt2). 02.11.96 for vs 2.08/00 New stuff to operate with FIT TEXTS: batch routines LKFDPN,LKFTXT, commands FTEXTSTOR,FTEXTDRAW,PFTEXT,FPARNAME. Command and batch routine PURGET to clear texts. 19.06.96 for vs 2.07/00 Batch routines LKFITC,LKFTYC to fit correlated data; keyword COV for the FIT command; old commands in new sections "5.9a Deletion and resetting of LOOK objects", "5.17 Commands for LOOK macros. Debugging macros". 07.03.96 for vs 2.06/01 # function in yy (sect.6.5); batch routine VECDF for vectorisation; command NOTERASE; more subsections in sect.7,8 of Part 1 . 29.02.1996 for vs 2.06/00 The first release of Manual from dice2 and the first update since May 94. It has been reformatted (max of 85 lines per page), a lot of cosmetic changes, like more blank lines etc., made in order to make it more readable and printable; the increased number of pages -- from 81 to 99 -- reflects mostly this reformatting and to much less extent -- an increase of the content. The YY section split into more subsections. A "Review Pages" have been added in the beginning (pp.i-x), which contain (a) a more detailed, than earlier, table of content, (b) this "What's new in the Manual" section you are reading now, for news about the manual, (c) Index of batch routines -- a copy of the old one buried somewhere inside the Manual, (d) a new Index of Interactive Commands. The goal of placing all this stuff together in the beginning is to facilitate a quicker/easier reference to any subject of interest. New material: - new commands HELPFILE,FONT2,FONTSCAL,SHOWFONT,MESSAGES and extended FONT; - new batch routines LSTORB,SVEC02,SVEC04,SVEC06; - yy: C_() functions, *#MACRO ; - LOOK login macro ; - changes in GRLNCL,GRTEXT, calls to FNT2LD,FNT2RM (txts in gr.display) 1 Review Pages - iv - What's new in the Manual _______________________________________________________________________ 1 Review Pages - v - Index of Batch Routines _______________________________________________________________________ Index of Batch Routines ======================= page CALL AHDATA(DATYPE,IFG,INR,IDAT,NR,ARRAY)......fill hist globally 20 CALL AHNENT(DATYPE,IFG,INR,NENTS).........add to the hist entries 20 CALL AHSTAT(DATYPE,IFG,INR,NENT,SW,RNEFF,XSTAT,YSTAT)...add stat. 20 CALL AVDATA(DATYPE,IFG,INR,NR,ARRAY).........append to the vector 20 CALL BHD (IFG,INR,NX,XA,XB,NY,YA,YB)......book 2d unweighted hist 5 CALL BHDW(IFG,INR,NX,XA,XB,NY,YA,YB)........book 2d weighted hist 6 CALL BHS (IFG,INR,NX,XA,XB)..........book 1d unweighted histogram 5 CALL BHSW(IFG,INR,NX,XA,XB)............book 1d weighted histogram 5 CALL BNT (IFG,INR,NVEC,NAMES)........................book n-tuple 7 CALL BVEC(IFG,INR,NVEC)...............................book vector 7 XC = CENTIN(I,N,A,B)............................return bin center 15 CALL COPYDF(IFG1,INR1,IFG2,INR2,IER)...............copy subfigure 20a CALL COPYFG(IFG1,IFG2,IER)...................copy complete figure 20a CALL COPYTX(IFG1,IFG2)...........................copy figure text 20a CALL DTAREA ..................................disable target area 23 CALL FDATA(DATYPE,IFG,INR,ID,NR,ARRAY,NDIM).....get data after ID 18 CALL GATTR(DATYPE,IFG,INR,NCH,ATTRIB)..............get attributes 12 CALL GDATA(DATYPE,IFG,INR,NR,ARRAY,NDIM)............get next data 18 CALL GHBINS(DATYPE,IFG,INR,NX,XA,XB,NY,YA,YB)....get booking par. 15 CALL GHNENT(DATYPE,IFG,INR,NENTS)...........get number of entries 16 CALL GHSTAT(DATYPE,IFG,INR,NENT,SW,RNEFF,XSTAT,YSTAT)...get stat. 15 CALL GPARM(DATYPE,IFG,INR,NVEC,NENT,NWORDS).....get steering par. 15 CALL GTEXT(IFG,IPOS,NCH,TEXT).....................get figure text 10 CALL HAVER(IP,IFG1,INR1,IFG2,INR2,IERR)..........produce profiles 22 CALL HISUM(IT,IFGI,INRI,IFGO,INRO,IERR).................integrate 21 CALL HNORM(INORM,SCALE,IFG1,INR1,IFG2,INR2,IERR)........normalize 21 CALL HOPER(IOP,A,IFG1,INR1,B,IFG2,INR2,IFG3,INR3,IERR)....operate 21 CALL HPEAK (DATYPE,IFG,INR,NP,RP).........find peaks in histogram 22 CALL HPROJ(IP,IFG1,INR1,IFG2,INR2,ILOW,IHIG,IERR).........project 21 CALL INITLB(NWLOOK)........initialise memory with size > default 28,88a CALL LCOPYF (NAMINP,NAMOUT)...............copy complete LOOK file 27 FLAG=LEXIST (DATYPE,IFG,INR)....check the existence of the figure 15 CALL LKFDPN(IPAR,'nam_1 ... nam_n') (re)define names of fit param 24b CALL LKFGET (IFLAG,S,NP,NPAR,PTIT,EFIT,CFIT).......get fit result 24b CALL LKFIT (NEXT,IFG,INR,ITG,XMIN,XMAX,UFUNC,NPAR,IERR).......fit 24 CALL LKFITC (NEXT,IFG,INR,ITG,XMIN,XMAX,UFUNC,NPAR, IFGC,INRC,C,IGNCOR,IERR)...........fit correlated data 24a CALL LKFITM (MODE,NIT,EPS,NPTF)..........select fitting algorithm 24 CALL LKFITP .....................................print fit result 24b CALL LKFITY (IFG,INR,ITG,XMIN,XMAX,TEXT,IERR)........standard fit 24 CALL LKFPAR (NPAR,PAR,PMIN,PMAX,IERR)..........set initial values 24b CALL LKFTXT .................store the last fit results as a text 24b CALL LKFTYC (IFG,INR,ITG,XMIN,XMAX,TEXT,IFGC,INRC,C,IGNCOR,IERR) ...standard fit of correlated data 24a CALL LOCKAR(ARNAME,IVERS,KEY)....lock/unlock output of given area 9 CALL LPEAKS(IFGA,IFGB)................print peak analysis results 13 CALL LREAD (DANAME,MODA,MODC,IER).......read data from input file 26 CALL LSTORB (LUN,MODA).for BOS users:write figures on output file 26 CALL LSTORE (LUN,DSNAME,MODA)........write figures on output file 26 CALL LTITLE (TITLE)............define global title for blank area 10 CALL MERGEF(IFG1,INR1,IFG2,INR2,IERR)........merge two subfigures 22 CALL NEXTDF(DATYPE,IFG,INR).....get pointers to the next data set 15 CALL PRNDEX ..........................................print index 13 CALL PRNTAF .......................print all figures in all areas 13 CALL PRNTF(IFGA,IFGB)...............................print figures 13 CALL PURGDF(DATYPE,IFG,INR).................purge single data set 19 CALL PURGEF(IFG)..................................purge figure(s) 19 CALL PURGET(IFG,IPOS)................reset fig. text(s) to blanks 19 CALL QAREA(ARNAME,IVERS)............get current area name/version 9 CALL QQAREA(I,ARNAME,IVERS)............get I-th area name/version 9 CALL REBINH(IFG1,INR1,IFG2,INR2,NBX,NX0,NBY,NY0,IERR).......rebin 22 CALL RESETD(DATYPE,IFG,INR).................reset single data set 19 CALL RESETF(IFG)..................................reset figure(s) 19 CALL RETAR ...........................return to the previous area 9 R = RNLOOK(IDUM)...........generate random number in (0,1) range 26 CALL RWDATA(DATYPE,IFG,INR).........................reset pointer 18 CALL SAREA(ARNAME,IVERS)...................switch to another area 9 CALL SATTR(DATYPE,IFG,INR,ATTRIB).......set attributes for figure 12 1 Review Pages - vi - Index of batch routines _______________________________________________________________________ CALL SETDAT(DATYPE,ATTRIB).................set default attributes 12 CALL SETPRP(LUNP,MPR)......................set printer parameters 13 CALL SHD (IFG,INR,X,Y).....................fill 2d unweigted hist 5 CALL SHDW(IFG,INR,X,Y,W)....................fill 2d weighted hist 6 CALL SHS (IFG,INR,X).................fill 1d unweighted histogram 5 CALL SHSW(IFG,INR,X,W).................fill 1d weighted histogram 5 CALL STEXT(IFG,IPOS,TEXT).........................set figure text 10 CALL SVEC(IFG,INR,ARRAY)......................fill vector/n-tuple 7 CALL SVEC02(IFG,INR,X,Y)..........alternative filling of 2-vector 8 CALL SVEC04(IFG,INR,X,Y,DX,DY)....alternative filling of 4-vector 8 CALL SVEC06(IFG,INR,X,Y,DXLOW,DXHIG,DYLOW,DYHIG) fill 6-vector 8 CALL SXY (IFG,INR,X,Y)........................fill XY scatterplot 7 CALL SXYZ(IFG,INR,X,Y,Z).....................fill XYZ scatterplot 7 CALL TAREA (ARNAME,IVERS).....................specify target area 22 CALL VECDF(IFG1,INR1,IFG2,INR2,IERR)...........vectorise a figure 23 1 Review Pages - vii - Index of Interactive Commands _______________________________________________________________________ Index of Interactive Commands ============================= Keywords in alphabetical order (without BOS related ones) Page ? 'item' show all keywords started with ITEM 38 ?? 'item' show list of all keywords containing ITEM 38 @ add new graphical objects to existing zone 42 ADDAREA add data from input file to the existing ar. 44,49 ALIAS define alias of a kwd: newkwd alias oldkwd 41 AREAS show table of existing areas 44,51 ARP aspect ratio preserved for act. gr. cmd 43 AS alias of AUTOSCAL 42 ASQUARE the rest from the largest possible square zone 43 ATEXT 'text' add any text line to the graphics screen 41a AUTOSCAL automatical definition of x and y scales 42 BGRCOL switch background color between black and white 38 BINS nx xa xb ny ya yb define binning for new histograms 45 BREAK break command, equivalent to "break" key 32 CLEAR clears the screen - COMPARE 'area' vers compare figures in given area with current area 44 CONT force contour plot mode for all 2-dim histos 50 COV ifc inc [igncor] define data covariance matrix for FIT command 63 CONTOUR levels 'col' set parameters for contour plots representation 50 COPYDF if in jf jn copy data set (if,in) into new one (jf,jn) 45a COPYFG ifg jfg copy a complete figure ifg into a new one: jfg 45a COPYTX ifg jfg copy all figure texts from ifg to jfg 41a CP alias of COPYFG 45a CP1 alias of COPYDF 45a CPT alias of COPYTX 41a CUT ic1 ic2 ... apply cuts in OR (for n-tuples) 47 CUT* ic1 ic2 ... apply cuts in AND (for n-tuples) 47 CUTS show all defined cuts 51,47 DATA num data fill look obj. with data read from keyboard 45a DATASET unit open/close data set 48 DATASETS overview over existing data sets 51,48 DATASETX lun type st 'name' open/close dataset without dialogue 48 DEFATT show current table of default gr. attributes 51 DD alias of DATASET 48 DO 'expression' execute expression using interact. interpreter 51 DOWN lower half of screen (see ZONE) 43 DNTCUT display definition of act. cut in separate zone 47 DROP keyword drop keyword (only possible for private kwrds) 41 DZOOM zoom on two figures (with locator input) 42 EDIT enter text editor (not yet implemented) - END stop LOOK (alias STOP). In a macro,terminate macro EVDIR lin lut 'text' create ev.directory (lin -> lut) acc. to 'text' 49 EXEC 'name' execute commands from 'name' macro file 37 F alias of FIGURE 42 FF plot next figures 42 FIGURE fig ... plot figures 42 FIGURES ifg0 n show table of figures 51 FILLSOME ncount fill some histograms with something - FIT ifg inr ...'fun' fit figure (IFG,INR) by the function FUN 63 FITPAR m ifg inr set init. values (and limits) for the fit param.63 FONT ifn_t ipr_t ifn_hc ipr_hc set main fonts for term. and hardcopy 39 FONT2 ifn_t ipr_t ifn_hc ipr_hc set aux. fonts for term. and hardcp 39 FONTSCAL F1_t F1_hc F2_t F2_hcp change sizes of main and aux. fonts39 FPARM 'statement' execute FPACK statement (e.g. OPEN, CLOSE etc.) 48 FPARNAME ipar 'name ...' define name(s) of fit parameter(s) 64 FRAME switch frame box around figures on/off (toggle) 40 FS alias FIGURES 51 FTEXT3 'text' reset default text for all figs in a pos. 3 ... 40 FTEXTDRAW 1/0 switch on/off graphic display of fit results 40a FTEXTSTOR 1/0 switch on/off storing fit results for graphics 64 FUN ifg inr xmin xmax 'f' create vector (IFG,INR) from the funct 'f 64 1 Review Pages - viii - Index of Interactive Commands _______________________________________________________________________ GKSCOR i1-i7 correct for drawbacks of DESY GKS installation 40a GR alias of GRAPHIC 38 GRAPHIC reshow last graphics display 38 GREEK 1/2 specifies GKS/PS encoding for Greek letters 40a GRID igx igy add grid to actually displayed figures 50 GRWC xa xb ya yb initialize graphics display 2D (see Part 3) 79 GRWC3 xa xb ya yb za zb initialize graphics display 3D (see P.3) 79 H alias for HELP 38,52 H1 x0 y0 size mode...add H1 logo to figures at given position - HBIN nx ix0 ny iy0 define parameters for histogram rebinning 44 HD ifg inr create new 2d unweighted histogram interact-ly 45 HDW ifg inr create new 2d weighted histogram interact-ly 45 HEADER switch on/off graphics header box 40 HELP keyword ... request for help info for given keyword(s) 38 HELPFILE 'filename' set the name of the file for the on-line help 38 HISTOS ifg0 n show list of general histogram information 51 HS ifg inr create new 1d unweighted histogram interact-ly 45 HSW ifg inr create new 1d weighted histogram interact-ly 45 INTEG integrate histogram (see detailed description) 44 KEEPAREA ignore area name/version from input file 44 KEYWORDS show table of keywords 38,51 KS alias of KEYWORDS 38,51 LEFT left half of screen (see ZONE) 43 LEGEND switch figure legend on/off (toggle type) 65 LEGO ilego iscale define parameters for legoplots representation 50 LISTF ifg inr list figure statistics, texts and attributes 51 LL alias of HISTOS 51 LOAD 'file' read and compile fortran program from the file 57 LOADFIGS ifg1 ... select figures to be loaded from input file 49 LOADROWS mrow set max number of rows per n-tuple to be loaded 49 LOCK keyword ... lock keyword(s) 41 LOOP nloops execute user defined command(s) nloops times 41 LOGO display LOOK logo with the current LOOK version - LOGX ipos1...iposN use log scale x-axis for figs at given posit. 51 LOGY ipos1...iposN use log scale y-axis for figs at given posit. 51 LREAD unit read and fill one LOOK area from input unit 48 LRALL unit read and fill all LOOK areas from input unit 48 LRNEXT unit read and show key of the next LOOK record 48 LREWIND unit rewind input unit 48 LS alias of FIGURES / FS 51 LTITLE ift 'title' define global title for blank area 50 LUTPUT unit alias of LWRITE 49 LWRITE unit write distributions from curr. area to data set 49 LWRALL unit write all LOOK areas to the output file 49 MAN alias of HELP / H 38,52 MANUAL show H1 graphics Manual (return to LOOK by EXIT)38 MEMORY show LOOK data base memory status 52 MESS alias of MESSAGE 53a MESSAGE nl 'text' show nl-line message text on the screen 53a MESSAGES ileft irght switch for l/r mess. duplication in cmd window 40 MERGEF if in jf jn add content of a figure (jf,jn) to the (if,in) 45a MZOOM zoom on many figures (with locator input) 42 N alias of NEWLIB 38 NEWLIB command execute NEWLIB command (return by EXIT or QUIT) 38 NOCLEAR no clear of display after command input - NOGRID force LEGN mode for all legoplots in act. cmd 50 NORM normalize histogram (see detailed description) 43 NOROUND ix iy iz suppress rounding of the x, y or z scales 51 NOTERASE 1/0 protect graphic window from erasure (on/off) 40a NOZOOM suppress zoom 42 NT ifg inr nev nskp 'list' process n-tuple ifg inr 46,47 NTBINS nx set autobinning for NT command 47 NTNAME ifg icl 'name' assign new name to the column icl of Ntuple ifg47 NTPLOT switch n-tuple plotting option on/off (toggle) 47 NTSCAN ifg inr nev nskp 'list' scan over n-tuple and show table 47 NTSHOW ifg inr show definition table of n-tuple 1 Review Pages - ix - Index of Interactive Commands _______________________________________________________________________ O alias of ZOOM 42 OO alias of DZOOM 42 OOO alias of MZOOM 42 OPERATE operations on histograms(see det. description) 43 OPTIONS show current status of LOOK toggle options 52 OVERLAY ifg inr define master fig. to be overlaied with others 42 PAUSE make a pause and wait until user hits enter 53a PEAKPARM switch peak parameter determination on/off 50 PEAKS ifg ... show resulting table of peak anal.for 1-d hist 51 PFTEXT x y size mode define position/size of fit results inside figs41a PL alias of PLOTTER 48 PLAN select plane projection instead of rotated view - PLOTTER num output to plotter with given number 48 PLOTTERS overview over hardcopy devices 52,48 PROFILE create profile figures from 2-dim histogram 43 PP alias of PEAKPARM 50 PROJECT projection of 2d-hist (see detailed description)43 PTEXT x y size mode define position and size for texts inside figs 41 PURGALL purge all figures in all existing areas 45 PURGDF ifg inr purge sub-figure 45 PURGEF ifg purge figure (all for ifg=0) 45 PURGET ifg ipos purge text(s) associated with a figure 41a PUTFIT ifg inr store fit results in the vector (IFG,INR) 63 QAREA get curr. area/version # of LOOK data base 44,52 Q alias of QQ 38 QQ quick quit (immediate stop) 38 QUIT stop of program (alias of STOP) REBIN if in jf jn rebin histo using parameters from HBIN keyword 44 RESETF ifg reset figure(clear content,keep booking), 0-all 45 RETAR return to the previous area of LOOK data base 44 RETURN lretc return from LOOK with return code = iabs(lretc) 38 RIGHT right half of screen (see ZONE) 43 RM alias of PURGEF 45 RM1 alias of PURGDF 45 RMA alias of PURGALL 45 RMT alias of PURGET 41a ROT specify rotation angle with "rubberbund" from 0,0 ROTATE dphi ddip modify VIEW parameters 43 SAREA 'area' vers select area of LOOK data base 44 SATTR 'dtyp' ifg inr set attribute for figure ifg/inr 50 SCALES iscale set scales type for actual command 43 SCUT ic 'definition' set (define) new cut for n-tuple applications 47 SECNUM list display only fig. with sec. # given in list 42 SETDAT 'dtyp' reset default attributes for all 'dtyp' objects 50 SETFIT m nit eps npf select fitting method and set global parameters 62 SH alias of SHELL 38 SHEADR ilr 'text' set text for header box 41 SHELL cmd execute a shell command or invoke shell prompt 38 SHOWFIT show last fit results on the text screen 64 SHOWFONT 'text' ... display the text with specified fonts 40 SIZE xcm ycm x0 y0 define actual size of the plotted picture 48 SMOOTH switch smoothing procedure for 1-d hist on/off 50 ST alias STATPARM 50 STATPARM switch output of statistics in figures on/off 50 STEXT ifg pos 'text' set figure text for the position pos 41 STOP stop of program (return code = 0) 38 SQUARE the largest possible square zone 43 SX xa xb lx define scale xa...xb lx=0 linear; lx=1 logar. 42 SY ya yb ly define scale ya...yb ly=0 linear; ly=1 logar. 42 SZ za zb lz define scale za...zb lz=0 linear; lz=1 logar. 42 TAREA 'area' vers define target area for histogram operations 44 TEXT reshow last Text display 38 TO 'attribute' new figure attribute 50 TOVEC if in vf vn vectorize single data set(convert into VEC typ)45a TX alias of TEXT 38 TXPRINT num print part of the txt screen on plotter/term 48 TUTOR tutorial for beginners 1 Review Pages - x - Index of Interactive Commands _______________________________________________________________________ UNLOCK keyword unlock keyword(s) 41 UP upper half of screen (see ZONE) 43 USERFACT f1 ... f12 factors defining fugure environment (see 5.13) 51 VEC ifg inr ndim create new vector data interactively 45 VIEW iaxis phi dip proji definition of 3D viewing parameters 42 WC xa xb ya yb [za zb] set world coord. limits for 2D [3D] screen 76 WITH ifg inr ... define list of figs to overlay with master one 42 XY ifg inr create new scatter plot interactively 45 XYZ ifg inr create new 3-dimensional scatter plot 45 YYCUT 'condition' apply complex cut in NT/NTSCAN fore YY 47 ZONE xa xb ya yb define graphics zone in 0/1 coordinates 43,65 ZOOM zoom on one figure (with locator input) 42 0 show previous (99) commands 38 -1 ... -99 get previous command 38 Internal keywords (for experts = LOOK authors only) --------------------------------------------------- DUMPCUTS show content of n-tuple cut banks on the screen GRIOFN widtht wt definition of GRIOFN parameters MOUSE request a locator position in world coordinates NXFG define next figure numbers (used in FF command) ONEPT enter one (x,y) point from screen TEXTPARM hch gap stt define text parameters for terminal workstation TPRINT ncol read and print text from unit 12 (ncol = 72 or 80) TWOPC enter two (x,y) points from screen TWOPT the same as before, but with intermediate prompt 1 - 1 - Introduction _______________________________________________________________________ INTRODUCTION ************ LOOK is a general system for graphics applications in physics. The standard version is written in FORTRAN 77; it uses GKS functions at a low level for the basic graphical operations. FPACK is the only further library necessary for LOOK. Portability of code to different computer types is one of the basic principles followed in the design of the system. No machine-dependent extensions of FORTRAN77 have been used. The system is running at present on IBM (main frames), VAX, APOLLO, SGI, ALLIANT, SUN, IBM R6000, DEC workstations, X-window HP stations, MIPS and MacII systems. All necessary machine dependent code (for example differences in OPEN statements, logical functions) are kept within macros in the source file. Special machine dependent code is used in specialized versions for some work stations in order to make use of their special options. A Motif interface is implemented for the X-window Unix systems using OnX package and emulating all necessary GKS functions by X-window primitives. LOOK has been designed as an open system, extendible in a simple way by specialized user-written graphical programs. It may be considered as a kernel system, as a program layer between the low level graphics (GKS or similar) and user display programs, and it provides a system of utility subprograms, which allows the user to write his *) own display program with a minimum amount of work. In particular it requires that the user learn only the so-called drawing primitives, which he can use in his display program. The user as a writer of display programs does not have to consider the opening of workstations, transformations, hardcopy devices etc; all this is covered by LOOK. One important area of application of a graphics program for the analysis of data is the area of distributions. LOOK includes a fast data base for distributions. Distributions may be binned (histograms) or unbinned (vector or n-tuple data). It also contains the interactive program parts for the display of data from the data base. Operations on histograms, fast peak finding together with more sophisticated analysis possible with the interactive LOOK interpreter, including fitting of functions to the data, makes the system a powerful tool for the data analysis. An essential part of LOOK is the command processor; this allows the execution of a collection of display subroutines which can be developed independently, together with LOOK, without the necessity to modify or recompile the LOOK system. The system allows the user to add, eventually in one subroutine, all the necessary instructions for a special display including the addition of new user commands for the interactive steering. The structure of LOOK is shown in the figure below: there can be a series of display subroutines, connected in a modular way to the LOOK kernel. One of these display subroutines is included in the standard LOOK for the display of distributions from the data base. +------------------------------------------------------+ | | | LOOK kernel (based on GKS) | | | +------------------------------------------------------+ | | | V V V | | | +-----------+ +-----------+ +-----------+ | Standard | | | | | | LOOK | | User displays | ...... | displays | | | | | +-----------+ +-----------+ +-----------+ ------------------------------- *) He/his can be replaced freely throughout the document by she/her. 1 - 2 - Introduction _______________________________________________________________________ This manual is organized in three parts. For most applications only one or two parts have to be read. In part 1 all functions of the data base for distributions are explained. Distributions may be binned (histograms) or unbinned (vectors or n-tuples). Using LOOK-subprograms, data for distributions can be stored in the data base and retrieved from the data base, either in interactive programs or in batch programs. Distributions from the data base can be printed on line printers or copied to files, which can later be copied back to the LOOK data base. In part 2 the standard functions available to the operator in interactive LOOK programs are explained. The general rules for commands, valid for all interactive LOOK programs, are discussed in detail, together with concepts like zones, zooming etc. New commands can be defined interactively by combining existing commands. In addition all commands for data from the LOOK data base, like display of histograms and curves, are explained. In part 3 the rules for writing interactive LOOK programs are described. The knowledge of part 2 is necessary for the understanding of this part. Concepts for the display modes, and the hierarchy of conditions, which define the graphical parameters, are introduced. The description also covers all those GKS functions that are essential for the program writing. Knowledge of the GKS functions, which are not described, is not required. 1 Part 1 - 3 - 1. Introductory remarks _______________________________________________________________________ Part 1 DISTRIBUTIONS ********************** Histograms and Vectors 1. Introductory remarks ======================= The LOOK system supports a data base for the data management for two types of distributions for statistical data analysis: > histograms (binned distributions) > vectors (unbinned distributions) A histogram, which may be one- or two-dimensional, has a certain fixed number of bins. Entries in a histogram are collected by adding all weights of entries for each bin. Histograms require a fixed number of words (depending on the number of bins), regardless of the number of entries. Histogramming of statistical quantities is the standard technique of data analysis. In addition to the histogram data type LOOK supports a second type of distribution, called vector (or n-tuple). A single vector is one statistical element of a distribution, which may have a dimension between 1 and 100. A unbinned distribution may have any number of entries (vectors). In contrast to the case of histograms, the vector data type requires a variable number of words, depending on the number of entries. The standard application of the vector type is in the area of statistical analysis. Because each single entry is kept, high resolution scatterdiagrams of one variable versus another one are possible (data of vector type can in principle also be used as input for interactive data manipulation; options for these applications are planned). The data type vector may also be used for other applications, which do not use vectors in the statistical sense, but only use the data storage options provided by the LOOK data base. For example a set of vectors with dimension 2 (x,y) can describe a curve. Thus the data storage options of LOOK for vectors may also be used systematically for non-statistical applications. 1 Part 1 - 4 - 1. Introductory remarks _______________________________________________________________________ This part of the manual describes the subprograms for storing and retrieving data for distributions in the LOOK data base. The LOOK data base works with a common, with automatic overflow to direct access data sets, and with options to dump certain data areas to external files. The subroutines are working in interactive and in batch programs. Options to print distributions on line printers are available. More important is the access to the distributions and display options in interactive LOOK programs; these options are described in part 2 of this manual. The display of data is done in terms of figures. A single figure may contain more than one data object (a single histogram or a single set of vectors is one data object). For example a figure may show one histogram together with a fit curve; then the figure contains two data objects, one histogram and one set of (x,y)-vectors for the curve. In order to simplify the identification of data objects, which belong to one figure (and should usually be displayed together in a figure), the following identifiers for data object (histograms and vectors) are used in the LOOK data base: > data objects have a figure number IFG as primary identifier > a secondary identifier INR is used to distinguish different data object of the same type with the same figure number Most of the subprograms described in this part have therefore the two arguments: IFG = figure number (any integer > 0) INR = secondary number (any integer >=0) The figure number has to be positive, the secondary number can be zero or positive. If during data creation data objects belonging together are assigned to the same figure number, the simple interactive command FIGURE (followed by the figure number) is sufficient to get the display of the various data objects in one figure. In addition the LOOK data base can be divided into different areas. This option allows to store in one data base different data objects, which carry the same figure numbers. Areas itself are identified by an area name and by a version number. Thus in total there are four levels of identification for one data object: > the area name (8 characters) and the > the version number (any integer) for a group of figures, > the figure number (a positive integer) and the > the secondary number (a non-negative number) for each data object. LOOK has been designed according to the requirement of simplicity of use and high speed. Among the properties are: > no initialization necessary by the user of the system (except for the case when the user needs a very big volume of LOOK data base which exceeds the default maximum) > histogram binning determined automatically,if not done by the user > large two-dimensional histograms and large vector sets possible A simple program to produce a one-dimensional histogram is the following: PROGRAM TEST DO 10 I=1,1000 X=RNLOOK(I) ! use LOOK random number generator 10 CALL SHS(1,0,X) ! fill one-dimensional histogram CALL PRNTF(0,0) ! print all histograms STOP END The time per filling call increases only weakly with the number of existing data objects (note that there may be thousands of data objects in the data base). The method used for the filling of large histograms minimizes paging times for computers with memory paging. 1 Part 1 - 5 - 2. Booking and filling _______________________________________________________________________ 2. Booking and filling ====================== 2.1 Histograms -------------- Histogram types: One-dimensional histograms of a variable X, and two-dimensional histograms of variables X,Y are supported. Both can be unweighted or weighted, that is: a weight W can be assigned to each single value X or pair X,Y. "Unweighted" means, that all weights are equal to 1.0. The variables X and Y (and W) are of type real (floating point). The four histogram types are abbreviated by the following letters, which are part of subprogram names for the histograms: HS 1-dimensional histogram (all weights assumed to be 1.0) HSW 1-dimensional weighted histogram HD 2-dimensional histogram (all weights assumed to be 1.0) HDW 2-dimensional weighted histogram The names of the subprograms to add a single entry to a histogram have a "S" in front of the letters above. For example an entry X is added to a unweighted 1-dimensional histogram by the call CALL SHS(IFG,INR,X) Bins and booking: The bins of a histogram are described by three parameters: for the variable X NX = number of bins XA = first bin, left edge XB = last bin, right edge (XA < XB) and NY, YA, YB for the variable Y. The bin width DX is (XB-XA)/NX. Bins for a histogram are defined in a booking call. The name of the subprogram to book a histogram has a "B" in front of the name of the corresponding histogram call. For example the bins for an unweighted 1-dimensional histogram are defined by the call CALL BHS(ifg,inr,NX,XA,XB) This booking of histograms is optional: bins are defined automatically on the basis of the first 100 entries, if entries are added to a histogram, which is not booked; by default the numbers of bins are 100 and 20, resp., for 1- and 2-dimensional histograms. There is no limit on the number of bins. The default value is used, if 0 is given for NX (or NY). If the limits XA and XB (or YA,YB) given in the call are identical, the limits are determined automatically. If the variables X (or Y) can only take on integer values , for example 13.0, 17.0 ... the bin width DX should also take on integer values. To simplify this definition, the booking subroutines correct the limits, to get integer valued bin width, if the user gives the number of bins negatively. For example, in the call CALL BHS(ifg,inr,-20,1.0,15.0) the stored values of XA and XB are XA=0.5 and XB=20.5. Histogram booking and filling calls: 1-dimensional unweighted histogram CALL BHS(IFG,INR,NX,XA,XB) book (optional) CALL SHS(IFG,INR,X) store (=fill) 1-dimensional weighted histogram CALL BHSW(IFG,INR,NX,XA,XB) book (optional) CALL SHSW(IFG,INR,X,W) store 2-dimensional unweighted histogram CALL BHD (IFG,INR,NX,XA,XB,NY,YA,YB) book( optional) CALL SHD (IFG,INR,X,Y) store 1 Part 1 - 6 - 2. Booking and filling _______________________________________________________________________ 2-dimensional weighted histogram CALL BHDW (IFG,INR,NX,XA,XB,NY,YA,YB) book (optional) CALL SHDW (IFG,INR,X,Y,W) store Statistical considerations ~~~~~~~~~~~~~~~~~~~~~~~~~~ In an unweighted histogram the number of entries in each bin is counted: bin content = number N of entries in the bin Histograms are used to get an estimate of an empirical distribution from a sample of a distribution. The number of entries in a bin follows a Poisson distribution with a mean value equal to the expectation value F for the bin. According to the Poisson distribution the variance is equal to F, thus the standard deviation is the square root of F. In practice, the square root of the bin content = square root of N is taken as the approximation to the standard deviation. Unless N is small (below 5) this is a good approximation. The statistical calculations for mean values and standard deviations are done with all the original data (not with binned data); entries outside of the bin limits are included in the calculations, which therefore do not depend on the binning. If a user wants to get the mean value within certain cuts, he has to do the cut before calling the histogram. With the notation N = total number of entries Sum [Xi] = sum of all X values Sum [Xi**2] = sum of the squares of all X values the formula for mean and standard deviations are as follows: Sum [Xi] mean = -------- N 1 sigma = square root of --- Sum [(Xi-mean)**2] N-1 In a weighted histogram a weight W is assigned to each entry. The content of a certain bin is equal to the sum of the weights W for the entries in the bin. In LOOK a full floating point word is used for each bin to accumulate the sum of weights: bin content = sum of weights for the N entries in the bin Problems with rounding should not be significant unless a large number of weights (above 10**5) is accumulated in a bin or very large fluctuations in the value of the weight occur (note, that in other packages more than one bin content is sometimes packed into one word, with serious round-off problems). The error estimate for the bin content is more complicated in the weighted histograms case: there are fluctuations of the number of entries (as in the unweighted histogram case) plus fluctuations of the value of the weight! A simple and (in most cases) acceptable method is to accumulate as well the sums of the squares of the weights for the entries in the bin. Then the estimate for the standard deviation of the bin content is the square root out of this sum. This method is used in LOOK; two adjacent floating point words are used to accumulate the sum of weights and the sum of the squares of the weights for one bin. If all weights are equal to 1.0, the results obtained in a weighted histogram are the same as in the unweighted case. If all weights are equal to some constant value c, then the content of all bins and the standard deviation are multiplied by this constant c (compared to the unweighted histogram). It is easy to see what happens if one weight is much larger than all others for a certain bin. Then the standard deviation will be nearly as big as the content (close to 100 % error). Thus, large fluctuations in the values of the weight deteriorate the statistical precision of a weighted histogram. 1 Part 1 - 7 - 2. Booking and filling _______________________________________________________________________ For weighted histograms a so called "effective number of entries" is calculated in LOOK. It is defined by the formula Sum [Wi]**2 Neff = ----------- Sum [Wi**2] If all weights have the same value, Neff = N. But if there are large fluctuations in the value of the weight, Neff can be much smaller than N. Neff gives an indication of the number of constant-weight entries, which would have the same statistical precision as the given weighted entries. For weighted histograms mean and standard deviation are calculated by the formulas: Sum [Wi*Xi] mean = ----------- Sum [Wi] Neff SUM [Wi*(Xi-mean)**2] sigma = square root of ------ --------------------- Neff-1 SUM [Wi] 2.2 Vectors ----------- A second set of subprograms can be used to store single coordinates (1- to 100-dimensions). There are three data types, which are abbreviated by the following letters, which are part of subprogram names for the data vectors: XY pair of two coordinates (2 dimensions) XYZ triple of three coordinates (3 dimensions) VEC vector with NVEC = 1 ... 100 components (NVEC dimensions) The name of the subprogram to add a data point have the letter "S" in front of the letters above. For example a 3-dimensional point with X,Y,Z is added to a set by the call CALL SXYZ(ifg,inr,X,Y,Z) Booking is necessary for the VEC data types, for the specification of the dimension parameter NVEC; for the XY and XYZ data types the dimension parameter NVEC is fixed to 2 and 3, resp.. Booking is not necessary and not possible. Most efficiently vector data can be used as Ntuples with (optionally) named columns. In LOOK, Ntuple column names are CHARACTER*8 variables satisfying FORTRAN-(90) rules for names. Note, that Ntuples with identical first number (IFG) will automatically have the same names for its columns. Vector booking and filling calls: 2-dimensional vector XY CALL SXY(IFG,INR,X,Y) store vector (x,y) 3-dimensional vector XYZ CALL SXYZ(IFG,INR,X,Y,Z) store vector(x,y,z) 1- to 100-dimensional vector CALL BVEC(IFG,INR,NVEC) book (necessary, NVEC = 1 ... 100) CALL SVEC(IFG,INR,ARRAY) store vector ARRAY CALL BNT (IFG,INR,NVEC,NAMES) alternate booking for vector data, assigning names to the columns. NAMES is user defined character*8 array of dimension NVEC 1 Part 1 - 8 - 2. Booking and filling _______________________________________________________________________ Vectors may represent a sample of a statistical distribution. Graphically the distributions (2- and 3-dimensions) can be represented by a scatter plot (for example marker style with dots). The vector data can be displayed graphically not only as MARKERS (X, Y), but in other styles like SYMBOL and CURVES too. The convention for the order of variables is the following (valid for all attributes) for the first two elements: ARRAY(1) = X ARRAY(2) = Y The following is necessary for the style symbol. In order to represent an arbitrary data point as symbol with error bars (symmetric) the two following words are necessary in addition in a 4-vector: ARRAY(3) = dX ARRAY(4) = dY In the case of asymmetric error bars, 6-vectors must be used, with the convention: ARRAY(3) = dX-left ARRAY(4) = dX-right ARRAY(5) = dY-up ARRAY(6) = dY-down In the above three cases of vectors which represent (X,Y) data with(out) error bars, the following alternative filling possibilities may be more convenient for 2-, 4- and 6- vectors respectively: CALL SVEC02(IFG,INR,X,Y) CALL SVEC04(IFG,INR,X,Y,DX,DY) CALL SVEC06(IFG,INR,X,Y,DXLOW,DXHIG,DYLOW,DYHIG) If LINE or CURVE style has been selected for XY or VEC(2) data, then points will be connected by a sraight line segments or smooth curve line correspondingly in the order they have been stored in XY or VEC(2) In addition, a style ARRW allows to connect pairs of 2- or 3-dim points from XY, XYZ or VEC(2) data by arrows with different type of pointers (1-->2, 3-->4, 5-->6 etc.) and VEC(4) (ARRAY(1,2)-->ARRAY(3,4) for each row). 1 Part 1 - 9 - 3. Areas in the LOOK data base _______________________________________________________________________ 3. Areas in the LOOK data base ============================== In addition to the identifiers of data objects, mentioned above, LOOK has the concept of areas. The whole data base is divided into areas and each data object belongs to a certain area. The concept of areas allows to have data objects with otherwise identical identifiers in different areas: for example histogram number 1 can be in two areas. An area is characterized by > an area name (up to 8 characters), and > a version number (any integer). Many areas/versions can be present in the data base at the same time. By default the so called blank area is selected at the start. The user may select different areas, which are characterized by a area-name ARNAME (character) and a version number IVERS (any integer). An area is entered by the call ------ ----- CALL SAREA(ARNAME,IVERS) and then all calls to LOOK subprograms or commands refer to the specified area, until there is a redefinition by another call of SAREA. If SAREA is not called, then a blank area is assumed, having the values ARNAME = ' ' IVERS = 0 Example: CALL SAREA('DST analysis',910817) The first 8 characters of ARNAME are significant. There is no distinction between lower and upper case characters within ARNAME. Further calls concerning areas are: CALL RETAR means return to previous area CALL QAREA(ARNAME,IVERS) get current area and version ------ ----- - CALL QQAREA(I,ARNAME,IVERS) get area and version number I ------ ----- I = 1 (blank area) ... maximum of 100 Thus, in order to process a full LOOK data base one has to make a loop over all existing areas. The corresponding code may look as follows: I=1 10 I=I+1 CALL QQAREA(I,ARNAME,IVERS) CALL SAREA(ARNAME,IVERS) * ... process data from current area, e.g. print all figures: CALL PRNTF (0,0) IF(ARNAME.NE.' '.OR.IVERS.NE.0) GOTO 10 Note, that for the printout (chapter 5) from all areas there is a special call (CALL PRNTAF). LOOK areas can be locked out against output (recording on the file or printout on the line printer): ------ ----- --- CALL LOCKAR(ARNAME,IVERS,KEY) KEY = 0 unlock given area (default for all areas) = 1 suppress all printout from given area = 2 suppress output of the given area = 3 suppress both printout and writing on the output file 1 Part 1 - 10 - 4. Text and graphical representation _______________________________________________________________________ 4. Text and graphical representation ==================================== Text ---- Text can be added to a figure in five different standard positions both for line-printer and graphical output; more text lines can be assigned to a figure which however will only appear in graphical output. The text becomes part of the data by the call: CALL STEXT(IFG,IPOS,TEXT) where IPOS = 1 x-scale (see example in next chapter) 2 y-scale 3 bottom left 4 top left 5 top right 6 ... inside figure (no limitation, see Part 2) TEXT = text string The text is stored in the LOOK data base, together with the histograms and vectors and takes part in input/output of the data. In addition for the blank area it is possible to define a global title by a call CALL LTITLE(TITLE) which is printed in position 5 unless there has already been added text to this position. Note, that the title does not become part of the data and thus cannot be transferred from the batch job to the interactive session (see also keyword LTITLE in Part 2). For the non-blank areas a global title is constructed automatically of the area name and version. The text belonging to a figure may be obtained back from the data base into a user character string by the call --- ---- CALL GTEXT(IFG,IPOS,NCH,TEXT) --- ---- TEXT = text NCH = number of returned characters Graphical representation ------------------------ Histograms and vector data (data points) can be displayed graphically in a variety of modes. The graphical representation is defined by graphical attributes. All objects have three types of attributes, which are relevant for the display mode of the objects. Default values of the objects are automatically defined; they can be changed at any time by the user, either by a call in batch mode or by a correspondent command interactively (SATTR, SETDAT). The three attributes are: style, for example 'curve' mode, for example 'dotted' colour, for example 'green'. If attributes are specified by the user in a call or command, only the upper case characters given below are significant, the order of attributes is irrelevant. A list of the possible attributes is given on the next page. For all styles and modes the following colours may be selected: BLACk = background colour (invisible) WHITe = foreground colour (default) RED GREEn BLUE YELLow MAGEnta CYAN 1 Part 1 - 11 - 4. Text and graphical representation _______________________________________________________________________ ----------------------------------------------------------------------- style | explanation .................................................. ----------------------------------------------------------------------- | mode explanation ...................................... ----------------------------------------------------------------------- MARKer marker of GKS style or similar ----------------------------------------------------------------------- | DOTS small dots, scatter plot (default for XY data) | PLUS plus signs | STAR asterisks | CIRCle circles | CROSs cross with 45 degree legs (default for 2-VECtors) ----------------------------------------------------------------------- SYMBol hollow symbol with error bars (symmetric or asymmetric) ----------------------------------------------------------------------- SYMF filled symbol with error bars (symmetric or asymmetric) ----------------------------------------------------------------------- | PLUS error and horizontal bar | CIRCle circle (disc for SYMF style) (default for 4,6-VEC) | TRIAngle triangle | RTRIangle rotated triangle | SQUAre square | RSQUare rotated square ----------------------------------------------------------------------- LINE polyline = straight line between given points ----------------------------------------------------------------------- | FULL solid | DASHed dashed | DOTTed dotted | DADOtted dash-dotted | LODAshed long-dashed (not implemented) ----------------------------------------------------------------------- CURVe curve = smooth curve between given points ----------------------------------------------------------------------- | FULL solid | DASHed dashed | DOTTed dotted | DADOtted dash-dotted | LODAshed long-dashed ----------------------------------------------------------------------- ARRW arrow = connection between pairs of 2D points ----------------------------------------------------------------------- | SIMPle full line (arrow without pointer) | OPEN arrow with an open pointer (--->) | TRIAngle arrow with a hollow triangle pointer | TRIFilled arrow with filled trianle pointer | NICE arrow with a "nice" hollow pointer | NICFilled arrow with a "nice" filled pointer ----------------------------------------------------------------------- HIST onedimensional histogram ----------------------------------------------------------------------- | NORMal normal histogram (default) | SOLId solid histogram | LHATched left-hatched histogram | RHATched right-hatched histogram | HHATched horizontally-hatched histogram | SIMPle line histogram (nice if many bins) ----------------------------------------------------------------------- DHIS twodimensional histogram ----------------------------------------------------------------------- | LEGO lego plot (default) 3D | LEGN lego plot (no grid for zero bin content) 3D | SURFace surface plot (not yet supported) 3D | CONTour contour plot 2D | BOXEs boxes 2D ----------------------------------------------------------------------- TABLe tabular data ----------------------------------------------------------------------- | IBIN integer content of 2d-hist written in equal boxes | IBOX integer content of 2d-hist in proportional boxes | RBIN real content of 2d-hist written in equal boxes | RBOX real content of 2d-hist in proportional boxes | BOS BOS banks (not yet supported) | NTUPle n-tuples (default for all vectors exept 2, 4, 6) ----------------------------------------------------------------------- Table 1: Styles and modes of graphical representaion of distributions 1 Part 1 - 12 - 4. Text and graphical representation _______________________________________________________________________ Each object, once started, gets default attributes. They can be changed by a call (or by a command in an interactive session): ------ --- --- ------ CALL SATTR(DATYPE,IFG,INR,ATTRIB) ATTRIB = text, specifying attributes Examples: CALL SATTR('XY' ,17,1,'full blue line') CALL SATTR('XYZ',17,1,'green circle symbol') Another possibility is to change default attributes for a whole class of LOOK objects (missed attributes remain unchanged): ------ ------ CALL SETDAT (DATYPE,ATTRIB) For example: CALL SETDAT ('HD','dhis boxes') Note, that SETDAT has influence only on the objects created after this call, attributes of the already existed figures remain unchanged. The attribute text is stored together with the distributions in the LOOK data base and can be obtained back into a user character string by a call: ------ --- --- CALL GATTR(DATYPE,IFG,INR,NCH,ATTRIB) --- ------ ATTRIB = text, specifying attributes NCH = number of returned characters Table 2 below shows the correspondence between various data types and graphical styles. Symbol "d" stands for default styles. Note, that if style CURVe has been defined for 1-dimensional histogram, the smoothing will be performed and only smoothed histogram will be shown. Presently 3-dim distributions XYZ can only be graphically presented in form of 2-dim projections (xy, xz or yz). ------------------------------------------------------------------ DATYPE | MARK SYMB SYMF LINE CURV ARRW HIST DHIS TABL ------------------------------------------------------------------ HS | + + + + + - d - - HSW | + + + + + - d - - HD | - - - - - - - d - HDW | - - - - - - - d - XY | d + + + + + - - - XYZ | d + + + + + - - - VEC(2) | + d + + + + - - + (4) | - d + + - + - - + (6) | - d + - - - - - + (.) | - - - - - - - - d ------------------------------------------------------------------ Table 2: Valid styles for different LOOK data types 1 Part 1 - 13 - 5. Printout on line printers _______________________________________________________________________ 5. Printout on line printers ============================ Histograms and vectors can be printed on a line-printer, the resolution is of course rather limited. Three printmodes are available: MPR > 0 full print-out (usually one full page per plot) MPR = number of lines per page, =1 means default number MPR = 0 reduced (many plots per page, with reduced number of bins) MPR < 0 "terminal"(only up to 72 columns, and up to 20 lines) For printing the number of histogram bins may be reduced, by combining a fixed number of bins into one printed bins content. XY- and XYZ-vectors are printed in a Y-vs-X plot with a certain binning, counting the number of points per bin. VEC-vectors are not printed. Two parameters, the print-unit LUNP and the print-mode MPR are selected by the call Default LUNP = print-unit 6 MPR = print mode (see above) 68 ---- --- CALL SETPRP(LUNP,MPR) set printer parameters The call to print histograms and vectors is: IFGA,IFGB = range of figure numbers (0,0 means ALL including index) all figures numbers IFGA ... IFGB ---- ---- CALL PRNTF(IFGA,IFGB) CALL PRNDEX print index (one-line per histogram,...) This call can be made at any time (during or after filling). An example for a histogram printout is shown below for the printmode MPR=-1. It also shows the print positions of text. ALL figures from ALL areas (see chapter 8 on areas) are printed by CALL PRNTAF print all figures from all areas together with a complete index of all areas. Besides, user has the possibility to analyse 1-dim histograms with help of LOOK peak analyser, which can find up to 5 peaks per distribution. ---- ---- CALL LPEAKS (IFGA,IFGB) make analysis of all 1-dim histograms from the requested range in a current area, and print table of results (one line per peak) In order to get access to the peak parameters in a batch job one may use another call, described in section 7. 1 Part 1 - 14 - 5. Printout on line printers _______________________________________________________________________ HS 11 7 2000 Entries Weight = 2000. ========= Min/Max Mean/Sigma Bins Low X-In High X 0.00286825 1.00896 100 0 2000 0 1.99188 0.796502 Position 4 Position 5/Title +L----+----L----+----L----+----L----+----L----+----+ P 100. T T o I I s I I i I X I t I XX X X I i T XXXX X T o I XXXX XXX I n I X XXXXXXXXX I I XX XXXXXXXXXXXXXX I 2 I XX XXXXXXXXXXXXXX I 50. T XXXXXXXXXXXXXXXXXXXX T I XX XXXXXXXXXXXXXXXXXXXXX I I XXXXXXXXXXXXXXXXXXXXXXXX X I I XXXXXXXXXXXXXXXXXXXXXXXXXXXX X I I XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XX I T XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX T I XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX I I XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX I I XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX I I XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXI 0. +L----+----L----+----L----+----L----+----L----+----+ 0. 0.4 0.8 1.2 1.6 2. Position 3 Position 1 112222333344445646688786786556555434232221111 15915003510574619939260235512889091076037844540053 In two-dimensional printer-plots a character 1 ... Z is printed to represent the content (the unit is 1.0 unless stated differently). I 0 1 2 3 4 5 6 7 8 9 Example: F ------+------------------------------- F is 15 00 + I . 1 2 3 4 5 6 7 8 9 content = 15*unit 10 + I A B C D E F G H I J rounded 20 + I K L M N O P Q R S T . = nonzero <1 30 + I U V W X Y Z * * = overflow ------+------------------------------- HD 70 1 500 Entries ========= Min/Max Mean/Sigma Bins High I 0 0 0 X 0.123525 395.938 50 Y-In I 0 91 409 598.94 147.844 Low I 0 0 0 Y 127.738E-12 34.5331E-6 20 +-----+------+---- 99.5956E-6 30.5695E-6 Low X-In High DST-ANALYSIS 870827 E-6 +L----+----L----+----L----+----L----+----L----+----+ 100. T 1 1 1 T I 1 1 I I I I 1 1 1 I I 1 1 I T 1 1 1 T I I I 1 1 1 I I 11 1 1 1 I E-6 I I 50. T1 1 2 1 1 1 1 T I 1 1 I I 1 1 I I 1 1 1 I I 1 1 I T1 1 1 1 T I 1 1 1 1 1 1 I I 1 1 11 1 1 1 1 1I I 1 1 11112 1 2 I I1 1 112 1 1 112 1 1 1 112 1 111I 0. +L----+----L----+----L----+----L----+----L----+----+ 0. 60. 120. 180. 240. 300. 1 Part 1 - 15 - 6. Access to the data _______________________________________________________________________ 6. Access to the data ===================== The stored information on Steering parameters and statistical data, Attributes, Text, and the Content is accessible by the user with calls of subroutines. In all these subroutines the first three arguments specify: DATYPE = data type (character string, e.g. 'HSW' or 'XYZ') IFG = figure number INR = second number ------ --- --- The logical function LEXIST(DATYPE,IFG,INR) tells whether the given figure exists in the current LOOK area. For example: IF (LEXIST('HS',10,1)) CALL PRNTF(10) The following call returns the next existing figure in the current LOOK area after the given one. Note, that all arguments will be modified at the output, therefore they must be variables! If no figure has been found, (' ', 0,0) are returned. ------ --- --- CALL NEXTDF(DATYPE,IFG,INR) 6.1 Steering parameters and statistical data -------------------------------------------- Information about steering parameters is obtained by a call: ------ --- --- CALL GPARM(DATYPE,IFG,INR,NVEC,NENT,NWORDS) ---- ---- ------ NVEC = dimension parameter of data (from booking), not existing if zero NENT = number of entries NWORDS = total number of data words (for content) The following calls apply only to histograms (information on Y is of course not filled for one-dimensional histograms, but dummy arguments have to be present): ------ --- --- CALL GHBINS(DATYPE,IFG,INR,NX,XA,XB,NY,YA,YB) -- -- -- -- -- -- where NX = number of bins for X XA, XB = left edge of first bin, right edge of last bin for X NY = number of bins for Y YA, YB = left edge of first bin, right edge of last bin for Y - - - - The LOOK-function CENTIN(I,N,A,B) returns the bin-center value for the I-th bin for N bins between A and B. This function is equivalent to a statement function: CENTIN(I,N,A,B)=0.5*(FLOAT(N+N-I-I+1)*A+FLOAT(I+I-1)*B)/FLOAT(N) 1 Part 1 - 16 - 6. Access to the data _______________________________________________________________________ ------ --- --- CALL GHSTAT(DATYPE,IFG,INR,NENT,SUMW,RNEFF,XSTAT,YSTAT) ---- ---- ----- ----- ----- where NENT = number of entries SUMW = sum of weight for all entries RNEFF = effective number of entries XSTAT(1) = minimum x-value XSTAT(2) = maximum x-value XSTAT(3) = mean x XSTAT(4) = sigma (standard deviation) YSTAT(1) = minimum y-value YSTAT(2) = maximum y-value YSTAT(3) = mean y YSTAT(4) = sigma (standard deviation) ------ --- --- CALL GHNENT(DATYPE,IFG,INR,NENTS) ----- where NENTS = integer array of dimension 3 for one-dimensional histogram NENTS(1) = number of x-entries outside low (x-outlow) NENTS(2) = number of x-entries inside (x-inside) NENTS(3) = number of x-entries outside high(x-outhigh) NENTS = integer array of dimension (3,3) for two-dimensional histogram NENTS(1,1) = x-outlow, y-outlow NENTS(2,1) = x-inside, y-outlow NENTS(3,1) = x-outhigh, y-outlow NENTS(1,2) = x-outlow, y-inside NENTS(2,2) = x-inside, y-inside NENTS(3,2) = x-outhigh, y-inside NENTS(1,3) = x-outlow, y-outhigh NENTS(2,3) = x-inside, y-outhigh NENTS(3,3) = x-outhigh, y-outhigh 6.2 Content ----------- The subroutines GDATA ("get" DATA) and FDATA ("fetch" DATA) can be used to copy the data of histograms and vectors into a user array. All data are floating point data. The data are organized in the following way: (a) Histograms ~~~~~~~~~~~~~~ For unweighted histograms there are as many data words as there are bins, one word contains the content of one bin. For an unweighted one-dimensional histogram with NTBIN bins: word | content -------+------------------------- 1 nr of entries bin 1 2 nr of entries bin 2 ... ... NTBIN nr of entries bin NTBIN The content of a bin is a measure of the density of a distribution; the error of the bin content (standard deviation) is usually assumed to be the square root of the bin content (Poisson distribution within one bin), and can be calculated from the bin content (note that "unweighted" means a constant weight of 1 for all entries). 1 Part 1 - 17 - 6. Access to the data _______________________________________________________________________ In a two-dimensional histogram bins are numbered in the order: x-bins 1...NX for y-bin 1 x-bins 1...NX for y-bin 2 ... x-bins 1...NX for y-bin NY For weighted histograms there are two words for each bin, in total 2*NTBIN words. For a weighted one-dimensional histogram: word | content -------+------------------------- 1 sum of weights bin 1 (SUMW) 2 sum of squares of weights bin 1 (SUMWS) 3 sum of weights bin 2 4 sum of squares of weights bin 2 ... ... 2*NTBIN-1 sum of weights bin NTBIN 2*NTBIN sum of squares of weights bin NTBIN Here the sum of weights (SUMW) is a measure of the density of a distribution, and the square root of SUMWS (sum of squares of weights) is a measure of the error of the density (standard deviation). In a two-dimensional weighted histogram the numbering is consecutive as in the unweighted case. (b) Vectors ~~~~~~~~~~~ For data points (XY, XYZ, VEC) all words can be accessed, which were given as entries. The total number of data words that can be accessed is NENT * NVEC, where NENT is the total number of entries and NVEC is the data length (dimension) of one vector. Possible values of NVEC are: data type NVEC ------------+-------- XY 2 XYZ 3 VEC 1...100 The data words are in the same order as in an array A(NVEC,NENT). That means: data point after data point, for example for the data type XYZ (NVEC=3): word | content -------+------------------------- 1 X of data point 1 2 Y of data point 1 3 Z of data point 1 4 X of data point 2 5 Y of data point 2 ... ... 3*NENT-1 Y of data point NENT 3*NENT Z of data point NENT By a call to one of the access routines GDATA and FDATA the available data are copied to a user array ARRAY. Since the amount of data may be very high, the data can be copied in parts: if the user array is too small to contain all data, the access is done one part after another. The user specifies a length for his array, and the data transferred in one call do no exceed the length. 1 Part 1 - 18 - 6. Access to the data _______________________________________________________________________ DATYPE = data type (character string, e.g. 'HSW' or 'XYZ') IFG = figure number INR = second number IDAT = index before data to be copied (only FDATA) NR = number of words, copied to the user array ARRAY = user array of dimension (at least) NDIM NDIM = dimension of the array The difference in the two access subroutines GDATA and FDATA is relevant only in the case, when the user array is too small to copy all the data at once. The subroutine GDATA allows sequential access to the data. Up to NDIM words are copied in one call, one part after another, until the end of data is reached. ------ --- --- ---- CALL GDATA(DATYPE,IFG,INR,NR,ARRAY,NDIM) -- For (NR = NDIM) there may be more words for the same set of data, and they may be obtained by another call. Obtaining data by this call is equivalent to "reading" a data set. It is recommended to use a dimension parameter NDIM, which is a multiple of the vector length NVEC (otherwise vectors will be split across calls). Internally there is a pointer, which shows the position of the next data to be copied. This pointer can be reset by the call ------ --- --- CALL RWDATA(DATYPE,IFG,INR) to be shure to get the first data with a subsequent GDATA call ("ReWind"). It is recommended to make this call before the first copy. The subroutine FDATA allows direct access to the data: the user specifies an index IDAT to obtain the data words IDAT+1 ... IDAT+NDIM. ------ --- --- ---- ---- CALL FDATA(DATYPE,IFG,INR,IDAT,NR,ARRAY,NDIM) -- Example: Assume the user wants to print the coordinates of all data vectors of 'XYZ' data with figure number 17, second number 2. The code could be as follows. Using subroutine GDATA the code could look as follows ... REAL ARRAY(120) NDIM=120 CALL RWDATA('XYZ',17,2) 10 CALL GDATA('XYZ',17,2,NR,ARRAY,NDIM) IF(NR.NE.0) THEN WRITE(6,'3(3F10.3,4X)') (ARRAY(I),I=1,NR) IF(NR.EQ.NDIM) GOTO 10 END IF ... and using subroutine FDATA the code could look as follows: REAL ARRAY(120) NDIM=120 IDAT=0 10 CALL FDATA('XYZ',17,2,IDAT,NR,ARRAY,NDIM) IF(NR.NE.0) THEN WRITE(6,'3(3F10.3,4X)') (ARRAY(I),I=1,NR) IDAT=IDAT+NR IF(NR.EQ.NDIM) GOTO 10 END IF 1 Part 1 - 19 - 7. Global filling _______________________________________________________________________ 7. Global filling ================= Complete histograms (or parts of histograms) and sets of vectors can be copied from a user array directly into the LOOK data base. This is the inverse operation of the subroutines GDATA and FDATA, which copy data into a user array. Because of the different types of histogram and vector data there are separate subroutines for both data types. However, the first three arguments specify the data as before: DATYPE = data type (character string, e.g. 'HSW' or 'XYZ') IFG = figure number INR = second number In addition the following arguments are used: IDAT = index before data to be copied NR = number of words, to be copied from the user array ARRAY = user array, with NR words The explanation of the organization of data of the previous chapter apply as well to this chapter. For the case of histograms the user data are always added to the histogram. If overwriting is required the user has to clear the histogram before. For the case of vector data the user data are appended to the existing data. If overwriting is required the user has to purge the data beforehand and book the object again. 7.1 Purging (deleting) and resetting figures -------------------------------------------- Existing figures (data sets) can be either purged completely, or reset. In latter case only figure texts, attributes and booking parameters are kept, while content of histograms and vectors (including statistics) is erased. ----- --- --- CALL PURGDF(DATYPE,IFG,INR) purge single data set ----- --- --- CALL RESETD(DATYPE,IFG,INR) reset single data set --- CALL PURGEF(IFG) purge figure IFG (IFG=0 means all) if IFG < 0 purge all but abs(IFG) --- CALL RESETF(IFG) reset figure IFG (IFG=0 means all) These calls can be used for histograms and vector data as well and refer to the current LOOK area. Texts can be reset to blanks by the following call: --- ---- CALL PURGET(IFG,IPOS) reset existing (i.e. defined with CALL STEXT) texts to blanks IPOS > 0 : purge a single text with position IPOS IPOS = 0 : purge ALL texts with positions < 1000 (fittexts are left intact) IPOS = -1 : purge ALL texts including fittexts IPOS < -1 : like IPOS=-1 but also assign blank to position 3 . 1 Part 1 - 20 - 7. Global filling _______________________________________________________________________ 7.2 Global filling of histograms -------------------------------- Calls in this chapter only apply to histogram data, the subroutines names start with AH. A histogram, to which data are added, must exist before, i.e. it has been booked, and the histogram limits have been defined (this means, that the same values for the upper and lower limit are not allowed here). The bin numbers NX and NY have to correspond to the amount of data transmitted (argument NR). In order to add data from a user array ARRAY of NR words to a histogram the user has to specify an index IDAT, which has the same meaning as in the FDATA call. The data from the user array will be added to the data words IDAT+1 ... IDAT+NR of the histogram. IDAT has to be zero for a copy of a complete histogram in one call. ------ --- --- ---- -- ----- CALL AHDATA(DATYPE,IFG,INR,IDAT,NR,ARRAY) The statistics and the information about the number of entries (see calls GHSTAT and GHNENT) can also be added: ------ --- --- ---- ---- ----- ----- ----- CALL AHSTAT(DATYPE,IFG,INR,NENT,SUMW,RNEFF,XSTAT,YSTAT) ------ --- --- ----- CALL AHNENT(DATYPE,IFG,INR,NENTS) 7.3 Global filling of vectors ----------------------------- Calls in this chapter only apply to vector data of type VEC or XY or XYZ. The user data can be appended to the existing data; if overwriting is required, the user has to purge the data before and eventually to book the vector again. Note that booking is necessary for the data with the type VEC, but not for data types XY and XYZ. Since the user data are appended, no index like IDAT is necessary. The number of data words has to be a multiple of the vector length NVEC, (otherwise the last NR-(NR/NVEC)*NVEC words of a user array are ignored). ------ --- --- -- ----- CALL AVDATA(DATYPE,IFG,INR,NR,ARRAY) 1 Part 1 - 20a - 7. Global filling _______________________________________________________________________ 7.4 Copying figures ------------------- Few subroutines can be used in order to copy a complete figure or only a part of it. As a default, the resulting figure will be created in the same area, unless another target area has been explicitly required (see next section). ---- ---- CALL COPYFG(IFG1,IFG2,IER) copy complete figure --- ---- ---- ---- ---- CALL COPYDF(IFG1,INR1,IFG2,INR2,IER) copy subfigure --- ---- ---- CALL COPYTX(IFG1,IFG2) copy figure text IFG1, INR1 = source (sub)figure identifiers IFG2, INR2 = target (sub)figure identifiers IER = 1 if target figure already exists, 0 otherwise 1 Part 1 - 21 - 8. Other operations with figures _______________________________________________________________________ 8. Other operations with figures ================================ 8.1 Operations with histograms ------------------------------ ----- ----- ---- ---- ---- ---- 1) CALL HNORM(INORM,SCALE,IFG1,INR1,IFG2,INR2,IERR) ---- With a call to this subroutine a normalised (always weighted) version of the input histogram will be created. SCALE is the scaling factor determining the integrated or summed content (normally 1). Two types of normalization are possible depending on INORM: INORM=1 - 'mathematical' normalization (integrated content = SCALE), INORM=2 - the 'relative frequency' type (summed content = SCALE). If the figure IFG2 INR2 already exists, the subroutine will fail, i.e. IERR>0. -- ---- ---- ---- ---- ---- ---- 2) CALL HPROJ(IP,IFG1,INR1,IFG2,INR2,ILOW,IHIG,IERR) ---- To produce projections of all or parts of 2-dimensional histograms, the input parameters should be set the following way: IP = 1 or 2 where 1 is projection on the x-axis and 2 is projection on the y-axis. IFG1,INR1 figure-numbers of the 2-dimensional histogram. IFG2,INR2 figure-numbers of the (1-dimensional) projection histogram to be produced (must not exist before the call). ILOW,IHIG these parameters are used to project only slices of bins, where ILOW is the starting bin and IHIG is the end bin to project. If ILOW=0 it will be set to 1 and if IHIG=0 it will be set to MAXBIN. IERR error code, if IERR>0 something went wrong. EXAMPLES: CALL HPROJ(1,1,0,2,0,0,0,IERR) will project figure 1 0 on the x-axis and put the result in figure 2 0 CALL HPROJ(2,3,0,4,1,10,10,IERR) will put the content of x-bin no 10 in figure 4 1 --- - ---- ---- - ---- ---- ---- ---- 3) CALL HOPER(IOP,A,IFG1,INR1,B,IFG2,INR2,IFG3,INR3,IERR) ---- With this subroutine it is possible to do six operations on two histograms (with figure numbers IFG1 INR1 and IFG2 INR2) and the result will be put in histogram IFG3 INR3 (which will always be a weighted histogram!) IOP=1 means A*Hist1 + B*Hist2 will be put into Hist3 IOP=2 .. A*Hist1 - B*Hist2 .. .. .. .. .. IOP=3 .. A*Hist1 * B*Hist2 .. .. .. .. .. IOP=4 .. A*Hist1 / B*Hist2 .. .. .. .. .. IOP=5 Same as IOP=4 except the way errors are calculated, IOP=4 assumes distributions are uncorrelated using relative errors whereas IOP=5 uses efficiency errors (corresponding to the EFF-operation in GEP explained in the GEP-manual on pp 104-105). IOP=6 means averaging of two histograms: the content of the resulting histogram is (A*w1*sigma2+B*w2*sigma1)/(sigma1+sigma2) IERR is the error code, which will be larger than 0 if e. g. Hist1 is non-existent or if Hist3 already has been created. -- ---- ---- ---- ---- 4) CALL HISUM(IT,IFGI,INRI,IFGO,INRO,IERR) ---- Sometimes it is convenient to integrate the bin-contents of histograms; a task which this subroutine is designed for. IT is set to either 1 which means integration from the left, or 2 which integrates from the right-hand side of 1-dimensional histograms (only 1-dim!). This routine 1 Part 1 - 22 - 8. Other operations with figures _______________________________________________________________________ could (must) be further developed if it's of any use. IFGI,INRI figure numbers of input histogram IFGO,INRO figure numbers of output histogram (non-existing before call) IERR error code, larger than 0 if an error occurred. -- ---- ---- ---- ---- 5) CALL HAVER(IP,IFG1,INR1,IFG2,INR2,IERR) ---- Create profile figure IFG2,INR2 of the type VEC(4) from 2-dim histogram IFG1,INR1 by averaging of X or Y bin slices. IP=1 produces profile as a function of Y (averaging along X axis) with errors of equal to sigma(X) IP=2 produces profile as a function of X (averaging along Y axis) with errors of equal to sigma(Y) IP=3 produces profile as a function of Y (averaging along X axis) with errors of equal to sigma(X)/sqrt(n) IP=4 produces profile as a function of X (averaging along Y axis) with errors of equal to sigma(Y)/sqrt(n) ---- ---- ---- ---- --- --- --- --- 6) CALL REBINH(IFG1,INR1,IFG2,INR2,NBX,NX0,NBY,NY0,IERR) ---- Change the binning of histogram (IFG1,INR1) and store the resulting one in (IFG2,INR2). NBX(NBY) is a number of x(y)-bins to be merged together starting from NX0(NY0): (NX0+1)...(NX0+NBX) ---> (1), (NX0+NBX+1)... (NX0+2*NBX) --> (2) etc. ---- ---- ---- ---- 7) CALL MERGEF(IFG1,INR1,IFG2,INR2,IERR) ---- Merge two figures and store the result in the first of them. IERR > 0 if figures mismatch. Applied both to histograms and vectors. ------ --- --- 8) CALL HPEAK (DATYPE,IFG,INR,NP,RP) -- -- Returns 2-dimensional array of peak parameters RP(5,5) for a single 1-dimensional histogram (DATYPE,IFG,INR). DATYPE can be either 'HS' or 'HSW'. NP - number of peaks found (NP<=5) NP=-1 if 1d historgam IFG,INR was not found in a current area RP(1,I) - peak abscissa, I=1,...NP RP(2,I) - sigma RP(3,I) - integral (total content under peak) RP(4,I) - peak ordinate RP(5,I) - background-to-signal ratio: Y_bgr(X_peak)/Y_peak(X_peak) 8.2 Target area --------------- By default a target figure is created in the same LOOK area. In order to create resulting figure in a different area the following call must be used before call a histogram operation: ------ ----- CALL TAREA(ARNAME,IVERS) set target area for resulting figures 1 Part 1 - 23 - 8. Other operations with figures _______________________________________________________________________ The target area is disabled by another call: CALL DTAREA keep target figures in the same area For example, the following code: CALL SAREA ('Source',0) ..... CALL HPROJ (1,10,1,11,1,0,0,IERR) CALL HPROJ (2,10,1,12,1,0,0,IERR) CALL TAREA ('Profiles',1) CALL HAVER (1,10,1,10,1,IERR) CALL HAVER (2,10,1,10,2,IERR) CALL HAVER (3,10,1,20,1,IERR) CALL HAVER (4,10,1,20,2,IERR) CALL DTAREA CALL HOPER (4,1.0,11,1,1.0,12,1,13,1,IERR) will produce figures (11,1),(12,1) and (13,1) in area 'SOURCE',0 figures (10,1),(10,2),(20,1),(20,2) in area 'PROFILES',1 8.3 Vectorisation of non-vector objects --------------------------------------- ---- ---- ---- ---- CALL VECDF(IFG1,INR1,IFG2,INR2,IERR) vectorise a figure (convert ---- into vector type) IFG1,INR1 a source figure of type HS,HSW,HD,HDW,XY or XYZ IFG2,INR2 a target figure of type IERR error code, if IERR>0 something went wrong. The dimension and content of the resulting VECtor is determined by the following table +---------+----------+------------------------------------+ | Source | Target | VEC(1) VEC(2) VEC(3) VEC(4) | +---------+----------+------------------------------------+ | HS,HSW | 4-VEC | X-bin Content Bin/2 Error | | HD,HDW | 4-VEC | X-bin Y-bin Content Error | | XY | 2-VEC | X-entry Y-entry - - | | XYZ | 3-VEC | X-entry Y-entry Z-entry - | +---------+----------+------------------------------------+ 1 Part 1 - 24 - 9. Fitting _______________________________________________________________________ 9. Fitting ========== LOOK allows to fit one- and multi-dimensional distributions (histograms and vectors) both in batch and interactively. Four different fitting methods are supported, based on the FUMILI (I.Silin, Dubna, 1961) and MLFIT (V.Blobel, Hamburg, 1971) programs adapted to LOOK. In case of FUMILI chi2 method, a full covariance matrix describing the correlations between the data points, may be taken into account (FUMILI extension by A.Fedotov,1996) Limitations: maximum number of free parameters in the approximating function is 50. Maximum number of arguments is 10. In case of fitting XY or XYZ scatterplots, all errors are assumed to be equal, and fitting is performed for Y(X) and Z(X,Y) correspondingly. 4- and 6-vectors are treated according to the description in the section 2.2. In case of fit of data with a covariance matrix, maximun number of data points is 100. ---- --- --- ---- CALL LKFITM (MODE,NIT,EPS,NPTF) select fitting algorithm MODE = 0 FIMILI chisquare = 1 FUMILI likelihood = 2 MLFIT chisquare = 3 MLFIT poisson NIT max number of iterations per one LKFIT call EPS relative precision required for the fitted parameters NPTF number of points for the function representing fit result This call is optional. As a default a FUMILI chisquare method is used with NIT = 20, EPS = 0.005, NPTF = 100. The following two calls can be used to fit LOOK figures either by user functions, or by the standard LOOK functions. ---- --- --- --- ---- ---- ----- ---- CALL LKFIT (NEXT,IFG,INR,ITG,XMIN,XMAX,UFUNC,NPAR,IERR) ---- ---- --- --- --- ---- ---- CALL LKFITY (IFG,INR,ITG,XMIN,XMAX,TEXT,IERR) ---- NEXT = 0 (irrelevant for LKFITY) for the first call for the figure > 0 next calls to the same figure (continue fit without init) IFG first and INR second identifiers of the figure to be fit ITG second number of the same IFG where to store fit result (if ITG < 0, or ITG = INR then target sub-figure is not created, otherwise it is created as a VEC in NPTF points) XMIN min limit for the argument, in case of multi-dimensional distribution applied only to the first argument XMAX max limit for the argument, in case of multi-dimensional distribution applied only to the first argument If XMIN.GE.XMAX then full range of the argument is used. UFUNC user function name NPAR number of free parameters in UFUNC TEXT text expression for the standard function (e.g. 'G+P1*E') Standard functions supported by LOOK fitting are: G gaussian: PAR(1)*EXP(-0.5*((X-PAR(2))/PAR(3))**2) E exponent: EXP(PAR(1)+X*PAR(2)) Pn polinom: (0 <= n <= 49) and any arithmetic expression built out of them (+,-,*,/ operations are allowed) IERR = 0 in case of successful fit = 1 warning: too many data points, truncated but fit is done = 2 not existing figure (IFG,INR) = 3 wrong figure type (e.g. n-tuple or VEC of dimension > 10) = 4 empty figure (or NEXP < NPAR) = 5 wrong number of parameters NPAR (e.g. NPAR > 50) =-1 wrong TEXT expression 1 Part 1 - 24a - 9. Fitting _______________________________________________________________________ The following two routines, LKFITC and LKFTYC, differ from the previous two LKFIT,LKFITY by additional parameters IFGC,INRC,C,IGNCOR and allow to fit the correlated data whose errors and correlations are described by a full covariance matrix. These routines may be called only for the FUMILI chi2 method (MODE=0). Note that errors of data points will always be taken from covariance matrix instead of the errors contained in the main figure IFG,INR . ---- --- --- --- ---- ---- ----- ---- CALL LKFITC (NEXT,IFG,INR,ITG,XMIN,XMAX,UFUNC,NPAR, ---- ---- - ------ + IFGC,INRC,C,IGNCOR,IERR) ---- ---- --- --- --- ---- ---- ---- ---- - ------ CALL LKFTYC (IFG,INR,ITG,XMIN,XMAX,TEXT, IFGC,INRC,C,IGNCOR,IERR) ---- IFGC determines one of three possibple ways of providing the covariance matrix: > 0 : cov matr. is in vector (IFGC,INRC) (C is dummy in this case) The vector should have dimension NVEC >= NDATA and # of entries (rows) >= NDATA , where NDATA is the number of data points in the non-truncated (by XMIN,XMAX) figure (IFG,INR); the cov matrix must be in rectangular form COV(I,J) = VEC(ICOL,IROW) = 0 : cov matr. is in C in rectangular form (INRC is dummy) C should be a 2-dim array with dimension of (NDATA,NDATA) where COV(I,J) = C(I,J) =-1 : cov matr. is in C in triangular form (INRC is dummy) C must have the length of NDATA * (NDATA + 1) /2 and contain the info in the folowing order (N = NDATA): COV(1,1), COV(2,1),COV(2,2), COV(3,1),...,COV(3,3) ........................ COV(N,1) , ... , COV(N,N) INRC second identifier of the vector with covariance matrix if IFGC>0 , otherwise dummy C the data covariance matrix in rectangular form if IFGC=0, or in triangular form if IFGC=-1, otherwise dummy (IFGC>0) IGNCOR flag telling whether the correlations (the non-diagonal elements of the covariance matrix) have to be ignored or not (ignoring may be useful in order to understand the net effect of correlations): =0 : use full covariance matrix =1 : ignore the non-diagonal elements IERR additional error conditions (in addition to those described above for LKFIT,LKFITY): = 6 vector (IFGC,INRC) does not exist or has a wrong size = 7 buffers in LKFDCi too short for cov. matrix = 8 IFGC < -1 = 9 problem with the invertion of cov. matrix 1 Part 1 - 24b - 9. Fitting _______________________________________________________________________ ---- --- ---- ---- CALL LKFPAR (NPAR,PAR,PMIN,PMAX,IERR) set initial values and limits ---- for the parameters; not needed for the gaussian fit by LKFITY NPAR number of free parameters. If NPAR >0 then max/min limits are taken into account, otherwise they are ignored, and ABS(NPAR) is used as a number of parameters PAR (NPAR) array containing initial values for the free parameters PMIN(NPAR) array containing minimal limits for the free parameters PMAX(NPAR) array containing maximal limits for the free parameters If PMIN(i)=PMAX(i), or PAR(i)PMAX(i) then parameter PAR(i) will be fixed during the fit. IERR = 0 ok = 1 wrong number of parameters CALL LKFITP print fit result CALL LKFGET (IFLAG,S,NP,NPAR,PTIT,EFIT,CFIT) get complete fit result ----- - -- ---- ---- ---- ---- IFLAG = 1 fit has converged = 0 iteration limit reached =-1 fit has not converged (for MLFIT) =-2 fit terminated due to the infinite errors (for FUMILI) =-4 error: Y<=0 for the Log(Y) (in the likelihood method) S objective function value (chi**2 or ML function) NP number of experimental points used in the fit NPAR number of the fitted parameters PFIT array of the fitted parameters EFIT array of the errors CFIT covariance matrix in a triangle form, i.e. array of the dimension NPAR*(NPAR+1)/2 CALL LKFTXT store a short form of the last fit results into the figure text with IPOS = 1000 + INR where INR is the second number of the fitted figure ; this info may be displayed later in an interactive LOOK session inside the figure display. The names of parameters, as defined by CALL LKFDPN (see below) are stored as well. ---- ------------------------ CALL LKFDPN (IPAR, 'nam_1 nam_2 ... nam_n') an optional (re)assignment of names nam_1 - nam_n to fit parameters ## IPAR - (IPAR+n-1) (n .ge. 0), where nam_i is a character string (without blanks inside) of length up to 15 characters, adjacent names separated by blanks. The defined names may be stored by CALL LKFTXT (see above) together with the fit results, and displayed later in an interactive LOOK session. The parameters with non-defined names will then appear with the default names P1, P2, ... . Example: CALL LKFDPN (3, 'Constant Slope') -- assign the names 'Constant' and 'Slope' to parameters ## 3,4 Special value: IPAR=0 => back to default names (P1,...) for ALL parameters. 1 Part 1 - 25 - 9. Fitting _______________________________________________________________________ The following example illustrates how to use LOOK fitting in batch mode and how to write the user function for the fitting. Note, that free parameters must be transferred to the user function via the predefined COMMON /FITPA/ (50). EXTERNAL FITFUN PARAMETER (MP=5, NDIM=MP*(MP+1)/2) REAL PAR(MP), PMIN(MP), PMAX(MP), ERR(MP), COV(NDIM) ... * fit two-dim histogram (ifg,inr) in a full range * ----------------------------------------------- CALL LKFPAR(3,PAR,PMIN,PMAX,IERR) NEXT=0 10 CALL LKFIT (NEXT,IFG,INR,-1,0.,0.,FITFUN,4,IERR) IF(IERR.LE.1) THEN CALL LKFITP ELSE WRITE (*,*) 'IFG,INR,IERR(LKFIT) =', IFG,INR,IERR GOTO 20 ENDIF * * (optionally) define parameter names, store the fit results * as a text, assign again default names * CALL LKFDPN(1,'Constant Exp_X Exp_Y') CALL LKFTXT CALL LKFDPN(0,' ') * * print fit results * CALL LKFITP * * get fit results * CALL LKFGET(IFLAG,S,NEXP,M,PAR,ERR,COV) .... NEXT=NEXT+1 IF(IFLAG.EQ.0 .AND. NEXT.LT.5) GOTO 10 * * fit figure (jfg,jnr) by gauss and store result in (jfg,jnr+1) * ------------------------------------------------------------- 20 CALL LKFITY (JFG,JNR,JNR+1,0.,0.,'G',IERR) * * fit figure (jfg,jnr) by gauss with the linear background; * note, that the order of parameters in PAR(i) is defined by the * order in the expression (i.e. G+P1 is not equivalent to P1+G); * we need 5 parameters: p1+p2*X + p3*exp(-0.5*((x-p4)/p5)**2) * ------------------------------------------------------------- CALL LKFPAR(5,PAR,PMIN,PMAX,IERR) CALL LKFITY (JFG,JNR,JNR+1,0.,0.,'P1+G',IERR) CALL LKFITP * .... FUNCTION FITFUN(ARG) * array of arguments * (the declaration can be omitted in case of 1-dim functions) REAL ARG(*) COMMON /FITPA/ P(50) * for two-dim histogram: X = ARG(1) Y = ARG(2) FITFUN = P(1) * (X**2+Y**2) * EXP (-P(2)*X) * EXP(-P(3)*Y) END 1 Part 1 - 26 - 11. Input/output of distributions _______________________________________________________________________ 10. LOOK random number generator ================================ LOOK contains a simple portable random number generator. In spite of there are only 714025 different values (spacing = 1.4E-6), the period is effectively infinite. ---- R = RNLOOK (IDUM) For IDUM < 0 the function is initialized or reinitialized. 11. Input/output of distributions ================================= Input/output operations within LOOK are done in a machine-independent way using F-package. Therefore, all possibilities supplied by F-package are automatically supported, including remote access to the files via networks. --- ------ ---- CALL LSTORE (LUN,DSNAME,MODA) store (write) LOOK figures on the output file --- ---- CALL LSTORB (LUN,MODA) (for BOS users) store (write) LOOK figures on the output file whose name is taken from BOS bank LKOUT ------ ---- ---- CALL LREAD (DANAME,MODA,MODC,IER) read data from input file and --- fill LOOK data base LUN = unit number DSNAME = full dsname for the file (or blank: ' ' for the opened file) DANAME = symbolic data set name (see F-pack Manual) MODA = 0 process (read or write) all areas = 1 process (read or write) current area only (for read: area name and version will be defined from input file) =-1 read current LOOK area from the input (area name/version will not be changed - analog of interactive KEEPAREA); irrelevant for LSTORE MODC = 0 clear LOOK area before reading = 1 add new input data to existing figures IER > 0 FPACK error when reading < 0 end-of-file condition = 0 no error Remark. For the backward compatibility former LUTPUT and LWRALL are still supported, but excluded from the Manual. The LSTORB call is designed for BOS users who initialise BOS and read text banks with BREADC . They have then a possibility to provide in the input stream a steering card LKOUT 'filename' which is read in by BREADC and recognized by LSTORB afterwards. Such a mode of work may be advantageous when one runs the same job many times and does not wish to change the code every time, then only the steering card has to be modified. If output file DSNAME already exists, the old content of the file will be overwritten; this mode may be used if the space of the existing file is sufficient for the new output. 1 Part 1 - 27 - 11. Input/output of distributions _______________________________________________________________________ No DD card is necessary. Openning of the output file is done internally unless it has been already opened before (then CALL LSTORE will just write data on the file). For the non-standard OPEN however (like keyed access or remote files) the actual openning must be done before, using CALL FPARM (STATEMENT) (see F-pack Manual). In this case DSNAME = ' ' must be used in the LSTORE call. For the reading OPEN m u s t always be done by user before CALL LREAD A simple utility routine allows direct copy of complete LOOK files: ------ ------ CALL LCOPYF (NAMINP,NAMOUT) NAMINP = symbolic name for input file (must be opened before) NAMOUT = symbolic name for output file (must be opened before) In the interactive mode of LOOK, the histograms and vector sets are obtained by the following commands (given here for unit 11): a) open input file either by FPARM 'open unit=11 file=file_name' or by DATASETX 11 1 1 'file_name' b) after successful open the file is read by one of the commands: LREAD 11 LRALL 11 LRNEXT 11 Further read options are available as described in the next Part (see keywords ADDAREA, KEEPAREA, LOADFIGS, LOADROWS). 1 Part 1 - 28 - 12. Memory and initialisation _______________________________________________________________________ 12. Memory and initialisation ============================== As it was said in "Introductory remarks", LOOK has been designed so that the user usually does not have to care of the initialisation of the system. It is true if the amount of the memory needed to store all the histograms and vectors, does not become too big and does not exceed the default limitations, set at the compilation of the LOOK library. These limitations may be changed by the user. Before discussing how it can be done, consider the process of memory usage by LOOK. A "primary" storage of the internal LOOK data base resides in COMMON/COMIC/IC(NWLOOK) . Its size is set usually to at least 1 megabyte (NWLOOK=250000) at the moment of creation of the LOOK library. At the run time, this storage is used first to put the newly created LOOK objects and/or those read-in from an input file. If the memory is filled up, LOOK tries to extend the data base using DISK SPACE: direct-access files are created automatically which form the "secondary" storage. The extension process is basically hidden from the user: all LOOK routines continue to work as if nothing has happened, except for, may be, some slowing-down of the execution speed. The size of each file is about 4*NWLOOK bytes. Up to five files may be opened, thus increasing the available memory by factor 5 with respect to the initially available NWLOOK words. Other characteristics of these files are very machine-dependent. On UNIX platforms, the files are created in the current working directory, therefore, the user has to ensure that the necessary free space is available there. On some platforms, the files are opened in SCRATCH mode such that they are automatically deleted by the system upon the completion of the program. If not, it is the user's task to delete them later. In the latter case, the user has to find out what are the default names of the direct-access fortran files (UNIT=35,36,37,38,39) for the machine in use. Thus, the NWLOOK parameter governs the size of both the primary and secondary memories, and determines whether the secondary one (disk files) will be invoked or not at all. In order to increase the total size of LOOK memory, or to prevent the usage of disk, the user has to add the following TWO LINES into his/her MAIN program: COMMON /COMIC/ IC(NWLOOK) . . . . . . . . . . . . . CALL INITLB (NWLOOK) initialise the LOOK memory of length NWLOOK > default value; the NWLOOK is the length IN WORDS, while the length IN BYTES is 4*NWLOOK. The call must be placed before any call to other LOOK routines. For safety, it is better to make it the very first CALL in the program. Example: COMMON /COMIC/ IC(500 000) -- initialisation of . . . . . . . . . . . . . 2 Mb LOOK data base. CALL INITLB (500 000) Note, that the procedure of memory extension differs slightly in case of interactive programs -- see section "Main program..." of Part 3 for details. 1 Part 1 - 29 - _______________________________________________________________________ 1 Part 2 - 30 - 1. Program structure _______________________________________________________________________ Part 2 EXECUTION OF INTERACTIVE PROGRAMS ****************************************** 1. Program structure ==================== In this part of the manual the operation of interactive programs based on LOOK is explained. Since LOOK is a kernel system, it is used in different applications; the basic system itself can also be operated directly and provides functions related to the LOOK data base for distributions (histograms and vectors). Interactive LOOK programs are usually steered by commands, typed in at the keyboard or, if appropriate, it is steered by locator (mouse) input. A typical command is FIGURE 1 3 - 5 which is the request to get a plot of figures 1, 3, 4 and 5. To get a magnification of a subarea, the operator has to type in the command ZOOM (or shorter: O); the two edges defining the subarea are then defined by locator input. In some machine dependent versions of LOOK keyword input for some of the commands is possible via the locator; this description is for the general version, which uses GKS options only. LOOK has a modular structure, which allows to combine user display programs with the standard display programs. Additional keywords are defined in such applications and can also be defined during an interactive session. This description is restricted to the keywords defined in the kernel, and to the general rules, valid for all keyword operations. The main steering routine of the LOOK system is SUBROUTINE LKUSER where all LOOK based applications must be called from. A detailed explanation of the code organization is given in Part 3 of this manual. The standard stand-alone version of LOOK contains also interface to the BOS system and a few commands related to BOS. These commands are not a part of the kernel (which does not use BOS), but they are explained in this manual too. After input of the command STOP any LOOK-based program will stop after closing GKS. Remark. A special version of LOOK running on X11 within the MOTIF environment does not use GKS. Low level graphics then is done using X11 primitives. This provides more powerful user interface which, however, is not described here. 1 Part 2 - 31 - 2. Display modes _______________________________________________________________________ 2. Display modes ================ LOOK distinguishes between the display of graphics and the display of text to the screen (in some machine-dependent installations there may be in fact two separate windows for graphics and for text). After input of a command by the operator the program can make output in the graphics mode or the text mode. The last graphics display can be repeated by giving the command GRAPHICS (or short: GR), provided the data to be displayed are still available. Text display mode is used for listings of tables etc. LOOK has a storage for several 100 lines of text; the text display is requested by the command TEXT (or short: TX); the operator may then scroll forward and backward in the text. A program can also make graphics and text output in parallel; in this case the priority is given to the graphics mode, but the text is stored internally and can be inspected by the TEXT command later. There is a header box in the graphics display, with some text defined within the program on the left, and the date on the right. The text for the header box and the font used for graphics can be defined by the user. Display of the header box can be switched off and on. +---------------------------------------------+ | | | | | | | display area for: | | | | graphics | | text output (80 chars/line) | | | | | | | | | |---------------------------------------------| | left message area right | |---------------------------------------------| | echo area of string input | +---------------------------------------------+ Figure 1: The division of the display screen into the display area for text and graphics output, the message area, and the echo line for command input. The graphics display can be directed to a hardcopy or meta file unit. On the screen there are, in addition to the display area for graphics and for text output, two text lines. The text line on the bottom shows the command, as it is typed in. The message area has a left and right part, it can display messages to the operator e.g. on the program status and it is used in dialogues. In the left part it usually shows, after a command input, the previous command. A command shown in the message line can be executed again by hitting then enter/return key. If something else is shown in the message line, the previous command will be shown after hitting the enter/return key; another hit on the enter/return key will execute it. Text in the echo line and the message area can be erased and modified without modifying anything in the large display area. 1 Part 2 - 32 - 3. Start of LOOK-programs _______________________________________________________________________ 3. Start of LOOK-programs ========================= After the start of the LOOK program it will ask the operator for the identifier of his work station (display/keyboard). Once this information has been provided, LOOK opens GKS and switches to input of text via GKS. The interpretation of terminal keys depends on the installation. In GKS one of the keys should have the meaning "break", which is used for example to suppress output to the text screen with many lines. In LOOK the operator may use the command break (in five characters) instead, if the "break" key is unknown. There may be a special key for locator input, that has to be known to the operator. A few histograms are filled by the command FILLSOME that may serve as material to try out some of the LOOK commands for graphics. The procedure to start a LOOK program depends on the local installation, a few examples are given below. 3.1 Central IBM (MVS) at DESY ----------------------------- A LOOK program is started from NEWLIB using the GKS Clist by entering the command ((GKS)) yourlibrary(member) for a load module on a library of the operator, or, as usual, with the library and member in quotes for a foreign library, for example ((GKS)) 'HERA01.H1LOOK.EXEC(LOOK)' (H1 Clist command: LOOK) ((GKS)) 'HERA01.H1LOOK.EXEC(H1LOOK)' (H1 Clist command: H1ED) For the two-terminal mode, one has to add in the same line GA ganumber (see IPS manual). Possible terminals are: IBM Graphic Terminal 3179 G (or similar) Tektronix in 2- or 1-terminal mode. Atari HP x-window terminals FALCO 3.2 Apollo workstations at DESY ------------------------------- The LOOK program is started by the command look from your current working directory. If you are running LOOK in the Apollo display manager environment, you should have two configuration files which are used by LOOK: - lookwindows.config (optional) provides a proper arrangement of several windows. The program searches for a file with this name first in your corrent working directory and then in your home directory. If such a file is not found, default values will be used. - gks_workstations.config necessary for GKS to identify the workstation type. 1 Part 2 - 33 - 3. Start of LOOK-programs _______________________________________________________________________ If you are using LOOK in the X window environment, you have to follow the following staps before you can start the first session: a) edit your file .profile in your home directory. Add the following lines: GKS_ROOT=/cern/gks/new export GKS_ROOT . gral_ftn Please note, that UNIX is case sensitive! b) create subdirectory with the name cgi_conf in your home directory and copy the configuration files: cp //h105/usr/users/gerhards/cgi_conf/* cgi_conf c) enter . .profile to execute your LOGIN profile (like starting a CLIST on the IBM) Now you are ready to start your LOOK session. 3.3 Work Group Servers at DESY ------------------------------ The default version of the LOOK program is started by the command look issued from an X-terminal or its equivalent. Other commands may be also used, like look_XXmb where XX=01,16,... determines the size of LOOK memory. One can see all the possible commands by typing ls /h1/bin/look* . LOOK starts, informs you about the LOOK version in use, and suggests you four different options for the size of the graphic window. You make your choice and type the corresponding number after the "LOOK>" prompt, followed by "Return key". A new window appears which will be used further to display mainly graphics. You will still need the first window (the start-up, or command window) to issue all your commands and to receive the most of text replies of LOOK. Therefore, you will make your life easier, if you resize now the start-up window and move the both windows so that they do not overlap. The session is established now, and you can type your commands making LOOK work. The session is finished, as always in LOOK, by typing the command qq, after which the graphic window disappears and you are back to the unix shell prompt in the start-up window. About commands. You always type them after the "LOOK>" prompt. The commands may be up to 3 lines long. A command is sent to LOOK whenever you hit the "Return" key. Your earlier commands are kept in a stack, and are reachable via up- and down- arrow keys, and can be edited. When editing a command, all zsh-commands to edit a command line, are applicable here as well: cntr-a, cntr-e, cntr-d, cntrl-b, cntr-f etc. The filename-completion mechanism is also active, which means that whenever you have typed a beginning of a file name, pressing the TAB key will complete the filename automatically (provided the completion is unique, otherwise the next pressing the TAB will show you all the possibilities). Two strongly recommended commands, which make a LOOK session much more friendly: 1 Part 2 - 34 - 4. Commands and keywords _______________________________________________________________________ 1) NOTERASE 1 : protects the graphic window from the erasure caused, e.g., by moving the window, iconising it, screening its content by another window. 2) MESSAGES 1 1 : causes a duplication of so called LOOK messages in the start-up window. Without the command, these messages appear only in the "message line" of the graphic window. These commands are good candidates for issuing in the beginning of any LOOK session (it would be also a good idea to place them into your start-up macro file looklogi.macro, which is always executed in the beginning of a session). 4. Commands and keywords ======================== 4.1 Keyword steering -------------------- Interactive LOOK program execution is steered by commands like SX 10.0 50.0 FIGURE 17 SAREA 'Dst-Analysis' 2047 STOP given at the keyboard. The commands consist out of so called keywords (SX, FIGURE, SAREA and STOP in the example), of numerical values and of text within quotes. The command text given by the operator is shown in an echo line at the bottom of the display area. The text is entered by hitting the enter/return key, and moved to the message line, above the echo line. A command shown in the message line can be executed again by hitting then enter/return key. If something else is shown in the message line, the previous command will be shown after hitting the enter/return key; another hit on the enter/return key will execute it. Earlier commands are shown in the text display after entering 0. A previous command can be moved into the message line by entering a negative number and executed by hitting enter again. Keywords can have several different functions, so one can distinguish different types of keywords. As a guide line the following notation for keyword types is used: a - action keywords (performs certain action immediately) d - keywords for dialogue (additional informations from a dialogue is necessary) p - passive keyword without parameters (part of a complex command) s - keyword to set parameters (used to define a set of parameters, which remain valid until the next definition via the command) 4.2 Keywords and their parameters --------------------------------- Keywords are composed out of alphabetical characters A...Z, in addition special characters are possible except the special characters +-.,'\&=; digits are possible, but the first character has to be non-numeric. There is no distinction between upper and lower case characters, all lower case characters are converted to upper case characters (thus the input of STOP and Stop and stop is equivalent). 1 Part 2 - 35 - 4. Commands and keywords _______________________________________________________________________ Several numerical and one text parameter can be assigned to a keyword. As a general rule, if a keyword is entered without parameters, then the previous values of the parameters remain assigned. If only a part of the numerical parameters are given, then for the omitted parameters a value of zero is assumed. Values of numerical parameters may be signed and may contain an exponent with a character E (or e). Blanks and commas (,) are separators. There is no distinction in input between the integer and the floating point representation (thus the input of 10 and 10.0 and 1.0E1 is equivalent). If at least one numerical value is given after a keyword, all unspecified numerical parameters are set to zero. Text has to be enclosed in quotes ('). Within text upper and lower case characters are different characters (in special applications however lower characters are converted within LOOK automatically to upper case characters, if only these are meaningful in the context). Quotes within text are not possible ( '' is ignored). Leading and trailing blanks within text are kept. If values (numerical and text) are given in a command, they are stored immediately under the keyword, which is to the left of the numerical values. 4.3 Keywords and actions ------------------------ Keywords in a command may trigger a certain action (type a in the notation above). The keyword FIGURE triggers the drawing of a figure, and the keyword STOP will stop the program. In contrast the keyword SX however will not trigger any action, it may be just considered as a name for the numerical parameters, which define the scale on the x-axis; these numerical values are used, when a figure is drawn (type s keyword in the notation above). A command has to start with a keyword; text and numerical values given in a command are stored under the keyword, which is to the left of the values. A separator (blank or comma) is necessary between a keyword and a numerical value or text within quotes. 4.4 Complex commands with multiple keywords ------------------------------------------- More than one keyword can be given in one command, for example SX 10.0 50.0 FIGURE 17 is a valid and meaningful command; the numerical values 10.0 and 50.0 are stored under the keyword SX, the numerical value 17 is stored under the keyword FIGURE. Only one of the keywords, FIGURE, triggers an action (drawing of a figure). Thus commands with multiple keywords are valid, the same keyword however may appear only once in a command. The actions triggered by keywords are, if there is more than one keyword with an action, executed not in the order of the keywords given in the command, but in an order specified within the program. Thus some combination of keywords may be meaningful, other may not. 4.5 Multiple commands ---------------------- Several commands, separated by semicolons (;), can be given in one command line. An example is the command line RETURN; FIGURE 17 which means the following: the first command is RETURN and the interactive subroutine LOOK will return to the calling program; at the next entry to LOOK the second command, FIGURE 17 will be executed and figure 17 will be displayed. Using multiple commands a definite order of the execution can be forced by the separation of commands by semicolons (;). If the above command would have been typed without the semicolon, then it may happen, that the figure 17 is drawn first, and then the program returns. When using multiple commands operator has to remember, that only those "command units"(i.e. set of keywords between semicolons) will be stored in the graphic command buffer (and thus can be repeated by the GR or PL commands) which contain at least one graphics related action. 1 Part 2 - 36 - 4. Commands and keywords _______________________________________________________________________ 4.6 User-defined keywords ------------------------- The user may define new keywords, either by the use of the ALIAS keyword or by the use of commands with the = sign. Keywords may consist out of up to eight characters. By a command of the type newkeyword ALIAS oldkeyword the user may define a new keyword as an alias of another keyword. The main application is to simplify often used (long) keywords by the definition of new (short) keywords. For example the keyword F is defined by the command F ALIAS FIGURE as an alias of FIGURE; thus commands F 17 FIGURE 17 will have the same effect. A whole command line (with or without semicolons) may be abbreviated by a user-defined new keyword. The assignment of the command line to the new keyword is done using the = sign in commands like newkeyword = command line The command RF = RETURN; FIGURE 17 for example defines the new keyword RF. If afterwards the command RF is given, the content of the above line after the = sign will be added internally for execution. User-defined keywords may again be used in the definition of new keywords etc. 4.7 Continuation of command lines --------------------------------- Commands may be too long to fit into one input line. If the character & is given as the last character in a command, a continuation line is expected. The total length of an input line may be 80 characters. The character & should not appear within a numerical value. It may appear within a text string; if a text string with characters & is displayed on the screen, the character & is treated as an end-of-line character, and start a new line during listings. If the character & has been forgotten in a line, the continuation line may start with the character &. 4.8 Execution of command macro-files. LOOK login macro ------------------------------------------------------ LOOK supports a helpful possibility to execute a special macro files, containing different commands, which can (must) be prepared by user in advance. Presently this command file is a simple text-file, containing usually one command per line. Continuation lines are accepted as well for long command text (see remarks below). The command EXEC 'name' asks LOOK to execute a set of commands stored in a command-file 'name'. Note, that naming convention may be different for different installation. An example for DESY IBM: 1 Part 2 - 37 - 4. Commands and keywords _______________________________________________________________________ The following macro file 'F99ABC.LOOK.MACRO' can be executed by the command EXEC '.f99abc.look' *------------------------------------------------------------------- * create your own commands * Q1 = $ left lower quadrant $ ZONE 0 0.5 0 0.5 Q2 = $ left upper quadrant $ ZONE 0 0.5 0.5 1.0 Q3 = $ right upper quadrant $ ZONE 0.5 1.0 0.5 1.0 Q4 = $ right lower quadrant $ ZONE 0.5 1.0 0 0.5 TRIGGER = TSE Q2; RA TRIG Q3; SC COAR TRIG DOWN BW=DBEMC BREF Q1;DBPC BREF Q2 NOHEAD;DTOF 0 BREF Q3;DTOF 1 BREF Q4 SCAN = BREAD; TRIGGER * * connect event BOS.FPACK file and DDL ASCII-file * DATASETX 1 9 1 'HERA01.INLINE.V10600' DATASETX 7 4 1 'HERA01.H1DDL.V10600' DMBKIN 7 BREAD 1 *------------------------------------------------------------------- Important remarks. - a '*' or a '#' in the 1-st column indicates a comment line, non significant leading and trailing blanks are ignored; - if the last nonblank character in the line is & then next line is assumed to be a continuation. Total length of the command (after compression) must not exeed 1024 characters, otherwise command string will be truncated and corresponding message will appear; - it is not recommended to use EXEC command itself inside a macro (recursion). If however, an EXEC command is met, the execution is switched to the new command file, and the rest of the first file will not be executed. - several commands per line are possible exept: LOCK, UNLOCK, DROP and definition commands (i.e. containing '='); - a special command END will stop the execution of the macro file, otherwise it is executed until end-of-file. For DESY IBM installation a concatenation of userid is done internally, and extension MACRO is always added. In order to use complete dataset name a fullstop must be as a first nonblank character in the EXEC text parameter. For example, EXEC 'look' will execute your file 'userid.LOOK.MACRO' EXEC '.f99abc.foreign' will execute file 'F99ABC.FOREIGN.MACRO' At the end of initialisation procedure LOOK tries to invoke a LOGIN MACRO where user may put, e.g., his favourite standard initialising commands. The macro is invoked in such a way as if the user has issued the command EXEC 'looklogi' . This implies the full name of the file to be USERID.LOOKLOGI.MACRO in case of IBM/MVS, and just "looklogi.macro" on UNIX platforms. Nothing happens if such file does not exist. On UNIX platforms, the file is first searched for in the current directory, then, if not found there, -- in the HOME directory. All commands entered by operator during LOOK session are automatically saved in a special history file and can be used afterwards in a command files. History file is created and updated by LOOK, deleting is up to the user. The file name is always LOOK.HISTORY: IBM/MVS userid.LOOK.HISTORY IBM VM LOOK HISTORY A (i.e. stored on disk A) Apollo,SGI $HOME/look.history (look.history in home directory) VAX SYS$LOGIN:LOOK.HISTORY 1 Part 2 - 38 - 5. Standard LOOK keywords _______________________________________________________________________ 5. Standard LOOK keywords ========================= 5.1 HELP commands ----------------- HELP [keyword [keyword2 [...]]] (or H help information on the given keyword(s) is shown in the or MAN) text display. HELP without keywords will show a main LOOK HELP panel. HELPFILE 'filename' Changes the help_file name to be open for the on-line help from the default one to that specified if issued BEFORE any HELP REQUEST. After a help request has no effect. KEYWORDS all existing keywords are listed in alphabetical order. (or KS) ? 'item' show list of all defined keywords started with ITEM. ?? 'item' show list of all defined keywords containing ITEM. 5.2 Control commands -------------------- RETURN iret this keyword will cause return to the calling program. The argument LRET of LKUSER is set to ABS(iret) at the return. Depending on the logic in the LKUSER, LOOK may be enterred again later. STOP after the final dialog the workstation is closed and LOOK returns to the main program. The keywords END or QUIT may also be used giving the same effect. QQ the workstation is closed and LOOK returns immediately (or Q) (Quick Quit). SHELL [cmd] (under unix only) execute the shell command cmd. If cmd (or SH) omitted, the shell prompt appears; type `exit' in the end of the shell session to return to the LOOK prompt. Similar actions on other mainframes is performed by the commands: DESY IBM: NEWLIB cmd (or N), return to LOOK with QUIT/EXIT IBM VM: SUBSET (alias CMS), return to LOOK with RETURN VAX: SPAWN (alias SHELL), return to LOOK with LOGOUT Ex.==> sh ls -l .. : list long catalog of the parent directory sh : invoke the shell (your default one!) session sh zsh : open the `zsh' session 0 show previous commands - number move previous command into message line (will be executed by another enter) MANUAL Open look manual with a viewer in the startup window. Equivalent to `sh man look' on unix platforms. 5.3 Display modes ----------------- TEXT the text display is shown. By the commands F (forward), or (or TX) FF (forward to most recent line), or B (backward), or BB (backward to first line) the operator may scroll through the text. GRAPHIC the previous graphics display is shown again. (or GR) BGRCOL switch background colour between black and white (toggle) 1 Part 2 - 39 - 5. Standard LOOK keywords _______________________________________________________________________ FONT ifont_term iprec_term [ ifont_hardcp iprec_hardcp ] Define MAIN text fonts for the terminal and hardcopy device in graphics mode (defaults are -1 2 -1 2). The MAIN fonts are used to display almost all texts: headers, figure captions etc (the exception is statistics and peakparm info where AUXILIARY fonts are applied, see FONT2). ==> FONT ifont iprec : sets the same fonts for a terminal and hardcopy ==> FONT 0 : sets the default values The command USERFACT allows to change the text size. A font is characterised by two numbers : font number (ifont) and font precision (iprec). There are two groups of fonts : PostScript (PS) fonts iprec = 0 , ifont= -1 ... -13, ... GKS fonts iprec = 2 (0 and 1 are also possible, but not recommen- ded since the font version with iprec=2 is always better) ifont = -1 ... -13 basic GKSGRAL fonts ifont = -101 ... -113 like basic but italics ifont = -201 ... -213 like basic but monospaced ifont = -301 ... -313 like basic but monospaced, italics Note that the availability of different fonts depends on the GKS installation. Although the PS fonts look nice in ps-files, there is a problem with them that they can not be displayed on the terminal since GKS does not have correspondent drivers. Depending on the installation you see some replacement on the screen by a GKS font or even by a sort of a terminal font. You can avoid this arbitrariness by setting the fonts differently for terminal and hardcopy. The appearance of various fonts can be easily inspected with the SHOWFONT command. FONT2 ifont_term iprec_term [ ifont_hardcp iprec_hardcp ] Define AUXILIARY text fonts for the terminal and hardcopy device in graphics mode (defaults are -1 2 -1 2). The AUXILIARY fonts are used to display mainly the statistics and peakparm info inside figures. ==> FONT2 ifont iprec : sets the same fonts for a terminal and hardcopy device ==> FONT2 0 : sets the default values See FONT for general information about different fonts. The size of texts displayed with the AUXILIARY fonts can be changed with a FONTSCALE command. FONTSCAL F1_term F1_hardcp F2_term F2_hardcp Allows to change the sizes of main (Font1) and auxiliary (Font2) fonts for terminal and hardcopy by multiplying them by the specified correction factors. Defaults: 1. 1. 1. 1. Implemented so far only for the auxiliary fonts (Font2). Designed for usage in the situation when the font2 size is not correctly determined by the automatic procedure (due to deficiencies in GKS installation) and stat/peakparm info does not fit into a figure or is too small. ==> FONTSCAL F_term F_hardcp : sets the same corrections for main and auxiliary fonts ==> FONTSCAL 0 : sets default (no) correction 1 Part 2 - 40 - 5. Standard LOOK keywords _______________________________________________________________________ SHOWFONT [ 'text' ] if1 ip1 [ if2 ip2 [...]] Display a 'text' with specified fonts in a separate zone. Fonts are specified by ifont=if_i and iprec=ip_i . Defaults: 0 2 'ABCDijmz0159+@{]' o Example. SHOWFONT -2 2 -3 2 -6 0 -1 0 ; pl 3 allows to have a look at 4 indicated fonts both on the screen and in a ps-file (the appearance will be different!) SPECIAL CASES to display various FAMILIES OF FONTS: ==> SHOWFONT if -1 [if2 ...] where if=-1...-13 displays the family of 12 fonts with ifont = if , -100+if, -200+if, -300+if iprec = 2 , 1 ,0 By [if2 ip2 [...]] one may indicate fonts inside the family which should be NOT DISPLAYED (one can wish to do that for example on DESY SGI, where fonts ifont=-100+if1, iprec=0 lead to the corrupted ps-files) o Examples: SHOWFONT -4 -1 displays all the derivatives of the basic font -4 SHOWFONT -4 -1 -104 0 ; pl 3 the same both for the screen AND hardcopy but excluding font -104 0 ==> SHOWFONT if ip [if2 ...] where if=0 or -100 or -200 or -300 displays the family of 13 fonts with the fixed iprec=ip and variable ifont = if-i for i=1...13 With [if2 ...] one can again discard some fonts. o Example: LEFT SHOWFONT 0 ; RIGHT SHOWFONT 200 displays 13 basic ps-fonts (iprec=0, ifont=-1,...,-13) and 13 non-ps fonts with modification ifont->ifont-200 HEADER switch header box off/on (toggle type) FRAME switch frame box around figures off/on (toggle type) FTEXT3 'text' reset the default text for all figures in the position 3 from to 'text' (the initial value is 'Figure') MESSAGES ileft iright Switch off/on a DUPLICATION in the startup window of the left and/or right messages which are normally displayed only in the message line of graphic window. ==> ileft(iright) = 1/0 means left(right) mess. on/off Defaults are usually off-off (0 0). Switching ON is especially useful for debugging purposes when an error occurs during a macro execution or in a long yy procedure if an error message is overwritten by subsequent messages. The command has an effect only in installations with a separate (non-graphic) command window (unix platforms). The current status can be checked with the command OPTIONS along with the status of all toggle functions. 1 Part 2 - 40a - 5. Standard LOOK keywords _______________________________________________________________________ NOTERASE i Prevents the graphics window erasure resulting from moving the window or clicking to another one and the like at some installations. ==> NOTERASE 1 switches on the protection mechanism ==> NOTERASE 0 switches it off ( d e f a u l t) Protection is achieved by putting all the graphics output into a GKS segment. Therefore, the command should not be used in applications employing graphics segmentation for other purposes. FTEXTDRAW i Switches on/off (i=1/0) the display of fit results in a text form inside a figure. D e f a u l t = on . When several subfigures are displayed then the first occurrence of a fit text is drawn. The position and size of the fit text is controlled by PFTEXT command, the font -- by FONT command. Other related commands: FIT,FTEXTSTOR,FPARNAME. In batch mode the fit text is stored by CALL LKFTXT . GREEK i specifies type of coding of Greek letters : GKS or Postscript (PS). See Appendix 5 for encodings' tables . ==> GREEK 1 (d e f a u l t) -- GKS encoding. If current font is a PS one, the text will be automatically converted into the PS encoding (when plotting) ==> GREEK 2 -- PS encoding. If current font is a GKS one, the text will be converted into the GKS encoding (when desplaying or plotting) GREEK 0 -- no automatic conversion. The text will be displayed/plotted as it is producing sometimes unexpected results. GKSCOR i1 i2 i3 i4 i5 i6 i7 (intended mostly for experts) Switches on (when corresponding flags are non zero) various algorithms to correct for deficiencies of the GKS installation in DESY on unix platforms. GKSCOR 1 1 1 -4 1 1 1 : default for DESY unix platforms GKSCOR 0 0 0 -1 0 0 0 : default for other installations i1 > 0 : invokes an alternative method of positioning the right message based on an inquiry function i2 > 0 : concatenation point of a text is recalculated (terminals) i3 > 0 : correction to character width is applied for ps fonts (hardcopy) i4.ne.0 : if (terminal & ps font) replace the font by the GKS font with iprec=2, ifont=-abs(i4) i5 > 0 : correction to character height is applied for ps fonts (hardcopy) i6 > 0 : improves the precision of ps texts positioning on hardcopy by plotting each "word" in a text separately ("words" are text parts separated by blanks) i7 > 0 : switches an alternative algorithm of drawing numbers with exponents (along axes) which allows to treat correctly also ps fonts. 1 Part 2 - 41 - 5. Standard LOOK keywords _______________________________________________________________________ 5.4 Keyword handling -------------------- newkeyword ALIAS oldkeyword a new keyword is defined to be an alias of old keyword. In further commands both keywords are treated in the same way newkeyword = command line a new keyword is defined as an abbreviation of the command line, or the command text of an existing keyword is replaced (unless the keyword was locked). In further commands the command line is added to the input. DROP keyword keyword ... all information about the given keyword is dropped. Only unlocked keywords can be dropped. LOCK keyword keyword ... The keywords are locked against dropping or modification of command text, associated with the keywords. Keywords defined within the program are locked automatically. UNLOCK keyword keyword ... The keywords are unlocked, and may afterwards be dropped, or their command text may be replaced. LOOP nlp execute user defined command (or series of commands) nlp times. Explanation: defining LOOP = cmd1; cmd2; ... cmdN and then typing: LOOP n the commands cmd1, cmd2,..., cmdN are executed n times. All commands can be used in this way, exept LOOP itself. When used in multiple command, LOOP m u s t be the last of the commands. 5.5 Commands for text --------------------- SHEADR i 'text' definition of text for the header box(i=1 left; i=2 right) STEXT ifg ipos 'text' set text for figure ifg in position ipos interactively. Makes the same effect as CALL STEXT in batch (see Part 1). ipos = 1-5 are used for standard figure description, ipos = 6... are used for texts inside figure Some special characters can be used in text for restricted graphical editting (in LaTeX style): \g{txt} show txt with greek font \i{txt} show txt with italic font \_{txt} interprete txt as subscript \"{txt} interprete txt as superscript (The conversion table between greek and latin letters is given in Appendix). Up to 5 nesting levels are possible, for instance: \i{T\_{ij}\"{\g{a}}} All blanks within text exept leading and trailing ones are significant. Examples for different modes: -interactive: STEXT 1 6 'curve: A\_{i}e\"{-bt\"{2}}' -batch: CALL STEXT(1,2,'d\g{s}/dt(\g{m}b/GeV\"{2}') PTEXT xt yt size mode specify position (xt,yt) in world coordinates and relative size (w.r.t. normal figure text size) for the text inside figures (text 6 etc.). If mode = 1, then (xt,yt) are in the normalized coordinate system (0...1, 0...1). Default: 0 0 0.7 1 which corresponds to left upper corner. 1 Part 2 - 41a - 5. Standard LOOK keywords _______________________________________________________________________ PFTEXT xt yt size mode specify position (xt,yt) in world coordinates and relative size (w.r.t. normal figure text size) for the FIT TEXT inside figures . If mode = 1, then (xt,yt) are in the normalized coordinate system (0...1, 0...1). ==> Default: 0.7 0 0.4 1 -- corresponds to the right upper corner. The fit text is stored by FIT command interactively or by CALL LKFTXT in batch. Other related commands: FTEXTSTOR, FTEXTDRAW, FPARNAME, FONT. ATEXT 'text' [ ZONE ] add any text line to the graphics screen at the position defined by the current PTEXT parameters. For multizone display text is added to requested zone; if ZONE is omitted then it is added to the last drawn zone. COPYTX ifg jfg [ TAREA ] (or CPT) copy all figure fext from ifg to jfg, optionally in another LOOK area. PURGET ifg [ ipos ] (or RMT) purge text(s) for figure ifg by replacing existing texts with a blank character. ipos > 0 : purge only text at position ipos = 0 : purge all texts excluding fittexts (default) = -1 : purge all texts including fittexts < -1 : like ipos=-1 but assign a blank text also at position 3 (figure number) . Ex.==> PURGET 5 : purge fig.5 texts not touching fittexts and position 3 PURGET 5 -1 : the same, but FITTEXTS also purged PURGET 5 -2 : the same, but TEXT POSITION 3 also purged 1 Part 2 - 42 - 5. Standard LOOK keywords _______________________________________________________________________ 5.6 Commands for graphics ------------------------- FIGURE ifg display figure ifg. More than one figure number may be (or F) given, also ranges for figure numbers (ifg - jfg) may be given. For example F 1 3 - 4 8 2 22-25 is legal. Up to 36 figures may be placed on one display. FF select next figure(s) and display them OVERLAY ifg inr WITH ifg1 inr1 ifg2 inr2 ... this complex command allows to overlay several (up to 9) figures specified in a list of keyword WITH, with a master figure ifg inr. (All texts and scales are extracted from the master figure). SECNUM list display only figure(s) having second number mentioned in list. Example: F 1-9 SECNUM 2 5 7 SX xa xb lx defines the limits xa and xb for the x-scale. Linear scale for lx=0 and logarithmic scale for lx=1. If xa=xb, the scale limits are chosen automatically. SY ya yb ly defines the limits ya and yb for the y-scale. Linear scale for ly=0 and logarithmic scale for ly=1. If ya=yb, the scale limits are chosen automatically SZ za zb lz (for 3D only) defines the limits za and zb for the z-scale. Linear scale scale for lz=0 and logarithmic scale for lz=1. If za=zb, the scale limits are chosen automatically AUTOSCALE cancels all previous SX , SY commands and invokes the (or AS) default aoutomatic definition of x and y scales VIEW iaxis phi dip proji (for 3D only) definition of up-axis (1=x, 2=y, 3=z), of phi angle and of dip angle (in degrees), and of inverse projection distance (proji=0 for parallel projection). ZOOM (or O) zoom on one figure (input of edges via locator) DZOOM (or OO) zoom on two figures (input of edges via locator) MZOOM (or OOO) zoom on many figures (input of edges via locator, stop by break) NOZOOM suppress zoom @ add new graphical object(s) to already existing picture 1 Part 2 - 43 - 5. Standard LOOK keywords _______________________________________________________________________ The following keywords and their parameters have an effect only in the actual command! SCALES iscale choose scale display type (for actual command only!) iscale = 0 no scale iscale = 1 only x-scale iscale = 2 only y-scale iscale = 3 x- and y-scale iscale = 4 x- and y-scale with box ARP preserve aspect ratio, forces iscale=0 (see SCALES) (unless ratio differs by more than a factor of 4) ZONE xa xb ya yb define zone (in 0-1;0-1 system) for graphics display. Restricts the display area for actual command Predefined are the following zone-definitions: LEFT = zone 0.0 0.5 0.0 1.0 RIGHT = zone 0.5 1.0 0.0 1.0 UP = zone 0.0 1.0 0.5 1.0 DOWN = zone 0.0 1.0 0.0 0.5 SQUARE = largest possible square zone ASQUARE = the rest from the largest possible square zone ROTATE dphi ddip (for 3D only) definition of step in phi and dip Viewing is done with phi+dphi and dip+ddip (see VIEW). 5.7 Operations with histograms ------------------------------ The following commands allow certain operations with histograms. The type of the input histograms is not specified in the commands, the existing histograms of the given figure and secondary numbers are taken (if they exist). The result is usually a weighted histogram (exept command PROFILE creating VEC(4) distributions) with figure identifier (destfig, dest2no). OPERATE f1 ifg1 inr1 f2 ifg2 inr2 destfig dest2no OP operation with histogram with OP = ADD or SUB or MULT or DIV or EFF or AVER f1, f2 are factors for the input figures: f1*(ifg1,inr1) OP f2*(ifg2,inr2) -> (destfig,dest2no) PROJECT ifg inr destfig dest2no lowbin highbin AXIS projection of two-dim histogram (ifg,inr) with AXIS = X or Y (axis) of bins lowbin ... highbin to the one-dimensional histogram (destfig,dest2no). If lowbin and highbin is omitted, the whole histogram will be projected. PROFILE ifg inr destfig dest2no errtype AXIS average slices of two-dim histogram (ifg,inr) along one of the AXIS = X or Y. This produces VEC(4) figure containing profiles: vs Y for AXIS=X or vs X for AXIS=Y. errtype = 0 produces errors of = sigma(A) errtype = 1 produces errors of = sigma(A)/sqrt(n) NORM inorm fact ifg inr destfig dest2no normalization of histogram to fact if inorm=1 then integrated content = fact, if inorm=2 then summed content = fact (ignore bin width) 1 Part 2 - 44 - 5. Standard LOOK keywords _______________________________________________________________________ INTEG ifg inr destfig dest2no IT integration of histogram ifg inr from left (if IT=L) or from right-hand side (if IT=R) REBIN ifg inr destfig dest2no make rebinning (merging of several bins) of 1- or 2-dim histogram according to the HBIN parameters HBIN nx ix0 ny iy0 define parameters for histogram rebinning: nx (ny) - number of bins to be merged together along x(y), starting from the bin ix0+1 (iy0+1) (ix0 < nx, iy0 < ny) TAREA 'areaname' vers selects target area (see explanation below) In order to create figures in a different LOOK area the keyword TAREA has to be entered in the same command with one of the histogram operation keywords. An example below demonstrates comparison of distributions 10 1 and 20 1 from different areas: SAREA 'H1SIM' 204; NORM 1 1 10 1 1 0 TAREA 'H1SIM' 206 SAREA 'H1SIM' 206; NORM 1 1 20 1 1 1; OPERATE 1 1 0 1 1 1 2 0 DIV;F 1 2 5.8 Area handling ----------------- AREAS shows table of all existing areas in LOOK data base SAREA 'area' vers selects given area of LOOK data base, or opens new area if not existed before. RETAR returns to the previous area (see Part 1, sec.8) QAREA shows current area name/version ADDAREA add data from input file to the existing area(s). Identical figures will be merged. For example: LRALL 1 ADDAREA KEEPAREA ignore area name/version from input stream. This is a passive keyword having an effect only for actual command (see an examlpe in Part 1, sec.9) COMPARE 'area' vers F list [SECNUM inr] compares figures, specified via F list, in selected area/vers with the same ones from the current area; if keyword SECNUM has been specified within command then only figures having 2-nd number=inr are drawn 1 Part 2 - 45 - 5. Standard LOOK keywords _______________________________________________________________________ 5.9a Deletion and resetting of LOOK objects -------------------------------------------- An object existing in the current LOOK area can be deleted (purged) completely or reset to the zero content with the following commands PURGALL delete all objects from the current area (or RMA) PURGEF ifg1 [ifg2 [...]] (or RM) delete completely the listed figures from the current area independently of second numbers Ex.: PURGEF 12 deletes all objects with the first id=12 PURGEF 12 35-43 99 PURGEF 0 deletes all figures PURGDF ifg inr (or RM1) delete a single object RESETF ifg1 [ifg2 [...]] clear (reset) the content of the figures with indicated first identifiers in the current area; clear all in case of RESETF 0 . 5.9b Creation of new LOOK objects ---------------------------------- Any figure of legal type can be created interactively in any LOOK area. As a general rule, if figure with required identifier already exists, it will be purged before booking of new one. New figures can be filled from different sources: n-tuples, input via keyboard, BOS banks, DSTs. In order to create new figure in another LOOK area, keyword TAREA must be entered together with one of the creating keywords. BINS nx xa xb ny ya yb specify parameters for booking of 1- and 2-dim histograms; the same rules as in batch mode are applied to parameters (default: 0 0 0 0 0 0) HS ifg inr create (book) 1-dim unweighted histogram (default: 999 1) HSW ifg inr create (book) 1-dim weighted histogram (default: 999 1) HD ifg inr create (book) 2-dim unweighted histogram (default: 999 1) HDW ifg inr create (book) 2-dim weighted histogram (default: 999 1) XY ifg inr create new scatter plot (default: 999 1) XYZ ifg inr create 3-dim scatter plot (default: 999 1) VEC ifg inr ndim create (book) VEC(ndim) object (default: 999 1 3) 1 Part 2 - 45a - 5. Standard LOOK keywords _______________________________________________________________________ DATA d1...dn fill last booked object with the data d1,...,dn numerical values in d1...dn list are assumed to be ordered according to the filled object type: n entries for HS, n/2 entries for HSW,HD,XY,VEC(2), n/3 entries for HDW, XYZ etc Examples: HD 5 1 DATA x1 y1 x2 y2 x3 y3 store 3 entries in 2-dim histogram (5 1) in current area VEC 1 1 4 DATA x y dx dy TAREA 'data' 1 store one data point in a 4-vector object in area 'data' 1 Remember, that according to LOOK rule, if you skip all the parameters for the keyword, then the last defined set of parameter values will be actually used. Other possibilities to create a new object are to copy existing LOOK objects into the new ones (optionally in different area, if keyword TAREA was given), or to merge two (sub)figures. Merging works only for identical objects. This means that merged vectors must have the same dimensions, and histograms must be of the same type and have the same binning. COPYDF ifg1 inr1 ifg2 inr2 [ TAREA ] (or CP1) copy a single data set (ifg1,inr1) into a new one (ifg2, inr2). New object will get the same content and attributes as a source, however text will not be transferred. Example: COPYDF 10 2 20 0 TAREA 'newarea' 1 COPYFG ifg1 ifg2 [ TAREA ] (or CP) copy a complete figure including all texts belonging to it Destination figure must not exist before. MERGEF ifg1 inr1 ifg2 inr2 add content of figure (ifg2,inr2) to the (ifg1,inr1); statistics of first figure is updated properly. One more possibility is the `vectorisation' of histos, XY-s or XYZ-s : TOVEC ifg1 inr1 ifg2 inr2 [ TAREA ] `vectorises' source data set (converts into VEC type). This allows to use the power of n-tuples-oriented commands afterwards: inspect the content by listing, create projections from XY and XYZ data etc. Source Target VEC(1) VEC(2) VEC(3) VEC(4) HS, HSW 4-VEC X-bin content dX error HD, HDW 4-VEC X-bin Y-bin content error XY 2-VEC X-entry Y-entry XYZ 3-VEC X-entry Y-entry Z-entry 1 Part 2 - 46 - 5. Standard LOOK keywords _______________________________________________________________________ 5.10 N-tuples (Vectors) ----------------------- N-tuple in LOOK is nothing but vector with (optionally) named columns. In all commands user can refer to the N-tuple entities either by name, or by column number. Names are assigned to the VECtor columns in batch mode by special booking (CALL BNT instead of CALL BVEC, see Part 1), or interactively by the command NTNAME (see below). A general command to create slices of N-tuple applying multidimensional cuts looks as follows: NT ifg inr [nev nskip] 'x [y z]' [DATYPE ifgt inrt] [CUT ic] ---------------------------------------------------------------- where DATYPE is one of the keywords creating new figure: HS,HSW,...,VEC If this keyword is skipped, then the last booked object will be overwritten by new content. For example: NT 15 'Q2' HS 99 1 CUT 4 create 1-d histogram (99,1) from column 'Q2' of N-tuple (15,0) satisfying cut 4 NT '1 3' XY 55 1 create scatterplot (55,1) from the same N-tuple as before: col. #3 vs col. #1 NT 'x q2' overwite scatterplot (55,1) by the new content: Q2 vs X NT 15 'theta 0 E' HSW 99 1 produce energy flow distribution (99,1) When defining cuts, user can refer either to column numbers or to names (provided they have been defined). Complex cuts can be created out of elementary ones as it is shown below: Cut class Syntax Examples ---------- ---------------------- ----------------------- elementary ' name1 rel name2' 'E_elec >= E_hadr' ' name1 rel const' 'x < 0.001 ' ' C_xx rel C_yy ' 'C_15 > C_3 ' ' C_xx rel const' 'C_7 .EQ. 0 ' complex '[-]cut1 lop [-]cut2' '2 .AND. 4' '50 .or. -1' lop (logical operators) rel (relatinal operators) ----------------------- ------------------------ .AND. > .GT. .OR. >= .GE. .EQV. < .LT. .NEQV. <= .LE. == .EQ. /= .NE. 1 Part 2 - 47 - 5. Standard LOOK keywords _______________________________________________________________________ NT ifg inr [nev nskip] 'x [y w]' define source: N-tuple identifier and columns and process it creating destination figure. Here 'x y w' is a string defining variable(s) and weight. If this string = ' ', then all HS slices (one per column) will be automatically created. Nev, nskip are number of events to be processed and skipped NTSCAN ifg inr [nev nskip] 'var.list' scan over N-tuple entries displaying N-tuple content in a tabular form; 'var.list' - variable list to be shown in a scanning table, if list = ' ' then first 6 columns will be shown NTSHOW ifg inr show N-tuple table on the screen NTNAME ifg icol 'name list' rename columns starting from icol by names in 'name list' in all Ntuples having ifg as a first identifier. E.g. NTNAME 99 2 'col_2 col_3 col_4 col_5' NTPLOT switch display of resulting figure on/off (toggle type) NTBINS nx set number of bins for all 1-dim. histograms created by the command NT ifg inr ' '. XA and XB parameters for the booking are then taken from the min and max values of the columns. If NX=0, then an automatic LOOK booking is used. SCUT ic 'cut definition text' set (define) new cut. Definition text may be one of the listed above; ic is an integer number from 1 to 99. CUTS show all defined cuts on the screen CUT ic1 ic2 ... apply cuts number ic1, ic2, ... in OR (-ic means .NOT.ic) up to 32 different cuts are possible; any of these cuts may in turn be a complex condition Example: NTSCAN 50 ' ' CUT 5 12 -22 display in a tabular form all entries of ntuple (50,0) satisfying condition: 5 .OR. 12 .OR.(.NOT.22) CUT* ic1 ic2 ... apply cuts number ic1, ic2, ... in AND for ic1, ic2, ... the same rules as in CUT are valid Example: NT 50 1 'x q2' CUT* 5 12 -22 XY 200 create scatter plot (200,0) from the ntuple (50,1) using entries satisfying condition: 5 .AND. 12 .AND.(.NOT.22) DNTCUT display actual cut definition in a separate zone Example: f 100 left; dntcut right YYCUT 'condition text' Apply complex condition to be treated by YY-interpreter. Can be used together with the commands: NT ifg inr [nev nskip] ' ' to create all 1-dim slices, NTSCAN ifg inr [nev nskip] ' ' to show selected NT-rows. Examples: NT 50 ' ' YYCUT 'very_complicated_condition' NTSCAN 50 'x y z' YYCUT 'very_complicated_condition' How to do more with n-tuples using the interactive interpreter power is explained in section 6. 1 Part 2 - 48 - 5. Standard LOOK keywords _______________________________________________________________________ 5.11 Files (Datasets) --------------------- Datasets may be opened and closed interactively. Before opening a dataset the operator may use the command DATASETS (see below). DATASETS overview over connected data sets DATASET unit enter a dialogue to open/close data set for given unit (or DD) DATASETX unit type status 'dsname' open / close data set without dialogue (convenient for use inside command macro-files) FPARM 'statement' execute any FPACK command defined by 'statement', e.g. FPARM 'open unit=1 file=f99abc.look access=keyed' 5.12 Hardcopies --------------- LOOK supports different types of output devices: normal laser printers, PostScript plotters and Metafiles. Actual possibilities may depend on particular GKS implementation and have to be checked with local system manager. Detailed explanation how to use PostScript output at DESY IBM is given in the Appendix. PLOTTERS overview over all hardcopy devices is given, including an internal plotter number, to be used in the selection of a certain plotter PLOTTER number (or PL) make a hardcopy of actual graphics on the hardcopy device with a given number (see PLOTTERS) SIZE xcm ycm x0 y0 define actual size and a position of the picture (in cm). (x0,y0) corresponds to the left lower corner of picture. For example: PL 12 SIZE 15 10 1 8 Note, that if a keyword SIZE is enterred together with PL command, then zones will not be rearranged for a portrait style. This is especially important for further including in TeX (see Appendix) TXPRINT num enter dialogue to print a part of the text screen on the plotter num (or on the terminal if num=0) 5.13 Input/output operations ---------------------------- LREAD unit read and fill one LOOK area from input unit LRALL unit read and fill all LOOK areas from input unit 1 Part 2 - 49 - 5. Standard LOOK keywords _______________________________________________________________________ LRNEXT unit will read and show only key of the next record (area name and version) and prompt operator to choose one of the following possibilities: 1 = skip shown area 2 = clear and fill in shown area 3 = add input data to shown area 4 = change area name/version, clear and fill it 5 = change area name/version and add to it 6 = break LREWIND unit rewind input unit By default before filling from input file LOOK area is cleared. If one wants to ADD input data to the existing area, keyword ADDAREA must be enterred together with LREAD or LRALL command. In latter case identical figures will be merged. ADDAREA add input data to the existing area, for example: LREAD 1 ADDAREA Usually a comlete LOOK area is loaded into memory when reading from the input F-pack file. A selective read is however possible in interactive mode, using commands LOADFIGS and/or LOADROWS. LOADFIGS ifg1 ... Only those figures listed in this command are actually loaded into LOOK memory. Note, that the parameters of this keyword are taken into account when executing any of LREAD, LRALL, LRNEXT commands and as usual are valid until next explicit re-definition. (Default: LOADFIGS 0 meaning load all figures) Example: LOADFIGS 10 20 99; LRALL 1; LOADFIGS 0 This will load only figures 10 20 and 99 from all areas where they do exist, and at the end reset the option to the default status. LOADROWS mrows Limits number of n-tuple(vector) rows to be loaded into LOOK memory. Acts on ALL LOOK objects of 'vector' type. As LOADFIGS it is taken into account when executing any of LREAD, LRALL, LRNEXT commands. (Default: LOADROWS 0 meaning load complete vectors) Example: LREAD 1 LOADROWS 1000 LWRITE unit write current LOOK area to the output unit (unit has to be opened before with the parameters allowing writing!) LWRALL unit write all existing LOOK areas to the output file (unit has to be opened before with the parameters allowing writing!) EVDIR lin lout 'YY-text' create INDEX file (event directory) selecting RUN/EVENT entries according to the YY-text, from unit LIN to unit LOUT. Both LIN and LOUT must be FPACK opened files. If RUN and EVENT are omitted in YY-text, they assumed to be 1-st and 2-nd columns of the n-tuple used. Example: EVDIR 11 21 'nt(1)(run,event)@(Q2>1000.)' 1 Part 2 - 50 - 5. Standard LOOK keywords _______________________________________________________________________ 5.14 Display options -------------------- LTITLE ift 'title' set global title for blank area. For non-blank areas the 'title' is irrelevant (the title is then constructed from area name/version automatically). Parameter ift = 0/1 will switch off/on a global title for currently selected area. LEGO ilego iscale define parameters for legoplot representation. Here iscale has the same meaning as in the command SCALES (see 5.4); ilego = 1-4 selects one of the four predefined 3D views, ilego = 5 allows any view using param. from VIEW keyword, ilego = 0 selects BOXEs mode for all 2-dim. histograms. Default: LEGO 1 4 GRID igx igy add grid to actually displayed figures. If ig(x/y)=0 then grid is drawn along big tick marks only, if ig(x/y)>0 then grid is drawn along small tick marks as well; igx/igy are responsible for x/y axis respectively. Default: GRID 0 0 NOGRID forces LEGN style for all legoplots, has an effect for actual command only! Example: F 1-6 NOGRID CONTOUR nlevels 'colour' define parameters for contour plot representation. nlevels is number of z-levels (<= 50) colour is color for negative content drawing (used also for BOXEs mode). Default: CONTOUR 16 'white' CONT forces contour plot style for all 2-dim histograms, has an effect for actual command only! Example: F 1-6 CONT PEAKPARM (alias PP) toggle type, switch on/off LOOK peak analyser STATPARM (alias ST) toggle type, switch on/off output of statistics in figures SMOOTH toggle type, switch on/off smoothing procedure for the 1-d histograms. If attribute style is CURVe then only smoothed result is shown, otherwise smoothed curve is superimposed on the original histogram LEGEND toggle type, switch on/off figure legend (acts only for figures having text 6, 7 etc.) SATTR 'datype' ifg inr TO 'attributes' this command sets/changes attributes for figure (ifg,inr). An example: SATTR 'vec' 10 1 TO 'blue square symbol' SETDAT 'datype' TO 'attributes' change default attributes for all figures belonging to the 'datype' class. Note, that this command has no influence on the already existing objects. An example: SETDAT 'xy' TO 'red plus marker' 1 Part 2 - 51 - 5. Standard LOOK keywords _______________________________________________________________________ PEAKS ifg ... make peak analysis for all 1-dim histograms in the list of figure numbers and show resulting table on the text screen More than one figure may be given, also ranges (ifg - jfg) are possible. For example PEAKS 1 10-24 99 Up to 50 figures are accepted within single command. USERFACT f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12 global factors to change character size (f1), graphical symbol size (f2), left (f3), right (f4), top (f5) and bottom (f6) margins, tick mark length (f7), error bars style (f8) and line widths (f9-f12). Line widths may be changed separately for: lines inside a figure (f9), figure box (f10), tick marks (f11), grid (f12). If f8>0 then error bars are drawn with delimiters. (default: USERFACT 1. 1. 1. 1. 1. 1. 1. 0. 1. 2. 2. 1.) NOROUND ix iy iz suppress rounding for x,y,z scales if ix,iy,iz /= 0. (Default: 0 0 0 - leading to the automatic rounding) LOGX ipos1...iposN use log scale x-axis for figures at given positions in a current zone LOGY ipos1...iposN use log scale y-axis for figures at given positions in a current zone 5.15 Inquiry functions ---------------------- AREAS show list of all defined LOOK areas CUTS show table of all defined cuts for N-tuples DATASETS show list of all defined datasets in actual session DEFATT show table of default graphical attributes DO '?' show all user defined DO-macros and a list of YY LOADed subroutines and common blocks FIGURES fg0 n show list of figures fg0...fg0+n-1 in current LOOK area; (or FS or LS) show all figures if parameters are omitted or = 0 HISTOS fg0 n show number of entries and texts 1,2 for the figures (or LL) fg0...fg0+n-1 in current LOOK area (show all figures if parameters are omitted or = 0) KEYWORDS show list of all defined keywords in alphabetical order LISTF ifg inr list figure statistics, text and attributes on a screen 1 Part 2 - 52 - 5. Standard LOOK keywords _______________________________________________________________________ MEMORY show status of LOOK database memory OPTIONS show status of all toggle options (on or off) and the state of MESSAGES command PLOTTERS show list of all supported hardcopy devices QAREA show current area name, version and list of all figures in this area H keyword show actual values for all parameters of given keyword 5.16 BOS related commands ------------------------- These commands are available only when LOOKBS is called as a user routine within LKUSER. The MAIN program used in the present standard LOOK program at DESY is the following: PARAMETER (LIW=250000) COMMON /BCS/ IW(LIW) * initialize BOS CALL BNAMES(1000) CALL BOS (IW,LIW) CALL LOBOIF * start LOOK CALL LOOK STOP END SUBROUTINE LKUSER (LRET) IF (LRET .LT. 0) THEN * BOS records handling CALL LOOKBS * place for the user code * ..... * ENDIF RETURN END In the first few statements BOS is initialized and subroutine LOBOIF is called: it defines unit 7 (instead of 5) as system input unit and predefines unit 1 as BOS input unit. LOOK itself does not make any use of BOS. A subroutine LOOKBS for some actions and displays related to BOS is called within the display loop. The user may add his own display programs there (see ...). BOSHELP show index of LOOKBOS commands on the screen BRECORD show table of banks from BOS record BOSDUMP index dump BOS array to the screen starting from index BKLIST 'list' list bank names of given list, for example 'E' BKNRS 'name' list all numbers for given bank 1 Part 2 - 53 - 5. Standard LOOK keywords _______________________________________________________________________ BDROP 'list' drop named bank(s) from the given list BOSBANK 'name' nr show bank specified by name and number BSWAP 'nam1 nam2' exchange names of two BOS banks BPRINT 'name' nr show bank specified by name and number in a format given in dialogue following this command, e.g. : 6F9.2,2I5 (note: no parenthesis!) BREAD unit read one BOS record from input data set (automatic rewind at the end-of-data condition) BWRITE unit write one BOS record in FPACK format on the output (alias WRITE) data set. Unit must be opened beforehand BREWIND unit rewind BOS data set BRUNEVT unit find on unit the record with run and event number given in dialogue following this command BSKIP unit skip on the unit the number of records given in dialogue following this command BREADC lun read BOS banks from text input file on unit lun BCALLC lun 'name' nr read and interprete text from the given bank Default parameter values for all these keywords are the following: unit = 1 'name' = 'HEAD' lun = 7 'list' = 'E' nr = 0 ind = 1 BFILL ifg inr 'text_string' fill figure (ifg,inr) from the BOS bank(s) defined in a text string, e.g. BLILL 100 1 'HEAD,12' 1 Part 2 - 53a - 5. Standard LOOK keywords _______________________________________________________________________ 5.17 Commands for LOOK macros. Debugging macros ------------------------------------------------ There are commands mainly designed for a usage inside macrosin order to facilitate the debugging process especially in case of long macros. MESSAGE [nl] 'text' (or MESS) print 'text' in the text screen, the length of 'text' must be less than 512 characters, nl is the no. of lines to be reserved for the message (default = 1) PAUSE suspends the macro execution and asks user whether s/he want to continue : answers y yes yeah oui will resume the execution, answers n no non nein will stop it. Ex.: MESS 'Pause #1'; PAUSE Apart from debugging, PAUSE is helpful when few graphical screens are created in the macro. In order to have a possibility to contemplate each of them as long as needed one has to place the PAUSE command after every drawing command. The error messages from various LOOK commands are not always very elaborate: often they reduce just to a message `error' displayed in a message field of the graphic screen. Besides, as a rule, the error situation is never fatal, so that one error usually induces many other erros. Interleaving the normal commands in a macro by MESS / PAUSE commands often helps to locate the erroneous command. On unix platforms, the role of text window is usually played by a separate command window. In this situation, debugging is especially facilitated by MESS commands inside macros combined with the command MESSAGES 1 1 (see) the latter leading to a duplication of the error messages in the same window: having run a macro, user can look through the full output of the procedure and find the erroneous place. This way of debugging does not need any usage of the PAUSE command. 1 Part 2 - 54 - 6. Interactive interpreter _______________________________________________________________________ 6. Interactive interpreter YY ============================= Starting from the version 2.00/00 LOOK contains YY package written by Ruten Gurin (Moscow). YY is an interpreter of a special programming language which is a dialect of the usual FORTRAN extended so as to incorporate some LOOK objects as language elements and certain operations with them. It is presently used in LOOK by the commands: DO, LOAD, YYCUT and FIT. 6.1 DO command: creating new LOOK objects ----------------------------------------- In the simplest applications of the DO command, the latter is a sort of extension of the NT command. It allows to create histograms / vectors from the existing n-tuples using full power of the YY-interpreter. The syntax is: DO 'LOOK_Obj = right_part' [TAREA] where LOOK_Obj is DATYPE(ifg,inr). DATYPE must be one of the legal LOOK data types: HS, HD, HSW, HDW, XY, XYZ, VEC, NT; ifg and inr are first and second figure numbers. If inr is omitted (together with preceeding comma) inr=0 is assumed. TAREA, as usual in LOOK, allows to create new objects in another (target) area. The bin definition for the new object in case of a 1-dim or 2-dim histogram may also be specified: for DATYPE=HS,HSW by writing DATYPE(ifg,inr,nbinx,xmin,xmax) = ... , and for DATYPE=HD,HDW by DATYPE(ifg,inr,nbinx,xmin,xmax,nbiny,ymin,ymax) = ... If not given explicitly, the bin definition is determined by the last BINS command (see 5.9), or a usual automatic binning is applied if no BINS command has been issued yet. The simplest form of the right_part is Vec_Obj. Vec_Obj is a LOOK_Obj restricted to the set: XY, XYZ, VEC, NT. Example: let VEC(17,2) be a 1-dim ntuple, one can write then DO 'HS(5) = VEC(17,2)' This means: "Create the histogram HS(5,0) and fill it with the content of VEC(17,2)". If the target figure already exists, it will be purged before the creation. Therefore avoid to use the same figure in the left and right parts! As usual, in order to create new figure in another area, the keyword TAREA must be enterred together with DO command. Left and right parts of a DO assignment must have equal dimensions. If for example, left part is HSW(...) - then the right part must have exactly two columns (second is treated as weight). If the left part is a new vector whose dimension is still unknown, then it inherits the dimension of the right part. 1 Part 2 - 55 - 6. Interactive interpreter _______________________________________________________________________ More complex expressions are possible within DO command. For example: DO 'HD(5) = (XY(7)-XY(8))/XY(7)' Operands of one operation must have equal dimensions. If operands have different sizes (number of rows), then the size of the result is the minimum of operands sizes; the last rows of the biggest operand are ignored. Operations are performed row by row and column by column, thus an example above will fill two dimensional histogram HD(5,0) with the pairs: ( Xcoord(XY(7)) - Xcoord(XY(8)) ) / Xcoord(XY(7)) , ( Ycoord(XY(7)) - Ycoord(XY(8)) ) / Ycoord(XY(7)) . All FORTRAN-supported operations may be used except power (**). One can also use the following operations (the two notations are equivalent): +------+------+------+------+------+-------+------+------+------+ | > | < | >= | <= | == | /= | & | | | ^ | | .gt. | .lt. | .ge. | .le. | .eq. | .ne. | .and.| .or. | .not.| +------+------+------+------+------+-------+------+------+------+ Note, that the operations, producing logical results in Fortran, produce an integer in DO-command. TRUE is replaced by 1, and FALSE - by 0. Using the scalars in the expression is allowed as well, e.g.: DO 'HD(5) = (XY(7) - XY(8)) / 3.14' Operations of the kind 'Vec_Obj opsign scalar' are also executed row by row and column by column. The dimension and size of the result are the same as of first operand. Operations like 'scalar opsign Vec_Obj' are forbidden. The operations of the kind 'scalar opsign scalar', including power, are valid operations. Note, that (5>3) + (4<6) is the correct expression giving the result = 2. The BUILT-IN FINCTIONS with the scalar arguments are possible in a DO expression. The set of presently supported builtin functions includes: +----------------------------------------------------------------+ | IABS ABS EXP LOG, ALOG LOG10 ALOG10 SIN COS | | TAN ASIN ACOS ATAN BTEST IAND IOR ATAN2 SINH | | COSH TANH SQRT MOD AMOD AINT ANINT NINT ISIGN | | SIGN INT REAL FLOAT MAX MAX0 AMAX1 AMAX0 MAX1 | | MIN MIN0 AMIN1 AMIN0 MIN1 EOR NOT ISHFT ISHIFT | | LSHFT LSHIFT IBSET IBCLR RSHFT RSHIFT ERF GAMMA | | Remark: ERF and GAMMA are not available on VAXes | +----------------------------------------------------------------+ An example: DO 'HD(5) = XY(7)*Sin(0.25) + XY(8)' User can create new vectors, selecting some columns from existing ones. The syntax is: Vec_Obj(column1,column2,...,columnN). This construction is called projection. Columns can be addressed either by their names (if the source Vec_Obj has named columns), or by their numbers (always) In latter case, the identifier C_number must be used as a column name. For example: DO 'HD(5) = NT(7)(Ebemc,C_17)' which means: "Fill the histogram HD(5,0) with the values of 'Ebemc' column and 17th column from ntuple NT(7,0)". The dimension of the projection is a number of columns in brackets. The size of the projection is the same as the size of source Vec_Obj. 1 Part 2 - 56 - 6. Interactive interpreter _______________________________________________________________________ The right part of the DO expression can contain the operations on the projections, e.g.: DO 'HD(5) = NT(7)(Ebemc,Angle) + XYX(4)(C_1,C_3)' One can use in projections the expressions with operations and function calls instead or together with the column names and constants: DO 'HDW(5) = NT(7)(Ebemc*C_24+Sin(Angle),1/C_17,Exp(2.3))' where Ebemc and Angle are the column names in NT(7,0). If the projection has exactly one column, it can be used at any place where the scalar may be used: DO 'HD(5) = XY(7) + Sin( XYZ(3)(C_1/C_3) )' Here, for each row the value of w = Sin(C_1/C_3) will be evaluated over the XYZ(3,0) columns, and then the pair (X+w, Y+w) will be stored in HD(5,0), where X and Y are the values from the current row of XY(7,0). Note, that XYZ(3)(C_1/C_3) has one column, XYZ(3)(C_1,C_3) has two columns and XYZ(3) has three columns. Another example: DO 'HD(5) = NT(7)(Ebemc+NT(5)(Ebemc2*Q), Sin(Angle))' Here Ebemc and Angle are supposed to be column names in NT(7), while Q and Ebemc2 are the column names in NT(5). All the operations in the right part of this example are done row by row, synchronously over all vector-objects, referenced in it. If some of them are exhausted (no more rows in it) then the evaluation is stopped. So, if Ebemc and Angle are taken from 17-th row of NT(7), then the corresponding Ebemc2 and Q will be taken from the 17-th row of NT(5). Note, that the column name resolving for the nested projections is done only for one level. If e.g. Q is a column name not of NT(5), but of NT(7), then the command from the previous example will lead to an error message (column Q will not be found). This can be avoided in the following way: DO 'HD(5) = NT(7)(Ebemc+NT(5)(Ebemc2*NT(7)(Q)), Sin(Angle))' 6.2 DO command: using YY-conditions ----------------------------------- User can select specific rows from the vector objects, using rather complicated conditions (cuts). General syntax is: Vec_Obj @ ( condition ) or Projection @ ( condition ). where the condition is a logical (= "YY integer") expression, in which the column names from the corresponding Vec_Obj can be used. If the value of condition is FALSE (zero), then the corresponding row will be skipped. Examples: DO 'HD(5) = XY(7)@( Sin(C_1) > C_2 & C_3 < 0.0 )' DO 'HS(5) = NT(7)(Sin(Ebemc))@( Angle > 0.16 & Exp(Q) > 4 )' 1 Part 2 - 57 - 6. Interactive interpreter _______________________________________________________________________ Vector-objects and projections with the conditions applied can be used in turn as operands of operations, like normal vector-objects: DO 'HS(5) = VEC(1)@(Q /= 0) + NT(2)(Ebemc)@( Sqrt(Ebemc)>2 )' Conditions, like projections, may be nested. DO 'HS(5) = NT(1)@( Q > NT(2)(Q)@( Ebemc /= Rho ) )' Resolving of the column names in the conditions is also done for one level only. In the example above the first occurrence of Q is supposed to be column name in NT(1). Second Q, Ebemc and Rho must be the column names in NT(2). If Rho is the column name in NT(1), then this command will lead to an error message. In order to avoid this one should use the command DO 'HS(5) = NT(1)@( Q > NT(2)(Q)@( Ebemc /= NT(1)(Rho) ) )' If an expression contains several terms, each with its own condition, then the row is skipped if any of them gives FALSE (zero) result, e.g.: DO 'HS(5) = VEC(1)@( Q>3 ) + VEC(2)@( Angle /= 0.0 )' If the first condition leads to the skipping of rows 1,4,15 in VEC(1), and the second condition leads to the skipping of rows 3,4,7 in VEC(2), then the rows 1,3,4,7,15 will be skipped in both VEC(1) and VEC(2). 6.3 DO command: YY-macro facility --------------------------------- To make the use of the DO-commands more convenient, one can define the macros and use them afterwards in DO-commands. A macro is defined by the command: DO '/name = text' where the name is a macro name, and the text is an arbitrary text. It may contain previously defined macro, however the recursive macro definition is forbidden. The maximal nesting level for a macro is 30. The following commands allow to inspect the macro definition, or to purge macro definition from the memory: DO '? name' - show the definition of the macro 'name' DO '?' - a global inquiry (list of all defined macros) DO '- name' - delete macro 'name' from the memory After the macro is defined, the given name will be replaced by the corresponding text in any DO command (except DO '/...' and DO '?...'). If the text contains other macro names, they will be replaced as well. An example: DO '/List1 = Ebemc,Q,Angle' DO '/List2 = Par1,Alfa,List1' DO '/CutX = (Sin(X) > Z)' DO '/Fig = NT(5,917)' DO '?List1' DO 'Vec(33) = Fig(List2)@CutX' 1 Part 2 - 58 - 6. Interactive interpreter _______________________________________________________________________ The last command is equivalent to the DO 'Vec(33) = NT(5,917)(Par1,Alfa,Ebemc,Q,Angle)@(Sin(X)>Z)' Using the macro facility to define the cuts for the DO commands, it is recommended to put the brackets around the condition, as in the example above. It is not obligatory, but you will avoid a lot of confusing doing that way. 6.4 YY programs and LOAD command -------------------------------- LOOK LOAD command with the syntax: LOAD 'filename' allows to load dynamically YY-program from a text file to the memory. The full name of the file on IBM/MVS is USERID.FILENAME.LTX. On UNIX platforms the full name is "filename.ltx" if "filename" does not contain a period, and it is just filename otherwise. All the subroutines/functions from the file are stored in a memory and can be used by subsequent DO and FIT commands. Note, that all macros defined via DO '/name = text' will be used by the LOAD command: the corresponding names in the loaded program will be replaced by the macro texts (which may contain macro names again - up to 30 levels). If the file contains a main program, it is executed immediately after the whole file is loaded. Let the content of the file userid.AAA.LTX be: function F(a,b) F = Exp(a) * Sin(b) end program Test1 r = 0 do k=0,15 r = r + F(0.5*k,7.0*k) enddo print *,r end Then the command LOAD 'AAA' will lead to the evaluation and printing of the value r. The definition of the function F will stay in the memory. YY-program loaded by another LOAD command can use the function F, as already defined, or can redefine it. YY input syntax is free, continuation signs are neither required, nor allowed. Labels may appear in any position, e.g. IF( I.GT.2 ) GOTO 30 I = I+1 30 CONTINUE GO TO 50 means IF( I.GT.2 ) GOTO 30 I = I+1 30 CONTINUE GOTO 50 1 Part 2 - 59 - 6. Interactive interpreter _______________________________________________________________________ To allow for use of normal FORTRAN code, which may contain continuation lines, two switchers can be used: *#FORTRAN6 in the positions 1-11 switches to the normal FORTRAN mode *#YY6 in the positions 1-6 switches to the default YY mode Upper and lower case characters are equivalent. Blanks are significant, lines like A B = 5 are not allowed. All keywords like DO, ENDIF and so on are reserved, the line FORMAT = 3+GOTO is correct in FORTRAN, but not in YY. Both forms are allowed: GO TO and GOTO END IF and ENDIF END DO and ENDDO ELSE IF and ELSEIF DO WHILE and DOWHILE However two parts of a keyword must reside in the same line. A set of the control structures includes: do-while, iterative do (both with and without label), if (including else-if). Brackets after DOWHILE and IF may be omitted, e.g.: DO WHILE I.GT.3 I = F(I) ENDDO means DO WHILE( I.GT.3 ) I = F(I) ENDDO The list of the not yet implemented FORTRAN features is: EQUIVALENCE statement double precision values types INTEGER*2,LOGICAL*1 statement-functions INTRINSIC statement I/O (only PRINT *,expression is presently allowed) alternate entries alternate returns computed and assigned GOTO PAUSE statement BLOCK DATA statement There are the limitations on the character variables use: > the type of the function result cannot be of character type, > concatenation operation is allowed only in the assignment to the character variable. There are limitations on the DATA statements, the only form is: DATA var1/list1/, var2/list2/, ..... where var must be a simple name, one can write DATA A/..../, but not DATA A(5,2)/..../. No do-loops in a list are allowed, only simple values or counter*value. The builtin functions listed in section 6.1 are allowed. 1 Part 2 - 60 - 6. Interactive interpreter _______________________________________________________________________ 6.5 LOOK extension of YY fortran. Equivalence of DO and LOAD ------------------------------------------------------------ YY interpreter has an important LOOK-oriented extension to the standard FORTRAN: one can use the expressions on LOOK-vectors in YY-programs. In general, all the things allowed in a DO-command are also allowed in a YY-program. In addition the local and common-block variables can also be used in these expressions. Finally, the user-defined functions can be used in them as well. An example. The content of the file userid.AAA.LTX is: program Test2 do k=0,15 Elim = k*0.5 HD(987,k) = NT(980,k)(F(Ebemc,Q),C_3)@(Q>Elim) enddo end Function F is supposed to be loaded by one of the previous LOAD command The command LOAD 'AAA' will fill 16 histograms: HD(987,0) - HD(987,15). An exception exists from the above general rule that all the things allowed in a DO-command are also allowed in a YY-program. The sintax of YY-macros is different in the YY programs: *#MACRO /a=... replaces DO '/a=...' *#MACRO - a replaces DO '- a' *#MACRO ? a replaces DO '? a' *#MACRO may also be written as C#MACRO or c#MACRO . Only one *#MACRO statement per line is allowed. If the program contains an expression on LOOK-vectors, then the problem arises: how to distinguish the column names in the expression from the FORTRAN variables? The YY-interpreter solves those in the following way: all the declared names, or the names explicitly used as variables are considered as variables, all other names are used as column names. In the example above Elim is used as a variable, so it is treated as a variable in (Q>Elim). On the contrary, Q is neither declared, nor used outside the expression, so it is treated as a column name. The decision is taken on the basis of the part of the program, preceeding the decision point, no lookahead is done. From that point of view, the command: DO 'something' is COMPLETELY equivalent to the loading of an .LTX file with the content: something END This means, that functions / subroutines, loaded via the LOAD command, can be used freely in the DO-commands dealing with LOOK-vectors. Moreover, any YY-statement can be used in a DO-command (except *#MACRO, *#FORTRAN6, *#YY6 instructions and keeping in mind that only the free format without the fortran continuation lines should be used in a DO ). The following DO-commands are all correct: DO 'call Subr1(739,0.5)' DO 'HS(3) = NT(5)(F(C_37,C_16))' DO 'do i=17,24 HS(3,i) = NT(5,i)(F(C_37,C_16)) enddo' E.g., enterring the command: DO 'function X(z) X = Sin(z)*Cos(z) end' one can define (or redefine) the function X and store it in a memory. 1 Part 2 - 61 - 6. Interactive interpreter _______________________________________________________________________ Another useful possibility provided by the DO command is a special iterative call. DO 'call mysubr(nt(1)(x,Q2)@(ELANSEL))' This command will call subroutine MYSUBR for each nt(1)-row satisfying the condition defined by the macro ELANSEL. In such calls all arguments containing strings "nt..." will be replaced by the vectors containing values of the specified columns (X and Q2 in the example above). If column names are omitted, a complete row is transferred to the user routine. For example, DO 'call fillv(10,nt(1)@(goodev))' is equivalent to the following code: do i=1,nrows if (goodev) then call fillv(10,row_i) endif enddo where the user routine should expect one-dimensional array as a second argument,e.g. subroutine fillv(ifg,row) real*(*) row call xy(ifg,0,row(1)+row(2),row(5)/row(6)) end One more LOOK extension of the YY fortran is the possibility to calculate the column number of an ntuple using the C_ function, instead of refering to it by the name. Syntax: C_(integer_expression) The function may be used in any place where a column name may be used. An example: a single line DO 'do i=1,15 hsw(100+i)=nt(1)(C_(i),w) enddo' allows to create 15 weighted histograms of 15 quantities stored in the ntuple with a weight stored also inside the ntuple in a column named 'w'. Actual column names will be indicated in the figures' captions. Similarly to C_ function there is another function # (yes! this number sign is its name) without arguments whose value is the number of the current row inside an ntuple. Looking at it differently, one can also consider it as a name of an actually non-existing extra colunmn of an ntuple containing the row-number: 1,2,...,N_rows. The # function may appear in any place where a column name may appear -- exactly like in case of the C_ function. Few examples: Ex.1 DO 'hs(10)=nt(1)(E)@(#<100)' will histogram column E from the first 99 rows of the ntuple nt(1) Ex.2 DO 'xy(3)=nt(1)(E,#)' will plot E values vs row number Ex.3 DO 'call fillv(10,nt(1)@(#==3))' will call the function fillv for the 3rd row of the ntuple. Ex.4 DO 'hs(5) = nt(2)(sin(# * 3.14)) @ (cos(# * 1.57) < 0.5)' an abstracted example of arithmetics with # function. Ex.5 DO 'hs(3)=nt(5)(C_(mod(#,5)))' an even more abstracted example 1 Part 2 - 62 - 6. Interactive interpreter _______________________________________________________________________ 6.6 Interface between YY and standard FORTRAN --------------------------------------------- Accessing the FORTRAN-compiled subroutines/functions from YY program. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ All the FORTRAN-compiled subroutines/functions, which the user intends to call from YY subroutines/functions, must be known to YY-interpreter. To achieve this, the user has to have in some initialisation subroutine a piece of code like this: EXTERNAL SUBR1, FUN2, ... SUBRLAST ... CALL YYFTNE('SUBR1',SUBR1) CALL YYFTNE('FUN2' , FUN2) ..... CALL YYFTNE('SUBRLAST',SUBRLAST) The first argument of YYFTNE must be uppercase. This code cannot be executed interactively, it must be FORTRAN-compiled and linked into the LOOK load module. Accessing the FORTRAN-compiled common blocks from the YY program. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ All the FORTRAN-compiled common blocks, which the user wants to use in the YY subroutines/functions, must be also known to the YY-interpreter. This is achieved by including in some initialisation subroutine the following code: CALL YYFTNC('COMZF',LOC(ALFA)) CALL YYFTNC('ABCOM',IYYSLC(STR)) ..... The first variable in a common block must be used as an argument to LOC or IYYSLC. If it is a character variable, then IYYSLC must be used, otherwise the LOC must be used. This code also must be FORTRAN-compiled and linked into the LOOK load module. In the present standard LOOK version the following subroutines and common blocks are included and can be used in the user YY-programs: STLOOP, KEYDEF, NAMIND, NLINK, BKTOW, BCS, INDW. and all LOOK subroutines and functions described in the Part 1 of this Manual. Subroutine STLOOP can be called to stop LOOP command. COMMON/INDW/INDW is included to be used together with the routine BKTOW (see BOS Manual) 1 Part 2 - 63 - 6. Interactive interpreter _______________________________________________________________________ 6.7 Fitting ----------- User can fit any legal LOOK distribution of the dimension <= 10 either to the standard LOOK functions, or to the user supplied function. The list of standard functions includes: > gaussian G = P(1)*EXP(-0.5*((X-P(2))/P(3))**2) > exponent E = EXP(P(1)+X*P(2)) > polinom Pn = P(1)+P(2)*X+P(3)*X**2+...+P(n+1)*X**n (0<=n<=49) and any arithmetic expression built from them, e.g. 'P1+G', 'P2+G/E' etc. Note, that 'G+G' (6 parameters) is not equivalent to '2*G' (3 parameters). In case of a simple gaussian fit (G) no initial values for the free parameters are needed, otherwise they have to be supplied before to execute the fit procedure. SETFIT mode nit eps nptfun Select fitting method and set the fit steering parameters. MODE = 0,1,2,3 invokes FUMILI chi**2, likelihood, MLFIT chi**2 or Poisson methods respectively. NIT - maximum no. of iterations, EPS - relative precision required, NPTFUN - number of points defining resulting function curve. (Default: SETFIT 0 20 0.005 99) FITPAR m ifg [inr i j k] Define initial values and (optionally) limits for the fit parameters. ABS(M) - number of free parameters in the approximating function (<=50), IFG,INR - VEC number where these parameters are stored, I,J,K - column numbers in the VEC(IFG,INR) containing PAR,PMIN,PMAX respectively. If IJK are omitted, then i=1,j=2,k=3 are assumed. If M < 0, then PMIN/PMAX values will be ignored during the fit. FIT ifg inr [itg xmin xmax] 'fun' [COV [ifc inc [igncor]]] Fit figure (ifg,inr) by the function FUN within the region (xmin,xmax) and put the result in the subfigure (ifg,itg). If itg<0, or itg=inr then the target subfigure will not be created. If figure (ifg,inr) is multidimensional distribu- tion, then (xmin,xmax) are only applied to the first argu- ment. FUN can be either a standard function, or expression of the standard functions (see above), or the user defined function. In the last case the user function must be known (loaded by LOAD command or defined via DO '...'), and the text parameter 'fun' of the FIT command must have the form 'UNAME.F', where UNAME is an actual function name. With the additional keyword COV one can define vector (ifc,inc) containing full covariance matrix of data points (effective only for FIMILI chi**2 method) ; igncor.ne. 0 requests the non-diagonal elements (i.e. correlations) to be ignored. Both the vector dimension and the # of rows must be greater or equal to NDATA = no. of data points in the main figure (ifg,inr) before a possible truncation by XMIN,XMAX. COV ifc inc [igncor] to be used with the FIT command, see above PUTFIT ifg inr [TAREA] Store the parameters, errors and covariance matrix of the last fit in VEC(ifg,inr). The content of each row is: PAR(irow) ERR(irow) (COV(irow,j),j=1,NPAR) (irow=1,NPAR). 1 Part 2 - 64 - 7. Zones _______________________________________________________________________ SHOWFIT Show the result of the last fit in the text screen. FTEXTSTOR i Switches on/off storing the fit results by FIT command in a (packed) text form into look database; the stored results may be displayed together with the fitted figure inside the figure display. ==> FTEXTSTOR 1 switches on storing ( d e f a u l t) ==> FTEXTSTOR 0 switches it off The storage is the figure text with position IPOS=1000+INR where INR is the second nimber (identifier) of the fitted figure. Related commands: FTEXTDRAW,PFTEXT,FPARNAME,FONT. FPARNAME ipar 'nam_1 [ nam_2 [...]]' (re)define name(s) of fit parameters ## ipar ,ipar+1 , ... to be nam_1, nam_2, ... for subsequent FIT commands. These names will be stored and displayed in the figure display instead of default names P1, P2, ... . The command is only effective BEFORE the FIT command. No blanks are allowed inside a name; different names are separated by blanks. ==> Ex.: FPARNAME 5 'Constant Slope Exponent A12' -- defines the names of 4 parameters ## 5-8 ==> Special value: FPARNAME 0 -- back to default names P1,P2,... for all parameters Related commands: FTEXTSTOR,FTEXTDRAW,PFTEXT,FONT. FUN ifg inr xmin xmax 'f' [TAREA] Create the VEC(ifg,inr) from the F(x) at NPTFUN+1 points within the interval [xmin vertical extension). By default the complete screen surface is used as display area, regardless of the shape. There is the possibility to define a zone on the display as a reduced display area for the graphics, requested by a keyword. By this feature it becomes possible to combine several independent displays on the screen. A zone on the display surface is defined by a command ZONE xa xb ya yb with xa, xb and ya, yb being the lower and upper limits of the zone, measured within limits 0 to 1, independent of the actual shape. Thus the total surface (assumed by default) corresponds to the command ZONE 0 1 0 1 Keywords which define certain zones are predefined (see under standard keywords). Display is restricted to the zone, if given together with the keyword steering the display. Thus the definition of a zone can be done by the definition of certain commands and keywords (it is never predefined within the program). In the ZONE command a normal, "landscape" or quadratic shape is assumed. If the actual display region is "portrait", then the coordinate limits are interprted by exchanging x and y: x' = y y' = 1 - x Thus the same display will look differently on "landscape" and "portrait" size display areas. This effect is shown below in the figure for a zone, defined by the command LEFT = ZONE 0 0.5 0 1 (such a zone is in fact defined in the LOOK kernel). The zone definition is used dynamically: the division of the display area may be different on a hardcopy in "portrait" format compared to a screen in "landscape" format. landscape format portrait format 1.0+-----------------+ 1.0+-------------+-------------+ | / / / / / / / / | |/ / / / / / /| | |/ / / / / / / / /| y | / / / / / / | | y' | / "left" / / / | |/ left / / /| | |/ / / /| | | | | / / zone / | |/ zone /| | |/ / / / / / / / /| | / / / / / / | | 0.5+-----------------+ |/ / / / / / /| | | | | / / / / / / | | | | 0.0+-------------+-------------+ | | 0.0 0.5 x 1.0 | | | | | | 0.0+-----------------+ 0.0 x' 1.0 Figure 2: The zone defined by "LEFT = ZONE 0 0.5 0 1" for landscape (normal) and for portrait (x and y exchanged) formats. 1 Part 2 - 66 - 7. Zones _______________________________________________________________________ In some displays the display area, as defined by the zone command is automatically divided into near quadratic subzones. This is for example done in the FIGURE command, if more than one figure is displayed. Note: in a certain application program the commands may already contain zone definitions. Zone definitions cannot be nested. Example: Try (eventually after the FILLSOME command) the following commands interactively. FIGURE 1 - 10 ZONE 0.2 0.8 0.5 1.0 MANY = FIGURE 1 - 4 LEFT; FIGURE 11 - 20 RIGHT MANY 1 Part 2 - 67 - _______________________________________________________________________ An empty page. Pages 68-70 do no exist. Next page: 71 1 Part 3 - 71 - 1. Principles of LOOK _______________________________________________________________________ Part 3 GUIDE TO USER GRAPHICS PROGRAMS **************************************** 1. Principles of LOOK ===================== LOOK provides a certain scheme, which should allow the user to write subroutines for graphics in a simple way. In these subroutines LOOK subroutines are called, which perform certain GKS-functions and also organize the dialogue with the operator. Actual displays are done using the basic GKS output primitives (lines, markers, text, ...) All transformations or other functions are organized by the LOOK KERNEL functions; these for example open and activate workstations (terminals and hardcopy devices) with a maximum display surface, execute clear workstation commands etc. One principal design idea of LOOK is to make a large display program modular. The KERNEL of LOOK itself consists out of several packages with minimal interaction. User programs from different authors can be combined without any modification in the KERNEL, if the user programs do not violate certain rules. The KERNEL itself makes use only of lower level GKS functions, in order to be less machine dependent and to be able to work even with low-level implementations or subsets of GKS. +------------------------------------------------------+ | | | LOOK kernel (based on GKS) | | | +------------------------------------------------------+ | | | V V V | | | +-----------+ +-----------+ +-----------+ | Standard | | | | | | LOOK | | User displays | ...... | displays | | | | | +-----------+ +-----------+ +-----------+ The user can add his own subroutines with display functions and other interactive functions to the KERNEL of LOOK according to the figure above. The calling sequence is shown in the code below, assuming a user subroutine USERLK. * main program * ============ CALL LOOK STOP END SUBROUTINE LKUSER (LRET) ********************************************************************* * User subroutine. Call here all graphics applications ********************************************************************* IF (LRET .EQ. 0) THEN stop/exit/quit condition ELSEIF (LRET. GT. 0) THEN "RETURN " condition LRET contains the value of ELSE normal user execution: CALL USERLK ENDIF RETURN END Note, that the subroutine LKUSER is called from LOOK, and must not be called directly from the user code. 1 Part 3 - 72 - 1. Principles of LOOK _______________________________________________________________________ Explanation of the program: At the first entry to LKUSER, the value of the variable LRET is irrelevant; initialization is done for the LOOK package and LOOK is waiting for input of text by the operator. For every command, entered by the operator, LKUSER will return with the value LRET=-1; according to the above example, the user subroutine USERLK will then be called and may display something, if one of the keywords given by the operator results in a display. Subsequently LKUSER will be called again, and again will wait for input of text by the operator. A different control flow is taken, if the operator types the commands STOP or RETURN. After the input of STOP, LOOK will close the workstations and GKS itself, and will return with LRET=0. Under this condition, the user may execute STOP (in FORTRAN) either immediately or after his "final" procedure. After the input of "RETURN nloop" the LKUSER routine will return with LRET = nloop (LRET is set to at least 1), and if the users program does not modify a value of nloop, than the code corresponding to nloop > 0 will be executed nloop times (internally LOOK will subtract 1 from the value of LRET, and will return immediately again, if LRET remains positive). Thus the input of "RETURN nloop" means the execution of "nloop" loops before the next waiting in LOOK for new operator input. A special case is the detection of a stop condition in the users loop: in this case the user should set LRET to zero before the return from LKUSER. The rules for the structure of LOOK user subroutines is explained in the following chapters. Briefly, in writing these subroutine the user may make use of a set of subprograms provided with the LOOK system. The steering of the KERNEL functions and of functions of the user program is done using so called keywords, which are organized in a part of the LOOK KERNEL, known as the KEYword command processor. Keywords may be used to trigger execution of a program for a certain display. The program for a certain display is coded in two parts. In the first part the initialization of the display is done including a definition of the limits in world (or physics) coordinates. Various parameters can be defined in this part, in which the complete transformation from the world coordinates to the (internal) screen coordinates is fixed. In many cases it may be sufficient to use a keyword (GRWC or GRWC3) instead of program code. In the second part the GKS drawing primitives are used to draw lines, markers, text and areas. The GKS calls may be used directly (for example GPL for a polyline), but then the coordinates specified in these calls have to be transformed before from the system of world coordinates to the internal LOOK system. This internal system is necessary for various reasons; in this system the unit is cm (centimeter) and the whole screen corresponds to an area of about 20 cm * 20 cm. This area is mapped to the screen in a transformation, which preserves the aspect ratio (circles remain circles). There is a set of calls which correspond to the four GKS calls for graphics primitives and in which the transformation from the world coordinates is done internally (for example LGPL instead of GPL for polylines). The screen, as handeled by LOOK, is divided in 3 parts, as shown in fig 1 of Part 2 (the large display area for graphics may have a header box with some text, which can be switched on and off). The message line and the echo line do NOT exist on hardcopy devices, only on the graphics terminal with keyboard. LOOK supports output of text and of graphics. Certain LOOK commands result in the output of tables etc, which represent several lines of text. Also application programs written by a user may result in the output of some text. It is NOT recommended to mix output using GKS and output via statements like WRITE(*,...), although it may work on some installations. LOOK provides subroutines, which allow text output to the display, using GKS functions internally. It is recommended to use them, since they also provide some useful features. They allow for example the operator to skip some lines (in a long output) and allow the operator to look at previous text output. For short messages (one line of text) the LOOK message line should be used. 1 Part 3 - 73 - 2. Keyword steering _______________________________________________________________________ 2. Keyword steering =================== The explanation in this section assumes that the user (writer of a LOOK user program) is already familiar with the usage of keywords as an operator (see detailed explanation in part 2 of this manual). The program package KEYPACK contains the keyword-based LOOK command processor. The most important subprograms are: KEYDEF definition of a new keyword KEYWDL logical function, to test the presence of a keyword KEYVAL subprogram, to get values associated with the keyword A full description of the KEYPACK package is given in the appendix. 2.1 Definition of a keyword: --------------------------- A keyword can be defined interactively by a command given on the keyboard, for example KEYWD = keyword definition (see part 2 of this manual). Such a keyword definition can also be done within the program, by calling subroutine KEYDEF with that text as argument. CALL KEYDEF(' KEYWD = keyword definition ') where the keyword definition may contain: numerical constants (=initial values for the numerial parameters, associated with the keyword; text constant (=default text, associated with the keyword); help text within $'s; other keywords with numerical values and text. Example: CALL KEYDEF('MYCMD = 1 2.0 -17 ''my text'' ') This call defines the keyword MYCMD, with 3 numerical parameters and a text parameter (if the keyword was not yet existing before the call). The initially assigned numerical values are 1.0, 2.0 and -17.0 and the initially assigned text is 'my text' (note that according to the FORTRAN rules a quote ' has to be given twice inside a character string within quotes). Example: CALL KEYDEF(' MYOWN = 2.0 1 KEYWD 3 2 ') This call defines the keyword MYOWN, with 2 numerical parameters. The initially assigned numerical values are 2.0 and 1.0, in addition the text KEYWD 3 2 is assigned to the keyword; this text will be added automatically to every command with the keyword MYOWN. Note that keywords may be defined in the same way either by use of the KEYDEF subroutine or by direct commands during program execution. Before the first call to the keyword definition within LOOK application program, it is recommended to initialize a new chapter in LOOK Help: CALL LKIHLP('Application_program_name') which allows for a quasi hierarchical help in the interactive session, for example: CALL LKIHLP('H1 Event Display') 1 Part 3 - 74 - 2. Keyword steering _______________________________________________________________________ 2.2 Test of the presence of a keyword ------------------------------------- For each command input by the operator all internal LOOK and external user display subroutines are called. Within these subroutines the presence of keywords in the actual command can be tested by the logical function KEYWDL. Logical function KEYWDL(KEYWD) value = .TRUE. if the keyword KEYWD is in the actual command value = .FALSE. if the keyword KEYWD is not in the actual command Example: IF(KEYWDL('MYCMD')) THEN * code, executed, if the keyword MYCMD is in the actual command ... END IF 2.3 Parameters of a keyword --------------------------- The values of numerical parameters and of the text parameter can be obtained by the subroutine KEYVAL. ----- CALL KEYVAL(KEYWD,ARRAY,NEL,TEXT,NCH) ----- --- ---- --- where ARRAY = array of numerical values (dimension sufficient!) NEL = number of elements returned TEXT = character string NCH = number of characters returned Example: REAL ARRAY(3) CHARACTER*16 TEXT CALL KEYVAL('NEWCMD',ARRAY,NEL,TEXT,NCH) For the keyword 'NEWCMD' as defined above the values would be (before redefinition by a command): ARRAY(1) = 1.0 ARRAY(2) = 2.0 ARRAY(3) = -17.0 NEL = 3 TEXT = 'my text' NCH = 7 A more complete description of the functions of the KEYPACK subroutines is given in the appendix. In order to understand the possibilities provided by the LOOK command processor the reader should try to run interactive LOOK programs according to the explanations given in Part 2 of this manual. A keyword that is assigned to a certain program code in a user subroutine can be used as the trigger to execute part of the user program (and to make the display). Assuming that the keyword is DISPLAY the code fragment below shows the steering of the program. 1 Part 3 - 75 - 3. Graphical displays _______________________________________________________________________ ... * initialization phase of the program CALL KEYDEF(' DISPLAY = ') ... ... IF(KEYWDL('DISPLAY)) THEN * make the display ... END IF After input of the keyword DISPLAY in a command, the function KEYWDL will return the value "TRUE" and consequently the code to make the display will be executed. Keywords can be used in several ways to steer the program; the next section includes some aspects of this sharing of program logic between the program itself on the one side, and keywords in commands on the other. Often the program logic can be kept rather simple by moving some of the steering in the command/keyword part. Normally the program will wait after a display for new input by the operator via the keyboard. However as an alternative the user may define text for the next command to be executed by a call: CALL CMDNXT(command text) If the next command is defined in such a way, LOOK will not request for command input from the terminal, but instead process the given text. 3. Graphical displays ===================== 3.1 Display parameters ---------------------- A display is determined by a number of parameters. In general parameters can or have to be determined in the program; they can be modified by commands interactively or by predefined command text. Before any drawing, the parameters have to defined in the initialization phase of the program. Parameters refer to the following topics: > display style > zones and subzones > limits of world coordinates In this chapter an overview is given, a more detailed description is given in the chapter 3.3. a) Display style ~~~~~~~~~~~~~~~~ The display style is determined by the integer ISTYLE, with the meaning: ISTYLE meaning 0 no x-scale, no y-scale (whole zone for data display) 1 only x-scale (bottom) 2 only y-scale (left) 3 x- and y-scale (bottom and left) 4 x- and y-scale (box) (for 1...4 some part of the zone is used for scales, text) The display style is selected within the program by a call to the subroutine GRINIT, but can be modified by giving the keyword SCALES istyle 1 Part 3 - 76 - 3. Graphical displays _______________________________________________________________________ b) Zone and subzone ~~~~~~~~~~~~~~~~~~~ The zone is the display area on the screen. By default the whole screen is the display area and no change of this default is possible within the program. However, the zone can be modified by the keyword ZONE xa xb ya yb within commands. The default (whole screen) is ZONE 0 1 0 1. Within the program (and not by keywords) a subzone can be defined. A subzone I with I = 1 .. N can be selected out of a total of N subzones, with N = 1 .. 36. The subdivision is done dynamically at the display time; for the given zone and given number N the subdivision with near quadratic subzones is determined. The call to select subzone I out of N is CALL GRIOFN(I,N) c) Limits of world coordinates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The limits of word coordinates have to be determined within the program. For a two-dimensional display the limits are xa, xb, ya and yb and for a three-dimensional display there are in addition limits za and zb; these limits can be defined by a call. The actual limits of world coordinates at display time are in addition determined by keywords; in the order of increasing priority there are the following keywords: The limits defined in the program are overwriten by the keywords WC xa xb ya yb or WC3 xa xb ya yb za zb The limits are further overwritten by the limits given in the keywords SX, SY and SZ (see part 2 of this manual). The limits are further overwritten by ZOOM keywords, where the operator can define limits interactively. Finally the limits are influenced by the presence of the keyword ARP which may be used to require "Aspect Ratio Preservation". If this keyword is given, the limits given by other means are corrected in order to get the same units of length in the x- and y-direction (thus circles will be displayed as circles). The display parameter definition by program call and keywords is summarized in table 3. +-------------------+-------------------------------------------------+ | Parameters | defined by | | | program keyword | +-------------------+-------------------------------------------------+ | | | | display style | CALL GRINIT(istyle) SCALES istyle | | | | | ZONE on screen | --- ZONE xa xb ya yb | | | | | subzone | CALL GRIOFN(I,N) --- | | | | | display limits | CALL GRLIMT(...) WC ... | | | SX, SY (SZ) | | | ZOOM | | | ARP | | | | + ------------------+-------------------------------------------------+ Table. Areas of display parameters with subprogram and keyword names, resp., which are used to define them. 1 Part 3 - 77 - 3. Graphical displays _______________________________________________________________________ 3.2 LOOK transformations ------------------------ LOOK allows the use of either two-dimensional or three-dimensional world coordinates. In both cases the world coordinates are transformed to two-dimensional coordinates in the LOOK system. The LOOK system is a reference system, with units of cm (centimeter) in both directions, having the values (0.0,0.0) in the lower left corner. The whole screen (ZONE 0 1 0 1) corresponds to an area of about 20 cm * 20 cm; reduced zones correspond to a smaller area (area is proportional to the zone). The display area in the LOOK reference system has a ratio of width (x-dimension) to height (y-dimension) identical to the ratio on the screen. For GKS the LOOK reference system is the GKS world coordinate system. The GKS transformation number 1 is used to define the transformation from the LOOK reference system to the final screen device coordinates (this transformation number should not be modified by the user). For the drawing of markers, lines, areas and text the user can call directly the GKS subroutines for the drawing primitives with coordinates (tx,ty) in the LOOK reference system. All necessary GKS subroutine calls are explained in chapter 3.4. In addition there are several GKS-like calls, starting with L... in their name. They perform first the transformation to the LOOK system and then call internally the corresponding GKS subroutine. Note that LOOK allows three-dimensional (3D) displays to be made by using the standard 2D-GKS functions only. This is accomplished through the introduction of the LOOK reference system and the transformation of world coordinates to the LOOK reference system. There are other reasons for the introduction of this intermediate system. It simplifies the problem of getting visible text with correct width:height ratio within the graphics display. It also simplifies the problem of adding e.g. "short" lines to a display, with a length measured in "cm on the screen" and not in units of world coordinates (note that by zooming the world coordinate limits can be changed interactively). World coordinates px, py (pz) have to be transformed to the LOOK coordinate system with coordinates tx, ty; the transformed coordinates can then be used in the GKS calls directly: Transformation to transformed system (LOOK reference system): Input: PX, PY (PZ) = arrays of coordinates in world coordinates Result: TX, TY = arrays of coordinates in the LOOK ref. system CALL LTR(N,PX,PY,TX,TY) for 2-D CALL LTR3(N,PX,PY,PZ,TX,TY) for LOOK 3 D Input arguments in the calls are the arrays (dimension N) PX, PY (PZ) and they are not changed during the call. The resulting arrays with transformed coordinates are TX and TY. The arrays PX and TX, and the arrays PY and TY can be identical. 1 Part 3 - 78 - 3. Graphical displays _______________________________________________________________________ a.) Two-dimensional displays (2D) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The transformation from the coordinates (PX,PY) in world (or physical) coordinates to the coordinates (TX,TY) in the LOOK reference frame is sketched in the figure below. xa xb yb+--------------------+ | / / / / / / / / / /| LOOK |/ / / / / / / / / / | | / / / / / /| world coordinate system |/ / / / (PX,PY) / | | / / / / / /| (units are physical coordinates) |/ / / / / / / / / / | | / / / / / / / / / /| ya+--------------------+ V V \ LOOK \ LTR(N,PX,PY,TX,TY) \ \ \ transformation \ \ \ \ \ ycm+--------------------+ |/ / / / / / / | LOOK reference system | / / / / / (TX,TY) /| (units are cm on the screen) |/ / / / / / / | | / / / / / / / / / /| (= GKS world coordinate system) 0.0+--------------------+ 0.0 xcm Figure: The LOOK 2 D - transformation b.) Three-dimensional displays (3D) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The transformation from the three-dimensional system of world coordinates (PX,PY,PZ) to the two-dimensional LOOK reference system (TX,TY) is determined by parameters, which are specified with the keyword VIEW (and the keyword ROTATE): VIEW iaxis phi dip proji ROTATE dphi ddip The value of IAXIS (1 .. 3) determines the axis which points upward in the display. The LOOK transformation 3D -> 2D does not include a general rotation, but is restricted such that one of the three coordinate axes after transformation is pointing upwards on the screen. The transformation includes a rotation by an azimutal angle PHI and by a dip angle DIP, as given with the keyword VIEW, or by angles PHI+DPHI and DIP+DDIP, if the keyword ROTATE is given in addition. Finally there is a parameter PROJI, which is the inverse distance between viewpoint and object, in units determined by the size of the object. Inverse distance PROJI = 0 means parallel-projection (distance infinite). 1 Part 3 - 79 - 3. Graphical displays _______________________________________________________________________ 3.3 Initialization of a display ------------------------------- Each display has to be initialized with definition of the parameters determining the display, as described in chapter 3.1. a.) Simplified initialization by one call ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The initialization is done by the following calls for 2D- and 3D displays, respectively. The arguments xa, xb, ... are the limits in the world coordinate system. CALL GRWC(xa,xb,ya,yb) for 2D CALL GRWC3(xa,xb,ya,yb,za,zb) for 3D (LOOK 3D) The display style is assumed to be ISTYLE = 0, i.e. no scales are drawn (by the keyword SCALES this option can of course be modified). There is no subdivision of the zone. The limits in the world coordinates are taken exactly as given. Example: The following is a part of the code of a subroutine that is used to make a display of (yellow) stars at the coordinates XDATA(i), YDATA(i), for i=1 .. 100, which are known to be within the limits 0 to 100 in x and 0 to 200 in y. The display is triggered by the keyword SHOWDATA; if this keyword is given in a command the logical function KEYWDL returns "true" and the code within the IF-THEN/ENDIF statements is executed. To initialize the display (definition of the transformation etc) GRWC is called with the limits in x and y. REAL XDATA(100),YDATA(100) LOGICAL KEYWDL IF(KEYWDL('SHOWDATA')) THEN CALL GRWC(0.0,100.0,0.0,200.0) * choose yellow stars CALL GSMK(3) CALL GSPMCI(5) * transform and plot data CALL LGPM(100,XDATA,YDATA) END IF Interactively the world coordinates can be modified, for example by the keyword WC. A display of the data within limits 0 to 100 in both the x and the y coordinates is obtained by the command: WC 0 100 0 100 SHOWDATA The limits given with the keyword within the command have higher priority than the limits given in the call. Note that by zooming (keyword ZOOM) the limits can be modified further interactively. a'.) Simplified initialization using keyword ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Identical to the above calls (GRWC and GRWC3) in functionality is the use of the keywords GRWC and GRWC3 in commands: GRWC xa xb ya yb for 2D GRWC3 xa xb ya yb za zb for 3D (LOOK 3D) If these keywords are found in a command, the corresponding calls will be made with the given limits. These commands may be very useful, if parts of the display elements come from different modules, steered by different keywords. 1 Part 3 - 80 - 3. Graphical displays _______________________________________________________________________ Example: Assume that there are two modules MODULA and MODULB for two detector parts A and B, with a display triggered by keywords DISPLAYA and DISPLAYB. Then one can define the following commands DA = GRWC - 50 + 50 - 60 +160 DISPLAYA DB = GRWC -100 +100 -120 +120 DISPLAYB DC = GRWC -100 +100 -120 +120 DISPLAYA DISPLAYB By these commands either only one or the other detector part or both are displayed, within limits depending on the keyword. This example also demonstrates the use of keywords to simplify the logic within the program: the modules do not have to make the initialization and nothing has to be known on the limits. This part of the program logic can be made via the command structure. b.) Initialization with detailed definition of display parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The full initialization has to be done in the order given here. 1) Basic initialization and selection of display style: ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ CALL GRINIT(ISTYLE) Several internal parameters are reset by this call, which also selects the display style by the argument ISTYLE. ISTYLE meaning 0 no x-scale, no y-scale (whole zone for data display) 1 only x-scale (bottom) 2 only y-scale (left) 3 x- and y-scale (bottom and left) 4 x- and y-scale (box) (for 1...4 some part of the zone is used for scales, text) 2) Subdivision of the zone (zone is either full screen or reduced by ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ the keyword ZONE in the display command): CALL GRIOFN(I,N) optional, to define field I = 1 .. N with N = 1 .. 36 (default: zone 1 out of 1) As mentioned earlier (chapter 3.1) the zone cannot be defined within the program, but only by the keyword ZONE in commands. A discussion of zones is given in chapter 6 of part 2 of this manual. In this chapter the zone definition by LEFT = ZONE 0 0.5 0 1 is described as an example. The zone definition is used dynamically: the division of the display area may be different on a hardcopy in "portrait" format compared to a screen in "landscape" format, as can be seen in figure 4 below. 1 Part 3 - 81 - 3. Graphical displays _______________________________________________________________________ landscape format portrait format 1.0+-----------------+ 1.0+-------------+-------------+ | / / / / / / / / | |/ / / / / / /| | |/ / / / / / / / /| y | / / / / / / | | y' | / "left" / / / | |/ left / / /| | |/ / / /| | | | | / / zone / | |/ zone /| | |/ / / / / / / / /| | / / / / / / | | 0.5+-----------------+ |/ / / / / / /| | | | | / / / / / / | | | | 0.0+-------------+-------------+ | | 0.0 0.5 x 1.0 | | | | | | 0.0+-----------------+ 0.0 x' 1.0 Figure: The zone defined by "LEFT = ZONE 0 0.5 0 1" for landscape (normal) and for portrait (x and y exchanged) formats. Subroutine GRIOFN allows a subdivision of a zone into subzones (this subdivision cannot be done by keywords). A subzone I with I = 1 .. N can be selected out of a total of N subzones, with N = 1 .. 36. The subdivision is done dynamically at the display time; for the given zone and given number N the subdivision with near quadratic subzones is determined. The subdivision by subroutine GRIOFN is used in the standard FIGURE command to display more than one figure, and the reader may try this command to learn the possibilities. The figure below shows the result of the subdivision for N = 3, if the zone is defined by the command "LEFT". landscape format portrait format 1.0+-------------+-------------+ 1.0+-----+-----+-----+ | GRIOFN | | | | | | y | (1,3) | | y' |GRI |GRI |GRI | +-------------+ | | OFN| OFN| OFN| | GRIOFN | | |(1,3)|(2,3)|(3,3)| | (2,3) | | | | | | +-------------+ | 0.5+-----+-----+-----+ | GRIOFN | | | | | (3,3) | | | | 0.0+-------------+-------------+ | | 0.0 0.5 x 1.0 | | | | 0.0+-----------------+ 0.0 x' 1.0 Figure: The subdivision into N = 3 parts of the zone defined by "LEFT = ZONE 0 0.5 0 1" for landscape (normal) and for portrait (x and y exchanged) formats 1 Part 3 - 82 - 3. Graphical displays _______________________________________________________________________ 3) Definition of limits in x, y (and z). ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ For 2D-displays the data range has to be defined separately for x and for y, for 3D-display the data range has to be defined for z too, by using calls to the subroutines: CALL GRLIMT(OPT,A,B) OPT='SX' or 'SY' or 'SZ' single values A and B, no rounding CALL GRLIMT(OPT,N,ARRAY) OPT='SXN' or 'SYN' or 'SZN' array of values, with rounding CALL GRLIMT(OPT,A,B) OPT='SXM' or 'SYM' or 'SZM' single values A and B, with rounding In these calls A, B and the array elements ARRAY(1)...ARRAY(N) are coordinate values; the minimal and maximal value of all calls, which may appear in any order, are determined. These extreme values are then used to determine the trasformation. The "round" and the "noround" options are available. Actual rounding is done later, when the limits have to be used. The 3D-transformation is used if the z limits have been defined. 4) Final call to initialization: ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ CALL GRSHOW The transformation is defined, and if requested (ISTYLE > 0), the scales are drawn. If scales are drawn, the limits of the world coordinates do not correspond to the complete zone (or subzone), because some space is added around the scales for scale numbers, text etc. The simplified initialization described under a.) and a') above is equivalent to the code: CALL GRINIT(0) CALL GRLIMT('SX',xa,xb) CALL GRLIMT('SY',ya,yb) CALL GRSHOW The display style selected within the program by a call to the subroutine GRINIT can be modified by giving the keyword SCALES istyle The limits used for the calculation of the transformation in GRSHOW may not be the ones, defined before GRLIMT calls; the limits can be modified by the use of keywords, in the order of increasing priority: by definition of limits with keywords SX, SY (,SZ) by zooming options. by the ARP keyword; Zooming allows the operator to change the limits interactively directly on the screen. ARP abbreviates "Aspect Ratio Preservation" and means same units on the x- and y-scale; this option is selected by the keyword ARP together with the actual display keyword. All the options can be used simultaneously, for example if zooming is done on a display, where "ARP" was specified, the interactively defined limits are automatically modified to preserve the aspect ratio. 1 Part 3 - 83 - 3. Graphical displays _______________________________________________________________________ 3.4 The GKS drawing primitives ------------------------------ This chapter contains a complete description of the GKS calls which are used directly in the coding of LOOK subprograms. The calls for the four GKS output primitives - polyline, polymarker, fill area, text - and the related calls for the selection of the drawing parameters are given. As explained previously, the coordinates in these direct GKS calls have to be given in the LOOK reference system (cm-units). For each of the four drawing primitives there is one alternative (name starting with L...), where the transformation from the world coordinates to the LOOK reference system is done internally before the GKS call. Transformation to transformed system (LOOK reference system): Input: PX, PY (PZ) = arrays of coordinates in world coordinates Result: TX, TY = arrays of coordinates in the LOOK ref. system CALL LTR(N,PX,PY,TX,TY) for 2-D CALL LTR3(N,PX,PY,PZ,TX,TY) for LOOK 3 D The coordinates are transformed and may be used directly in calls with GKS drawing primitives. For enumerated types there is the PCM-style include file below: *MACRO ENUMSTYL * list of colours INTEGER GBLACK,GWHITE,GRED,GGREEN,GBLUE,GYELLO,GMAGEN,GCYAN PARAMETER (GBLACK=0,GWHITE=1,GRED =2,GGREEN=3, + GBLUE =4,GYELLO=5,GMAGEN=6,GCYAN =7) * list of line styles INTEGER GSOLID,GDASHE,GDOTTE,GDADOT PARAMETER (GSOLID=1,GDASHE=2,GDOTTE=3,GDADOT=4) * list of marker types INTEGER GDOT ,GPLUS ,GASTER,GCIRCL,GCROSS PARAMETER (GDOT =1,GPLUS =2,GASTER=3,GCIRCL=4,GCROSS=5) * list of fill area interior styles INTEGER GHOLLO,GFULL ,GHATCH PARAMETER (GHOLLO=0,GFULL =1,GHATCH=3) *END Colours ~~~~~~~ For all types of GKS objects the following standard colours may be specified: * list of colours INTEGER GBLACK,GWHITE,GRED,GGREEN,GBLUE,GYELLO,GMAGEN,GCYAN * Black = background colour, others are foreground colours PARAMETER (GBLACK=0,GWHITE=1,GRED =2,GGREEN=3, + GBLUE =4,GYELLO=5,GMAGEN=6,GCYAN =7) 1) Polylines ~~~~~~~~~~~~ CALL GPL(n,tx,ty) draw line segments (n > 1) or CALL LGPL(n,px,py) draw line segments (n > 1) 2D or CALL LGPL3(n,px,py,pz) draw line segments (n > 1) 3D CALL GSLN(linestyle) line style (see below) CALL GSPLCI(colour) colour index(see above) CALL GSLWSC(factor) line width scale factor (1.0 ... 10.0) * list of line styles INTEGER GSOLID,GDASHE,GDOTTE,GDADOT PARAMETER (GSOLID=1,GDASHE=2,GDOTTE=3,GDADOT=4) 1 Part 3 - 84 - 3. Graphical displays _______________________________________________________________________ 1a) Curves (all subprograms are LOOK subprograms, not GKS subprograms) ~~~~~~~~~~~ CALL GCU(n,tx,ty) draw curves (n > 1) or CALL LGCU(n,px,py) draw curves (n > 1) 2D A smooth curve is drawn exactly through the given points. Line style, colour and line width is selected by the calls given under 1). Depending on the data slightly different algorithms are used for the smooth interpolation between the points: (a) If x(i+1) > x(i) for all i = 1 ... n-1, then a function y=y(x) is assumed (unique y-value for each x). (b) Otherwise if the first and the last points are differrent, a curve x(s),y(s) is drawn (multiple y-values at some x possible). (c) If the first and the last points are identical, then a close curve is drawn (smooth even at first/last point). 2) Polymarker ~~~~~~~~~~~~~ CALL GPM(n,tx,ty) draw marker symbols (n > 0) or CALL LGPM(n,px,py) draw marker symbols (n > 0) 2D or CALL LGPM3(n,px,py,pz) draw marker symbols (n > 0) 3D CALL GSMK(marktype) marker type (see below) CALL GSPMCI(colour) colour index(see above) CALL GSMKSC(factor) marker size scale factor * list of marker types INTEGER GDOT ,GPLUS ,GASTER,GCIRCL,GCROSS PARAMETER (GDOT =1,GPLUS =2,GASTER=3,GCIRCL=4,GCROSS=5) 3) Text ~~~~~~~ CALL GTX(tx,ty,string) draw text or CALL LGTX(px,py,string) draw text 2D or CALL LGTX3(px,py,pz,string) draw text 3D CALL GSTXFP(font,prec) font and precision font = 1 default (fast) prec = 2 CALL GSTXCI(colour) colour index CALL GSCHH(height) character height (within LOOK in cm of display size) CALL GSCHUP(cx,cy) character up vector 0.,1. for usual upward text CALL GSTXAL(hor,vert) horizontal and vertical alignment relative to coordinates px,py hor = 1 left vert = 1 top = 2 center = 2 cap (level of capitals) = 3 right = 3 half (center of characters) = 4 base = 5 bottom CALL GSTXP(textpath) text path textpath = 0 right, perp. to up-vector (default) 1 left 2 up 3 down 1 Part 3 - 85 - 3. Graphical displays _______________________________________________________________________ 4) Fill area ~~~~~~~~~~~~ CALL GFA(n,tx,ty) fill area or CALL LGFA(n,px,py) fill area 2D or CALL LGFA3(n,px,py,pz) fill area 3D CALL GSFAIS(areastyle) fill area interior style (see below) CALL GSFACI(colour) colour index (see above) CALL GSFASI(stylind) fill area style index (see below) * list of fill area interior styles INTEGER GHOLLO,GFULL ,GHATCH PARAMETER (GHOLLO=0,GFULL =1,GHATCH=3) 3.5 Text in the graphics display -------------------------------- The area of the graphics display can be divided into a certain number of lines and columns at any time after initialization of a graphics display. The user may request a certain number of lines (NLINE) and of columns (NCOL) in a call to GRLNCL. The subroutine returns the actual number of lines (MLINE) and of columns (MCOL); these values depend on the shape and the size of the zone. By default (i.e. if GRLNCL is not called) there are at least 8 lines with 16 columns. ----- ---- CALL GRLNCL(NLINE,NCOL,MLINE,MCOL) ----- ---- The subroutine GRTEXT adds text to a certain line and column in the graphics display. Employing any font, it produces a monospaced font by positioning every character separately, and a quasi-monospaced one by positioning separately every group of consecutive non-blank characters. This ensures a (quasi)tabular location of characters. -- -- ---- CALL GRTEXT(IL,IC,TEXT) IL = line number IL = 1 ... MLINE IC = 1 left adjusted , monospaced = 0 centered , the whole text is positioned without an attempt to make it momospaced = -1 right adjusted, ------ " -------- = 1 ... MCOL starting at column IC, monospaced = 1001 ... 1000+MCOL starting at column IC-1000, quasi-monospaced In order to make use of the auxiliary font defined by the FONT2 keyword and intended mostly for tabular information, one can load (unload) this font in a relevant common by ---- CALL FNT2LD(CHXP)-- load the font2 : should be called before GRLNCL, CHXP is character expansion factor to be set temporarily CALL FNT2RM -- restore the previously loaded font : should be called after the last call of GRTEXT for the involved table. 1 Part 3 - 86 - 5. Text display _______________________________________________________________________ 4. Text display =============== LOOK provides two subroutines for text output within GKS to the so called "text" display (to be distinguished from the graphics display). A text line has a maximum of 80 columns. LOOK uses an internal buffer of several 100 lines, which allow the operator to obtain a display of previous text output. For short (= one line) text output it is recommended to use the message line (see Chapter 5), which has the advantage of not disturbing the large display area. If the user wants to add a group of text lines to the text output, he should follow the schema: Initially for a group of lines once CALL TXINIT(NRL) ! add a blank line to text output then for each line of text CALL TXSHOW(TEXT) ! add TEXT to text output IF(BREAKL(0)) GOTO ... ! test "break by operator Explanation: The output of a group of text lines is initialized by the TXINIT call, which also adds a blank line as separator to previous text output (if NRL=0, no blank line is added). The meaning of the argument NRL is "number of lines". If at the time of the call there is already text shown in the large display area, and there is space left in the display area for at least NRL lines, there will be no "clear screen", but the next text lines are added to the same display. If space for less than NRL lines is left, the screen will be cleared and the output of text will start at the top of the display area. If, within the execution of one command line, there is graphics output in addition, the output of text to the screen will be suppressed; the text will however be stored internally and can be inspected by the operator using the "TEXT" command, which switches back to the text display in the display area. A negative value of NRL defers output to the screen; the text will however be always stored internally. If, during output of text, the bottom of the display area is reached, LOOK will ask the operator: "hit enter to continue or enter number of lines to skip or enter break" If the operator hits enter, the screen will be cleared and the next text will appear on the top of the display area. If he enters a number, the display of this number of lines will be skipped internally. If the operator hits the break key or enters "break", the output of the group of lines should be stopped; therefore a test of the value of the logical function BREAKL should follow each call of TXSHOW. Example for text output in a user program: CHARACTER*80 TEXT LOGICAL BREAKL REAL X(10),Y(10) CALL TXINIT(3) CALL TXSHOW('index X Y') IF(BREAKL(0)) GOTO 20 DO 10 I=1,10 * internal write WRITE(TEXT,101) I,X(I),Y(I) 101 FORMAT(I5,2G12.4) CALL TXSHOW(TEXT) IF(BREAKL(0)) GOTO 20 10 CONTINUE 20 CONTINUE 1 Part 3 - 87 - 5. Dialogue, messages and alerts _______________________________________________________________________ 5. Dialogue, messages and alerts ================================ A message line is supported by LOOK for short messages and for communication with the operator (for examples questions with answer yes or no). The message line is at the bottom of the display above the echo line of command input. The message line is used by the KERNEL too, usually to show the last command of the operator. This message line may be overwritten using one of the calls described below, which also allow to restore the previous content of the message line. The message in the message line is changed, leaving the content of the remaining part of the screen unchanged. The message line has two parts, a left part (longer) and a right part (short). Most messages are shown in the left part. The operator may be asked for some input, for example yes/no or a numerical value; he may respond with "break". If the answer of the operator is formally wrong (for example the answer for a numerical value is non-numeric), the utility subprograms ask again automatically. The calls provided for the message line have the following parameters: TEXT = text, provided in the calling program, to be shown in the message line Following parameters are returned: VAL = numerical value (in floating point format) RTX = text (from input) The response "break" of the operator has to be tested by the logical function BREAKL (see below). The following calls are provided: Messages to the operator: CALL MESSGL(TEXT) show TEXT in the left part CALL MESSGR(TEXT) show TEXT in the right part CALL MESSGC show again last command Messages, which require response by the operator: CALL MESSGQ(TEXT) show TEXT and get back yes/no CALL MESSGV(VAL,TEXT) show TEXT and get back numerical value CALL MESSGT(RTX,TEXT) show TEXT and get back text RTX CALL MESSGM(IVAL,AW,TEXT) show TEXT as a menu and get back text AW plus an integer IVAL CALL MESSGH(IVAL,AW,TEXT) same as MESSGM but TEXT is assumed to consist of valid command keywords. More IVAL's are accepted from user: 0 (AW='0'), -1 (AW='UP'), -2 (HELP texts of keywords are shown and one more IVAL is expected). Good for tree. 1 Part 3 - 88 - 5. Dialogue, messages and alerts _______________________________________________________________________ The operator may respond with "break". In the case of MESSGQ this is interpreted as "no" and all input except "yes" (or equivalent) is interpreted as "no". The user/programmer should have a statement like IF(BREAKL(0)) GOTO ... immediately following one of the above MESSG_ calls. BREAKL is a logical function with a dummy argument; it has the value .TRUE. for a "break" response by the operator and the value .FALSE. otherwise. Examples for calls are: CALL MESSGL('Good morning!') CALL MESSGQ('Do you want to stop the program?') IF(BREAKL(0)) GOTO ... ! ("no" or "break") CALL MESSGV(VAL,'How many records?) IF(BREAKL(0)) GOTO ... NREC=VAL CALL MESSGT(RTX,'Please specify the file name!') IF(BREAKL(0)) GOTO ... FILE=RTX CALL MESSGM(IVAL,ANSWER,'Old New') IF(BREAKL(0)) GOTO ... In the last example, the message line will show 1=Old 2=New and a numerical value 1 or 2 is expected. Note that the numbers, which can be selected by the operator, are automatically inserted into the given text at each separation of items by a blank. If the operator enters such a number, it will be returned in IVAL and the corresponding text will be returned in ANSWER (for example IVAL=1 and ANSWER=Old). It is recommended, to show the last command again in the message line after a dialogue with the operator, by calling CALL MESSGC The right part of the message line is only used by the call CALL MESSGR(TEXT) and could be used to show a program status text; it is shown immediately. A possible application is to tell the user about the program status during a time consuming function, where the operator has to wait for some time: CALL MESSGR('Working...') ... CALL MESSGR('...finished') 1 Part 3 - 88a - 6. Main program and memory size _______________________________________________________________________ 6. Main program and memory size =============================== The simplest MAIN program for the LOOK-based interactive programs, shown already in section 1, looks like CALL LOOK STOP END Linked with a LOOK library, this program will have the LOOK data base, where all histograms and vectors are kept, of default size fixed at the time of compilation of the library. This size is equal usually to at least 1 megabyte = 250000 words. The size of available memory may be increased to NWLOOK words by extending the MAIN program as follows (the example is given for NWLOOK= 1000000): PARAMETER (NWLOOK=1000000) COMMON /COMIC/ IC(NWLOOK) LOGICAL BATCH COMMON /IBATCH/ BATCH CALL INITLB (NWLOOK) BATCH = .FALSE. CALL LOOK STOP END The above procedure of memory extension differs from the analogous procedure, used in batch programs (see Part 1 , section "Memory and ...") by explicitly defining the value of the variable BATCH in COMMON /IBATCH/. Note that all the principles of the memory management, described in Part 1, including an automatic memory extension with a disk space, apply to the interactive programs as well. 1 Appendix - 89 - 1. Installation _______________________________________________________________________ APPENDIX ******** 1. Installation =============== The source of the LOOK program is available after authorization in form of a CMZ file. To get a compile file, one has to select under CMZ all necessary compile options from the list below: -----------------+---------------------------------------------------- Machine version comment -----------------+---------------------------------------------------- IF= ALLIANT Alliant FX IF= APOLLO Apollo IF= DECS DEC workstations IF= HPUX X-window HP stations IF= IBM IBM VM/CMS (only!) IF= IBMMVS IBMMVS IF= IBMRT IBM Real Time systems IF= MACII Macintosh II IF= SGI Silicon Graphics IF= SUN SUN IF= VAX VAX IF= VAXSTN VAX workstations -----------------------------+---------------------------------------- Computer location comment -----------------+---------------------------------------------------- IF= AACH Aachen IF= BIRM University of Birmingham IF= DAVI University of California, Davis IF= DESY DESY IF= DESYGPX DESY VAX Gpx system IF= DESYPMES DESY VAXstation at PMES IF= ETHZ ETH-Zuerich at Villigen IF= LIVE Liverpool IF= LYON Lyon computer center IF= ORSA Orsay IF= QMWC Queen Mary and Westfield College London IF= RAL Rutherford and Appleton Laboratory IF= ROME Rome IF= ZEUT Zeuthen IF= ZUER Zuerich -----------------+---------------------------------------------------- Other specifiers comment -----------------+---------------------------------------------------- IF= GDDM Use HIGZGDDM interface IF= H1 Include H1 specific stuff IF= HELP Select help comments IF= LKBUF04M Use 4 Mb LOOK database common COMIC IF= LKBUF16M Use 16 Mb LOOK database common COMIC IF= LKBUF64M Use 64 Mb LOOK database common COMIC IF= LOOK1 Select LOOK 1.xx/yy code IF= MAINLOOK Select standard main LOOK program IF= MOTIF Select version using MOTIF interface IF= NOBOS Remove all references to BOS IF= READLINE GNU READLINE package for cmd input (UNIX platforms) IF= VAXDWCAL Dec Windows on H1 calorimeter VAX IF= VAXSHARE Shared LOOK commons for VAX -----------------+---------------------------------------------------- By default, 1 Mb LOOK database common COMIC will be selected and LOOK- BOS interface part will be included. 1 Appendix - 90 - 1. Installation _______________________________________________________________________ For an additional installation it may be necessary to add certain machine dependent macros, and to add a macro INSTALL for the installation. The DESYIBM version of this macro is shown below: KEEP, HINSTALL. workstation tables for various systems ----------------------------------------------------------------------- Table of workstation data = 3 integers (wtype conid nr) per workstation wtype = workstation type (GKS) conid = connection identifier (GKS) nr = 0 terminal > 0 plotter or metafile output. Number to be used in PL or PLOTTER command (unique) ----------------------------------------------------------------------- KEEP, INSTALL, IF=IBMMVS,IF=DESY. DESY IBM installation ----------------------------------------------------------------------- PARAMETER (NTABWK=26) INTEGER ITABWK(3,NTABWK) CHARACTER*40 TTABWK(NTABWK),TXTLAB Text to describe lab/computer DATA TXTLAB /'DESY Hamburg / central IBM systems'/ DATA ITABWK / ----- terminals ------------------------------------------------------ + 5005, 1, 0, 5003, 1, 0, 4702, 1, 0, + 4713, 51, 0, 4713, 52, 0, 4713, 53, 0, + 7878, 11, 0, 104, 11, 0, 121, 11, 0, + 4725, 1, 0, ----- laserprinters -------------------------------------------------- + 13001, 101, 11, 13002, 101, 1, + 12201, 107, 17, 12202, 107, 7, 12203, 107, 18, + 12204, 107, 8, 12201, 207,117, 12202, 207,107, + 12203, 207,118, 12204, 207,108, + 5010, 1, 19, 5020, 1, 9, ----- other units ---------------------------------------------------- + 5011, 2, 21, + 4, 33, 51, 5, 34, 52, 10201, 32, 53/ text description in same order DATA TTABWK / ----- terminals ------------------------------------------------------ + 'MacII 3270 emulation', 'IBM graphic terminal e.g. 3192G', + 'Tektronix-619 storage-screen','Atari MICOM 4 (GA)', + 'Atari MICOM IBM', 'Atari MICOM Apollo', + 'FALCO cheap terminal', 'TEK 4010/4014', + 'TEK 4107', 'Workstation X-terminal', ----- laserprinters -------------------------------------------------- + 'QMS L1 portrait ', 'QMS L1 landscape', + 'Postscript Color Printer Portrait ', + 'Postscript Color Printer Landscape ', + 'Postscript Monochrome Printer portrait ', + 'Postscript Monochrome Printer landscape ', + 'Encapsulated Postscript Portrait Colour ', + 'Encapsulated Postscript Landscape Colour', + 'Encapsulated Postscript Portrait Mono. ', + 'Encapsulated Postscript landscape Mono. ', + 'Laserprinter 3820 (LI1) portrait ', + 'Laserprinter 3820 (LI1) landscape ', ----- other units ---------------------------------------------------- + 'Matrix printer IBM ext', 'Metafile output GKS-2D ', + 'Metafile input GKS-2D ', '2D-Metafile output GKS-3D'/ error file DATA IERFIL /6/ To resolve all sequences one needs to use also FPACK cmz file in the installation procedure. An example for DESY IBM is given below. IBM version needs one assembler routine YYAIBM (kept in LOOK cmz file) which has to be extracted and compiled separately, since CMZ does not support assempler language. 1 Appendix - 91 - 1. Installation _______________________________________________________________________ *---------------------------------------------------------------------- * * (H 1) L O O K Installation kumac for DESY IBM version * * Note, that at DESY IBM you m u s t allocate datasets for * the LOOK Kernel libraries in advance, since default number of * directory blocks (50) is not enough! * Use NEWLIB CLIST command ALLOC to allocate file H1.LOOK.LOAD * (specify 80-90 blocks for the directories) * *---------------------------------------------------------------------- * MESSAGE 'Installation procedure for the complete H1 Graphics' file .HERA01.H1UTIL file .HERA01.H1PHAN file .HERA01.H1REC file .HERA01.H1.FPACK file .HERA01.H1.LOOK file .HERA01.H1LOOK * MESSAGE ' ' MESSAGE 'Step 1) Create LOOK library with 16 Mb memory /COMIC/' SEL IBMMVS DESY LKBUF16M H1 SEQ //LOOK/LOOK_MACROS SEQ //FPACK/FPACK_MACROS SET H1.LOOK.LOAD -L CD //LOOK V CFL * MESSAGE 'Extract assembler code to be compiled "by hand"' SET H1.LOOK.ASS -D CD //LOOK/YYIBM CTOT -S -D YYAIBM * MESSAGE ' ' MESSAGE 'Step 2) Create H1LOOK library for the H1 Event Display' SEL EVLOOK RCLOOK PHLOOK DATMAN H1MODS SEQ //H1LOOK/H1LOOK_MACROS SEQ //H1UTIL/H1UTIL_MACROS SEQ //H1REC/H1REC_MACROS SEQ //H1PHAN/H1PHAN_MACROS REL FPACK H1UTIL H1PHAN H1REC SET H1LOOK.LOAD -L CD //H1LOOK V CFL * * MESSAGE ' ' MESSAGE 'Step 3) Extract LOOK help file - for interactive use' SET H1LOOK.HELP -F TEXT CD //LOOK/TEXTFILE CTOT -S -D LHELP H1HELP * MESSAGE ' ' MESSAGE 'Step 4) Extract H1LOOK command file (macro file for H1ED)' SET H01.H1LOOK.MACRO -F TEXT CD //H1LOOK/COMMAND_FILES CTOT -S -D DEFAULT * MESSAGE ' ' MESSAGE 'Step 5) Extract H1LOOK Manual and put it in a text file' SET H1LOOK.MANUAL -F TEXT CD //H1LOOK/MANUAL CTOT -S -D * * MESSAGE 'Do not forget to add YYAIBM to the LOOK.LOAD !' MESSAGE 'End of installation. Bye !' EXIT 1 Appendix - 92 - 2. Bank layout for distributions _______________________________________________________________________ 2. Bank layout for distributions ================================ For documentation the layout of the basic bank for histograms and vectors is given below. The normal user does not need any knowledge about these internal details. Content of basic bank five basic steering words 1 length of basic region (=pointer to buffer region) 2 data type, derived from data name 3 attribute 1 graphics representation 4 attribute 2 graphics mode 5 attribute 3 colour index five control words for read/write ... 6 NWB 0=unbinned 1=weight1 2=weightvar 7 NTB total number of bins 8 NDL data length (0= variable) 9 NRRE number of read-record 10 IRRE pointer within read-record statistical information 11 total weight = sum of all weights 12 total number of entries 13 xmin for graphics (not in records) 14 xmax 15 ymin 16 ymax 17 zmin 18 zmax for histograms only 19 sum of squares of all weights 20 =0 single value storage =1 histogram storage mode 21 NX bin definition for X 22 XA 23 XB 24 xmin 25 xmax 26 x mean 27 x sigma 28 xref 29 sum x 30 sum x**2 31 NY bin definition for Y 32 YA 33 YB 34 ymin 35 ymax 36 y mean 37 y sigma 38 yref 39 sum y 40 sum y**2 41 x low entries onedimensional histogram 42 x inside -"- 43 x high -"- 41 x low y low entries twodimensional histogram 42 x inside y low -"- 43 x high y low -"- 44 x low y inside -"- 45 x inside y inside -"- 46 x high y inside -"- 47 x low y high -"- 48 x inside y high -"- 49 x high y high -"- 50 51...350 buffer part 1 Appendix - 93 - 3. The LOOK command processor _______________________________________________________________________ 3. The LOOK command processor ============================= The KEYPACK package of subroutines is used for most of the operations with commands. It is a small, independent package of subroutines. It uses a numeric and a character common, and allows to create banks, identified by a so-called keyword. Within a bank up to ND numeric parameters can be stored. In addition three types of text can be stored, characterized by the letters T for text parameter, C for command text, and H for help text, associated to the keyword. The bank structure is as follows: IND - 4 pointer to help text IND - 3 pointer to command text IND - 2 pointer to text parameter IND - 1 control word IND number of numerical data = ND IND + 1 numerical data 1 ... IND + N numerical data ND Access to the (numerical or text) parameters of a bank can be done by calls (store/get), or (for experts) directly. Initialization -------------- The package is initialized by a call to KEYNIT, where the dimension parameters of the numerical and the text common are specified as arguments. Initialization by the user is not necessary, if the default dimension are sufficient. Otherwise the user has to define correponding commons. COMMON/KEYNUC/JG(NJG) CHARACTER*8 TG COMMON/KEYTEX/TG(NTG) CALL KEYNIT(NJG,NTG) where: NJG = dimension of array JG in common /KEYNUC/ NTG = dimension of array TG in common /KEYTEX/ Creation of a keyword-bank -------------------------- A bank is characterized by a keyword, and is created by a call to KEYBNK. ----- -- CALL KEYBNK(KEYWD,ND,IER) --- where: KEYWD = keyword (character string, up to 8 characters) ND = number of numerical data words IER = returned error flag = 0 no error = 1 bank already existing (unchanged) = 2 insufficient space All numerical data words are set to zero, all text strings corresponding to this keyword are reset to zero-length. 1 Appendix - 94 - 3. The LOOK command processor _______________________________________________________________________ Index of a bank --------------- The index IND of a bank is obtained by a call to the function KEYIND. The position of a bank may change, if a bank is dropped. ----- IND = KEYIND(KEYWD) where: KEYWD = keyword (character string, up to 8 characters) IND = returned index or flag > 0 index of bank < 0 bank not existing Dropping a bank --------------- The bank is dropped by a call to KEYDRP; a garbage collection is done automatically in the numerical and the text array. ----- CALL KEYDRP(KEYWD) where: KEYWD = keyword (character string, up to 8 characters) The subroutines returns without action, if the bank cannot be found or if the bank is protected Storing and retrieving data --------------------------- a) Simplified call ~~~~~~~~~~~~~~~~~~ Numerical values and text parameters are obtained by calling KEYVAL. ----- CALL KEYVAL(KEYWD,AR,ND,TEXT,NCH) -- -- ---- --- where: KEYWD = keyword (character string, up to 8 characters) AR = array (floating point) for data to be obtained ND = number of data words TEXT = text NCH = number of characters The array AR is filled with the ND data from the bank, no check for the length of the array is done. The string TEXT will contain after return the text stored with the bank. b) Numerical data ~~~~~~~~~~~~~~~~~ Numerical data are stored under a given keyword by calling KEYWSV. ----- --- -- CALL KEYWSV(KEYWD,NAR,AR,IER) --- where: KEYWD = keyword (character string, up to 8 characters) NAR = dimension parameter of array AR AR = array (floating point) with data to be stored IER = error flag = 0 no error = 1 bank not existing = ? NAR greater than bank length 1 Appendix - 95 - 3. The LOOK command processor _______________________________________________________________________ The bank content is replaced by the data of array AR. If NAR is less than the bank length, the remaining bank data words are set to zero. If the dimension parameter is larger than the bank length N, only the first N elements of the array are stored in the bank. Numerical data are fetched by calling either KEYWGV (all data) or KEYWG1V (just one single parameter). ----- --- CALL KEYWGV(KEYWD,NAR,AR,NDL) -- --- where: KEYWD = keyword (character string, up to 8 characters) NAR = dimension parameter of array AR AR = array (floating point) for data to be fetched NDL = number of parameters stored at the last call of subroutine KEYWSV The content of the array AR is replaced by the data from the bank. If the dimension parameter is larger than the bank length N, only the first N elements of the array are filled, otherwise all NAR array elements are filled from the bank. ----- ---- CALL KEYWG1V(KEYWD,IPAR,PAR,IER) --- --- where: KEYWD = keyword (of type character, up to 8 characters) IPAR = parameter number PAR = fetched parameter value if IERR.ne.0 (0. otherwise) IER = error flag: = 0 : OK = 1 : keyword not defined = 2 : IPAR is out of range c) Text ~~~~~~~ Text is stored under a given keyword by calling KEYWST. ----- --- ---- CALL KEYWST(KEYWD,TCH,TEXT,IER) --- where: KEYWD = keyword (character string, up to 8 characters) TCH = character, describing type of text = either T or C or H (for the text parameter, for the comand. connected to the keyword, and for help text, respectively (character*1) TEXT = character string IER = error flag = 0 no error = 1 bank not existing = 2 insufficient space in text array = 2 wrong argument TCH = 7 bank protected against change of command-text Text stored in the bank before the call is overwritten by the call. There is no limit for the length of the text. Text is fetched from the bank by calling KEYWGT. ----- --- CALL KEYWGT(KEYWD,TCH,TEXT,NCH) ---- --- where: KEYWD = keyword (character string, up to 8 characters) TCH = character, describing type of text = either T or C or H (for the text parameter, for the comand. connected to the keyword, and for help text, respectively (character*1) TEXT = character string, filled with text from the bank NCH = number of last non-blank character in TEXT 1 Appendix - 96 - 3. The LOOK command processor _______________________________________________________________________ Control data ------------ The control word within a bank contains the following data: JN = last number of data words stored JP = 0 defined by operator = 1...9 defined within program JL = 0 not locked = 1 locked Parameter JP is used internally to distinguish between different HELP chapters. Control words are fetched by calling KEYWSC. ---- CALL KEYWSC(KEYWD,JN,JP,JL) -- -- -- Control words are stored by calling KEYWGC. ----- -- -- -- CALL KEYWGC(KEYWD,JN,JP,JL) Command definition within the program ------------------------------------- Commands can be defined within the program by giving the command text as argument of subroutine KEYDEF. ------------- CALL KEYDEF('command text') Command definition by operator ------------------------------ A subroutine KEYCMD is used for the command execution together with the logical function KEYWDL ---- ----- CALL KEYCMD(text,ltext,iret) ---- where IRET > 0 number of keywords to process IRET = 0 no keyword IRET > 0 negative error code (new text input in case of IRET = 0 or IRET < 0) KEYWDL(keywd) = .true. if keywd in last command = .false. if keywd not in last command Internal subroutines -------------------- Internal subroutine KEYDRT for text removal. Dump ---- For test purposes there is subroutine KEYDMP, which prints on the standard print unit the content of the numerical array and the text array. CALL KEYDMP 1 Appendix - 97 - 4. Creation of LOOK executable _______________________________________________________________________ 4. Creation of LOOK executable at DESY IBM ========================================== // JOB CLASS=A,MSGLEVEL=(2,0),TIME=(00,00),NOTIFY=F11LEV //*MAIN RELPRI=HIG,LINES=5 //******************************************************************** //* Creation of the executable module for LOOK Kernel //* //* F O R T R A N IBM VS (with Dynamic Common allocation) //******************************************************************** //* // EXEC VFORTCL, // CPRM='DC(BCS,COMIC,CYYMEM)', // LPRM='AMODE=31,RMODE=ANY', //* // LLB1='HERA01.H1.LOOK.LOAD', LOOK library // LLB2='HERA01.H1LOOK.LOAD', H1LOOK library (for lumi) // LLB3='HERA01.H1UTIL.LOAD', BOS-FPACK interface // LLB4='HERA01.H1.FPACK.LOAD', F-package // LLB5='HERA01.H1.BOS.LOAD', BOS // LLB6='R02SCH.GKS2D.LOAD', GKS // LLB7='R02SCH.GKSDRIV.LOAD', GKS drivers // LLB8='R01UTL.CERN.PRO.PACKLIB' CERN library //* //C.SYSIN DD * PROGRAM H1LOOK *********************************************************************** * Main program for the LOOK Kernel standard display. * SEL LOOK1 selects version for the LOOK 1.xx/yy * otherwise selects version for the LOOK 2.xx/yy *********************************************************************** PARAMETER (LIW = 250000) COMMON /BCS/ IW(LIW) CALL BNAMES(1000) CALL BOS (IW,LIW) CALL LOBOIF CALL IXINITC CALL LOOK STOP END SUBROUTINE LKUSER (LRET) *********************************************************************** * * User subroutine. Call here all graphics applications * *********************************************************************** IF (LRET .LT. 0) THEN * BOS records handling CALL LOOKBS * display online luminosity data CALL LUMIH1 * ENDIF RETURN END //L.SYSLMOD DD DSN=HERA01.H1LOOK.EXEC(LOOK),DISP=SHR //L.SYSIN DD * INCLUDE SYSLIB(GKDDLKH1) // 1 Appendix - 98 - 5. GKS/PS encodings for Greek _______________________________________________________________________ 5. GKS and PS encodings for Greek letters ========================================= The GKS encoding for Greek letters is that needed intrinsically for GKS Greek fonts (iprec=2, ifont=-...13, see command FONT for details). Similarly the slightly different PS encoding is that of PS Greek font (iprec=0,ifont=-12). These fonts are usually invoked automatically when constructions like \g{some_text} appear in text commands (STEXT etc.). Both may be used. You have only to inform LOOK about your choice with GREEK command. GREEK 1 (default) specifies the GKS encoding. In this case, if current font is a PS one, the text will be re-coded automatically into the PS encoding. Similarly, GREEK 2 specifies the PS encoding. The tables of encodings are given below for Greek alphabet, extended by versions of small letters epsilon, theta, pi, rho, sigma (LaTeX names varepsilon, vartheta, varpi, varrho, varsigma are used). Sign "-" denotes the absense of a letter in an encoding. Sign "=" for the PS encoding means that it is identical to the GKS one. +-------------+----------------------------+ |What you want| What you type | +-------------+-------------+--------------+ | | GKS | PS | | | encoding | encoding | | +-------------+--------------+ | Greek | | | | letter | Cap. Sm. | Cap. Sm. | +-------------+-------------+--------------+ | | | | | | | | | alpha | A a | = = | | beta | B b | = = | | gamma | G g | = = | | delta | D d | = = | | epsilon | E - | = - | | varepsilon | e | = | | zeta | Z z | = = | | eta | H h | = = | | theta | Y - | Q q | | vartheta | y | J | | iota | I i | = = | | kappa | K k | = = | | lambda | L l | = = | | mu | M m | = = | | nu | N n | = = | | ksi | X x | = = | | omicron | U u | O o | | pi | P p | = = | | varpi | - | v | | rho | R r | = = | | varrho | - | - | | sigma | S s | = = | | varsigma | - | V | | tau | T t | = = | | upsilon | V v | U u | | phi | F - | = f | | varphi | f | j | | chi | C c | = = | | psi | W w | Y y | | omega | O o | W w | +-------------+----------------------------+ 1 Appendix - 99 - 6. PostScript output at DESY IBM _______________________________________________________________________ 6. PostScript output at DESY IBM ================================ PostScript is a specially formatted graphical output which can be used either for direct plotting on PostScript plotters or for a file transfer over the networks. So called "encapsulated" PostScript allows to include pictures in a TeX files (but can not be directly plotted!). In order to use PostScript in LOOK, one has to allocate an existing sequential file to the unit 77 before starting LOOK session and then to use in the PL command one of the supported numbers: 7,17,8,18,107, .... A list of the existing PostScript units can be inspected with a command PLOTTERS. Note, that each change of plotter number during LOOK session (which is possible and correct for the normal laserprinters), will lead to overwriting of the old PostScript file content by the latest stuff, e.g. PL 17 ! writes picture on unit 77 for a portrait colour PS plotter PL 118 ! overwrites content of the file allocated to unit 77 with a ! new picture in the encapsulated PostScript format After finishing of LOOK session a file containing PostScript graphics can be sent to any PostScript plotter by the command PLOT. Encapsulated PostScript output should be converted from sequential text file to the partitioned dataset (one picture per member) as required by the TeX implementation at DESY IBM. This is done by a special procedure EPS (see below). For those who do not very well familiar with DESY IBM system, all steps are explained below in details (steps 1-2 need to be done only once). File name F99ABC.LOOK.PS, used in the description should be replaced by the actual file name. 1) Once create a sequential file, e.g. F99ABC.LOOK.PS (this should be a formatted text file, use CARDIM for DCB in NEWLIB ALLOC procedure; specify space of 5-10 tracks with a secondary space of 5 tracks). It is recommended to use PS as a rightmost period of the dsname. This will simplify PLOT command (see help PLOT in the NEWLIB). 2) Include in your CLIST(#START) member the following lines: IF DSN('FT77F001') = 'F99ABC.LOOK.PS' GOTO L1 IF DSN('FT77F001') ^= ' ' FREE F(FT77F001) ALLOC DATASET(LOOK.PS) FILE(FT77F001) OLD LABEL L1 This will automatically allocate dataset for LOOK PostScript output whenever you will logon at DESY IBM. 3) Plotting of normal PostScript files. ------------------------------------ Note, that unlike laserprinters L1-L6 your normal PostScript dataset will not be plotted automatically after finishing of LOOK session! You have to send your output file on any wanted PostScript plotter by means of the NEWLIB command PLOT: plot look.ps dest h01ps3 Here destination H01PS3 means H1 Plotter in the North Hall. In order to get an overview of all possible destinations as well as further supported options one can do: HELP PLOT under NEWLIB. 4) Using of encapsulated PostScript files (EPS) for LaTeX. ------------------------------------------------------- Encapsulated PostScript graphics (i.e. fugures produced within LOOK by command PL nn with nn = 107,117,108 or 118) can be included in LaTeX files using special "epsfig" style (see HELP TEXMACROS, then select Macros for including EPS-graphics in (La)TeX documents).