Built-in Commands and Functions

mcount(t)

Begins counting for t monitor counts. Returns true. Hardware errors starting most counters result in a reset to the top-level command prompt.

tcount(t)

Begins counting for t seconds. Returns true. Hardware errors starting most counters result in a reset to the top-level command prompt.

cnt_mne(i)

Returns the string mnemonic of counter i as given in the configuration file. Returns -1 for an invalid argument.

cnt_name(i)

Returns the string name of counter i as given in the configuration file. Returns -1 for an invalid argument.

cnt_num(mne)

Returns the counter number corresponding to the counter mnemonic mne, or -1 if there is no such counter configured. As of spec release 6.05.01, mne can be a variable or an expression. If mne is an uninitialized variable, the function returns -1.

counter_par(mne, s [, v])

Returns or sets configuration parameters for counter mne. Recognized values for the string s include:

"monitor?"

Returns 1 if the associated controller allows software reassignment of the channel used for counting to monitor presets. Returns 0 otherwise. Controllers that support this feature include the following:

Generic EPICS scaler

Joerger VSC16/8 VME scaler

KS 3640 CAMAC counter

Macro Hardware counters

Measurement Computer USB-CTR

Missouri Research Reactor Custom

Naitonal Instruments PCIe 63XX

National Instruments PCI 6601/6002

Struck SIS3820 VME scaler

"monitor"

Reassigns the scaler channel used as the monitor-preset counter to the channel associated with counter mne if the hardware allows it. Rereading the hardware configuration file with the config macro or reconfig command will restore the monitor channel to that set in the config file.

"timer"

Reassigns the scaler channel used as the time-preset counter to the channel associated with counter mne. Rereading the hardware configuration file with the config macro or reconfig command will restore the time channel to that set in the config file. Currently only macro hardware counter/timers support this feature.

"scale"

Returns the scale factor as set in the config file.

"normalize_to_time"

With no argument, returns zero or nonzero to indicate whether the counter is configured to have its values automatically normalized to the value of the timebase counter. With an argument, sets the normalize mode. The configuration can also be set in the config file in the "Use As" column on the Scaler screen. Timebase counters are ineligible. Rereading the config file resets the mode to the setting in the file. As of spec release 6.10.07.

"controller"

Returns a string containing the controller name of the specified counter. The controller names are those used in spec's config files.

"device_id"

Returns a string for some hardware devices that identifies the hardware device ID. For example, for serial devices, returns the device name (such as /dev/ttyS1) or for GPIB devices, returns the GPIB address.

"unit"

Returns the unit number of the specified counter. Each counter controller unit may contain more than one counter channel.

"channel"

Returns the channel number of the specified counter.

"responsive"

Returns a nonzero value if the counter responded to an initial presence test or appears otherwise to be working.

"disable"

Returns a nonzero value if the counter has been disabled by software. If v is given and is nonzero, then the counter is disabled. If v is given and is zero, the counter becomes no longer disabled. A disabled counter channel will not be accessed by any of spec's commands. Any cdef()-defined macros will automatically exclude the portions of the macro keyed to the particular counter when the counter is software disabled.

"add", "delete", "name"

See RUN-TIME COUNTERS below.

getcounts

Reads values from all enabled counters and loads the built-in array S[] with their contents.

Run-Time Counters

Runtime counters can be created without editing the spec hardware config file or reinitializing the hardware (as of spec release 6.10.01). The command:

counter_par(mne, "add" [, macro_name ])

creates a new counter with the specified mnemonic. The optionally specified macro function will be called with the counter mnemonic as argument when the getcounts command is executed. When spec executes the getcounts command, hardware counters are read first, then macro-hardware counter macros are called, then runtime counter macros are called. This order determines what counter values are available to the macros. The command:

counter_par(mne, "delete")

removes the specified counter. The command:

counter_par(mne, "name", "New Name")

can be used to assign the counter name. Otherwise the name will be the same as the mnemonic. Mnemonics can be at most 7 characters, while names can be 15 characters long.

The runtime counters disappear on exit or hardware reconfiguration (reconfig). The built-in config_mac macro can be used to have the counters automatically recreated after reading the hardware configuration. (See an example of that in the acq.mac file.)

The "controller" and "device_id" options to counter_par() both return the string "RUNTIME" for these counters.

Global Variables

S[]

Built-in array that holds scaler contents after a getcounts command.

COUNT

Global variable that holds the default count time used by the ct and uct macros.

COUNT_TIME

Global variable that holds the actual count time used by the ct and uct macros.

DET

Global variable that is set to the channel to be used as the detector during scans, usually set to det.

