Scripting NeXus Files
This section describes the scripting interface to NeXus
files, called nxscript. Scripting the generation of NeXus files has
the advantage that
it can be customised very quickly to special needs. Moreover it might
help to reduce the amount of instrument specific code required for an
instrument. This scripting interface uses the NeXus dictionary API for
the actual writing process. This has the following consequences:
- The interface needs two filenames: the
NeXus filename and the dictionary filename when opening files.
- Writing commands have the general form: alias object. This means
that object is written to the NeXus file using the specified alias.
- Another property is that some writing commands write several bits
of information in one go. In such cases the aliases for the additional
bits are derived from the base alias by appending specific
strings. Thus dictionary files need to have a special form for this
scripting interface to work.
- Nxscript also tries to figure out the dimensions of
multidimensional datasets such as histogram memories by itself. In
such cases the dimension attribute in the dictionary file must be
omitted.
- Nxscript assumes the following policy for data writing:
irrespective of errors write everything you can. Thus this interface
will complain bitterly and verbosely if something does not work, but
never return an error.
Usage
Before this facility can be used nxscript has to be installed into the
SICServer from the instrument configuration file. This is done through
the command:
- MakeNXScript ?name?
- This creates a NeXus scripting object. If the name is omitted, an
object named nxscript is created. If a name is given, this name is
used for the scripting object. Having scripting objects with different
names is also the only possibility to have more then one NeXus file
writing operation going at a given time.
In the following sections it is assumed that an object nxscript
had been configured into SICS.
File Opening and Closing
- nxscript create5 nexusFile dictFile
- Creates a new NeXus file based on HDF-5 with the name
nexusFile. The dictionary file dictFile is used.
- nxscript create4 nexusFile dictFile
- Creates a new NeXus file based on HDF-4 with the name
nexusFile. The dictionary file dictFile is used.
- nxscript reopen nexusFile dictFile
- Reopens an existing NeXus with the name
nexusFile for modification or appending.
The dictionary file dictFile is used.
- nxscript close
- Closes the current NeXus file. This command MUST be given at the
end of each script in order to make sure that all data is written
properly to disk.
Writing Things
- nxscript puttext alias bla bla bla ....
- Writes everything after alias as text data to the alias. The
definition string for the alias should not contain a dimension
description, this is automatically appended.
- nxscript putfloat alias value
- Writes a single floating point value to alias alias.
- nscript putmot aliasName motorName
- Writes the position of the motor motorName into the NeXus file as
described by aliasName. Theposition is a zero point corrected position. If
another alias aliasname_null exists in the dictionary, the zero
point of the motor is also written to file.
- nxscript putcounter aliasBase counterName
- Writes counter data to a NeXus file. Data is taken from the single
counter counterName. What is written depends on the aliases present in
the dictionary file:
- aliasBase_preset
- The preset value.
- aliasBase_mode
- The counter mode
- aliasBase_time
- The actual time counted, without breaks due to insufficient beam.
- aliasbase_00 ... aliasBase_09
- The monitor readings for monitors 0 to 9. Please note that 00
would denote the normal counting tube at a scanning type of
experiment.
- nxscript puthm hmAlias hmName ?start? ?length?
- Writes data from the histogram memory hmName to a NeXus file using
the alias hmAlias. The definition string for the alias should not
contain neither -rank nor -dim information as this will be appended by
nxscript. If the optional parameters start and end are given, a
subset of the data is written. It is the users responsability that the
values requested make sense to the histogram memory. In the case of
subset writing, the dimensions have to be specified in the definition
string belonging to the alias. Nxscript sets a variable timedim in the
dictionary though which contains the length of a time binning if
appropriate. This is a special help for writing extra detectors at
SANS and AMOR.
- nxscript puttimebinning aliasName hmName
- Writes the time binning at histogram memory hmName to file using
the alias aliasName. The length of the time binning data is
automatically appended to the definition string for the alias.
- nxscript putarray aliasName arrayName length
- Writes the Tcl array arrayName to file using the aliasName. The
definiton string belonging to aliasName does not need to contain a
-dim argument as this is set by this routine. The parameter length is
the length of the array. Only rank 1 arrays are supported.
- nxsript putglobal attName bla bla bla
- This writes an global attribute attName. Everything after attName
is concatenated to a string which then respresents the value of the
attribute.
- nxscript makelink targetAlias victimAlias
- This creates a symbolic link for victimAlias in the group
designated by targetAlias.