WS12-1 ADM704-705, Workshop 12, August 2005 Copyright 2005 MSC.Software Corporation WORKSHOP 12 MACROS AND PARAMETER SYNTAX

WS12-1ADM704-705, Workshop 12, August 2005Copyright 2005 MSC.Software Corporation

WORKSHOP 12

MACROS AND PARAMETER SYNTAX



WORKSHOP 12 - MACROS AND PARAMETER SYNTAX

Problem statement In Workshop 11 – Macros: Overview, you wrote parameterless macros

that worked well for specific purposes. However, you saw that parameterless macros have some limitations because they don't allow data to be passed into them. In this workshop you will learn how to write ADAMS/View macros that use parameters, allowing them to become general purpose solutions and powerful tools for automating your work.

You will use the diskette transfer model and a customized Arc toolkit, and will run and write macros that do the following:

Create marker midway between two markers

Swap markers from one part to another

Replicate parts and offset them a prescribed distance along a given axis

Create arcs and outlines that are tangent





Getting started

To get started:

1. Start ADAMS/View from the directory, mod_12_macro_syntax.

2. Select Create a new model, using the default settings.

3. Create two markers on ground in two different locations in the window.



Example of a simple macro

The online help has some basic macro examples. One of the macros, ex1_mar_mid, will create a new marker midway between two existing markers that you specify. Let’s look at it closer to see how it works.

To take a closer look at the macro:1. Import the command file, load_online_doc_macros.cmd.

This loads the macro (and a few other example macros) into the database.

2. Using the Command Navigator, select the ex1_mar_mid command.



ADAMS/View automatically generates the Ex1 Mar Mid dialog box. The text boxes correspond to parameters in the macro.

3. Close the Command Navigator.

4. Run the macro as follows: First Marker: MARKER_1 Second Marker: MARKER_2 New Marker Name: midway

5. Select Apply.

ADAMS/View creates a marker named midway, halfway between the two markers you specified.



6. Display the macro commands that created the marker: From the Tools menu, point to Macro, point to Edit, and then select

Modify.

From the Database Navigator, select the macro ex1_mar_mid.



7. Move the macro editor so it is alongside the Ex1 Mar Mid dialog box, so you can compare its text boxes to the text in the macro editor.

8. Review the macro commands, noting the following:

A. Three parameters (indicated by $ at the top of the macro) are used to pass in the data you entered in the three text boxes.

B. These parameters, have type qualifiers indicated by T=...

Note: The type marker is different from the type new_marker.

C. The labels in the dialog box correspond to the naming of the parameters, without the underscore and $ characters. Therefore, Second Marker corresponds to $SECOND_MARKER.

D. A new marker will be created at a location calculated from the database values of the existing marker locations. It will have the name that is passed in through the $NEW_MARKER_NAME parameter.



9. Right-click the New Marker Name text box that currently contains the text midway, point to Field Info, and then select Validate.

Notice that the text box turns yellow, and ADAMS/View issues a warning message. Here you see the parameter's type qualifier in action. The qualifier specified that parameter must be a new marker, and since midway already exists, it's no longer new and is, therefore, an invalid choice. Now, if you want to create another marker between markers, you will have to choose a unique name.

10. Close the Ex1 Mar Mid dialog box.



11. Display information on the midway marker you created and review its local location expression.

((MARKER_1.loc_x + MARKER_2.loc_x) / 2), ((MARKER_1.loc_y + MARKER_2.loc_y) / 2), ((MARKER_1.loc_z + MARKER_2.loc_z) / 2)

Notice that the expression ($FIRST_MARKER.loc_x) in the macro has become (MARKER_1.loc_x) after the data was passed through the macro.

Tip: Use the eval function in your macros to reduce an expression to literal values.

Now you've seen the structure of a basic macro. Let's write one by hand.



Writing a macro to change the parent of several markers Let's write a macro that will swap the parent of several markers

from one part to another.

To write a macro:1. Delete the current model from the database:

Close the macro editor.

Select the Select tool so nothing is selected.

From the Edit menu, select Delete.

