Automating Tasks Using Adams/View

Scripting, Macros, and GUI

Customization
ADM 704B Course Notes

February 2013

Part Number: ADAM*V2012*Z*ADVVIEW*Z*SM-ADM704B-NT

 Legal Information

MSC.Software Corporation reserves the right to make changes in specifications and other information contained in this
document without prior notice. The concepts, methods, and examples presented in this text are for illustrative and
educational purposes only, and are not intended to be exhaustive or to apply to any particular engineering problem or
design. MSC.Software Corporation assumes no liability or responsibility to any person or company for direct or indirect
damages resulting from the use of any information contained herein.
Copyright © 2013 MSC.Software Corporation. All Rights Reserved. This notice shall be marked on any reproduction of
this documentation, in whole or in part. Any reproduction or distribution of this document, in whole or in part, without the
prior written consent of MSC.Software Corporation is prohibited.
The MSC.Software corporate logo, Adams, Dytran, Easy5, Fatigue, Laminate Modeler, Marc, Mentat, MD Nastran, MD
Patran, MSC, MSC Nastran, Mvision, Patran, SimDesigner, SimEnterprise, SimManager, SimXpert and Sofy are
trademarks or registered trademarks of the MSC.Software Corporation in the United States and/or other
countries. NASTRAN is a registered trademark of NASA. All other trademarks belong to their respective owners.
CONTENTS
Section Page

1 Command Language
What is in this Section 1-3
General Structure 1-4
Getting Familiar with Commands 1-7
Command Navigator 1-8
Command Window 1-10
Log File 1-12
Types of Commands 1-13
Exercise – Workshop 1 1-16
2 Conditional Constructs and Loops
What is in this Section 2-3
FOR/END Loop (Numeric Iteration) 2-4
FOR /END Loop (Object-Based) 2-8
WHILE/END 2-11
IF/THEN/ELSE 2-13
Exercise – Workshop 2 2-16
3 Macros: Overview
What is in this Section 3-3
Macro Overview 3-4
Macro Object Parameters 3-7
Ways to Create Macros 3-8
Executing Macros 3-11

ADM704B, Section 0, February 2013

Copyright© 2013 MSC.Software Corporation S0 - 3
CONTENTS
Section Page

3 Macros: Overview (Cont.)

Debugging Macros 3-14
Exercise – Workshop 3 3-17
4 Macros: Parameters
What is in this section 4-3
Types of Parameters 4-4
Generalized Format 4-5
Naming Conventions 4-6
Qualifiers and Formats 4-7
Default Characteristics 4-8
Examples 4-9
Exercise – Workshop 4 4-10
5 Menus
What is in this section 5-3
Menu Builder 5-4
Syntax of Menu File 5-5
Using Commands to Add Menus 5-9
Exercise – Workshop 5 5-10

ADM704B, Section 0, February 2013

Copyright© 2013 MSC.Software Corporation S0 - 4
CONTENTS
Section Page

6 Dialog Boxes
What is in this Section 6-3
Adams/View Interface Overview 6-4
Terminology 6-5
Working with Dialog Boxes 6-6
Modifying Existing Pre-Built Dialog Boxes 6-7
Modifying Dialog Boxes that Were Auto Generated Using Macros 6-8
Creating Dialog Boxes from Scratch Using the Dialog Box Builder 6-9
Dialog Box Builder Overview 6-10
Dialog Box commands 6-14
Dialog Box Database Storage 6-16
Exercise – Workshop 6 6-17
7 Dialog Box Builder
What is in this Section 7-3
Substituting Text into Commands 7-4
Working with Dialog Boxes 7-8
Buttons 7-9
Radio Boxes 7-10
Sliders 7-11
Containers 7-12
Option Menu 7-13
Saving Dialog Boxes 7-14
Exercise – Workshop 7 7-15

ADM704B, Section 0, February 2013

Copyright© 2013 MSC.Software Corporation S0 - 5
CONTENTS
Section Page

8 Organizing Customization with Command Files

What is in this Section 8-3
Build Files 8-4
Adams/View Startup Files 8-5
Exercise – Workshop 8 8-9
9 Plugins
What is in this Section 9-3
Creating an Adams/View Library 9-4
Macros, Dialog Boxes as Children of a Library 9-6
The Plugin Load & Unload Macros 9-7
Adams/View Partial Binary Files 9-9
The Plugin XML File 9-10
Location for Plugin Files 9-11
Setting the MDI_USER_PLUGIN_DIR Variable 9-12
Test the Plugin 9-13
Exercise – Workshop 9 9-14

ADM704B, Section 0, February 2013

Copyright© 2013 MSC.Software Corporation S0 - 6
 SECTION 1
COMMAND LANGUAGE

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 1
ADM704B, Section 1, February 2013
Copyright© 2013 MSC.Software Corporation S1 - 2
WHAT IS IN THIS SECTION
• General Structure
• Getting Familiar with Commands
• Types of Commands

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 3
GENERAL STRUCTURE
• Syntax rules for commands
– Comment lines are allowed by placing an exclamation point (!) as the first
character on the line.
– Continuation of a command is denoted by an ampersand (&) at the end of a
line.
– Abbreviations are allowed as long as they are unique.

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 4
GENERAL STRUCTURE (CONT.)

