OLE and Server Process support

Old Content - visit altium.com/documentation

Parent page: EnableBasic

Overview of OLE support

Object linking and embedding (OLE) is a technology that allows a programmer of Windows-based applications to create an application that can display data from many different applications and allows the user to edit that data from within the application in which it was created. In some cases, the user can even edit the data from within their application.

An OLE object refers to a discrete unit of data supplied by an OLE application. An application can expose many types of objects. For example, a spreadsheet application can expose a worksheet, macro sheet, chart, cell, or range of cells all as different types of objects. The OLE control is used to create linked and embedded objects. When a linked or embedded object is created, it contains the name of the application that supplied the object, its data (or, in the case of a linked object, a reference to the data) and an image of the data.

Some applications provide objects that support OLE Automation. Enable Basic can be used to programmatically manipulate the data in these objects. Some objects that support OLE Automation also support linking and embedding. An OLE Automation object can be created by using the CreateObject function.

An objects class determines the application that provides the object's data and the type of data the object contains. The class names of some commonly used Microsoft applications include MSGraph, MSDraw, WordDocument, and ExcelWorksheet.

What is an OLE object?

An OLE Automation Object is an instance of a class within your application that can be manipulated programmatically, such as with Enable Basic. These may be new classes whose sole purpose is to collect and expose data and functions in a way that makes sense to your users.

The object becomes programmable when those member functions are exposed. OLE Automation defines two types of members that can be exposed for an object:

  • Methods are member functions that perform an action on an object. For example, a Document object might provide a Save method.
  • Properties are member function pairs that set or return information about the state of an object. For example, a Drawing object might have a style property.

For example, Microsoft suggests the following objects could be exposed by implementing the listed methods and properties for each object:

OLE Automation object

Methods

Properties

Application

Help

ActiveDocument

 

Quit

Application

 

Add Data

Caption

 

Repeat

DefaultFilePath

 

Undo

Documents

 

 

Height

 

 

Name

 

 

Parent

 

 

Path

 

 

Printers

 

 

StatusBar

 

 

Top

 

 

Value

 

 

Visible

 

 

Width

Document

Activate

Application

 

Close

Author

 

NewWindow

Comments

 

Print

FullName

 

PrintPreview

Keywords

 

RevertToSaved

Name

 

Save

Parent

 

SaveAs

Path

 

 

ReadOnly

 

 

Saved

 

 

Subject

 

 

Title

 

 

Value

To provide access to more than one instance of an object, a collection object needs to be exposed. A collection object manages other objects. All collection objects support iteration over the objects they manage.

For example, Microsoft suggests an application with a multiple document interface (MDI) might expose a Documents collection object with the following methods and properties:

Collection object

Methods

Properties

Documents

Add

Application

 

Close

Count

 

Item

Parent

 

Open

 

OLE Automation

Applications that support OLE Automation can be controlled by Enable Basic. It can be used to manipulate objects by invoking methods on the object, or by getting and setting the object's properties — in the same way as with the objects in Enable Basic. For example, if a script creates an OLE Automation object named MyObj, code such as the following could be written to manipulate the object:

Sub Main
 Dim MyObj As Object
 Set MyObj = CreateObject ("Word.Basic")
 MyObj.FileNewDefault
 MyObj.Insert "Hello, world."
 MyObj.Bold l
End Sub

The following functions and properties allow you to access an OLE Automation object:

  • CreateObject: Creates a new object of a specified type.
  • GetObject: Retrieves an object pointer to a running application

The following syntax is supported for the GetObject function:

Set MyObj = GetObject ("", class)
...where class is the parameter representing the class of the object to retrieve. The first parameter at this time must be an empty string.

The properties and methods an object supports are defined by the application that created the object. See that application's documentation for details on the properties and methods it supports.

Passing and Returning Strings with OLE

The Macro server maintains variable-length strings internally as BSTRs.

BSTRs are defined in the OLE header files as OLECHAR FAR*. An OLECHAR is a UNICODE character in 32-bit OLE and an ANSI character in 16-bit OLE. A BSTR can contain NULL values because a length is also maintained with the BSTR. BSTRs are also NULL terminated so they can be treated as an LPSTR. Currently this length is stored immediately prior to the string. This may change in the future, so you should use the OLE APIs to access the string length.