The model is selected in the Database Navigator.

Select OK.

ADAMS/View deletes .model_1.



2. Import the command file named ch_par_start.cmd.



3. Display the Macro editor so you can create a new macro.

Tip: Under the Tools menu, point to Macro, point to Edit, and select New.

4. Clear the Macro Name text box by placing your cursor at the start of the text box and pressing Ctrl-k.

5. Name the macro, mar_swa_par.

6. Clear the selection of Use Macro name.

7. Give the macro the User-Entered Command: marker swap_parent.

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 example, entering MARKER CREATE is invalid, because a MARKER CREATE command already exists. Entering MARKER GENERATE is valid.



8. Set Wrap in undo to No.

You can specify whether or not the entire macro can be undone with a single UNDO command. Note that UNDO, while convenient, may consume a great deal of memory for a very large macro, or slow macro execution noticeably, even if you do not actually use the UNDO.Tip: You can check the memory usage of UNDO with the following command:

list_info undo write_to_terminal = on

To learn more about UNDO commands in general, open the Command Navigator, point to undo, and then select HELP at the bottom of the window.

Now it's time to construct the macro by entering text in the large Commands text box. ADAMS/View does not check your entries in the Commands box for correct syntax when you create the macro, only when the macro is executed.



9. Enter the following parameters and commands:

!$marker:t=marker:C=1,0

!$new_parent:t=part

!END_OF_PARAMETERS

variable create variable=tmp_model & object_value= (eval(DB_DEFAULT(.system_defaults,”model”)))

for variable=tmp_loop object=$marker type=marker

marker modify marker=(tmp_loop) &

new_marker_name= & .(eval(tmp_model)) . ($new_parent.name) (tmp_loop.object_value.name)

end

variable delete variable=tmp_model





Here's a description of what some of the key pieces do:A. The C=1,0 is a Count qualifier that specifies the number of values

required. Here, it's allowing one or more markers to be passed into the macro.

B. The colon character is used to separate the various qualifiers for a parameter.

C. The temporary variable tmp_model passes in the name of the default model. This variable is later used as a part of the name of the new marker and is then deleted at the end of the macro.



D. The FOR/END loop is operating on the set of objects passed in through the $marker parameter. For each marker it will swap the parent from its current part to that which is passed in through $new_parent.

E. The new_marker_name is constructed in pieces. The use of parentheses is required on some pieces because they are expressions (that is, accessing database values). Here's a breakdown of each:

(eval(tmp_model)) becomes MODEL_x

($new_parent.name) becomes PART_x

(tmp_loop.object_value.name) becomes MARKER_x

So the new_marker_name takes the form: .MODEL_X.PART_x.MARKER_x.



Note: If the .name database operator hadn't been used on the $new_parent parameter, the macro wouldn't have worked. That's because the full part name would have been expanded, and as a result, an unacceptable name would have been formed, like this:

10. Select Apply.

ADAMS/View creates the macro.Tip: For further discussion of macro parameters, the exclamation point (!), END_OF_PARAMETERS, and more, see the Knowledge Base Article 8885, available at: http://support.adams.com/kb/faq.asp?ID=kb8885.dasp.



11. Run the macro from the Command Navigator so that a dialog box is auto generated.

From the Command Navigator, select marker, and then select swap_parent.

ADAMS/View displays the dialog box.

You may have noticed from other dialog boxes that some text box backgrounds are white while others are gray. This color difference distinguishes the required text boxes (white) from the optional ones (gray). Here, both of your text boxes are white, therefore all of your parameters are required.



12. Enter the following: Marker: Browse and select the following markers on PART_2:

MARKER_2, MARKER_3, MARKER_4

New Parent: Pick the blue part (PART_3) off of the screen.

13. Select Apply.

The markers now belong to PART_3.

If you had made any typographical mistakes, error messages would have been issued. This is quite common as it's difficult to type a macro without any errors, even with substantial experience writing macros.

Even if your macro was successful, review the next section because it covers essential information for developing your own macros.



Modifying a macro that isn't working It’s important to know that an auto-generated dialog box grabs and

