dpl manual version 12-1

DPL ManualDIgSILENT PowerFactoryVersion 12.1

DIgSILENT GmbHGomaringen, Germany

2003

Publisher:DIgSILENT GmbHBuchenstrasse 10D-72810 GomaringenTel : (07072)9168-0Fax : (07072)9168-88

Visit our homepage at:www.digsilent.de

Copyright DIgSILENT GmbH.All rights reserved. No part of thispublication may be reproduced ordistributed in any form withoutpermission of the publisher.doc 103 05 06 920

http://www.digsilent.de

Contents

1 DPL 21.1 The DPL Command Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 The DPL Script Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Access to Other Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.4 Access to Locally Stored Objects . . . . . . . . . . . . . . . . . . . . . . . . 91.5 Accessing the General Selection . . . . . . . . . . . . . . . . . . . . . . . . 101.6 Accessing External Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.7 Remote Scripts and DPL command Libraries . . . . . . . . . . . . . . . . . 111.8 DPL Functions and Subroutines . . . . . . . . . . . . . . . . . . . . . . . . 13

DPL Manual 1

DIgSILENT PowerFactory DPL

Chapter1

DPL

The DIgSILENT Programming Language “DPL” serves the purpose of offering an interface forautomating tasks in the PowerFactory program. The DPL method distinguishes itself from thecommand 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 thecreation of new calculation functions. Such user-defined calculation commands can be used inall 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, thefollowing is important to understand:

DPL Manual 2


• A DPL command either executes its own script or the script of another, remote, DPLcommand. In the first case, the DPL command is called a ‘root command’ and the scriptis 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 scriptand which are used to define default values.

• Each root command may define one or more external objects . External object are used tomake a DPL command run with specific power system objects, selections, commands, etc.

• A referring command may overrule all default interface values and all selected externalobjects 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 creategeneric DPL commands, which may be used with different settings in many different projects andstudy cases.

1.1 The DPL Command Object

The DPL command object holds a reference to a remote DPL command when it is not a rootcommand. The example depicted in Fig. 1.1 is apparently a referring command, since its “DPLscript” reference is set to the remote command \LIBRARY\DPL COMMANDS\CHECKVLOADING.A root command has its own script on the “script” page of the dialog. A referring command usesthe script of the remote DPL command.

The DPL command also holds a reference to a selection of objects (“General Selection”). Thegeneral selection in the example is empty. Only one single “General Selection” is valid at a timefor 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 DPLcommand itself. DPL commands that call other DPL commands as subroutines, may use andchange 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 DPLcommand that, for example, searches the set of lines for which a short-circuit causes too deep avoltage 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 externalobject 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. Thistype of language is intuitive, easy to read, and easy to learn. The basic command set has beenkept as small as possible.

DPL Manual 3


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 togetherby braces.

Example:

statement1;statement2;if (condition) {

groupstatement1;groupstatement2;

}

1.2.1 Variable DefinitionsDPL uses the following internal parameter types

• double , a 15 digits real number

• int , a integer number

DPL Manual 4


• 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] varname, varname, ..., varname;[TYPE] = double | int | object | set

All parameter declarations must be given together in the top first lines of the DPL script. Thesemicolon is obligatory.

Examples:

double Losses, Length, Pgen;int NrOfBreakers, i, j;string txt1, nm1, nm2;object O1, O2, BestSwitchToOpen;set AllSwitches, AllBars;

1.2.2 Assignments and ExpressionsThe following syntax is used to assign a value to a variable:

variable = expressionvariable += expressionvariable -= 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(); ! x now equals 1.5708y = sin(x); ! y now equals 1.0x += y; ! x now equals 2.5708y -= x; ! y now equals -1.5708

The following operators and functions are available:

• arithmetic operators: +, -, *, /

• standard functions:sin(x) cos(x) tan(x) asin(x)acos(x) atan(x) sinh(x) cosh(x)tanh(x) exp(x) ln(x) log(x) (basis 10)abs(x) min(x,y) max(x,y) sqrt(x) (square root)trunc(x) frac(x) round(x) sqr(x) (power of 2)pow(x,y) modulo(x,y) ceil(x) floor(x)rand()

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


1.2.3 Program Flow InstructionsThe following flow commands are available.

if ( [boolexpr] ) [statlist]if ( [boolexpr] ) [statlist] else [statlist]

do [statlist] while ( [boolexpr] )while ( [boolexpr] ) [statlist]

in which

[boolexpr] = expression [boolcomp] expression[boolcomp] = ”<” | ”>” | ”=” | ”>=” | ”>=” | ”<>”

[statlist] = 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. Theexecution 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 smallestenclosing ‘do-while’ or ’while-do’ statement. The execution of the DPL script is continued with theevaluation of the boolean expression of the loop statement. The loop statement list will beexecuted again when the expression evaluates to TRUE. Otherwise the loop statement is endedand the execution will continue with the first command following the loop statement.

Examples:

DPL Manual 6


O1 = S1.First();while (O1) {

O1.Open();err = Ldf.Execute();if (err) {

! skip this oneO1 = S1.Next;continue;

}O2 = S2.First();AllOk = 1;DoReport(0); !resetwhile (O2) {


! do not continueAllOk = 0;break;

} else {DoReport(1); ! add

}O2 = S2.Next();

}if (AllOk) {

DoReport(2); ! report}O1 = S1.Next();

}

1.2.4 Input and OutputThe “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 mayenter 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 bereplaced 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


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 alreadypossible to create a small program. However, such a script would not be able to use ormanipulate variables of ‘external’ objects. It would not be possible, for instance, to write a scriptthat 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 ofobjects (the set of alternative line types).

The DPL language has several methods with which the database objects and their parametersbecome available in the DPL script:

• The most direct method is to create an object, or a reference to an object, in the DPLcommand 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 theobjects are accessed is not important. The general selection is automatically filled when aselection is right clicked in either the single line graphic or the database browser and theoption “Execute DPL script” is selected.

• The list of external objects is mainly used when a script should be executed for specificobjects or selections. The list of external objects is nothing more than a list of ‘aliases’. Theexternal object list is used to select specific objects for each alias, prior to the execution ofthe script.

1.3.1 Object Variables and MethodsIf a database object is known to the DPL command, then all its methods may be called, and allits variables are available. For example, if we want to change a load flow command in order toforce an asymmetrical load flow calculation, we may alter the parameter “iopt net”. This is doneby 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


objectname:parametername

In the same way, it is possible to get a value from a database object, for instance a result fromthe load flow calculations. One of such a result is the loading of a line object, which is stored inthe variable “c:loading”. The following example performs the unbalanced loadflow and reportsthe line loading:

00. int error;01. double loading;02. Ldf:iopt_net = 1; ! force unbalanced03. error = Ldf.Execute(); ! execute load flow04. if (error) {05. exit();06. } else {07. loading = Line:c:loading; ! get line loading08. output(’loading=loading’); ! report line loading09. }

This examples is very primitive but it shows the basic methods for accessing database objectsand 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 objectqualifies as a variable name in the DPL script. It will not be possible to access an object whichname 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 flowcommand 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 toperform a load flow.

00. int error;01. error = Ldf.Execute();02. if (error) {03. output(’Load flow command returns an error’);04. exit();05. }

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


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 wouldcreate a problem if many objects have to be accessed, for instance if we want to search the linewith the highest loading. It would be impractical to create a reference to each and every line. Amore elegant way would be to use the DPL global selection and fill it with all lines. The databasebrowser offers several ways in which to fill the DPL selection with little effort. The selection maythen be used to access each line indirectly by a DPL “object” variable. In this way, we may createa loop in which we search for the highest loading. This is shown in the following example.

00. int error;01. double max;02. object O, Omax;03. set S;04.05. error = Ldf.Execute(); ! execute a loadflow06. if (error) exit(); ! exit on error07.08. S = SEL.AllLines(); ! get all selected lines09. Omax = S.First(); ! get first line10. if (Omax) {11. max = Omax:c:loading; ! initialize maximum12. } else {13. output(’No lines found in selection’);14. exit(); ! no lines: exit15. }16. O = S.Next(); ! get next line17. while (O) { ! while more lines18. if (O:c:loading>max) {19. max = O:c:loading; ! update maximum20. Omax = O; ! update max loaded line21. }22. O = S.Next();23. }24. output(’max loading=max for line’); !output results25. Omax.ShowFullName();

The object “SEL” used in line 08 is the reserved object variable which equals the “GeneralSelection” in the DPL command dialog. The “SEL” object is available in all DPL scripts at alltimes and only one single “General Selection” object is valid at a time for all DPL scripts. Thismeans that setting the “General Selection” in the one DPL command dialog, will change it for allother DPL commands too.

The method “AllLines()” in line 08 will return a set of all lines found in the general selection. Thisset is assigned to the variable “S”. The lines are now accessed one by one by using the setmethods “First()” and “Next()” in line 09, 16 and 22. The line with the highest loading is kept inthe variable “Omax”. The name and database location of this line is written to the output windowat the end of the script by calling “ShowFullName()”.

DPL Manual 10


1.6 Accessing External Objects

The DPL contents makes it possible to access external object in the DPL script. The specialgeneral selection object (“SEL”) is used to give all DPL functions and their subroutines access toa central selection of objects.

Although flexible, this method would create problems if more than one specific object should beaccessed in the script. By creating references to those objects in the DPL command itself, theDPL command would become specific to the current calculation case. Gathering the objects inthe general selection would create the problem of selecting the correct object.

To prevent the creation of calculation-specific DPL commands, it is recommended practice toreserve the DPL contents for all objects that really ‘belong’ to the DPL script and which are thusindependent on were and how the script is used. Good examples are load flow and short-circuitcommands, 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 isused, 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 objectis referred to by that name. Changing the object is then a matter of selecting another object. InFig. 1.4, an example of a external object is given. This external object may be referred to in theDPL 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 currentlyactive study case and to write the script directly in that DPL object. In such a way, a DPL “rootcommand” is made. If this root command needs DPL subroutines, then one or more DPLcommand objects may be created in its contents. Each of these subroutines will normally also bewritten as root functions.

The newly written DPL command with its subroutines may be tested and used in the currentlyactive study case. However, it cannot be executed when another study case is active. In order touse the DPL command in other study cases, or even in other projects, we would have to copy the

DPL Manual 11


DPL command and its contents. This, however, would make it impossible to alter the DPLcommand without having to alter all its copies.

The solution is in the use of ‘remote scripts’. The procedure to create and use remote scripts isdescribed 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 otherstudy 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 DPLcommand, 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. Setall interface variable values to their default values. To avoid deleting a part of the DPLcommand, make sure that if any of the DPL (sub)commands refers to a remote script, allthose 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 areneeded for execution. This includes all subroutines, which will also refer to remote scripts, allcommand objects, and all other objects. Some classes objects are copied as reference, otherclasses are copied completely.

The new DPL command does not contain a script, but executes the remote script. For theexecution itself, this does not make a change. However, more than one DPL command may nowrefer to the same remote script. Changing the remote script, or any of its local objects orsub-commands, will now change the execution of all DPL commands that refer to it.

1.7.1 Subroutines and Calling ConventionsA 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. Inprinciple, 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 bechanged by the calling command. These interface parameters can also be set directly at callingtime, by providing one or more calling arguments. These calling arguments are assigned to theinterface 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


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 likesimple 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. Afunction which can be called by a DPL command is called a “method” . Four types of methodsare distinguished:

