# The Internal Scan Command

Scans are preformed from a variety of commands in SICS. All these commands are just Tcl--wrappers around an internal scan object implemented in C. This section describes this internal scan command and how it works. This internal scan command is installed into the SICS server via the MakeScanCommand command in the initialisation file. This command install the internal scan object under a user defined name. For the rest of this document it is assumed that this name is xxscan.

The scan object (named here xxscan, but may have another name) understands the following commands:

xxscan add name start step
  This command adds the variable specified by the argument name to the list of variables scanned in the next scan. The arguments start and step define the starting point and the sptep width for the scan on this variable.
xxscan clear
  clears the list of scan variables. Must be called before each scan with different parameters.
xxscan run NP mode preset
  Executes a scan. The arguments are: NP the number of scan points, mode the counter mode to use (this can be either timer or monitor) and preset which is the preset value for the counter. Scan data is written to an output file.
xxscan silent NP mode preset
  Executes a scan. The arguments are: NP the number of scan points, mode the counter mode to use (this can be either timer or monitor) and preset which is the preset value for the counter. The difference to run is, that this scan does not produce an output file.
xxscan recover
  Recovers an aborted scan. The scan object writes a file with all data necessary to continue the scan after each scan point. If for some reason a scan has been aborted due to user intervention or a system failure, this scheme allows to continue the scan when everything is alright again. This works only if the scan has been started with run, not with silent.
xxscan getfile
  This command retuns the name of the current data file.
xxscan setchannel n
  Sometimes it is required to scan not the counter but a monitor. This command sets the channel to collect data from. The argument n is an integer ID for the channel to use.
xxscan getcounts
  Retrieves the counst collected during the scan.
xxscan getvardata n
  This command retrieves the values of a scan variable during the scan (the x axis). The argument n is the ID of the scan variable to retrieve data for. ID is 0 for the first scan variable added, 1 for the second etc.
xxscan interest
  A SICS client can be automatically notified about scan progress. This is switched on with this command. Three types of messages are sent: A string NewScan on start of the scan, a string ScanEnd after the scan has finished and a string scan.Counts = {109292 8377 ...} with the scan values after each finished scan point.
xxscan uninterest
  Uninterest switches automatic notification about scan progress off.
xxscan integrate
  Calculates the integrated intensity of the peak and the variance of teh intensity for the last scan. Returns either an error, when insufficient scan data is available or a pair of numbers. Peak integration is performed along the method described by Grant and Gabe in J. Appl. Cryst. (1978), 11, 114-120.
xxscan window [newval]
  Peak Integration uses a window in order to determine if it is still in the peak or in background. This command allows to request the size of this window (without argument) or set it (with argument giving the new window size).
xxscan simscan pos FWHM height
  This is a debugging command. It simulates scan data with a hundred points between an x axis ranging from 10 to 20. A gauss peak is produced from the arguments given: pos denotes the position of the peak maximum, FWHM is the full width at half maximum for the peak and height is its height.
xxscan command tclcommand
  Sets the tcl command procedure to invoke at each scan point. See below for the description of user defined scans. Invoked without argument command returns the name of the current command procedure.
xxscan configure mode
  Confugures the several possible scan modes for the scan object. Currently there are two:
  - standard, the default mode writing ASCII files.
  - amor, a special mode the reflectometer AMOR which writes NeXus files.

## User Defined Scans

In some cases users wish to exert more influence about the scan. Especially about what gets counted. In order to cater for this a hook was implemented in the internal scan command. This hook allows to run a tcl procedure at each scan point. This Tcl procedure is required to return a string containing up to 11 values for counters and monitors. The first value will be the one used as counts in the data file. The others will be placed as monitors. Please note, that only the first three monitors are written to file as of current. In order to use this facility the following steps are required:

1. Write The Tcl-macro procedure to run. Make sure that is creates proper output.
2. Test the Tcl-procedure in SICS.
3. Install the Tcl-procedure into the scan object with the xxscan command name syntax.
4. Make the scan command use the Tcl procedure by setting channel to -10 with the xxscan setchannel -10 command.

A hint: If you need to control the counting operation as well (because you are not using a counter to count) just run the scan object with a very low preset and do the counting yourself in your procedure.