Writing a JScript Expression
A Macro JScript Expression contains one or more Macro API Commands. These commands are used to obtain information from the Asset Database or modify information in the Asset Database. A Macro however is not just a sequential series of commands; the commands must be able to interact with each other, one command might provide input for another command. Furthermore it might be necessary to only execute a command under certain conditions and the same command may have to be executed many times with different input parameters. The Macro API Commands are therefore 'tied together' via JScript syntax. The following diagram explains how the different V-Suite CORE components interact together to execute a Macro where the JScript Engine evaluates the JScript Expression and calls the Macro API to execute Macro API Commands. The Macro API integrates with V-Suite CORE to read and write data to the Asset Database.
When writing and testing the Macro JScript Expression it important to understand the following concepts:
JScript Errors
JScript syntax is evaluated by the JScript Engine. The Macro can not be executed if the JScript Expression contains JScript syntax errors. The Macro Execute Wizard will abort the Macro and display the error;
Consider the following expression:
The Macro Execute Wizard will display the error:
Another example of invalid JScript Syntax:
The Macro Execute Wizard will display the JScript syntax error:
(The Search.GetAssetsByTemplate parameters are not the correct data type)
One will observe from above examples that invalid JScript syntax will always abort Macro execution.
Macro API Command Errors
The Macro API however is designed in such a way that if a Macro API Command fails it will not abort Macro execution.
Consider the following expression:
Note that there are no syntax errors so Macro execution will not be aborted, however there is a typo at line 2 (parameter Plnat). The command at line 2 will not be able to get the workspace however the Macro Execute Wizard will not display any errors, it will execute all commands and display the message that was send from the Macro;
If the JScript expression contains many commands it may be hard to find the command that is causing the problem. The user who wrote above example was expecting a result and needs to find out why the script is not returning the expected result. The JScript Editor does not support debugging, however the Macro API will report errors when the Macro is executed in verbose mode. In the Macro Wizard check the Verbose Mode;
The Macro Wizard will display the Macro API Errors:
Error Handling
Because Macro API Command errors will not abort Macro Execution it is highly recommended that you implement error checking like;
var workspace = Database.GetWorkspace("Plant")
// Verify that workspace exists.
if (workspace == 0)
{
// Stop the Macro
}
else
{
// Continue the Macro
}
So how can Macro execution be aborted if an error is encountered? If you have done some reading on JScript you may have read that you can generate an error condition via the throw statement (throw an exception). The following sample illustrates how you can use this statement to stop execution if a command failed.
try
{
var workspace = Database.GetWorkspace("Asset Workspace")
if (workspace == 0)
{
Messages.SendMessage("Asset Workspace not found !")
throw "Handled"
}
else
{
var appearance = Database.GetAppearance("Blue")
if (appearance == 0)
{
Messages.SendMessage("Appearance 'Blue' not found !")
throw "Handled"
}
// More Code to do something
}
}
catch(e)
{
if (e != "Handled")
{
throw e
}
else
{
Messages.SendMessage("Macro Aborted. Please contact your V-Suite CORE Administrator.")
}
}
Parameters
Macro's may receive input from the user. Parameters have a name and strongly typed value. To obtain a parameter value use reserved global variable PARAMETERS;
var paramValue = PARAMETERS.Get("Parameter Name")
Constants
Some Macro API functions will require you to specify argument string values. For instance to set the position of a cylinder primitive you must specify the name of the cylinder position property;
var ok = Primitives.SetPrimitivePropertyValue(cyl,"GraphicPosition", cylPos)
You may not know the name of the cylinder position property and specifying hard-coded names in script is from a maintenance and versioning aspect not always a good practice. It is therefore recommended that you use reserved global variable CONST where possible. This object will provide most common pre-defined constants and is also supported by the auto-complete feature in the JScript Expression Editor. Thus to set the cylinder position property;
var ok = Primitives.SetPrimitivePropertyValue(cyl, CONST.CylinderProperties.Position, cylPos)
Using .NET Class Library
Macros are intended to perform actions on the Asset Database. If you are an experienced JScript user you will probably know that the .NET class library provides many classes to perform a multitude of tasks. Please note that the JScript Engine used by V-Suite CORE does not allow you to use these classes. You will be able to use the different JScript Objects to perform Math functions, String Manipulations and many more and the Macro API provides functions to perform actions in the Asset Database but you will for instance not be to perform actions on the File System. In addition the Macro API provides some Utility Classes which methods can be used to perform miscellaneous operations.