21.
Converting GENESIS 1.4 Scripts to GENESIS 2.0
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.
21.1.
The Conversion Process
Below is the process through which a GENESIS 1.4 script is converted
to run under GENESIS 2.0.
1. Use the convert program to convert scripts from 1.4 to 2.0 syntax.
2. Fix any known problem areas (See ``Convert Problem Areas''
(Convert_prob.doc)).
3. Try the script out and fix any remaining problems.
21.2.
Using the Convert Program
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
21.3.
Global Script Variables
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.
21.4.
Compatibility Libraries
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.
21.5.
The X1compat Library
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.
21.6.
The Connection Compatibility Library
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'').
21.7.
Converting User Libraries
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'' (Customizing.doc).
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''
(NewObjects.doc) for details.
21.8.
Convert Problem Areas
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.
21.9.
Script Callbacks
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.
21.10.
Command Options in Script Variables
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.
21.11.
Command Arguments That Look Like Options
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.
code like
However,
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.
21.12.
Script Variable/Command Name Conflicts
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.)
21.13.
Setting Integration Methods
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'' (setmethod.doc) (or
type ``help setmethod'' in GENESIS) for the new numbering.
21.14.
Sizing of XODUS Forms
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.
21.15.
Positioning and Sizing of Widgets
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.