ApplicationDevelopmentInput

Input Structure

Configuring Input Items

Some effort has to be put in the design of the input configuration structure. This requires knowledge about how to declare interface items and how these translate into the input argument of the computation code. Interface items are organised in a class based configuration tree? and the transition from this tree to the input data structure is implemented in the harvest method for each input item class. The data structure used to describe the batch inputs may require some changes to the way one used to think about user input:

• Context sensitivity is limited.
  • It is not possible to change the structure of the configuration based on the contents of user input (e.g. to read a file and offer input options based on some contents of the file). It is necessary to implement a choice first and rely on the user to enter appropriate input.
  • It is not possible to set default entries of one configuration item based on user input to another item.
• Consistency checks are limited.
  • Checks for validity of one input given the contents of another input are possible, but are limited to subtrees in the configuration tree (i.e. it is not possible to access contents of sibling nodes).
  • Final consistency checks have to be done at run time, after dependencies have been resolved.

The input structure has to be programmed using the class construction methods of the batch system. There is a GUI designer available that uses the batch system to generate input configuration scripts.

Context Sensitivity in Input Dialogs

Consider the following pseudo code:

% get a data file
file = uigetfile;
% load the file, inspect its contents
var = load(file);
if isfield(var,'dataX')
    paramX1 = get_input('ParamX1');
    paramX2 = get_input('ParamX2');
elseif isfield(var,'dataY')
    paramY1 = get_input('ParamY1');
end

Based on the contents of the data file, two different sets of parameters are required. In the batch system, it is not possible to read the data file during data entry (because it might not yet exist). The solution to this problem is to ask the user to specify the type of data file (i.e. whether the file will contain dataX or dataY at run time) and offer the appropriate set of parameter inputs for each case. The batch system can call a customised consistency check after the input is really available to test whether user input and data file really match. This check will be performed before the module is actually run. Thus, the module itself can rely on being called with correct inputs and input checks do not need to be repeated there.

Configuring Default Values

There are several ways to initialise the configuration with default values:

• Programming them in the configuration files itself. This has the disadvantage that it may be difficult to find out what defaults have been programmed - especially if your configuration files grow larger.
• Using a defaults file that will be read by the configuration management utility while loading the configuration. This defaults file consists of a harvested, job-like structure. It can document all possible job tags and thus serve as a reference to what fields are allowed in a job and what defaults they have.
• Using a .def field in any cfg_leaf item. This should be a cell with at least two entries: The first one a function handle, the following arguments are free-form. Once a job is created, the configuration will be initialised by calling feval(item.def{:}), i.e. calling the function handle with the entries .def{2:end} as argument. This way, each application can manage its defaults in its own way, and the configuration utility will pick up the current defaults at run time.

Defaults in the configuration files have lowest precedence, defaults from a .def field will override all other defaults.

Transition from cfg_item Tree to Job Input (Harvesting)

The configuration tree used to define input items has too many information to be useful as input to a computation module. Therefore, a harvest operation is performed before a computation module is run. This operation collects all information entered during job creation in a struct/cell variable according to the following rules:

• cfg_entry items:

The entered input will be returned.

• cfg_branch:

Returns a struct. The field names are the tags of the items in the .val field of the cfg_branch, their values are set to the harvest output from the corresponding item.

• cfg_choice:

Returns a struct with a single element. The tag of the choosen item is used as field name and the value of this field is the result of harvesting this item.

• cfg_repeat:

This is the item with the most complicated harvest rules.

• If there is only one item in values, then for each item in val:
  • If this item is a cfg_branch, then a struct array will be returned, containing the fields of the harvested structs. The tag of the cfg_repeat item is not used in this case.
  • If this item is not a struct, a cell array with as many elements as items in val is returned. Each cell element contains the harvested output of the corresponding item. The tag of this cell is the tag of the child item, the tag of the cfg_repeat is not used.
  • If the forcestruct flag is set to true, harvest as if there were multiple items in values. This is useful e.g. in application development if there is currently only one item to repeat , but in a future release there will be more choices.
• If there are multiple items in values or if forcestruct is true, then the result will be a cell array of structs. Each struct has a single element with the tag of the corresponding val item as fieldname (similar to cfg_choice). The tag of the cell array itself will be the tag of the cfg_repeat item.