You can pass a string from Chart to a DLL in one of two ways. You can pass it 'by value' (ByVal) or 'by reference' (ByRef). When you pass a string by value, Chart passes a pointer to the beginning of the string data (that is, it passes a BSTR). When a string is passed by reference, Macro passes a pointer to a pointer to the string data (that is, it passes a BSTR ).

OLE API

SysAllocString/SysAllocStringLen
SysAllocString/SysAllocStringLen
SysFreeString
SysStringLen
SysReAllocStringLen
SysReAllocString

Note
The BSTR is a pointer to the string, so you don't need to de-reference it.

Overview of Server Process Support

All servers in Altium Designer have processes stored in corresponding server install files with an *.INS extension. Server processes can be modeled at high levels of abstraction — for example, report electrical rules violations in the same style as low level system functions (say, obtaining a sheet handle of a document in the Altium Designer).

A parametric server process allows the information needed by a process to be passed when that process is called. This ability to be able to pass process parameters allows direct control over the operation of the process.

Each server process has a process identifier. The process identifier is made up of two parts separated by a colon. The first part of the process identifier indicates the server that defines the process and the second part is the process name.

For example, the process Sch:ZoomIn is provided by the Schematic server. When this process is launched, either by selecting a menu item, pressing a hot key or activating a toolbar button (which are all defined as process launchers in Altium Designer), it will perform the task of zooming in on the currently active schematic sheet.

Generally a process is executed by selecting a packaged process launcher (by an action such as clicking on a toolbar button, or pressing a hot key or selecting a menu item), which called as a command in Altium Designer. However a process can also be run manually. Different types of process launchers can be used to launch the same process.

For parametric processes (those with parameters), each parameter has a value assigned. This parameter / value block is represented as Parameter = Name.

For example; FileName = C:\Program Files\TestFile.Txt

To concatenate several parameters as a whole string, each parameter / value block is separated by the pipe | symbol.

For example; Parameter1 = Name1 | Parameter2 = Name 2 etc

In practice, there are two ways a process may be executed in a script. To run a server process in a script use process routines such as the ResetParameters and RunProcess procedures, or the Client.SendMessage function.

Example 1

Sub SchJump
 ResetParameters     ' Clear parameter list
 ' The process "Sch:JumpNewLocation" requires 2 integer parameters -
 ' LocationX & LocationY - which set the location to jump to.
 AddIntegerParameter "Location.X", 100
 AddIntegerParameter "Location.Y", 100
 RunProcess "Sch:JumpNewLocation"
End Sub

Example 2

Client.SendMessage("WorkspaceManager:OpenObject","OpenMode=NewFromTemplate | ObjectKind=Project",1024,Nil);

Server Processes Support

This section provides an overview of a range of supported Server Processes:

AddColorParameter

AddIntegerParameter

AddLongIntParameter

AddSingleParameter

AddStringParameter

GetColorParameter

GetIntegerParameter

GetLongIntParameter

GetSingleParameter

GetStringParameter

 

 

AddColorParameter

Description
Adds a color specification parameter to the parameter buffer.
Syntax
AddColorParameter ParamName$, RedVal, GreenVal, BlueVal
Parameters
ParamName$ - a string expression that represents the name of the parameter to set, usually "Color".
RedVal - integer expression from 0 to 255 representing the red level in an RGB color specification.
GreenVal - integer expression from 0 to 255 representing the green level in an RGB color specification.
BlueVal - integer expression from 0 to 255 representing the blue level in an RGB color specification.
Notes
This extension is used to define a color for use by a process that requires a color parameter. Running this extension constructs a parameter of the form:
Color = number
...where number = RedVal + 256*(GreenVal+ 256*BlueVal) and Color is the name contained in the ParamName$ parameter.
Example
When the following example is run with a schematic document active, it prompts the user to select a location and then draws a 200 unit long red wire from the cursor location.