Internal methods These are the build-in methods of the DPL command. They can be calledalways.

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 DIgSILENTobjects, such as the loadflow command, the line object, the asynchronous machine, etc.

1.8.1 DPL Internal MethodsThe DPL program language has a small set of DPL-specific internal commands:

Random returns a random numbervalidLDF checks for a valid loadflow resultvalidRMS checks for a valid simulation resultvalidSHC checks for a valid short-circuit resultvalidSIM checks for a valid simulation resultAllRelevant returns all calculation relevant objectsActiveCase returns the active calculation caseSummaryGrid returns the summary gridActiveProject returns the active projectWrite writes a report

DPL Manual 13


ResetCalculation resets the calculationsPostCommand adds a command to the command pipeExe executes a commandClearCommands clears the command pipeGetLanguage returns the current languageDelete deletes the objectEchoOn Re-activates the user interfaceEchoOff Freezes (de-activates) the user-interfaceGetGraphBoard Returns the currently active Graphics BoardGetCaseCommand Returns default command objectsprintf Outputs a formatted stringsprintf Returns a formatted stringError Emits a formatted errorWarn Outputs a formatted warningInfo Outputs a formatted informationNoFinalUpdate Prevents “EchoOn()” at end of executionGetLocalLib Returns a local library folderGetGlobalLib Returns a global library folder

More information about these commands can be found in the on-line manual.

1.8.2 DPL Set MethodsSet methods are functions for the set type parameters.

set . [SETMETHOD] ( arguments ) ;

The following [SETMETHOD] methods are available:

Clear removes all objects from the setIsIn searches for an object in the setAdd adds an objectRemove removes an objectCount returns the number of stored objectsFirst returns the first objectsNext returns the next objectFirstmatch returns the first matching objectNextmatch returns the next matching objectFirstFilt returns the first matching objectNextFilt returns the next matching objectSortToVar sorts the objects to a variable valueSortToClass sorts the objects to their classSortToName sorts the objects to their namesMarkInGraphics marks the objects in the graphic


1.8.3 Object MethodsThe object methods are specific for each type of object class. A result file object (ElmRes ), forinstance, 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


The following overview lists all the non-specific [OBJMETHOD] methods which are available forall classes.

Unom returns the nominal voltageMarkInGraphics marks the object in the graphicShowFullName prints the full database path and nameIsClass checks for a certain classAddCopy adds a copy of an objectCreateObject creates a new objectEdit opens the object dialogGetParent Returns the parent folderGetContents Returns the stored objectsHasResults returns if the object has result parametersIsRelevant Returns if the object is used for calculationsIsOutOfService Returns if the object is out of serviceGetConnectionCount Returns the number of electrical connectionsGetCubicle returns the object’s cubicleMove Moves an objects to this folderIsInFeeder Returns if the object belongs to the feederVarExists Checks a variable name


The following overview lists all the available object specific [OBJMETHOD] methods. Callingthese methods for the wrong class will result in an error message.

ComRes.ExportFullRange ComEcho.Execute ComEcho.OnComEcho.Off ComTime.ExecuteSetFilt.Get ComDpl.ExecuteIntMat.Get IntMat.SetIntMat.Init IntMat.ResizeIntMat.NRow IntMat.NColIntMat.RowLbl IntMat.ColLblIntVec.Get IntVec.SetIntVec.Init IntVec.ResizeIntVec.Size ElmCoup.CloseElmCoup.Open ElmCoup.IsOpenElmCoup.IsClosed ElmLne.HasRoutesOrSecElmLne.GetType ElmLne.IsCableElmLne.IsNetCoupling ElmLne.SetCorrTypLne.IsCable ElmLne.SetNomCurrElmRes.Clear ElmRes.WriteElmRes.Draw ElmRes.WriteDrawComRel3.Execute ComInc.ExecuteComLdf.Execute ComShc.ExecuteStaSwitch.Close StaSwitch.OpenStaSwitch.IsOpen StaSwitch.IsClosedSetFeeder.GetAll SetFeeder.GetBusesSetFeeder.GetBranches SetPath.GetAllSetPath.GetBusses SetPath.GetBranchesSetPath.AllBreakers SetPath.AllClosedBreakersSetPath.AllOpenBreakers SetSelect.AddRefSetSelect.Clear SetSelect.AllElmSetSelect.AllLines SetSelect.AllBarsSetSelect.AllLoads SetSelect.AllAsm

DPL Manual 15


SetSelect.AllSym SetSelect.AllTypLneSetSelect.All SetSelect.GetAllSetSelect.AllBreakers SetSelect.AllClosedBreakersSetSelect.AllOpenBreakers IntForm.SetText


LoadResData

void LoadResData (object O)Loads the data of a result file (ElmRes ) in memory. An error is produced when O is not aElmRes object.

Argumentsobject O (obligatory) : The result file object

Return valuevoid

ExampleExample.

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 30.73286 12.91360-0.040000 : 0.12676 30.73286 12.91360-0.030000 : 0.12676 30.73286 12.91360-0.020000 : 0.12676 30.73286 12.91360-0.010000 : 0.12676 30.73286 12.91360-0.000000 : 0.12676 30.73286 12.913600.010000 : 0.12676 30.73286 12.913600.020000 : 0.12676 30.73286 12.91360

DPL Manual 16


0.030000 : 0.12676 30.73286 12.913600.040000 : 0.12676 30.73286 12.913600.050000 : 0.12676 30.73286 12.91360

ResNvars

int ResNvars (object O)returns the number of variables (columns) in result file. An error is produced when O is not aElmRes object.

Argumentsobject 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 whenO is not a ElmRes object.

Argumentsobject O (obligatory) : The result file objectint 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 isnot a ElmRes object.

Argumentsdouble d (obligatory) : the returned valueobject O (obligatory) : The result file objectint iX (obligatory) : the row indexint iCrv (optional) : The curve number, which equals the variable or column number, firstcolumn value (time,index, etc.) is returned when omitted.

Return value0 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.

Argumentsstring ClassName (optional) : Class name of the object

Return valueThe found or created object.

ExampleThe following example gets the SetTime object.

object Obj;Obj = GetCaseObject(’SetTime’);

DPL Manual 17


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 calculationcase. Creates such a command when possible and when the calculation case not yet containsa command of the given class. Initializes newly created commands according to the projectsettings.

The buttons on the main menu for loadflow, short-circuit, transient simulation, etc. also openthe corresponding default command from the currently active study case. Using ”GetCaseC-ommand()” in a DPL script will return the same command.

Argumentsstring ClassName (optional) : Class name of the command

Return valueThe found or created command.

ExampleThe 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.

Argumentsnone

Return valuevoid

ExampleThe following example de-activates the user-interface to speed up the calculations, after whichthe 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 “NoFi-nalUpdate()” has been called.

Argumentsnone

DPL Manual 18


Return valuevoid

ExampleExample.

ExampleThe following example de-activates the user-interface to speed up the calculations, after whichthe 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.

Argumentsnone

Return valuevoid

ExampleExample.

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, inwhich case the complete local library folder is returned.

Argumentsstring ClassName (optional) : The classname of the objects for which the library folder issought

Return valueThe library folder

ExampleThe 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


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.

Argumentsstring ClassName (optional) : The classname of the objects for which the library folder issought

Return valueThe library folder

ExampleThe 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 sameformat string syntax.

The format string must contain a valid place holder for every given argument. The placeholderformat 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 decimaldigit, “‘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 decimaldigits. The number of digits before the decimal point depends on the magnitude of thenumber, and the number of digits after the decimal point depends on the requestedprecision.

’g’ For a double value. Printed format is the “f” or “e” format, whichever is more compact for thegiven value and precision. The e format is used only when the exponent of the value is lessthan 4 or greater than or equal to the precision argument. Trailing zeros are truncated, andthe 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


’+’ : 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.

ExampleThe 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.

ArgumentsString Format (obligatory) : The format stringString T (optional) : string argumentdouble X (optional) : double argumentint I (optional) : int argument

Return valueThe formatted string

The output format is defined by the format string. The passed arguments and the passed formatstring must match. An error message will be produced when, for instance, a format string for twostrings 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


sprintf

string sprintf (String Format , String T | double X | int I, ...)Returns a formatted string. The sprintf() command uses the C++ printf() formatting syntax.



ExampleThe following example redirects the output to a file. The filename is formatted from a path andthe name of the current calculation case. “Redirect” is an ComOp and “StopRedirect” is anComCl object in the DPL command

Redirect:f = sprintf(’%s%s.out’, ’c:\\MyDocuments\\results0813\\’, O:loc_name);Redirect.Execute();Form.WriteOut(Lines); ! write a reportStopRedirect.Execute(); ! stop redirection


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 willcontinue, but a pop-up error message box will appear at the end of execution.



ExampleThe following example writes an error to the output window.

Error(’Index could not be calculated.’);



DPL Manual 22


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.



ExampleThe following example writes an info message to the output window.

Info(’Trying to calculate first index...’);



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.



ExampleThe following example writes a warning message to the output window.

Warn(’No loads attached: using approximation.’);


DPL Manual 23



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.

Argumentsstring Format (obligatory) : The format stringobject aObj (optional) : An object which is used to get data fromset aSet (optional) : A set which is used to get objects from

Return value0 on success, 1 on error

The “Write” command is used to quickly output a line of formatted output, using the sameformatting language as is used for defining reports and result-boxes. See “The DIgSILENToutput language” in ?? , page ?? for more information.Because data or parameters of more than object is often written out, the DIgSILENT outputlanguage has the special macro “ACC(x)” to distinguish between these objects. Prior toexecution, 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. Ifthe 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 normaltext. The second line writes the name and loading of two lines. In this example, “ACC(1)” refersto 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


String Format (obligatory) : The format stringThe 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 valueThe formatted time string

ExampleThe 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.

Argumentsstring S (obligatory) : The string

strcmp

int strcmp (string S1, string S2, int count )Compares two strings.

Argumentsstring S1 (obligatory) : The first stringstring S1 (obligatory) : The second stringint 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


strcpy

String strcpy (string S, int start , int count )copies a substring from a string.

Argumentsstring S (obligatory) : The stringint start (obligatory) : The start position in Sint count (optional) : Number of characters to copy

Return valueThe copied substring

ExampleExample.

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.

Argumentsstring S1 (obligatory) : The stringstring S2 (obligatory) : The substring

Return valueThe first position in S1 where S2 was found, or -1 when S2 was not found.

ExampleExample.

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 papersize.

Argumentsint orientation (obligatory) : Paper orientation: 0: landscape, 1: portrait

Return valueThe 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 aremoved to the recycle bin.

Argumentsobject O (optional) : The object to deleteset S (optional) : The set of objects to delete

Return value

DPL Manual 26


voidExample

The following example removes all ”Dummy” fuses from the network. The ‘DummyType’ vari-able is a local variable in the DPL script. A set of objects-to-delete is created first and thenthat set is deleted. This has the advantage that one single entry in the recycle bin is createdwhich contains all deleted fuses. Manually restoring (‘undelete’) the deleted fuses, in case of amistake, 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] isreturned. If only x1 is given, the possible range is [0 ... x1] and with both x1 and x2, [x1 ... x2].

Argumentsdouble x1 (optional) : upper/lower limitdouble x1 (optional) : upper limit

Return valueA pseudo-random number

ExampleThe 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.

Argumentsnone

Return value0 if no load flow results are available

ExampleThe 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


Checks to see if the last RMS simulation results are still valid and available.Arguments

noneReturn value