• Examples:
– One “gotcha” when writing command files is that the last line might not get
executed. Therefore, make it a habit of making the last line a comment
character (!).
– marker delete marker_name=.mod1.par4.mar27
– marker delete &
– marker_name=.mod1.part4.mar27
– mar del mar=.mod1.par4.mar27
– mar del mar=mar27

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 5
GENERAL STRUCTURE (CONT.)

• Syntax rules for entering values

– Values can contain letters, numbers, and underscore characters.
– They must begin with a letter or underscore character.
– Values can contain any characters that are enclosed by double quotation
marks.
– They must have separators (blank space or tab) between keywords and
parameters. Placing separators between parameters and their values is
optional.
– All parameter values of type string should be enclosed in double-quotes (“).
– All parameter values of type object will accept the full database name or the
relative object name provided it is unique in the database.

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 6
GETTING FAMILIAR WITH COMMANDS

• Command Navigator
• Command Window
• Log file

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 7
GETTING FAMILIAR WITH COMMANDS (CONT.)

• Command Navigator
– Enables you to browse through the Adams/View command language and
execute commands.
• The entire Adams/View command language is accessible through the Command
Navigator.
• Use the Command Navigator to navigate on keywords.
• Double-clicking the last keyword of a command displays a dialog box of
parameter names and parameter values.

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 8
GETTING FAMILIAR WITH COMMANDS (CONT.)
Example:
Double-Click here

Which executes the command :

xy_plots template delete title plot_name =
plot_1

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 9
GETTING FAMILIAR WITH COMMANDS (CONT)

• Command Window
– Text-based way to enter commands.
– Assumes that you understand the Adams/View command language.

Command information area

Input
field

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 10
GETTING FAMILIAR WITH COMMANDS (CONT.)

• Command Window continued.

– Command History
• Use the up and down arrows on your keyboard to scroll through previously
executed commands.
– Command Expansion
• Use a question mark (?) or the Esc key for help with completing commands:
– Completes keywords or parameter names.
– Prompts for keywords or parameter names.
– Prompts for parameter values.

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 11
GETTING FAMILIAR WITH COMMANDS (CONT.)

• Log file
– A file named aview.log is saved during each Adams/View session. In the
vertical applications, it is called acar.log, aengine.log, and arail.log.
– Contains commands that you entered and messages you received.
– The log file for the previous session is aview.log% on UNIX and aview.log
on Windows.

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 12
TYPES OF COMMANDS

• Adams/View commands can be categorized as follows:

– Model-based
• Examples:
– marker create marker_name=mar1 location=2,0,0
– marker modify marker=mar1 orientation=0d,90d,0d
– Interface-based (GUI)
• Example:
interface dialog_box display &
dialog_box_name = .gui.db_beam_size &
parameters=”$f_beam_name”

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 13
TYPES OF COMMANDS (CONT.)

• Conditional constructs
– Adams/View command language contains commands for creating
conditional constructs and loops.
• BREAK
• CONTINUE
• IF/ELSEIF/ELSE/END
• FOR/END
• RETURN
• WHILE/END

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 14
TYPES OF COMMANDS (CONT.)

• 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.
Note: For more information on the file text write command, see Knowledge
Base Article KB8012767 available at:
http://simcompanion.mscsoftware.com/infocenter/index?page=content&id=K
B8012767
This command is also documented in the online help.

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 15
EXERCISE

• Perform Workshop 1, “Understanding the Command Language,” in

your exercise workbook

ADM704B, Section 1, February 2013

Copyright© 2013 MSC.Software Corporation S1 - 16
 SECTION 2
CONDITIONAL CONSTRUCTS AND LOOPS

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 1
ADM704B, Section 2, February 2013
Copyright© 2013 MSC.Software Corporation S2 - 2
WHAT IS IN THIS SECTION

• FOR/END Loop (Numeric Iteration)

• FOR/END Loop (Object-Based)
• WHILE/END
• IF/THEN/ELSE

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 3
FOR/END LOOP (NUMERIC ITERATION)

• Overview
– The FOR and END commands allow you to execute a group of commands
a fixed set of times.
– This example performs numeric iterations. Adams/View executes the
commands bracketed by the FOR and END for each value of a variable in
the specified range.
– You can nest any combination of looping (FOR/END, WHILE/END) and
conditional constructs (IF/ELSEIF/ELSE/END).

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 4
FOR/END LOOP (NUMERIC ITERATION) (CONT.)

• Syntax
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 an Adams/View
variable of type REAL named var. 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 to
happen, you can use the EVAL function.
– START_VALUE, INCREMENT_VALUE, and END_VALUE can be any valid
real expression.

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 5
FOR/END LOOP (NUMERIC ITERATION) (CONT.)

• Syntax continued
– 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.

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 6
FOR/END LOOP (NUMERIC ITERATION) (CONT.)

• Example
– 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 reference frame.
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

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 7
FOR/END LOOP (OBJECT-BASED)

