Using Daphne with the MSU/NSCL Acquisition System Page 1 1 Introduction Daphne has been modified to work with the MSU/NSCL acquisition system for both on-line and off-line (Replay) analysis. The MSU acquisition system was written by Ron Fox of the Michigan State University National Superconducting Cyclotron Laboratory (NSCL). 2 User-Function The structure of the Daphne user-function has not been changed, but the method of linking is different. There are additional entry points available for users who wish to perform special processing of the buffers generated by the MSU acquisition system. 2.1 Linking To link a user-function for use with an MSU data stream or data file: $ @dapexe:msuuserfunc.lnk my_program link_options Example: $ @dapexe:msuuserfunc.lnk oxyfis /debug/map Using Daphne with the MSU/NSCL Acquisition System Page 2 2.2 MSU Entry Points The Daphne sort program allows the user to supply routines to handle each of the following MSU buffer types: - Subroutine MSU_SCALER (MSUheader) This routine will be called for both SCALER and SCALER_PEEK records. SCALER_PEEK buffers are not recorded on tape by the standard MSU recording routines, so they are never seen during Replay. SCALER is buffer type 2 SCALER_PEEK is buffer type 3 - Subroutine MSU_START (MSUheader) Buffer type 11 is generated at the start of a run - Subroutine MSU_STOP (MSUheader) Buffer type 12 is generated at the end of a run - Subroutine MSU_PAUSE (MSUheader) Buffer type 13 is generated when an MSU PAUSE command is issued - Subroutine MSU_RESUME (MSUheader) Buffer type 14 is generated when an MSU RESUME command is issued - Subroutine MSU_LINKLOST (MSUheader) Buffer type 15 is generated when the computer loses its link to the front-end acquisition system. There is NO routine MSU_DATA (buffer type 1) at this time. All these routines are optional. If any of them is not supplied by the user then the Daphne subroutine library dapexe:DapUserFuncLib.olb will supply a stub routine. Using Daphne with the MSU/NSCL Acquisition System Page 3 3 Structure of an MSU Buffer The MSUheader consists of sixteen 16 bit words: - *Word 1: The size of the record (in bytes) The byte count includes the header itself - *Word 2: The buffer type - Word 3: Checksum of header - *Word 4: Run Number - Words 5 and 6: Buffer sequence number within a run Event data buffers are numbered independently of control data buffers - Word 7: Event count - Word 8: Number of LAM registers - Word 9: Number of generating CPU - Word 10: Number of bit registers - Word 11: Buffer structure version (Currently value is 1) - Words 12 to 16 not used An asterisk ("*") indicates a field which Daphne uses. The interpretation of information following the sixteen word header depends on the buffer type. For information on the format of each type of buffer consult the MSU documentation. The offsets are defined in the include file "daq_include:fedef.inc". Daphne keeps a copy of this file for compiling Daphne on machines without a full MSU system in "dapexe:msu_fedef.inc" Using Daphne with the MSU/NSCL Acquisition System Page 4 4 Input from Disk or Tape The MSU system records data in a format which is compatible with the VAX/VMS file system. As a result, it is possible to use a routine designed for disk data files to read files whether they be on tape or disk. When you use the /MSU qualifier Daphne will use the default MSU extension of ".EVT" rather than the default Daphne extension of ".EV". For data files on disk: $ disk/in/msu run000005 $ rdd $ disk/in/msu run000006 $ rdd and so on For data files on tape: $ mount mka0: /override=identification $ disk/in mka0:run000005 $ rdd $ disk/in mka0:run000006 $ rdd and so on Please note the use of $RDD ("Read Data from Disk") rather than $RDT ("Read Data from Tape"). This is because the tape is written in a file structured format which allows VMS to emulate some disk operations. You can use the standard VMS commands and programs to position the tape before starting replay. There are two qualifiers to the $DISK command: - RewindOnClose - NoRewindOnClose This is useful for data files on tape. At then end of the sort the program will rewind the tape to the start of the data file (not the start of the tape). This is simpler than trying to reposition the tape to replay the same run. - PassNonSortableData - NoPassNonSortableData The sortable event data an MSU data file may be mixed with scaler information, run start, run pause, run resume, and run end. These later kinds are "non-sortable". Specifying /NOpassNonSortableData causes these records to be dropped by the tape reading process. Using Daphne with the MSU/NSCL Acquisition System Page 5 If you fail to specify these qualifiers the program will ask you: If you intend to make several consecutive passes over a data file on tape answer "Y" to the following question Rewind to beginning of file at end-of-run [Y/N] Should SCALER records be passed to the sorting routine ? [Y/N] Another technique for dealing with these questions: you can redirect the questions/answers from the program reading the tape by reassigning logical names: $ define/job for005 answers.dat $ disk/in/msu mka0:run000005 $ deassign/job for005 $ rdd 5 No Output in MSU Format Daphne can create subsets of events and save them in a data file. However, the data files will be in Daphne format, not MSU format. See the Daphne "Guide to Replay" on how to select a subset of events for a new data file. 6 Starting Sorting with MSU Acquisition There is a special version of the Daphne VAXSORT program for use with the on-line MSU acquisition system. It is invoked by: $ ACQ/MSU Since it is easy to forget the use of the /MSU qualifier one may want to create a symbol to start acquisition. For example use the following command to redefine the symbol "ACQ": $ ACQ:==ACQ/MSU The acquisition program includes the equivalent of the MSU "CONNECT/CONSUMER" command. Once started the sorting program will look for an MSU stream with the name "DAPHNE" by default. This can be over-ridden using the Daphne $STREAM command (described below). Because of the changes necessary to start the sorting process when running with the MSU system, a user may not receive the same error messages one would were Daphne running without the MSU system. For instance there are special error messages for problems related to starting shareable images. These will not appear when running in on-line mode with the MSU system. Using Daphne with the MSU/NSCL Acquisition System Page 6 The method of linking an MSU user-function is identical whether used for Replay or Acquisition: $ @dapexe:msuuserfunc.lnk my_user_function link_options To use the VAX/VMS symbolic debugger with this MSU specific version of VAXSORT, start acquisition with the following command: $ ACQ/MSU/DEBUG For information on using the VAX/VMS symbolic debugger with a Daphne user-function see the Daphne "Guide to Replay". Using Daphne with the MSU/NSCL Acquisition System Page 7 7 Daphne Command for MSU Users 7.1 The Daphne $STREAM Command With the $ACQ/MSU command the Daphne sort process normally reads data from the MSU stream "DAPHNE". The $STREAM command allows the user to change the name of the stream used by Daphne. This is most useful when there are multiple Daphne consumers used with a single MSU based experiment. $ STREAM BACKGROUND_CHECKS or $ STREAM MSU stream name: BACKGROUND_CHECKS The MSU stream name is limited to 32 characters. 7.2 The Daphne $FORWARD Command The $FORWARD command allows an MSU job to forward an MSU data stream to another job where it can be analyzed by a second user or another Daphne sort process such as $ACQ/MSU. $ FORWARD sourceStream [destStream] If the destStream is omitted it defaults to the same name as the sourceStream. The sourceStream and destStream must be no more than 11 characters long. At the moment there are two programs that are written to be used with the $FORWARD command: $MSURUN and $ACQ/MSU. The $FORWARD command was originally written because the MSU router requires all routers to be in the same job tree, whereas Daphne's design does NOT allow two Daphne sessions in the same job tree. In the past it was not possible to have two Daphne sessions working with a single MSU router. Some advantages of $FORWARD: - Several users can have totally independent analysis of the same data stream using a single machine (possibly with several X terminals). - If the router fails or the front-end needs to be restarted the sort process is NOT automatically terminated as is the case with a normal consumer process. Using Daphne with the MSU/NSCL Acquisition System Page 8 - A user can test a change to a user-function or Daphne setup while acquisition is in progress, and then install the change between runs without extra delays for testing the change. Suggested by Elliot Kanter. - A remote user (someone at home or another institution) with an X terminal or Tektronix emulation can look at the data stream using Daphne without sending data packets over the internet. A job tree includes that "master" process and all processes which are sub-processes of the original master process, and their descendents. To find out the structure of a job tree use the DCL command: $SHOW PROC/ACC/ALL. If you are using VMS Motif X windows then you should know that $CREATE/TERMINAL creates a sub-process of the process to which you issued the command, whereas using the session manager to create a DECterm application window creates a new, independent, master process. The $FORWARD command requires GRPNAM privilege or that the program dapexe:forward.exe be installed with GRPNAM privilege by the system manager. If the program lacks sufficient privilege you will receive an appropriate message. The $FORWARD program creates group level mailboxes "SND_destStream" and "ACK_destStream" through which to pass messages. It then starts a sub-process to peform the actual passing of messages and data. In the destination job tree the user can pass the destStream name to the dap_open_stream routine in order to get similar to that of a true MSU consumer. The process which performs the forwarding operation has the process name "FWD_sourceStream". If the MSU Router should crash the FWD_sourceStream process is automatically terminated by VMS. Once the user has restarted the router and reissued the $MAKE, $SEND, and $FORWARD commands the destination process should begin receiving data again. The FORWARD subprocess does not depend on Daphne being active, however the command itself is defined in the Daphne command tables, so, at the minimum, the following command must be executed to read the Daphne command tables: $ set command dapexe:dpcmmds A user who wishes to write programs that work with $FORWARD must use the Daphne "envelopes" for the MSU routines:: open_stream -> dap_open_stream get_buf -> dap_get_buf map_to_buffer -> dap_map_to_buffer release_buf -> dap_release_buf close_stream -> dap_close_stream Using Daphne with the MSU/NSCL Acquisition System Page 9 The sequence of commands necessary to use the $FORWARD command resembles the following: In the ROUTER job tree: $ make daphne2 $ send/sample 1,11,12 ! data & start/stop run $ forward daphne2 <--------------------+ | | These In a separate job tree of the same VMS group: | names | must $ dap/noban d2 | match $ stream daphne2 <---------------------+ $ acq/msu 7.3 The Daphne $MSURUN command A program is distributed with Daphne which updates the Daphne run number from the MSU run number. The program runs as a standard MSU consumer process: $ make msurun $ ! $ ! Select start/stop buffers $ ! $ send/nosample 11,12 msurun $ MSURUN Using Daphne with the MSU/NSCL Acquisition System Page 10 8 Writing Your Own block-handler Routine A "block-handler" routine is a subroutine which is linked with the Daphne user-function and which is called once for each block of data before the data in that block is sorted. A user can perform operations which depend on the factors other than the event data. When processing data from non-Daphne sources, such as the MSU acquisition system, it allows one to look at the MSU specific parts of the block without having to incorporate MSU specific code into the standard user-function. Daphne provides only two trivial block-handlers. The default "NULL" block-handler is daptab:nullblockhandler.for and is part of dapexe:DapUserFuncLib.olb object library. It is linked automatically with a user-function when one uses the dapexe:dapuserfunc.lnk link command procedure (unless the user explicitly supplies one when the user-function is linked). The MSU block-handler is dapexe:msublockhandler.obj and is linked with your user-function automatically when one uses the dapexe:msuuserfunc.lnk link command procedure. The source code for both block-handlers is in daptab:*blockhandler*.for. A block-handler has three entry points: Using Daphne with the MSU/NSCL Acquisition System Page 11 c++ c subroutine blockHandlerInit (name) c c This routine is called before sorting begins so that c Daphne can verify that the blockHandler is compatible with c the tape or disk input routine and to allow the user to c perform any necessary initialization c c name - ouput/character*4 c identifies tape handler so VAXSORT can verify c that this routine matches the input tape/disk c routine c code must match value supplied by input tape/disk c routine or be space in order to indicate DAPHNE c-- c++ c logical*4 function blockHandler (blockNumber,buffer,dataArray) c c This routine is provided by the installation or user to provide tape c format specific processing in the sort program. For instance when c processing MSU format data it allows user supplied routines to be c called for processing scaler data. c c function value - output/logical*4 c .true. => block should be sorted c .false. => block should NOT be sorted c c blockNumber - input/integer*4 c for passing to isGoodBlock routine c c buffer - input/integer*2(*) c array pointing to buffer passed by input c tape/disk routine c includes any header provided by input c tape/disk routine c c dataArray - input/integer*2(*) c array pointing to data to be sorted c-- c++ c subroutine blockHandlerExit (VMSstatus) c c This routine is called automatically at the end of sorting c c VMSstatus - input/integer*4 c standard VMS status code c odd value => normal exit c even value => non-normal exit c-- Using Daphne with the MSU/NSCL Acquisition System Page 12 9 Relinking When MSU DAQ_LIB:DAQOBJLIB Routines Change NOTE For maintainers of the MSU acquisition system The Daphne program DAPTAB:MSUVAXSORT.EXE which receives data from the MSU acquisition system depends on the following routines which are located in DAQ_LIB:DAQOBJLIB.OLB - OPEN_STREAM - GET_BUF - MAP_TO_BUFFER - RELEASE_BUF To relink and reinstall MSUVAXSORT.EXE use the following procedure: $ SET DEFAULT dapdir: $ @LOGIN $ SET DEFAULT DAPTAB: $ @MSUVAXSORT.LNK "/NODEBUG/NOTRACE" $ @MSUVAXSORT.LNK "/DEBUG/EXE=MSUVAXSORTDEBUG.EXE" $ COPY MSUVAXSORT*.EXE dapdir:*.*;0 $ SET DEFAULT dapdir: $ COPY MSUVAXSORT*.EXE [DAPHNE.EXE]*.*;0 There are two version of MSUVAXSORT, one with debug symbols and one without. The version which is activated depends on whether the user selects the /DEBUG qualifier when sorting is started.