0 if no RMS simulation results are availableExample

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.

Argumentsnone

Return value0 if no short-circuit results are available

ExampleThe 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.

Argumentsnone

Return value0 if no simulation results are available

ExampleThe 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 theobjects that are check-marked in the database browser. The set of calculation relevant objectsis determined by the currently active study case and the currently active grids.

Argumentsnone

Return value

DPL Manual 28


The set of all calculation relevant objectsExample

The following example writes the full path and name of all calculation relevant objects in theoutput 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.

Argumentsnone

Return valueA “IntCase” object

ExampleThe 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 combi-nation of all active grids in the study case.

Argumentsnone

Return valueA “ElmNet” object, or a ‘NULL’ object when no grids are active

ExampleThe 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

Argumentsnone

Return valueA “IntPrj” object

ExampleThe following example prints the name of the active project to the output window.

DPL Manual 29


object Prj;Prj = ActiveProject();Prj.ShowFullName();

ResetCalculation

void ResetCalculation ()Resets all calculations and destroys all volatile calculation results.

Argumentsnone

Return valuevoid (no return value)

Results that have been written to result objects (for display in graphs) will not be destroyed. Allresults 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 beexecuted after the DPL command has finished.

Argumentsstring Command (obligatory) : The command string


ExampleThe following command causes the DIgSILENT program to end after the DPL script has fin-ished.

PostCommand(’exit’);

Exe

void Exe (string Command )Immediately executes the command, bypassing the command pipe in the input window. TheDPL command will continue after the command has been executed. The ‘Exe’ command isprovided for compatibility and testing purposes only and should only be used by experiencedusers.

Argumentsstring Command (obligatory) : The command string


ExampleThe following command causes the output or graphical window to be printed.

PostCommand(’pr’);

ClearCommands

void ClearCommands ()Clears the command pipe of the input window.

Argumentsnone


DPL Manual 30


ExampleThe following command clears the input window.

ClearCommands();

ClearCommands

void ClearOutput ()Clears the output window.

Argumentsnone


ExampleThe following command clears the output window.

ClearOutput();

GetLanguage

int GetLanguage ()Returns the current program language setting.

Argumentsnone

Return value0 = English, 1 = German

ExampleThe following example displays a different message, depending on the language.

int err, lng;lng = GetLanguage();


if (lng) {output(’Loadflow command returned an error’);

} else {output(’Fehler im Lastfluss Kommando’);

}exit();

}

GetGraphBoard

SetDeskTop GetGraphBoard ()Returns the currently active Graphics Board.

Argumentsnone

Return valueThe graphics board object

ExampleThe following example looks for an opened Graphics Board and sets its default results to theresults object named ’Results’.

object aGrf;! Look for opened graphics board.aGrf=GetGraphBoard();

DPL Manual 31


if (aGrf) {! Set default results objectaGrf.SetResults(Results);

}

Also seeSetDeskTop.GetPage in 1.8.36, page 80SetDeskTop.SetResults in 1.8.36, page 81SetDeskTop.SetXVar in 1.8.36, page 81SetDeskTop.SetScaleX in 1.8.36, page 81SetDeskTop.SetAutoScaleX in 1.8.36, page 82SetDeskTop.SetAdaptX in 1.8.36, page 83

Clear

void Set.Clear ()Clears the set.

Argumentsnone

Return valuevoid

ExampleThe 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’.

Argumentsobject O (obligatory) : an object

Return value1 if the O is in the set.

ExampleThe 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


ArgumentsOne of the following two parameter has to be givenobject O (optional) : an objectset S (optional) : a set of objects

Return value0 on success

ExampleThe following example collects all loads and lines and the first breaker from the general DPLselection

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.

Argumentsobject O (obligatory) : the object to remove


ExampleThe 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.

Argumentsnone

Return valueThe number of objects in the set.

ExampleThe following example terminates the DPL script when the general selection is found to containno lines.

set S;int n;S = SEL.AllLines();

DPL Manual 33


n = S.Count();if (n=0) {

exit();}

Obj

int Set.Obj (int Index )Returns the object at the given index in the set.

Argumentsint Index (obligatory) : the index of the object.

Return valueThe 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

Argumentsnone

Return valueThe first object or 0 when the set is empty

ExampleThe following example writes the full names of all line in the general selection to the outputwindow.

set S;object OS = SEL.AllLines();O = S.First();while (O) {

O.ShowFullName();O = O.Next();

}

Next

Object Set.Next ()Returns the next object in the set

Argumentsnone

Return valueThe next object or 0 when the last object has been reached

ExampleThe following example writes the full names of all line in the general selection to the outputwindow.

set S;object OS = SEL.AllLines();O = S.First();while (O) {

O.ShowFullName();O = O.Next();

}

DPL Manual 34


Firstmatch

Object Set.Firstmatch (String WildCard )Returns the first object from the set which class name matches the wildcard

ArgumentsString WildCard (obligatory) : class name, possibly containing ‘*’ and ‘?’ characters

Return valueThe first matching object, or 0 when no such object

ExampleThe 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

Argumentsnone

Return valueThe next object, or 0 when no next object


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 maycontain (parts of the) name and classname.

ArgumentsString WildCard (obligatory) : class name, possibly containing ‘*’ and ‘?’ characters

Return valueThe first matching object, or NULL when no first object exists.

ExampleThe 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


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.

Argumentsnone

Return valueThe next object, or NULL when no next object exists.


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 tolower when R == 1, and reverse when R == 0.Arguments

int R (obligatory) : sorting directionstring V1 (obligatory) : first variable namestring V2 (optional) : , · · · , string V5 (optional) : 2nd..5th variable names


ExampleThe following example writes all lines to the output window, sorted to cable or OHL, nominalvoltage, 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) {


}

DPL Manual 36


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 reversewhen R = 1.Arguments

int R (obligatory) : sorting directionReturn value

0 on successExample

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) {


}

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 whenR = 1.Arguments

int R (obligatory) : sorting directionReturn value

0 on successExample

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) {


}

MarkInGraphics

void Set.MarkInGraphics ()Marks all objects in the set in the currently visible graphic by hatch crossing them.

Argumentsnone

Return valuevoid

ExampleThe following example will try to mark a set of lines in the single line graphic.

DPL Manual 37


set S;object O;S = SEL.AllLines();S.MarkInGraphics();

GetParent

object Object.GetParent ()Returns the parent folder.

Argumentsnone

Return valueThe parent folder object.

ExampleThe 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.

Argumentsnone

Return value‘true’ (1) or ‘false’ (0)

Exampleexample.

example is in preparation

GetConnectionCount

int Object.GetConnectionCount ()Returns the number of electrical connections.

Argumentsnone

Return valueThe number of connections.

Exampleexample.


GetCubicle

object Object.GetCubicle (int N)returns the cubicle in which the object is stored, or NULL when the object is not stored in acubicle.

Argumentsint N (obligatory) : The connection number.

DPL Manual 38


Return valueThe cubicle object or NULL.

Exampleexample.


Move

void Object.Move (object O | set S )Moves an object or a set of objects to this folder.

Argumentsobject O (optional) : Object to move set S (optional) : Set of objects to move

Return value0 on success, 1 on error.

Exampleexample.


IsInFeeder

void Object.Function (object Feeder [, double OptNested=0 ] )Returns if the object belongs to the feeder area defined by “Feeder”.

Argumentsobject Feeder (obligatory) : The Feeder definition object double OptNested (optional) :“Nested feeders” option (1 or 0)

Return value1 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”

Argumentsstring VarName (obligatory) : The name of the variable.

Return value1 when “VarName” is the name of a currently valid variable for this object.

ExampleThe 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


IsNode

int Object.IsNode ()Returns 1 if object is a node (terminal or busbar).

Argumentsnone

Return value1 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.

Argumentsstring VarName (obligatory) : The name of the variable int rows (obligatory) : The number ofrows for a vector or matrix int cols (optional) : The number of columns for a matrix

Return value0 when “VarName” is a valid variable name, else 1.

ExampleThe 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.0163720.016869 0.066832 0.016701 0.016576 0.016445 0.0164080.016594 0.016701 0.066738 0.016372 0.016408 0.0165160.016851 0.016576 0.016372 0.067073 0.016869 0.0165940.016576 0.016445 0.016408 0.016869 0.066832 0.0167010.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 thegiven row and column.

Arguments

DPL Manual 40


double|object X (obligatory) : The variable in which to return the resultstring VarName (obligatory) : The name of the variableint rows (obligatory) : The row number for a vector or matrixint cols (optional) : The column number for a matrix

Return value0 when “VarName” is a valid variable name and row number and column number are in range,else 1.

Examplesee “GetSize” in 1.8.3, page 40

lnm

string Object.lnm (string VanName )Returns the long variable name.

Argumentsstring VarName (obligatory) : The variable name

Return valueThe long name.

ExampleThe 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 41Also 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 ordialogs.


Return valueThe short name.

Examplesee “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.


Return valueThe unit name.

Example

DPL Manual 41


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 theobject’s container is empty or if the object is not capable of storing objects.

Argumentsnone

Return valueThe set of objects

ExampleThe 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.

Argumentsnone

Return valueThe nominal voltage

ExampleThe 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


Marks the object in the currently visible graphic by hatch crossing it.Arguments

noneReturn value

voidWhen 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.

Argumentsnone

Return valuevoid

Because the complete database path is written to the output window, the written names can beright clicked in the output window to edit the objects. This procedure is therefore useful forselecting 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.


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.

Argumentsstring ClassName (obligatory) : The name of the class.

Return value1 when the object is of the given class, 0 otherwise

ExampleThe following example write all overloaded lines and transformers to the output window, wherea different maximum loading is used for lines or transformers.

set S;object O;

DPL Manual 43


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.

Argumentsnone

Return valueThe class name of the object

ExampleThe 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 concatenationof ‘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 thecopy operation was successful. A “NULL” object is returned otherwise.

Copying a set of objects will respect all internal references between those objects. Copying aset of lines and their types, for example, will result in a set of copied lines and line types, wherethe copied lines will use the copied line types.

Argumentsset aSet (obligatory) : The set of objects to copyorobject aObj (obligatory) : The object to copystring | int NM1 (optional) : The first part of the new namestring | int NM2 (optional) : The next part of the new name...

DPL Manual 44


Return valuevoid

ExampleThe 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 ableto 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, ...)” willcreate a new object of class aClass and names it to the result of the concatenation of ‘nm1’,‘nm2’, etc.

Argumentsstring ClassNm (obligatory) : The class name of the object to createstring | int NM1 (optional) : The first part of the object namestring | int NM2 (optional) : The next part of the object name...

Return valueThe created object, or NULL when no object was created

ExampleThe following example creates a fuse in a set of cubicles. The new fuses will be named “FuseNr.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 ‘Exe-cute’ button disabled. The execution of the running DPL script will be halted until the edit dialogis closed again.Editing of DPL command objects ComDPL is not allowed.

Argumentsnone

Return valuevoid

DPL Manual 45


ExampleThe 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.

Argumentsnone

Return value0 when not used

ExampleThe 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.

Argumentsnone

Return value0 when not out of service

ExampleThe 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.

Argumentsset S (obligatory) : the set of objects

Return valueO on success, 1 on error.

GetObj

object ComOutage.GetObj (int i)Returns the object at position i in the list of objects.

Argumentsint i (obligatory) : the index is the list.

Return valueThe object at position i, or NULL when i is out of bound.

DPL Manual 46


