GENESIS 2.0 includes a major revision of command format and command option naming, script language syntax changes, and changes in various GENESIS features. The convert program converts GENESIS 1.4 compatible scripts to use GENESIS 2.0 syntax, commands and features. Some features have changed dramatically enough that an automatic conversion to the new features is not feasible. In these cases, convert generates script code for compatibility libraries which support the GENESIS 1.4 features.
Some scripts can be converted and run successfully without any manual changes to the converted scripts. In most cases, however, some changes to the converted scripts will be necessary.
Below is the process through which a GENESIS 1.4 script is converted to run under GENESIS 2.0.
The easiest way to use convert is to create a new directory for the new scripts, cd to the new directory and convert the files from the old directory. A simple shell procedure may be used to convert an entire directory. For example, if your 1.4 script files are in the directory ../oldscript, then the following shell commands will convert the entire directory placing the converted scripts in the current working directory:
csh:
foreach script (../oldscript/*.g)
convert $script
end
sh:
for script in (../oldscript/*.g)
convert $script
end
In order for convert to handle certain script expressions involving global script variables, it must know what globals exist for a given set of scripts. (This is not a problem for a self contained script where global variables are defined and used within the script.) Often a single script file is devoted to defining and initializing global variables and constants for a given set of scripts.
The -constants option of the convert program gives a list of script
files which define the global variables for the script set. For
example, if the file constants.g contains global variable definitions
which are used throughout a set of scripts in the ../oldscripts
directory then the following csh code would convert the scripts:
foreach script (../oldscripts/*.g)
convert $script -constants ../oldscripts/constants,g
end
The ``-constants'' option will allow one or more scripts to be given.
Two areas of major change in GENESIS 2.0 are the XODUS GUI and support for network modeling (e.g. GENESIS 1.4 connections). Support for use of these facilities in GENESIS 2.0 is provided by compatibility libraries.
While the compatibility libraries allow faster conversion of GENESIS 1.4 scripts for use under GENESIS 2.0, these libraries will not be aggresively supported and should be viewed as a transitional step in converting scripts to GENESIS 2.0 facilities. Those areas of your scripts which use these libraries should eventually be recoded to use the new GENESIS 2.0 features.
Compatibility for GENESIS 1.4 features of XODUS is provided as a set of scripts using GENESIS 2.0 extended objects to implement the old XODUS objects and script functions to implement old XODUS commands. To load the X1compat library, include Scripts/X1compat in your SIMPATH and include X1compat from your .simrc or your main simulation script. Convert will not add an include statement for X1compat to your scripts.
X1compat defines a set of old XODUS compatible objects which are
named using the prefix ``x1'' in place of the normal ``x'' prefix for
XODUS objects (e.g. xform becomes x1form, etc.). Convert will
automatically transform create statements from XODUS objects in 1.4
scripts to use the X1compat objects. Some support for field naming
of old XODUS objects is included in the new XODUS objects, which may
allow direct use of the new XODUS objects. The
``-noX1compat'' convert option causes convert not to perform
the translation to X1compat objects. This is likely to be useful for
only those scripts which use the basic XODUS widgets (i.e. xform,
xlabel, xbutton, xtoggle, xdialog, and most uses of xgraph). Uses of
the xdraw widget family are likely to require use of X1compat.
Convert and the X1compat library cannot address various issues of layout of widgets on a form. See Convert Problem Areas for more information.
While GENESIS 1.4 connections are not a standard part of GENESIS 2.0, a compatibility library may be compiled into GENESIS 2.0 which supports the old connection feature. (See src/Makefile or Usermake for instructions on including the library.) The library defines the connection related objects (e.g. axon, synapses, etc.) and the connection related commands (e.g. region_connect, expweight, radialdelay, etc.) as well as connection specific commands which support set/get/show of connections (e.g. setconn, getconn and showconn). Access to connection fields is not supported by the GENESIS 2.0 setfield, getfield and showfield commands.
Convert will change connection related script statements as needed to use the Connection Compatibility Library. In particular, it will convert uses of set, get and show on connections to use setconn, et al. In some cases, convert will be unable to convert these statements (See Convert Problem Areas).
Objects and commands defined in user libraries (for the most part) will not need to change to run under GENESIS 2.0. To compile your libraries and create a new GENESIS you will need to replace and update your Usermake, Libmake(s), liblist and perhaps the library startup script.
Copy the Usermake and liblist files from the GENESIS 2.0 installation directory to your local GENESIS directory renaming Usermake to Makefile. Add your user libraries to the Makefile and liblist files. In each user library you must copy the Libmake from the GENESIS 2.0 installation directory into the library directory, renaming it Makefile. Add your library specific information and files to the Makefile. This procedure is described in detail in the section on Customizing GENESIS.
The convert program cannot be used to convert startup scripts. The only changes you should need to make are to modify any GENESIS 1.4 script language features which change in 2.0 and to remove any non-startup commands from the script. (Startup commands are object, addfunc, hashfunc, newclass and addaction.) Since a startup script is usually straight line code and the typical commands in a 1.4 startup script are the above named commands, there are normally no changes required. There are, however, some GENESIS 2.0 features you may want to take advantage of in your startup scripts. See the on library startup scripts in Defining New Objects and Commands for details.
There are a number of areas in which convert will be unable to transform script statements or where the converted code will perform in a less than optimal manner. Each problem area described below must be found and fixed manually.
Commands used as callbacks to script commands or functions are not translated by convert. As such, script callbacks like the following would fail:
create xbutton echoButton -script "echo -n this is a test"
create xdialog vmDialog -script "set /mycompt Vm <v>"
The echoButton will result in a usage error when pressed and the
vmDialog will fail because the set command has been replaced by setfield.
A command option which is passed to a command through a script variable or as the result of a command or script function will not be translated. For example, if leoptions is a script string variable holding the value ``-R'' (a recursive listing), then the following code will not be converted:
le {leoptions}
The code which sets leoptions must be found and changed.
All GENESIS 2.0 commands check for valid command options and complain when an unkown option is given. As a result, code like
echo -notAnOption
will result in a usage error. This will also be the case if a script
variable value looks like an option, e.g.
str echoOption = "-notAnOption"
echo {echoOption} // Usage error!
The usage statement can be avoided by placing whitespace before the
value, e.g.
echo " -notAnOption"
echo " "{echoOption}
Set/Get/Show Connections in Script Variables
Commands like
set anElm:0 weight 10
will be correctly translated to use the setconn command. However, code
like
str connelm = "anElm:0"
set {connelm} weight 10
will be translated to a setfield command. Convert behaves similarly
with translating the get and show commands.
With all the command name changes in GENESIS 2.0, it is possible that a script variable in a GENESIS 1.4 script may coincide with a new GENESIS 2.0 command name. In this case, you may receive a syntax error or unexpected result as the script variable will take precedence over the command name. This may be particularly likely with the el command.
(The convert program may be updated at some future point to rename script variables which clash with GENESIS 2.0 command names.)
GENESIS 2.0 removes some of the previously existing integration
methods and renumbers some of the remaining methods. Convert will
handle the renumbering as long as a number is given directly to the
setmethod command. If this is not the case, convert will issue a
warning and the command will be left unaltered. You must change the
integration numbering manually. See
setmethod (or type ``help setmethod'' in GENESIS)
for the new numbering.
XODUS 1 made use of an unsupported feature of MIT X11 which allowed forms to automatically adjust their height to accomodate all the widgets which they contain, even if the form was made too short. Although this did not work under Openwindows, it allowed users of MIT X11 to be somewhat sloppy in the sizing of forms when writing scripts. This feature no longer exists in XODUS, so forms which are incorrectly sized may not show all the widgets which they contain. The most convenient way to detemine the proper geometry specification for the form is to properly resize it with the mouse and then inspect the hgeom field for the value to use in your script.
Apart from the preceding issue, forms previously large enough to encompass a given set of widgets may not be large enough under GENESIS 2.0, as the border widths of XODUS object have increased.
Scripts which explicitly set the dimensions of a widget based on the expected dimensional requirements of a 1.4 widget may cause text or graphics within the widget to be clipped under 2.0. This is due to the additional requirements of the Motif style borders.
Likewise, widgets which are positioned using absolute coordinates on the form based on expected default dimensions of other widgets on the form may overlap other widgets on the form.
The only widget layouts used under GENESIS 1.4 which are likely to work well under 2.0 are those using relative positioning. Even if this is the case, the form size may need to be changed.