Sub Main
 Dim AResult As Integer, X As Integer, Y As Integer
 ResetParameters           ' Reset the parameter buffer
 RunProcess "Sch:AskForXYLocation" ' Run a schematic process
' The AskForXYLocation process returns three parameters:
' LocationX, LocationY and Result. Result = 1 if the user
' selects a valid schematic location, otherwise it is 0.
 GetIntegerParameter "LocationX", X ' Get the X and Y values
 GetIntegerParameter "LocationY", Y ' of the location.
 GetIntegerParameter "Result", AResult ' Get the Result param.
 If AResult <> 0 then
' The PlaceWire process requires 5 pramameters: Location1X,
' Location1Y, Location2X, Location2Y and Color.
  ResetParameters           ' Reset the parameter buffer
  AddColorParameter "Color", 255,0,0   ' Set Color param.
  AddIntegerParameter "Location1.X", X ' Set X start position.
  AddIntegerParameter "Location1.Y", Y ' Set Y start position.
  AddIntegerParameter "Location2.X", X + 200 ' Set X end position.
  AddIntegerParameter "Location2.Y", Y ' Set Y end position.
  RunProcess "Sch:PlaceWire"           ' Place the wire.
 End If
 MsgBox "The wire has been drawn", 64, "Wire Me"
End Sub

AddIntegerParameter

Description
Adds a parameter with an Integer data type to the parameter buffer.
Syntax
AddIntegerParameter ParamName$, value
Parameters
ParamName$ - a string expression that represents the name of the process parameter.
value - an Integer expression that represents the value of the process parameter.
Notes
This extension is used to set an integer value for use by a process that requires an integer parameter whose value is between -32,768 and 32,767. Running this extension constructs a parameter of the form:
ValName = integer
...where integer = value and ValName is the name contained in the ParamName$ parameter.
Example
When the following example is run with a schematic document active, it prompts the user to select a location and then draws a 200 unit long red wire from the cursor location.

Sub Main
 Dim AResult As Integer, X As Integer, Y As Integer
 ResetParameters           ' Reset the parameter buffer
 RunProcess "Sch:AskForXYLocation" ' Run a schematic process
' The AskForXYLocation process returns three parameters:
' LocationX, LocationY and Result. Result = 1 if the user
' selects a valid schematic location, otherwise it is 0.
 GetIntegerParameter "LocationX", X ' Get the X and Y values
 GetIntegerParameter "LocationY", Y ' of the location.
 GetIntegerParameter "Result", AResult ' Get the Result param.
 If AResult <> 0 then
' The PlaceWire process requires 5 pramameters: Location1X,
' Location1Y, Location2X, Location2Y and Color.
  ResetParameters           ' Reset the parameter buffer
  AddColorParameter "Color", 255,0,0   ' Set Color param.
  AddIntegerParameter "Location1.X", X ' Set X start position.
  AddIntegerParameter "Location1.Y", Y ' Set Y start position.
  AddIntegerParameter "Location2.X", X + 200 ' Set X end position.
  AddIntegerParameter "Location2.Y", Y ' Set Y end position.
  RunProcess "Sch:PlaceWire"           ' Place the wire.
 End If
 MsgBox "The wire has been drawn", 64, "Wire Me"
End Sub

AddLongIntParameter

Description
Adds a parameter with a Long integer data type to the parameter buffer.
Syntax
AddLongIntParameter ParamName$, value
Parameters
ParamName$ - a string expression that represents the name of the process parameter.
value - a Long integer expression that represents the value of the process parameter.
Notes
This extension is used to set an integer value for use by a process that requires an integer parameter whose value is greater than that stored by a standard Integer variable. Running this extension constructs a parameter of the form:
ValName = integer
...where integer = value and ValName is the name contained in the ParamName$ parameter.
This extension can be used instead of AddIntegerParameter if you are unsure how large the value will be.
Example
When the following example is run with a schematic document active, it prompts the user to select a location and then draws a 200 unit long red wire from the cursor location.

Sub Main
 Dim AResult As Integer, X As Long, Y As Long
 ResetParameters           ' Reset the parameter buffer
 RunProcess "Sch:AskForXYLocation" ' Run a schematic process