1.8.5 ComSimoutage Methods

Reset

int ComSimoutage.Reset ()Resets the intermediate results of the outage simulation.

Argumentsnone


ExecuteCntcy

int ComSimoutage.ExecuteCntcy (object O)Executes an (additional) ComSimoutage, without resetting results. The results of the outageanalyses 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.

Argumentsobject O (obligatory) : The ComSimoutage object


AddCntcy

int ComSimoutage.AddCntcy (object O, string name )Executes an (additional) ComOutage, without resetting results. The results of the outage anal-ysis will be added to the intermediate results. Object “O” must be a ComOutage object. Ifthe outage definition has already been analyzed, it will be ignored. The ComOutage will berenamed to “name” when “name” is given.

Argumentsobject O (obligatory) : The ComOutage object string name (optional) : A name for the outage


SetLimits

int ComSimoutage.SetLimits (double vlmin , double vlmax , double ldmax )Sets the limits for the outage simulation.

Argumentsdouble vlmin (obligatory) : The minimum voltage double vlmax (obligatory) : The maximumvoltage double ldmax (obligatory) : The maximum loading

Return value1 always

ExampleThe following example analyses all selected outage definitions and adds the results to theintermediate results.

set s;object o;

s = SEL.GetAll(’ComOutage’);o = s.First();while (o) {

CA.AddCntcy(o);o = s.Next();

}

DPL Manual 47


1.8.6 IntCase Methods

Activate

int IntCase.Activate ()Activates the study case. Deactivates other study cases first.

Argumentsnone


Deactivate

int IntCase.Deactivate ()De-activates the study case.

Argumentsnone


1.8.7 IntPrj Methods

Activate

int IntPrj.Activate ()Activates the project. Deactivates other projects first.

Argumentsnone


Deactivate

int IntPrj.Deactivate ()De-activates the project.

Argumentsnone


1.8.8 TypAsm Methods

CalcElParams

int typAsm.CalcElParams ()Calculates the electrical parameters from the input data.

Argumentsnone

1.8.9 TypAsmo Methods

CalcElParams

int typAsmo.CalcElParams ()Calculates the electrical parameters from the input data.

DPL Manual 48


Argumentsnone

1.8.10 Elmfeeder Methods

GetAll

set Elmfeeder.GetAll (int iNested )Returns a set with all objects belonging to this feeder.

Argumentsint 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 valueThe 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.



GetObjs

set Elmfeeder.GetObjs (string ClassName int iNested )Returns a set with all objects of class ‘ClassName” which belong to this feeder.



1.8.11 ComNmink Methods

AddRef

void ComNmink.AddRef ([object O | set S])Adds shortcuts to the objects to the existing selection


Return valuevoid

ExampleThe following prepares and executes an outage simulation for all high loaded lines.

PrepOut.Clear();S = AllRelevant();O = S.Firstmatch(’ElmLne’);

DPL Manual 49


while (O) {if (O:c:loading>75) {

PrepOut.AddRef(O);}O = S.Nextmatch();

}PrepOut.Execute();

Clear

void ComNmink.Clear ()Empties the selection.

Argumentsnone

Return valuevoid

ExampleThe 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’.

ArgumentsString ClassName (obligatory) : The object class name.


ExampleThe following example writes all three winding transformers in the preparation command to theoutput window.

set S;object O;S = Prep.GetAll(’ElmTr3’);O = S.First();while (O) {


}

1.8.12 ElmComp Methods

Slotupd

int ElmComp.Slotupd ()

DPL Manual 50


Performs a slot update for the composite model, to automatically select available models forthe slots.

Argumentsnone

Return value0

Example

1.8.13 ComRes Methods

ExportFullRange

int ComRes.ExportFullRange ()Executes the export command for the whole data range.

Argumentsnone

Return value1

ExampleThe 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.

Argumentsnone

Return value1

1.8.14 ComEcho Methods

On

int ComEcho.On ()Turns on the user interface

ComEcho.On() is obsolete. Use the internal command EchoOn() instead.

Argumentsnone


ExampleThe following example turns off the user interface, calls a subroutine and turns it back on again.

DPL Manual 51


aEcho.Off();PerformCalculation();aEcho.On();

Off

int ComEcho.Off ()Turns off the user interface

ComEcho.Off() is obsolete. Use the internal command EchoOff() instead.

Argumentsnone


ExampleThe 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.

Argumentsnone

Return valuenone

ExampleThe following example executes a load flow for 14:30 at the current day (the computer’s systemdate).

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.

Argumentsnone

Return valuenone

ExampleThe following example executes a load flow for the current time and date (the computer’s systemtime).

DPL Manual 52


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.

Argumentsnone

Return valuenone

PrintAllVal

void IntMon.PrintAllVal ()Prints a description for all available variables to the output window.

Argumentsnone

Return valuenone

NVars

int IntMon.NVars ()returns the number of selected variables or, more exact, the number of lines in the variableselection text on the second page of the IntMon dialog, which should contain one variablename per line.

Argumentsnone

Return valueThe 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 pageof the IntMon dialog, which should contain one variable name per line.

Argumentsnone

Return valueThe variable name.

Example

DPL Manual 53


RemoveVar

int IntMon.RemoveVar (string name )Removes the variable “name” from the list of selected variable names.

ArgumentsThe variable name.

Return value1 when the variable name was not found, 0 otherwise.

Example

ClearVars

int IntMon.ClearVars ()Clears the list of selected variable names.

Argumentsnone

Return valuenone

Example

AddVar

int IntMon.AddVar (string name )Appends the variable “name” to the list of selected variable names.

ArgumentsThe variable name.

Return valuenone

Example

1.8.17 SetFilt Methods

Get

Set SetFilt.Get ()Returns a container with the filtered objects.

Argumentsnone

Return valueThe set of filtered objects

ExampleThe 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


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.

Argumentsuser defined arguments


ExampleThe following example performs a loadflow and calls the DPL subroutine “CheckVoltages” tocheck 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’ areout of range.

Argumentsint row (obligatory) : row in matrix: 1..NRow()int col (obligatory) : column in matrix: 1..NCol()

Return valueValue in matrix.

ExampleThe 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


}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 ifnecessary.

Argumentsint row (obligatory) : row number: 1..NRows()int col (obligatory) : col number: 1..NCols() double Vj (obligatory) : value


ExampleSee “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.

Argumentsint NRows (obligatory) : number of rowsint NCols (obligatory) : number of columns



Resize

int IntMat.Resize (int NRows, int NCols)Resizes the matrix. Existing values will not be changed. Added values will be set to 0.

Argumentsint NRows (obligatory) : number of rowsint NCols (obligatory) : number of columns


ExampleThe 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


Returns the number of rows in the matrix. The function “NRow()” replaces the obsolete function“SizeX()”.

Argumentsnone

Return valueThe number of rows


NCol

int IntMat.NCol ()Returns the number of columns in the matrix. The function “NCol()” replaces the obsoletefunction “SizeY()”.

Argumentsnone

Return valueThe number of columns


RowLbl

int IntMat.RowLbl (String S, int R)Sets the label of the R’th row.

ArgumentsString S (obligatory) : Labelstringint R (obligatory) : Number of the row


ExampleThe 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.

ArgumentsString S (obligatory) : Labelstringint C (obligatory) : Number of the column


ExampleThe 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


double IntVec.Get (int i)Returns the value at index i.

Argumentsint i (obligatory) : Vector index.

Return valueValue at index i.

ExampleThe 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()]

Argumentsint i (obligatory) : Vector index.double V (obligatory) : The value to set.


ExampleSee “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.

Argumentsint Size (obligatory) : The initial size.



Resize

int IntVec.Resize (int Size)Resizes the vector. Added values are set to 0.0.

Argumentsnone

DPL Manual 58



ExampleThe 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.

Argumentsnone

Return valueThe size of the vector


1.8.21 ElmCoup Methods

Close

int ElmCoup.Close ()Closes the buscoupler

Argumentsnone


ExampleThe 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

Argumentsnone

DPL Manual 59



ExampleThe 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.

Argumentsnone

Return value1 when open, 0 when closed

ExampleSee “ElmCoup.Close” in 1.8.21, page 59 for an example

IsClosed

int ElmCoup.IsClosed ()Returns 1 when the coupler is closed.

Argumentsnone

Return value1 when closed, 0 when open

ExampleSee “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.

Argumentsnone

Return value0 when the line is a single line, 1 when it is subdivided into routes.

ExampleThe following example reports all lines with routes.

set S; object O; int i;S = AllRelevant();O = S.Firstmatch(’ElmLne’);

DPL Manual 60


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.

Argumentsnone

Return value0 when the line is a single line, 1 when it is subdivided into routes, 2 when into sections.

ExampleThe 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.

Argumentsnone

Return valueThe TypLne object

ExampleThe 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.

Argumentsnone

Return value

DPL Manual 61


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.

Argumentsnone

Return value1 when the line is a coupler, otherwise 0.

ExampleThe 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.

Argumentsnone

Return value0 on success, 1 on error;

ExampleThe following example sets a correction factor.

BuriedLine.SetCorr();

CreateFeederWithRoutes

DPL Manual 62


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.

Argumentsdouble 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 sideint sw1 (optional) : when true, a switch is inserted on the other side

Return value0 on success, 1 on error;

Example

1.8.23 ElmLneroute Methods

IsCable

int ElmLneroute.IsCable ()Returns if the route is a cable.

Argumentsnone

Return value1 when a cable, otherwise 0.

ExampleThe 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.

Argumentsnone

Return value1 when subdivided sections, 0 otherwise

ExampleThe 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


1.8.24 TypLne Methods

IsCable

int TypLne.IsCable ()Returns if the line type is a cable type.

Argumentsnone

Return value1 when the line type is a cable type, otherwise 0.

ExampleThe 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.

Argumentsnone


ExampleThe 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 DPLcommand object.

Argumentsnone


ExampleThe following example initializes the result object.

Res.Init();

Clear

int ElmRes.Clear ()Clears the result object.

Argumentsnone

DPL Manual 64



ExampleThe following example clears the result object.

Res.Clear();

Write

int ElmRes.Write ()Writes the current results to the result object.

Argumentsnone


ExampleThe following example performs load flows for a number of load levels and writes the results tothe 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.

Argumentsnone


ExampleThe following example updates the graphics every 10 steps to save time and yet follow theresults while calculating

double i,n;Ld:pini = LoadMin;i = 1;n = 0;while ({Ld:pini<LoadMax}.and.{i}) {


Res.Write();n += 1;Ld:pini += LoadStep;

}if (n>9) {

Res.Write();n = 0;

DPL Manual 65


}}

WriteDraw

int ElmRes.WriteDraw ()Writes to and displays the result objects.

Argumentsnone


ExampleThe following example performs load flows for a number of load levels and writes the results tothe result object

double P;double i;P = LoadMin;i = 1;while ({P<LoadMax}.and.{i}) {


Res.WriteDraw();P += LoadStep;

}}

SetAsDefault

void ElmRes.SetAsDefault ()Sets this results object as the default results object.

Argumentsnone

Return valuenone

Example

AddVars

void ElmRes.AddVars (object O, string v1 [,string v2,...])Adds variables to the list of monitored variables for the Result object.

Argumentsobject O (obligatory) : an object.string v1 (obligatory) : variable name for object O.string v2..v9 (optional) : optional further variables names for object O.

Return valuenone

Exampleobject Res; Res = MyResults(); Res.AddVars(MyLine,’m:Ikss:busshc’,’m:I:busshc’);

