The GX Developer environment provides APIs for accessing Geosoft technologies from other programming languages, which allows you to extend the platform for other applications. The following languages are explicitly supported:

'C' style API which can be accessed by any language which supports the C calling convention
C# .NET API which can be used by any of Microsoft's .Net languages
C++ API in 32 bit or 64 bit which can be used by external applications
Python API which can be used from standalone Python 3 scripts (both 32-bit and 64-bit).

Functions exported from Windows DLLs can be called from within GXs. Functions exported from Windows .NET DLLs can be called directly from a menu item.

External standalone applications can use the Geosoft redistributables to access the free and public parts of the APIs or can leverage a licensed installation, to integrate Geosoft functionality into your own application or other software packages. For more information on how to access the Geosoft API from external programs, refer to Part 3: Stand-Alone Programs.

Although the GX API accessed from within GX language is the same as that available from other languages, the GX approach is limited in a number of areas. You may choose to use a more comprehensive development environment to address one or more of the following:

Code reuse - GXC programs are monolithic, all of the code must be contained within a single gxc file, which means that you will have to do lots of copy and paste to reuse code. Then when you change your preferred way of doing things, or would like to make changes to take advantage of new features in the API, you will have to seek out and edit all of those copies of the same thing. With a more advanced language you can develop a library of tools that you reuse in all of your programs.
Functions - GXC programs are also linear, there is no facility for breaking your code into smaller pieces for clarity or reuse.
Debugging - There is simply no comparing the GXC debugger with a full fledged debugger available in the IDE of most modern programming environments. You will be much more productive and less frustrated!
Dialogs - Interactive user interfaces that react to input are awkward or simply not possible within the GRC/GXC environment. By building your user interface in another environment you can have full control over the appearance and functionality of your application.
Development Support - The C++, Python or .Net communities are huge and very collegial. There are many online resources to help you learn general programming topics or the minutiae of your chosen environment.

Using the GX Developer API

The GX Developer API exposes all same functions that are exposed to the GXC language, and operate within the Oasis montaj platform. You should read through and understand many of the topics described in Part 1: GX Language Reference, which covers both the GXC language and how Geosoft configures and works with GXs and extensions. Much of this information will apply to your custom extensions developed in another language.

GX Based DLL Development

In order for your DLL code to interact via a GX all of the functionality must be wrapped in a function which will be called within GXC code. The function must be exported from the DLL using the "C" calling convention in order to be accessible from within GXC. The first parameter in the exported function MUST BE the Geosoft handle, and is the only required parameter. If your function is providing it's own user interface that will typically be all that is passed.

excerpt from callfunc.c

// In this example taken from the callfunc example the user interface 
// is being provided by the GX and all parameters are being passed in.  
// GX_OBJECT_PTR is a void pointer and is defined in geoengine.core.gxlib.h
__declspec(dllexport) 
long __cdecl iSum_CALLFUNC(       // returns sum of two numbers
		GX_OBJECT_PTR pGeo,  // geosoft handle 
 		const long *pl1,     // first number
		const long *pl2)     // second number


// Strings are a special case, you need to pass the length as well
__declspec(dllexport)
long __cdecl iStringFunction(
		GX_OBJECT_PTR pGeo,  // geosoft handle 
		char * myString,
        const long * pmyStringLen)

The exported function will not be visible to your GXC code without being declared either in a GXH file or within the GXC itself. The function declaration does not include the geosoft handle. Note also that the integer pointers expected by the DLL are declared simply as type int within the header. There are no pointers in the GXC language. Strings are a special case. The length of the string must always be passed along with the string.

Callfunc.gxh

//----------------------------------------------------------
// iSum_CALLFUNC    Return the sum of two numbers
[callfunc] // --- this is the name of the DLL (callfunc.dll) ---
int iSum_CALLFUNC( int,      // first number
                   int );    // second number

[MyDLL] // name of DLL containing iStringFunction
int  iStringFunction(	string,
						int); // length of string;

The alternative to declaring the function in a GXH is to declare it within the GXC file. See the iMyFunction example below.

Finally, the last step is to call the function from within a GX.

Error Handling

It is good practice for your DLL function to return a code to the calling GX indicating succesful completion or an error code. For example if the user presses Cancel on your DLL controlled form it would be advantageous to capture that information in the GX so that the GX and any script calling the GX can be halted.

__declspec(dllexport)
long __cdecl iMyFunction(
		GX_OBJECT_PTR pGeo){
	const GX_RESULT_OK = 0;
	const GX_RESULT_CANCEL = 1;
	const GX_RESULT_ERROR = -1;
	
	if ( .. something that returns an error...) {
		return GX_RESULT_ERROR;
	} else if ( .. user pressed cancel...) {
		return GX_RESULT_CANCEL;
	} else {
		return GX_RESULT_OK;
	}	
}

MyFunction.gxc

//=================================================
NAME              ="MyFunction"
VERSION           ="v1.00  "
DESCRIPTION       ="Does something wonderful, I'm sure
"
//===========================================================================
#include <all.gxh>
[MyDLL] int iMyFunction();
//===========================================================================
{	
	switch  (iMyFunction()) {
		case -1:
			Abort_SYS();
		case 1:
			Cancel_SYS();
	}
}