stores the parameters from the macro when it is initially generated. If you subsequently modify the parameters in the macro, they are not automatically updated in the dialog box. Therefore, you must delete the auto-generated dialog box and re-issue the macro from the Command Navigator so that ADAMS/View will use the new macro parameters. If you only modify commands, you do not have to delete and regenerate the dialog box.





To modify macro parameters and commands:1. Delete the macro's auto-generated dialog box.

From the Tools menu, point to Dialog Box, and then select Delete.

At the bottom of the Database Navigator, set Sort by to No Sort.

Scroll down until you see your dialog box name.

2. Select the dialog box you want to delete, that is, mar_swa. This dialog box should be at the bottom of the list in the Database Navigator.

3. Select OK.

4. Modify your macro (using the macro editor) to correct the syntax errors.

5. Select Apply.

6. Access the macro command using the Command Navigator.

ADAMS/View generates a new dialog box.

7. Run the macro to see if your modifications have fixed the problem.



To modify commands only:1. Modify your macro (using the macro editor) to correct the syntax

errors.

2. Select Apply.

3. Run the macro to see if your modifications have fixed the problem.



Exporting a macro Once your macro is functioning the way you want it to, you should

save it for future use. Although you could save the database and the macro would be stored there, we don’t recommend it. It's a better idea to save your macros in ASCII (flat text) format, like a command file. This will ensure successful upgrades from one ADAMS/View release to the next.

Because a macro is not the child of a model, it will not be written out when you export your model as a command file. The macro export is done through its own command language.



To export a macro:1. From the Tools menu, point to Macro, and then select Write.

Macro Name: .mar_swa_par File Name: mar_swa_par.cmd

2. Select OK.

3. Review the exported macro in a text editor.

It should look similar, if not identical, to the way it did in the macro editor.



Writing a macro that calls another macro Because the macros you write become extensions of the

ADAMS/View command language, it is easy to begin using them just like any other command. For instance, you can write a macro that calls another macro you've written. In this section, you will write a macro for making multiple copies of a part and project them along the axis of a marker. The macro will achieve this by calling another macro (for single replication) in a FOR loop so that it is executed repeatedly. This is similar to how you copied the diskettes in Workshop 10 – Conditional Constructs and Loops, but this time you will use a macro with parameters.



To write a macro that calls another:1. Open a new database, and then import the command file,

disk_start.cmd.

2. Import the macro part_replicate_single_mac.cmd. From the Tools menu, point to Macro, and then select Read.

Macro Name: par_rep_single

File Name: part_replicate_single_mac.cmd

Accept the defaults for the remaining text boxes, and then select OK.





3. Display the macro in the macro editor and review the commands used.



Items of special interest in this macro are:

A - Use of a List type qualifier for $which_axis. This allows the user to choose from a list of axes: x, y, and z. The default qualifier, D, has set the default value to z. If the user doesn't choose an axis, the z-axis is used.

B - Temporary local variables ($_self.tmp_mod, $_self.tmp_name) are defined up front. This is good macro programming practice. They are often used to store a value or object up front, such as the model name, so that you don't have to do a database lookup or write a lengthy expression every time. That's why $_self.tmp_mod is there. In other cases, they are handy for prototyping out strings, such as message text or part names. Here, the $_self.tmp_name is used to construct the name of the replicated copy.

The $_self is often confusing at first glance, but is actually pretty straightforward. It is possible to create an ADAMS/View variable as a child of anything. This includes macros. This is very useful when creating clean macros with variable names that make sense. Overall, it cleans up the entire structure of the database.



This is what $_self is if you were to think of it as a macro parameter defined at the top of a macro:

!$_self:T=macro

Therefore, $_self is the macro itself, and $_self.tmp_var is a variable whose parent is the macro.

C - Use of IF/ELSEIF/END logic to decide along which axis to project the copy.

D - The cleaning up of local variables at the end of the macro by deleting both of them with a simple wildcard, $_self.*.



4. Save the database as disk.bin so you can quickly reopen it later.

