Server Process Routines
The following content has been imported from Legacy Help systems and is in the process of being checked for accuracy.
To execute server processes from a script, you can use process routines provided by Altium Designer's Run Time Library in order to execute these server processes and their parameters.
Generally you would just use three ResetParameters, AddStringParameter and RunProcess routines to execute a server process with parameters in your script.
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. 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.
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; 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; AddSingleParameter
Declaration
Procedure AddSingleParameter(Const Name: String; Value: Single);
Description
The AddSingleParameter 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; 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") 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; 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.
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; 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.
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.
GetStringParameter
Declaration
Procedure GetStringParameter(Const Name: String; Var Value: String);
Description
The GetStringParameter 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; 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.
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.
When you use any of the AddXXX 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 in Delphiscript
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; 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.
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 PCB:Zoom
Example in Delphiscript
Begin ResetParameters; AddStringParameter('ObjectKind','Netlist'); AddIntegerParameter('Index',5); AddStringParameter('ReturnGeneratedDocuments', 'True'); RunProcess('WorkspaceManager:GenerateReport'); GetIntegerParameter('Result', Result); If Result = 0 Then Exit; ShowMessage(GetStringParameter('File1', Result)); End; Scripting System Processes
This section covers the Scripting processes and their parameters (if any).
RunScript Process
Description
This process is to used to run a script from the Run Process dialog ( DXP » Run Process ). There are two parameters in this case: the ProjectName and the ProcName. For the ProcName parameter, you need to specify the script filename and the main procedure in this script.
So the format is as follows: ProcName = ScriptFileName>ProcedureName. Note the GreaterThan symbol used between the script file name and the procedure name.
Parameters
ProjectName (string) Full path to the script project.
ProcName (string) A string containing two blocks separated by the >, Greater Than symbol. The first block is the script file name, and the second block is the procedure name within this script file.
Example
Process: ScriptingSystem:RunScript
Parameters : ProjectName = C: Program Files\Altium Designer\Examples\Scripts\DelphiScript Scripts\General\HelloWorld.PrjScr | ProcName = HelloWorldDialog>RunHelloWorld
RunScriptFile process
Description
Execute a DelphiScript unit script from Altium Designer (with a pas extension). Note, only DelphiScript unit scripts can be used
- not these scripts that have forms.
Parameters
FileName (String) The path to a DelphiScript file (not the script project).
ProcName (String) The procedure name within the DelphiScript file.
Example
Process: ScriptingSystem:RunScriptFile
Parameters : FileName = c:\scripts\testascript.pas | ProcName = ProcedureName
RunScriptText process
Description
This process can be used to execute a series of commands within the Begin End; block.
Parameters
Text (String)
Example
Process: ScriptingSystem:RunScriptText
Parameters : Text = Begin RunApplication('Notepad.exe'); End;