Example

To illustrate the process of compiling, running and debugging a GX from Oasis montaj, we will use a simple "Hello" example.  The GX will ask  for your name, then say hello. Create a working folder and cut/paste the following to two new files:

RESOURCE,FORM,HELLO,"Who are you?",-1
EDIT,,,64,"Your name please",,,,,
EBUT,&Greetings,0
EBUT,&Cancel,-1,cancel

NAME = "Just saying hello"
DESCRIPTION = "Sample program to demonstrate simple compile process."
RESOURCE = "hello.gr"
#include "hello.grh"
#include <all.gxh>

// local variables
string(256) sName;
DGW   Diag;
{
   // Create the Dialogue
   Diag = Create_DGW("HELLO");

   // display the dialog, and if user clicked "Greetings", say hello...
   if (iRunDialogue_DGW(Diag) == 0) 
   {
      // get the name and display it
      GetInfo_DGW(Diag, _HELLO_0, DGW_TEXT, sName);
      DisplayMessage_SYS("Hello there",sName);
   }
}

Compiling a GX

To run a GX on a specific version of Oasis montaj, you will need to compile that GX's source code files using that particular Oasis montaj version.

Prerequisites: 

1. Install Oasis montaj: https://my.seequent.com/products
2. Download and unzip the GX Developer GXC zip: https://github.com/GeosoftInc/gxc/releases and configure include variable (see below)

The GX source code files are compiled using grc.exe and gxc.exe. These executables are installed with Oasis montaj in the bin folder. Take note of the full path to these executables. For example C:\Program Files\Geosoft\Desktop Applications\bin

Virtually all gxc scripts will have a dependency on GX Developer GXC header file. After you have unzipped the GX Developer package, take note of the include folder path. For example C:\workspace\gxc\include. The compiler executables need to be pointed to this include folder and this can be done by setting the include environment variable. This can be done in multiple ways, but this example shows how to set it during the lifetime of a command prompt window.

set include=C:\workspace\gxc\include

If the include environment variable is not correctly set, we expect an error like "can't find include file all.gxh" when running gxc.exe

Step 1 - compile the resource file (hello.grc):

Open a command prompt window and check that the environment variables are set as required. Set the current directory to where you have located hello.grc and hello.gxc, which for the example bellow is located in C:\workspace

cd C:\workspace
"C:\Program Files\Geosoft\Desktop Applications\bin\grc.exe" hello

This will create two files, hello.gr and hello.grh.  The hello.gr file is a binary file that describes the dialog and will be build into the final compiled GX.  The hello.grh is a header file that defines numbered labels as DGW_OBJ types that are used in the GXC code to interact with the dialog.  In this case we are only interested in the first item, which is the name the user enters, and this is identified as "_HELLO_0".  Note that dialog items are numbered in the order encountered in the GRH file. See GRC Resources and Dialogs for more information on working with dialogs.

Step 2 - compile the GXC source file (hello.gxc):

"C:\Program Files\Geosoft\Desktop Applications\bin\gxc.exe" hello

This step creates a compiled final GX named hello.gx.  This gx can be run directly from Oasis montaj.

Step 3 - Run the GX to test that it works:

Open an existing or new project in Oasis montaj, then select  "Settings / Run a Gx...", and browse to your GX:

Clicking [OK] will run the GX.  The first time a non-Geosoft GX is run you will be prompted to confirm that you want to run this GX.  This is a security measure that helps protects you from malicious GX's that may be run from some other source.  You should only run GXs in which you have convidence of the source.  Once you have accepted this GX as safe, you will not be promted again, though each time the GX is recompiled you will need to re-verify its safety.

Environment variables

As mentioned above, there are many ways of setting up environment variables in windows. As such here some additional notes

1. Users may want to set the include variable at the operating system level to avoid setting it up
2. Users may want to add the Oasis montaj bin folder to the path variable at the operating system level to avoid writing out the full path to the compiler executables

Debugging a GX

The GX Developer debugger is a flexible and useful tool for debugging GXs, and will tremendously speed up the development of more complex GXs.

By enabling the debugger on a GX, the user can step at run-time through the GXC code of the GX.  The user may place break points in the code, and search for strings.   Furthermore, this process gives the user access to the memory stack as well as the ability to modify the stack at run-time.  The illustration below displays a typical GX debugger session.  If you are familiar with other debugging tools you should find the use of this debugger straight forward.

To run the debugger, load the GX Developer Debugger menu.  Once loaded, to enable a debugging session choose "GX Developer Debugger / Enable..." and select the folder that contains your GX and spurce code.  Once enabled, runing a GX from the folder will start-up a debugger session using your source code.

"Settings / Run a GX..."

1 - The menu consists of a single item,Debug.

2 - The Debug options are (F9) to toggle breakpoints on/off, (F5) to continue to the next break point, or (F10) to single step through the code one line at a time.  These shortcut keys are the same as the Visual studio keys. 

3 – The Gutter displays the line numbers, breakpoints and the current line of execution. 

4 – The user can set/unset Breakpoints at the current cursor position by hitting F9.  A brown circle identifies the breakpoints in the gutter.  The debugger allows you to set breakpoint on any line in any of the files preloaded into the file list. Many lines do not actually contain any execution code and the debugger will skip over break points in these lines even if you set a breakpoint on them. Problems also arise on multi-line statements where the breakpoint will only be caught if set on the last line of the statement..

5 – A yellow arrow indicates the Current line of execution. If no such symbol exists in the file you are currently viewing, the current position of the GX execution is elsewhere in one of the other files in the File List.

6 – The Watch Window contains four tabs where you can add watches to variables in the debugged GX’s. Add a watch by typing the variable’s name in the Name column. If a variable is not in the current scope, it won’t be displayed. The size of strings and arrays are indicated in parentheses following the variable name. The second column (Value) contains the values of the watch variables. In the case of string, int and real variables you will be able to edit the values before stepping to the next line of execution or continuing the GX run.

7 – All the files found underneath the directory you specified in the DBGENABLE GX will be displayed in the File list. You can view the source code of any file in the list by double clicking on it.

8 – The Breakpoint list shows all the breakpoints active in the session. Double clicking on these will take you to the location in the source code.

9 – The Source Code displays the colorized source code of one of the files in you File List.  The colourized scheme follows the Visual Studio standards. 

Notes