OLE Automation From a Script | OLE Automation From a Compiled Language

OLE Automation

Based on the Component Object Model (COM), STK can be used as an automation server on Microsoft Windows. Automation is a protocol that allows one application or component (the client) to control another application or component (the server).

STK can be started and controlled by any Windows program that can be an automation client. A program controls STK by sending commands to it. If you have used Microsoft Office automation (for instance to automate Excel), you will apply the same concepts and capabilities to STK automation. Other programs such as MATLAB and ArcGIS can also be used as automation clients. In addition, automation client programs can be written in Visual Basic, C++, VBScript, JScript, Perl, and other languages.

OLE automation can be used both from scripts and from external applications. In both cases the AgUiApplication library (AGI.Ui.Application namespace) is used.

Generally scripts use the AgUiApplication library in late binding mode while compiled applications (for instance .Net or Java) use early binding. In late binding, types exceptions are resolved at run-time, so a syntax error will result in an exception at run-time. With early binding, types are resolved at compile time, and syntactical errors will break at compile time. Early binding also leads to better performance than late binding, as the compiler performs some steps that will no longer need to be performed at runtime.

Once you start a new instance of STK or attach to an already running instance, you can:

You can start or connect to STK by using either the STK.Application or STK<ver>. Application (for instance STK11.Application) identifiers (also called ProgIds in OLE automation terminology). There are other ProgIDs available that enable various scenarios (like connecting to a specific instance of STK, or enumerating all the instances of STK currently running). Program IDs (ProgID) supported by AGI Products are outline on a separate page.

Note: Sending asynchronous Connect commands to STK is not supported over COM.

Note: Running the COM interface between two different computers is not recommended.

OLE Automation From a Script

You can use OLE automation from most scripting environments (VBScript, JScript, Perl, Python, MATLAB, etc.).

Below is a simple example that starts a new instance of STK using JScript, and then creates a new scenario using the STK Object Model:

// Starts a new instance of STK
var stk = new ActiveXObject('STK11.Application')

// Do not quit when script terminates
stk.UserControl = true

// Access the STK object model from the Personality2 property (of type IAgStkObjectRoot)
stk.Personality2.NewScenario('Demo')

You can also connect to a running instance of STK and then use the STK Object Model. For instance, still in JScript:

// Attach to a running instance of STK
var stk = GetObject('', 'STK11.Application')

// Use the STK object model. The Personality2 property is of type IAgStkObjectRoot.
stk.Personality2.NewScenario('Demo')

Note: The OnQuit event is raised by the application upon exiting to let external components such as plugins, out-of-process applications and User Interface plugins perform necessary cleanup operations before the application is terminated.

OLE Automation From a Compiled Language

You can also connect and drive STK from a compiled language. Compiled code may be implemented in a variety of languages (Visual Basic, Visual C#, C++, Java, etc.) that support COM interfaces.

In general you first need to add a reference to the required libraries and namespaces so the compiler can check the correctness of the code. The names of the libraries and namespaces vary with your specific development environment and language. For instance, PIAs (Primary Interop Assemblies) are provided for .Net development, while jar files are available for Java development. Please refer to the tutorial or reference documentation for more details.

The following example shows how a simple C# console application can start STK and create a scenario:

using AGI.Ui.Application;
using AGI.Ui.Core;
using AGI.STKObjects;

namespace ConsoleApplication3
{
class Program
{
[STAThread]
static void Main(string[] args)
{
// Starts STK Application
IAgUiApplication uiApp = new AgUiApplicationClass();

// Launches STK Personality
uiApp.LoadPersonality(“STK”);

// Do not quit when script terminates and show STK GUI
uiApp.UserControl = true;
uiApp.Visible = true;

// Use the STK object model to create a new scenario.
IAgStkObjectRoot root = uiApp.Personality2 as IAgStkObjectRoot;
root.NewScenario("Demo");
}
}
}

Alternatively you can also connect to a running instance of STK as shown in the following example.

using AGI.Ui.Application;
using AGI.Ui.Core;
using AGI.STKObjects;

using System.Runtime.InteropServices;

namespace ConsoleApplication3
{
class Program
{
static void Main(string[] args)
{
// Starts STK
IAgUiApplication uiApp = Marshal.GetActiveObject("STK11.Application") as IAgUiApplication;

// Use the STK object model to create a new scenario.
IAgStkObjectRoot root = uiApp.Personality2 as IAgStkObjectRoot;
root.NewScenario("Demo");
}
}
}

Related Topics:

STK Programming Interface 11.0.1