GetObj

object ElmRes.GetObj (int index )

DPL Manual 66


Returns the objects used in the result file. Positive index means objects for which parametersare being monitored (i.e. column objects). Negative index means objects which occur in writtenresult rows as values.

Argumentsint index (obligatory) : index of the object.

Return valuethe object, when found.

Example

1.8.26 ElmZone Methods

GetAll

set ElmZone.GetAll ()Returns all objects which belong to this zone.

Argumentsnone


GetBuses

set ElmZone.GetBuses ()Returns all buses which belong to this zone.

Argumentsnone


GetBranches

set ElmZone.GetBranches ()Returns all branches which belong to this zone.

Argumentsnone


GetObjs

set ElmZone.GetObjs (string classname )Returns all objects of the given class which belong to this zone.

Argumentsstring classname (obligatory) : name of the class.


1.8.27 ComRel3 Methods

Execute

int ComRel3.Execute ()Executes the Level 3 reliability assessment calculations

Arguments

DPL Manual 67


noneReturn value

0 on successExample

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.

Argumentsnone


ExampleThe following example executes the ComInc command named ‘Inc’

Inc.Execute();

1.8.29 ComLdf Methods

Execute

int ComLdf.Execute ()Execute a load flow calculation

Argumentsnone


ExampleThe following example executes the ComLdf command name ‘Ldf’

Ldf.Execute();

1.8.30 ComShc Methods

Execute

int ComShc.Execute ()Executes a short-circuit calculation

Argumentsnone


ExampleThe following example execute the ComShc command named ‘Shc’

Shc.Execute();

DPL Manual 68


1.8.31 StaSwitch Methods

Close

int StaSwitch.Close ()Closes the switch

Argumentsnone


ExampleThe 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 ()

Argumentsnone


ExampleThe 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.

Argumentsnone

Return value

DPL Manual 69


1 when open, 0 when closedExample

See “StaSwitch.Close” in 1.8.31, page 69 for an example

IsClosed

int StaSwitch.IsClosed ()Checks if the switch is closed.

Argumentsnone

Return value1 when closed, 0 when open

ExampleSee “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.

Argumentsnone

Return valueThe set with all objects

ExampleThe following example gets all feeder objects

set S;S = Feeder1.GetALL();

GetBuses

Set SetFeeder.GetBuses ()Returns all busbars and terminals in the feeder.

Argumentsnone

Return valueThe set with all busbars and terminals

ExampleThe following example gets all feeder bars

set S;S = Feeder1.GetBusses();

GetBranches

Set SetFeeder.GetBranches ()Returns all branches in a feeder.

Argumentsnone

Return valueThe set with all branches

ExampleThe following example gets all feeder branches

DPL Manual 70


set S;S 0 Feeder1.GetBranches();

1.8.33 SetPath Methods

GetAll

Set SetPath.GetAll ()Returns all objects in the path definition.

Argumentsnone


ExampleThe 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) {


}

GetBusses

Set SetPath.GetBusses ()Returns all busbars and terminals in the path definition.

Argumentsnone


ExampleThe following example writes all busbars and terminals in the path definition to the outputwindow.

set S;object O;S = aPath.GetBusses();O = S.First();while (O) {


}

GetBranches

Set SetPath.GetBranches ()Returns all branches in the path definition.

Argumentsnone


ExampleThe following example writes all branches in the path definition to the output window.

DPL Manual 71


set S;object O;S = aPath.GetBranches();O = S.First();while (O) {


}

AllBreakers

Set SetPath.AllBreakers ()Returns all breakers in the path definition.

Argumentsnone


ExampleThe 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) {


}

AllClosedBreakers

Set SetPath.AllClosedBreakers ()Returns all closed breakers in the path definition.

Argumentsnone


ExampleThe 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) {


}

AllOpenBreakers

Set SetPath.AllOpenBreakers ()Returns all open breakers in the path definition.

Argumentsnone

Return value

DPL Manual 72


The set of objectsExample

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) {


}

1.8.34 SetSelect Methods

AddRef

void SetSelect.AddRef ([object O | set S])Adds a reference to the objects to the existing selection


Return valuevoid

ExampleThe 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.

Argumentsnone

Return valuevoid

ExampleThe 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.

Argumentsnone

DPL Manual 73



ExampleThe 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) {


}

AllLines

Set SetSelect.AllLines ()Returns all lines and line routes in the selection.

Argumentsnone


ExampleThe following example writes all lines and line routes in the general DPL selection to the outputwindow.



}

AllBars

Set SetSelect.AllBars ()Returns all busbars and terminals in the selection.

Argumentsnone


ExampleThe 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) {


}

DPL Manual 74


AllLoads

Set SetSelect.AllLoads ()Returns all loads in the selection.

Argumentsnone


ExampleThe 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) {


}

AllAsm

Set SetSelect.AllAsm ()Returns all asynchronous machines in the selection.

Argumentsnone


ExampleThe following example writes all asynchronous machines in the general DPL selection to theoutput window.

set S;object O;S = SEL.AllAsm();O = S.First();while (O) {


}

AllSym

Set SetSelect.AllSym ()Returns all synchronous machines in the selection.

Argumentsnone


ExampleThe following example writes all synchronous machines in the general DPL selection to theoutput window.

set S;object O;S = SEL.AllSym();O = S.First();while (O) {

DPL Manual 75



}

AllTypLne

Set SetSelect.AllTypLne ()Returns all line types in the selection.

Argumentsnone


ExampleThe 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) {


}

All

Set SetSelect.All ()Returns all objects in the selection.

Argumentsnone


ExampleThe 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) {


}

GetAll

Set SetSelect.GetAll (String ClassName )Returns all objects in the selection which are of the class ‘ClassName’.

ArgumentsString ClassName (obligatory) : The object class name.


ExampleThe following example writes all three winding transformers in the general DPL selection to theoutput window.

DPL Manual 76


set S;object O;S = SEL.GetAll(’ElmTr3’);O = S.First();while (O) {


}

AllBreakers

Set SetSelect.AllBreakers ()Returns all breakers in the selection.

Argumentsnone


ExampleThe 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) {


}

AllClosedBreakers

Set SetSelect.AllClosedBreakers ()Returns all closed breakers in the selection.

Argumentsnone


ExampleThe following example writes all closed breakers in the general DPL selection to the outputwindow.

set S;object O;S = SEL.AllClosedBreakers();O = S.First();while (O) {


}

AllOpenBreakers

Set SetSelect.AllOpenBreakers ()Returns all open breakers in the selection.

Argumentsnone

Return value

DPL Manual 77


The set of objectsExample

The following example writes all open breakers in the general DPL selection to the outputwindow.

set S;object O;S = SEL.AllOpenBreakers();O = S.First();while (O) {


}

1.8.35 IntForm Methods

SetText

int IntForm.SetText (String Text )Sets the format text of a report form.

ArgumentsString Text (obligatory) : The format text string


ExampleThe 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 theobjects in the ListSet and the PoolSet. The ListSet is used in the _EXTERNAL macro. All formatlines between the $LOOP,_EXTERNAL and the $END macro’s will be written for each object in theListset, which is therefore called the ‘sequential set’. In the format text itself, objects from thePoolSet may be referenced directly by the “ACC(x)” macro, which is replaced by the x’th object inthe PoolSet. The PoolSet is therefore called the ‘random access set’. The ListSet or PoolSet maybe empty.The command object that is normally reached by the macro “DEF” in report forms will alwaysreturn the main DPL command that is running at the moment, even when the ‘WriteOut’ call ismade in a DPL subscript.

Arguments

DPL Manual 78


Set ListSet (obligatory) : The sequential set of objectsSet PoolSet (optional) : The random access set of objects


ExampleThe following example reports the loading of a list of objects for a certain load condition. Theobjects for the loading are sequentially listed. The load conditions are reported for a special setof 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 GraphicsBoard. The object “O” is typically a ViPage object but, as only its name is used, it may be anyother type of object.

Arguments

DPL Manual 79


string name (obligatory) : Name of graphics page.object O (optional) : An object.


ExampleThe following example activates all pages in the graphics board one by one and exports themas 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.

Argumentsstring name (obligatory) : Filename without extension.

Return valuenone.

ExampleSee “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 pagewith the name was found.

Argumentsstring name (obligatory) : Name of the page.int create=1 (optional) : create ¿ 0 =¿ create panel if not exists.

Return valueVirtual Instrument Panel (SetVipage)

ExampleThe following example looks for the Virtual Instrument Panels named Voltage, Current andPower 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 PanelsaPageV=aGrf.GetPage(’Voltage’,1);aPageC=aGrf.GetPage(’Current’,1);

DPL Manual 80


aPageP=aGrf.GetPage(’Power’,1);}

SetResults

void SetDesktop.SetResults (object res )Sets default Results (ElmRes) of Graphics Board.

Argumentsobject res (obligatory) : Results to set (ElmRes) or NULL to reset.

Return valuenone

ExampleThe following example looks for an opened Graphics Board and sets its default results to theresults object named ’Results’.

object aGrf;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {

! Set default results objectaGrf.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.

Argumentsobject obj (optional) : x-axis objectstring varname (optional) : variable of obj

Return valuenone

ExampleThe following examples look for an opened Graphics Board and set its x-axis variable. The firstexample sets a user defined x-axis variable. The second one sets the default x-axis (time).


! Set user defined x-axis variableaGrf.SetXVar(line,’m:U1:bus1’);

}


! Set default x-axis variable (time)aGrf.SetXVar();

}

SetScaleX

void SetDesktop.SetScaleX (double min , double max , int log )

DPL Manual 81


Sets scale of x-axis. Invalid arguments like neg. limits for log. scale are not set. No arguments=¿ automatic scaling.

Argumentsdouble min (optional) : Minimum of x-scale.double max (optional) : Maximum of x-scale.int log (optional) : ¿ 0 =¿ x-scale is logarithmic.

Return valuenone

ExampleThe following examples look for an opened Graphics Board and set its x-axis scale. There arethree different examples. 1. Example: Scale x-axis automatically 2. Example: Set minimum to0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to 1000. Changes to alog. scale

! Scale x-axis automaticallyobject aGrf;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {

! Scale automaticallyaGrf.SetScaleX();

}

! Set minimum and maximum without changing map modeobject aGrf;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {

! Set minimum and maximumaGrf.SetScaleX(2,10);

}

! Set minimum and maximum, change to log. scaleobject aGrf;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {

! Set minimum and maximumaGrf.SetScaleX(1,1000,1);

}

SetAutoScaleX

void SetDesktop.SetAutoScaleX (int mode )Sets the automatic scaling mode of the x-scale.

Argumentsint mode (obligatory) : Possible values: 0 never, 1 after simulation, 2 during simulation

Return valuenone

ExampleThe following example looks for an opened Graphics Board and sets its auto scale mode to off.

! Set autoscale mode to offobject aGrf;

DPL Manual 82


! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {

! Turn off automatic scaling of x-scaleaGrf.SetAutoScaleX(0);

}

SetAdaptX

void SetDesktop.SetAdaptX (int mode , double trigger )Sets the adapt scale option of the x-scale.

Argumentsint mode (obligatory) : Possible values: 0 off, 1 ondouble trigger (optional) : Trigger value, unused if mode is off or empty.

Return valuenone

ExampleThe following example looks for an opened Graphics Board and sets its adapt scale option.


