Example

To illustrate the process of compiling, running and debugging a GX fro 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 ( (https://github.com/GeosoftInc/gxc/tree/master/examples/hello):

//-----------------------------------------------------------------------------
// Simple dialog example

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

The GXC compilers and tools are available in a zip file on GitHub: https://github.com/GeosoftInc/gxc/tree/master/tools.

GRC resource files are compiled using the GRC resource compiler grc.exe and GXC source code is compiled using the GXC source code compiler gxc.exe.  The grc.exe and gxc.exe need to be available in your system path, and the folder that contains the GX API header files (.gxh) must to be included in your INCLUDE environment variable. The examples assume you have installed to the folder:

C:\gxc-v9.3\
set include c:\gxc-v9.3\include
path=%path%;c:\gxc-v9.3\tools

Open a command 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 E:\Hello\

e:\Hello\grc 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.

e:\Hello\gxc 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.

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