Overview

Macros can be executed in two modes:

• Synchronous – wait for the macro to finish and return a result.
• Asynchronous – run the macro in the background without waiting.

callMacro (synchronous)

Executes a macro and waits for it to finish. Returns the macro output as a string.

JavaScript / JScript.NET

var params = { Name: "User", Count: 5 };
var result = callMacro(false, "MyMacro", "Common\\Utilities", params);
writeln(result);
    

PowerShell

$params = @{ Name = "User"; Count = 5 }
$result = callMacro $false "MyMacro" "Common\Utilities" $params
Write-Host $result
    

Parameters

• bDisplayResult – show macro result window (true/false)
• macroName – name of the macro
• macroPath – folder path inside the macro tree
• params – parameter object (JS object or PS hashtable)

Notes

• Blocks until macro completes.
• Returns a string result.

callMacroAsync (asynchronous)

Executes a macro in the background without waiting for completion. Does not return a result.

JavaScript / JScript.NET

var params = {};
callMacroAsync(false, "LongRunningTask", "Common\\Tasks", params);
    

PowerShell

$params = @{}
callMacroAsync $false "LongRunningTask" "Common\Tasks" $params
    

Notes

• Does not block the UI.
• Ideal for long-running or background tasks.
• Does not return a value.

Parameter Passing

Parameters may be any object supported by the scripting engine. AdvantageBuilder does not impose restrictions on the types you can pass.

• JavaScript / JScript.NET – objects, arrays, strings, numbers, booleans, nested structures
• PowerShell – hashtables, PSCustomObjects, arrays, strings, numbers, nested objects

Example

    var params = {
    FirstName: "John",
    LastName: "Smith",
    Items: [1, 2, 3],
    Details: { Active: true, Level: 4 }
    };

    callMacro(false, "ProcessUser", "Common\\Users", params);
    

Parameters can be simple or deeply structured. Both synchronous and asynchronous macro execution support full object passing.

Return Values

Synchronous macros return a string. The content depends on what the macro writes using:

• writeln() (JavaScript)
• Write-Host (PowerShell)
• Template output

Asynchronous macros do not return a value.

Choosing an Execution Mode