! Turn on adapt scale, use a trigger value of 3aGrf.SetAdaptX(1,3);! Turn off adapt scaleaGrf.SetAdaptX(0,3);! Turn on adapt scale again, do not change the trigger valueaGrf.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.

Argumentsstring name (obligatory) : Name of Virtual Instrumentstring class=’VisPlot’ (optional) : classname of Virtual Instrument.int create=1 (optional) : create ¿ 0 =¿ create panel if not exists.

Return valueVirtual Instrument.

ExampleThe following example looks for a Plot (VisPlot) named RST on a Virtual Instrument Panel. Theplot 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 VoltageaPage=aGrf.GetPage(’Voltage’,1);if (aPage) {

! Get plot named RST. Create the plot if not exists

DPL Manual 83


aPlot=aPage.GetVI(’RST’,’VisPlot’,1);}

}

SetStyle

void SetVipage.SetStyle (string name )Sets style folder of Virtual Instrument Panel.

Argumentsstring name (obligatory) : Name of style.

Return valuenone

ExampleThe 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) {


! Set style named PaperaPage.SetStyle(’Paper’);

}}

SetTile

void SetVipage.SetTile (int tile )Rearranges the Virtual Instruments.

Argumentsint tile=1 (optional) : tile ¿ 0 =¿ tile Virtual Instruments, tile=0 =¿ arrange them horizontally.

Return valuenone

ExampleThe following example looks for a Virtual Instrument Panel named Voltage and rearranges theVirtual 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


SetResults

void SetVipage.SetResults (object res )Sets default Results (ElmRes) of Virtual Instrument Panel.

Argumentsobject res (obligatory) : Results to set (ElmRes) or NULL to reset.

Return valuenone

ExampleThe following example looks for a Virtual Instrument Panel named Voltage and resets its defaultresults.



! Set default results on pageaPage.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.


Return valuenone

ExampleThe following examples look for a Virtual Instrument Panel named Voltage and set the x-axisvariable. The first example sets a user defined x-axis variable of the Virtual Instrument Panel.The second one sets the default x-axis (time).



! Set x-scale from 100 to 120aPage.SetScaleX(100,120);! Set x-scale variableaPage.SetXVar(line,’m:U1:bus1’);

}}

object aGrf;object aPage;

DPL Manual 85




! Set x-scale from 100 to 120aPage.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. Noinput arguments =¿ automatic scaling.


Return valuenone

ExampleThe following examples look for a Virtual Instrument Panel named Voltage and set its x-axisscale. There are three different examples. 1. Example: Scale x-scale automatically. 2. Exam-ple: Set minimum to 0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to1000. Changes to a log. scale

! Scale x-scale automatically.object aPage;object aGrf;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {


! Automatic scalingaPage.SetScaleX();

}}

! Set minimum and maximum without changing map modeobject aPage;object aGrf;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {


! Set minimum and maximumaPage.SetScaleX(0,20);

DPL Manual 86


}}

! Set minimum and maximum, set map mode to log.object aPage;object aGrf;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {


! Set minimum and maximum, change to log. scaleaPage.SetScaleX(1,1000,1);

}}

SetDefScaleX

void SetVipage.SetDefScaleX ()Sets default scale of x-axis (SetDesktop).

Argumentsnone

Return valuenone

ExampleThe 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-scaleobject aPage;object aGrf;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {


! 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.


Return valuenone

ExampleThe following examples look for a Virtual Instrument Panel named Voltage and change itsauto scale mode. The first example works fine, the second one generates an error messagebecause the x-scale is unused.

DPL Manual 87


! Set autoscale mode Offobject aGrf;object aPage;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {


! Set limits to change x-scale of page to used scaleaPage.SetScaleX(0,10);! Turn off automatic scaling of x-scaleaPage.SetAutoScaleX(0);

}}

! Try to set autoscale mode to onlineobject aGrf;object aPage;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {


! Reset option ’Use local x-Axis’ of Virtual Instrument PanelaPage.SetDefScaleX();! Try to set automatic scaling of x-scale to OnlineaPage.SetAutoScaleX(2);

}}

SetAdaptX

void SetVipage.SetAdaptX (int mode , double trigger )Sets the adapt scale option of the x-scale for local scales.

Argumentsint mode (obligatory) : Possible values: 0 off, 1 ondouble trigger (optional) : Trigger value, unused if mode is off or empty

Return valuenone

ExampleThe following examples look for a Virtual Instrument Panel named Voltage and sets its adaptscale option. The first example works fine, the second one generates an error message be-cause the x-scale is unused.

! Modify adapt scale option of Virtual Instrument Panelobject aPage;object aGrf;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {


DPL Manual 88


! Set x-scale limits to set option ’Use local x-Axis’aPage.SetScaleX(0,20);! Turn on adapt scale, use a trigger value of 3aPage.SetAdaptX(1,3);! Turn off adapt scaleaPage.SetAdaptX(0,3);! Turn on adapt scale again, do not change the trigger valueaPage.SetAdaptX(1);

}}

! Try to turn on adapt scaleobject aPage;object aGrf;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {


! Reset option ’Use local x-Axis’ of Virtual Instrument PanelaPage.SetDefScaleX();! Try to turn on adapt scale, use a trigger value of 3! Leads to error message because scale is not localaPage.SetAdaptX(1,3);

}}

GetScaleObjX

object SetVipage.GetScaleObjX ()Returns used object defining x-scale. The returned object is either the Virtual Instrument Panelitself or the Graphics Board.

Argumentsnone

Return valueObject defining the x-scale.

ExampleThe following examples look for a Virtual Instrument Panel named Voltage and get the usedx-scale object. GetScaleObjX of the first example gets the Graphics Board, in the second onethe Virtual Instrument Panel itself is returned.

! Used scale is Graphics Boardobject aPage;object aGrf;object aScale;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {


! Reset option ’Use local x-Axis’ of Virtual Instrument PanelaPage.SetDefScaleX();! Get object defining scale

DPL Manual 89


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 itselfobject aPage;object aGrf;object aScale;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {


! Set x-scale to change it to localaPage.SetScaleX(1,100);! Get object defining scaleaScale=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 addedstring V1..V8 (obligatory) : One to eight variables names for object Oorstring V (obligatory) : Variable name which is added for objects O1..O8object O1..O8 (obligatory) : One to eight objects variable V

Return valuenone

Using AddVars a single object with different variables or one variable with several objects can beadd to the Subplot. To append a list of variables of a single object the first input parameter is anobject followed by a list of maximum nine variables. To append the same variable for severalobjects the first input parameter is the variable name followed by a list of maximum nine objects.

DPL Manual 90


ExampleThe following examples look for a Subplot named RST on Virtual Instrument Panel namedVoltage 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 aPage;object aGrf;object aPlot;object aScale;

! Note: object load is an interface parameter, therefore it is not defined here



! Get subplot named ’RST’aPlot=aPage.GetVI(’RST’,’VisPlot’,1);if (aPlot) {

! Clear variable listaPlot.Clear();! Append variablesaPlot.AddVars(load, ’m:U1:bus1’,’m:U1l:bus1’,’m:phiu1:bus1’);

}}

}

! Append several objects with one single variable


! objects load,line and xnet are interface parameters,! therefore they are not defined here.




! Clear variable listaPlot.Clear();! Append variables

DPL Manual 91


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 andvariables which are already in the plot are not added.

Argumentsobject Res (obligatory) : Result objectplusobject O (obligatory) : Object for which variables V1..V8 are addedstring V1..V8 (obligatory) : One to eight variables names for object Oorstring V (obligatory) : Variable name which is added for objects O1..O8object O1..O8 (obligatory) : One to eight objects variable V

Return valuenone

See “AddResVars” in 1.8.38, page 92 for more information.

Clear

void VisPlot.Clear ()Removes all variables from SubPlot

Argumentsnone

Return valuenone

ExampleThe following example looks for a Subplot named RST on Virtual Instrument Panel namedVoltage and removes all variables from the plot.

! Remove all variables in Subplot named RST on Virtual Instrument Panel named Voltageobject aPage;object aGrf;object aPlot;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {


! Get Subplot named ’RST’aPlot=aPage.GetVI(’RST’,’VisPlot’,1);if (aPlot) {

! Remove all variables from SubplotaPlot.Clear();

}}

}

SetXVar

DPL Manual 92


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.


Return valuenone

ExampleThe following examples look for a Subplot named RST and set its x-axis variable. The firstexample sets a user defined x-axis variable of the plot. The second one sets the default x-axisvariable (time).

! Set user defined x-axis variableobject aPage;object aGrf;object aPlot;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



! Set x-scale from 100 to 120aPlot.SetScaleX(100,120);! Set x-scale variableaPlot.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) {



! Set x-scale from 100 to 120aPlot.SetScaleX(100,120);! Set default x-scale variable (time)aPlot.SetXVar();

}}

}

SetScaleX

DPL Manual 93


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. Noarguments =¿ automatic scaling.


Return valuenone

ExampleThe following examples look for a Subplot named ’RST’ and set its x-scale. There are threedifferent examples. 1. Example: Perform auto scaling on x-axis. 2. Example: Set minimum to0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to 1000. Changes to alog. scale

! Automatic scaling of x-scaleobject aPage;object aGrf;object aPlot;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



! Automatic scalingaPlot.SetScaleX();

}}

}

! Set minimum and maximum without changing map modeobject aPage;object aGrf;object aPlot;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



! Set minimum and maximumaPlot.SetScaleX(0,20);

}}

}

! Set minimum and maximum, set map mode to log.

DPL Manual 94


object aPage;object aGrf;object aPlot;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



! Set minimum and maximum, change to log. scaleaPlot.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. Noarguments =¿ automatic scaling.

Argumentsdouble min (optional) : Minimum of y-scale.double max (optional) : Maximum of y-scale.int log (optional) : ¿ 0 =¿ y-scale is logarithmic.

Return valuenone

ExampleThe following examples look for a Subplot named ’RST’ and set its y-axis scale. There are threedifferent examples. 1. Example: Perform auto scaling on y-Axis. 2. Example: Set minimum to0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to 1000. Changes to alog. scale

! Automatic scaling of y-scaleobject aPage;object aGrf;object aPlot;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



! Automatic scalingaPlot.SetScaleY();

}}

}

! Set minimum and maximum without changing map mode

DPL Manual 95


object aPage;object aGrf;object aPlot;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



! Set minimum and maximumaPlot.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) {



! Set minimum and maximum, change to log. scaleaPlot.SetScaleY(1,1000,1);

}}

}

SetDefScaleX

void VisPlot.SetDefScaleX ()Sets default scale of x-axis (SetDesktop or SetVipage).

Argumentsnone

Return valuenone

ExampleThe 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 InstrumentPanel (SetVipage).

! Reset option ’Use local x-Axis’object aPage;object aGrf;object aPlot;! Look for opened graphics board.

DPL Manual 96


aGrf=GetGraphBoard();if (aGrf) {



! Reset option ’Use local x-Axis’aPlot.SetDefScaleX();

}}

}

SetDefScaleY

void VisPlot.SetDefScaleY ()Sets default scale of y-axis (IntPlot).

Argumentsnone

Return valuenone

ExampleThe following example looks for a Subplot named ’RST’ and sets its option ’Use local y-Axis’ to0. 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) {



! 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.


Return valuenone

ExampleThe following example looks for a Subplot named ’RST’ and change its auto scale mode. Thefirst example works fine, the second one generates an error message because the x-scale isunused.

DPL Manual 97


! Set autoscale mode of x-scale to offobject aPage;object aGrf;object aPlot;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



! Set limits to change x-scale of page to used scaleaPlot.SetScaleX(0,10);! Turn off automatic scaling of x-scaleaPlot.SetAutoScaleX(0);

}}

}