• Overview
– The FOR and END commands allow you to execute a group of commands
a fixed set of times.
– This example operates on a set of Adams/View objects, such as markers or
parts. Adams/View executes the commands bracketed by the FOR and
END on the specified set of objects.
– You can nest any combination of looping (FOR/END, WHILE/END) and
conditional constructs (IF/ELSEIF/ELSE/END).

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 8
FOR/END LOOP (OBJECT-BASED) (CONT.)

• Syntax
FOR VARIABLE_NAME=var OBJECT_NAMES=objects &
TYPE=database_object_type
...
END
– For this type of FOR loop, Adams/View creates an Adams/View variable 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.

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 9
FOR/END LOOP (OBJECT-BASED) (CONT.)

• Example
– In this example, Adams/View renumbers the ADAMS IDs of markers
belonging to the part follower; it starts at 5000 and increments by one for
each marker in the set.
variable create variable_name=ip integer_value=5000
for variable_name=the_marker object_names=.fourbar.follower.* type=marker
marker modify marker_name=(eval(the_marker)) adams_id=(eval(ip))
variable modify variable_name=ip integer_value=(eval(ip+1))
end
variable delete variable_name=ip

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 10
WHILE/END

• Overview
– 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).
– You can nest any combination of looping (FOR/END, WHILE/END) and
conditional constructs (IF/ELSEIF/ELSE/END).
• Syntax
WHILE CONDITION=(expression)
...
END

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 11
WHILE/END (CONT.)