MON

Global variable that is set to channel to be treated as the monitor during scans, usually set to mon.

MON_RATE

Global variable that holds the value S[MON]/S[sec] and is updated in the count macro.

Scaler channel assignments and scaler mnemonics are set in the config file. The standard assignments for the first three channels are:

sec = channel 0

mon = channel 1

det = channel 2

Macros

counters [new_mon new_det]

With scaler channel arguments, this macro assigns those channels to the MON and DET symbols and displays the changed scaler assignment.

Without arguments, the macro displays a menu to select which counter to use for MON and which for DET. In addition, the menu is used to configure which counters to display on the data plots. If the option to use more than one plot window is selected in setplot, the menu allows configuration of which counters are plotted in which plot windows.

ct

A macro that counts for COUNT time if invoked without arguments, or for the time given as an argument. The macro first waits for any moving to finish. After counting, the macro prints the scaler contents. If interrupted with a ^C, the counts at the time of the interrupt are displayed. A user_prect macro is called before counting is started. A user_ct macro is called after the counts have been displayed.

uct

As above, but updates the screen with the scaler contents while counting. The screen is updated every UPDATE seconds. Use the setshow macro to configure display options, such as column width, number of columns, maximum number of counters to display, etc.

count_em

The lowest level counting macro. Its optional argument is the count time. If no argument, the default COUNT time is used. Calls user_precount before and user_postcount after the call to the built-in tcount() or mcount() functions.

show_cnts

A macro that reads counters and displays the scaler contents on the screen and is invoked by ct.

scan_count

Normally defined as _count, it is called by all the scan macros. It is redefined in powder mode to be _pcount and with fly scans as _fly_count.

_count

Defined as either _ord_count or _upd_count, depending on whether scans are configured to show updated counts. Use the mstartup macro to configure updated moving and counting.

_ord_count

Defined as count.

count

Default routine for counting during scans. It waits for moving to end, counts, waits and reads scalers. It also uses the chk_beam macro.

_upd_count

Similar to count, but updates the screen with current counter values while waiting for the count interval to finish.

chk_beam

A hook macro, normally defined as break. Can be used to wait for sufficient counts during scans. See the discussion below.

get_counts

The lowest level counter-reading macro. Calls the built in getcounts command to read the hardware counters. Invokes user_pregetcounts before and user_getcounts after.

get_counts_func()

Performs the same commands as get_counts but as a macro function.

user_prect

A hook macro that allows the user to insert code to be run before the call of count_em in the ct and uct macros.

user_ct

A hook macro that allows the user to insert code to be run after counts have been displayed in the ct and uct macros.

user_precount

A hook macro that allows the user to insert code to be run before the call to tcount() or mcount() in the count_em macro.

user_postcount

A hook macro that allows the user to insert code to be run after the call to tcount() or mcount() in the count_em macro.

user_pregetcounts

A hook macro that allows the user to insert code to be run before the call to getcounts.

user_getcounts

A hook macro that allows the user to insert code after the call to getcounts.

is_using_counter(mne)

Returns zero if counter mne is named "unused" or is currently disabled. Otherwise returns 1. Used to see if the counter should be displayed and saved to the data file.

A negative argument to ct, uct, count or count_em means count to monitor counts.

Note, the words "scaler" and "counter" are used interchangeably.

The chk_beam Macro

At synchrotron facilities, there are times when the beam is unavailable, perhaps due to refilling. The standard spec counting macros include a provision to pause scans via the chk_beam macro.

The standard count macro includes the following:

for (;;) {
        count_em $1
        waitcount
        get_counts
        chk_beam
}

Under normal conditions the code within loop only executes once because the chk_beam macro is defined as the command break, which ends the loop. However, users can define chk_beam to test whether there were counts during the specified interval. Consider:

global chk_thresh

def chk_beam '
    local   nobeam_detected, start_time

    if (start_time == 0)
        start_time = time()

    if (set_sim(-1) || S[MON] >= chk_thresh)  {
        if (nobeam_detected) {
            # You can do something here if beam had been down.
            printf("Waited %d seconds for beam.", time() - start_time)
            tty_cntl("ce")
            printf("\n")
        }
        break
    }
    if (nobeam_detected == 0) {
        # You can do something here if beam goes down.
        nobeam_detected = 1
    }
    printf("Been waiting %d seconds for beam ...\r", time() - start_time)
'

The above example checks whether the number of counts in the MON scaler channel is above a threshold value to determine whether there was beam during the count interval. If the value is above the threshold, the break exits the outer for loop. Otherwise, a status message is displayed and the count interval is repeated.