! Try to set autoscale mode of x-scale to onlineobject aPage;object aGrf;object aPlot;! Look for opened Graphics Board.aGrf=GetGraphBoard();if (aGrf) {



! Reset option ’Use local x-Axis’ of SubplotaPlot.SetDefScaleX();! Try to set automatic scaling of x-scale to OnlineaPlot.SetAutoScaleX(2);

}}

}

SetAutoScaleY

void VisPlot.SetAutoScaleY (int mode )Sets automatic scaling mode of the y-scale for local scales.


Return valuenone

ExampleThe following example looks for a Subplot named ’RST’ and change its auto scale mode. Thefirst example works fine, the second one generates an error message because the y-scale isunused.

DPL Manual 98


! Set autoscale mode of y-scale to offobject aPage;object aGrf;object aPlot;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



! Set limits to change y-scale of page to used scaleaPlot.SetScaleY(0,10);! Turn off automatic scaling of y-scaleaPlot.SetAutoScaleY(0);

}}

}

! Try to set autoscale mode of y-scale to onlineobject aPage;object aGrf;object aPlot;! Look for opened Graphics Board.aGrf=GetGraphBoard();if (aGrf) {



! Reset option ’Use local y-Axis’ of SubplotaPlot.SetDefScaleY();! Try to set automatic scaling of y-scale to OnlineaPlot.SetAutoScaleY(2);

}}

}

SetAdaptX

void VisPlot.SetAdaptX (int mode , double trigger )Sets the adapt scale option of the x-scale for local scales.

Argumentsint mode (obligatory) : Possible values: 0 off, 1 ondouble trigger (optional) : Trigger value, unused if mode is off or empty

Return valuenone

ExampleThe following examples look for a Subplot named ’RST’ and change its adapt scale option. Thefirst example works fine, the second one generates an error message because the x-scale isunused.

DPL Manual 99


! Modify adapt scale option of Subplotobject aPage;object aGrf;object aPlot;! Look for opened Graphics Board.aGrf=GetGraphBoard();if (aGrf) {



! Set x-scale limits to set option ’Use local x-Axis’aPlot.SetScaleX(0,20);! Turn on adapt scale, use a trigger value of 3aPlot.SetAdaptX(1,3);! Turn off adapt scaleaPlot.SetAdaptX(0,3);! Turn on adapt scale again, do not change the trigger valueaPlot.SetAdaptX(1);

}}

}

! Try to turn on adapt scale of x-scaleobject aPage;object aGrf;object aPlot;! Look for opened Graphics Board.aGrf=GetGraphBoard();if (aGrf) {



! Reset option ’Use local x-Axis’ of SubplotaPlot.SetDefScaleX();! Try to turn on adapt scale, use a trigger value of 3! Leads to error message because scale is not localaPlot.SetAdaptX(1,3);

}}

}

SetAdaptY

void VisPlot.SetAdaptY (int mode , double offset )Sets the adapt scale option of the y-scale for local scales.

Argumentsint mode (obligatory) : Possible values: 0 off, 1 ondouble trigger (optional) : Offset, unused if mode is off or empty

Return value

DPL Manual 100


noneExample

The following examples look for a Subplot named ’RST’ and change its adapt scale option ofthe y scale. The first example works fine, the second one generates an error message becausethe y-scale is unused.

! Modify adapt scale option of Subplotobject aPage;object aGrf;object aPlot;! Look for opened Graphics Board.aGrf=GetGraphBoard();if (aGrf) {



! Set y-scale limits to set option ’Use local y-Axis’aPlot.SetScaleY(0,20);! Turn on adapt scale, use a trigger value of 3aPlot.SetAdaptY(1,3);! Turn off adapt scaleaPlot.SetAdaptY(0,3);! Turn on adapt scale again, do not change the trigger valueaPlot.SetAdaptY(1);

}}

}

! Try to turn on adapt scale for y-scaleobject aPage;object aGrf;object aPlot;! Look for opened Graphics Board.aGrf=GetGraphBoard();if (aGrf) {



! Reset option ’Use local y-Axis’ of SubplotaPlot.SetDefScaleY();! Try to turn on adapt scale, use a trigger value of 3! Leads to error message because scale is not localaPlot.SetAdaptY(1,3);

}}

}

GetScaleObjX

DPL Manual 101


object VisPlot.GetScaleObjX ()Returns used object defining x-scale. The returned object is the Subplot itself, the VirtualInstrument Panel or the Graphics Board.

Argumentsnone

Return valueObject defining the x-scale.

ExampleThe following examples look for a Subplot named ’RST’ and get the used x-scale object. Thereare three different examples.1. Example: Used scale is Graphics Board 2. Example: Used scale is Virtual Instrument Panel3. Example: Used scale is Subplot itself.

! Used scale is Graphics Boardobject aPage;object aGrf;object aPlot;object aScale;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {


! Reset option ’Use local x-Axis’ of Virtual Instrument PanelaPage.SetDefScaleX();! Get subplot named ’RST’aPlot=aPage.GetVI(’RST’,’VisPlot’,1);if (aPlot) {

! Reset option ’Use local x-Axis’ of SubplotaPlot.SetDefScaleX();! Get object defining scaleaScale=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 Panelobject aPage;object aGrf;object aPlot;object aScale;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {

! Get Virtual Instrument Panel named VoltageaPage=aGrf.GetPage(’Voltage’,1);

DPL Manual 102


if (aPage) {! Set x-scale to change it to localaPage.SetScaleX(1,100);! Get subplot named ’RST’aPlot=aPage.GetVI(’RST’,’VisPlot’,1);if (aPlot) {

! Reset option ’Use local x-Axis’ of SubplotaPlot.SetDefScaleX();! Get object defining scaleaScale=aPlot.GetScaleObjX();if (aPlot=aScale) {output(’The scale used is the Subplot itself.’);




}}

}}

! Used Scale is Subplot itselfobject aPage;object aGrf;object aPlot;object aScale;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {


! Reset option ’Use local x-Axis’ of Virtual Instrument PanelaPage.SetDefScaleX();! Get subplot named ’RST’aPlot=aPage.GetVI(’RST’,’VisPlot’,1);if (aPlot) {

! Set x-scale of Subplot to change it to localaPlot.SetScaleX(1,100);! Get object defining scaleaScale=aPlot.GetScaleObjX();if (aPlot=aScale) {output(’The scale used is the Subplot itself.’);




}}

}}

DPL Manual 103


GetScaleObjY

object VisPlot.GetScaleObjY ()Returns used object defining y-scale. The returned object is either the Subplot itself or the PlotType (IntPlot).

Argumentsnone

Return valueObject defining the y-scale.

ExampleThe following examples look for a Subplot named ’RST’ and get the used y-scale object. Thereare three different examples.1. Example: Used scale is Plot Type. 2. Example: Used scale is Subplot itself.

! Used scale is Plot Typeobject aPage;object aGrf;object aPlot;object aScale;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



! Reset option ’Use local y-Axis’ of SubplotaPlot.SetDefScaleY();! Get object defining scaleaScale=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 itselfobject aPage;object aGrf;object aPlot;object aScale;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



! Set x-scale of Subplot to change it to local

DPL Manual 104


aPlot.SetScaleY(1,100);! Get object defining scaleaScale=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 beset.

Argumentsint 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.

ExampleThe following examples look for a Subplot named ’RST’ sets the description for the curvesdefined in row two and three. The first variable’s description remains unchanged.

! Modify descriptions


! Note: object load is an interface parameter, therefore it is not defined here




! Clear variable listaPlot.Clear();! Append variablesaPlot.AddVars(load, ’m:U1:bus1’,’m:U1l:bus1’,’m:phiu1:bus1’);! Set description of row 2 and 3aPlot.SetCrvDesc(2,,’Line-Line Voltage’,’Angle’);

}}

}

1.8.39 IntPlot Methods

SetScaleY

DPL Manual 105


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. Noarguments =¿ automatic scaling.

Argumentsdouble 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 valuenone

ExampleThe following example looks for a Subplot named ’RST’ and set its y-axis scale. There are threedifferent examples. 1. Example: Perform auto scaling on y-Axis. 2. Example: Set minimum to0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to 1000. Changes to alog. scale

! Automatic scaling of y-scaleobject aPage;object aGrf;object aPlot;object aScale;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



! Reset option ’Use local y-Axis’ of subplotaPlot.SetDefScaleY();! Get object defining scale (now IntPlot)aScale=aPlot.GetScaleObjY();if (aScale) {! Perform auto scalingaScale.SetScaleY();

}

}}

}

! Set minimum and maximum without changing map modeobject aPage;object aGrf;object aPlot;object aScale;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



DPL Manual 106


! Reset option ’Use local y-Axis’ of subplotaPlot.SetDefScaleY();! Get object defining scale (now IntPlot)aScale=aPlot.GetScaleObjY();if (aScale) {! Perform auto scalingaScale.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) {



! Reset option ’Use local y-Axis’ of subplotaPlot.SetDefScaleY();! Get object defining scale (now IntPlot)aScale=aPlot.GetScaleObjY();if (aScale) {! Perform auto scalingaScale.SetScaleY(1,1000,1);

}

}}

}

SetAutoScaleY

void IntPlot.SetAutoScaleY (int mode )Sets automatic scaling mode of the y-scale.


Return valuenone

ExampleThe following example sets the auto scale mode of the Plot Type to On.

! Set autoscale option of Plot Typeobject aPage;object aGrf;object aPlot;

DPL Manual 107


object aScale;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



! Reset option ’Use local y-Axis’ of subplotaPlot.SetDefScaleY();! Get object defining scale (now IntPlot)aScale=aPlot.GetScaleObjY();if (aScale) {! Set auto scale option to onaScale.SetAutoScaleY(1);

}

}}

}

SetAdaptY

void IntPlot.SetAdaptY (int mode , double offset )Sets the adapt scale option of the y-scale.

Argumentsint mode (obligatory) : Possible values: 0 off, 1 ondouble offset (optional) : Offset, unused if mode is off or empty

Return valuenone

ExampleThe following examples look for a Subplot named ’RST’, gets its Plot Type and changes theadapt scale option of the scale.

! Modify adapt scale option of Plot Typeobject aPage;object aGrf;object aPlot;object aScale;! Look for opened graphics board.aGrf=GetGraphBoard();if (aGrf) {



! Reset option ’Use local y-Axis’ of subplotaPlot.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


! Turn on adapt scale, use a offset of 3aScale.SetAdaptY(1,3);! Turn off adapt scaleaScale.SetAdaptY(0,3);! Turn on adapt scale again, do not change the offsetaScale.SetAdaptY(1);

}}

}}

DPL Manual 109

DPL Manual

Index

abs, 5acos, 5Activate(IntCase), 48Activate(IntPrj), 48Add(Set), 32AddCntcy(ComSimoutage), 47AddCopy(Object), 44AddRef(ComNmink), 49AddRef(SetSelect), 73AddResVars(VisPlot), 92AddVar(IntMon), 54AddVars(ElmRes), 66AddVars(VisPlot), 90All(SetSelect), 76AllAsm(SetSelect), 75AllBars(SetSelect), 74AllBreakers(SetPath), 72AllBreakers(SetSelect), 77AllClosedBreakers(SetPath), 72AllClosedBreakers(SetSelect), 77AllElm(SetSelect), 73AllLines(SetSelect), 74AllLoads(SetSelect), 75AllOpenBreakers(SetPath), 72AllOpenBreakers(SetSelect), 77AllSym(SetSelect), 75AllTypLne(SetSelect), 76Arguments, 12asin, 5Assignment, 5atan, 5Automating tasks, 2

