Script Files

XSPEC/tcl script files can be executed in three different ways, as follows:

%xspec - <script>			!		executing script on initialization
XSPEC>@<script>			!		executing script from within the program
XSPEC>source <tclscript>			!		use tcl's source command from within the program

Each of these usages does something slightly different. In the first form, XSPEC will execute a file called <script>. One may execute a series of script files at startup with the following command syntax:

unix> xspec - file1 file2 file3 ...

Note that the space following the - is required.

The second form is @<name>, where <name> is the name of the script file to be executed. Here the default extension of .xcm is assumed. Scripts containing valid tcl or XSPEC commands will be executed using this form, and (unless the script ends in "quit" or "exit") will return to the interactive prompt after completion.

The final form, using tcl's source command, is intended for the special case where the script contains the implementation of a new command written in tcl/tk. It will not work for general scripts containing XSPEC/tcl commands, for example those produced by XSPEC's save command. These should rather be executed using the @ form.

Note that only in the second case @ is there a default filename suffix: for both the other methods of script execution the filename must be given in full.

As mentioned above, command abbreviations can be used in scripts executed using the @ syntax, to allow backward compatibility with scripts written for XSPEC 10, but not otherwise. Therefore, it is recommended that users choose avoid the use of command abbreviations in all scripts to avoid suprise failures when, for example, entering a script name from the command line.

Command Echoing

By default, when XSPEC is executing a script file, it echoes each command to the terminal before it is executed. This can be controlled using the tcl variable xs_echo_script, whose default value is 1. If this variable is set to 0, the commands from the script file will not be echoed to the terminal.

Converting scripts from XSPEC V.9 and Earlier

Given the differences in command syntax between the current version of XSPEC and that of versions 9.02 and earlier, a perl script file has been produced to aid in converting script files from XSPEC version 9.02 and eariler into a format that will run under the current version of XSPEC. This script is called xs_update.pl, and can be found in the directory $XANADU/spectral/xspec/src/tools. See the Script_conversion help topic in the XSPEC help facility for details on using this script.

Usage Advice

We suggest the following convention:

1.

Running an xspec script from the unix command prompt is intended to be used for background processing or overnight batch jobs. Using the unix 'at' command, one can arrange to receive the log file by e-mail.

2.

The @ usage is intended for processing previously run xspec command sequences, such as are produced by the save command.

3.

The source usage, as well as executing the commands in the script, performs the equivalent of pre-compiling the script for later invocation. Its most appropriate use is in preparing new custom XSPEC command procedures. Once the script is working correctly, it can be placed in the $XSPEC_HOME directory and become part of the user's standard command set. For examples, see the implementation of the addline and modid commands, which is through scripts to be found in the directory src/xanadu/spectral/xspec/manager. These also show how to make commands self-documenting.

Writing Custom XSPEC commands

XSPEC commands can be written by users as tcl procedures, which have similarities with fortran subroutines. Within XSPEC, tcl procedures can take arguments and execute XSPEC and tcl commands. The syntax for specifying arguments to a tcl procedure is as follows:

proc my_proc {arg1 arg2}{

...

data 1:1 ${arg1}_s0_20
data 2:2 ${arg2}_s1_20
...

}

Here, arg1, arg2 are values supplied by the user (here, part of a filename) from the command line, and substituted wherever ${arg1}, ${arg2} appear within the script. One may also give an argument a default value, so that the command so created may be invoked even without needing to specify the argument:

proc my_proc {arg1    {arg2 file2} }  {
...

}

Note that the parentheses enclosing both arg2 and file2 in this expression distinguish this from the case where 3 arguments are required for my_proc. Once this file is created, it needs to be source'd once, which compiles the script into an internal bytecode representation (this is similar to the way Java operates). Alternatively, one may place it in the $XSPEC_HOME directory before starting XSPEC, in which case it will be found automatically and compiled the first time it is invoked. The my_proc procedure is then defined such that one may type:

XSPEC>my_proc eso103 eso104

And then the data statement in the above example will be executed as if the following had been entered:

data 1:1 eso103_s0_20
data 2:2 eso104_s1_20

The tcl info command can be used to show which procedures have been defined:

XSPEC>info commands <procedure name>

This will return <procedure name> if that procedure has been compiled already or is a built-in command, or nothing if it has not (yet) been invoked or defined.

Scripting commands that prompt the user

The commands model, editmod, addmod, newpar, and fakeit may prompt the user for more information when used interactively. In order to write scripts that use these commands, one must know how to force XSPEC to enter the information that would be prompted for. The technique is exemplified as follows. Suppose we defined a procedure xmodel that makes a model with certain predefined parameter values:

          
 
set p1  {1.5 0.001 0 0 1.E05 1.E06}
set p2  {1 0.001 0 0 1.E05 1.E06}


 proc xmodel {modelString param1  param2  args} {
  
   ...
                            
  model $modelString & $param1 & param2 & /*

        ...
 }

In this context, the & character is taken by XSPEC as a carriage return, delimiting the model string and parameter arguments into separate input lines.

The procedure xmodel may be compiled with the command

XSPEC> source xmodel.tcl

This creates xmodel as a command with two arguments which sets subsequent parameters to their default values. It can be invoked e.g. by

XSPEC>xmodel {wa(po + peg)} $p1 $p2

Note that the model string, which contains spaces, needs to be entered in { } or quotes. Note also the "args" argument, (not used here) that tcl uses to supply a variable number of arguments to a procedure (it is supplied as a tcl list, which can be split within the procedure into separate strings for digestion by xspec if present).

tcl Script Example

In the directory $XANADU/spectral/session is a script file called tclex.xcm. This script gives an example of how one might use the power of tcl's scripting language in an XSPEC session.

This script should be executed with

XSPEC> @tclex

# This script gives an example of how one might use the power of tcl's
# scripting language in an XSPEC session.  In this example, XSPEC loops
# thru 3 data files (file1, file2 and file3) and fits them each to the
# same model `wabs(po+ga)'.  After the fit the value of parameter 4 (the
# line energy for the gaussian) for each data set is saved to a file.

# Keep going until fit converges.
query yes

# Open the file to put the results in.
set fileid [open fit_result.dat w]

for {set i 1} {$i < 4} {incr i} {

# Set up the model.
  model wabs(po+ga) & /*

# Get the file.
  data file$i

# Fit it to the model.
  fit

# Get the values specified for parameter 4.
  tclout param 4
  set par4 [string trim $xspec_tclout]

# Turn it into a Tcl list.
  regsub -all { +} $par4 { } cpar4
  set lpar4 [split $cpar4]

# Print out the result to the file.  Parameter value is
# the 0th element of the list `lpar4'.
  puts $fileid "$i [lindex $lpar4 0]"

}

# Close the file.
close $fileid

The user is encouraged to read the voluminous on-line documentation and literature available about tcl in order to benefit fully its flexible command processing, graphical interfacing, and scripting capabilities. See the Scriptics WWW site for much more information and extensive bibliography.