How To Ask For Help

: For most issues, bug reports, etc. the best way to get help is to use the SDAQ ticketing system. To create a ticket, send an email to daqhe.nosp@m.lp@f.nosp@m.rib.m.nosp@m.su.e.nosp@m.du. For on-call support during an experiment, tell the control room that there is a DAQ issue and they will call the appropriate people.

Submitting a Good Help Ticket

: A good help ticket should provide context for the action being performed, messages or errors reported by the software being run, and any steps taken to troubleshoot the issue. If the problem is repeatable, the conditions which trigger the error should be spelled out as precisely as possible.

: As an example, lets consider a user "Bob" who is trying to convert an event file to ROOT format using the ddasdumper program. Bob has an event file called run-1234-00.evt which he knows was taken last week using NSCLDAQ 11.3-034. He wants to convert to ROOT format using the ddasdumper program from NSCLDAQ version 12.1-xiaapi4 but the program exits without generating any output:

<genesis:rawdata >. /usr/opt/daq/12.1-xiaapi4/daqsetup.bash
<genesis:rawdata >$DAQBIN/ddasdumper -s file:///scratch/chester/rawdata/run-1234-00.evt -f run-1234-00.root
ddasdumper main caught a C++ exception: Unable to dump a data format item... likely you've specified the wrong --nscldaq-format

: Bob immediately emails daqhe.nosp@m.lp@f.nosp@m.rib.m.nosp@m.su.e.nosp@m.du and says:

"ddasdumper doesn't work for run-1234-00.evt, please help."

: This is an example of a bad daqhelp email. There is a great deal of missing context here which is crucial to understanding the underlying cause of the aborted conversion! Alice, the SDAQ group member answering responding to the help ticket, doesn't know where to begin, and it will take some back and forth with Bob to figure out what has gone wrong and how to fix it.

: A better version of this email would look something like:

"I have a data file run-1234-00.evt which was recorded using NSCLDAQ version 11.3-034. I am trying to convert the file to ROOT format using the ddasdumper from NSCLDAQ version 12.1-xiaapi4. No output ROOT file is produced, and I see the following message:

$DAQBIN/ddasdumper -s file:///scratch/chester/rawdata/run-1234-00.evt -f run-1234-00.root ddasdumper main caught a C++ exception: Unable to dump a data format item... likely you've specified the wrong –nscldaq-format

: I do not understand what –nscldaq-format refers to or how I should set it. This issue is repeatable and occurs immediately after I attempt to dump the file."

: At this point it is easy to address the issue: there is a format mismatch between the run file's data format and the data format that the ddasdumper program expects. The response by Alice would point user Bob in the right direction:

<genesis:rawdata >$DAQBIN/ddasdumper -h
Usage: ddasdumper [OPTION]...
Write NSCLDAQ PHYSICS_EVENT data obtained using DDAS to a ROOT TTree and
perform a formatted dump of selected data items.

  -h, --help                 Print help and exit
  -V, --version              Print version and exit
  -s, --source=STRING        Data source URL. Note that only file and streaming
                               data sources
  -f, --fileout=STRING       Path of output file
  -c, --count=INT            Number of items to dump before exiting. If no count
                               value is provided, all items are dumped
  -k, --skip=INT             Number of items to skip before dumping
  -e, --exclude=STRING       List of item types to exclude from the dump
                               (default=`')
  -w, --scaler-width=INT     Scaler counter width in bits  (default=`32')
  -F, --nscldaq-format=ENUM  NSCLDAQ format version  (possible values="12",
                            "11", "10" default=`12')

Which shows two important things:

The --nscldaq-format option expects one of 10, 11, and 12, corresponding to the major version of the NSCLDAQ code used to take the data.
The default format expected by NSCLDAQ 12.1-xiaapi4 is for version 12 data.

: Specifying the correct format version allows the code to run as expected:

<genesis:rawdata >$DAQBIN/ddasdumper -s file:///scratch/chester/rawdata/run-1234-00.evt -f run-1234-00.root --nscldaq-format=11
Ring items formatted for: 11.0

Mon May 16 17:39:43 2022
 : Run State change : Begin Run at 0 seconds into the run
Body Header:
Timestamp:    18446744073709551615
SourceID:     0
Barrier Type: 1
Title     :
Run Number: 283

Glom is building events
Event building coincidence window is: 10000 timestamp ticks
TimestampPolicy : last

...

Conclusion

: We have seen in this section, using a fairly trivial example, how providing important contextual information can expedite the process of identifying and solving a user's issues.