NI AWR's Script Development Environment (SDE) allows you to create and execute macros and utilities to automate complex tasks from within the NI AWRDE. The SDE supports scripting in Visual Basic and includes syntax highlighting and powerful debugging capabilities.
...
To open the SDE, choose or click the toolbar button. The NI AWR SDE window opens.
The following table describes the components of the SDE are described in the following table:
Name | Description |
---|---|
Project | Script Project Browser (or simply, Project Browser). Allows you to create scripts to automate tasks within the NI AWRDE. The scripts display as two subnodes. The first subnode, Global, contains global modules. The second subnode, Untitled Project.emp contains project-specific modules also called local modules. |
Menus | A set of menus: | , , , , , , and Help. Most of the menu choices and commands are also available as buttons on the toolbar.
Script workspace | The area in which you design, run, and debug scripts. |
Immediate/Watch/Stack window | The area in which you can print the results of a running script and watch the value of the variables during the debugging process. |
Toolbars (Standard, Debug, and Edit) | A row of buttons that provides shortcuts for editing, running, and debugging scripts; creating new Code Modules; accessing VBA Object Browser Help; adding available references to a Project; and for accessing Immediate, Watch and Quick Watch Windows.To view a tooltip for a particular toolbar command, pass the cursor over the button. |
...
The scripting browser is along the left side of the SDE and organizes the scripts available in the project. Scripts can be either global , or local to a project. If a script is general purpose and can be used with many projects, you should save it as a global script. If the script only works with a specific project, you should save it as a local script.
...
Shown in the scripting browser with the name of the project, in this example “Untitled Project.emp”emp. ” Local scripts are saved in the project, so if you copy your project file to another machine, your scripts are automatically included.
...
Scripts stored in the Scripts or ScriptsUser folders are included in this. From the NI AWR Design Environment, select Help > Show Files/Directories to find these folders. Scripts folder contains the factory scripts shipped with the product installer. ScriptUser contains global scripts that the user manages. Global scripts are available to all projects. The Global subnode contains all global scripts that are stored separately in individual *.bas
files located in specific folders on your computer. You can add a new *.bas
file to your ScriptUser folder, then right-click the Global node and choose to make the new script available.
...
The code can either be in code modules or object modules. Code modules contain procedures that run from start to finish when executed. This is useful for creating macros or procedures for automating tasks that you would normally perform manually. Each module will begin with a 'Sub Main', and each code module is listed the project browser as a separate item. To create a module, right-click the Global or the local node and choose Insert Module. A new module is added to the node, and a new window will be opened with the 'Sub Main" defined.
...
An Object module runs code in response to events generated by the NI AWRDE object. Object modules do not have a Sub Main that executes when they run. Instead, they contain special functions called Event Handlers that execute in response to events that objects start. When run, the Basic engine waits for an event to occur, such as adding a schematic to the project. When the event occurs, the associated event handler code executes.
To enter the code that responds to an event, expand the project tree for the local scripts, into the Object Modules node and double click on the node named ThisProject. Note: we do not support global object modules at this time. In the code editor window, select the object that starts the event from the object list (this will be called Project for events from the AWR API), and then select an event from the Proc list. After you select an event, a handler procedure is added to the module, and you can add any additional code you want to execute. The following figures show this process.
...
Before the code can respond to events, you must run the module by clicking the Run button on the toolbar.
Next time you open the project containing object modules, a dialog box will appear asking if you would like to Enable enable or Disable disable macros.
If you choose Disable Macros, the object module will not be running. You can immediately edit the code, and you will need to click Run on the toolbar to be able to respond to an event.
If you choose Enable Macros, the object module will be running. You will need to click End on the toolbar to be able to edit the code, and the NI AWRDE will be automatically responding to events.
If you set option the option, Always use the settings and do not warn again, the dialog will not show again for that project. If you will need to change the settings and to have the dialog, there will be an entry in the user.ini file. Search for the project name in the user.ini and remove the entry for the warning about the script.
...
Click the
button on the toolbar or select Edit > References from the menus. A list of references similar to those shown in the following figure displays.Select the checkbox next to the reference you want to add.
If the desired reference is not listed, click the
button and locate the type of library you want to use.
The NI AWRDE object library is selected by default and references must be set for the object module and each code module separately. Each checked reference is searched in order from top to bottom.
...
The following figure shows the object browser with the NI AWRDE (MWOffice) type library selected.
...
The object list shows all the objects for in the current module
- The (general) object groups all of the procedures which are not part of any specific object.
- When in an object module, you can also select Project
...
- Selecting a procedure that is not bold inserts the proper procedure definition for that procedure, this mostly applies to object modules.
- Selecting a procedure that is bold will arrange the file such that the selected procedure is in view.
- (declarataionsdeclarations) takes you to the beginning of the file for where global variables can be defined.
...
To see language extensions, built-in instructions/functions, and user-defined procedures/variables press Ctrl-Space on a blank line in the IDE.
...
If you want to reference subroutines or functions in other *.bas
files, there are several options. This Referencing code can be a good way to track common groups of code you want to reuse and easily update.
Stand-Alone File on Disk
To reference subroutines and functions in a stand-alone file
...
The path to the file can be an absolute path or a path relative to the NI AWR Project file in which you are working. The disadvantage of this approach is that you cannot debug into any referenced functions.
...
When typing code, press the F1 key to display Help for the specific word the cursor is over. If the cursor is over a component that belongs to the NI AWR API, the NI AWRDE Help opens to the appropriate section. Newer Microsoft operating systems do not support the help system build into the current SDE. We recommend you use the PDF documentation to understand the SAX basic specific commands.
...
There are various techniques to debug scripts that will be described below.
Break Bar
The break bar shows which lines have breakpoints. It also shows which line is next to execute. Clicking on the break bar toggles the breakpoint for that line. Alternately, the Debug > Toggle Breakpoint will toggle the current line of the cursor to have a breakpoint or not.
...
When your code has stopped at a breakpoint, you have various options, ; the options are available from the Debug menu. See the menu listings below for the hotkeys.
...
The immediate window is automatically displayed above your code. Use your mouse to drag the divider between the code and the Immediate window to change how big each one is relative to the window size. The Immediate window is used to evaluate an expression, assign a variable or call a subroutine.
- Type "?expr" to show the value of "expr".
- ype Type "var = expr" to change the value of "var".
- Type "Set var = expr" to change the reference of "var".
- Type "subname args" to call a subroutine or built-in instruction.
- Type "Trace" to toggle trace mode. Trace mode prints each statement in the immediate window when a macro/module is running.
...
The Watch window is automatically displayed above your code when the code paused during debugging. The Watch window is used to list the variables, functions, and expressions that are calculated and displayed.
- Each time execution pauses the value of each line in the window is updated.
- The expression to the left of "->" may be edited.
- Pressing Enter updates all the values immediately.
- Pressing Ctrl-Y deletes the line.
- Add variables to the Watch window typing the name and typing Enter. Alternately, when the code is paused, put your cursor over a variable and select Debug > Add Watch.
Stack Window
The Stack window is automatically displayed above your code when the code paused during debugging. The Watch window is used to list the lines which called the current statement.
...
Use the controls on the left to add items to design your form. Hover your mouse over each item to understand what they are for. When you are done, close the dialog, and the code for the form will be inserted into your script.
...
The Caption field will be the name of the dialog, and the Dialog Function name is to reference the function to do advanced dialog controls.
...
When closing the dialog with the Dialog Function field filled, you will get the prompt below. You usually would click next, and then the shell of the dialog function code will be added.
...
You can run scripts directly from the NI AWRDE Scripts display either one of three areas.
...
<module name>(<sub name>). Any Sub in a given module that takes no input arguments is available in this list. You can hide any such sub by using the Private declaration before the name of the subroute. For example, the following figure shows a macro named "example" that has three sub functionssubroutines, a,b, and c.
The list that displays is in the format
Notice that the third sub is declared private. If you choose sub functions subroutines as shown in the following figure.
you can access only the first two...
You can control how scripts display in the , you can add a line that defines the folder in which to display the script. This line is in the form '$MENU=name
where name
is the desired folder name. The name of the sub displays under that folder. You can use the folder name "hidden" to prevent that sub from displaying. For example, you can add the line "' $MENU=Data" to display this script under the Data sub menu. Only one level of folders is allowed. When you use this syntax the script is only in this folder; it is no longer in the or folders. Because of this structure, NI AWR recommends that you write your scripts with one Sub Main that uses the hidden folder tag, and then give your code a meaningful name that you then call from the Sub Main. This is because you need a Sub Main to run the script from the SDE, but you want a meaningful name when running the script from the menu. The following example scripting code demonstrates these various concepts.
...
The following figure shows how this script displays in the NI AWRDE menu.
Notice that there is a folder named Layout and a script named "Delete_Unassociated_iNets" under that folder.
...
Item | Description |
---|---|
MWOffice | Switch control to the NI AWR Design Environment |
Save | Save the current NI AWRDE Project. |
Print the current macro/module. | |
Print Setup | Select the default printer. |
Close | Close the SDE |
...
Item | Description (Hot Key) |
---|---|
Step Into | Execute the current line. If the current line is a subroutine or function call, stop on the first line of that subroutine or function. (If the macro is not active, start it.) (F8) |
Step Over | Execute to the next line. If the current line is a subroutine or function call, execute that subroutine of or function completely. (Shift+F8) |
Step Out | Step out of the current subroutine or function call. (Ctrl+F8) |
Run to Cursor | Execute until the line the cursor is on is the current line. (If the macro is not active, start it.) (F7) |
Quick Watch | Show the value of the expression under of the cursor in the immediate window. |
Add Watch | Add the expression under of the cursor in the watch window, only avaialble available when a script is paused. |
Toggle Breakpoint | Toggle the breakpoint on the current line. (F9) |
Clear All Breakpoints | Clear all breakpoints. (Shift+Ctrl+F9) |
Set Next Statement | Set the next statement to be executed. Only statements in the current subroutine/function can be selected. |
Show Next Statement | Show the next statement to be executed. |
...