NOTE: The actual effect of Cancel_SYS is to cause the GX to end without logging it in the event log or displaying an error message, which is sufficient in an interactive sense. However when the user Cancels the execution of a GX during a script they generally want the script to end as well. This can be accomplished by beginning the script with the "CANCEL_AS_ERROR ON" command as the first item. Terminating your GX with Abort_SYS will always terminate a script and show an error message.

Installing your custom DLL

Third party applications are usually placed in the <geosoft>\bin or the <geosoft>\resourcefiles\bin directory but can be placed in a different location if desired. A registry setting is required to locate each DLL that is not placed in a \bin directory. Add the following registry key to the system running the application:

HKEY_LOCAL_MACHINE\SOFTWARE\Geosoft\{KEY}\3rdPartyDLLs.

The {KEY} is the version of oasis montaj that will be running. In the standard Oasis montaj version this key is “Oasis montaj” and for the Viewer it is “Oasis montaj Viewer”. However, some special versions of montaj for our CS customers do have unique key names. Note that in this case version doesn't refer to the version number, but rather the name of the product.

Once this key is created, populate it with the names of each DLL needing to be redirected to a different location. For example, if a custom GX called a method in my geocustom.dll file installed in c:\program files\custom, I would create a new string in the registry:

Name: geocustom.dll

Data: <Program Files>\custom\geocustom.dll

The first time your GX is run, montaj will try to load the DLL from <geosoft>\bin first. If it is not found there, it will check this registry setting for any matches of the DLL name and load it from the specified path instead. Until montaj has been restarted, the DLL will always be loaded from the alternate location.

GX API for .NET

The GX API can by used to create .NET DLLs that can be called directly from a Geosoft menu.

Links to the reference documentation for the GX .Net API can be found in the GX API Reference page.

Connecting your code to the Geosoft environment

There are several different ways of connecting your code to the Geosoft environment of your choice:

GX based - In this scenario, which is the simplest, you create a GX which calls an exported function or functions in your DLL. That function receives a "handle" to the Geosoft object which is necessary to interact with the API functions. Upon completion the DLL function returns control to the GX. In this scenario your function behaves similarly to an API function, in that it's lifespan is limited to the GX execution.
.NET based - A function exported from a .NET assembly can be called directly from a menu item without wrapping it in a GX, but is otherwise the same as above.
External application - A standalone program can be built which creates a separate instance of the Geosoft executable in memory and accesses databases or maps. Some parts of the API are not available using this method. Furthermore the external application can not interact with a running instance of the Geosoft program. However, a GX can be created that will prepare your Geosoft project so that it can be opened and processed by the external application, which can be run using the GX iShellExecute_SYS() method. The Python package also allows you to create fully 64-bit external applications that access the GX API.
GeoXTool application - This is a DLL based program that becomes part of the running instance of Geosoft. A GeoXTool is able to interact with the program and 'react' to user actions such as changing line, selecting data or zooming/ panning a map. This type of tool is most difficult to create but very powerful.

GeoXTool Application

A GeoXTool is a DLL based application that integrates itself into the environment. Once launched from a GX the process stays resident and responds to events within the environment. If the tool has a user interface, the exposed form will become part of the sidebar, or will be displayed as stay-on-top if undocked. Currently the C and GXNET APIs may be used to create a GeoXTOOL, and examples are provided of each.

Several steps are necessary to create a GeoXTool.

Create an exported function that initializes the GeoXTool.
Create an object that IS the GeoXTool. This object can respond to the events in the GeoXTool Interface and can trigger events in the GeoXTool API via callbacks. Typically it will display a form that gets parented (ie embedded into) the sidebar. Once initialized the interface method callbacks will be called whenever appropriate. The API callback functions can be triggered by user actions or within the interface methods.
Create a GX to launch the GeoXTool.

Creating a GeoXTool

For C developers all of the function prototypes are provided in "geoxtool.h". All of the functions in the API and Interface need to be separately created and assigned to their respective callbacks during the creation of the tool. The GeoXTool MFC example is a complete example.

from MyGeoXTool.cpp

extern "C" __declspec(dllexport) void * _cdecl
hCreate_GEOXTOOL(void *hGEO,                    // Geosoft Handle
                 HWND hParent,                  // Parent Window
                 long lMETA,                    // META object to get info from
                 HWND *phWND,                   // Filled with new HWND of your tool
           const GEOXTOOL_API       *pAPI,      // API Functions
                 GEOXTOOL_INTERFACE *pFuncs,    // Filled with function pointers
                 char *pcToolName,              // Buffer for the name of the tool
                 long lToolNameSize)            // Size of Tool Name Buffer

For .Net developers the process is somewhat simpler. By creating a control descending from ToolControl most of the plumbing is already taken care of. ToolControl is implemented in the geoengine.core.gxnetx assembly

GeoXTool API

This object can respond to the following events in the environment:

1. General Info
2. ChangeArea
3. ChangeLocation
4. ChangeProjection

Browser not supported