# 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.