Parameter class

The Parameter class allows you to access the parameters in a model. More...

The PRIMER JavaScript API provides many class constants, properties and methods. For Arup to be able to extend and enhance the API in the future any constant, property or method names beginning with a lowercase or uppercase letter are reserved.
If you need to add your own properties or methods to one of the existing classes then to avoid any potential future conflict you should ensure that the name begins with either an underscore (_) or a dollar sign ($) or the name is prefixed with your own unique identifier.
For example if company 'ABC' need to add a property called 'example' then to avoid any potential future conflict use one of:

Class functions

Member functions

Parameter constants

Name Description
Parameter.CHARACTER Parameter is a character.
Parameter.INTEGER Parameter is an integer.
Parameter.LOCAL Parameter has _LOCAL suffix (used in suffix argument for constructor).
Parameter.MUTABLE Parameter has _MUTABLE suffix (used in suffix argument for constructor).
Parameter.NOECHO Parameter has _NOECHO suffix (used in suffix argument for constructor).
Parameter.REAL Parameter is a real.

Parameter properties

Name Type Description
expression (read only) logical true if this parameter is a *PARAMETER_EXPRESSION, false otherwise.
include integer The Include file number that the parameter is in.
local logical true if this parameter is a *PARAMETER_... _LOCAL, false otherwise.
model integer The Model number that the parameter is in.
mutable logical true if this parameter is a *PARAMETER_... _MUTABLE, false otherwise.
name (read only) string Parameter name.
noecho logical true if this parameter is a *PARAMETER_... _NOECHO, false otherwise.
type (read only) constant Can be Parameter.INTEGER, Parameter.REAL or Parameter.CHARACTER.
value integer/real/string Parameter value. The value will be a string for parameter expressions, or a number for normal parameters.
By default when a parameter value is changed PRIMER will re-evaluate and update all of the parameters in the model as changing this parameter could cause others to change because of parameter expressions. There could be some situations where changing parameters one at a time could cause problems with re-evaluation. For example, changing parameter A could temporarily cause a division by zero when re-evaluating parameter expression B until parameter C is changed. In this case the automatic re-evaluation can be prevented by using Parameter.SaveAll and Parameter.UpdateAll.

Detailed Description

The Parameter class allows to create and query parameters in a model. See the documentation below for more details.

Constructor

new Parameter(Model[Model], name[string], type[constant], expression[boolean], value[integer/real/string], suffix (optional)[constant])

Description

Create a new Parameter object.

