Table of Contents
The GRT is a thin C layer, inspired by Objective C, which allows for dynamic typing and dynamic data objects. The GRT is used by the MySQL Migration Toolkit and provides a means for expanding these tools. Through the use of the GRT, these tools can support new behavior and data sources using code written in languages such as C, C++, Java, Python, and Lua with support for Mono forthcoming.
The GRT is not only useful for expanding MySQL GUI Tools. By using a script file from within the GRT shell you can perform repetitive tasks programmatically from the command line. Suppose, for example, that you have multiple schemata that you wish to migrate to MySQL. You can do this once using the graphical interface, in the process saving the procedure as a script file. You can then adapt this script file and run it unattended from the GRT shell.
The preferred development language is Lua
, a
lightweight scripting language expressly designed for extending
applications. For more information about this language see
lua.org.
The GRT supports Lua version 5.0. Version 5.1 is not supported.
To open the GRT shell from within the MySQL Migration Toolkit choose the
option under the menu. I
The GRT shell itself is the default tab on the left of the screen.
Beside it is the Snippets
tab, used for saving
code snippets.
On the right, is the GRT Globals
Tree
—showing the various objects, variables,
structures, and code modules used by the application. These
objects are all directly accessible from the shell.
The menu runs across the top of the screen and varies significantly depending upon which OS you are using. Since the MySQL Migration Toolkit is currently only implemented on Windows, all references to invoking the GRT shell from this application apply only to the Windows OS.
Currently only two of the submenus under the
menu are implemented;
, which simply exits the GRT shell,
and . The option is for opening existing
Lua
scripts and is only implemented under
Windows.
Sample scripts are found in the Scripts
directory which is immediately below the installation
directory. Opening a script from this menu option will
create an additional tab labeled with the name of the
script. Click on this tab to see the file contents. You may
paste text between the GRT Shell
tab and
any script tab.
Under Linux the
menu shows menu items for closing the shell, refreshing the objects listed in the Global tree or saving the object tree.
The Objects Tree
.
Under Linux there is no menu option to open a script.
The
option of the menu refreshes the view of the objects shown in the object tree tabs on the right.
The Values
tab
on the right. When checked, shows the data type of objects and
shows their value.
The
shows the current number of references to specific objects.
The GRT shell is principally used for running Lua scripts or
typing Lua commands directly. However, you can also access the
GRT Scripting Library functions and global functions and
objects. To see the available commands type
“?
”.
Some OS-specific commands are also available. For instance, under Windows you can clear the screen by typing cls. Unlike most shells, you can cut and paste text to and from the shell window.
Working from the command line is described in detail in Section 31.3, “Using the GRT Shell”.
The Snippets
tab functions as a scratch pad
for saving code snippets. This makes it easy to reuse code and
does away with the need to retype it at the command line.
If you have opened script files as described in
Section 31.2.1.1.1, “Windows File Menu”, there may be any number of tabs
to the right of the Snippets
tab. These tabs
will be labeled with the names of the script files. As with the
Snippets
tab you can cut and paste to or from
any of the tabs. This gives you the opportunity to test code
from the command line.
The Globals Tree
is found on the right side
of the screen and is made up of three tabs,
Values
, Structs
, and
Modules
.
If you are running MySQL Migration Toolkit, find a
migration
object beneath the
root
object. Both applications show the
rdbmsMgmt
object.
When the Values
tab is selected right
clicking an object in the Globals Tree panel opens a pop-up
menu with the options:
Refresh
Remove Object
Display Type Info
Display Object Values
Display Object RefCount
With the exception of Section 31.2.1.2, “The View Menu”. You may remove any object
except the root
object.
Note this pop-up menu only shows under Windows.
A struct
is a user-defined data type formed
by combining primitive data types. This tab shows the
definitions of the structs used by the objects in the
Values
tab and the modules in the
Modules
tab.
When the Structs
tab is selected right
clicking a structure in the list opens a pop-up menu with the
options:
Order by Name
Order by Hierarchy
Order by Package
Note this pop-up menu only shows under Windows.
The default view for this tab is by package, a grouping of
elements by functionality. Double-click a package to show
related structures. Under db.mgmt
, for
example, you should see elements you are already familiar with
from the user interface, Connection
,
Driver
, and so forth. If an element can be
further decomposed, an arrow will show on it's left.
Double-click the item to reveal its constituent elements.
If you switch to the hierarchical view you'll find the
db.mgmt.driver
object under the
GRT Object
since this is the parent object
from which it is derived.
Ordering by name simply shows all the different objects arranged alphabetically.
A module can be either a Python or Lua script or a Java class
file. Information about modules appears in the window below
the module tree. For example, go to the
Modules
tab and click on the
ReverseEngineeringGeneric
module. Double
click a module and you will see its methods.
Double clicking a method name will copy it into the GRT shell window. You will see how useful this can be in Section 31.3, “Using the GRT Shell”.
There are three built-in Lua modules that assist working from the GRT shell:
grtV
– for accessing any
object/variable in the Values
tab
grtS
– for viewing the structs
defined in the Structures
tab
grtM
– for accessing any object in
the Modules
tab
All items in all the tabs are accessible from the GRT shell.
The script example below uses the getGlobal
method of the grtV
object to return a list of
databases and then iterates through this list.
dbs = grtV.getGlobal("/rdbmsMgmt/rdbms") for i = 1, grtV.getn(dbs) do print(dbs[i].name) end
The getGlobal
method returns the object found
at the path parameter passed to it. In this case, the object is a
list that is traversed using a for
loop
controlled by the getn
method which returns the
number of elements in the database list.
Running this for
loop outputs the names of the
database formats supported by the MySQL Migration Toolkit:
"Oracle" "Mysql" "MaxDB" "GenericJdbc" "Mssql" "Access"
To discover all the methods available for a specific object, type
the object name preceded by a “?
”.
For example typing ?grtV shows:
GRT Value Management Library - grtV ----------------------------------- A library that contains functions to work with GRT values. clearList child diffMake diffApply duplicate fromXml getContentType getKey getListItemByObjName getListRefValueByObjName getn getGlobal insert load lookupAdd lookupId newDict newList newObj remove save setContentType setGlobal toLua toXml typeOf Type 'help grtV.<command>' to get help on a specific command.
This capability is currently only available under Windows.
In addition to using the GRT shell from within the
MySQL Migration Toolkit, you can invoke it directly from the command
line. If the location of the MySQL GUI Tools is not included in the
PATH
variable, navigate to the installation
directory and find the grtsh.exe
file.
Execute this file by typing:
C:\> grtsh -?
Do this and you should see the following listing:
Usage: C:\Program Files\MySQL\MySQL Tools for 5.0\grtsh.exe [-classpath path] » [-modulepath path] [-jvm library] [-d path] [-listen port] [-verbose] [-x] [luafile] C:\Program Files\MySQL\MySQL Tools for 5.0\grtsh.exe -j structsfile outputdir C:\Program Files\MySQL\MySQL Tools for 5.0\grtsh.exe -p structsfile outputdir -lua ......... Use the Lua shell (default). -py .......... Use the Python shell. -classpath ... Sets the java classpath to the given value. -modulepath .. Sets the location of the GRT module directory. -jvm ......... The java virtual machine library to use (with absolute path). -basedir ..... Path to the data files location. -d path ...... Modules directory -x ........... Exits the shell after running the specified file luafile ...... File that is run at startup. -listen port . Runs in 'remote agent' mode on the given port number. -verbose ..... Prints detailed startup information. -j ........... Generates Java classes from the given structs file. -p ........... Generates PHP classes from the given structs file. -D var=value . Sets a global shell variable to the given value. Environment variables: GRT_MODULE_PATH Equivalent to -modulepath, must point to the directory where the grtsh binary resides
The default shell is the Lua
shell and is
indicated by the / >
prompt. Using the
-py
option opens a Python shell, indicated by the
/>>>
prompt.
If you wish to set the classpath for Java classes use the
classpath
option. You may also change the Java
Virtual Machine (JVM) by using the jvm
option
with the absolute path to the JVM you wish to use.
The modulepath
option sets the location of the
dll
files used with the GRT shell. These
files are located in the same directory as the
grtsh.exe
file. You can also set this
directory by defining the environment variable,
GRT_MODULE_PATH
.
The location of any data files you wish to use may be set using
the basedir
option.
To see the various modules that are loaded at startup use the
verbose
option. The java modules are stored in
the java\com\mysql\grt\modules
directory
immediately below the installation directory and the
Lua
modules in the lua
directory. Currently, importing Python modules is not supported.
To include modules other than the default modules, use the
d
option with a path.
It is also possible to use the GRT shell to convert XML files to
Java or PHP class files, by opening the shell using the
j
or the p
option and specifying
the XML source file and the destination directory.
Use the listen
option with a port number to run
the GRT shell as a service that can be accessed from a remote
location.
Perhaps most importantly, you can pass a Lua
script to the shell on startup. This allows you to perform tasks
using a script file without even opening the MySQL Migration Toolkit.
This is an especially useful feature if you need to migrate the
same database a number of times or you want to customize a
migration. You can easily create a Lua
script
by clicking the
when migrating using the graphical interface. For information on
creating a Lua script, see
Section 27.17, “The Summary Screen”. A Lua
migration script is examined in detail in
Chapter 28, Scripted Migration.
Passing a Lua
file to the shell is usually
invoked using the x
option so that the shell
closes after the script has executed.
The appearance of the GRT shell run from the command line is identical to its appearance when run from within the MySQL Migration Toolkit. All the commands and options described in Section 31.3, “Using the GRT Shell” are available when the GRT shell is invoked from the command line.