Dialogs and the Project Parameter Block

Owned by serban.marin
Dec 15, 2021
3 min read

Project Parameter Block

Each Oasis montaj project maintains a private registry of name:value pairs that is managed with a set of SYS functions.  This is called the Project Parameter Block.

When you run a GX, typically you will use functions, such as SetInfoSYS_DGW or GetInfoSYS_DGW to set parameters in dialog boxes from the Project Parameter Block, and to move user input back to the Project Parameter Block. In this way the parameters are preserved so that when a dialog is presented a second time the parameters are restored from the last use, which is convenient for users.  This also supports the ability for GX extensions to be included with a script file where parameters can be set using the SETINI command.

Using SetInfoSYS_DGW and GetInfoSYS_DGW

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.

Real, int and string variables

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.

Read-only text

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

CEDIT


Colours in a CEDIT (colour edit) contol are accessed using the “DGW_TEXT” option, since it works with the colour string. 

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