Previous: Glossary
Next: Calling sequences
Previous Page: ROOT data set
Next Page: Data set attributes

# Basic concepts

DSPACK data set is a two-dimensional object (very much like an array of structures). It is defined by the program - usually in initialization phase (although new objects may be defined at any time - for instance when reading a DSPACK tape) and this definition is used later when the data set is used. The data set definition specifies the number of items (corresponding to elements of a structure), the number of entries (the count of how many times the structure is repeated) is 'dynamic' - it may change every time data are stored in the data set. Access to the whole data set or individual entries as well as to individual words is possible through DSPACK calls. DSPACK items may have different length - they may even be arrays of structures themselves.

Data set is identified by data set name (up to 16 characters). However - for efficiency, all DSPACK calls accessing data do it using two arguments: data set name and data set handle (address of the data set pointer). The search for the data set based on the name is performed in the first call which then returns the correct value of the handle. As long as the user does not modify the handle all subsequent calls address the data directly, at most checking whether the handle and the name agree (although even this test may be disabled by the caller) - even if the actual address of the data set changes in the meantime - for instance in the new event. This method provides fast access to data where necessary but allows access by name if this is more convenient - for instance in interactive programs the user enters data set names and the full search is performed every time (all pointers and names are kept in one place which makes the search quite fast anyway).

Example

{\bf Fortran:}
save my_handle
data my_handle/0/

...
...
call dsget('MY_DATA_SET',my_handle....

{\bf c:}
static int my_handle=0;
...
...
dsget("MY_DATA_SET",&my_handle...

In both cases the name 'MY_DATA_SET' is only used on the first call. On all subsequent calls variable my_handle provides quick access to the data even if the data set has been removed and stored again, for instance in the next event. The programmer must have a separate variable to store the handle for each data set accessed and the values returned by DSPACK should never be modified.

Each item of a data set has a name (up to 16 characters). This is mainly used by tools (like histogram definitions, calculator, test package) and interactive programs but may also be used in calls accessing data. Additionally each item may have an additional 20 character description which is used by interactive programs as a comment. A multi-entry data set fills a contiguous region in memory . Therefore it is usually filled completely by one call or the memory is 'booked' and then filled entry-by-entry. Adding entries to a complete data set is expensive. However a mechanism is provided to fill a data set of unknown size and to declare the size afterwards - thus avoiding the need to know the number of entries in advance.

If used with ZEBRA memory manager DSPACK I/O uses ZEBRA FZ I/O routines. However it defines a convention of how the data should be written in order to make sure that all information needed by DSPACK is kept. The user makes a list of data sets to be written out after each event. All the definitions of all data sets tagged this way are written as a first block of DSPACK output. After each event all tagged data sets (and their dependants) are written out. (The same system is applied separately to constants stored by DSPACK ). When the DSPACK file is read by DSPACK I/O, the header with definitions is used to construct the definitions for all data sets in the file. This means that the reading program does not need to define any structures which it reads from the file or tape. Of course the FZ files may be read by any program using ZEBRA (like PAW) and used directly.

Previous: Glossary