wiki:ShmDocPlugins

Version 1 (modified by MarcusWalther, 14 years ago) (diff)

--

Plug-ins

SHM provides an interface for the integration of external programs. These external programs may operate on the parameter data gathered so far or on waveform data exported in ASCII data files. Parameter data can also be reimported into SHM. Parameter data exchange format is the text based evt-File format. Typical examples of such programs are mapping tools for epicentres or own location programs. But, of course, many more types of applications can be implemented by the user.

The interface is controlled by a text file located in the user's private directory: $SH_USERDIR/external_processes.txt. Configurable are the twenty plug-in entries of the Plugin menu, one of the two location buttons of the LocSAT dialog box and routines executed after activation of Read New and Final Parameters. The syntax of the file entries is:

<command> <iface-number> <parameter>

Lines beginning with ! are comments and are ignored. The items specified on the lines must be separated by one or more blanks. The items itself therefore must not contain any blanks.

<iface-number>

Integer number specifying the interface number. The numbers 1 to 20 refer to the twenty menu entries of the plugin menu (from top to bottom). Number 21 stands for the second location button in the LocSAT dialog box. This is preferably connected with a location program (which is not checked, however). Number 22 is a routine called after Read New of the read dialog box has been selected, number 23 is a routine called after Final Parameters has been activated.

By default, all plugin entries are empty, i.e. no action is associated. Usually several commands are associated with a plugin interface, which means that several lines exist for each interface number in the external_processes.txt file. Even if not required by the software, it is recommended to group the commands sorted by interface number.

<command> and <parameter>

Available commands are:

label
Set name of the entry, this name appears in the menu entry and in the button (number 21), for interface number 22 and 23 this has no meaning. <parameter> is a text string containing the name. Please replace all blanks in the name by underscores '_'.
writeevt
Write out evt-file with the current analysis parameters to the $SH_SCRATCH directory. <parameter> contains the name of the evt-file.
shell
Call external program and pass an eventually written file (writeevt) as parameter. <parameter> contains the name of the program called. Default path is the user's private directory $SH_USERDIR, otherwise absolute paths have to be used.
bgshell
Flag. Indicates whether a separately specified shell command of this interface number should be executed in background. Default behaviour (without this flag) is that SHM waits until the shell command has finished. <parameter> is not used.
resetpar
Deletes all analysis parameters and phase picks of SHM. Usually this command is called before a readevt command to have the parameter set cleared. Please make sure that the following readevt command is successful, otherwise the analysis done so far is lost. That means the external program should provide at least the input evt-file for reading (created by writeevt) if some problem during execution arises. <parameter> is not used.
remtheo
Delete theoretical phases in the display window. <parameter> is not used. This action is included in resetpar.
waveform
Write the content of the current display window (waveform data) in ASCII format to disk. <parameter> specifies the name of the output file. Default path is $SH_SCRATCH.
currwindow
Write out the currently set display time window into a text file. The name of the text file is given in <parameter>.
shcfile
Call SH-script. <parameter> contains the name of the script (.SHC-file). Only recommended for SH experts.
readevt
Read in evt-file. Return event information into SHM. This file is usually created by an external program, e.g. called in a shell command. Please note the remarks given in resetpar.
reread
Reread the plugin definitions from external_processes.txt. In case that you want to change the plugin entries on the fly you can reread your changed definitions here.

Please note that there is only one command of a type per plugin entry available. If you specify e.g. two shell commands within one iface-number then the second shell overwrites the first. The order of execution is also fixed to: writeevt, waveform, shcfile, remtheo, resetpar, readevt, reread.

An example entry in external_processes.txt would look like:

label    1 Preview_Map
writeevt 1 epimap.evt
shell    1 preview_map.csh

The first line sets the name in the first menu entry to Preview Map, the second creates an output file $SH_SCRATCH/epimap.evt and the third line calls a plotting program to create a map around the epicentre found in epimap.evt. The program needs to read and interpret the evt-file format.

In case of a location program the lines would look similar to

label    21 Hypocenter
writeevt 21 hypo.evt
shell    21 call_hypo.csh
resetpar 21
readevt  21 hypout.evt

The additional entries resetpar and readevt replace the original parameter set and phase picks. The hypout.evt is an output of the call_hypo.csh program. This program must be able to read and write evt-files. The hypout.evt file should include all information passed by hypo.evt plus an added/modified epicenter location.


back to documentation index