Boolean expression, 6Break, 6Buscoupler

Methods, 59

CalcElParams(typAsm), 48CalcElParams(typAsmo), 48Calling conventions, 12ceil, 5Clear(ComNmink), 50Clear(ElmRes), 64Clear(Set), 32Clear(SetSelect), 73Clear(VisPlot), 92

ClearVars(IntMon), 54Close(ElmCoup), 59Close(StaSwitch), 69ColLbl(IntMat), 57ComDpl, 3

Execute, 55ComEcho

Off, 52On, 51

ComIncExecute, 68

ComLdfExecute, 68

ComNminkAddRef, 49Clear, 50GetAll, 50

ComOutageGetObj, 46SetObjs, 46

ComRel3Execute, 67

ComResExportFullRange, 51FileNmResNm, 51

ComShcExecute, 68

ComSimoutageAddCntcy, 47ExecuteCntcy, 47Reset, 47SetLimits, 47

Continue, 6cos, 5cosh, 5Count(Set), 33Coupler

Methods, 59CreateFeederWithRoutes(ElmLne), 62CreateObject(Object), 45

Date(SetTime), 52Deactivate(IntCase), 48Deactivate(IntPrj), 48DIgSILENT Programming Language, 2do, 6double (DPL variable), 4

DPL Manual

DPLassignement, 5Boolean expression, 6calling subroutines, 12command object, 3expressions, 5external objects, 11Flow instructions, 6input, 7internal methods, 13Macros, 12Methods, 55object methods, 14output, 7set methods, 14Subroutines, 12syntax, 3variables, 4

DPL functions, 5Draw(ElmRes), 65

Edit(Object), 45ElmComp

Slotupd, 50ElmCoup

Close, 59IsClosed, 60IsOpen, 60Open, 59

ElmfeederGetAll, 49Get-

Buses/GetBranches/GetNodesBranches,49

GetObjs, 49ElmLne

CreateFeederWithRoutes, 62GetType, 61HasRoutes, 60HasRoutesOrSec, 61IsCable, 61IsNetCoupling, 62SetCorr, 62SetNomCurr, 64

ElmLnerouteHasSections, 63IsCable, 63

ElmResAddVars, 66Clear, 64Draw, 65GetObj, 66Init, 64SetAsDefault, 66Write, 65WriteDraw, 66

ElmZoneGetAll, 67GetBranches, 67GetBuses, 67GetObjs, 67

else, 6Execute(ComDpl), 55Execute(ComInc), 68Execute(ComLdf), 68Execute(ComRel3), 67Execute(ComShc), 68ExecuteCntcy(ComSimoutage), 47exp, 5ExportFullRange(ComRes), 51Expressions, 5External objects, 11

FeederMethods, 70

FileNmResNm(ComRes), 51Filter

Methods, 54First(Set), 34FirstFilt(Set), 35Firstmatch(Set), 35floor, 5Flow instructions, 6Form

Methods, 78frac, 5Function(Object), 39Functions

DPL internal, 13DPL objects, 14DPL sets, 14

functions, 5

Get(IntMat), 55Get(IntVec), 57Get(SetFilt), 54GetAll(ComNmink), 50GetAll(Elmfeeder), 49GetAll(ElmZone), 67GetAll(SetFeeder), 70GetAll(SetPath), 71GetAll(SetSelect), 76GetBranches(ElmZone), 67GetBranches(SetFeeder), 70GetBranches(SetPath), 71GetBuses(ElmZone), 67GetBuses(SetFeeder), 70GetBuses/GetBranches/GetNodesBranches(Elmfeeder),

49GetBusses(SetPath), 71GetClass(Object), 44GetConnectionCount(Object), 38

DPL Manual

GetContents(Object), 42GetCubicle(Object), 38GetObj(ComOutage), 46GetObj(ElmRes), 66GetObjs(Elmfeeder), 49GetObjs(ElmZone), 67GetPage(SetDesktop), 80GetParent(Object), 38GetScaleObjX(SetVipage), 89GetScaleObjX(VisPlot), 101GetScaleObjY(VisPlot), 104GetSize(Object), 40GetType(ElmLne), 61GetVal(Object), 40GetVar(IntMon), 53GetVI(SetVipage), 83

HasResults(Object), 38HasRoutes(ElmLne), 60HasRoutesOrSec(ElmLne), 61HasSections(ElmLneroute), 63

if, 6Init(ElmRes), 64Init(IntMat), 56Init(IntVec), 58Input instruction, 7int (DPL variable), 4IntCase

Activate, 48Deactivate, 48

Interactive instructions, 7IntForm

SetText, 78WriteOut, 78

IntMatColLbl, 57Get, 55Init, 56NCol, 57NRow, 56Resize, 56RowLbl, 57Set, 56

IntMonAddVar, 54ClearVars, 54GetVar, 53Methods, 53NVars, 53PrintAllVal, 53PrintVal, 53RemoveVar, 54

IntPlotmethods, 105SetAdaptY, 108

SetAutoScaleY, 107SetScaleX, 105

IntPrjActivate, 48Deactivate, 48

IntVecGet, 57Init, 58Resize, 58Set, 58Size, 59

IsCable(ElmLne), 61IsCable(ElmLneroute), 63IsCable(TypLne), 64IsClass(Object), 43IsClosed(ElmCoup), 60IsClosed(StaSwitch), 70IsIn(Set), 32IsNetCoupling(ElmLne), 62IsNode(Object), 40IsOpen(ElmCoup), 60IsOpen(StaSwitch), 69IsOutOfService(Object), 46IsRelevant(Object), 46

LineMethods, 60

Line RouteMethods, 63

Line TypeMethods, 64

ln, 5lnm(Object), 41log, 5logarithm, 5Loop control, 6

Macros, 12MarkInGraphics(Object), 42MarkInGraphics(Set), 37Matrix

Methods, 55max, 5method, definition, 13min, 5modulo, 5Move(Object), 39

NCol(IntMat), 57Next(Set), 34NextFilt(Set), 36Nextmatch(Set), 35NRow(IntMat), 56NVars(IntMon), 53

Obj(Set), 34Object

DPL Manual

AddCopy, 44CreateObject, 45Edit, 45Function, 39GetClass, 44GetConnectionCount, 38GetContents, 42GetCubicle, 38GetParent, 38GetSize, 40GetVal, 40HasResults, 38IsClass, 43IsNode, 40IsOutOfService, 46IsRelevant, 46lnm, 41MarkInGraphics, 42Move, 39ShowFullName, 43snm, 41unm, 41Unom, 42VarExists, 39

object (DPL variable), 4Object Methods, 14Off(ComEcho), 52On(ComEcho), 51Open(ElmCoup), 59Open(StaSwitch), 69Output instruction, 7

PathMethods, 71

pow, 5PrintAllVal(IntMon), 53PrintVal(IntMon), 53Programming language, 2, 3

Remove(Set), 33RemoveVar(IntMon), 54Reset(ComSimoutage), 47Resize(IntMat), 56Resize(IntVec), 58Results

Methods, 64root, 5round, 5RowLbl(IntMat), 57

Script, 3Selection

Methods, 73Set

Add, 32Clear, 32Count, 33

First, 34FirstFilt, 35Firstmatch, 35IsIn, 32MarkInGraphics, 37Next, 34NextFilt, 36Nextmatch, 35Obj, 34Remove, 33SortToClass, 37SortToName, 37SortToVar, 36

set (DPL variable), 4Set Methods, 14Set(IntMat), 56Set(IntVec), 58SetAdaptX(SetDesktop), 83SetAdaptX(SetVipage), 88SetAdaptX(VisPlot), 99SetAdaptY(IntPlot), 108SetAdaptY(VisPlot), 100SetAsDefault(ElmRes), 66SetAutoScaleX(SetDesktop), 82SetAutoScaleX(SetVipage), 87SetAutoScaleX(VisPlot), 97SetAutoScaleY(IntPlot), 107SetAutoScaleY(VisPlot), 98SetCorr(ElmLne), 62SetCrvDesc(VisPlot), 105SetDefScaleX(SetVipage), 87SetDefScaleX(VisPlot), 96SetDefScaleY(VisPlot), 97SetDesktop

GetPage, 80methods, 79SetAdaptX, 83SetAutoScaleX, 82SetResults, 81SetScaleX, 81SetXVar, 81Show, 79WriteWMF, 80

SetFeederGetAll, 70GetBranches, 70GetBuses, 70

SetFiltGet, 54

SetLimits(ComSimoutage), 47SetNomCurr(ElmLne), 64SetObjs(ComOutage), 46SetPath

AllBreakers, 72AllClosedBreakers, 72AllOpenBreakers, 72

DPL Manual

GetAll, 71GetBranches, 71GetBusses, 71

SetResults(SetDesktop), 81SetResults(SetVipage), 85SetScaleX(IntPlot), 105SetScaleX(SetDesktop), 81SetScaleX(SetVipage), 86SetScaleX(VisPlot), 93, 95SetSelect

AddRef, 73All, 76AllAsm, 75AllBars, 74AllBreakers, 77AllClosedBreakers, 77AllElm, 73AllLines, 74AllLoads, 75AllOpenBreakers, 77AllSym, 75AllTypLne, 76Clear, 73GetAll, 76

SetStyle(SetVipage), 84SetText(IntForm), 78SetTile(SetVipage), 84SetTime

Date, 52Time, 52

SetVipageGetScaleObjX, 89GetVI, 83methods, 83SetAdaptX, 88SetAutoScaleX, 87SetDefScaleX, 87SetResults, 85SetScaleX, 86SetStyle, 84SetTile, 84SetXVar, 85

SetXVar(SetDesktop), 81SetXVar(SetVipage), 85SetXVar(VisPlot), 92Show(SetDesktop), 79ShowFullName(Object), 43sin, 5sinh, 5Size(IntVec), 59Slotupd(ElmComp), 50snm(Object), 41SortToClass(Set), 37SortToName(Set), 37SortToVar(Set), 36sqr, 5

sqrt, 5square root, 5StaSwitch

Close, 69IsClosed, 70IsOpen, 69Open, 69

string (DPL variable), 4Switch

Methods, 69Syntax, 3

tan, 5tanh, 5Time

Methods, 52Time(SetTime), 52trigonometric, 5trunc, 5typAsm

CalcElParams, 48typAsmo

CalcElParams, 48TypLne

IsCable, 64

unm(Object), 41Unom(Object), 42

VarExists(Object), 39Variable Definitions, 4Variable Set

Methods, 53Vector

Methods, 57VisPlot

AddResVars, 92AddVars, 90Clear, 92GetScaleObjX, 101GetScaleObjY, 104methods, 90SetAdaptX, 99SetAdaptY, 100SetAutoScaleX, 97SetAutoScaleY, 98SetCrvDesc, 105SetDefScaleX, 96SetDefScaleY, 97SetScaleX, 93, 95SetXVar, 92

while, 6Write(ElmRes), 65WriteDraw(ElmRes), 66WriteOut(IntForm), 78WriteWMF(SetDesktop), 80

DPL Manual