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.

Python

Stand-alone Python scripts are those that can be run directly from the Python interpreter.  Such a script will create a Geosoft context by calling geosoft.gxpy.gx.GCpy(), followed by further us of the geosoft.gxpy and geosoft.gxapi module interfaces. As an example, following is a sample script that will add a value to a channel of a database (https://github.com/GeosoftInc/gxpy/blob/master/examples/stand-alone/chanadd.py):

"""
Add a constant value to a channel on all selected lines.

This is a sample Python program that illustrates how to connect to the GX
developer environment from a stand-alone program.

Follwoing are the basic steps:

   1. Get (create) a GX Object handle.
   2. Collect command-line parameters
   3. Open the database
   4. Process the data
"""
import os
import sys
import argparse as argp
import geosoft.gxpy as gxpy

def rungx():
    raise Exception("This is not an extension.  Please use a python interpreter.")

def process_database(db, channel_name, add_value):
    """
    Process all selected lines in a database by adding a constant
    value to a channel. The data is processed in-place.
    """

    # work through the data a line at a time - get a list of selected lines
    print('Processing selected lines...')
    lines = db.list_lines()

    # for each line, get the data, add a value, return the data to the line
    for l in lines:

        # print to the console to reflect progress
        print('line {}...'.format(str(l)))

        # get the data and determine the dummy to the data type
        data, ch, fid = db.read_line(l, channels=channel_name)
        dummy = gxpy.utility.gx_dummy(data.dtype)

        # make a dummy mask so we can replace dummies after processing
        dMask = gxpy.utility.dummy_mask(data)

        # process - add the value, then replace the dummies
        sum = data + add_value
        sum[dMask] = dummy

        # write the data back to the database
        db.write_channel(l, channel_name, sum, fid)


if __name__ == "__main__":

    gxpy.utility.check_version('9.2')

    # get (create) a GX context
    with gxpy.gx.GXpy() as gxp:  # get the current gx context

        # The GX_GEOSOFT_BIN_PATH Environment variable should contain a path with geodist.dll
        print("GX_GEOSOFT_BIN_PATH: {}".format(os.getenv("GX_GEOSOFT_BIN_PATH")))
        print('Working directory: ' + os.path.abspath(os.curdir))
        print('User: {}'.format(gxp.gid))

        # get command line parameters
        parser = argp.ArgumentParser(description="Add a constant to a Geosoft database channel")
        parser.add_argument("sDB", help="Geosoft database")
        parser.add_argument("sCh", help="channel to process")
        parser.add_argument("-v",
                            "--value",
                            type=float,
                            default=1.0,
                            help="value to add, default is 1.0")
        args = parser.parse_args()

        # echo parameters
        print("\nDatabase = "+args.sDB)
        print("Channel = "+args.sCh)
        print("Value to add = {}\n".format(args.value))

        # open the database
        with gxpy.gdb.Geosoft_gdb.open(args.sDB) as db:

            # process the data
            process_database(db, args.sCh, args.value)

To run this "stand-alone" script from the command-line:

python chanadd.py --help
usage: chanadd.py [-h] [-v VALUE] sDB sCh

Add a constant to a Geosoft database channel

positional arguments:
  sDB                   Geosoft database
  sCh                   channel to process

optional arguments:
  -h, --help            show this help message and exit
  -v VALUE, --value VALUE
                        value to add, default is 1.0


python chanadd.py mydata.gdb dem -v 100

Examples

• Examples in GX API for Python
• C - See C:\Program Files\Geosoft\GX Developer\cpp\examples\c
• C++ - C:\Program Files\Geosoft\GX Developer\cpp\examples\cpp
• C# - See C:\Program Files\Geosoft\GX Developer\gxnet\examples\chanadd