• Example
– 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 local part reference frame (LPRF).
variable create variable_name=ip integer_value=0
while condition=(ip < 10)
marker create marker_name=(eval("MAR"//ip+1)) &
location=(eval(ip)),0,0
variable modify variable_name=ip integer_value=(eval(ip+1))
end
variable delete variable_name=ip

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 12
IF/THEN/ELSE

• Overview
– Use IF/ELSE to execute a group of commands conditionally.
– The execution of commands bracketed by IF and END depend on the value
of an expression.

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 13
IF/THEN/ELSE (CONT.)

• Syntax
IF CONDITION=(expression) Helpful operators for expressions:
...
END
!= not equal to
IF CONDITION=(expression) && logical AND
... || logical OR
ELSE
== equal to
...
END < less than

IF CONDITION=(expression) For information on these and other

... operators, see the Expression
ELSEIF Language Reference in the
... Adams/View Function Builder online
ELSE help.
...
END

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 14
IF/THEN/ELSE (CONT.)

• 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

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 15
EXERCISE

• Perform Workshop 2, “Conditional Constructs and Loops,” in your

exercise workbook

ADM704B, Section 2, February 2013

Copyright© 2013 MSC.Software Corporation S2 - 16
 SECTION 3
MACROS: OVERVIEW

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 1
ADM704B, Section 3, February 2013
Copyright© 2013 MSC.Software Corporation S3 - 2
WHAT IS IN THIS SECTION

• Macro Overview
• Macro Object Parameters
• Ways to Create Macros
• Executing Macros
• Debugging Macros

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 3
MACROS: OVERVIEW

• Definition
– A macro is an object that adds a command to the Adams/View language to
execute a series of Adams/View commands.
– Adams/View treats a macro as it does all other Adams/View commands.

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 4
MACROS: OVERVIEW (CONT.)
• Purpose
– Automate model building, simulating, and reviewing
• Examples:
– Generate a series of objects
– Generate a series of plots for a simulation
– Build an entire model (one for parts, one for joints, one for forces, and so on).
– Automate user preferences
– You can also write macros to automate how you work in Adams/View. For
example, you can:
• Automatically turn icons on or off
• Specify a certain grid size
• Set whether or not to use the external Adams/Solver library, and so on.
• Examples:
– Icon settings (visibility, size, color)
– Grid settings (on/off, size, and so on)
– Solver preferences (use external/internal, save files, and so on)

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 5
MACROS: OVERVIEW (CONT.)

• Types
– Parameterless
• Executes the Adams/View commands stored in the macro.
– With parameters
• You can add parameters to a macro that will be evaluated when the macro is
executed.
• This makes the macro more generic.

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 6
MACRO OBJECT PARAMETERS

• To create a macro, you must specify:

– Name (for database storage and reference).
• We recommend that you save your macros in a user-created library.
• If you save them in the .gui library, they will not be upward compatible.
• By default, macros are saved at the root level of the database.
– A command that will run the macro.
• The default is the macro name.
– The commands the macro will execute.
– What to do in case of a subsequent Undo.

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 7
WAYS TO CREATE MACROS

• Macro editor
– Here, you enter the name of the macro and a unique command string that
executes the macro.

Command
text area

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 8
WAYS TO CREATE MACROS (CONT.)

• Record/Replay
– You can create a macro by recording a sequence of steps. Once you start
the recording process, you perform the operations that you want to be
included in the macro. Then, you stop the recording process and play it
back. You can also save the macro you just recorded.
• Reading text from a file
– You can create a macro by using 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 standard
command file but it can also contain parameters embedded in the
commands and can have special comments at the top.

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 9
WAYS TO CREATE MACROS (CONT.)
• Example for reading text from a file
macro read &
file_name = "part_replicate_single_mac.cmd" &
macro_name = .par_rep_single

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 10
EXECUTING MACROS

• When you create a macro, the command is added to Adams/View

language.
• Command line
– Enter the command (with any applicable parameters) in the command line
of the Command Window.

Command
line

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 11
EXECUTING MACROS (CONT.)

• Command Navigator
– The Command Navigator displays a list of all Adams/View command
keywords. When you select an object, a dialog box appears in which you
enter parameters for executing the command.

Selecting this command…

Opens this
dialog box

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 12
EXECUTING MACROS (CONT.)

• Custom dialog boxes

– You can create a custom dialog box that upon execution executes a macro.
• Other macros
– If needed, a command within a macro can execute another macro.

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 13
 DEBUGGING MACROS

• Using list information and temporary variables

• Using the ADAMS Command Debugger
• Crawl-walk-run approach

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 14
DEBUGGING (CONT.)
• Using list information and temporary variables
– You can debug a macro if you:
• Create it in pieces.
• Store the pieces in variables.
• Get list information on these variables.
– For more information on building function expression strings in a macro, see
the Knowledge Base Article KB8013202, available at:
http://simcompanion.mscsoftware.com/infocenter/index?page=content&id=K
B8013202
• Using the ADAMS Command Debugger
– Used for heavy development
– Unsupported and details undocumented

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 15
DEBUGGING (CONT.)
• Crawl-walk-run approach
– Crawl - Learn the commands
• Use interface to facilitate.
• Execute by interface (GUI), Command Navigator, and so on.
• Review commands and parameters (log file and Command Window).
• Add to macro editor and test.
– Walk - Add parameters and qualifiers
• Declare parameters and simple qualifiers.
• Substitute parameters into commands.
• Test.
• Add looping constructs, if necessary.
• Use temporary variables.
– Run - Fine tune
• Add comment lines
• Remove dependencies (model object names, environment, and so on).
• Add error trapping (using IF condition).
• Add detailed qualifier, as needed.
ADM704B, Section 3, February 2013
Copyright© 2013 MSC.Software Corporation S3 - 16
EXERCISE

• Perform Workshop 3, “Macros Overview,” in your exercise

workbook

ADM704B, Section 3, February 2013

Copyright© 2013 MSC.Software Corporation S3 - 17
ADM704B, Section 3, February 2013
Copyright© 2013 MSC.Software Corporation S3 - 18
 SECTION 4
MACROS: PARAMETERS

ADM704B, Section 4, February 2013

Copyright© 2013 MSC.Software Corporation S4 - 1
ADM704B, Section 4, February 2013
Copyright© 2013 MSC.Software Corporation S4 - 2
WHAT IS IN THIS SECTION

• Types of Parameters
• Generalized format
• Naming conventions
• Qualifiers and formats
• Default characteristics
• Examples

ADM704B, Section 4, February 2013

Copyright© 2013 MSC.Software Corporation S4 - 3
TYPES OF PARAMETERS

• Real
• Integer
• File
• Object
• String
• List
• Location
• Orientation

ADM704B, Section 4, February 2013

Copyright© 2013 MSC.Software Corporation S4 - 4
GENERALIZED 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.

ADM704B, Section 4, February 2013

Copyright© 2013 MSC.Software Corporation S4 - 5
NAMING CONVENTIONS

• 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).
• 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.
• Not case sensitive.
• Use single quotes to explicitly separate the name or qualifiers from
command text immediately following the parameter.

ADM704B, Section 4, February 2013

Copyright© 2013 MSC.Software Corporation S4 - 6
QUALIFIERS AND FORMATS

• You can use qualifiers on the first occurrence of the parameter to

control the parameter characteristics.
– Qualifiers are optional.
– They can only be used the first time the parameter appears in the macro
text.
– You can use the qualifiers in any combination and any order.
– If repeated, ADAMS/View uses the last value.
– Qualifiers are not case-sensitive.
• Parameters can have one or more of the following qualifiers:
– Type
– Range
– Count
– Defaults

ADM704B, Section 4, February 2013

Copyright© 2013 MSC.Software Corporation S4 - 7
DEFAULT CHARACTERISTICS

• We recommend that you explicitly set the characteristics of your

parameters in comments at the beginning of your macro.
• 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.

ADM704B, Section 4, February 2013

Copyright© 2013 MSC.Software Corporation S4 - 8
EXAMPLES
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 An integer from 3 to 8 and a constant

=3 default of 3.

$infile:t=file(*.dat) File name. The File Selection dialog

box lists all files with the extension
.dat.

$cm_location_from_part:t=location:d=0,0,0
$excitation_mode:t=list(heave,pitch,roll,warp):d=heave
$error_variable:t=variable:d=.ACAR.variables.errorFlag
$number_of_steps:t=integer:gt=0

For more examples of parameters, see the Customize tab in the ADAMS/View
online help.

ADM704B, Section 4, February 2013

Copyright© 2013 MSC.Software Corporation S4 - 9
EXERCISE

• Perform Workshop 4, “Macros and Parameters Syntax,” in your

exercise workbook

ADM704B, Section 4, February 2013

Copyright© 2013 MSC.Software Corporation S4 - 10
 SECTION 5
MENUS

ADM704B, Section 5, February 2013

Copyright© 2013 MSC.Software Corporation S5 - 1
ADM704B, Section 5, February 2013
Copyright© 2013 MSC.Software Corporation S5 - 2
WHAT IS IN THIS SECTION

• Menu Builder
• Syntax of Menu File
• Using Commands to Add Menus

ADM704B, Section 5, February 2013

Copyright© 2013 MSC.Software Corporation S5 - 3
MENU BUILDER
• Overview
– You can use the Menu Builder (Tools  Menu  Modify) to modify and
create menus to better suit your needs and preferences or match your
industry’s terminology.
– You can specify keyboard accelerators (shortcuts) and mnemonics.
• Mnemonics create an underlined keystroke equivalent to a menu item, such as
File.
• Accelerators let you associate a key (such as F10) or key sequence (such as
CTRL+k) with a menu item.
– You can build menus for a particular model or for an entire application. For
example, you can add the elements shown below:

Menu Button
ADM704B, Section 5, February 2013
Copyright© 2013 MSC.Software Corporation S5 - 4
SYNTAX OF MENU FILE
• Each line of a menu file 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.
• The figure below shows a portion of the Menu Builder that defines the Tools
menu in Adams/View. Below the Menu Builder is the corresponding Tools
menu as it appears in Adams/View.

ADM704B, Section 5, February 2013

Copyright© 2013 MSC.Software Corporation S5 - 5
SYNTAX OF MENU FILE (CONT.)
• Menu
– MENUn TITLE
NAME=name
HELP=Help
• Button
– BUTTONn LABEL :: ACCELERATOR
NAME=name
HELP=help
CMD=command
• Separator
– SEPARATORn
• Toggle
– TOGGLEn TITLE
NAME=name
HELP=help
STATE=state
CMD=command

ADM704B, Section 5, February 2013

Copyright© 2013 MSC.Software Corporation S5 - 6
SYNTAX OF MENU FILE (CONT.)
• Referring to the example syntax on the previous page, 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.
• For example, if MENU1 appears on the menu bar, then BUTTON2 will appear 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.
– LABELs can contain ampersand (&) characters that specify keyboard mnemonic shortcuts
for a menu item (for example, ALT-F opens the File 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.

ADM704B, Section 5, February 2013

Copyright© 2013 MSC.Software Corporation S5 - 7
SYNTAX OF MENU FILE (CONT.)
• The text lines have the following parameters continued:
– BUTTONs can specify an accelerator key (for example, CTRL+M,
SHIFT+G, or F12) that invokes the button action.
– If NAME is omitted, Adams/View constructs a default identifier, such as
MENU_4 or BUTTON_7.
– TOGGLE buttons create a menu item that displays a check mark depending
on the STATE value (ON or OFF). The state value is toggled when the
button is clicked.
– SEPARATOR elements create horizontal line breaks that denote groups of
commands.
– Note, that with the exception of CMD= lines, spaces are not permitted in the
menu structure input. So NAME = my_menu is not valid, but
NAME=my_menu is valid. This differs from Adams/View command
language syntax where spacing rules are flexible.

ADM704B, Section 5, February 2013

Copyright© 2013 MSC.Software Corporation S5 - 8
USING COMMANDS TO ADD MENUS

• If you want to modify the Adams/View main menu, we highly

recommend that you do this using commands instead of the Menu
Builder or .mnu file.
– If you modify a menu structure for one version of Adams/View and save it, it
may not represent the full, default, menu structure for subsequent
Adams/View versions.
– For the above reason, it is better to use command language to build only
the changes that you want rather than re-doing the entire menu structure.

ADM704B, Section 5, February 2013

Copyright© 2013 MSC.Software Corporation S5 - 9
EXERCISE

• Perform Workshop 5, “Creating Custom Menu Buttons,” in your

exercise workbook

ADM704B, Section 5, February 2013

Copyright© 2013 MSC.Software Corporation S5 - 10
 SECTION 6
DIALOG BOXES

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 1
ADM704B, Section 6, February 2013
Copyright© 2013 MSC.Software Corporation S6 - 2
WHAT IS IN THIS SECTION

• Adams/View Interface Overview

• Terminology
• Working with Dialog Boxes
• Dialog Box Builder Overview
• Dialog Box Commands
• Dialog Box Database Storage

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 3
ADAMS/VIEW INTERFACE OVERVIEW
• Database hierarchy for graphical user interface (GUI) objects
All default objects
Stored in .gui library

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 4
 TERMINOLOGY
• Dialog Box and its children’s object terminology

Dialog
box Label
Button
Text box

Slider Option
Menu

Radio
button
Separator
Container

Toggle
button
Tool
stack
ADM704B, Section 6, February 2013
Copyright© 2013 MSC.Software Corporation S6 - 5
WORKING WITH DIALOG BOXES

• Modifying existing pre-built dialog boxes

• Modifying dialog boxes that were auto generated using macros
• Creating dialog boxes from scratch using the Dialog Box Builder

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 6
WORKING WITH DIALOG BOXES (CONT.)
• Modifying existing pre-built dialog boxes

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 7
WORKING WITH DIALOG BOXES (CONT.)
• Modifying dialog boxes that were auto generated using macros.

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 8
WORKING WITH DIALOG BOXES (CONT.)
• Creating dialog boxes from scratch using the Dialog Box Builder.

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 9
DIALOG BOX BUILDER OVERVIEW

Title

Dimensioning
and Positioning
Toolbar
Attribute type
selector
Attributes
indicator
Attributes
Area

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 10
DIALOG BOX BUILDER OVERVIEW (CONT.)
• You can access the Dialog Box Builder in one of two ways:
– From the Tools menu, point to Dialog Box and then select Create or Modify.
– Double-click on a dialog box.
• For security reasons, this method is disabled by default.
• You can enable this feature by either:
– Modifying or creating a dialog box for the first time
– Setting the environment variable MDI_AVIEW_CUSTOMIZE=enabled

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 11
DIALOG BOX BUILDER OVERVIEW (CONT.)

• Operational modes for renaming, reshaping, and modifying

• Open objects in the Dialog Box Builder
– Name of open object is displayed in title.
– You can only modify characteristics (size, name, attribute) of the open
object and/or a direct child of the open object. In other words, you cannot
modify a “grandchild” directly.
– Limited to dialog boxes, containers, toolbars, and tab containers.
– Open objects using the Dialog Box Open menus.
• Editing open object
– Use the Dialog Box menu to rename, fit, or edit its attributes.

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 12
DIALOG BOX BUILDER OVERVIEW (CONT.)

• Editing children objects of open objects

– Double-click the object with the left mouse button (notice that the attributes
indicator changes).
OR
– Select the object you want to modify:
• Single-click on an object with the left mouse button.
or
• From the Edit menu, point to Select and then browse for the object in the
Database Navigator.
– Then, use the Edit menu to rename, resize, or edit its attributes.

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 13
DIALOG BOX COMMANDS

• Start
– Commands are executed when object is displayed.
– Useful in initializing settings and putting default values into fields when
object is displayed.
• Execution
– Commands are executed by the dialog box when the user clicks OK or
Apply.

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 14
DIALOG BOX COMMANDS (CONT.)

• Finish
– Commands are executed when object is undisplayed.
– Allows you to clean up work when object is undisplayed.

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 15
DIALOG BOX DATABASE STORAGE

• Existing interface objects

All dialog boxes

are placed in this
library by default

• New GUI objects

– It is highly recommended that you place all new objects in a user-created
library.
– Objects placed in the .gui library will not be upward compatible!
ADM704B, Section 6, February 2013
Copyright© 2013 MSC.Software Corporation S6 - 16
EXERCISE

• Perform Workshop 6, “Working with Dialog Boxes,” in your

exercise workbook

ADM704B, Section 6, February 2013

Copyright© 2013 MSC.Software Corporation S6 - 17
ADM704B, Section 6, February 2013
Copyright© 2013 MSC.Software Corporation S6 - 18
 SECTION 7
DIALOG BOX BUILDER

ADM704B, Section 7, February 2013

Copyright© 2013 MSC.Software Corporation S7 - 1
ADM704B, Section 7, February 2013
Copyright© 2013 MSC.Software Corporation S7 - 2
WHATS IN THIS SECTION

• Substituting Text into Commands

• Working with Dialog Boxes
• Saving Dialog Boxes

ADM704B, Section 7, February 2013

Copyright© 2013 MSC.Software Corporation S7 - 3
SUBSTITUTING TEXT INTO COMMANDS
• Holding down the right mouse button over the Commands area of
the Dialog Box Builder displays a pop-up menu with several
options for editing the commands.
• When you select References, you can display and insert the
available $xxx references.

ADM704B, Section 7, February 2013

Copyright© 2013 MSC.Software Corporation S7 - 4
SUBSTITUTING TEXT INTO COMMANDS (CONT.)

ADM704B, Section 7, February 2013

Copyright© 2013 MSC.Software Corporation S7 - 5
SUBSTITUTING TEXT INTO COMMANDS (CONT.)

• Objects that contain values

ADM704B, Section 7, February 2013

Copyright© 2013 MSC.Software Corporation S7 - 6
SUBSTITUTING TEXT INTO COMMANDS (CONT.)
• Example

ADM704B, Section 7, February 2013

Copyright© 2013 MSC.Software Corporation S7 - 7
WORKING WITH DIALOG BOX OBJECTS

• Buttons
• Radio boxes
• Sliders
• Containers
• Option menu

ADM704B, Section 7, February 2013

Copyright© 2013 MSC.Software Corporation S7 - 8
WORKING WITH DIALOG BOX OBJECTS (CONT.)

• Buttons
– Buttons do not contain values.
– They simply execute commands upon single or double-clicking.

Buttons

Button

ADM704B, Section 7, February 2013

Copyright© 2013 MSC.Software Corporation S7 - 9
WORKING WITH DIALOG BOX OBJECTS (CONT.)
• Radio boxes
– Set states or modes

Radio
boxes

Values
Text
appearance
ADM704B, Section 7, February 2013
Copyright© 2013 MSC.Software Corporation S7 - 10
WORKING WITH DIALOG BOX OBJECTS (CONT.)
• Sliders
– Sets value of an object without having to type it in.
– Currently limited to integer values.

As you move the slider to the

right, notice that value changes.

ADM704B, Section 7, February 2013

Copyright© 2013 MSC.Software Corporation S7 - 11
WORKING WITH DIALOG BOX OBJECTS (CONT.)

• Containers
– Sub-region inside dialog box window
or toolbar.
– Can hold other objects

Container for
design study

ADM704B, Section 7, February 2013

Copyright© 2013 MSC.Software Corporation S7 - 12
WORKING WITH DIALOG BOX OBJECTS (CONT.)
• Option menu
– Allows one of many selections
– Contains a push graphic that displays the entire list, like a menu.
– Displays only one column of options.

When you select the arrow here…

You will get the pull-down menu

of available selections here

ADM704B, Section 7, February 2013

Copyright© 2013 MSC.Software Corporation S7 - 13
SAVING DIALOG BOXES
• On the Dialog Box menu, point to Export and then select
Command File.
– The dialog box is saved in the current working directory.
– The file name will be the dialog box name.
– You will probably want to rename the file so that subsequent saves do not
overwrite the file.
– 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.

ADM704B, Section 7, February 2013

Copyright© 2013 MSC.Software Corporation S7 - 14
EXERCISE

• Perform Workshop 7, “Working with Dialog Box Builder,” in your

exercise workbook

ADM704B, Section 7, February 2013

Copyright© 2013 MSC.Software Corporation S7 - 15
ADM704B, Section 7, February 2013
Copyright© 2013 MSC.Software Corporation S7 - 16
 SECTION 8
Organizing Customization with Command
Files

ADM704B, Section 8, February 2013

Copyright© 2013 MSC.Software Corporation S8 - 1
ADM704B, Section 8, February 2013
Copyright© 2013 MSC.Software Corporation S8 - 2
WHAT IS IN THIS SECTION

• Build Files
• Adams/View Startup Files

ADM704B, Section 8, February 2013

Copyright© 2013 MSC.Software Corporation S8 - 3
BUILD FILES
• Files that read in (or create) the various components of a customized
interface are typically called “build” files.
• We highly recommend that you organize all types of GUI customization
objects in subdirectories for organization and easy access.
• Sample build file:

ADM704B, Section 8, February 2013

Copyright© 2013 MSC.Software Corporation S8 - 4
ADAMS/VIEW STARTUP FILES
• Startup files
– Startup files are files that Adams/View searches for and loads automatically if they
exist.
– The following are the types of Adams/View startup files. They are listed in the order in
which Adams/View searches for them:
• Aview.bin
– Used to save a customized Adams/View environment in binary format.
– Used to store the state of a specific modeling session.
– file is unique when compared to the other startup files. This is because it is always read
in. By default, this file is located in the <install>/aview directory and will load in the
default Adams/View session. Adams/View will open the Aview.bin file that it finds first.
• AviewBS.cmd
– Preferences that you set. Before Startup (BS) means that Adams/View reads this
command file before it reads other startup files.
• Aview.cmd
– Contains commands for starting Adams/View. This file tends to be more model/project
specific.
• AviewAS.cmd
– Preferences that you set. After Startup (AS) means that Adams/View reads this
command file after it reads other startup files.

ADM704B, Section 8, February 2013

Copyright© 2013 MSC.Software Corporation S8 - 5
ADAMS/VIEW STARTUP FILES (CONT.)

• You can use the startup files to:

– Automatically customize your interface (for example, menus, buttons, and
dialog boxes)
– Speed up the file-import/open process
– Modify your Adams/View environment (for example, lighting features,
layouts, and creating custom views)

ADM704B, Section 8, February 2013

Copyright© 2013 MSC.Software Corporation S8 - 6
ADAMS/VIEW STARTUP FILES (CONT.)

• Locations:
– Adams/View will read in the first startup file it encounters with the correct
name (Aview.bin, AviewBS.cmd, Aview.cmd, and so on).
– Adams/View searches first for these files in your current working directory.
– If these files do not exist in your local working directory, Adams/View
searches for them in your directories specified in the aview.pth file.
– The aview.pth file is located by default in your <install>/common directory.

ADM704B, Section 8, February 2013

Copyright© 2013 MSC.Software Corporation S8 - 7
ADAMS/VIEW STARTUP FILES (CONT.)

ADM704B, Section 8, February 2013

Copyright© 2013 MSC.Software Corporation S8 - 8
EXERCISE

• Perform Workshop 8, “Organizing Customization with Command

Files,” in your exercise workbook

ADM704B, Section 8, February 2013

Copyright© 2013 MSC.Software Corporation S8 - 9
ADM704B, Section 8, February 2013
Copyright© 2013 MSC.Software Corporation S8 - 10
 SECTION 9
PLUGINS

ADM704B, Section 9, February 2013

Copyright© 2013 MSC.Software Corporation S9 - 1
ADM704B, Section 9, February 2013
Copyright© 2013 MSC.Software Corporation S9 - 2
WHAT IS IN THIS SECTION

• Creating an Adams/View Library

• Macros, Dialog Boxes as children of a Library
• The plugin Load & Unload Macros
• Adams/View partial binary files
• The plugin XML file
• Location for plugin files
• Setting the MDI_USER_PLUGIN_DIR variable
• Test the plugin

ADM704B, Section 9, February 2013

Copyright© 2013 MSC.Software Corporation S9 - 3
CREATING AN ADAMS/VIEW LIBARY
• A library is created from the command navigator as shown in the image
below.
• A library is just that: a container in which to hold other elements such as
macros, dialog boxes and variables.

ADM704B, Section 9, February 2013

Copyright© 2013 MSC.Software Corporation S9 - 4
CREATING AND ADAMS/VIEW LIBRARY (CONT.)
• Set the ‘Filter’ to ‘All’ to see the library in the database navigator:

ADM704B, Section 9, February 2013

Copyright© 2013 MSC.Software Corporation S9 - 5
MACROS, DIALOG BOXES AS CHILDREN OF A
LIBRARY
• It is a good practice to write/test macros separately.
• Once they are complete, read them into the library using the
command:
macro read file_name = "create_circular_pattern.mac" macro_name =
.example_plugin.MACRO_1 create_panel = yes
– Note how the macro name indicates that the macro is a child of the library.
– Dialog boxes are handled in a similar fashion
• Read the dialog box into View, naming it as a child of the library
OR
• Simply rename an existing dialog box (or macro) in your model such that it is the
child of the library.

ADM704B, Section 9, February 2013

Copyright© 2013 MSC.Software Corporation S9 - 6
PLUGIN LOAD AND UNLOAD MACROS

ADM704B, Section 9, February 2013

Copyright© 2013 MSC.Software Corporation S9 - 7
PLUGIN LOAD AND UNLOAD MACROS (CONT.)

• When the plugin library is loaded, Adams/View looks for a special

macro named LOAD under the library. If found, the macro is
executed when the plugin is loaded.
• Similarly, an UNLOAD macro is sought when the plugin is
unloaded; if found, Adams/View executes it.
• The LOAD and UNLOAD macros should do tasks such as
loading/unloading custom menus in View.

ADM704B, Section 9, February 2013

Copyright© 2013 MSC.Software Corporation S9 - 8
ADAMS/VIEW PARTIAL BINARY FILES
• Adams/View allows you to save portions of your existing database
session into partial binary files
• Save the custom library to the partial binary file. The plugin
automatically loads this binary file giving access to your
customization library.

ADM704B, Section 9, February 2013

Copyright© 2013 MSC.Software Corporation S9 - 9
PLUGIN XML FILE

• <basename>_plg.xml file needs to be created so that the

Adams/View Plugin Manager can find the plugin.
• The naming convention must be followed such that the
<basename> is same as the prefix part of the partial binary file.
• For example:
example_plugin.bin
example_plugin_plg.xml

ADM704B, Section 9, February 2013

Copyright© 2013 MSC.Software Corporation S9 - 10
LOCATION FOR PLUGIN FILES (XML, BIN)

• Adams/View searches for plugin files in the following order:

– Current working directory
– Private location for product (ie: MDI_ACAR_PRIVATE)
– MDI_USER_PLUGIN_DIR environment variable
– Site location for product (ie: MDI_ACAR_SITE)
– System path (ie: $PATH, %PATH%)
– Installation path of Adams
– Library path (ie: $SHLIB_PATH, LD_LIBRARY_PATH)

ADM704B, Section 9, February 2013

Copyright© 2013 MSC.Software Corporation S9 - 11
SETTING THE MDI_USER_PLUGIN_DIR VARIABLE

• To set an environment variable, identify a folder location where the

necessary files will be placed then point the environment variable
to this location.
• There are two ways to set an environment variable:
– Temporary method: Open a DOS command window and issue the
command:
set MDI_USER_PLUGIN_DIR=C:\temp\plugindir
• Adams/View must be launched from this DOS shell so that the environment
variable is properly picked up.
– Permanent method: Right-click on ‘My Computer’ on your machine and
select ‘Properties’. Under ‘Advanced’ tab select ‘Environment Variables’.
Under ‘User variables’ create your new variable.

ADM704B, Section 9, February 2013

Copyright© 2013 MSC.Software Corporation S9 - 12
TEST THE PLUGIN

• Launch Adams/View from the DOS shell where the

MDI_USER_PLUGIN_DIR environment variable was set.

• Go to Tools  Plugin Manager and check whether your plugin

appears in the list.

• Check on the plugin and hit OK to load the plugin. Verify that the
plugin library is loaded, then test the customization in the library.

ADM704B, Section 9, February 2013

Copyright© 2013 MSC.Software Corporation S9 - 13
EXERCISE

• Perform Workshop 9, “Working with Plugins,” in your exercise

workbook

ADM704B, Section 9, February 2013

Copyright© 2013 MSC.Software Corporation S9 - 14