DPL Manual
DIgSILENT PowerFactory
Version 12.1
DIgSILENT GmbH
Gomaringen, Germany
2003
Publisher:
DIgSILENT GmbH
Buchenstrasse 10
D-72810 Gomaringen
Tel : (07072)9168-0
Fax : (07072)9168-88
Visit our homepage at:
www.digsilent.de
Copyright DIgSILENT GmbH.
All rights reserved. No part of this
publication may be reproduced or
distributed in any form without
permission of the publisher.
doc 103 05 06 920
Contents
1
DPL
1.1
1.2
1.3
1.4
1.5
1.6
1.7
1.8
DPL Manual
The DPL Command Object . . . . . . . . . .
The DPL Script Language . . . . . . . . . . .
Access to Other Objects . . . . . . . . . . . .
Access to Locally Stored Objects . . . . . . .
Accessing the General Selection . . . . . . .
Accessing External Objects . . . . . . . . . .
Remote Scripts and DPL command Libraries
DPL Functions and Subroutines . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2
3
3
8
9
10
11
11
13
1
DIgSILENT PowerFactory
DPL
Chapter1
DPL
The DIgSILENT Programming Language “DPL” serves the purpose of offering an interface for
automating tasks in the PowerFactory program. The DPL method distinguishes itself from the
command batch method in several aspects:
• DPL offers program decision and flow commands
• DPL offers the definition and use of user-defined variables
• DPL has a flexible interface for input-data and external objects
• DPL offers mathematical expressions
The DPL adds a new dimension to the DIgSILENT PowerFactory program by allowing the
creation of new calculation functions. Such user-defined calculation commands can be used in
all areas of power system analysis, such as
• Network optimizing
• Cable-sizing
• Protection coordination
• Stability analysis
• Parametric sweep analysis
• Contingency analysis
• etc. etc.
Such new calculation functions are written as program scripts which comprise
• flow commands like ‘if-then-else and ‘do-while’
• DIgSILENT commands (i.e. load flow or short-circuit commands)
• Input and output routines
• Mathematical expressions
• DIgSILENT object procedure calls
• subroutine calls
Such program scripts are executed by DPL command objects.
To understand the DPL philosophy and the resulting hierarchical structure of DPL scripts, the
following is important to understand:
DPL Manual
2
DIgSILENT PowerFactory
DPL
• A DPL command either executes its own script or the script of another, remote, DPL
command. In the first case, the DPL command is called a ‘root command’ and the script
is called a ‘local script’. In the second case, the DPL command is called a ‘referring’
command and the script is called a ’remote script’.
• A root command may define interface variables that are accessible from outside the script
and which are used to define default values.
• Each root command may define one or more external objects. External object are used to
make a DPL command run with specific power system objects, selections, commands, etc.
• A referring command may overrule all default interface values and all selected external
objects of the remote command.
• Each DPL command can be called as a subroutine by other DPL commands.
The use of remote scripts, external objects and interface variables makes it possible to create
generic DPL commands, which may be used with different settings in many different projects and
study cases.
1.1 The DPL Command Object
The DPL command object holds a reference to a remote DPL command when it is not a root
command. The example depicted in Fig. 1.1 is apparently a referring command, since its “DPL
script” reference is set to the remote command \L IBRARY\DPL C OMMANDS\C HECK VL OADING.
A root command has its own script on the “script” page of the dialog. A referring command uses
the script of the remote DPL command.
The DPL command also holds a reference to a selection of objects (“General Selection”). The
general selection in the example is empty. Only one single “General Selection” is valid at a time
for all DPL scripts. This means that setting the “General Selection” in one DPL command dialog,
will change the “General Selection” for all DPL commands in the database.
The interface section is used to define variables that are accessible from outside the DPL
command itself. DPL commands that call other DPL commands as subroutines, may use and
change the values of the interface variables of these DPL subroutines.
The list of External Objects is used to execute the DPL command for specific objects. A DPL
command that, for example, searches the set of lines for which a short-circuit causes too deep a
voltage dip at a specific busbar, would access that specific busbar as an external object.
Performing the same command for another busbar would then only require setting the external
object to the other busbar.
The most important part of a DPL root command is of course the actual DPL program script.
That script is written on the “Script” page of a DPL root command dialog.
1.2 The DPL Script Language
The DPL script language uses a syntax quite similar to the C++ programming language. This
type of language is intuitive, easy to read, and easy to learn. The basic command set has been
kept as small as possible.
DPL Manual
3
DIgSILENT PowerFactory
DPL
Figure 1.1: A DPL command
The syntax can be divided into the following parts:
• variable definitions
• assignments and expressions
• program flow instructions
• method calls
The statements in a DPL script are separated by semicolons. Statements are grouped together
by braces.
Example:
statement1;
statement2;
if (condition) {
groupstatement1;
groupstatement2;
}
1.2.1 Variable Definitions
DPL uses the following internal parameter types
• double, a 15 digits real number
• int, a integer number
DPL Manual
4
DIgSILENT PowerFactory
DPL
• string, a string
• object, a reference to a DIgSILENT object
• set, a container of objects
Vectors and Matrices are available as external objects.
The syntax for defining variables is as follows:
[VARDEF]
[TYPE]
=
=
[TYPE] varname, varname, ..., varname;
double | int | object | set
All parameter declarations must be given together in the top first lines of the DPL script. The
semicolon is obligatory.
Examples:
double
int
string
object
set
Losses, Length, Pgen;
NrOfBreakers, i, j;
txt1, nm1, nm2;
O1, O2, BestSwitchToOpen;
AllSwitches, AllBars;
1.2.2 Assignments and Expressions
The following syntax is used to assign a value to a variable:
variable
variable
variable
=
+=
-=
expression
expression
expression
The add-assignment “+=” adds the right side value to the variable and the subtract-assignment
“-=” subtracts the right-side value.
Examples:
double x,y;
x = 0.5*pi();
y = sin(x);
x += y;
y -= x;
!
!
!
!
x
y
x
y
now
now
now
now
equals
equals
equals
equals
1.5708
1.0
2.5708
-1.5708
The following operators and functions are available:
• arithmetic operators: +, -, *, /
• standard functions:
sin(x)
cos(x)
acos(x)
atan(x)
tanh(x)
exp(x)
abs(x)
min(x,y)
trunc(x)
frac(x)
pow(x,y) modulo(x,y)
rand()
tan(x)
sinh(x)
ln(x)
max(x,y)
round(x)
ceil(x)
asin(x)
cosh(x)
log(x) (basis 10)
sqrt(x) (square root)
sqr(x) (power of 2)
floor(x)
All trigonometric functions are based on radians (RAD).
The function ‘rand()’ returns a uniform distributed random number in the range [0, 1].
DPL Manual
5
DIgSILENT PowerFactory
DPL
1.2.3 Program Flow Instructions
The following flow commands are available.
if
if
do
while
( [boolexpr] )
( [boolexpr] )
[statlist]
( [boolexpr] )
[statlist]
[statlist]
while
[statlist]
else
( [boolexpr] )
[statlist]
in which
[boolexpr]
[boolcomp]
[statlist]
=
=
=
expression [boolcomp] expression
”<” | ”>” | ”=” | ”>=” | ”>=” | ”<>”
statement; | { statement; [statlist] }
• Unary operators: ”.not.”
• Binary operators: ”.and.” | ”.or.” | ”.nand.” | ”.nor.” | ”.eor.”
• Parentheses: {logical expression}
Examples:
if (a<3) b = a*2;
else
b = a/2;
while (sin(a)>=b*c) {
a = O:dline;
c = c + delta;
}
if ({.not.a}.and.{b<>3}) {
err = Ldf.Execute();
if (err) {
Ldf:iopt_lev = 1;
err = Ldf.Execute();
Ldf:iopt_lev = 0;
}
}
Break and Continue
The loop statements ‘do-while’ and ‘while-do’ may contain ‘break’ and ‘continue’ commands. The
‘break’ and ‘continue’ commands may not appear outside a loop statement.
The ‘break’ command terminates the smallest enclosing ‘do-while’ or ‘while-do’ statement. The
execution of the DPL script will continue with the first command following the loop statement.
The ‘continue’ command skips the execution of the following statements in the smallest
enclosing ‘do-while’ or ’while-do’ statement. The execution of the DPL script is continued with the
evaluation of the boolean expression of the loop statement. The loop statement list will be
executed again when the expression evaluates to TRUE. Otherwise the loop statement is ended
and the execution will continue with the first command following the loop statement.
Examples:
DPL Manual
6
DIgSILENT PowerFactory
DPL
O1 = S1.First();
while (O1) {
O1.Open();
err = Ldf.Execute();
if (err) {
! skip this one
O1 = S1.Next;
continue;
}
O2 = S2.First();
AllOk = 1;
DoReport(0); !reset
while (O2) {
err = Ldf.Execute();
if (err) {
! do not continue
AllOk = 0;
break;
} else {
DoReport(1); ! add
}
O2 = S2.Next();
}
if (AllOk) {
DoReport(2); ! report
}
O1 = S1.Next();
}
1.2.4 Input and Output
The “input” command asks the user to enter a value.
input(var, string);
The input command will pop up a window with the string and a input line on which the user may
enter a value. The value will be assigned to the variable “var”.
The “output” command writes a line of text to the output window.
output(string);
The string may contain “=”-signs, followed by a variable name. The variable name will then be
replaced by the variable’s value.
Example:
input(diameter, ’enter diameter’);
output(’the entered value=diameter’);
The example results in the pop up of a window as depicted inFig. 1.2.
The following text will appear in the output window:
DIgSI/dpl - the entered value=12.3400
DPL Manual
7
DIgSILENT PowerFactory
DPL
Figure 1.2: The input window
The output command is considered obsolete and has been replaced by the more versatile
“printf” and “sprintf” functions.
See “sprintf” in 1.8.3, page 21 and “printf” in 1.8.3, page 21 for more information.
1.3 Access to Other Objects
With the syntax for the parameter definitions, program flow and the input and output, it is already
possible to create a small program. However, such a script would not be able to use or
manipulate variables of ‘external’ objects. It would not be possible, for instance, to write a script
that replaces a specific line by possibly better alternatives, in order to select the best line type.
Such a script must be able to access specific objects (the specific line) and specific sets of
objects (the set of alternative line types).
The DPL language has several methods with which the database objects and their parameters
become available in the DPL script:
• The most direct method is to create an object, or a reference to an object, in the DPL
command folder itself. Such an object is directly available as “object” variable in the script.
The variable name is the name of the object in the database.
• The general selection may be used. This method is only useful when the order in which the
objects are accessed is not important. The general selection is automatically filled when a
selection is right clicked in either the single line graphic or the database browser and the
option “Execute DPL script” is selected.
• The list of external objects is mainly used when a script should be executed for specific
objects or selections. The list of external objects is nothing more than a list of ‘aliases’. The
external object list is used to select specific objects for each alias, prior to the execution of
the script.
1.3.1 Object Variables and Methods
If a database object is known to the DPL command, then all its methods may be called, and all
its variables are available. For example, if we want to change a load flow command in order to
force an asymmetrical load flow calculation, we may alter the parameter “iopt net”. This is done
by using an assignment:
Ldf:iopt_net = 1; ! force unbalanced
In this example, the loadflow objects is known as the objects variable “Ldf”.
The general syntax for a parameter of a database object is
DPL Manual
8
DIgSILENT PowerFactory
DPL
objectname:parametername
In the same way, it is possible to get a value from a database object, for instance a result from
the load flow calculations. One of such a result is the loading of a line object, which is stored in
the variable “c:loading”. The following example performs the unbalanced loadflow and reports
the line loading:
00.
01.
02.
03.
04.
05.
06.
07.
08.
09.
int error;
double loading;
Ldf:iopt_net = 1; ! force unbalanced
error = Ldf.Execute(); ! execute load flow
if (error) {
exit();
} else {
loading = Line:c:loading; ! get line loading
output(’loading=loading’); ! report line loading
}
This examples is very primitive but it shows the basic methods for accessing database objects
and their parameters.
1.4 Access to Locally Stored Objects
The access to locally stored (references to) objects is only possible if the name of the object
qualifies as a variable name in the DPL script. It will not be possible to access an object which
name is “My Loadflow\~{}1*”, for instance.
An example is shown in Fig. 1.3, where a DPL script is shown on the left which has a load flow
command and a reference to a line in its contents folder on the right.
Figure 1.3: DPL contents
The example DPL script may now access these objects directly, as the objects “Ldf” and “Line”.
In the following example, the object “Ldf”, which is a load flow command, is used in line 01 to
perform a load flow.
00.
01.
02.
03.
04.
05.
int error;
error = Ldf.Execute();
if (error) {
output(’Load flow command returns an error’);
exit();
}
In line 01, a load flow is calculated by calling the method “Execute()” of the loadflow command.
The details of the loadflow command, such as the choice between a balanced single phase or an
DPL Manual
9
DIgSILENT PowerFactory
DPL
unbalanced three phase load flow calculation, is made by editing the object “Ldf” in the database.
Many other objects in the database have methods which can be called from a DPL script.
The DPL contents are also used to include DPL scripts into other scripts and thus to create DPL
“subroutines”.
1.5 Accessing the General Selection
Accessing database objects by storing them or a reference to them in the DPL command would
create a problem if many objects have to be accessed, for instance if we want to search the line
with the highest loading. It would be impractical to create a reference to each and every line. A
more elegant way would be to use the DPL global selection and fill it with all lines. The database
browser offers several ways in which to fill the DPL selection with little effort. The selection may
then be used to access each line indirectly by a DPL “object” variable. In this way, we may create
a loop in which we search for the highest loading. This is shown in the following example.
00.
01.
02.
03.
04.
05.
06.
07.
08.
09.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
int error;
double max;
object O, Omax;
set S;
error = Ldf.Execute();
if (error) exit();
! execute a loadflow
! exit on error
S = SEL.AllLines();
!
Omax = S.First();
!
if (Omax) {
max = Omax:c:loading;
!
} else {
output(’No lines found in
exit();
!
}
O = S.Next();
!
while (O) {
!
if (O:c:loading>max) {
max = O:c:loading;
!
Omax = O;
!
}
O = S.Next();
}
output(’max loading=max for
Omax.ShowFullName();
get all selected lines
get first line
initialize maximum
selection’);
no lines: exit
get next line
while more lines
update maximum
update max loaded line
line’); !output results
The object “SEL” used in line 08 is the reserved object variable which equals the “General
Selection” in the DPL command dialog. The “SEL” object is available in all DPL scripts at all
times and only one single “General Selection” object is valid at a time for all DPL scripts. This
means that setting the “General Selection” in the one DPL command dialog, will change it for all
other DPL commands too.
The method “AllLines()” in line 08 will return a set of all lines found in the general selection. This
set is assigned to the variable “S”. The lines are now accessed one by one by using the set
methods “First()” and “Next()” in line 09, 16 and 22. The line with the highest loading is kept in
the variable “Omax”. The name and database location of this line is written to the output window
at the end of the script by calling “ShowFullName()”.
DPL Manual
10
DIgSILENT PowerFactory
DPL
1.6 Accessing External Objects
The DPL contents makes it possible to access external object in the DPL script. The special
general selection object (“SEL”) is used to give all DPL functions and their subroutines access to
a central selection of objects.
Although flexible, this method would create problems if more than one specific object should be
accessed in the script. By creating references to those objects in the DPL command itself, the
DPL command would become specific to the current calculation case. Gathering the objects in
the general selection would create the problem of selecting the correct object.
To prevent the creation of calculation-specific DPL commands, it is recommended practice to
reserve the DPL contents for all objects that really ‘belong’ to the DPL script and which are thus
independent on were and how the script is used. Good examples are load flow and short-circuit
commands, or the vector and matrix objects that the DPL command uses for its computations.
If a DPL script must access a database object dependent on where and how the DPL script is
used, an “External Object” must be added to the external object list in the DPL root command.
Such an external object is a named reference to a external database object. The external object
is referred to by that name. Changing the object is then a matter of selecting another object. In
Fig. 1.4, an example of a external object is given. This external object may be referred to in the
DPL script by the name “Bar1”, as is shown in the example.
Figure 1.4: DPL external object table
Example:
sagdepth = Bar1:u;
1.7 Remote Scripts and DPL command Libraries
The easiest way to develop a new DPL command is to create a new ComDpl in the currently
active study case and to write the script directly in that DPL object. In such a way, a DPL “root
command” is made. If this root command needs DPL subroutines, then one or more DPL
command objects may be created in its contents. Each of these subroutines will normally also be
written as root functions.
The newly written DPL command with its subroutines may be tested and used in the currently
active study case. However, it cannot be executed when another study case is active. In order to
use the DPL command in other study cases, or even in other projects, we would have to copy the
DPL Manual
11
DIgSILENT PowerFactory
DPL
DPL command and its contents. This, however, would make it impossible to alter the DPL
command without having to alter all its copies.
The solution is in the use of ‘remote scripts’. The procedure to create and use remote scripts is
described as follows.
Suppose we have created and tested a new DPL command in the currently active study case.
We would like to store this DPL command in a save place and make it possible to use it in other
study cases and projects.
This is done by the following steps:
• copy the DPL command to a library folder. This will also copy the contents of the DPL
command, i.e. with all it’s DPL subroutines and other locally stored objects.
• “Generalize” the copied DPL command by resetting all project specific external objects. Set
all interface variable values to their default values. To avoid deleting a part of the DPL
command, make sure that if any of the DPL (sub)commands refers to a remote script, all
those remote scripts are also stored in the library folder.
• Activate another study case.
• Create a new DPL command object (ComDPL) in the active study case.
• Set the “DPL script” reference to the copied DPL command.
• Select the required external objects.
• Optionally change the default values of the interface variables
• Press the Check button to check the DPL script
The Check or Execute button will copy all parts of the remote script in the library that are
needed for execution. This includes all subroutines, which will also refer to remote scripts, all
command objects, and all other objects. Some classes objects are copied as reference, other
classes are copied completely.
The new DPL command does not contain a script, but executes the remote script. For the
execution itself, this does not make a change. However, more than one DPL command may now
refer to the same remote script. Changing the remote script, or any of its local objects or
sub-commands, will now change the execution of all DPL commands that refer to it.
1.7.1 Subroutines and Calling Conventions
A DPL command object may be included in the contents of another DPL command. In that case,
the included DPL “subroutine” may be called in the script of the enclosing DPL command. In
principle, this is not different from calling, for example, a load flow command from a DPL script.
As with most other command objects, the DPL command only has one method:
int Execute() ; executes the DPL script.
The difference is that each DPL subroutine has different interface parameters, which may be
changed by the calling command. These interface parameters can also be set directly at calling
time, by providing one or more calling arguments. These calling arguments are assigned to the
interface parameters in order of appearance. The following example illustrates this.
Suppose we have a DPL sub-command “Sub1” with the interface section as depicted in Fig. 1.5.
The calling command may then use, for example:
DPL Manual
12
DIgSILENT PowerFactory
DPL
Figure 1.5: Interface section of subroutine
! set the parameters:
Sub1:step
= 5.0;
Sub1:Line
= MyLine;
Sub1:Outages = MySelection;
! execute the subroutine:
error = Sub1.Execute();
However, using calling arguments, we may also write:
! execute the subroutine:
error = Sub1.Execute(5.0, MyLine,
MySelection);
1.8 DPL Functions and Subroutines
The DPL syntax is very small because it mainly serves the purpose of basic operations like
simple calculations, if-them-else selections, do-while’ loops, etc..
The strength of the DPL language is the possibility to call functions and to create subroutines. A
function which can be called by a DPL command is called a “method” . Four types of methods
are distinguished:
Internal methods These are the build-in methods of the DPL command. They can be called
always.
Set methods These methods are available for the DPL ‘set’ variables.
Object methods These methods are available for the DPL ‘object’ variables.
External methods These are the methods which are available for certain external DIgSILENT
objects, such as the loadflow command, the line object, the asynchronous machine, etc.
1.8.1 DPL Internal Methods
The DPL program language has a small set of DPL-specific internal commands:
Random
validLDF
validRMS
validSHC
validSIM
AllRelevant
ActiveCase
SummaryGrid
ActiveProject
Write
DPL Manual
returns a random number
checks for a valid loadflow result
checks for a valid simulation result
checks for a valid short-circuit result
checks for a valid simulation result
returns all calculation relevant objects
returns the active calculation case
returns the summary grid
returns the active project
writes a report
13
DIgSILENT PowerFactory
ResetCalculation
PostCommand
Exe
ClearCommands
GetLanguage
Delete
EchoOn
EchoOff
GetGraphBoard
GetCaseCommand
printf
sprintf
Error
Warn
Info
NoFinalUpdate
GetLocalLib
GetGlobalLib
DPL
resets the calculations
adds a command to the command pipe
executes a command
clears the command pipe
returns the current language
deletes the object
Re-activates the user interface
Freezes (de-activates) the user-interface
Returns the currently active Graphics Board
Returns default command objects
Outputs a formatted string
Returns a formatted string
Emits a formatted error
Outputs a formatted warning
Outputs a formatted information
Prevents “EchoOn()” at end of execution
Returns a local library folder
Returns a global library folder
More information about these commands can be found in the on-line manual.
1.8.2 DPL Set Methods
Set methods are functions for the set type parameters.
set . [SETMETHOD] ( arguments ) ;
The following [SETMETHOD] methods are available:
Clear
IsIn
Add
Remove
Count
First
Next
Firstmatch
Nextmatch
FirstFilt
NextFilt
SortToVar
SortToClass
SortToName
MarkInGraphics
removes all objects from the set
searches for an object in the set
adds an object
removes an object
returns the number of stored objects
returns the first objects
returns the next object
returns the first matching object
returns the next matching object
returns the first matching object
returns the next matching object
sorts the objects to a variable value
sorts the objects to their class
sorts the objects to their names
marks the objects in the graphic
More information about these commands can be found in the on-line manual.
1.8.3 Object Methods
The object methods are specific for each type of object class. A result file object (ElmRes), for
instance, has a “Write” method, which would not make sense for a load flow command object.
The general syntax for an object method equals that of the set method:
object . [OBJMETHOD] ( arguments ) ;
DPL Manual
14
DIgSILENT PowerFactory
DPL
The following overview lists all the non-specific [OBJMETHOD] methods which are available for
all classes.
Unom
MarkInGraphics
ShowFullName
IsClass
AddCopy
CreateObject
Edit
GetParent
GetContents
HasResults
IsRelevant
IsOutOfService
GetConnectionCount
GetCubicle
Move
IsInFeeder
VarExists
returns the nominal voltage
marks the object in the graphic
prints the full database path and name
checks for a certain class
adds a copy of an object
creates a new object
opens the object dialog
Returns the parent folder
Returns the stored objects
returns if the object has result parameters
Returns if the object is used for calculations
Returns if the object is out of service
Returns the number of electrical connections
returns the object’s cubicle
Moves an objects to this folder
Returns if the object belongs to the feeder
Checks a variable name
More information about these commands can be found in the on-line manual.
The following overview lists all the available object specific [OBJMETHOD] methods. Calling
these methods for the wrong class will result in an error message.
ComRes.ExportFullRange
ComEcho.Off
SetFilt.Get
IntMat.Get
IntMat.Init
IntMat.NRow
IntMat.RowLbl
IntVec.Get
IntVec.Init
IntVec.Size
ElmCoup.Open
ElmCoup.IsClosed
ElmLne.GetType
ElmLne.IsNetCoupling
TypLne.IsCable
ElmRes.Clear
ElmRes.Draw
ComRel3.Execute
ComLdf.Execute
StaSwitch.Close
StaSwitch.IsOpen
SetFeeder.GetAll
SetFeeder.GetBranches
SetPath.GetBusses
SetPath.AllBreakers
SetPath.AllOpenBreakers
SetSelect.Clear
SetSelect.AllLines
SetSelect.AllLoads
DPL Manual
ComEcho.Execute
ComEcho.On
ComTime.Execute
ComDpl.Execute
IntMat.Set
IntMat.Resize
IntMat.NCol
IntMat.ColLbl
IntVec.Set
IntVec.Resize
ElmCoup.Close
ElmCoup.IsOpen
ElmLne.HasRoutesOrSec
ElmLne.IsCable
ElmLne.SetCorr
ElmLne.SetNomCurr
ElmRes.Write
ElmRes.WriteDraw
ComInc.Execute
ComShc.Execute
StaSwitch.Open
StaSwitch.IsClosed
SetFeeder.GetBuses
SetPath.GetAll
SetPath.GetBranches
SetPath.AllClosedBreakers
SetSelect.AddRef
SetSelect.AllElm
SetSelect.AllBars
SetSelect.AllAsm
15
DIgSILENT PowerFactory
DPL
SetSelect.AllSym
SetSelect.All
SetSelect.AllBreakers
SetSelect.AllOpenBreakers
SetSelect.AllTypLne
SetSelect.GetAll
SetSelect.AllClosedBreakers
IntForm.SetText
More information about these commands can be found in the on-line manual.
LoadResData
void LoadResData (object O)
Loads the data of a result file (ElmRes) in memory. An error is produced when O is not a
ElmRes object.
Arguments
object O (obligatory) : The result file object
Return value
void
Example
Example.
object obj, res;
double x;
int Nvar, Nval, n, ix,iy;
string str;
obj = GetCaseCommand(’ComInc’);
res = obj:p_resvar;
LoadResData(res);
Nvar = ResNvars(res);
Nval = ResNval(res,0);
printf(’Nvar=%d Nval=%d’, Nvar, Nval);
ix = 0;
while (ix<Nval) {
iy = 0;
GetResData(x, res, ix);
str = sprintf(’%f :’, x);
while (iy<Nvar) {
GetResData(x, res,ix,iy);
str = sprintf(’%s %8.5f ’, str, x);
iy += 1;
}
printf(’%s’, str);
ix += 1;
}
An example (depending of the results in the result object) of the output for this script :
Nvar=3 Nval=11
-0.050000 : 0.12676
-0.040000 : 0.12676
-0.030000 : 0.12676
-0.020000 : 0.12676
-0.010000 : 0.12676
-0.000000 : 0.12676
0.010000 : 0.12676
0.020000 : 0.12676
DPL Manual
30.73286
30.73286
30.73286
30.73286
30.73286
30.73286
30.73286
30.73286
12.91360
12.91360
12.91360
12.91360
12.91360
12.91360
12.91360
12.91360
16
DIgSILENT PowerFactory
0.030000 :
0.040000 :
0.050000 :
DPL
0.12676
0.12676
0.12676
30.73286
30.73286
30.73286
12.91360
12.91360
12.91360
ResNvars
int ResNvars (object O)
returns the number of variables (columns) in result file. An error is produced when O is not a
ElmRes object.
Arguments
object O (obligatory) : The result file object
Also see “LoadResData()” in 1.8.3, page 16 .
ResNval
int ResNval (object O, int iCrv)
returns the number of values stored in result object for curve iCrv. An error is produced when
O is not a ElmRes object.
Arguments
object O (obligatory) : The result file object
int iCrv (obligatory) : The curve number, which equals the variable or column number.
Also see “LoadResData()” in 1.8.3, page 16 .
GetResData
int ResNval (double x, object O, int iX, int iCrv)
Returns a value from a result object for row iX of curve iCrv. An error is produced when O is
not a ElmRes object.
Arguments
double d (obligatory) : the returned value
object O (obligatory) : The result file object
int iX (obligatory) : the row index
int iCrv (optional) : The curve number, which equals the variable or column number, first
column value (time,index, etc.) is returned when omitted.
Return value
0 when ok
1 when iX out of bound
2 when iCrv out of bound
3 when invalid value is returned (‘INFINITY’, ‘DUMMY’, etc.)
Also see “LoadResData()” in 1.8.3, page 16 .
GetCaseObject
object GetCaseObject (string ClassName)
Returns the first found object of class “ClassName” from the currently active calculation case.
Creates such an object when no object of the given class was found in the calculation case.
Arguments
string ClassName (optional) : Class name of the object
Return value
The found or created object.
Example
The following example gets the SetTime object.
object Obj;
Obj = GetCaseObject(’SetTime’);
DPL Manual
17
DIgSILENT PowerFactory
DPL
if (Obj) {
...
}
Also see “GetCaseCommand()” in 1.8.3, page 18 .
GetCaseCommand
object GetCaseCommand (string ClassName)
Returns the default command object of class “ClassName” from the currently active calculation
case. Creates such a command when possible and when the calculation case not yet contains
a command of the given class. Initializes newly created commands according to the project
settings.
The buttons on the main menu for loadflow, short-circuit, transient simulation, etc. also open
the corresponding default command from the currently active study case. Using ”GetCaseCommand()” in a DPL script will return the same command.
Arguments
string ClassName (optional) : Class name of the command
Return value
The found or created command.
Example
The following example executes the default loadflow command.
object Com;
Com = GetCaseCommand(’’ComLdf’);
if (Com) {
Com.Execute();
}
Also see “GetCaseObject()” in 1.8.3, page 17 .
EchoOn
void EchoOn ()
Re-activates the user interface.
Arguments
none
Return value
void
Example
The following example de-activates the user-interface to speed up the calculations, after which
the user-interface is re-activated again.
EchoOff();
.. do some calculation ...
EchoOn();
Also see “EchoOff()” in 1.8.3, page 18 . Also see “NoFinalUpdate()” in 1.8.3, page 19 .
EchoOff
void EchoOff ()
Freezes (de-activates) the user-interface. For each EchoOff(), a EchoOn() should be called.
A EchoOn() is automatically executed at the end of a DPL execution, except for when “NoFinalUpdate()” has been called.
Arguments
none
DPL Manual
18
DIgSILENT PowerFactory
DPL
Return value
void
Example
Example.
Example
The following example de-activates the user-interface to speed up the calculations, after which
the user-interface is re-activated again.
EchoOff();
.. do some calculation ...
EchoOn();
Also see “EchoOn()” in 1.8.3, page 18 . Also see “NoFinalUpdate()” in 1.8.3, page 19 .
NoFinalUpdate
void NoFinalUpdate ()
Prevents the automatic “EchoOn()” at end of execution.
Arguments
none
Return value
void
Example
Example.
EchoOff();
.. do some calculation ...
NoFinalUpdate();
Also see “EchoOff()” in 1.8.3, page 18 . Also see “EchoOn()” in 1.8.3, page 18 .
GetLocalLib
object GetLocalLib ([string ClassName])
Returns the local library for object-types of class “ClassName”. ClassName may be omitted, in
which case the complete local library folder is returned.
Arguments
string ClassName (optional) : The classname of the objects for which the library folder is
sought
Return value
The library folder
Example
The following example shows the contents of the local library for line types.
object Lib, O;
set S;
Lib = GetLocalLib(’TypLne’);
S = lib.GetContents();
O = S.First();
while (O) {
O:ShowFullName();
O = S.Next();
}
Also see “GetGlobalLib” in 1.8.3, page 20 .
DPL Manual
19
DIgSILENT PowerFactory
DPL
GetGlobalLib
object GetGlobaleLib ([string ClassName])
Returns the global library for object-types of class “ClassName”. ClassName may be omitted,
in which case the complete global library folder is returned.
Arguments
string ClassName (optional) : The classname of the objects for which the library folder is
sought
Return value
The library folder
Example
The following example shows the contents of the global library for line types.
object Lib, O;
set S;
Lib = GetGlobalLib(’TypLne’);
S = lib.GetContents();
O = S.First();
while (O) {
O:ShowFullName();
O = S.Next();
}
Also see “GetLocalLib” in 1.8.3, page 19 .
Format String Syntax
The string printing commands “printf” , “sprintf” , “Error” , “Warn” , and “Info” all use the same
format string syntax.
The format string must contain a valid place holder for every given argument. The placeholder
format is
[flags] [width] [.precision] type
Where “type” is one of the following specifiers:
’d’ or ’i’ For an integer value.
’e’ For a double value. The printed format is “[ ]d.dddd e [sign]ddd” where d is a single decimal
digit, “‘dddd” is one or more decimal digits, “ddd” is exactly three decimal digits, and “[sign]”
is “+” or “”.
’E’ Identical to the e format except that “E” in stead of “e” is used.
’f’ For a double value. Printed format is “[ ]dddd.dddd”, where “dddd” is one or more decimal
digits. The number of digits before the decimal point depends on the magnitude of the
number, and the number of digits after the decimal point depends on the requested
precision.
’g’ For a double value. Printed format is the “f” or “e” format, whichever is more compact for the
given value and precision. The e format is used only when the exponent of the value is less
than 4 or greater than or equal to the precision argument. Trailing zeros are truncated, and
the decimal point appears only if one or more digits follow it.
’G’ Identical to the “g” format, except that “E” in stead of “e”, is used (where appropriate).
’s’ For a string.
The optional “flag” can be one of the following specifiers:
’-’ : Left align the result within the given field width.
DPL Manual
20
DIgSILENT PowerFactory
DPL
’+’ : Prefix the output value with a sign (+ or )
The optional “width” specifies the number of characters to be printed and the optional
“.precision” specifies the number of decimals printed.
Example
The following examples shows various placeholder definitions.
double x;
int i;
string s;
x = 123456789.987654321;
i = 2468;
s = ’hello dpl’;
printf(’%f|%15.3f|%E|%.2e|%+f|’, x,x,x,x,x);
printf(’%d|%6d|%-6d|’, i,i,i);
printf(’%s|%-20s|%20s|’,s,s,s);
! string concat is possible:
s = ’this’;
s = sprintf(’%s %s’, s, ’DPL script’);
! print and assign in one action:
s = printf(’%s %s "%s"’, s, ’is called’, this:loc_name);
printf(’%s (again)’,s); ! print again:
fWrite
The command “fWrite” is obsolete and has been replaced by the “printf” command. See “printf”
in 1.8.3, page 21 for more information.
ToStr
The command “ToStr” is obsolete and has been replaced by the “sprintf” command. See “sprintf”
in 1.8.3, page 22 for more information.
printf
string printf (String Format,String T | double X | int I, ...)
Outputs a formatted string. The printf() command uses the C++ printf() formatting syntax.
Arguments
String Format (obligatory) : The format string
String T (optional) : string argument
double X (optional) : double argument
int I (optional) : int argument
Return value
The formatted string
The output format is defined by the format string. The passed arguments and the passed format
string must match. An error message will be produced when, for instance, a format string for two
strings is used together with three doubles.
See the “format string syntax” in 1.8.3, page 20 for more information.
Also see “sprintf” in 1.8.3, page 22 .
Also see “Error” in 1.8.3, page 22 .
Also see “Warn” in 1.8.3, page 23 .
Also see “Info” in 1.8.3, page 23 . Also see “Write” in 1.8.3, page 24 .
DPL Manual
21
DIgSILENT PowerFactory
DPL
sprintf
string sprintf (String Format, String T | double X | int I, ...)
Returns a formatted string. The sprintf() command uses the C++ printf() formatting syntax.
Arguments
String Format (obligatory) : The format string
String T (optional) : string argument
double X (optional) : double argument
int I (optional) : int argument
Return value
The formatted string
Example
The following example redirects the output to a file. The filename is formatted from a path and
the name of the current calculation case. “Redirect” is an ComOp and “StopRedirect” is an
ComCl object in the DPL command
Redirect:f = sprintf(’%s%s.out’, ’c:\\MyDocuments\\results0813\\’, O:loc_name);
Redirect.Execute();
Form.WriteOut(Lines);
! write a report
StopRedirect.Execute(); ! stop redirection
The output format is defined by the format string. The passed arguments and the passed format
string must match. An error message will be produced when, for instance, a format string for two
strings is used together with three doubles.
See the format string syntax in 1.8.3, page 20 for more information.
Also see “printf” in 1.8.3, page 21 .
Also see “Error” in 1.8.3, page 22 .
Also see “Warn” in 1.8.3, page 23 .
Also see “Info” in 1.8.3, page 23 . Also see “Write” in 1.8.3, page 24 .
Error
string Error (String Format,String T | double X | int I, ...)
Writes a formatted string as error message to the output window. The DPL execution will
continue, but a pop-up error message box will appear at the end of execution.
Arguments
String Format (obligatory) : The format string
String T (optional) : string argument
double X (optional) : double argument
int I (optional) : int argument
Return value
The formatted string
Example
The following example writes an error to the output window.
Error(’Index could not be calculated.’);
The output format is defined by the format string. The passed arguments and the passed format
string must match. An error message will be produced when, for instance, a format string for two
strings is used together with three doubles.
See the format string syntax in 1.8.3, page 20 for more information.
DPL Manual
22
DIgSILENT PowerFactory
DPL
Also see “printf” in 1.8.3, page 21 .
Also see “sprintf” in 1.8.3, page 22 .
Also see “Warn” in 1.8.3, page 23 .
Also see “Info” in 1.8.3, page 23 .
Also see “Write” in 1.8.3, page 24 .
Info
string Info (String Format, String T | double X | int I, ...)
Writes a formatted string as information message to the output window.
Arguments
String Format (obligatory) : The format string
String T (optional) : string argument
double X (optional) : double argument
int I (optional) : int argument
Return value
The formatted string
Example
The following example writes an info message to the output window.
Info(’Trying to calculate first index...’);
The output format is defined by the format string. The passed arguments and the passed format
string must match. An error message will be produced when, for instance, a format string for two
strings is used together with three doubles.
See the format string syntax in 1.8.3, page 20 for more information.
Also see “printf” in 1.8.3, page 21 .
Also see “sprintf” in 1.8.3, page 22 .
Also see “Error” in 1.8.3, page 22 .
Also see “Warn” in 1.8.3, page 23 .
Also see “Write” in 1.8.3, page 24 .
Warn
string Warn (String Format, String T | double X | int I, ...)
Writes a formatted string as warning to the output window.
Arguments
String Format (obligatory) : The format string
String T (optional) : string argument
double X (optional) : double argument
int I (optional) : int argument
Return value
The formatted string
Example
The following example writes a warning message to the output window.
Warn(’No loads attached: using approximation.’);
The output format is defined by the format string. The passed arguments and the passed format
string must match. An error message will be produced when, for instance, a format string for two
strings is used together with three doubles.
DPL Manual
23
DIgSILENT PowerFactory
DPL
See the format string syntax in 1.8.3, page 20 for more information.
Also see “printf” in 1.8.3, page 21 .
Also see “sprintf” in 1.8.3, page 22 .
Also see “Error” in 1.8.3, page 22 .
Also see “Info” in 1.8.3, page 23 .
Also see “Write” in 1.8.3, page 24 .
Write
int Write (string Format, [object aObj | set aSet], ...)
Writes out a line of formatted text, using the DIgSILENT output language.
Arguments
string Format (obligatory) : The format string
object aObj (optional) : An object which is used to get data from
set aSet (optional) : A set which is used to get objects from
Return value
0 on success, 1 on error
The “Write” command is used to quickly output a line of formatted output, using the same
formatting language as is used for defining reports and result-boxes. See “The DIgSILENT
output language” in ??, page ?? for more information.
Because data or parameters of more than object is often written out, the DIgSILENT output
language has the special macro “ACC(x)” to distinguish between these objects. Prior to
execution, all given objects and all objects in the given sets are listed together in a single list.
The “ACC(x)” macro returns the object with the index “x” in that list. The ACC (“acc”=“access”)
macro can be used more than once for the same object.
Interface variables of the DPL script can also be used in the format string by the “DEF” macro. If
the DPL script has “ResX” as an interface double, then “DEF:ResX” will access that variable.
Example
In the following example, two lines of output are written out. The first line only contains normal
text. The second line writes the name and loading of two lines. In this example, “ACC(1)” refers
to the object “LineA’, and “ACC(2)” to “LineB”
Write(’The following results are found’);
Write(’#
: #.## # , #
: #.## # $N,
ACC(1):loc_name,ACC(1):c:loading,[ACC(1):c:loading,
ACC(2):loc_name,ACC(2):c:loading,[ACC(2):c:loading’, LineA, LineB);
Also see “printf” in 1.8.3, page 21 .
Also see “sprintf” in 1.8.3, page 22 .
Also see “Error” in 1.8.3, page 22 .
Also see “Warn” in 1.8.3, page 23 .
Also see “Info” in 1.8.3, page 23 .
strftime
string strftime (String Format)
Creates a formatted time string.
Arguments
DPL Manual
24
DIgSILENT PowerFactory
DPL
String Format (obligatory) : The format string
The following formatting codes are recognized in the format string.
%a
Abbreviated weekday name
%A
Full weekday name
%b
Abbreviated month name
%B
Full month name
%c
Date and time representation appropriate for locale
%d
Day of month as decimal number (01 31)
%H
Hour in 24-hour format (00 23)
%I
Hour in 12-hour format (01 12)
%j
Day of year as decimal number (001 366)
%m
Month as decimal number (01 12)
%M
Minute as decimal number (00 59)
%p
Current locales A.M./P.M. indicator for 12-hour clock
%S
Second as decimal number (00 59)
%U
Week of year as decimal number, with Sunday as first day of week (00 53)
%w
Weekday as decimal number (0 6; Sunday is 0)
%W
Week of year as decimal number, with Monday as first day of week (00 53)
%x
Date representation for current locale
%X
Time representation for current locale
%y
Year without century, as decimal number (00 99)
%Y
Year with century, as decimal number
%z, %Z Time-zone name or abbreviation; no characters if time zone is unknown
%%
Percent sign
Return value
The formatted time string
Example
The following example shows the date.
str = strftime(’Today is %A, day %d of %B in the year %Y.’);
printf(’%s’, str);
Output
Today is Wednesday, day 30 of April in the year 2003.
strlen
int strlen (string S)
returns the length of a string.
Arguments
string S (obligatory) : The string
strcmp
int strcmp (string S1, string S2, int count)
Compares two strings.
Arguments
string S1 (obligatory) : The first string
string S1 (obligatory) : The second string
int count (optional) : Number of characters to compare
Return value
-1 when S1 ¡ S2, for up to count characters
0 S1 = S2, for up to count characters
1 when S1 ¿ S2, for up to count characters
DPL Manual
25
DIgSILENT PowerFactory
DPL
strcpy
String strcpy (string S, int start, int count)
copies a substring from a string.
Arguments
string S (obligatory) : The string
int start (obligatory) : The start position in S
int count (optional) : Number of characters to copy
Return value
The copied substring
Example
Example.
string S1, S2;
S1 = ’The brown fox’;
S2 = strcpy(S1, 4, 5);
! S2 now equals ’brown’
strstr
int strcpy (string S1, String S2)
Searches for a substring in a string.
Arguments
string S1 (obligatory) : The string
string S2 (obligatory) : The substring
Return value
The first position in S1 where S2 was found, or -1 when S2 was not found.
Example
Example.
string S1, S2;
int i;
S1 = ’The brown fox’;
i = strstr(s1, ’brown’);
S2 = strcpy(S1, i, 5);
! S2 now equals ’brown’
GetPageLen
int GetPageLen (int orientation)
Returns the number of lines per page according to the currently selected printer and paper
size.
Arguments
int orientation (obligatory) : Paper orientation: 0: landscape, 1: portrait
Return value
The maximum number of lines that can be printed on a single sheet of paper.
Delete
void Delete (object O | set S)
Deletes an object or a set of objects from the database. The objects are not destroyed but are
moved to the recycle bin.
Arguments
object O (optional) : The object to delete
set S (optional) : The set of objects to delete
Return value
DPL Manual
26
DIgSILENT PowerFactory
DPL
void
Example
The following example removes all ”Dummy” fuses from the network. The ‘DummyType’ variable is a local variable in the DPL script. A set of objects-to-delete is created first and then
that set is deleted. This has the advantage that one single entry in the recycle bin is created
which contains all deleted fuses. Manually restoring (‘undelete’) the deleted fuses, in case of a
mistake, can then be done by a single restore command.
object O;
set S, Del;
S = AllRelevant();
O = S.Firstmatch(’RelFuse’);
while (O) {
if (O:typ_id=DummyType) {
Del.Add(O);
}
O = S.Nextmatch();
}
Delete(Del);
Random
double Random ([double x1 [,double x2]])
Returns a pseudo random value. If x1 and x2 are omitted, a value in the range of [0 ... 1] is
returned. If only x1 is given, the possible range is [0 ... x1] and with both x1 and x2, [x1 ... x2].
Arguments
double x1 (optional) : upper/lower limit
double x1 (optional) : upper limit
Return value
A pseudo-random number
Example
The following example sets a load to a random active power prior to calculating a loadflow.
double P;
Load:plini = Random(1.2, 2.3);
Ldf.Execute();
validLDF
int validLDF ()
Checks to see if the last load flow results are still valid and available.
Arguments
none
Return value
0 if no load flow results are available
Example
The following example checks if a loadflow is available, and performs one when not.
int valid;
valid = validLDF();
if (.not.valid) {
Ldf.Execute();
}
validRMS
int validRMS ()
DPL Manual
27
DIgSILENT PowerFactory
DPL
Checks to see if the last RMS simulation results are still valid and available.
Arguments
none
Return value
0 if no RMS simulation results are available
Example
The following example checks if a RMS simulation is available, and performs one when not.
int valid;
valid = validRMS();
if (.not.valid) {
Rms.Execute();
}
validSHC
int validSHC ()
Checks to see if the last short-circuit results are still valid and available.
Arguments
none
Return value
0 if no short-circuit results are available
Example
The following example checks if a short-circuit result is available, and performs one when not.
int valid;
valid = validSHC();
if (.not.valid) {
Shc.Execute();
}
validSIM
int validSIM ()
Checks to see if the last simulation results are still valid and available.
Arguments
none
Return value
0 if no simulation results are available
Example
The following example checks if a simulation result is available.
int valid;
valid = validSIM();
if (.not.valid) {
output(’No simulation result available’);
}
AllRelevant
Set AllRelevant ()
Returns a set with all objects which together form the target for all calculations. These are the
objects that are check-marked in the database browser. The set of calculation relevant objects
is determined by the currently active study case and the currently active grids.
Arguments
none
Return value
DPL Manual
28
DIgSILENT PowerFactory
DPL
The set of all calculation relevant objects
Example
The following example writes the full path and name of all calculation relevant objects in the
output window.
set S;
object O;
S = AllRelevant();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
ActiveCase
Object ActiveCase ()
Returns the currently active Study Case.
Arguments
none
Return value
A “IntCase” object
Example
The following example writes the name of the active study case to the output window.
object aCase;
aCase = ActiveCase();
aCase.ShowFullName();
SummaryGrid
Object SummaryGrid ()
Returns the summary grid in the currently active Study Case. The summary grid is the combination of all active grids in the study case.
Arguments
none
Return value
A “ElmNet” object, or a ‘NULL’ object when no grids are active
Example
The following example performs a loadflow and returns the total grid active power losses.
object SumGrid;
SumGrid = SummaryGrid();
if (SumGrid) {
Ldf.Execute();
output(’Active Power Losses=SumGrid:c:LossP’);
}
ActiveProject
Object ActiveProject ()
Returns the currently active project
Arguments
none
Return value
A “IntPrj” object
Example
The following example prints the name of the active project to the output window.
DPL Manual
29
DIgSILENT PowerFactory
DPL
object Prj;
Prj = ActiveProject();
Prj.ShowFullName();
ResetCalculation
void ResetCalculation ()
Resets all calculations and destroys all volatile calculation results.
Arguments
none
Return value
void (no return value)
Results that have been written to result objects (for display in graphs) will not be destroyed. All
results that are visible in the single line diagrams, however, will be destroyed.
Example
The following example resets all calculations.
ResetCalculation();
PostCommand
void PostCommand (string Command)
Adds a command to the command pipe in the input window. The posted commands will be
executed after the DPL command has finished.
Arguments
string Command (obligatory) : The command string
Return value
void (no return value)
Example
The following command causes the DIgSILENT program to end after the DPL script has finished.
PostCommand(’exit’);
Exe
void Exe (string Command)
Immediately executes the command, bypassing the command pipe in the input window. The
DPL command will continue after the command has been executed. The ‘Exe’ command is
provided for compatibility and testing purposes only and should only be used by experienced
users.
Arguments
string Command (obligatory) : The command string
Return value
void (no return value)
Example
The following command causes the output or graphical window to be printed.
PostCommand(’pr’);
ClearCommands
void ClearCommands ()
Clears the command pipe of the input window.
Arguments
none
Return value
void (no return value)
DPL Manual
30
DIgSILENT PowerFactory
DPL
Example
The following command clears the input window.
ClearCommands();
ClearCommands
void ClearOutput ()
Clears the output window.
Arguments
none
Return value
void (no return value)
Example
The following command clears the output window.
ClearOutput();
GetLanguage
int GetLanguage ()
Returns the current program language setting.
Arguments
none
Return value
0 = English, 1 = German
Example
The following example displays a different message, depending on the language.
int err, lng;
lng = GetLanguage();
err = Ldf.Execute();
if (err) {
if (lng) {
output(’Loadflow command returned an error’);
} else {
output(’Fehler im Lastfluss Kommando’);
}
exit();
}
GetGraphBoard
SetDeskTop GetGraphBoard ()
Returns the currently active Graphics Board.
Arguments
none
Return value
The graphics board object
Example
The following example looks for an opened Graphics Board and sets its default results to the
results object named ’Results’.
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
DPL Manual
31
DIgSILENT PowerFactory
DPL
if (aGrf) {
! Set default results object
aGrf.SetResults(Results);
}
Also see
SetDeskTop.GetPage in 1.8.36, page 80
SetDeskTop.SetResults in 1.8.36, page 81
SetDeskTop.SetXVar in 1.8.36, page 81
SetDeskTop.SetScaleX in 1.8.36, page 81
SetDeskTop.SetAutoScaleX in 1.8.36, page 82
SetDeskTop.SetAdaptX in 1.8.36, page 83
Clear
void Set.Clear ()
Clears the set.
Arguments
none
Return value
void
Example
The following example clears a set
set Sbig;
Sbig = SEL.AllLines();
...
Sbig.Clear();
IsIn
int Set.IsIn (object O)
Checks if the set contains object ’O’.
Arguments
object O (obligatory) : an object
Return value
1 if the O is in the set.
Example
The following example collects all not selected lines.
set Ssel, Srel, Snsel;
object lne;
int i;
Ssel = SEL.AllLines();
Srel = AllRelevant();
lne = Srel.Firstmatch(’ElmLne’);
while (lne) {
i = Ssel.IsIn(lne);
if (i=0) Snsel.Add(lne);
lne = Srel.Nextmatch();
}
Add
int Set.Add ([object O | set S])
Adds an object or all objects from a set to the set.
DPL Manual
32
DIgSILENT PowerFactory
DPL
Arguments
One of the following two parameter has to be given
object O (optional) : an object
set S (optional) : a set of objects
Return value
0 on success
Example
The following example collects all loads and lines and the first breaker from the general DPL
selection
set S, Sbig;
object O;
Sbig = SEL.AllLines();
S = SEL.AllLoads();
Sbig.Add(S);
S = SEL.AllBreakers();
O = S.First();
Sbig.Add(O);
Remove
int Set.Remove (object O)
Removes an object from the set.
Arguments
object O (obligatory) : the object to remove
Return value
0 on success
Example
The following example removes al short lines from a set
set S;
object O;
double l;
S = SEL.ALLLines();
O = S.First();
while (O) {
l = O:dline;
if (l<1) {
S.Remove(O);
}
O = S.Next();
}
Count
int Set.Count ()
Returns the number of objects in the set.
Arguments
none
Return value
The number of objects in the set.
Example
The following example terminates the DPL script when the general selection is found to contain
no lines.
set S;
int n;
S = SEL.AllLines();
DPL Manual
33
DIgSILENT PowerFactory
DPL
n = S.Count();
if (n=0) {
exit();
}
Obj
int Set.Obj (int Index)
Returns the object at the given index in the set.
Arguments
int Index (obligatory) : the index of the object.
Return value
The object at the given index in the set, when “Index” is in range, NULL otherwise.
First
Object Set.First ()
Returns the first object in the set
Arguments
none
Return value
The first object or 0 when the set is empty
Example
The following example writes the full names of all line in the general selection to the output
window.
set S;
object O
S = SEL.AllLines();
O = S.First();
while (O) {
O.ShowFullName();
O = O.Next();
}
Next
Object Set.Next ()
Returns the next object in the set
Arguments
none
Return value
The next object or 0 when the last object has been reached
Example
The following example writes the full names of all line in the general selection to the output
window.
set S;
object O
S = SEL.AllLines();
O = S.First();
while (O) {
O.ShowFullName();
O = O.Next();
}
DPL Manual
34
DIgSILENT PowerFactory
DPL
Firstmatch
Object Set.Firstmatch (String WildCard)
Returns the first object from the set which class name matches the wildcard
Arguments
String WildCard (obligatory) : class name, possibly containing ‘*’ and ‘?’ characters
Return value
The first matching object, or 0 when no such object
Example
The following example writes all two and three winding transformers to the output window
set S;
object O;
S = AllRelevant();
O = S.Firstmatch(’ElmTr?’);
while (O) {
O.ShowFullName();
O = S.Nextmatch();
}
Nextmatch
int Set.Nextmatch ()
Returns the next object from the set which class name matches the wildcard
Arguments
none
Return value
The next object, or 0 when no next object
Example
The following example writes all two and three winding transformers to the output window
set S;
object O;
S = AllRelevant();
O = S.Firstmatch(’ElmTr?’);
while (O) {
O.ShowFullName();
O = S.Nextmatch();
}
FirstFilt
Object Set.FirstFilt (String WildCard)
Returns the first object from the set which name matches the wildcard. The wildcard may
contain (parts of the) name and classname.
Arguments
String WildCard (obligatory) : class name, possibly containing ‘*’ and ‘?’ characters
Return value
The first matching object, or NULL when no first object exists.
Example
The following example writes all two and three winding transformers whose name start with a
“T” to the output window
set S;
object O;
S = AllRelevant();
O = S.FirstFilt(’T*.ElmTr?’);
while (O) {
DPL Manual
35
DIgSILENT PowerFactory
DPL
O.ShowFullName();
O = S.NextFilt();
}
Also see “NextFilt” in 1.8.3, page 36 .
NextFilt
int Set.NextFilt ()
Returns the next object from the set which name matches the wildcard.
Arguments
none
Return value
The next object, or NULL when no next object exists.
Example
The following example writes all two and three winding transformers to the output window
set S;
object O;
S = AllRelevant();
O = S.FirstFilt(’T*.ElmTr?’);
while (O) {
O.ShowFullName();
O = S.NextFilt();
}
Also see “FirstFilt” in 1.8.3, page 35 .
SortToVar
int Set.SortToVar (int R, string V1, · · · , string V5)
Sorts the objects in the set to the variable names.
Sorts the objects to the values for V1. Within the sorting for V1, a sub-sorting for V2,
sub-sub-sorting for V3, etc., until V5 can be performed. The sorting is from higher values to
lower when R == 1, and reverse when R == 0.
Arguments
int R (obligatory) : sorting direction
string V1 (obligatory) : first variable name
string V2 (optional) : , · · · , string V5 (optional) : 2nd..5th variable names
Return value
0 on success
Example
The following example writes all lines to the output window, sorted to cable or OHL, nominal
voltage, and length.
set S, Sl;
object O;
S = AllRelevant();
Sl = S.AllLines();
Sl.Sort(0, ’t:aohl_’, ’t:uline’, ’dline’);
O = Sl.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
DPL Manual
36
DIgSILENT PowerFactory
DPL
SortToClass
int Set.SortToClass (int R)
Sorts the objects in the set to their class.
Sorts the objects in the set to their class name. The sorting is from A..Z when R = 0 and reverse
when R = 1.
Arguments
int R (obligatory) : sorting direction
Return value
0 on success
Example
The following example writes all objects to the output window, sorted to classes.
set S;
object O;
S = AllRelevant();
S.SortToClass(0);
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
SortToName
int Set.SortToName (int R)
Sorts the objects in the set to their name.
Sorts the objects in the set to their name. The sorting is from A..Z when R = 0 and reverse when
R = 1.
Arguments
int R (obligatory) : sorting direction
Return value
0 on success
Example
The following example writes all objects to the output window, sorted to names.
set S;
object O;
S = AllRelevant();
S.SortToName(0);
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
MarkInGraphics
void Set.MarkInGraphics ()
Marks all objects in the set in the currently visible graphic by hatch crossing them.
Arguments
none
Return value
void
Example
The following example will try to mark a set of lines in the single line graphic.
DPL Manual
37
DIgSILENT PowerFactory
DPL
set S;
object O;
S = SEL.AllLines();
S.MarkInGraphics();
GetParent
object Object.GetParent ()
Returns the parent folder.
Arguments
none
Return value
The parent folder object.
Example
The following example returns the folder in which a line is stored. The function “GetBestLine()”
is an example DPL script wich returns a line.
object Lne, Fold;
Lne = GetBestLine();
Fold = Lne.GetParent();
...
Also see “GetContents” in 1.8.3, page 42 .
HasResults
void Object.HasResults ()
returns ‘true’ when the object has calculated result parameters.
Arguments
none
Return value
‘true’ (1) or ‘false’ (0)
Example
example.
example is in preparation
GetConnectionCount
int Object.GetConnectionCount ()
Returns the number of electrical connections.
Arguments
none
Return value
The number of connections.
Example
example.
example is in preparation
GetCubicle
object Object.GetCubicle (int N)
returns the cubicle in which the object is stored, or NULL when the object is not stored in a
cubicle.
Arguments
int N (obligatory) : The connection number.
DPL Manual
38
DIgSILENT PowerFactory
DPL
Return value
The cubicle object or NULL.
Example
example.
example is in preparation
Move
void Object.Move (object O | set S )
Moves an object or a set of objects to this folder.
Arguments
object O (optional) : Object to move set S (optional) : Set of objects to move
Return value
0 on success, 1 on error.
Example
example.
example is in preparation
IsInFeeder
void Object.Function (object Feeder [, double OptNested=0] )
Returns if the object belongs to the feeder area defined by “Feeder”.
Arguments
object Feeder (obligatory) :
The Feeder definition object double OptNested (optional) :
“Nested feeders” option (1 or 0)
Return value
1 if “Feeder” is a feeder definition and the object is in the feeder area, 0 otherwise.
VarExists
void Object.VarExists (string VarName)
Checks to see if this object has a currently valid variable called “VarName”
Arguments
string VarName (obligatory) : The name of the variable.
Return value
1 when “VarName” is the name of a currently valid variable for this object.
Example
The following example calculates the total length of cables and lines.
double x;
int i;
set s;
object O;
s = AllRelevant();
O = s.First();
while (O) {
i = O.VarExists(’dline’);
if (i) {
x += O:dline;
}
O = s.Next();
}
printf(’Total length = %d’, x);
DPL Manual
39
DIgSILENT PowerFactory
DPL
IsNode
int Object.IsNode ()
Returns 1 if object is a node (terminal or busbar).
Arguments
none
Return value
1 if object is s node, 0 otherwise
GetSize
int Object.GetSize (string VarName,int rows,int cols)
Returns the size of the variable “VarName” when this variable is a vector or a matrix.
Arguments
string VarName (obligatory) : The name of the variable int rows (obligatory) : The number of
rows for a vector or matrix int cols (optional) : The number of columns for a matrix
Return value
0 when “VarName” is a valid variable name, else 1.
Example
The following example prints the matrix resistances from a Tower model with 2 circuits.
int ierr;
double x;
int r, rows, c, cols;
string s;
ierr = Tower.GetSize(’R_c’,rows, cols);
if (.not.ierr) {
r=0; while (r<rows) {
s = ’’;
c = 0; while (c<cols) {
ierr = Tower.GetVal(x, ’R_c’, r,c);
if (.not.ierr) s = sprintf(’%s %f’, s, x);
c+=1;
}
printf(s);
r+=1;
}
}
Example Output :
0.067073
0.016869
0.016594
0.016851
0.016576
0.016372
0.016869
0.066832
0.016701
0.016576
0.016445
0.016408
0.016594
0.016701
0.066738
0.016372
0.016408
0.016516
0.016851
0.016576
0.016372
0.067073
0.016869
0.016594
0.016576
0.016445
0.016408
0.016869
0.066832
0.016701
0.016372
0.016408
0.016516
0.016594
0.016701
0.066738
Also see “GetVal” in 1.8.3, page 40 .
GetVal
int Object.GetVal (double|object X, string VarName,int rows,int cols)
Returns the value of the variable “VarName” when this variable is a vector or a matrix, for the
given row and column.
Arguments
DPL Manual
40
DIgSILENT PowerFactory
DPL
double|object X (obligatory) : The variable in which to return the result
string VarName (obligatory) : The name of the variable
int rows (obligatory) : The row number for a vector or matrix
int cols (optional) : The column number for a matrix
Return value
0 when “VarName” is a valid variable name and row number and column number are in range,
else 1.
Example
see “GetSize” in 1.8.3, page 40
lnm
string Object.lnm (string VanName)
Returns the long variable name.
Arguments
string VarName (obligatory) : The variable name
Return value
The long name.
Example
The following example prints information about the length of a line.
string s1,s2,s3;
s1 = Line.lnm(’dline’);
s2 = Line.snm(’dline’);
s3 = Line.unm(’dline’);
printf(’%s (%s) = %5.3f [%s]’,s1, s2, Line:dline, s3);
Example output:
Length of Line (Length) = 0.547 [km]
Also see “snm” in 1.8.3, page 41
Also see “unm” in 1.8.3, page 41
snm
string Object.snm (string VanName)
Returns the short variable name. By default, the short name equals the long variable name.
In some cases, the variable also has a short name which is used to save space in reports or
dialogs.
Arguments
string VarName (obligatory) : The variable name
Return value
The short name.
Example
see “lnm” in 1.8.3, page 41
Also see “unm” in 1.8.3, page 41
unm
string Object.unm (string VanName)
Returns the unit of the variable.
Arguments
string VarName (obligatory) : The variable name
Return value
The unit name.
Example
DPL Manual
41
DIgSILENT PowerFactory
DPL
see “lnm” in 1.8.3, page 41
Also see “snm” in 1.8.3, page 41
GetContents
set Object.GetContents ()
Returns the set of objects that are stored in the object. Returns an empty set when if the
object’s container is empty or if the object is not capable of storing objects.
Arguments
none
Return value
The set of objects
Example
The following example collects all terminals that are stored in line objects.
set S, Lns, Trms;
object O;
Lns = SEL.AllLines();
O = Lns.First();
while (O) {
S = O.GetContents();
O = S.Firstmatch(’ElmTerm’);
while (O) {
Trms.Add(O);
O = S.Nextmatch();
}
O = Lns.Next();
}
Unom
double Object.Unom ()
Returns the nominal voltage of the object.
Arguments
none
Return value
The nominal voltage
Example
The following example collects all high voltage lines.
set S, Shv;
object O;
double U;
S = SEL.AllLines();
O = S.First();
while (O) {
U = O.Unom();
if (U>VoltageLevel) {
Shv.Add(O);
}
O = S.Next();
}
MarkInGraphics
void Object.MarkInGraphics ()
DPL Manual
42
DIgSILENT PowerFactory
DPL
Marks the object in the currently visible graphic by hatch crossing it.
Arguments
none
Return value
void
When the currently visible single line graphic does not contain the object, nothing will happen.
Example
The following example will try to mark a set of lines in the single line graphic.
set S;
object O;
S = SEL.AllLines();
O = S.First();
while (O) {
O.MarkInGraphics();
O = S.Next();
}
ShowFullName
void Object.ShowFullName ()
Writes the complete path and name to the output window.
Arguments
none
Return value
void
Because the complete database path is written to the output window, the written names can be
right clicked in the output window to edit the objects. This procedure is therefore useful for
selecting objects which should be inspected or edited after the DPL script has finished.
Example
The following example will write all overloaded lines from the selection to the output window.
set S;
object O;
S = SEL.AllLines();
O = S.First();
while (O) {
if (O:c:loading>100.0) {
O.ShowFullName();
}
O = S.Next();
}
IsClass
int Object.IsClass (string ClassName)
Checks to see if the object is of a certain class.
Arguments
string ClassName (obligatory) : The name of the class.
Return value
1 when the object is of the given class, 0 otherwise
Example
The following example write all overloaded lines and transformers to the output window, where
a different maximum loading is used for lines or transformers.
set S;
object O;
DPL Manual
43
DIgSILENT PowerFactory
DPL
int i;
S = AllRelevant();
O = S.First();
while (O) {
i = O.IsClass(’ElmLne’);
if (i) {
if (O:c:loading>0.85) O.ShowFullName();
} else {
i = O.IsClass(’ElmTr2’);
if (i) {
if (O:c:loading>0.95) O.ShowFullName();
}
}
O = S.Next();
}
GetClass
string Object.GetClass ()
Returns the class name of the object.
Arguments
none
Return value
The class name of the object
Example
The following example checks to see if two sets start with the same class.
object O1, O2;
O1 = S1.First();
O2 = S2.First();
i = O1.IsClass(O2.GetClass());
if (i) {
output(’Both sets start with the same class’);
}
AddCopy
void Object.AddCopy (set aSet | object aObj [, string | int NM1, ...])
Copies a single object or a set of objects to the target object. “Fold.Copy(aObj)” copies object
‘aObj’ into the target object ‘Fold’, “Fold.Copy(aSet)” copies all objects in ‘aSet’ to “Fold”.
“Fold.Copy(aObj, nm1, nm2, ...)” will copy aObj and rename it to the result of the concatenation
of ‘nm1’, ‘nm2’, etc.
The target object must be able to receive a copy of the objects.
The function
“Fold.Copy(aObj,...)” returns the copy of “aObj”, “Fold.Copy(aSet)” returns “Fold”, when the
copy operation was successful. A “NULL” object is returned otherwise.
Copying a set of objects will respect all internal references between those objects. Copying a
set of lines and their types, for example, will result in a set of copied lines and line types, where
the copied lines will use the copied line types.
Arguments
set aSet (obligatory) : The set of objects to copy
or
object aObj (obligatory) : The object to copy
string | int NM1 (optional) : The first part of the new name
string | int NM2 (optional) : The next part of the new name
...
DPL Manual
44
DIgSILENT PowerFactory
DPL
Return value
void
Example
The following example copies a fuse to a set of cubicles. The copies will be named “Fuse Nr.0”,
“Fuse Nr.1”, etc.
object target, copy;
set Cubs;
Cubs = SEL.GetAll(’StaCubic’);
target = Cubs.First();
while (target) {
copy = target.AddCopy(aFuse, ’Fuse Nr’, n);
if (copy) copy.ShowFullName();
target = Cubs.Next();
}
CreateObject
object Object.CreateObject (string ClassNm [, string | int NM1, ...])
Creates a new object of class ‘ClassNm’ in the target object. The target object must be able
to receive an object of the given class. A fatal DPL error will occur when this is not the case,
causing the running DPL command to exit. “Fold.CreateObject(aClass, nm1, nm2, ...)” will
create a new object of class aClass and names it to the result of the concatenation of ‘nm1’,
‘nm2’, etc.
Arguments
string ClassNm (obligatory) : The class name of the object to create
string | int NM1 (optional) : The first part of the object name
string | int NM2 (optional) : The next part of the object name
...
Return value
The created object, or NULL when no object was created
Example
The following example creates a fuse in a set of cubicles. The new fuses will be named “Fuse
Nr.0”, “Fuse Nr.1”, etc.
object target;
set Cubs;
int n;
Cubs = SEL.GetAll(’StaCubic’);
target = Cubs.First();
n = 0;
while (target) {
target.CreateObject(’RelFuse’, ’Fuse Nr’, n);
target = Cubs.Next();
n+=1;
}
Edit
void Object.Edit ()
Opens the edit dialog of the object. Command objects (like the ComLdf) will have their ‘Execute’ button disabled. The execution of the running DPL script will be halted until the edit dialog
is closed again.
Editing of DPL command objects ComDPL is not allowed.
Arguments
none
Return value
void
DPL Manual
45
DIgSILENT PowerFactory
DPL
Example
The following example opens a line dialog, prior to calculating a loadflow.
MyLine.Edit();
Ldf.Execute();
IsRelevant
int Object.IsRelevant ()
Returns 1 if the object is currently used for calculations. Returns 0 otherwise.
Arguments
none
Return value
0 when not used
Example
The following example checks if a line is used in the calculation.
i = MyLine.IsRelevant();
if (i) {
MyLine.ShowFullName();
}
IsOutOfService
int Object.IsOutOfService ()
Returns 1 if the object is currently out of service. Returns 0 otherwise.
Arguments
none
Return value
0 when not out of service
Example
The following example checks if a line is out of service.
i = MyLine.IsOutOfService();
if (i) {
MyLine.ShowFullName();
}
1.8.4 ComOutage Methods
SetObjs
int ComOutage.SetObjs (set S)
Sets the list of objects according to S.
Arguments
set S (obligatory) : the set of objects
Return value
O on success, 1 on error.
GetObj
object ComOutage.GetObj (int i)
Returns the object at position i in the list of objects.
Arguments
int i (obligatory) : the index is the list.
Return value
The object at position i, or NULL when i is out of bound.
DPL Manual
46
DIgSILENT PowerFactory
DPL
1.8.5 ComSimoutage Methods
Reset
int ComSimoutage.Reset ()
Resets the intermediate results of the outage simulation.
Arguments
none
Return value
O on success, 1 on error.
ExecuteCntcy
int ComSimoutage.ExecuteCntcy (object O)
Executes an (additional) ComSimoutage, without resetting results. The results of the outage
analyses will be added to the intermediate results. Object “O” must be a ComSimoutage object.
Outage definitions in O which have already been analyzed will be ignored.
Arguments
object O (obligatory) : The ComSimoutage object
Return value
O on success, 1 on error.
AddCntcy
int ComSimoutage.AddCntcy (object O, string name)
Executes an (additional) ComOutage, without resetting results. The results of the outage analysis will be added to the intermediate results. Object “O” must be a ComOutage object. If
the outage definition has already been analyzed, it will be ignored. The ComOutage will be
renamed to “name” when “name” is given.
Arguments
object O (obligatory) : The ComOutage object string name (optional) : A name for the outage
Return value
O on success, 1 on error.
SetLimits
int ComSimoutage.SetLimits (double vlmin, double vlmax, double ldmax)
Sets the limits for the outage simulation.
Arguments
double vlmin (obligatory) : The minimum voltage double vlmax (obligatory) : The maximum
voltage double ldmax (obligatory) : The maximum loading
Return value
1 always
Example
The following example analyses all selected outage definitions and adds the results to the
intermediate results.
set s;
object o;
s = SEL.GetAll(’ComOutage’);
o = s.First();
while (o) {
CA.AddCntcy(o);
o = s.Next();
}
DPL Manual
47
DIgSILENT PowerFactory
DPL
1.8.6 IntCase Methods
Activate
int IntCase.Activate ()
Activates the study case. Deactivates other study cases first.
Arguments
none
Return value
0 on success, 1 on error.
Deactivate
int IntCase.Deactivate ()
De-activates the study case.
Arguments
none
Return value
0 on success, 1 on error.
1.8.7 IntPrj Methods
Activate
int IntPrj.Activate ()
Activates the project. Deactivates other projects first.
Arguments
none
Return value
0 on success, 1 on error.
Deactivate
int IntPrj.Deactivate ()
De-activates the project.
Arguments
none
Return value
0 on success, 1 on error.
1.8.8 TypAsm Methods
CalcElParams
int typAsm.CalcElParams ()
Calculates the electrical parameters from the input data.
Arguments
none
1.8.9 TypAsmo Methods
CalcElParams
int typAsmo.CalcElParams ()
Calculates the electrical parameters from the input data.
DPL Manual
48
DIgSILENT PowerFactory
DPL
Arguments
none
1.8.10 Elmfeeder Methods
GetAll
set Elmfeeder.GetAll (int iNested)
Returns a set with all objects belonging to this feeder.
Arguments
int iNested (optional) : In case of nested feeders, all elements will be returned when iNested=1,
otherwise only the objects up to the next feeder will be returned.
Return value
The set of feeder objects.
GetBuses
GetBranches
GetNodesBranches
set Elmfeeder.GetBuses/GetBranches/GetNodesBranches (int iNested)
Returns a set with all Buses and/or Branches belonging to this feeder.
Arguments
int iNested (optional) : In case of nested feeders, all elements will be returned when iNested=1,
otherwise only the objects up to the next feeder will be returned.
Return value
The set of feeder objects.
GetObjs
set Elmfeeder.GetObjs (string ClassNameint iNested)
Returns a set with all objects of class ‘ClassName” which belong to this feeder.
Arguments
int iNested (optional) : In case of nested feeders, all elements will be returned when iNested=1,
otherwise only the objects up to the next feeder will be returned.
Return value
The set of feeder objects.
1.8.11 ComNmink Methods
AddRef
void ComNmink.AddRef ([object O | set S])
Adds shortcuts to the objects to the existing selection
Arguments
One of the following two parameter has to be given
object O (optional) : an object
set S (optional) : a set of objects
Return value
void
Example
The following prepares and executes an outage simulation for all high loaded lines.
PrepOut.Clear();
S = AllRelevant();
O = S.Firstmatch(’ElmLne’);
DPL Manual
49
DIgSILENT PowerFactory
DPL
while (O) {
if (O:c:loading>75) {
PrepOut.AddRef(O);
}
O = S.Nextmatch();
}
PrepOut.Execute();
Clear
void ComNmink.Clear ()
Empties the selection.
Arguments
none
Return value
void
Example
The following example creates a selection of all loads.
PrepOut.Clear();
S = AllRelevant();
O = S.Firstmatch(’ElmLne’);
while (O) {
if (O:c:loading>75) {
PrepOut.AddRef(O);
}
O = S.Nextmatch();
}
PrepOut.Execute();
GetAll
Set ComNmink.GetAll (String ClassName)
Returns all objects which are of the class ‘ClassName’.
Arguments
String ClassName (obligatory) : The object class name.
Return value
The set of objects
Example
The following example writes all three winding transformers in the preparation command to the
output window.
set S;
object O;
S = Prep.GetAll(’ElmTr3’);
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
1.8.12 ElmComp Methods
Slotupd
int ElmComp.Slotupd ()
DPL Manual
50
DIgSILENT PowerFactory
DPL
Performs a slot update for the composite model, to automatically select available models for
the slots.
Arguments
none
Return value
0
Example
1.8.13 ComRes Methods
ExportFullRange
int ComRes.ExportFullRange ()
Executes the export command for the whole data range.
Arguments
none
Return value
1
Example
The following example exports a range of results
object O;
set S;
S = SEL.GetAll(’ElmRes’);
O = S.First();
while (O) {
Export:pResult = O;
Export.ExportFullRange();
O = S.Next();
}
FileNmResNm
int ComRes.FileNmResNm ()
Sets the filename for the data export.
Arguments
none
Return value
1
1.8.14 ComEcho Methods
On
int ComEcho.On ()
Turns on the user interface
ComEcho.On() is obsolete. Use the internal command EchoOn() instead.
Arguments
none
Return value
0 on success
Example
The following example turns off the user interface, calls a subroutine and turns it back on again.
DPL Manual
51
DIgSILENT PowerFactory
DPL
aEcho.Off();
PerformCalculation();
aEcho.On();
Off
int ComEcho.Off ()
Turns off the user interface
ComEcho.Off() is obsolete. Use the internal command EchoOff() instead.
Arguments
none
Return value
0 on success
Example
The following example turns off the user interface, calls a subroutine and turns it back on again.
aEcho.Off();
PerformCalculation();
aEcho.On();
1.8.15 SetTime Methods
Date
void SetTime.Date ()
Sets the current date.
Arguments
none
Return value
none
Example
The following example executes a load flow for 14:30 at the current day (the computer’s system
date).
object Time, Com;
Time = GetCaseObject(’SetTime’);
Com = GetCaseCommand(’ComLdf’);
Time.Date();
Time:hour = 14;
Time:min = 30;
Com.Execute();
Time
void SetTime.Time ()
Sets the current time.
Arguments
none
Return value
none
Example
The following example executes a load flow for the current time and date (the computer’s system
time).
DPL Manual
52
DIgSILENT PowerFactory
DPL
object Time, Com;
Time = GetCaseObject(’SetTime’);
Com = GetCaseCommand(’ComLdf’);
Time.Date();
Time.Time();
Com.Execute();
1.8.16 IntMon Methods
PrintVal
void IntMon.PrintVal ()
Prints the values of the selected variables to the output window.
Arguments
none
Return value
none
PrintAllVal
void IntMon.PrintAllVal ()
Prints a description for all available variables to the output window.
Arguments
none
Return value
none
NVars
int IntMon.NVars ()
returns the number of selected variables or, more exact, the number of lines in the variable
selection text on the second page of the IntMon dialog, which should contain one variable
name per line.
Arguments
none
Return value
The number of selected variables.
Example
GetVar
string IntMon.GetVar (int row)
Returns the variable name on the given row of the variable selection text on the second page
of the IntMon dialog, which should contain one variable name per line.
Arguments
none
Return value
The variable name.
Example
DPL Manual
53
DIgSILENT PowerFactory
DPL
RemoveVar
int IntMon.RemoveVar (string name)
Removes the variable “name” from the list of selected variable names.
Arguments
The variable name.
Return value
1 when the variable name was not found, 0 otherwise.
Example
ClearVars
int IntMon.ClearVars ()
Clears the list of selected variable names.
Arguments
none
Return value
none
Example
AddVar
int IntMon.AddVar (string name)
Appends the variable “name” to the list of selected variable names.
Arguments
The variable name.
Return value
none
Example
1.8.17 SetFilt Methods
Get
Set SetFilt.Get ()
Returns a container with the filtered objects.
Arguments
none
Return value
The set of filtered objects
Example
The following example shows the names of objects filtered by the FiltLongLines.SetFilt filter
set S;
object O;
S = FiltLongLines.Get();
O = S.First();
DPL Manual
54
DIgSILENT PowerFactory
DPL
while (O) {
O.ShowFullName();
O=S.Next();
}
1.8.18 ComDpl Methods
Execute
int ComDpl.Execute (user defined arguments)
Executes an External DPL script as a subroutine.
Arguments
user defined arguments
Return value
0 on success
Example
The following example performs a loadflow and calls the DPL subroutine “CheckVoltages” to
check the voltage conditions.
int err;
err = Ldf.Execute();
if (.not.err) err = CheckVoltages(0.94, 1.05);
if (err) printf(’Voltage conditions are violated’);
1.8.19 IntMat Methods
Get
double IntMat.Get (int row, int col)
Returns the (row, col) value from the matrix. An run-time error will occur when ‘row’ or ‘col’ are
out of range.
Arguments
int row (obligatory) : row in matrix: 1..NRow()
int col (obligatory) : column in matrix: 1..NCol()
Return value
Value in matrix.
Example
The following example multiplies two matrices
int r,c,z,s,s1r,s2c;
double v1,v2,v;
s = M1.NCol();
r = M2.NRow();
if (s<>r) {exit();}
s1r = M1.NRow();
s2c = M2.NCol();
M3.Init(s1r,s2c);
r=1;
while (r<=s1r) {
c=1;
while (c<=s2c) {
z=1; v=0.0;
while (z<=s) {
v1=M1.Get(r,z);
v2=M2.Get(z,c);
v+=v1*v2;
z+=1;
DPL Manual
55
DIgSILENT PowerFactory
DPL
}
M3.Set(r,c,v);
c+=1;
}
r+=1;
}
Set
int IntMat.Set (int row, int col, double V)
Set the value at position (row,col) in the matrix to V. The matrix is automatically resized if
necessary.
Arguments
int row (obligatory) : row number: 1..NRows()
int col (obligatory) : col number: 1..NCols() double Vj (obligatory) : value
Return value
0 on success
Example
See “IntMat.Get” in 1.8.19, page 55 for an example
Init
int IntMat.Init (int NRows, int NCols)
Initializes the matrix. The size is set to (NRows, NCols), all values are set to 0.
Arguments
int NRows (obligatory) : number of rows
int NCols (obligatory) : number of columns
Return value
0 on success
Example
See “IntMat.Get” in 1.8.19, page 55 for an example
Resize
int IntMat.Resize (int NRows, int NCols)
Resizes the matrix. Existing values will not be changed. Added values will be set to 0.
Arguments
int NRows (obligatory) : number of rows
int NCols (obligatory) : number of columns
Return value
0 on success
Example
The following example gets a value from the matrix, possibly resizing it first.
int Nc,Nr,x,y;
Nr = Mat.NRows();
Nc = Mat.NCols();
x=5;y=3;
if ({x>Nr}.or.{y>Nc}) {
Mat.Resize(x,y);
}
v = Mat.Get(x,y);
NRow
int IntMat.NRow ()
DPL Manual
56
DIgSILENT PowerFactory
DPL
Returns the number of rows in the matrix. The function “NRow()” replaces the obsolete function
“SizeX()”.
Arguments
none
Return value
The number of rows
Example
See “IntMat.Get” in 1.8.19, page 55 for an example
NCol
int IntMat.NCol ()
Returns the number of columns in the matrix. The function “NCol()” replaces the obsolete
function “SizeY()”.
Arguments
none
Return value
The number of columns
Example
See “IntMat.Get” in 1.8.19, page 55 for an example
RowLbl
int IntMat.RowLbl (String S, int R)
Sets the label of the R’th row.
Arguments
String S (obligatory) : Labelstring
int R (obligatory) : Number of the row
Return value
0 on success
Example
The following example labels some rows.
Mat.RowLbl(’overloaded’,1);
Mat.RowLbl(’overvoltage’,2);
Mat.RowLbl(’undervoltage’,3);
ColLbl
int IntMat.ColLbl (String S, int C)
Sets the label of the C’th column.
Arguments
String S (obligatory) : Labelstring
int C (obligatory) : Number of the column
Return value
0 on success
Example
The following example labels some columns.
Mat.ColLbl(’transformers’,1);
Mat.ColLbl(’lines’,2);
Mat.ColLbl(’busbars’,3);
1.8.20 IntVec Methods
Get
DPL Manual
57
DIgSILENT PowerFactory
DPL
double IntVec.Get (int i)
Returns the value at index i.
Arguments
int i (obligatory) : Vector index.
Return value
Value at index i.
Example
The following example adds two vectors.
int i,j;
double v1,v2;
i = Vec1.Size();
j = Vec2.Size();
if (i<>j) {
output(’invalid operation’);
exit();
}
Vec3.Init(i);
i=1;
while (i<=j) {
v1 = Vec1.Get(i);
v2 = Vec2.Get(i);
Vec3.Set(i,v1+v2);
i+=1;
}
Set
double IntVec.Set (int i, double V)
Sets the value at index i to V. Valid indexes are in [1, IntVec.Size()]
Arguments
int i (obligatory) : Vector index.
double V (obligatory) : The value to set.
Return value
0 on success
Example
See “IntVec.Get” in 1.8.20, page 57 for an example
Init
int IntVec.Init (int Size)
Initializes the vector. Sets the length to Size and all values to 0.
Arguments
int Size (obligatory) : The initial size.
Return value
0 on success
Example
See “IntVec.Get” in 1.8.20, page 57 for an example
Resize
int IntVec.Resize (int Size)
Resizes the vector. Added values are set to 0.0.
Arguments
none
DPL Manual
58
DIgSILENT PowerFactory
DPL
Return value
0 on success
Example
The following example adds a value to a dynamically scaled vector.
int i,s;
i = 5;
s = Vec.Size();
if (i>s) {
Vec.Resize(i);
}
Vec.Set(i,V);
Size
int IntVec.Size ()
Returns the size of the vector.
Arguments
none
Return value
The size of the vector
Example
See “IntVec.Get” in 1.8.20, page 57 for an example
1.8.21 ElmCoup Methods
Close
int ElmCoup.Close ()
Closes the buscoupler
Arguments
none
Return value
0 on success
Example
The following example gathers all open couplers before closing them.
int opn;
set S, So;
object O;
S = Couplers.AllElm();
O = S.First();
while (O) {
opn = O.IsOpen();
if (opn) {
O.Close();
So.Add(O);
};
}
Open
int ElmCoup.Open ()
Opens the buscoupler
Arguments
none
DPL Manual
59
DIgSILENT PowerFactory
DPL
Return value
0 on success
Example
The following example gathers all closed couplers before opening them.
int cl;
set S, Sc;
object O;
S = Couplers.AllElm();
O = S.First();
while (O) {
cl = O.IsClosed();
if (opn) {
O.Open();
Sc.Add(O);
};
}
IsOpen
int ElmCoup.IsOpen ()
Returns 1 when the coupler is open.
Arguments
none
Return value
1 when open, 0 when closed
Example
See “ElmCoup.Close” in 1.8.21, page 59 for an example
IsClosed
int ElmCoup.IsClosed ()
Returns 1 when the coupler is closed.
Arguments
none
Return value
1 when closed, 0 when open
Example
See “ElmCoup.Open” in 1.8.21, page 59 for an example
1.8.22 ElmLne Methods
HasRoutes
int ElmLne.HasRoutes ()
Returns if the line is subdivided into routes.
Arguments
none
Return value
0 when the line is a single line, 1 when it is subdivided into routes.
Example
The following example reports all lines with routes.
set S; object O; int i;
S = AllRelevant();
O = S.Firstmatch(’ElmLne’);
DPL Manual
60
DIgSILENT PowerFactory
DPL
while (O) {
i = O.HasRoutes();
if (i) O.ShowFullName();
O = S.Nextmatch();
}
HasRoutesOrSec
int ElmLne.HasRoutesOrSec ()
Returns if the line is subdivided into routes or sections.
Arguments
none
Return value
0 when the line is a single line, 1 when it is subdivided into routes, 2 when into sections.
Example
The following example reports all lines with sections.
set S; object O; int i;
S = AllRelevant();
O = S.Firstmatch(’ElmLne’);
while (O) {
i = O.HasRoutesOrSec();
if (i=2) O.ShowFullName();
O = S.Nextmatch();
}
GetType
int ElmLne.GetType ()
Returns the line type object.
Arguments
none
Return value
The TypLne object
Example
The following example reports all ‘untyped’ lines
set S;
object O, T;
S = AllRelevant();
O = S.Firstmatch(’ElmLne’);
while (O) {
T = O.GetType();
if (T=0) {
O.ShowFullName();
}
O = S.Nextmatch();
}
IsCable
int ElmLne.IsCable ()
Returns if the line is a cable.
Arguments
none
Return value
DPL Manual
61
DIgSILENT PowerFactory
DPL
1 when the line is a cable, otherwise 0.
Example
The following example reports the loading of all cables.
set S;
object O;
int i;
S = AllRelevant();
O = S.Firstmatch(’ElmLne’);
while (O) {
i = O.IsCable();
if (i) {
Write(’# : #.## $N, @ACC(1):loc_name, @ACC(1):c:loading, O);
}
O = S.Nextmatch();
}
IsNetCoupling
int ElmLne.IsNetCoupling ()
Returns if the line connects two grids.
Arguments
none
Return value
1 when the line is a coupler, otherwise 0.
Example
The following example reports all the loading of all couplers
set S;
object O;
int i;
S = AllRelevant();
O = S.Firstmatch(’ElmLne’);
while (O) {
i = O.IsNetCoupling();
if (i) {
Write(’# : #.## $N, @ACC(1):loc_name, @ACC(1):c:loading, O);
}
O = S.Nextmatch();
}
SetCorr
int ElmLne.SetCorr ()
Sets the correction factor of the line, according to IEC364-5-523.
Arguments
none
Return value
0 on success, 1 on error;
Example
The following example sets a correction factor.
BuriedLine.SetCorr();
CreateFeederWithRoutes
DPL Manual
62
DIgSILENT PowerFactory
DPL
int ElmLne.CreateFeederWithRoutes (double dis,double rem,object O[int sw0,int sw1])
Creates a new feeder in the line by splitting the line in 2 routes and inserting a terminal.
Arguments
double dis (obligatory) :
double rem (obligatory) :
object O (obligatory) : A branch object that is to be connected at the inserted terminal.
int sw0 (optional) : when true, a switch is inserted on the one side
int sw1 (optional) : when true, a switch is inserted on the other side
Return value
0 on success, 1 on error;
Example
1.8.23 ElmLneroute Methods
IsCable
int ElmLneroute.IsCable ()
Returns if the route is a cable.
Arguments
none
Return value
1 when a cable, otherwise 0.
Example
The following example reports all cable routes.
set S; object O; int i;
S = AllRelevant();
O = S.Firstmatch(’ElmLneroute’);
while (O) {
i = O.IsCable();
if (i) O.ShowFullName();
O = S.Nextmatch();
}
HasSections
int ElmLneroute.HasSections ()
Returns if the line route is subdivided into sections.
Arguments
none
Return value
1 when subdivided sections, 0 otherwise
Example
The following example reports all lines routes with sections.
set S; object O; int i;
S = AllRelevant();
O = S.Firstmatch(’ElmLneroute’);
while (O) {
i = O.HasSections();
if (i) O.ShowFullName();
O = S.Nextmatch();
}
DPL Manual
63
DIgSILENT PowerFactory
DPL
1.8.24 TypLne Methods
IsCable
int TypLne.IsCable ()
Returns if the line type is a cable type.
Arguments
none
Return value
1 when the line type is a cable type, otherwise 0.
Example
The following example reports all cable types.
set S; object O; int i;
S = AllRelevant();
O = S.Firstmatch(’TypLne’);
while (O) {
i = O.IsCable();
if (i) O.ShowFullName();
O = S.Nextmatch();
}
SetNomCurr
int ElmLne.SetNomCurr ()
Sets the nominal current of the line type, according to IEC364-5-523.
Arguments
none
Return value
0 on success, 1 on error.
Example
The following example sets the correction factor.
BuriedLineType.SetNomCurr();
1.8.25 ElmRes Methods
Init
int ElmRes.Init ()
Initializes the result object. This is required for all result files that are not stored in the DPL
command object.
Arguments
none
Return value
0 on success
Example
The following example initializes the result object.
Res.Init();
Clear
int ElmRes.Clear ()
Clears the result object.
Arguments
none
DPL Manual
64
DIgSILENT PowerFactory
DPL
Return value
0 on success
Example
The following example clears the result object.
Res.Clear();
Write
int ElmRes.Write ()
Writes the current results to the result object.
Arguments
none
Return value
0 on success
Example
The following example performs load flows for a number of load levels and writes the results to
the result object
double P;
double i;
P = LoadMin;
i = 1;
while ({P<LoadMax}.and.{i}) {
i = Ldf.Execute();
if (i) {
Res.Write();
P += LoadStep;
}
}
Draw
int ElmRes.Draw ()
Updates all graphics that display values from the result object.
Arguments
none
Return value
0 on success
Example
The following example updates the graphics every 10 steps to save time and yet follow the
results while calculating
double i,n;
Ld:pini = LoadMin;
i = 1;
n = 0;
while ({Ld:pini<LoadMax}.and.{i}) {
i = Ldf.Execute();
if (i) {
Res.Write();
n += 1;
Ld:pini += LoadStep;
}
if (n>9) {
Res.Write();
n = 0;
DPL Manual
65
DIgSILENT PowerFactory
DPL
}
}
WriteDraw
int ElmRes.WriteDraw ()
Writes to and displays the result objects.
Arguments
none
Return value
0 on success
Example
The following example performs load flows for a number of load levels and writes the results to
the result object
double P;
double i;
P = LoadMin;
i = 1;
while ({P<LoadMax}.and.{i}) {
i = Ldf.Execute();
if (i) {
Res.WriteDraw();
P += LoadStep;
}
}
SetAsDefault
void ElmRes.SetAsDefault ()
Sets this results object as the default results object.
Arguments
none
Return value
none
Example
AddVars
void ElmRes.AddVars (object O, string v1 [,string v2,...])
Adds variables to the list of monitored variables for the Result object.
Arguments
object O (obligatory) : an object.
string v1 (obligatory) : variable name for object O.
string v2..v9 (optional) : optional further variables names for object O.
Return value
none
Example
object Res; Res = MyResults(); Res.AddVars(MyLine,’m:Ikss:busshc’,’m:I:busshc’);
GetObj
object ElmRes.GetObj (int index)
DPL Manual
66
DIgSILENT PowerFactory
DPL
Returns the objects used in the result file. Positive index means objects for which parameters
are being monitored (i.e. column objects). Negative index means objects which occur in written
result rows as values.
Arguments
int index (obligatory) : index of the object.
Return value
the object, when found.
Example
1.8.26 ElmZone Methods
GetAll
set ElmZone.GetAll ()
Returns all objects which belong to this zone.
Arguments
none
Return value
The set of objects
GetBuses
set ElmZone.GetBuses ()
Returns all buses which belong to this zone.
Arguments
none
Return value
The set of objects
GetBranches
set ElmZone.GetBranches ()
Returns all branches which belong to this zone.
Arguments
none
Return value
The set of objects
GetObjs
set ElmZone.GetObjs (string classname)
Returns all objects of the given class which belong to this zone.
Arguments
string classname (obligatory) : name of the class.
Return value
The set of objects
1.8.27 ComRel3 Methods
Execute
int ComRel3.Execute ()
Executes the Level 3 reliability assessment calculations
Arguments
DPL Manual
67
DIgSILENT PowerFactory
DPL
none
Return value
0 on success
Example
The following example executes a ComRel3 Command named ‘Rel3’
Rel3.Execute();
1.8.28 ComInc Methods
Execute
int ComInc.Execute ()
Executes a calculation of initial values.
Arguments
none
Return value
0 on success
Example
The following example executes the ComInc command named ‘Inc’
Inc.Execute();
1.8.29 ComLdf Methods
Execute
int ComLdf.Execute ()
Execute a load flow calculation
Arguments
none
Return value
0 on success
Example
The following example executes the ComLdf command name ‘Ldf’
Ldf.Execute();
1.8.30 ComShc Methods
Execute
int ComShc.Execute ()
Executes a short-circuit calculation
Arguments
none
Return value
0 on success
Example
The following example execute the ComShc command named ‘Shc’
Shc.Execute();
DPL Manual
68
DIgSILENT PowerFactory
DPL
1.8.31 StaSwitch Methods
Close
int StaSwitch.Close ()
Closes the switch
Arguments
none
Return value
0 on success
Example
The following example gathers all open switches before closing them.
int opn;
set S, So;
object O;
S = Switches.AllElm();
O = S.First();
while (O) {
opn = O.IsOpen();
if (opn) {
O.Close();
So.Add(O);
};
}
Open
int StaSwitch.Open ()
Arguments
none
Return value
0 on success
Example
The following example gathers all closed switches before opening them.
int cl;
set S, Sc;
object O;
S = Couplers.AllElm();
O = S.First();
while (O) {
cl = O.IsClosed();
if (opn) {
O.Open();
Sc.Add(O);
};
}
IsOpen
int StaSwitch.IsOpen ()
Checks if the switch is open.
Arguments
none
Return value
DPL Manual
69
DIgSILENT PowerFactory
DPL
1 when open, 0 when closed
Example
See “StaSwitch.Close” in 1.8.31, page 69 for an example
IsClosed
int StaSwitch.IsClosed ()
Checks if the switch is closed.
Arguments
none
Return value
1 when closed, 0 when open
Example
See “StaSwitch.Open” in 1.8.31, page 69 for an example
1.8.32 SetFeeder Methods
GetAll
Set SetFeeder.GetAll ()
Returns all objects in the feeder.
Arguments
none
Return value
The set with all objects
Example
The following example gets all feeder objects
set S;
S = Feeder1.GetALL();
GetBuses
Set SetFeeder.GetBuses ()
Returns all busbars and terminals in the feeder.
Arguments
none
Return value
The set with all busbars and terminals
Example
The following example gets all feeder bars
set S;
S = Feeder1.GetBusses();
GetBranches
Set SetFeeder.GetBranches ()
Returns all branches in a feeder.
Arguments
none
Return value
The set with all branches
Example
The following example gets all feeder branches
DPL Manual
70
DIgSILENT PowerFactory
DPL
set S;
S 0 Feeder1.GetBranches();
1.8.33 SetPath Methods
GetAll
Set SetPath.GetAll ()
Returns all objects in the path definition.
Arguments
none
Return value
The set of objects
Example
The following example writes all objects in the path definition to the output window.
set S;
object O;
S = aPath.GetAll();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
GetBusses
Set SetPath.GetBusses ()
Returns all busbars and terminals in the path definition.
Arguments
none
Return value
The set of objects
Example
The following example writes all busbars and terminals in the path definition to the output
window.
set S;
object O;
S = aPath.GetBusses();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
GetBranches
Set SetPath.GetBranches ()
Returns all branches in the path definition.
Arguments
none
Return value
The set of objects
Example
The following example writes all branches in the path definition to the output window.
DPL Manual
71
DIgSILENT PowerFactory
DPL
set S;
object O;
S = aPath.GetBranches();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
AllBreakers
Set SetPath.AllBreakers ()
Returns all breakers in the path definition.
Arguments
none
Return value
The set of objects
Example
The following example writes all breakers in the path definition to the output window.
set S;
object O;
S = aPath.AllBreakers();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
AllClosedBreakers
Set SetPath.AllClosedBreakers ()
Returns all closed breakers in the path definition.
Arguments
none
Return value
The set of objects
Example
The following example writes all closed breakers in the path definition to the output window.
set S;
object O;
S = aPath.AllClosedBreakers();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
AllOpenBreakers
Set SetPath.AllOpenBreakers ()
Returns all open breakers in the path definition.
Arguments
none
Return value
DPL Manual
72
DIgSILENT PowerFactory
DPL
The set of objects
Example
The following example writes all open breakers in the path definition to the output window.
set S;
object O;
S = aPath.AllOpenBreakers();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
1.8.34 SetSelect Methods
AddRef
void SetSelect.AddRef ([object O | set S])
Adds a reference to the objects to the existing selection
Arguments
One of the following two parameter has to be given
object O (optional) : an object
set S (optional) : a set of objects
Return value
void
Example
The following example adds all loads and lines from the general DPL selection to the selection
“MySelection”.
set S;
S = SEL.AllLines();
MySelection.AddRef(S);
S = SEL.AllLoads();
MySelection.AddRef(S);
Clear
void SetSelect.Clear ()
Empties the selection.
Arguments
none
Return value
void
Example
The following example creates a selection of all loads in the general DPL selection.
set S;
S = SEL.AllLines();
MySelection.Clear();
MySelection.AddRef(S);
AllElm
Set SetSelect.AllElm ()
Returns all elements (Elm*) in the selection.
Arguments
none
DPL Manual
73
DIgSILENT PowerFactory
DPL
Return value
The set of objects
Example
The following example writes all objects in the general DPL selection to the output window.
set S;
object O;
S = SEL.AllElm();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
AllLines
Set SetSelect.AllLines ()
Returns all lines and line routes in the selection.
Arguments
none
Return value
The set of objects
Example
The following example writes all lines and line routes in the general DPL selection to the output
window.
set S;
object O;
S = SEL.AllLines();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
AllBars
Set SetSelect.AllBars ()
Returns all busbars and terminals in the selection.
Arguments
none
Return value
The set of objects
Example
The following example writes all bars in the general DPL selection to the output window.
set S;
object O;
S = SEL.AllBars();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
DPL Manual
74
DIgSILENT PowerFactory
DPL
AllLoads
Set SetSelect.AllLoads ()
Returns all loads in the selection.
Arguments
none
Return value
The set of objects
Example
The following example writes all loads in the general DPL selection to the output window.
set S;
object O;
S = SEL.AllLoads();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
AllAsm
Set SetSelect.AllAsm ()
Returns all asynchronous machines in the selection.
Arguments
none
Return value
The set of objects
Example
The following example writes all asynchronous machines in the general DPL selection to the
output window.
set S;
object O;
S = SEL.AllAsm();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
AllSym
Set SetSelect.AllSym ()
Returns all synchronous machines in the selection.
Arguments
none
Return value
The set of objects
Example
The following example writes all synchronous machines in the general DPL selection to the
output window.
set S;
object O;
S = SEL.AllSym();
O = S.First();
while (O) {
DPL Manual
75
DIgSILENT PowerFactory
DPL
O.ShowFullName();
O = S.Next();
}
AllTypLne
Set SetSelect.AllTypLne ()
Returns all line types in the selection.
Arguments
none
Return value
The set of objects
Example
The following example writes all line types in the general DPL selection to the output window.
set S;
object O;
S = SEL.AllTypLne();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
All
Set SetSelect.All ()
Returns all objects in the selection.
Arguments
none
Return value
The set of objects
Example
The following example writes objects in the general DPL selection to the output window.
set S;
object O;
S = SEL.All();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
GetAll
Set SetSelect.GetAll (String ClassName)
Returns all objects in the selection which are of the class ‘ClassName’.
Arguments
String ClassName (obligatory) : The object class name.
Return value
The set of objects
Example
The following example writes all three winding transformers in the general DPL selection to the
output window.
DPL Manual
76
DIgSILENT PowerFactory
DPL
set S;
object O;
S = SEL.GetAll(’ElmTr3’);
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
AllBreakers
Set SetSelect.AllBreakers ()
Returns all breakers in the selection.
Arguments
none
Return value
The set of objects
Example
The following example writes all breakers in the general DPL selection to the output window.
set S;
object O;
S = SEL.AllBreakers();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
AllClosedBreakers
Set SetSelect.AllClosedBreakers ()
Returns all closed breakers in the selection.
Arguments
none
Return value
The set of objects
Example
The following example writes all closed breakers in the general DPL selection to the output
window.
set S;
object O;
S = SEL.AllClosedBreakers();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
AllOpenBreakers
Set SetSelect.AllOpenBreakers ()
Returns all open breakers in the selection.
Arguments
none
Return value
DPL Manual
77
DIgSILENT PowerFactory
DPL
The set of objects
Example
The following example writes all open breakers in the general DPL selection to the output
window.
set S;
object O;
S = SEL.AllOpenBreakers();
O = S.First();
while (O) {
O.ShowFullName();
O = S.Next();
}
1.8.35 IntForm Methods
SetText
int IntForm.SetText (String Text)
Sets the format text of a report form.
Arguments
String Text (obligatory) : The format text string
Return value
0 on success
Example
The following example sets a format string and writes the report for two sets
set SLines,SLoads;
...
fill SLines and SLoads
...
OvlReport.SetText(’
| Loading of lines: |$H
$LOOP,_EXTERNAL
|#
#.# |$N,loc_name,loading
$END
’);
OvlReport.WriteOut(SLines, SLoads);
See also IntForm.WriteOut, page 78
WriteOut
int IntForm.WriteOut (Set ListSet, Set PoolSet)
Write the report to the output window.
The report form object will write a report to the output window, based on the format text, for the
objects in the ListSet and the PoolSet. The ListSet is used in the _EXTERNAL macro. All format
lines between the $LOOP,_EXTERNAL and the $END macro’s will be written for each object in the
Listset, which is therefore called the ‘sequential set’. In the format text itself, objects from the
PoolSet may be referenced directly by the “ACC(x)” macro, which is replaced by the x’th object in
the PoolSet. The PoolSet is therefore called the ‘random access set’. The ListSet or PoolSet may
be empty.
The command object that is normally reached by the macro “DEF” in report forms will always
return the main DPL command that is running at the moment, even when the ‘WriteOut’ call is
made in a DPL subscript.
Arguments
DPL Manual
78
DIgSILENT PowerFactory
DPL
Set ListSet (obligatory) : The sequential set of objects
Set PoolSet (optional) : The random access set of objects
Return value
0 on success
Example
The following example reports the loading of a list of objects for a certain load condition. The
objects for the loading are sequentially listed. The load conditions are reported for a special set
of loads, which are given as a pool of objects.
set SLines,SLoads;
...
fill SLines and SLoads
...
OvlReport.WriteOut(SLines, SLoads);
If OvlReport has the following format string:
---------------------$H,
| command : #
|$H,DEF:loc_name
| Load settings:
|$H
| #
#.# |$H,ACC(2):loc_name,ACC(2):plini
| #
#.# |$H,ACC(3):loc_name,ACC(3):plini
---------------------$H,
| Loading of lines: |$H
$LOOP,_EXTERNAL
|#
#.# |$N,loc_name,loading
$END
---------------------$F,
the following report could be the result:
--------------------| command : FindWL |
| Load settings:
|
| Ld12a
3.43 |
| Ld14b
2.52 |
--------------------| Loading of lines: |
| Ln1
95.6 |
| Ln2
92.1 |
| Ln3
90.4 |
| Ln4
85.3 |
| Ln5
84.7 |
| Ln6
84.2 |
| Ln7
82.6 |
| Ln8
62.5 |
--------------------See also IntForm.SetText, page 78
1.8.36 SetDesktop Methods
Show
int SetDesktop.Show ([string name—object O])
Shows the page with the same name as ‘O” or the page with name “name” in the Graphics
Board. The object “O” is typically a ViPage object but, as only its name is used, it may be any
other type of object.
Arguments
DPL Manual
79
DIgSILENT PowerFactory
DPL
string name (obligatory) : Name of graphics page.
object O (optional) : An object.
Return value
0 on success, 1 on error.
Example
The following example activates all pages in the graphics board one by one and exports them
as WMF pictures.
object GrBr,Pg;
set Pgs;
int n;
GrBrd = GetGraphBoard();
if (GrBrd) {
Pgs = GrBrd.GetContents();
Pg = Pgs.First();
while (Pg) {
GrBrd.Show(Pg);
GrBrd.WriteWMF(sprintf(’c:\\mydoc\\%s%d’, n, Pg:loc_name));
Pg = VI.Next();
}
}
WriteWMF
void SetDesktop.WriteWMF (string filename)
Exports the currently open graphic in the graphics board to a WMF picture.
Arguments
string name (obligatory) : Filename without extension.
Return value
none.
Example
See “SetDeskTop.Show()” in 1.8.36, page 79
GetPage
object SetDesktop.GetPage (string name, int create)
Searches, activates and returns a graphics page in the currently open Graphics Board. If
“create” is true, then a new ViPage will be created added to the graphics board when no page
with the name was found.
Arguments
string name (obligatory) : Name of the page.
int create=1 (optional) : create ¿ 0 =¿ create panel if not exists.
Return value
Virtual Instrument Panel (SetVipage)
Example
The following example looks for the Virtual Instrument Panels named Voltage, Current and
Power in the Graphics Board currently opened. The pages are created if they do not exist.
object aGrf;
object aPageV;
object aPageC;
object aPageP;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Search or create Virtual Instrument Panels
aPageV=aGrf.GetPage(’Voltage’,1);
aPageC=aGrf.GetPage(’Current’,1);
DPL Manual
80
DIgSILENT PowerFactory
DPL
aPageP=aGrf.GetPage(’Power’,1);
}
SetResults
void SetDesktop.SetResults (object res)
Sets default Results (ElmRes) of Graphics Board.
Arguments
object res (obligatory) : Results to set (ElmRes) or NULL to reset.
Return value
none
Example
The following example looks for an opened Graphics Board and sets its default results to the
results object named ’Results’.
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Set default results object
aGrf.SetResults(Results);
}
SetXVar
void SetDesktop.SetXVar (object obj, string varname)
Sets x-axis variable. If obj and varname are empty the default x-axis variable (time) is set.
Arguments
object obj (optional) : x-axis object
string varname (optional) : variable of obj
Return value
none
Example
The following examples look for an opened Graphics Board and set its x-axis variable. The first
example sets a user defined x-axis variable. The second one sets the default x-axis (time).
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Set user defined x-axis variable
aGrf.SetXVar(line,’m:U1:bus1’);
}
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Set default x-axis variable (time)
aGrf.SetXVar();
}
SetScaleX
void SetDesktop.SetScaleX (double min, double max, int log)
DPL Manual
81
DIgSILENT PowerFactory
DPL
Sets scale of x-axis. Invalid arguments like neg. limits for log. scale are not set. No arguments
=¿ automatic scaling.
Arguments
double min (optional) : Minimum of x-scale.
double max (optional) : Maximum of x-scale.
int log (optional) : ¿ 0 =¿ x-scale is logarithmic.
Return value
none
Example
The following examples look for an opened Graphics Board and set its x-axis scale. There are
three different examples. 1. Example: Scale x-axis automatically 2. Example: Set minimum to
0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to 1000. Changes to a
log. scale
! Scale x-axis automatically
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Scale automatically
aGrf.SetScaleX();
}
! Set minimum and maximum without changing map mode
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Set minimum and maximum
aGrf.SetScaleX(2,10);
}
! Set minimum and maximum, change to log. scale
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Set minimum and maximum
aGrf.SetScaleX(1,1000,1);
}
SetAutoScaleX
void SetDesktop.SetAutoScaleX (int mode)
Sets the automatic scaling mode of the x-scale.
Arguments
int mode (obligatory) : Possible values: 0 never, 1 after simulation, 2 during simulation
Return value
none
Example
The following example looks for an opened Graphics Board and sets its auto scale mode to off.
! Set autoscale mode to off
object aGrf;
DPL Manual
82
DIgSILENT PowerFactory
DPL
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Turn off automatic scaling of x-scale
aGrf.SetAutoScaleX(0);
}
SetAdaptX
void SetDesktop.SetAdaptX (int mode, double trigger)
Sets the adapt scale option of the x-scale.
Arguments
int mode (obligatory) : Possible values: 0 off, 1 on
double trigger (optional) : Trigger value, unused if mode is off or empty.
Return value
none
Example
The following example looks for an opened Graphics Board and sets its adapt scale option.
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Turn on adapt scale, use a trigger value of 3
aGrf.SetAdaptX(1,3);
! Turn off adapt scale
aGrf.SetAdaptX(0,3);
! Turn on adapt scale again, do not change the trigger value
aGrf.SetAdaptX(1);
}
1.8.37 SetVipage Methods
GetVI
object SetVipage.GetVI (string name, string class, int create)
Searches for a virtual instruments on the Virtual Instrument Panel.
Arguments
string name (obligatory) : Name of Virtual Instrument
string class=’VisPlot’ (optional) : classname of Virtual Instrument.
int create=1 (optional) : create ¿ 0 =¿ create panel if not exists.
Return value
Virtual Instrument.
Example
The following example looks for a Plot (VisPlot) named RST on a Virtual Instrument Panel. The
plot is created if it was not found.
object aGrf;
object aPage;
object aPlot;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get plot named RST. Create the plot if not exists
DPL Manual
83
DIgSILENT PowerFactory
DPL
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
}
}
SetStyle
void SetVipage.SetStyle (string name)
Sets style folder of Virtual Instrument Panel.
Arguments
string name (obligatory) : Name of style.
Return value
none
Example
The following example looks for a Virtual Instrument Panel named Voltage and sets its style to
’Paper’.
object aGrf;
object aPage;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Set style named Paper
aPage.SetStyle(’Paper’);
}
}
SetTile
void SetVipage.SetTile (int tile)
Rearranges the Virtual Instruments.
Arguments
int tile=1 (optional) : tile ¿ 0 =¿ tile Virtual Instruments, tile=0 =¿ arrange them horizontally.
Return value
none
Example
The following example looks for a Virtual Instrument Panel named Voltage and rearranges the
Virtual Instrument.
object aGrf;
object aPage;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Arrange the VIs horizontally
aPage.SetTile(0);
! Tile VIs (default input parameter is 1)
aPage.SetTile();
}
}
DPL Manual
84
DIgSILENT PowerFactory
DPL
SetResults
void SetVipage.SetResults (object res)
Sets default Results (ElmRes) of Virtual Instrument Panel.
Arguments
object res (obligatory) : Results to set (ElmRes) or NULL to reset.
Return value
none
Example
The following example looks for a Virtual Instrument Panel named Voltage and resets its default
results.
object aGrf;
object aPage;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Set default results on page
aPage.SetResults(NULL);
}
}
SetXVar
void SetVipage.SetXVar (object obj, string varname)
Sets x-axis variable. If obj and varname are empty the default x-axis variable (time) is set.
Arguments
object obj (optional) : x-axis object
string varname (optional) : variable of obj
Return value
none
Example
The following examples look for a Virtual Instrument Panel named Voltage and set the x-axis
variable. The first example sets a user defined x-axis variable of the Virtual Instrument Panel.
The second one sets the default x-axis (time).
object aGrf;
object aPage;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Set x-scale from 100 to 120
aPage.SetScaleX(100,120);
! Set x-scale variable
aPage.SetXVar(line,’m:U1:bus1’);
}
}
object aGrf;
object aPage;
DPL Manual
85
DIgSILENT PowerFactory
DPL
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Set x-scale from 100 to 120
aPage.SetScaleX(100,120);
! Set default x-scale variable (time)
aPage.SetXVar();
}
}
SetScaleX
void SetVipage.SetScaleX (double min, double max, int log)
Sets scale of x-axis. Invalid arguments like negative limits for logarithmic scale are not set. No
input arguments =¿ automatic scaling.
Arguments
double min (optional) : Minimum of x-scale.
double max (optional) : Maximum of x-scale.
int log (optional) : ¿ 0 =¿ x-scale is logarithmic.
Return value
none
Example
The following examples look for a Virtual Instrument Panel named Voltage and set its x-axis
scale. There are three different examples. 1. Example: Scale x-scale automatically. 2. Example: Set minimum to 0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to
1000. Changes to a log. scale
! Scale x-scale automatically.
object aPage;
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Automatic scaling
aPage.SetScaleX();
}
}
! Set minimum and maximum without changing map mode
object aPage;
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Set minimum and maximum
aPage.SetScaleX(0,20);
DPL Manual
86
DIgSILENT PowerFactory
DPL
}
}
! Set minimum and maximum, set map mode to log.
object aPage;
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Set minimum and maximum, change to log. scale
aPage.SetScaleX(1,1000,1);
}
}
SetDefScaleX
void SetVipage.SetDefScaleX ()
Sets default scale of x-axis (SetDesktop).
Arguments
none
Return value
none
Example
The following example looks for a Virtual Instrument Panel named Voltage and resets the option
’Use local x-Axis’ to 0. After that the x-scale used is the Graphics Board (SetDesktop).
! Set default x-scale
object aPage;
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Reset option ’Use local x-Axis’
aPage.SetDefScaleX();
}
}
SetAutoScaleX
void SetVipage.SetAutoScaleX (int mode)
Sets automatic scaling mode of the x-scale for local scales.
Arguments
int mode (obligatory) : Possible values: 0 never, 1 after simulation, 2 during simulation
Return value
none
Example
The following examples look for a Virtual Instrument Panel named Voltage and change its
auto scale mode. The first example works fine, the second one generates an error message
because the x-scale is unused.
DPL Manual
87
DIgSILENT PowerFactory
DPL
! Set autoscale mode Off
object aGrf;
object aPage;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Set limits to change x-scale of page to used scale
aPage.SetScaleX(0,10);
! Turn off automatic scaling of x-scale
aPage.SetAutoScaleX(0);
}
}
! Try to set autoscale mode to online
object aGrf;
object aPage;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Reset option ’Use local x-Axis’ of Virtual Instrument Panel
aPage.SetDefScaleX();
! Try to set automatic scaling of x-scale to Online
aPage.SetAutoScaleX(2);
}
}
SetAdaptX
void SetVipage.SetAdaptX (int mode, double trigger)
Sets the adapt scale option of the x-scale for local scales.
Arguments
int mode (obligatory) : Possible values: 0 off, 1 on
double trigger (optional) : Trigger value, unused if mode is off or empty
Return value
none
Example
The following examples look for a Virtual Instrument Panel named Voltage and sets its adapt
scale option. The first example works fine, the second one generates an error message because the x-scale is unused.
! Modify adapt scale option of Virtual Instrument Panel
object aPage;
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
DPL Manual
88
DIgSILENT PowerFactory
DPL
! Set x-scale limits to set option ’Use local x-Axis’
aPage.SetScaleX(0,20);
! Turn on adapt scale, use a trigger value of 3
aPage.SetAdaptX(1,3);
! Turn off adapt scale
aPage.SetAdaptX(0,3);
! Turn on adapt scale again, do not change the trigger value
aPage.SetAdaptX(1);
}
}
! Try to turn on adapt scale
object aPage;
object aGrf;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Reset option ’Use local x-Axis’ of Virtual Instrument Panel
aPage.SetDefScaleX();
! Try to turn on adapt scale, use a trigger value of 3
! Leads to error message because scale is not local
aPage.SetAdaptX(1,3);
}
}
GetScaleObjX
object SetVipage.GetScaleObjX ()
Returns used object defining x-scale. The returned object is either the Virtual Instrument Panel
itself or the Graphics Board.
Arguments
none
Return value
Object defining the x-scale.
Example
The following examples look for a Virtual Instrument Panel named Voltage and get the used
x-scale object. GetScaleObjX of the first example gets the Graphics Board, in the second one
the Virtual Instrument Panel itself is returned.
! Used scale is Graphics Board
object aPage;
object aGrf;
object aScale;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Reset option ’Use local x-Axis’ of Virtual Instrument Panel
aPage.SetDefScaleX();
! Get object defining scale
DPL Manual
89
DIgSILENT PowerFactory
DPL
aScale=aPage.GetScaleObjX();
if (aPage=aScale) {
output(’The scale used is the Virtual Instrument Panel itself.’);
} else if (aGrf=aScale) {
output(’The scale used is the Graphics Board.’);
} else {
output(’The scale used was not found.’);
}
}
}
! Used scale is Virtual Instrument Panel itself
object aPage;
object aGrf;
object aScale;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Set x-scale to change it to local
aPage.SetScaleX(1,100);
! Get object defining scale
aScale=aPage.GetScaleObjX();
if (aPage=aScale) {
output(’The scale used is the Virtual Instrument Panel itself.’);
} else if (aGrf=aScale) {
output(’The scale used is the Graphics Board.’);
} else {
output(’The scale used was not found.’);
}
}
}
1.8.38 VisPlot Methods
AddVars
void VisPlot.AddVars (string V, object O1,...,O8)
void VisPlot.AddVars (object O, string V1,...V8)
Appends variables to the SubPlot. Variables which are already in the plot are not added.
Arguments
object O (obligatory) : Object for which variables V1..V8 are added
string V1..V8 (obligatory) : One to eight variables names for object O
or
string V (obligatory) : Variable name which is added for objects O1..O8
object O1..O8 (obligatory) : One to eight objects variable V
Return value
none
Using AddVars a single object with different variables or one variable with several objects can be
add to the Subplot. To append a list of variables of a single object the first input parameter is an
object followed by a list of maximum nine variables. To append the same variable for several
objects the first input parameter is the variable name followed by a list of maximum nine objects.
DPL Manual
90
DIgSILENT PowerFactory
DPL
Example
The following examples look for a Subplot named RST on Virtual Instrument Panel named
Voltage and append a list of variables.
1. Example: Append several variables for one single object.
2. Example: Append one variable for a list of objects.
! Append several variables for one single object.
object
object
object
object
aPage;
aGrf;
aPlot;
aScale;
! Note: object load is an interface parameter, therefore it is not defined here
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Clear variable list
aPlot.Clear();
! Append variables
aPlot.AddVars(load, ’m:U1:bus1’,’m:U1l:bus1’,’m:phiu1:bus1’);
}
}
}
! Append several objects with one single variable
object
object
object
object
aPage;
aGrf;
aPlot;
aScale;
! objects load,line and xnet are interface parameters,
! therefore they are not defined here.
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Clear variable list
aPlot.Clear();
! Append variables
DPL Manual
91
DIgSILENT PowerFactory
DPL
aPlot.AddVars(’m:U1:bus1’,load, line, xnet);
}
}
}
AddResVars
void VisPlot.AddResVars (object Res, string V, object O1,...,O7)
void VisPlot.AddResVars (object Res, object O, string V1,...V7)
Appends variables frmo a specific result file to the SubPlot. Combinations of result file and
variables which are already in the plot are not added.
Arguments
object Res (obligatory) : Result object
plus
object O (obligatory) : Object for which variables V1..V8 are added
string V1..V8 (obligatory) : One to eight variables names for object O
or
string V (obligatory) : Variable name which is added for objects O1..O8
object O1..O8 (obligatory) : One to eight objects variable V
Return value
none
See “AddResVars” in 1.8.38, page 92 for more information.
Clear
void VisPlot.Clear ()
Removes all variables from SubPlot
Arguments
none
Return value
none
Example
The following example looks for a Subplot named RST on Virtual Instrument Panel named
Voltage and removes all variables from the plot.
! Remove all variables in Subplot named RST on Virtual Instrument Panel named Voltage
object aPage;
object aGrf;
object aPlot;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get Subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Remove all variables from Subplot
aPlot.Clear();
}
}
}
SetXVar
DPL Manual
92
DIgSILENT PowerFactory
DPL
void VisPlot.SetXVar (object obj, string varname)
Sets x-axis variable. If obj and varname are empty the default x-axis variable (time) is set.
Arguments
object obj (optional) : x-axis object
string varname (optional) : variable of obj
Return value
none
Example
The following examples look for a Subplot named RST and set its x-axis variable. The first
example sets a user defined x-axis variable of the plot. The second one sets the default x-axis
variable (time).
! Set user defined x-axis variable
object aPage;
object aGrf;
object aPlot;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get Subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Set x-scale from 100 to 120
aPlot.SetScaleX(100,120);
! Set x-scale variable
aPlot.SetXVar(line,’m:U1:bus1’);
}
}
}
! Set default x-axis variable (time)
object aPage;
object aGrf;
object aPlot;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get Subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Set x-scale from 100 to 120
aPlot.SetScaleX(100,120);
! Set default x-scale variable (time)
aPlot.SetXVar();
}
}
}
SetScaleX
DPL Manual
93
DIgSILENT PowerFactory
DPL
void VisPlot.SetScaleX (double min, double max, int log)
Sets scale of x-axis. Invalid arguments like negative limits for logarithmic scale are not set. No
arguments =¿ automatic scaling.
Arguments
double min (optional) : Minimum of x-scale.
double max (optional) : Maximum of x-scale.
int log (optional) : ¿ 0 =¿ x-scale is logarithmic.
Return value
none
Example
The following examples look for a Subplot named ’RST’ and set its x-scale. There are three
different examples. 1. Example: Perform auto scaling on x-axis. 2. Example: Set minimum to
0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to 1000. Changes to a
log. scale
! Automatic scaling of x-scale
object aPage;
object aGrf;
object aPlot;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Automatic scaling
aPlot.SetScaleX();
}
}
}
! Set minimum and maximum without changing map mode
object aPage;
object aGrf;
object aPlot;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Set minimum and maximum
aPlot.SetScaleX(0,20);
}
}
}
! Set minimum and maximum, set map mode to log.
DPL Manual
94
DIgSILENT PowerFactory
DPL
object aPage;
object aGrf;
object aPlot;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Set minimum and maximum, change to log. scale
aPlot.SetScaleX(1,1000,1);
}
}
}
SetScaleY
void VisPlot.SetScaleX (double min, double max, int log)
Sets scale of y-axis. Invalid arguments like negative limits for logarithmic scale are not set. No
arguments =¿ automatic scaling.
Arguments
double min (optional) : Minimum of y-scale.
double max (optional) : Maximum of y-scale.
int log (optional) : ¿ 0 =¿ y-scale is logarithmic.
Return value
none
Example
The following examples look for a Subplot named ’RST’ and set its y-axis scale. There are three
different examples. 1. Example: Perform auto scaling on y-Axis. 2. Example: Set minimum to
0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to 1000. Changes to a
log. scale
! Automatic scaling of y-scale
object aPage;
object aGrf;
object aPlot;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Automatic scaling
aPlot.SetScaleY();
}
}
}
! Set minimum and maximum without changing map mode
DPL Manual
95
DIgSILENT PowerFactory
DPL
object aPage;
object aGrf;
object aPlot;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Set minimum and maximum
aPlot.SetScaleY(0,20);
}
}
}
! Set minimum and maximum, set map mode to log.
object aPage;
object aGrf;
object aPlot;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Set minimum and maximum, change to log. scale
aPlot.SetScaleY(1,1000,1);
}
}
}
SetDefScaleX
void VisPlot.SetDefScaleX ()
Sets default scale of x-axis (SetDesktop or SetVipage).
Arguments
none
Return value
none
Example
The following example looks for a Subplot named ’RST’ and sets the option ’Use local x-Axis’
to 0. After that the x-scale used is the Graphics Board (SetDesktop) or the Virtual Instrument
Panel (SetVipage).
! Reset option ’Use local x-Axis’
object aPage;
object aGrf;
object aPlot;
! Look for opened graphics board.
DPL Manual
96
DIgSILENT PowerFactory
DPL
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Reset option ’Use local x-Axis’
aPlot.SetDefScaleX();
}
}
}
SetDefScaleY
void VisPlot.SetDefScaleY ()
Sets default scale of y-axis (IntPlot).
Arguments
none
Return value
none
Example
The following example looks for a Subplot named ’RST’ and sets its option ’Use local y-Axis’ to
0. After that the y-scale used is the Plot Type (IntPlot).
! Reset option ’Use local y-Axis’
object aPage;
object aGrf;
object aPlot;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Reset option ’Use local y-Axis’
aPlot.SetDefScaleY();
}
}
}
SetAutoScaleX
void VisPlot.SetAutoScaleX (int mode)
Sets automatic scaling mode of the x-scale for local scales.
Arguments
int mode (obligatory) : Possible values: 0 never, 1 after simulation, 2 during simulation
Return value
none
Example
The following example looks for a Subplot named ’RST’ and change its auto scale mode. The
first example works fine, the second one generates an error message because the x-scale is
unused.
DPL Manual
97
DIgSILENT PowerFactory
DPL
! Set autoscale mode of x-scale to off
object aPage;
object aGrf;
object aPlot;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Set limits to change x-scale of page to used scale
aPlot.SetScaleX(0,10);
! Turn off automatic scaling of x-scale
aPlot.SetAutoScaleX(0);
}
}
}
! Try to set autoscale mode of x-scale to online
object aPage;
object aGrf;
object aPlot;
! Look for opened Graphics Board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Reset option ’Use local x-Axis’ of Subplot
aPlot.SetDefScaleX();
! Try to set automatic scaling of x-scale to Online
aPlot.SetAutoScaleX(2);
}
}
}
SetAutoScaleY
void VisPlot.SetAutoScaleY (int mode)
Sets automatic scaling mode of the y-scale for local scales.
Arguments
int mode (obligatory) : Possible values: 0 never, 1 after simulation, 2 during simulation
Return value
none
Example
The following example looks for a Subplot named ’RST’ and change its auto scale mode. The
first example works fine, the second one generates an error message because the y-scale is
unused.
DPL Manual
98
DIgSILENT PowerFactory
DPL
! Set autoscale mode of y-scale to off
object aPage;
object aGrf;
object aPlot;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Set limits to change y-scale of page to used scale
aPlot.SetScaleY(0,10);
! Turn off automatic scaling of y-scale
aPlot.SetAutoScaleY(0);
}
}
}
! Try to set autoscale mode of y-scale to online
object aPage;
object aGrf;
object aPlot;
! Look for opened Graphics Board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Reset option ’Use local y-Axis’ of Subplot
aPlot.SetDefScaleY();
! Try to set automatic scaling of y-scale to Online
aPlot.SetAutoScaleY(2);
}
}
}
SetAdaptX
void VisPlot.SetAdaptX (int mode, double trigger)
Sets the adapt scale option of the x-scale for local scales.
Arguments
int mode (obligatory) : Possible values: 0 off, 1 on
double trigger (optional) : Trigger value, unused if mode is off or empty
Return value
none
Example
The following examples look for a Subplot named ’RST’ and change its adapt scale option. The
first example works fine, the second one generates an error message because the x-scale is
unused.
DPL Manual
99
DIgSILENT PowerFactory
DPL
! Modify adapt scale option of Subplot
object aPage;
object aGrf;
object aPlot;
! Look for opened Graphics Board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Set x-scale limits to set option ’Use local x-Axis’
aPlot.SetScaleX(0,20);
! Turn on adapt scale, use a trigger value of 3
aPlot.SetAdaptX(1,3);
! Turn off adapt scale
aPlot.SetAdaptX(0,3);
! Turn on adapt scale again, do not change the trigger value
aPlot.SetAdaptX(1);
}
}
}
! Try to turn on adapt scale of x-scale
object aPage;
object aGrf;
object aPlot;
! Look for opened Graphics Board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Reset option ’Use local x-Axis’ of Subplot
aPlot.SetDefScaleX();
! Try to turn on adapt scale, use a trigger value of 3
! Leads to error message because scale is not local
aPlot.SetAdaptX(1,3);
}
}
}
SetAdaptY
void VisPlot.SetAdaptY (int mode, double offset)
Sets the adapt scale option of the y-scale for local scales.
Arguments
int mode (obligatory) : Possible values: 0 off, 1 on
double trigger (optional) : Offset, unused if mode is off or empty
Return value
DPL Manual
100
DIgSILENT PowerFactory
DPL
none
Example
The following examples look for a Subplot named ’RST’ and change its adapt scale option of
the y scale. The first example works fine, the second one generates an error message because
the y-scale is unused.
! Modify adapt scale option of Subplot
object aPage;
object aGrf;
object aPlot;
! Look for opened Graphics Board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Set y-scale limits to set option ’Use local y-Axis’
aPlot.SetScaleY(0,20);
! Turn on adapt scale, use a trigger value of 3
aPlot.SetAdaptY(1,3);
! Turn off adapt scale
aPlot.SetAdaptY(0,3);
! Turn on adapt scale again, do not change the trigger value
aPlot.SetAdaptY(1);
}
}
}
! Try to turn on adapt scale for y-scale
object aPage;
object aGrf;
object aPlot;
! Look for opened Graphics Board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Reset option ’Use local y-Axis’ of Subplot
aPlot.SetDefScaleY();
! Try to turn on adapt scale, use a trigger value of 3
! Leads to error message because scale is not local
aPlot.SetAdaptY(1,3);
}
}
}
GetScaleObjX
DPL Manual
101
DIgSILENT PowerFactory
DPL
object VisPlot.GetScaleObjX ()
Returns used object defining x-scale. The returned object is the Subplot itself, the Virtual
Instrument Panel or the Graphics Board.
Arguments
none
Return value
Object defining the x-scale.
Example
The following examples look for a Subplot named ’RST’ and get the used x-scale object. There
are three different examples.
1. Example: Used scale is Graphics Board 2. Example: Used scale is Virtual Instrument Panel
3. Example: Used scale is Subplot itself.
! Used scale is Graphics Board
object aPage;
object aGrf;
object aPlot;
object aScale;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Reset option ’Use local x-Axis’ of Virtual Instrument Panel
aPage.SetDefScaleX();
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Reset option ’Use local x-Axis’ of Subplot
aPlot.SetDefScaleX();
! Get object defining scale
aScale=aPlot.GetScaleObjX();
if (aPlot=aScale) {
output(’The scale used is the Subplot itself.’);
} else if (aPage=aScale) {
output(’The scale used is the Virtual Instrument Panel.’);
} else if (aGrf=aScale) {
output(’The scale used is the Graphics Board.’);
} else {
output(’The scale used was not found.’);
}
}
}
}
! Used Scale is Virtual Instrument Panel
object aPage;
object aGrf;
object aPlot;
object aScale;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
DPL Manual
102
DIgSILENT PowerFactory
DPL
if (aPage) {
! Set x-scale to change it to local
aPage.SetScaleX(1,100);
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Reset option ’Use local x-Axis’ of Subplot
aPlot.SetDefScaleX();
! Get object defining scale
aScale=aPlot.GetScaleObjX();
if (aPlot=aScale) {
output(’The scale used is the Subplot itself.’);
} else if (aPage=aScale) {
output(’The scale used is the Virtual Instrument Panel.’);
} else if (aGrf=aScale) {
output(’The scale used is the Graphics Board.’);
} else {
output(’The scale used was not found.’);
}
}
}
}
! Used Scale is Subplot itself
object aPage;
object aGrf;
object aPlot;
object aScale;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Reset option ’Use local x-Axis’ of Virtual Instrument Panel
aPage.SetDefScaleX();
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Set x-scale of Subplot to change it to local
aPlot.SetScaleX(1,100);
! Get object defining scale
aScale=aPlot.GetScaleObjX();
if (aPlot=aScale) {
output(’The scale used is the Subplot itself.’);
} else if (aPage=aScale) {
output(’The scale used is the Virtual Instrument Panel.’);
} else if (aGrf=aScale) {
output(’The scale used is the Graphics Board.’);
} else {
output(’The scale used was not found.’);
}
}
}
}
DPL Manual
103
DIgSILENT PowerFactory
DPL
GetScaleObjY
object VisPlot.GetScaleObjY ()
Returns used object defining y-scale. The returned object is either the Subplot itself or the Plot
Type (IntPlot).
Arguments
none
Return value
Object defining the y-scale.
Example
The following examples look for a Subplot named ’RST’ and get the used y-scale object. There
are three different examples.
1. Example: Used scale is Plot Type. 2. Example: Used scale is Subplot itself.
! Used scale is Plot Type
object aPage;
object aGrf;
object aPlot;
object aScale;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Reset option ’Use local y-Axis’ of Subplot
aPlot.SetDefScaleY();
! Get object defining scale
aScale=aPlot.GetScaleObjY();
if (aScale=aPlot) {
output(’The y-scale used is the Subplot itself.’);
} else {
output(’The y-scale used is the Plot Type.’);
}
}
}
}
! Used scale is Subplot itself
object aPage;
object aGrf;
object aPlot;
object aScale;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Set x-scale of Subplot to change it to local
DPL Manual
104
DIgSILENT PowerFactory
DPL
aPlot.SetScaleY(1,100);
! Get object defining scale
aScale=aPlot.GetScaleObjY();
if (aScale=aPlot) {
output(’The y-scale used is the Subplot itself.’);
} else {
output(’The y-scale used is the Plot Type.’);
}
}
}
}
SetCrvDesc
object VisPlot.SetCrvDesc (int index, string desc [, string desc1]...)
Sets the description of curves starting at curve number ’index’. A list of descriprions can be
set.
Arguments
int index (obligatory) : Row of first curve to change the description.
string desc (obligatory) : Description to set for curve in row index.
string desc1 (optional) : Description to set for curve in row index+1. Object defining the y-scale.
Example
The following examples look for a Subplot named ’RST’ sets the description for the curves
defined in row two and three. The first variable’s description remains unchanged.
! Modify descriptions
object
object
object
object
aPage;
aGrf;
aPlot;
aScale;
! Note: object load is an interface parameter, therefore it is not defined here
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Clear variable list
aPlot.Clear();
! Append variables
aPlot.AddVars(load, ’m:U1:bus1’,’m:U1l:bus1’,’m:phiu1:bus1’);
! Set description of row 2 and 3
aPlot.SetCrvDesc(2,,’Line-Line Voltage’,’Angle’);
}
}
}
1.8.39 IntPlot Methods
SetScaleY
DPL Manual
105
DIgSILENT PowerFactory
DPL
void IntPlot.SetScaleX (double min, double max, int log)
Sets scale of y-axis. Invalid arguments like negative limits for logarithmic scale are not set. No
arguments =¿ automatic scaling.
Arguments
double min (optional) : Minimum of y-scale.
double max (optional) : Maximum of y-scale.
int log (optional) : ¿ 0 =¿ y-scale is logarithmic; 0 =¿ y-scale is linear.
Return value
none
Example
The following example looks for a Subplot named ’RST’ and set its y-axis scale. There are three
different examples. 1. Example: Perform auto scaling on y-Axis. 2. Example: Set minimum to
0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to 1000. Changes to a
log. scale
! Automatic scaling of y-scale
object aPage;
object aGrf;
object aPlot;
object aScale;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Reset option ’Use local y-Axis’ of subplot
aPlot.SetDefScaleY();
! Get object defining scale (now IntPlot)
aScale=aPlot.GetScaleObjY();
if (aScale) {
! Perform auto scaling
aScale.SetScaleY();
}
}
}
}
! Set minimum and maximum without changing map mode
object aPage;
object aGrf;
object aPlot;
object aScale;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
DPL Manual
106
DIgSILENT PowerFactory
DPL
! Reset option ’Use local y-Axis’ of subplot
aPlot.SetDefScaleY();
! Get object defining scale (now IntPlot)
aScale=aPlot.GetScaleObjY();
if (aScale) {
! Perform auto scaling
aScale.SetScaleY(0,20);
}
}
}
}
! Set minimum and maximum, set map mode to log.
object aPage;
object aGrf;
object aPlot;
object aScale;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Reset option ’Use local y-Axis’ of subplot
aPlot.SetDefScaleY();
! Get object defining scale (now IntPlot)
aScale=aPlot.GetScaleObjY();
if (aScale) {
! Perform auto scaling
aScale.SetScaleY(1,1000,1);
}
}
}
}
SetAutoScaleY
void IntPlot.SetAutoScaleY (int mode)
Sets automatic scaling mode of the y-scale.
Arguments
int mode (obligatory) : Possible values: 0 never, 1 after simulation, 2 during simulation
Return value
none
Example
The following example sets the auto scale mode of the Plot Type to On.
! Set autoscale option of Plot Type
object aPage;
object aGrf;
object aPlot;
DPL Manual
107
DIgSILENT PowerFactory
DPL
object aScale;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Reset option ’Use local y-Axis’ of subplot
aPlot.SetDefScaleY();
! Get object defining scale (now IntPlot)
aScale=aPlot.GetScaleObjY();
if (aScale) {
! Set auto scale option to on
aScale.SetAutoScaleY(1);
}
}
}
}
SetAdaptY
void IntPlot.SetAdaptY (int mode, double offset)
Sets the adapt scale option of the y-scale.
Arguments
int mode (obligatory) : Possible values: 0 off, 1 on
double offset (optional) : Offset, unused if mode is off or empty
Return value
none
Example
The following examples look for a Subplot named ’RST’, gets its Plot Type and changes the
adapt scale option of the scale.
! Modify adapt scale option of Plot Type
object aPage;
object aGrf;
object aPlot;
object aScale;
! Look for opened graphics board.
aGrf=GetGraphBoard();
if (aGrf) {
! Get Virtual Instrument Panel named Voltage
aPage=aGrf.GetPage(’Voltage’,1);
if (aPage) {
! Get subplot named ’RST’
aPlot=aPage.GetVI(’RST’,’VisPlot’,1);
if (aPlot) {
! Reset option ’Use local y-Axis’ of subplot
aPlot.SetDefScaleY();
! Get object defining scale (now IntPlot)
aScale=aPlot.GetScaleObjY();
if (aScale) {
! Set y-scale limits to set option ’Use local y-Axis’
aScale.SetScaleY(0,20);
DPL Manual
108
DIgSILENT PowerFactory
DPL
! Turn on adapt scale, use a offset of 3
aScale.SetAdaptY(1,3);
! Turn off adapt scale
aScale.SetAdaptY(0,3);
! Turn on adapt scale again, do not change the offset
aScale.SetAdaptY(1);
}
}
}
}
DPL Manual
109
Index
DPL Manual
Index
abs, 5
acos, 5
Activate(IntCase), 48
Activate(IntPrj), 48
Add(Set), 32
AddCntcy(ComSimoutage), 47
AddCopy(Object), 44
AddRef(ComNmink), 49
AddRef(SetSelect), 73
AddResVars(VisPlot), 92
AddVar(IntMon), 54
AddVars(ElmRes), 66
AddVars(VisPlot), 90
All(SetSelect), 76
AllAsm(SetSelect), 75
AllBars(SetSelect), 74
AllBreakers(SetPath), 72
AllBreakers(SetSelect), 77
AllClosedBreakers(SetPath), 72
AllClosedBreakers(SetSelect), 77
AllElm(SetSelect), 73
AllLines(SetSelect), 74
AllLoads(SetSelect), 75
AllOpenBreakers(SetPath), 72
AllOpenBreakers(SetSelect), 77
AllSym(SetSelect), 75
AllTypLne(SetSelect), 76
Arguments, 12
asin, 5
Assignment, 5
atan, 5
Automating tasks, 2
Boolean expression, 6
Break, 6
Buscoupler
Methods, 59
CalcElParams(typAsm), 48
CalcElParams(typAsmo), 48
Calling conventions, 12
ceil, 5
Clear(ComNmink), 50
Clear(ElmRes), 64
Clear(Set), 32
Clear(SetSelect), 73
Clear(VisPlot), 92
DPL Manual
ClearVars(IntMon), 54
Close(ElmCoup), 59
Close(StaSwitch), 69
ColLbl(IntMat), 57
ComDpl, 3
Execute, 55
ComEcho
Off, 52
On, 51
ComInc
Execute, 68
ComLdf
Execute, 68
ComNmink
AddRef, 49
Clear, 50
GetAll, 50
ComOutage
GetObj, 46
SetObjs, 46
ComRel3
Execute, 67
ComRes
ExportFullRange, 51
FileNmResNm, 51
ComShc
Execute, 68
ComSimoutage
AddCntcy, 47
ExecuteCntcy, 47
Reset, 47
SetLimits, 47
Continue, 6
cos, 5
cosh, 5
Count(Set), 33
Coupler
Methods, 59
CreateFeederWithRoutes(ElmLne), 62
CreateObject(Object), 45
Date(SetTime), 52
Deactivate(IntCase), 48
Deactivate(IntPrj), 48
DIgSILENT Programming Language, 2
do, 6
double (DPL variable), 4
DPL
assignement, 5
Boolean expression, 6
calling subroutines, 12
command object, 3
expressions, 5
external objects, 11
Flow instructions, 6
input, 7
internal methods, 13
Macros, 12
Methods, 55
object methods, 14
output, 7
set methods, 14
Subroutines, 12
syntax, 3
variables, 4
DPL functions, 5
Draw(ElmRes), 65
ElmZone
GetAll, 67
GetBranches, 67
GetBuses, 67
GetObjs, 67
else, 6
Execute(ComDpl), 55
Execute(ComInc), 68
Execute(ComLdf), 68
Execute(ComRel3), 67
Execute(ComShc), 68
ExecuteCntcy(ComSimoutage), 47
exp, 5
ExportFullRange(ComRes), 51
Expressions, 5
External objects, 11
Feeder
Methods, 70
FileNmResNm(ComRes), 51
Filter
Edit(Object), 45
Methods, 54
ElmComp
First(Set), 34
Slotupd, 50
FirstFilt(Set), 35
ElmCoup
Firstmatch(Set), 35
Close, 59
floor, 5
IsClosed, 60
Flow instructions, 6
IsOpen, 60
Form
Open, 59
Methods, 78
Elmfeeder
frac, 5
GetAll, 49
Function(Object), 39
GetFunctions
Buses/GetBranches/GetNodesBranches,
DPL internal, 13
49
DPL objects, 14
GetObjs, 49
DPL sets, 14
ElmLne
functions, 5
CreateFeederWithRoutes, 62
Get(IntMat), 55
GetType, 61
Get(IntVec), 57
HasRoutes, 60
Get(SetFilt), 54
HasRoutesOrSec, 61
GetAll(ComNmink), 50
IsCable, 61
GetAll(Elmfeeder), 49
IsNetCoupling, 62
GetAll(ElmZone), 67
SetCorr, 62
GetAll(SetFeeder), 70
SetNomCurr, 64
GetAll(SetPath), 71
ElmLneroute
GetAll(SetSelect), 76
HasSections, 63
GetBranches(ElmZone), 67
IsCable, 63
GetBranches(SetFeeder), 70
ElmRes
GetBranches(SetPath), 71
AddVars, 66
GetBuses(ElmZone), 67
Clear, 64
GetBuses(SetFeeder), 70
Draw, 65
GetBuses/GetBranches/GetNodesBranches(Elmfeeder),
GetObj, 66
49
Init, 64
GetBusses(SetPath), 71
SetAsDefault, 66
GetClass(Object), 44
Write, 65
GetConnectionCount(Object), 38
WriteDraw, 66
DPL Manual
GetContents(Object), 42
GetCubicle(Object), 38
GetObj(ComOutage), 46
GetObj(ElmRes), 66
GetObjs(Elmfeeder), 49
GetObjs(ElmZone), 67
GetPage(SetDesktop), 80
GetParent(Object), 38
GetScaleObjX(SetVipage), 89
GetScaleObjX(VisPlot), 101
GetScaleObjY(VisPlot), 104
GetSize(Object), 40
GetType(ElmLne), 61
GetVal(Object), 40
GetVar(IntMon), 53
GetVI(SetVipage), 83
HasResults(Object), 38
HasRoutes(ElmLne), 60
HasRoutesOrSec(ElmLne), 61
HasSections(ElmLneroute), 63
if, 6
Init(ElmRes), 64
Init(IntMat), 56
Init(IntVec), 58
Input instruction, 7
int (DPL variable), 4
IntCase
Activate, 48
Deactivate, 48
Interactive instructions, 7
IntForm
SetText, 78
WriteOut, 78
IntMat
ColLbl, 57
Get, 55
Init, 56
NCol, 57
NRow, 56
Resize, 56
RowLbl, 57
Set, 56
IntMon
AddVar, 54
ClearVars, 54
GetVar, 53
Methods, 53
NVars, 53
PrintAllVal, 53
PrintVal, 53
RemoveVar, 54
IntPlot
methods, 105
SetAdaptY, 108
DPL Manual
SetAutoScaleY, 107
SetScaleX, 105
IntPrj
Activate, 48
Deactivate, 48
IntVec
Get, 57
Init, 58
Resize, 58
Set, 58
Size, 59
IsCable(ElmLne), 61
IsCable(ElmLneroute), 63
IsCable(TypLne), 64
IsClass(Object), 43
IsClosed(ElmCoup), 60
IsClosed(StaSwitch), 70
IsIn(Set), 32
IsNetCoupling(ElmLne), 62
IsNode(Object), 40
IsOpen(ElmCoup), 60
IsOpen(StaSwitch), 69
IsOutOfService(Object), 46
IsRelevant(Object), 46
Line
Methods, 60
Line Route
Methods, 63
Line Type
Methods, 64
ln, 5
lnm(Object), 41
log, 5
logarithm, 5
Loop control, 6
Macros, 12
MarkInGraphics(Object), 42
MarkInGraphics(Set), 37
Matrix
Methods, 55
max, 5
method, definition, 13
min, 5
modulo, 5
Move(Object), 39
NCol(IntMat), 57
Next(Set), 34
NextFilt(Set), 36
Nextmatch(Set), 35
NRow(IntMat), 56
NVars(IntMon), 53
Obj(Set), 34
Object
AddCopy, 44
CreateObject, 45
Edit, 45
Function, 39
GetClass, 44
GetConnectionCount, 38
GetContents, 42
GetCubicle, 38
GetParent, 38
GetSize, 40
GetVal, 40
HasResults, 38
IsClass, 43
IsNode, 40
IsOutOfService, 46
IsRelevant, 46
lnm, 41
MarkInGraphics, 42
Move, 39
ShowFullName, 43
snm, 41
unm, 41
Unom, 42
VarExists, 39
object (DPL variable), 4
Object Methods, 14
Off(ComEcho), 52
On(ComEcho), 51
Open(ElmCoup), 59
Open(StaSwitch), 69
Output instruction, 7
Path
Methods, 71
pow, 5
PrintAllVal(IntMon), 53
PrintVal(IntMon), 53
Programming language, 2, 3
Remove(Set), 33
RemoveVar(IntMon), 54
Reset(ComSimoutage), 47
Resize(IntMat), 56
Resize(IntVec), 58
Results
Methods, 64
root, 5
round, 5
RowLbl(IntMat), 57
Script, 3
Selection
Methods, 73
Set
Add, 32
Clear, 32
Count, 33
DPL Manual
First, 34
FirstFilt, 35
Firstmatch, 35
IsIn, 32
MarkInGraphics, 37
Next, 34
NextFilt, 36
Nextmatch, 35
Obj, 34
Remove, 33
SortToClass, 37
SortToName, 37
SortToVar, 36
set (DPL variable), 4
Set Methods, 14
Set(IntMat), 56
Set(IntVec), 58
SetAdaptX(SetDesktop), 83
SetAdaptX(SetVipage), 88
SetAdaptX(VisPlot), 99
SetAdaptY(IntPlot), 108
SetAdaptY(VisPlot), 100
SetAsDefault(ElmRes), 66
SetAutoScaleX(SetDesktop), 82
SetAutoScaleX(SetVipage), 87
SetAutoScaleX(VisPlot), 97
SetAutoScaleY(IntPlot), 107
SetAutoScaleY(VisPlot), 98
SetCorr(ElmLne), 62
SetCrvDesc(VisPlot), 105
SetDefScaleX(SetVipage), 87
SetDefScaleX(VisPlot), 96
SetDefScaleY(VisPlot), 97
SetDesktop
GetPage, 80
methods, 79
SetAdaptX, 83
SetAutoScaleX, 82
SetResults, 81
SetScaleX, 81
SetXVar, 81
Show, 79
WriteWMF, 80
SetFeeder
GetAll, 70
GetBranches, 70
GetBuses, 70
SetFilt
Get, 54
SetLimits(ComSimoutage), 47
SetNomCurr(ElmLne), 64
SetObjs(ComOutage), 46
SetPath
AllBreakers, 72
AllClosedBreakers, 72
AllOpenBreakers, 72
GetAll, 71
GetBranches, 71
GetBusses, 71
SetResults(SetDesktop), 81
SetResults(SetVipage), 85
SetScaleX(IntPlot), 105
SetScaleX(SetDesktop), 81
SetScaleX(SetVipage), 86
SetScaleX(VisPlot), 93, 95
SetSelect
AddRef, 73
All, 76
AllAsm, 75
AllBars, 74
AllBreakers, 77
AllClosedBreakers, 77
AllElm, 73
AllLines, 74
AllLoads, 75
AllOpenBreakers, 77
AllSym, 75
AllTypLne, 76
Clear, 73
GetAll, 76
SetStyle(SetVipage), 84
SetText(IntForm), 78
SetTile(SetVipage), 84
SetTime
Date, 52
Time, 52
SetVipage
GetScaleObjX, 89
GetVI, 83
methods, 83
SetAdaptX, 88
SetAutoScaleX, 87
SetDefScaleX, 87
SetResults, 85
SetScaleX, 86
SetStyle, 84
SetTile, 84
SetXVar, 85
SetXVar(SetDesktop), 81
SetXVar(SetVipage), 85
SetXVar(VisPlot), 92
Show(SetDesktop), 79
ShowFullName(Object), 43
sin, 5
sinh, 5
Size(IntVec), 59
Slotupd(ElmComp), 50
snm(Object), 41
SortToClass(Set), 37
SortToName(Set), 37
SortToVar(Set), 36
sqr, 5
DPL Manual
sqrt, 5
square root, 5
StaSwitch
Close, 69
IsClosed, 70
IsOpen, 69
Open, 69
string (DPL variable), 4
Switch
Methods, 69
Syntax, 3
tan, 5
tanh, 5
Time
Methods, 52
Time(SetTime), 52
trigonometric, 5
trunc, 5
typAsm
CalcElParams, 48
typAsmo
CalcElParams, 48
TypLne
IsCable, 64
unm(Object), 41
Unom(Object), 42
VarExists(Object), 39
Variable Definitions, 4
Variable Set
Methods, 53
Vector
Methods, 57
VisPlot
AddResVars, 92
AddVars, 90
Clear, 92
GetScaleObjX, 101
GetScaleObjY, 104
methods, 90
SetAdaptX, 99
SetAdaptY, 100
SetAutoScaleX, 97
SetAutoScaleY, 98
SetCrvDesc, 105
SetDefScaleX, 96
SetDefScaleY, 97
SetScaleX, 93, 95
SetXVar, 92
while, 6
Write(ElmRes), 65
WriteDraw(ElmRes), 66
WriteOut(IntForm), 78
WriteWMF(SetDesktop), 80