index

Varkon MBS Programmers manual

# Parameter declarations

A parameter_declaration is either a value_parameter_declaration:

      type parameter_definition [:=default_value] [>prompt_string]

or a reference_parameter_declaration:

      VAR type parameter_definition

Value parameters are evaluated at runtime and the actual value of the parameter is transferred from the caller to the called module. A reference parameter is not passed to the called module, only its adress.

MBS supports the following types:

Type | Description
--- | ---
INT | - 32 bit integer
FLOAT | - 64 bit float
VECTOR | - 3 floats, .x, .y and .z
STRING | - String of maximum 132 8 bit characters
REF | - ID of entity in DB
FILE | - File variable

Here are some valid value_parameter_declarations:

      INT    number_of_holes:=5 >"How many holes ?"
      FLOAT  distance           >"What distance ?"
      VECTOR pos:=vec(100,100);
      STRING name*20            >"What is your name ?"
      REF    id                 >"Pick a line !"

STRING parameters need an extra "*length" after the identifier to indicate the maximum length of the string. MBS supports strings up to 132 characters.

A FILE parameter must be declared with a reference_parameter_declaration. Here are some valid reference_parameter_declarations:

      VAR INT    number_of_holes
      VAR FLOAT  distance
      VAR VECTOR pos
      VAR STRING name*20
      VAR REF    id
      VAR FILE   customer_data

A reference parameter may also be used to pass an indexed variable from one module to another:

      VAR INT    sizes(100)
      VAR FLOAT  matrix(4,4)
      VAR STRING name_list(100)*20

It is not necessary to declare each parameter of the same type individually. The following style with multiple parameters separated by commas is also possible:

      VECTOR pos_1 >"First position !",
             pos_2 >"Mid position !",
             pos_3 >"Last position !

A module with only one parameter declaration might begin as follows:

      MODULE shaft(FLOAT size);

but with multiple parameter declarations they must be separated by semicolons...

      MODULE shaft(FLOAT size; INT number_of_holes; STRING material*10);

MBS is not line oriented. The line above may just as well be written as follows:

      MODULE   shaft(
        FLOAT  size;
        INT    number_of_holes;
        STRING material*10);

A value parameter may be declared with default value and prompt string. This information is displayed to the user by Varkon when the module is called interactively. The Create part and Change part functions both rely on default values and prompt strings.

## Hidden parameters

A parameter without any prompt at all, is called a hidden parameter. Hidden parameters are not prompted for when the module is called. Varkon uses the default value automatically. This mechanism is intended for modules with many parameters but only a few that need to be set by the user initially. Change part can be used to change the value also of hidden parameters.

A prompt may be any string like "How many ?" or "Pick a line !" but may also be preceded by a @-modifier. @-modifiers are used by Varkon to modify the standard behaviour of presenting default values and prompts. A parameter without @-modifier is called a normal parameter.

## Optional parameters

A parameter with a prompt preceded by a single "@" and a space is called an optional parameter. Optional parameters can be used to present a varying number of parameters like in the following example:

      VECTOR p1 >"Give a start position !";
      VECTOR p2 >"@ Second position ! (optional)";
      VECTOR p3 >"@ Third position ! (optional)";
      VECTOR p4 >"@ Fourth position ! (optional)";
      VECTOR p5 >"@ Fifth position ! (optional)";
      VECTOR p6 >"Last position !";

In the example above Varkon will first prompt for p1 and then for p2. If the user defines a valid position for p2 Varkon goes on with p3, p4 and so on. As long as the user answers the questions he gets positively Varkon will continue to present the next parameter even if it is optional. If the user refuses to input a valid value for an optional parameter and rejects the question Varkon will use the default value for the parameter in question as well as all optional parameters directly following. This mechanism makes it possible to construct dialogues where the user may input a varying number of values from call to call. In the example above the user must always define p1 and will always be prompted for p2. If he rejects p2 Varkon will skip even p3, p4 and p5 but finally prompt for p6. 2, 3, 4, 5 or 6 positions are the alternatives in this example.

## Menu parameters

A STRING parameter may get its value from a menu instead of the normal input from the keyboard by the use of the @m-modifier. Such a parameter is called a menu parameter.

      STRING type*2 >"@m250 Select a type from the menu !"

The parameter above will force Varkon to display menu 250 and prompt the user to make a selection. The answer is either an empty string "" if the user rejects, or the action code of the selected alternative. See the get_alt() function for related information.

Menu parameters may also be optional as in the following example:

      STRING type*2 >"@@m250 Select a type from the menu !"

## Position parameters

A VECTOR parameter normally uses the position method currently active as shown by the buttons in the bottom part of the menu window. If you know in advance what method to use, you can specify this with a @-modifier. Here is an example of a position method parameter:

      VECTOR p1 >"@a3 Where do you want to start ?"

The @a followed by a number forces Varkon to override the normal method and use the method indicated by the number instead. Number 3 is the same as alternative button 3 in the bottom section of the menu window. Position parameters may also be optional.

## Typemask parameters

A REF parameter can be used to input the identity of all types of entities. The @t-modifier makes it possible to restrict the input to an entity of a certain type (or types). Such a parameter is called a typemask parameter...

      REF id >"@t6 Pick a line or arc !"

The typemask is created by adding the type codes for the valid entity types. In this case 2 + 4 = line and arc. See the gethdr() procedure for a list of type codes. Typemask parameters may also be optional.

## Dynamic default parameters

An INT, FLOAT or STRING parameter can have its default value fetched from a textfile by the use of the @f-modifier. This makes it possible to present new default values each time the module is called and such a parameter is therefore called a dynamic default parameter. Here are some examples:

      INT number >"@ffilename Enter next number !"

Reads default value from the first line in the file with the name filename. A path may be included.

      INT number >"@fact_job Enter next number !"

If the special filename "act_job" is used Varkon replaces this with the value of act_jobdir()+act_jobnam(). This is a way to dynamically link individual default values to different jobs. (act_job is actully the value of t-string 119 and may be redefined if prefered).

      INT number >"@defvals.dat(5) Enter next number !"

Reads the default value from line 5 in the file defvals.dat. An extra @ makes the parameter optional in the same way as all other parameters.

## Dynamic prompt parameter

A normal prompt string is static but may be linked to a t-string using a slightly different syntax than the @-modifier described above.

      INT n >"t625"

A prompt beginning with lower case "t" directly followed by a number is treated as a dynamic prompt parameter. A dynamic prompt parameter may be optional but may not be combined with other @-modifiers.

Varkon version 1.19C svn# 120