10d29d597c
This is our new RELEASE-4_0 branch which was taken from ansto/93d9a7c Conflicts: .gitignore SICSmain.c asynnet.c confvirtualmot.c counter.c devexec.c drive.c event.h exebuf.c exeman.c histmem.c interface.h motor.c motorlist.c motorsec.c multicounter.c napi.c napi.h napi4.c network.c nwatch.c nxscript.c nxxml.c nxxml.h ofac.c reflist.c scan.c sicshipadaba.c sicsobj.c site_ansto/docs/Copyright.txt site_ansto/instrument/lyrebird/config/tasmad/sicscommon/nxsupport.tcl site_ansto/instrument/lyrebird/config/tasmad/taspub_sics/tasscript.tcl statusfile.c tasdrive.c tasub.c tasub.h tasublib.c tasublib.h
258 lines
12 KiB
HTML
258 lines
12 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>Scripting NeXus Files</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<H1>Scripting NeXus Files</H1>
|
|
<P>
|
|
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:
|
|
<ul>
|
|
<li>The interface needs two filenames: the
|
|
NeXus filename and the dictionary filename when opening files.
|
|
<li>Writing commands have the general form: alias object. This means
|
|
that object is written to the NeXus file using the specified alias.
|
|
<li>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.
|
|
<li>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.
|
|
<li>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.
|
|
</ul>
|
|
</P>
|
|
<h2>Usage</h2>
|
|
<p>
|
|
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:
|
|
<dl>
|
|
<dt>MakeNXScript ?name?
|
|
<dd>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.
|
|
</dl>
|
|
In the following sections it is assumed that an object <b>nxscript</b>
|
|
had been configured into SICS.
|
|
</p>
|
|
<h3>File Opening and Closing</h3>
|
|
<p>
|
|
<dl>
|
|
<dt>nxscript create5 nexusFile dictFile
|
|
<dd>Creates a new NeXus file based on HDF-5 with the name
|
|
nexusFile. The dictionary file dictFile is used.
|
|
<dt>nxscript create4 nexusFile dictFile
|
|
<dd>Creates a new NeXus file based on HDF-4 with the name
|
|
nexusFile. The dictionary file dictFile is used.
|
|
<dt>nxscript createxml nexusFile dictFile
|
|
<dd>Creates a new NeXus file based on XML with the name
|
|
nexusFile. The dictionary file dictFile is used.
|
|
<dt>nxscript reopen nexusFile dictFile
|
|
<dd>Reopens an existing NeXus with the name
|
|
nexusFile for modification or appending.
|
|
The dictionary file dictFile is used.
|
|
<dt>nxscript close
|
|
<dd>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.
|
|
</dl>
|
|
</p>
|
|
<h3>Writing Things</h3>
|
|
<p>
|
|
<dl>
|
|
<dt>nxscript puttext alias bla bla bla ....
|
|
<dd>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.
|
|
<dt>nxscript putfloat alias value
|
|
<dd>Writes a single floating point value to alias alias.
|
|
<dt>nxscript putint alias value
|
|
<dd>Writes a single integer value to alias alias.
|
|
<dt>nxscript updatedictvar alias value
|
|
<dd>Updates the dictionary value alis to value.
|
|
<dt>nscript putmot aliasName motorName
|
|
<dd>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.
|
|
<dt>nxscript putcounter aliasBase counterName
|
|
<dd>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:
|
|
<dl>
|
|
<dt>aliasBase_preset
|
|
<dd>The preset value.
|
|
<dt>aliasBase_mode
|
|
<dd>The counter mode
|
|
<dt>aliasBase_time
|
|
<dd>The actual time counted, without breaks due to insufficient beam.
|
|
<dt>aliasbase_00 ... aliasBase_09
|
|
<dd>The monitor readings for monitors 0 to 9. Please note that 00
|
|
would denote the normal counting tube at a scanning type of
|
|
experiment.
|
|
</dl>
|
|
<dt>nxscript puthdb path ?alias
|
|
<dd>Put a hipadaba path. The alias to put the data too is found in one of two places: as the nxalias
|
|
property on the node or as given on the command line. The alias is expected to match the size and type of
|
|
the data. Please note that hipadaba stores all floats as double which is NX_FLOAT64 as number type.
|
|
<dt>nxscript puthdboff path offset ?alias</dt>
|
|
<dd>Put a hipadaba path. The alias to put the data too is found in one of two places: as the nxalias
|
|
property on the node or as given on the command line. The alias is expected to match the size and type of
|
|
the data. Please note that hipadaba stores all floats as double which is NX_FLOAT64 as number type. Writing
|
|
data is started with the offset specified from the start of the data. This is useful to split a histogram
|
|
memory area into separate detectors or whatever. The length of the amount of data to
|
|
copy is implied by the dimension of the SDS alias points to.
|
|
<dt>nxscript puthdbslab path start size
|
|
<dd>Put a hipdaba node as a slab. The node must have a property nxalias to determine where to write to.
|
|
Start and size are Tcl lists which give the start point where to write and the size of the data
|
|
to write. See nxscript putslab for more information.
|
|
<dt>nxscript puthm hmAlias hmName ?start? ?length? ?bank?
|
|
<dd>Writes data from the histogram memory hmName to a NeXus file using
|
|
the alias hmAlias. Nxscript automatically updates the dim0, dim1, ..., timedim
|
|
dictionary variables. Thus these can be used to define the dimensions in the
|
|
dictionary file.
|
|
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 feauture for writing extra detectors at
|
|
SANS and AMOR. Optionally, together with start and length, a bank number can
|
|
be given. This is a feauture to support the rare case of having multiple banks
|
|
in one histogram memory. If not give bank defaults to 0.
|
|
<dt>nxscript puttimebinning aliasName hmName
|
|
<dd>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.
|
|
<dt>nxscript putarray aliasName arrayName length
|
|
<dd>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. The array is
|
|
considered a float array.
|
|
<dt>nxscript putintarray aliasName arrayName length
|
|
<dd>The same as above, but the data is considered integer.
|
|
<dt>nxsript putglobal attName bla bla bla
|
|
<dd>This writes an global attribute attName. Everything after attName
|
|
is concatenated to a string which then respresents the value of the
|
|
attribute.
|
|
<dt>nxscript putsicsdata alias dataname
|
|
<dd>Writes the sicsdata array dataname to alias.
|
|
<dt>nxscript putattribute alias name value
|
|
<dd>Add another text attribute to alias. The name of the attribute is name, the
|
|
value value.
|
|
<dt>nxscript makelink targetAlias victimAlias
|
|
<dd>This creates a symbolic link for victimAlias in the group
|
|
designated by targetAlias.
|
|
<dt>nxscript putslab alias startlist sizelist obj
|
|
<dd>Writes a slab of data. alias is the alis to write too. startslist is
|
|
a Tcl list containing the start indexes, sizelist is the size of the slab
|
|
to write as a Tcl list and obj is the SICS object to write. Obj can be a
|
|
histogram memory; then the histogram memory data is written. Or it can be
|
|
a sicsdata object, the value of which will then be written.
|
|
<dt>nxscript putslab16 alias startlist sizelist obj
|
|
<dd>Writes a slab of data as above. Parameters are as setailed above.
|
|
The difference is that this converts the data to a6 bit int before writing.
|
|
And SICSData objects are not supported.
|
|
</dl>
|
|
<dt>nxscript puts alias sgetstring [dim,dim]
|
|
<dd>
|
|
Writes any SICS data which can be fetched with sget. The input to sget is the
|
|
sgetstring. If sgetstring contains spaces, it must be quoted. The code tries to guess types
|
|
and dimensions automatically, thus alias must point to a definition string without -type,
|
|
-dim and -rank. The dimensions can be overriden with the optional dim argument which is a
|
|
komma separated list of dimensions.
|
|
</dl>
|
|
<dt>nxscript sappend alias sgetstring point [dim,dim]
|
|
<dd>
|
|
Appends any SICS data which can be fetched with sget to alias. The input to sget is the
|
|
sgetstring. If sgetstring contains spaces, it must be quoted. The code tries to guess types
|
|
and dimensions automatically, thus alias must point to a definition string without -type,
|
|
-dim and -rank. It is assumed that the first dimension is NX_UNLIMITED. The dimensions can be
|
|
overriden with the optional dim argument which is a komma separated list of dimensions. This override
|
|
only allows to specify the correct dimensions of the detector, NX_UNLIMITED is prepended
|
|
automatically. Point is the count in the dataset where to append to. Usually this is the
|
|
scan point number.
|
|
</dl>
|
|
</p>
|
|
<H1>Automatic Updating of NeXus Files</H1>
|
|
<P>
|
|
Some instruments perform measurements for quite long counting
|
|
times. In such cases it is advisable to save the data measured so far
|
|
to file in order to protect against hardware or software failures. To
|
|
this purpose an automatic file upgrade manager is provided. On
|
|
installation the automatic update object is connected wth a counting
|
|
device through the the callback interface. This makes sure that the
|
|
update manager is automatically notified when counting starts or
|
|
finishes.
|
|
</P>
|
|
<h2>Prerequisites for Using the Automatic Update Manager</h2>
|
|
<p>
|
|
In order to use automatic updating, three programs must be
|
|
provided. Each of these programs can be a script which uses the
|
|
nxscript facility. It can also be a SICS command.
|
|
<dl>
|
|
<dt>startScript
|
|
<dd>This program is supposed to write the static part of the file. It
|
|
is called once when the file is created.
|
|
<dt>updateScript
|
|
<dd>This program is supposed to create and update the variable data
|
|
elements in the NeXus file. This is called frequently.
|
|
<dt>linkScript
|
|
<dd>This program is supposed to create the links within the NeXus
|
|
file. This is called once after startscript and updateScript have been
|
|
run.
|
|
</dl>
|
|
</p>
|
|
<h2>Installing Automatic Update</h2>
|
|
<p>
|
|
An automatic update object is installed into SICS with:
|
|
<pre>
|
|
updatefactory name countername
|
|
</pre>
|
|
name is a placeholder for the name under which SICS knows the
|
|
automatic update object. name is available as a SICS command later on.
|
|
countername is a placeholder for a counter
|
|
object (counter or HM) which triggers automatic updating of NeXus
|
|
files. This object has to support both the countable and callback
|
|
interfaces of SICS. Suitable SICS objects include counter and
|
|
histogram memory objects.
|
|
</p>
|
|
<h2>Configuring Automatic Update</h2>
|
|
<p>
|
|
The SICS command created with updatefactory (see above) supports a few
|
|
parameters which allow for the configuration of the whole
|
|
process. Parameters follow the normal SICS syntax. Futhermore there is
|
|
a subcommand list, which lists all configuration
|
|
parameters. Supported parameters are:
|
|
<dl>
|
|
<dt>startScript
|
|
<dd>The program supposed to write the static part of the file.
|
|
<dt>updateScript
|
|
<dd>The program supposed to create and update the variable data
|
|
elements in the NeXus file.
|
|
<dt>linkScript
|
|
<dd>This program supposed to create the links within the NeXus
|
|
file.
|
|
<dt>updateintervall
|
|
<dd>The time intervall in seconds between updates. The defualt is
|
|
1200, eg. 20 minutes.
|
|
</dl>
|
|
</p>
|
|
</BODY>
|
|
</HTML>
|