Customizing View

Customizing Adams/View
You can customize Adams/View so that it works and looks the way you want it to and mimics your design
environment. There are four major ways to customize it. You can:
• Customize the graphical interface - For example, you can create your own set of menus or
dialog boxes.
• Automate your work using macros - You can also speed up your work by creating macros to
perform complex or repetitive tasks. You can edit the macros to include design variables to
further customize and automate the modeling process.
• Create your own Adams/View library - The library you create can read in different
Adams/View functions and execute commands. For information on creating libraries, refer to
Running and Configuring Adams.
• Edit Adams/View startup files - You can edit the files that Adams/View reads when it first
starts. These files can automatically load a model, execute commands, or change menus or
dialog boxes. For information on editing startup files, refer to the Running and Configuring
Adams.
Automating Your Work Using Macros

You can automate repetitive processes by creating a macro of a command or a group of commands that
you use frequently. You can record, edit, save, and replay as many macros as you like.
Once you have your macros working properly, you can make them easier to use by associating them with
graphical user interface (GUI) objects you create. For more information, see Customizing Menus Using
the Menu Builder and Creating Dialog Boxes
2 Adams/View
About Adams/View Macros

A macro is a single command that you create to execute a series of Adams/View commands. To create a
macro, you give Adams/View the list of commands you want executed, as well as a new command that
will execute them. You write the commands that the macro executes using the Adams/View command
language.
You can use parameters in macros. Parameters give you a way to send data to the macro each time you
use it. They are placeholders for information that you will provide when you actually execute the macro.
When you issue a macro command containing a parameter, Adams/View substitutes the values that you
provide into the commands contained in the macro.
Adams/View treats a macro as it does all other Adams/View commands. You can enter the macro in the
command window, select it from the Command Navigator, include it in other macros, or execute it from
your own custom menus, dialog boxes, or buttons.
Among the tasks you can perform with macros are:
• Automate repetitive procedures.
• Build general-purpose extensions to Adams/View.
• Automatically create an entire model.
• Quickly build many variations of a mechanism.
To make it easy for you to create a macro, Adams/View contains tools to automate the creation of macros.
The tools let you interactively record, play, and test your macros and command files. You can also use
text-editing applications to modify existing macros or create them from scratch.
About Creating Macros

To create a Macro, give Adams/View the list of commands you want executed, as well as a new command
that will execute them. You write the commands that the macro executes using the Adams/View
command language.
You can use parameters in macros. Parameters give you a way to send data to the macro each time you
use it. They are placeholders for information that you will provide when you actually execute the macro.
When you issue a macro command containing a parameter, Adams/View substitutes the values that you
provide into the commands contained in the macro.
You can create macros in four different ways:
• Interactively by recording key strokes. Learn about how to record key strokes in Recording
Macros.
• Typing the commands to be executed into the Macro Editor. You can also use the Macro Editor to
edit an existing macro.
• Reading in a command file that contains the commands that the macro will execute. Learn about
Creating Macros from Existing Files.
Automating Your Work Using Macros 3
• Using the Command Navigator or Command window to type in the commands to create macros
as well as the commands to be executed. Learn about using the Command Navigator and
Command Window.
Recording a macro is easiest for simple macros, while reading in a file is best for more complex macros.
When you read in a file, you can also specify the help file or string that you want associated with the
macro. Using the Macro Editor is best for editing existing macros. If you use the Macro Editor to create
macros, you must type in the commands that the macro is to execute.
Editing and Creating Macros Using the Macro Editor

You can use the Macro Editor to edit macros that you recorded or that you created by importing a macro
file. You can also use the Macro Editor to create a macro.
To use the Macro Editor:

1. On the Tools menu, point to Macro, point to Edit, and then select either New or Modify.
2. If you selected Modify, the Database Navigator appears. Select a macro to modify.
The Macro Editor appears as shown below. If you chose to edit a macro, the macro commands
appear in the Commands text area of the Macro Editor.
3. If you are creating a macro, in the Macro Name text box, enter the name of the macro.
4 Adams/View
4. In the Command text box, enter the command string that executes the macro. To use the name of
the macro, select Use Macro Name.
Note: The command string you enter must be unique. You cannot redefine an existing command,
although you can add a new keyword at any level to an existing command. For instance,
entering MARKER CREATE is invalid, because a MARKER CREATE command already
exists, but entering MARKER GENERATE is valid.
5. Specify whether or not the entire macro can be undone with a single Undo command. Note that a
single Undo=yes, while convenient, can consume a great deal of memory for very large macros,
or slow macro execution noticeably, even if you do not ever use the Undo. You might want to
specify Undo=yes during initial creation and debugging until your macro works properly, then
switch to Undo=no to improve performance.
6. In the Commands text area, enter the commands that the macro is to execute, and select OK.
Recording Macros
Recording a Macro is easiest for simple macros.
To record a macro:
1. From the Tools menu, point to Macro, point to Record/Replay, and then select Record Start.
2. Perform the operations you want included in the macro.
3. To stop recording the macro, from the Tools menu, point to Macro, point to Record/Replay, and
then select Record Stop.
To play back a macro you recorded:

• From the Tools menu, point to Macro, point to Record/Replay, and select Execute Recorded
Macro.
To save a recorded macro:

• From the Tools menu, point to Macro, point to Record/Replay, and then select Write
Recorded Macro.
Adams/View saves the macro as the command file macro.cmd. If a file called macro.cmd already
exists, Adams/View asks you if you want to overwrite it or create a backup copy of it.
Creating Macros from Existing Files

You can use the Read command to read in an existing command file containing the commands to be
executed. You can also assign a help file or text string to the macro that explains the macro's use.
The file you supply that contains the macro definition is a command file that can also contain parameters
embedded in the commands and can have special comments at the top.
Some of the comments in the file you supply can correspond to Read command parameters that are listed
in the Macro Read dialog box, such as the command users enter to execute the macro. These comments
must appear at the beginning of the file and must contain the name of one of the reserved parameters
(USER_ENTERED_COMMAND, WRAP_IN_UNDO, HELP_STRING, or HELP_FILE) followed by
an appropriate value.
These reserved parameters must be in uppercase letters and must immediately follow the comment
character (!). You enter the values without equal signs or quotes. Adams/View treats the values in the
comments as defaults. For example, the following comments set the default values for
USER_ENTERED_COMMAND and HELP_STRING.
!USER_ENTERED_COMMAND lmark
!HELP_STRING This command lists information on all markers in your database.
list_info marker marker_name=.*
If you specify values for these parameters using the Macro Read dialog box, the values in the dialog box
override the values in the comments.
To create a macro by reading in a file:

1. On the Tools menu, point to Macro, and then select Read.
The Macro Read dialog box appears.
Note: The Macro Read dialog box contains an option to create a panel. This option is no
longer supported or recommended.
2. In the Macro Name text box, enter the name of the macro that Adams/View uses to store the
macro in the current database.
3. In the File Name text box, enter the name of the file containing the commands to be executed.
4. In the User Entered Command text box, specify the command string that will execute the macro.
The command string defaults to the name of the macro if you do not enter a command string.
5. Specify whether or not the entire macro can be undone with a single Undo command. Note that
a single Undo, while convenient, can consume a great deal of memory for very large macros or
slow macro execution noticeably, even if you do not actually use the Undo.
6. Specify a text file containing help on the macro or enter a text string describing the macro.
Currently, you can only specify help for the entire macro command, not its parameters or leading
keywords.
7. To ensure that you do not create an outdated dialog box, from the Create Panel option menu,
select no.
6 Adams/View
8. Select OK.
Note: To create an up-to-date dialog box to execute your macro, go to the Command
Navigator and double-click on the name of your macro after you have created it.
Adams/View automatically creates a dialog box whose name is based on the user-
entered commands associated with the macro. For example, if you create a macro
called mar_scale_down and associated with it the user-entered commands: marker
scale down, then Adams/View names the auto-generated dialog box
.gui.mar_sca_dow (Adams/View uses the first three characters of each command in
the user-entered commands to create the name of the dialog box). See also
Customizing Dialog Boxes Using the Dialog-Box Builder, and the example.
Saving Macros
Adams/View automatically stores your macros in the current modeling session. You can also export your
macros to command (.cmd) files, which allows you to edit, archive, or import them into other modeling
session. It also lets you give the macro to another user, and also helps you to modify long macros when
you do not have the original file
If you used non-default values for the other macro data, such as the help string, the command file includes
comments with those values. You can read in the command file using the Macro Read command.
To save a macro to a command file:

1. On the Tools menu, point to Macro, and then select Write.
The Macro Write dialog box appears.
2. Enter the name of the macro to save to a file.
3. Enter the file name in which to save the macro.
4. Select OK.
Deleting Macros
To delete objects using the Database Navigator:
1. Clear the select list of any existing selections by selecting the Select Tool .
2. On the Edit menu, select Delete.
The Database Navigator appears.
3. Select the macro or macros that you want to delete. Learn about navigating through a modeling
database using the Database Navigator.
4. Select OK.
Note: If the Database Navigator does not appear as indicated in Step 2, the select list was
not cleared before executing the Delete command. You can always use the Edit ->
Select List commands to be sure it is cleared.
Debugging Macros
Adams/View provides a debugging tool to help you troubleshoot your macros if they don't run or work
as expected. You can use the debugging tool to:
• View your macro and the output from it.
• Step through each command in the macro.
• Print your macro.
To access the macro debugging tool:

• On the Tools menu, point to Macro, and then select Debug.
Executing Macros
Once you have created a macro, you execute it by issuing the command that you specified when you
created the macro. You can issue the command by:
• Entering the command in the Command window. The full command is a combination of the
command and macro parameters, if any.
• Using the Command Navigator to execute the command. Selecting the macro command in the
Command Navigator, automatically displays a dialog box in which to enter parameters.
• Using a custom dialog box and menu command that you created to execute the macro. Learn
more about Customizing Dialog Boxes Using the Dialog-Box Builder.
Adams/View treats the macro as it does other Adams/View commands. For example, if you enter the
command in the command window, but do not enter all required parameters, Adams/View prompts you
for the missing required parameters.
Tips on Writing Macros

Command Echo and Screen Update
As Adams/View executes a macro, it updates the view windows each time their content changes. If you
execute a macro from the command window, Adams/View, by default, echoes each command to the
command information area of the command window as it executes the macro. This can be useful when
debugging because you can see the executed commands and their immediate effects.
8 Adams/View
It can also be slow and distracting, however, once your macro is working properly. You can prevent this
by including the following as the first command in the macro:
defaults command_file echo=off update=off
Including the command allows macros to run more quickly because Adams/View does not echo the
macro commands to the command information area and updates the views only once, when the macro is
finished. You can reset the defaults by including the following command as the last line in your macro:
defaults command_file echo=on update=on
If you execute a macro from a dialog box or menu, Adams/View, by default, updates the screen at each
change, but does not echo the macro commands to the command information area.
Using Conditionals and Loops