5. From your working directory, open the file, part_replicate_multi_partial_mac.cmd in a text editor.

This file contains an incomplete version of the macro you need to write. The parameters you need to use can be found in the commands but have not been properly qualified at the top of the file.



6. Define the parameter qualifiers at the top of the file, keeping in mind the following:

You can only specify a single marker along which to project.

The distance to offset each replicate (that is, copy) is a real number with a default of 100.

The maximum number of copies you can make with a single execution of the macro is 25 and the minimum is one. Use a default value of three copies.

Let the z-axis be the default axis, but choose from a list of three: x, y and z.

For more information, see the Customize tab in the ADAMS/View online help.

7. Save your macro file as part_replicate_multi_mac.cmd.



8. Import the macro par_rep_multi.

Tip: If you encounter errors and want to refresh the model, just open a new database and choose the file, disk.bin, which you saved earlier.

9. Execute the macro you wrote so it makes three copies of DISK_1 offset 5 mm a piece along the z-axis of the diskette's center-of-mass.

In the Command Navigator, select part, select replicate, and then select multi.

Marker To Project Along: .model_1.DISK_1.cm Offset Distance: 5 Number Of Copies: 3 Which Axis: z



10. Select OK.

The DISK_1 part has been successfully replicated three times.



Example of how to organize a suite of macros Sooner or later you will have written enough macros that keeping

them organized will be a task in and of itself. Let's look at one approach you could use to organize a suite of macros.

Several versions ago, one of the application engineers at the MSC.Software office in Germany had assembled many of his macros and packaged them together for internal use as the TK_toolkit. Since then, ADAMS/View has changed quite a bit, making many of the macros in the toolkit obsolete. However, there are still some very useful gems: a fine set of examples from which you can harvest tricks, expand your understanding of macro syntax usage, and see some creative ideas.



The Arc Toolkit example

A large portion of the macros in the TK_toolkit dealt with the creation of arc geometry. Here we've taken that subset of macros and grouped them together in a custom interface window, complete with its own set of menus, and called it the Arc Toolkit.



To organize a macro:1. Open a new database, and select Create a new model.

2. Draw a simple arc on ground (using the Main Toolbox).

3. Load the Arc Toolkit by importing the command file, custom_window_start.cmd.

Notice that it displayed the standard toolbar, which appears beneath the Main menubar, as shown in the figure on the previous slide.

4. To display the Arc Toolkit, from the standard toolbar, select the Arc Toolkit icon



5. Browse through the menus to see the variety of choices available. Behind each menu push button is a separate set of macro commands.

6. Select one of the menu buttons and fill in the text boxes in the dialog box accordingly.

7. Pick one or two of the macros and review their commands in the macro editor.

Tip: You can find the macros inside the library, my_cust.

Do you notice anything different about the macro(s)? One big difference is that $_self was not used. Why? Because it didn't exist back when the macros were originally developed. Keep that in mind when you review these or any other macros, because some of the techniques used may be a bit dated when judged against the latest standards or available commands and features.



Using a build file When you imported the file that built the Arc Toolkit, the building

was being done in a creative way. All of the macros for the Arc Toolkit are in a separate subdirectory. An environment variable stores the path. When the build file is imported, it uses the value of the environment variable to know where to look for the macros. Here you’ll learn more about how it was done.


WORKSHOP 12 - MACROS AND PARAMETER SYNTAX To use a build file:

1. Open the custom_window_start.cmd file in a text editor.

2. Review the general structure of this build file. (We refer to it as a build file because it builds the toolkit.) Here are the primary sections:

A. The PUTENV design-time function is used so that the environment variable tk_tools is set to the directory path where all of the macros reside. (Setting the environment variable using a command in this fashion is optional. Although you must set the environment variable for the macros to load properly, it is not necessary to set it with this command. You could set it directly in a UNIX or DOS shell, if you prefer.)

B. An ADAMS/View library is created, which acts as a repository for all the customizations of the Arc Toolkit, such as macros and menus. This keeps the database organized so that everything customized is isolated from the standard interface objects.

