6.4. Customizing the ReadoutShell

6.4.1. Environment variables

This section describes sets of related environment variables that can affect the way the ReadoutShell operates.

Note that settings made using the Settings->Event Recording... override environment variables. This includes settings that have been saved from prior runs of the program.

The table below describes the settings used to control where data is saved.

	NOTE - difference from prior versions
	In the 10.x and prior versions it was possible to separate where the experiment view lived from where the event view lived by specifying the EXPDIR environment variable. This variable is now ignored and that the experiment directory will always live in the stagearea directory tree.

SSHPipe clients also have default parameterizations. These are based on the environment variables that were used by the 10.x readout shell. Reliance on these environment variables is not recommended, as they only populate the sshPIPE parameter prompter and because the point of this software is to manage multiple data sources rather so the concept of default data source parameters becomes a bit meaningless.

The table below shows the environment variables that can populate the SSHPipe settings prompter:

One last word. In the past, ReadoutShell has failed to run properly because users have defined the environment variable TCLLIBPATH to include Tcl package directories from an older version of NSCLDAQ. In the 11.x version of the program, if TCLLIBPATH is defined the program will exit with an error message unless you additionally define TCLLIPATH_OK which indicates that you are sure your TCLLIBPATH definition doesn not include any NSCLDAQ directories.

6.4.2. ReadoutCallouts.tcl

As with the 10.x and earlier ReadoutShells, the 11.0 program looks for a ReadoutCallouts.tcl file which, if found is sourced as the program is initialized. This script can contain anything, however it's main purpose is to define one or more of a set of procs that can be called by the ReadoutShell at specific times during the program's execution.

The ReadoutShell looks for the ReadoutCallouts.tcl file in the following three locations. Any ReadoutCallouts.tcl script found is sourced in at the global level. The search order (and thereby execution order) is:

1. ~ your home directory.

2. ~/stagearea/experiment/current The location the metadata associated with the current run is stored.

3. . the current working directory. at the time ReadoutShell was first started.

If ReadoutCallouts or any other script sourced into ReadoutShell provides them the following procs are called.

	NOTE
	Two additional callouts not available in ReadoutCallouts.tcl scripts for NSCLDAQ-10.x and earlier have been added.

Note that all procs described above are called at the global level (uplevel #0).

6.4.3. Integrating Tcl scripts

Besides automatically sourcing the ReadoutCallouts.tcl script described in the previous section, the ReadoutShell's File->Load... allows you to choose a Tcl/Tk script and source it at the global level at any time. The script you source can define any of the procs described inthe previous section. It can also invoke API procs from the packages described in ReadoutGUI API packages.

6.4.4. Libraries and Data source providers

The File->Library... menu command allows you to choose a directory to be added to your library path. One of the main reasons to do this is to add a custom data source provider. This section describes in general terms how to create data source providers. See Introduction for reference information on data source providers.

Data source providers can be thought of as a class whose instances manage data sources. In order to create a data source provider you must:

• Create a provider package that encapsulates the provider's interface into a Tcl namespace.

• Optionally create a prompter package that encapsulates provides a custom GUI prompter for the parameterization of the data sources your data source provider manages.

A data source provider has a name which we will refer to as providername in this chapter. The provider must provide a Tcl package. The name of that package must be providername_Provider. Furthermore it must define a namespace ::providername. If these conditions are met, and the provider's package is in the Tcl library search path, the ReadoutShell's Data Source->Add... will list the providername as one of the providers available to add a data source

Data sources have parameterizations. It is differences in their parameterizations that typically distinguish between the data sources a provider manages. Data sources describe their the form of their parameterizations via their providername::parameters proc. The parameters proc is described in parameters

If the data source provider does not provide a parameter prompeter, the ReadoutShell will construct a default simple prompter from the information returned by the data sourcde provider's parameters proc. This prompter will just be a bunch of verbose names and text entries for each name.

If this prompter is too simplistic, it is possible for a data source provider to also define a prompter. A prompter is provide by providing a package named providername_Prompter which defines the proc ::providername::promptParameters. This proc is called by the ReadoutShell with no parameters and is expected to return the either the parameterization dict (see start) for information about this dict. If the user declines to provide parameters (e.g. cancels the dialog prompter's dialog), the prompter should return an empty string.

The parameterization of a data source, along with a data source id are passed to the ::providername::start proc to start a data source. The source id is a unique value that is generated by the ReadoutShell and used to refer to individual data sources. The data source id is globally unique (not just unique to the provider). For more information abut starig data sources see: start.

Not all data sources are created equal. Thus a data source must provide a proc named ::providername::capabilities that returns a dict that descsribes the capabilities of the data sources it manages. For example, if a data source is not capable of pausing an active run its capabilities proc will report that in the dict it returns. For more information see: capabilities

Data sources must also provide a ::providername::check proc. The check proc is passed the data source id and is expected to return a boolean that is true if the data source is still alive or false if the data source is no longer alive. The data source provider can expect the ReadoutShell to periodically poll its check proc so that it is able to report to the user an unexpected exit of a data source. The check proc is described more completely in check.

Data source providers must know how to end a data source. This mechanism is exposed to the ReadoutShell via a proc named: ::providername::stop. This proc is passed the source id of the source to stop. For more information see: stop.

Finally, providers must be able to actually control their data sources. This implies at a minimum providing ::providername::begin to start a run and ::providername::end to end a run. In addition, if the provider's capabilities include the ability to pause and resume an active run, ::providername::pause and ::providername::resume must also be supplied.

The data source manager is capable of sending on-demand initialization to its registered data sources. It is thus required that each provider implements a proc named: ::providername::init to handle on-demand initialization procedures. It is particularly useful for doing things like loading firmware.

6.4.5. Using the ReadoutGUI in your own container script

The ReadoutShell is a very small script. It simply creates an instance of a ReadoutGui object after getting the package paths set up properly. This allows you to customize the way the Readout GUI is produced, not only via ReadoutCallouts.tcl scripts and State maching callback bundles, but by writing your own container script.

If you are going to do this you'll certainly need to know about ReadoutGUI API packages and their contents so that you can effectively customize the behavior and appearance of the resulting GUI.

Assuming the environment variable DAQROOT is defined and points to the top directory of the DAQ installation The example below shows a minimal ReadoutGUI startup script with comments that show where to include customizations.

set TclLibs [file join $::env(DAQROOT) TclLibs]    
lappend auto_path $TclLibs

package require ReadoutGui
ReadoutGuiApp  r                                  

                                                   
                

6.4.6. ReadoutGUI API packages

This section will describe in general terms the packages that make up the ReadoutGui's application programming interface. pointers to reference material will be provided as well.