Developing a GX

To develop a new GX you will create an optional resource file (GRC) with extension .grc, and a program code file (GXC) with extension .gxc. Both the resource file and code file are text files and you can use any text editor to create and work with these files.

The resource file (.grc) defines the layout of a dialog that can be used to collect user parameters and other information that is required at the time your GX runs. The resource file is only required if your GX requires user input and interaction and it uses the DGW class to create a user dialog.

In most cases there is an existing Geosoft GX that does almost what you need, or which can be used as a model to develop a new GX. All Geosoft GX source code is available on GitHub at https://github.com/GeosoftInc/gxc/tree/master/examples. Once you find a GX that you want to use as a model, copy the gxh and gxc files to a new working folder and rename these to something unique for your project.

GX Compiler Configuration

Go to https://github.com/GeosoftInc/gxc/releases, choose a release and follow the configuration instructions.

Sections on this page

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:

hello.grc - resource definition file

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

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

hello.gxc - this is the code that does the work

//===========================================================================
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\

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

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.

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

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

There are dividers between the different parts of the debugger window that allow the resizing of the parts to individual preference. The whole window can also be resized. The positions will be remembered for the duration of the debugging session.

The watch windows are not the only way to inspect variable values. If you hover over a variable in the source code, a tool tip will pop up displaying its value.

When stepping (F10) to the next line of execution, and the GX is terminated, the debugger will retain the stepping mode. This means as soon as on of the GX’s in the file list is run the debugger will pop up and display the current line of execution at the first executing line in that file. Another handy feature of stepping is that you may ‘step into’ GX’s in your file list by hitting F10 on a iRunGX_SYS call to such a GX.

Currently there is no checking for consistency between the GX binaries and the source code. If an outdated binary is used with newer source code, the breakpoints and source window may display wrong information and can cause confusing situations. For example, a blank line may be the current line of execution or none of your breakpoints will stop the execution of the GX. In this eventuality stop the process, reload the GX to debug, and run it again.

Dummy values will always be shown as an asterix character ‘*’. Similarly, you can change a numeric value of a variable to a dummy by typing an asterix in the Values column.

A specific element in the array may be indicated using square braces containing the 0-based index into the array. When you attempt to view an array by typing its name in the Name column it will show the first element (VariableName[0]) in it. The alternative is to hover over the variable in the source code window; the tool tip will display the entire array.

Browser not supported