' The AskForXYLocation process returns three parameters:
' LocationX, LocationY and Result. Result = 1 if the user
' selected a valid schematic location, otherwise it is 0.
 GetLongIntParameter "LocationX", X ' Get the X and Y values
 GetLongIntParameter "LocationY", Y ' of the location.
 GetIntegerParameter "Result", AResult ' Get the Result param.
 If AResult <> 0 then
' The PlaceWire process requires 5 pramameters: Location1X,
' Location1Y, Location2X, Location2Y and Color.
  ResetParameters           ' Reset the parameter buffer
  AddColorParameter "Color", 255,0,0   ' Set Color param.
  AddLongIntParameter "Location1.X", X ' Set X start position.
  AddLongIntParameter "Location1.Y", Y ' Set Y start position.
  AddLongIntParameter "Location2.X", X + 200 ' Set X end position.
  AddLongIntParameter "Location2.Y", Y ' Set Y end position.
  RunProcess "Sch:PlaceWire"           ' Place the wire.
 End If
 MsgBox "The wire has been drawn", 64, "Wire Me"
End Sub

Note
The use of the LongInt form of the extension is unnecessary in this macro as the parameter values will not exceed the bounds for a normal integer. They are used here for illustration purposes.

AddSingleParameter

Description
Adds a parameter with a single-precision value to the parameter buffer.
Syntax
AddSingleParameter ParamName$, value
Parameters
ParamName$ - a string expression that represents the name of the process parameter.
value - a Single precision expression that represents the value of the process parameter.
Notes
This extension is used to set a single-precision real value for use by a process that requires a Single data type number parameter. Running this extension constructs a parameter of the form:
ValName = number
...where number = value and ValName is the name contained in the ParamName$ parameter.

AddStringParameter

Description
Adds a parameter with a string value to the parameter buffer.
Syntax
AddStringParameter ParamName$, value$
Parameters
ParamName$ - a string expression that represents the name of the process parameter.
value - a string expression that represents the value of the process parameter.
Notes
This extension is used to set a string for use by a process that requires a String data type value. Running this extension constructs a parameter of the form:
ValName = string
...where string is the string contained in value$ and ValName is the name contained in the ParamName$ parameter.
Example
The following example constructs the string parameter Dialog = Color and adds it to the parameter buffer. The example then calls the Client: RunCommonDialog process, which uses the parameter and launches the Choose Color dialog.

Sub Main
 ResetParameters                    ' Reset the parameter buffer
 AddStringParameter "Dialog", "Color"
 RunProcess "Client:RunCommonDialog"
End Sub

GetColorParameter

Description
Retrieves the values of a color parameter from the return buffer after the running a process that returns a color.
Syntax
GetColorParameter ParamName$, RedVal, GreenVal, BlueVal
Parameters
ParamName$ - a string expression that contains the name of the parameter to retrieve, usually "Color".
RedVar - name of a valid integer variable to accept the value of the Red component of an RGB color description.
GreenVar - name of a valid integer variable to accept the value of the Green component of an RGB color description.
BlueVar - name of a valid integer variable to accept the value of the Blue component of an RGB color description.
Notes
A process that returns a Color parameter must be run before running this extension. If there is no Color parameter called ParamName$ in the return buffer, the extension will generate an error.
The RedVar, GreenVar and BlueVar variables must be declared as Integer data type variables before using this extension.

GetIntegerParameter

Description
Retrieves the value of an integer parameter from the return buffer after the running a process that returns an integer.
Syntax
GetIntegerParameter ParamName$, IntVar
Parameters
ParamName$ - a string expression that contains the name of the parameter to retrieve.
InVar - the name of a valid integer variable in which to store the value of the parameter.
Notes
A process that returns an integer parameter must be run before executing this extension. If there is no integer parameter called ParamName$ in the return buffer, the extension will generate an error.
The IntVar variable must be run as an Integer data type before using this extension.
Example
When the following example is run with a schematic document active, it prompts the user to select a location and then draws a 200 unit long red wire from the cursor location.

