Using Parameters in Macros

Parameters are placeholders for information that you will provide when you actually execute a macro. You include parameters in the text of the commands to be executed by a macro. You write parameters as a "$" followed by the name of the parameter (the full format is explained below). You can include many different parameters, and you can include the same parameter more than once.

When you create a macro, Adams View scans the command text to identify all the parameters. When you issue the command to execute the macro, you provide values for the parameters, or they assume a default value. Adams View substitutes the values into the commands in place of the parameters, then executes the commands. If you used the same parameter more than once in the command text, Adams View substitutes the same value each place the parameter appears.

For example, the following macro shows how to change the size of all force and constraint icons in your modeling sessions. The command in the macro, named icon_size, contains a parameter named size:

When you enter the command:

Adams View executes the commands:

In some cases, Adams View may reformat or expand parameter values before substituting them into the command text. Adams View never changes values, however. In particular, Adams View does not convert units during the macro substitution. It passes the values you enter directly to the commands. The commands themselves may convert units, as usual.

Adams View expands database names into full names before substituting them into the macros. The expanded names use "." to separate levels in the name. Using "." allows you to directly access database values in expressions.

For example, the following is a macro lpart that contains a parameter name:

When you enter the following command:

Adams View substitutes the full name of part left_wheel (for example, .mod1.left_wheel) for $name and executes the command:

The general format of a parameter is $'name:q1:q2:q3...', where:

The single quotes and qualifiers are optional (see below), giving four possible formats:

A parameter name must start with an alphabetic character. The rest of the name can include numeric characters and underscores ("_") as well as alphabetic characters (a-z, A-Z) but no spaces. The name ends at the first character that is not alphabetic, numeric, or an underscore. For more information, see Using Extended Names. Therefore, $P, $P1, and $PART_1 are valid parameter names while $PART#1 and $1P are invalid. Parameter names are not case sensitive, meaning $PART, $Part, and $part are all the same parameter.

You use single quotes to explicitly separate the name or qualifiers from command text immediately following the parameter. Normally, you place a space, comma, colon, or other special character after a parameter, which separates it from the following text. If you want to concatenate text to the end of a parameter, however, you must enclose the parameter name in single quotes. If, for example, you want to add "_1" onto the end of parameter $part, you cannot write $part_1, because Adams View would interpret it as a parameter named part_1. Instead, you must write $`part'_1.

You can use qualifiers on the first occurrence of the parameter to control the parameter characteristics. Qualifiers are optional and can only be used the first time the parameter appears in the macro text.

Parameter can have one or more of the following qualifiers:

You can use the qualifiers in any combination and any order, and you do not need to define all of them. If you repeat a qualifier, Adams View uses the last value. Qualifiers can be in upper or lowercase. Examples of qualifiers are:

The type qualifier specifies the type of value a user must enter. The format for the type qualifier is:

where:

A range qualifier specifies the minimum and/or maximum values allowed. It only applies to numeric types. The formats for the range qualifiers are listed in the table below.

Count qualifiers specify the number of values required. The formats for the count qualifier are listed in the table below.

Default qualifiers are optional. If a parameter has no default, users must enter a value when executing the macro. There are three types of default qualifiers as well as a default value:

The table below lists the formats for the default qualifiers.

The first occurrence of a parameter in the command text defines the parameter characteristics. This is true even if the first occurrence is in a comment. If the first occurrence includes qualifiers, the qualifiers determine the parameter characteristics. If there are no qualifiers and the parameter appears immediately after an "=" in a valid command, then the parameter inherits the type, range, count, and default from the preceding command parameter. If there are no qualifiers and the parameter does not appear immediately after an "=" in a valid command, the default characteristics are one string value with no default.

In the example below, parameter $text defaults to a string because it has no qualifiers and is not in a command. Parameter $numbers has qualifiers that specify it as one or more integers greater than zero. Parameter $part_1 is a part because it immediately follows an "=" and, therefore, inherits the type from parameter part_name. Parameter $part_2 defaults to string because it does not immediately follow the "=". Parameters $part_3 and $part_4 have qualifiers that specify them both as parts.