Spice_icon SPICE
Spectrometer Instrument Control Environment


How to use command-line variables:

A structure exists in SPICE where any quantity stored in global variable space can be used from the command line.  The combination of this together with the ability to perform mathematical operations on the command line is very powerful and makes the command-line interface much more powerful.


Usage:

The use of these command line variables is best described with an example.  An example of a command which extensively uses these command-line variables is the setpos alias.  The definition of this alias is:

     zero %1 @(%1.zero)+@(%1)-%2

To understand this definition lets consider a specific case.  Let's assume the motor s2 isn't correctly zeroed.  The user finds the correct zero to be at 1.5 degrees, moves to this position and then issues the following command:

     setpos s2 0

If the currently stored zero angle for s2 is -0.5 degrees, the above setpos command will issue the following zero command:

     zero s2 @(s2.zero)+@(s2)-0

Since @(s2) reads the current position for motor s2 (1.5 degrees) and @(s2.zero) will read the currently stored zero angle for motor s2 (-0.5 degrees), the parsing of the command-line variables translates the command to:

     zero s2 -0.5+1.5-0

which the mathematical parser in the command-line then converts to:

     zero s2 1.0

which is the correct zero angle which is needed to convert the current position (1.5 degrees) to the specified position (0 degrees).  It should be fairly clear from the above example that the use of these command line variables takes a process which requires the user to know the current zero angle of a motor and the definition of how that zero angle should be properly applied and convert it to an alias which is very easy to use.


Definitions:

The definitions of command-line variables requires a knowledge of global variable names and the corresponding global variable files in LabVIEW and, therefore, should only be added or modified by someone with a fairly good understanding of the underlying code.

The command-line variables are defined in a configuration file.  The location of that file is specified in the top-level configuration file (usually named configure.ini and located in the same location as the spice.exe executable - typcally c:\program files\spice).  Under the [Paths] section, there is a Variables key which defines the name of the command-line variable configuration file.  This file name will be relative to the System path, defined by the System key, which is relative to the top-level path, defined by the TopPath key.  So, for example if the top-level configuration file looks like the following:

[Paths]
TopPath=C:\DataAcquisition
.
.
System=System
.
.
Variables=variables.txt

then the command-line variable definition file will be:

C:\DataAcquisition\System\variables.txt

The configuration file itself has a syntax which is best described through a series of examples.

Example 1:

[numdevices]
globalfile=instrument_globals.vi
globalname="Number of Devices"
globaltype=integer

This definition defines the number of devices reads the value from the Number of Devices integer control which is contained in the instrument_globals.vi global LabVIEW file.  The name of the variable defines the name which can be accessed from the command line so access to this command would be @(numdevices).  As an example, if there were 30 devices, the command:

comment "The number of devices for this spectrometer is @(numdevices)"

would generate the command

comment "The number of devices for this spectrometer is 30"

Example 2:

[alat]
globalfile=UBmat_globals.vi
globalname="Lattice Parameters"
globaltype=2dreal
rowindex=0
columnindex=0

This definition allows the a lattice constant to be used.  This lattice constant is stored in a 2d real array in the UBmat_globals.vi file.  This differs from example 1 in that the row index and column index of the 2d array must be specified to allow the variable to be extracted.  For a 1d array, only the rowindex is needed.  This command line argument is accessed by @(alat).

Example 3:

[zero]
prefix=motor
globalfile=MotorUserGlobals.vi
globalname="Motor Zeros"
globaltype=1dreal

The above definition allows the current stored zero angle for a motor to be used and is the variable employed in the example above.  This differs from the previous 2 examples in that it includes the prefix= key.  This allows an array to be indexed by a given name which in this case is the motor name.  So Motor Zeros is a 1d real array stored in the MotorUserGlobals.vi file but the value returned from it depends on which motor name is given as the prefix.  For instance, @(s1.zero) will return the zero angle for motor s1.

Existing Definitions:

The definition which currently exist in SPICE can be separated into 2 categories, those that require a prefix and those that do not:

No prefix required:

Variable Name
 Usage
 Description
 Type
lastcommand
 @(lastcommand)
 The last as-typed command issued
 string
defy
 @(defy)
 The default y variable
 string
defx
 @(defx)
 The default x-variable
 string
numdevices
 @(numdevices)
 The number of defined devices
 integer
alat
 @(alat)
 The a lattice constant
 real
blat
 @(blat)
 The b lattice constant
 real
clat
 @(clat)
 The c lattice constant
 real
alpha
 @(alpha)
 The alpha lattice constant
 real
beta
 @(beta)
 The beta lattice constant
 real
gamma
 @(gamma)
 The gamma lattice constant
 real
energy
 @(energy)
 The stored energy value (meV)
 real
methodreal0
 @(methodreal0) The first real value returned from the method command
 real
methodreal1
 @(methodreal1) The second real value returned from the method command real
methodreal2
 @(methodreal2) The third real value returned from the method command real
methodint0
 @(methodint0) The first integer value returned from the method command
 integer
methodint1 @(methodint1) The second integer value returned from the method command integer
methodint2 @(methodint2) The third integer value returned from the method command integer
methodstr0
 @(methodstr0) The first string value returned from the method command string
methodstr1 @(methodstr1) The second string value returned from the method command string
methodstr2 @(methodstr2) The third string value returned from the method command string
methodreturn
 @(methodreturn)
 The overall integer return code from the method command integer

Prefix required:

Variable Name Prefix
 Usage
 Description
 Type
ulimit
 motor
 @(s1.ulimit)
 The upper limit for the specified motor
 real
zero
 motor
 @(s1.zero)
 The zero angle for the specified motor
 real
tolerance
 motor
 @(s1.tolerance)
 The tolerance for the specified motor
 real
speed
 motor
 @(s1.speed)
 The speed of the specified motor
 real
status
 motor
 @(s1.status)
 The status of the specified motor
 real
llimit
 motor
 @(s1.llimit)
 The lower limit for the specified motor
 real
motorunits
 motor
 @(s1.motorunits)
 The units of measure for the specified motor
 string
presetable
 counter
 @(detector.presetable)
 Whether a counter if presetable or not
 boolean
defpreset
 counter
 @(detector.defpreset)
 The default preset value for the specified channel
 real
countunits
 counter
 @(detector.countunits)
 The units of counting for the specified channel
 string
name
 device
 @(s2.name)
 The name of the specified device
 string
alias
 device
 @(s2.alias)
 The alias of the specified device
 string
type
 device @(s2.type) The type of the specified device
 string
desc
 device @(s2.desc) The description of the specified device
 string
vi
 device @(s2.vi) The vi name for the specified device
 string

NOTE: for prefix=device, the prefix can be any specified device (motors, counters, etc.) not only a motor (as used in the above example).