Chapter 31. The Generic Runtime Environment (GRT) Shell

Table of Contents

31.1. Introduction
31.2. Exploring the GRT Shell
31.2.1. Menu Items
31.2.2. The Shell
31.2.3. The Globals Tree Panel
31.3. Using the GRT Shell
31.4. Invoking the GRT Shell From the Command Line

31.1. Introduction

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.

Note

The GRT supports Lua version 5.0. Version 5.1 is not supported.

31.2. Exploring the GRT Shell

To open the GRT shell from within the MySQL Migration Toolkit choose the GRT Environment Shell option under the Tools menu. I

Figure 31.1. The GRT Shell (Windows)

The GRT shell (Windows)

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.

31.2.1. Menu Items

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.

31.2.1.1. The File or Shell Menu

31.2.1.1.1. Windows File Menu

Currently only two of the submenus under the File menu are implemented; Exit, which simply exits the GRT shell, and Open Script. The Open Script 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.

31.2.1.1.2. Linux Shell Menu

Under Linux the Shell menu shows menu items for closing the shell, refreshing the objects listed in the Global tree or saving the object tree.

The Save Tree ... menu option saves an XML file of all the data types and classes shown in the three tabs of the Objects Tree.

Under Linux there is no menu option to open a script.

31.2.1.2. The View Menu

31.2.1.2.1. The View Menu: Windows

The Refresh option of the View menu refreshes the view of the objects shown in the object tree tabs on the right.

The Display Type Info and Display Object Values menu items toggle the view of the objects in the Values tab on the right. When checked, Display Type Info shows the data type of objects and Display Object Values shows their value.

The Display Object Refcount shows the current number of references to specific objects.

31.2.1.2.2. The View Menu: Linux

The View menu has only one element, Structure Only and it is not yet activated.

31.2.1.3. Mac OS X Menu

Under Mac OS X there are only two menu options, Reload and Reload Selected. Reload reloads all the objects in the Object Tree panel and is equivalent to the Windows View, Refresh option. The Reload Selected option only reloads the selected object.

31.2.2. The Shell

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.

31.2.3. The Globals Tree Panel

The Globals Tree is found on the right side of the screen and is made up of three tabs, Values, Structs, and Modules.

31.2.3.1. The Values Tab

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 Remove Object, these options are the same as those shown in Section 31.2.1.2, “The View Menu”. You may remove any object except the root object.

Note

Note this pop-up menu only shows under Windows.

31.2.3.2. The Struct Tab

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

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.

31.2.3.3. The Modules Tab

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”.

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.

31.4. Invoking the GRT Shell From the Command Line

Note

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 Generate Migration Script 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.