# 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 control the scan more closely, i.e. do multiple counting operations at the same point etc. This is especially true when magnets are involved. In order to do this a facility has been provided which allows the user to specify a macro routine which is called at each point. This macro routine then performs all necessary operations and then is responsible for storing its data. In order to this commands have been defined which allow to append a line to the scan data file and to store measured data in the scan data structure. The last feature is necessary in order to make scan status displays and scan analysis, such as center detection, work. The following steps are required:

1. Write a suitable macro procedure for the actions required at each scan point. The procedure signature looks like this:

       proc myScanPoint {point} {
       }

   And will be called with the number of the current scan point as a parameter. Besides all usual Tcl and SICS commands the following special commands may be used:
   xxxscan line text
     Appends all the text after line to the scan data file.
   xxxscan storecounts c1 c2 c3 c4 ...
     Stores the first number given as count data, all the others as monitor values in the internal scan data structure.
2. Test the procedure.
3. Switch the internal scan command command into user scan mode with the command: xxxscan configure user
4. Assign your procedure to the internal scan command with the command: xxxscan command myScanPoint
5. Use normal scan commands for doing your scan.
6. Switch the internal scan command into normal mode with the command: xxxscan configure standard.

In all this replace xxxscan with the name of the internal scan command.