UP arb.hlp UP agde.hlp UP glossary.hlp UP save.hlp TITLE GDE menus DESCRIPTION ARB uses the GDE menus to plugin external tools This helpfile contains parts of the original GDE helpfile and has been slightly modified to fit to the way GDE menus are used inside ARB. SECTION Using the GDE menus The GDE uses a menu description language to define what external programs it can call, and what parameters and data to pass to each function. This language allows users to customize their own environment to suite individual needs. The following is how the GDE handles external programs when selected from a menu: Each step in this process is described in the file $ARBHOME/GDEHELP/ARB_GDEmenus You may modify that file to include other external tools into the ARB interface. The language used in this file describes three phases to an external function call. The first phase describes the menu item as it will appear, and the Unix command line that is actually run when it is selected. The second phase describes how to prompt for the parameters needed by the function. The third phase describes what data needs to be passed as input to the external function, and what data (if any) needs to be read back from its output. The form of the language is a simple keyword/value list delimited by the colon (:) character. The language retains old values until new ones are set. For example, setting the menu name is done once for all items in that menu, and is only reset when the next menu is reached. The keywords for phase one are: menu:menu name Name of current menu item:item name Name of current menu item itemmeta:meta_key Meta key equivalence (quick keys) itemhelp:help_file Help file (either full path, or in $ARBHOME/lib/help) itemmethod: Unix command The itemmethod command is a bit more involved, it is the Unix command that will actually run the external program intended. It is one line long, and can be up to 256 characters in length. It can have embedded variable names (starting with a '$') that will be replaced with appropriate values later on. It can consist of multiple Unix commands separated by semi-colons (;) and may contain shell scripts and background processes as well as simple command names. If one of the commands needs access to the running ARB, the whole command should be run asynchronously, i.e. be run using '( command ) &'. Otherwise the command may lock. The keywords for phase two are: arg:argument_variable_name Name of this variable. It will appear in the itemmethod: line with a dollar sign ($) in front of it. argtype:TYPE The type of graphic object representing this argument. Known types are choice_list choice_menu chooser filename sai slider text tree weights arglabel:descriptive label A short description of what this argument represents argmin:minimum_value (integer) Used for sliders. argmax:maximum_value (integer) Used for sliders. argvalue:default_value (integer) It is the numeric value associated with sliders or the default choice in choosers, choice_menus, and choice_lists (the first choice is 0, the second is 1 etc.) argtext:default value text: Default value filename: default extension argchoice:displayed value:passed value Used for choosers and choice_menus. The first value is displayed on screen, and the second value is passed to the itemmethod line. The keywords for phase three are as follows: in:input_file GDE will replace this name with a randomly generated temporary file name. It will then write the selected data out to this file. informat:file_format Write data to this file for input to this function. Currently support values are Genbank, and flat. inmask: This data can be controlled by a selection mask. insave: Do not remove this file after running the external function. This is useful for functions put in the background. out:output_file GDE will replace this name with a randomly generated temporary file name. It is up to the external function to fill this file with any results that might be read back into the GDE. outformat:file_format The data in the output file will be in this format. Currently support values are colormask, Genbank, and flat. outsave: Do not remove this file after reading. This is useful for background tasks. outoverwrite: Overwrite existing sequences in the current GDE window. Currently supported with "gde" format only. Here is a sample dialog box, and it's entry in the .GDEmenus file: Using the default parameters given in the dialog box, the executed Unix command line would be: (tr '[a-z]' '[A-Z]' < .gde_001 >.gde_001.tmp ; mv .gde_001.tmp CAPS ; gde CAPS -Wx medium ; rm .gde_001 ) & where .gde_001 is the name of the temporary file generated by the GDE which contains the selected sequences in flat file format. Since the GDE runs this command in the background ('&' at the end) it is necessary to specify the insave: line, and to remove all temporary files manually. There is no output file specific because the data is not loaded back into the current GDE window, but rather a new GDE window is opened on the file. A simpler command that reloads the data after conversion might be: item: All caps itemmethod: tr '[a-z]' '[A-Z]' OUTPUT in: INPUT informat: flat out: OUTPUT outformat: flat In this example, no arguments are specified, and so no dialog box will appear. The command is not run in the background, so the GDE can clean up after itself automatically. The converted sequence is automatically loaded back into the current GDE window. In general, the easiest type of program to integrate into the GDE is a program completely driven from a Unix command line. Interactive programs can be tied in (MFOLD for example), however shell scripts must be used to drive the parameter entry for these programs. Programs of the form: program_name -a1 argument1 -a2 argument2 -f inputfile -er errorfile > outputfile can be specified in the .GDEmenus file directly. As this is the general form of most one Unix commands, these tend to be simpler to implement under the GDE. As functions grow in complexity, they may begin to need a user interface of their own. In these cases, the command line calling arguments are still necessary in order to allow the GDE to hand them the appropriate data, and possible retrieve results after some external manipulation. SECTION Copyright Notice The Genetic Data Environment (GDE) software and documentation are not in the public domain. Portions of this code are owned and copyrighted by the The Board of Trustees of the University of Illinois and by Steven Smith. External functions used by GDE are the proporty of, their respective authors. This release of the GDE program and documentation may not be sold, or incorporated into a commercial product, in whole or in part without the expressed written consent of the University of Illinois and of its author, Steven Smith. All interested parties may redistribute the GDE as long as all copies are accompanied by this documentation, and all copyright notices remain intact. Parties interested in redistribution must do so on a non-profit basis, charging only for cost of media. Modifications to the GDE core editor should be forwarded to the author Steven Smith. External programs used by the GDE are copyright by, and are the property of their respective authors unless otherwise stated. While all attempts have been made to insure the integrity of these programs: SECTION Disclaimer THE UNIVERSITY OF ILLINOIS, HARVARD UNIVERSITY AND THE AUTHOR, STEVEN SMITH GIVE NO WARRANTIES, EXPRESSED OR IMPLIED FOR THE SOFTWARE AND DOCUMENTATION PROVIDED, INCLUDING, BUT NOT LIMITED TO WARRANTY OF MERCHANTABILITY AND WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE. User understands the software is a research tool for which no warranties as to capabilities or accuracy are made, and user accepts the software "as is." User assumes the entire risk as to the results and performance of the software and documentation. The above parties cannot be held liable for any direct, indirect, consequential or incidental damages with respect to any claim by user or any third party on account of, or arising from the use of software and associated materials. This disclaimer covers both the GDE core editor and all external programs used by the GDE.