The Adams/View command language contains commands for creating conditional constructs and loops.
You will find these very useful in writing macros. The constructs are:
• FOR/END
• WHILE/END
• CONTINUE
• BREAK
• IF/ELSE/ELSEIF/END
• RETURN
For example, you can use an IF command to conditionally execute commands within your macro. You
can create a parameter to specify a choice of options, then use the IF statement to determine which option
was chosen and execute the appropriate commands.
For more information on the different conditional constructs, see Conditional Constructs and Loops.
Writing Text Files

To create macros that write formatted reports, command files, or other data files, you can use the
commands:
file text write=...
This command writes information from Adams/View into a text file. You control the format of the output
and, using database access expressions, you can write any model or simulation data from the
Adams/View database.
Executing System Commands

You can execute system commands using the Adams/View System command. Its Adams/View command
language is:
system command_text=...
By including the System command, you can create macros that invoke outside utilities and programs.
You could, for example, create a macro that generates hardcopy files for a standard series of plots, then
use the System command to issue comments to print and delete the plots.
Ensuring Unique Names and Adams Identifiers

If your macro creates new entities, you must take special care to construct unique names and unique
Adams identifiers each time you execute the macro. Otherwise, the macro fails the second time you run
it because the names or identifiers already exist. One way to construct unique names is to create a string
parameter and use it in creating all the new names. If, for example, a macro creates three plots, use a
string parameter $pname to create three plot names such as $'pname'_1, $'pname'_2, and $'pname'_3.
Each time you run the macro, enter a new string and all the new names are unique.
If you want a special numbering scheme for the Adams identifiers, you can also pass in an integer
parameter for constructing them. It is usually easier, however, to leave them out and let Adams/View
create them automatically. If you do not specify an adams id, then it defaults to adams id=0. The next
time you write an Adams/Solver dataset, Adams/View replaces zero identifiers with unique, nonzero
identifiers.
Including a Literal "$" in a Macro

Normally, Adams/View interprets any "$" character as the start of a parameter name. You can avoid this
by using a backslash first: "\$". Adams/View deletes the "\ " and keeps the "$" as part of the macro text.
Speeding up Object References in Expressions

When Adams/View executes expressions in the macro command text, it must look up each referenced
object name in the database. Object names in expressions can refer to almost anything, so if you use a
local name such as MAR1, Adams/View must search the entire database for any object named MAR1.
This is relatively slow, and in large macros with several object references, it can consume a large portion
of the overall macro execution time.
You can drastically reduce the lookup time by using full database names in expressions within the macro.
Instead of referencing variable DV1, use .MOD1.DV1 for example. This way, Adams/View only needs
to search a fraction of the database to find the proper object.
10 Adams/View
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.
Example of a Macro with a Parameter

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:
constraint attributes constraint_name=.* size_of_icons = $size
force attributes force_name=.* size_of_icons = $size
When you enter the command:
icon_size size=1.5
Adams/View executes the commands:
constraint attributes constraint_name=.* size_of_icons = 1.5
force attributes force_name=.* size_of_icons = 1.5
Expanding Parameter Values

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:
list_info part part_name=$name
When you enter the following command:
lpart name=left_wheel
Adams/View substitutes the full name of part left_wheel (for example, .mod1.left_wheel) for $name and
executes the command:
list_info part part_name=.mod1.left_wheel
Generalized Parameter Format

The general format of a parameter is $'name:q1:q2:q3...', where:
• name is the name of the parameter.
• q1, q2, q3... are one or more qualifiers that specify the characteristics of the parameter.
The single quotes and qualifiers are optional (see below), giving four possible formats:
• $name
• $'name'
• $name:q1:q2:q3...
• $'name:q1:q2:q3...'
Parameter Naming Conventions

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. 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.
Parameter Qualifiers and Formats

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:
• Type
• Range
• Count
• Defaults
12 Adams/View
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:
Examples of Qualifiers
The qualifiers: Specify that the parameter requires:
$parts:t=part:c=2 Names for two existing parts.
$NSpokes:T=INTEGER:GE=3:LE=8:D=3 An integer from 3 to 8 and a constant default of 3.
$infile:t=file(*.dat) A file name. The File Selection dialog box lists all files
with the extension .dat.
Type Qualifier
The type qualifier specifies the type of value a user must enter. The format for the type qualifier is:
• T = type
• T = type(additional data)
where:
• type is a basic type, database object type, or database object class type as explained in the next
sections.
• Additional data is either optional or required depending on the type.
Range Qualifiers
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.
Range Qualifier Formats

The format: Specifies values must be:
GT=r Greater than r
GE=r Greater than or equal to r
LT=r Less than r
LE=r Less than or equal to r
Count Qualifiers
Count qualifiers specify the number of values required. The formats for the count qualifier are listed in
the table below.
Count Qualifier Formats

The format: Specifies:
C=0 One or more values
C=n n values
C=n,0 n or more values
C=n,m n to m values
Default Qualifiers
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:
• Constant - The parameter is optional. Adams/View uses the default value if a user does not
supply a parameter value.
• Updated - The parameter is optional and Adams/View uses the last value the user entered if the
user does not supply a parameter value. If a user has not yet entered any value for a parameter,
Adams/View uses the default value.
• Database object - The default for database objects is automatic. If the type is an existing
database object, the automatic default is the current default object.
The table below lists the formats for the default qualifiers.
Default Qualifier Formats

The format: Specifies:
D=value Constant default
U=value Updated default
A Uses the default object for the specified type if no explicit value is given
Default Parameter Characteristics

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
14 Adams/View
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.
Tip: To avoid unexpected results, we recommend that you explicitly set the characteristics of
your parameters in comments at the beginning of your macro. For examples of setting the
characteristics in comments, see Example Macros.
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.
! Parameter $text is a string.
! $numbers:t=integer:c=0:gt=0
list_info part part_name=$part_1, $part_2
list_info part part_name=$part_3:t=part, $part_4:t=part
Helpful Commands in Macros

Two commands are particularly helpful in creating macros:
• FILE TEXT WRITE
• SYSTEM
Tip: For more help on using commands, see the online help available from the Command
Navigator. Simply select a command and then select the Help button at the bottom
of the Command Navigator.
file text write

Lets you write a general-purpose text file from Adams/View, using information and formatting that you
control. You can use a text file to create:
• Standard reports
• Data files for other applications
• Adams/View command files
• Scripts for executing other applications
You can specify to write to a file, a variable, both, or neither. If writing to a file, you must open it first
using the file text open command.
If you specify:
• Just the file_name, Adams/View writes the output to that file.
• Just the variable_name, Adams/View assigns the text string to that variable.
• Both file_name and variable_name, Adams/View performs both actions.
• Neither, Adams/View assumes the last opened, written, or read file is the intended destination. If
you perform a write after a read, you should explicitly identify the file with the file_name
parameter, so Adams/View does not overwrite the file you last read from.
16 Adams/View
Parameters
file_name Specifies the name of the text file to be written. The proper extension is the
(optional) default, but you can be override it by supplying a different extension.
It's not necessary to enclose the file name in quotes if it only contains alpha-
numeric characters and starts with a letter. If you want to include other
characters, such as a '.' for an extension or '/' or '[]' for directory paths, you
must enclose the name in quotes.
variable_name Specifies a variable to which Adams/View stores a formatted string.
(optional)
format_for_output Specifies the format of the output text. Output formats are a mixture of text
(required) and conversion specifications. Each conversion specification usually has a
matching argument in the values_for_output parameter. A conversion
specification begins with a percent sign, %, and is terminated by a letter or
another percent sign.
The conversion specifications provided by Adams/View are a subset of those

used in the ANSI-C programming language. Valid conversion specifiers are:
% - Literal percent sign ("%%" is output as "%")

d - Integer in base 10, 1, or 123
e - Exponential floating point, 1.23e-04
E - Exponential floating point, 1.23E-04
f - Fixed point real, 345.67
g - General fixed or floating point (depending upon magnitude)
G - General fixed or floating point (depending upon magnitude)
i - Same as d, above
o - Unsigned integer in base 8 (o is for octal)
s - Character string
u - Unsigned integer in base 10
x - Unsigned integer in base 16 (decimal 10 is "a", 11 is "b", and so on)
X - Unsigned integer in base 16 (decimal 10 is "A", 11 is "B", and so on)
Most conversion specifications can contain flags between the leading percent
sign and the terminating conversion specifier. These flags allow you to further
refine the format of your output. Some of the valid flags are:
- Indicates that the output is to be left justified in the field, with the default
being right justification. This is only useful when the field width is specified
(see below).
+ Forces a sign to be output for all numeric values. For example:
... FORMAT="%+d %+d" VALUES=(-1), (1)

produces:
-1 +1
0 Forces output of leading zeros when a field width is specified.
" " Blank. Same as + but no explicit + sign, only a blank.
Field width is specified by prefixing the conversion specifier with a number.

It determines how much space is to be reserved for the output text. For
example, the following format and values:
... FORMAT="%03d%6d" VALUES=(5),(7)

generates the following as output ('.' is used to denote blank space in this
example only):
"005.....7"
You specify precision by entering a decimal point followed by a number. You
enter the precision after the field width. For example:
... FORMAT="%5.2f %010.3e" VALUES=(2.3),(5.4)

produces the output:
" 2.30 05.400e+00"

Values for output are converted to the appropriate type for the conversion
specifier, and using expressions is extremely useful here.
You can write information from the Adams/View database to the text file by
using data access references in the value expressions. For example,
VALUES= (.mod1.par1.mass) writes the mass of part par1. For more
information on expressions and database access, see Adams/View Function
Builder online help.
18 Adams/View
values_for_output Specifies the values to be placed in the output string.

(optional)
newline Controls whether or not file write text causes the output to terminate the line
(optional) with this write command. If newline is no, then subsequent write commands
produce output on the same line. If newline is yes (the default), then any
succeeding write command produces content on a new line.
Values are: yes and no. The default is yes.
system
Issues a device-dependent operating system command. You can select to display the results of the
command in the Information Window or the Adams/View Log file.
Parameters
command_text Specifies the text for a device-dependent operating system

