Experimenter's Guide To Daphne Page 1 Daphne Data Acquisition System - Overview 3 October 1990 1 Daphne Data Acquisition System - Overview The Daphne data acquisition system consists of the following major parts: - Host Computer The host computer is a VAX manufactured by Digital Equipment Corporation. Through programs running on the host a user describes what data is to be collected and how it is to be processed. The host controls the Camac and Event Processor subsystems. The host provides the software and peripherals for producing graphics displays, hardcopy plots, and recording data on tape or disk. - High Speed Camac Acquisition - Event Handler Data read-out is performed by a specialized computer, called the Event Handler (EH), designed by D. C. Hensley of Oak Ridge National Laboratory. The Event Handler has an instruction time of about 500 nSec, but other parts of the Daphne system limit data rates to something less than what the Event Handler is capable of. Daphne can provide fast read-out of up to two crates of Camac hardware with a single Event Handler, or up to four crates by using two Event Handlers in a master/slave arrangement. - Low Speed Camac Control - RS232 Camac Crate Controller An experimenter can control low data rate Camac hardware from the host by programming a Kinetic Systems Model 3989 RS-232 crate controller (KS/CC). For instance, an experimenter could program a Camac controlled power supply so as to sweep back and forth through a range of voltages, stepping the voltage at one-second intervals. - Event Processors Data read-out from the Camac hardware is processed by one of several microprocessors running in parallel. As many as five processors have been used simultaneously in the processing of data from a single experiment. The microprocessor is an NS32016 with NS32081 floating point processor, both manufactured by National Semiconductor Corporation. Analysis might consist in checking for data within certain ranges, checking for certain bits being set, and various combinations of conditions. It might also involve a limited amount of arithmetic on the original data of an event to produce more meaningful "pseudo-parameters". The pseudo-parameters can be computed by a user suppplied Fortran subroutine. The results of analysis on the microprocessors is a list of histogram bins which should be incremented. The list of bins to be incremented are collected into large blocks and transmitted to the host where the histograms are actually located. The list is in the form of VAX machine instructions. If the user wants the original data recorded, that too is collected into large blocks and forwarded to the host for recording on tape. Experimenter's Guide To Daphne Page 2 Major Steps in Acquiring Data Using Daphne 3 October 1990 2 Major Steps in Acquiring Data Using Daphne The following are the major steps in using Daphne to acquire data: - If unfamiliar with Daphne objects such as maps, conditions, and pseudo-parameters then read section 5 ("Daphne Objects"). - Use $DAP to initialize Daphne (Section 6.3) - Specify options and override defaults Use $MAX to specify limits (Section 6.4) Use $PSEUDOEVENT to enable use of pseudo-parameters (Section 6.7) - Define I/O devices Use $CDV to define the Camac crate (Section 6.8) Use $MDV to define the Multibus (Section 6.9) Use $DDV to define the display device (Section 6.10) Use $PDV to define the hardcopy plot device (Section 6.11) - Use $EVS to define the event structure (Section 6.13) - Program the Event Handler - Determine Camac modules to read, the order of read-out, etc. - Read "Overview of a Daphne Event Handler Program" (Section 19) - Read "Programming the Event Handler" (Section 20) - Write the Event Handler program - Use $EHASM to assemble the Event Handler program (Section 20.9) - Connect the Event Handler to the trigger electronics (Section 21) - Check hardware setup steps frequently overlooked (Section 6.12) - Use $EHSEND to load the Event Handler (Section 20.10) Experimenter's Guide To Daphne Page 3 Major Steps in Acquiring Data Using Daphne 3 October 1990 - If you intend to write a user-function to compute pseudo-parameters or to unpack a variable length event: - Use $PSEUDOEVENT to enable use of pseudo-parameters (Section 6.7) - Read "User-Functions" (Section 24) - Do you want to be able to change the values of some variables in your user-function during acquisition ? See section 22 on how to define FIX ("fixed-point" or integer) and FLT ("floating-point" or real) variables in your user-function in such a way that they can be changed from the VAX during acquisition. - Compile and link your user-function (Section 26) - If NOT using pseudo-parameters use the standard Event Processor program DAPEP:STANDARD (Section 27.3) - Use $EPLOAD to load the Event Processors (Section 27) - Define histograms, maps, and conditions (Sections 5 and 7) - Define scatterplots (Section 33) - Use $SCL/FILE to define scaler channels to be read periodically (Section 8.10) - Use $SAV or $SAV/COMMAND to save definitions - Use $TAPE/OUT to ready tape for event mode recording (Section 17) - Use $TEV/OFF to disable event mode recording Use $TEV to re-enable event mode recording - Use $INZ to enter run number, comments, and other banner information (Section 28) - Use $ACQ to start acquisition (Section 29) - Use $FIX and $FLT (Section 22) to adjust FIX and FLT parameters during acquisition - Use $D1H/$D2H and other programs to display histograms (Section 32) - Use $SP/CREATE to create and $SP to display scatterplots (Section 33) Experimenter's Guide To Daphne Page 4 Major Steps in Acquiring Data Using Daphne 3 October 1990 - Use $DSV and $PTSV to monitor scalers (Section 8.13) - Use $STP to stop acquisition (Section 30) - Use $WR if you wish to save histograms on disk or tape You cannot save histograms on an event mode tape To use $WR with tape, the tape must be in VAX/VMS format - Use $CNT/OUTPUT if you wish to save condition counts on disk - Use $PTSV/OUTPUT if you wish to save scaler counts on disk - Use $ZAP to clear histograms, condition counts, and scaler counts - Use $KLT when changing tapes (Section 18) - Use $EXT to exit from Daphne and release system resources - About once a day back up important files to tape (Section 50). Experimenter's Guide To Daphne Page 5 Major Steps in Acquiring Data Using Daphne 3 October 1990 The following shows all the commands that need to be issued to read and display a histogram for the first channel of an Ortec 811 ADC in slot 1 of the Camac crate at the spectrograph experimental station of Atlas: +---------------------------------------------------------------------+ | Username: EXP (log in to VAX/VMS | | Password: | | | | $ create/directory [EXP.ICE] (separate directory for your files | | $ set default [EXP.ICE] (make it the default directory | | $ dap ice (start Daphne with id "ICE" | | $ cdv tzc4 (specify Camac interface | | $ mdv a (specify Multibus interface | | $ ddv/type=4115/dma=xta0 tzc2 (display device with DMA interface | | $ ehasm read811 (assemble Event Handler program | | | | Where READ811.EHA contains: | | | | +-------------------------------------------------------+ | | | bru start ; jump to Daphne part | | | | | | | |init cnaf 1,1,7,2 ; reset ADC | | | | brur ; subroutine return | | | | | | | |main dlay 100*10 ; wait 100 uSec | | | | ; for ADC conversion | | | | ; (100 nSec units) | | | | cnaf 1,1,0,0 ; read ADC chan 0 | | | | out ca1 ; output for analysis | | | | cnaf 1,1,7,2 ; reset ADC | | | | brur ; subroutine return | | | | | | | | include dapeh:standard ; standard Daphne part | | | +-------------------------------------------------------+ | | | | $ ehsend read811 (download Event Handler program | | $ epload dapep:standard (download "standard" Event | | ( Processor program | | $ evs 0/fix=1 (fixed length event of 1 word | | $ h1 2048 /name=adc (1D histogram of 2048 chan named "ADC" | | $ m1 1 adc (parameter 1 to histogram "ADC" | | $ acq (start acquisition | | $ stp (stop acquisition | | $ d1h adc (display histogram "ADC" | | $ ext (exit from Daphne | | $ log (log out from VAX/VMS | +---------------------------------------------------------------------+ Experimenter's Guide To Daphne Page 6 On-Line HELP 3 October 1990 3 On-Line HELP All VMS and Daphne commands are described by on-line HELP files. To get information about a particular command, such as the Daphne command $SUM: $ HELP SUM To get a list of all topics covered in the Daphne HELP file: $ HELP @DAPHNE To get a printed copy of the output from HELP, use the "/OUTPUT" qualifier immediately after the word "HELP". If you put it elsewhere the $HELP utility will think it modifies the topic of the command, rather than the $HELP command itself. $ HELP/OUTPUT=SUM.HLP SUM !Save in file SUM.HLP $ HELP/OUTPUT=LPA0: SUM !Write to printer LPA0: $ HELP SUM/OUTPUT !About the /OUTPUT qualifier of SUM If you want a listing of the entire Daphne HELP file: $ HELP/OUTPUT=DAPHNE.HLP @DAPHNE *... !Everything Some aspects of Daphne are described in detail in separate documents. Section 4.1 lists these documents and how to obtain copies. Experimenter's Guide To Daphne Page 7 Related Documents and Articles 3 October 1990 4 Related Documents and Articles 4.1 Printing Daphne Documents Documentation is available in two formats: - QMS format These files have the extension ".QMS". They are formatted for printing on a QMS laser printer using a 10 pitch font without proportional spacing. In the Argonne Physics Department use the following commands: $ GPRLTR/NOFEED file-name.QMS (Node PHYA:: G-Wing laser printer) $ FPRLTR/NOFEED file-name.QMS (Node PHYA:: F-Wing laser printer) $ APRLTR/NOFEED file-name.QMS (Node ATLA:: laser printer) - Standard format These files have the extension ".MEM". They are formatted for printing on a conventional printer such as a Printronix 600. In the Argonne Physics Department use the following command: $ PRINT/NOFEED file-name.MEM (Node PHYA:: Printronix 600) 4.2 Daphne Documents - Experimenter's Guide to Daphne (this document) File name: DAPHLP:HANDBOOK.MEM or DAPHLP:HANDBOOK.QMS - Using Daphne for off-line analysis File name: DAPHLP:REPLAY.MEM or DAPHLP:REPLAY.QMS - Examples of Event Handler and Event Processor Programs File name: DAPHLP:ACQ_EXAMPLES.MEM or DAPHLP:ACQ_EXAMPLES.QMS - Daphne Tape Format File name: DAPHLP:TAPE_FORMAT.MEM or DAPHLP:TAPE_FORMAT.QMS - Event Handler A detailed description of the Event Handler has been written by D. C. Hensley, its designer. File name: DAPHLP:EH_HENSLEY.MEM or DAPHLP:EH_HENSLEY.QMS Experimenter's Guide To Daphne Page 8 Related Documents and Articles 3 October 1990 - Writing a UH (User Histogram) Routine The $UH program makes it relatively easy for users who know Fortran to write their own routines for manipulating histograms and the graphics device. For instance, the $D1H, $DO1H, $D2H, and $CUR commands are available as subroutine calls from within a user-histogram routine. File Name: DAPHLP:UH.MEM or DAPHLP:UH.QMS - Using two Event Handlers to control four Camac crates File Name: DAPHLP:TWO_EH.MEM or DAPHLP:TWO_EH.QMS - Spectrum Analysis Program (SAP) File name: DAPHLP:SAP.MEM or DAPHLP:SAP.QMS - Known Daphne Bugs File name: DAPHLP:DAPHNE_BUGS.MEM or DAPHLP:DAPHNE_BUGS.QMS 4.3 Daphne Articles D.C. Hensley, "The Event Handler II, a Fast, Programmable, CAMAC-Coupled Data Acquisition Interface" IEEE Trans. Nucl. Sci., vol. NS-26(4), 4454 (1979). R.T. Daly, T.H. Moog, and L.C. Welch, "DAPHNE...The Design of a Parallel Multiprocessor Data Acquisition System" IEEE Trans. Nucl. Sci., vol. NS-32(4), 1379 (1985). L.C. Welch, R.T. Daly, D. Loucks, T.H. Moog, and J. Stewart, "DAPHNE...A Parallel Multiprocessor Data Acquisition System-Software" IEEE Trans. Nucl. Sci., vol. NS-32(4), 1405 (1985). L.C. Welch, "DAPHNE...A Parallel Multiprocessor Data Acquisition System for Nuclear Physics" IEEE Trans. Nucl. Sci., vol. NS-32(1), 238 (1985). R.K. Crawford, et. al., "The Data Acquisition System for the Neutron Scattering Instruments at the Intense Pulsed Neutron Source" IEEE Trans. Nucl. Sci., vol. NS-28(5), 3692 (1981). L.C. Welch, T.H. Moog, R.T. Daly, and F. Videbaek, "The Design, Creation and Performance of the Parallel Multiprocessor Nuclear Physics Data Acquisition System, DAPHNE" IEEE Trans. Nucl. Sci., vol. NS-34(4), 823 (1987). Experimenter's Guide To Daphne Page 9 Daphne Objects 3 October 1990 5 Daphne Objects Every user is familiar with the idea of parameters and histograms for analyzing nuclear physics data. Daphne has other objects: maps, conditions, windows, linearizations, etc. Conditions are called "gates" when they are used to veto sorting into a histogram. 5.1 Naming Conventions Daphne objects can have names, which may be up to 12 characters long, and must contain at least one non-digit so that they will not be confused with numbers. The only exception are FIX and FLT variables which may be up to 12 characters long, but should conform to Fortran naming conventions. No distinction is made between uppercase and lowercase letters. Names may contain any printable special characters that will not interfere with the command language interpreter: Okay: _ . - # % Bad: / , & ' @ + : ( ) Each class of object in Daphne is named and numbered independently. For instance, there can exist simultaneously a 2D map, a 2D window, a condition, and a 2D histogram all with the name "NOT_ALPHAS". Object numbers in a class are assigned in ascending order by Daphne and are not under the control of the user. If an object is deleted it leaves a "hole" which will be filled by the next definition of an object of that class. The classes of objects in Daphne are: - 1D Maps - 2D Maps - 1D Histograms - 2D Histograms - 1D Windows - 2D Windows - Conditions - Linearizations - Scatterplots - FIX variables - FLT variables Experimenter's Guide To Daphne Page 10 Daphne Objects - Parameters 3 October 1990 5.2 Parameters Daphne has two kinds of parameters: "real" parameters and pseudo-parameters. Pseudo-parameters are parameters created by user-defined functions from real parameters, linearization values, and other pseudo-parameters. Daphne refers to parameters by number rather than name. Since users normally refer to maps (which can have names) rather than parameters, this is less of an inconvenience than it might first appear. All parameters are treated as unsigned 16 bit integers with values between 0 and 65,535. User-functions can treat parameters in any fashion they choose. 5.2.1 Real Parameters The real parameters of an event can be thought of as a vector where element 1 is real parameter 1, element 2 is real parameter 2, and so on. The number of real parameters in an event is limited by acquisition hardware to 1023. NOTE At the moment, the firmware in the Event Processor FIFO limits Daphne to a maximum of 127 words for variable length events and to 255 words for fixed length events (January '88). 5.2.2 Pseudo-parameters The pseudo-parameters constitute a second, independent vector. The pseudo-event vector, like the real event vector, starts with element 1. Daphne uses the qualifier "/PSEUDO" in map statements and scatterplot commands to indicate a reference to a pseudo-parameter. For instance, the following command would be used to sort real parameter 1 vs. pseudo-parameter 2 into a 2D histogram (X_VS_COR_Y): $ M2 1 2/PSEUDO X_VS_COR_Y There is no practical limit on the number of pseudo-parameters, however, each pseudo-parameter (which must be computed by the user-defined function during acquisition) requires some CPU time and, depending on the data rate and the percentage of data analyzed, might reduce the throughput of the acquisition system. Experimenter's Guide To Daphne Page 11 Daphne Objects - Maps 3 October 1990 5.3 Maps The first purpose of maps is to "connect" parameters, pseudo-parameters, or linearization values to histograms. For instance, to indicate that parameter 4 should be sorted into a one dimensional histogram "H", one would use the command: $ M1 4 H /NAME=A ^ ^ ^ | | | | | +---- Name to be assigned to map | | | +---- Name of 1D histogram to be incremented | Channel number is determined by | parameter number ------------+ | | +---- Parameter number ("4")------------+ The 1D Map has only one source while the 2D Map has two sources: one for the X component and one for the Y component. A source can be any of the following: Source Example of Use in Map ------------------ --------------------- real parameter $M1 1 HIST1 pseudo-parameter $M1 1/PSEUDO HIST1 1D map value $M1 1/MAP HIST1 linearized value $M1 1/LNZ HIST1 (Linearizations are discussed in section 5.8) The type of source (real parameter, pseudo-parameter, map, or linearization) is sometimes called the map "flavor". Examples of 2D Maps: $M2 1 2/PSEUDO HIST2 (real parameter #1 vs. pseudo parameter #2) $M2 1/PSEUDO 2/PSEUDO HIST2 (pseudo parameter #1 vs. pseudo parameter #2) $M2 ADC1/MAP 1/LNZ HIST2 (1D Map "ADC1" vs. linearization #1) Experimenter's Guide To Daphne Page 12 Daphne Objects - Maps 3 October 1990 5.3.1 Source of Linearizations The source of a linearization is always a 2D Map. The result of a linearization is parameter-like and can be used as a source of both 1D and 2D Maps. 5.3.2 Circular Definitions The possibility of a 1D Maps using as input another 1D Map or linearization raises the possibility of circular definitions. For instance, 1D map #1 might use linearization #1 as input. Linearization #1 might require 2D map #1 as input, and 2D map #1 might require 1D map #1 as input. Such circular references should be detected by Daphne at the time sorting is started. 5.3.3 Map Offsets and Gains The second purpose of the map statement is to define an "offset" and "gain" (sometimes called "compression") for a parameter before it is sorted into a histogram. Together, an offset and gain provide for simple linear scaling of parameters before any sorting according to the following formula: parameter_value - offset map_value = ------------------------ gain For instance, a parameter with a range of 0 to 8,191 could be sorted into a 1,023 channel histogram named "H" (with a 3 bit loss of resolution) using the following Daphne command: $ M1 1 H /GAIN=8 /NAME=TOF Gains must be positive, but can have any value between 1 and 65,535. The "offset" of a map is subtracted from the parameter, prior to division by the gain, before the parameter is sorted into a histogram. Offsets can be positive or negative with any value between -65,535 and +65,535. If the result of subtracting the offset yields a negative number the result is set to zero. If the result of subtracting a negative offset yields a value greater than 65,535 the result is set to 65,535. Experimenter's Guide To Daphne Page 13 Daphne Objects - Maps 3 October 1990 5.3.4 Two-Dimensional Maps There are one dimensional maps for use with one dimensional histograms and two dimensional maps for use with two dimensional histograms and linearizations. The two dimensional maps have both an "xgain" and "ygain" and an "xoffset" and "yoffset". The xgain and ygain are usually used to "compress" parameters so as to fit what would have been a very large two dimensional histogram into a reasonable amount of memory. For instance, a histogram of parameter 3 versus parameter 5, each with a range 0 to 2047, would normally require at least 8 megabytes for counts up to 32,767 per bin. If the two dimensional map specifies /XGAIN=4 and /YGAIN=8 then the histogram need be only 512 channels in the x direction and 256 channels in the y direction. The command would be: $ M2 3 5 P1_VS_P2 /NAME=A_VS_B /XGAIN=4 /YGAIN=8 ^ ^ -------- ------ | | ^ ^ | | | | | | | +-- Name to be assigned to map | | | | | +-- Name of 2D histogram | | | +-- Y parameter | +-- X parameter Experimenter's Guide To Daphne Page 14 Daphne Objects - Names 3 October 1990 5.3.5 Maps Can Refer to More Than One Histogram Maps can connect a single parameter (or a pair of parameters in the case of a two dimensional map) with more than one histogram. Suppose one wanted two histograms of parameter 8: one histogram containing all events and the other gated by some condition. The SECOND step, after defining the histograms would probably be to define the map: $ M1 8 ALL,NO_ALPHAS /NAME=A ^ --- --------- ^ | ^ ^ | | | | +-- Name to be assiged to map | | | | | +-- second histogram referenced by map | | | +-- first histogram referenced by map | +-- parameter number The additional steps, which will be covered later, are to define the window, define a condition using the window, and to use the condition as a gate on the "NO_ALPHAS" histogram. 5.3.6 Maps Without Histograms One can define a map which references no histogram. This might occur, for instance, with a pattern register where each bit represents status information. Many of the bits in the pattern register might be used to control the sorting process, but it would, in general, be meaningless to histogram the pattern register: it would be difficult to interpret a count in channel 99 (1100011 binary) as representing hits in detectors 7, 6, 2, and 1. (However, it is common to build a "bit histogram" in which channel "i" is incremented if bit "i" of the pattern register is set). Even though a pattern register would not be sorted into any histogram it would, nonetheless, be used in a map command, since otherwise it could not be tested by a condition. If it isn't tested in a condition, it cannot be used to gate a histogram. Experimenter's Guide To Daphne Page 15 Daphne Objects - Diagrams 3 October 1990 5.4 Relationships Between Daphne Objects In the diagrams which follow I have tried to show the relationship among Daphne Objects. Each diagram is accompanied by a fragment of Daphne commands which would create the relationship depicted. There is no particular importance attached to the choice of names or parameter numbers. Parameter Map Window Condition Histogram --------- --- ------ --------- --------- $ M1 1 H /NAME=H Parameter -------> 1D-Map ------------------------------> 1D-Histogram #1 M H $ M1 2 HA,HB /NAME=M Parameter -------> 1D-Map ------------------------------> 1D-Histogram #2 M \ HA \ +---------------------------> 1D-Histogram HB Parameter -------> 1D-Map #3 MA \ $ M1 3 H /NAME=MA \ $ M1 4 H /NAME=MB >---------------------------> 1D-Histogram / H / Parameter -------> 1D-Map #4 MB $ M1 5 HA,HB /NAME=MA $ M1 6 HB,HC /NAME=MB Parameter -------> 1D-Map ------------------------------> 1D-Histogram #5 MA \ HA \ >---------------------------> 1D-Histogram / HB / Parameter -------> 1D-Map ------------------------------> 1D-Histogram #6 MB HC $ M1 7 HA,HB /NAME=MA $ M1 8 HB,HC /NAME=MB $ M1 8 HD /NAME=MC Parameter -------> 1D-Map ------------------------------> 1D-Histogram #7 MA \ HA \ >---------------------------> 1D-Histogram / HB / Parameter -------> 1D-Map ------------------------------> 1D-Histogram #8 \ MB HC \ +----> 1D-Map ------------------------------> 1D-Histogram MC HD Experimenter's Guide To Daphne Page 16 Daphne Objects - Diagrams 3 October 1990 Parameter Map Window Condition Histogram --------- --- ------ --------- --------- X-Parameter #9 \ $ M2 9 10 H /NAME=M \ --> 2D-Map ------------------------------> 2D-Histogram / M H / Y-Parameter #10 X-Parameter #11 \ \ $M2 11 12 HA,HB /NAME=M --> 2D-Map ------------------------------> 2D-Histogram / M \ HA / \ Y-Parameter \ #12 \ +-------------------------> 2D-Histogram HB X-Parameter #13 \ \ --> 2D-Map / MA \ / \ $ M2 13 14 H /NAME=MA Y-Parameter \ $ M2 15 16 H /NAME=MB #14 \ >--------------------------> 2D-Histogram / H X-Parameter / #15 \ / \ / --> 2D-Map / MB / Y-Parameter #16 Experimenter's Guide To Daphne Page 17 Daphne Objects - Diagrams 3 October 1990 X-Parameter $ M2 17 18 HA,HB /NAME=MA #17 \ $ M2 19 20 HB,HC /NAME=MB \ --> 2D-Map ------------------------------> 2D-Histogram / MA \ HA / \ Y-Parameter \ #18 \ >--------------------------> 2D-Histogram / HB X-Parameter / #19 \ / \ / --> 2D-Map ------------------------------> 2D-Histogram / MB HC / Y-Parameter #20 Parameter #21 \ \ X-Axis $ M2 21 22 HA,HB /NAME=MA \ $ M2 22 23 HC,HD /NAME=MA \ --> 2D-Map ------------------------------> 2D-Histogram / MA \ HA / \ Y-Axis +---------------------------> 2D-Histogram / HB / Parameter #22 \ \ X-Axis \ \ --> 2D-Map ------------------------------> 2D-Histogram / MB \ HC / \ Y-Axis +---------------------------> 2D-Histogram / HD / Parameter #23 Experimenter's Guide To Daphne Page 18 Daphne Objects - Diagrams 3 October 1990 Parameter Map Window Condition Histogram --------- --- ------ --------- --------- $ M1 1 /NAME=M $ CON condition-file C: BITON M 0 Parameter -----> 1D-Map ----------------> Condition #1 M C $ M1 1 H /NAME=M $ CON condition-file C: BITON M 0 +------------------------------ Histogram / H / Parameter -----> 1D-Map ----------------> Condition #2 M C $ M1 1 H /NAME=M $ W1/NAME=WA /MAP=M /LOW=111 /HIGH=222 $ W1/NAME=WB /MAP=M /LOW=333 /HIGH=444 $ CON condition-file CA: ANYON M 1111111111111111 CB: ALLON M 1111111111111111 CC: IN1 WA CD: OUT1 WB +-----------------------------> Histogram / H / Parameter -----> 1D-Map ----------------> Condition #3 M | CA | BITON BITOFF | ALLON ALLOFF ANYON ANYOFF | +---------------> Condition | CB | BITON BITOFF | ALLON ALLOFF ANYON ANYOFF | +-> 1D-Window --> Condition | NA CC | IN1 (Inside 1D Window) | OUT1 (Outside 1D Window) | +-> 1D-Window --> Condition WB CD IN1 (Inside 1D Window) OUT1 (Outside 1D Window) Experimenter's Guide To Daphne Page 19 Daphne Objects - Diagrams 3 October 1990 $ W1 /NAME=W /MAP=MA /LOW=111 /HIGH=222 $ W1 /NAME=W /MAP=MB /LOW=333 /HIGH=444 Not Possible: A window can only be used with a single map . . . . . . .1D Map MA ----------------> Condition Name 1D Window W IN1 A W (A Inside W) ^ OUT1 A W (A Outside W) | | - - - - - | W R O N G | - - - - - v 1D Window W . . . . . . 1D Map MB ----------------> Condition Name IN1 B W (B Inside W) OUT1 B W (B Outside W) $ W2 /NAME=W /MAP=MA ... $ W2 /NAME=W /MAP=MB ... Not Possible: A window can only be used with a single map . . . . . . .2D Map MA ----------------> Condition Name 2D Window W IN2 A W (A Inside W) ^ OUT2 A W (A Outside W) | | - - - - - | W R O N G | - - - - - v 2D Window W . . . . . . 2D Map MB ----------------> Condition Name IN2 B W (B Inside W) OUT2 B W (B Outside W) $ M2 4 5 H /NAME=M $ W2 /NAME=WA /MAP=M ... $ W2 /NAME=WB /MAP=M ... $ CON conditions-file CA: IN2 WA CB: IN2 WB +----------------------------> Histogram X Parameter / H #4 \ / \ / - 2D-Map +-> 2D-Window --> Condition / M | WA CA / | IN2 (Inside 2D Window) Y Parameter | OUT2 (Outside 2D Window) #5 | +-> 2D-Window --> Condition WB CB IN2 (Inside 2D Window) OUT2 (Outside 2D Window) Experimenter's Guide To Daphne Page 20 Daphne Objects - Diagrams 3 October 1990 Parameter Map Window Condition Histogram --------- --- ------ --------- --------- For 1D histograms use $G1H for gating 1D maps into 1D histograms For 2D histograms use $G2H for gating 2D maps into 2D histograms . . . . . . . . . . . . . . . . . . . . . . Cond C | | $ G1H /COND=C H Gate | . . . . . . . . . Map --------------------- | --------> Histogram M H . . . . . . . . . . . . . . . . . . . . . . . . Cond CA| . . . . . . . . . . . . . . . . . . . . . . Cond | CB| | | | $ G1H /COND=(CA,CB) HA,HB | Gate | | Gate | | | . . . . . . . . . Map --------------------- | - | ---> Histogram MA | | HA | | . . . . . . . . . Map --------------------- | - | ---> Histogram MB \ HB \ +----------------------------> Histogram HC . . . . . . . . . . . . . . . . . . . . . . . . Cond CA| . . . . . . . . . . . . . . . . . . . . . . Cond | CB| | | | $ G1H /COND=(CA,CB) H | Gate | | Gate | | | . . . . . . . . . Map \ | | MA \ | | \ | | . . . . . . . . . Map ---+----------------- | - | ---> Histogram MB / H / . . . . . . . . . Map / MC Experimenter's Guide To Daphne Page 21 Daphne Objects - Diagrams 3 October 1990 . . . . . . . . . . . . . . . . . . . . . . . . Cond CA| . . . . . . . . . . . . . . . . . . . . . . Cond | CB| | | | $ G1H /COND=(CA,CB) HA | Gate $ G1H /COND=(CB) HB | | Gate | | | . . . . . . . . . Map --------------------- | - | ---> Histogram MA | HA | . . . . . . . . . Map --------------------- | -------> Histogram MB \ HB \ +----------------------------> Histogram HC . . . . . . . . . . . . . . . . . . . . . . Cond CA| $ G1H /COND=CA H | | Not Possible: Can't veto one map and | allow another map to INC histogram | | Gate | . . . . . . . . . Map --------------------- | -------> Histogram MA / H - - - - - / . . . . . . . . . Map ------- W R O N G -------+ MB - - - - - Experimenter's Guide To Daphne Page 22 Daphne Objects - Histograms 3 October 1990 5.5 Histograms Daphne histograms are characterized by the number of counts they can hold in one bin or cell and the number of channels. 5.5.1 Number of Counts Per Bin The number of counts that can be held in a bin is specified by the /BYTES qualifier. /BYTES=1 (8 bits) maximum value in bin: 127 /BYTES=2 (16 bits) maximum value in bin: 32,767 /BYTES=4 (32 bits) maximum value in bin: 2,147,483,647 For one dimensional histograms the default is "/BYTES=4", while for two dimensional histograms the default is "/BYTES=2". NOTE When the number of counts in a bin exceeds the maximum value stated above, overflow from the maximum positive number to the most negative number occurs. Depending on the program, this error may or may not be reported to the user. For instance, the projection commands will report overflows. However, the acquisition program does not at present detect the problem and cannot report it. 5.5.2 Number of Channels The number of channels in a one dimensional histogram can range from 1 to 65,535. Channels are numbered starting at zero. The following command: $ H1 8192 /NAME=GE declares a one dimensional histogram with channels numbered from 0 to 8,191. By default it would have 32 bit bins. For two dimensional histograms, the same range of channels is allowed for each axis (0 to 32,767), although machine limitations and operating system quotas may limit the size of any single histogram or the size of all histograms taken together. Experimenter's Guide To Daphne Page 23 Daphne Objects - Histograms 3 October 1990 As an extreme example, it would be possible to have a 16 by 32,767 channel histogram. A more typical example is a histogram 512 by 512 channels. $ H2 16 32767 /NAME=TALL&THIN/BYTES=4 $ H2 512 /NAME=GAMMA.GAMMA The first command creates a two dimensional histogram 16 channels in the X direction and 32,767 channels in the Y direction requiring about 2 megabytes. The second command declares a square histogram (512 channels in each direction) requiring about 512 kBytes. Note that names in Daphne may contain non-alphanumeric characters. 5.5.3 Options for Zeros and Overflow Channels What happens when the channel to be incremented in a histogram is greater than the number of channels in the histogram ? In Daphne the normal practice is to count them in the last channel of the histogram, sometimes termed the overflow channel. Using the /NOOVERFLOW qualifier (and its two dimensional equivalents) one can turn off this feature. Similarly, the /NOZERO qualifier suppresses histogramming of data into channel zero. There are three main reasons for using these switches: - Simplify Reading of Displays When counts in the first and last channel have no experimental importance they may still make it difficult to determine the fraction of "interesting" events since counts in the first and last channel of histogram will be included in the total number of counts in the histogram. By using /NOZERO or /NOOVERFLOW only the "interesting" events appear in the histogram. - Reducing Bandwidth Requirements Every histogram bin which needs to be incremented requires 6 bytes of data to be transferred from an Event Processor to the VAX. The Multibus to Unibus bandwidth is about 450 kBytes/sec: for some experiments this can be a limiting factor in event rates. If (a) I/O bandwidth is a limiting factor and (b) values that fall in channel zero or the overflow channel represent a significant fraction of the data and (c) such data is not experimentally significant THEN using the /NOZERO and /NOOVERFLOW switches can increase the rate at which events can be processed without loss of information. This raises the question of how to tell when an experiment is I/O limited. This is discussed in the section on improving throughput (Section 35). Experimenter's Guide To Daphne Page 24 Daphne Objects - Histograms 3 October 1990 - Map Gating Daphne allows one or more maps to be sorted into a histogram. The histogram can be gated by a number of conditions. If any condition is false, then all sorting into the histogram is suppressed. As an example, suppose there are two detectors, A and B, which are to be sorted into the same histogram. Detector A should be sorted into the histogram only if its value is between 500 and 600; detector B should be sorted into the histogram only if its value is between 550 and 650. This cannot be handled without the use of a user-defined function in Daphne, because, to veto A would mean to veto B also, and vice versa, since the gate is on the histogram, not on a specific map/histogram combination. The normal solution to this problem is a user-defined function which replaces any values which should be vetoed with zero and then to use the /NOZERO qualifier in defining the histogram. The default is to histogram all data, namely, "/ZERO" and "/OVERFLOW". The following table shows all versions of this qualifier. The program that creates 2D histograms processes the more general qualifiers first. Thus /NOZERO and /XZERO together would be equivalent to /NOYZERO and /XZERO together. One Dimensional Two Dimensional ---------------------- --------------------------- /ZERO /NOZERO /ZERO /NOZERO /OVERFLOW /NOOVERFLOW /OVERFLOW /NOOVERFLOW /XZERO /NOXZERO /XOVERFLOW /NOXOVERFLOW /YZERO /NOYZERO /YOVERFLOW /NOYOVERFLOW 5.5.4 Axis Labels One can give an axis a label of up to 12 characters which will appear on displays and hardcopy plots. For 1D histograms one can only code "/XAXIS", while for 2D histograms one can code both "/XAXIS" and "/YAXIS" $ H2 512 512 /NOZERO /XOVERFLOW /NOYOVERFLOW - /XAXIS="TOF Det 1" - /YAXIS="Delta E" Actually, the above example can be simplified a little bit. If the number of Y channels is omitted it is assumed that the number of Y channels is the same as the number of X channels: $ H2 512 ! a "square" histogram 512 by 512 channels Experimenter's Guide To Daphne Page 25 Daphne Objects - 1D Windows 3 October 1990 5.6 One-Dimensional Windows One dimensional windows allow a user to select events based on whether a parameter has values that fall inside (or outside) a certain range. Values that fall on the edges of the window are considered to be inside the window. Thus a window from 577 to 617 includes 577, 617, and all values between. Each window is associated with a map which gives the parameter which is to be tested. It is not possible to define a window without reference to a map. In cases where the window is defined using a displayed histogram, the /MAP qualifier is optional as the $W1 program is able to work backwards from the histogram that is currently displayed to the map which created it. If there are (a) two or more maps which reference the displayed histogram and (b) you wish the window to be evaluated using anything other than the lowest numbered map, then you should use the /MAP qualifier of the $W1 command. 5.6.1 Definition Using Graphic Input The command below allows the user to define the window using the graphics cursor of the terminal (assuming that a one dimensional histogram has been displayed). It waits for the user to position the cursor twice in order to define the upper and lower bounds of the window. This is the default mode of operation. $ W1/NAME=PEAK2 or $ W1/NAME=PEAK/MAP=DETECTOR_1 5.6.2 Definition Using Keyboard or Command File One can also define a 1D window without using a graphics terminal. In the example below, the qualifier "/KEY" is meant to suggest that data will be entered from the keyboard: $ W1/KEY Name of Window being created? PEAK Number or name of MAP upon which the window is to be placed? DETECTOR_1 What is the lower value on the window? 577 What is the upper value on the window? 617 or $ W1/NAME=PEAK/MAP=DETECTOR_1 /LO=577 /HI=617 Experimenter's Guide To Daphne Page 26 Daphne Objects - 2D Windows 3 October 1990 5.7 Two-Dimensional Windows Two dimensional windows allow a user to select events based on whether a combination of two parameters falls inside (or outside) a region in the X-Y plane. The region is represented as a series of X-Y coordinates which are the vertices of a polygon. Points on the edge of the polygon are considered to be inside the region. The number of points used in defining the vertices of the polygon has been arbitrarily limited to 100 points. Each window is associated with a map which gives the parameter which is to be tested. It is not possible to define a window without reference to a map. In cases where the window is defined using a displayed histogram, the /MAP qualifier is optional as the $W2 program is able to work backwards from the histogram that is currently displayed to the map which created it. If there are (a) two or more maps which reference the displayed histogram and (b) you wish the window to be evaluated using anything other than the lowest numbered map, then you should use the /MAP qualifier of the $W2 command. 5.7.1 Restriction on Shape Because of the way 2D windows are implemented, the shape of a 2D window is not arbitrary: a vertical line of constant X may not cross the window boundary more than twice. For example, the figure on the left is legal, while the figure on the right is illegal. Okay Not Okay xxxxx xxxxx xxxxxxxxxx x x x x x x x x x x x x x x x x x x x x x x x xxxxxxxxxxxxx xxxxxxxxxx Another way of expressing this restriction is to say that for a given value of X it must be possible to tell whether a given point is inside or outside the window by simply comparing an "upper" value of Y and a "lower" value of Y which has been tabulated for every value of X. When 2D windows do not meet the above requirements there are two ways around the problem. - The X and Y axes can be interchanged, thereby rotating the window by 90 degrees. This can fix cases such as the one above. Experimenter's Guide To Daphne Page 27 Daphne Objects - 2D Windows 3 October 1990 - The region can be defined using two or more smaller windows, each of which conforms to the requirements. The user must then modify condition definitions to test whether a point is inside any of the smaller regions. 5.7.2 Definition Using Graphic Input One can define a 2D window using a cross-hair, mouse, or other pointing device with a graphics terminal to indicate the coordinates of the window vertices. The points can be entered starting at any point and proceeding either clockwise or counter-clockwise to the last point. When the command is terminated, the last point is automatically connected to the first point to create a closed figure. This is the default mode of operation. $ W2 /NAME=PEAK /OUTPUT=CREATE_PEAK or $ W2 /NAME=PEAK /MAP=DETECTOR_1 /OUTPUT=CREATE_PEAK When using a graphics input device to draw a window on a histogram it is not necessary to use the /MAP qualifier, except when there are more than two maps that go to the same histogram, and you wish the window to be drawn on a map other than the lowest numbered one. The /OUTPUT qualifier allows one to save the definition of the window in the form of a command file. This makes it much easier to redefine the window at a later time, should it be necessary. 5.7.3 Definition Using Keyboard or Command File One can also define a 2D window without using a graphics terminal. In the example below, the qualifier "/KEY" is meant to suggest that data will be entered from the keyboard. $ W2 /NAME=PEAK /MAP=DETECTOR_1 /KEY /OUPUT=CREATE_PEAK Experimenter's Guide To Daphne Page 28 Daphne Objects - Linearizations 3 October 1990 5.8 Linearizations Linearizations allow users to "straighten" lines that appear in 2D histograms. Consider the following hypothetical mass/energy histogram where the letters "A" through "F" represent prominent lines for nucleii of six different masses: | 60 | FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF | FFF 50 | FF EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE |FF EEEEEE DDDDDDDDDDDDDDDDDDDDDDDD 40 |F EEE DDDDDDDDD Mass | EE DDDDDDDDDD * <---------------- Point "P" 30 |E DDDDDDD CCCCCCCCCCCCCCCCCCCC |DDD CCCCCCCCCCCCCCCCCCCCC 20 |CCCCCC BBBBBBBBBBBBBBBBBBBBBBBBBBBBBB |BBBBBBBBBBB 10 |AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA +---------------------------------------- Energy If the user wanted to be able to make projections in order to compare the frequency of each mass or set windows based on the mass of the particle it would be much easier if the the mass lines could be made straight: | 60 |FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF | 50 |EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE Linearized |DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD Mass 40 | | * <--------------- Linearized 30 |CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC Point "P" | 20 |BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB | 10 |AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA +---------------------------------------- Energy Linearizations are described by a series of "linearization lines" with each linearization line having an assigned "linearization value". This is similar to the countour lines of a geographical map in which each contour line will be assigned a characteristic elevation. In Daphne each linearization can be defined with as many as 20 linearization lines. Points which fall on a linearization line will be assigned the linearized value of that line. Points which fall between two linearization lines will be assigned a value computed by interpolation from the linearization values of the surrounding lines. Experimenter's Guide To Daphne Page 29 Daphne Objects - Linearizations 3 October 1990 As an example, suppose the user has drawn six linearization lines coinciding with the prominent lines for each mass, and assigned linearization values equal to the mass values (10, 20, 30, 45, 50, and 60). A point "P" in the first figure above with coordinate (Px,Py) sandwiched between lines "C" and "D" would have a linearized value computed in the following way (where Cy and Dy are the y coordinates of lines C and D at X=Px): Py - Cy linearized Py = -------- * (D value - C value) + C value Dy - Cy However: If linearized Py negative: Use 0 If linearized Py greater than 65,535: Use 65,535 5.8.1 Extreme Cases Points which fall below the bottom linearization line, or above the top linearization line, are computed using the nearest two lines. It is assumed that points which fall to the right of the area in which the linearization is defined are not really of interest and they receive the maximum linearization value (65,535) so that they will be well separated from points which fall in the area in which the linearization is defined. 5.8.2 Horizontal and Vertical Linearizations The example above is a horizontal linearization. A vertical linearization, created by using the /VERTICAL qualifier of the $LNZ command, computes linearized X coordiates so that plotting Py against linearized Px would yield vertical lines. 5.8.3 Maps and Linearizations Each linearization is associated with a 2D map which gives the parameters which are to be used in the linearization. It is not possible to define a linearization without reference to a map. In cases where the linearization is defined using a displayed histogram, the /MAP qualifier is optional as the $LNZ program is able to work backwards from the histogram that is currently displayed to the map which created it. If there are (a) two or more maps which reference the displayed histogram and (b) you wish the linearization to be evaluated using anything other than the lowest numbered map, then you should use the /MAP qualifier of the $LNZ command. Experimenter's Guide To Daphne Page 30 Daphne Objects - Linearizations 3 October 1990 5.8.4 Linearization of a Linearization Because linearizations are based on 2D maps, which can themselves be defined in terms of linearizations, it is possible to "correct" a not quite straight linearization line by applying a second linearization. This fragment of Daphne commands demonstrates how this might be done: - Define the map and histogram which will be used to draw the first linearization $ H2 512 /NAME=FIRST_H2 $ M2 1 2 FIRST_H2 /NAME=FIRST_MAP - Display the histogram and draw the linearization using FIRST_H2 $ D2H FIRST_H2 $ LNZ /NAME=FIRST_LNZ - Define a new histogram for the linearized parameters Define a map so data will be sorted into the new histogram This will allow us to see how straight the line is $ H2 512 /NAME=FIRST_LNZ_H2 $ M2 1 FIRST_LNZ/LNZ FIRST_LNZ_H2 /NAME=SECOND_MAP - Inspection of FIRST_LNZ_H2 will show whether the linearization has yielded sufficiently straight lines Assume that the lines are not straight enough Define a new linearization on the map "SECOND_MAP" $ D2H FIRST_LNZ_H2 $ LNZ /NAME=SECOND_LNZ - Create a third histogram and its map which will allow us to check the results of the second linearization $ H2 512 /NAME=THIRD_H2 $ M2 1 SECOND_LNZ/LNZ THIRD_LNZ /NAME=FINAL_MAP Experimenter's Guide To Daphne Page 31 Daphne Objects - Linearizations 3 October 1990 5.8.5 Defining a Linearization with Graphics Input One can define a linearization using a cross-hairs, mouse, or other pointing device with a graphics terminal to indicate the points in each linearization line. All the points of a linearization line must be entered before starting to define the next linearization line. The points of a horizontal (vertical) linearizations line must be entered from left to right (bottom to top) starting with the points with the smallest X (Y) values. Although the points of a linearization line must be entered in a particular order, the lines can be defined in any order. For instance, after defining two lines one could define a third line between lines 1 and 2. When defining the linearization by graphics input, the program will guide the user through each step in creating the linearization. One can use the "zoom-in" (key "I") or zoom-out (key "O") to see more or less detail in the histogram when placing the points of the linearization lines. When all the points of a linearization line are entered the points are connected with a curve computed by spline fit. $ LNZ /NAME=LNZ_MASS /OUTPUT=LNZ_MASS or $ LNZ /NAME=LNZ_MASS /MAP=MASS_ENERGY /OUTPUT=LNZ_MASS The /OUTPUT qualifier allows one to save the definition of the linearization in the form of a command file. This makes it much easier to redefine the linearization at a later time, should it be necessary. It is strongly recommended. 5.8.6 Defining a Linearization from Keyboard or Command File One can also define a linearization without use of the graphics terminal. In the example below, the qualifier "/KEY" is meant to suggest that data will be entered from the keyboard. As before, the program will guide the user through each step. $ LNZ /KEY /NAME=LNZ_MASS /OUTPUT=LNZ_MASS Experimenter's Guide To Daphne Page 32 Daphne Objects - Conditions 3 October 1990 5.9 Conditions (Gates) Conditions are the means Daphne provides to veto sorting into histograms. Conditions always evaluate to a value of "true" or "false". A second purpose of conditions is to act as "software scalers" and to count the number of times a user-defined condition is true. Conditions are defined in Daphne by using the $CON command. Unlike most other Daphne commands, the $CON command gets its instructions from a file rather than the command line. The command line gives the name of a file (or files) containing the definitions rather the the condition definitions themselves. The condition definition file is a text file which can be created with any standard text editor. The default file type for the condition definition file is ".CON". For example, a conditions file ICE.CON could be used to define conditions with the following command: $ CON ICE 5.9.1 Combining Condition Definition Files Conditions can be defined in several files and then combined on the command line: $ CON ICE_PART1+ICE_PART2+ICE_PART3 This format is particularly useful in an experiment in which some of the conditions depend on information which must be acquired during the run. Conditions based on 2D windows and linearizations often fall into this category. 5.9.2 Conditions for Multiple Event Types Using a plus sign ("+") to combine condition file names is completely different then using a comma (","). A comma is used to separate condition files for different event types: $ CON ICE_TYPE0,ICE_TYPE1,ICE_TYPE2 This defines conditions for three different event types. The concept of event types is described in detail in section 6.13.2. Experimenter's Guide To Daphne Page 33 Daphne Objects - Conditions 3 October 1990 5.9.3 Deleting Conditions To delete or change a condition the condition file must be edited and the $CON command reissued. To delete all conditions use as input the null file: $ CON NL: 5.9.4 Syntax A condition definition begins with an optional name followed by a condition type and any arguments. FIRED: BITON PAT 0 !True when low order bit PAT set to 1 ^ ^ ^ ^ ^ ^ | | | | | | | | | | +--- Comment (introduced by "!") ---+ | | | | | | | +--- Argument 2 | | +--- Argument 1 | +--- Condition Type +--- Condition Name - Names Like other Daphne objects, conditions can have names of up to 12 characters. Condition names are declared by putting the symbol in column 1 and following it immediately with a colon (":"). If there is no name then column 1 must be blank. - Comments Comments begin with the exclamation mark ("!") and continue to the end of the line. A line may consist of just a comment. - Punctuation For condition types which have more than one argument, the arguments can be separated by one or more spaces. The TAB character is equivalent to a space. - Continuation Lines There is no way to continue a statement to another line. - Upper and Lower Case No distinction is made between uppercase and lowercase characters. Experimenter's Guide To Daphne Page 34 Daphne Objects - Conditions 3 October 1990 5.9.5 Condition Types The following section lists all the condition types. Examples are given using the format accepted by the $CON command. - TRUE - FALSE These allow a user to define conditions which are always true or always false. - IN1 1D-window-name - OUT1 1D-window-name IN1 is true when the value of the map falls within the specified 1D window. The window is inclusive. Thus the values 10 and 20 are considered to be inside a window extending from 10 to 20. OUT1 is the complement of IN1. - IN2 2D-window-name - OUT2 2D-window-name IN2 is true when the value of the map falls within the specified 2D window. The window is inclusive: a point falling on the edge is considered to be inside the window. OUT2 is the complement of IN2. - BITON map-name bit-number - BITOFF map-name bit-number BITON is true if the specified bit is 1 and false otherwise. Bits are numbered starting from 0. Bit 0 is the least significant bit of the word and bit 15 is the most significant bit. BITOFF is the complement of BITON. A typical application of BITON is to test a pattern register recording which detectors have fired: DET1: BITON PAT 0 DET2: BITON PAT 1 DET3: BITON PAT 2 DET4: BITON PAT 3 Experimenter's Guide To Daphne Page 35 Daphne Objects - Conditions 3 October 1990 - ANYON map-name mask - ANYOFF map-name mask - ALLON map-name mask - ALLOFF map-name mask The above four condition types allow a user to test a number of bits in a map value with a single condition. The mask is a string of 16 characters representing 16 bits. Zeroes or ones are coded in bit positions of interest and an asterisk is coded for "don't care bits". Note that no distinction is made between a "0" and a "1" in the mask string. A: ALLOFF PAT1 ********00000000 !True if lower 8 bits all zero B: ALLOFF PAT2 ********11111111 !Same as above C: ALLON PAT3 1*******1*****11 !True only if bits 15,7,1,0 all set D: ANYON PAT4 0000000000000000 !True if PAT4 non-zero (any bit set) - NOTAPE condition-name When true, this condition sets a flag which prevents the event from being added to the tape buffer and eventually recorded. There can be any number of NOTAPE conditions, but if even one evaluates to true, the event will not be recorded. There is no way to "undo" the NOTAPE flag once it is set for a given event: the internal flag which is set by the NOTAPE condition is cleared only at the start of processing of each event. Considered as a software scaler, the NOTAPE condition has the same truth value as its input condition. When event mode recording is not enabled, the NOTAPE condition is still allowed, but has no effect other than to count the number of times its input condition is true. The NOTAPE condition is independent of the KILL condition. For instance, an event may be analyzed but not recorded, or recorded but not analyzed. - KILL condition-name When true, this condition causes any remaining analysis of this event to be skipped: no additional conditions are evaluated and NO sorting of data into histograms will take place. When false, execution proceeds normally. The KILL condition is independent of the NOTAPE condition. For instance, an event may be analyzed but not recorded, or recorded but not analyzed. Considered as a software scaler, the KILL condition has the same truth value as its input condition. Experimenter's Guide To Daphne Page 36 Daphne Objects - Conditions 3 October 1990 - ONEOFN condition-name number This condition acts like a pre-scaler. It is true only 1 out of "N" times the condition referenced in the first argument is true. A typical use is to bypass analysis of a known fraction of events while taping 100% of the data. COUNTER: TRUE ! Count the number of events PRESCALE: ONEOFN COUNTER 5 ! Will be true only 20% of the time OTHERS: NOT PRESCALE ! Will be true 80% of the time NO_EXAMINE: KILL OTHERS ! Don't analyze 4 out of 5 events ! All will still be taped OKAY: TRUE ! Count how many have gotten ! by the KILL command - NOT condition-name The result is the complement of the referenced condition: if the input condition is "true" the result is "false" and vice-versa. - AND cond-1 cond-2 cond-3 cond-4 cond-5 - OR cond-1 cond-2 cond-3 cond-4 cond-5 These are the only conditions that accept a variable number of arguments: from one to five conditions can be referenced. The "OR" condition is true if any of the referenced conditions are true. The "AND" condition is true only if all of the referenced conditions are true. More than five conditions can be combined by using cascaded AND and OR conditions. The following example shows how to compute the AND of 10 conditions: FIRST5: AND A B C D E SECOND5: AND F G H I J GRAND_AND: AND FIRST5 SECOND5 - USER entry-point-number This condition calls the specified user-defined function. The function can return a logical value which becomes the value of the condition. OKAY: USER 5 BAD: NOT OKAY KILL BAD These conditions cause a call to the function with the name "USER5". If the function returns the value "false", processing of this event will be aborted. If it returns the value "true", processing will continue. Experimenter's Guide To Daphne Page 37 Daphne Objects - Conditions 3 October 1990 - FORCELNZ - FORCELNZ linearization-number This condition forces the evaluation of all linearizations (the first case) or a specific linearization (the second case). It is used in conjunction with the USER-n user-defined functions to guarantee evaluation of a linearization prior to entering a user-function which requires a linearized value in order to compute a pseudo-parameter. FORCELNZ 2 USER 1 A FORCELNZ condition is always false. It computes no value: it might be described as pseudo-condtion. Experimenter's Guide To Daphne Page 38 Daphne Objects - Gates 3 October 1990 5.10 Gates Conditions are called "gates" when they must be satisfied in order to sort data into a histogram. A histogram can have from zero to 16 gates, and each one must be satisfied ("true") before a map can be sorted into the histogram. The choice of 16 gates is not a serious limitation because a condition can be defined so that it is "true" only when, for example, five other conditions are true. Gates are defined using the $G1H command for one-dimensional histograms and the $G2H command for two dimensional histograms. By default, the $G1H and $G2H command replaces all the gates with the new gates. Using the "/ADD" qualifier adds the new conditions to the list, while the "/DELETE" qualifier removes the specified conditions. $ G1H /COND=NOT_ALPHAS DET1 ^ ^ | | | +--- Histogram | +--- Condition name $ G1H /ADD /COND=(NOT_LIGHT,NOT_HEAVY) DET1 ^ ^ ^ ^ | | | | | | | +--- Histogram | | | | | +--- 2nd additional condition | | | +--- 1st additional condition | +--- add more conditions to histogram DET1 default is to replace existing conditions on DET1 $ G1H /COND=(NOT_ALPHAS,NOT_LIGHT,NOT_HEAVY) DET1,DET2,DET3 This gate command is equivalent to the first two above taken together (for DET1). It demonstrates that a set of gates can be placed on several histograms in a single command. $ G1H /DELETE /COND=(NOT_HEAVY) DET1 This leaves histogram DET1 with gates NOT_ALPHA and NOT_LIGHT The first command below deletes all gates from all histograms while the second command deletes gates from just the two specified 1D histograms. $ XG $ XG/1D DET3_USEFUL,DET1 Experimenter's Guide To Daphne Page 39 Daphne Objects - Gates 3 October 1990 5.11 Method Of Evaluation The following steps take place in evaluating an event: 1. Fetch the next event 2. Add 1 to the count of events 3. The NOTAPE flag is set to "false" 4. The "1-of-N" counter: a. Subtract 1 from the "1-of-N" counter b. If the "1-of-N" counter is now greater than 0 go to step (13) c. If the "1-of-N" counter is now less than or equal to 0 then: Reset the "1-of-N" counter to "N" Go to step (5) 5. The USER user-defined function is called If an arithmetic trap occurs during evaluation of the user-defined function: add 1 to the count of "trapped events" and go to step (13). 6. For each condition, in order, perform the following steps: a. If the condition is "true", add 1 to the count of times this condition is true b. If a USER-n condition: call the appropriate user-defined function. If an arithmetic trap occurs during evaluation of the user-defined function: add 1 to the count of "trapped events" and go to step (13). c. If a KILL condition and the argument is "true" go to step (13) d. If a NOTAPE condition is "true" then set the NOTAPE flag to "true" e. If a condition refers to a map or window which has not been evaluated, then evaluate it. This may require evaluating other maps and linearizations. The results of any maps, linearizations, or windows which are evaluated are saved for additional references by the event analysis routine. For instance, an "inside-window" condition may be followed by an "outside-window" condition for the same window. f. Process the next condition Experimenter's Guide To Daphne Page 40 Daphne Objects - Gates 3 October 1990 7. Evaluate all 1D maps which were not evaluated during condition evaluation. This is necessary because the user can start a scatterplot involving a 1D map without stopping acqusition. 8. Evaluate all remaining 2D maps which reference histograms 9. For each 1D histogram, in order, perform the following steps: a. If any of the gates on this histogram are false, then go to step (c) b. For each map on this histogram perform the following steps: i. If the /NOZERO option is selected and the value is zero go to step (iv) ii. If the /NOOVERFLOW option is selected and the value is greater than or equal to the number of channels the go to step (iv) iii. Add 1 to the corresponding channel of the histogram iv. Process the next map for this histogram c. Process the next 1D histogram 10. For each non disk-sorted 2D histogram perform the same steps as outlined for 1D histograms. 11. For each disk-sorted 2D histogram perform the same steps as outlined for 1D histograms. Note: Disk-sorted histograms are used only for replay; for acquisition they are treated as normal 2D histograms. 12. If scatterplots are active, then call the subroutine to process requests for scatterplot data. 13. If event mode taping is active, and the NOTAPE flag is "false", then add the event to the tape output buffer. Experimenter's Guide To Daphne Page 41 Daphne Objects - Example 1 3 October 1990 5.12 Extended Example 1 Consider an experiment of three parameters from an Ortec 811 ADC with a range of 0 to 2047. Call these parameters A, B, and C. Suppose one is interested in histogramming C in one of three different 1D histograms, depending on where the event falls when B is graphed against A: | | Region U | // | // // Region V Parameter B | // // | // /// Region W | // /// | /// | /// | +--------------------------------- Parameter A | | | C | C | C | o | o | o | u | u | u | n | A n | B n | C t | t | t | s | s | s | | | | +--------------- +--------------- +--------------- Parameter A Parameter B Parameter C | | | C | C | C | o | A x B o | A x B o | A x B u | Inside u | Inside u | Inside n | Window n | Window n | Window t | - U - t | - V - t | - W - s | s | s | | | | +--------------- +--------------- +--------------- Parameter C Parameter C Parameter C In the Daphne commands below, I have used uppercase letters for Daphne words which have a special meaning, and lowercase letters for names which can be chosen by the user. Experimenter's Guide To Daphne Page 42 Daphne Objects - Example 1 3 October 1990 One might start the experiment with the following definitions: Create a 2D histogram 512 by 512 channels to contain A vs. B. By default a 2D histogram will allow counts of up to 32,767 per bin: $ H2 512 512 /NAME=a_b Use parameter #1 (A) as the X coordinate. Use parameter #2 (B) as the Y coordinate. Divide both A and B by 4 so as to fit the 2048 channel ADC reading into the 512 by 512 histogram: $ M2 1 2 a_b /NAME=a_b /XGAIN=4 /YGAIN=4 An experimenter will normally have a 1D histogram of each parameter. I like to allocate histograms which are slightly larger than the maximum value produced by an ADC so that I can detect cases where the parameter values exceeds the normal output of an ADC. For instance, an Ortec 811 which has a nominal 10 volt range of 0 to 2047 can produce values up to about 2200 for voltages greater than 10 volts in a highly non-linear fashion. With extra channels in the 1D histogram I can see if the voltages are entering this non-linear region. Because 1D histograms require relatively little space, there is no need for a gain greater than 1 as in the 2D case. By default, the $H1 command allocates 32 bits per histogram bin so counts of up to about 2,000,000,000 per bin can be accomodated without concern about overflow. $ H1 2100 /NAME=a $ H1 2100 /NAME=b $ H1 2100 /NAME=c Sort parameters #1 (A), #2 (B), and #3 (C) into the corresponding 1D histograms: $ M1 1 a $ M1 2 b $ M1 3 c Experimenter's Guide To Daphne Page 43 Daphne Objects - Example 1 3 October 1990 The entire Event Handler program for such an experiment would look like this: +---------------------------------------------------------------------+ | adcSlot=5 ; Ortec 811 in slot 5 of crate | | | | bru start | | | |init cnaf 1,adcSlot,7,2 ; Reset ADC | | brur ; return to caller | | | |main dlay 100*10 ; wait 100.0 uSec (100 nSec units) | | ; for Ortec 811 to convert | | cnaf 1,adcSlot,0,0 ; read channel 0 - "A" | | out ca1 ; output A as parameter 1 | | cnaf 1,adcSlot,1,0 ; read channel 1 - "B" | | out ca1 ; output B as parameter 2 | | cnaf 1,adcSlot,2,0 ; read channel 2 - "C" | | out ca1 ; output C as parameter 3 | | | | cnaf 1,adcSlot,7,2 ; Reset ADC | | | | brur ; return to caller | | | | include 'DAPEH:STANDARD' | +---------------------------------------------------------------------+ For information on writing Event Handler programs see sections 19 and 20. Experimenter's Guide To Daphne Page 44 Daphne Objects - Example 1 3 October 1990 Assume that after running for a while one can discern where the windows are to be drawn. After stopping acquisition one could define windows, conditions, and gates in the following manner: Display the 2D histogram A_B in order to draw the windows using graphical input: $ D2H a_b The map qualifier of the $W2 command is optional since the window program is able to work backwards from the histogram displayed to the map which created the histogram. When a histogram is referenced by more than one map, the first map which references the histogram is the default. Use the cross-hairs to enter the coordinates of the window vertices. Finish the creation of the window by using the "." key of the graphics terminal keyboard. The window program wil connect the last point to the first point to create a closed figure. $ W2 /NAME=u /OUTPUT=create_u Similarly for the V and W windows: $ W2 /NAME=v /OUTPUT=create_v $ W2 /NAME=w /OUTPUT=create_w Define conditions based on data being inside the windows: $ CON uvw Where UVW.CON contains the following three lines: +-------------------------------------+ | in_u: IN2 u | | in_v: IN2 v | | in_w: IN2 w | +-------------------------------------+ Now define three 1D histograms (one for each window) and a map which causes parameter #3 (C) to be sorted into each of these histograms: $ H1 /NAME=c_and_u 2100 $ H1 /NAME=c_and_v 2100 $ H1 /NAME=c_and_w 2100 $ M1 3 c_and_u,c_and_v,c_and_w Finally, define gates which can veto sorting into those histograms if A vs. B does not fall into the appropriate window: $ G1H/CON=in_u c_and_u $ G1H/CON=in_v c_and_v $ G1H/CON=in_w c_and_w Experimenter's Guide To Daphne Page 45 Daphne Objects - Example 2 3 October 1990 5.13 Extended Example 2 In this experiment the goal was to determine the composition of very large biological molecules by measuring the mass of sputtered molecules. The mass is determined by time-of-flight measurements using a Lecroy 4208 TDC with 1 nSec resolution that can record up to 8 hits. Times are measured from the time of the arrival of the beam. In order to allow for molecules of as many as 20,000 AMU the experimenters decided to use 1D histograms of 65,535 channels to histogram the data. The experimenters wanted a histogram of each TDC channel considered separately, as well as one containing the union of all channels. Because it seldom happens that they have 8 hits, they decided to use the /NOZERO option to avoid placing a lot of uninteresting counts in channel zero. In order to save space in this document I have pretended they are using only three TDC channels. File SETUP.COM +------------------------------------+ a. | $H1 65535 /NAME=lptot/NOZERO | | $H1 65535 /NAME=lp1/NOZERO | | $H1 65535 /NAME=lp2/NOZERO | | $H1 65535 /NAME=lp3/NOZERO | b. | $M1 1 lp1,lptot /NAME=t1 | | $M1 2 lp2,lptot /NAME=t2 | | $M1 3 lp3,lptot /NAME=t3 | c. | $con usual | +------------------------------------+ File USUAL.CON +------------------------------------+ d. | hit1: ANYON t1 1111111111111111 | | hit2: ANYON t2 1111111111111111 | | hit3: ANYON t3 1111111111111111 | e. | any_hits: OR hit1 hit2 hit3 | f. | no_hits: NOT any_hits | +------------------------------------+ a. Create histogram LPTOT which will contain all TDC hits which are not zero. b. Create map T1 which will sort parameter 1 into histograms LPTOT and LP1. c. The $CON command expects its input to be from a file with the extension ".CON". In this case the file is "USUAL.CON". Experimenter's Guide To Daphne Page 46 Daphne Objects - Example 2 3 October 1990 d. Create a condition HIT1 which is true if any of its 16 bits are not zero. In other words: count the number of hits in channel 0 by counting the number of times map T1 (parameter 1) is non-zero. e. Conditon ANY_HITS will be true if there is a hit in either channel 0, 1, or 2 f. Condition NO_HITS will be true when ANY_HITS is false: at least one of channels 0, 1, or 2 received a hit. This was the basic setup file. Sometimes they wanted to look at what fragments were found in combination with a fragment of a particular mass. Because the fragment of interest could show up in any of the eight channels, they needed to define 8 duplicate windows: one for each channel. As before, I will pretend that there are only 3 channels. A one-time-only step was to define a gated version of LPTOT called "LPTOTG" and to indicate by an $M1 commands which parameters should be sorted into it: File WINDOW_A_INIT.COM: +---------------------------------------+ | $ H1 65535/NAME=lptotg/NOZERO | | $ M1 1 lptotg | | $ M1 2 lptotg | | $ M1 3 lptotg | +---------------------------------------+ Each time they wanted to change the window they executed the following command file: File WINDOW_A.COM: +---------------------------------------------+ a. | $ INQUIRE l "Lower channel number" | | $ INQUIRE h "Upper channel number" | b. | $ X1W wa1,wa2,wa3 | c. | $ W1/MAP=t1/NAME=wa1/low='l'/high='h' | | $ W1/MAP=t2/NAME=wa2/low='l'/high='h' | | $ W1/MAP=t3/NAME=wa3/low='l'/high='h' | d. | $ CON usual+window_a | e. | $ G1H/COND=(window_a) lptotg | +---------------------------------------------+ Experimenter's Guide To Daphne Page 47 Daphne Objects - Example 2 3 October 1990 File WINDOW_A.CON: +---------------------------------------------+ f. | in_wa1: IN1 wa1 | | in_wa2: IN1 wa2 | | in_wa3: IN1 wa3 | g. | window_a: OR in_wa1 in_wa2 in_wa3 | +---------------------------------------------+ a. Ask user to supply a value for the symbol "l". $INQUIRE is a VMS DCL command b. Delete the previously defined 1D windows prior to creating them with new upper and lower bounds. c. Create new 1D windows ("WA1", "WA2", and "WA3") with the specified upper and lower bounds. d. Repeat the definition of the earlier conditions with new conditions in file "WINDOW_A.CON". It is important to use a plus-sign ("+") rather than a comma. Plus-signs are used to separate condition files for the same event type. Commas are used to separate condition files for different event types. e. Allow histogram LPTOTG to be incremented only when condition WINDOW_A is true. f. Define a condition "IN_WA1" which is true when map T1 is inside window WA1. g. Define a condition "WINDOW_A" which is true whenever at least one of T1, T2, or T3 is between the lower and upper limits of the windows Ater using this feature for a while they decided to try looking at histograms which were gated by a combination of two fragments. A very general solution was adopted allowing most meaningful combination of two windows to be used as gating condition: Experimenter's Guide To Daphne Page 48 Daphne Objects - Example 2 3 October 1990 File WINDOW_AB.COM +---------------------------------------------+ a. | $ INQUIRE l "Lower channel number" | | $ INQUIRE h "Upper channel number" | | $ X1W wa1,wa2,wa3 | | $ W1/MAP=T1/NAME=wa1/LOW='l'/HIGH='h' | | $ W1/MAP=T2/NAME=wa2/LOW='l'/HIGH='h' | | $ W1/MAP=T3/NAME=wa3/LOW='l'/HIGH='h' | | $ ! | b. | $ INQUIRE l "Lower channel number" | | $ INQUIRE h "Upper channel number" | | $ X1W wb1,wb2,wb3 | | $ W1/MAP=t1/NAME=wb1/LOW='l'/HIGH='h' | | $ W1/MAP=t2/NAME=wb2/LOW='l'/HIGH='h' | | $ W1/MAP=t3/NAME=wb3/LOW='l'/HIGH='h' | | $ ! | c. | $ CON usual+selectcond | d. | $ @setcoinc | +---------------------------------------------+ File SELECTCOND.CON +---------------------------------------------+ e. | in_wa1: IN1 wa1 | | in_wa2: IN1 wa2 | | in_wa3: IN1 wa3 | | a: OR in_wa1 in_wa2 in_wa3 | f. | in_wb1: IN1 wb1 | | in_wb2: IN1 wb2 | | in_wb3: IN1 wb3 | | b: OR in_wb1 in_wb2 in_wb3 | g. | and: AND a b | h. | or: OR a b | i. | -a: NOT a | j. | -b: NOT b | k. | a-b: AND a -b | l. | b-a: AND b -a | +---------------------------------------------+ File SETCOINC.COM +----------------------------------------------------------+ m. | $ INQUIRE coinc "Coinc logic [A B AND OR -A -B A-B B-A]" | n. | $ G1H/COND=('coinc') lptotg | +----------------------------------------------------------+ Experimenter's Guide To Daphne Page 49 Daphne Objects - Example 2 3 October 1990 a. As before, create window A b. Create window B in the same manner as window A c. Combine the standard conditions with new conditions in file "SELECTCOND.CON" d. The gate command is placed in a separate file "SETCOINC.COM" so that the gate on LPTOTG can be changed without redefining the windows and conditions. To change the gate on LPTOTG execute the following command after stopping acquisition: $ @setcoinc e. Conditions related to window A as before f. Conditions related to window B are similar to those for window A. Conditions (g) through (l) obey the following truth table: Key Description A not A A not A B B not B not B g and: AND a b T F F F "Both A and B" h or: OR a b T T T F "Either A or B" i -a: NOT a F T F T "Outside A" j -b: NOT b F F T T "Outside B" k a-b: AND a -b F F T F "Inside A and outside B" l b-a: AND b -a F T F F "Inside B and outside A" m. The list of possible responses are identical to the names of the conditions. This makes good use of the fact that Daphne allows special characters in symbolic names. n. Use the condition whose name was supplied by the $INQUIRE statement as a gate on histogram LPTOTG. Experimenter's Guide To Daphne Page 50 Getting Started 3 October 1990 6 Getting Started For convenience of discussion, let's assume that a new group has arrived from the University of the Arctic and is studying ice-cube decay. The name of their experiment is ICE. 6.1 Where to Put Files At the Argonne Atlas accelerator users normally use the EXP account while performing experiments. Each experimental group keeps their files in a separate subdirectory of the EXP account in order to minimize the danger of deleting another group's files. The first step is to login and create a subdirectory where their files will reside. Username: EXP Password: {password} $ create/directory [exp.ice] $ set default [exp.ice] 6.2 The CONFIG.COM file Part of setting up Daphne to collect data is specifying the I/O devices and options that an experiment will use. These five to ten commands must be used each time a user logs in to EXP to run an experiment. By convention, these "configuration" commands are put in a file named "CONFIG.COM" so they can be executed easily when needed. 6.3 Use $DAP to Start the Daphne Subsystem The $DAP command must be the first command. It initializes a number of data files, sets up defaults for some options, and reserves a section of system memory to save information entered by the user with later commands. Although $DAP sets defaults, most of them can be changed with the $MAX command. The $DAP command requires a single operand: a three character identifier. The identifier is used to give unique names to Daphne resources so that two or more Daphne users can be simultaneously active without interfering with each other. Experimenter's Guide To Daphne Page 51 Getting Started - $MAX 3 October 1990 6.4 Use $MAX to Specify Limits There are a number of assumptions made by Daphne when a session is started about the number and size of objects a user will need. For instance, at one time it was assumed that users would seldom need more than 50 1D histograms or 25 2D histograms. The $MAX command allows a user who anticipates requiring more than the default number of histograms, maps, etc. to declare his plans so that Daphne can allocate the extra resources in advance of need. For instance, a user requiring as many as 100 1D histograms and 75 2D histograms would use the following command: $ MAX /H1=100 /H2=75 Some limits controlled by the $MAX command can be changed at any time. An example of such a limit is the amount of memory to allocate for generated code. Other limits may not be changed after Daphne has allocated space using the information. For instance, the maximum number of one dimensional histograms cannot be changed once the first one dimensional histogram has been created. Immediately following the $DAP command any limit under control of the $MAX command may be changed. The following limits are those most often changed from the defaults: - /H1 - Number of 1D histograms - /H2 - Number of 2D histograms - /M1 - Number of 1D maps - /M2 - Number of 2D maps - /SP - Number of scatterplots - /COND - Number of conditions - /C_TBL - Number of pages for conditions - /W1 - Number of 1D windows - /W2 - Number of 2D windows - /W_COR - Space for lists of vertices of 2D windows - /W_BLK - Space for tabulation of 2D window values - /LNZ - Number of linearizations - /LNZ_COR - Space for lists of points in linearizations - /LNZ_BLK - Space for tabulation of linearization lines - /CODE - Space for generated code - /TAB - Space for generated tables - /FIX - Number of fix constants - /FLT - Number of float constants - /SCL - Number of scaler modules NOTE The default for these values can be seen using the $SWP/MAX command. Space is allocated in units of pages which are 512 bytes. Experimenter's Guide To Daphne Page 52 Getting Started - $MAX 3 October 1990 6.5 Using $SAV/$RES to Change Limits You can use $SAV/$RES together to change some limits when it is too late to change them with $MAX. For instance, if you discover that you neglected to change the limit on the number of 1D maps after having created several, use the following sequence to increase the limit to, say 100: $ KLT ! stop the tape process $ SAV TEMP_SAVEFILE ! save definitions $ RES TEMP_SAVEFILE /M1_MAX=100 ! restore while changing limit NOTE It is suprising that it is necessary to kill the tape process. This is necessary because of a (temporary) lack of coordination between the $RES program and the output tape process. This is the proper procedure to use for changing any limit with $RES, EXCEPT for the maximum number of histograms. The following limits can be changed with $SAV/$RES: - /H1_MAX - Number of 1D histograms - /H2_MAX - Number of 2D histograms - /M1_MAX - Number of 1D maps - /M2_MAX - Number of 2D maps - /W1_MAX - Number of 1D windows - /W2_MAX - Number of 2D windoes - /W_COR_MAX - Space for lists of vertices of 2D windows - /W_BLK_MAX - Space for tabulation of 2D window values - /LNZ_MAX - Number of linearizations - /L_COR_MAX - Space for lists of points in linearizations - /L_BLK_MAX - Space for tabulation of linearization lines NOTE To change the limits on the number of scatterplots, FIX variables, or FLT variables you must exit and restart Daphne (January '88). Experimenter's Guide To Daphne Page 53 Getting Started - $MAX 3 October 1990 6.6 Changing Histogram Limits Increasing the number of histograms, whether 1D or 2D, is more complicated because you must use the $WR command to save the histogram data. The $SAV command does NOT save histogram data, just histogram attributes. Of course, if your histograms are brand new, or they have just been zeroed by the $ZAP command, then there is no need to actually write them out with $WR and then read them back in with $RD. To increase the number of 1D histograms to 125 and the number of 2D histograms to 100 use the following sequence: $ WR HISTS ! creates files HISTS.HS1 and HISTS.HS2 $ SAV HISTS ! creates HISTS.SAV $ RES HISTS /H1_MAX=125 /H2_MAX=100 ! restore definitions with increased limits $ RD HISTS ! fills hists from HISTS.HS1 and HISTS.HS2 Experimenter's Guide To Daphne Page 54 Getting Started - $PSEUDOEVENT 3 October 1990 6.7 Use $PSEUDOEVENT to Enable Pseudo-Parameters Pseudo-Parameters are values computed by user-defined functions from the original event data. For instance, a position sensitive detector produces four signals: X-Left, X-Right, Y-Top, and Y-Down. From these four signals the approximate X and Y position of the particle passing through the detector can be computed by: (XL-XR) + constant1 X = --------------------- * constant2 XL + XR (YD-YT) + constant3 Y = --------------------- * constant4 YD + YT By displaying a histogram of X versus Y, a much clearer picture of the detector's operation is seen than by displaying X-Left, X-Right, Y-Top, and Y-Down separately. The programming of Event Processors to compute user-defined functions is described in section 24. However, if you are planning on using user-defined functions and pseudo-parameters, you must tell Daphne before acquisition begins by using the command: $ PSEUDOEVENT Without the $PSEUDOEVENT command Daphne will not generate code to call your user-defined function. If the user-defined function is not called, no pseudo-parameters are computed. Since Daphne realizes that no pseudo-parameters will be computed it will not let you reference them in Map statements ($M1, $M2, and others). Use the $PSEUDOEVENT command if, and only if, you intend to have a user-defined function running on the Event Processors. To disable the use of pseudo-events use the command: $ PSEUDOEVENT/OFF Experimenter's Guide To Daphne Page 55 Getting Started - $CDV 3 October 1990 6.8 Use $CDV to Specify the Camac Device The $CDV command tells Daphne the address of the Camac crate containing the acquisition hardware and the slots of modules within the crate that are important to Daphne. The $CDV command does no I/O: it checks that the arguments are reasonable, and stores them in a convenient place for use by $EHSEND, $EHFIFO, $ACQ, and $STP. The $CDV command also sets the terminal attributes to make them compatible with the communication format used by the KS/CC. For example, it disables echo and broadcasts. The terminal attributes are automatically reset by VMS to the original state when the terminal port is released. The following is a typical $CDV command: $ CDV TZC3 The following shows an unusual case: no defaults were accepted: $ CDV TZC3 /EH_CRATE=2 /EH_SLOT=18 /DELAY=10 The parts of the $CDV command are: - A terminal port [Required - No Default] This parameter gives the name of the terminal port interface connecting the VAX to the Kinetic Systems 3989 Crate Controller of the crate containing the Event Handler. For instance, "TTA1" or "TZA3". How does one tell the name of the terminal port used at an experimental station ? Generally, it is written in a conspicuous place near the experimental station. - /EH_CRATE [Optional - Default is crate 1] This is the crate number of the Kinetic Systems 3989 Crate Controller of the crate containing the Event Handler. The crate number is set by switches inside the crate controller. For information on how to set the crate address see section 48 on configuring the KS/CC crate controller. - /EH_SLOT [Optional - Default is slot 20] This is the number of the slot containing the AUX of the Event Handler. If the AUX is a black unit occupying two slots, count it as occupying the lower numbered of the two slots. If the AUX and Event Handler are combined in a single silver module, count it as occupying the higher numbered of the two slots. For instance, when using the default slot (/EH_SLOT=20), a black AUX would occupy slots 20 and 21, while the silver Event Handler/AUX would occupy slots 19 and 20. When a black dual-width AUX is combined with a black dual-width Event Handler slots 18 through 21 will normally be occupied. Experimenter's Guide To Daphne Page 56 Getting Started - $CDV 3 October 1990 - /DELAY [Optional - Default is 5 seconds] This is part of the $CDV command for historical reasons. It specifies the time interval, in seconds, between read-out of scalers. 6.8.1 Releasing the $CDV Port The terminal port used by the $CDV command is released by issuing a $CDV command for another port, by leaving Daphne with the $EXT command, or by using the deallocate qualifier of the $CDV command: $ CDV/DEALLOC Experimenter's Guide To Daphne Page 57 Getting Started - $MDV 3 October 1990 6.9 Use $MDV to Specify the Multibus Interface The Multibus is an electronic chassis similar to a Camac crate or VAX Unibus. Even if your acquisition system has just one Multibus (and one set of Event Processors) you must tell Daphne which Multibus you will be using, if only to reserve it and prevent others from using it. The $MDV command has a single argument which identifies which Multibus interface the experiment will be using. When you give the $MDV command you get exclusive access to the interface: no one else can use it until you surrender it by giving another $MDV command (or by leaving Daphne). The $MDV command does no I/O: it merely checks that there is such a Multibus interface, reserves the device, and then stores the information away for later use by the acquisition program. To allocate Multibus interface "A" use the command: $ MDV A The Multibus interfaces have long names, but are abbreviated by using the last part of the name: instead of "DAP$EVENT_CHAN_A" just use "A" and for "DAP$EVENT_CHAN_B" just use "B". To get a list of Multibus interfaces use the command: $ SHOW LOGICAL DAP$EVENT_CHAN_* The Multibus is always released when you exit Daphne or log off. If you want to release it without leaving Daphne or logging out, use the following command: $ MDV/DEALLOC Experimenter's Guide To Daphne Page 58 Getting Started - $DDV 3 October 1990 6.10 Use $DDV to Specify the Display Device The $DDV command tells Daphne the terminal port and type of the display device you will be using, if any. The following list show the devices that are supported and the corresponding $DDV command: (assuming the terminal is at terminal port TTA1:) - Tektronix 4000 series terminals (4006/4010/4014/4015) and other storage tube displays (for example, the Tektronix 4114): $ DDV TTA1 - Tektronix 4107A $ DDV TTA1 /TYPE=4107 - Tektronix 4111 $ DDV TTA1 /TYPE=4111 - Tektronix 4115 with NO DMA interface $ DDV TTA1 /TYPE=4115 - Tektronix 4115 with DMA interface (DMA interface address of XTA0) $ DDV TTA1 /TYPE=4115 /DMA=XTA0 6.10.1 Simultaneous Use of Two Graphics Terminals A user can use two graphics terminals at the same time. All commands which allow the use of a graphics terminal, with the exception of scatterplot commands, will allow you to use a second graphics terminal by using the "/SECOND" qualifier in the command. This would be useful, for instance, when you want the color capabilities of the Tektronix 4100 series terminals and the quick hardcopy capability of the hardcopy unit connected to the Tektronix 4014 terminals. $ DDV TZC2 /TYPE=4115 /DMA=XTA0 $ DDV TZC0 /TYPE=4010 /SECONDARY $ D2H E_VS_T $ D1H/SECOND TOF Experimenter's Guide To Daphne Page 59 Getting Started - $DDV 3 October 1990 6.10.2 Using a Command Terminal as a Graphics Terminl It is possible to use a Tektronix 4100 series terminal simultaneously as both a command terminal and graphics terminal, although it is not as convenient as having two terminals. When you issue the $DDV command, simply use the name of your current command terminal port. $ SHOW LOGICAL TT "TT" = "TTA0:" (LNM$PROCESS_TABLE) $ DDV TTA0 /TYPE=4107 6.10.3 Acknowledgement The Tektronix 4000 series programs makes use of the Unified Graphics package written by Robert C. Beech of the Stanford Linear Accelerator Center (SLAC). 6.10.4 Tektronix 4100 The 4100 series terminals have a large number of setup options. If you are having problems using a 4100 series terminal, consult section 44. 6.10.5 Releasing the Graphics Terminal To release the display device in order to use a different unit, or so that someone else can use it, issue the $KLG ("kill graphics") command: $ KLG Experimenter's Guide To Daphne Page 60 Getting Started - $PDV 3 October 1990 6.11 Use $PDV to Define the Plot Device The $PDV command gives the name and type of the hardcopy plot device you will be using, if any. Plots are made using the Unified Graphics package written by Robert C. Beech of the Stanford Linear Accelerator Center (SLAC). Devices supported at the Argonne Physics Division include the following: Name $PDV Code Resolution Orientation Versatec V80 VEP12FF 200 dots/inch landscape Versatec 1100 VEP11FF 100 dots/inch landscape QMS 1200 QMS1200 300 dots/inch landscape 6.11.1 For Unavailable Plot Devices Use "$PDV/TYPE plot-device-type" Even if the hardcopy unit you wish to use is not available or not connected to the computer you are using, you can still create data files which can be sent to the device at a later time for printing. For instance, if you wish to create files which will eventually be printed on the QMS 1200 laser printer use the command: $ PDV/TYPE QMS1200 When you subsequently issue plot commands, such as $P1H, files with the extension ".PLT" will be created, which you can copy over a network or to magnetic tape for later printing. 6.11.2 For Known Plot Devices Use "$PDV plot-device-name" This form of the $PDV command is suited for plot devices which are at known addresses and don't change. With this command you just specify the device name from among a list maintained by the system manager. It is not necessary (or possible) for the user to specify the type of device in this case. The $PDV command consults a dictionary in a file maintained by the system manager (SYS$MANAGER:DAPTERMS.DAT) to determine the device type. The method of implementation of the $PDV command precludes the use of logical names and requires that the trailing colon (":") be omitted from device specifications. A typical $PDV command is: $ PDV LPA0 6.11.3 Use $KLP to Stop the Plot Process To stop the plot process use the "kill plot" command: $ KLP Experimenter's Guide To Daphne Page 61 Getting Started - Hardware Checks 3 October 1990 6.12 Hardware Connections Most Frequently Neglected This is a list of the most common oversights in setting up the Daphne hardware for a new experiment at an existing experimental station. For a complete list of hardware connections see section 46. - EMUX (Section 46.3) - Have you selected your Experimental Station using the switches on the EMUX ? - Have you checked that your Experimental Station is NOT selected by the other half of the EMUX ? - Have you reset the EMUX ? - Check Kinetic Systems Crate Controller (Section 46.5) - REQUEST to GRANT IN ? - GRANT OUT to Event Handler GRANT IN ? - Event Handler (Section 46.9) - GRANT IN to KS/CC GRANT OUT ? - Input 8 ("Acquisition Active") from Jorway NIM Output 1 (Section 46.8) - Supplied by User - EVENT Signal to Event Handler from trigger electronics - BUSY Signal from Event Handler to trigger electronics For more information on the EVENT and BUSY signal see Section 21 ("Interfacing the Event Handler") Experimenter's Guide To Daphne Page 62 Getting Started - $EVS 3 October 1990 6.13 Use $EVS to Define the Event Structure 6.13.1 The Most Common Event Structures You can avoid reading most of this section (a section which, even by the standards of this document, is incredibly boring) if your event structure falls into one of two classes. These two classes include all the experiments conducted with Daphne in the first two years of operation. - Fixed Length Event By far the most common form of the $EVS command is for experiments in which the same parameters are read-out for every event. The following command defines an experiment with a single event type (when there is only one event type it will always be type 0) with exactly 5 parameters: $EVS 0/FIX=5 ^ ^ ^ | | | | | +---- 5 parameters | | | +---------- a fixed length event | +----------------- the event type - Variable Length Events of a Single Event Type The second most common form of the $EVS command is that of a single event type in which the number of parameters varies, depending on which set of detectors have fired. The detectors which have fired are usually recorded in a pattern register of 16 to 48 bits, typically a Lecroy 4448. The /VAR format is not used because, in general, the number of parameters is not the same for each detector, a requirement of the /VAR format. For example, an experiment in which there are two 16 bit pattern registers at the beginning of the event, followed by a number of words depending on the combination of detectors which fired, could be described with the following command: $EVS 0/FIX=2/QSC=1 ^ ^ ^ ^ | | | | | | | +--- one part of indefinite (variable) length | | | | | +---- at least 2 parameters always present | | (the two 16 bit pattern register) | | | +---------- a fixed length part is present | +----------------- the event type Experimenter's Guide To Daphne Page 63 Getting Started - $EVS 3 October 1990 6.13.2 Event Types Daphne can support up to 16 event types as well as variable length events. Data sources can be considered separate event types if they are logically independent. As an example, consider an experiment with a detector set of five arms and a separate monitor counter. The experiment requires a minimum of two of the five arms to fire to have a coincident event. In Daphne, arms 2 and 4 firing would be considered the same event type as arms 1, 3, and 4 firing. However, the firing of the monitor would be considered a distinct event type. The information about which combination of detector arms fired would be just one parameter of a single event type. Events of different type are analyzed independently, even if they happen "simultaneously". For instance, assume that detector A and detector B are treated as different event types. Even if A and B fire simultaneously, A will be read-out as one event (type 0 for example) and B will be read-out as a separate event (type 1 perhaps). One event may go to Event Processor 2, while the other may be routed to Event Processor 4. They will end up in different data blocks on the tape, perhaps not even adjacent blocks, since data from Event Processor 1 might be sent to the VAX between transmissions by Event Processors 2 and 4. The event type is determined by the number, between 0 and 15, written as the first word of the event by the Event Handler program. Usually the number written corresponds to the bit number in a pattern register such as the Bi-Ra 2351 shown in the diagram in section 9.1. The event type word should only be present when the user has specified multiple event types in the $EVS command. If coincidences between the detectors are important in the analysis of the data, it is necessary to treat this case as a single event type of variable length. The single event can be viewed as being composed of a number of optional segments in which each segment corresponds to one detector. In this case, the first word of an event should contain a pattern word which indicates which detectors fired and are present in the event. Bits which are zero would indicate that data from the corresponding detector has been omitted from the event. For instance, an experiment at Atlas in June '86 consisted of the detectors descibed below, each of which could fire independently, and was treated as a single event type of variable length: - 2 telescopes of 4 parameters each - 3 telescopes of 3 parameters each - 4 time-of-flight detectors of 4 parameters each - 1 time-of-flight detectors of 2 parameters - 1 monitor of 2 parameters - 7 strip detectors of 2 parameters each - 4 NaI detectors of 3 parameters each - 2 Breskin detectors of 6 parameters each Experimenter's Guide To Daphne Page 64 Getting Started - $EVS 3 October 1990 The event was preceded by three 16 bit pattern words in which each detector was represented by a single bit. Other bits represented combinations of interest for prescaling the data or rejecting certain combinations of detector firings. Only those detectors which fired were read-out. Since all detectors which fired simultaneously were treated as a single event, data from one detector would not be separated from other, related, information. Variable length events can also be used for events with zeroes suppressed. As before, it is necessary to have some method, such as a pattern word, to indicate which parameters are present and which have been omitted. Daphne assumes that (most) event types can be described as a combination of a "fixed" part, a "variable" part, and a "QSCAN" part. - FIX The FIX part are those parameters which are always present in an event. Most experiments consist of only a FIX part. Daphne assumes that FIX parameters will be placed at the beginning of any event. The number of words in the FIX part of an event is specified by the /FIX qualifier of the $EVS command. - VAR The VAR part of an event follows the FIX part and consists of those parameters whose read-out depends on a bit significant mask or pattern register. The pattern register, or registers, may total more than 16 bits. For each bit, one or more words of data may be read-out, but the same number of words must be read-out for each bit. Consider as an example, an experiment consisting of 8 detectors, any combination of which may fire, including all or none. When the "N th" detector fires the "N th" bit in a pattern register is set. On read-out the Event Handler program inspects the pattern register and when it finds a bit set, it will read-out the modules corresponding to that detector. The pattern register value precedes the rest of the VAR group in the event. The number of VAR groups is specified by the /VAR qualifier of the $EVS command. Experimenter's Guide To Daphne Page 65 Getting Started - $EVS 3 October 1990 For each VAR group one can specify the number of 16 bit words of coincidence register ("CR") data using the /CR qualifier. For instance, when using the Lecroy 4448 48 bit coincidence register, one might code: $ EVS 0/FIX=4/VAR=1/CR=3 48 bit module /CR=3 because CR = ------------------- 16 bits/pattern word By default, the $EVS command assumes each VAR group is controlled by a coincidence register of 16 bits. For each VAR group one can also specify the number of words of data read-out for each bit set using the /PARM qualifier. For instance, if for each detector that fires one reads an ADC and a TDC, one would code: $ EVS 0/FIX=4/VAR=1/CR=3/PARM=2 By default the $EVS command assumes only one parameter is read-out for each bit set in the coincidence register. - QSCAN The QSCAN is the last part of an event: it follows the VAR group (if it is present), and the FIX part. The QSCAN part has no definite length and no particular structure. Its invention is meant to handle two special cases: (a) events with no defined structure and (b) modules where the number of words to be read-out is not known until the last word in a sequence is read, and the Camac Q signal goes to "0". The number of QSCAN groups is specified by the /QSC qualifier of the $EVS command. There is no standard way of telling when one QSCAN group ends and another begins. Some users have advocated using a word with all bits set (negative 1) to indicate the end of a QSCAN group. When there are several event types, they must be defined in numerical order by event type without skipping any event types. For instance, in defining event type 2, it is illegal to define event types 0 and 2 only: one must define 0, 1, and 2 and they must be defined in that order. If there are more than 8 event types the first 8 (numbered 0 to 7) must be defined in the first $EVS command, any remaining event types are defined in a second command, again in numerical order without omissions. Experimenter's Guide To Daphne Page 66 Getting Started - $EVS 3 October 1990 Here are some more examples of the $EVS command: - $EVS 0/FIX=50 There is a single event type with exactly 50 parameters - $EVS 0/FIX=5 1/FIX=7 2/FIX=10 There are three event types, all with a fixed number of parameters. Event type 0 has 5 parameters, event type 1 has 7 parameters and event type 2 has 10 parameters. - $EVS 0/FIX=5/VAR=1/PARM=2 There is a single event type. It begins with 5 parameters which are always present. It is followed by a single VAR group consisting of a pattern word and 2 words of data for each bit set in the pattern word. - $EVS 0/FIX=5/VAR=2/PARM=(1,4) There is a single event type. It begins with 5 parameters which are always present. It is followed by two VAR groups. The first VAR group consists of a pattern word and 1 word of data for each bit set in the pattern word. The second VAR group consists of a pattern word and 4 words of data for each bit set in the pattern word. - $EVS 0/VAR=1 1/VAR=1/PARM=3 There are two event types, neither of which has a FIX part. For event type 0 there is one word of data for each bit set in the pattern word. For event type 1 there are 3 words of data for each bit set in the pattern word. - $EVS 0/FIX=4/QSC=1 There is a single event type which always begins with 4 words of data. The FIX part is followed by a single QSCAN group (of indefinite length). - $EVS 0/FIX=4/QSC=2 There is a single event type which always begins with 4 words of data. The FIX part is followed by two QSCAN groups (each of indefinite length). Since there is no standard method of indicating the end of a QSCAN group, the user must program the Event Handler to separate the QSCAN groups in such a way that he can later tell when the first one ends and the second one starts. Experimenter's Guide To Daphne Page 67 Getting Started - CONFIG.COM file 3 October 1990 6.14 Examples of CONFIG.COM File Here are some examples of the CONFIG.COM files. The $INQUIRE statement causes the command language interpreter to prompt the user to supply a value for a symbol. The value entered by the user can then be substituted for the symbol when it is recognized by the command language interpreter (by enclosing it in single quote marks). $ DAP BGO $ CDV TZC5 $ MDV A $ DAP MAG $ CDV TZC3 $ INQUIRE MULTIBUS "Use Multibus A or B [Enter A or B]" $ MDV 'MULTIBUS' $ DAP SMG $ CDV TZA1 $ INQUIRE MULTIBUS "Use Multibus A or B [Enter A or B]" $ MDV 'MULTIBUS' $ INQUIRE DISPLAY "Use the Display device [Enter Y or N]" $ IF DISPLAY THEN $ DDV TZC1 $ DAP BGO $ CDV TZA1 $ INQUIRE MULTIBUS "Use Multibus A or B [Enter A or B]" $ MDV 'MULTIBUS' $ INQUIRE DISPLAY "Use the Display device [Enter Y or N]" $ IF DISPLAY THEN $@DDV Where DDV.COM contains: $ DDV TZC2 /TYPE=4115 /DMA=XTA0 Experimenter's Guide To Daphne Page 68 A Strategy for Defining Daphne Objects 3 October 1990 7 A Strategy for Defining Daphne Objects Suppose you are from the University of the Arctic conducting an experiment named ICE. The following strategy has been shown by experience to cause the least inconvenience: 7.1 Number the Pseudo-Parameters If you want histograms of pseudo-parameters you must have maps which refer to the pseudo-parameters. In order to create these maps you must know the pseudo-parameter number. Pseudo-parameters are numbered starting from 1, but not every position in the pseudo-event vector need be assigned. A common method is to group pseudo-parameters by detector. For instance pseudo-parameters for detector 1 might be in positions 11, 12, and 13; for detector 2 in positions 21, 22, and 23; and so on. Assigning numbers to pseudo-parameters will also force you to think about the nature of your user-function at an early stage. 7.2 Define 1D Histograms and Maps Using your favorite editor you should create a command file ICE.1D defining all the 1D histograms and maps. The $H1 commands should precede the $M1 commands. Experimenter's Guide To Daphne Page 69 A Strategy for Defining Daphne Objects 3 October 1990 7.3 Define 2D Histograms and Maps Create a command file ICE.2D defining all the 2D histograms and maps. The $H2 commands should precede the $M2 commands. If you have variable length events with optional segments you will probably want to define your histograms with the /NOZERO qualifier: Parameters and pseudo-parameters for segments which aren't present in an event will usually be zero. There are good reasons for defining the 2D histograms separately from the 1D histograms. In many experiments the first steps in debugging the acquisition hardware is to make sure each piece of equipment works and that the triggering is working properly. Only later does an experimenter need 2D histograms to look for interactions between devices. Since 2D histograms are not really used during this stage of setup, why bother with the extra overhead of defining them and clearing them ? Secondly, in many experiments, calibrations must be done either before or after the main experiment. When the calibrations are complete they are usually saved as a disk file. It is easier to save all histograms rather than just a subset, yet there's no point in saving the 2D histograms if they are not part of the calibration of the equipment. Furthermore, the 2D histograms usually require vastly more disk space than the 1D histograms. Thirdly, there is only a limited amount of main memory available for use by the current experiment and the groups doing setup or calibrations. If the 2D histograms are not necessary for setup or calibrations then by not using them more memory is left for the main experiment with no loss to the group doing setup or calibrations. If you have variable length events with optional segments you will probably want to define your histograms with the /NOZERO qualifier: Parameters and pseudo-parameters for segments which aren't present in an event will usually be zero. Experimenter's Guide To Daphne Page 70 A Strategy for Defining Daphne Objects 3 October 1990 7.4 Define Conditions Create a "first guess" conditions file ICE.CON containing: - Pattern Registers or Bit Significant Parameters If you have any pattern registers or bit significant parameters put in tests for every bit of interest. It is often useful in these cases to have every bit tested. Each bit test adds only 5 or 10 uSec to the time required to analyze each event, and removes any doubt about the contents of the pattern register. If the additional tests might slow down acquisition too much, you can always remove the unnecessary tests after equipment has been checked out. - Tests for Zeroes If you want any maps (parameters) tested for zero or non-zero for use in gating, put them in at this time. - KILL Conditions If you want to use KILL conditions you might define them now, but it is often useful, when debugging acquisition hardware, to be able to see everything. Thus, I suggest that you put in a placeholder such as TRUE or FALSE for the KILL condition. Later on, when the hardware has been checked out, you can replace the TRUE condition with the KILL condition you wanted originally. - Windows The problem with putting window tests such as IN1/OUT1 or IN2/OUT2 in your initial conditions file is that you haven't had a chance to figure out where to put the windows. I suggest that you use a placeholder such as TRUE or FALSE until you have a chance to define the window. A second possibility is to defined windows which are degenerate (for instance from 0 to 2048 when using a 2048 channel ADC). At a later time one can delete the window and recreate it with real values. A third possibility is to place the window type conditions in a separate conditions file, and make use of the $CON command's ability to combine several condition files once windows have been defined: $ CON BASIC ! initial conditions $ CON BASIC+WINDOW1D ! after 1D windows defined $ CON BASIC+WINDOW1D+WINDOW2D ! after 1D and 2D windows ! have been defined It is important when combining several condition files in this way to use plus signs ("+") rather than commas (","). Commas are used to combine condition files for different types of events. Experimenter's Guide To Daphne Page 71 A Strategy for Defining Daphne Objects 3 October 1990 7.5 Define Gates Define a command file ICE.GATES to contain 1D and 2D gates The main reason for putting gate definitions in a separate command file is that during initial testing they are often not used, and can actually obscure problems in the acquisition hardware ("Is this histogram empty because the XYZ detector isn't working or because of this gate ?"). A second reason for putting them in a separate file is due to the way $RD works. When $RD reads in a histogram, it creates a histogram without any gates. If you have the gate definitions in a separate command file, it's easy to redefine them. If they are mixed up with other unrelated commands, such as $H2, then you will get a lot of error messages, duplicated maps, and other forms of confusion. You may want to start your gate command file with a $XG command, which clears all gates, but this is not really necessary. 7.6 Define 2D Windows I suggest that whenever you use the $W2 command to define a 2D window you use the /OUTPUT qualifier. The /OUTPUT qualifier creates a command file which you can later use to recreate the window. This is a great deal easier than trying to type in, say, 10 X-Y pairs. You can also edit the Daphne command file created by $SAV/COMMAND to recover your window definitions. 7.7 Define Linearizations I suggest that whenever you use the $LNZ command to define a linearization you use the /OUTPUT qualifier. The /OUTPUT qualifier creates a command file which you can later use to recreate the linearization. This is a great deal easier than trying to duplicate, for instance, 30 points which defined an earlier linearization. You can also edit the Daphne command file created by $SAV/COMMAND to recover your linearization definitions. 7.8 Define Scalers See section 8 for a discussion of scalers, especially sections 8.9 and 8.10 for a list of the supported scalers and how to specify what scalers are to be read-out. 7.9 Fix and Float Variables FIX and FLT variables are covered in section 22. Experimenter's Guide To Daphne Page 72 Scalers 3 October 1990 8 Scalers Daphne can be programmed to periodically read-out scalers and record them on the event tape. The scalers are read-out over the same RS-232 line which is used to load the Event Handler. Thus, all scalers to be read-out in this manner must be in the same crate as the Event Handler, or one of the crates daisy-chained to it. Because read-out is over the low speed RS-232 I/O channel, only about 25 scalers can be read per second. 8.1 At Acquisition Start When acquisition begins, Daphne starts a subprocess named "Scaler_ttt" where "ttt" represents the three character Daphne identifier. The first action of the scaler subprocess is to reset all scalers that have been defined with $SCL/MENU or $SCL/FILE. The clearing of hardware scalers can be suppressed by using the /KEEP qualifier of the $ACQ command: $ ACQ/KEEP 8.2 $ZAP and $ZAP/SC The scaler program does NOT zero the accumulated scaler values which are in the host computer's memory. To zero the values kept in the host's memory, one uses the $ZAP or $ZAP/SC command. The $ZAP command without arguments clears all histograms, scalers, and condition counts. To zero only the scaler counts (in computer memory) one can use: $ ZAP/SC To zero everything but scaler counts (in computer memory) one can use: $ ZAP/NOSC Experimenter's Guide To Daphne Page 73 Scalers 3 October 1990 8.3 Frequency of Read-out The "/DELAY" qualifier of the $CDV command specifies how many seconds to wait between the end of one read-out cycle and the beginning of the next read-out cycle. The default delay between cycles is 5 seconds. As an example, to specify that the scalers should be read out once every 60 seconds: $ CDV TTA4:/DELAY=60 The scalers are always read at the beginning and end of a run, regardless of the value of /DELAY. 8.4 Frequency of Recording The frequency with which the scaler information is written to an event mode tape is controlled by the "/SC" qualifier of the $TAPE/OUT command. The "/SC" qualifier tells how many blocks of event data must be written to the tape before new scaler data can be written to tape. The requirement that the scaler data be new, prevents the same scaler information from being recorded several times when data rates are much lower than the frequency of scaler read-out. The choice of writing the scaler information AFTER a certain number of blocks of event data prevents scaler information from being written to tape when there are no events. Scaler values are always recorded at the beginning and end of a run, regardless of the value the /SC qualifier. Experimenter's Guide To Daphne Page 74 Scalers 3 October 1990 8.5 Testing Scalers With the exception of the Lecroy 4434, all supported scalers respond to F=25 A=0 by incrementing every channel by 1. 8.6 Testing the Lecroy 4434 The Lecroy 4434 can be tested by using the following sequence which adds 1 to each byte of the 24 bit counters. This is equivalent to adding 65,793 decimal (hexadecimal 010101) to each channel of the scaler. In the example below, the crate controller is connected to terminal port TZC5: and the Lecroy 4434 is in slot 10 of crate 1. The hexadecimal constant "0040" is first loaded into the control register by F=16 to zero all 32 scalers. The hexadecimal constant "80A0" is then loaded into the control register by F=16 in order to set the scaler to test mode and to set it for read-out starting at channel 0. Read-out is performed with an F=0 or F=2 function code. The F=2 increments the channel number in the control register (after read-out) so that successive channels of the scaler can be read-out without loading each channel number into the control register. $ CNAF TZC5: Enter crate, slot, sub address, and function: 1,10,0,16 Data: [nnn dec/Xnnn hex/Onnn octal] x0040 Enter crate, slot, sub address, and function: 1,10,0,16 Data: [nnn dec/Xnnn hex/Onnn octal] x80a0 Enter crate, slot, sub address, and function: 1,10,0,0 Data: 65793 (dec) 010101 (hex) 0000 0001 0000 0001 0000 0001 (bin) Enter crate, slot, sub address, and function: 1,10,0,16 Data: [nnn dec/Xnnn hex/Onnn octal] x80a0 Enter crate, slot, sub address, and function: 1,10,0,0 Data: 131586 (dec) 020202 (hex) 0000 0010 0000 0010 0000 0010 (bin) Enter crate, slot, sub address, and function: 1,10,0,2 Data: 131586 (dec) 020202 (hex) 0000 0010 0000 0010 0000 0010 (bin) Test mode can be cleared by the following sequence: Enter crate, slot, sub address, and function: 1,10,0,16 Data: [nnn dec/Xnnn hex/Onnn octal] x40 Experimenter's Guide To Daphne Page 75 Scalers 3 October 1990 8.7 Counting Above 2**24 (16,777,215) When a Camac scaler overflows at (2**24)-1 it will read the correct count value modulo 16,777,216. The scaler read-out program exploits this fact by keeping count of the number of times a scaler overflows and weighing it as 2**24 counts. The scaler read-out program records scaler values in a 32 bit integer. When it reads a scaler it compares the value with the low order 24 bits recorded the last time the scaler was read. If the value is less than the previous value, the program concludes that the scaler has overflowed, and adds 1 to the the high order 8 bits of the 32 bit integer. In either case, overflow or no-overflow, the low order 24 bits of the 32 bit counter are replaced with the current value read-out from the scaler. Using this technique Daphne can accumulate scaler values up to 2,147,483,647 or (2**31)-1. 8.8 Beware Interaction Between Event Handler and Scaler Process Scaler modules which will be read-out by the scaler process must NOT be cleared by the Event Handler at the start of acquisition unless they are gated by the "Acquisition Active" signal from the NIM Output register or the BUSY signal of the Event Handler. Why ? There is a small window in time between when the scaler process clears a hardware scaler and when the Event Handler INIT routine starts execution, during which the scaler may accumulate some counts if it is not gated by one of two signals mentioned above. If the scaler process reads a non-zero value during this interval, and then later sees a value of zero (due to the Event Handler clearing the scaler) it will mistakenly conclude that the scaler has overflowed and that there has been at least 16,777,216 (2**24) counts. 8.9 Supported Scalers The following scalers are supported by Daphne: Daphne Manufacturer/Model Channels First Module Channel Code Channel Clear Clear -------- ------------------ -------- ------- ------ ------- LRS2550 Lecroy 2550 4 0 N Y LRS2551 Lecroy 2551 12 0 Y N LRS2552 Lecroy 2552 12 0 Y N LRS4434 Lecroy 4434 32 0 Y N KS3610 Kinetic Systems 3610 6 1 N Y KS3615-0 Kinetic Systems 3615 6 0 N Y KS3615-1 Kinetic Systems 3615 6 1 N Y Experimenter's Guide To Daphne Page 76 Scalers 3 October 1990 8.10 Use $SCL/FILE to Define Scalers Scalers are defined in Daphne by using the $SCL/FILE command. Unlike most other Daphne commands, the $SCL/FILE command gets its instructions from a file, rather than the command line. The command line gives the name of a file containing the definitions, rather the the scaler definitions themselves. The default file type for the scaler definitions file is ".SCL". A scaler module is defined by specifying its type and the crate and slot it occupies. A channel within a module is defined by giving its channel number and a symbolic name. There are only four kinds of statements: TYPE module-type CRATE crate-number SLOT slot-number CHANNEL channel-number channel-name Here is an example of a scaler definition file: $ SCL/FILE MYSCALERS Where MYSCALERS.SCL contains: +-------------------------------------------------------+ | type LRS4434 | | crate 1 | | slot 2 | | Channel 0 msc1 | | Channel 1 tel1 | | Channel 2 tel2 | | Channel 3 tel3 | | Channel 4 tel4 | | Channel 5 msc2 | | Channel 6 chan6 | | Channel 7 tof1 | | ! | | Channel 16 nai1 | | Channel 17 nai2 | | Channel 18 nai3 | | Channel 19 nai4 | | Channel 20 nai5 | | Channel 21 nai6 | | Channel 22 nai7 | | ! | | Channel 26 chan26 | | Channel 27 bci_ran | | | | type lrs2550 | | crate 1 | | slot 12 | | channel 0 bci | | channel 1 hardware_coin | | channel 2 timer | | channel 3 software_coin | +-------------------------------------------------------+ Experimenter's Guide To Daphne Page 77 Scalers 3 October 1990 The syntax of the scaler definitions is similar to that of VMS commands: - Names Like other Daphne objects, scalers can have names of up to 12 characters. - Comments Comments begin with the exclamation mark ("!") and continue to the end of the line. A line may consist of just a comment. - Punctuation In definitions which have more than one argument, the arguments can be separated by one or more spaces. The TAB character is equivalent to a space. - Continuation Lines There is no way to continue a statement on another line. - Upper and Lower Case No distinction is made between uppercase and lowercase characters. 8.11 Listing the Scaler Configuration You can get a list of the scaler configuration created by $SCL/FILE, $SCL/MENU, or $SAV/COMMAND with the $SWSC command: $SWSC ! Output on terminal or $SWSC /OUPUT=MY_SCALERS ! Output to file MY_SCALERS.SCL The output is a text file suitable for input to the $SCL/FILE program. 8.12 Changing Scaler Definitions You can change or delete scaler definitions only when acquisition is not active. To change the definitions, modify your scaler definition file and reissue the $SCL/FILE command. To disable scalers altogether, use the null file as input to the $SCL/FILE command: $ SCL/FILE NL: Experimenter's Guide To Daphne Page 78 Scalers 3 October 1990 8.13 Displaying Scaler Values The $DSV command will display and update the values of scalers on the command terminal. The rate at which $DSV updates information on the command terminal is independent of the rate at which the hardware scalers are read-out. The $PTSV will print the values of scalers, along with identifying information and a timestamp, on the default system printer. If you want to save scaler values in a file you can use the "/OUTPUT" qualifier of the $PTSV command. For instance, the following command can be included in a command file used at the end of each run: $ PTSV /OUTPUT=SCALER_DATA.DAT The first time the $PTSV program will create the output file "SCALER_DATA.DAT". At the end of subsequent runs the new scaler values will be appended to the file. +---------------------------------------------------------------+ | Date: 27-JAN-88 14:19:05 | | Physicist: TAMU_LEGNARO_HOPE Target: 100MO | | Beam: 60NI Energy: 645 | | Comments: TESTING | | | | C N A TITLE COUNT | | 1 3 0 MASTER_LIVE 3,224,243 | | 1 3 1 MASTER_TOTAL 0 | | 1 3 2 BEAM_LIVE 0 | | 1 3 3 BEAM_TOTAL 0 | | 1 3 4 RES_NEU 642,502 | | 1 3 5 RES_LP 267,633 | | 1 3 6 PLF_NEU 0 | | 1 3 7 PLF_LP 35,656 | | 1 3 8 PLF_FF 913,497 | | 1 3 9 FF_NEU 534 | | 1 3 10 FF_LP 113,082 | | 1 3 11 LP_NEU 0 | | 1 3 12 RES_GAMMA 779,829 | | 1 3 13 PLF_GAMMA 13,637 | | 1 3 14 FF_GAMMA 43,312 | | 1 3 15 LP_M>2 0 | +---------------------------------------------------------------+ Experimenter's Guide To Daphne Page 79 Diagram of Daphne Hardware 3 October 1990 +-------------------------+ +-------------------------+ | Primary Camac Crate | | Secondary Camac Crate | +-------------------------+ +-------------------------+ | Auxiliary Controller #1 | +----->| Auliliary Controller #2 | + - - - - - - - - - - - - + | +-------------------------+ | Event Handler |<-----+ +-------------------------+ V +------------------------------+ | 256 word by 24 bit FIFO | +------------------------------+ V +------------------------------+ | Word Parallel Cable Driver | +------------------------------+ V +------------------------------+ | Word Parallel Cable Receiver | +------------------------------+ V +------------------------------+ | Multiplexor | +- EMUX - - - - - - - - - - - + | Event Distributor | +------------------------------+ Daisy-Chained | via Twisted Pair Cable +------------------------------------------------------ ^ ^ ^ | | | V V V +-------+ +-------+ +-------+ | FIFO | | FIFO | | FIFO | +- - - -+ +- - - -+ +- - - -+ o o o o o | EP #1 | | EP #2 | | EP #3 | +-------+ +-------+ +-------+ ^ ^ ^ | | | V V V Multibus I +-------------------------------------------------------- | +-------------------------------+ | Multibus/Unibus Interface | +-------------------------------+ V +-------------------------------+ | Interface for VAX Unibus | +-------------------------------+ | | Approximately 250 kWords/second (500 kBytes/second) V +-------------------------------+ | VAX | +-------------------------------+ Experimenter's Guide To Daphne Page 80 Diagram of Daphne Camac Hardware 3 October 1990 +----------------------+ | VAX RS-232 Interface | Optional Second Camac Crate | Control Information | | Very Low Data Rates | +----------------------+ +-------------------------------------------+ ^ | RS-232 Crate Controller #2 | | | Daisy-Chain Connection to Crate #1 |<---------->| +-------+-----------------------------------+ | Other Kinetic ^ | User Camac Modules | | Systems 3989 | +-----------------------------------+ | Camac Crates V | User Camac Modules | |<------------> +-------+-----------------------------------+ | | Auxiliary Crate Controller #2 |<------+ | +-------------------------------------------+ | | | | Other Kinetic +------------------------------------------------+ | Systems 3989 | | Camac Crates | Required Primary Camac Crate |<------------> | | | +-----------------------------------------+ | | | RS-232 Crate Controller #1 | | | | Kinetic Systems Model 3989 |<---->| | | Up to 19.2 Kbaud | | +-----+-----------------------------------+ | ^ | Word Parallel Cable Driver |>-------+ | | | Differentially Driven Signals | | | | | R.T. Daly - Argonne Electronics |<--+ | | | +-----------------------------------+ | | | | | 256 Word by 24 Bit FIFO Buffer |---+ | | | | Kinetic Systems Model 3841 | | | V | |<--+ | | +-----+-----------------------------------+ | | | | Auxiliary Crate Controller #1 |---+ | | | D.C. Hensley - Oak Ridge Nat'l Lab | | | | |<--+ | | +- - - - - - - - - - - - - - - - - - - - -+ | | | | Event Handler |<--+ | +--->| Special Purpose Computer) | | | D.C. Hensley - Oak Ridge Nat'l Lab |<--+ | +-----------------------------------------+ | | | Camac Output Register - NIM or TTL |---+ | | Several Vendors | | +-----------------------------------------+ | | User Camac Modules | | +-----------------------------------------+ | | User Camac Modules | | +-----------------------------------------+ | | In Computer Room | +---------------------------------+ | | Word Parallel Cable Receiver |<---+ | Differentially Driven Signals | | R.T. Daly - Argonne Electronics | +---------------------------------+ Experimenter's Guide To Daphne Page 81 Event Handler - Overview 3 October 1990 9 Event Handler - Overview NOTE It is possible to use two Event Handlers in a master/slave arrangement to control up to four Camac crates. See "Related Documentation" (Section 4.1). Let's assume that the experimenter has already started acquisition. What happens to the data when an event occurs ? 9.1 An Event is Detected The EH program is normally in a tight loop waiting for the latch controlled by the EVENT front panel inputs to change from "0" to "1". There are actually two EVENT inputs, one TTL and one NIM. When either undergoes a transition from "0" to "1", the EVENT latch is set. When using multiple event types, the EVENT input should be the set to "1" by user electronics when an event of any type is detected. Please examine the diagram on the following page. Experimenter's Guide To Daphne Page 82 Event Handler - Overview 3 October 1990 +----------+ +------------+ | Lecroy | | Bi Ra | | 429A | | 2351 | | Quad | | NIM | | Mixed | | Input | | Logic | | Register | | Fan-In | | | | Fan-Out | | | | | | | | 2 x 8 | | | | | | | | IN | Event Type 0 Trigger (NIM) | | | o <----------- O --------------------------------> o Bit 1 | | | | | | IN | Event Type 1 Trigger (NIM) | | | o <----------- O --------------------------------> o Bit 2 | | | | | | IN | Event Type 2 Trigger (NIM) | | | o <----------- O --------------------------------> o Bit 3 | | | | | | IN | Event Type 3 Trigger (NIM) | | | o <----------- O --------------------------------> o Bit 4 | | | | | | IN | Event Type 4 Trigger (NIM) | | | o <----------- O --------------------------------> o Bit 5 | | | | | | | | | | | | | o o o o o o | | | OUT | | o Bit 12 | | o -------------+ | | +----------+ | +------------+ | | | | | +-------> o Event Handler NIM Event Input Fan-In of Event Signal When Using Multiple Event Types Experimenter's Guide To Daphne Page 83 Event Handler - Overview 3 October 1990 9.2 New Events are Inhibited When the EVENT latch is set, the BUSY output latch is set automatically by hardware. The BUSY output is asserted the entire time the EH is reading-out an event. It is reset by the EH program to indicate that it is ready to process another event. The BUSY signal should be used to gate triggers for all other devices which should be disabled during read-out. The EH is unable to set the crate INHIBIT line and thereby stop certain devices, such as scalers, from operating. The KS/CC can be programmed by the host to set the crate INHIBIT line, but the EH is unable to request the crate controller to perform the same operation. One module, aside from the crate controller, that can be programmed to set the crate INHIBIT line is the Kinetic Systems 3655 Timing Pulse Generator. This module can be of use when acquisition is to be halted under hardware control when software delays on the order of a tenth of a second are unacceptable. 9.3 Steps in an Event Handler Program When the EH program senses the occurrence of an event by the EVENT latch being set, it performs the four operations described below. 9.3.1 Check for Space in FIFO Transfer of data from the EH to the rest of the data acquisition system is buffered by a Kinetic Systems Model 3841 FIFO (KS/FIFO). It is 256 words deep and 24 bits wide. Before reading out an event, the EH program makes sure that there is sufficient room in the FIFO by checking a status bit. Normally, it is necessary to check the FIFO status bit only at the beginning of an event. If there is insufficient space, the EH program goes into a tight loop, waiting for the FIFO to partially empty. This is not the responsibility of the user's Event Handler program: these operations are performed by an Event Handler routine supplied by the Daphne developers. Experimenter's Guide To Daphne Page 84 Event Handler - Overview 3 October 1990 9.3.2 Determine Event Type An Event Handler program which handles multiple event types will start the processing of an event by trying to determine the type of the event. This is essential, since each event type can cause the read-out of entirely different devices. A common method of indicating the event type is to use one bit of a pattern register for each event type. With the Bi Ra Model 2351 NIM Input Register up to 12 event types can be supported. Daphne will handle up to 16 event types. The event type code, a number between 0 and 15, is written to the FIFO as the first word of an event. The concept of multiple event types is discussed in the section describing the $EVS command. (Section 6.13) 9.3.3 Execute EH Subroutine and Write Data to FIFO The Event Handler subroutine written by a user usually consists of a series of Camac CNAF operations followed by OUT instructions which transfer the EH accumulator to the FIFO. Occasionally, a user-written EH subroutine contains compare instructions and tests bits to determine what operations to perform. To separate the end of one set of event data from the begining of the next set, a Daphne supplied part of the EH program writes a value to the FIFO which can be distinguished from the usual event data. Normal event data is output by using the "OUT CA1" or "OUT CA2" instructions, which leaves a certain bit of the FIFO word set. The end-of-event marker generated by the "OUT constant" instruction leaves this special bit clear. Thus, should an EH program need to write a constant to the FIFO as part of the normal event data stream, it uses two instructions: "MOV constant,CA" followed by "OUT CA". 9.3.4 Clear BUSY The last step is to clear the BUSY latch. As mentioned above (Section 9.2) the state of the BUSY latch is available as a front panel output for use in enabling and disabling triggers. The BUSY latch is cleared by code supplied by the Daphne developers. Experimenter's Guide To Daphne Page 85 Event Handler Auxiliary Controller 3 October 1990 10 Event Handler Auxiliary Controller The Event Handler talks to a Camac crate through a closely related module, an auxiliary crate controller, known as the AUX. So close is the relationship between the AUX and the Event Handler that the two units are now available as a single double-width module. The AUX is connected to the Kinetic Systems 3989 crate controller through a ribbon cable from the rear of the AUX to the rear of the crate controller. A second lemo cable connects the AUX front panel input GRANT IN to the front panel GRANT OUT signal generated by the crate controller. When an experiment requires read-out of Camac hardware in two crates, another AUX is placed in the second crate, and daisy-chained to the first AUX and Event Handler. There are jumpers on the AUX circuit board which are used to configure it as a crate 1 AUX or a crate 2 AUX. The second AUX must be connected to its crate controller in the same manner as the first AUX is connected to its crate controller. The Event Handler does not itself execute Camac function codes, nor respond to Camac operations. For instance, when downloading a program into the Event Handler the CNAF codes contain the slot number of the AUX controller, not that of the Event Handler. It is worth noting, as a curiosity, that if two AUX units are in use, the Event Handler program can be downloaded through either one. Experimenter's Guide To Daphne Page 86 Kinetic Systems Model 3841 FIFO 3 October 1990 11 Kinetic Systems Model 3841 FIFO The KS/FIFO, a 256 word deep, 24 bit wide FIFO is intended to partly compensate for irregularites in the rate at which data is transferred to other parts of the acquisition system. The KS/FIFO is a 1 MHz FIFO (nominal) capable of accepting one word of data every 1.5 to 2.0 uSec. As the EH has a cycle time of 500 nSec, it is possible for the EH to supply data to the FIFO faster than the FIFO can accept it even when the FIFO is far from being full. As a consequence, two consecutive OUT instructions should always be separated by a NOP or other instructions. Each Event Processor has attached to its printed circuit board a FIFO, independent of the KS/FIFO, which is 256 words deep and 16 bits wide. When event rates approach or exceed what can be handled by Daphne, the data tends to be removed from the KS/FIFO in units of 128 words because of the way the Event Processor on-board FIFO is filled. The EH was originally designed to work closely with a FIFO such as the Kinetic Systems 3841. For instance, part of the EH design called for the Event Handler CPU to stall during execution of any instruction which transferred data to the FIFO if the status line indicated that the FIFO was full. The EH and FIFO exchange data and status information through a connector on the front of each unit. The most important status information exchanged by the two units are Data Present, Data Accepted, and the bits which indicate whether the FIFO is empty, 1/4, 1/2, 3/4, or totally full. Unfortunately, there is a synchronization problem which can cause data to be lost occasionally when the FIFO is full. For this reason, Event Handler programs use the FIFO 3/4 full status bit to control event read-out and prevent the FIFO from becoming totally full, thus revealing this synchronization problem. Experimenter's Guide To Daphne Page 87 Cable Driver 3 October 1990 12 Cable Driver The Cable Driver and Cable Receiver allow the Camac equipment used by an experimenter to be located several hundred feet from the computer room where the Event Distributor, Event Processors, and host are located. The Cable Driver and Cable Receiver are matched units which transfer data from the Camac system in word parallel fashion over a differentially driven, optically isolated, flat cable, with 25 twisted pairs. Experiments have been performed in which the experimental station was 100 meters from the computer room. The Cable Driver is connected to the Kinetic Systems FIFO by a front panel connector. The Cable Driver was designed by R. T. Daly of the Argonne Electronics Division. 13 Cable Receiver The Cable Receiver converts the differentially driven signals produced by the Cable Driver to TTL signals needed by the Event Distributor. A number of Cable Receivers, each connected to the Cable Driver of a different experimental station, can be located in the crate with the Event Distributor. The experimenter selects the Cable Receiver (and its corresponding experimental station) by using front panel switches on the Event Distributor. The crate in which the Cable Receivers and Event Distributor are housed is a Camac crate, but the modules do not use Camac conventions for communicating: the crate provides only power and bus lines for these units. The Cable Receiver was designed by R. T. Daly of the Argonne Electronics Division. Experimenter's Guide To Daphne Page 88 Event Distributor (EMUX) 3 October 1990 14 Event Distributor (EMUX) The Event Distributor, also known as the EMUX, sits in the position of a Camac crate controller, on the right side of the crate containing the Cable Receivers. The EMUX is actually a dual unit containing two essentially identical modules. The unit in the top half is called the PRIMARY unit and the bottom unit is called the SECONDARY unit. Two experiments can be run simultaneously, with the Primary unit talking to one Cable Receiver, while the Secondary unit talks to a separate Cable Receiver. There is no conflict when the units request data at the same time: requests from the Primary unit use the Camac READ lines while the Secondary unit uses the Camac WRITE lines. If the same station is selected by both units the result are unpredictable. The EMUX performs three major functions. 14.1 Selection of Experiment Station The Camac crate in which the EMUX sits can contain up to 22 Cable Receivers. Each Cable Receiver can be connected to a separate experimental station. The experimenter connects an experiment to the EMUX by encoding the slot number (actually the slot number minus 1) of the corresponding Cable Receiver as a binary number, using the 5 switches on the front of the EMUX. There is a separate set of switches for the Primary and Secondary EMUX. When the EMUX is ready to process more data from an experiment, it executes a dataway cycle addressed to the Cable Receiver in the selected slot, and receives the next word of data, if it is available. 14.2 Selection of an Empty FIFO The EMUX is connected to the on-board FIFO of one or more Event Processors in a daisy-chain by a flat cable of 25 twisted pairs. When the EMUX has received data from the cable receiver, it checks the on-board FIFO of each of the microprocessors connected to it in round-robin fashion. When a polled FIFO does not respond, or responds with a status of NOT EMPTY, the EMUX selects the next FIFO in rotation. If the FIFO responds with a status of EMPTY, the EMUX starts to transfer data to it. Experimenter's Guide To Daphne Page 89 Event Distributor (EMUX) 3 October 1990 14.3 Determination of the End-of-Event It is important for the EMUX to be able to determine when the data from one event ends and the next event starts. Otherwise, the first part of an event might be sent to one EP while the remainder is routed to a second EP, making analysis impossible. The data from the experimental station consists of experimental data and end-of-event markers. The end-of-event markers always have bit 24 (counting from 1) clear, while experimental data always has this bit set. The EMUX contains a 10 bit counter which counts the number of words between the end-of-event markers and substitutes the word count for the low order 10 bits of the end-of-event marker. Thus, the EMUX produces a "trailing" word count for each event, while not changing the number of words in the data stream. The trailing word count is placed in the on-board FIFO instead of the end-of-event word. As each word is transferred to the on-board FIFO, the EMUX checks to see if more than 128 words have been placed in the FIFO. Once the FIFO has reached the 128 word mark the EMUX will stop filling the FIFO at the next end-of-event marker, and begin looking for another non-empty FIFO. A special case is events with lengths from 128 to 1023 words, since these can cause the FIFO to be filled without the end-of-event marker having been detected. In this case, the on-board FIFO is filled up and the FULL status bit is set without the DONE bit being set. The EP empties the FIFO into a buffer and waits for the EMUX to fill up the on-board FIFO again. This is repeated until an end-of-event marker is encountered, which causes the DONE bit to be set. When processing events which require the on-board FIFO to be emptied several times, the EMUX stalls while waiting for the Event Processor to empty the FIFO. This is not a long time, though, since processing of the data by the EP does not occur until the entire event is read in. The Event Distributor and on-board FIFO were designed by R. T. Daly of the Argonne Electronics Division. Experimenter's Guide To Daphne Page 90 Event Processor - Overview 3 October 1990 15 Event Processor - Overview 15.1 Event Processor Hardware - Overview Event Processors are DB32016 development boards manufactured by National Semiconductor Corporation. The DB32016 boards are housed in a Multibus I ("I" is a Roman numeral) crate, developed by the Intel Corporation and now an IEEE standard. Multibus I has a 24 bit wide address capable of addressing 16 MBytes, and a 16 bit wide data path. The DB32016 boards are single width boards, but because of the on-board FIFO boards that sit piggy-back on them, they must be placed two slots apart. The number of Event Processors which can fit on the Multibus is limited by crate space to about 7 units. Each board contains 128 kBytes of RAM, all of which is dual ported: it can be accessed by the on-board processor without any Multibus cycles or by an I/O device (or another processor) over the Multibus. NOTE There are plans to upgrade the boards to 512 kBytes 15.2 Event Procesor Software - Overview The Event Processor reads data from the on-board FIFO, analyses it according to the experimenter's instructions, and transfers the data to the host for further analyses, display, or recording on tape. Except when acquisition is being stopped, the Event Processor receives a minimum of 128 words as a consequence of the way the EMUX and FIFO are designed. As the events have a trailing word count, the EP program works its way from the last event filled into the FIFO towards the first event in the buffer in reverse chronological order. For each event the EP calls a user supplied transformation, if one has been provided. The user-supplied routine may create pseudo-parameters in a separate area of memory, or overwrite existing parameters. The user-function may SHORTEN the event by rewriting the argument which contains the number of words in the event. The user-function may NOT EXTEND the event with additional parameters because this will over-write events which follow the modified event in the buffer. The EP program then performs the standard Daphne functions on data in the original event and on pseudo-parameters created by the user-specified transformation. Experimenter's Guide To Daphne Page 91 Event Processor - Overview 3 October 1990 The results of performing the standard Daphne functions are of four types. 15.3 Raw Data If the user has requested that the data be recorded on tape, then the event is appended to a "tape buffer". When the tape buffer is full, it is transmitted to the host and recorded on tape. The tape buffer is, by default, set to its maximum size of about 12 kBytes. The minimum size is 512 bytes. Using large block sizes reduces I/O overhead on the host and increases the amount of data which can fit on a reel of tape by reducing the number of inter-record gaps. Using smaller buffers does NOT increase the amount of space available for other purposes because the size and allocation of the buffers are controlled by parameters determined when the main Event Processor program is compiled. About 135 megabytes can fit on a 2400 foot tape reel at 6250 bpi when using blocks of 12 kBytes. 15.4 Histogram Data When the sorting program executing on an Event Processor needs to add one to a certain bin of a 1D or 2D histogram, it combines the bin number with the base address of the histogram in the VAX memory to calculate the absolute address of the histogram bin. It uses the computed address to generate a VAX INC instruction which will add 1 to the specified address. Depending on whether the bin size is 8 bits (a byte), 16 bits (a word), or 32 bits (a longword), the EP program will generate an INCB, and INCW, or an INCL instruction, respectively. Each INC instruction is 6 bytes long. The INC instruction generated is appended to an INC buffer in the Event Processor. When the INC buffer is nearly full, a VAX RET instruction is appended to the buffer, and it is transmitted to the VAX where the INC instructions are executed. Experimenter's Guide To Daphne Page 92 Event Processor - Overview 3 October 1990 15.5 Software Scalers and Conditions Conditions are the method Daphne provides for disabling sorting into a histogram on an event by event basis. Examples of conditions include: - One Dimensional Windows Is parameter 1 between 1230 and 1257 ? - Bit Tests Does parameter 2 must have one of bits 1, 2, or 3 set ? - Two Dimensional Windows Are parameters 3 and 4 when considered as points in X/Y space inside a polygon with vertices at coordinates ... Daphne programs automatically count the number of times each condition is true. The experimenter can get a summary of these software scalers by using the $CNT command. The condition counts, as they are called, are kept in Event Processor memory until the host asks for an update as part of its polling sequence. 15.6 Scatterplot Data Scatterplots are designed to allow an experimenter to display one parameter against another parameter as a two dimensional graph with a minimum of inconvenience. Scatterplot points are gathered on a single Event Processor and forwarded to the VAX at one second intervals. For more information on scatterplots see section 33. Experimenter's Guide To Daphne Page 93 Event Processor - Overview 3 October 1990 15.7 Event Processor Polling During acquisition the host polls one Event Processor per second for information, such as condition counts, as part of its monitoring of Event Processor operation. The Event Processor program decides to send a partially full INC buffer when it is polled, and it realizes that no INC buffer has been sent since the last time it was polled. Thus, even at low data rates, the host receives some new information about once per second. Partially full INC buffers are transmitted to the host when data rates are low in order that the user receive timely information: otherwise, it might take minutes or hours to fill up a 12 kByte buffer and to receive the first bit of data. Partially full INC buffers will also be transmitted when acquisition is stopped. Raw data buffers, unlike INC buffers, are transmitted only when filled or when acquisition is stopped. Experimenter's Guide To Daphne Page 94 Camac Output Register 3 October 1990 16 Camac Output Register A Jorway Model 41 twelve bit NIM output register is used to communicate to the Event Handler (and the user's trigger electronics) information about the state of the run: started, stopped, paused, beginning, etc. A diagram showing the time and logic relationship among these signals and the Event Handler EVENT and BUSY signals is in section 21 ("Interfacing the Event Handler"). 16.1 NIM Level for Acquisition Start/Stop - Bits 1, 2, and 3 The low order bit (bit 1) of the output register is connected to front panel input 8 of the Event Handler. When idle, the Event Handler waits for front panel input 8 to go to "1". Once acquisition starts, the Event Handler alternately checks to see if input 8 has gone to "0" or there is a new event. Bits 2 and 3 mimic bit 1, but are available to the user for controlling equipment. Since bita 2 and 3 are "1" only during acquisition, the experimenter can use them to measure elapsed time ("wall-clock" time) of a run or experiment. When used in combination with the Event Handler BUSY signal, one can measure the dead-time. 16.2 NIM Pulse at Acquisition Start - Bit 4 Bit 4 is pulsed for approximately 1 uSec at the beginning of acquisition by the Event Handler program. This is intended to provide a convenient signal for the user to clear NIM scalers at the start of acquisition. Experimenter's Guide To Daphne Page 95 Camac Output Register 3 October 1990 16.3 NIM Level for Pause/Resume - Bit 5 There are plans to use Bit 5 to implement a hardware based "pause" and "resume" capability. The reason it must be hardware based is that it must disable not only the Event Handler, but also the scalers which are used to measure acquisition dead-time. 16.4 Available to User - Bits 6 through 12 Bits 6 through 12 are not used by any standard Daphne programs. An experimenter could use these to control some of his electronics. For instance, bit 12 could be fed to a Lecroy 622 Quad Coincidence unit to disable certain sources of events. 16.5 Programming Note When a user programs the Jorway Model 41 output register he must remember not to change the state of bits 1 through 5. This means: - Do NOT Use F=16 or F=17 This will change the state of ALL bits in the register including those which control the Event Handler - Do Use F=20 to Set Specific Bits The bits in the data word determine which bits are to be SET. Bits which are zero in the data word are unaffected. - Do Use F=22 to Clear Specific Bits The bits in the data word determine which bits are to be CLEARED. Bits which are zero in the data word are unaffected. The output register powers up with all bits set to "0". Another method of providing pulses to user electronics, either NIM or TTL is to use the Event Handler front panel outputs. See section 21.5 ("Using the Event Handler Front Panel Outputs"). Experimenter's Guide To Daphne Page 96 Use $TAPE/OUT to Ready Tape for Recording 3 October 1990 17 Use $TAPE/OUT to Ready Tape for Recording The $TAPE/OUT command specifies the tape drive, block size, recording density (800, 1600, or 6250 bpi) and frequency of scaler data recording. In examples given below, the tape drive name is given as a physical device name with NO colon. The manner in which the Daphne $TAPE commands are programmed discourages the use of logical device names and requires that the physical device names be given without colons. A typical $TAPE/OUT command to initialize a tape and ready it for recording is: $ TAPE/OUT MFA0/DENS=6250/REC=13000 17.1 Use of Two Tape Drives If you specify a second tape drive in the $TAPE/OUT command, the tape output process will automatically switch from one drive to the other when it reaches the end of the tape volume: $ TAPE/OUT/DENS=6250/REC=1300 MFA0,MFA1 17.2 Positioning Tape to end-of-volume You can put data from a new run at the end of an existing Daphne data tape, if you wish. However, you cannot mix data from a Daphne run with tapes in any other formats: for example, the ANSI standard labels used by VAX/VMS or the VAX/VMS Backup utility. To put data from a new run at the end of an already used Daphne data tape, use the /APPEND qualifier: $ TAPE/OUT/APPEND MFA0/REC=13000 17.3 Block Size The /REC qualifier specifies, in bytes, the largest block size that can be used for recording data. The default value for the /REC qualifier is the largest block size which can be generated by the Event Processors: about 13 kBytes. The minimum allowed value for the /REC qualifier is 512 bytes. With a larger block size, more data can fit on a tape. Using blocks of about 13 kBytes allows about 135 megabytes to fit on a 2400 foot tape at 6250 bpi. With a block size of 512 bytes recorded on the same tape at the same density, only about 30 megabytes can be recorded. Experimenter's Guide To Daphne Page 97 Use $TAPE/OUT to Ready Tape for Recording 3 October 1990 17.4 Recording Density The default density depends on the installation and the density of the tape which has been loaded. It is recommended that one specify the recording density. 17.5 Recording Scaler Values When event mode recording is enabled, and scalers have been defined, the current values of the scalers are always written to tape at the beginning and end of the run. The /SC qualifier controls how often scaler information is written to tape during the run, assuming there is new scaler information since the last time scalers were written to tape. The frequency with which scalers are read-out is controlled by the /DELAY qualifer of the $CDV command. For instance, the following command writes out the scaler information after every 10 blocks of event data: $ TAPE/OUT/SC=10 MFA1/DENS=1600/REC=8190 By default, scaler information is written to tape after every fifth block of event data. Because of the number of qualifiers in the $TAPE/OUT command, it is convenient to place the command in a command file, even though it is a single command. Experimenter's Guide To Daphne Page 98 Use $KLT When Changing Tapes 3 October 1990 18 Use $KLT When Changing Tapes When recording begins on a new tape, the tape must be initialized. When using two tapes, the tape output process will switch to the next drive when it reaches the end of the tape on one tape drive. Under these circumstances, the tape output program knows that a new tape has started and initializes the tape without any additional commands from the user. However, if one is using a single tape drive and stops the run before the end of the tape, it is important not to rewind and mount a new tape. If you do this, the tape output program will not be aware of the change of tapes and will not initialize the new tape. The proper way to change tapes after stopping a run before the end of a tape is to issue the "kill tape" command, and then issue a new $TAPE/OUT command: $ KLT $ TAPE/OUT ... ! your favorite $TAPE/OUT command Experimenter's Guide To Daphne Page 99 Overview of a Daphne Event Handler Program 3 October 1990 19 Overview of a Daphne Event Handler Program An Event Handler program consists of two user-written subroutines together with a standard section of code provided by the Daphne system. A simple, but complete, example appears on the next page. The machine instructions and assembly language format are explained in the next section. The device initialization subroutine begins with the label "INIT", and ends with the subroutine return instruction "BRUR" (Branch Unconditional Return !). The MAIN event handler routine begins with the label "MAIN", and ends with the subroutine return instruction "BRUR". The user-written routines may NOT contain subroutine calls because the subroutine stack is only one level deep. The Camac LAM (Look-At-Me) is not used by Event Handler programs. The LAM is useful in conventional computer systems because it causes an interrupt of background processing, such as analysis, to handle an event. After servicing the request, the program returns to the previous activity. The Event Handler, in contrast, spends all its time between events just waiting for the EVENT signal, making interrupts unnecessary. Users who are accustomed to using LAM to wait for Camac modules to complete an operation can use two strategies: - Use Q Response Execute a Camac control code which reports the state of a module's LAM through the Q bit. The Event Handler records the Q response of each Camac operation in the EX register, which can be then be tested by Event Handler instructions. The symbolic name "QBIT" is defined in the include file "DAPEH:STANDARD.EHA" for the bit in the EX registers, which records the Q response from the previous Camac operation. WAITLAM IF (EX1 .NONE. QBIT) WAITLAM ;Wait for LAM request Experimenter's Guide To Daphne Page 100 Overview of a Daphne Event Handler Program 3 October 1990 - Assume Worst Case Timing Suppose you have a module which may take anywhere from 60 to 80 uSec to finish an operation triggered by an event. You can insert a programmed delay of 80 uSec at the beginning of the event read-out routine routine. DLAY 80*10 ;Delay 80.0 uSec in 100 nSec units The normal method of preparing an Event Handler program is to use your favorite editor to modify an existing Daphne Event Handler program. A number of examples are kept in the DAPEH: directory. Event Handler programs should always have a file type of ".EHA". Do not use diagnostic programs as examples. You might also look at some examples which are in a separate document. See Section 4.1 ("Related Documentation") for information on how to obtain a copy. The following is a complete Daphne Event Handler program to read-out channels 0 and 1 of an Ortec 811 ADC in slot 5 of crate 1. Lines preceded by a letter at the left side of the box are are those which are necessary in any Daphne Event Handler program. Their purpose is explained below. +---------------------------------------------------------------+ a | bru start ;branch to START stuff | | | | adcSlot=5 ;symbolic name for ADC slot| | | | ; | | ; INITIALIAZATION ROUTINE | | ; CALLED AT ACQUISITION START | | ; | | | b | init cnaf 1,adcSlot,7,2 ;reset ADC | c | brur ;return to caller | | | | ; | | ; EVENT ROUTINE | | ; CALLED WHEN AN EVENT IS DETECTED | | ; | | | d | main dlay 100*10 ;wait 100.0 uSec in | | ; 100 nSec units | | cnaf 1,adcSlot,0,0 ;read channel 0 | | out ca1 ;output to Event Processor | | ; as parameter 1 of event | | cnaf 1,adcSlot,1,0 ;read channel 1 | | out ca1 ;output to Event Processor | | ; as parameter 2 of event | | cnaf 1,adcSlot,7,2 ;reset the ADC to ready it | | ; for the next event | e | brur ;return to caller | | | f | include dapeh:standard ;standard stuff | +---------------------------------------------------------------+ Experimenter's Guide To Daphne Page 101 Overview of a Daphne Event Handler Program 3 October 1990 a. The program must start by branching over user routines to Daphne code which handles acquisition start and stop. b. Label INIT marks the beginning of a required user routine that is called at acquisition start to initialize a user's Camac modules. c. The "BRUR" is a subroutine return instruction which terminates the user-supplied Camac initialization routine. d. Label MAIN marks the beginning of a required user routine that is called when an event is detected to read-out and reset a user's Camac modules. e. The "BRUR" is a subroutine return instruction which terminates the user-supplied MAIN routine. f. The INCLUDE statement is required to merge the standard Daphne Event Handler code, which handles acquisition start and stop, with the user-supplied routines. Experimenter's Guide To Daphne Page 102 "Silver" Event Handler Front Panel 3 October 1990 +------------------------------+ | E V E N T | | H A N D L E R | | | | * ON | | | | Reset LOCK | | Button 2-Way Switch | | | | Inputs +------------+ | ------------ | AUXILIARY | | o 1 o 2 | CRATE | | TTL TTL | CONTROLLER | | | | | o 3 o 4 | Req Dataway| | TTL TTL | o | | | | | o 5 o 6 | Grant IN | | TTL TTL | o | | | | | o 7 o 8 | Grant OUT | | NIM NIM | o | | +-+ | | * BUSY | * 1 | | * STOP | * 2 | | * WAIT | | | * NAF | * NAF | | * OUT | * N | | * NO Q | * NO Q | | +--------------+ | | | o Event o Event | | TTL NIM | | | | o Int o Hold +--+ | | (not (not | | | | used) used) | | | | | | | | o Busy | | | | TTL | | | | o Busy o Busy | | | | NIM NIM | | | | | | | | --- Outputs --- | | | | o 1 o 2 | | | | TTL TTL | | | | | | | | o 3 o 4 | | | | TTL TTL | | | | | | | | o 5 o 6 | | | | TTL TTL | | | | | | | | o 7 o 8 +--+ | | NIM NIM | +------------------------------+ "Silver" Event Handler with built-in Auxiliary Controller Experimenter's Guide To Daphne Page 103 "Black" Event Handler Front Panel 3 October 1990 +------------------------------+ +------------------------------+ | E V E N T H A N D L E R | | A U X C O N T R O L | | DC99-1 | | CTR29-1 | | | | | | Reset MASTER | | | | Button 2-Way Switch | | | | | | | | ------- TTL Inputs ------- | | * 1st | | | | * 2nd | | o 1 o 2 o 3 | | | | TTL TTL TTL | | | | | | | | o 4 o 5 o 6 | | | | TTL TTL TTL | | * N | | | | * NAF | | ------- NIM Inputs ------- | | * NO-Q | | | | | | o 7 o 8 | | | | NIM NIM | | | | | | Request | | * BUSY | | o | | * STOP | | | | * WAIT | | | | * NAF | | Grant | | * OUT | | o In | | * NO Q | | o Out | | | | | | o Event o Event | | | | TTL NIM | | | | | | Data Out | | o Int o Hold | | | | (not (not | | +--+ | | used) used) | | | | | | | | | | | | o Busy | | | | | | TTL | | | | | | o Busy o Busy | | | | | | NIM NIM | | | | | | | | | | | | o +5V | | | | | | (not used) | | | | | | | | | | | | 50 OHM Out | | | | | | ------- TTL Outputs -------- | | | | | | | | | | | | o 1 o 2 o 3 | | | | | | TTL TTL TTL | | | | | | | | | | | | o 4 o 5 o 6 | | | | | | TTL TTL TTL | | | | | | | | | | | | ------ NIM Outputs ------ | | +--+ | | | | | | o 7 o 8 | | | | NIM NIM | | | +------------------------------+ +------------------------------+ "Black" Event Handler "Black" Auxiliary Controller Experimenter's Guide To Daphne Page 104 Programming the Event Handler 3 October 1990 20 Programming the Event Handler The Event Handler is a simple computer designed by D. C. Hensley. It has only a few registers and a few operations. It is so simple that, aside from a few special purpose registers, it has no data memory. Present models cannot do arithmetic, but they are capable of testing bits, making comparisions, and changing program flow based on the results of these tests. The program memory can hold 2048 instructions. 20.1 Two Models of Event Handler There are two versions of the Event Handler and AUX in use at Argonne. The older versions are double width modules with a flat black front panel, built using wirewraps to connect pins. The newer version is a single or double width module with a silver front panel, built using Multiwire to connect pins. The silver, double-width modules contain both an Event Handler and AUX in a single module. Diagrams of the front panels of the two models are on the two pages immediately preceding this page. There are a few specialized instructions which operate on the new Event Handlers, but do not operate on the old Event Handler. Such instructions are flagged by the assembler. 20.2 CA Registers All I/O to Camac is done through the 24 bit CA (Crate Accumulator) register. There are actually two CA registers: the CA1 register for I/O to the first Camac crate and a CA2 register for doing operations to a second crate. When Event Handler instructions are discussed, the symbol "CAX" is used where either CA1 or CA2 may appear. Aside from input and output, operations on the CA registers are limited to bit tests and arithmetic comparisons on the low order 16 bits. The mnemonics UCA1 and UCA2 refer to the upper 8 bits of the 24 bit CA1 and CA2 registers. Experimenter's Guide To Daphne Page 105 Event Handler - EX Input Register 3 October 1990 20.3 EX Input Registers There are two 16 bit EX input registers, EX1 and EX2, one for each crate. Some information, such as the state of the front panel inputs, are reported in both EX registers, while other information, such as the Q response generated by Camac operations, will be crate specific, and therefore EX register specific. Operations on the EX registers are limited to the testing of bits. Assignment of bits in the EX registers: - Bit 1 Front panel input [1] - TTL - Bit 2 Front panel input [2] - TTL - Bit 3 Front panel input [3] - TTL - Bit 4 Front panel input [4] - TTL - Bit 5 Front panel input [5] - TTL - Bit 6 Front panel input [6] - TTL - Bit 7 Front panel input [7] - NIM - Bit 8 Front panel input [8] - NIM (Reserved) - Bit 9 Q Response from last operation - Crate Specific - Bit 10 Event latch - Bit 11 FIFO 3/4 full - Bit 12 Not used in Daphne - Bit 13 AUX busy (?) - Crate specific - Bit 14 FIFO full (?) - Not used in Daphne - Bit 15 Copy of output bit 4 - Bit 16 Copy of output bit 5 NOTE Open TTL inputs are interpreted as "1", whereas open NIM inputs are interpreted as "0". However, the EVENT inputs, both TTL and NIM, are edge triggered and thus requires a "0" to "1" transition to signal an event. 20.3.1 EX Input 8 Reserved for Acquisition Start/Stop Front panel input 8 is reserved. It is connected to the least significant bit of the Jorway NIM output register in slot 16. The VAX acquisition program tells the Event Handler when acquisition has started by setting this bit to "1". When the VAX wants to stop acquisition it resets the bit to logic "0". 20.3.2 Distinguishing NIM and TTL Inputs The NIM and TTL inputs of the EH can be distinguished by markings on jacks. On black Event Handlers the NIM inputs are silver colored, while the TTL inputs are bronze colored. On silver Event Handlers the NIM inputs have a black half circle above or below the jack, while the TTL inputs are unmarked. Experimenter's Guide To Daphne Page 106 Event Handler - EX Output Register 3 October 1990 20.4 EX Output Register There is a single 8 bit EX output register which controls front panel outputs of the Event Handler. - Bit 1 Front panel output [1] - Buffered TTL (50 ohm) - Bit 2 Front panel output [2] - Buffered TTL (50 ohm) - Bit 3 Front panel output [3] - Buffered TTL (50 ohm) - Bit 4 Front panel output [4] - TTL - Bit 5 Front panel output [5] - TTL - Bit 6 Front panel output [6] - TTL (Reserved for debugging) - Bit 7 Front panel output [7] - NIM - Bit 8 Front panel output [8] - NIM 20.4.1 Distinguishing NIM and TTL Outputs The NIM and TTL outputs on the EH can be distinguished by markings on the jacks. On black Event Handlers the NIM outputs are silver colored, while the TTL outputs are bronze colored. On silver Event Handlers the NIM outputs have a black half circle above or below the jacks, while the TTL outputs are unmarked. The buffered TTL outputs are able to sink up to 100 mA while maintaining a logic "0". Normal TTL outputs can sink up to 16 mA, (10 TTL loads) while maintaining a logic "0". 20.4.2 EX Output 6 Reserved for Debugging Aid TTL output 6 is used by the Event Handler program as an aid in trouble-shooting acquisition system problems. Characteristic output patterns are generated for each of the following conditions: - Waiting for acquisition to start - Waiting for an event - Waiting for the FIFO to empty The output patterns are described in the section on "Trouble-Shooting Acquisition Problems" (Section 41.21). Experimenter's Guide To Daphne Page 107 Event Handler - PAT Register 3 October 1990 20.5 PAT register The 24 bit PAT register of the Event Handler has the same bit test and compare operations as the CA registers. It is useful for inspecting bit significant patterns which control the read-out of other devices. Consider as an example, a Camac NIM input register, such as the Bi Ra Model 2351, which might be used to indicate which of several detectors have fired. (Refer to the diagram of the Bi Ra 2351 and Lecroy 429A in section 9.1) After reading the register with an F0 or F2 function code the pattern value is in CA1. If the pattern could not be copied into the PAT register, the pattern would have to be reread several times, as each Camac I/O operation would load the CA1 with ADC information, destroying the pattern value. The following code segment shows how to use the PAT register to control what devices are read-out. o o o MAIN CNAF 1,N_PAT,0,2 ;read pattern module into CA1 OUT CA1 ;first parameter of event MOV CA1,PAT ;copy to PAT register of EH IF (PAT .NONE. [1]) NOT1 ;branch if det 1 didn't fire CNAF 1,N_ADC,0,2 ;read channel 0 of ADC OUT CA1 ;place in FIFO NOT1 IF (PAT .NONE. [2]) NOT2 ;branch if det 2 didn't fire CNAF 1,N_ADC,1,2 ;read channel 1 of ADC OUT CA1 ;place in FIFO NOT2 IF (PAT .NONE. [3]) NOT3 ;branch if det 3 didn't fire CNAF 1,N_ADC,2,2 ;read channel 2 of ADC OUT CA1 ;place in FIFO NOT3 o o o The mnemonic UPAT refers to the upper 8 bits of the 24 bit PAT register. Experimenter's Guide To Daphne Page 108 Event Handler - IF statements 3 October 1990 20.6 IF Statements The IF statement is a macro which generate two machine instructions: a SKIP instruction and a BRANCH instruction. The first operand of the IF statment must be a register, such as CA1 or EX1. The second operand must be a compile-time constant. One cannot cannot compare two registers. - IF (register .ANY. constant) TARGET Valid for CA1, CA2, EX1, EX2, PAT, and UPAT If the bitwise AND of register and constant is non-zero then branch to TARGET - IF (register .NONE. constant) TARGET Valid for CA1, CA2, EX1, EX2, PAT, and UPAT If the bitwise AND of register and constant is zero then branch to TARGET - IF (register .GT. constant) TARGET Valid for CA1, CA2 and PAT Performs a 16 bit unsigned comparison between a register and a constant - IF (register .LT. constant) TARGET Valid for CA1, CA2, and PAT Performs a 16 bit unsigned comparison between a register and a constant The Event Handler's instruction set is neither complete nor symmetric. For the following types of branches use the code appearing at the right as a substitute: Imaginary instruction Simulate With IF (register .EQ. constant) X IF (register .GT. constant) NOT_X IF (register .LT. constant) NOT_X IF (register .LE. constant) X IF (register .LT. constant+1) X IF (register .GE. constant) X IF (register .GT. constant-1) X Experimenter's Guide To Daphne Page 109 Event Handler - Most Frequently Used Instructions 3 October 1990 20.7 Most Frequently Used Instructions Most user-written routines will consist solely of the following few instructions: - CNAF c,n,a,f For Camac read operation the appropriate CA register is loaded from the dataway after executing the CNAF code. For Camac write function codes the appropriate CA register is put on the dataway. - OUT CA1 or OUT CA2 The lower 16 bits of the CA register are transferred to the Kinetic Systems FIFO. Successive OUT instructions should be separated by at least 2 uSec in order to avoid synchronization problems between the Event Handler and the KS/FIFO. A convenient way of delaying the program is to use the NOP instruction described below. To transfer the upper 8 bits to the FIFO use the the instruction described next. - OUT UCA1 or OUT UCA2 The upper 8 bits (bits 24 through 17) of the corresponding CA register are transferred, right justified, to the FIFO. The upper 8 bits of the word transferred to the FIFO will be zero. Successive OUT instructions should be separated by at least 2 uSec in order to avoid synchronization problems between the Event Handler and the KS/FIFO. A convenient way of delaying the program is to use the NOP instruction described below. - MOV constant,CA1 or MOV constant,CA2 The 16 bit constant is loaded into the corresponding CA register. The upper 8 bits (bits 24 through 17) of the CA register are set to zero. - NOP The NOP instruction performs no operation, hence its name. It is useful for adding a 500 nSec delay when references to the FIFO would not be separated by at least 2.0 uSec. Experimenter's Guide To Daphne Page 110 Event Handler - Most Frequently Used Instructions 3 October 1990 - DLAY constant The operand of the DLAY instruction is the number of 100 nSec intervals to wait before resuming execution of the program. The argument may be between 1 and 4095, allowing for intervals up to 409.5 uSec. This instruction is especially useful when reading-out ADCs that require many micro-seconds to digitize a signal. The capabilities of the Event Handler are described more completely in a separate document. See section 4.1 ("Related Documentation") for information on how to obtain a copy. Experimenter's Guide To Daphne Page 111 Summary of Event Handler Assembly Language 3 October 1990 20.8 Summary of Event Handler Assembly Language The Event Handler is programmed in a simple assembly language. Here is a QUICK overview. For more complete information consult W. T. Milner's notes in DAPHLP:EH_HENSLEY.MEM (See section 4.1 for information on how to obtain a copy). - Source code may be in either uppercase or lowercase - A TAB character is treated as one or more space characters - Symbols and statement labels may NOT have the same name - Symbols - Symbols may be up to 8 characters long - Symbols are created by statements of the form: SYMBOL=value - Symbols may contain the underscore character ("_") - Examples NDET=8 COUNT=COUNT+1 MASK=MASK*2 REPEAT=C_BEGIN-C_END+1 - Statement Labels - Statement labels must begin in column 1 - Statement labels may be up to 8 characters long - Statement labels may contain the underscore character ("_") - Statement labels must be followed by an instruction of some kind - Statement labels sitting by themselves on a line are ignored - Source Code Format - Statement labels must begin in column 1 - Opcodes start anywhere after column 1 (Column 9 is recommended) - Only one statement is allowed per line - Comments can appear at the end of any line by preceding the comment with a semicolon. - The INCLUDE statement may be used to copy Event Handler source code from other files into a program. INCLUDE DAPEH:STANDARD INCLUDE MY_IO_CONFIGURATION Experimenter's Guide To Daphne Page 112 Summary of Event Handler Assembly Language 3 October 1990 - LOOP Statement The LOOP/ENDLOOP statement is a macro which allows a block of code to be repeated up to 99 times. I=-1 LOOP 8 ;Read out all channels 0 to 7 of ADC I=I+1 ;Next channel of ADC CNAF 1,N_ADC,I,2 ;Read "Ith" channel OUT CA1 ;Transmit to FIFO ENDLOOP ;Repeat - Constants - Numbers are assumed to be base 10 - Hexadecimal numbers are represented by using the suffix "H" MASK=10H ;Same as 16 decimal MOV 0FFh,CA ;Lower 8 bits set - The expression [N] generates a constant with only bit N set (counting from 1). In other words: [N] is equal to 2 to the (N-1) power. READY=[8] ;128 ERROR=[9] ;256 DONE=READY+ERROR ;384 LOW3BITS=[1,2,3] ;7 Experimenter's Guide To Daphne Page 113 Assembling and Loading an Event Handler Program 3 October 1990 20.9 Assembling and Loading an Event Handler Program To assemble an Event Handler program in a file named MYPROG.EHA use the following command: $ EHASM MYPROG This creates a listing file named MYPROG.LIS and an object file named MYPROG.EHO which can be loaded into the Event Handler by the $EHSEND command. The listing file contains the original program side-by-side with the generated machine code. A symbol table and cross reference appears at the end of the listing. If you wish to see in the listing the code generated by (a) LOOP/ENDLOOP statements and (b) by IF macros use the /FULL qualifier: $ EHASM MYPROG /FULL If you are using the silver Event Handlers, and do not want to receive warnings about instructions which are not implemented on the black Event Handlers, use the /NEW qualifier: $ EHASM MYPROG /NEW The Event Handler assembler was written by W. T. Milner of Oak Ridge National Laboratory. 20.10 Downloading and Starting an Event Handler Program Let's assume that you have already executed the $CDV command (Camac Device Command - Section 6.8) in order to tell Daphne the crate and slot in which the Event Handler and AUX are located. To download the assembled Event Handler object program MYPROG.EHO and then start execution: $ EHSEND MYPROG The EHSEND program executes a Camac crate INIT before beginning to load the Event Handler. When an Event Handler program has been successfully loaded, and is waiting for acquisition to start, it will blink the select light of the Jorway NIM Output Register in slot 16 of the Camac crate about 4 times per second. Occasionally one needs to restart an Event Handler program which has already been loaded and started once. The following command issues a crate reset and starts execution of a previously loaded Event Handler program: $ EHGO Experimenter's Guide To Daphne Page 114 Assembling and Loading an Event Handler Program 3 October 1990 20.11 When Must the Event Handler Be Reloaded ? Once an Event Handler program has been loaded, it is not necessary to reload it until the program is changed or power to the crate is lost. In particular, one may start and stop acquisition any number of times without reloading the Event Handler. In fact, one can exit the Daphne subsystem, log out of the VAX, and even shut down the VAX and restart it without reloading the Event Handler. Experimenter's Guide To Daphne Page 115 Interfacing the Event Handler 3 October 1990 21 Interfacing the Event Handler 21.1 Fan-In of Event Trigger The front panel event input, whether NIM or TTL, is edge triggered and must be at least 50 nSec in duration. In contrast, an Ortec 811 ADC requires a 5 nSec NIM signal. 21.2 Fan-Out of Busy Signal The BUSY output is available as both a NIM and TTL output level. 21.3 NIM Levels For NIM output signals, a value less than -0.8 V into 50 ohms is considered logic "1", while a value of 0 V is considered logic "0". 21.4 TTL Levels For TTL output signals, a value greater than 2.4 V is considered logic "1", while a value less than 0.8 V is considered logic "0". 21.5 Using Front Panel Outputs Some users need a pulse at the end of each event to enable their electronics to accept new events. The INCLUDE files "DAPEH:PULSE7.EHA" and "DAPEH:PULSE8.EHA" will generate a NIM pulse on front panel outputs 7 and 8 of the Event Handler. They must be placed in the Event Handler program at the point where the pulse should be generated. The Event Handler front panel outputs might be preferred to the Jorway Ouput Register because the Event Handler can perform this operation in about 1 uSec using the front panel outputs, but requires about 2.5 uSec to do this through the Camac dataway, besides destroying the contents of the CA1 register. Front panel outputs 1 through 6 of the Event Handler generate TTL signals and tend to be less popular. Output 6 is reserved for debugging Event Handler programs. Experimenter's Guide To Daphne Page 116 Time Relationship of Some Daphne Signals 3 October 1990 This timing diagram attempts to show the relationship between the Event Handler EVENT and BUSY signals, as well as the signals provided by the Jorway NIM Output Register (Section 16). A "time line" at the top of the page goes from left to right showing acquisition start ("A"), accepted events ("E"), and the end of acquisition ("Z"). A "1" represents a signal which is "true", a "." represents a signal which is "false" or logic "0". Before Acq Event Event Acq Acq Start #1 #2 Stop Start | | | | | | | | V V V V A E E Z "Acquisition Active" Level Bits 1, 2, and 3 of NIM Output Register ..................11111111111111111111111111111111111111111......... A E E Z "Acquisition Start" Pulse Bit 4 of NIM Output Register ..................1................................................. A E E Z "New Event" on Rising Edge To Event Handler EVENT Input .........................1111111111........1111111111............... A E E Z "Do Not Accept Events" Level From Event Handler BUSY Output High while (a) acquisition OFF or (b) Event Handler BUSY processing an Event 1111111111111111111......1111111111........11111111111....1111111111 A E E Z Events before being gated by BUSY ..1...1.......1..........1....1...1........1...1.....1..........1.1.. A E E Z Experimenter's Guide To Daphne Page 117 Interfacing the Event Handler - Simple Example 3 October 1990 21.6 Example 1 In the example below, detectors 1A, 1B, 2A, 2B, 3A, 3B are required to be coincident by pairs, as in a (delta E) - E telescope. The Event Handler is triggered by applying a pulse to the EVENT input when at least one of the pairs is present within the coincident time overlap period. In the example below, the detector pair (or pairs) which has a coincidence is identified by providing a signal (through a shaping unit) to the Event Handler front panel inputs. The front panel inputs are one method for altering the behavior of the Event Handler based on the detectors which have fired. For instance, one may want to read only those ADCs or TDCs corresponding to the bits set. The Event Handler BUSY signal is used to veto any other pulses into the coincidence unit. In this example, a logic fan-in/fan-out unit allows us to add other veto conditions such as "Linac Out of Lock", or excessive count rates. In this example, the gates of the ADCs are actuated at the same time the Event Handler EVENT signal is asserted. Hence, the Event Handler program will have to provide any delays required for the conversion times of ADCs and TDCs. Experimenter's Guide To Daphne Page 118 Interfacing the Event Handler - Diagram 3 October 1990 Coincidence Register Veto +-----------------------+-----------------------+-----------------------+ | +----------+ | +----------+ | +----------+ | | | Coincid. | | | Coincid. | | | Coincid. | | | | | | | | | | | | | #1A----> In 1 | | #2A----> In 1 | | #3A ----> In 1 | | | | | | | | | | | | | | Out ----+ | | Out ----+ | | Out ----+ | | | | | | | | | | | | | | | #1B----> In 2 | | | #2B----> In 2 | | | #3B----> In 2 | | | | | | | | | | | | | | | | | | | | | | | | | | | | | +--------> Veto | | +--------> Veto | | +--------> Veto | | | +----------+ | +----------+ | +----------+ | | | | | | +-----------------+ +-----------------+ +-----------------+ | | | | | | +--------+ | +--------+ | +--------+ | | | Gate & | | | Gate & | | | Gate & | | | | Delay | | | Delay | | | Delay | | | | | | | | | | | | +-----> In | +-----> In | +-----> In | | | | | | | | | | Out ----+ | Out ----+ | Out ----+ | | | | | | | | | | | +--------+ | +--------+ | +--------+ | | | #1C | #2C | #3C | +-----------------+ | | | | | | | | +--------------------------------------+ | | | | | | | | +-----------------------------------------------------------+ | | | | | | | | +-----------+ | | | | | Logic OR | +-----------+ | | | | | | | Event | | | | +------> In 1 | | Handler | | | | | | | | | | | | Out 1 -----------------> EVENT | | | | | | | | | | +---------> In 2 | #1C -----> In 1 | | | | | | | | | | Out 2 ----+ #2C -----> In 2 | | | | | | | | +------------+ | +------------> In 3 | | #3C------> In 3 | | Logic Or | | | | | | | | | | +-----------+ | | BUSY -------> In 1 | | | +-----------+ | | | <---------------------+ | | | To gates Linac Out of Lock ----> In 2 | | on ADCs | | | on TDCs | | | etc. Other Veto Conditions ----> In 3 | | | | Veto | | Out ---------+ | | +------------+ Experimenter's Guide To Daphne Page 119 Event Handler Interfacing - Fast Clear 3 October 1990 21.7 Example 2 The following diagram shows how to generate a "fast clear" signal. The fast clear signal is used when ADCs or TDCs must be triggered before an event is known to be "interesting". If the event turns out not to be interesting, the ADCs and TDCs must be cleared and the trigger logic re-enabled, preferably without the delay introduced by the intervention of the Event Handler. A typical example would be the selection of only those events which have deposited a certain amount of energy into a detector. The ADCs and TDCs must be triggered long before the amount of energy deposited is known: the integration of the energy signal may take several micro-seconds. In the diagram below, the ADCs and TDCs are triggered by the "fast" signal since there is substantial time jitter in the measurement of the slow signal. The trigger logic waits for a signal from the "slow" discriminator for up to 2 uSec, starting from the signal generated by the "fast" discriminator. If the "slow" discriminator does not trigger within 2 uSec, the "fast clear" pulse is generated, otherwise the EVENT signal of the Event Handler is asserted for 150 nSec in order to provide ample time for the Event Handler signal to be propagated through the trigger logic to the VETO inputs of both discriminators. Experimenter's Guide To Daphne Page 120 Event Handler Interfacing - Fast Clear 3 October 1990 Slow Signal Fast Signal | | V | +---------+ Slow Discr VETO | | Discr | <------------------ | ---------------------------------+ +---------+ V | | +--------+ Fast Discr VETO | | | Discr | <----------------------+ | | +--------+ | | | | | | +-----------+ +------+ | | | | +---> | Gate Gen | --> | OR | | | | | +-----------+ +------+ | | | | 3 uSec ^ | | +------------+ | | | | | | Gate Gen | <--+ | | | | +------------+ | | | | | | | | | V | | | | Strobe | | | | ADC/TDC/etc. | | | V V | | +------------+ +------------+ | | | Gate Gen | | Gate Gen | | | | > 2 uSec | | 2 uSec | | | +------------+ +------------+ | | | | | | | | | +-------+ | | ************* | | | | NOT | | | ** Delayed ** | | | +-------+ | | ** Marker ** | | | | | | ************* | | | +-- | -------------------+ | | | | | +-----------------------+ | | | | | | | | | V V V V | | +------------+ +------------+ | | | AND | | AND | | | +------------+ +------------+ | | | | | | V | | | +------------+ V | | | Gate Gen | | | | > 150 nSec | Fast Clear | | +------------+ (Pulse) | | | +-----------+ | | | +-----------+ | OR | | | | | Event | | | | | | | Handler | Linac Out of Lock ----> | | | | | | | Out -----+ | +------> EVENT | PAUSE ----> | | | | | Out ------------+ | BUSY ------ Event Handler BUSY ----> | | | | | +-----------+ Other VETO Conditions ----> | | | +-----------+ Experimenter's Guide To Daphne Page 121 FIX Variables 3 October 1990 22 FIX Variables The $FIX command allows one to define and modify, without stopping acquisition or replay, 32 bit integer parameters used by a user-function. The number of such parameters is limited to 255 for on-line user-functions. There is no practical limit for user-functions during replay. - $ FIX - change the parameter value - $ FIX/DEFINE - give symbolic name to parameter value - $ FIX/DELETE - delete symbolic name for parameter - $ FIX/LIST - list parameters and current values - $ FIX/LIST - list parameters and current values - $ FIX/LIST/COMMAND - DCL command language format - $ FIX/LIST/FORTRAN - Fortran source code for user-function New values may be supplied in binary, octal, hexadecimal, or decimal. Symbolic names may apply to scalers or arrays. Symbolic names should be Fortran compatible. Parameters can be referenced by position or symbolic names. Listings can be created which are compatible with Fortran declarations or DCL commands which recreate the current state of the FIX variables. 22.1 Use $FIX/DEFINE to Create Symbolic Names If no initial value is specifed, zero is used. Some examples: $ FIX/DEFINE A - assign first unused position to A $ FIX/DEFINE B /POS=10 - give parameter 10 the name B $ FIX/DEFINE C:10 - define array of 10 parameters named C:1 through C:10 $ FIX/DEFINE D 1 - define parameter D with initial value 1 $ FIX/DEFINE E XFF - parameter E with initial value of hexadecimal 'FF' (decimal 255) $ FIX/DEFINE F O177 - parameter F with initial value of octal '177' (decimal 127) $ FIX/DEFINE G B1111.1111 - parameter G with initial value of binary 11111111 (decimal 255) the periods are ignored on input $ FIX/DEFINE H:5 10,9,8,7,6 - parameter H is an array of 5 elements each with an initial value Initial values for the parameters (if non-zero) are recorded in the Daphne log file. Experimenter's Guide To Daphne Page 122 FIX Variables 3 October 1990 22.2 Use $FIX to Change Values $ FIX A 1 - change A to 1 $ FIX B - ask user for new value for B $ FIX 10 - ask user for new value for parameter 10 $ FIX/DEFINE C:3 $ FIX C - ask user for new values for C:1 C:2 and C:3 $ FIX C:2 - ask user for new value for C:2 $ FIX A,B,C - ask user for new values for A B and C:1 C:2 and C:3 $ FIX A,B,C 10,20,31,32,33 - assign new values to A B and C:1 C:2 and C:3 do not query user $ FIX - prompt user for names as well as values The user can stop the request for new values by entering a blank, EXIT, STOP, or QUIT when the program is waiting for the user to supply a parameter name. All changes to parameter values are recorded in the Daphne log file. 22.3 $FIX/LIST $ FIX/LIST - list parameter names/values on terminal $ FIX/LIST/OUTPUT=A.LIS - same listing but place in file A.LIS $ FIX/LIST/COMMAND/OUT=A.COM - create command file which can be used to recreate current state of FIX parameters $ FIX/LIST/FORTRAN/OUT=FIXDEFS.INC - create Fortran include file which can be included in Fortran user-function to define the FIX parameter vector 22.4 Use $FIX/DELETE to Delete Definitions $ FIX/DELETE - deletes all symbolic names $ FIX/DELETE A,B,C - deletes symbolic names A B and C Experimenter's Guide To Daphne Page 123 FLT Variables 3 October 1990 23 FLT Variables The $FLT command allows one to define and modify, without stopping acquisition or replay, single precision floating point parameters used by a user-function. The number of such parameters is limited to 255 for on-line user-functions. There is no practical limit for replay user-functions. - $ FLT - change the parameter value - $ FLT/DEFINE - give symbolic name to parameter value - $ FLT/DELETE - delete symbolic name for parameter - $ FLT/LIST - list parameters and current values - $ FLT/LIST - list parameters and current values - $ FLT/LIST/COMMAND - DCL command language format - $ FLT/LIST/FORTRAN - Fortran source code for user-function Except for the use of single precision floating point numbers rather than integers, there is no significant difference between $FLT and $FIX (which is described in the immediately preceding section). For this reason, there is no point in giving examples of the $FLT commands. Experimenter's Guide To Daphne Page 124 User-Functions 3 October 1990 24 User-Functions The main purpose of the user-function is to compute pseudo-parameters. If you are not computing any pseudo-parameters there is usually no need to write a user-function: instead the user should load the "standard" event processor program (Section 27.3 of EG). A second reason to write a user function is to modify an event before it is written to tape. The organization of a user-function is essentially the same for acquisition, replay on the Event Processors, or replay on the VAX. A user-function written for acquisition can usually be used without changes for replay on the VAX or replay on the Event Processors. The converse is not true, however, since VAX user-functions tend to require access to files containing information such as calibration constants: it is not possible to access VAX files from the Event Processors. A description of the difference between the VAX/VMS Fortran compiler and the National Semiconductor GNX cross compiler is given in section 26.2 of EG A Daphne user function consists of several subroutines and functions, all of which are optional. These routines are: - An initialization routine for when sorting starts (Entry userIn) - A routine for when a FIX or FLT variable changes (Entry FixFlt) - Up to 50 routines to be executed as part of "Condition" evaluation (Entry points user1, user2, ... user50) - A routine for when sorting stops (Entry userEx) Some examples of simple user functions begin at section 1.19. Experimenter's Guide To Daphne Page 125 User-Functions 3 October 1990 24.1 Multiple Entry Points The user can code the parts of a Daphne user-function as separate Fortran subroutines and functions, or as several entry points of a single Fortran module. The use of multiple entry points in a single module is recommended for the following reasons: - Variables need to be declared only once - Declarations of variables shared among the user routines will always match as there is only a single declaration - It will be easier to locate the source of an arithmetic trap when working from the link map, since there will be a single base address for all user routines. The main reasons NOT to use multiple entry points are (a) if the subroutines or functions must call one another either directly or indirectly or (b) the data types of the functions are inconsistent. For instance, one cannot have one entry point of a module which is INTEGER*4 and another which is REAL*4. Fortunately, there is no reason not to declare all Daphne user function entry points as LOGICAL or LOGICAL*4. Although all entry points of a function must be of the same type, the arguments of these functions may differ in number and order. The next page shows how a collection of several subroutines might be recast into a single module with multiple entry points. Experimenter's Guide To Daphne Page 126 User-Functions 3 October 1990 Separate Subprograms Single Subprogram with Entry Statements +------------------------------+ +------------------------------+ | subroutine a (aArg,bArg) | | function a (aArg,bArg) | | integer*4 aArg,bArg | | logical a,b,c | | common /c/ x,y,z | | integer*4 aArg,bArg | | ... | | real*4 cArg | | return | | common /c/ x,y,z | +------------------------------+ | c | | ... | +------------------------------+ | return | | logical function b (aArg) | | c | | integer*4 aArg | | entry b (aArg) | | common /c/ x,y,z | | ... | | ... | | b=... | | b=... | | return | | return | | c | | end | | entry c (cArg) | +------------------------------+ | ... | | c=... | +------------------------------+ | return | | logical function c (cArg) | | end | | real*4 cArg | +------------------------------+ | common /c/ x,y,z | | ... | | c=... | | return | | end | +------------------------------+ Illegal use of ENTRY (Routine A calls B, another entry point of the same module) +------------------------------+ | subroutine a (aArg) | | integer*4 aArg,bArg | | c | | ... | | call b (xyz) | | return | | c | | entry b (bArg) | | ... | | return | | end | +------------------------------+ Experimenter's Guide To Daphne Page 127 User-Functions 3 October 1990 24.2 Service Routines The Daphne developers have written some subroutines which users might find handy in writing their user functions: - bit16 - break apart an INTEGER*2 variable into separate bits - cntbit - count number of bits set in an INTEGER*2 variable - defPEV - define pseudo-event vector - defFIX - define FIX parameter vector - defFLT - define FLT parameter vector - trapID - aid to locating source of arithmetic traps - unpack - break apart event using pattern words - unpack_hit - break apart event using pattern words and provide extra information for hit patterns - zeroI2 - zero an INTEGER*2 array These routines are called "service routines", and are described starting at section 1.9. 24.3 Interception of Arithmetic Traps Both the VAX and NS3200 sorting programs intercept arithmetic traps which occur in user functions. In the VAX version the user can replace the Daphne supplied trap handler with one of his own. The NS32000 sort program does not allow the user to substitute a trap routine for the standard one. Arithmetic traps in the user functions are not considered fatal since the problem may by data dependent, and it might be possible to process most events. For instance, a division by zero might occur only in 1 out of 1,000,000 events in which two ADCs both read zero. In contrast, arithmetic traps in the userIn, userEx, or FixFlt routines are fatal: sorting will not continue. This is because these three routines do not depend on event data. They should give the same result, regardless of which event was last analyzed. For help in diagnosis of arithmetic traps on the VAX see the Replay Guide, a separate document, which contains instructions on how to use the VAX/VMS symbolic debugger with Daphne user-functions. To diagnose arithmetic traps on the NS3200 see section 2. Experimenter's Guide To Daphne Page 128 User-Functions 3 October 1990 24.4 Entry UserIn (User Initialization) This routine is called at the beginning of the sort process to let the user perform any user specific or run specific initialization. The userIn routine almost always includes a call to subroutine defPEV (Section 1.10) to define the pseudo-event vector The declaration of userIn: +-----------------------------------------------------------------+ | Event Processors Only | +-----------------------------------------------------------------+ | entry userIn | | | | No Arguments for Event Processor | +-----------------------------------------------------------------+ +-----------------------------------------------------------------+ | VAX Replay Only | +-----------------------------------------------------------------+ | entry userIn (runNumberString) | | | | runNumberString - input/character*(*) | | the run number entered by the user | +-----------------------------------------------------------------+ Experimenter's Guide To Daphne Page 129 User-Functions 3 October 1990 24.5 Entry userEx (User Exit) This optional VAX routine is called at the end of the sorting to let the user perform any user or run specific clean up. For example, the user could write summary information to a log file, or print out performance statistics. The declaration of userEx: +-----------------------------------------------------------------+ | VAX Replay Only | +-----------------------------------------------------------------+ | entry userEx (statusCode) | | | | statusCode - input/integer*4 | | | | a standard VMS status code giving | | exit status of the sort process | | if odd then normal exit from sort | | if even then exit is due to error | +-----------------------------------------------------------------+ There is no support for a user exit routine on the Event Processors. Experimenter's Guide To Daphne Page 130 User-Functions 3 October 1990 24.6 Entry User (Process an Event) This routine is optional, but almost always supplied. It is called once for each event before any maps, windows, conditions, linearizations, etc. are evaluated. It allows the user to compute pseudo-parameters for the pseudo-event vector declared in the call to defPEV by userIn (Section 1.10). The declaration of User: +------------------------------------------------------------------+ | entry user (eventType,eventSize,eventVector) | | | | eventType - input/integer*2 | | the type of the event | | for experiments with: | | | | fixed length events: always 0 | | | | variable length events with a single | | event type: always 0 | | | | multiple event types: the event type | | assigned by the user's event handler | | program (a number between 0 and 15) | | | | eventSize - input/integer*2 | | the number of integer*2 words in the event | | | | eventVector - input/integer*2 array | | the event data | +------------------------------------------------------------------+ Experimenter's Guide To Daphne Page 131 User-Functions 3 October 1990 24.7 Logical Function User1, User2, ... User50 These optional routines allow the user to break the computation of pseudo parameters into as many as 50 parts. This is useful for two main reasons: - Linearization values are sometimes needed to compute pseudo-parameters. If you want to use linearizations in computing pseudo-parameters then place the calculation in a USER-n routine and precede the USER-n condition by a FORCELNZ condition. - An expensive computation is needed for only a fraction of events. Place the computation in a USER-n function after a KILL condition which aborts processing of events which are not of interest. See section 35.8 of EG for an example. The declaration of User1, User2, ... User50: +------------------------------------------------------------------+ | logical function user1 (eventType,eventSize,eventVector, | | lnzVector) | | | | function value - output/logical | | | | the function value used to set the | | corresponding condition to true (or false) | | | | eventType - input/integer*2 | | the type of the event | | same meaning as for the plain USER function | | | | eventSize - input/integer*2 | | the number of integer*2 words in the event | | | | eventVector - input/integer*2 array | | the event data | | | | lnzVector - input/integer*4 array | | | | value of linearization 1 in lnzVector(1) | | linearization 2 in lnzVector(2) | | and so on | | | | the user must be sure that the linearization | | has been evaluated for this event, | | otherwise the array will contain old | | values from previous events | | | | *** WARNING *** the lnzVector is integer*4 | +------------------------------------------------------------------+ Experimenter's Guide To Daphne Page 132 User-Functions 3 October 1990 24.8 Entry FixFlt (Change in Fix or Float Values) This routine is optional. It is called each time the user changes a FIX or FLT parameter. It is also called as part of the sort initialization sequence, after entry point userIn has been called, but before any events are sorted. There are two major uses for the FixFlt entry point: - Derived Values If computations depend on a complex expression, which in turn depends on parameters which are changed only by the $FIX and $FLT command, the complex expression can be computed just once in the FixFlt routine rather than recomputed for each event. A simple case would be a change in units from angle-in-degrees to angle-in-radians. A more complicated case would be a quanity which depends on the arctangent of the quotient of two quantities. - Request Program Action The user can change the value of a $FIX or $FLT parameter to get the attention of the program. For instance, by changing the value of some $FIX parameter during replay on the VAX from 0 to 1, the program would enter the FixFlt routine where the program might recognize that a value of 1 for that parameter means the program should print out some summary information, or enter into a dialogue, etc. The declaration of FixFlt: +------------------------------------------------------------------+ | entry FixFlt | | | | This entry point has no arguments | | | +------------------------------------------------------------------+ See sections 1.11 and 1.12 on defFIX and defFLT for how to declare and access the FIX and FLT variables. Experimenter's Guide To Daphne Page 133 User-Functions 3 October 1990 24.9 Subroutine TRAP (Interception of Arithmetic Traps on the VAX) Although the user has the option of supplying a handler for arithmetic traps during replay on the VAX, the Daphne routine is generally adequate when used in combination with the VAX/VMS symbolic debugger. The Daphne supplied TRAP routine counts the number of arithmetic traps and prints a message on the command terminal when the number of traps is a power of 10 or a multiple of 100,000. The declaration of the VAX version of TRAP: +------------------------------------------------------------------+ | VAX Replay Only | +------------------------------------------------------------------+ | subroutine trap (eventType,eventLength,event,trapCode,trapID) | | | | eventType - input/integer*2 | | the type of the event | | | | same meaning as for the plain USER function | | | | eventSize - input/integer*2 | | the number of integer*2 words in the event | | | | eventVector - input/integer*2 array | | event being analyzed at time of trap | | this is the event as written to tape | | | | trapCode - input/integer*4 | | standard VMS status code: | | | | SS$_INTOVF Integer overflow | | SS$_INTDIV Integer division by 0 | | | | SS$_FLTOVF Floating point overflow | | SS$_FLTOVF_F | | | | SS$_FLTDIV Floating point division by 0.0 | | SS$_FLTDIV_F | | | | SS$_FLTUND Floating point underflow | | SS$_FLTUND_F | | | | to define the SS$_xxx symbols use the Fortran | | statement: | | | | INCLUDE '($SSDEF)' | | | | trapID - input/integer*4 | | last value registered by a call to | | trapID(number) | +------------------------------------------------------------------+ Experimenter's Guide To Daphne Page 134 User-Functions 3 October 1990 24.10 Service Routine defPEV (Define Pseudo-Event Vector) This routine is called by userIn to tell the sort program the location and length of the pseudo-event vector. This call is required if the user-function uses pseudo-parameters. +-----------------------------------------------------------------+ | entry userIn (runNumberString) | | .... | | integer*2 pseudo (50) | | ... | | call defPEV (pseudo,pseudo(50)) | | ^ ^ | | | | | | | +-- last element of | | | pseudo-event vector | | | | | +-- first element of pseudo-event vector | | ... | +-----------------------------------------------------------------+ Experimenter's Guide To Daphne Page 135 User-Functions 3 October 1990 24.11 Service Routine defFIX (Define FIX Vector) This routine is called by userIn to tell the sort program the location and length of the FIX parameter vector. This call is required if the user-function uses FIX parameters. A user defines the names of the FIX variables with the $FIX/DEFINE command (Section 22 of EG). Normally, the last step is to create a Fortran compatible INCLUDE file which declares all the FIX variables by name and creates Fortran EQUIVALENCE statements between them and the FIX vector. For example: +-----------------------------------------------------+ | $ FIX/DEFINE MASSLO 40 | | $ FIX/DEFINE MASSHI 60 | | $ FIX/LIST/FORTRAN/OUTPUT=FIXDEFS.INC | +-----------------------------------------------------+ Would create the INCLUDE file: +-----------------------------------------------------+ | c | | c Date: 5-OCT-87 23:21:08 | | c | | common /fixcom/ fixArr,fixZZZ | | integer*4 fixArr ( 100) | | integer*4 fixZZZ | | c | | integer*4 MASSLO | | equivalence (fixarr( 1),MASSLO) | | integer*4 MASSHI | | equivalence (fixarr( 2),MASSHI) | +-----------------------------------------------------+ The include file allows the user to reference the FIX parameters by name ("MASSLO") and creates a symbolic name for the last element of the FIX vector ("FIXZZZ"). The call to defFIX is now routine: +--------------------------------------------------------------+ | entry userIn (runNumberString) | | .... | | include 'FIXDEFS.INC' | | ... | | call defFIX (fixArr,fixZZZ) | | ^ ^ | | | | | | | +-- last element of FIX vector | | +-- first element of FIX vector | | ... | | entry user (eventType,nWords,eventVector) | | if (mass .ge. massLo .and. mass .le. massHi) then | | ... | | else | | ... | | endif | +--------------------------------------------------------------+ Experimenter's Guide To Daphne Page 136 User-Functions 3 October 1990 24.12 Service Routine defFLT (Define FLT Vector) The defFLT routine is essentially the same as defFIX, except that $FLT and defFLT are used with Fortran REAL*4 variables, whereas $FIX and defFIX are used with Fortran INTEGER*4 variables. The defFLT routine is called by userIn to tell the sort program the location and length of the FLT parameter vector. This call is required if the user-function uses FLT parameters. A user defines the names of the FLT variables with the $FLT/DEFINE command (Section 23 of EG). Normally, the last step is to create a Fortran compatible INCLUDE file, which declares all the FLT variables by name, and creates Fortran EQUIVALENCE statements between them and the FLT vector. For example: +-----------------------------------------------------+ | $ FLT/DEFINE T0 0.378 | | $ FLT/DEFINE U 60.0E3 | | $ FLT/LIST/FORTRAN/OUTPUT=FLTDEFS.INC | +-----------------------------------------------------+ Would create the INCLUDE file: +-----------------------------------------------------+ | c | | c Run Information | | c | | common /fltcom/ fltArr,fltZZZ | | integer*4 fltArr ( 100) | | integer*4 fltZZZ | | c | | real*4 T0 | | equivalence (fltarr( 1),T0) | | real*4 U | | equivalence (fltarr( 2),U) | +-----------------------------------------------------+ The include file allows the user to reference the FLT parameters by name ("T0") and creates a symbolic name for the last element of the FLT vector ("FLTZZZ"). The call to defFLT is now routine: +--------------------------------------------------------------+ | subroutine userIn (runNumberString) | | .... | | include 'FLTDEFS.INC' | | ... | | call defFLT (fltArr,fltZZZ) | | ^ ^ | | | | | | | +-- last element of FLT vector | | +-- first element of FLT vector | | ... | | entry user (eventType,nWords,eventVector) | | if (time .lt. t0) ... | | ... | +--------------------------------------------------------------+ Experimenter's Guide To Daphne Page 137 User-Functions 3 October 1990 24.13 Service Routine trapID (Debug Aid for Arithmetic Traps) The trapID routine is used to help identify the section of code causing arithmetic traps on an Event Processor. Suspected parts of a program are sandwiched between calls to the trapID routine: call trapID (10) call trapID (11) call trapID (12) etc. Should an arithmetic trap be intercepted, the trap recovery routine passes the last trap ID number (in the example above: 10, 11, or 12) to the host to be included in the error message, thus identifying the block of code containing the problem. See section 2 for information on how to read a report of an arithmetic trap on an Event Processor. The trapID subroutine is implemented on the VAX for compatibility with Event Processor user functions, however, it is not recommended for the VAX because the VAX/VMS symbolic debugger provides a much better and more efficient tool for this class of problem. +-----------------------------------------------------------------+ | Recommended for Event Processors Only | +-----------------------------------------------------------------+ | subroutine trapID (idWord) | | | | idWord - input/integer*2 | | word to be reported to host computer when | | there is an arithmetic trap | +-----------------------------------------------------------------+ Experimenter's Guide To Daphne Page 138 User-Functions 3 October 1990 24.14 Service Routine zeroI2 (Zero an INTEGER*2 Array) The zeroI2 subroutine is an efficient way to zero an entire INTEGER*2 array. +------------------------------------------------------------------+ | zeroI2 recommended for Event Processors | +------------------------------------------------------------------+ | subroutine zeroI2 (nWords,vector) | | | | nWords - input/integer*2 | | the number of elements in the vector | | | | vector - output/integer*2 array of size "nWords" | | the entire array is filled with zero | +------------------------------------------------------------------+ Although the subroutine is supported on both the VAX and the NS32000, it is of less importance on the VAX, since the VAX Fortran compiler can recognize such a loop, when optimization is enabled, and use the appropriate machine instruction. The NS32000 does not generate very good machine code to zero an entire array. The main use of the subroutine is to zero the pseudo-event vector at the beginning of the user function. For instance, it could replace the "DO loop" in the following code fragment: +-----------------------------------------------------------------+ | ... | | integer*2 npev | | parameter (nPev=300) | | integer*2 pev (nPev) | | ... | | do 10 i=1,nPev -----> | | pev(i)=0 -----> call zeroI2 (nPev,pev) | | 10 continue -----> | | ... | +-----------------------------------------------------------------+ Experimenter's Guide To Daphne Page 139 User-Functions 3 October 1990 24.15 Service Routine BIT16 (Unpack Bits of an INTEGER*2 Word) The BIT16 routine makes it easy to test individual bits of a 16 bit INTEGER*2 variable by copying the "i th" bit of the word to the "i th" element of a 16 element INTEGER*2 array. For example, if bit 6 of the variable is 1 then element 6 of the array is set to 1 otherwise it is set to 0. +------------------------------------------------------------------+ | subroutine BIT16 (anInt,array) | | | | anInt - input/integer*2 | | variable to be broken apart into separate bits | | | | array - output/integer*2 array of 16 elements | | | | bit 1 of "anInt" 1 then arrary(1) set to 1 | | otherwise set to 0 | | bit 2 of "anInt" 1 then arrary(2) set to 1 | | otherwise set to 0 | | ... | | bit 16 of "anInt" 1 then arrary(16) set to 1 | | otherwise set to 0 | | | | the least significant bit of "anInt" is bit 1 | | the most significant bit of "anInt" is bit 16 | +------------------------------------------------------------------+ This provides a method, independent of the compiler, of testing individual bits of a variable. The VAX and NS32000 have different names for bit manipulation routines (Section 26.2 of EG). Experimenter's Guide To Daphne Page 140 User-Functions 3 October 1990 24.16 Service Routine CNTBIT (Count Bits Set in an INTEGER*2 Word) The CNTBIT routine provides a fast, compiler independent method of counting the number of bits set in a word. +------------------------------------------------------------------+ | integer*4 function CNTBIT (anInt) | | | | function value - output/integer*4 | | number of bits set in word (between 0 and 16) | | | | anInt - input/integer*2 | | count the number of bits that are "1" | | | | Examples: | | cntbit(0) is 0 | | cntbit(255) is 8 | | cntbit(256) is 1 | | cntbit(-1) is 16 | +------------------------------------------------------------------+ Experimenter's Guide To Daphne Page 141 User-Functions 3 October 1990 24.17 Service Routine UNPACK This routine is for unpacking a variable length event composed of multiple, optional, segments. A segment may be one or more 16 bit words. It is assumed that bits in a pattern word near the beginning of the event will be set or cleared to indicate the presence (or absence) of segments. Each pattern word is 16 bits, although not necessarily all bits of each pattern word are used. There may be more than one pattern word. This routine is controlled by a description passed to the routine as an array. For each possible segment there is a row in the array describing how to test for the presence of the segment (what bit in what word of the event vector to test) and where to put the segment, if it is present (how many words and what position of the pseudo-event vector). On exit, the subroutine returns to its caller the number of words in the event, and a vector describing which fields were found to be present. Fields NOT present are NOT zeroed in the pseudo-event vector. Experimenter's Guide To Daphne Page 142 User-Functions 3 October 1990 Suppose one has an event with two pattern words: 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ Pattern | | 3 | 3 | 1 | Word | | | | | 1 | | B2| B1| A1| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ Pattern | | 4 | 4 | 4 | | 2 | 2 | 2 | Word | | | | | | | | | 2 | | D3| D2| D1| | C3| C2| C1| +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ The numbers at the top of the boxes indicate the number of parameters for that segment or detector. The two character symbols at the bottom of each box is a name for the detector or segment assigned to that bit of the pattern word. If the box is empty, the bit is not used. Assume that the segements are assigned to positions in the pseudo-event vector in the following way: Name Number of Parameters Position in Pseudo-event Vector A1 1 1 B1 3 11,12,13 B2 3 14,15,16 C1 2 21,22 C2 2 23,24 C3 2 25,26 D1 4 31,32,33,34 D2 4 41,42,43,44 D3 4 51,52,53,54 The UNPACK routine is designed to do this unpacking from the real event vector to the pseudo-event vector. The most complicated part of using the routine is describing the relationship between bits in the pattern word, detectors, and positions in the pseudo-event vector. This information is supplied to the subroutine in the form of a table. The first page following gives the calling sequence for the UNPACK routine. The second page following shows how the multiple detector example given above would be represented using the table that the UNPACK routine requires. Experimenter's Guide To Daphne Page 143 User-Functions 3 October 1990 +----------------------------------------------------------------------+ | subroutine unpack (desc,ev,evHead,evEnd,pev,bitVal) | | | | desc - input/integer*2 array of size (5,*) | | describes how to unpack | | the event vector into the pseudo-event vector | | | | desc (1,i) word # in the event vector of the pattern | | register for the "i th" field | | event vector begins at word 1 | | | | desc (2,i) bit # in pattern register of "i th" field | | starts with bit 1 | | must be between 1 and 16 | | | | desc (3,i) number of words to copy from event vector | | to pseudo-event vector when bit is set | | | | desc (4,i) offset (in words) in pseudo-event vector of | | position to place parameters | | pseudo-event vector begins at word 1 | | | | desc (5,i) which element of the "bitVal" vector should | | be set to 1 (or zero) to indicate that an | | optional segment is present (or absent) | | | | list is terminated by negative number in position (1,i) | | | | ev - input/integer*2 vector of size (*) | | event vector | | | | evHead - input/integer*2 | | the number of "header" words before the beginning of the | | first data word (non-pattern word) to be unpacked | | Example: | | if there are two pattern words then evHead=2 | | | | evEnd - output/integer*2 | | the position in the event vector of the last word unpacked | | Example: | | if an event vector consists of 2 pattern words and | | 14 data words (non-pattern words) then evHead=2 and | | evEnd will be set to 16 on exit from the routine | | | | this is especially important when there is more than one | | group of pattern words, and some pattern words must be | | analyzed before the location of the other groups of | | pattern words can be located in the event | | | | pev - output/integer*2 vector of size (*) | | pseudo-event vector | | | | bitVal output/integer*2 vector of size (*) | | records the value of the bit described by a row of the | | "desc" array were | | if field described by desc (*,i) is present then | | "bitVal (desc(5,i))" is set to 1 otherwise set to 0 | +----------------------------------------------------------------------+ Experimenter's Guide To Daphne Page 144 User-Functions 3 October 1990 Note, in particular, that this is an INTEGER*2 array and that the last row of the table contains values of (-1) to indicate to the unpack subroutine that this is the last row. +-----------------------------------------------------------------+ | integer*2 desc (5,10) | | | |c pat bit nwords pseudo bitVal | | | | data desc / 1, 1, 1, 1, 1, | | * 1, 2, 3, 11, 2, | | * 1, 3, 3, 14, 3, | | * 2, 1, 2, 21, 4, | | * 2, 2, 2, 23, 5, | | * 2, 3, 2, 25, 6, | | * 2, 10, 4, 31, 7, | | * 2, 11, 4, 41, 8, | | * 2, 12, 4, 51, 9/ | | * -1, -1, -1, -1, -1/ | | | +-----------------------------------------------------------------+ Since standard Fortran allows only 19 continuation lines, you may want to use the following style of data declaration when there are more than 19 segments to be defined: +-----------------------------------------------------------------+ | integer*2 desc (5,10) | | | |c pat bit nwords pseudo bitVal | | | | data (desc(i, 1),i=1,5) / 1, 1, 1, 1, 1 / | | data (desc(i, 2),i=1,5) / 1, 2, 3, 11, 2 / | | data (desc(i, 3),i=1,5) / 1, 3, 3, 14, 3 / | | data (desc(i, 4),i=1,5) / 2, 1, 2, 21, 4 / | | data (desc(i, 5),i=1,5) / 2, 2, 2, 23, 5 / | | data (desc(i, 6),i=1,5) / 2, 3, 2, 25, 6 / | | data (desc(i, 7),i=1,5) / 2, 10, 4, 31, 7 / | | data (desc(i, 8),i=1,5) / 2, 11, 4, 41, 8 / | | data (desc(i, 9),i=1,5) / 2, 12, 4, 51, 9 / | | data (desc(i,10),i=1,5) / -1, -1, -1, -1, -1 / | +-----------------------------------------------------------------+ If you still find this confusing, you may want to look at the source code for the UNPACK routine. The VAX source code is in DAPTAB:VAXUNPACK.FOR The NS32000 source code is in DAPEP:NSUNPACK.FOR Experimenter's Guide To Daphne Page 145 User-Functions 3 October 1990 24.18 Service Routine UNPACK_HIT UNPACK_HIT is a version of UNPACK which provides extra information when unpacking an event. One use of the routine is to produce histograms of bit patterns. For UNPACK_HIT the description array created by the user is six elements wide rather than five (as with UNPACK). When an optional segment is present in an event, the sixth element of the description array is copied to the corresponding element of the "bitVal" array. In contrast, the plain UNPACK routine would store the value 1 in the "bitVal" array. The value in the sixth element of the description array is the extra information some users need to simply the construction of histograms of bit patterns. When an optional segment is not present in an event both routines store 0. Users who wish to create histograms of detectors which have fired, will place in the sixth element of the row, the detector number corresponding to the bit in the pattern word being tested. A histogram of the appropriate section of the "bitVal" vector will yield a list of detector numbers that fired (or zero if the detector did not fire). By combining this with the /NOZERO qualifier one has an accurate picture of how many times each detector has fired. To examine the source code for the UNPACK_HIT routine: The VAX source code is in DAPTAB:VAXUNPACK_HIT.FOR The NS32000 source code is in DAPEP:NSUNPACK_HIT.FOR Experimenter's Guide To Daphne Page 146 User-Functions 3 October 1990 24.19 Examples 24.19.1 Example 1 - Minimal User Function +------------------------------------------------------------------+ | logical function userIn | | implicit none | | c | | c Initialization Routine | | c Called just once at the beginning of a run | | c Function value is ignored | | c | | c et - (event type) is hardly ever used | | c np - (number of parameters) is hardly ever used | | c ev - the real-event vector is composed of 16 bit integers | | c | | integer*2 et | | integer*2 np | | integer*2 ev (*) | | c | | c the pseudo-event vector is composed of 16 bit integers | | c there is no intrinsic limit to the number of pseudo-parameters| | c in this example the user needs only 30 pseudo-parameters | | c | | integer*2 pev (30) | | c | | c must declare entry point & functions as logicals | | c | | logical user | | c | | c tell the sort program where pseudo-events are located | | c | | call defPEV (pev,pev(30)) | | c | | c end of initialization | | c the function value returned by userIn is ignored | | c | | return | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | | entry user (et,np,ev) | | c | | c called once for each event before any maps, conditions, | | c windows, linearizations, etc. are evaluated | | c it can compute pseudo-parameters | | c | | c only argument is the real event (composed of 16 bit integers) | | c | | pev(1)=(ev(1)+ev(2))/2 | | pev(2)=(ev(1)-ev(2)) | | | | | | | | return | | end | +------------------------------------------------------------------+ Experimenter's Guide To Daphne Page 147 User-Functions 3 October 1990 24.20 Example 2 - USERIN USER and USER1 +------------------------------------------------------------------+ | logical function userIn | | implicit none | | c | | c Initialization Routine | | c Called just once at the beginning of a run | | c Called with single argument giving name of run as string | | c Function value is ignored | | c | | c et - (event type) is hardly ever used | | c np - (number of parameters) is hardly ever used | | c ev - the real-event vector is composed of 16 bit integers | | c | | integer*2 et | | integer*2 np | | integer*2 ev (*) | | c | | c the pseudo-event vector is composed of 16 bit integers | | c there is no intrinsic limit to the number of pseudo-parameters| | c in this example the user needs only 30 pseudo-parameters | | c | | integer*2 pev (30) | | c | | c linearization values can be used in USER1 USER2 ... USER50 | | c routines, but only if the user can be sure they have been | | c evaluated - see the main text for more information | | c | | c note that the linearization vector is composed of 32 bit | | c integers - unlike the event and pseudo-event vectors | | c | | integer*4 lnzVec (*) | | c | | c must declare entry point & functions as logicals | | c | | logical user,user1 | | c | | c tell the location of the pseudo-parameters | | c | | call defPEV (pev(1),pev(30)) | | c | | c end of initialization | | c the function value returned by userIn is ignored by VAXSORT | | c | | return | | c | | | Experimenter's Guide To Daphne Page 148 User-Functions 3 October 1990 | | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | | c | | entry user (et,np,ev) | | c | | c called once for each event before any maps, conditions, | | c windows, linearizations, etc. are evaluated | | c it can compute pseudo-parameters | | c | | c only argument is the real event (composed of 16 bit integers) | | c | | pev(1)=float(ev(1))* | | * float(ev(2)**2) / 1.0e6 | | pev(2)=ev(3)+ev(4) | | c | | c the function value returned by USER is ignored by sort program| | c | | return | | entry user1 (et,np,ev,lnzvec) | | c | | c called once for each event when the condition "USER 1" is | | c evaluated | | c it will not be called if it was preceded by a KILL condition | | c which caused the event to be "killed" | | c | | c it can compute pseudo-parameters based on linearization | | c values if the user has made sure that the linearization has | | c been evaluated - see main text | | c | | c argument 1 is the real event vector (16 bit integers) | | c argument 2 is the linearization vector (32 bit integers) | | c | | pev(3)=lnzVec(1)*1000.0/ev(4) | | c | | c the USER1 USER2 ... USER50 routines (unlike the plain USER) | | c can pass back a logical value to sort program which will be | | c the value of the corresponding condition | | c | | user1=ev(5) .gt. ev(6) | | return | | end | +------------------------------------------------------------------+ Experimenter's Guide To Daphne Page 149 Arithmetic Traps on the Event Processor 3 October 1990 25 Arithmetic Traps on the Event Processor When an arithmetic trap occurs in a user-function executing on an Event Processor, the sort program drops any effort at further analysis of the event, and transfers control to the end of the sorting routine, which copies an event to the tape buffer for later recording. If event mode recording is enabled, the event will be copied to the output tape buffer, unless a NOTAPE condition was found to be true prior to the arithmetic trap. The number of such arithmetic traps is counted by the sort program and the first, 100 th, and 10,000 th cause a message to be sent to the user's command terminal along with specific information to aid in locating the problem. The variable which counts the number of traps is reset at the beginning of each run. The debug information is put in the file "ttt.TRAP" (where "ttt" represents the Daphne User ID) in the default diretory. An example of the trap report from an Event Processor is on the next page. Experimenter's Guide To Daphne Page 150 Arithmetic Traps on the Event Processor 3 October 1990 +--------------------------------------------------------------------+ a | Arithmetic Trap in User Function Integer division by zero | | | b | Event Proc: 2 Date: 17-SEP-87 15:15:58 | | Experiment: Run number: | | Physicist: Target: | | Beam: Energy: | | Comments: | | | | Count of traps: 1 | | Event Type: 3 | c | User "Trap ID": 0 (dec) | | 0000 (hex) | | | | | | Absolute Address PC Relative Address | | (hex) (dec) (hex) (dec) | | ---------------- ------------------- | | | | PC at time of trap: A059 41049 0000 0 | | Address of User Init routine A0C4 41156 FFFFFF95 -107 | d | Address of USER routine: A030 41008 0029 41 | | ^ | | ############ # | | # See Text ###################### | | ############ | | | | ---------- E V E N T D A T A ---------- | | | | Word Hex Dec (Unsigned) Dec (Signed) | | ---- ------- -------------- ------------ | | | | 1 0003 3 | | 2 0000 0 | | 3 0080 128 | | | +--------------------------------------------------------------------+ Experimenter's Guide To Daphne Page 151 Arithmetic Traps on the Event Processor 3 October 1990 I would like to point out some important information provided by this report. - Reason for Arithmetic Trap (line "a") The most common cause is division by zero. The second most common cause is floating point overflow due to assignment of a floating point number larger than 32,767 (or less than -32,768) to a Fortran INTEGER*2 variable, such as an element of the pseudo-event vector. The NS32000, unlike the VAX, does not have an arithmetic trap when an INTEGER*4 variable with a value too large to fit is assigned to an INTEGER*2 variable. The NS32000 simply ignores the most significant bits. - Event Processor Number (line "b") This assists in locating a processor with a malfunctioning floating-point unit. - Trap ID (line "c") The "Trap ID" is a substitute for the subroutine traceback-with-line-numbers provided by many Fortran systems. The GNX development system used by Daphne does have a source code symbolic debugger, but most users appear to prefer debugging programs with PRINT statements. Unfortunately, there are three drawbacks to debugging your Event Processor user-function with PRINT statements: - Memory Limitations The code necessary to support I/O requires too much memory when combined with the very large buffers used in the Daphne acquisition program. This limitation should disappear when the Event Processor memory boards are upgraded from 128 kBytes to 512 Kbytes. - Acquisition Slowed Down The PRINT statements are so slow that the acquisition rate would be practically zero. - Flood of Output Some problems occur only rarely, and the PRINT statement might be executed thousands of times before the problem appeared. Experimenter's Guide To Daphne Page 152 Arithmetic Traps on the Event Processor 3 October 1990 When a user is having difficulty locating the problem in the program, a few extra statements can be added to the code: call trapID (10) call trapID (11) call trapID (12) etc. The trapID routine (Section 1.13) records the value passed to it. It is a quick subroutine call: the body of the subroutine is a single "move word" instruction. +-----------------------------------------------------------------+ | Recommended for Event Processors Only | +-----------------------------------------------------------------+ | subroutine trapID (idWord) | | | | idWord - input/integer*2 | | word to be reported to host computer when | | there is an arithmetic trap | +-----------------------------------------------------------------+ Should an arithmetic trap occur, the trap recovery routine passes the last trap ID number (in the example above: 10, 11, or 12) to the host to be included in the error message, thus identifying the block of code containing the problem. This is not recommended for the VAX because the VAX/VMS symbolic debugger provides a much better tool for isolating problems. Experimenter's Guide To Daphne Page 153 Arithmetic Traps on the Event Processor 3 October 1990 - PC at Time of Trap (line "d") The PC (program counter) is the address of the instruction causing the trap. If your user-function is written as a single subroutine starting with entry point USER or USERIN, it can be relatively easy to locate the instruction causing the problem. Assume, for the purpose of this example, that your user function begins with USER (rather than USERIN). Note the value (in hexadecimal) of the item "PC address relative to the address of USER" (In the example above the value is "0029" at line "d"). If you compile your Fortran program with the "DAPEP:EPBUILD" command procedure, the Fortran compiler will create a file containing the machine code generated by the compiler, interspersed with "comment lines" containing the Fortran code responsible for the machine code which follows it. If you use the Fortran optimizer, the relationship between the Fortran comment lines and the generated machine code may break down because an optimized program will not necesarily perform operations in the same order as a non-optimized program. On the second page following, the lines preceded by "#---" are the Fortran statements inserted as comment lines in the assembler listing. Assume your user function is in the file "ICE.FOR". The assembler source code will have been placed in the file "ICE.ASM" by the Fortran compiler. Assemble the assembler source code with the following command to create a list file "ICE.LIS": $ NASM/LIST ICE Compare the "PC address relative to the the user-function" with the location counter (the number preceded by the letter "T") listed in the second column down the left side of the listing file. When you find a match, look above it to find the Fortran code associated with the machine code. In the following example, the program will produce a division by zero in computing pev(1) when both ev(3) and ev(4) are zero. The PC relative address would be equal to 0018 (the offset of the "quotient" instruction relative to the beginning of the program). This is line 26 of the assembler list file appearing on the second page following. Experimenter's Guide To Daphne Page 154 Original Fortran Program 3 October 1990 +--------------------------------------------------------------+ | subroutine user (et,np,ev) | | implicit undefined (a-z) | | save | |c | | integer*2 et | | integer*2 np | | integer*2 ev (*) | |c | | integer*2 pev (20) | |c | -> | pev(1)=(ev(3)-ev(4))/(ev(3)+ev(4)) | | return | |ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | | entry userin | | call defPEV (pev) | | return | |c | | end | +--------------------------------------------------------------+ Experimenter's Guide To Daphne Page 155 Fortran Annotated Assembly Language Output 3 October 1990 +------------------------------------------------------------------+ | | | | | 9 #--- implicit undefined (a-z) | |10 #--- save | |11 #--- integer*2 et | |12 #--- integer*2 np | |13 #--- integer*2 ev (*) | |14 #--- integer*2 pev (20) | ->|15 #--- pev(1)=(ev(3)-ev(4))/(ev(3)+ev(4)) | |16 .align 4 | |17 _user_ : | |18 T00000000 7ca504 adjspb $(4) | |19 T00000003 eac00000 br .L3 | | 49 | |20 .align 4 | |21 .L4: | |23 T0000000c 21881006 subw 6(16(sp)),r0 | |24 T00000010 55881004 movw 4(16(sp)),r1 | |25 T00000014 41881006 addw 6(16(sp)),r1 | ->|26 T00000018 ce3108 quow r1,r0 | |27 T0000001b 55050000 movw r0,.L6_pev | | 005c | |28 #--- return | |29 T00000021 eac00000 br .L2 | | 23 | |30 #--- entry userin | |31 #### br .L7 | |32 T00000026 a2a2 .align 4 | |33 _userin_ : | |34 T00000028 7ca504 adjspb $(4) | |35 T0000002b eac00000 br .L6 | | 29 | |36 .align 4 | |37 .L7: | |39 T00000030 67ae0000 addr .L6_pev,0(sp) | | 005c00 | | 0000 | |42 T0000003d eac00000 br .L2 | | 07 | |44 T00000042 a2a2 .align 4 | |45 .L2: | |47 T00000044 7ca5fc adjspb $(-4) | |48 T00000047 1200 ret $(0) | | | | | +------------------------------------------------------------------+ The arithmetic trap was caused by the "quow" instruction (quotient for word length operands) appearing at line 26. Please note that the Fortran code appearing at line 15 caused code to be generated for lines 16 through 27. Actually, lines 16 through 20 are subroutine "prologue", and have to do with subroutine initialization, rather than the computation of pev(1). They are automatically generated at the first appearance of an executable Fortran statement. Experimenter's Guide To Daphne Page 156 Compiling and Linking an Event Processor Program 3 October 1990 26 Compiling and Linking an Event Processor Program 26.1 GNX Cross Development Tools Daphne uses a VAX/VMS to NS32000 cross-development package named GNX developed by National Semiconductor for programming the Event Processors. It contains a Fortran-77 compiler, assembler, linker, object code librarian, and source code symbolic debugger. Reference manuals for the GNX assembler, Fortran-77 Compiler, and other utilities are available from the computer staff. A user can add a subroutine written in GNX Fortran-77 or GNX assembler to the standard Event Processor program to compute pseudo-parameters, or modify real parameters, before they are histogrammed or written to tape. The best way to write an Event Processor routine is to use one of the examples in DAPHLP:ACQ_EXAMPLES.MEM as a model. See Section 4.1 ("Related Documentation") for information on how to obtain a copy. Experimenter's Guide To Daphne Page 157 Compiling and Linking an Event Processor Program 3 October 1990 26.2 Differences Between VAX/VMS Fortran and GNX Fortran Below is a list of differences between the the VAX/VMS and GNX Fortran compilers that have caused inconvenience to users: VAX/VMS GNX length of symbolic names 31 characters 24 characters special characters in names "$" and "_" "_" defeat implicit types implicit none implicit undefined (a-z) hexadecimal constants '0001'X X'0001' octal constants '0001'O O'00001' binary constants not implemented B'00001' bitwise AND IAND (I,J) AND (I,J) bitwise OR IOR (I,J) OR (I,J) bitwise complement NOT (I) NOT (I) bitwise exclusive or IEOR (I,J) XOR (I,J) left shift ("S" bits) ISHFT (I,S) LSHIFT (I,S) or RSHIFT (I,-S) right shift ("S" bits) ISHFT (I,-S) RSHIFT (I,S) or LSHIFT (I,-S) comments at end of line precede by "!" not implemented local variables retain always yes if SAVE values at subroutine exit statement used DO statement DO I=1,N extensions no extensions END DO DO WHILE (logical) END DO The compilers are alike in supporting the following extensions or little used features: - INTEGER*2 and INTEGER*4 - REAL*4 and REAL*8 - PARAMETER statement - ENTRY statement - INCLUDE statement - SAVE statement - tab character as method of skipping to column 9 of source code 26.3 Differences in Bitwise Operations One of the most annoying differences between the compilers is that a bitwise "AND" of two INTEGER*2 variables is peformed by the "IAND" function on the VAX, and the "AND" function on the NS32000. You may want to consider using the BIT16 function described in section 24.15 of EG to provide a reasonably efficient and compiler independent method of testing bits in an INTEGER*2 variable. One should avoid using multiply and divide for testing bits since, in general, it will Experimenter's Guide To Daphne Page 158 Compiling and Linking an Event Processor Program 3 October 1990 be significantly slower than using the bit test routines. Experimenter's Guide To Daphne Page 159 Compiling and Linking an Event Processor Program 3 October 1990 26.4 Compiling and Linking Fortran User Routine The default file type for a user routine written in Fortran is ".FOR". Suppose you have created your Fortran routine in file "ICE.FOR". You can compile and link it with the command: $ @DAPEP:EPBUILD Name of user routine: ICE Language [Enter F/FO/A or HELP] HELP F - Fortran without optimization FO - Fortran with optimization A - Assembler Language [Enter F/FO/A or HELP] F This links the user routine with the rest of the Event Processor program to create an NS32000 executable file named "ICE.EXE". Experienced users may want to combine this into a single command line: $ @DAPEP:EPBUILD ICE F /NOANNOTATE ^ ^ ----------- | | ^ | | | | | +--- Optional Fortran | | Qualifiers | | | +--- Select Fortran Language | +--- File Containing User Function This creates the GNX executable file "ICE.EXE" from the "ICE.OBJ" file created by the Fortran compiler. 26.5 Compiling without Linking For those who want to compile their Fortran program without linking you can invoke the compiler with the recommended options by using: $ @DAPEP:EPFORT ICE F /NOANNOTATE ^ ^ ----------- | | ^ | | | | | +--- Optional Fortran Qualifiers | | | +--- Select Fortran Language | +--- File Containing User Function This creates the object file "ICE.OBJ" which can by linked using the command procedure described below. Experimenter's Guide To Daphne Page 160 Compiling and Linking an Event Processor Program 3 October 1990 26.6 Assembling a User Routine The default file type for a user routine written in assembler is ".ASM". Suppose you have created an assembler routine named "BCD_TO_INT.ASM" which converts from binary coded decimal to an integer. You can compile it with the command: $ NASM/LIST BCD_TO_INT The output from the assembler will normally include two files: - Object file with extension ".OBJ" This is GNX NS32000 object that must be processed by the GNX linker - Listing file with extension ".LIS" 26.7 Linking Without Compiling Suppose you want to link together several parts of a user-function which have been compiled separately, say ICE1.FOR, ICE2.FOR, and ICE3.FOR. The following demonstrates the recommended procedure: $ @DAPEP:EPFORT ICE1 F $ @DAPEP:EPFORT ICE2 F $ @DAPEP:EPFORT ICE3 F $ @DAPEP:EPLINK ICE1.OBJ,ICE2.OBJ,ICE3.OBJ The ".OBJ" appearing in the EPLINK command is required. Experimenter's Guide To Daphne Page 161 Use $EPLOAD to Load the Event Processors 3 October 1990 27 Use $EPLOAD to Load the Event Processors Once the Event Processor executable file has been created and you have selected your Multibus using the $MDV command, you can load the Event Processors in a few seconds using the $EPLOAD command. To determine the processors that are normally configured for a Multibus (say Multibus A): $ SHOW LOGICAL DAP$CONFIGURE_EP_A "DAP$CONFIGURE_EP_A" = "123" ^ | +--- Processors 1, 2, and 3 27.1 When Must the Event Processors be Reloaded The Event Processors need to be loaded when you first start Daphne with the $DAP command, or when your user routine has been changed. It is NOT necessary to reload the Event Processors each time you want to start acquisition. 27.2 Loading a User-Written EP Program Suppose you have used the command procedure DAPEP:EPBUILD to create ICE.EXE, a GNX executable file. To download this use the command: $ EPLOAD ICE 27.3 Loading the Standard EP Program When you do not need to compute any pseudo-parameters you can use the vanilla version of the Event Processor program: $ EPLOAD DAPEP:STANDARD Experimenter's Guide To Daphne Page 162 Use $EPLOAD to Load the Event Processors 3 October 1990 27.4 Status Lights When an Event Processor has been successfully loaded and it is waiting for acquisition to start, the three LEDs on the front edge of the board turn off and on in unison about once a second. 27.5 Using a Subset of Event Processors By redefining the logical name DAP$CONFIGURE_EP_x (where "x" represents the Multibus code appearing in the $MDV command) one can control which Event Processors are configured by the $EPLOAD and sorting programs. For instance, the following statement will allow only processors 1,2, and 4 to be configured on Multibus A: $ DEFINE/JOB DAP$CONFIGURE_EP_A "124" To determine the processors that are normally configured for Multibus A: $ SHOW LOGICAL/SYSTEM DAP$CONFIGURE_EP_A Experimenter's Guide To Daphne Page 163 Banner Information 3 October 1990 28 Banner Information Banner information is written to tape at the beginning of a run. Changing the banner information after a run begins does not write any additional information to tape, even at the time the run ends. However, those changes made will show up on the event tape when the next run begins The $BAN command can be used to turn on or off the display of information on the top few lines of the display. $BAN ! turns on display of information $BAN/OFF ! turns off display 28.1 Use $INZ to Specify Banner Information The $INZ command can be used before a run begins to enter information that will be saved on the event mode tape. This information also appears in the output of many programs, and in graphs and plots. The $INZ command displays the current values of each of the banner fields. As the current value of each field is displayed, you have the opportunity to change it using the standard line-editing features of VMS. For instance, the left and right arrow keys move the cursor in the obvious directions. The DELETE key (sometimes labeled DEL or RUB or RUBOUT, and not to be confused with the backspace key labeled BS or BACKSPACE) deletes the character to the left of the cursor. Entering control/A allows one to switch from overstrike mode to insert mode. One can also change just one field at a time using commands listed in the following table. Field Length Command to change (in characters) just this field beam 6 $ BEAM comments 60 $ COMMENT energy 6 $ ENERGY experiment name 20 $ EXP physicist 20 $ PHY run number 6 $ RN target 6 $ TGT 28.2 Use $RN INC to add 1 to the Run Number The $RN command has a feature which makes it easy to add 1 to the run number: code the word "INC" instead of a true run number. $ RN INC This is especially convenient in command files which an experimenter might use at the beginning or end of each run. Experimenter's Guide To Daphne Page 164 Use $ACQ to Start Acquisition 3 October 1990 29 Use $ACQ to Start Acquisition To start acquisition: $ ACQ If you restart acquisition too soon after entering $STP, you may receive the error message "%SYSTEM-F-DUPLNAM, duplicate name". If you should receive this message, wait for 5 to 30 seconds and try issuing the $ACQ command again. When the acquisition program exits, the operating system requires anywhere from a few seconds to a minute to write all the histograms which have been modified back to disk from memory. During this period, the acquisition program appears to have been deleted, but the operating system still forbids any process to be created with the same name. When you enter the $ACQ command the following actions take place: - If taping is enabled, the tape subprocess is told that a new run is beginning. - If scalers are defined, a subprocess is created to read them out. - The scaler subprocess, if present, zeroes the scalers (Unless the /KEEP qualifier is coded in the $ACQ command). - The NSSORT acquisition subprocess is started. - NSSORT checks that the Multibus channel is working properly. - The TABGEN program is run which checks the map, window, condition, linearization, and histogram definitions for consistency and reasonableness. - If TABGEN finds no serious errors, it generates information for NSSORT describing how and what the user wants sorted. - The NSSORT program examines the information generated by TABGEN and creates executable machine code for the Event Processors. - The NSSORT program starts the Event Handler by sending an instruction to the NIM output register to turn on the three least significant bits (bits 1, 2, and 3). Bit 1 is is connected to the Event Handler front panel input 8. - The Event Handler senses that front panel input 8 is now "1" and calls the user's Event Handler initialization routine. - The Event Handler clears the BUSY latch allowing the acquisition equipment to accept new events. - The NSSORT program sends a message to each of the Event Processors telling them that it is ready to download new sorting instructions. Experimenter's Guide To Daphne Page 165 Use $ACQ to Start Acquisition 3 October 1990 - The Event Processors that receive the message send a reply asking for the sorting instructions to be downloaded. - When NSSORT receives the request for sort instructions from an Event Processor, it downloads the code to that Event Processor. - When an Event Processor receives the sorting instructions, it waits for the first buffer of data from the EP FIFO and proceeds to sort it. Experimenter's Guide To Daphne Page 166 Use $STP to Stop Acquisition 3 October 1990 30 Use $STP to Stop Acquisition To stop acquisition: $ STP When you enter the $STP command the following actions take place: - The $STP program sends a message to the NSSORT subprocess saying that the user wants to stop acquisition. - The NSSORT program acknowledges the message from $STP - When $STP receives the acknowledgement from NSSORT, it issues a Camac command to the NIM output register clearing the three least significant bits (bits 1, 2 and 3). Bit 1 is connected to the Event Handler front panel input 8. - The Event Handler senses that front panel input 8 is now logic "0" and sets the BUSY output to "1". If the user has set up his triggering logic properly, this should prevent the acquisition hardware from accepting any new events. - The Event Handler generates 128 zero length events and then goes into an idle mode, waiting for acquisition to start again. A zero length event is an event with no data, just the end-of-event sentinel. - The zero length events percolate through the Kinetic Systems FIFO and into the EMUX. - Eventually an Event Processor asks for additional events and the EMUX gives some or all of the zero length events to it to sort. - The Event Processor input routine recognizes the zero length events as an indicator that acquisition is to stop. It sends a message to the NSSORT program reporting the zero length events. - The NSSORT program sends a message to all the Event Processors telling them that acquisition has stopped. - Each Event Processor sends any partially full buffers of INC data or tape data to NSSORT. - Each Event Processor sends a "DONE" message to NSSORT saying that it is finished sorting. The Event Processor returns to an idle mode waiting for acquisition to start again. Experimenter's Guide To Daphne Page 167 Use $STP to Stop Acquisition 3 October 1990 - When NSSORT has received a "DONE" message from all the active Event Processors it sends a message to the scaler program, if active, telling it to read the scalers one last time. The NSSORT program also sends a message to the tape output process, if event mode taping is enabled, telling it that acquisition has stopped. - The NSSORT program tells the user the run time in minutes and then exits. - The $STP program recognizes that the NSSORT subprocess has stopped and itself exits. - The tape output program, if active, waits for the scaler program, if active, to read the scalers one last time. It then writes the scaler information to tape. - The tape output program, if active, writes out two file marks and then backspaces one file mark. Under normal circumstances the NSSORT program will wait about 10 seconds for an Event Processor to report that is has found a zero length event. If none is found in that time interval, the program tells the user that it can't stop because it hasn't received the "end-of-data sentinel". When the /FORCE qualifier is used with the $STP command the NSSORT program will wait just as long for the zero length events to be reported. However, when no zero length events are encountered it will force acquisition to stop just the same, by sending messages to the Event Processors to stop acquisition. Experimenter's Guide To Daphne Page 168 What Happens at the End of a Tape ? 3 October 1990 31 What Happens at the End of a Tape ? When the tape output subprocess reaches the reflective strip that indicates that the end of the tape is near, the tape output process temporarily stops writing event data. - If scalers have been defined, the scaler information is written to tape - Two end-of-file marks are written - The tape is rewound and unloaded from the tape drive - The user receives a message at the command terminal requesting that he mount a new tape - If the $TAPE/OUT command specified just one tape drive, the tape process alternately (a) attempts to use the tape and (b) checks to see if the user has entered the $STP command. - If the $TAPE/OUT command specified two drives, the tape output process switches to the second drive immediately, even while the first drive is rewinding. - If the user enters $STP while the the tape process is waiting for a new tape to be loaded, the tape process abandons its attempt to use the new tape and discards any event data that has arrived since the end of volume was detected. Data is discarded ONLY when the user enters $STP while the tape output process is also waiting for a new tape. - Once a new tape is ready, whether using one or two tape drives, the tape output program begins writing the information that customarily appears at the start of a run, including the current value of the scalers, at the beginning of the tape. - Following the banner information, any pending event data is written out. Since all event data is saved while waiting for the user to mount the new tape (unless the user enters the $STP command), it is possible that all the data buffers will be filled. Depending on the data rates, this could take anywhere from a fraction of a second to hours. First the buffers in the host computer fill. Then the buffers in the Event Processors fill. Then the Event Processor FIFOs fill. Then the Kinetic System Camac FIFO fills to the 3/4 FULL level. When the Event Handler detects that the Kinetic Systems FIFO is 3/4 FULL, it asserts the Event Handler BUSY signal. If the user has set up his trigger logic properly, this will prevent any new events from being accepted by the acquisition hardware. Experimenter's Guide To Daphne Page 169 Using Daphne to Display Data 3 October 1990 32 Using Daphne to Display Data There isn't much to be said about the display programs that isn't in the HELP files. The last section of this manual is two lists of Daphne programs: one by subject and one alphabetically. One of the subject categories is display programs. There are two versions of the display programs: one for Tektronix 4107/4111/4115 color display terminals (called D4100) and one for the Tektronix 4010 and compatible terminals (called DSPDP). 32.1 $D1H The $D1H command displays 1D histograms. $ D1H TOF1,TOF_CORR The qualifiers are: - /LOW=number to set the lowest numbered channel to display - /HIGH=number to set the highest numbered channel to display - /SCALE=number to set the scale of the vertical axis - /RESET to reset /LOW and /HIGH to the first and last channels - /AUTO automatic scaling to undo the effects of /SCALE The vertical axis will be scaled to the largest channel value. - /LOG for logarithmic scaling - /LIN for linear scaling For example, to see channels 705 through 900 of histogram TOF with logarithmic scaling: $ D1H TOF /LOW=705 /HIGH=900 /LOG The D4100 version can display 25 1D histograms at a time, while the DSPDP version can display up to 6 at a time. Experimenter's Guide To Daphne Page 170 Using Daphne to Display Data 3 October 1990 32.2 $D2H The $D2H command displays 2D histograms. $ D2H ANODE The qualifiers are: - /XLOW=number to set the lowest numbered channel to display /YLOW=number - /XHIGH=number to set the highest numbered channel to display /YHIGH=number - /SCALE=number to set the scaling of the Z or color axis - /RESET to reset /XLOW /XHIGH /YLOW /YHIGH to the first and last channels - /AUTO automatic scaling to undo the effects of /SCALE The Z or color axis will be scaled to the largest channel value. - /LOG for logarithmic scaling /LIN for linear scaling /SQRT for square root scaling For example, to see X channels 10 through 390 and Y channels 110 through 400 of histogram PEV2-DYN with logarithmic scaling: $ D2H PEV2-DYN /XLOW=10 /XHI=390 /YLO=110 /YHI=400 /LOG The D4100 version can display 25 2D histograms at a time, while the DSPDP version can display up to 4 at a time. Experimenter's Guide To Daphne Page 171 Using Daphne to Display Data 3 October 1990 The DSPDP version is capable of displaying 2D histograms using three dimensional projections: - /MESH A grid is superimposed on the X-Y plane. The height of each point in the grid is based on the number of counts at the X-Y coordinate located below the grid point. - /GEOMETRIC Bars are drawn whose height are based on the number of counts at the X-Y coordinate at the base of the bar. - /ISOMETRIC=X /ISOMETRIC=Y Similar to the mesh plot above, but only grid lines parallel to the x-axis (or the y-axis) are drawn. - /POINTS Similar to the mesh plot above but no grid lines are drawn. The following qualifiers can be used only with the three dimensional types of plots mentioned above: - /ROTATION=degrees [Between -180 and +180] Specifies the rotation of the viewpoint about the Z axis. - /INCLINATION=degrees [Between 1 and 89] Specifies the angle of view above the X-Y plane. - /BINNING=number [Between 1 and number of channels] Reduces the number of channels actually displayed. For instance, a mesh plot with a binning factor of 2 reduces the number of lines drawn by a factor of 4 (a factor of 2 in the X direction and a factor of 2 in the Y direction). Use /NOBIN to disable binning. - /AVERAGING=number [Between 0 and 10] This smooths the data by averaging a channel value with its nearest neighbors. A value of 1 uses the 8 nearest neighbors. A value of of 2 uses the 24 nearest neighbors. Use /NOAVERAGE to disable averaging. Experimenter's Guide To Daphne Page 172 Using Daphne to Display Data 3 October 1990 32.3 Use $BLW to Expand Scales and Get Channel Values The $BLW program ("Blowup") allows you to use graphics input to select the region of a 1D or 2D histogram to expand in scale. It can perform other functions using graphics input, such as giving the number of counts and the channel number of a channel selected with a cross-hair. 32.4 Use $SUM to Integrate Regions The $SUM program can sum the counts in a region of a 1D or 2D histogram, including allowance for simple background subtraction. The range of channels can be selected by graphics input or by entering the coordinates from the keyboard. 32.5 Use $CUR to Display Cross-Hair Sometimes it is useful to to compare the position of peaks in a series of histograms which are arranged vertically. Experimenter's Guide To Daphne Page 173 Using Daphne to Display Data 3 October 1990 32.6 Projections Strictly speaking, the projection programs $PJX and $PJY are not display programs. The $PJX program sums a 2D histogram along vertical lines into an existing 1D histogram. The region of summing can be selected using the /YLOW and /YHIGH qualifiers or by using a 2D window which has been previously defined. The $PJY program has the same capabilities, but the sum is along horizontal lines, and the qualifiers are named /XLOW and /XHIGH. $PJY Original 2D Histogram +--------+ +----------------------------------+ | | | | |--+ | | ......... | | | | | ......... | | +--+ | | ....................... | | | | | ....................... | |-----+ | | | +--------+ +----------------------------------+ +----------------------------------+ | +-------+ | | | | | | +--+ +----------+ | | | | | +----------------------------------+ $ PJX The projection commands assume that the 2D histogram currently displayed is the source of data unless you use the /FROM qualifier. The name of the 1D histogram must be given in the command. The 1D histogram is cleared to zero before beginning the projection unless the /NOZAP qualifier is used. $ H1 1024 /NAME=PROJ $ PJX PROJ Sum the currently displayed 2D histogram by columns. The sum of column "i" is put into channel "i" of 1D histogram PROJ. $ PJY PROJ /FROM=MASS_LINES /W2D=GOOD Sum the 2D histogram MASS_LINES along rows. The sum of row "i" is put into channel "i" of 1D histogram PROJ. Only channels inside the window GOOD are counted $ PJX /W2D=TYPE1 PROJ $ PJX /W2D=TYPE2 PROJ /NOZAP $ PJX /W2D=TYPE3 PROJ /NOZAP The counts falling in three different windows are summed into a single 1D histogram. Experimenter's Guide To Daphne Page 174 Scatterplots 3 October 1990 33 Scatterplots NOTE Scatterplots are implemented only for the Tektronix 4107/4111/4115 color terminals. Scatterplots do not allow an event type argument (January '88). The general idea behind Daphne scatterplots is that the scatterplot is like a magic-slate or scratchpad, which can be used over and over again for drawing different things. All scatterplot commands can be issued even while a scatterplot is displayed and acquisition is active. Scatterplots in Daphne are more like 2D histograms than traditional scatterplots: - They can be removed from the screen and later redisplayed - On redisplay one can zoom-in or zoom-out - They use colors - They require disk space - They require memory space when active A scatterplot can take up the entire screen, or the screen can be divided into quadrants, with one scatterplot per quadrant. The screen positions are named: - C - center (full screen) - TL - top left - TR - top right - BL - bottom left - BR - bottom right 33.1 Bins versus Channels Scatterplots make a distinction between channel numbers used for parameters and the number of "bins" or "cells" in a histogram. For instance, a scatterplot with 1000 bins in the X direction could contain channel numbers from 1000 to 2000 with one channel per bin, or channels 1000 to 9000 with 8 channels per bin. Of course, in the second case there would be a loss of resolution. Bin numbers always begin at zero and extend to the number of bins less 1. Channel numbers can begin at any reasonable value. Experimenter's Guide To Daphne Page 175 Scatterplots 3 October 1990 33.2 Defaults and Defaults**2 When Daphne is first started, it assumes that new scatterplots will have 800 bins along both the X and Y axis, and the usual range of channel numbers will be 0 to 2048. If these are unacceptable they can be changed when the scatterplot is created or the defaults themselves can be changed using the $SP/DEFAULT command. For instance, if your experiment (a) uses ADCs which have a range of 0 to 8192 (b) you want to avoid displaying channels less than 5 because they are usually due to noise, then it might make sense to issue the following command when you first start Daphne: $ SP/DEFAULT /XHI=8200 /YHI=8200 /XLO=5 /YLO=5 The default number of bins in a scatterplot is controlled by the /XBIN and /YBIN qualifiers. The $SP/DEFAULT command does not change any existing scatterplots only newly created scatterplots. 33.3 Use $SP/CREATE to Create a Scatterplot To create a scatterplot with the default number of bins and default range of channel numbers (0 to 2048 in both the X and Y axis): $ SP/CREATE A Suppose you want a very large scatterplot with default channel numbers of zero to 8192: $ SP/CREATE B /XBINS=1000 /YBINS=1000 /XHI=8192 /YHI=8192 Creating a scatterplot only allocates disk space for it. It is still necessary to tell what parameters are to be displayed. Experimenter's Guide To Daphne Page 176 Scatterplots 3 October 1990 33.4 Use $SP to Display a Scatterplot This command tells Daphne what parameters, pseudo-parameters, 1D-Maps, or linearization values are to be displayed on each axis of the scatterplot. The scatterplot is zeroed before being displayed. If an argument is omitted it defaults to the previous value, if there is one. Some examples: $ SP A 1 2 Scatterplot A with real parameter 1 vs. real parameter 2. Default range of channels $ SP A /TITLE="Residue 1" /XAXIS=Time /YAXIS=Energy Same data as before, but with annotation $ SP A 1/PSEUDO 2 Scatterplot A with pseudo-parameter 1 vs. real parameter 2. Default range of channels $ SP B 1/MAP 4/MAP /XLO=100 /XHI=500 /YLO=4 /YHI=400 Scatterplot B with 1D Map 1 vs. 1D Map 4 $ SP C 1/LNZ 14/PSEUDO /XHI=1000 /YHI=1000 Scatterplot C with linearization 1 vs. pseudo-parameter 14 $ SP A/TL Display scatterplot A in the top left quadrant Use previous choice of parameters or whatever Use previous range of channels $ SP A Display scatterplot A in the center Use previous parameters and channels To redisplay a scatterplot without clearing it use $SP/ZOOM. 33.5 $SP/ZOOM to Zoom-In or Zoom-Out The zoom command allows a user to change the portion of an exisiting scatterplot which is displayed. Even if only a small corner of a scatterplot is displayed, the entire scatterplot continues to be updated in memory. $ SP/ZOOM A/TL /XLO=100 /XHI=500 Redisplay scatterplot A in the top left corner Display X channels between 100 and 500 only Display the same range of Y channels as at present $ SP/ZOOM B/C /RESET Redisplay scatterplot B in the center (full screen) Display the entire range of X and Y channels Experimenter's Guide To Daphne Page 177 Scatterplots 3 October 1990 33.6 $SP/LIST to Get Information About Scatterplots This command will accept a list of scatterplots. 33.7 $SP/MODIFY to Change Attributes The /XLO /XHI /YLO and /YHI attributes of a scatterplot (which give the number of channels) can be changed with the $SP/MODIFY command. Also the /TITLE, /XAXIS, and /YAXIS annotation can be changed using $SP/MODIFY. In contrast, the number of bins in a scatterplot cannot be altered once it is created, short of deleting it and recreating it with the desired number of bins. This command will accept a list of scatterplots. 33.8 $SP/COPY to Duplicate a Scatterplot The $SP/COPY creates a new scatterplot which is identical to the original scatterplot in all but name. Scatterplot shape, data, and all attributes are inherited from the original scatterplot. $ SP/COPY XY XY_RUN3 33.9 Other Scatterplot Commands The following scatterplot commands all accept a list of scatterplots and interpret an empty list as meaning ALL scatterplots (and ask for confirmation). - $SP/DELETE to delete scatterplots - $SP/RESUME to allow a scatterplot to be updated when displayed - $SP/SUSPEND to prevent a scatterplot from being updated when displayed - $SP/ZAP to zero a scatterplot Experimenter's Guide To Daphne Page 178 Scatterplots 3 October 1990 How do Daphne scatterplots differ from histograms ? - Out-of-Sight Out-of-Mind Data is recorded in a scatterplot only when the scatterplot is displayed. Data recorded in histograms is accumulated even when a histogram is not being displayed. - Memory Requirements Daphne scatterplots require 25% of the memory of a 2D histogram with the same number of bins created with /BYTES=2 . - Data Rates The number of scatterplot points that can be displayed per second is limited by the display terminal and its I/O bandwidth to the computer. Daphne can display roughly 50 scatterplot points per second. The number of histogram points that can be accumulated per second is limited by the speed of the acquisition system and its I/O bandwidth, which is roughly 500 kilobytes/second: about two orders of magnitude faster than a terminal port. - Ease of Interaction vs. Efficiency Daphne scatterplots commands are designed so that they can be issued, changed, or cancelled while acquisition is in progress. They have traded efficiency for ease of interaction. Histogram definitions cannot be changed while acquisition is in progress. Histograms are optimized for efficiency rather than ease of interaction. - Information Displayed Daphne scatterplots use 16 colors to give an ESTIMATE of the number of counts a given cell would have, were it counted exactly. A scatterplot cell can hold numbers between 0 and 15. For fewer than 7 counts in a cell, the scatterplot contains the exact number of counts in that cell. When it is necessary to increment a cell that already has 7 counts, the program computes the greatest power of 2 which is a divisor of the total number of counts in the entire scatterplot, and uses that as a basis to compute the new cell value (assuming that it is greater than the previous value). If the total number of counts in the scatterplot happens to be: Experimenter's Guide To Daphne Page 179 Scatterplots 3 October 1990 Multiple of 1024 (or greater) - Use 15 Multiple of 512 - Use 14 Multiple of 256 - Use 13 Multiple of 128 - Use 12 Multiple of 64 - Use 11 Multiple of 32 - Use 10 Multiple of 16 - Use 9 Multiple of 8 - Use 8 Otherwise - Use 7 The result is a quasi-logarithmic effect. Because histograms accumulate data, they can usually be displayed in a way that provides more information. For instance, the Tektronix 4115 display can be used to show a histogram using colors to indicate how many times a bin has been hit. The range of values which are assigned colors can be played with to bring out features of interest. - Completeness Only a limited amount of scatterplot data is generated. The designers of the acquisition system decided that no more than about 500 vectors per second can be usefully displayed. Because generation of scatterplot data is more time consuming than generation of histogram data, it was decided to limit the number of scatterplots points generated in any one-second period. When this threshold is reached no more scatterplot data is generated for the remainder of that second. The only limit on the amount of histogram data generated, is the limitation of the acquisition system itself. No histogram data, once generated, is ever thrown away - never never never! - Keystrokes The word "scatterplots" has 12 letters, whilst the word "histograms" has only 10. Experimenter's Guide To Daphne Page 180 Using SAP (Spectrum Analysis Program) 3 October 1990 34 Using SAP (Spectrum Analysis Program) The Spectrum Analysis Program was written by Flemming Videbaek of Argonne National Lab while at the Niels Bohr Institute. The main advantage of SAP over Daphne is its greater complement of features. Like Daphne, it can display both one dimensional and two dimensional spectra. A Daphne histogram is called a "spectrum" in SAP. Some of the features which make SAP pleasant to use are the following: - SAP can display Daphne histograms while acquisition is active. - SAP displays up-to-date information from the very same source that Daphne display programs use. - SAP fully exploits the color capabilities of the 4100 series terminals - SAP makes good use of the graphics input capabilities of terminals to position markers, define regions of interest, and to select points of interest in a spectrum. - The user can perform simple arithmetic operations on entire spectra such as sum, difference, and divison. The results of the operation can then be saved as a separate spectrum. - The user can perform background fits. - The user can define new scales. For instance, the user can specify through graphic input that the abscissa of one peak corresponds to 4.05 MeV and the abscissa of another peak corresponds to 4.32 MeV. SAP can then display on request the linearly interpolated values of other points on the X axis. - SAP can display many one dimensional spectra in a ladder-like arrangement and perform some operations on all the spectra with a single command. For example, integrate all the spectra between channel 57 and 63. - SAP supports command procedures with parameter substitution so that often repeated, long, complex, command sequences can be put in a file and executed with a single command. - SAP can use symbols to replace long commands with a single word - SAP has a built-in HELP facility Experimenter's Guide To Daphne Page 181 Using SAP (Spectrum Analysis Program) 3 October 1990 There are two main disadvantages to SAP: - SAP uses numbers rather than names to refer to spectra. Thus, the "display spectrum" command will look like ">display sp,b4" rather than the Daphne command "$D2H E_ET". (Daphne can also use numbers to refer to histograms). - Although a special effort was made to make SAP and Daphne work together, the joining is not seamless. To use SAP with Daphne requires some extra work. Fortunately, the extra work amounts to about 5 commands, which need be issued on average about once per session. This section of the Experimenter's Guide is not meant to be a guide to SAP, but simply an outline of how to use SAP with Daphne. A complete document describing SAP, along with an index, is available on-line at the main VAX in Physics (node PHYA::). The following command will print the file on the default printer: $ PRINT/NOFEED DAPHLP:SAP.MEM Experimenter's Guide To Daphne Page 182 Using SAP (Spectrum Analysis Program) 3 October 1990 34.1 Once Per LOGIN The first time you wish to use SAP after logging in you must issue the following command to define symbols and logical names: $ @DAPSAP:SAPASSIGN If you use SAP regularly, you may want to place this in your CONFIG.COM or LOGIN.COM file. Usually, the execution of this command file will automatically define the graphics device which SAP is to use. If you want to know the graphics device assigned by the SAPASSIGN.COM command file, use the following VMS command: $ SHOW LOGICAL TEKTRONIX When SAP starts, it translates the logical names "TEKTRONIX" in order to locate the graphics terminal and determine its type. For instance, this VMS command tells SAP that the graphics terminal is at port "TXD7:" $ DEFINE TEKTRONIX TXD7: Once SAP successfully translates the logical name "TEKTRONIX", it tries to translate the logical name "TEKTRONIX_MODEL" which gives the type of the graphics device. The following devices are supported: Model Code Tektronix 4115 TK4115 Tektronix 4114 TK4114 Tektronix 4107A TK4107 Tektronix 4111 TK4111 Tektronix 4010/4014/4015 and similar terminals TK4010 Digital Equipment VT240 emulating a Tektronix 4010 VT240 For instance, this VMS command tells SAP that the graphics device is a Tektronix 4115: $ DEFINE TEKTRONIX_MODEL TK4115 If the logical name is undefined, SAP will ask you to enter the device type. Experimenter's Guide To Daphne Page 183 Using SAP (Spectrum Analysis Program) 3 October 1990 34.2 Each time SAP is Started SAP runs as a separate process largely independent of Daphne. Both Daphne and SAP can be simultaneously active, although only one program can use the same display device at any one time. To start SAP use the following command: $ START_SAP SAP will then print a welcome message. At this point SAP does not know what spectra you wish to use, or even that you intend to use it with Daphne. The SAP command ">connect" is used to tell SAP where to locate spectra, but this is best postponed until some Daphne spectra have been defined. 34.3 When Daphne Histograms Are Defined Or Changed Once your Daphne histograms have been defined, it is necessary to build a SAP spectrum catalog where SAP can store the additional information it maintains on spectra. The following command builds two catalogs: one for one dimensional histograms (named DAP1D) and a second for two dimensional histograms (named DAP2D): $ MAPTODAP This command needs to be reissued only when Daphne histograms have been deleted, or new histograms have been created which you want to refer to from SAP. The $MAPTODAP command creates four files: DAP1D.SPC, DAP1D.SPS, DAP2D.SPC, and DAP2D.SPS. It does NOT make copies of the histograms. SAP gets the histogram data from the very same sources that Daphne display programs do: the information that SAP displays is just as current and up-to-date as possible. 34.4 Connect to the Daphne Histograms The following commands tell SAP the name of the spectra catalogs and gives a single character prefix to associate with each catalog: > connect prefix,a file,dap1d > connect prefix,b file,dap2d One drawback to SAP is that it uses only numbers to refer to spectra, not names. Thus, to refer to the first, second, and third one dimensional spectra, one would use the expression "a1,a2,a3". Experimenter's Guide To Daphne Page 184 Using SAP (Spectrum Analysis Program) 3 October 1990 34.5 Returning Control to Daphne from SAP If you are using SAP, and wish to return temporarily to Daphne, there is no need to exit SAP. Issue the SAP command: > attach This does not release the graphics terminal. If you wish to release the graphics terminal temporarily: > graph off When you leave SAP by using the ">attach" command, all your definitions remain active, including the ">connect" commands you used to define your Daphne spectra. This can cause problems if you use the Daphne command "$RD/REPLACE". When you intend to use $RD/REPLACE, you must either exit from SAP using the ">exit" command, or issue the following commands to disassociate SAP from the Daphne histogram directories: > deconnect file,dap1d > deconnect file,dap2d This same kind of problem shows up when one exits from Daphne and attempts to restart it while SAP is still active. NOTE When one intends to exit and restart Daphne one should also exit SAP. 34.6 Returning Control to SAP from Daphne If you are using Daphne, and and wish to return temporarily to SAP there is no need to restart SAP if you previously left SAP by using the ">attach" command. The following command resumes SAP: $ RETURN_TO_SAP If you had released the graphics terminal from SAP, you can now reallocate it using the command: > graph on Experimenter's Guide To Daphne Page 185 Using SAP (Spectrum Analysis Program) 3 October 1990 34.7 Arithmetic Operation on Spectra It is possible to manipulate and create new spectra within SAP, for instance, as a result of adding spectra. In order to create and save these synthetic spectra, a spectrum file must be created BEFORE using SAP. In the example below, a spectrum file named "ICE" with room for 100 entries has been created. (There is an advantage in creating spectrum files with the name "SPECTRA" because SAP automatically looks for a spectrum file of that name when it starts.) +------------------------------------------------------+ | $ crspfile | | This program will create a spectrum file | | It will be made in this directory | | First give the name of the file | | e.g. spectra or sisisexp | --> | specfile: ICE | | Give now the maximum number of spectra which | | you are likely to have in a spectrum file | | A spectrum file can have a max size of 40000 block | | so it is unlikely that you need more than about | | 300-500 entries | --> | catalog entries: 100 | | files created | +------------------------------------------------------+ The $CRSPFILE command shown above created three files: ICE.SPS, ICE.SPH and ICE.SPC - all of which are required for proper operation on spectra files. To use an existing spectrum file from within SAP you must first execute a ">connect" command: > connect file,ice pre,t write ^ ^ ^ ^ ^ | | | | | +-+--+ +-+-+ +--- write access to spectrum file ^ ^ allows update | | omit if read-only access desired | | | +--- use the letter "t" as prefix | thus spectra named: t1,t2,t3 ... | any unused letter okay | +--- the spectrum file is named "ICE" must be initialized by $CRSPFILE command If you have a spectrum file named "SPECTRA" in your current directory, SAP automatically issues the following command on your behalf: > connect file,spectra pre,s write Experimenter's Guide To Daphne Page 186 Using SAP (Spectrum Analysis Program) 3 October 1990 To perform an arithmetic operation, such as addition of two Daphne 1D spectra to create a new spectrum, use a command such as the following: > arit add,a1,a12 save,t ^ ^ ^ ^ | | | | +-+-+ +-+-+ | | | +--- save result in spectrum file | with prefix "t" | +-- add Daphne 1D histograms 1 and 12 assumes ">connect prefix,a file,dap1d" executed earlier Experimenter's Guide To Daphne Page 187 Improving Throughput 3 October 1990 35 Improving Throughput With Daphne, the problem is generally one of I/O bandwidth, not CPU power. In estimating throughput there are three key numbers: - The bandwidth between the Multibus and the VAX is about 450 kBytes/sec - Each time a histogram bin must be incremented, 6 bytes must be transmitted through the Multibus to the VAX. - Each parameter that must be recorded on tape requires 2 bytes to be tranmitted through the Multibus to the VAX. 35.1 Is Multibus/Unibus Link Saturated One can determine whether the Multibus/Unibus interface has reached its bandwidth limit by watching the third (counting from top to bottom) of the four red LEDs on the top front edge of the Event Processor board. The third LED is turned on by the Event Processor when it is waiting to tranfer data to the VAX over the Multibus/Unibus link. 35.2 Data Rates to Tape The rate at which the DEC TU78 can record data depends on the block size and the density. Generally the TU78 is only a factor when recording at 1600 bpi or with small data blocks. At the default block size of 12 kBytes the maximum data rate at 6250 bpi is about 550 kBytes/sec. At 1600 bpi the maximum data rate is about 160 kBytes/sec. 35.3 Histogram Increments If events are not being recorded on tape, then the full Multibus to VAX bandwidth is available for INC data. This limits the number of times per second a histogram bin can be incremented to (450,000/6) or about 75,000 times/sec. Experimenter's Guide To Daphne Page 188 Improving Throughput 3 October 1990 35.4 Avoid Inefficient Program Constructs - To zero an INTEGER*2 array When programming the Event Processors, use the ZEROI2 subroutine (Section 24.14) to zero a large INTEGER*2 array, such as the pseudo-event vector. It will be much faster than a Fortran "DO loop". The GNX Fortran cross-compiler does not exploit the special instructions on the NS32000 which can clear an area of memory quickly. - Do NOT use multiply/divide for bit manipulation For manipulating bits on the Event Processors, use the operators described in section 26.2: AND, OR, LSHIFT (left shift), and RSHIFT (right shift). Using multiply and divide for bit operations is an order of magnitude slower. 35.5 The $ONEFN Command vs. the ONEOFN Condition Do not confuse the $ONEOFN command with the ONEOFN condition. The $ONEOFN command causes Daphne to analyze only one event out of every "N" events. - For N-1 events out of N events The events which are NOT analyzed are copied to the tape output buffer, if taping is enabled. If no tape is mounted, or event mode recording is not enabled, these events are lost. The event is NOT passed to the user-function, is NOT tested against conditions, and is NOT histogrammed. It does not pass GO, and does not collect $200. - For 1 event out of N events The one event out of every "N" which is analyzed is processed "normally" as described in section 5.11 The value of "N" can be changed without stopping acquisition. In contrast, the ONEOFN condition is evaluated as part of condition evaluation, and thus is evaluated AFTER the USER entry point of the user-function has been called. The value of "N" appearing in the condition cannot be changed during acquisition. However, the ONEOFN condition gives the user more control over which kinds of events are analyzed. For instance, one could suppress analysis of 95% of events outside a window, something which is not possible with the $ONEOFN command. Experimenter's Guide To Daphne Page 189 Improving Throughput 3 October 1990 35.6 Event Data One extreme is when you want to tape everything, but analyze only a small fraction of the events, say 1 out of 20, in order to maximize the amount of bandwidth available for recording events on tape. The following command accomplishes this goal, but bypasses the user-function for unanalyzed events, so there is no control over which events will be analyzed and taped, and which events will be taped without analysis: $ ONEOFN 20 Using the $ONEOFN command, the Event Processors can deliver 450 kBytes/sec of event data to the VAX for recording on tape. 35.7 Analyze Only Interesting Events If you are not taping events, there is no point in trading off INC data against event data. Sometimes one can exploit the fact that certain events are not of real interest. If 50% of the events are uninteresting, perhaps because they represent alpha particles, then twice as many raw events could be processed before the bandwidth became saturated. In this case the KILL condition would be useful to terminate analysis of alpha particle events at an early stage. In the example below, a 2D window (ALPHAS) has been drawn around the region which should be excluded from further analysis: Conditions: NOT_USEFUL: IN2 ALPHAS IGNORE: KILL NOT_USEFUL Experimenter's Guide To Daphne Page 190 Improving Throughput 3 October 1990 35.8 Interactions Between KILL and User-Defined Functions Sometimes a large percentage of the events are "uninteresting", and you wish to skip them as quickly as possible. The strategy to use depends on what must be computed in order to know whether an event is to be rejected or not. It might be necessary to call the user-defined function in order to compute a pseudo-parameter or evaluate a condition which can't be expressed in Daphne. On the other hand, Daphne may be required because the decision to reject depends on evaluation of a 2D window or a linearization, things which are difficult for a user-defined function to do. - No User-Defined Function Present Suppose one wants to reject events that have a map TIME outside a 1D window (already defined) named OK_TIME: Conditions: NOT_OK: OUT1 OK_TIME REJECT: KILL NOT_OK - User-Defined Function Present but NOT Required to Reject This case is different from the previous one because one wants to postpone evaluation of the user-defined function until after the event is known to be interesting. By definition, the USER routine is called BEFORE any conditions are evaluated, while the USER-n routines are called DURING condition evaluation. As a result, your computation should be placed in a USER-n routine (say USER1) while the USER routine should be omitted altogether. Suppose one wants to reject events that have parameter TIME outside a 1D window (already defined) named OK_TIME: User Function USER: Do not code User Function USER1: Compute pseudo-parameters Conditions: NOT_OK: OUT1 OK_TIME REJECT: KILL NOT_OK USER 1 Experimenter's Guide To Daphne Page 191 Improving Throughput 3 October 1990 - Only User-Defined Function Required to Reject In this case you have a choice of placing the computation in the USER function, or the USER-n function. If you want to place the decision in the USER function, set a pseudo-parameter (say pseudo-parameter 1) to 1 if you want the event killed, otherwise set it to 0. The pseudo-parameter can then be tested in the conditions: User Function USER: subroutine user (eventType,nWords,event) integer*2 event (*) ... common /pev/ pseudo integer*2 pseudo (100) ... if (ev(4) .ge. pev(3)) then pseudo(1)=1 else pseudo(1)=0 endif ... return end Maps: $M1 1/PSEUDO /NAME=PEV1 Conditions: NOT_OK: BITON PEV1 0 REJECT: KILL NOT_OK Experimenter's Guide To Daphne Page 192 Improving Throughput 3 October 1990 A second method is to exploit the fact that the USER-n function can return a logical value which can be used to set a condition. In this case, one would code the computation as part of the USER-n function rather than as part of the USER function. User Function USER: Do not code Conditions: NOT_OK: USER 1 REJECT: KILL NOT_OK User Function USER1: logical function user1 (eventType,nWords,event) integer*2 event (*) ... if (ev(4) .ge. pev(3)) then user1=.true. else user1=.false. endif ... return end Experimenter's Guide To Daphne Page 193 Improving Throughput 3 October 1990 - User-Defined Function and Daphne Required to Reject This case occurs when rejection depends on windows or linearizations, which are easier to evaluate in Daphne than in a user function. The proper strategy is to perform the computation in a USER-n function, after making sure that Daphne has evaluated any linearizations that the computation depends on. The purpose of the "FORCELNZ" condition is to guarantee that the specified linearization has been evaluated. If the FORCELNZ condition has no arguments, then ALL linearizations are evaluated. A linearization is relatively expensive to compute, about as much as three two-dimensional histograms, so it is generally worthwhile to postpone evaluation of linearizations until as many events as possible are rejected. Linearizations will always be evaluated if they are needed to evaluate maps, windows, conditions, or to increment histograms: the FORCELNZ just controls WHEN they are evaluated. Conditions: DO_LNZ_2: FORCELNZ 2 NOT_OK: USER 1 REJECT: KILL NOT_OK User Function logical function user1 (eventType,nWords,event,lnz) integer*2 event (*) integer*4 lnz (*) ... if (lnz(2) .ge. 400.0 .and. lnz(2) .le. 570.0) then user1=.true. else user1=.false. endif ... return end Experimenter's Guide To Daphne Page 194 Improving Throughput 3 October 1990 In some cases you might have several rejection criteria, each one requiring time-consuming computations in order to make the next round of rejections. This can be handled through the use of several USER-n conditions and several KILL conditions. In the following example, the user-defined function is broken into three parts (USER1, USER2, and USER3). The first rejection is determined by USER1 using the result of linearization MASS. A second set of events are rejected if certain parameters are outside all three two-dimensional windows. If the event is still interesting, a second linearization is performed, and USER2 is called to perform additional computations, and possibly reject the event. If the event is still interesting, USER3 is called, and any remaining conditions are evaluated, and finally, the histograms are incremented (not shown). Conditions: DO_LNZ_1: FORCELNZ MASS NOT_OK_1: USER 1 REJECT_1: KILL NOT_OK_1 INSIDE_1: IN2 WIND1 INSIDE_2: IN2 WIND2 INSIDE_3: IN2 WIND3 ALL_WIND: OR INSIDE_1 INSIDE_2 INSIDE_3 OUT_ALL: NOT ALL_WIND REJECT_2: KILL OUT_ALL DO_LNZ_2: FORCELNZ 2 NOT_OK_3: USER 2 REJECT_3: KILL NOT_OK_3 LAST_USER: USER 3 ... Experimenter's Guide To Daphne Page 195 Improving Throughput 3 October 1990 35.9 For Sparse Data Use the /NOZEROS Option for Histograms When a large fraction of the parameters being histogrammed are zero, there can be a savings in the amount of INC data transmitted to the VAX. Consider the following case as an example: There are two sources of triggers in an event with eleven parameters: A1, A2, and B1 through B9. Trigger TA causes 95% of the events and produces two meaningful parameters, A1 and A2, leaving B1 through B9 zero. A second trigger, TB, fires ony 5% of the time and produces nine meaningful parameters, B1 through B9, leaving A1 and A2 zero. Occasionally, they fire together making all eleven parameters interesting. If one wants to analyze both types of events, a significant amount of bus traffic can be saved in the incrementing of histograms by using the /NOZEROS qualifier of the $H1 and $H2 commands. The /NOZERO qualifier tells Daphne that it should not bother to count the events which would normally go in channel zero. This extra check itself does not take much time compared to its value in reducing the amount of data transmitted to the VAX. If the number of counts in channel zero is important, you can collect the same information in a way which makes better use of the available bandwidth. Use conditions to count the number of times the parameter has no bits on (value is zero) or is outside a window starting at channel 1 and going to the second to last channel. Conditions are transmitted only once per second, and require only 4 bytes per condition - a negligible amount of data. Conditions: ADC1_ZERO: ALLOFF 0000000000000000 ADC2_ZERO: ALLOFF 0000000000000000 ADC3_ZERO: ALLOFF 0000000000000000 etc. Of course, you shouldn't use this strategy if the number of zero counts is important to your analysis, and you don't want the channel zero information separated from the rest of the spectrum. Experimenter's Guide To Daphne Page 196 Daphne Traps and Pitfalls 3 October 1990 36 Daphne Traps and Pitfalls 36.1 Object Names are Saved as Numbers Daphne allows users to give names to objects such as maps, histograms, and windows. Later on, these objects can be referred to by name rather than number. Daphne "translates" names to numbers at the time the command is entered, a relatively early stage. If an object is deleted, the reference to the number remains, even though the object has ceased to exist. Consider the following as an example: $ H1 1024/NAME=ADC1 (Command a) $ M1 1 ADC1 (b) $ H1 1024/NAME=ADC2 (c) $ X1H ADC1 (d) $ H1 2048/NAME=TDC1 (e) In command (a) 1D histogram #1 is created. In command (b) the histogram is referenced by name. The name is looked up and found to be a reference to 1D histogram #1. In command (d) the original histogram is deleted, leaving a "hole" in the numbering of 1D histograms. In command (e) a new 1D histogram is created and assigned the "hole" left by the deletion of histogram ADC1. Histogram TDC1 becomes the new 1D histogram #1. When there are references to an object, and that object is deleted, some thought must be given to how those "dangling" references will be resolved. In the example above, Daphne warns the user that histogram #1 is already referenced by one or more maps. If the user intends to redefine the object just deleted, it may be desirable to leave the dangling references unchanged. In other cases, the user may wish to delete these references using one of the following commands: Command Object Deleted $X1M 1D maps $X2M 2D maps $X1H 1D histograms $X2H 2D histograms $X1W 1D windows $X2W 2D windows $XG/1D 1D gates $XG/2D 2D gates $XLNZ linearizations $CON NL: all conditions $FIX/DELETE fix (integer) parameters $FLT/DELETE float (real) parameters $SP/DELETE scatterplots Experimenter's Guide To Daphne Page 197 Daphne Traps and Pitfalls 3 October 1990 The following commands do not delete objects, but they can break associations between objects: $G1H/DELETE remove gate on 1D histogram $G2H/DELETE remove gate on 2D histogram $M1M/DELETE remove reference to 1D histogram from map $M2M/DELETE remove reference to 2D histogram from map You might want to use the Daphne command $SAV/COMMAND, which creates a Daphne command file which can be used to recreate the current setup. The $SAV/COMMAND command always tries to use symbolic names for references between objects. When the user has not defined symbolic names, the program will create "synthetic" symbolic names, thus doing away with references by object number. For instance, 1D histogram #5, if not named by the user, would be recreated with the name "H1#5". 36.2 Separation of Maps and Histograms Maps and histograms can be saved and restored separately. It is possible to restore a set of histogram definitions which do not match the maps currently defined, and vice-versa. For instance, if you use $RD to read a set of histogram data made when using an incompatible setup file, it is very likely you will have maps referring to histograms which don't exist, and histogram references to maps which do not actually refer to that histogram. 36.3 Use $EXT to Release Resources It is important to exit Daphne by using the $EXT command rather than simply logging out. If you log out or stop the main process, significant system resources, such as global sections and global pages, are not released to VMS for reuse because they are created as "permanent" global sections. VMS allows users to create "permanent" and "temporary" global sections. Permanent global sections exist until they are explicitly deleted or until the system is rebooted. Temporary global sections exist until the reference count goes to zero, which is usually when the program that created them exits. There is no easy way to create global sections that are automatically deleted when a user logs out. Suppose you try to start Daphne and receive the message: %DAPHNE-F-RUNNING, daphne already running for this terminal This is an indication that the previous user at this terminal logged out without using $EXT. Execute the $EXT command yourself and then reissue the $DAP command. Experimenter's Guide To Daphne Page 198 Daphne Traps and Pitfalls 3 October 1990 36.4 Definitions Frozen at Start of Acquisition When a user enters the $ACQ command, the maps, histograms, windows, conditions, and so on defined by the user are analyzed and instructions are downloaded to the Event Processors. If a user should define new histograms, maps, or windows after acquisition has started, they will not affect the sorting process until acquisition has stopped and the $ACQ command has been reissued. Experimenter's Guide To Daphne Page 199 Daphne Traps and Pitfalls 3 October 1990 36.5 Changing Pseudo-Parameters in USER-n Routines Daphne maps are evaluated only once. This can cause surprises sometimes. Consider the following example: $ H1 1024 /NAME=HA $ H1 1024 /NAME=HB $ M1 1/PSEUDO HA /NAME=MA $ M1 1/PSEUDO HB /NAME=MB $ W1 /MAP=MA /LOW=111 /HIGH=222 /NAME=WA $ CON EXAMPLE Where EXAMPLE.CON contains: IN_WA: IN1 WA OKAY: USER 1 User Function USER: subroutine USER (eventType,nWords,ev) ... integer*2 ev (*) common /pev/ pseudo integer*2 pseudo (4) ... do 10 i=1,4 pseudo(i)=0 10 continue ... pseudo(1)=... pseudo(2)=... return end User Function USER1: subroutine USER1 (eventType,nWords,ev) ... integer*2 ev (*) common /pev/ pseudo integer*2 pseudo (4) ... pseudo(3)=... pseudo(4)=... return end Maps MA and MB appear to be defined in an identical fashion. Acquisition shows, however, that HB contains a real spectrum, while HA is uniformly zero. The problem is that the condition "IN_WA" causes the evaluation of map MA BEFORE the USER1 function has been called, while MB is not evaluated until AFTER all conditions are evaluated. Since the value of pseudo-parameter #1 is zero from the time of the call to USER until USER1, MA will always appear to be zero. The solution to this is to rearrange the order of the conditions so that pseudo-parameters are not used before they are computed. Experimenter's Guide To Daphne Page 200 Messages from NSSORT 3 October 1990 37 Messages from NSSORT 37.1 EP i does not respond This error message is sent to the terminal by NSSORT when an Event Processor does not respond to requests for information in a timely fashion. Unless it is followed within seconds by "EP i is now responding", the user should investigate the problem. See section 41.26 ("Is EP Running" in the section "Trouble-shooting Acquisition System Problems"). 37.2 Error Messages Preventing Acquisition - 1D histogram #99 could not be locked down - check privileges and quotas - 1D histogram #99 could not be mapped - 2D histogram #99 could not be locked down - check privileges and quotas - 2D histogram #99 could not be mapped - 2D window #99 could not be mapped - Linearization #99 could not be mapped - Error generating code - consult for more information - No event processors were configured - NSSORT appears to be hung -- hh:mm:ss - Sorting stopped due to exception The message about NSSORT being hung appears if the acquisition program does not reset a watchdog timer approximately every 5 seconds. This message could appear when the NSSORT program fails to get any CPU time, for whatever reason, or because the program has become trapped in some routine, and is not getting back to the point where the watchdog timer is reset. If the message continues to appear, then one must investigate the problem. The message about "exceptions" appears when the NSSORT acquisition program fails in an unexpected manner. Experimenter's Guide To Daphne Page 201 Messages from NSSORT 3 October 1990 37.3 Warnings Requiring Action by User The following messages indicate problems that can usually be fixed by the user. For instance, reducing the size or number of two dimensional windows, or increasing the amount of memory allocated for the code global section. - Arithmetic trap during user initialization routine - cannot continue - Arithmetic trap during FIXFLT routine - cannot continue - Generated code is 99 bytes - it exceeds space allocated (99 bytes) on the event processors - Increase code area size using $MAX /COD=99 - No End-of-Data sentinel found - use $STP/FORCE to make sorting stop - To represent all 2D windows on EP requires 99 (decimal) bytes 37.4 Warnings Requiring No User Action - Output tape record size is 99 bytes: minimum tape record size of 99 bytes used instead - Output tape record size (99) exceeds maximum size (99) - maximum will be used 37.5 Informational Messages - 2D Windows use 99 pages of EP memory - Code downloaded to EP 99 - Code generation complete - First data received at hh:mm:ss - Linearizations use 99 pages of EP memory - No End-of-Data sentinel found - sorting will be stopped anyway - Number of events (event type 99) has exceeded (2**31-1) - event count computed modulo 2,147,483,643 - Sorting stopped - Run time was 99 minutes - Sorting stopped - Run time was 99 minutes since event counts last cleared - Sorting stopped - No events were processed - Sorting stopped - Fewer than 10 seconds of events were processed Experimenter's Guide To Daphne Page 202 Messages from NSSORT 3 October 1990 37.6 Warnings About EP Status - EP 99 is no longer starved for event data - EP 99 is now responding - EP 99 is starved for event data - EP 99 is used to generate scatterplots - EP 99 reports zero length event but no $STP command has been issued - No "DONE" message received from EP: 99 - Received buffer of type 99 (bt_xxxx) from EP 99 with wrong generation - Processors with data transmission errors: 99 ... - Processors absent from multibus: 99 ... 37.7 Warnings About User-Function Initialization Most of these messages are warnings about an inconsistentcy between the user-function and the way you have set up Daphne. When you receive one of these messages, check your user-function initialization routine. - No User-Function present but pseudo-parameters were enabled - Pseudo-parameters enabled but user-function did not call defPEV - User issued a $FIX command but there is no call to defFIX - User issued a $FLT command but there is no call to defFLT - User called defFIX but never issued a $FIX command - User called defFLT but never issued a $FLT command - More FIX values than room in FIX vector - More FLT values than room in FLT vector - Start or End address of pseudo-event vector suspect - Start or End address of FIX vector suspect - Start or End address of FLT vector suspect - FIX vector has more than 254 elements - FLT vector has more than 254 elements Experimenter's Guide To Daphne Page 203 Messages from NSSORT 3 October 1990 37.8 Warnings About Buffer Integrity The following messages indicate that something is amiss in a buffer that was transmitted to the VAX. If it happens as often as once an hour something is wrong. If it happens constantly, this probably indicates that the Event Processors and VAX are running mismatched versions of software. - Exception while executing INC buffer Remainder of INC buffer discarded Acquisition continues - Word 99 of buffer indicates 99 bytes transferred - byte count must be between 99 and 99 (decimal) bytes - Word 99 of buffer indicates EP = 99 but EP must be between 1 and 99 inclusive - Word 99 of buffer indicates buffer type = 99 but buffer type must be between 1 and 99 inclusive 37.9 Warnings About Event Structure The following messages are generated when the event arriving at the Event Processor program appears to be malformed. This is most frequently caused by a mismatch between the $EVS command and the Event Handler program. A second source is garbage events generated when the Camac crate containing the Cable Driver and Event Handler is turned off. The message can also be due to having the same experimental station selected by both halves of the EMUX. Occasionally, we have seen cases where data words were dropped between the Event Handler and the Kinetic Systems FIFO, even though the OUT CA instructions were separated by one Camac I/O instruction lasting at least 1.5 uSec. This problem is sometimes fixed by adding a NOP instruction at the critical point. - Count of words in event (99 decimal) does not match the $EVS command - Type of event is 99 (decimal) - not between 0 and 15 - Unexpected event type 99 (decimal) - Word count and Empty bit disagree Experimenter's Guide To Daphne Page 204 Messages from NSSORT 3 October 1990 More information about the form of the event can be discovered by examining the file "ttt.BAD" where "ttt" represent the three character Daphne identifier. For instance, in the example below, the computer generated message "Bad Word Count" plus the "?" characters around the value of 3 indicates that this is the word causing the problem. Knowing that event data from the Event Processor FIFO has trailing word counts, allows one to conclude that the word count is wrong: it shoud be "9", like all the other events in the buffer. +--------------------------------------------------------------------+ |Bad word count | | | |Event Proc: 1 Date: 29-APR-87 15:36:54 | |Experiment: ############ Run number: | |Physicist: # See Text # Target: | |Beam: ############ Energy: | |Comments: # | | V | | 0 0000 0000 00FE ?0003? 0095 0000 0000 0000 | | 8 0000 0000 0000 0000 00FE 0009 0096 0000 | | 16 0000 0000 0000 0000 0000 0000 00FE 0009 | | 24 0096 0000 0000 0000 0000 0000 0000 0000 | | 32 00FE 0009 0000 0000 0000 0000 0000 0000 | | 40 0000 0000 00FA 0009 0096 0000 0000 0000 | | 48 0000 0000 0000 0000 00FE 0009 0096 0000 | | 56 0000 0000 0000 0000 0000 0000 00FE 0009 | | 64 0096 0A60 14EE 0000 0000 0000 0000 0000 | | 72 00FE 0009 0000 0000 0000 0000 0000 0000 | | 80 0000 0000 00FA 0009 0096 06A8 0DDC 1331 | | 88 13F9 0000 0000 0000 00FE 0009 0095 0000 | | 96 0000 0000 0000 0000 0000 0000 00FE 0009 | | 104 0096 0986 0BA3 0D9C 0000 0000 0000 0000 | | 112 00FE 0009 0096 0000 0000 0000 0000 0000 | | 120 0000 0000 00FE 0009 0096 0000 0000 0000 | | 128 0000 0000 0000 0000 00FE 0009 | +--------------------------------------------------------------------+ Experimenter's Guide To Daphne Page 205 Trouble-shooting EHSEND Problems 3 October 1990 38 Trouble-shooting EHSEND Problems 38.1 SYSTEM-F-TIMEOUT, device timeout This means that the Kinetic Systems 3989 Crate Controller has not responded to the VAX within a few seconds of a command. First check that the crate is powered up and the crate controller is on-line. Check that on the front panel of the crate controller REQUEST IN is connected to GRANT IN. Without this connection, the crate controller will not grant itself permission to use the dataway! If an Event Handler or AUX controller is in the same crate, check the two connections between the AUX and the KS/CC according to section 46.5 If the crate controller has been used recently, the problem is likely due to the host and the crate controller being out of synchronization. If this is the case, it can be fixed by resetting the crate controller using its front panel switches: - Move the Off-Line/On-Line switch to "Off-Line" - Move the momentary "C" versus "Z" Switch to "Z" and release it - Move the Off-Line/On-Line switch to "On-Line" 38.2 Terminal Characteristics If the crate controller needs to be reset often, it could be an indication that the terminal characteristics are mismatched with the crate controller. In particular, use the $SHOW TERMINAL command after the $CDV command to check that the terminal is set: /PASSALL /NOPARITY /TYPEAHEAD /ALTYPEAHD /NOBROADCAST /NOTTSYNC /NOHOSTSYNC /FRAME=8 The normal user does not have sufficient privilege to change these characteristics "permanently"; however, the $CDV command should set all these characteristics except /FRAME=8. If the terminal characterstics are wrong, but things worked until recently, use the command $SHOW SYSTEM to find out when the VAX was last rebooted. If the VAX was rebooted recently, it could mean that the terminal characteristic were changed at one time, but the changes were not placed in the system startup file. See a member of the computer staff about placing these changes in the system startup file so that they will be retained across a system crash and shutdown. Experimenter's Guide To Daphne Page 206 Trouble-shooting EHSEND Problems 3 October 1990 If the crate controller needs to be reset every time the VAX is rebooted, this could mean that the terminal line connected to the crate controller is not set /NOBROADCAST. Again, see a member of the computer staff about changing the terminal characteristics. 38.3 First Time Problems If this is the first time this crate controller has been used recently, there are a number of things to check: - Check that the VAX and the Crate Controller agree on baud rate and other terminal characteristics. At Atlas, most crate controllers are configured for 9600 baud, no parity, 1 stop bit. - If using a Telematics SmartSwitch to connect the VAX to the crate controller, check that it too has a matching baud rate and parity, that it has handshake set to NONE, and that the correct ports are connected together. If you do not know how to operate the SmartSwitch, consult the SmartSwitch User's Manual or the Daphne Hardware Log. - Check that the VAX and the Crate Controller have the correct cross-overs (straight through or null modems) between them. This is most easily done by adding or subtracting a null modem and noting if things then work. - Check that the crate number selected by switches in the crate controller match the crate number given in the $CDV command. The default crate number for the $CDV command is crate 1, rather than zero. - The Crate Controller has a number of operating mode switches. See section 48 on how to configure the KS/CC. 38.4 Event Handler MASTER Switch is Set The MASTER switch on the front panel of the Event Handler disables access to the Event Handler from the crate controller. The MASTER switch has nothing to do with master/slave Event Handlers. The main purpose of this switch is to prevent people from interfering with the Event Handler while a program is running. The MASTER switch should be in the down position. Whether the corresponding status light is on, or not, depends on the phase of the moon. Experimenter's Guide To Daphne Page 207 Trouble-shooting EHSEND Problems 3 October 1990 38.5 Memory Compare Errors False memory compare errors can be given if the Event Handler slot number or crate number given in the $CDV is wrong, since no device, or the wrong device, will respond to the Camac function codes. The default crate number is crate 1. The default slot number of the AUX is slot 20, whether it appears in crate 1 or crate 2. If you wish to determine the proper value for the /EH_SLOT qualifier of the $CDV command for your Camac configuration, one should remember: the slot number to use is that of the auxiliary crate controller (AUX) rather than the Event Handler. For black, double-width AUX modules, the slot number is the lower of the two slots occupied by the module. For silver Event Handlers, in which the AUX and EH are combined in a single, double-width module, the correct slot number is that of the higher of the two slots occupied. One can verify that the AUX is in the correct slot by watching the select light (labeled "N") of the AUX blink during program loading. The crate number of the Event Handler is a different kind of crate number than the crate number used in Event Handler instructions. The crate number used in Event Handler instructions (crate 1 or crate 2) implies use of AUX 1 or AUX 2. The number of an AUX is determined by internal jumper options, not by the crate number of the KS/CC, because the AUX is connected directly to the Event Handler, bypassing the crate controller. The purpose of Crate Controller crate number is to allow a number of Kinetic Systems 3989 crate controllers to share a single RS-232 cable. To specify a slot number for the Event Handler, other than the default of 20, use the /EH_SLOT qualifier of the $CDV command. To specify a crate number, other than the default of 1, use the /EH_CRATE qualifier of the $CDV command. The EHSEND program always checks that the program was properly downloaded by reading back the contents of the Event Handler memory. Any discrepancies are reported by giving the memory address, the correct value, and the value read back. The Event Handler memory is organized as three, 8 bit wide, 2048 bit deep memories. If bits are wrong in random places, the most likely problem is that the data is transmitted at too high a data rate for the length of the RS-232 cable. This is very likely the problem if the terminal is running at 19,200 baud and the cable is over 30 meters long. Experimenter's Guide To Daphne Page 208 Trouble-shooting Event Handler Programs 3 October 1990 39 Trouble-shooting Event Handler Programs Locating problems in Event Handler programs can be difficult because the Event Handler cannot be stepped one instruction at a time. Nor is there any way to read the internal state of the processor, such as the value of the program counter or the contents of the CA1 register. The first problem in debugging an Event Handler program may be to determine what is wrong by looking at the data stream, parameter by parameter, event by event. - Use $EHFIFO to look at data as it is leaving the KS/FIFO - Use $EPFIFO to look at data as it leaves the Event Processor FIFO - If you are getting error messages from NSSORT telling you that the number of parameters in the event does not match the $EVS command, you can look at the file ttt.BAD which contains a dump of any Event Processor FIFO buffers that were considered to be badly formatted. The string "ttt" in the file name represents your three character Daphne identifier. For instance, if your identifier was "BGO" the file name would be "BGO.BAD". See section 37.9 for an example of the BAD file format. If you do not know your Daphne identifier, consult section 41.38. 39.1 Use $EPFIFO to Look at Data Leaving the Event Processor FIFO The $EPFIFO command allows you to look at the next complete FIFO buffer of an Event Processor. Since an Event Processor FIFO is considered filled only when it contains between 128 and 256 words, this may take some time at very low data rates. There are two output formats, depending on whether the buffer is to be broken up event by event, or not. Copies of the dump in machine readable format were obtained using the "/OUTPUT" qualifier of the $EPFIFO command. By default, the dump is broken up event by event. In the first example below, we see a formatted hexadecimal dump of 12 events where each event contains 10 parameters. Experimenter's Guide To Daphne Page 209 Trouble-shooting Event Handler Programs 3 October 1990 +-----------------------------------------------------------------+ | Event Proc: 5 Date: 20-NOV-86 10:47:00 | | Experiment: NEWRTE Run number: 0 | | Physicist: Tanis et al. Target: He | | Beam: Ni(25+ Energy: 600 | | Comments: | | | | 1 0004 0000 0000 0000 0000 0012 0016 0000 0014 0012 | | 2 0004 0000 0000 0000 0000 0015 0494 0000 0014 0011 | | 3 0004 0000 0000 0000 0000 0015 0019 0000 0014 0011 | | 4 0004 0000 0000 0000 0000 0017 001E 0000 0014 0011 | | 5 0004 0000 0000 0000 0000 0016 001E 0000 0014 0011 | | 6 0004 0000 0000 0000 0000 0015 001E 0000 0014 0012 | | 7 0004 0000 0000 0000 0000 0017 06CB 0000 0014 0011 | | 8 0004 0000 0000 0000 0000 0013 0022 0000 0014 0011 | | 9 0004 0000 0000 0000 0000 0014 001A 0000 0014 0011 | | 10 0004 0000 0000 0000 0000 0016 001A 0000 0014 0011 | | 11 0004 0000 0000 0000 0000 0011 0015 0000 0014 0011 | | 12 0004 0000 0000 0000 0000 0013 001B 0000 0014 0011 | +-----------------------------------------------------------------+ An unformatted hexadecimal dump from the same run appears below. It was obtained with the "/NOFORMAT" qualifier of the $EPFIFO command. The "/" characters enclose the word count field that follows each event. +-----------------------------------------------------------------+ | 0 0004 0000 0000 0000 0000 0013 001C 0000 | | 8 0014 0012 /000A/ 0004 0000 0000 0000 0000 | | 16 0000 0019 0000 0014 0011 /000A/ 0004 0000 | | 24 0000 0000 0000 0012 0012 0000 0014 0012 | | 32 /000A/ 0004 0000 0000 0000 0000 0018 0017 | | 40 0000 0014 0011 /000A/ 0004 0000 0000 0000 | | 48 0000 0015 07FA 0000 0014 0011 /000A/ 0004 | | 56 0000 0000 0000 0000 0011 001F 0000 0014 | | 64 0011 /000A/ 0004 0000 0000 0000 0000 0015 | | 72 001E 0000 0014 0011 /000A/ 0004 0000 0000 | | 80 0000 0000 0010 0015 0000 0014 0012 /000A/ | | 88 0004 0000 0000 0000 0000 0011 0020 0000 | | 96 0014 0011 /000A/ 0004 0000 0000 0000 0000 | | 104 0013 001C 0000 0014 0012 /000A/ 0004 0000 | | 112 0000 0000 0000 0014 001D 0000 0014 0011 | | 120 /000A/ 0004 0000 0000 0000 0000 0017 001C | | 128 0000 0014 0011 /000A/ | +-----------------------------------------------------------------+ Experimenter's Guide To Daphne Page 210 Trouble-shooting Event Handler Programs 3 October 1990 39.2 Exercise the Event Handler Without ACQ Being Active Unless you have changed your Event Handler program, it will not generate any data until acquisition is started. If you want to have it run without acquisition being active, you have three alternatives: - Simulate the Acquisition Signal in the Event Handler Program Change the INCLUDE statement near the end of the Event Handler program to use DAPEH:EHDEBUG rather than DAPEH:STANDARD. The EHDEBUG differs from STANDARD in that it ignores whether acquisition is active or not. It calls the user's Camac initialization routine once the program is loaded, then calls the user's event read-out routine whenever an event is detected. The program will not stop until the Event Processor is reset in some way. - Simulate the Acquisition Signal in Hardware One can fool the Event Handler into thinking that acquisition has started by disconnecting front panel input 8 from bit 1 of the NIM output register, which should be in slot 16, and connecting it to a NIM signal which is "true". Both an open connection and a grounded connection are considered "false" in NIM logic. - Simulate the ACQ Program by Programming the Output Register A second method of fooling the Event Handler into thinking acquisition has started, is to use the $CNAF command to change the state of bits 1, 2, and 3 of the NIM output register to "true". Both examples below assume that the NIM output register is in its customary place: slot 16 of crate 1. To set just bits 1, 2, and 3 in the output register, and then start the Event Handler, use the following sequence: $ CNAF CDV Enter crate, slot, sub address, and function: 1,16,0,20 Data [nnn dec/Xnnn hex/Onnn octal] 7 To reset bits 1, 2, and 3 in the output register and stop the event handler use the following sequence: $ CNAF CDV Enter crate, slot, sub address, and function: 1,16,0,22 Data [nnn dec/Xnnn hex/Onnn octal] 7 Experimenter's Guide To Daphne Page 211 Trouble-shooting Event Handler Programs 3 October 1990 39.3 Use $EHFIFO to Look at Data Leaving the KS/FIFO The Kinetic Systems FIFO can be read-out like any other Camac device. If output from the FIFO to the EMUX and Event Processors is disabled, one can examine all data entering the FIFO by using the RS-232 crate controller to read the FIFO. All data read this way is lost to the Event Processors, but this is usually not a concern when debugging Event Handler programs or Camac hardware. The best way to disable transmission of data from the FIFO to the EMUX is to move the GO/NOGO switch on the EMUX to the right, the NOGO position. I do not recommend removing the cables from the FIFO or Cable Driver since these connectors tend to be delicate and tempermental. Input to the EMUX is restored by moving the switch back to the GO position. The $EHFIFO program assumes the FIFO is in slot 22 of the crate with the Event Handler. The program displays the data in six digit hexadecimal format. If the high order bit is set, then the lower 4 digits contain a 16 bit data word. If the upper 8 bits contain "58", then this is an end-of-event marker, and the lower 4 digits should be zero. If the entire word is zero, the FIFO is empty. The following example was created using the $EHFIFO program when the Event Handler was running a test program that generates four word events using a scaler: +--------------------------------+ | 1 80000D | | 2 580000 End of Event | | 3 80000E 1 | | 4 80000E 2 | | 5 80000E 3 | | 6 80000E 4 | | 7 580000 End of Event | | 8 80000F 1 | | 9 80000F 2 | | 10 80000F 3 | | 11 80000F 4 | | 12 580000 End of Event | | 13 800010 1 | | 14 800010 2 | | | | and so on | +--------------------------------+ When changing Event Handler programs, remember that it may take a while for a change to show up in the FIFO output because the FIFO may contain as many as 256 words of data generated by the previous Event Handler program. Experimenter's Guide To Daphne Page 212 Trouble-shooting Event Handler Programs 3 October 1990 39.4 Use the CNAF program to Understand Device Behavior The CNAF program allows users to execute simple CNAF codes, one at a time, without writing a special program. Here is an example of using the program to perform one read and one write function to a module: $ CNAF CDV Enter crate, slot, sub address, and function: 1,3,0,2 Data: 1 (dec) 000001 (hex) 0000 0000 0000 0000 0000 0001 (bin) Enter crate, slot, sub address, and function: 1,3,16,0 Data: [nnn dec/Xnnn hex/Onnn octal] 1234 Enter crate, slot, sub address, and function: o o o Please recall that the $CDV command sets the terminal characteristics required for communication with the KS/CC. If you have not executed the $CDV command, then the $CNAF program may not operate properly. See section 38.2 for a list of the proper terminal characteristics. The user can enter a specific terminal line (for example "TTA1:") or use the symbol "CDV" to indicate that it is the same terminal port used in the $CDV command. Data read out is displayed in decimal, hexadecimal, and binary. Data may be entered in decimal, hexadecimal, or octal. NOTE There are several modules which will honor the Crate Inhibit line signal. This is a common problem when testing modules in a crate controlled by the Kinetic Systems 3989 Crate Controller, which powers up with Crate Inhibit asserted. To turn off the crate inhibit on a Kinetic Systems 3989, execute N=30 A=0 F=17 with the value 0. This will clear INHIBIT by clearing bit 6 (counting from 1) of the 3989 control/status register. Experimenter's Guide To Daphne Page 213 Trouble-shooting Event Handler Programs 3 October 1990 39.5 Dataway Display A Dataway Display can be the easiest way to monitor the exection of an Event Handler program, since bus activity can be displayed without modification of the Event Handler program. Event Handler programs can also be modified to write out the contents of CA registers to the display. Another way to use the Dataway Display is to write out a characteristic number to the Display at each important step of the program. There is one drawback to this technique: writing out a constant to a Camac device requires use of the CA register while the CA register may contain valuable information. If one has a two crate Camac system in which crate two is not used, then the Dataway Display can be placed in that crate and CA2 used rather than CA1. With either of the above techniques one can have the problem that, at one million instructions per second, all one sees on the Dataway Display is the "time averaged" behavior of the program: some of the lights are brighter than others. Thus, it is often useful to combine the Dataway Display with use of the front panel inputs described below. 39.6 Use Front Panel Inputs Using the front panel inputs, one can insert "wait loops" at key points in a program to slow execution. For instance, in the following program segment, the Event Handler will hang at the obvious places until front panel input 4 is first set, then reset. Waiting for it merely to be set would not be sufficient. Once the bit were set, the processor would race through all the other "waits" at a rate of over 1,000,000 instructions per second. +---------------------------------------+ | o | | o | | W1A IF (EX1 .NONE. [4]) W1A | | W1B IF (EX1 .ANY. [4]) W1B | | o | | o | | o | | W2A IF (EX1 .NONE. [4]) W2A | | W2B IF (EX1 .ANY. [4]) W2B | | o | | o | | o | | W3A IF (EX1 .NONE. [4]) W3A | | W3B IF (EX1 .ANY. [4]) W3B | | o | | o | +---------------------------------------+ This technique has the added advantage of not requiring use of the CA registers. Experimenter's Guide To Daphne Page 214 Trouble-shooting Event Handler Programs 3 October 1990 39.7 Use Front Panel Outputs The front panel outputs can serve as a "poor man's" Dataway Display. It has one advantage over the Dataway Display in not requiring use of the CA register. The SSET, SCLR, and SCMP instructions allow one to change the state of the EX register. They affect only those bits in the EX register which have the corresponding bits set in the operand. For instance, "SCLR 1" would clear bit 1 of the output register, but leave all other bits unchanged. The following instructions control the EX output register: - SSET constant Set bits in output register that are set in constant. - SCLR constant Clear bits in output register that are set in constant - SCMP constant Complement bits in output register that are set in constant - LOAD constant All bits in the constant are copied to the output register. When the Event Handler executes one of these instructions, look for the change using an oscilloscope or logic analyzer. One should remember in choosing which bits to use, that some front panel outputs are NIM, and some are TTL. See the description of the EX Output Register (Section 20.4) or D. C. Hensley's documentation for more information. Section 4.1 ("Related Documentation") describes how to obtain a copy. Do not use front panel output 6. Its use is described in section 41.21. Experimenter's Guide To Daphne Page 215 Trouble-shooting Tape Problems 3 October 1990 40 Trouble-shooting Tape Problems 40.1 Auto-Thread Tape Drive Doesn't Inspect the tape leader. If it has creases, is wrinkled, has ripples on the edge, try using the tape trimmer normally kept near such a tape drive. The unit provided with Digital Equipment Corporation tape drivers is about 2 inches long, an inch tall, and about 3/4 of an inch wide. 40.2 Tape Drive Status Light Indicates Incorrect Density after $TAPE Command An observed characterisitic of VAX/VMS tape drives, not fully understood, is that the density of the tape drive will not indicate the density at which data will be read or written, until at least one read or write has taken place. Mounting a tape using the $TAPE/IN or $TAPE/OUT command does not necessarily cause a read or write operation to take place. Wait until data is being read or written and the status light indicates the wrong density to become alarmed. In other words, wait until it is too late to prevent the problem. NOTE Now that the $TAPE qualifier /APPEND has been implemented, this problem should disappear, since the tape output program must perform at least one read as part of its normal operation. 40.3 TU78 Drive Loses Power The DEC TU78 tape drive sometimes trips its circuit breaker during load operations. When one of the circuit breakers trips, all status lights, including the POWER light at front left hand side of the unit, will go out. Open the rear door of the tape drive. When looking at the tape drive from behind, the breaker will be located about one foot from the floor, and to your left. Reset the breaker by pulling up on it. It may require two or three attempts before it "sticks" in the "on" position. Experimenter's Guide To Daphne Page 216 Trouble-shooting Tape Problems 3 October 1990 40.4 TU78 Loses Vacuum in Mid-Reel Instructions for reloading a tape when the TU78 has lost vacuum in mid-reel are usually posted on the side of the tape drive. Do NOT hit the LOAD button while there is slack in the tape path, unless you wish to make a qualitative study of the elastic qualities of half-inch wide acetate. 40.5 Tape Drive Allocated By Non-Existent Process Under certain circumstances, a sub-process using the tape drive, such as the tape output process, can exit in such a manner that VMS does not release the tape drive, but leaves it assigned to a now non-existent process. This is a bug in VMS. To determine the owner of a tape drive, say MFA0:, use the following command: +------------------------------------------------------------------+ | $ SHOW DEVICE MFA0:/FULL | | | | Magtape MFA0:, device type TU78, is online, allocated, ... | | mounted foreign, record-oriented device, file-oriented ... | | is enabled. | | | | Error count 6 ... | | Owner process "Daphne_BGO" ... | | Owner process ID 0000002D <-------- owner process ID | | Reference count 3 ... | | | | Volume label " " ... | | Record size 0 ... | | Mount status Process ... | | ACP process name "" | | Density 6250 ... | | | |Volume status: odd parity. | +------------------------------------------------------------------+ Use the $SHOW SYSTEM command to locate a process with the same process ID. If none exists, and a second check shows that it isn't because the tape drive has been released between your checks, then you may be seeing this problem. There is no fix at this time, aside from rebooting the computer. Experimenter's Guide To Daphne Page 217 Trouble-shooting Acquisition System Problems 3 October 1990 41 Trouble-shooting Acquisition System Problems Let's assume you have: - Configured the Daphne I/O devices using your CONFIG.COM file - Checked Overlooked Hardware Connections (Section 6.12) - Loaded the Event Handler using $EHSEND - Loaded the Event Processors using $EPLOAD - Defined the Event Structure using $EVS - Defined some maps, histograms, and conditions You enter the Daphne command $ACQ. After getting the "$" prompt from VMS you wait a few seconds and receive no error message. Nor do you receive that wonderful message: "First Data Received at ...". What is wrong ? The procedures outlined below all start from two assumptions: that you have received no error message after entering $ACQ, and that you have received a "$" prompt (without entering control/Y or control/C). In the following discussion, verbs that appear in all uppercase ("DETERMINE", "CHECK","PERFORM") request you to perform procedures that are described elsewhere in this section. The procedure outlined is not the quickest. I have tried to make it systematic, while checking early those things which are easy to check, and postponing those things which are difficult to check. Unfortunately, this means that some simple things, which rarely fail but are easy to check, will be checked unnecessarily. An entire section of this document is dedicated to outlining all the cables and user accessible switches. If you have not inspected these connections before: do so now. This is something one should normally need to do only once per experiment. You need only check switches on the front panel of the Kinetic Systems crate controller. One can assume that internal jumpers and switches were properly configured if the Event Handler program was loaded successfully. Simon says ... Experimenter's Guide To Daphne Page 218 Trouble-shooting Acquisition System Problems 3 October 1990 41.1 Message "Code Generation Complete" If this message does NOT appear, go to "Is ACQ Okay" (Sec 41.31). Otherwise, drop through 41.2 Message "EP i does not respond" If this message appears, go to "Was EP Loaded" (Sec 41.25). Otherwise, drop through 41.3 Message "Code downloaded to EP i" If this message does NOT appear, go to "Multibus Hangup Check" (Sec 41.32). Otherwise, drop through. 41.4 Is Camac Crate Okay Check that the Camac crate has power at +/- 6V, +/- 12V, and +/- 24V. Most Camac crates have built-in meters to make such checking easy. If this is a two crate Event Handler system, check the second crate too. 41.5 Is Crate Controller Okay - Check that the Kinetic Systems 3989 crate controller switch is set to "on-line". - Check that the "Request IN" is connected to "Grant IN". - Check that the "Grant OUT" is connected to the Event Handler "Grant IN". - On the rear of the unit, check that the blue ribbon cable is properly seated, and that it is connected to the rear of the AUX. If this is a two crate Event Handler system, repeat all of the above steps for the second crate controller and its AUX as well. Check that the Secondary AUX is daisy-chained to the Event Handler and the Primary AUX Experimenter's Guide To Daphne Page 219 Trouble-shooting Acquisition System Problems 3 October 1990 41.6 Is the Cable Driver Okay If the Cable Driver is selected by the Primary (Secondary) EMUX, then the "PRI" ("SEC") light should be lit. If neither light is lit, then the Cable Driver has not been selected. Check that the EMUX address select switches have been properly set (Section 46.3). Examine the "+5 IS" status light on the Cable Driver in slot 23 of the crate containing the Event Handler. The "+5 IS" indicates that an isolated 5 volt source is operating. If this light is dark, replace the module. 41.7 Is EH FIFO Full Look at the Kinetic Systems 3841 FIFO in slot 22 of the crate containing the Event Handler. If the FIFO 1/4, 1/2, and 3/4 FULL status lights are lit, then the Event Handler is generating data: go to "Where is EH Data" (Sec 41.9). Otherwise, drop through. 41.8 Is Data Being Read-Out From the FIFO There might be no data in the Event Handler FIFO for two reasons (a) none is being generated or (b) it is being read-out more quickly than it is being filled. Examine the "READ" status light on the Cable Driver in slot 23 of the crate containing the Event Handler. The "READ" light blinks for each word of data transferred from the Camac crate to the EMUX. If the light blinks or is on steady, then data is being transferred to the EMUX. If the Cable Driver light blinks, or is on, and yet no data is received by the VAX, go to "Where Is EH Data" (Sec 41.9). If the Cable Driver light does not blink then go to "EH FIFO Receives No Data" (Sec 41.11). Experimenter's Guide To Daphne Page 220 Trouble-shooting Acquisition System Problems 3 October 1990 41.9 Where Is EH Data Resetting the EMUX has never caused anything worse than the loss of a few hundred words of data, and sometimes an error message or two from the NSSORT acquisition program. PERFORM an EMUX reset (Sec 41.23). Check that both the Primary and Secondary EMUX units have not selected the same station. This is a common oversight when switching from one Multibus system, used when setting up an experiment, to a different Multibus, perhaps with more processors, used when the experiment has beam time. Check that you have selected the correct experimental station using the EMUX switches. Remember, you must subtract one from the slot number of the Cable Receiver to get the number which is encoded in the EMUX switches. Check that you are using the EMUX appropriate to your $MDV command: Multibus A uses the Primary EMUX, Multibus B uses the Secondary EMUX. Check that the cable from your experimental station is indeed connected to the cable receiver. An EMUX has an "ACCEPT" light which blinks once for each word received from the Cable Receiver (and thus, indirectly, from the Event Handler). If the light blinks, or is on steady, then drop through to "Where Did EMUX Data Go" (Sec 41.10). Watch the ACCEPT light and ADDRESS lights very carefully while you PERFORM an EMUX reset (Sec 41.23) - Very Low Data Rates You should see the ACCEPT light blink as each word of data is transferred from the Cable Receiver to each of the Event Processor FIFOs in turn. Since each FIFO is considered "almost" filled when it contains 128 words, it may require some patience to wait for all of the Event Processor FIFOs to be filled. While each Event Processor's FIFO is being filled you should see its address (Event Processor number) appear in the EMUX ADDRESS status lights. When all the Event Processor FIFOs have been filled, all the address lights will go on as the EMUX quickly scans the still full FIFOs looking for one which is empty. - Otherwise At data rates greater than a hundred words per second, the Event Processor FIFOs (which are only 256 words) can fill up in an instant if the processors are not running. If you see the ACCEPT light blink, and then stay off, and then several of the ADDRESS lights go on steady, this is an indication that no Event Processor is consuming the data. Experimenter's Guide To Daphne Page 221 Trouble-shooting Acquisition System Problems 3 October 1990 If you see the symptom described above (EMUX receives data until Event Processor FIFOs are full and then stops) while the Event Processors appear to be working properly (as determined earlier in this decision tree) then it is likely that the Event Handler is generating an infinitely long event. The hypothesis of an infinitely long event can be verified by using the $EHFIFO command (Section 39.3) to dump out the contents of the Event Handler FIFO before it reaches the EMUX. Once the data passes through the EMUX, the control information is stripped from the data, leaving only the low order 16 bits as data. Remember, the output of the $EHFIFO command is meaningful only when no data is being removed from the Kinetic Systems FIFO by the EMUX. In this case, we know from watching the ACCEPT light, that no data is being accepted. In running the $EHFIFO program, you are looking for the ABSENCE of end-of-event words. An end-of-event word contains hexadecimal "58" in the high part of the 24 bit Camac data word. The low order part should be zero. In a normal event data stream one should see "580000" separating events. Anything other than zeroes in the low order 16 bits indicates a serious problem: contact a member of the computer staff. All the words between the "580000" words represent event data, and every word should have the most significant bit set. In other words, the first hexadecimal digit ought to be one of the following characters: "89ABCDEF". A word containing all zeroes indicates an attempt to read the Kinetic Systems FIFO when there is no data. This should occur only for very low data rates - less than a dozen words per second. If end-of-event words are present in Kinetic Systems FIFO, we are at a dead end. If examination of the Kinetic Systems FIFO shows an absence of end-of-event words, PERFORM "EH Infinite Loop Check" (Sec 41.22). If this does not uncover a problem, we are at a dead end. 41.10 Where Did EMUX Data Go It is difficult to reconcile a continuing transfer of data from the Camac system through the EMUX while the VAX receives no data. Where is it all going ? We have already checked for certain obvious things, such as looking at the wrong EMUX. With low data rates, it is possible that the deep buffering provided by the Event Processor memories is postponing other symptoms of a problem. Check for this possibility by watching the second LED from the top of the Event Processor board. It should change state if the Event Processor FIFO has been filled within the previous fraction of a second. If it remains lit, or remains dark for "too long", then it would appear that the data is disappearing between the EMUX and the Event Processor. Review the Cable Driver, Cable Receiver, EMUX, and Multibus connections described in section 46 ("Physical Connections"). In particular, check that there is exactly one Event Processor with termination resistors as described in section 46.4. Without proper Experimenter's Guide To Daphne Page 222 Trouble-shooting Acquisition System Problems 3 October 1990 termination, the EMUX can start filling the Event Processor FIFO of a non-existent Event Processor, or can get stuck filling an Event Processor because the FULL signal is never seen. If none of these suggestions help, then we are at a dead end. 41.11 EH FIFO Receives No Data Check that the Primary AUX is connected to the Kinetic Systems FIFO in slot 22 through its multi-pin connector. 41.12 Is NIM Output Register Connected Check that there is a Jorway Model 41 NIM Output Register in slot 16 of the crate containing the Event Handler. The least significant bit (bit 1) of the NIM Output register should be connected to front panel input 8 of the Event Handler. 41.13 Is EH Able to Access Camac Dataway CHECK Event Handler access to the Camac dataway (Sec 41.20). Experimenter's Guide To Daphne Page 223 Trouble-shooting Acquisition System Problems 3 October 1990 41.14 Is EH Waiting for Acquisition to Start The Event Handler is programmed to address the NIM Output Register, in slot 16, about 4 times a second while it is waiting for acquisition to start. 41.14.1 User-Written Routine Uses NIM Output Register If the user-written EH routine accesses the NIM Output Register, then the NIM Output Register select light may not be a reliable guide to Event Handler behavior. Go to "Easy Test for Event Signal Problem" (Sec 41.15). 41.14.2 User-Written Routine Does NOT Use NIM Output Register If the Output Register select light is blinking about 4 times a second then the Event Handler program does not realize that acquisition has started: go to "Acquisition Start Problem" (Sec 41.17). Otherwise, drop through to "Easy Test for Event Signal Problem" (Sec 41.15). Experimenter's Guide To Daphne Page 224 Trouble-shooting Acquisition System Problems 3 October 1990 41.15 Easy Test for Event Signal Problem The most frequent problem is in the generation of the Event signal. Assume for the moment that this is the problem. If the Event Handler program is not lost in the user routine, then disconnecting input 8 on the EH front panel input will make the Event Handler think that accquisition has stopped. It will respond by generating 128 zero length events to flush the Event Processor FIFOs. Zero length events are events with no parameters: just the end-of-event marker. These zero length events will show up in three ways: - When the 128 zero length events are generated, one should see them work their way through the system. For instance, if no other data is being read out by the Event Handler, one should see the READ light of the Cable Driver (as well as the SEND light of the EMUX) turn on momentarily. If there is no sign of this, then the Event Handler program is failing for another reason. - The Event Handler program will return to the routine which waits for acquisition to start. This should be obvious, because the select light of the NIM output register will begin to blink or pulse about 4 times a second. - The NSSORT program will report that it has received zero length events when no $STP has been issued. If this occurs, this is a sign that all parts of the system between the Event Handler and the VAX sorting program are working. If this message does not appear, even though observation of the FIFO tells you that the end-of-event words have been generated, this is a sign that there may be a second problem, this one between the Cable Driver and the VAX program. First fix the Event Handler problem, then start the trouble-shooting procedure again. If all three of the above signs are seen, it is a virtual certainty that the problem is in generation or recognition of the Event signal. Go to "Event Handler Triggering" (Sec 41.24). Otherwise, drop through. Experimenter's Guide To Daphne Page 225 Trouble-shooting Acquisition System Problems 3 October 1990 41.16 What is EH State There are several reasons why the Event Handler may not be generating any data even though acquisition has started. A. Perhaps no EH program has been loaded since the crate was last powered up B. Perhaps the EH program is lost in one of the user-written routines C. Perhaps the EH program is waiting for an event signal D. Perhaps the EH thinks the Kinetic Systems FIFO is 3/4 FULL DETERMINE the Event Handler State (Sec 41.21). If the state is: - Not Running - Go to "EH Program Crash" (Sec 41.18) - Waiting For Acquisition to Start - Go to "Acquisition Start Problem" (Sec 41.17) - Waiting For FIFO - Go to "EH/FIFO Problem" (Sec 41.19) - Waiting For EVENT - Go to "Event Triggering" (Sec 41.24) 41.17 Acquisition Start Problem PERFORM "NIM Output Register Check" (Sec 42.2) PERFORM "EH Inputs Check" (Sec 42.4) If neither of these checks detect a failure, we have reached a dead end. Experimenter's Guide To Daphne Page 226 Trouble-shooting Acquisition System Problems 3 October 1990 41.18 EH Program Crash The Event Handler program may have crashed for several reasons. First, check those things which are easy to check: the omission of key instructions in the Event Handler program. - No "BRU START" The user may have forgotten to put the following statement as the first executable statement of the Event Handler program: BRU START Without this statement, the "standard" part of the Event Handler program may never get control. - No "BRUR" at End of INIT Routine The INIT subroutine receives control when acquisition begins. Without the subroutine return instruction ("BRUR"), the "standard" part of the Event Handler program may never regain control. - No "BRUR" at End of MAIN Routine The MAIN subroutine receives control when an event is detected. Without the subroutine return instruction ("BRUR") the "standard" part of the Event Handler program may never regain control. After checking for any of these common errors, load (or reload) the Event Handler program using the $EHSEND command. One side effect of the $EHSEND command is a crate reset, which clears the NIM Output Register. Fool the Event Handler into starting acquisition with the following command: $ CNAF CDV Enter crate, slot, sub address, and function: 1,16,0,20 Data: [nnn dec/Xnnn hex/Onnn octal] 7 DETERMINE the state of the Event Handler (Section 41.21). If it is anything OTHER THAN "Not Running", return to the beginning of the trouble-shooting procedure. If the state is "Not Running", CHECK for infinite loops (Sec 41.22). If none are found, we have reached a dead end. Experimenter's Guide To Daphne Page 227 Trouble-shooting Acquisition System Problems 3 October 1990 41.19 EH/FIFO Problem Suppose analysis of the oscilloscope traces generated by front panel output 6 of the Event Handler indicates that the EH is waiting for the Kinetic Systems 3841 FIFO while the FIFO is not 3/4 FULL. There is then a problem in communications between the Event Handler and the FIFO. Check that the multi-pin connector between the Event Handler and FIFO makes good contact. PERFORM the KS FIFO Test (Sec 42.6). If the unit passes this test then we have reached a dead end. 41.20 EH Able to Access Camac Dataway Check If the Event Handler NAF light is on steady while no AUX crate control NAF light is lit (some experiments have two AUX controllers), this indicates that the EH in unable to get access to the Camac dataway. Otherwise, the Event Handler is not blocked by being unable to access the dataway There are several reasons that the Event Handler may not be able to access the Camac dataway: - By far the most frequent cause is a failure to make some required connection between an AUX crate controller and the Kinetic Systems 3989 crate controller. Review the required connections in section 46.5 - If the Event Handler and Primary AUX were recently handled, check that both cables between the Event Handler and Primary AUX make good contact. If access to the Camac dataway remains blocked, we have reached a dead end. Experimenter's Guide To Daphne Page 228 Trouble-shooting Acquisition System Problems 3 October 1990 41.21 Event Handler State When the Event Handler program is operating properly, it is possible to determine the state of the Event Handler program by observing the pattern generated by the EH front panel output 6, a TTL output. Connect an oscilloscope to output 6, and look at the trace. - If the trace shows no change at all, this means that the EH is not running. This could have several causes: - Perhaps no EH program was loaded - Perhaps the EH stalled while waiting for access to the dataway - Perhaps the EH crashed in one of the user routines - Perhaps it is a hardware problem. - If the trace changes state at the incredibly low rate of about 4 times a second, this indicates that it is waiting for acquisition to start. Verify by seeing if the NIM Output Register select light is blinking at this same rate. - If the observed signal has a period of about 4 uSec, and has the following pattern: +-----------+ +-----------+ +--------- | | | | | ---+ +-----------+ +-----------+ <-----------------------> 4.0 uSec This is a clear sign that the Event Handler is waiting for an Event. - If the observed signal has a period of about 4 uSec, and has the following pattern, in which the blips have a width of 500 nSec: +-+ +-+ +-+ +-+ +-+ +-+ | | | | | | | | | | | | ---+ +-+ +-----------------+ +-+ +-----------------+ +-+ +--- <-----------------------> 4.0 uSec This is a clear sign that the Event Handler is waiting for the FIFO to become less than 3/4 FULL. The appearance of this pattern is an indication of a probable error in the experiment's BUSY logic. During normal operation the Event Handler hardware keeps the BUSY output asserted whenever the FIFO 3/4 FULL bit is set. Experimenter's Guide To Daphne Page 229 Trouble-shooting Acquisition System Problems 3 October 1990 - If the trace has a series of blips at irregular intervals, some as short as 2 uSec and some much longer, this is a sign that event data is being acquired. The pattern will consist of 2.0 uSec blips, while waiting for the next event, followed by a relatively long interval when the user's routine is reading-out and then resetting the Camac devices. Remember, the user routine may be over 100 uSec long if there is a programmed delay for ADC conversion. At the end of the user routine, the Event Handler again goes into the wait-for-event loop, which changes the state of output 6 every 2.0 uSec. 41.22 EH Infinite Loop Check Sometimes it is difficult to locate suspected problems in Event Handler programs (such as infinite loops) because of the sheer number of instructions. The following command extracts just those lines that appear to be branch instructions from an Event Handler program named "MYPROGRAM.EHA", and places them in a new file where they can be examined more carefully: $ SEARCH MYPROGRAM.EHA IF,BRU,BRUR /OUTPUT=MYPROGRAM.OUT A second technique is to use the cross-reference appearing at the end of the listing file created by the Event Handler assembler. For instance, a symbol with no references deserves attention. If one has a group of related detectors such as NAI1, NAI2, .. NAI8 it would be suspicious if some of these symbols had one more, or one less, reference than another. The listing file created by the $EHASM command has the extension ".LIS". 41.23 EMUX Reset The GO/NO switch for the Primary (Secondary) EMUX is located at the top left (right) of the dual EMUX unit. Move the appropriate switch to the NO position if it is not already there. Then move the switch to the GO position. Experimenter's Guide To Daphne Page 230 Trouble-shooting Acquisition System Problems 3 October 1990 41.24 Event Handler Triggering Whether the Event signal is NIM or TTL, it is edge triggered, and must have a duration of at leat 50 nSec. This is about 10 times the duration required by the strobe signal of a module like the Ortec 811 ADC. The Event Handler has separate front panel inputs for the NIM Event signal and the TTL Event signal. Make sure you are using the correct front panel input. See section 19 for a diagram of the Event Handlers' front panels, with indications of which are NIM, and which TTL signals. If you see no Event signal when other factors indicate you have an event, look at the BUSY front panel output. - If BUSY is logical "0" Check that there is no mistake in your BUSY logic which might make your acquisition hardware think that acquisition has been inhibited when it is not. If no problem in handling the BUSY signal is located, we have reached a dead end. - If BUSY is logical "1" We have reached a dead end. When acquisition is active, and there are no events, the Event Handler should not be busy. 41.25 Was EP Loaded The most common reason for receiving the message "EP i does not respond" is that the user has neglected to load the Event Processors using the $EPLOAD command. If you have forgotten this step, then stop acquisition using the $STP command, issue the $EPLOAD command, then reissue the $ACQ command. Otherwise, drop through. 41.26 Is EP Running There are two cases: if none of the processors are running we should look for some systematic problems. If only one or two of the Event Processors are not running then, perhaps, it is just a fault with those particular processors. 41.27 Does EP Have Heartbeat During normal operation, the top LED of each Event Processor should always be blinking about once per second. If none of the processors are running, go to "EP Crash" (Sec 41.29). If just one or two are failing, drop through to "Check EP Reset Failure" (Sec 41.28). Experimenter's Guide To Daphne Page 231 Trouble-shooting Acquisition System Problems 3 October 1990 41.28 Check EP Reset Failure Each Event Processor has four red LED status lights. Three are readily visible on the front edge of the board. The fourth LED, below the others, is recessed, making it more difficult to see unless it is lit. The fourth LED is not under program control, and will be lit only if the Event Processor board fails its hardware bootstrap diagnostics, or the RESET switch becomes stuck. If any of the processor boards have the fourth LED lit, go to "Fix EP Reset Failure" (Sec 41.30). Otherwise, we have reached a dead end. 41.29 EP Crash The Event Processors may have stopped because of a Multibus Reset, or because of a program failure. The following operations can cause a Multibus reset: - VAX Reboot - $EPLOAD - Loss of power on Multibus - Hitting the RESET button on an Event Processor board - Hitting the NMI buttton on the Event Processor board In general, one should not have to worry about power failures. Experience has shown that power failures which stop the Event Processors also cause the VAX to fail. By far the most common reason for the Event Processors to stop is an error in the user-written routines that compute pseudo-parameters. Most arithmetic errors in the user-function, such as division by zero, will be reported to the user while the program continues to execute. Thus, the user should assume, in the absence of an error message, that it is some other kind of programming problem. You might want to consider replaying some of your data on the VAX in order to locate the problem using the VAX/VMS symbolic debugger. See a separate document, "Guide to Replay with Daphne", on how to use the VAX/VMS symbolic debugger with a Daphne user-function. Experimenter's Guide To Daphne Page 232 Trouble-shooting Acquisition System Problems 3 October 1990 41.30 Fix EP Reset Failure Stop acquisition using the $STP command. Try pressing the NMI ("Non-Maskable Interrupt") button or the RESET button on the problem processor. If this does not clear the fourth LED, then turn off power to the Multibus for five seconds, and then turn it back on. If this does not clear the problem, turn the power off, remove and reseat each board in turn. If this fails to solve the problem, we have reached a dead end. The only solution is to drop the problem processor from the set of Event Processors which are being used. This is most easily done, on a temporary basis, by overriding the system logical name which specifies which Event Processors to configure. Suppose you want to configure only processors 2 and 3 on Multibus B: $ DEFINE/JOB DAP$CONFIGURE_EP_B "23" NOTE Do not remove EP 1. The Multibus requires timing signals generated by the first Event Processor in order to operate at all. Do not remove from the Event Processor daisy-chain the board which contains the termination resistors. For more information see section 46.4. After this procedure the Event Processors must be reloaded by $EPLOAD before acquisition can be restarted. Experimenter's Guide To Daphne Page 233 Trouble-shooting Acquisition System Problems 3 October 1990 41.31 Is ACQ Okay DETERMINE whether the acquisition process is running (Sec 41.34). If not, then contact a member of the computer staff. Although it is unusual for the acquisition process to fail, it is rarer still for it to fail without any error message whatsoever. A problem during Multibus I/O is the most likely reason for the failure. One of the first actions of the NSSORT program is to verify the reliability of the Multibus/VAX link by writing a test pattern to each of the Event Processors on the Multibus, and then reading the data back for comparisom. PERFORM the Multibus Hangup Check (Sec 41.32). If the state is LEF, which indicates a Multibus problem, there is a substantial probability that the VAX will have to be shut down and rebooted. ABORT the acquisition process (Sec 41.33). CHECK the acquisition process state (Sec 41.36). If the state is RWAST then you have run out of luck: you must restart the VAX. - Save whatever information you feel you must with the $WR, $SAV, or $SAV/COMMAND commands. - If you are using tape, then issue the $KLT command to stop the tape output process. - PERFORM a VAX reboot (Sec 41.39) If the acquisition process no longer exists, then there is probably no need to shut down and restart the VAX. Verify the proper operation of the interface by reissuing your $EPLOAD command. - If $EPLOAD does not complete within 10 seconds: If you do not receive a "$" prompt when you enter control/Y followed by the VMS command $EXIT, then you must REBOOT the VAX (Sec 41.39). - If $EPLOAD completes successfully: This is a very good sign. Try to restart acquisition by reissuing the $ACQ command. Experimenter's Guide To Daphne Page 234 Trouble-shooting Acquisition System Problems 3 October 1990 41.32 Multibus Hangup Check DETERMINE the acquisition process state (Sec 41.36). If it is LEF, there is a problem with the Multibus, or the VAX/Multibus link. If the state of the acquisition process is CEF, the program is NOT hung waiting for Multibus I/O. If the state of the acquisition is COM, the program is waiting for CPU time. This might be a temporary snapshot of the acquisition program, or it may actually be CPU bound. CHECK the state of the acquisition process again (Sec 41.36). If the program is still in COM state then the problem is probably not due to a Multibus failure. 41.33 Aborting the Acquisition Process First try using the $KLSORT command: $ KLSORT If this doesn't work, DETERMINE the acquisition process ID (Sec 41.35). The process ID is an 8 digit hexadecimal number. Assume the process ID is 00002C04: $ STOP/ID=2C04 Experimenter's Guide To Daphne Page 235 Trouble-shooting Acquisition System Problems 3 October 1990 41.34 Is ACQ Running DETERMINE the name of the acquisition process. Get a list of the active subprocesses using the following command: $ SHOW SYSTEM/SUBPROCESS If the name of the your acquisition process appears in the list then acquisition is running. Otherwise, the acquisition process does not exist (is not running). 41.35 Acquisition Process ID DETERMINE the name of the acquisition process (Sec 41.37). To determine the process ID of the acquisition process, execute the following VMS command: $ SHOW SYSTEM/SUBPROCESS Search for the name of the acquisition process in the second column. The first column of the corresponding row (with header "Pid") gives the process ID, an 8 digit hexadecimal number. 41.36 Acquisition Process State DETERMINE the name of the acquisition process (Sec 41.37). To determine the state of the acquisition process execute the following VMS command: $ SHOW SYSTEM/SUBPROCESS The column labeled "State" (just to the right of the process name) gives the process state. Typical process states are: - CEF or CEFO - Common Event Flag Wait - LEF or LEFO - Local Event Flag Wait - COM or COMO - Compute bound - waiting for CPU - PFW - Page Fault Wait - RWAST - Waiting for I/O rundown - RWMPB - Waiting for modified page to be written - SUSP or SUSPO - Suspended - HIB or HIBO - Hibernate - CUR - Current (This process) Experimenter's Guide To Daphne Page 236 Trouble-shooting Acquisition System Problems 3 October 1990 41.37 Acquisition Process Name DETERMINE your Daphne identifier. The acquisition process name is formed by appending the Daphne identifier to the string "Acqs_". For instance, if the identifier is "BGO", then the acquisition process name would be "Acqs_BGO". 41.38 Determine Daphne Identifier ("ttt") The Daphne identifier is the three character identifier entered as the first parameter of the $DAP command which started Daphne. The string is used in the naming of files, global sections, sub-processes, and so on. For instance, a user with the identifier "BGO" would have an acquisition process with the name "Acqs_BGO". If you are unable to remember your Daphne identifier use the following command: $ SHOW PROCESS The VAX will respond: +--- Daphne | Identifier | ("ABC") | V 18-AUG-1986 16:35:11.88 TZC0: --- User: MOOG Pid: 000002ED Proc. name: Daphne_ABC UIC: [MOOG] Priority: 4 Default file spec: SYS$SYSDEVICE:[DAPHNE] Devices allocated: TZC0: The last three characters of your process name, "Daphne_ABC" in this example, are your Daphne identifier ("ABC"). Daphne identifiers which are only one or two characters long will have extra underscores ("_") at the end. Experimenter's Guide To Daphne Page 237 Trouble-shooting Acquisition System Problems 3 October 1990 41.39 Stopping the VAX/750 NOTE The VAX should only be shut down after attempts to reach a member of the computer staff have failed. If possible, warn other users of the computer that you will be stopping it. The following procedure stops a VAX-750 and saves main memory in a file for later analysis: Turn key on front of computer to "LOCAL" Enter Control/P at console terminal >>>E/G F (Examine program counter register >>>E P ( processor status word >>>E/I 0 (Examine internal processor registers >>>E/I 1 >>>E/I 2 >>>E/I 3 >>>E/I 4 >>>D/G F FFFFFFFF (Set program counter to illegal value >>>D P 1F0000 (Set IPL to 31 and kernel mode >>>C (Continue The computer should then give a BUGCHECK message and proceed to reboot. If the machine fails to display two percent signs ("%%") within a minute, drop through to "VAX Boot" 41.40 VAX/750 Boot Turn key on front of computer to "LOCAL" Enter Control/P at console terminal >>>I (Initialize processor >>>B (Boot If you do not receive two percent signs ("%%") within 10 seconds, then there may be a serious hardware problem. Consult a member of the computer staff. From the time the percent signs appear, it may be as long as 5 minutes before the VAX will be ready for users to log in. Experimenter's Guide To Daphne Page 238 Test Programs 3 October 1990 42 Test Programs 42.1 NIM Output Register Select Light Test The following command sequence should turn on, momentarily, the NIM Output Register select light, without altering the outputs or interfering with acquisition. This assumes that the NIM Output Register is in slot 16 of crate 1. $ CNAF CDV Enter crate, slot, sub address, and function: 1,16,0,20 Data: [nnn dec/Xnnn hex/Onnn octal] 0 42.2 NIM Output Register Check The Event Handler Output Register diagnostic program turns on, for about 3 uSec, each of the 12 NIM outputs in rotation. The select light of the module should also turn on, of course. $ EHSEND DAPEH:OUTPUT_REG_DIAG This program will run until the Event Handler or crate is reset. The program loop requires about 45 uSec. 42.3 EH Outputs Check The Event Handler Outputs diagnostic program turns on, and then off, in sequence, all the front panel outputs of the Event Handler (including BUSY). It also drives the NIM Output Register least significant bit (bit 1). Examine the Event Handler front panel outputs with an oscilloscope. Remember, some outputs are NIM and some are TTL (See diagrams at the beginning of section 19). Disconnect the EVENT inputs for this test so that they will not interfere with the BUSY signal, which is set under hardware control (but cleared under software control). $ EHSEND DAPEH:EH_OUTPUTS_DIAG This program will run until the Event Handler or crate is reset. The program loop requires about 10 uSec and turns on each output for about 1 uSec. Experimenter's Guide To Daphne Page 239 Test Programs 3 October 1990 42.4 EH Inputs Check This diagnostic program uses the Event Handler outputs to test the Event Handler inputs, since they are the most convenient source of controllable NIM and TTL signals. Each pass through the diagnostic program requires about 35 uSec. After each pass the front panel outputs are complemented. Thus, if the test connections suggested below are made, one should see the NIM output change state every 35 uSec. There are 8 front panel inputs plus the EVENT signal. The program tests the state of each front panel input in turn. If the input is on (off) the corresponding bit of the NIM output register is turned on (off). Use the following table as a guide: Input Number Type Input NIM Output Register Source Bit Number Input 1 TTL Output 1 Bit 1 Input 2 TTL Output 1 Bit 2 Input 3 TTL Output 1 Bit 3 Input 4 TTL Output 1 Bit 4 Input 5 TTL Output 1 Bit 5 Input 6 TTL Output 1 Bit 6 TTL EVENT TTL Output 1 Bit 9 Input 7 NIM Output 7 Bit 7 Input 8 NIM Output 7 Bit 8 NIM EVENT NIM Output 7 Bit 9 At the end of each loop the BUSY output is cleared and bit 10 of the output register is turned on for about 3 uSec. The bit should change state about every 35 uSec. $ EHSEND DAPEH:EH_INPUTS_DIAG This program will run until the Event Handler or crate is reset. The program loop requires about 35 uSec. Experimenter's Guide To Daphne Page 240 Test Programs 3 October 1990 42.5 EH BUSY Output Check There is no special program for checking the BUSY output. Use the Event Handler Outputs diagnostic program. 42.6 KS FIFO Test This diagnostic program has not been written, however, the FIFOTEST program (Section 42.8) requires proper operation of the KS/FIFO in order to test other components. Thus, proper operation of the FIFOTEST program should inspire confidence in the KS/FIFO. 42.7 Unibus/Multibus Interface Test The ZBMEMORY diagnostic program exercises the Unibus/Multibus interface by writing, reading back, and then comparing a test pattern transmitted to every Event Processor on the Multibus. The program will give erroneous results if it is run while the Event Processors are loaded, since the Event Processor programs may be changing memory during the time the test pattern has been written, and before it is read back. For this reason, it is best to stop acquisition and turn the Multibus power off for 5 seconds. Under normal conditions the program requires about 10 seconds to test up to six processors in a Multibus. There are actually two programs, one for Multibus A (named DAPEP:ZBMEMORYA) and one for Multibus B (named DAPEP:ZBMEMORYB). +---------------------------------------------------------+ | $ RUN DAPEP:ZBMEMORYA | | Processor 1 No Errors | | Processor read failure 2 IOSB: 2710008C 0000FFFF | | Processor 3 Compare errors: 4 | | XOR of first 32 are: | | 002C 0016 0017 0075 | | Addr of first 32 are: | | 7015A 7062E 7172C 720E8 | | Processor read failure 4 IOSB: 2710008C 0000FFFF | | Processor read failure 5 IOSB: 2710008C 0000FFFF | | Processor read failure 6 IOSB: 2710008C 0000FFFF | | FORTRAN STOP | +---------------------------------------------------------+ This test run shows that processor 1 had no memory errors, while processor 3 had a number of memory errors. Processors 2, 4, 5, and 6 gave read errors because they were absent from the Multibus. Experimenter's Guide To Daphne Page 241 Test Programs 3 October 1990 42.8 FIFOTEST Program This program tests the following components as a whole: - Event Processor FIFO - EMUX - Cable Receiver - Cable Between Cable Driver and Cable Receiver - Cable Driver - Kinetic Systems FIFO - Auxiliary Controller - Event Handler An Event Handler program uses a Camac scaler placed in the crate with the Event Handler to count up in sequence. A matching program in the Event Processor in the Multibus checks that it receives the numbers in order. Although this does not identify components which are failing, a successful test should give one confidence that all the major components between the Camac crate and the Event Processor are working properly. 42.8.1 Matching Event Handler Program DAPEHDIAG:TEST_c_n.EHA The Event Processor program assumes there is a scaler in the Camac crate which is being controlled by the Event Handler so as to generate events with consecutive values for the parameters. Thus, if the number of parameters per event is 4, then an event of four 1s is generated, then an event of four 2s, four 3s, etc. When the counter reaches 65,535 ('FFFF' hexadecimal) it is reset. There is actually a family of Event Handler programs to generate events. There is one for each possible slot and crate the scaler might occupy. The Event Handler programs are DAPEHDIAG:TEST_c_n.EHA where "c" (the crate number) is "1" or "2" and "n" (the slot number) is between 1 and 17 for crate 1, and between 1 and 23 for crate 2. Thus, to test using a scaler in slot 13 of crate 1 use the program DAPEHDIAG:TEST_1_13.EHA This family of Event Handler programs generate events of four parameters. When loaded, the test program immediately starts to generate events and increment the scaler without external signals. It does not stop until the crate is reset. Experimenter's Guide To Daphne Page 242 Test Programs 3 October 1990 42.8.2 The DBG16 Debugger for the DB32016 (Event Processor Board) The port used by DBG16 to communicate with the Event Processors should have the following terminal attributes: /SPEED=9600 (Speed normally used at Atlas) /NOECHO /PASSALL /NOBROADCAST /ALTYPEAHD Occasionally the DBG16 program is unable to establish communications with the DB32016 monitor because of characters in the VAX terminal port's typeahead buffer. To purge characters in the typeahead buffer of terminal port "EP1:" use the following command: +-----------------------------------------------------------+ | $ set host/dte ep1: | | %REM-I-TOEXIT, connection established, type ^\ to exit | | | | %REM-S-END, control returned to node _ANPH01:: | +-----------------------------------------------------------+ To break the connection to the Event Processor hit the "\" key (backwards "divide" character) while holding down the control key. 42.8.3 Event Processor Program FIFOTEST This program checks that in a buffer read from the event processor FIFO, values for the parameters are in consecutive ascending order and that the number of parameters per event is as expected. This program is loaded in the following way (assuming you have the EP1: cable connected to the top RS-232 edge connector of the processor board): NOTE The DBG16 debugger is case sensitive: commands MUST be typed in lowercase. +-------------------------------------------------------------+ | $ allocate ep1: | | $ dbg16 | | --> sl ep1: (select RS-232 port) | | --> sr 4h (select radix - hexadecimal mode) | | --> b fifotest/sp=27000 (load this program and | | set stack pointer) | | --> r np (replace number of parameters/event | | 0 ? 4 new value) | | --> bc 2,funny (breakpoint "create" to catch | | malformed events) | | --> g (go - begin execution) | +-------------------------------------------------------------+ Experimenter's Guide To Daphne Page 243 Test Programs 3 October 1990 It is not unusual to have one spurious breakpoint at the beginning of execution. The user must change the variable "np" to contain the number of parameters per event: +-------------------------------------------------------------+ | --> r np (replace "number of parameters/event") | | 0000 ? 4 | +-------------------------------------------------------------+ The user must set a breakpoint at "funny" to catch the events which are malformed: +-------------------------------------------------------------+ | --> bc 2,funny (breakpoint "create" for "bad" events) | +-------------------------------------------------------------+ When the program stops at "funny" you can examine the data causing the problem, pointed to by R1. For instance, to look at the 20 bytes preceding R1 and 8 bytes following R1 use the command: +-------------------------------------------------------------+ | --> p -20(r1)..8(r1) (print values in range start..end) | +-------------------------------------------------------------+ Sometimes one suspects that there is just one bit that is wrong and you would like to test the data stream for any problems other than those you know about. You can do this by changing the value of the variables "dataMask" and "wcMask". For instance, if you want to verify a suspicion that the only problem is in the low order data bit, you can use the following command to force the FIFOTEST program to ignore the low order bit in doing comparisons: +-------------------------------------------------------------+ | --> r dataMask 2h | | 0000 ? 0001 | +-------------------------------------------------------------+ On the following page is sample dialogue from the FIFOTEST program. Experimenter's Guide To Daphne Page 244 Log of FIFOTEST session 3 October 1990 +-----------------------------------------------------------+ | $ dbg16 | | | | Copyright (c) 1985 National Semiconductor Corporation | | All Rights Reserved | | Welcome to the NS32000 debugger - dbg16 [rev 2.00] | | | | --> sl ep1: | | --> sr 4h | | Was 4d | | --> b fifotest/sp=27000 | | kk | | 2864 Bytes loaded. | | --> bc 2,funny | | --> pa event | | Address = 0a230 = FIFOTEST fifoTest: .263 | | --> g | | Breakpoint 2 reached at FIFOTEST fifoTest: .234 | | .234 .ln 234;funny: nop | | -->p -10(r1)..0(r1) 2h | | (0a2f0) = 0d7ee | | (0a2f2) = 0d7ee | | (0a2f4) = 4 | | (0a2f6) = 0d7ef | | (0a2f8) = 0d7ef | | (0a2fa) = 0d7ef | | (0a2fc) = 0d7ef | | (0a2fe) = 4 | | (0a300) = 0a2a2 | | -->p event!20 2h | | (0a230) = 0d7db | | (0a232) = 0d7db | | (0a234) = 0d7db | | (0a236) = 4 | | (0a238) = 0d7dc | | (0a23a) = 0d7dc | | (0a23c) = 0d7dc | | (0a23e) = 0d7dc | | (0a240) = 4 | | (0a242) = 0d7dd | | (0a244) = 0d7dd | | (0a246) = 0d7dd | | (0a248) = 0d7dd | | (0a24a) = 4 | | (0a24c) = 0d7de | | (0a24e) = 0d7de | | (0a250) = 0d7de | | (0a252) = 0d7de | | (0a254) = 4 | | (0a256) = 0d7df | | --> r np | | 0 ? 4 | | --> g | +-----------------------------------------------------------+ Experimenter's Guide To Daphne Page 245 Daphne Subroutines for Low Speed Camac I/O 3 October 1990 43 Daphne Subroutines for Low Speed Camac I/O Users may write routines to control Camac devices through the Kinetic Systems Model 3989 RS-232 crate controller. To use these routines one must know the name of the VAX terminal port which is connected to the crate controller. Normally, this is posted in a conspicuous place near the crate controller. 43.1 Sharing an I/O Device If you wish to run a program from a second command terminal to perform Camac operations while acquisition is active, and to use the same terminal port that is used to load the Event Handler and read-out scalers, then you must exercise some foresight. Under normal circumstances only one process can use a non-shareable I/O device (such as a terminal port) at a time. However, some of the acquisition programs have SHARE privilege which allows them to use a non-shareable device even when it is owned by another user. Under the circumstances described above, you should log on to the second terminal and start your Camac program BEFORE executing the Daphne $CDV command on your main command terminal. If you execute the $CDV command first, then when you run your own program, you will receive the error message: %SYSTEM-W-DEVALLOC, device already allocated to another user 43.2 Fortran Callable Routines 43.2.1 Open I/O Channel +--------------------------------------------------------------+ | call init_term (device-name) | | | | device-name - input/character string | | name of the I/O device to be used to | | communicate with the crate controller | +--------------------------------------------------------------+ 43.2.2 Close I/O Channel +----------------------------------------------------+ | call close_term | +----------------------------------------------------+ Experimenter's Guide To Daphne Page 246 Daphne Subroutines for Low Speed Camac I/O 3 October 1990 43.2.3 Camac Operation +----------------------------------------------------+ | call cnaf (crate,slot,address,func,data) | | | | crate - input/integer*4 | | crate number | | | | slot - input/integer*4 | | slot within crate of module | | | | address - input/integer*4 | | sub-address within module | | | | func - input/integer*4 | | Camac function code | | | | data - output/integer*4 | | | | read code: output/integer*4 | | write code: input/integer*4 | | control code: not used | +----------------------------------------------------+ This routine does not return to the caller if there is an I/O error. This routine returns to the user only if there is no detected error 43.3 Linking +--------------------------------------------------------------+ | $ LINK MYPROGRAM,DAPDIR:DAPHNE/LIBRARY,DAPMSG:MSG/LIBRARY | +--------------------------------------------------------------+ Experimenter's Guide To Daphne Page 247 The Tektronix 4100 Series Terminals 3 October 1990 44 The Tektronix 4100 Series Terminals The Tektronix 4100 series terminals have a large number of "setup" switches which can make it difficult to use the first time. 44.1 SETUP Mode To enter Setup mode hit the SETUP key. It should respond by giving an asterisk as a prompt character. Hit the SETUP key a second time to leave Setup mode. Use the STATUS command to find the current value of all the Setup switches, or a particular switch. The first command below will display the value of all Setup switches; the second will display the value of just the FLAGGING switch; the third command will display the state of all Setup switches related to "communications" (one of several Setup switch groups). * STATUS * STATUS FLAGGING * STATUS COMMUNICATIONS Setup switches may have one or more parameters, some of which may be defaulted. Setup parameters may be strings (like "IN/OUT") or numbers. To change the value of a Setup parameter, give its name and new value. For instance, to set the baud rate of the terminal to 9600 use the following command: * BAUDRATE 9600 44.2 Using a Tektronix 4100 with VAX/VMS To set the 4115, 4114, 4111, or 4107A setup switches for communication with VAX/VMS and Daphne use the following commands: * FLAGGING IN/OUT * BYPASSCAN * REOM 1 If using a color hardcopy unit: * HCINTERFACE COLOR If using a black-and-white (monochrome) hardcopy unit: * HCINTERFACE MONO Experimenter's Guide To Daphne Page 248 The Tektronix 4100 Series Terminals 3 October 1990 44.3 Emulating Tektronix 4000 Series Terminals (4006/4010/4014/4015) To run the 4115 or 4114 in Tektronix 4000 emulation mode one must use the following command in addition to the ones given above: * DAENABLE NO To run the 4107A or 4111 in Tektronix 4000 emulation mode one must use the following commands in addition to the ones given in the previous section: * CODE TEK * DAENABLE NO 44.4 Emulating a DEC VT100 using the Tektronix 4107A or 4111 The Tektronix 4107A and 4111 can be set to emulate most functions of the VT100 by using the following Setup command, * CODE EDIT and making the dialog area visible by hitting the DIALOG key once or twice. 44.5 Saving SETUP changes For the 4115, all changes made to SETUP switches are automatically placed in non-volatile memory, and will be saved even if the terminal is turned off. For the 4107A and 4111, changes made to SETUP switches are NOT saved unless the following command is issued to transfer the Setup information to non-volatile memory: * NVSAVE 44.6 Setup HELP On the 4107A the following command displays the syntax of each Setup command: * HELP If the information is displayed on the screen too quickly use control/S and control/Q to control the flow of text to the screen. There is no comparable command for the 4111 or 4115. Experimenter's Guide To Daphne Page 249 The Tektronix 4100 Series Terminals 3 October 1990 44.7 Factory Defaults The 4107A and 4111 can be set to factory defaults with the following command: * FACTORY The 4115 can be set to factory defaults using the following procedure from pages B-2 and B-5 of the Tektronix 4115 Operator's Manual: - On the 4115 pedestal, below the table which supports the keyboard, locate the SELF-TEST and RESET buttons on the front right-hand side. - Press the SELF-TEST button, and then press and release the RESET button. Continue to hold down the SELF-TEST button until the keyboard indicator lights begin to cycle (about 3 seconds). You can then release the SELF-TEST button. - When the bell rings, enter control/C and wait about 15 seconds for the "411X" menu to appear. - In response to the 411X menu, press Function Key 2 on the upper left-hand side of the keyboard. After a few seconds the "Processor Board" menu will appear. - In response to the "Processor Board Menu", press Function Key 1. After a few seconds the "CMOS Reset" menu will appear. - In response to the "CMOS Reset" menu, enter control/E to exit the self-test sequence. The following options must normally be entered after a Tektronix 4100 terminal has been reset to factory defaults: * BAUDRATE 9600 * FLAGGING IN/OUT * BYPASSCAN * REOM 1 If using a color hardcopy unit: * HCINTERFACE COLOR If using a black-and-white (monochrome) hardcopy unit: * HCINTERFACE MONO Experimenter's Guide To Daphne Page 250 DEC VT240 Emulation of Tektronix 4000 3 October 1990 45 DEC VT240 Emulation of Tektronix 4000 The Digital Equipment Corporation VT240 terminal can be set to emulate a Tektronix 4000 series terminal (4006/4010/4014/4015) albeit slowly, and with significantly poorer resolution. Nonetheless, this can be useful when high resolution displays are unavailable. To configure the VT240 to emulate a Tektronix 4000 series terminal, hit the SETUP key on the keyboard in order to get into the VT240 main Setup Menu. Select the "General" sub-menu. In the "General" sub-menu there is a panel which will be in one of the following states: - VT240 - 8 bit Controls - 4010/4014 Mode - VT52 Mode - VT100 Mode - VT240 - 7 bit Controls Use the ENTER key on the keypad to move through the list until the 4010/4014 option is displayed. Leave the menu by hitting the Setup key. When the VT240 is emulating the graphic input feature of the Tektronix the arrow keys move the cross-hairs in the obvious directions. Movement of the cross-hairs can be speeded up by holding down the shift key at the same time as the arrow key. To terminate the cursor position report it may be necessary to hit the RETURN or ENTER key. To emulate the PAGE key use the NEXT PAGE key of the VT240 keyboard. Experimenter's Guide To Daphne Page 251 Physical Connections 3 October 1990 46 Physical Connections 46.1 Multibus/Unibus Interface The Multibus half of the Multibus/Unibus interface occupies the rightmost slot of the Multibus. It is connected to the VAX by two, flat, 25 twisted pair cables labeled "Z1" and "Z2". Cable Z2 goes to the upper edge connector, while cable Z1 goes to the lower one. The connectors are not keyed, but should be plainly labeled. 46.2 Cable Receiver Each flat cable running from an experimental station to the EMUX should be labeled with the name of an experimental station. Locate the cable for your experimental station and find out which Cable Receiver of the EMUX it is connected to. On the Cable Reciver there are two connectors, one labeled "IN" the other labeled "OUT". The cable should be connected to "IN". The "OUT" connector is not used. 46.3 Event Distributor (EMUX) The Cable Receivers are housed in a Camac crate with numbered slots starting at 1. Each EMUX, Primary and Secondary, has a set of five switches which can be programmed with the slot number of a Cable Receiver. If you are using Multibus A (Multibus B) set the address switches of the Primary EMUX (Secondary EMUX) to the slot number of your Cable Receiver minus 1. Thus, if the Cable Receiver is in slot 17, select address 16 by moving switches 1, 2, 4, and 8 to the left, while moving switch 16 to the right. Check that the other EMUX does not have the same select address as the EMUX you have just programmed. At the top of the EMUX is a GO/NO switch for each EMUX. The GO/NO switch for the Primary (Secondary) EMUX is on the left (right). Reset the appropriate EMUX by first moving the switch to the GO position, then to the NO position, and back to the GO position. Experimenter's Guide To Daphne Page 252 Physical Connections 3 October 1990 46.4 Multibus The Event Processor boards are the only double width boards in the Multibus crate. The Event Processor FIFO is the 3/4 height board sitting piggy-back on the Event Processor board. A flat, 25 twisted pair cable leads from the Primary (Secondary) EMUX to the FIFO boards of each of the Event Processors in Multibus A (Multibus B). The EMUX end of the cable is keyed. The cable has a half twist between the EMUX and the Event Processors, so that the top wires coming out of the EMUX become the bottom wires on the FIFO. The FIFO connectors on the cable are not keyed, but will be plainly labeled. The Event Processors must occupy Multibus slots that have been wired for parallel bus arbitration. These Multibus slots have been marked at the top or bottom with the symbols "EP" or "P". Each Event Processor has a number between 1 and 16 written on the push tab plainly visible when the processor is in the Multibus. There should be no two Event Processors with the same number in a Multibus. There should be exactly one FIFO card, usually on Event Processor 1, with about 10 precision resistors that provide electrical termination of the Event Processor FIFO daisy-chain. The resistors are located at the top front edge of the FIFO card. Event Processor 1 is special in another way: it is configured to provide timing signals required for the proper operation of the Multibus. Thus, even when the CPU on EP 1 is not operating properly, its presence in the Multibus is necessary. If EP 1 is causing problems with acquisition, it can be removed from the set of processors that the acquisition program will use by redefining the logical name "DAP$CONFIGURE_EP_x" (Section 27.5). The command can disconnect the processor "logically", but it will remain connected electrically. This makes sense as the hardware on the processor card will usually continue to provide the proper Multibus signals even when the CPU is no longer running. Experimenter's Guide To Daphne Page 253 Physical Connections 3 October 1990 46.5 Kinetic Systems 3989 Crate Controller The crate controller sits in the rightmost two slots of the Camac crate. An RS-232 line runs from the DB-25 connector to the VAX. The crate controller may be connected to other crate controllers in daisy-chain fashion. A lemo cable connects REQUEST to GRANT IN. This connection must be made on every 3989 crate controller. A lemo cable connects GRANT OUT of the crate controller to GRANT IN on the AUX. If this is a two crate Event Handler system, make the same connection for the second AUX and its crate controller. At the rear of the crate controller, a ribbon cable connects to the rear of the AUX. Both ends of the ribbon cable are keyed. Different connectors are required for the AUX depending on whether it is a black or silver AUX. If this is a two crate Event Handler system, make the connection for the second AUX and its crate controller. The proper setting of the 3989 crate controller jumpers and DIP switches is described in section 48. Pay particular attention to the section describing configuration for multi-drop vs. single crate operation. Experimenter's Guide To Daphne Page 254 Physical Connections 3 October 1990 46.6 Cable Driver The Cable Driver occupies slot 23 of the Camac crate. Input is from the adjacent Kinetic Systems 3841 FIFO through a front panel connector. Output is through a flat, 25 twisted pair cable which goes to the Cable Receiver in the EMUX crate in the computer room. The label on the cable should match what is written on the other end of the cable in the computer room. 46.7 Kinetic Systems 3841 FIFO The FIFO occupies slot 22 of the Camac crate. Input is from the adjacent AUX controller by a front panel, multi-pin connector. Output is to the Cable Driver in slot 23 by another front panel, multi-pin connector. 46.8 Jorway Model 41 NIM Output Register The NIM output register in slot 16 should have the least significant bit (bit 1) connected by lemo cable to the Event Handler front panel input 8. When the Event Handler sees front panel input 8 go to "1" it starts acquisition; when it goes to "0" is stops acquisition. The same information is available to user devices from bits 2 and 3 of the NIM output register. I recommend that users who wish to fan-out the acquisition start/stop signal use bits 2 or 3 rather than bit 1 of the output register. If bit 1 is connected directly to the Event Handler there is little likelihood that any acquisition start/stop problems are due to devices inserted by the user between the NIM output register and the Event Handler Experimenter's Guide To Daphne Page 255 Physical Connections 3 October 1990 46.9 Event Handler and Primary AUX There are two versions of the Event Handler and AUX controller. The older ones are made by wirewrap and have flat black front panels. The newer ones are made using Multiwire, have silver colored front panels, and have traces run on the board. A diagram of the front panel of each unit can be found between sections 19 and 20. The black units are two dual-width modules that normally occupy slots 18 through 21 inclusive. The silver units are single, dual-width modules that normally occupy slots 19 and 20. The NIM and TTL inputs of the EH can be distinguished by markings on jacks. On old Event Handlers the NIM inputs are silver colored, while the TTL inputs are bronze colored. On new Event Handlers the NIM inputs have a black half circle around the jack, while the TTL inputs are unmarked. Front panel input 8 should be connected to the least significant bit (bit 1) of the NIM Output Register in slot 16. The Event Handler watches this signal to determine when acquisition has started or stopped. There are three front panel outputs labeled "BUSY". One generates TTL signals while the other two generate NIM signals. The BUSY output is logic "1" when acquisition is not active or the Event Handler is busy processing an event. It is "0" when acquisition is active and the Event Handler is ready to process an event. There are two front panel inputs labeled "EVENT". One is for TTL signals, while the other is for NIM signals. Both inputs are edge triggered. When there is a valid event, user electronics should generate a logic "1" that lasts at least 50 nSec to signal the Event Handler that an event has occurred. The primary AUX is connected to the adjacent FIFO by a multi-pin front panel connector. Black and silver AUX controllers require different connectors. The primary AUX is connected by a flat cable running from its rear to the rear of its crate controller. Black and silver AUX controllers require different connectors. Experimenter's Guide To Daphne Page 256 Physical Connections 3 October 1990 46.10 Secondary AUX The second AUX is required only if the Camac devices to be read-out occupy a second crate. The second AUX is connected to the Event Handler and first AUX in daisy-chain fashion. The cable is a 40 pin flat cable with keyed connectors. Consult section 47 for information on how to configure an AUX for operation in crate 2, or as a secondary AUX. NOTE The cable connecting the second AUX to the first AUX should be shorter than 1 meter to reduce problems due to noise and reflections. The second AUX may be placed in any available slot of the second crate, but by convention it is placed in the same slot of the second crate it would occupy were it a single crate system: slot 20 for a single width unit, slots 20 and 21 for a dual-width unit. The secondary AUX is connected by a flat cable running fron its rear to the rear of its crate controller. Black and silver AUX controllers require different connectors. Experimenter's Guide To Daphne Page 257 Configuring the AUX Crate Controller 3 October 1990 47 Configuring the AUX Crate Controller There are two versions of the AUX controller and Event Handler. The older ones are made by wirewrap and have flat black front panels. The newer ones are made using Multiwire, have silver colored front panels, and have traces run on the board. 47.1 Primary and Secondary AUX Controllers A primary AUX connects the Event Handler to the FIFO, as well as performing Camac I/O operations. A secondary AUX connects the Event Handler to a Camac crate, but does not transfer any data to the FIFO. In this document I have assumed that the primary AUX is AUX 1, and the secondary AUX is AUX 2, but this need not be the case. In discussing how to configure an AUX this distinction is important. The silver AUX controllers can be subdivided into two kinds, depending on whether they were designed as primary or secondary AUX controllers. The silver, primary AUX controller, is built as one-half of a combined Event Handler/AUX dual-width module. The silver, secondary AUX controller, is a single width module. All black AUX are capable of serving as either a primary or secondary AUX. A silver secondary AUX cannot serve as a primary AUX because it lacks some connections and logic required to connect to the external FIFO. A silver primary AUX can serve as a secondary AUX if its Event Handler is bypassed. Experimenter's Guide To Daphne Page 258 Configuring the AUX Crate Controller 3 October 1990 47.2 Configuring an AUX for Crate 1 or Crate 2 Both black and silver AUX can be configured to serve as an AUX 1 or an AUX 2. The current configuration of an AUX can be determined by looking at front panel lights with the labels "1" and "2". Disconnecting a black Event Handler from its companion AUX and connecting it to another one requires disconnecting and reconnecting two short cables. This will require some manual dexterity, and may even require that the front panel of the units be removed, in order to create a little extra working space for fingers. On silver AUX controllers the DIP switches are near the top right hand side of the unit, when looking at the module with the front panel to the right. Crate 1 Crate 2 silver AUX switch 1 (bottom) off/left on/right silver AUX switch 2 (top) off/left on/right On black AUX controllers the DIP switch can be seen through a small square hole cut through the side panel near the top right hand side of the module, when looking at the module with the front panel to the right. The DIP switch is mounted with switch "1" above switch "2" and the OPEN position to the left. Switch 1 must always be closed for proper operation of the AUX. Crate 1 Crate 2 black AUX switch 1 (top) closed/right closed/right black AUX switch 2 (bottom) open/left closed/right Experimenter's Guide To Daphne Page 259 Configuring the Kinetic Systems Crate Controller 3 October 1990 48 Configuring the Kinetic Systems Crate Controller 48.1 Position of Jumpers and Switches This describes the normal position of switches and jumpers for the Crate Controllers at Atlas. Descriptions of "left" and "right" assume that the board is held with the front panel to the right and the writing on the board upside up. See section 48.5 for the location of jumpers and switches on the circuit board. P-2 Hold enable: make jumper Q Reset on Z disable: make jumper T Transmit Clock asynchronous: make jumpers O and L RS-232/RS-422 RS-232: make jumpers E, H, and K (Experience shows that jumper H is not necessary) RTS disable: make jumper B DTR disable: make jumper D Mode 4 position dip switch Asynchronous with 1 stop bit position 1 off (to left) position 2 on (to right) position 3 on (to right) Normal Operation position 4 on (to right) Format 8 position dip switch Ascii Decimal position 1 on (to right) position 2 on (to right) Parity Disabled position 3 on (to right) position 4 on (to right) Checksum Disabled position 5 on (to right) Not Used position 6 on (to right) position 7 on (to right) position 8 on (to right) Baud Rate 4 position dip switch 9600 baud position 1 on (to right) position 2 off (to left) position 3 off (to left) position 4 off (to left) Experimenter's Guide To Daphne Page 260 Configuring the Kinetic Systems Crate Controller 3 October 1990 Crate Address 8 position dip switch crate 1 crate 2 crate 4 position 1 to left to right to right position 2 to right to left to right position 3 to right to right to left position 4 to right to right to right position 5 to right to right to right position 6 to right to right to right position 7 to right to right to right position 8 to right to right to right Do NOT configure a controller with a crate address of 3. This will cause communication problems because the binary value 3 is used to terminate messages sent by a crate controller to the host. Addresses of 4,5,6,7, and so on are okay. 48.2 Multi-Drop Mode There is an undocumented jumper (with 3 pins) located just below and to the left of the baud rate switch, next to the silver colored baud rate generator. On the manufacturer's schematics it is labeled "U/V". When using several 3989 crate controllers in multi-drop mode, there must be exactly one crate in the daisy-chain with a 5.6 kOhm resistor added to the backplane. On the modified 3989, the jumper should connect pin "V" to the unlabeled pin directly above it. All other boards in the daisy-chain must NOT have the resistor modification and must have the U/V jumper removed. 48.3 Single Crate Mode If there is only a single crate in the daisy-chain, then the placement of the U/V jumper (described above) depends on whether the 3989 has had the 5.6 kOhm resistor added to its backplane. If the resistor is present, the "V" pin should be connected to the unlabeled pin directly above it. If the resistor is not present, then the jumper should connect pin "U" to pin "V". 48.4 Connection to AUX On the front panel KS/CC REQUEST should be connected to KS/CC GRANT IN. The KS/CC GRANT OUT should be connected to the AUX GRANT IN. On the rear of the unit there should be a cable running to an AUX if one is present in that crate. Experimenter's Guide To Daphne Page 261 Configuring the Kinetic Systems Crate Controller 3 October 1990 48.5 Position of Jumpers +----------------------------------------------------------------+ | | | X Q/R X Crate Address | | X | +---+ X | | X S/T | | X Baud | | X Rate | | b | | blank/V/U -> V | | (in this order) U | | X Mode X A/B | | X X C/D | | X E/F | | X Format X L/M X G/H | | X X J/K | | X X N/O/P | | X | | | +--------------------------------------------------------------------+ 48.6 Status Lights - ADD REC - Address Recognized (3989 has received a message) - S/B - Sync/Break Detect (Not used in Daphne) - CS ERR - Checksum Error (Not used in Daphne) - IF - Invalid Format (Not a valid NAF combination) - TC - Transfer Complete (Message transmitted to host) - RSV - Requesting Service BREAK condition - Not used in Daphne - OPT - Option Mode (Not used in Daphne) - BUSY - Executing a dataway cycle - NO-Q - NO-X - INHIBIT - Camac INHIBIT is set - L-SUM - A module is asserting its LAM Experimenter's Guide To Daphne Page 262 Configuring the Event Distributor (EMUX) 3 October 1990 49 Configuring the Event Distributor (EMUX) While the EMUX has data, it is continually checking the the on-board FIFO of each processor to see if it is empty. It starts with processor 1 and polls each FIFO in turn. The number of the last processor to be checked is encoded in a four position DIP switch on the EMUX board. Since the EMUX is really a dual unit, there are actually two such switches. This is not a critical adjustment since the EMUX is designed to recognize when an addressed FIFO is not present and skip to the next unit. The DIP switch is normally set to the maximum number of processors likely to ever be used on the Multibus. Experimenter's Guide To Daphne Page 263 How to Backup Your Files to Tape 3 October 1990 50 How to Backup Your Files to Tape Do you keep data on disk which is essential to the interpretation of your experiment and difficult to reproduce ? Do you have programs on the disk which have taken you days to develop and debug ? Are you about to run out of disk space ? The amount of disk space you can use will be limited either by the capacity of the disk or by "quotas" placed on your account by the "System Manager". In VAX/VMS, disk quotas depend both on your UIC ("user identification code") and the disk on which you wish to place a file. It is possible to use up your quota on one disk, yet still be able to create files on a second disk. Disk space on VAX/VMS is measured in units of 512 byte blocks. To determine your quota use the following command: $ SHOW QUOTA User [EXP] has 24541 blocks used, 375459 available, of 400000 authorized and permitted overdraft of 40000 blocks on SYS$SYSDEVICE Your current disk is given by the logical name "SYS$DISK". To find the total space available on your current disk: $ SHOW DEVICE SYS$DISK Device Device Error Volume Free Trans Mnt Name Status Count Label Blocks Count Cnt DUA0: Mounted 0 ATLAS_VMSV4 143130 160 1 Note that in the above case, the quota for EXP far exceeds the amount of space actually available. Take 10 minutes to back up your files to tape. The backup can take place while acquisition is running, if there is a free tape drive. I recommend the use of the VAX/VMS $BACKUP utility over the $COPY utility because it is far more resistant to single tape failures. A secondary consideration is that it generally requires less tape. Do not mix tapes created with $BACKUP with other tapes, especially Daphne data tapes. The output from the $BACKUP utility is called a save-set, and consists of a "file" which contains all the files you want saved. Many save-sets can be placed on a single tape, or a single save-set can span several tape volumes. Try to avoid splitting save-sets across tapes. This can cause book-keeping problems. If a save-set is too large to fit on a single tape, start it at the beginning of a tape and do not put any other save-sets on the continuation tapes. Experimenter's Guide To Daphne Page 264 How to Backup Your Files to Tape 3 October 1990 Let's assume that you have a new tape on which you want to place all your files of value using tape drive "MFA0:" at 6250 BPI. - Load Tape With Write Ring Start by loading the tape on the selected tape drive with a write-ring. - New Tape or Scratch tape - then $INITIALIZE Skip this step if your tape already contains one or more save-sets. Choose a label for your tape of no more than 6 alphanumeric characters, for example, "MYDATA". ################################################### ## ## ## Execute the following command only if: ## ## Tape is a new tape or a scratch tape ## ## and contains no useful data of any kind ## ## ## ################################################### $ INITIALIZE/DENSITY=6250 MFA0: MYDATA - $MOUNT Assume that the label of your tape is "MYDATA". The following command makes the tape available to programs: $ MOUNT/FOREIGN MFA0: MYDATA The "/FOREIGN" qualifier tells VMS that the tape will not necessarily follow the conventions used by VMS for managing files on a tape. - Choose a Save-Set Name You can give a name of up to 39 characters to your save-set. The name can be made up from the 36 alphanumeric characters and a few special characters such as the underscore ("_") and dollar-sign ("$"). My practice is to use a suggestive (but not lewd) name combined with the date in some easy to remember format, for example, "ICE_21JUL86AM". It can be quite inconvenient to have two save sets on a tape with the same name. Experimenter's Guide To Daphne Page 265 How to Backup Your Files to Tape 3 October 1990 - Backing up Nearly Everything The normal type of backup is to save everything worth saving in your usual directory and all its subdirectories. If you are unsure of your current directory use the following command: $ SHOW DEFAULT SYS$SYSDEVICE:[EXP.ICE] For instance, if your usual directory is [EXP.ICE], then the following command would save everything but the "global section files" (which have no value since they are just temporary files): $ BACKUP [EXP.ICE...]/EXCLUDE=(*.SEC) - MFA0:ICE_21JUL86.BAC/SAVE - /COMMENT="SAVE ALL AFTER CALIB. OF DET. 1 to 5 COMPLETED" - Backing Up files Created by $WR The standard $BACKUP command given above will save just about everything, including the *.HS1 and *.HS2 created by the the "Write Histogram" command. However, by using special qualifiers one can optimize the backup process for the large files created by the $WR command. This generally isn't worthwhile when there are a large number of small files. $ BACKUP [EXP.ICE...]*.HS1,*.HS2 - MFA0:ICE_WR_21JUL86.BAC/SAVE - /BLOCK=32000 - /COMMENT="SAVE JUST HISTOGRAMS CREATED BY $WR COMMAND" Experimenter's Guide To Daphne Page 266 How to Backup Your Files to Tape 3 October 1990 - $BACKUP Options of General Interest - /VERIFY After writing the files to the tape, the tape will be rewound and the data read back and compared with the original disk file. Any discrepancies will be reported. - /LIST or /LIST=file The first form gives a list of files copied to the tape on the terminal. The second form places the list of files into a file of your choice. For instance, to get a list of the files as they are being backed up one might use the command: $ BACKUP [EXP.ICE...]/EXCLUDE=(*.SEC) - MFA0:ICE_21JUL86.BAC/SAVE - /LIST=FILES_BACKED_UP_21JUL86.LIS - /COMMENT="CALIB. OF DETECTORS 1 to 5 COMPLETED" File names can be as long as 39 characters and contain underscores ("_") and dollar-sign ("$"). - /INTERCHANGE If you intend to make copies of the tape, you should use this qualifier. This changes the manner in which $BACKUP handles recoverable tape errors. Without this qualifier, most programs will have trouble copying the tape. - Do NOT Use /REWIND The /REWIND qualifier places the save-set at the beginning of the tape DESTROYING any other data on the tape. I mention this qualifier here only to warn users NOT to use it. - $DISMOUNT This unloads the tape and frees the drive. $ DISMOUNT MFA0: I will not describe how to restore files from a tape save-set. With luck you will not need to do this, and besides, restoring files from a save-set is not for the beginner. If you need to restore files consult the VMS Utilities manual or a member of the computer staff. Experimenter's Guide To Daphne Page 267 How to Make Copies of Data Tapes 3 October 1990 51 How to Make Copies of Data Tapes The simplest method of copying data tapes is to use the Daphne TAPECOPY utility program. If the program encounters blocks on the tape that cannot be read, the program reports the error, and continues the copy operation with the next block on the tape. Assume that the original tape is on MFA0: and that the new tape is threaded on MFA1: To copy the tape from MFA0: to MFA1: at 6250 bpi: $ MOUNT MFA0:/FOREIGN/OVERRIDE=ID !mount original tape $ INITIALIZE MFA1:/DENSITY=6250 X !init destination tape $ MOUNT MFA1:/FOREIGN/DENSITY=6250/OVERRIDE=ID !mount destination tape $ RUN DAPEXE:TAPECOPY Input tape unit (Example: MT:) MFA0: Output tape unit (Example: MF:) MFA1: Number of blocks read: 1375 Number of files read: 4 $ DISMOUNT MFA1: $ DISMOUNT MFA0: If many tapes are being copied, it is worthwhile to put these statements into a command file, which can then be invoked with just a few keystrokes. $ set noon $ dismount/nounload mfa0: $ dismount/nounload mfa1: $ again: $ initialize mfa1:/density=6250 x $ mount mfa0:/foreign/ov=id/block=13000 $ mount mfa1:/foreign/ov=id/block=13000 $ set magtape/rewind mfa0: $ set magtape/rewind mfa1: $ run dapexe:tapecopy mfa0: mfa1: $ dismount mfa0: $ set magtape/rewind mfa1: $ dump mfa1:/block=(start:1,end:1) $ dismount mfa1: $ show time $ inquire dummy "Hit return to continue with new tape on mfa1:" $ goto again The TAPECOPY program can be used to combine several Daphne data tapes onto a single reel. The procedure starts out as above, but the output tape should be neither dismounted nor rewind until the last tape is copied to it. This will work because the TAPECOPY program, after writing two end-of-file marks on the output tape, skips backward one end-of-file mark, leaving the output tape properly positioned for additional TAPECOPY operations. Experimenter's Guide To Daphne Page 268 File Name Conventions 3 October 1990 52 File Name Conventions This is a list of file types and file names that have special meaning to Daphne. This list does not include file types which are already used only by VMS. The string "ttt" represents the three character Daphne identifier used in the $DAP command. The string "nnn" represents a number padded with zeroes to three characters. .A - GNX archive (object library) .ASC1D - $WR/ASCII for 1D histogram .ASC2D - $WR/ASCII for 2D histogram .ASM - GNX assembler source code .BAD - Dump of malformed events reported by Event Processors .CNT - Condition counts from the $CNT program .CON - Condition definitions .EHA - Event Handler assembler source code .EHO - Event Handler object code .EXE - Executable code from GNX or VMS linker .FOR - Fortran 77 source for the GNX or VMS compilers .HS1 - One dimensional histogram data from $WR .HS2 - Two dimensional histogram data from $WR .OBJ - Object code from GNX or VMS compilers or assemblers .PAS - Pascal source code .PLT - Plot file for hardcopy device from $P1H or $P2H .PRT - Dump of histograms from $PT1H or $PT2H .SAV - Daphne configuration from the $SAV program .SCL - Scaler configuration definition from $SWSC or $PTSC .SETUP - $SAV/COMMAND command files .SPC - SAP spectrum catalog .SPH - SAP spectrum header .SPS - SAP spectrum .SUM - Log file from SUM program .SV - Scaler values written by $PTSV .TAB - Log file from TABGEN .TRAP - Information about arithmetic traps on the Event Processors ttt.LOG - Debugging information from NSSORT or VAXSORT DAPHNttt.LOG - Daphne log file (not a printable file) DAPSCLttt.SV - Scaler values from $PTSV DAPtttPAR.LIS - Daphne parameters from $PTP DSPttt.ERR - Error file from display process DSPttt.OUT - SYS$OUTPUT file from display process PLTttt.ERR - Error file from plot process PLTttt.OUT - SYS$OUTPUT file from plot process Experimenter's Guide To Daphne Page 269 List of Daphne Commands 3 October 1990 53 List of Daphne Commands 53.1 Alphabetical For detailed information on a command make use of the Daphne on-line HELP file. See section 3 for information on how to use the HELP command. A ACQ start acquisition AR1 1D histogram manipulation (add, sub, shift, etc.) AR2 1D histogram manipulation (add, sub, shift, etc.) B BANNER turns banner on or off BEAM banner information (beam) BLW expand 1D or 2D histogram on display BSP backspace tape C CDV define Camac device CDV/DEALLOC deallocate Camac device CHLOE synonym for SAP CLR clear graphics display CNAF execute Camac command CNT counts of events and conditions COMMENT banner information (comment) CON define conditions control/P during acquisition displays run time & event count CRSPFILE SAP - create spectrum file CUR display graphics cursor D D1H display 1D histogram D2H display 2D histogram DAP start Daphne DAQ display data acq. control block (for debugging) DDV define display device DISK define disk file to save (or replay) event data DO1H display 1D histogram overlayed on another histogram DSV display scaler values DW display window or linearization E EHASM assemble event handler program EHFIFO show data in event handler FIFO EHGO restart event handler EHSEND load program into event handler and start it ENDRDD wait for $RDD ("Replay Data from Disk") to complete ENDRDT wait for $RDT ("Replay Data from Tape") to complete ENERGY banner information EPFIFO show data in event processor FIFO EPLOAD load event processor program into event processor EPRESET reset Multibus (diagnostic program) EVS define event structure EXP banner information (experiment) EXT exit Daphne F FIX change value of integer (fixed point) parameter FIX/DEFINE give symbolic name to integer parameter FIX/DELETE delete symbolic name for integer parameter FIX/LIST list symbolic names and values of integer parameters FIXLOG fix corrupted log file by creating new version of it FLT change value of real (floating point) parameter FLT/DEFINE give symbolic name to real parameter FLT/DELETE delete symbolic name for real parameter FLT/LIST list symbolic names and value of real parameter FND position tape by run number Experimenter's Guide To Daphne Page 270 List of Daphne Commands 3 October 1990 G G1H define gate for 1D histogram G2H define gate for 2D histogram Experimenter's Guide To Daphne Page 271 List of Daphne Commands 3 October 1990 H H1 define 1D histogram H2 define 2D histogram HARDCOPY start hardcopy unit attached to display device I INZ enter (or modify) all banner information K KLG kill graphics (display) process KLP kill hardcopy plot process KLSORT kill sort process (use only if $STP fails) KLT kill tape process L LNZ define linearization LVT live time display of 1D hist. (continuously updated) (temporarily unavailable as of January '88) M M1 define 1D map M1H modify 1D histogram M1M modify 1D map M2 define 2D map M2H modify 2D histogram M2M modify 2D map MAPTODAP SAP - make Daphne histogram accessible to SAP MAX specify upper limits for Daphne resources MDV define Multibus device MDV/DEALLOC deallocate Multibus device MLNZ modify linearization O ONEOFN select only 1 out of N events for analysis OVR (not implemented) override condition value P P1H plot 1D histogram P2H plot 2D histogram PDV define plot device PDV/TYPE define plot device for metafile PHY banner information (physicist) PJX create projection of 2D histogram on X axis PJY create projection of 2D histogram on Y axis PO1H plot 1D histogram overlayed on another histogram PSEUDOEVENT enable use of pseudo-parameters in maps PT1H print 1D histogram (values of each bin printed out) PT2H print 2D histogram (values of each bin printed out) PTL print log file PTP print parameters PTSC print scaler configuration PTSV print scaler values R RD read histograms from disk file RDEV formatted dump of data from Daphne event tape RDD replay data from disk RDT replay data from tape RDD/EP replay data from disk through Event Processors RDT/EP replay data from tape through Event Processors RES restore Daphne definitions from disk file RETURN_TO_SAP resume SAP process REW rewind tape RN banner information (run number) Experimenter's Guide To Daphne Page 272 List of Daphne Commands 3 October 1990 S SAFE enables/disables program requests for confirmation SAV save Daphne definitions in disk file SAV/COMMAND save Daphne definitions as command file SCAMP record information from SCAMP control program (not implemented as of January '88) SCL/FILE define scaler configuration from command file SCL/MENU define scaler configuration interactively SIM generate simulated event stream SKP position tape by skipping files SNAPDIR display information about runs on a SNAP tape SP define X/Y axis parameters of scatterplot and display SP/COPY copy scatterplot and give it a new name SP/CREATE allocate memory for scatterplot SP/DEFAULT set defaults for attributes of new scatterplots SP/LIST list information about scatterplots SP/MODIFY change defaults attributes of existing scatterplots SP/RESUME allow update of scatterplot when displayed SP/SUSPEND prevent update of scatterplot when displayed SP/ZAP zero scatterplot SP/ZOOM display different section of scatterplot START_SAP start SAP process STP stop acquisition or replay SUM integrate region of 1D histogram or 2D histogram SW display information about a single map, histogram, window, etc. SWEV display formatted copy of tape buffer SWL show log SWP show parameter SWSC show scaler configuration SYS show status information about Daphne T TAPE define input or output tape TDIR display information about runs on a Daphne tape TEV enable or disable event mode recording TGT banner information (target) U UH user-defined operation on histogram USERFUNC identify user-function for replay W W1 define 1D window W2 define 2D window WR save histogram data in disk file (binary format) WR/ASCII save histogram data in text file X X1H delete 1D histogram X1M delete 1D map X1W delete 1D window X2H delete 2D histogram X2M delete 2D map X2W delete 2D window XG delete gates on a 1D or 2D histogram XLNZ delete linearization Z ZAP zero histograms, scalers, or condition counts Experimenter's Guide To Daphne Page 273 List of Daphne Commands 3 October 1990 53.2 By Subject Banner Information BANNER turns banner on or off BEAM banner information (beam) COMMENT banner information (comment) ENERGY banner information EXP banner information (experiment) INZ enter (or modify) all banner information PHY banner information (physicist) RN banner information (run number) TGT banner information (target) Camac CDV define Camac device CDV/DEALLOC deallocate Camac device CNAF execute Camac command EHFIFO show data in event handler FIFO EPFIFO show data in event processor FIFO Conditions and Gates CNT counts of events and conditions CON define conditions G1H define gate for 1D histogram G2H define gate for 2D histogram OVR (not implemented) override condition value XG delete gates on a 1D or 2D histogram ZAP zero histograms, scalers, or condition counts Control ACQ start acquisition DAP start Daphne ENDRDD wait for $RDT ("Replay Data from Disk") to complete ENDRDT wait for $RDT ("Replay Data from Tape") to complete EVS define event structure EXT exit Daphne KLSORT kill sort process (use only if $STP fails) MAX specify upper limits for Daphne resources ONEOFN select only 1 out of N events for analysis PSEUDOEVENT enable use of pseudo-parameters in maps RDD replay data from disk RDT replay data from tape RDD/EP replay data from disk through Event Processors RDT/EP replay data from tape through Event Processors SIM generate simulated event stream STP stop acquisition or replay TEV enable or disable event mode recording USERFUNC identify user-function for replay Experimenter's Guide To Daphne Page 274 List of Daphne Commands 3 October 1990 Define Objects CON define conditions CRSPFILE SAP - create spectrum file EVS define event structure FIX/DEFINE define integer (fixed point) parameter FLT/DEFINE define real (floating point) parameter H1 define 1D histogram H2 define 2D histogram LNZ define linearization M1 define 1D map M2 define 2D map MAX specify upper limits for Daphne resources SCL/FILE define scaler configuration from command file SCL/MENU define scaler configuration interactively SP define X/Y axis parameters of scatterplot and display SP/CREATE allocate memory for scatterplot USERFUNC identify user-function for replay W1 define 1D window W2 define 2D window Delete Objects CON delete conditions by recreating new conditions FIX/DELETE delete symbolic name for integer parameter FLT/DELETE delete symbolic name for real parameter G1H/DELETE remove gates on 1D histograms G2H/DELETE remove gates on 2D histograms M1M/DELETE remove reference to 1D histogram from map M2M/DELETE remove reference to 1D histogram from map SP/DELETE delete scatterplot X1W delete 1D window X2W delete 2D window X1H delete 1D histogram X1M delete 1D map X1W delete 1D window X2H delete 2D histogram X2M delete 2D map XG delete gates on a 1D or 2D histogram XLNZ delete linearization Device Assignment and Deassignment CDV define Camac device CDV/DEALLOC deallocate Camac device DDV define display device DISK define disk file to save (or replay) event data KLG kill graphics (display) process MDV define Multibus device MDV/DEALLOC deallocate Multibus device PDV define plot device PDV/TYPE define plot device for metafile KLP kill plot process TAPE define input or output tape KLT kill tape process Experimenter's Guide To Daphne Page 275 List of Daphne Commands 3 October 1990 Display (To select second display device use the /SECOND qualifier) BLW expand 1D or 2D histogram on display CHLOE synonym for SAP CLR clear graphics display CUR display graphics cursor D1H display 1D histogram D2H display 2D histogram DDV define display device DO1H display 1D histogram overlayed on another histogram DW display window or linearization HARDCOPY start hardcopy unit attached to display device KLG kill graphics (display) process LVT live time display of 1D histogram (continuously updated) (unavailable as of January '88) SP define X/Y axis parameters of scatterplot and display SP/ZOOM display different section of scatterplot SUM integrate region of 1D or 2D histogram Event Handler CDV define Camac device CDV/DEALLOC deallocate Camac device EHASM assemble event handler program EHFIFO show data in event handler FIFO EHGO restart event handler EHSEND load program into event handler and start it EPFIFO show data in event processor FIFO Event Processor and Multibus EHFIFO show data in event handler FIFO EPFIFO show data in event processor FIFO EPLOAD load event processor program into event processor EPRESET reset Multibus (diagnostic program) MDV define Multibus device MDV/DEALLOC deallocate Multibus device ONEOFN select only 1 out of N events for analysis Fix and Float Commands FIX change value of integer (fixed point) parameter FIX/DEFINE give symbolic name to integer parameter FIX/DELETE delete symbolic name for integer parameter FIX/LIST list symbolic names and values of integer parameters FLT change value of real (floating point) parameter FLT/DEFINE give symbolic name to real parameter FLT/DELETE delete symbolic name for real parameter FLT/LIST list symbolic names and value of real parameter Experimenter's Guide To Daphne Page 276 List of Daphne Commands 3 October 1990 Histogram (Does not include histogram display commands) AR1 1D histogram manipulation (add, sub, shift, etc.) AR2 1D histogram manipulation (add, sub, shift, etc.) G1H define (or drop) gate on 1D histogram G2H define (or drop) gate on 2D histogram H1 define 1D histogram H2 define 2D histogram M1 associate map with 1D histogram M2 associate map with 2D histogram M1H modify 1D histogram M2H modify 2D histogram M1M add (or remove) reference to 1D histogram from map M2M add (or remove) reference to 1D histogram from map P1H plot 1D histogram P2H plot 2D histogram PJX create projection of 2D histogram on X axis PJY create projection of 2D histogram on Y axis PT1H print 1D histogram (values of each bin printed out) PT2H print 2D histogram (values of each bin printed out) RD read histograms from disk file UH user-defined operation on histogram WR save histogram data in disk file (binary format) WR/ASCII save histogram data in text file X1H delete 1D histogram X2H delete 2D histogram ZAP zero histograms, scalers, or condition counts Kill Processes KLG kill graphics (display) process KLP kill plot process KLSORT kill sort process (use only if $STP fails) Linearizations LNZ define linearization MLNZ modify linearization XLNZ delete linearization DW draw linearization on display unit Experimenter's Guide To Daphne Page 277 List of Daphne Commands 3 October 1990 List Information on Terminal (Many also have /PRINT or /OUTPUT options) CNT counts of events and conditions control/P during acquisition displays run time & event count DAQ display data acq. control block (for debugging) DSV display scaler values FIX/LIST list symbolic names and values of integer parameters FLT/LIST list symbolic names and value of real parameter PTSV print scaler values RDEV formatted dump of data from Daphne event tape SNAPDIR display information about runs on a SNAP tape SP/LIST list information about scatterplots SW display information about a single map, histogram, window, etc. SUM integrate region of 1D histogram SWEV display formatted copy of tape buffer SWL show log SWP show parameter SWSC show scaler configuration TDIR display information about runs on a Daphne tape Maps M1 define 1D map M1M modify 1D map M2 define 2D map M2M modify 2D map X1M delete 1D map X2M delete 2D map Miscellaneous DAQ display data acq. control block (for debugging) FIXLOG fix corrupted log file by creating new version of it HARDCOPY start hardcopy unit attached to display device ONEOFN select only 1 out of N events for analysis SAFE enables/disables program requests for confirmation SCAMP record information from SCAMP control program (not implemented as of January '88) SYS show status information about Daphne Modify Definitions FIX change value of integer (fixed point) parameter FLT change value of real (floating point) parameter M1H modify 1D histogram M1M modify 1D map M2H modify 2D histogram M2M modify 2D map MLNZ modify linearization OVR (not implemented) override condition value SP/MODIFY change defaults attributes of existing scatterplots Plot on Hardcopy Device HARDCOPY start hardcopy unit attached to display device KLP kill hardcopy plot process P1H plot 1D histogram P2H plot 2D histogram PDV define plot device PDV/TYPE define plot device for metafile PO1H plot 1D histogram overlayed on another histogram Experimenter's Guide To Daphne Page 278 List of Daphne Commands 3 October 1990 Print on Hardcopy Device PT1H print 1D histogram (values of each bin printed out) PT2H print 2D histogram (values of each bin printed out) PTL print log file PTP print parameters PTSC print scaler configuration PTSV print scaler values SAP CHLOE synonym for SAP CRSPFILE SAP - create spectrum file MAPTODAP SAP - make Daphne histogram accessible to SAP RETURN_TO_SAP resume SAP process START_SAP start SAP process Scalers DSV display scaler values PTSC print scaler configuration PTSV print scaler values SCL/FILE define scaler configuration from command file SCL/MENU define scaler configuration interactively SWSC show scaler configuration ZAP zero histograms, scalers, or condition counts Save/Restore FIX/LIST use /COMMAND/OUTPUT=file to create command file FLT/LIST use /COMMAND/OUTPUT=file to create command file RD read histograms from disk file RES restore Daphne definitions from disk file SAV save Daphne definitions in disk file SAV/COMMAND save Daphne definitions as command file SWSC/OUTPUT save scaler configuration as command file WR save histogram data in disk file (binary) WR/ASCII save histogram data in text file Scatterplots SP define X/Y axis parameters of scatterplot and display SP/COPY copy scatterplot and give it a new name SP/CREATE allocate memory for scatterplot SP/DEFAULT set defaults for attributes of new scatterplots SP/DELETE deallocate memory reserved for scatterplot SP/LIST list information about scatterplots SP/MODIFY change defaults attributes of existing scatterplots SP/RESUME allow update of scatterplot when displayed SP/SUSPEND prevent update of scatterplot when displayed SP/ZAP zero scatterplot SP/ZOOM display different section of scatterplot Experimenter's Guide To Daphne Page 279 List of Daphne Commands 3 October 1990 Tape (and Disk) BSP backspace tape DISK define disk file to save (or replay) event data FND position tape by run number KLT kill tape process RDEV formatted dump of data from Daphne event tape REW rewind tape SCAMP record information from SCAMP control program (not implemented as of January '88) SKP position tape by skipping files SNAPDIR display information about runs on a SNAP tape TAPE define input or output tape TDIR display information about runs on a Daphne tape TEV enable or disable event mode recording Windows DW display window W1 define 1D window W2 define 2D window X1W delete 1D window X2W delete 2D window 54 Index