Stand-Alone Programs

Owned by Copy Space for Confluence
Last updated: Nov 15, 2017 by ian macleod (Deactivated)
4 min read

The GX Developer environment provides APIs for accessing Geosoft technologies from other programming languages so you can create stand-alone programs that can read and/or write Geosoft files, or access Geosoft library functions.  64 bit API's are provided for:

  • 'C' style API which can be accessed by any language which supports the C calling convention
  • .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 scripts (version 3.5 and up).

The same APIs are used as described in Extending Oasis montaj so refer to it as a general introduction to using the APIs. This page just describes what is required to initialize the APIs for external use.

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. See Using the GX API Externally for details on how to redistribute stand-alone programs.

Note that stand-alone programs run in their own memory space and do not have access to the Oasis montaj GUI elements, including GX Developer dialogs, user messages, eDB and eMAP classes, although the formal API includes these methods as it is auto-generated from the GX API. If you call methods that depend on the Oasis montaj user interface, these methods will fail.

Stand-alone programs can be combined with a GX that collects interactive information from a user using the GXC language and then calls your program using the iShellExecute_SYS function.  Note that your program cannot open a database of map that is open in Oasis montaj, so if this is required the GX should close the database or map before running your program, and then re-open the database or map on completion. The only exception is if your program only needs to read a shared database, in which case the database can remain open in Oasis montaj. Attempting to write to an open database will fail.

Page tree

Initialization and User Authentication

In each of the GX API language a context needs to be initialized and maintained while the API is in use. In each case an application and version strings are required. application is a string that describes your application, and version is a string for your version information. In UI applications it is a good idea to pass the optional Windows HWND handle of your application's main window. This will result in a UI based progress bar and will allow a greater subset of the API to function. One can even call other GX API scripts and GXs etc reliably this way and have their UIs display.

Initializing the GX API establishes the credentials of the person running your program. These credentials are required to grant access to various features in the API used by your program.  Although most of the GX API is available to anyone with a Geosoft ID (freely and easily established at https://my.geosoft.com), certain features are restricted to authorized users in order to support licensing restrictions, both with Geosoft and with Geosoft's partners. Attempting to create context with a call to GXContect.create() will trigger the need for your user to be authenticated.  Authentication is managed by Geosoft Connect, which is part of the Geosoft library and part of all installed Geosoft technologies. There are two scenarios to be aware of:

Your program running with installed Geosoft technology:  In most cases, we expect your users will have some version of Geosoft installed, which as a mimimum may simply be the free Geosoft viewer. In this case your user will likely already be authenticated and GXContext.create() will use this authentication such that your user will not be challenged to sign-in. If for some reason we cannot determine the the credentials of your user, they will be challenged to authenticate (sign-in) using their Geosoft ID credentials.  Authenticating, in this case, requires an Internet connection.

Your program running independently: It is also possible to run your program from a system without any existing Geosoft technology.   In this case you will have shipped the Geosoft DLL's to support the GX API calls together with your program.  The first time your program calls GXContext.create(), your user will be challenged to provide their Geosoft ID and password on a sign-in dialog.  Should your user not have a Geosoft ID, they will have the opportunity to register on my.geosoft.com.  Once registered and authenticated, the authentication information is maintained on your user's system and, under normal circumstances, your users will not be challenged again. Note that an Internet connection is required to register a new Geosoft ID, and to authenticate for the first time. Once authentication is established an Internet connection is no longer required as the saved authentication is used each time your user runs your program.

IMPORTANT: Should your users need to use your program without an Internet connection, possibly in the field or while travelling, they must establish their identity on their system before disconnecting from the Internet.  This can be done by simply running your program once when connected to the Internet. This only needs to be done once.

Examples