Desire Graphical Editor
General Manager System
DESIRE Specifications
User Manual

Special version for DEMAS course



This document describes tools that can be used to

Create and edit DESIRE specifications,
Automatically generate a prototype from the specification, and
Monitor execution of this prototype.

The first step is supported by a graphical editor called DesTool. Separate tools are available for generating a prototype and executing it. These tools can be activated from within the graphical editor.


This section describes the invocation of and interaction with the tools.

Tool invocation


DesTool is the graphical editor for specifications of multi-agent systems. Normally, DesTool is invoked from a UNIX shell prompt1. To load and manipulate a specific DESIRE specification stored in a file called specification.dtb, type the following command:

destool specification

After the graphical editor has loaded the specification, the specification can be manipulated. The functionality of the graphical editor is described in more detail in Chapter 5.

Specifications of multi-agent systems in DESIRE use a graphical representation. When saving these specifications, this graphical information has to be included. Therefore, specifications are saved in a binary format which is not (directly) readable by the user. These binary files have a .dtb suffix.

From within DesTool, the automatic prototype generation and prototype execution tools can be activated using the appropriate commands from DesTool's File menu as explained in Chapter 5. Sometimes, it is more convenient to generate prototypes and to execute them separately from (not from within) DesTool, and for that purpose separate programs are available. If you want to create a prototype from within DesTool, but execute it externally, the procedure is as follows. First generate a prototype from DesTool, through the File, Check Impl sub-menu entry. This results in the creation of a file called which serves as input to the general manager (which is the environment for executing prototypes). The program tgm implements the general manager.

To start the general manager either choose Run from the File menu or simply type:


It is also possible to externally generate the implementation file. For this purpose, an intermediate ASCII file (which does not contain the graphical information) must be generated from DesTool. This can be done through the Build and Build As entries in the File, Advanced sub-menu. A file called specification.hkb will be generated.

By typing at a UNIX prompt:

