OLE and Server Process support

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.