Arguments

  • Model (Model)

    Model that parameter will be created in

  • name (string)

    Parameter name

  • type (constant)

    Can be Parameter.INTEGER, Parameter.REAL or Parameter.CHARACTER.

  • expression (boolean)

    true if *PARAMETER_EXPRESSION, false otherwise.

  • value (integer/real/string)

    Parameter value. The value will be a string for character parameters or parameter expressions, or a number for integer or real parameters.

  • suffix (optional) (constant)

    Keyword suffix Can be Parameter.LOCAL for *PARAMETER_..._LOCAL, Parameter.MUTABLE for *PARAMETER_..._MUTABLE, or Parameter.NOECHO for *PARAMETER_..._NOECHO. These may be bitwise ORed together, ie Parameter.LOCAL | Parameter.MUTABLE | Parameter.NOECHO. If omitted the parameter will not be local or mutable.

    Returns

    Parameter object

    Return type

    Parameter

    Example

    To create a new real parameter THK in model m with value 5.0 

    var p = new Parameter(m, "THK", Parameter.REAL, false, 5.0);

    To create a new LOCAL integer parameter INDEX in model m with value 3 

    var p = new Parameter(m, "INDEX", Parameter.INTEGER, false, 3, Parameter.LOCAL);

    Details of functions

    AutoReorder(Model[Model]) [static]

    Description

    Auto Reorders all the parameters in the model.

    Arguments

  • Model (Model)

    Model that contains all parameters that will be re-ordered

    Returns

    No return value

    Example

    To auto-reorder all parameters in model m: 

    Parameter.AutoReorder(m);

    ClearFlag(flag[Flag])

    Description

    Clears a flag on the parameter.

    Arguments

  • flag (Flag)

    Flag to clear on the parameter

    Returns

    No return value

    Example

    To clear flag f for parameter p: 

    p.ClearFlag(f);

    Error(message[string], details (optional)[string])

    Description

    Adds an error for a parameter. For more details on checking see the Check class.

    Arguments

  • message (string)

    The error message to give

  • details (optional) (string)

    An optional detailed error message

    Returns

    No return value

    Example

    To add an error message "My custom error" for parameter p: 

    p.Error("My custom error");

    Evaluate()

    Description

    Evaluates a parameter expression, updating the evaluated value stored in PRIMER and returns the value. If the parameter is not an expression then the parameter value will just be returned.
    If evaluating the expression cannot be done because of an error (e.g. dividing by zero) an exception will be thrown.

    Arguments

    No arguments

    Returns

    number (real and integer parameters) or string (character parameters)

    Return type

    Number

    Example

    To evaluate parameter p: 

    var value = p.Evaluate();

    FlagAll(Model[Model], flag[Flag]) [static]

    Description

    Flags all of the parameters in the model with a defined flag.

    Arguments

  • Model (Model)

    Model that all parameters will be flagged in

  • flag (Flag)

    Flag to set on the parameters

    Returns

    No return value

    Example

    To flag all of the parameters with flag f in model m: 

    Parameter.FlagAll(m, f);

    Flagged(flag[Flag])

    Description

    Checks if the parameter is flagged or not.

    Arguments

  • flag (Flag)

    Flag to test on the parameter

    Returns

    true if flagged, false if not.

    Return type

    Boolean

    Example

    To check if parameter p has flag f set on it: 

    if (p.Flagged(f) ) do_something...

    GetAll(Model[Model]) [static]

    Description

    Returns an array of Parameter objects for all of the parameters in a model in Primer

    Arguments

  • Model (Model)

    Model to get parameters from

    Returns

    Array of Parameter objects

    Return type

    Array

    Example

    To make an array of Parameter objects for all of the parameters in model m 

    var p = Parameter.GetAll(m);

    GetAllOfName(Model[Model]) [static]

    Description

    Returns an array of Parameter objects for all parameters in a model matching Name. If none are found that match it will return NULL. (Multiple parameters of the same name may exist if they use the _LOCAL or _MUTABLE suffices. PRIMER will also store multiple illegal instances of parameter name, using the instance as determined by the PARAMETER_DUPLICATION card.)

    Arguments

  • Model (Model)

    Model to get parameters from

    Returns

    Array of Parameter objects

    Return type

    Array

    Example

    To make an array of Parameter objects for all of the parameters of name in model m 

    var p = Parameter.GetAllOfName(m, name);

    GetFromName(Model[Model], parameter name[string]) [static]

    Description

    Returns the stored Parameter object for a parameter name. WARNING: if more than one parameter Name exists (eg _LOCAL, _MUTABLE) then only the first occurrence is returned. To return all parameters matching Name use GetAllOfName() instead.

    Arguments

  • Model (Model)

    Model to find the parameter in

  • parameter name (string)

    name of the parameter you want the Parameter object for

    Returns

    Parameter object (or null if parameter does not exist).

    Return type

    Parameter

    Example

    To get the Parameter object for parameter "THK" in model m 

    var p = Parameter.GetFromName(m, "THK");

    Keyword()

    Description

    Returns the keyword for this parameter (*PARAMETER, *PARAMETER_EXPRESSION). Note that a carriage return is not added. See also Parameter.KeywordCards()

    Arguments

    No arguments

    Returns

    string containing the keyword.

    Return type

    String

    Example

    To get the keyword for parameter p: 

    var key = p.Keyword();

    KeywordCards()

    Description

    Returns the keyword cards for the parameter. Note that a carriage return is not added. See also Parameter.Keyword()

    Arguments

    No arguments

    Returns

    string containing the cards.

    Return type

    String

    Example

    To get the cards for parameter p: 

    var cards = p.KeywordCards();

    SaveAll(Model[Model]) [static]

    Description

    Saves the current status and values of all of the parameters in the model. Calling this will also have the effect of turning off re-evaluating and updating of all parameters in the model when a parameter value is changed.
    To update several parameters in a model without re-evaluating all the parameters after each one is changed first call this, then update all of the parameter values, and then call Parameter.UpdateAll to apply the update.
    Parameter.SaveAll must be called before using Parameter.UpdateAll.

    Arguments

  • Model (Model)

    Model that the parameters will be saved in

    Returns

    No return value

    Example

    To save the status of all of the parameters in model m: 

    Parameter.SaveAll(m);

    SetFlag(flag[Flag])

    Description

    Sets a flag on the parameter.

    Arguments

  • flag (Flag)

    Flag to set on the parameter

    Returns

    No return value

    Example

    To set flag f for parameter p: 

    p.SetFlag(f);

    UnflagAll(Model[Model], flag[Flag]) [static]

    Description

    Unsets a defined flag on all of the parameters in the model.

    Arguments

  • Model (Model)

    Model that the defined flag for all parameters will be unset in

  • flag (Flag)

    Flag to unset on the parameters

    Returns

    No return value

    Example

    To unset the flag f on all of the parameters in model m: 

    Parameter.UnflagAll(m, f);

    UpdateAll(Model[Model]) [static]

    Description

    Updates all of the parameters in the model after saving the state of all parameters using Parameter.SaveAll and modifying the parameter values. As parameter re-evaluation has been suppressed by Parameter.SaveAll you should ensure that all parameters in the model can be evaluated correctly before calling this to ensure that there are no errors. If any of the parameters cannot be evaluated then the values saved in Parameter.SaveAll will be restored, the update will be aborted and an exception thrown. Calling this will also have the effect of turning back on re-evaluating and updating of all parameters in the model when a parameter value is changed.
    Parameter.SaveAll must be called before this method can be used.

    Arguments

  • Model (Model)

    Model that the parameters will be updated in

    Returns

    No return value

    Example

    To update all of the parameters in model m: 

    Parameter.UpdateAll(m);

    Warning(message[string], details (optional)[string])

    Description

    Adds a warning for a parameter. For more details on checking see the Check class.

    Arguments

  • message (string)

    The warning message to give

  • details (optional) (string)

    An optional detailed warning message

    Returns

    No return value

    Example

    To add a warning message "My custom warning" for parameter p: 

    p.Warning("My custom warning");

    Xrefs()

    Description

    Returns the cross references for this parameter.

    Arguments

    No arguments

    Returns

    Xrefs object.

    Return type

    Xrefs

    Example

    To get the cross references for parameter p: 

    var xrefs = p.Xrefs();

    toString()

    Description

    Creates a string containing the parameter data in keyword format. Note that this contains the keyword header and the keyword cards. See also Parameter.Keyword() and Parameter.KeywordCards().

    Arguments

    No arguments

    Returns

    string

    Return type

    String

    Example

    To get data for parameter p in keyword format 

    var s = p.toString();