General hooks, conditions and on_stop function

It is possible to customize all scans in a general way. The features included are: hooks, repeat-a-point-in-condition and on_stop. Hooks and repeat-a-point-in-condition have to be implemented as standard sardana macros, while on_stop has to be implemented as a function.

We recommend to define the hooks and repeat-a-point-in-condition macros in a file called

$HOME/sardanaMacros/general_features.py

and the on_stop function in a file called

$HOME/sardanaMacros/generalFunctions/general_functions.py

The file where the on_stop function is defined has to be in the directory

$HOME/sardanaMacros/generalFunctions

If this is not the case, the directory where it is defined has to be included in the property PythonPath of the Macroserver device, otherwise the function can not be loaded.

Names of the macros and on_stop functions are arbitrary, but we suggest to use the following names:

• gh_pre_scan, macro to be run before the scan
• gh_pre_move, macro to be run before each movement during the scan, also used in move commands, by default.

  There is a flag that controls this feature: PRE_POST_MOVE_HOOK_IN_MV. To change the flag edit ~/.sardana/sardana.ini:

  [sardana]
  PRE_POST_MOVE_HOOK_IN_MV = False
  

• gh_post_move, macro to be run after each movement during the scan
• gh_pre_acq, macro to be run before each acquisition during the scan
• gh_post_acq, macro to be run after each acquisition during the scan
• gh_post_step, macro to be run after each step during the scan
• gh_post_scan, macro to be run after the scan

for the hooks (the order in which the macros will be run, corresponds to the one given above),

• gc_macro

for implementing the repeat-a-point-in-condition (this macro has to have a return value: 0 if the point do not have to be repeated and 1 if it has),

• general_on_stop

for the function implemented the on_stop feature (to be run if the scan is stopped with ctrl-C).

Hooks and repeat-a-point-in-condition macros can get arguments, the general on_stop function has to be defined without arguments. If a macro is set as a general hook but it is not defined or not found, the scan will continue and a warning printout will be shown in the spock session. If the macro set as repeat-a-point-in-condition macro is not defined or not found, the scan will stop with an error.

The following macros, defined in

/usr/share/pyshared/sardana/sardana-macros/DESY_general/handleGeneralFeatures.py,

allow to activate/deactivate these general features and display information about the status:

• For general hooks:
  • gh_enable, enables hooks. If no argument is given all hooks with the default values, as suggested above, are enabled.

  • gh_enable gh_pre_scan pre-scan, enables the pre-scan hook. To be precise: the macro gh_pre_scan is executed at the pre-scan position.

    For giving other names, ex. for a post-scan hook:

    gh_enable "mymacroforpostscan oneargument otherargument" post-scan
    

    or several macros:

    gh_enable "mymacroforpostscan arg1 arg2, myseconmacro arg3" post-scan
    

  • gh_disable, disables general hooks in the position given as argument, if not argument is given disables all hooks. Ex.:

    gh_disable post-scan
    

    for disabling the general hooks running at the post-scan position.

  • gh_isEnabled, returns true and macro names if general hooks are enabled.

• For general conditions:
  • gc_enable, enables general conditions, if not argument is given the default name suggested above, gc_macro, will be given. For setting any other macro use:

    gc_enable macro_withoutargs
    

    for setting a macro without arguments, or:

    gc_enable "macro_withargs arg1 arg2"
    

    for a macro with arguments.

    Only one macro is allowed, since a condition is checked and it is better to have all the logic in one macro and not make 'and'/'or' conditions betweenn different macros.

  • gc_disable, disables general condition

  • gc_isEnabled, returns true and name of the macro if the general condition feature is enabled.

• For general stop:
  • gs_enable, enables general stop feature, if not argument is given a function called general_on_stop in the module general_functions will be called. An argument will be the name of the function and the module it belong to, ex:

     gs_enable mymodulename.new_onstop_function
    

    for calling the function new_onstop_function defined in the file mymodulename.py. The file has to be in a directory included in the macropath property of the MacroServer device.

    Also only one function is allowed. If you want to switch between several according to the hook you are running, call in your hooks this macro for setting the on stop function to the corresponding name.

    Note: the on-stop feature is not reliable.

  • gs_disable, disables general stop feature

  • gs_isEnabled, returns true and name of the function if general stop feature is enabled.

• All features together:
  • gf_status, displays the status of the general features: hooks, conditions, on_stop
  • gf_enable, enables all general features to default names
  • gf_disable, disables all general features

The general features are set in environment variables in spock, one can set/unset this variables for selecting these features or checking the selected ones:

p09/door/haso111n.01 [2]: lsenv General.*
                    Name                                                          Value   Type
 ----------------------- -------------------------------------------------------------- ------
        GeneralCondition                                                       gc_macro    str
            GeneralHooks   {'post-scan': ['gh_post_scan'], 'post-step': ['gh_post [...]   dict
   GeneralOnStopFunction                              general_functions.general_on_stop    str

On new systems (Debian-9, 21.8.2018) it looks like this:

p09/door/haso113u.01 [8]: lsenv .*Gen.*
                    Name                                                          Value   Type
 ----------------------- -------------------------------------------------------------- ------
           _GeneralHooks   [('gh_post_scan', ['post-scan']), ('gh_post_step', ['p [...]   list
        GeneralCondition                                                       gc_macro    str
   GeneralOnStopFunction                              general_functions.general_on_stop    str

The macros described in this section are DESY-specific. They have been created to provide am common interface to all hook-like features and to maintain continuity moving from Debian-8 to Debian-9. The current system macros are lsdef, defgh and udefgh.