System API Server Processes
Parent page: Technical Reference - System API
System API: Server Processes and Routines
The System API Server Processes Reference includes the following sections and content:
Server Process Routines
Servers
A server provides its services in the Altium NEXUS environment. The Client module within the Altium NEXUS interprets the tasks in terms of server processes and then delegates these processes to the appropriate servers.
For example when a user is clicking on the Schematic menu to place a wire, the Client module interprets this action as a 'PlaceWire' process and delegates the process to the Schematic Editor server. The Schematic server responds by executing the process. The functionality of a server that is installed in the Altium NEXUS is exposed by that server's processes and its exposed functions.
Generally a process is executed by selecting a command which is a packaged process launcher (such as clicking on a toolbar button, or pressing a hot key or selecting a menu item) in Altium NEXUS. Up to three different types of process launchers can be used to launch the same process.
You can manually run a process by going to the Run Process menu item in the System menu within
Server Processes
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 Editor 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 the Altium NEXUS), it will perform the task of zooming in on the currently active schematic sheet.
A process is implemented as a server name:server process name string. Processes are stored in a command launcher table maintained by the server. Every time you execute a process via the user interface, it consults the appropriate server’s command table to fetch the process string and then sends this string over to the server for the server to determine which process to execute. These processes are stored in corresponding server installation text files with an INS extension.
Parametric Processes
A parametric server process allows the information, a process needs, to be passed when the process is called. This ability to be able to pass process parameters allows direct control over the operation of a process. For parametric processes, each parameter has a value assigned and 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.
Manipulating Server Processes
There are server process functions and a TParameterList class in the parameters part of the Altium NEXUS API that do the manipulation of process strings much more easily.
TParameterList Class
Overview
The TParameterList class stores parameter name = value blocks separated by the Pipe symbols in a single null terminated string easily. For example, Orientation=1|Location.X=10000000|Location.Y=20000000 is a typical parameter string.
To add parameters in the TParameterlist object, you use one of the following SetState_AddParameterX methods. Normally the SetState_AddParameterAsString method is used in this case.
To retrieve a specially formatted null terminated string from the TParameterList object, you can invoke one of the GetState_ParameterX methods. The GetState_ToString or GetState_ParameterAsPChar methods are used in this case.
You create an instance of the TParameterList class and invoke the ClearAllParameters method to reset it.
TParameterList Methods
Constructor Create;
Destructor Destroy; Override;
SetState_FromString and GetState_ToString methods
Procedure SetState_FromString (Const S : TDynamicString);
Function GetState_ToString : TDynamicString;
SetState_AddParameterX methods
Procedure SetState_AddParameter (Const AName, AValue : TDynamicString);
Procedure SetState_AddParameterAsString (Const AName : TDynamicString; Const Value : TDynamicString);
Procedure SetState_AddParameterAsBoolean (Const AName : TDynamicString; Value : Boolean);
Procedure SetState_AddParameterAsInteger (Const AName : TDynamicString; Value : Integer);
Procedure SetState_AddParameterAsInt64 (Const AName : TDynamicString; Value : Int64);
Procedure SetState_AddParameterAsDouble (Const AName : TDynamicString; Const Value : Double);
GetState_AddParameterX methods
Function GetState_ParameterAsString (Const Name : TDynamicString; Var Value : TDynamicString ) : Boolean; Overload;
Function GetState_ParameterAsString (Const Name : TDynamicString; Var Value : TString ) : Boolean; Overload;
Function GetState_ParameterAsPChar (Const Name : TDynamicString; Var Value : PChar ) : Boolean;
Function GetState_ParameterAsLongInt (Const Name : TDynamicString; Var Value : LongInt) : Boolean;
Function GetState_ParameterAsInteger (Const Name : TDynamicString; Var Value : Integer) : Boolean;
Function GetState_ParameterAsInt64 (Const Name : TDynamicString; Var Value : Int64 ) : Boolean;
Function GetState_ParameterAsSmallInt (Const Name : TDynamicString; Var Value : SmallInt) : Boolean;
Function GetState_ParameterAsWord (Const Name : TDynamicString; Var Value : Word ) : Boolean;
Function GetState_ParameterAsBoolean (Const Name : TDynamicString; Var Value : Boolean) : Boolean;
Function GetState_ParameterAsWordBool (Const Name : TDynamicString; Var Value : WordBool) : Boolean;
Function GetState_ParameterAsReal (Const Name : TDynamicString; Var Value : Single ) : Boolean;
Function GetState_ParameterAsDouble (Const Name : TDynamicString; Var Value : Double) : Boolean;
Other methods
Function GetState_ParameterByName (Const AName : TDynamicString) : TParameter;
Function SetState_RemoveByName (Const AName : TDynamicString) : Boolean;
Procedure ClearAllParameters;
Procedure SetState(P : PChar);
Procedure GetState(P : PChar);
Scripting Notes
In Scripting, we can only use the following methods SetState_FromString (Const S : TDynamicString); and GetState_ToString to process strings. The SetState and GetState methods cause problems in the scripting engine.
Example in DelphiScript
//Parameters = Orientation=1|Location.X=10000000|Location.Y=20000000';
P := TParameterList.Create; // P is of TParameterList type.
P.ClearAllParameters;
P.SetState_FromString(Parameters);
P.SetState_AddParameterAsString ('Orientation','1');
P.SetState_AddParameterAsString ('Location.X' ,'10000000');
P.SetState_AddParameterAsString ('Location.Y' ,'20000000');
P.SetState_AddParameterAsString ('Designator' ,'dB1');
P.SetState_AddParameterAsString ('Comment' ,'50pF');
Parameters := P.GetState_ToString;
IntegratedLibraryManager.PlaceLibraryComponent(SchLibRef,SchLibpath,Parameters);
P.Free;
Process Parameter Functions
Function GetState_Parameter (P : PChar; Const Name : TString; Var Value : TString) : Boolean; Overload;
Function GetState_Parameter (P : PChar; Const Name : TDynamicString; Var Value : TDynamicString) : Boolean; Overload;
Procedure SetState_RemoveParameter(P : PChar; Const Name : TDynamicString); Overload;
Function GetState_ParameterPChar (P : PChar; Const Name : TDynamicString; Value : PChar) : Boolean;
Procedure SetState_ParameterPChar (P : PChar; Const Name : TDynamicString; Value : PChar);
Procedure SetState_Parameter (P : PChar; Const Name : TDynamicString; Const Value : TDynamicString); Overload;
Function GetState_Parameter (Const S : TDynamicString; Const Name : TDynamicString; Var Value : TDynamicString) : Boolean; Overload;
Procedure SetState_Parameter (Var S : TDynamicString; Const Name : TDynamicString; Const Value : TDynamicString); Overload;
Procedure SetState_RemoveParameter(Var S : TDynamicString; Const Name : TDynamicString); Overload;
Server Routines from ClientApiReg
The server process routines are defined in the ClientApiReg part of the Altium NEXUS API.
There are two ways you can execute a process in a script
To execute a server process in a script, you need to use commands such as ResetParameters and RunProcess procedures or invoke the Client.SendMessage function.
RunProcess Example
ResetParameters;
AddStringParameter('OpenMode','NewFromTemplate');
AddStringParameter('ObjectKind,'Project');
RunProcess('WorkSpaceManager:OpenObject);
Client.SendMessage Example
Client.SendMessage('WorkspaceManager:OpenObject','OpenMode=NewFromTemplate | ObjectKind=Project',1024,Nil);
See also
Process Parameters Reference online help
Process Examples in \Examples\Scripts\Delphiscript Scripts\Processes\ folder.
AddWordParameter
Declaration
Procedure AddWordParameter(Const Name: String; Value: Word);
Description
The AddWordParameter procedure defines a parameter with a Word data type to the parameter buffer for use by a server process.
Example
Begin
ResetParameters;
AddWordParameter('WordValue',5);
// code here
End;
See also
Server Process routines
AddColorParameter
Declaration
Procedure AddColorParameter(Const Name: String; Red: Integer; Green: Integer; Blue: Integer);
Description
This procedure adds a color value parameter to the parameter buffer in Altium NEXUS. This procedure is used to define a color for use by a process that requires a color parameter.
The Color is a value where value = RedVal + 256*(GreenVal + 256*BlueVal) and Name is the name representing this color value.
See also
Server Process routines
AddIntegerParameter
Declaration
Procedure AddIntegerParameter(Const Name: String; Value: Integer);
Description
The AddIntegerParameter procedure defines a parameter with an Integer data type to the parameter buffer for use by a server process.
Example
Begin
ResetParameters;
AddStringParameter('ObjectKind','Netlist');
AddIntegerParameter('Index',5);
AddStringParameter('ReturnGeneratedDocuments', 'True');
RunProcess('WorkspaceManager:GenerateReport');
End;
See also
Server Process routines
AddLongIntParameter
Declaration
Procedure AddLongIntParameter(Const Name: String; Value: LongInt);
Description
The AddLongIntParameter procedure defines a parameter with a longint data type to the parameter buffer for use by a server process.
Example
Begin
ResetParameters;
AddLongIntParameter('LongIntValue',5);
// code here
End;
See also
Server Process routines
AddSingleParameter
Declaration
Procedure AddSingleParameter(Const Name: String; Value: Single);
Description
The AddLongIntParameter procedure defines a parameter with a single data type to the parameter buffer for use by a server process.
Example
Begin
ResetParameters;
AddSingleParameter('SingleValue',5);
// code here
End;
See also
Server Process routines
AddStringParameter
Declaration
Procedure AddStringParameter(Const Name, Value: String);
Description
This procedure adds a parameter with a string value to the parameter buffer. The Name parameter represents the name of the process parameter and the Value parameter represents the value of the process parameter.
Example
ResetParameters
Call AddStringParameter("Object","JumpToLocation10")
Call RunProcess("PCB:Jump")
ResetParameters
Call AddStringParameter("ZoomLevel","2.0")
Call RunProcess("PCB:Zoom")
See also
Server Process routines
GetColorParameter
Declaration
Procedure GetColorParameter(Const Name: String; Var Red: Integer; Var Green: Integer; Var Blue: Integer);
Description
The GetColorParameter procedure retrieves the values of a color parameter as RGB values from the parameter buffer after running a process that returns a color value.
See also
Server Process routines
GetIntegerParameter
Declaration
Procedure GetIntegerParameter(Const Name: String; Var Value: Integer);
Description
The GetIntegerParameter procedure retrieves the value of an integer type parameter from the parameter buffer. This procedure after a process has been executed can return a resultant word value.
Example
Var
ErrorCode : Integer;
CommandLine : String;
Result : Integer;
NetlistName : String
Begin
ResetParameters;
AddStringParameter('ObjectKind','Netlist');
AddIntegerParameter('Index',5);
AddStringParameter('ReturnGeneratedDocuments', 'True');
RunProcess('WorkspaceManager:GenerateReport');
GetIntegerParameter('Result', Result);
If Result = 0 Then Exit;
NetListName := GetStringParameter('File1', Result);
End;
See also
Server Process routines
GetLongIntParameter
Declaration
Procedure GetLongIntParameter(Const Name: String; Var Value: LongInt);
Description
The GetLongIntParameter procedure retrieves the value of a long int type parameter from the parameter buffer. This procedure after a process has been executed can return a resultant long int type value.
See also
Server Process routines
GetSingleParameter
Declaration
Procedure GetSingleParameter(Const Name: String; Var Value: Single);
Description
The GetSingleParameter procedure retrieves the value of a single type parameter from the parameter buffer. This procedure after a process has been executed can return a resultant single type value.
See also
Server Process routines
GetStringParameter
Declaration
Procedure GetStringParameter(Const Name: String; Var Value: String);
Description
The GetSingleParameter procedure retrieves the value of a string type parameter from the parameter buffer. This procedure after a process has been executed can return a resultant string type value.
Example
Var
ErrorCode : Integer;
CommandLine : String;
Result : Integer;
NetlistName : String
Begin
ResetParameters;
AddStringParameter('ObjectKind','Netlist');
AddIntegerParameter('Index',5);
AddStringParameter('ReturnGeneratedDocuments', 'True');
RunProcess('WorkspaceManager:GenerateReport');
GetIntegerParameter('Result', Result);
If Result = 0 Then
Exit;
NetListName := GetStringParameter('File1', Result);
End;
See also
Server Process routines
GetWordParameter
Declaration
Procedure GetWordParameter(Const Name: String; Var Value: Word);
Description
The GetWordParameter procedure retrieves the value of a word type parameter from the parameter buffer. This procedure after a process has been executed can return a resultant integer value.
See also
Server Process routines
ResetParameters
Declaration
Procedure ResetParameters;
Description
The ResetParameters procedure clears the parameter buffer. Execute the procedure to reset the parameter buffer before setting parameters used by a process in your script or server project.
When you use any of the Add...Parameter procedures, the parameter declared is appended to the parameter buffer. When you run a process, any parameters that need to be passed to the process are read from the parameter buffer.
Running a process, however, DOES NOT clear the parameter buffer. Therefore, it is important to use the ResetParameters procedure to clear the buffer of old values before placing a new series of parameters into the buffer.
Example
Var
ErrorCode : Integer;
CommandLine : String;
Result : Integer;
NetlistName : String
Begin
ResetParameters;
AddStringParameter('ObjectKind','Netlist');
AddIntegerParameter('Index',5);
AddStringParameter('ReturnGeneratedDocuments', 'True');
RunProcess('WorkspaceManager:GenerateReport');
GetIntegerParameter('Result', Result);
If Result = 0 Then
Exit;
NetListName := GetStringParameter('File1', Result);
End;
See also
Server Process routines
RunProcess
Declaration
Procedure RunProcess(Const Command: String);
Description
The RunProcess procedure allows you to execute a server process. If the process invoked by this extension requires parameters to be passed to it, you must add the parameters to the parameter buffer using the AddXXXParameter functions before running the process.
If the process returns values, these will be placed in the return buffer and can be read using the GetXXXParameter functions.
Server: Process format
The Command string takes on the following form: Server:Process
where Server is the name of the server the process is supplied by, and Process is the command name of the process. An example is PCB:Zoom.
Client Process example
// available parameters for Dialog: Color or FileOpenSave Names
ResetParameters;
AddStringParameter('Dialog','Color'); // color dialog
AddStringParameter('Color', '0'); // black color
RunProcess('Client:RunCommonDialog');
//Result value obtained from the RunCommonDialog's Ok or Cancel buttons.
GetStringParameter('Result',S);
If (S = 'True') Then
Begin
GetStringParameter('Color',S);
ShowInfo('New color is ' + S);
End;
PCB Process example
// Refresh PCB workspace.
ResetParameters;
AddStringParameter('Action', 'Redraw');
RunProcess('PCB:Zoom');
Schematic Process example
// Refresh Schematic workspace
ResetParameters;
AddStringParameter('Action', 'All');
RunProcess('Sch:Zoom');
Workspace Manager Process example
Var
ErrorCode : Integer;
CommandLine : String;
Result : Integer;
NetlistName : String
Begin
ResetParameters;
AddStringParameter('ObjectKind','Netlist');
AddIntegerParameter('Index',5);
AddStringParameter('ReturnGeneratedDocuments', 'True');
RunProcess('WorkspaceManager:GenerateReport');
End;
See also
Server Process routines
Helper Functions and Objects for the Scripting System
The Scripting System has provided a few Helper objects which are to help simplify your scripting tasks especially with creating and managing lists of strings or objects.
Useful functions:
CopyFile
Useful classes:
TStringListTListTIniFile
Many routines and objects from the Borland Delphi's Run Time Library cannot be used in the scripting system because the scripting system cannot support Int64 type parameters.
For example the TStream and its descendant classes cannot be used in the scripting system because many of the methods use the Int64 parameter type. The other limitations are that you cannot define classes or records because the scripting system is typeless.
CopyFile function
Declaration
The CopyFile function copies a file specified by the original filename to a new file with the new filename. The function returns a true value if the CopyFile fuhnction is successful otherwise a false value is returned.
The FailIfExists parameter controls how an existing target file can be overrwritten or not with the new source file by the CopyFile function.
- If this parameter is TRUE and the new file already exists, the function fails.
- If this parameter is FALSE and the new file already exists, the function overwrites the existing file and succeeds.
Syntax
Function CopyFile(SourceFileName, TargetFilename : PChar; FailIfExists : Boolean) : Boolean;
DelphiScript Example
Procedure CopyFromTo;
Var
Project : String;
PathSource : String;
PathTarget : String;
Begin
PathSource := 'C:\3M Footprints.PcbLib';
PathTarget := 'C:\Temp\3M Footprints.PcbLib';
CopyFile(PathSource, PathTarget, False);
End;
See also
Helper Classes and Functions
TIniFile object
The TIniFile object (derived from Borland Delphi's TIniFile class) stores and retrieves application-specific information and settings from a text file with an INI extension. When you instantiate the TIniFile object, you pass as a parameter to the TIniFile's constructor, the filename of the INI file. If the file does not exist, the ini file is created automatically.
You then can read values using ReadString, ReadInteger, or ReadBool methods. Alternatively, if you want to read an entire section of the INI file, you can use the ReadSection method. As well, you can write values using WriteBool, WriteInteger, or WriteString methods.
Each of the Read routines takes three parameters. The first parameter identifies the section of the INI file. The second parameter identifies the value you want to read, and the third is a default value in case the section or value doesn't exist in the INI file. Similarly, the Write routines will create the section and/or value if they do not exist.
Script example
See at the end of this page the example code which creates an INI file.
TIniFile Methods
DeleteKey(const Section, Ident: String);
EraseSection(const Section: String);
ReadSection (const Section: String; Strings: TStrings);
ReadSections(Strings: TStrings);
ReadSectionValues(const Section: String; Strings: TStrings);
ReadString(const Section, Ident, Default: String): String;
WriteString(const Section, Ident, Value: String);
UpdateFile;
Derived from TCustomIniFile
Create(const FileName: String);
ReadBinaryStream(const Section, Name: string; Value: TStream): Integer;
ReadBool (const Section, Ident: String; Default: Boolean): Boolean ;
ReadDate (const Section, Ident: String; Default: TDateTime): TDateTime;
ReadDateTime (const Section, Ident: String; Default: TDateTime): TDateTime;
ReadFloat (const Section, Ident: String; Default: Double): Double;
ReadInteger(const Section, Ident: String; Default: Longint): Longint;
ReadTime (const Section, Ident: String; Default: TDateTime): TDateTime;
SectionExists (const Section: String): Boolean;
WriteBinaryStream(const Section, Name: string; Value: TStream);
WriteBool(const Section, Ident: String; Value: Boolean);
WriteDate(const Section, Ident: String; Value: TDateTime);
WriteDateTime(const Section, Ident: String; Value: TDateTime);
procedure WriteFloat(const Section, Ident: String; Value: Double);
WriteInteger(const Section, Ident: String; Value: Longint);
WriteTime(const Section, Ident: String; Value: TDateTime);
ValueExists (const Section, Ident: String): Boolean;
Derived from TObject
AfterConstruction
BeforeDestruction
ClassInfo
ClassName
ClassNameIs
ClassParent
ClassType
CleanupInstance
DefaultHandler
Destroy
Dispatch
FieldAddress
Free
FreeInstance
GetInterface
GetInterfaceEntry
GetInterfaceTable
InheritsFrom
InitInstance
InstanceSize
MethodAddress
MethodName
NewInstance
SafeCallException
Example of an Ini file creation
Procedure WriteToIniFile(AFileName : String);
Var
IniFile : TIniFile;
I,J : Integer;
Begin
IniFile := TIniFile.Create(AFileName);
For I := 1 to 2 Do
For J := 1 to 2 Do
IniFile.WriteString('Section'+IntToStr(I),
'Key' + IntToStr(I) + '_' + IntToStr(J),
'Value' + IntToStr(I));
IniFile.Free;
(* The INIFILE object generates a text file of the
following format;
[Section1]
Key1_1=Value1
Key1_2=Value1
[Section2]
Key2_1=Value2
Key2_2=Value2
*)
End;
See also
Helper Classes and Functions
Refer to the IniFileEg script example in the \Examples\Scripts\General\ folder.
TList Object
The TList class stores an array of pointers to objects. You can create an instance of a TList object and you can add, sort or delete individual objects from this TList object in your script in Altium NEXUS for example.
TList Properties
Capacity
Count
Items
List
TList methods
Add(Item: Pointer): Integer;
Assign(ListA: TList; AOperator: TListAssignOp = laCopy; ListB: TList = nil);
Clear
Delete(Index: Integer);
Destroy
Exchange(Index1, Index2: Integer);
Expand: TList;
Extract(Item: Pointer): Pointer;
First: Pointer;
IndexOf
IndexOf(Item: Pointer): Integer;
function Last: Pointer;
Move(CurIndex, NewIndex: Integer);
Pack
Remove(Item: Pointer): Integer;
Sort
Methods derived from TObject
AfterConstruction
BeforeDestruction
ClassInfo
ClassName
ClassNameIs
ClassParent
ClassType
CleanupInstance
Create
DefaultHandler
Dispatch
FieldAddress
Free
FreeInstance
GetInterface
GetInterfaceEntry
GetInterfaceTable
InheritsFrom
InitInstance
InstanceSize
MethodAddress
MethodName
NewInstance
SafeCallException
Example
//The following code adds an object to TheList container if the object is not in the list.
Begin
If TheList.IndexOf(AnObject)=-1 Then
TheList.Add(AnObject);
// do something
TheList.Remove(AnObject);
End;
See also
Helper Classes and Functions
TStringList object
The TStringList object maintains a list of strings. You can create an instance of a TStringList object and you can add, sort or delete individual strings from this object in your script.
If you need to do a customized sorting of the TStringList container, you need to write your own sorting routine. See examples below.
TStringList Properties
Capacity: Integer;
CaseSensitive: Boolean;
Count: Integer;
Duplicates: TDuplicates;
Objects[Index: Integer]: TObject;
Sorted: Boolean;
Strings[Index: Integer]: string;
Derived from TStrings
CommaText: string;
DelimitedText: string;
Delimiter: Char;
Names[Index: Integer]: string;
QuoteChar: Char;
StringsAdapter: IStringsAdapter;
Text: string;
Values[const Name: string]: string;
TStringList Methods
Add(const S: string): Integer;
AddObject(const S: string; AObject: TObject: Integer);
Clear
Delete(Index: Integer);
Destroy
Exchange(Index1, Index2: Integer);
Find(const S: string; var Index: Integer): Boolean;
IndexOf(const S: string): Integer;
Insert(Index: Integer; const S: string);
InsertObject(Index: Integer; const S: string; AObject: TObject);
Sort
Methods derived from TStrings
AddStrings(Strings: TStrings);
Append(const S: string);
Assign(Source: TPersistent);
BeginUpdate
EndUpdate
Equals(Strings: TStrings): Boolean;
GetText: PChar;
IndexOfName(const Name: string): Integer;
IndexOfObject(AObject: TObject): Integer;
LoadFromFile(const FileName: string);
LoadFromStream(Stream: TStream);
Move(CurIndex, NewIndex: Integer);
SaveToFile(const FileName: string);
SaveToStream(Stream: TStream);
SetText(Text: PChar);
Methods derived from TPersistent
GetNamePath
Methods derived from TObject
AfterConstruction
BeforeDestruction
ClassInfo
ClassName
ClassNameIs
ClassParent
ClassType
CleanupInstance
Create
DefaultHandler
Dispatch
FieldAddress
Free
FreeInstance
GetInterface
GetInterfaceEntry
GetInterfaceTable
InheritsFrom
InitInstance
InstanceSize
MethodAddress
MethodName
NewInstance
SafeCallException
Example
Procedure TDialogForm.FormCreate(Sender: TObject);
Var
StringsList : TStringList;
Index : Integer;
Begin
StringsList := TStringList.Create;
Try
StringsList.Add('Capacitors');
StringsList.Add('Resistors');
StringsList.Add('Antennas');
StringsList.Sort;
// The Find method will only work on sorted lists.
If StringsList.Find('Resistor', Index) then
Begin
ListBox.Items.AddStrings(StringsList);
Label.Caption := 'Antennas has an index value of ' + IntToStr(Index);
End;
Finally
StringsList.Free;
End;
End;
End;
Example of a customized sorting routine
Refer to the Netlister script example in the \Examples\Scripts\WSM\ folder of the Altium NEXUS installation.
See also
Helper Classes and Functions