There are some cases where the librarires provided to create ring items are not well suited for the job. Specifically, sometimes you'd like to create ring items to be emitted on stdout.
A simple set of functions that can be called by either C or C++ programs allows you to format ring items that can be dealt with however you might wish.
The functions provided are prototyped in DataFormat.h. The functions are also part of libdataformat.so.
The reference section provides full documentation. All functions
return a pointer to storage allocated with malloc(3)
that contains the ring item. It is the caller's responsibility
to invoke free(3) to release this storage.
The functions defined in DataFormat.h are implemented
in C and the header is written to be usable from both C and C++
programs. The functions are divided into two sets of functions.
The first set are intended to be used for compatiblity with
pre nscldaq 11.0 applications. With the exception of
formatNonIncrTSScalerItem, which was introduced
in NSLCDAQ-10.1-100 to support S800 scaler items that provide event
timestamps, the functions below provide a body header of length
zero (no body header).
formatEventItemFormats the data read from a physics trigger into a ring item.
formatTriggerCountItemFormats a trigger count item.
formatScalerItemCreates an incremental scaler ring item.
formatTextItemFormats a text string item. Text string items are items whose payload contains, among other things, a set of null terminated strings.
formatStateChangeCreates a state change ring item. State change ring items indicate that the run state has changed.
formatNonIncrTSScalerItemThis is a convenience function that produces a scaler item that has an event timestamp and has the incremental flag cleared.
The functions that are new since NSCLDAQ-11.0 and, produce fully filled out body headers are listed below:
formatDataFormatCreates a data format item for the format described in the version of libdataformat.so your application is linked to. Each ring producer should emit one of these as the first item it produces after attaching to the ring so that consumers know what data format to expect.
formatGlomParametersProduces a glom parameters ring itme. This is normally only called by the glom stage of the event builder pipeline. If, however you have replaced that stage of the pipeline with something different, you might want to emit this or some user specific item to describe the conditions being used to glue event fragments together into events.
formatEVBFragmentNormally this is only emitted to event builder monitor rings by teering. Formats an event builder fragment when you have a good idea the fragment contains a ring item.
formatEVBFragmentUnknown
Same as formatEVBFragment but
used when there's a pretty good idea the fragment payload
is not a ring item.
formatTimestampedEventItemCreates an evet ring item that has a timestamp (full body header).
formatTimestampedTriggerCountItemFormas a physics event count item with a full body header. In addition, the ring items allows you to provide an offsetdivisor for the run offset which supports run times with sub-second resolution. The concept of the run time divisor which (as of NSCLDAQ-11.0) is present in all ring item types that have run time offsets is that if you take the run time offset, and divide it by the run time divisor (floating point arithmetic), you get the offset into the run in seconds.
formatTimestampedScalerItemFormats a periodic scaler item that has a full body header. Again, this version allows you to set the run time offset divisor to something other than 1.
formatTimestampedTextItemFormats a text array item that has a full body header. The full body headder no only allows the emitter to specify a timestamp at which the item was created, but also to specify which data source created the item. If the text item should not have a timestamp, you should either fill in the most recent timestamp emitted by that source or, if that's not convenient, the value NULL_TIMESTAMP which is defined in the header fragment.h.
formatTimestampedStateChangeFormats a state change item that has a full body header and, possible, value for the run time divisor other than 1.
bodyPointerGiven a pointer to a ring item that comes from NSCLDAQ-11.0 or later, returns a pointer to the body payload of the item. The body payload is the section of the ring item that is just after the Body Header or, if the body header is not emitted, after the zero longwords.