Variables, Constants and Function Identifiers

Variable Identifiers

All variables used in a GXC program must be declared immediately before the opening brace for the GXC program statements. Variables are declared by specifying a data type followed by a comma-separated list of variable names and a semicolon to end the declaration statement. The GX language supports a simplified selection of variable types - int, real, and string as well as Class handles:

int

The int variable type stores integers, and replaces the short and long types found in normal C. It is equivalent to the 4-byte long type. Int variables may also be declared and accessed as arrays, as in the following examples:

int iVal;
int(4) iNum;
{
   iVal = 2;
   iNum[0] = iVal + 1;
   iNum[1] = 2*iNum[0];
}

Note that array allocations are done with round brackets “(4)”, while access is performed using square brackets “[0]”. As with C variables, indexing begins at 0 and proceeds to one less than the allocated size. Note also that the declaration syntax for arrays is a different from standard C in that the array size is part of the variable type, not the variable name.

real

The real variable type stores floating point numbers, and replaces the float and double types found in normal C. It is equivalent the 8-byte double type. Real variables may be declared and accessed as arrays, as in the following examples:

real rVal, rVal2;
real(4) rNum;
{
    // Note that you MUST include a decimal place when assigning a value to a real variable
	rVal = 2.1; 
	rVal2 = rNum[0];
    rNum[2] = rNum[1];
}

string

The string type is roughly equivalent to the char type in normal C. String variables must be declared with a maximum string length, as in the following examples:

// STR_DB_SYMBOL and GS_MAX_PATH are constants. They are defined in geosoft.gxh.
string(STR_DB_SYMBOL)  sInCh,sChan;
string(80) sTextLine;
string(GS_MAX_PATH)   sFile,sData;

Unlike the int and real variables, string variables may not be accessed by element indices; for example the following is illegal:

sFile[6] = 'a';   // illegal statement

Instead, the STR library functions must be used to manipulate strings.

Class handles

Instances of Geosoft object classes that are defined in the GX API. To use a class you must declare a class variable as in the following examples:

DB  hData;        // hData is a handle to a DB class that deals with databases.
DGW hDialog;      // hDialog is a handle to a DGW class that deals with resource dialogs.
LST hChannelList; //  hChannelList is a handle to an LST class that deals with lists.

Constants

Constants are tokens that evaluate to a number or a string in your code. Constants can be integers, floating-point numbers or strings enclosed in double quotes.

Integer and floating point constants

Note that if there are any white-space characters following the backslash, other than a newline character, the continuation is not recognised.

Numeric constants are either integer or floating point real numbers, as illustrated in the following example:

int iValue;
real rValue;    
iValue = 1234;      // assigns integer to constant
iValue = 0777;      // assigns integer to constant octal 777 (decimal 511)
ivalue = 0xff;      // assigns integer to constant hex ff (decimal 255)
rValue = 32.1;      // assigns real to a constant
rValue = 3.21e1;    // real constant in exponential notation

Note that numeric constants can only be used in context with the implied constant type. The implied type of a constant is integer unless there is a decimal place or the constant is in exponential format. You can use a type cast to change the type of a constant if required (see Casting Types).

String Constants

A string constant is a sequence of characters enclosed in double quotes. Strings are always terminated by an implied null character. In GXC, you must use the STR methods defined in str.gxh to work with strings. For example, the Strcpy_STR function will copy a string constant to a string variable:

String(16) sName;
Strcpy_STR(sName,"Bill");   // copies the constant "Bill" to string variable sName

Special characters in a string can be defined using escape sequences. An escape sequence consists of a backslash character (\) followed by one or more characters. The following table defines the ANSI escape sequences supported in GXC:

Escape Sequence	Represents
\a	Bell
\b	Backspace
\f	Form feed
\n	New line
\r	Carriage return
\t	Horizontal tab
\v	Vertical tab
\”	Double quotation
\\	Backslash
\ooo	ASCII character in octal
\xhhh	ASCII character in hexadecimal notation

If a backslash character precedes a character not specified in the table, The undefined character is interpreted as the character itself. If a backslash appears as the last character in a line (immediately before a new line character), the next line is considered a continuation of the current line. This can be useful for defining long string constants.

Defining Constants

Constants that are used repeatedly in your GX source code can be defined once using a #define statement to establish a token name to represent the constant. The #define statement must start in column 1 of the source line, it must be the only statement on the line, and it must precede the first use of the constant token. It is a common convention to use all upper-case characters for the defined token, in this case TWOPI. All occurrences of TWOPI in the source code that follow this line will be replaced by the constant “6.2831853”:

#define TWOPI  6.2831853
rCirc = TWOPI * rRadius;  // seen as rCirc = 6.2831853 * rRadius

The GX Programming Language predefines many constant values in the GXH header files, both in the geosoft.gxh file and in the individual function library header files. For example, the integer and real dummy values are defined in geosoft.gxh as follows:

#define iDUMMY -2147483647
#define rDUMMY -1.0E32

Note that #define statement lines cannot contain comments.

You can use the backslash character before the end of a line to define a long string constant that continues onto the next line:

#define LONG_STR "Long strings can be broken into two or more \
pieces."

Note that if there are any white-space characters following the backslash, other than a newline character, the continuation is not recognised.

Function Identifiers

GXs call functions to perform most of the real processing work and to control the Oasis montaj interface. The suite of functions available to the GX programmer is called the GX API, or GX Application Programming Interface. Before calling a function, the function identifier must be declared in a function prototype statement. All Geosoft function prototypes are defined in the GXH files in the GxDev/gxh directory. You can refer to GX Function Libraries for more information on working with GX functions in the GX API.

A function prototype statement is normally contained in a separate GXH file that is included (using the #include directive) in your source code immediately before your variable declarations. Following is the syntax for a function identifier:

[dll_name] return_type function_name(arg_1_type,arg_2_type,…);

dll_name or license type

The name of the DLL that contains the function. Note that functions provided by Geosoft use this field to identify the type of license this function can used under. The valid license types for Geosoft are: “_public”, “_licensed”, “_extended” and their application versions: “_public_app”, “_licensed_app” and “_extended_app”. See the Geosoft License Issues section for more details.

return_type

The function return value type, which can be an int, a real, a class, or void. The type void indicates that the function does not return a value. Note that in C and GXC, you can call a function that returns a type just as you would call a void function.

function_name

The function identifier name that you use to call the function.

arg_#_type

A list of types that correspond to the required argument types. Unlike C, GXC does not support functions with undefined argument lists. The “var” qualifier should precede any arguments that may be modified by the function.

For example, the following prototype defined the function identifier ReadReal_BF in the BF class, which can be used to read a real value from a binary file:

[_public] void   
ReadReal_BF(BF,    // BF handle
            int,   // BF element type, one of GS_? types in Geosoft.gxh
            var real); // real data returned