Sub Main
 Dim AResult As Integer, X As Integer, Y As Integer
 ResetParameters           ' Reset the parameter buffer
 RunProcess "Sch:AskForXYLocation" ' Run a schematic process
' The AskForXYLocation process returns three parameters:
' LocationX, LocationY and Result. Result = 1 if the user
' selects a valid schematic location, otherwise it is 0.
 GetIntegerParameter "LocationX", X ' Get the X and Y values
 GetIntegerParameter "LocationY", Y ' of the location.
 GetIntegerParameter "Result", AResult ' Get the Result param.
 If AResult <> 0 then
' The PlaceWire process requires 5 pramameters: Location1X,
' Location1Y, Location2X, Location2Y and Color.
  ResetParameters           ' Reset the parameter buffer
  AddColorParameter "Color", 255,0,0   ' Set Color param.
  AddIntegerParameter "Location1.X", X ' Set X start position.
  AddIntegerParameter "Location1.Y", Y ' Set Y start position.
  AddIntegerParameter "Location2.X", X + 200 ' Set X end position.
  AddIntegerParameter "Location2.Y", Y ' Set Y end position.
  RunProcess "Sch:PlaceWire"           ' Place the wire.
 End If
 MsgBox "The wire has been drawn", 64, "Wire Me"
End Sub

GetLongIntParameter

Description
Retrieves the value of a long integer parameter from the return buffer after the running a process that returns a long integer.
Syntax
GetLongIntParameter ParamName$, LongVar
Parameters
ParamName$ - a string expression that returns the name of the parameter to retrieve.
LongVar - the name of a valid long integer variable in which to store the value of the parameter.
Notes
A process that returns an Integer or Long integer parameter must be run before executing this extension. If there is no integer or long integer parameter called ParamName$ in the return buffer, the extension will generate an error.
The LongVar variable must be declared as a Long data type before using this extension.

GetSingleParameter

Description
Retrieves the value of a real number parameter from the return buffer after the running a process that returns a real number.
Syntax
GetSingleParameter ParamName$, SingleVar
Parameters
ParamName$ - a string expression that returns the name of the parameter to retrieve.
SingleVar - the name of a valid single precision variable in which to store the value of the parameter.
Notes
A process that returns a single precision parameter must be run before executing this extension. If there is no real number parameter called ParamName$ in the return buffer, the extension will generate an error.
The SingleVar variable must be declared as a Single data type before using this extension.

GetStringParameter

Description
Retrieves the value of a string parameter from the return buffer after the running a process that returns a string.
Syntax
GetStringParameter ParamName$, StringVar
Parameters
ParamName$ - a string expression that returns the name of the parameter to retrieve.
LongVar - the name of a valid string variable in which to store the value of the parameter.
Notes
A process that returns a string parameter must be run before executing this extension. If there is no string parameter called ParamName$ in the return buffer, the extension will generate an error.
The StringVar variable must be declared as a String data type before using this extension.
 

You are reporting an issue with the following selected text and/or image within the active document:
ALTIUM DESIGNER FREE TRIAL
Altium Designer Free Trial
Let’s get started. First off, are you or your organization already using Altium Designer?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

In that case, why do you need an evaluation license?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Got it. You actually don’t need an evaluation license for that.

Click the button below to download the latest Altium Designer installer.

Download Altium Designer Installer

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Please fill out the form below to get a quote for a new seat of Altium Designer.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

If you are on Altium Subscription, you don’t need an evaluation license.

If you are not an active Altium Subscription member, please fill out the form below to get your free trial.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Why are you looking to evaluate Altium Designer?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

You came to the right place! Please fill out the form below to get your free trial started.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Sounds exciting! Did you know we offer special discounted student licenses? For more information, click here.

In the meantime, feel free to request a free trial by filling out the form below.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Got it. You can download a free Altium Designer Viewer license which is valid for a 6 months.

Please fill out the form below to request one.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

That’s great! Making things is awesome. We have the perfect program for you.

Upverter is a free community-driven platform designed specifically to meet the needs of makers like you.

Click here to give it a try!

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Got it. You can download a free Altium Designer Viewer license which is valid for a 6 months.

Please fill out the form below to request one.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.