command. See your operating system documentation for more
information.
send_output_to_info_window Specifies whether or not to send the output from the command
to the Information window. The default is to send the output to
the Information window (on).
echo_to_logfile Specifies whether or not to send the standard output and
standard error streams from a system command to the
Adams/View log file. The default is to not send the output to the
log file (off).
Examples
The following example issues a UNIX-appropriate command to remove the file named test.txt without
displaying the command in either the Adams/View Information window or a log file:
SYSTEM COMMAND="rm test.txt" SEND=OFF ECHO=OFF
Conditional Constructs and Loops

Learn about each of the conditional constructs in the Adams/View command language. The constructs
are listed in alphabetical order for reference.
BREAK
Use the BREAK command to exit the innermost FOR or WHILE loop immediately and stop execution
of the loop.
When Adams/View encounters a BREAK command inside a loop, it immediately exits the loop without
executing the remaining commands for that iteration.
The BREAK command affects only the innermost FOR or WHILE loop.
Format
BREAK
Example
In this example, Adams/View creates markers, named MAR1, MAR2, MAR3, MAR4, and MAR5,
unless a marker already exists with one of those names. As soon as it encounters an existing marker,
Adams/View exits the loop and does not create any more.
variable create variable_name=ip integer_value=0
while condition=(ip < 5)
variable modify variable_name=ip integer_value(eval(ip+1))
if condition=(eval(DB_EXISTS ("MAR"//ip)))
break
end
marker create marker_name=(eval("MAR"//ip)) &
location=(eval(ip-1)),0,0
end
variable delete variable_name=ip
CONTINUE
Use the CONTINUE command to skip commands inside the innermost FOR or WHILE loop and
continue with the next iteration of the loop.
When Adams/View encounters a CONTINUE command inside of a loop, it skips over the remaining
commands of the loop and goes directly to the END of the innermost loop. Adams/View tests the loop
condition and continues looping if the condition is still valid.
The CONTINUE command affects only the innermost FOR or WHILE loop.
Format
CONTINUE
20 Adams/View
Example
In this example Adams/View creates four markers on the default part: MAR1, MAR2, MAR4, and
MAR5. Adams/View skips MAR3, because when ip evaluates to 3, Adams/View encounters the
CONTINUE command and skips to the END of the WHILE loop.
variable modify variable_name=ip integer_value=(eval(ip+1))
if condition=(ip == 3)
continue
end
marker create marker_name=(eval("MAR"//ip)) &
location=(eval(ip-1)),0,0
end
The results of the example would be:
Results of CONTINUE Example
Name: Loc_X: Loc_Y: Loc_Z:

MAR1 0.0 0.0 0.0
MAR2 1.0 0.0 0.0
MAR4 3.0 0.0 0.0
MAR5 4.0 0.0 0.0
IF/ELSEIF/ELSE/END
Use the IF, ELSE, ELSEIF, and END commands to execute a group of commands conditionally. The
execution of commands bracketed by IF and END depends on the value of an expression.
You can nest any combination of looping (FOR/END, WHILE/END) and conditional constructs
(IF/ELSEIF/ELSE/END).
Note: As with all Adams/View commands, you can use the IF, ELSE, ELSEIF, and END
commands on the command line, in macros, and in command files.
Format
You can use the IF command with or without the ELSE command. A few examples of many variations
are shown below.
Tip: You can have any number of ELSEIF CONDITION commands.

IF CONDITION=(expression)
...
END
...
ELSE
...
END
...
ELSEIF CONDITION=(expression)
...
ELSE
...
END
If the expression evaluates to a non-zero value, Adams/View executes the commands following the IF or
ELSEIF command up to the ELSE, when present, or the END if you do not use the ELSE. If the
expression evaluates to zero and you used ELSE, Adams/View executes the commands between the
ELSE and the END commands.
The question-mark/colon (?:) operator used in a conditional expression replaces and IF/ELSE command
that distinguishes one of two values. The expression consists of three parts, a condition whose truth
determines which value is selected, and two expressions for the values.
condition expression ? expression a : expression b
When evaluated, the conditional takes on one of the two values. The expression that comes before the
question-mark is interpreted as boolean-valued. If it is true (non-zero), then expression a is used as the
value of the conditional, otherwise expression b is used as the value.
For example, consider the commands below:
if condition = (variable_a < variable_b) variable set variable =
variable_min real = (EVAL(variable_a)) else variable set
variable = variable_min real = (EVAL(variable_b)) end
This can be expressed more concisely by using a ?: conditional operator:
variable set variable = variable_min & real = (EVAL((variable_a <
variable_b)? variable_a : variable_b))
Example
In the following example, if the marker MAR1 exists, Adams/View modifies its location. If the marker
does not exist, Adams/View creates it and sets its location.
if condition=(DB_EXISTS ("MAR1"))
marker modify marker=mar1 location=2,0,0
else
marker create marker=mar1 location=2,0,0
end
22 Adams/View
The next example illustrates how to use ELSEIF to determine the type of object and then perform an
operation on the object based on the object's type. The example assumes that an Adams/View variable
named .mdi.org exists and its type is database object.
! Bodies
variable create variable=object_type string=(eval(DB_TYPE(.MDI.obj)))
if condition=(object_type == "marker")
interface command_builder command="marker modify marker" initial=(.MDI.obj)
elseif condition=(object_type == "point")
interface dialog display dialog=.gui.main_objecttable parameter="Points"
elseif condition=(object_type == "flexible_body")
interface dialog display dialog=.gui.flx_dia_panel parameter=(.MDI.obj)
! Constraints - complex joints
elseif condition=(object_type == "coupler" )
interface dialog display dialog=.gui.coupler_cremod parameter=(.MDI.obj)
elseif condition=(object_type == "gear" )
interface command_builder command="constraint modify complex_joint gear"
initial=(.MDI.obj)
! Constraints - Higher Pair contact
elseif condition=(object_type == "curve_curve" )
interface command_builder command="constraint modify higher_pair_contact
curve_curve" init=(.MDI.obj)
elseif condition=(object_type == "point_curve" )
interface command_builder command="constraint modify higher_pair_contact
point_curve" init=(.MDI.obj)
end
FOR/END
The FOR and END commands allow you to execute a group of commands a fixed set of times. You can
use FOR either to perform numeric iteration or to operate on a set of Adams/View objects, such as
markers or parts. Adams/View executes the commands bracketed by the FOR and END for each value
of a variable in the specified range or upon the specified set of objects.
(IF/ELSEIF/ELSE/END).
Format
Using FOR/END to Perform Numeric Iteration

To perform numeric iteration, use this form of FOR/END:
FOR VARIABLE_NAME=var START_VALUE=REAL &
INCREMENT_VALUE=REAL &
END_VALUE=REAL
...
END
Adams/View executes the commands between the FOR and END for each value of var, in the range
START_VALUE to END_VALUE. At the beginning of the FOR loop, Adams/View creates a temporary
Adams/View variable named var of type REAL. Adams/View deletes the variable when the loop
terminates. If you use the loop variable in an expression that requires it to persist, Adams/View issues a
warning message and does not delete the variable at the termination of the loop. If you do not want this
behavior, you can use the EVAL function as described in Examples of Numeric Iteration for FOR/END.
START_VALUE, INCREMENT_VALUE, and END_VALUE can be any valid real expression.
INCREMENT_VALUE can be either positive or negative, and defaults to 1.0 if not specified. If
INCREMENT_VALUE is positive, Adams/View increments the value of var by the increment for each
iteration and stops looping when the value of var is greater than END_VALUE.
If INCREMENT_VALUE is negative, Adams/View decrements var by the increment for each iteration
and continues looping until var is less than END_VALUE.
The commands inside the FOR/END loop can use var as they would any other Adams/View variable of
type REAL.
Examples of Numeric Iteration for FOR/END:

In this example, Adams/View creates 10 markers, MAR1 through MAR10, on the default part, and
locates them one unit apart on the x-axis of the part's coordinate system.
for variable_name=tempreal start_value=1 end_value=10
marker create marker_name=(eval("MAR" // RTOI(tempreal))) &
location=(eval(tempreal-1)), 0, 0
end
The example demonstrates the use of the EVAL function when you want to assign the instantaneous value
of an expression rather than the expression itself. An expression's value changes whenever the value of
any variable in it changes. Sometimes you want this behavior; other times you do not. Using EVAL
avoids this behavior.
When Adams/View applies EVAL to an expression, it obtains the current value of the expression. For
example, when you use EVAL with the expression (tempreal-1), Adams/View assigns 0.0 to the x
component of the location for MAR1, 1.0 to MAR2, and so on. Without EVAL, Adams/View assigns the
expression, (tempreal-1), to the x component of the location, resulting in all the markers having locations
at (9, 0, 0) at the termination of the FOR loop. Another effect is that Adams/View does not delete the
variable tempreal when the FOR loop terminates, because the locations of the markers still depend on it.
The locations change again if you subsequently assign a different value to tempreal.
Using FOR/END To Operate on a Set of Objects

Use the following form of FOR/END to operate on a set of objects (for how to view the list of database
object types, see Database Object Type):
FOR VARIABLE_NAME=var OBJECT_NAMES=objects &
TYPE=database_object_type
...
END
For this type of FOR loop, Adams/View creates a temporary Adams/View variable named var of type
OBJECT and successively assigns the value of each object in the set to the variable. The commands
inside the FOR/END pair can use var as they would any other Adams/View variable of type OBJECT.
Adams/View deletes the variable when the loop terminates.
24 Adams/View
In this example Adams/View renumbers the Adams IDs of markers belonging to the part follower,
starting at 5000, and incrementing by one for each marker in the set.
for variable_name=the_marker object_names=.fourbar.follower.*
type=marker
marker modify marker_name=(eval(the_marker))
adams_id=(eval(ip))
end
As in the previous example, you can use the EVAL function to get the instantaneous value of an
expression rather than assigning the expression itself.
As shown, you can use wildcards to specify the objects for the OBJECT_NAME parameter. The TYPE
parameter applies a filter to the set of objects, in this case, matching only children of the part that are
markers.
If you use a more general wildcard, Adams/View may execute the command more slowly than if you use
a more specific wildcard. For example, if you want all the markers in the model MOD1, use
OBJECT_NAME=.MOD1.* type=MARKER instead of OBJECT_NAME=* type=MARKER.
For more sophisticated searching and filtering, see the database functions, such as DB_CHILDREN, in
the Design-Time Functions section of the Adams/View Function Builder online help. You also may want
to use the miscellaneous function SELECT_OBJECT of the same guide.
WHILE/END
Use the WHILE and END commands to execute a group of commands zero or more times. Adams/View
executes the commands that WHILE and END bracket repeatedly until the condition associated with the
WHILE command is FALSE (zero).
(IF/ELSE/ELSEIF/END).
Format
The format of the WHILE command is:
WHILE CONDITION=(expression)
...
END
Adams/View evaluates the value of expression and executes the commands between the WHILE and the
END command if the value is non-zero. Adams/View evaluates the expression at the end of the loop and
continues looping as long as the value of the expression is non-zero.
Examples
In this example, Adams/View creates 10 markers, MAR1 through MAR10, on the default part, and
locates them one unit apart on the x-axis of the coordinate system.
marker create marker_name=(eval("MAR"//ip+1)) &
location=(eval(ip)),0,0
end
You can use the EVAL function to get the value of an expression rather than assigning the expression
itself. Use of the EVAL function with loops is described in the FOR/END.
RETURN
Use the RETURN command to exit a command file or macro and return to the command file or macro
that invoked it. Its effect is similar to BREAK when you use it to exit a loop, skipping all remaining
commands in the command file or macro (including any cleanup commands you may have at the end of
your macro).
If a RETURN is executed within loops (nested to any depth), it exits those loops and performs all required
cleanup, just as multiple BREAKs would do. You can have as many RETURN commands in your
command files or macros as you want.
Format
RETURN
Example
RETURN is often used as a means for recovering from an error condition or allowing a user to cancel an
operation. Below are two examples.
Example 1
In the example, the RETURN command lists information on the contents of the select list, but only if
there are objects on the list. If it finds no objects, it returns and issues an error message.
if condition=(DB_COUNT(.SELECT_LIST, "objects_in_group")==0)
mdi gui_utl_alert_box_1 type="Error" text="Select List is
empty. Select objects first."
return
end !if
!
info empty
!
list_info group &
group_name = .SELECT_LIST &
brief = on &
26 Adams/View
write_to_terminal = on
!
Example 2
This example macro determines if a particular file exists and asks the user if it should overwrite the
existing file.
variable create variable=$_self.fileName string="file.dat"
if condition=(file_exists($_self.fileName))
if condition=(alert("warning", "Delete existing
"//$_self.fileName//"?", "Ok", "Cancel", "", 2) == 2)
variable create variable=$_self.junk &
int=(alert("information", "File "//$_self.fileName//" not
destroyed.", "Ok", "", "", 1))
variable delete variable=$_self.*
return
end
variable create variable=$_self.junk &

int=(alert("information", "File "//$_self.fileName//" was
destroyed.", "Ok", "", "", 1))
end
! Write the new file.

file text open file=($_self.fileName) open_mode=overwrite
file text close
! Clean up.
variable delete variable=$_self.*
Ternary Conditional Operator

The ternary conditional operator used in a conditional expression replaces an IF/ELSE command that
distinguishes between one of two values. The expression consists of three parts: a condition whose truth
determines which value is selected, and two expressions for the values.
Format
condition expression ? expression a : expression b
When evaluated, the conditional takes on one of the two values. The expression that comes before the
question mark is interpreted as Boolean-valued. If it is true (nonzero), then expression a is used as the
value of the conditional, otherwise expression b is used as the value.
Example
For example, consider the commands below:
if condition = (variable_a < variable_b)
variable set variable = variable_min real = (EVAL(variable_a))
else
variable set variable = variable_min real = (EVAL(variable_b))
end
Interface 27
You can express this more concisely using the ternary conditional operator:
variable set variable = variable_min &
real = (EVAL((variable_a < variable_b)? variable_a : variable_b))
Note: The ternary conditional operator has lower precedence than all other operators. Any
operations performed in sub expressions are performed before the ternary operator is
evaluated:
x < 10 ? x + 10 : x * 10
is the same as:
(x < 10) ? (x + 10) : (x * 10)
Likewise:
s == "Bob" ? "Hello" : "Goodbye" // ", " // s
is evaluated as:
(s == "Bob") ? ("Hello") : ("Goodbye" // ", " // s)
Interface
28 Adams/View
About Adams/View Menus and Dialog Boxes

Many of the windows, menus, and dialog boxes you see in Adams/View are interface objects in the
Adams/View Modeling database. Using Adams/View commands, the Menu Builder, and the Dialog-Box
Builder, you can modify, delete, or add to the standard windows, menus, and dialog boxes. You can make
changes such as:
• Remove menu entries that you seldom use.
• Add a new shortcut menu to display a standard dialog box that you often use.
• Add a set of menus and dialog boxes to execute your own macros or command files. (For more
on macros, see Automating Your Work Using Macros.)
• Create a custom interface for your particular Adams application, perhaps simplifying virtual
prototyping for novice users.
Note: You cannot customize all Adams/View dialog boxes and tools. For example, you cannot
customize the Plugin Manager or the Information window. The Dialog-Box Builder's
Dialog Box -> Open menu provides access to those dialog boxes, containers, and toolbars
that you can customize.
Adams/View Interface Objects

Most of the Adams/View interface is stored in the Modeling database in a hierarchy similar to that of
modeling objects. All standard, customizable interface objects are stored under a library named GUI. The
library is a convenient place to collect all the standard interface objects.
The two top-level interface objects are windows and dialog boxes. The main modeling window, for
example, is named main. Its full database name is .gui.main.
Windows and dialog boxes look similar, although they are quite different. Windows usually stay on the
screen for some time as you work in them, while dialog boxes come and go as you need to enter data or
access controls. Windows can contain toolbars and menu bars. Both windows and dialog boxes contain
other interface objects such as buttons, labels, and so on.
Most customizing involves creating new dialog boxes or modifying standard dialog boxes. Unless you
are creating an entirely custom interface, you will not need to modify the standard windows themselves.
You may want to modify the menu bars, menus, and toolbars.
Dialog boxes and toolbars can contain interface objects such as labels, fields, buttons, toggle buttons,
radio boxes, option menus, and sliders. In addition, containers and button-stack objects allow you to
group other objects.
Most of the modeling menus and dialog boxes ar e available in the database, and you can customize these.
Some dialog boxes are controlled entirely from within Adams/View. These do not appear in the database,
and you cannot customize them. They include:
• Database Navigator
Interface 29
• Dialog-Box Builder
• Command Navigator
• Data Browser in the plotting window
• File Selection dialog box
• Coordinate window
• Plugin Manager
List of Interface Objects

Below is a list of objects you can add to dialog boxes and their intended uses.
Object: Does the following:

Label Displays text or an image in a dialog box.
Field Provides space where you can enter text or numbers.
Button Activates an operation; has a picture (icon), label, or text on it, indicating what the
operation is.
Toggle Button Indicates an active status.
Separator Draws a horizontal line. Does not allow application interaction.
Slider Sets the numerical value of an object without having to type in data.
Option Menu Allows one of many selections; with a push graphic to allow the entire list to
appear.
Radio Box Sets states or modes.
Button Stack Allows multiple buttons to come up so you can select one by clicking and dragging
the right mouse button.
Container Allows overlaid information.
Tab Container Similar to a container but can be added to a dialog box or another container. When
you add a tab container, a tab appears in the parent container.
Data Table Displays numbers and allows you to add columns or rows.
30 Adams/View
Hierarchy of Interface Objects

Interface 31
Examples of Interface Objects
How the Interface Works

As you use the Adams/View interface to make changes to your model, the interface executes
Adams/View commands. For example, if you use a dialog box to change a spring's stiffness, when you
select OK, the interface issues the commands to modify the spring object, including the spring stiffness
you specified in the dialog box. You can see these commands in the Command window or in the
Adams/View Log file.
You control the behavior of your custom interface by programming commands for it to issue. For
example, you specify the commands a button executes when the user selects it. Fields, option menus,
radio boxes, toggle buttons, and sliders can also execute commands.
There are no restrictions on the commands that the interface can execute. A button can change your
model, display a dialog box, or change another setting or object in the dialog box. It can also execute a
macro you wrote. Adams/View macros allow you to create your own commands that automate complex
or repetitive procedures. For more information on macros, see Automating Your Work Using Macros.
Changing the Interface

The Menu Builder and Dialog-Box Builder are interactive tools that you can use to customize the interface.
They allow you to quickly access and change most Interface objects and capabilities. Using these, you
can do a great deal of customization without going into the details of the interface commands and how
they are stored.
The command interface in the Command Navigator contains full creation, deletion, and modification
commands for all the interface objects. These commands give you access to all capabilities, some of
which are not available from the builders. You will find these commands useful within the interface itself
to display objects, change settings, or change appearances depending on a user's input.
32 Adams/View
Saving Interface Changes

There are several ways to save your interface changes. One option is to save the objects in the standard
Modeling database, aview.bin, or in any modeling database you create. Whether you save your changes
in the standard modeling database or your own depends on the extent to which you want the menu
changes available in future work:
• Storing the changes in the standard modeling database aview.bin makes the changes available
whenever a user starts Adams/View.
• Storing the changes in a particular modeling database makes the menus available only when a
user opens that database.
Another option is to save the new or modified objects in a command or menu text file that you can reload
as needed. The Dialog-Box Builder’s Export command writes a dialog box to an Adams/View command
file. To reload this file, use the Import command or the file command read command to read the
command file. This is the most reliable way of making your GUI customization upwardly compatible in
future versions of Adams/View.
The Menu Builder Export Text menu writes the text outline for the menu to a text file. To reload the
menu, use the Menu Builder Import Text menu or the interface menubar read command to read the
text file into a menubar.
For a comparison of modeling databases and command files, see Comparison of Adams File Formats. For
information on using aview.cmd to execute commands automatically when you start Adams/View, see
Running and Configuring Adams.
Interface 33
Customizing Menus Using the Menu Builder

You can use the Menu Builder to modify and create menus to better suit your needs and preferences. With
the Menu Builder, you can change the structure of an existing menu to match your industry's terminology
or create new menus. For example, you can use the Menu Builder to change the main window's menu bar
so it includes a Tire menu for adding tires to your model. You can build menus for a particular model or
for an entire application.
When you create menus in Adams/View, you can specify keyboard accelerators (shortcuts) and
mnemonics.
Menu Entry Syntax

The Menu Builder uses an outline-like format to display menus. You modify the menus by directly
editing the text outline.
Each line defines an object and its name, or specifies information about the parent object. For clarity,
Adams/View indents the lines. As you edit the text, you can also indent the lines.
34 Adams/View
There are four types of objects in menus: menus, push buttons or icon buttons, toggle buttons, and
separators. The text lines that define these are shown in the table below. Click a text line to learn more.
Text Lines Defining Objects

The text line: Its parameter is:
MENUn label
BUTTONn label or name of icon file
TOGGLEn label
SEPARATORn (none)
The text lines have the following parameters:

• n is an integer between 1 and 10, usually 1, 2, or 3. It defines the menu level in which the object
appears. Level 1 is the first level. MENU1 appears on the menu bar, for example, while
BUTTON2 appears under the preceding MENU1. The n is required for MENU, but is optional
for the other objects. If you omit the level, Adams/View assumes the object belongs under the
last MENU.
You can cascade menus up to 10 deep by nesting MENUs below other MENUs. You can include
as many buttons in a menu as you want, although you should not create more than will fit on
your screen.
• label is the text that appears in the menu. For an icon button, you specify the icon name instead
of the text. In Motif, the icon name is the name of a XBM (X BitMap) or XPM (X PixMap)
format file. In Windows, the icon name is the name of a bitmap (.bmp) format file.
labels can contain ampersand (&) characters that specify keyboard mnemonic shortcuts for a
menu item (for example, ALT-F opens the File menu).
Note that with the exception of CMD=lines, spaces are not permitted in the menu structure input.
Therefore, NAME = my_menu is not valid, but NAME=my_menu is. This differs from Adams/View
command language where spacing rules are flexible.
The following shows a portion of the Menu Builder could be used to define a Help menu in Adams/View.
To the right of the Menu Builder is the corresponding Help menu as it appears in Adams/View.
Interface 35
Menu Builder and Corresponding Help Menu
MENU1 &Help NAME=help

HELP=Get Help on Adams
BUTTON2 &Toggle Tip Text
NAME=tips
HELP=Toggle popup descriptions on/off
CMD=help tips=toggle
SEPARATOR2
BUTTON2 Adams/View &Help
NAME=view_help
HELP=Help for Adams/View
CMD=interface help file="view/view_hlp/view_home.htm"

BUTTON2 &Other Product Help
NAME=other_help
HELP=Help for other products
CMD=interface help file=products.htm"
SEPARATOR2
BUTTON2 &About...
HELP=Display product info
CMD=int dia disp dia=.gui.about_adams
MENU
A MENU entry creates a pull-down or pull-right menu. First-level menus, MENU1, appear in the menu
bar and pull downward. Lower-level menus, such as MENU2 and MENU3, appear as cascading pull-
right menus.
Syntax
MENUn TITLE
NAME=name
HELP=Help
Parameters
• n = Number identifying whether the menu appears on the menu bar or on a pull-down menu. Can
be either:
• n = 1 - Menu appears on menu bar.
• n 2 - Menu appears on pull-down menus.
• TITLE = Text string that appears in the menu bar. You can also place an & in the title in front of
the letter to be used as the keyboard mnemonic (for example, enter &File to have the resulting
menu be File and the mnemonic would be Alt+F).
• NAME = Name of the object in the modeling database. If you omit NAME, Adams/View
constructs a default identifier, such as MENU_4 or BUTTON_7.
36 Adams/View
• HELP = Text that appears in the status bar and in the tool tips, and describes the menu group.
Example
MENU1 File
NAME=file
HELP=Read and write files
BUTTON (Menu Command)

A BUTTON entry defines a menu command. You can place a button either on a pull-down menu or on a
sub-menu. BUTTONS can specify an accelerator key (for example, Ctrl+M, Shift+G, or F12) that
invokes the button's action.
Syntax
BUTTONn LABEL :: ACCELERATOR
NAME=name
HELP=help
CMD=command
Parameters
• n = Number identifying the placement of the button. Can be either:
• n = 2 - Button appears on pull-down menu.
• n = 3 - Button appears on a sub-menu.
• LABEL = Button name that appears in the pull-down or sub-menu. By convention, you should
include ellipsis (...) after the button name if the button displays a dialog box. You can also place
an & in the label in front of the letter to be used as the keyboard mnemonic (for example, enter
&Save to have the resulting menu command be Save and its mnemonic be Alt+S.)
• ACCELERATOR = Key or series of keys that execute the menu command. To create a series of
keys, you use the Shift, Ctrl, or Alt keys followed by the plus symbol (+) and any letter (a to z)
or function key (F1, F2, and so on). No spaces can be between any of the keys (for example,
Alt+A, instead of Alt + A).
The Shift, Ctrl, and Alt keys are case sensitive (the first letter must be capitalized), while the
key letters are not (user can enter A or a). You also can group the Shift key with the Ctrl and Alt
keys (for example, Shift+Ctrl+A). If you combine the keys, the Shift key must be executed first.
• NAME = Name of the menu object in the modeling database. If you omit NAME, Adams/View
constructs a default identifier, such as MENU_4 or BUTTON_7.
• HELP = Text that appears in the status bar or tool tips describing the button.
• CMD = Command, sequence of commands, that the button executes.
Note: Multiple-line commands need CMD before each line.

Interface 37
Example
BUTTON2 &Export
NAME=export
HELP=Write data to file
CMD=interface dialog_box display dialog_box_name=.gui.file_export
TOGGLE
A toggle creates a menu entry that toggles between two states. It creates a check mark depending on the
state value (on or off). Make sure that if you create a toggle, you maintain its state. A TOGGLE can be
on a pull-down or sub-menu.
Syntax
TOGGLEn TITLE
NAME=name
HELP=help
STATE=state
CMD=command
Parameters
• n = Number identifying the placement of the toggle. Can be either:
• n = 2 - Toggle appears on pull-down menu
• n = 3 - Toggle appears on a sub-menu
• TITLE = Toggle name that appears in the pull-down or sub-menu.
• NAME = Text that identifies the toggle so that you can define keyboard shortcuts and
mnemonics for it. If you omit NAME, Adams/View constructs a default identifier, such as
MENU_4 or BUTTON_7.
• HELP = Text that appears in the status bar or tool tips describing the toggle.
• STATE = Current state of toggle (on or off).
• CMD = Command to execute.
SEPARATOR
A separator creates a horizontal line between menu entries on either a pull-down or sub-menu to indicate
groups of comments.
Syntax
SEPARATORn
Parameters
• n = Number identifying the placement of the separator. Can be either:
• n = 2 - Separator appears on pull-down menu
38 Adams/View
• n = 3 - Separator appears on a sub-menu
Example
SEPARATOR2
Creating or Modifying a Menu

The Menu Builder lets you create and modify menu bars for existing Adams/View windows. If you don't
want to use the Menu Builder to create and modify menus, you can create a text file that defines a menu
and then import that text into the Menu Builder.
To create or modify a menu in the Menu Builder:

1. On the Tools menu, point to Menu, and then select Modify.
The Menu Builder appears, displaying the main menu.
2. Scroll to the menu you want to modify or to the location where you want to add a menu.
3. Type in your changes.
4. From the Menu Bar, select Apply.
Restoring a Customized Menu

There are two menu commands that read in your customized menus:
• Read local Main Menu - Reads in the file main.mnu, which must be located in the local
directory (the directory where you started Adams/View or the current directory set using the
commands File - Select Directory).
• Read - Reads in a .mnu menu file of any name and location.
These menu commands are helpful if you have a new version of Adams/View or created a new Modeling
database and want to read in your customized menus.
To read a main.mnu file in the local directory:

• From the Tools menu, point to Menu, and then select Read local Main Menu.
To read in any .mnu file:

1. From the Tools menu, point to Menu, and the select Read.
2. Enter the name and location of the file.
3. Select OK.
Interface 39
Importing and Exporting Menus

You can import text from a .mnu file at the current position of the cursor in the Menu Builder. You can
also export the menu to a .mnu text file, for example, for review by others or use in another Modeling
database.
To import text:
1. In the Menu Builder, place the cursor at the location you want to bring in the text.
2. From the Menu Builder File menu, select Import.
3. Enter the name and location of the text file containing the menu text.
4. Select OK.
Loading a Menu into the Menu Builder

After opening the Menu Builder, you can load any .mnu menu file in the current modeling database for
editing or review. After loading the menu, Adams/View also displays it in its window.
To load a menu into the Menu Builder:

1. From the Menu Builder File menu, select Load.
The Database Navigator appears with a list of menus in the modeling database.
2. Select the desired menu, and then select OK.
40 Adams/View
Customizing Dialog Boxes Using the Dialog-Box Builder
Customizing Dialog Boxes Using the Dialog-Box

Builder
Adams/View uses dialog boxes that contain a variety of Interface objects, such as labels, fields, buttons,
and more. You can use the Adams Dialog-Box Builder to create and modify dialog boxes to better suit
your needs and preferences. For example, you can add a new button to a standard dialog box that selects
options you commonly use, or create a new dialog box to execute special procedures you run often,
including one or more macros.
Creating Dialog Boxes

To create a dialog box:
1. On the Tools menu, point to Dialog Box, and then select Create.
The Dialog-Box Builder appears.
2. On the Dialog Box menu in the Dialog-Box Builder, select New.
3. Enter the library to which the new dialog box should belong. By default, it belongs in the library
.gui.
4. In the Name text box, enter a title for your dialog box.
5. Select any predefined buttons you'd like on your dialog box.
6. Select OK.
A new dialog box appears.
Modifying Dialog Boxes

Once you create a dialog box, the Dialog-Box Builder changes to modify mode. You can then add a variety
of interface objects to the dialog box, as well as customize the layout, appearance, commands, and size
of the objects in the dialog box.
Interface 41
To modify an existing dialog box:

1. On the Tools menu, point to Dialog Box, and then select Modify.
2. Select the desired dialog box.
The Dialog-Box Builder appears.
3. Modify the dialog box as desired.
Tip: After displaying a dialog box from the Tools menu, you can double-click the
background of a displayed dialog box to display the Dialog-Box Builder and modify
the dialog box.
Renaming Dialog Boxes

To rename a dialog box:
1. From the Tools menu in the Dialog-Box Builder, point to Dialog Box, and then select Modify.
2. Select the desired dialog box by double-clicking the name. The Dialog-Box Builder appears.
3. From the Dialog Box menu, select Rename.
4. Enter a new name for the dialog box.
5. Select OK.
Adding Interface Objects to Dialog Boxes

Learn about:
• Adding Objects
• Adding Predefined Objects
• Adding Images
Adding Objects
You can add Interface objects to your dialog box.The instructions for adding objects to your dialog box
are the same for all types of objects.
To add interface objects to a dialog box:

1. On the Create menu in the Dialog-Box Builder, select the object you want to add.
2. Place the cursor in the dialog box to which you are going to add the object.
3. Hold down the left mouse button and drag to create your object.
42 Adams/View
You can also click the left mouse button, and Adams/View creates an object of default size.
Example of Adding an Object to a Dialog Box
Adding Predefined Objects

You can add more standard buttons to your dialog box even after you've created several using the
Predefined menu. For example, if you did not place an Apply button on your dialog box and would like
to add one after you created your dialog box, you can do so from the Predefined menu.
To add a predefined object:

• On the Create menu, point to Predefined, and select a predefined object to add.
Adding Images
You add an image to your dialog box just as you add a label. The image format for the label must be:
• Motif - .xbm (X BitMap) or .xpm (X PixMap)
• Windows - .bmp (must be a 16-color bitmap)
You cannot size the image in the Dialog-Box Builder. Therefore, if you want to fill the entire dialog box,
you'll need a very big image.
For sample images, see the directory /install_dir/aview/bitmaps where install_dir is the directory where
you installed your Adams products.
To add an image:
1. On the Create menu, select Label.
2. Draw the label so it fits the size of the image.
3. Double-click the label to activate it.
Interface 43
4. From the option menu, select Appearance.

5. Clear the value in the Label Text box.
6. In the Icon File box, enter the path to and name of the image.
7. From the Justified option buttons, select the alignment for the image.
8. Select Apply.
Tip: To see the image, you may need to select Test Box from the Options menu.
Moving Interface Objects

You can move Interface objects:
• Using the mouse.
• By entering coordinate locations in the Dialog-Box Builder.
• Using the Arrow tools in the Dialog-Box Builder. The tools move objects
to the edges of the dialog box or to the edges of other objects. The tools are located along the top
of the Dialog-Box Builder.
Learn about Setting Distance Between Interface Objects.
To move objects using the mouse:

1. Select the object to move by clicking it. If you want to select more than one object, hold down the
left mouse button and drag across all the objects you want to select.
You can also click the middle mouse button to select more objects.
2. Hold down the left mouse button, with the cursor over a selected object, and move the mouse in
the direction you want to move the object.
The selected object or objects move as you move the mouse.
To move objects using coordinate locations:

1. Select the object to move by clicking it.
2. On the Edit menu, select Attributes to load the object’s attributes for that object into the Dialog-
Box Builder.
You can also double-click on the object to select and load its attributes at the same time.
3. If it is not already selected, set Attributes to Layout.
4. In the Left: and Top: boxes, enter your coordinate values. The lower the value, the closer your
object is to the upper left corner of your dialog box or container.
5. From the Units option buttons, select the type of locations you entered in Step 4. You can define
the location of the objects by entering absolute pixel locations (Absolute) or relative locations
(Relative) as a percentage of the parent object.
44 Adams/View
6. Select Apply.
To move objects using the Arrow tools :

1. Select the object or objects to move.
2. Select the Arrow tool indicating the direction in which to move your object.
The object moves next to the edge of the dialog box. If another object is in the way, the selected
object stops next to that object.
Resizing Interface Objects

Adams/View provides several ways to resize your Interface objects, as described below. The tools are
located along the top of the Dialog-Box Builder.
To increase the size of objects using the last four arrow icons on the
Dialog-Box Builder toolbar:
1. Select the object(s).
2. Click on the arrow icon indicating the direction in which you want to increase your object(s).
To resize objects in small increments using the mouse:

1. Double-click on the object.
Adams/View selects the object and displays reshaping handles around it.
2. Increase or decrease the size of your object by moving the reshaping handles.
To resize objects by entering measurements in the Dialog-Box Builder:

1. Select the object.
2. On the Edit menu, select Attributes to load the object’s attributes for that object into the Dialog-
Box Builder window.
You can also double-click on the object to select and load its attributes at the same time.
3. Set Attributes to Layout, if it is not already selected.
4. Enter measurements in the Width: and/or Height: boxes.
Interface 45
5. Select Apply.
To make two or more objects the same height or width with respect to the first object
you select:
1. Select the objects. The height and width are with respect to the first object you select.
2. Select one of the following:
• Height tool to make objects the same height.
• Width tool to make objects the same width.
To make two or more objects identical in size, as well as align them:

1. Select the objects. The alignments are with respect to the first object you select.
2. Select one of the following:
• Horizontal Alignment tool to make the objects identical in size and align them
horizontally.
• Vertical Alignment tool to make the objects identical in size and align them vertically.
46 Adams/View
Aligning Interface Objects

You can use the Alignment tools to align Interface objects with respect to the first
object you select. The tools are located along the top of the Dialog-Box Builder.
To align dialog box objects:

1. Use the middle mouse button to select one or more objects.
2. Select the appropriate alignment tool.
Setting Distance Between Interface Objects

In the Dialog-Box Builder, you can specify the distance between Interface objects and their distance from
the border of the dialog box.
To set distance between objects:

1. From the Preferences menu on the Dialog-Box Builder, select Separation.
Interface 47
2. Enter a value for Horizontal and Vertical Border Width to specify the distance from the object
to the dialog box border.
3. Enter a value for Horizontal and Vertical Separation to specify the distance between other
interface objects.
Restricting the Size and Position of Interface Objects

In the Dialog-Box Builder, you can restrict the size and position of Interface objects by using the Snap
Grid option. It works similar to the grid in the modeling window. When you drag an item with the mouse
to move or resize it, the mouse position will snap to the nearest grid point.
Note: Because the snap grid points are not visible, and the default grid is very fine (2 pixel
distance), snapping is not very noticeable by default.
To restrict the position and size of objects:

1. On the Preferences menu on the Dialog-Box Builder, select Snap Grid.
2. Enter values for the Horizontal and Vertical Grid Spacing to set the spacing distance between
grid points.
3. Enter values for the Horizontal and Vertical Grid Offset to set where to begin snap grid points
from the top and left borders.
Deleting Interface Objects

To delete interface objects from a dialog box in the Dialog-Box Builder:
1. Select the interface object you want to delete.
2. On the Edit menu in the Dialog-Box Builder, select Delete.
Adding Online Help to Your Dialog Box

You can add an online help file to your dialog box by linking an HTM or HTML file to your customized
dialog box
Note: The following steps only include instructions for linking your dialog box to a help file; they
do not explain how to create HTML help files. Refer to HTML reference guides.
To attach a help file to your dialog box:

1. From the Attributes option menu, select Help.
48 Adams/View
2. In the Tip Text text box, enter the text you want displayed in the Status toolbar (at the bottom of
the Adams/View window) when your dialog box is open.
3. In the Help File text box, enter the complete path and file name of your help file.
Note: You do not need to complete the Help Link text box. It is used for backward
compatibility only.
Using Commands in Dialog Boxes

Most objects have commands that Adams/View executes when the object changes or a user selects it.
These commands do the real work of the interface, changing your model or changing the interface as
users enter data and make selections.
Learn more about using commands in dialog boxes:
• Viewing and Generating Object Commands
• Substituting Text into Commands
• Conditional Command Expansion
• Special Commands for Windows, Dialog Boxes, and Containers
• Editing Commands
Viewing and Generating Object Commands

You use the Adams/View command language to create commands for objects. You can use the Command
Navigator to find the commands you need. Once you find the commands, copy the commands from the
command window or log file, and paste or type them in to the command text box for the dialog box
object.
You can view and edit the commands in an existing dialog box. Some objects have more than one set of
commands. Push buttons, for example, have commands for a single-click and additional commands for
a double-click. Note that single commands are executed even on double-click. Windows, dialog boxes,
and containers also have special sets of commands which are described below.
To view the commands for an object:

1. Double-click an object containing the commands you want to view.
2. From the Attributes pull-down menu, select Commands.
Substituting Text into Commands

Before executing the commands, Adams/View performs several types of text substitutions. These
substitutions let you include values from interface objects into commands. For example, you can include
a value a user has entered in a text box.
Interface 49
Include identifiers starting with the symbol $, to indicate where to substitute text. There are four kinds of
substitutions:
$object_name $object_name refers to an interface object whose name is the same as

object_name. When Adams/View executes the command, it substitutes the
current value of object_name for $object_name. For example, $my_field
substitutes the value of the interface object my_field. The following table lists
the values for different interface objects:
IFor example, to include the contents of the field my_value in a command, you
enter:
my_command my_parameter = $my_value
If the field contains 123, then Adams/View executes the command:
my_command my_parameter = 123
By default, the value of an option menu or radio box is the text of the displayed
or selected button. By default, the value of a toggle is on or off.
You can specify other values for Adams/View to substitute. In the toggle
button Value attributes, there are fields to set the toggle values. In the Option
Menu and Radio Box Value attributes, you can add a substitution value after
the text for each choice, separated by a vertical bar "|". The values do not affect
the displayed text; they are only used in commands.
The Object: Has the value:
Field Contents of field
Option-menu Selection of value for current selection
Radio-box Selection or vale for current selection
Toggle button On/off or specified on/off value.
Slider Integer slider value
50 Adams/View
$_value $_value substitutes the value of the object that contains the command. For
example, if the commands are on a button named my_toggle, $_value is the
same as $my_toggle. Another example might be if you want to create a toggle
button that returns a value of "1" or "0". You would do so with commands like
the following:
if condition=($_value)
! commands executed when user turns on toggle
else
! commands executed when user turns off
toggleend
Wherever possible, you should use $_value instead of the name of the actual
object because it is easier to understand and maintain since it does not rely on
the name of the object holding the command. If you see $_value in a
command, you know immediately that it refers to the value of the interface
object. In addition, if you change the name of the object, you do not need to
change the commands. You will find this especially helpful for toggle buttons,
radio boxes, and option menus, where you almost always want the value of the
object in the associated commands.
$_self, $_parent, These substitute the name of the object executing the commands, the object's
$_topgui immediate parent, or the parent dialog box, window, or toolbar. When
Adams/View executes the commands, it substitutes the full database name of
the appropriate object.
$_self, $_parent, and $_topgui help you make your dialog boxes easier to read
and maintain. For example, a dialog box can load one of its child fields with
this command:
interface field set field=$_self.myfield

strings=...
If you use this command and you rename the dialog box, you don't have to
change the command. Wherever possible, it's a good idea to make your object
names refer to $_self or $_parent rather than literal full names.
Note that $_value and $_self are different, but easy to confuse. $_value inserts
the value of the object, $_self inserts the name of the object.
Interface 51
$_1, $_2, $_3,... These refer to parameters passed with a window or dialog-box display
command.
The window or dialog-box, and any child of the window or dialog box, can
include $_1,... in the commands. When Adams/View executes the commands,
it substitutes the current value of the parameter. This allows you to pass
information to a window or dialog box as you display it. You might, for
example, pass the name of an object to a dialog box. Commands executed by
the dialog box or objects in the dialog box can then refer to this object.
$_1, $_2, $_3,... These refer to parameters passed with a window or dialog-box display
command.
The window or dialog-box, and any child of the window or dialog box, can
include $_1,... in the commands. When Adams/View executes the commands,
it substitutes the current value of the parameter. This allows you to pass
information to a window or dialog box as you display it. You might, for
example, pass the name of an object to a dialog box. Commands executed by
the dialog box or objects in the dialog box can then refer to this object.
Conditional Command Expansion

Back quotes contain a conditional substitution. If any $name or $value substitution inside the quotes is
empty, then Adams/View removes the text between the . $name is empty if the text returned is empty
( ) or if the object is disabled or not displayed.
Conditional substitution makes it easier to handle optional or mutually-exclusive parameters in
commands. For example, if you use a command such as the following and the user does not supply a
value, the command fails:
my_command my_parameter = $my_value ...
Instead, if you use a command like the following Adams/View only includes my_parameter =
$my_value, if the user has entered a value:
my_command my_parameter = $my_value ...
The same technique handles mutually-exclusive parameters. As long as the parameters are wrapped in
, and only one option is displayed or enabled at a time, the command only includes the displayed
parameter.
Example
Conditional expansion allows for the commands for custom interface objects to ignore parameters in
which the user does not enter any value. Back quotes [ parameter=value ] indicate parameters that will
be collapsed when the command is executed. This makes the resulting custom interface object easier to
use and relieves you from having to handle error checking for empty fields.
52 Adams/View
The Easy Beam Properties custom dialog box below shows how conditional expansion can be used.
The command for this dialog box modifies the indicated beam's properties as shown below:
force modify element_like beam &
beam_name = $f_beam_name &
youngs_modulus = $f_youngs_modulus &
shear_modulus = $f_shear_modulus &
damping_ratio = $f_damping_ratio
The problem with this configuration is that the user must enter all of the fields in the dialog box or the
entire command fails. For example, if the user left the Damping Ratio Field blank, its command would
fail with the following error:
ERROR: ---------------------------------------
ERROR: Invalid input. Enter a number.
ERROR: The command was not executed.
ERROR: &> damping_ratio =
ERROR: -------------------------------
If the command is modified to incorporate conditional expansion, the user could leave fields blank
without affecting the execution of the command.
To add the conditional expansion, you add back quotes ( ) for each parameter. The resulting command
looks like the following:
beam_name = $f_beam_name &
youngs_modulus = $f_youngs_modulus &
shear_modulus = $f_shear_modulus &
damping_ratio = $f_damping_ratio
Now the command can handle blank fields. For example, if the user of the dialog box leaves the Shear
Modulus field blank with the new command, the following command is executed:
beam_name = .model_1.ebm_beam4 &
Interface 53
youngs_modulus = 2.07E+05 &

damping_ratio = 1.0E-02
Adams/View did not include the parameter for the blank field.
Conditional expansion is valid for all parameter types in addition to fields that can return no value.
Conditional expansion can be included for none, some, or all parameters in a command. In the example
above, the beam_name parameter is required by the command, so the single quotes are not included.
Special Commands for Windows, Dialog Boxes, and Containers

Windows, dialog boxes, and containers have special sets of commands: start, execution, and finish
commands. Adams/View automatically executes start commands when the object is displayed and
automatically executes finish commands when an object is undisplayed. Execution commands are
executed by the interface dialog_box/window/container execute command.
Start and finish commands help you initialize settings and put default values into fields when an interface
object is displayed. If necessary, finish commands also allow you to clean up when the object is not
displayed.
Execution commands are not required, but are a useful place to put a set of commands that several objects
can execute. The default OK and Apply buttons use execution commands, for example.
Example
You can display windows and dialog boxes with a list of parameters. These parameters can be used by
the interface objects and commands within that interface object. The parameters are passed as quoted text
strings into the interface object.
Once the window or dialog box is displayed, it can make use of these parameters in its own commands.
These parameters are automatically assigned the special names $_1, $_2, ..., $_n, for each parameter that
is passed to it.
This functionality is especially useful for specifying default values for fields or other interface objects in
the new window or dialog box. For example, a button labeled Easy Beam Size has been added to the
54 Adams/View
custom Easy Beam Properties dialog box. The button contains commands that display a new dialog box
for further modification of a beam:
The name of the beam is passed to the new dialog box so that it automatically loads the relevant
parameters. The command for the Easy Beam Size button is:
interface dialog_box display &
dialog_box_name = .gui.db_beam_size &
'parameters="$f_beam_name"'
In addition to specifying the name of the dialog box to open, the command also specifies a parameter to
pass to the new dialog box.
The start command for the new Easy Beam Size dialog box uses this passed parameter to automatically
load the current values for the beam as shown below:
if condition=("$_1" != "")
interface field set field_name=$_self.f_beam_name str="$_1"
end
if condition=("$f_beam_name" != "")
interface field set &
field_name=$_self.f_length &
database_field="$f_beam_name.length"
field_name=$_self.f_area_of_cross_section &
data_base_field="$f_beam_name.area"
field_name=$_self.f_i_marker_name &
database_field="$f_beam_name.i_marker_name"

field_name=$_self.f_j_marker_name &
database_field="$f_beam_name.j_marker_name"
end
The if statements check to see if the passed parameter "$_1" contains a value. If a value is found, the
interface field set command loads with the name passed from the calling interface object (in this case, the
Interface 55
name of the beam). The second if statement checks to see if the field was set to a beam name. If so, it gets
the current values for the beam and sets the appropriate fields.
Window and dialog box parameters are useful tools for communicating information between interface
objects. To pass multiple parameters, separate them with commas, as in the following example:
interface dialog_box display dialog_box=my_dialog_box
parameters="parameter1", "parameter2", "parameter3"
When the new dialog box appears, it has access to those parameters as $_1, $_2, and $_3, respectively.
Editing Commands
Holding down the right mouse button over the Commands area of the Dialog-Box Builder displays a
shortcut menu with several options for editing the commands as shown in the table below.
Command Editing Options

The command: Does the following:
References Displays and inserts the available $xxx references.
Pick Lets you select an object and insert selected name into commands.
Browse Displays the Database Navigator and inserts selected name into commands.
Cut Removes selected text and places it in the system clipboard.
Copy Copies selected text to system text buffer.
Paste Pastes from system clipboard to cursor location or over selected text.
Edit Displays the text editor vi (by default) with text loaded (UNIX only).
Testing Your Dialog Box

You can test the execution of your dialog box without saving it to your database.
To test your dialog box changes:

1. On the Options menu, select Test Box.
Adams/View displays the dialog box without any object highlighting.
2. Execute your dialog box as desired.
Saving and Reloading Custom Dialog Boxes

Saving your dialog boxes as Adams/View command files is the most reliable way of ensuring that your
custom dialog boxes are upwardly compatible with new versions of Adams/View.
56 Adams/View
To save your dialog box:

• On the Dialog Box menu on the Dialog-Box Builder, point to Export, and then select Command
File.
Note: You can also save your dialog box by saving your modeling database as a binary file.
All of your changes are saved if you save a binary file.
Before you reload your dialog box, note that Adams/View does not allow the command file to create
interface objects with the same names as objects that already exist in the database. You must delete or
rename to read in the command file.
This is the most reliable way of ensuring your custom dialog boxes are upwardly compatible with new
versions of Adams.
To reload your custom dialog box:

• On the File menu, select Import, and then read in the desired command file.
Displaying Dialog Boxes

You can display dialog boxes using the Database Navigator. Standard Adams/View dialog boxes are
listed first, in alphabetical order, followed by your custom dialog boxes.
1. On the Tools menu, point to Dialog Box, and then select Display.
The Database Navigator appears, listing all dialog boxes.
2. Select the desired dialog box, and then select OK.
As an alternative, you can create a menu that displays your dialog boxes. For more information, see
Customizing Menus Using the Menu Builder.
Exiting the Dialog-Box Builder

To exit the Dialog-Box Builder:
• From the Dialog Box menu of the Dialog-Box Builder, select Exit.
The Dialog-Box Builder exits but Adams/View still displays your custom dialog box.
See Examples of Customizing the Adams/View Interface.
Authoring Plugins
Authoring Plugins 57
Introduction
Introduction
By definition, a plugin is a computer program that can or must interact with some other program to
provide a specific functionality. Plugins typically use the UI of their parent program and rely on the native
environment of their parent to provide this functionality.
Plugins in Adams
Adams provides plugins as a very powerful way of customization. With plugins, the end user can modify
the Adams environment to suit their needs. This may involve anything from personalizing the UI (menus,
adding custom dialogs etc.) to writing custom routines, directly called by the Adams/Solver at runtime.
Information is organized into the following sections:
• Section 1 - This section talks in brief about the files that constitute a plugin, their contents and
their role
• Section 2 - This section talks about the locations in which the plugin files can reside
• Section 3 - This section talks about the directory structure in which the files should reside in one
of the locations.
58 Adams/View
Section 1: The basic plugin

The following files constitute a basic plugin,
1. Plugin xml (plugin_plg.xml)
2. One or both of the ‘plugin binary file’ (plugin.bin) and the ‘The plugin View Dll’ (plugin_view.dll)
3. Solver DLL (plugin.dll)
Plugin xml
The plugin xml serves to publish the existence of a plugin to the product (View, Car, PPT etc). The plugin
manager makes use of the xml files that belong to the individual plugins to create a consolidated list of
plugins that is available for use with the current product.
Among other things, the xml contains information such as the plugin name, version and author as well
as the list of products with which the plugin is compatible. This information is made use of by the plugin
manager to display the information about the plugin in its UI as shown below,
It is recommended, that while creating new plugins, existing plugin xml files be used as reference.
Explanation for some of the most common tags in the xml file is given below,
• Description - Specifies a short multi-line description of the plugin.
• Version - Specifies the version number of the plugin.
• Author - Contains information such as the name of the person/organization that created the
plugin.
• LicenseFeature - Contains information related to the licensing feature used by the plugin. The
plugin manager uses this information to denote the number of available licenses.
• ValidWith / NotValidWith - List of the products that the plugin is valid for use with and
otherwise. Only plugins specified in the ValidWith list are displayed in the plugin manager.
The naming convention for the plugin xml file is (plugin_plg.xml), where plugin is the placeholder for
the actual name of the plugin.
The plugin View Dll

The view dll contains a collection of custom written functions/routines to be registered with
Adams/View. The custom routines are written in C or FORTRAN and can reside in any number of files.
Registering a function with Adams/View makes it accessible from the Adams/View command language
for use in expressions.
Apart from the custom functions, a view dll must contain 2 other functions named plugin_initialize and
plugin_terminate (where plugin is a placeholder for the name of the actual plugin). The initialize function
takes care of the function registration, performing license checkouts if necessary etc. The terminate
function on the other hand does exactly the opposite, in un-registering the functions and any other clean
up tasks involved in unloading of the plugin.
The plugin view DLL is created using the ‘adams2012 –c aview cr-u’ command. The naming
convention for the view dll is plugin_view.{so, sl, dll}, with the extension specific to the platform under
consideration.
View GUI
The view GUI is a full or a partial binary file containing a View library object. The library has the same
name as that of the plugin (.plugin). The library object typically contains all the macros, UDE definitions
and dialog boxes which the plugin makes use of.
The library object also contains a load macro (.plugin.load). The load macro is typically responsible for
making changes to the parent UI (like adding plugin specific menus to the parent UI) during the plugin
load operation. It is important that the load macro uses a User-Entered Command, for instance:
myplugin load
The user-entered command is required to have the load macro called upon plugin startup. For this, it
might reference other menu or command files. After Adams/View loads the binary, the plugin library will
be searched for this macro for the load process to continue.
The View library object will also contain a corresponding unload macro (.plugin.unload). The unload
macro is complementary to the load macro and usually restores the parent environment when the plugin
is unloaded.
60 Adams/View
Also, plugin dialog boxes should have commands which call plugin specialized macros instead of
building long command structures in the dialog boxes itself. The plugin load operation automatically sets
an environment variable within the Adams/View session which helps locate the binary file from which
the plugin was loaded. The variable name is plugin_BIN_DIR where plugin is the upper-cased version
of the plugin name. This can be used in the plugin load macro, for instance, to read gui components that
are inside the plugin library.
Example:
macro create macro = .plugin.load &
user = “mdi plugin load” &
com = “file binary read &”, &
“ file = (getenv(\” PLUGIN_BIN_DIR \”) // \” plugin.bin \”) & “, &
“ entity = .gui.main.mbar.my_menu”
This plugin binary must be named plugin.bin (where plugin is the name of the plugin).
Note that no database object in the plugin library references any object outside of the library, otherwise
an unresolved dependency would be introduced between the plugin and the parent application.
The bitmap below shows the controls plugin components as seen through the database navigator. Note
the library name (which is the name of the plugin) and the load/unload macros beneath the library.
Solver DLL
This binary contains the custom written functions/routines which are used by the solver during analysis.
The functions can be written in C or FORTRAN and can reside in any number of files. The solver dll is
created using the ‘adams2012 –c cr-u’ command.
The naming convention for the solver dll is plugin.{so, sl, dll}, with the extension specific to the platform
under consideration. The convention is not a requirement. It is a recommendation, just so that the solver
dll is easily distinguished from the view dll.
It is recommended that the solver dll have the two standard functions DLL_INIT and
DLL_TERMINATE, although having them is not a requisite. The INIT and TERMINATE functions have
the same role as the initialize and the terminate functions of a View dll. Typical initialization operations
for a solver dll include allocating memory for the plugin, checking out licenses and opening device
62 Adams/View
handles while termination operations include de-allocating the memory, returning licenses and closing
any open device handles.
The init function is called by the solver as soon as the statements FUNCTION = USER(…), ROUTINE
= libname::fname1 are encountered by the solver. Solver will not initialize the same DLL more than once.
Conversely, DLLs are automatically unloaded under the following conditions,
• A new database is opened
• Solver changed from C++ to FORTRAN or vice-versa.
• The STOP command is issued
• The FILE command is used to read a new model
Again, solver will not call the DLL_TERMINATE function more than once for each dll. Also note that
the terminate function will be called only if the init function was called in the first place.
Section 2: The search path algorithm for plugin discovery
Section 2: The search path algorithm for plugin

discovery
There is a definite manner in which a product/vertical (such as View, Car, and Engine) searches for a
plugin, when the plugin load command is issued by the user. The method in which a product searches a
given plugin is termed here as the search path algorithm.
The following section, describes the locations in which a plugin will be searched. The search order will
be exactly as mentioned below. Note that the plugin files (Plugin xml, view GUI, view dll and solver dll)
that we discussed in the earlier sections need to reside in any one of these locations, in order for the plugin
to be discoverable. The directory structure in which the files should reside in a location is described in
the next section.
1. MDI_USER_PLUGIN_DIR
This environment variable contains a list of colon separated (semi-colon separated on windows)
directories, set by the user. Each individual directory in this path will be searched for the plugin.
2. Private location for the product
The private location is specific to verticals and is not applicable to View. The set of environment
variables that define the private location for a product are as follows,
Product Private environment variable

Adams/Car MDI_ACAR_PRIVATE_DIR
Adams/Engine (FEV) MDI_AENG_PRIVATE_DIR
Adams/Rail (VI Grade) MDI_RAIL_PRIVATE_DIR
Adams/Aircraft (VI Grade) MDI_AIR_PRIVATE_DIR
Adams/Driveline MDI_ADRV_PRIVATE_DIR
3. Site location
The site location is specific to verticals and is not applicable to View. This location is defined by
an environment variable which has the format MDI_<product_name>_SITE, where
product_name is the product under consideration. The environment variable is set to the desired
location/locations by the user in the form of a colon separated (semi-colon separated on windows)
list of directories. The site environment variable for individual products is listed below,
Product Old private environment variable

Adams/Car MDI_ACAR_SITE
Adams/Engine (FEV) MDI_AENGINE_SITE
Adams/Rail (VI Grade) MDI_ARAIL_SITE
64 Adams/View
Section 2: The search path algorithm for plugin discovery
Product Old private environment variable

Adams/Aircraft (VI Grade) MDI_AIRCRAFT_SITE
Adams/Driveline MDI_ADRIVELINE_SITE
For a given product, the list of directories in the corresponding environment variable will be
checked for the existence of a plugin.
4. Installation path
The environment variable $topdir is set to the installation path of the Adams product. The
platform specific sub-directory (win32, hpux11 etc.) as applicable, will be searched for in the
plugin directory, if present in the installation path. Note that the environment variable
$MDI_CPU is set to the appropriate platform. So essentially, the location
$topdir/plugin/$MDI_CPU will be searched for the existence of the specified plugin.
5. Library path
On different platforms, the library path is specified using different environment variables. The list
of the library path environment variable on individual platforms is as specified below,
Platform Library Path Environment variable

Windows PATH
HPUX SHLIB_PATH
IBM LIBPATH
Sun and Linux LD_LIBRARY_PATH
This variable contains a colon/semi-colon separated list of directories. Individual directories will
be searched for during the plugin load operation.
6. Current working directory
The current working directory is the last location which will be searched for the existence of the
plugin.
Section 3: The Plugin directory structure
Section 3: The Plugin directory structure

A plugin X is represented by a directory X. We already have seen the locations where this plugin
directory should reside, in order for the plugin to be discoverable. We will call this directory as the plugin
root directory or simply, the root.
Also, a plugin may make use of platform specific files for its functionality (such as a solver.dll or a
solver.so as the case may be). Such files should reside in platform specific directories (e.g. win32,
rh_linux, hpux11 etc.) within the root. The platform specific directories are searched automatically for
each specified location and as such should not be explicitly specified.
For example,
Lets say that the a user has set the location “C:/Plugins/X” through the environment variable
MDI_USER_PLUGIN_DIR on the windows platform, then the following locations will be searched, for
a plugin X,
1. C:/Plugins/X
2. C:/Plugins/win32
This applies to all locations mentioned in the previous section.
The help files associated with a plugin should be placed in the help directory located inside the root.
Similarly examples associated with the plugin should be placed in a directory called as examples. Both,
the xml file and the bin file should be located directly in the root and not inside any directory.
A possible directory structure is shown below,
<Plugin searchable location>
X (root directory)
- rh_linux (o)
- win32 (o)
- hpux11 (o)
- help (o)
- examples (o)
Directories that are optional are marked with an (o) beside them.
66 Adams/View
Creating Partial Binary (.bin) Files:
Creating Partial Binary (.bin) Files:

1. Create a new library in Adams/View to hold any customization:
library create library_name = .mylibrary
2. Place any customization into this library within Adams/View, for example:
macro create macro_name = .mylibrary.firstmacro
commands_to_be_executed = "list_info variable variable=*"
user_entered_command = all_variables
3. Save this library as a partial binary file. Specifying the proper library name as the entity is very
important:
file binary write entity_name = .mylibrary file_name =
"mylibrary.bin"
4. This partial binary can be read in, for testing or use, via a similar 'read' command that specifies
the entity:
file binary read file_name = "mylibrary.bin" entity_name =
.mylibrary

Customizing View

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Customizing View

Uploaded by

Copyright:

Available Formats

Customizing Adams/View

Automating Your Work Using Macros

About Adams/View Macros

About Creating Macros

Editing and Creating Macros Using the Macro Editor

To use the Macro Editor:

To play back a macro you recorded:

To save a recorded macro:

Creating Macros from Existing Files

To create a macro by reading in a file:

To save a macro to a command file:

To access the macro debugging tool:

Tips on Writing Macros

Using Conditionals and Loops

Writing Text Files

Executing System Commands

Ensuring Unique Names and Adams Identifiers

Including a Literal "$" in a Macro

Speeding up Object References in Expressions

Using Parameters in Macros

Example of a Macro with a Parameter

Expanding Parameter Values

list_info part part_name=.mod1.left_wheel

Generalized Parameter Format

Parameter Naming Conventions

Parameter Qualifiers and Formats

Range Qualifier Formats

Count Qualifier Formats

Default Qualifier Formats

Default Parameter Characteristics

Helpful Commands in Macros

file text write

The conversion specifications provided by Adams/View are a subset of those

% - Literal percent sign ("%%" is output as "%")

+ Forces a sign to be output for all numeric values. For example:

... FORMAT="%+d %+d" VALUES=(-1), (1)

" " Blank. Same as + but no explicit + sign, only a blank.

Field width is specified by prefixing the conversion specifier with a number.

... FORMAT="%03d%6d" VALUES=(5),(7)

... FORMAT="%5.2f %010.3e" VALUES=(2.3),(5.4)

" 2.30 05.400e+00"

values_for_output Specifies the values to be placed in the output string.

Values are: yes and no. The default is yes.

command_text Specifies the text for a device-dependent operating system

Conditional Constructs and Loops

Results of CONTINUE Example

Name: Loc_X: Loc_Y: Loc_Z:

Tip: You can have any number of ELSEIF CONDITION commands.

Using FOR/END to Perform Numeric Iteration

Examples of Numeric Iteration for FOR/END:

Using FOR/END To Operate on a Set of Objects

variable create variable=$_self.junk &

! Write the new file.

Ternary Conditional Operator

About Adams/View Menus and Dialog Boxes

Adams/View Interface Objects

List of Interface Objects

Object: Does the following:

Hierarchy of Interface Objects

Examples of Interface Objects

How the Interface Works

Changing the Interface

Saving Interface Changes