Back to:
Parameter file handling and parameter editing accounts for a significant amount of the time spent in writing and using geophysical (or any other) software.
The current generation of Lynx's Exploration Archivist Programs standard libraries for editing pages of input parameters, using a "screen definition" within the Program's INI file as a template to determine the layout when the parameters are edited. Actual parameter values are stored in the program's parameter files as ASCII characters.
This system has the following general aims:
Parameter page definitions (previously in the .SCR "screen" files in the older Lynx 3-S MS-DOS system) for each program are included as sections in its INI file. The PrmEdit and LEASys Delphi units combine an extended definition of the old screen file format with the use of the more-or-less standard INI file widely used in MS Windows and adopted as a convenient way of carrying program specific information in LEA programs (see the LEA Application Framework). Compactness and speed of reading and writing are not really big issues, because most parameter (as opposed to data) files contain relatively few individual parameter values and the storage overheads are quite small.
In each application program's INI file, the definitions of the parameter types, along with their descriptions, default values and limits are carried within special "page" sections.
This approach has a number of useful features:
The actual parameters for a program are stored as ASCII strings in a parameter file, which is divided into sections, as for an INI file, each containing a "page" of related parameters. These correspond to the pages that the user sees when using the parameter editor. The pages will usually correspond to logical groups (Pascal record or C struct) of parameters within the program.
The first line in the file is the section [lynx], which identifies the file as being a LEA parameter file. This is followed by the program ident which identifies what program generated it. This section also contains the version ident which determines what the program's version number was when the parameter file was generated. (see Program and Parameter Version Control).Each parameter section has a name, corresponding to the name ident in the corresponding page section of the program INI file (see [page] directives below)
[pagename.nn]
The optional number .nn indicates that the page is one of a
sequence of pages of the same type within the parameter file (multiple pages).
The numbers nn must start at 1 and increment by 1 for each subsequent
instance of the page.
Each parameter is written as a single line of ASCII
characters, (followed by an end-of-line delimiter), eg
[LYNX] program=progname version=1.1 [DISPLAY] 10.0 Some text information [OUTPUT] etc... [END]
[END] indicates the end of the stored parameter values
When parameters are to be converted the program's internal variables, PrmEdit initially reads the parameters as ASCII strings. These are then mapped to the calling program's internal format . On initialisation, PrmEdit creates tables from the page information in an INI file, which define how the ASCII parameters will be translated into the internal form they will have as program variables. For example, text could be converted into internal 'C' null terminated strings or Pascal strings. Numbers can be handled in whatever way is appropriate - numbers written with a decimal point can even be converted to integers internally if desired.
Parameters representing "choices" eg YES/NO, true/false or a selection from a list of alternatives are represented numerically in the parameter file. Although this goes against the grain of the concept "never represent a non numerical argument with a number", it enables the parameter files to be independent of the actual strings in the INI file which present choices to the user. For example, YES/NO could be changed to TRUE/FALSE (or OUI/NON) in the INI file without affecting either parameter files or the program itself. The advantage of this is that INI files can contain setup definitions in different foreign languages, without affecting the behaviour of the program. Within programs, clarity can be maintained by using manifest constants (C) or enumerated variables (Pascal) to represent the choices.
For example, the parameter
> Size _____ |small,medium,large
in the INI file would appear as 0, 1 or 2 , in ASCII, in the corresponding parameter file. Inside a Pascal program the actual parameter could be defined as:-
type Tsize = (small,medium,large); var Vsize: Tsize;
The variable Vsize would always take on the value small, medium or large within the program (with corresponding ordinal values 0,1 or 2), even though the parameter description could be later changed to:
> Grosse _____ |klein,mitte,gross
by a german user.
Saving parameters is the reverse process of loading, ie internal format is converted to string, then the strings are written to the parameter file.
Summary of INI file parameter information:
The LEA application INI file should have a parameters key in the [program] section (which is language dependent) which describes the filter for parameter open/save file dialogues, eg:
[program] input=Input files (*.inp)|*.inp output=Output files (*.out)|*.out parameters=Parameter files (*.prm)|*.prm
Within a program's INI file, the definition of the parameters
consists of a [parameters] section, followed by a separate section for
each setup page, of the form [Pfx.page.nn], where Pfx is a
(optional) language prefix, page is the word "page" and nn is an
integer denoting the page's sequence number in the setup.
The [parameters] section is language independent: ie there should not be separate [parameters] sections for each language defined in the INI file.
This section has the form:
[parameters] paramversion=1.2 extension=rcv pagemax=5 pagewidth=40 pageheight=22where:
paramversion is a version control that is independent of the program version number, which should be incremented when the parameter types or order are altered, although this is not implemented in the PrmEdit unit at present.extension should match the extension in the parameters filter in the [program] section.
pagemax determines the maximum page number which will follow in the page sections. Note that this refers to the highest page number nn in a page.nn section, not the actual number of pages. For example, if the INI file contains 3 pages, with section names [page.1], [page.2] and [page.8], pagemax should be set to 8, not 3.
pagewidth, pageheight are in the [parameters] section are the global default dimensions for all the following pages, in characters. These can be overridden for a particular page by individual width, height keywords within the page section.
You can also include the following optional directives in the [parameters] section:
wizard=true back check=truewhere:
wizard=true indicates that the PrmEdit dialogue should be displayed using a "wizard" interface with Back/Next buttons rather than the default menu interface.back check=true is only applicable in wizard mode, and indicates that parameter values should be checked when paging backward as well as forward.
Each [page.n] section should contain the following compulsory keys; eg:
[page.1] name=SETUP_OPTS title=Setup Optionswhere:
name is a string of up to 20 characters (containing no spaces) which is used as the section name for the page in parameter files.title is a descriptive string which is displayed in PrmEdit as the page title, and used to select the page from a list of parameter pages.
Each [page.n] section can also contain a number of optional keys, or directives, eg:
showif=PAGENAME,2,0 height=10 width=30 nosave=true noshow=true repeat=4 group=1where:
showif=PAGENAME,fieldno,xxx[,PAGENAME,fieldno,xxx,...] defines a condition for the current page to be displayed in the editor; this page will be displayed if parameter number fieldno (parameter field numbers start at 1) on the page with name PAGENAME has a numeric value of xxx . If the field is an options field, then xxx is equal to the index of the option (0,1,2 etc) which causes this page to be displayed. If more than one PAGENAME,fieldno,xxx condition is listed, the page will only be displayed when all conditions are met.nosave directive is for pages which are not to be saved in the parameter file. These can be used for temporary setup of parameters which are only required while the program is running. Parameter pages with this directive are saved as blank pages in parameter files; default values are read from the INI file or calling program. Note that this directive cannot be used in conjunction with the repeat directive.
noshow directive is for pages that should not be displayed in the normal paging sequence. It will normally be used in conjunction with the nosave directive. Pages with the noshow directive can only be displayed explicitly by the PrmForm.ShowPage() method (see below) after a call to the PrmForm.DisablePaging() method. This directive can be used for parameter pages that are functioning as "quick dialogue boxes" where some response to a question, or some input value is required from the user in addition to the standard program parameters.
repeat directive specifies that this page can have a maximum of repeat instances. See Multiple Parameter Pages below.
group directive can be used for complex paging sequences.
The screen layout of each parameter page is defined in each [page.n] section.
There are four basic kinds of parameters defined - numbers, options, strings and colours. Numbers can be small integers (2-byte signed) or long integers (4-byte signed) (which appear identical to the user except for the range of legal values) or floating point (4-byte). Options are usually stored by a program as a value of an enumerated type (with values starting at zero), and can be represented to the user as either a combo-box or a group of radio buttons. String fields can be straightforward text values, file or folder paths, or lists of values (stored as a comma-delimited string), and may or may not have a default value.
Each line in the parameter page layout starts with a '>' character (except where noted). Each parameter field can have an associated descriptive label, and there can also be free text which is not associated with any parameter field in particular.
Bear in mind that the layout positioning as defined in the INI file (and the page height and width) are translated to screen coordinates based on the default (proportional) font, so the displayed parameter layout may differ from the layout designed in the INI file.
- Short integers are underscores terminated by a letter "I":
>Short Integer Value _____I- Long integers are underscores terminated by a letter "L":
>Long Integer parameter _______L- Floating point numbers consist of underscores with a a single period to indicate the decimal point position. The number of underscores after the period indicates the precision with which the parameter value will be stored in the parameter file, and the rounding precision for display:
>Floating Point parameter _____.__- String fields consist of underscores with the number of underscores indicating only the width of the edit field displayed - the string length is unlimited:
>String parameter __________String parameters can also be specified as filenames or lists:
Open file name parameters will display an edit box with a browse button which will display a standard open file selection dialogue.
This is specified by underscores terminated by an "F".
You must specify an optional default filename, the caption to use for the dialogue, and the file filter to use.
You can leave the default filename field bank if you wish. You can add more file filters by adding more description,wildcard strings:
>Open file parameter ________________F |default.prm,"Open PRM file","PRM files",*.prm
Save file name parameters will display an edit box with a browse button which will display a standard save file selection dialogue.
This is specified by underscores terminated by an "S".
You must specify an optional default filename, the caption to use for the dialogue, and the file filter to use.
>Save file parameter ________________S |,"Save PRM file","PRM files",*.prm,"TXT files",*.txt
String list parameters will display an edit box with a browse button which will display a multi-line edit dialogue to enable easier editing of comma-delimited lists:
>String list parameter __________________E- Combo-box option parameters are always accompanied by a default value and one or more alternatives, as below.
> Size _____ |medium,small,medium,large
In this case, the default is medium and the three possible options are small, medium and large. Note that although the option strings can contain spaces, there should be no leading or trailing spaces on any of the strings.- Radio group option parameters are defined by the keyword RADIOGROUP, followed by the radio box caption and a list of options, which will be displayed as radio buttons. The radio group definition is ended by the keyword ENDRADIOGROUP.
RADIOGROUP Select an option >This is the first option >This is the second option >This is the third option ENDRADIOGROUP >- Colour parameters will display a combo-box with a list of standard colours, plus a custom entry which can be clicked to invoke a colour selection dialogue for the user to select a non-standard colour.
>Colour parameter _________________C
Default values for parameters can be set in the INI file, so that they can, in principle, be customised by a user. Parameter limits for numeric parameters can similarly be defined. Defaults and limits appear to the right of the corresponding parameter field in the INI and preceded by a "|" character .
In the case of an integer or floating point number, the layout is |A,B,C where A is the default value, B is the minimum and C is the maximum, eg
>Integer value ______L |2,1,25 >Floating point value ____.__ |10.0,-5.0,100.0In the case of a string or stringlist, the | can be omitted, to give a null string as default, or a default string can be specified, eg
>string without default _________ >string with default value _________ |Lynx >stringlist with default list ________E |Item1,"Item 2"String list items that contain spaces should be enclosed in double-quotes.
In the case of an combo-box option, the field is specified as a string with N different choices indicated by |default,option1,option2,option3,.......,optionN (note that default must be one of the values option1-optionN
>Program memory model _______ |medium,small,medium,large,hugeNote that in the corresponding parameter file, the options are stored as integers 0,1,2... corresponding to option1,option2,option3... This enables parameter files and programs to be "language independent", ie the string descriptions of the options can be changed without this affecting the parameter file or the program which reads it.
For radio group options, if no default is specified, the first option is initialised as the default. The default option can be specified by adding '|1' to the end of the string for the default value: eg
>The specified file already exists. RADIOGROUP What do you want to do? >Append file >Overwrite file |1 >Reselect file ENDRADIOGROUPIn this case the second option, Overwrite file will be the default option.
For colour parameters, the default value is specified as a 4-byte integer in hexadecimal notation preceded by a "$" (dollar symbol). The highest byte should be zero. The low three bytes represent RGB colour intensities for blue, green and red respectively. In the example below the default colour specified is RED:
>&Line Colour _____________C |$000000FFFor multiple parameter definitions on a single line, the default and range for each parameter field should be separated by a | character: eg
>Resolution ______L per _____ |200,1,1000|inch,inch,mm
For certain purposes, eg setting up and editing velocities, a parameter file needs to contain many instances of the same page.
repeat=maxpagesThis directive, in a [page.n] section (see [page.n] directives) indicates that multiple setup of the page is allowed, with a maximum of maxpages pages. For example, at present, programs using velocities use multiple pages of velocity tables, one per velocity point.
In the corresponding parameter file, the parameter page sections would be of the form [PAGENAME,nn] where nn is the sequence number of the instance of the page.
To provide online help for each individual parameter within a setup page, PrmEdit automatically generates a help context whenever a given parameter page or parameter field becomes active. The help context for a parameter is in the form PAGENAME_n where PAGENAME is the name, in upper case, of the parameter page from the name keyword and n is the sequence number of the parameter field within the page. For example, the third field of the OUTPUT page would generate a help context of the form OUTPUT_3. When using an HTML browser, this context string is the label part of a URL used to refer to the appropriate part of the program's documentation and help file.
For example, if the help file was C:\Lynxsys\docs\myprog.htm, the complete URL would be file:///C|/Lynxsys/docs/myprog.htm#OUTPUT_3