Run Control Scripts

The Run Control provides a scripting subsystem. Scripts that want to use it must be of the form:

#!/usr/bin/env python2
import time,datetime

progress=0

def script_example_init():
    declare_param("xml_config","calxml configuration file","")
    declare_param("storage_id","id of the storage device","")
    declare_param("xml_config","calxml configuration file","")
    declare_param("acq_time","duration of acquisition","0")

def script_example_run(dev_name,storage_id,xml_config,acq_time):
    global progress

    progress=0
    print("loading config file")
    load_config_file(xml_config)

    progress=10
    print("initialize")
    transition(dev_name,"init","deinit")

    progress=20
    print("configure")
    transition(dev_name,"config","inval")

    progress=30
    run_name="script_example/%s"%(datetime.datetime.now().strftime("%Y%m%d_%H%M%S"))
    print("creating run %s"%(run_name))
    run=new_run_rcs(storage_id,run_name)

    progress=40
    print("start acq in run %s"%(run["id"]))
    acq=new_acq_rcs(storage_id,"single_acq",run)
    transition(dev_name,"start_acq","undef","{'acq_id':'%s','acq_path':'%s'}"%(acq["id"],acq["path"]))

    div=3
    try:
        for i in range(div):
            print("sleeping for %.1fs..."%(float(acq_time)/div))
            int_sleep(float(acq_time)/div)
            progress=40+i*30/div
    finally:
        print("stop acq")
        transition(dev_name,"stop_acq","undef")

    progress=80
    print("invalidate")
    transition(dev_name,"inval","undef")

    progress=90
    print("deinitialize")
    transition(dev_name,"deinit","undef")

    progress=100

def script_example_get_progress():
    return progress

execfile("/opt/pyrame/common_rcs.py")

The NAME of the script is script_example. The filename must therefore be named script_example.py. At least one function named NAME_run must exist. In this case that is script_example_run. Two more functions can optionally be used:

• NAME_run: This is the main function that runs the script.
• NAME_init: This is the initialization function. It is run when loading the script and is typically used to declare parameters. The declaration of parameters allows to define a description and a default value. This is how GUIs can expose meaningful dialogs for scripts.
• NAME_get_progress: This function must return the progress status of the script at any moment. In this example, we return the global variable progress that is set through the script_example_run function.

At the end of the script, the mandatory execfile(“/opt/pyrame/common_rcs.py”) command is required.

These scripts can be simply executed as ./script_example.py or using the API of cmd_rc (load_script_rc, set_script_param_rc, start_script_rc, stop_script_rc, etc.).

Functions available to scripts

common_rcs.check_stop()

Check if the stop flag has been set by the Run Control. If yes, raise a rc_stop_exception

common_rcs.int_sleep(timeout)

Perform an interruptible sleep of timeout seconds

common_rcs.declare_param(name, desc, value)

Declare script parameter named name and described by desc. Initialized to value.

common_rcs.rc_call(function, *args)

Performs a call to a pyrame function through RC. This function checks for stop signal before returning

common_rcs.rc_pycall(function, *args)

Performs a call to a pyrame function through RC. This function checks for stop signal before returning

common_rcs.rc_exec(command, *params)

Executes a command in a shell and checks for stop signal and turns bash returns 1 into exceptions and returns output (stdout and stderr) of command

common_rcs.transition(dev_name, transition_name, transition_fallback, params='')

Perform an arbitrary transition with name transition_name and in case of error, perform the transition transition_fallback. Pass params to transitions

common_rcs.load_config_file(filename)

Load an XML configuration file filename

common_rcs.save_config_file(filename)

Save the current configuration file to filename

common_rcs.new_run_rcs(storage_id, run_name, mode='append')

Create a new run named run_name. mode can be remove or append. ‘remove’ overwrites existing runs with the same name. Use the storage module with storage_id

common_rcs.new_acq_rcs(storage_id, acq_name, run, mode='append', convert_script='undef')

Create a new acquisition named acq_name in run. mode can be remove or append. ‘remove’ overwrites any existing acq with the same name. Use the storage module with storage_id

common_rcs.wait_acq_finished_rcs(storage_id, acq)

Wait until the acquisition acq (object returned by new_acq) has finished. Use the storage module with storage_id

common_rcs.wait_run_finished_rcs(storage_id, run)

Wait until the run run (object returned by new_run) has finished. Use the storage module with storage_id

common_rcs.set_param_run_rcs(storage_id, run, name, value)

Set the value of parameter name for run (object returned by new_run). Use the storage module with storage_id

common_rcs.get_param_run_rcs(storage_id, run, name)

Get the value of parameter name for run (object returned by new_run). Use the storage module with storage_id

common_rcs.set_param_acq_rcs(storage_id, acq, name, value)

Set the value of parameter name for acquisition acq (object returned by new_acq). Use the storage module with storage_id

common_rcs.get_param_acq_rcs(storage_id, acq, name)

Get the value of parameter name for acquisition acq (object returned by new_acq). Use the storage module with storage_id