impl specification.hkb
a prototype is created (stored into a default file If you wish to run this prototype, simply type:

User interaction with the general manager

The general manager is the tool that monitors execution of prototypes generated from DESIRE specifications. This section describes its user interface.


The UNIX command tgm or the File, Run sub-menu entry in DesTool activates the general manager. By default, tgm uses the most recent prototype file, which is stored in If the name of a prototype file is explicitly specified when invoking tgm, this prototype will be used.

We want to mention here the following properties of tgm:


tgm maintains a list of atomic tasks that need to be performed. The main tasks are task control activations and primitive component activations.

Some care has been taken to minimize the number of activations, i.e., task control is only activated when some relevant input atom changes its value. When the task control is rescheduled this is clear in the trace, for example:

		rescheduled "utility_agent" : ev change  of "own_process_control"
		rescheduled "utility_agent" : state->idle  of "own_process_control"
		rescheduled own_process_control: own ev change

Primitive awake components or composed component input interfaces may also be rescheduled by awake links, since such a link changes the input information of a component. This will be signaled as follows:

		rescheduled awake link destination "own_process_control_l1_output"


Links are not put onto the task list. Awake links are activated once immediately after they become awake. Later, they are triggered immediately by changes in their source interface.

General manager user interaction

tgm starts up in a single step mode, where each step is the activation of a scheduled component or task control task.

After each step, tgm displays the following menu (or an abbreviated version of it) to the user:

main menu

continue :c quit :q restart :r debug :d pr lastm :p pr modx :m new kbs :n output :o pr file :f dump :u stepping :s
enter choice:

We will briefly describe each of these choices:
  • continue: Continue with the next action.
  • quit: Stop execution, leave tgm.
  • restart: Restart this implementation. Presently not functioning.
  • debug: This choice offers a debugging menu; it is used onlyfor debugging tgm.
  • pr lastm: Give a print-out of the most recently activated component/task control. The print-out consists of a list of all true or false atoms inthe buffers and of those atoms for which a meta relation holds.Besides the truth value, the way the result was obtained is alsoindicated.
  • pr modx: Give a print-out of a specific component, task control or buffer. After choosingthis option the user is asked for the name of the component, for thename of a task control, or for the buffer name.
  • new kbs: Start a different implementation. Not functioning.
  • output: Redirect further output to a file instead of to thescreen. After choosingthis option, the user is asked for the name of the file. The main menu will still be visible on the screen. The output will returnto the screen when this option is again invoked, and user is typed in as file name.
  • pr file: Redirect only the output of buffer contents print-out toa file instead of to the screen. After choosingthis option, the user is asked for the name of the file.Each new activation of print-out overwrites the old contents of this file. The output will returnto the screen when this option is again invoked, and user is typed in as file name.
  • dump: Activate a sub-menu for saving and restoring thestate of a running prototype.
  • stepping: Activate a sub-menu that controls the way thegeneral manager steps through the supervisor rules. This menu looks as follows:
    control menu

    leap :l spy modx :s spy mod# :p spy atom :a unspy m :u unspy at :n leap tm. :t quit :q mainmenu :m
    enter choice:

    We will describe the most useful options:

  • leap: Continue with next actions, do not interrupt the sessionwith further menus until a marked component/buffer/task control is encountered. At the end of the run the main menu will be offered once more for inspecting the final result.
  • spy modx: Mark a specific component/buffer/task control such that when option
  • leap is chosen later, the leap mode is exited after activation of thespecified component/buffer/task control. More elements may be marked in such a way. The element will remain marked until it is explicitly unmarked.
  • unspy x: Unmark a marked component/buffer/task control.
  • quit: Stop execution.
  • mainmenu: Return to the main menu.
  • Run Trace Output

    During the session, tgm generates output when:

    One should avoid halting tgm by typing CONTROL-C. If this is necessary nonetheless, the prolog interactive environment is entered. Prolog might ask input, indicated by the text Action (h for help):; to abort the session you could type in e, Return and if the prolog prompt (which looks like ``:-'') is shown, type halt..(The full stop should be entered too.)

    Atom links and term links

    In atom links and term links, no isolated variables may occur; each variable on one side of the link should also occur on the other side. Moreover, on the same side each variable may occur only once. So each variable links exactly one argument of the left-hand side of the link with exactly one argument on the right-hand side. Arguments of atom links and term links may also be constants (objects).

    Implementation generator

    The current section describes user interaction with the separate implementation generator impl. Please note that it is not normally necessary to directly use the separate implementation generator. A better interface is provided by using the implementation generator through DesTool's File, Check Impl sub-menu entry. This interface is descibed in Chapter 6.

    The implementation generator impl reads an input file containing the specification, checks the syntax, carries out some semantic checks and -- if no errors are encountered -- builds a prototype the general manager may execute.

    You should use files generated with DesTool by the Build or Build As buttons as argument to the implementation generator. These files will normally have an extension .hkb.

    The .hkb files are partial mappings of new DESIRE specification parts onto an earlier version of DESIRE. You may encounter older terminology in error messages. Interpret the word module as task control/primitive component or buffer, interpret transformation as link.

    Examples of detected errors:

    Error messages

    Implementation generation takes place in three phases:

    If a syntax error is detected, implementation generation is aborted immediately with a message containing the line where the error has been detected.

    In the second phase errors may occur that are caused by undefined elements (such as the use of objects that are not defined to be part of a sort).

    The prototype generator considers defining an information type within another information type an error. Such a definition would not be visible outside of the information type in which it is defined. Warnings may occur such as for sort links for which no object links are present (such sort links serve no purpose).

    Errors may occur that may be classified as `bugs'. Error messages of the form

    Programming Error: [tex2html_wrap_inline425]
    Implementation Error: [tex2html_wrap_inline427]
    are `bug' related. Another form of `bug' may be uncontrolled programming errors leading to core dumps. In case of bugs in tgm it is possible that one unintentionally enters the prolog environment. We did our best to avoid such errors2.

    Limitations of impl and tgm

    Both the prototype generator and the general manager system have some limitations. Some of these limitations will be dealt with.


    In the specification language, relations are defined within information types. It is possible to use the same name for different relations within different information types. As long as these information types are not used in one and the same component, there are no problems. But if they do occur in one component there are two distinct relations present with the same name and the prototype generator will have to choose which one is valid. It is better to avoid this.

    If the same relation is needed both in the input and in the output information type of a component, but the input and output information type should be different, then one should define the relation in a separate information type and import this information type in both input and output information type.

    As object level atoms are meta level objects and functions, distinct names should be used for all objects, functions and relations within a component information type. Also names should differ from predefined meta information type elements.

    Implementation generator

    The whole specification is loaded into memory for analysis. This limits the size of specifications that can be handled.


    The DesTool user interface is based on two main concepts:

    The primary user interface consists of a window with the following parts:

    Some user actions initiated in the canvas will activate an independent editor for a DESIRE specification element. These editors will be called "dialogs" and are described in Section 5.3.

    Menu Bar

    The menu bar consists of a number of buttons containing sub-menus. At the moment the documentation only describes those features that need the most clarification.


    The entries Load, Save and Save As provide the basic loading and saving facilities.

    If you decide to run specifications from within DesTool, Run or Run connected should be pressed. Run starts tgm, the stand-alone version of the general manager. Run connected starts xtgm, a special version of the general manager which connects itself to DesTool and is able to show component and link activations in a graphical way by changing colours in DesTool's canvas windows. User interaction with this special version is the same as for the stand-alone version, which is described in Section 2.2.3.

    The entry Check Impl is used to generate prototypes that can be run using the Run or Run connected entries. Errors detected during prototype generation are reported by DesTool in a small message window. Clicking on an error message in this window opens a dialog containing the specification element where the error was detected. See also Chapter 6. Check Impl always checks the whole specification. It is also possible to check certain specification elements separately by choosing Check semantical from their dialog's popup menu, as described in Section 5.4.1.

    The Print sub(sub) menu allows you to print a nicely laid out version of the specification and the graphical information.

    The entries in the Advanced submenu provide variants of the functions accessible by the menu entries described above. If you wish to generate an intermediate file that can be translated with external programs as described elsewhere, select Build or Build As from the Advanced submenu. This creates an .hkb file, from which a prototype can be generated using impl. However, the error messages that are possibly generated are quite obscure and difficult to track back to the specification elements from which they originated, so it is adviced to use Check from the Advanced submenu and handle errors before activating Run or Build. Of course, using Check Impl directly is even more convenient.

    Edit Selection and Edit

    The Edit Selection and Edit menus provide almost the same menus. These menus are also available through the canvas, by pressing the right mouse button, which is called the `menu'-button. It is possible to zoom in or out into the hierarchy through these menus and the component editor dialog may be activated through this menu.


    The response of the canvas to user mouse actions does not depend on a mode, contrary to what is often the case with other graphical editors.

    Pressing the left button on the canvas creates a new component. Pressing the left button of the mouse while on an output buffer of a component (i.e. the small extensions on the right side of component boxes) starts a link. Then a line connects the current mouse position to the location of the initiating button press. Pressing the left mouse button again defines a new line segment of the link, which is useful for making bends in the link. If you press the middle mouse button while pointing to an input buffer of a component, the link is really added. Leaving the canvas window, or pressing the middle or right button while not pointing to an input buffer, removes the line segments without creating a link.

    Pressing the menu-button (the right mouse button) on different objects and on the background shows an appropriate menu. The canvas background menu refers to operations on the composed component that is represented in the canvas.

    Alternatives to menu-button operation is provided by the Edit and Edit Selection menus at the top of the frame. Edit Selection provides operations on the currently selected graphical element (select by pressing shift left button). Edit provides operations on the current composed component.


    This subsection will provide a detailed documentation of the functionality of the dialogs appearing in DesTool. The application will refer extensively to these chapters by means of help buttons or menu entries.

    Common Behavior

    Most dialogs provide a number of buttons at the bottom of their window. Their function is as follows:

    Buttons, text entry elements, lists etc, that are grayed out, indicate that they are not active and insensitive to user actions.

    Only text entries with a caret (`^') in them are editable. Some text entries may only be changed by activating their menu, e.g. by pressing the right button in them. When you have changed the contents of a text entry, take care that you press the Return key to finalize the result. If you do not do this, the result of your changes may be lost!

    Dialog Elements


    Editors are sub-windows where you may enter text. Presently editors are used for the following specification parts:

    Each editor provides a menu (press the right mouse button while in the editor sub-window).

    Some menu entries are common, i.e.

    The behavior of the editors remotely resembles the editor `emacs'. An undo facility is not available yet. The way keys are denoted here may look unfamiliar to non-emacs users:

    Moving the cursor

    The arrow keys can also be used for the first four functions.


    It is possible to select a region to be deleted or grabbed. Be aware that the selection that shows as a yellow colored region when dragging the mouse over a piece of text is not the region the following commands work on.

    The region that is deleted or grabbed by C-w is determined by a mark set by C-@ and the current pointer position. This region is not visible as such but may be identified by multiple invocation of C-x C-x.


    After entering the required Control key combination, just type in the text you are interested in. The search commands are incremental search commands, i.e., after entering part of a text, the editor will search for it, after which you can extend the text, and the editor will search for this extended text.


    First select the text to be copied by dragging the left mouse button. Then put the cursor at the position you want the text copied to by pointing the mouse there and pressing the left mouse button. Finally press the right mouse button.

    Specialized Menus

    By pressing the right mouse button, a locally configured menu is shown. If you do not like the functionality provided by this emacs-subset, all menus will provide a save/load facility that enables you to activate your own editor on the files.

    Key bindings

    Below are all the commands in one list:

    Information type Editor

    With this editor the information type may be edited.

    Relation Editor

    The relation name may be changed by first editing the Relation: field and then typing Return. Sorts may be added by pressing the right mouse button while in the Sorts: list. A menu becomes visible.

    Sort Editor

    The sort name may be changed by editing the Sort: field and then typing Return. The other fields may be manipulated by activating the menus of the lists with the right mouse button.

    The name of an object may be changed by selecting the edit entry in the objects list with the pointer pointing to the object you wish to edit. Then the text field to the right of the list may be changed after which you should press Enter to finalize the new object name.

    Component Editor

    Three kinds of components are supported: reasoning, alternative, and test. The last kind is the initial kind a component belongs to. It allows for testing a specification without specifying component bodies. This mode is the default mode.

    Link Editor

    The Source and Destination information types may be chosen by activating the menu of one of both information type fields. One value is the value default, which will be assigned as a default. This means that the information type is the whole output or input information type of the source respectively destination module. For meta roles, only one builtin information type is possible, so only the default value is valid for these roles.

    The links (sort links, object links etc) may be specified as default. If this is chosen, DesTool internally generates a default set of links depending on the information link kinds and the module information types. The other option is Specified. In this case you should enter the link body in the editor field.

    Task Control Editor

    This allows one to enter task control rules. For the time being these rules must be typed in. The menu-button (right mouse button) allows one to insert a template or example rule.

    Component Rule Editor

    This editor allows the user to enter a primitive component knowledge base. The menu-button allows one to insert a template or example rule.

    Dialog Properties Editor

    The Dialog Properties Editors purpose is to configure the various other dialogs. Presently one may only change the way editors get activated on demand, denoted by the Activate: field. This is the only field that may be edited, and only if the message "kind editable" is marked beneath the Activate: field.

    Values have the following meaning:

    Errors in Specifications

    By selecting the Check Impl sub-entry of the File menu, the specification is checked. This is necessary since there still are parts of the specification that are not automatically checked for errors by DesTool. This is notably the case for areas where you have to enter text, e.g. initial kernel facts, task control knowledge bases, primitive component knowledge bases, and user defined link bodies.

    When selecting the Check Impl or Advanced, Check sub-entries from DesTool's File menu, a syntax/semantic checker is started up. If errors are found, different windows may be opened for you to be able to investigate the errors.

    Two kinds of errors are distinguished:


    ... prompt1
    For the DEMAS course, DesTool is started from the Windows `Start' menu.
    ... errors2
    If such errors should occur in spite of our efforts, we would like to hear about them, preferably accompanied by the specification in which the error occurred and after which actions (Lourens van der Meij, e-mail:

    Wijngaards WCA