Persistent Parameter Storage

The geosettings META file in the Geosoft ini directory contains global default settings for use throughout the Oasis montaj environment. This is the type of parameter set using the “Oasis montajSettings” menu item (the SETTINGS GX) or the Advanced Settings (the ADVSETTINGS GX). To set a parameter in the geosettings META file, examine the following example:

GlobalSet_SYS("MYGROUP.MYPARAM", “Example”);

This command sets the system parameter “MYPARAM” in the group “[MYGROUP]” to the value “Example”. Once all values are set, it is necessary to use the following command to save the changes to the actual file:

WriteGlobal_SYS("");
Stored values may be retrieved in the following manner:
 
if (iGlobal_SYS("MYGROUP.MYPARAM",sTemp) == 0) {
            // Do something...
}

For more information on storing and retrieving global parameters, see the SYS.GXH header file.

Each Oasis montaj project has a designated area for storing program information called the parameter block. Data stored in this area is unique to the project — it cannot be shared with other projects directly.

When you run a GX, typically you will use functions, such as SetInfoSYS_DGW or GetInfoSYS_DGW to set parameters in dialog boxes and to retrieve them for processing. The values of these parameters are saved in the workspace for future use.

Saving parameters within the workspace gives you flexibility when running GX processes using Geosoft Scripts. 

The SetInfoSYS_DGW or GetInfoSYS_DGW functions transfer values between the workspace parameter block and the dialog. Without these functions, the transfer would require two steps. The following two lines:

GetString_SYS(“MYGX”, “PARAM”, sBuff);    // --- retrieve from parameter block
SetInfo_DGW(Diag, _MYFORM_0, DGW_TEXT, sBuff);  // --- set in dialog

are replaced by...

SetInfoSYS_DGW(Diag, _MYFORM_0, DGW_TEXT, “MYGX”, “PARAM”);

Perusal of GX code reveals that SetInfoSYS_DGW (and by extension GetInfoSYS_DGW), is used mainly for passing four different types of information: real, integer and string variables, read-only text, file paths, and list values.

Most commonly, parameters are numeric or text variables. Parameters are always stored as text strings, even if they are later interpreted as real or int values using the GetReal_SYS and GetInt_SYS functions. The source line would look like:

SetInfoSYS_DGW(Diag, _MYFORM_0, DGW_TEXT, “MYGX”, “PARAM”);

while the corresponding lines in the resource (GRC) file, for real, int and string variables, could be:

EDIT ,,,30,"A Real value",,REAL
EDIT ,,,30,"An Int value",,INT
EDIT ,,,30,"A String value"

The “DGW_TEXT” parameter indicates that the parameter is to be interpreted as a text string when it is passed back and forth between the parameter block and the dialog. In the resource file the “REAL” and “INT” parameters ensure that the value is correctly interpreted and validated by type.

EDIT resources may be used to print read-only information to a greyed field in the dialog, such as a statistical value, or a channel name. Values are passed into the dialog using SetInfoSYS_DGW, or SetInfo_DGW, but there is no corresponding GetInfoSYS_DGW or GetInfo_DGW call:

SetInfo_DGW(Diag, _MYFORM_0, DGW_TEXT, sChan);

while the corresponding line in the resource file could be:

EDIT ,,,30,"Current Channel",N

File paths

The “DGW_FILEPATH” argument is used when working with file names. Even though just the local name of the file is displayed in the dialog field, the full path, including disk and directories, is passed back and forth. The source code could be:

SetInfoSYS_DGW(Diag, _MYFORM_0, DGW_FILEPATH, “MYGX”, “FILENAME”);

The resource lines could be either of the following:

FEDIT,,,40,"Create a New File",R,NEW,,,*.dat
FEDIT,,,40,"Open an Old File",R,OLD,,,*.dat

List values

Individual values from lists of items are passed as text strings, exactly as in the “Real, Int and String Variables” section above. Therefore the “DGW_TEXT” parameter is used:

SetInfoSYS_DGW(Diag, _MYFORM_0, DGW_TEXT, “MYGX”, “SIZES”);

The corresponding lines in the resource file, along with the list items, could be:

LEDIT,,,20,"Sizes",R,FORCE,"Large",SIZE
 
RESOURCE,LIST,SIZE
ITEM, Small
ITEM, Medium
ITEM, Large

List alias values

Often, lists items have two parts, the value (the name which appears to the user), and the alias (which we wish to work with). An example is a choice of “yes” or “no”, where the item “yes” could have as its alias the number “1”. To the programmer, it is the alias that is useful. The “DGW_LISTALIAS” argument ensures that the list alias is passed back and forth to the dialog, even though the list value is seen by the user (If you wish the value instead, use the “DGW_TEXT” option ). The following is an example using list aliases:

