Parameter Definition File

The parameter definition file specifies the format of the parameter input performed by the module. It also contains all the information necessary to generate a make file which is used to compile the module's source files, to specify the locations of the module's object code and of used libraries, and to generate the documentation files.

All processing of the .mpar file is performed by the program called pdf, located in the directory $SIABIN, using the following command (again, we assume the name of the module ourmod, and thus the name of the PDF file is ourmod.pdf): 

$SIABIN/pdf ourmod 

Normally, all files of module ourmod will be placed in a directory also named ourmod; the program pdf is aware of this and thus, when issued in this directory, the following command will be identical to the above:

 $SIABIN/pdf

 The format of .mpar files is quite simple. Every statement begins with a key word, which, in its turn, always begins with a colon ':'. The parameters are divided into groups, referred to as "lists" and "repeat groups". 

Lists of parameters appear usually in the same line of the job, following the module name ("global; list"), or the name of the list. Repeat groups of parameters appear one or several times per line, any number of lines following the corresponding list in which these groups are defined. The lists appear in the documentation file in the alphabetical order, thus the sequence of the lists in the `mpar  file is not essential. A template of the module parameter file for our module ourmod (file ourmod.mpar), showing the use of all allowed key words, looks like this:

PROC OURMOD # name of the module After the name of the module, 

	several lines of module description follow, until the next key word. 

	This text appears as the module description in the documentation, 

	so it should contain all the important information about the module, 

	programmer's name and date of the release, hints, tips, warnings, etc. 

:DESCGL Optional description of global parameters. 

	This text is intended for the user only, 

	and it should contain general remarks, for example, 

	about the type of module parameterization, some details about 

	relations between the global parameters, etc. 

:GLOBAL # "Global" list describes the parameters 

	# immediately following the name of the 

	# module in the same line of job call 

	# See below! ... 

:DESCR Optional description of the REPEAT group associated with current list. 

	This text may contain an explanation of the use of the REPEAT group. 

	Another spelling of the same key word is: :DESCRP. 

:REPEAT 2 # Repeat groups of the global list, if any 

	# The number specifies the number of the 

	# parameter groups per line of the input file ... 

:LIST LIST1 # Name of the list ("LIST1" in this case) 

	The name of the list is followed by a description of the 

	function performed by the parameters of the list. 

	This description is put into the module documentation file. ... 

:REPEAT 1 # Repeat groups of the list "LIST1", if any 

	# The number specifies the number of the 

	# parameter groups per line of the input file ... 

:LIST LIST2 # Another list, etc. ... 

:FILES 	file1.c 	# Tells the program which files it is file2.f

	file2.C		# necessary to compile, besides ourmod_ep.C 

	file3.f		# and ourmod_pp.C ...

:INCL another.pdf.inc 

	# Includes another file formatted 

	# in the same manner. Nested inclusions are allowed 

:STORE library_name # Object library where the compiled 

	# subroutines of the module will be stored. 

	# All libraries are stored in the directory $SIALIB, and 

	# have names of the form liblibrary_name.a 

	# The default module library is # $SIALIB/libSIAmodules.a 

:LIB library_1 # Names of the libraries containing library_2 

	# subroutines used by the module, in the above sense. 

	# The default # library $SIALIB/libSIAmodules.a 

	# is always linked and does not need to be specified ... 

:END # End of this module parameter file 

The parameter descriptions in the above example have the following format: 

NAME,format,'Min','Max','Default','Description' where: 

• NAME is the up to 7-character name of the parameter field. This name is used by the Edit phase subroutine to access the parameter. This name must differ from the name of other parameters in the same group, but it may be the same as the name of the list, or as the names of parameters in other groups.

• format is the format of the field, as listed in the following table:

  I	integer value, occupies 8 positions (one tab stop)
  F	floating-point value in 8 positions
  C<number>	e.g., C16 character (ASCII) value, occupies 'number' of positions. The number must be a multiple of 8
  L	long integer value, occupies 8 positions
  D	double value, occupies 8 positions
  HV	equivalent to C8, but the character field is interpreted as a trace header name or a constant numerical value.
  nfmt	Numeric format: a numeric value is expected in this field

• Min, Max, Default are character strings describing the minimum, maximum, and default (used when the field is left blank) values which may be put into the field. The field is not analyzed and is transferred to the documentation file only after minor reformatting. 

• Description is the character string describing the parameter. This string is put into the module documentation, into the "List Details" section. This string, as well as the Min, Max, Default records, may occupy as many lines of the `mpar file, as you find it necessary. Note: the apostrophes delimiting the strings Min, Max, Default, and Description are required, and thus they may not appear in the texts! To skip some of the fields, ignore them completely, as in the following example: 

FILE,C64,,,,'File name'.