C. ADAMS/View reads the macros into the database and stores them in the library, .my_cust. The path to each macro file is constructed by getting the value of the environment variable and concatenating that string with the known path beneath the known macros subdirectory structure.



A

B

C



D.An interface window, menubar, and menus are created.

D



E. Menu push buttons are defined, with each having an underlying macro command.

You will learn more about D and E in Workshop 13 – Creating Custom Menu Buttons.

This is one approach for building a suite of customized macros. You might consider doing something similar with the macros you develop.

You have learned to write macros. You can find more information about the syntax in the online help.

E



Other resources This workshop contains a few macros from the Knowledge Base.

You can find the macros in the subdirectory, from_kb. Some of the subdirectories are:

contact_site - Contains a macro, cont_site_mac.cmd, for visualization of the site of contact. This is a good example of how to use comments in your macro for documentation purposes.

fixed_jnt_selected parts - Contains two macros for creating fixed joints for every part that is on the select list.

geometry_select_only - Contains a menu button that uses a parameterless macro to loop through all the parts on the select_list and find the immediate children that are of type=geometry. Then, it empties the select list and replaces it with those geometries that it found. It also displays the select list manager so you can remove some geometry from the list.



line_of_markers - Contains a macro, line_of_markers_mac.cmd, that uses a FOR loop to generate a number of new markers equally spaced along the line between two existing markers. All new markers will automatically belong to whatever part is currently the default and will be given unique names like MAR_1, MAR_2, and so on. The new markers will all have their primary axis (which is the z-axis, by default) pointing from the first marker toward the second marker.

list_inactive_objects - Contains a macro, check_if_inactive.mac, that will loop through parts, forces, and joints in a model. When it finds an object that has attributes of active=off, it will put it inside a group. This group of objects will be listed later in the Information window when the macro finishes running.

solver_curve_to_polyline - Contains a macro, curve2poly.mac, that will convert an ADAMS_curve entity to a Polyline entity. All you have to do is specify the curve that you want converted and the marker representing the reference frame for the data. The polyline will be created and will belong to the parent of the marker specified.

For more information, see the MSC.ADAMS Knowledge Base, located on the support site (http://www.mscsoftware.com/support/prod_support/adams/). To find macros, use the keyword 'macro' or perform boolean searches like 'macro* and joint' or 'macro* and beam'.



Several older macros, from version 8.2, are on the CD in the directory, old_v8_macros. This directory contains many macro examples that were shipped with version 8.x (as mentioned in Knowledge Base Article 6660, which is available at:

http://support.adams.com/kb/faq.asp?ID=kb6660.dasp). None of the macros provided there have been updated for release 9.x or beyond. In fact, it's possible that the functionality provided by a given example may now be superseded by standard ADAMS/View features. Regardless, they represent an assortment of examples from which you can improve your understanding of syntax and expressions, and what you can do with the macro language in general. See the file, readme.txt, in that directory for a list of the macros available.

The macros for this training course are available from your instructor.



Optional tasks

1. Write a macro that creates markers at every vertex of a given polyline. Use either a FOR/END or a WHILE/END construct.

2. Write a macro, poly_2_outline_mac.cmd, that converts polyline geometry to outline geometry.

3. Review the commands for the macro that was used to sweep the value of a design variable. You can find the macro, var_swe_mac.cmd in the subdirectory, DV_sweep.

4. Write a macro, cre_imp_sfo_mac.cmd that creates an impact SFORCE from two markers, and the IMPACT function parameters: stiffness, damping_coefficient, and free_length. For simplicity, for this example, hardcode the exponent to 1.0 and the penetration to 0.1.



5. Write a macro, display_joint_mac.cmd, that displays a joint and its parent parts.

6. Try out the macro, tra_swe_btw_mar_mac.cmd, which can sweep the animation trace in ADAMS/PostProcessor from one marker to another.

Documents

WS12-1 ADM704-705, Workshop 12, August 2005 Copyright 2005 MSC.Software Corporation WORKSHOP 12 MACROS AND PARAMETER SYNTAX