SetInfoSYS_DGW(Diag, _MYFORM_0, DGW_LISTALIAS, "MYGX", "LEGEND");

The corresponding lines in the resource file, along with the list items, could be:

LEDIT,,,20,"Plot Legend?",R,FORCE,"Yes",YN
 
RESOURCE,LIST,YN
ITEM,"Yes"         ,1
ITEM,"No"          ,0

Colour values

Before v5.0.7, colour values were specified using the LEDIT component and list mappings between names like “Dark Red” and list values “R64”. This cumbersome method has now been superseded by the CEDIT resource. In the GRC file, you would replace the old combination of LEDIT and LIST resource:

LEDIT,,,20,"Colours",R,FORCE,"Black",COLOURS
 
RESOURCE,LIST,COLOURS
ITEM,"Black"         ,K
ITEM,"Dark Red"      ,R64
ITEM,"Green"         ,G
ITEM,"Blue"          ,B

with the new CEDIT resource the old “COLOURS” LIST is no longer necessary:

CEDIT,,,20, "Colours","K"

In the GXC code, the CEDIT resource is accessed using the “DGW_TEXT” option, since it works directly with the colour string. When updating an older GXC file which previously used the LEDIT resource for specifying colours, you would replace:

SetInfoSYS_DGW(Diag, _MYFORM_0, DGW_LISTALIAS, "MYGX", "COLOURPARM");

with

SetInfoSYS_DGW(Diag, _MYFORM_0, DGW_TEXT, "MYGX", "COLOURPARM");

No other GXC code need be altered to make use of the CEDIT resource.

Parameter Storage in Oasis montaj objects

A special object, call the “REG” is used to store data within an individual database line, database channel, map or map view. An example is measurement units (such as “m” for meters), which are unique to a particular channel and which are stored within the channel REG. The following example illustrates how the channel REG is obtained and how parameter information is exchanged with it:

// --- Create (an empty) REG object ---
ChReg = Create_REG(128);

// --- Get the channel symbol, and the channel parameter data ---
Ch = FindSymb_DB(Data,sCh,DB_SYMB_CHAN);
GetRegSymb_DB(Data, Ch, ChReg);

// --- Get values from the REG ---                
GetInt_REG(ChReg,"INTPARAM", iVal);
GetReal_REG(ChReg,"REALPARAM", rVal);
Get_REG(ChReg, "STRINGPARAM", sVal, sizeof(sVal));

// --- Use values...
.
.
.

// --- Set values back into the REG ---
SetInt_REG(ChReg,"INTPARAM", iVal);
SetReal_REG(ChReg,"REALPARAM", rVal);
Set_REG(ChReg, "STRINGPARAM", sVal);

// --- Set the REG data back into the channel ---
SetRegSymb_DB(Data, Ch, ChReg);

// --- Destroy the REG object ---
Destroy_REG(ChReg);

Note that the REG object is created, then filled with values from the channel using the GetRegSymb_DB function. If the REG object is altered, the new settings must be loaded back into the channel using SetRegSymb_DB for the changes to take effect in the channel itself. Finally, the REG must be destroyed.

The line REG is accessed in the same way as the channel REG. A new REG object is created, then filled, and must be destroyed in the end. It is accessed by using a line symbol:

GetRegSymb_DB(Data, Line, LineReg); // Get REG from a line symbol
SetRegSymb_DB(Data, Line, LineReg); // Set REG to a line symbol

Access to other objects’ REGs is handled differently. For a MAP or MVIEW object, a handle to the object’s own REG is returned to the user, and the user works directly with the object’s REG. No Create or Destroy is performed, and no “SetREG_MAP” (for example) function is required:

// --- Get the handle to the map REG ---
MapReg = GetREG_MAP(Map);

// --- Set a value in the map REG ---
Set_REG(MapReg, "MAP.MAPPARAM", sVal);

The REG in a map’s view is accessed using the GetREG_MVIEW function.

Data string values obtained from a REG may be loaded to, and retrieved from a dialog using the SetInfo_DGW and GetInfo_DGW commands. (When using REG-derived data in dialogs, it is most practical to work with all data, including real and integer variables, as strings using the Get_REG and Set_REG functions.) Alternatively, the REG settings can be added to the workspace parameter block using the SetREG_SYS function, so that the SetInfoSYS_DGW function can be used, as in the following example:

GetRegSymb_DB(Data, Ch, ChReg);
SetREG_SYS(ChReg);

// --- REG parameters are now available as SYS parameters ---
SetInfoSYS_DGW(Diag, _MYFORM_0, DGW_TEXT, “MAP”, “MAPPARAM”);
.
.
.

Note that the REG parameters should be stored in the form “GROUP.PARAM” so that both the group and parameter values are defined in the system parameter block when SetREG_SYS is called.