Description

FRED can act as an OLE automation server, which means that FRED can be run remotely from other applications such as Microsoft Visual Basic, Microsoft Excel, Matlab, or any other application that can act as an OLE/Automation client.  In  this configuration, FRED is the automation server and the application which is controlling FRED is the automation client.  The following information describes the fundamentals of how to run FRED as an automation server.

The general sequence of operations for using FRED as an automation server is the following:

The client procedure should execute tasks in the following sequence:

The functions which perform tasks 1 - 3 above are part of the FRED "Core object Model" which is detailed below.

Controls

The Component Object Model (COM)

The collection of available server commands that control FRED is called the "Component Object Model".  The core object model consists of three objects: the Application object, the Documents Collection object, and the Document object.  The Application object is the FRED application, the Documents Collection object is a list of documents (i.e. FRED files) currently open in the FRED application, and a Document object is a particular document retrieved from the Documents Collection object.  Each object has associated properties and methods as outlined in the following table.

Please note that in addition to the properties and methods in the following table, FRED specific commands are also associated with the Application and Document Objects.  These commands are provided in the Scripting Reference Manual.

Using the FRED Library

In FRED v9.50 or later, it is possible to directly load the FRED Library into any application which can read type libraries.  With the FRED library referenced, the automation client has direct access to the FRED language extensions.  This method allows direct control of a FRED model through programs such as Microsoft Excel (see example).

Please note that in order to run the 64-Bit version of FRED through Excel using the FRED Type Library, it is necessary to have a 64-Bit version of Excel.

Application Notes

Starting FRED as an automation server

There are two ways to start FRED as an automation server.  The first starts FRED and returns the FRED application object.  The second starts FRED, adds an empty document, and returns the document object.

In general, if FRED is running when you invoke it via "CreateObject", the currently running copy of FRED is used as the automation server.  If no copy of FRED is running, then FRED is automatically started and used as the automation server.

Visual Basic Example

Set app = CreateObject( "FRED.Application" )
Set doc = CreateObject( "FRED.Document" )

Matlab Example

fredsvr = actxserver( 'FRED.Application' );

Array data

It is often desirable to pass array data as subroutine or function arguments between the client and server.  The internal format for representing an array in FRED is the SAFEARRAY.  This format is defined by Microsoft and applications using Visual Basic as the scripting language should be able to simply define arrays as usual without regard to the internal details of the array format.

Matlab does not use the SAFEARRAY as its fundamental array type.  The advanced command, feature('COM_SafeArraySingleDim',1), can be issued in Matlab to allow passing of one dimensional array arguments between FRED and Matlab.  A one dimensional array in matlab, test = [a;b;c], can then be passed to functions or subroutines within a FRED script.  The commands 'PutFullMatrix' and 'GetFullMatrix' can also be used to pass multidimensional array data to Matlab.

Examples

Using the FRED library in Microsoft Excel

The example below demonstrates an Excel VBA script that will open a new FRED document, define a lens element, add the element to the FRED document and then print the lens node information to the Excel workbook.

Before writing the VBA script, the FRED Type Library can be referenced, allowing the VBA script editor to provide syntax helpers for the FRED script commands.  In the Excel VBA editor this is accessed by going to Menu > Tools > References.  To add the FRED Library, scroll through the Available Reference list and check the entry "FRED Type Library" (making sure that the library is v9.50 or newer).

Sub main()

       'Create the application object

    Dim app As Object

    Set app = CreateObject("FRED.Application")

    app.Visible = True

    'Create the document object

    Dim doc As Object

    Set doc = app.SysNew("FREDTest")

    'Dimension a lens structure and node number

    Dim lens As T_LENS

    Dim lensNode As Long

    'Set the members of the T_LENS structure

    lens.glassCatalog = "Current"

    lens.glassName = "Standard Glass"

    lens.immerseCatalog = "Current"

    lens.immerseName = "Air"

    lens.param1 = 100

    lens.param2 = 0

    lens.paramType = "FocalBend"

    lens.semiApe = 25.4

    lens.Thickness = 10

    lens.wavelength = 0.5

    'Dimension an entity structure and node number

    Dim ent As T_ENTITY

    Dim entNode As Long

    'Set the members of the T_ENTITY structure

    ent.axesDrawable = True

    ent.Description = ""

    ent.limitsDrawable = False

    ent.Name = "MyLens"

    ent.neverTraceable = False

    ent.Parent = 2

    ent.traceable = True

    'Add the lens to the FRED document

    lensNode = doc.AddLens(ent, lens)

    'Update the document

    doc.Update

    Range("A1").Value = "Lens Node:"

    Range("B1").Value = lensNode

End Sub

Matlab as the Client

The following client script shows how to use FRED as an automation server through Matlab.  The script does not perform the same task as the previous Visual Basic script example.  This example can be found in the <install dir>\Resources\Samples\Scripts\Submitted by Users\ directory.

% defining global variables for the plotting
global fredfield xc yc
 

% ... makes black backgrounds for the plotting (matter of taste ;-)
colordef black
 

% Opening FRED and make it visible
fredsvr = actxserver('FRED.Application'); pause(1)
freddoclist = get(fredsvr,'Documents'); pause(1)
set(fredsvr,'Visible',1);
 

% Defining filenames and their path
testpath = 'c:\temp\fred\';
testfrd = 'matlab_spheric_lens.frd';
testfrs = 'matlab_spheric_lens.frs';
testdoc = [ testpath testfrd ];
testscr = [ testpath testfrs ];
 

% Opening the FRED document and compiling the script
freddoc = invoke(freddoclist,'Open',testdoc); pause(1);
fredscr  = invoke(freddoc,'GetEmbeddedScriptLib',0);
 

% Some sample script files that create and transfer the data to matlab
get(fredscr,'makerays');
get(fredscr,'makexycoords');
get(fredscr,'scfield');
 

% Plot
fredsurfplot;
 

Take special note of the two "pause" statements when opening FRED and making it visible near the beginning of the above example.  These provide time for FRED to open and prepare itself before execution continues in Matlab.  There are also other ways of providing for the necessary time delays.  Please see the other Matlab examples in the <install dir>\Resources\Samples\Scripts\Submitted by Users\ directory.

Matlab as the Server 

In this configuration Matlab is servicing requests from FRED, so Matlab is the Server and FRED is the Client.  To get this configuration to work, you should take the following actions:

In MATLAB:

    Start an instance of MATLAB

    Execute the command: enableservice(‘AutomationServer’,true)

    Execute the command: enableservice(‘AutomationServer’)

In FRED:

    Right mouse click in the script editor and choose: Edit > References

    Choose the Matlab Type Library

    Dimension your Matlab object in the script as type MLApp.MLApp

The above steps will ensure that 1) FRED uses the current instance of MATLAB as the server instead of the command console, and 2) FRED loads the Matlab type library and can recognize and execute the server’s application commands.  In general, it is not necessary to load the Matlab type library in FRED since the Matlab server can be generically defined as an Object.

Related Topics

Scripting With Libraries