powerfactory api v3

D I g S I L E N T T e c h n i c a l D o c u m e n t a t i o n

PowerFactory API

P o w e r F a c t o r y A P I 2

DIgSILENT GmbH

Heinrich-Hertz-Strasse 9

D-72810 Gomaringen

Tel.: +49 7072 9168 - 0

Fax: +49 7072 9168- 88

http://www.digsilent.de

e-mail: [email protected]

PowerFactory API

Published by

DIgSILENT GmbH, Germany

Copyright 2011. All rights

reserved. Unauthorised copying

or publishing of this or any part

of this document is prohibited.

18 November 2011

T a b l e o f C o n t e n t s


Table of Contents

Table of Contents .................................................................................................................. 3

1 Introduction ....................................................................................................................... 8

2 Overview ............................................................................................................................ 9

2.1 Logical Structure .................................................................................................................................... 9

2.2 Physical Structure................................................................................................................................. 10

2.3 Interface Data Model ............................................................................................................................ 10

2.4 Compiler Settings ................................................................................................................................. 11

3 Create and Destroy an Instance of the API ..................................................................... 12

3.1 Create an Instance of the API ............................................................................................................... 12

3.2 Delete an Instance of the API ................................................................................................................ 12

4 Accessing Objects and Attributes .................................................................................... 13

4.1 Accessing specific objects and browsing the database ............................................................................. 13

4.2 Accessing Object Attributes ................................................................................................................... 13

4.3 Modifying Objects and Attributes ........................................................................................................... 13

4.4 Creating and Deleting Objects ............................................................................................................... 14

4.5 Topological Routines ............................................................................................................................ 14

4.5.1 Example for GetConnectionCount ...................................................................................................... 14

4.5.2 Example for GetTerminal .................................................................................................................. 15

4.5.3 Example for GetCubicle .................................................................................................................... 15

4.6 Accessing and Post-processing Results ................................................................................................... 16

4.6.1 Load-flow and short-circuit calculations results ................................................................................... 16

4.6.2 Dynamic simulation results ............................................................................................................... 16

5 Executing Commands....................................................................................................... 17

5.1 On an instance of the class “Application” ................................................................................................ 17

5.2 On an instance of a “DataObject” .......................................................................................................... 17

5.3 Running Calculations ............................................................................................................................ 17

5.4 Available Generic Functions on api::Application instance .......................................................................... 18

5.4.1 SearchFull ....................................................................................................................................... 18

5.4.2 GetDefaultLocation .......................................................................................................................... 18



5.4.3 NewProject ..................................................................................................................................... 18

5.4.4 Activate .......................................................................................................................................... 19

5.4.5 Deactivate ...................................................................................................................................... 19

5.4.6 MakeNameValid .............................................................................................................................. 19

5.4.7 SearchByForeignKey ........................................................................................................................ 19

5.4.8 GetCaseObject ................................................................................................................................ 20

5.4.9 ExecuteCmd.................................................................................................................................... 20

5.4.10 GetSettingsFolder .......................................................................................................................... 20

5.4.11 GetProjectFolder ............................................................................................................................ 21

5.4.12 GetTempDir .................................................................................................................................. 21

5.4.13 GetActiveStudyCase ....................................................................................................................... 21

5.4.14 GetActiveScenario .......................................................................................................................... 22

5.4.15 GetActiveRecordingStage ............................................................................................................... 22

5.4.16 IsLdfValid ..................................................................................................................................... 22

5.4.17 IsRmsValid .................................................................................................................................... 23

5.4.18 IsShcValid ..................................................................................................................................... 23

5.4.19 IsSimValid ..................................................................................................................................... 23

5.5 Available Generic Functions on api::DataObject instance .......................................................................... 24

5.5.1 SlotUpdate ...................................................................................................................................... 24

5.5.2 IsBlockEncrypted ............................................................................................................................. 24

5.5.3 IsTransformer ................................................................................................................................. 24

5.5.4 IsOutOfCalculation .......................................................................................................................... 24

5.5.5 HasResults ...................................................................................................................................... 25

5.5.6 GetConnectionCount ........................................................................................................................ 25

5.5.7 GetActiveGrids ................................................................................................................................ 25

5.5.8 GetProjectFolder ............................................................................................................................. 25

6 References: Classes, Objects and Methods...................................................................... 27

6.1 Classes ................................................................................................................................................ 27

6.2 Api ...................................................................................................................................................... 28

6.2.1 GetVersion ...................................................................................................................................... 28

6.2.2 ReleaseObject ................................................................................................................................. 28

6.2.3 ReleaseValue .................................................................................................................................. 28

6.2.4 GetApplication ................................................................................................................................. 29

6.2.5 IsDebug ......................................................................................................................................... 29

6.3 Application .......................................................................................................................................... 29

6.3.1 GetVersion ...................................................................................................................................... 29

6.3.2 GetTempDirectory ........................................................................................................................... 30

6.3.3 GetWorkingDirectory ....................................................................................................................... 30

6.3.4 GetOutputWindow ........................................................................................................................... 30

6.3.5 GetCurrentUser ............................................................................................................................... 31

6.3.6 GetActiveProject .............................................................................................................................. 31

6.3.7 GetActiveStudyCase ......................................................................................................................... 32

6.3.8 GetCalcRelevantObjects ................................................................................................................... 32

6.3.9 GetClassId ...................................................................................................................................... 33



6.3.10 GetClassDescription ....................................................................................................................... 33

6.3.11 AttributeMode ............................................................................................................................... 34

6.3.12 SetAttributeMode ........................................................................................................................... 34

6.3.13 GetAttributeMode .......................................................................................................................... 34

6.3.14 SetWriteCacheEnabled ................................................................................................................... 35

6.3.15 IsWriteCacheEnabled ..................................................................................................................... 35

6.3.16 GetAttributeType ........................................................................................................................... 36

6.3.17 GetAttributeDescription .................................................................................................................. 36

6.3.18 GetAttributeUnit ............................................................................................................................ 37

6.3.19 GetAttributeSize ............................................................................................................................ 38

6.3.20 Execute ........................................................................................................................................ 39

6.3.21 WriteChangesToDb ........................................................................................................................ 39

6.4 OutputWindow ..................................................................................................................................... 40

6.4.1 MessageType .................................................................................................................................. 40

6.4.2 Print ............................................................................................................................................... 40

6.4.3 Clear .............................................................................................................................................. 40

6.5 DataObject .......................................................................................................................................... 41

6.5.1 AttributeType .................................................................................................................................. 41

6.5.2 GetClassName ................................................................................................................................. 41

6.5.3 GetClassId ...................................................................................................................................... 42

6.5.4 GetName ........................................................................................................................................ 43

6.5.5 GetFullName ................................................................................................................................... 43

6.5.6 GetChildren ..................................................................................................................................... 44

6.5.7 GetParent ....................................................................................................................................... 44

6.5.8 IsNetworkDataFolder ....................................................................................................................... 45

6.5.9 IsHidden ......................................................................................................................................... 46

6.5.10 IsDeleted ...................................................................................................................................... 47

6.5.11 GetAttributeType ........................................................................................................................... 47

6.5.12 GetAttributeDescription .................................................................................................................. 48

6.5.13 GetAttributeUnit ............................................................................................................................ 48

6.5.14 GetAttributeSize ............................................................................................................................ 49

6.5.15 GetAttributeInt .............................................................................................................................. 49

6.5.16 GetAttributeDouble ........................................................................................................................ 50

6.5.17 GetAttributeObject ......................................................................................................................... 50

6.5.18 GetAttributeString .......................................................................................................................... 51

6.5.19 SetAttributeObject ......................................................................................................................... 51

6.5.20 SetAttributeString .......................................................................................................................... 51

6.5.21 SetAttributeDouble ........................................................................................................................ 52

6.5.22 SetAttributeInt .............................................................................................................................. 52

6.5.23 ResizeAttribute .............................................................................................................................. 53

6.5.24 CreateObject ................................................................................................................................. 53

6.5.25 Execute ........................................................................................................................................ 54

6.5.26 WriteChangesToDb ........................................................................................................................ 55

6.6 Value .................................................................................................................................................. 55

6.6.1 Properties ....................................................................................................................................... 55

6.6.1.1 Type ......................................................................................................................................... 55



6.6.1.2 Data .......................................................................................................................................... 55

6.6.2 Constructor / Destructor .................................................................................................................. 56

6.6.3 GetType ......................................................................................................................................... 56

6.6.4 GetInteger ...................................................................................................................................... 56

6.6.5 GetInteger64 .................................................................................................................................. 57

6.6.6 GetDouble ...................................................................................................................................... 57

6.6.7 GetString ........................................................................................................................................ 57

6.6.8 GetDataObject ................................................................................................................................ 58

6.6.9 MatGetRowCount ............................................................................................................................ 58

6.6.10 MatGetColCount ............................................................................................................................ 58

6.6.11 MatSetDouble................................................................................................................................ 59

6.6.12 MatGetDouble ............................................................................................................................... 59

6.6.13 SetValue ....................................................................................................................................... 59

6.6.14 VecGetInteger ............................................................................................................................... 60

6.6.15 VecGetInteger64 ........................................................................................................................... 60

6.6.16 VecGetDouble ............................................................................................................................... 61

6.6.17 VecGetString ................................................................................................................................. 61

6.6.18 VecGetDataObject ......................................................................................................................... 62

6.6.19 VecGetValue ................................................................................................................................. 62

6.6.20 VecClear ....................................................................................................................................... 63

6.6.21 VecGetSize .................................................................................................................................... 63

6.6.22 VecGetType .................................................................................................................................. 64

6.6.23 VecInsertInteger ........................................................................................................................... 64

6.6.24 VecInsertInt64 .............................................................................................................................. 64

6.6.25 VecInsertDouble ............................................................................................................................ 65

6.6.26 VecInsertString ............................................................................................................................. 65

6.6.27 VecInsertDataObject ...................................................................................................................... 65

6.6.28 VecInsertValue .............................................................................................................................. 66

Annexes ............................................................................................................................... 67

Annex A-1 : Application – interface with Google Earth ...................................................... 68

1 Introduction ..................................................................................................................... 68

2 Managed Code Wrapper ................................................................................................... 70

2.1 Definition ............................................................................................................................................ 70

2.2 Example: Wrapping “Application” class ................................................................................................... 70

2.2.1 C++/CLI basic syntax ...................................................................................................................... 70

2.2.2 Calls in C# ...................................................................................................................................... 70

2.2.3 Code .............................................................................................................................................. 70

3 KML and PowerFactory Projects ...................................................................................... 71

4 Exporting diagrams to Google Earth ................................................................................ 73

4.1 Exporting ............................................................................................................................................ 73



4.2 Example: exporting one diagram ........................................................................................................... 73

5 Importing kml files to PowerFactory ............................................................................... 77

6 Show/Hide PowerFactory ................................................................................................ 79

7 Running load flows .......................................................................................................... 79

1 I n t r o d u c t i o n


1 Introduction

The DIgSILENT PowerFactory Application Programming interface (API) offers third party applications the

possibility to embed PowerFactory’s functionality into their own program. It offers direct access to the

PowerFactory data model and gives access to the varied calculations and its results. It has been designed to be

reasonable small and consistent while being as powerful as possible.

Based on one single dll, the idea is to keep the interface as small as possible while providing all the necessary

functions to manipulate objects and execute commands. Technically, the interface is realized in C++ and

provided as a DLL that can dynamically be linked to any external application.

This document presents the structure of the API, and how to include it in third party applications. Available

instructions and commands, methods to access objects and their parameters are illustrated by short examples.

A full application example is presented in appendix: importing and exporting DIgSILENT PowerFactory projects

from and to kml files that can be interpreted by GoogleEarth. This example also includes a wrapper

implementation that allows using the API within managed code (managed C++, C#, etc.).

2 O v e r v i e w


2 Overview

2.1 Logical Structure

The PowerFactory API is a logical layer of the PowerFactory application that encapsulates the internal data

structures and makes them available to external applications. Its purpose is to give a consistent interface being

as close as on the PowerFactory data model. The API takes care about internal memory management and data

persistency. It does not allow any external functions to access directly PowerFactory objects as illustrated on the

following figure.

Figure 1.

PowerFactory Application

API

3rd Party Application

2 O v e r v i e w

P o w e r F a c t o r y A P I 1 0

2.2 Physical Structure

Figure 2.

Physically, the interface consists of the following files

• digapi.dll: dynamic library that is part of the PowerFactory application. This library holds the

implementation of the interface layer. For static linking, a digapi.lib can be provided.

• api.hpp: interface definition as a C++ header file.

• apivalue.hpp / apivalue.lib: header and static library for the value transfer object that is used by the

API.l

2.3 Interface Data Model

The API offers 5 different classes:

- Api: instance of the API

- Application: one single instance of PowerFactory (running PowerFactory instance is linked to the dll

“digapi.dll” that has been loaded)

- OutputWindow: PowerFactory output window to display messages, warnings and errors

- DataObject: any PowerFactory object

- Value: encapsulation of data values acting as input or output for the API functions. A Value is a kind of

variant used to offer a consistent interface while respecting different memory managements on the

PowerFactory and external application side. The data stored in a Value object can be of different types

(i.e. string, double, vector, etc.)

digapi.dll

void Function1();

void Function2();

void Function3();

...

digcal.dl

l

digapl.dl

l

digadm.dl

l

dig*.dl

2 O v e r v i e w


2.4 Compiler Settings

To avoid errors at runtime, the compiler settings for the third party application using the API should be set as

following:

Character Set: No multi-byte / Unicode character set

• MS Visual Studio Project Property:

Configurations Properties\General\Character Set: Not Set

Calling Convention: cdecl

• MS Visual Studio Project Property:

Configurations Properties\C/C++Advanced\Calling Convention : __cdecl (/Gd)

3 C r e a t e a n d D e s t r o y a n I n s t a n c e o f t h e A P I


3 Create and Destroy an Instance of the API

The linchpin of the interaction with PowerFactory is an instance of the API. The dll “digapi.dll” offers two

functions CreateApiInstance and DestroyApiInstance to respectively create and destroy an instance of the API.

3.1 Create an Instance of the API

Using the function CreateApiInstance as in the following example to create an instance of the API; only one

instance can be created at the time.

#include "Api.hpp"

#include <windows.h>

using api::Api;

api::Api* apiInstance = CreateApiInstance(null, null);

Note: The executable file must be copied inside PowerFatory installation directory, else the link to the library is

not done and dllHandle returns NULL. To use the API from an executable installed outside PowerFactory

installation directory, a solution would be to create a start-up dll that can be called from outside the installation

directory to start the api.

3.2 Delete an Instance of the API

Using DestroyApiInstance, the corresponding instance of the API will be deleted and the memory occupied by the

created objects within this instance of the API will be freed.

DestroyApiInstance(apiInstance);

4 A c c e s s i n g O b j e c t s a n d A t t r i b u t e s


4 Accessing Objects and Attributes

4.1 Accessing specific objects and browsing the database

Specific objects can be accessed by using different methods on an instance of class “Application”:

GetCurrentUser, GetActiveProject, GetActiveStudyCase, GetCalcRelevantObjects combined with DataObject’s

methods GetChildren and GetParent to browse up and down the database.

Examples:

Value* user = apiInstance->GetApplication()->GetCurrentUser() will return a pointer of the generic type “Value”

(see 6.6, for a description of this class), pointing to the current user in the PowerFactory database.

Value* userProjects = user->GetDataObject()->GetChildren(false) returns a vector containing the objects

(projects or folders) at the first level below the current user.

4.2 Accessing Object Attributes

To access any attribute of an object (DataObject), its type must be known. The method GetAttributeType(name

of the attribute) returns the type of the corresponding attribute.

Attribute types are for instance:

• TYPE_INVALID in case of error

• TYPE_INTEGER for attributes of type “int32”

• TYPE_ INTEGER_VEC for vectors of int32

• TYPE_DOUBLE for attributes of type “double”

• TYPE_DOUBLE_VEC for vectors of doubles

• TYPE_DOUBLE_MAT for matrices of doubles

• TYPE_OBJECT for an attribute of type “object”

• TYPE_OBJECT_VEC for vectors of objects

• TYPE_STRING for an attribute of type string

• TYPE_STRING_VEC for vectors of strings

• TYPE_INTEGER64 for attributes of type “int64”

• TYPE_ INTEGER64_VEC for vectors of int64

Once the type has been identified, methods like GetAttributeInt, GetAttributeDouble, GetAttributeObject,

GetAttributeString return respectively the content of the attribute as an integer, double, DataObject or string.

For manipulating matrices and vectors, their size can be identified using GetAttributeSize (see 6.5.14 for calling

convention). GetAttributeInt, GetAttributeDouble, GetAttributeObject, GetAttributeString offer an overloaded

method allowing to access specific objects in the matrix or the vector referring at its row and columns indices.

4.3 Modifying Objects and Attributes

Objects and their attributes can be modified using one the following methods:



SetAttributeInt, SetAttributeDouble, SetAttributeString and SetAttributeObject

For matrices and vectors, overloaded methods of the above ones allowing targeting a specific element (row and

column indices) are available. The method ResizeAttribute resizes a vector or matrix attribute.

Blocks of attributes can be accessed or modified at once using DefineTransferAttributes, GetAttributes and

SetAttributes.

Api::Application* application; application->DefineTransferAttributes(“ElmTerm”, “loc_name, uknom”);

DataObject* terminal; Value* attr = new Value(api::Value::VECTOR);

attr->VecInsertString(“my terminal”); attr->VecInsertDouble(20);

terminal->SetAttributes(attr); attr = terminal->GetAttributes();

4.4 Creating and Deleting Objects

Objects of a given class can be created using “CreateObject”. The new object is created inside the parent object

(object from which the “CreateObject” method has been called) if possible.

The following example creates a new folder (IntFolder) inside currently active project:

DataObject* prj = apiInstance->GetApplication()->GetActiveProject();

if (prj) { DataObject* newFolder = prj->CreateObject(“IntFolder”, “MyFolder");

}

Objects can be deleted by: obj->DeleteObject(error)

4.5 Topological Routines

The API does not include functions that can be classified as “topological” but it is possible to build functions like

“GetConnectionCount”, “GetTerminal”, “GetCubicle” to navigate from node to branch or from element to element.

4.5.1 Example for GetConnectionCount

Returns the number of connections as an integer.

int GetConnectionCount(DataObject* obj)

{ int count = 0;

if(obj->GetClassId() != CLASSID_ELMTERM) {

int error (0); Value* v = obj->Execute(“GetConnectionCount”, NULL, error);

count = v->GetInteger(); api->ReleaseValue(v);

} else

{ Value* cubs = obj->GetChildren(false, CLASSID_STACUBIC);

count = cubs->VecGetSize();

api->ReleaseValue(cubs);



}

return count;

}

4.5.2 Example for GetTerminal

Returns a vector containing the terminals connected to the element.

std::vector<DataObject*> GetTerminals(DataObject* obj)

{ std::vector<DataObject*> terms;

if (obj->GetClassId() != 0 CLASSID_ELMTERM) { int error (0);

Value* count = obj->Execute("GetConnectionCount", NULL, error);

for(int i=0; i<count->GetInteger(); ++i) { Value* term = obj->Execute("GetTerminal", &Value(i), error);

if (error == 0 && term->GetDataObject()) { terms.push_back(term->GetDataObject());

} api->ReleaseValue(term);

} api->ReleaseValue(count);

} else {

terms.push_back(obj); }

return terms; }

4.5.3 Example for GetCubicle

Returns a vector containing the cubicles the element is connected to.

std::vector<DataObject*> GetCubicles(DataObject* obj)

{ std::vector<DataObject*> cubs;

if (obj->GetClassId() != 0 CLASSID_ELMTERM) { int error (0);

Value* count = obj->Execute("GetConnectionCount", NULL, error); for(int i=0; i<count->GetInteger(); ++i) {

Value* cub = obj->Execute("GetCubicle", &Value(i), error); if (error == 0 && cub->GetDataObject()) {

cubs.push_back(cub->GetDataObject()); }

api->ReleaseObject(cub); }

api->ReleaseObject(count); }



else {

Value* cubs = obj->GetChildren(false, 0 /*CLASSID_STACUBIC*/); for(int i=0; i < cubs->VecGetSize(); ++i) {

cubs.push_back(cubs->VecGetDataObject(i)); }

api->RelesaeObject(cubs); }

return cubs; }

4.6 Accessing and Post-processing Results

4.6.1 Load-flow and short-circuit calculations results

Load-flow and short-circuit variables of a network element can be accessed as element attributes; they have the

format “m:P”, “m:Q”, etc. The name of the variable for a specific element can be retrieved by looking for it in the

variable selection tab of a “flexible page” or by adding this object to the result file ( ) and then check the

variables appearing in the Load-Flow/Short-Circuit tab.

The function GetAttributeDouble can be used to retrieve the results from load-flow or short-circuit calculation. For

instance, to get the voltage at a bus bar, the code would look like:

DataObject* elmTerm;

double busVoltage = elmTerm->GetAttributeDouble(“m:u”);

4.6.2 Dynamic simulation results

The API in its current version does not allow to access elements in result files. As a work-around, it is possible to

export to result file as a text file and then read it.

The “ComRes” object exports a result file to different formats/outputs: Output Window, Windows Clipboard,

Measurement File and Text File.

The example below creates a “ComRes” object, sets its parameters and executes the command.

comRes = prj->CreateObject("ComRes","myExport");

comRes->SetAttributeObject("pResult",elmRes); comRes->SetAttributeInt("iopt_exp",4);

comRes->SetAttributeString("f_name", "c:\\test_export.txt"); comRes->Execute("Execute", NULL);

5 E x e c u t i n g C o m m a n d s


5 Executing Commands

5.1 On an instance of the class “Application”

The “Application” class contains an “Execute” method to execute a set of generic commands like “Activate” to

activate a project

“ExecuteCmd” allows reproducing commands like they would be entered in PowerFactory input window.

Example:

To show PowerFactory user interface

api::Value cmd ("rcom/show");

apiInstance->GetApplication()->Execute("ExecuteCmd", &cmd, error);

To hide PowerFactory user interface

api::Value cmd ("rcom/hide");


5.2 On an instance of a “DataObject”

Commands can also be executed on an object level by the method “Execute”. (See also 5.5 and 6.5.25)

Example: executing a DPL script

comdpl->Execute("Execute", NULL, error);

5.3 Running Calculations Calculations can be run by using the “Execute” method on a command object. The following example runs a

short-circuit calculation with a short-circuit at a specific terminal:

if (comShc == null)

{ comShc = actStdyCase->CreateObject("ComShc", "Short-Circuit");

}

comShc->SetAttributeObject("shcobj", elmTerm); comShc->Execute("Execute", NULL);

Where comShc is an “ComShc” object (short-circuit command), elmTerm is the terminal where the short-

circuit has to be performed.

Once again, the generic function “ExecuteCmd” can also be used for running calculations like load-flows, short-

circuits or rms/transient simulation even this is not the recommended way of performing calculations.

Example: running a load-flow calculation

api::Value cmd ("ldf/notopo/disp"); apiInstance->GetApplication()->Execute("ExecuteCmd", &cmd, error);

For a short-circuit calculation:



api::Value cmd ("shc/iec/3psc/max/agi/all/asc");


5.4 Available Generic Functions on api::Application instance

api->GetApplication()->Execute(string command, const Value* inArgs, int* error)

Where “command” can be one of the following:

5.4.1 SearchFull

Description:

Searches and returns an object specified by path.

Arguments:

Value::VECTOR

[0]: string, full path of object to search (e.g. .\Digsi.intUser\MyPrj.intPrj)

[1]: optional DataObject, parent from which to start search (default is database root)

Return value:

Value::DataObject

Returned Value* is never NULL but contained DataObject might be NULL if no object was found.

5.4.2 GetDefaultLocation

Description:

Gets default location where objects of given class name are stored. e.g. Library for Typ*

Arguments:

Value::VECTOR

[0]: string, class name for which the default location is searched

[1]: optional integer, create location if not exist (0 = no create, default; 1 = create)

Return value:

Value::DataObject

Returned Value* is never NULL but contained DataObject might be NULL if location exists

5.4.3 NewProject

Description:

Creates a new project (using copy template in PF) and returns it.

Arguments:



Value::VECTOR

[0]: DataObject, parent for new project (e.g. current user)

[1]: optional string, name for new project

Return value:

Value::DataObject

Returned Value* is never NULL but contained DataObject might be NULL on error

5.4.4 Activate

Description:

Activates given object.

Arguments:

Value::DATAOBJECT: intPrj, intCase, intScenario, intScheme, ElmNet, intStage, intGrfnet object to activate

Return value:

NULL

5.4.5 Deactivate

Description:

Deactivates given object. No error if object is not active.

Arguments:

Value::DATAOBJECT: intPrj, intCase, intScenario, intScheme, ElmNet, intStage, intGrfnet object to activate

Return value:

NULL

5.4.6 MakeNameValid

Description:

Replaces all characters that are not allowed for loc_name and returns cleaned name.

Arguments:

Value::STRING, name

Return value:

VALUE::STRING, modified version of input name that is valid as loc_name

5.4.7 SearchByForeignKey

Description:



Searches and returns an object by foreign key (foreign keys are defined per project; search is executed only on

active project)

Arguments:

Value::STRING, foreign key string

Return value:

Value::DataObject

returned Value* is never NULL but contained DataObject might be NULL if no object was found

5.4.8 GetCaseObject

Description:

Same as DPL command. Gets (creates if necessary) instance of given class name from active study case.

Arguments:

Value::STRING, class name

Return value:

Value::DataObject

Returned Value* is never NULL but contained DataObject might be NULL if no object was found

5.4.9 ExecuteCmd

Description:

Executes a command string as it can be entered in PF Input Window (e.g. "ac/de all")

Arguments:

Value::STRING, command string

Return value:

NULL

5.4.10 GetSettingsFolder

Description:

Returns settings folder (SetFold). The settings folder is automatically created if it does not exist.

Arguments:

Value::INTEGER, type:

type<0: from user project

type>0: from default project

type=0: from parent of active case or from active project



Return value:

Value::DataObject

Returned Value* is never NULL but contained DataObject is never NULL

5.4.11 GetProjectFolder

Description:

Returns the project folder.

Arguments:

Value::STRING type: as in DPL, e.g.

'scen': scenario folder

'dia': diagram folder

'netdat': network data folder

'oplib': operational data library

'lib': library

Return value:

Value::DataObject

Returned alue* is never NULL but contained DataObject might be null if folder does not exist or folder type is

unknown

5.4.12 GetTempDir

Description:

Returns the path to directory for temporary files.

Arguments:

NULL

Return value:

Value::STRING

Returned Value* is never NULL

5.4.13 GetActiveStudyCase

Description:

Returns the active study-case object.

Arguments:

NULL



Return value:

Value::DataObject

Returned Value* is never NULL but contained DataObject might be null if folder or no active object found

5.4.14 GetActiveScenario

Description:

Returns the active scenario object.

Arguments:

NULL

Return value:

Value::DataObject


5.4.15 GetActiveRecordingStage

Description:

Returns the active system stage object.

Arguments:

NULL

Return value:

Value::DataObject


5.4.16 IsLdfValid

Description:

Identical to DPL routines, checks if valid results are available.

Arguments:

NULL

Return value:

Value::INTEGER


0 = false

1 = true



5.4.17 IsRmsValid

Description:


Arguments:

NULL

Return value:

Value::INTEGER


0 = false

1 = true

5.4.18 IsShcValid

Description:


Arguments:

NULL

Return value:

Value::INTEGER


0 = false

1 = true

5.4.19 IsSimValid

Description:


Arguments:

NULL

Return value:

Value::INTEGER


0 = false

1 = true



5.5 Available Generic Functions on api::DataObject instance

DataObject_Instance->Execute(string command, const Value* inArgs, int* error)

Where “command” can be one of the following:

5.5.1 SlotUpdate

Description:

Performs a slot update for objects of class ElmComp

Arguments:

NULL

Return value:

None

5.5.2 IsBlockEncrypted

Description:

For objects of class BlkDef only, checks if block is encrypted

Arguments:

NULL

Return value:

Value::INTEGER, 0=false, >0=true

5.5.3 IsTransformer

Description:

Checks if current object is a transformer, Tr2, Tr2n, Tr3

Arguments:

NULL

Return value:


5.5.4 IsOutOfCalculation

Description:

Checks if current object is out of calculation. This status is determined by outserv flag and (optionally) automatic

out-of-calc detection.

Arguments:



NULL

Return value:


5.5.5 HasResults

Description:

Checks if current object has calculation results.

Arguments:

NULL

Return value:


5.5.6 GetConnectionCount

Description:

Number of connections for given object, e.g. ElmLne->2

Arguments:

NULL

Return value:

Value::INTEGER

5.5.7 GetActiveGrids

Description:

Returns all currently active grids (ElmNet objects). Returned value might be empty, but is never null.

Arguments:

NULL

Return value:

Value::VECTOR, entries of type DataObject

5.5.8 GetProjectFolder

Description:

Returns the project folder for given type, e.g. scen->Scenario. Same as DPL routine GetProjectFolder()

Arguments:

either



Value::STRING = folder type

or

Value::VECTOR

[0]: Value::STRING = folder type

[1]: Value::INTEGER = 1 create if don't exists, 0 do not create

Return value:

Value::DATAOBJECT, IntPrjFolder of given type

6 R e f e r e n c e s : C l a s s e s , O b j e c t s a n d M e t h o d s


6 References: Classes, Objects and Methods

6.1 Classes

The API offers 5 different classes:

- Api: one single instance of the API

- Application: one single instance of PowerFactory (running PowerFactory instance is related to the dll

“digapi.dll” that has been loaded)

- OutputWindow: PowerFactory output window to display messages, warnings and errors

- DataObject: any PowerFactory object

- Value: value of a property, an argument or an attribute of an API instance, an application or an object

The relationships among these classes are displayed on the following figure:

Figure 3.

Only one instance of the API can be created at the time (CreateApiInstance). An instance of the Application is

automatically linked to the instance of the API. One single OutputWindow is attached to the application instance.

PowerFactory objects (grid elements, etc.) are represented as DataObject, as many as necessary DataObject can

be created. Values represent arguments or attributes of an API instance, an application or DataObjects.

For each of the above objects or instance of classes, once the program is done using it, the memory should be

released in order to avoid memory leaks (see 6.2.2 ReleaseObject, 6.2.3 ReleaseValue). When the API is

released, the memory is automatically freed; all remaining objects are released.



6.2 Api

6.2.1 GetVersion

Value* GetVersion()

Returns the version of the current API instance

Arguments:

none

Return value:

A pointer of type Value pointing to a string with the version of the current API

Example:

The following example displays in the command window the version of the api used to create the running

instance.

apiInstance = CreateApiInstance();

std::cout << std::endl << apiInstance->GetVersion()->GetString()<< std::endl;

6.2.2 ReleaseObject

int ReleaseObject(const DataObject* object)

Releases an Api object instance. All Api object pointers created by via an api must be released using this function.

Calling delete from an external DLL is not possible as the Api instance has its own memory management.

Arguments:

const DataObject* object: the pointer to the object to be released

Return value:

0 on success, >0 on error

Example:

api::DataObject* user = apiInstance->GetApplication()->GetCurrentUser()->GetDataObject();

apiInstance->ReleaseObject(user);

6.2.3 ReleaseValue

int ReleaseValue(const Value* object)

Releases an Api value instance. All Api object pointers created by via an api must be released using this function.

Calling delete from an external DLL is not possible as the Api instance has its own memory management.

Arguments:

const Value* object: pointer to the object to be released

Return value:



0 on success, >0 on error

Example:

api::Value* user = apiInstance->GetApplication()->GetCurrentUser();

apiInstance->ReleaseValue(user);

6.2.4 GetApplication

Application* GetApplication()

The function returns an instance of the application. There exists only one application object per Api instance. This

application object must not be deleted.

Arguments:

None

Return value:

Pointer to the instance of an application object, never NULL

Example:

The following example displays in the command window the version of the running instance of PowerFactory.


std::cout << "PowerFactory version:" << apiInstance->GetApplication()->GetVersion()->GetString() << std::endl;

6.2.5 IsDebug

bool IsDebug()

Arguments:

None

Return value:

True if PowerFactory is in debug mode; false otherwise.

Example:


if(apiInstance->IsDebug()) {

std::cout << "PowerFactory running in debug mode" << std::endl; }

6.3 Application

6.3.1 GetVersion

const Value* GetVersion()

The function returns the version of the currently running PowerFactory, e.g. "14.0.505"



Arguments:

None

Return value:

Pointer to a Value object holding version information of PowerFactory application; returned string is never null

and must be released when no longer in use.

Example:

The following example displays in the command window the version of the running instance of PowerFactory.


std::cout << "PowerFactory version:" << apiInstance->GetApplication()->GetVersion()->GetString() << std::endl;

6.3.2 GetTempDirectory

const Value* GetTempDirectory()

Returns the path to the temporary directory of the running instance of PowerFactory

Arguments:

None

Return value:

A pointer of type Value pointing to a string with the temporary directory of PowerFactory

Example:

std::cout << apiInstance->GetApplication()->GetTempDirectory()->GetString() << std::endl;

6.3.3 GetWorkingDirectory

const Value* GetWorkingDirectory()

Returns the path to the working directory of the running instance of PowerFactory

Arguments:

None

Returns

A pointer of type Value pointing to a string with the working directory of PowerFactory

Example:

std::cout << apiInstance->GetApplication()->GetWorkingDirectory()->GetString() << std::endl;

6.3.4 GetOutputWindow

OutputWindow* GetOutputWindow()



This function returns an instance of the running PowerFactory output window. Each api instance has only one

output window instance.

Arguments:

None

Return value:

Returns a pointer to an instance of OutputWindow, never NULL

Example:

The following example displays a message in the PowerFactory output window.

api::OutputWindow* outWindow = apiInstance->GetApplication()->GetOutputWindow();

outWindow->Print(api::OutputWindow::M_INFO,"Running PowerFactory from the API"); outWindow->Clear();

6.3.5 GetCurrentUser

api::DataObject* GetCurrentUser()

This function returns the current user.

Arguments:

None

Return value:

Returns a pointer to the currently logged in user object.

Example:

The following example displays the name of the current user in the command window.

int error = 0;

api::DataObject* user = apiInstance->GetApplication()->GetCurrentUser(); std::cout << *(user->GetAttributeString("loc_name",error)) << std::endl;

6.3.6 GetActiveProject

api::DataObject * GetActiveProject()

Returns a pointer to the currently active PowerFactory project, NULL if there is no active project.

Arguments:

None

Return value:

a pointer to the currently active PowerFactory project

Example:

The following example returns the current active project in a textbox; if no project has been activated, the

message is “no active project”



int* error;

api::DataObject* activProj = apiInstance->GetApplication()->GetActiveProject(); if(activProj)

{ printf("Active Project: %s \n",

activProj->GetName()->GetString()),); }

else {

printf("No active project \n"); }

6.3.7 GetActiveStudyCase

api::DataObject * GetActiveStudyCase()

Returns a pointer to the currently active study case, NULL if there is no active case.

Arguments:

None

Return value:

a pointer of type Value to the currently active study case

Example:

The following example returns the current active study-case in a textbox; if no study-case has been activated, the

message is “no active study-case”

int* error; api::DataObject* activStudycase = apiInstance->GetApplication()->GetActiveStudyCase();

if(activStudycase) {

printf("Active studycase: %s \n", activStudycase->GetName()->GetString());

} else

{ printf("No active studycase \n");

}

6.3.8 GetCalcRelevantObjects

const Value* GetCalcRelevantObjects()

This function returns all objects that are currently relevant for calculation: lines, nodes, switches, transformers,

etc. and their types.

Arguments:

None

Return value:

Returns a pointer of type Value to a vector of objects relevant for calculation, never NULL.



The container must be released if no longer in use.

Example:

This example iterates through the vector of the relevant objects for calculation and displays them in a treeview

object.

int* error;

const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects(); if(relevantObj)

{ printf("Getting relevant object for calculation... \n");

for (size_t i = 0, count = relevantObj->VecGetSize(error); i < count; ++i) {

DataObject* obj = relevantObj->VecGet(i)->GetDataObject();

treeViewCalcRelevant->Nodes->Add(obj->GetName()->GetString(error)); }

} else

{ printf("No relevant object for calculation \n");

}

6.3.9 GetClassId

int GetClassId(const char* className)

This function returns the class identifier integer of the considered class “className”. Each class name

corresponds to one unique index. The mapping of class name might be different according to the build version of

PowerFactory, but it is guaranteed that it will not change while an Api instance exists. This indices should not be

stored statically but rather be generated dynamically in the code using the GetClassId method

Arguments:

const char* className: the name of the considered class

Return value:

Returns an integer representing the index (>0) of the considered class; 0 if className is not a valid class name.

Example:

int filterID = apiInstance->GetApplication()->GetClassId("intPrj");

std::cout << "Project ID (intPrj):" << filterID << std::endl;

6.3.10 GetClassDescription

const Value* GetClassDescription(const char* className)

Returns the description of a PowerFactory class.

Arguments:

const char* className => name of the considered PowerFactory class

Retrun value:



Returns the description text, never NULL; but the string is empty for invalid class names

Example:

The following example displays the description text of the class “intPrj”

std::cout << "intPrj description text:" << apiInstance->GetApplication()->GetClassDescription("intPrj")-

>GetString() << std::endl;

6.3.11 AttributeMode enum AttributeMode {

MODE_DISPLAYED = 0, MODE_INTERNAL = 1

};

Enumerated type for accessing object attributes in PowerFactory.

MODE_DISPLAYED = as displayed in PF (unit conversion applied)

MODE_INTERNAL = as internally stored

6.3.12 SetAttributeMode

void SetAttributeMode(AttributeMode mode)

Changes the way how attribute values are accessed:



Arguments:

AttributeMode mode: the way the attribute values should be accessed

Return value:

void

Example:

6.3.13 GetAttributeMode

AttributeMode GetAttributeMode()

Returns the mode how object attributes are accessed.

Return value of type AttributeMode (see 6.3.11)

Arguments:

None

Return value:



AttributeMode



Example:

This example displays in a textbox the attribute mode

api::Application::AttributeMode mode = apiInstance->GetApplication()->GetAttributeMode();

const char* strAttributeMode[]={"MODE_DISPLAYED","MODE_INTERNAL"}; printf("Attribute mode: %s \n", strAttributeMode[mode]);

6.3.14 SetWriteCacheEnabled

void SetWriteCacheEnabled(bool enabled)

This function intends to optimize performances. In order to modify objects in PowerFactory, those must be set in

a special edit mode before any value can be changed. Switching back and forth between edit mode and stored

mode is time consuming; enabling the write cache flag will set objects in edit mode and they will not be switched

back until WriteChangeToDb (see 6.3.21) is called.

Default value: disabled.

Arguments:

Bool enabled: true = enabled; false = disabled

Return value:

void

Example:

apiInstance->GetApplication()->SetWriteCacheEnabled(true);

6.3.15 IsWriteCacheEnabled

bool IsWriteCacheEnabled()

Returns whether or not the cache method for optimizing performances is enabled (see 6.3.14)

Arguments:

None

Return value:

Boolean: whether or not the cache method for optimizing performances is enabled

Example:

bool cacheEnabled;

cacheEnabled = apiInstance->GetApplication()->IsWriteCacheEnabled();



6.3.16 GetAttributeType

DataObject::AttributeType GetAttributeType(const char* classname, const char* attribute)

This function returns the actual type of an object attribute.

Arguments:

const char* classname: class name for which the attribute type is considered

const char* attribute: attribute which type must be returned

Return value:

Returns the type of the attribute or TYPE_INVALID on error (no attribute of that name exists)

• TYPE_INVALID in case of error

• TYPE_INTEGER for attributes of type “int”

• TYPE_INTEGER_VEC for a vector of type “int”

• TYPE_DOUBLE for attributes of type “double”

• TYPE_DOUBLE_VEC for vectors of doubles

• TYPE_DOUBLE_MAT for a 2D matrix of doubles

• TYPE_OBJECT for an attribute of type “object”

• TYPE_OBJECT_VEC for a vector of objects

• TYPE_STRING for an attribute of type string

• TYPE_STRING_VEC for a vector of strings

• TYPE_INTEGER64 for attributes of type 64bit integer

• TYPE_INTEGER64_VEC for vector of 64bit integers

Example:

The following example displays the attribute type for a given class and attribute (entered in textboxes) in a

textbox.

DataObject::AttributeType type = apiInstance->GetApplication()->GetAttributeType( textBoxAttributeClass)

textBoxAttributeAttr); const char* strAttributeType[]={ "TYPE_INVALID","TYPE_INTEGER","TYPE_INTEGER_VEC","TYPE_DOUBLE",

"TYPE_DOUBLE_VEC","TYPE_DOUBLE_MAT","TYPE_OBJECT","TYPE_OBJECT_VEC","TYPE_STRING",

"TYPE_STRING_VEC","TYPE_INTEGER64","TYPE_INTEGER64_VEC"}; printf("Attribute %s for class %s: %s", textBoxAttributeAttr,

textBoxAttributeClass, strAttributeType[type+1]);

6.3.17 GetAttributeDescription

const Value* GetAttributeDescription(const char* classname, const char* attribute)

Returns the description of an attribute, NULL if the attribute does not exist

Arguments:




const char* attribute: attribute which description must be returned

Return value:

Pointer of type Value to the current attribute description (=string)

Example:

This example displays in a textbox the type, the description, the units and the size of a given attribute for a given

class.

DataObject::AttributeType type = apiInstance->GetApplication()->GetAttributeType( textBoxAttributeClass,

textBoxAttributeAttr); const char* strAttributeType[]={ "TYPE_INVALID","TYPE_INTEGER","TYPE_INTEGER_VEC","TYPE_DOUBLE",

"TYPE_DOUBLE_VEC","TYPE_DOUBLE_MAT","TYPE_OBJECT","TYPE_OBJECT_VEC","TYPE_STRING", "TYPE_STRING_VEC","TYPE_INTEGER64","TYPE_INTEGER64_VEC"};

const Value* descr = apiInstance->GetApplication()->GetAttributeDescription(

textBoxAttributeClass, textBoxAttributeAttr);

const Value* unit = apiInstance->GetApplication()->GetAttributeUnit(

textBoxAttributeClass,

textBoxAttributeAttr);

int countRow; int countCol;

apiInstance->GetApplication()->GetAttributeSize( textBoxAttributeClass,

textBoxAttributeAttr, countRow, countCol);

printf("Attribute %s for class %s: %s – Description: %s – Units: %s – Size: %d"’ textBoxAttributeAttr,

textBoxAttributeClass, strAttributeType[type+1],descr->GetString(), unit->GetString(), countRow, countCol);

6.3.18 GetAttributeUnit

const Value* GetAttributeUnit(const char* classname, const char* attribute)

Returns the unit of an attribute, e.g. km, MW...; NULL if the given attribute name does not exist; the string is

empty for attributes without units

Arguments:



Return value:

Pointer of type Value to the units of the considered attribute (=string)

Example:


class.



DataObject::AttributeType type = apiInstance->GetApplication()->GetAttributeType(


const char* strAttributeType[]={ "TYPE_INVALID","TYPE_INTEGER","TYPE_INTEGER_VEC","TYPE_DOUBLE", "TYPE_DOUBLE_VEC","TYPE_DOUBLE_MAT","TYPE_OBJECT","TYPE_OBJECT_VEC","TYPE_STRING",

"TYPE_STRING_VEC","TYPE_INTEGER64","TYPE_INTEGER64_VEC"};

const Value* descr = apiInstance->GetApplication()->GetAttributeDescription( textBoxAttributeClass,


const Value* unit = apiInstance->GetApplication()->GetAttributeUnit( textBoxAttributeClass,


int countRow; int countCol;

apiInstance->GetApplication()->GetAttributeSize( textBoxAttributeClass,

textBoxAttributeAttr,

countRow, countCol);

textBoxCmd->Text = sprintf("Attribute %s for class %s: %s – Description: %s – Units: %s – Size: %d"’ textBoxAttributeAttr, textBoxAttributeClass, strAttributeType[type+1],descr->GetString(), unit->GetString(),


6.3.19 GetAttributeSize

void GetAttributeSize(const char* name, const char* attribute, int& countRows, int& countCols)

This function returns the size of object attribute if this attribute is a vector or a matrix.

Arguments:



int& countRows: the returned number of rows

int& countCols: the returned number of columns

Return value:

void

Example:


class.

DataObject::AttributeType type = apiInstance->GetApplication()->GetAttributeType(



"TYPE_STRING_VEC","TYPE_INTEGER64","TYPE_INTEGER64_VEC"};





const Value* unit = apiInstance->GetApplication()->GetAttributeUnit(


int countRow;

int countCol; apiInstance->GetApplication()->GetAttributeSize(

textBoxAttributeClass, textBoxAttributeAttr,


printf("Attribute %s for class %s: %s – Description: %s – Units: %s – Size: %d"’ textBoxAttributeAttr, textBoxAttributeClass, strAttributeType[type+1],descr->GetString(), unit->GetString(), countRow, countCol);

6.3.20 Execute

Value* Execute(const char* command, const Value* inArgs, int* error)

This function executes a command on the instance of the application.

Arguments:

const char* command: the command that should be executed

const Value* inArgs: input arguments for the command to be executed

int* error: returned error code

Return value:

The function returns a pointer of type Value to the result of the command if applicable.

Example:

The following example displays the running PowerFactory instance to the screen by executing “ExecuteCmd”

which executes a line of command as it would be entered in PowerFactory input window.6

int* error;

api::Value cmd ("rcom/show"); apiInstance->GetApplication()->Execute("ExecuteCmd", &cmd, error);

6.3.21 WriteChangesToDb

void WriteChangesToDb()

This function combined with “SetWriteCacheEnabled” (see 6.3.14) is meant to optimize performances. If the write

cache flag is enabled all objects remain in “edit mode” until “WriteChangesToDb” is called and all the

modifications made to the objects are saved into the database.

Arguments:

None



Return value:

void

Example:

apiInstance->GetApplication()->WriteChangeToDb();

6.4 OutputWindow

6.4.1 MessageType

Enumerated type to define the type of message that should be displayed in PowerFactory output window: plain,

error, warning, info.

enum MessageType

{ M_PLAIN = 0, ///message not prepended by any text

M_ERROR = 1, ///message prepended by error prefix, will also popup as error dialog M_WARN = 2, ///message prepended by warning prefix

M_INFO = 4 ///message prepended by info prefix };

6.4.2 Print

void Print(MessageType type, const char* msg)

This function prints a message to the PowerFactory output window.

Arguments:

MessageType type: type of message: plain, error, warning, info (see 6.4.1)

const char* msg: the actual message to be displayed

Return value:

void

Example:

The following example displays a message in the PowerFactory output window.

api::OutputWindow* outWindow = apiInstance->GetApplication()->GetOutputWindow(); outWindow->Print(api::OutputWindow::M_INFO,"Running PowerFactory from the API");

6.4.3 Clear

void Clear()

Empties the content of the output window.

Arguments:

None



Return value:

void

Example:

The following example displays a message in the PowerFactory output window and clears it.

api::OutputWindow* outWindow = apiInstance->GetApplication()->GetOutputWindow(); outWindow->Print(api::OutputWindow::M_INFO,"Running PowerFactory from the API");

outWindow->Clear();

6.5 DataObject

6.5.1 AttributeType

Enumerated type for defining the type of object attributes

enum AttributeType {

TYPE_INVALID = -1, //error or inexisting attribute

TYPE_INTEGER = 0, //integer TYPE_INTEGER_VEC = 1, //vector of integers

TYPE_DOUBLE = 2, //double

TYPE_DOUBLE_VEC = 3, //vector of double TYPE_DOUBLE_MAT = 4, //matrix of doubles

TYPE_OBJECT = 5, //object TYPE_OBJECT_VEC = 6, //vector of objects

TYPE_STRING = 7, //string

TYPE_STRING_VEC = 8, //vector of strings

TYPE_INTEGER64 = 9, //long integer (64bits) TYPE_INTEGER64_VEC= 10, //vector of long integers

};

6.5.2 GetClassName

const Value* GetClassName()

Returns the class name of the considered DataObject (ex: ElmTerm, etc.)

Arguments:

None

Return value:

Pointer of type Value to the class name of the object, never NULL.

Example:

This example iterates through the vector of the relevant objects for calculation and displays them and their

classes in a treeview object.



int* error;


{ printf("Getting relevant object for calculation... \n");


DataObject* obj = relevantObj->VecGetDataObject(i); treeViewCalcRelevant->Nodes->Add(

gcnew String(obj->GetName()->GetString(error)) + " (" + gcnew String(obj->GetClassName()->GetString()) + ")");

} }

else {

Printf("No relevant object for calculation"); }

6.5.3 GetClassId

int GetClassId()

Returns the index of the class of the current object (see 6.3.9)

Arguments:

None

Return value:

integer representing the index number of the class of the considered object

Example:


classes id in a treeview object.

int* error; const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects();

if(relevantObj) {

textBoxCmd->Text = "Getting relevant object for calculation..." + System::Environment::NewLine

+ textBoxCmd->Text;



gcnew String(obj->GetName()->GetString(error)) + " (" + gcnew String(obj->GetClassId()) + ")");

} }

else {

textBoxCmd->Text = "No relevant object for calculation" + System::Environment::NewLine

+ textBoxCmd->Text;



}

6.5.4 GetName

const Value* GetName()

Returns the name of the object = attribute “loc_name” in PowerFactory;

Arguments:

None

Return value:

Pointer of type value with the name of the object (=string); never NULL

Example:


classes in a treeview object.

int* error;


{


+ textBoxCmd->Text; for (size_t i = 0, count = relevantObj->VecGetSize(error); i < count; ++i)

{ DataObject* obj = relevantObj->VecGetDataObject(i);

treeViewCalcRelevant->Nodes->Add( gcnew String(obj->GetName()->GetString(error))

+ " (" + gcnew String(obj->GetClassName()->GetString()) + ")"); }

} else

{ textBoxCmd->Text = "No relevant object for calculation"

+ System::Environment::NewLine + textBoxCmd->Text;

}

6.5.5 GetFullName

const Value* GetFullName(DataObject* relParent)

Returns the name, including the path, of the current object relative to a parent object

Arguments:

DataObject* relParent: relative parent = start point of the path

Return value:

Pointer of type value with the full path to the object (=string); never NULL

Example:



This example iterates through the vector of the relevant objects for calculation and displays the full name path

(starting at the database level) in a treeview object.

int* error;


{ textBoxCmd->Text = "Getting relevant object for calculation..."




gcnew String(obj->GetFullName(NULL)->GetString(error)) + " (" + gcnew String(obj->GetClassName()->GetString()) + ")");

} }

else {


+ textBoxCmd->Text;

}

6.5.6 GetChildren

const Value* GetChildren(bool recursive)

Returns a collection of children objects for the current object. If the recursive flag is set to false, only the direct

children of the object are returned else the function explores the full tree starting at the considered object.

The returned value is a vector of DataObject; it is never NULL.

Arguments

Bool recursive: false � only direct children are returned; true � the complete descendant tree is returned.

Return value:

The returned value is pointer of type value pointing to a vector of DataObject; it is never NULL.

Example:

The following code displays the project of the current user into a tree view

const Value* user(apiInstance->GetApplication()->GetCurrentUser()); TreeNode^ nodeUser = treeView1->Nodes->Add(gcnew String(user->GetDataObject()->GetName()-

>GetString())); const Value* children(user->GetDataObject()->GetChildren(false));

for (size_t i = 0, count = children->VecGetSize(); i < count; ++i) { DataObject* child = children->VecGetDataObject(i);

nodeUser->Nodes->Add(gcnew String(child->GetName()->GetString()));

6.5.7 GetParent

DataObject* GetParent()



Returns the parent object of the current object.

Arguments:

None

Return value:

the parent object of the current object; NULL if the object has no parent.

Example:

This example iterates through the vector of the relevant objects for calculation and displays them and their direct

parent in a treeview object.

int* error;






gcnew String(obj->GetName()->GetString(error)) + " (" + gcnew String(obj->GetParent()->GetName()->GetString()) + ")");

} }

else {


+ textBoxCmd->Text;

}

6.5.8 IsNetworkDataFolder

bool IsNetworkDataFolder()

Checks whether the object is a network data folder (intBmu, intZone, etc.)

Arguments:

None

Return value:

Returns “true” if the object is a network data folder, false otherwise.

Example:

#define BOOL_STR(b) (b?"true":"false")


if(relevantObj)



{





+ " (" + gcnew String(BOOL_STR(obj->IsNetworkDataFolder())) + ")"); }

} else

{ textBoxCmd->Text = "No relevant object for calculation"


}

6.5.9 IsHidden

bool IsHidden()

Checks whether the object is active or not (depending on currently activated variation stage)

Arguments:

None

Return value:

Returns “true” if the object is inactive (stored in a inactive variation stage or deleted in the current stage)

Example:

This example iterates through the vector of the relevant objects for calculation and displays them and if they are

hidden or not in a treeview object.


int* error;






gcnew String(obj->GetName()->GetString(error)) + " (" + gcnew String(BOOL_STR(obj->IsHidden())) + ")");

} }

else {



textBoxCmd->Text = "No relevant object for calculation"


}

6.5.10 IsDeleted

bool IsDeleted()

Checks whether the object is deleted (stored in the recycle bin).

Arguments:

None

Return value:

Returns “true” if the object is in the recycled bin; “false” otherwise.

Example:



if(relevantObj) {





+ " (" + gcnew String(BOOL_STR(obj->IsDeleted())) + ")");

} }

else {


+ textBoxCmd->Text; }

6.5.11 GetAttributeType

DataObject::AttributeType GetAttributeType(const char* attribute)

Returns the type of an attribute; “TYPE_INVALID” on error or for wrong attribute names (see 6.5.1 for type

definition).

Arguments:

const char* attribute: the considered attribute for which the type must be returned

Return value:



Returns a value of type AttributeType with the type of the considered attribute

Example:

This example returns the type of the “Project settings” (pPrjSettings) attribute of the active project

const Value* activProj = apiInstance->GetApplication()->GetActiveProject();

const DataObject* prj = activProj->GetDataObject(); DataObject::AttributeType type = prj->GetAttributeType("pPrjSettings");


"TYPE_STRING_VEC","TYPE_INTEGER64","TYPE_INTEGER64_VEC"}; printf( "Project settings attribute type (pPrjSettings): %s \n", strAttributeType[type+1]);

6.5.12 GetAttributeDescription

const Value* GetAttributeDescription(const char* attribute)

Returns the description of an attribute of the current object; null if the required attribute does not exist.

Arguments:

const char* attribute: the considered attribute

Return value:

A pointer of type Value to the description of the attribute (=string)

Example:

This example returns the description of the “Project settings” (pPrjSettings) attribute of the active project


const DataObject* prj = activProj->GetDataObject(); const Value* descr = prj->GetAttributeDescription("pPrjSettings");

printf("Project settings attribute description (pPrjSettings): %s\n", descr->GetString());

6.5.13 GetAttributeUnit

const Value* GetAttributeUnit(const char* attribute)

Returns the unit of an attribute of the considered object (km, MW, etc.); NULL if the attribute does not exist;

empty string for attributes without units.

Arguments:


Return value:

Pointer of type Value to the units of the given attribute of the considered object (=string)

Example:

The following example displays the units of the attribute “Retention period”


if(activProj)



{

const Value* units = activProj->GetDataObject()->GetAttributeUnit("st_retention"); printf("retention period units: %s\n",units->GetString());

}

6.5.14 GetAttributeSize

void GetAttributeSize(const char* attribute, int& countRows, int& countCols)

Returns the number of rows and columns for attributes of type matrix and vector.

Arguments:


int& countRows: number of rows (return value)

int& countCols: number of columns (return value)

Return value:

void

Example:

DataObject* myMatrix;

int* row; int* col;

myMatrix->GetAttributeSize(“matrix”, row, col);

6.5.15 GetAttributeInt

int GetAttributeInt(const char* attribute, int* error)

int GetAttributeInt(const char* attribute, int row, int col, int* error)

Returns the value of an attribute as an integer.

Arguments:


int row (optional): the row index of the element to be extracted if attribute is a matrix or a vector

int col (optional): the row index of the element to be extracted if attribute is a matrix

int* error (optional): returned error code

Return value:

Value of the considered attribute as an integer

Example:

The following example displays the value and the units of the attribute “Retention period”


if(activProj)



{

const Value* units = activProj->GetDataObject()->GetAttributeUnit("st_retention"); int nbDays = activProj->GetDataObject()->GetAttributeInt("st_retention");

printf(“retention period: %d %s”, nbDays, units->GetString()); }

6.5.16 GetAttributeDouble

double GetAttributeDouble(const char* attribute, int* error)

double GetAttributeDouble(const char* attribute, int row, int col, int* error)

Returns the value of an attribute as a double.

Arguments:



int col (optional): the row index of the element to be extracted if attribute is a matrix


Return value:

Value of the considered attribute as a double

Example:

DataObject* generator;

double P = generator->GetAttributeDouble(“pgini”);

6.5.17 GetAttributeObject

DataObject* GetAttributeObject(const char* attribute, int* error)

DataObject* GetAttributeObject(const char* attribute, int row, int* error)

Returns the value of an attribute as a pointer to a DataObject.

Arguments:



int* error (optional): the returned error code

Return value:

Pointer to DataObject containing the corresponding attribute

The data object must be released when no longer in use

Example:

DataObject* generator; DataObject* bus1 = generator->GetAttributeObject(“bus1”);



6.5.18 GetAttributeString

const Value* GetAttributeString(const char* attribute, int* error)

const Value* GetAttributeString(const char* attribute, int row, int* error)

Returns the value of an string attribute.

Arguments:




Return value:

Pointer of type “Value” to the attribute

Example:

DataObject* generator; char* name = generator->GetAttributeString(“loc_name”);

6.5.19 SetAttributeObject

void SetAttributeObject(const char* attribute, DataObject* obj, int* error)

void SetAttributeObject(const char* attribute, DataObject* obj, int row, int* error)

Sets the corresponding object attribute.

Arguments:


DataObject* obj: the new value of the attribute

int row (optional): the row index of the element to be extracted if attribute is a vector


Return value:

void

Example:

DataObject* generator;

DataObject* newbus;

generator->SetAttributeObject(“bus1”, newbus);

6.5.20 SetAttributeString

void SetAttributeString(const char* attribute, const char* value, int* error)

void SetAttributeString(const char* attribute, const char* value, int row, int col, int* error)



Sets the corresponding string attribute.

Arguments:


const char* value: the new value of the attribute

int row (optional): the row index of the element to be extracted if attribute is a vector or a matrix

int col (optional): the column index of the element to be extracted if attribute is a vector or a matrix


Return value:

void

Example:

DataObject* generator; generator->SetAttributeString(“loc_name”, “new name”);

6.5.21 SetAttributeDouble

void SetAttributeDouble(const char* attribute, double value, int* error)

void SetAttributeDouble(const char* attribute, double value, int row, int col, int* error)

Sets the corresponding double attribute.

Arguments:


double value: the new value of the attribute




Return value:

void

Example:

DataObject* generator; generator->SetAttributeDouble(“pgini”, 1.600);

6.5.22 SetAttributeInt

void SetAttributeInt(const char* attribute, int value, int* error)

void SetAttributeInt(const char* attribute, int value, int row, int col, int* error)

Sets the corresponding double attribute.



Arguments:


int value: the new value of the attribute




Return value:

void

Example:

6.5.23 ResizeAttribute

void ResizeAttribute(const char* attribute, int rowSize, int colSize, int* error)

Resize an attribute of the current object if this attribute is a matrix or a vector

Arguments:


int rowSize: the new number of rows for the element

int colSize: the new number of columns for the element


Return value:

void

Example:

obj->ResizeAttribute(“matrix”, 1, 4);

6.5.24 CreateObject

DataObject* CreateObject(const char* className, const char* locname)

Create a new object of a given class inside the considered object (if this one can hold the new object)

Returns a DataObject pointer to the newly created object if successful; NULL otherwise.

Arguments:

const char* className: the class name of the object to be created

const char* locname: the name of the new object

Return value:



Pointer to the newly created DataObject

Example:

The following example creates a new object of class “textBoxobjClass->Text” and name “textBoxobjName->Text”

in the active project.

if(apiInstance->GetApplication()->GetActiveProject())

{ DataObject* prj = apiInstance->GetApplication()->GetActiveProject()->GetDataObject();

DataObject* newObject = prj->CreateObject(textBoxobjClass->Text, textBoxobjName->Text); }

6.5.25 Execute

Value* Execute(const char* command, const Value* inArgs, int* error)

This function executes a command on the instance of the object.

Arguments:

const char* command: the command that should be executed

const Value* inArgs: input arguments for the command to be executed


Return value:

The function returns a pointer of type Value to the result of the command if applicable.

Example:

The following example executes a dpl script

void RunDplScript(char* name) {

int error = 0; int filterID = apiInstance->GetApplication()->GetClassId("ComDpl");

DataObject* comdpl = NULL; if(apiInstance->GetApplication()->GetActiveProject())

{

DataObject* prj = apiInstance->GetApplication()->GetActiveProject()->GetDataObject(); const Value* children = prj->GetChildren(false);

for (size_t i = 0, count = children->VecGetSize(); i < count; ++i) { DataObject* child = children->VecGetDataObject(i);

if (child->GetClassId() == filterID && strcmp(child->GetName()->GetString(), name) == 0) { comdpl = child;

break; }

} }

if (!comdpl) { error = 1;

printf("Cannot run dpl script %s\n",name); }

else { printf("Running dpl script %s\ …n", name);



comdpl->Execute("Execute", NULL, &error);

printf("script ok \n"); }

}

6.5.26 WriteChangesToDb

void WriteChangesToDb()

This function combined with “SetWriteCacheEnabled” (see 6.3.14) is meant to optimize performances. If the write

to cache flag is enabled all objects remain in “edit mode” until “WriteChangesToDb” is called and all the

modifications made to the current object are saved into the database.

Arguments:

None

Return value:

void

Example:

DataObject* myObj; myObj->WriteChangeToDb();

6.6 Value

6.6.1 Properties

6.6.1.1 Type

Enumerated type to define the type of a “Value” object.

enum Type { UNKNOWN, INTEGER, DOUBLE, STRING, INTEGER64, DATAOBJECT, VECTOR,

DOUBLEMATRIX, VALUE

};

6.6.1.2 Data

union Data { Data(int val) : m_int(val) {};

Data(__int64 val) : m_int64(val) {}; Data(double val) : m_double(val) {};

Data(void* val) : m_ptr(val) {}; int m_int;

__int64 m_int64; double m_double;

const void* m_ptr; };



6.6.2 Constructor / Destructor

Value(const int val)

Value(const __int64 val)

Value(const double val)

Value(const char* val)

Value(DataObject* val)

Value(Type type)

~Value()

6.6.3 GetType

const Type GetType()

Returns the actual type of the “Value” object (see 6.6.1.1 for available types)

Arguments:

None

Return value

Type =actual type of the value object

Example:


const api::Value::Type typ = activProj->GetType(); const char* strType[]={ "UNKNOWN”, “INTEGER”, “DOUBLE”, “STRING”, “VECTOR_OLD2”, “INTEGER64”,

“DATAOBJECT”, “VECTOR”, “DOUBLEMATRIX”, “VALUE"};

if(activProj)

{ printf("Active Project: %s Type: %s \n",

activProj->GetDataObject(error)->GetName()->GetString(), strType[typ]);

}

6.6.4 GetInteger

int GetInteger(int* error)

Returns an integer if the “Value” object is of integer type, otherwise returns 0.

Arguments:


Return value:

Returns an integer if the “Value” object is of integer type, otherwise returns 0.



Example:

Value* val; int iret = val->GetInteger();

6.6.5 GetInteger64

__int64 GetInteger64(int* error)

Returns a long integer if the “Value” object is of long integer type, otherwise returns 0.

Arguments:


Return value:

Returns a long integer if the “Value” object is of long integer type, otherwise returns 0.

Example:

Value* val; __int64 iret = val->GetInteger64();

6.6.6 GetDouble

double GetDouble(int* error)

Returns a double if the “Value” object is of type double, otherwise returns 0.

Arguments:


Return value:

Returns a double if the “Value” object is of type double, otherwise returns 0.

Example:

Value* val; double iret = val->Getdouble();

6.6.7 GetString

const char* GetString(int* error)

Returns a string if the “Value” object is of type string, otherwise returns NULL.

Arguments:


Return value:

Returns a string if the “Value” object is of type string, otherwise returns NULL.

Example:





printf("Description: %s", descr->GetString())

6.6.8 GetDataObject

DataObject* GetDataObject(int* error)

Returns a pointer to a “DataObject” if the “Value” object is of type DataObject, NULL otherwise.

DataObject must be released when no longer in use.

Arguments:


Return value:

Returns a pointer to a “DataObject” if the “Value” object is of type DataObject, NULL otherwise.

Example:

This example returns the description of the “Project settings” (pPrjSettings) attribute of the active project


const DataObject* prj = activProj->GetDataObject(); const Value* descr = prj->GetAttributeDescription("pPrjSettings");

printf("Project settings attribute description (pPrjSettings): %s\n", descr->GetString());

6.6.9 MatGetRowCount

unsigned int MatGetRowCount(int* error=0)

returns the number of rows/elements if the “Value” is matrix/vector

Arguments:


Return value:

Number of rows as unsigned int

Example:

Value* val;

int row = val->MatGetRowCount();

6.6.10 MatGetColCount

unsigned int MatGetColCount(int* error=0)

returns the number of columns if the “Value” is a matrix

Arguments:




Return value:

Number of columns as unsigned int

Example:

Value* val;

int col = val->MatGetColCount();

6.6.11 MatSetDouble

void MatSetDouble(const unsigned int row, const unsigned int col, const double val, int* error=0)

set the value of a double in a matrix at position (row, col)

Arguments:

const unsigned int row: row index

const unsigned int col: column index

const double val: double value to be inserted in the matrix


Return value:

void

Example:

Value* val; val->MatSetDouble(1,1,2.5);

6.6.12 MatGetDouble

double MatGetDouble(const unsigned int row, const unsigned int col, int* error=0)

returns the value of the double in the considered matrix at position (row, col)

Arguments:

const unsigned int row: row index of the considered matrix element

const unsigned int col: column index of the considered matrix element


Return value:

The value of the double at position (row, col)

Example:

double d = val->MatGetDouble(1,1);

6.6.13 SetValue

void SetValue(const int val)



void SetValue(const __int64 val)

void SetValue(const double val)

void SetValue(const char* val)

void SetValue(DataObject* val)

Set the value of a “Value” type object; value can be of types int, __int64, double, char* and DataObject*

Arguments:

According to the type of the value to be set:

const int val: if the value to be set is an integer

const __int64 val: if the value to be set is a long integer

const double val: if the value to be set is a double

const char* val: if the value to be set is a string

const DataObject* val: if the value to be set is a DataObject

Return value:

void

Example:

double d = 5.5;

Value* val; val->SetValue(d);

6.6.14 VecGetInteger

int VecGetInteger(const unsigned int index, int* error)

Returns the integer stored in a vector at position index

Arguments:

const unsigned int index: index of the element to be read


Return value:

integer stored in a vector at position index

Example:

Value* val;

int iret = val->VecGetInteger(1);

6.6.15 VecGetInteger64

__int64 VecGetInteger64(const unsigned int index, int* error)

Returns a long integer stored in a vector at position “index”



Arguments:



Return value:

Returns a long integer stored in a vector at position “index”

Example:

Value* val;

__int64 iret = val->VecGetInteger64(1);

6.6.16 VecGetDouble

double VecGetDouble(const unsigned int index, int* error)

Returns a double stored in a vector a position “index”

Arguments:



Return value:

Returns a double stored in a vector a position “index”

Example:

Value* val; double iret = val->VecGetDouble(1);

6.6.17 VecGetString

const char* VecGetString(const unsigned int index, int* error)

Returns a string of characters stored in a vector at position “index”

Arguments:



Return value:

Returns a string of characters stored in a vector at position “index”

Example:

Value* val;

char* iret = val->VecGetString(1);



6.6.18 VecGetDataObject

DataObject* VecGetDataObject(const unsigned int index, int* error)

Returns an object stored in a vector at position “index”

Arguments:



Return value:

Returns an object stored in a vector at position “index” if the considered element is a “DataObject”, NULL

otherwise.

Example:




if(relevantObj) {

printf("Getting relevant object for calculation...\n");




} }

else {

printf("No relevant object for calculation"); }

6.6.19 VecGetValue

const Value* VecGetValue(const unsigned int idx, int* error=0)

Returns a pointer to a “Value” stored in a vector at position “idx”

Arguments:



Return value:

Returns a pointer to a “Value” if the considered element is a “Value”, NULL otherwise.

Example:



Value* val;

Value* v = val->VecGetValue(1);

6.6.20 VecClear

void VecClear(int* error=0)

empties the considered vector

Arguments:


Return value:

void

Example:

Value* val; Val->VecClear();

6.6.21 VecGetSize

unsigned int VecGetSize(int* error)

Returns the size of the considered vector

Arguments:


Return value:

the size of the considered vector

Example:




if(relevantObj) {


+ textBoxCmd->Text;




} }

else {



textBoxCmd->Text = "No relevant object for calculation"


}

6.6.22 VecGetType

Type VecGetType(const unsigned int index, int* error)

returns the type (integer, string, etc.) of an element stored in a vector at position “index”

Arguments:



Return value:

Type = UNKNOWN, INTEGER, DOUBLE, STRING, VECTOR_OLD2, INTEGER64, DATAOBJECT, VECTOR,

DOUBLEMATRIX, VALUE

Example:

Value* val;

Type elType = val->VecGetType(1);

6.6.23 VecInsertInteger

void VecInsertInteger(const int val, int* error=0)

inserts an integer into a vector (at the end)

Arguments:

const int val: integer value to be inserted in the vector


Return value:

void

Example:

Value* val(VECTOR); val->VecInsertInteger(1);

6.6.24 VecInsertInt64

void VecInsertInt64(const __int64 val, int* error=0)

inserts an 64-bit integer into a vector (at the end)

Arguments:

const __int64 val: integer value to be inserted in the vector




Return value:

void

Example:

Value* val(VECTOR); val->VecInsertInt64(1);

6.6.25 VecInsertDouble

void VecInsertDouble(const double val, int* error=0)

inserts double at the end of a vector

Arguments:

const double val: double value to be inserted in the vector


Return value:

void

Example:

Value* val(VECTOR);

val->VecInsertDouble(1.5);

6.6.26 VecInsertString

void VecInsertString(const char* val, int* error=0)

inserts a string at the end of a vector

Arguments:

const char* val: string to be inserted in the vector


Return value:

void

Example:

Value* val(VECTOR); val->VecInsertString(“test string”);

6.6.27 VecInsertDataObject

void VecInsertDataObject(DataObject* val, int* error=0)

inserts a pointer to a DataObject at the end of a vector



Arguments:

DataObject* val: pointer to the DataObject to be inserted in the vector


Return value:

void

Example:

Value* val(VECTOR);

DataObject* obj; val->VecInsertDataObject(obj);

6.6.28 VecInsertValue

void VecInsertValue(const Value* val, int* error=0)

inserts a pointer to a Value at the end of a vector

Arguments:

const Value* val: pointer to the “Value” to be inserted in the vector


Return value:

void

Example:

Value* val(VECTOR);

Value* v(1); val->VecInsertValue(v);


Annexes


Annex A-1 : Application – interface with Google Earth

1 Introduction

The purpose of this application is to illustrate how DIgSILENT PowerFactory API can be used, especially within

GIS systems.


This simple toolbar allows the user to export PowerFactory diagrams to KML files, which are immediately

displayed in Google Earth, import KML files as PowerFactory projects, show and hide PowerFactory GUI and run

load flows and display the voltages at all bus bars.

The application has been written in C#. To achieve this goal, a wrapper for the API functions and classes had had

to be written first.


2 Managed Code Wrapper

2.1 Definition

A wrapper class is a class that has no functionality of its own. Its member functions hide the use of a third party

software component or an object with the non-compatible interface or a non-object-oriented implementation.

It allows the use of unmanaged code (C++ native code) with managed code (C#). The wrapper in this

application is a dll called “digApiWrapper.dll” that is included as a reference in all the projects of this application

(importing to PowerFactory, exporting to kml, etc.)

The principle is to encapsulate the unmanaged objects into managed functions and classes.

2.2 Example: Wrapping “Application” class

The wrapper for Application class of digapi.dll is called WApplication.

2.2.1 C++/CLI basic syntax

C++/CLI has a different syntax to identify managed and unmanaged code:

Native C++ C++/CLI

pointer * ^

New element new gcnew

reference & %

NULL NULL nullptr

2.2.2 Calls in C#

The new WApplication class can simply be called as if it was written directly in C#.

Example:

The following code gets the running PowerFactory application from the current api object (WApi is the wrapper

for the class “Api”) and returns the active project as a WValue (the wrappel for the class “Value”).

WApplication myPowerFactory = WApi.GetApplication();

WValue activeProj = myPowerFactory.GetActiveProject();

2.2.3 Code

This document contains only code snippets that might be helpful for understanding. The whole source code for

the wrapper is part of the following Google Earth example and can be obtained separately.


3 KML and PowerFactory Projects

To interface PowerFactory with KML language, a match must be done between objects and types of both

programs (PowerFactory and Google Earth).

KML “Extended Data” field is used to store all the PowerFactory objects specific values and attributes (e.g. Type

(typ_id), parent, etc.).

The choice of exported objects and attributes mostly depends on the desired use of the exported data; in this

example, as the second goal was to import kml files to PowerFactory, we have exported all possible objects and

attributes in order for the imported project to look like the original one.

The position of the object on the map is given by the coordinates of the “placemark”; objects like substations or

terminals are represented as kml “Point” and lines are represented by kml “LineString”.

For this application, a dll “DigKml.dll” has been written to manage, read and write kml objects from/to text files.

This dll does not include the full kml standard and all its features but only the aspects that are useful for the

purpose of this project.

Below a simple example for representing one line “Line 2” in a grid “Nine_Bus” from a project called “example1”

in kml format:

<Document id="Example1">

<name>Example1</name>

<Folder id="__Network Model_intPrjfolder_Network Data_intPrjfolder_Nine_Bus_ElmNet">

<name>Nine_Bus</name>

<visibility>1</visibility>

<Placemark id="__Network Model_intPrjfolder_Network

Data_intPrjfolder_Nine_Bus_ElmNet_System Stage Mag-A-Stat_intVariant_Line 2_ElmBranch">

<name>Line 2</name>

<ExtendedData>

<Data name="parent">

<displayName>Parent</displayName>

<value>__Network Model_intPrjfolder_Network

Data_intPrjfolder_Nine_Bus_ElmNet_System Stage Mag-A-Stat_intVariant</value>

</Data>

<Data name="class">

<displayName>Class</displayName>

<value>ElmBranch</value>

</Data>

<Data name="bus1">

<displayName>Id bus1</displayName>


Data_intPrjfolder_Nine_Bus_ElmNet_System Stage Mag-A-Stat_intVariant_Bus

7_ElmTerm_Cub_1_StaCubic</value>

</Data>

<Data name="bus2">

<displayName>Id bus2</displayName>


Data_intPrjfolder_Nine_Bus_ElmNet_System Stage Mag-A-Stat_intVariant_Bus

5_ElmTerm_Cub_3_StaCubic</value>

PowerFactory KML

Project Document

Grid Folder

Object Placemark


</Data>

</ExtendedData>

</Placemark>

</Folder>

</Document>


4 Exporting diagrams to Google Earth

4.1 Exporting

For the time being, PowerFactory does not work with geographical coordinates. During the export, the user is

asked to enter the coordinates of the bottom-left and top-right corners of the selected diagram; the program

then manages to recompute the coordinates of the displayed objects based on their position on the PowerFactory

diagram.

To convert PowerFactory project to kml, the program uses the library DigKmlExport.dll, containing the necessary

classes and functions for converting objects and generating related kml strings.

4.2 Example: exporting one diagram

Figure 5 displays the diagram in PowerFactory that will be exported. Figure 6 shows how the coordinates can be

entered by the user to choose the area of the globe where the diagram must be transferred. Figure 7 displays the

result of the kml export.

Figure 4. Export to KML


Figure 5. Diagram to be exported


Figure 6. Coordinates of the corners


Figure 7. Exported diagram


5 Importing kml files to PowerFactory

“DigKmlImport.dll” contains all the necessary functions to convert kml files and string to PowerFactory objects:

creating a new project, a new grid and setting the elements (type, attributes, etc).

Figure 9 shows the re-imported diagram (that has been previously exported)

The quality of the PowerFactory project and its usefulness highly depend on the data available in the kml file.

Figure 8. Import to PowerFactory


Figure 9. Re-imported diagram


6 Show/Hide PowerFactory

To observe and compare, the user can show or hide the PowerFactory GUI.

Figure 10. Show/Hide PowerFactory GUI

7 Running load flows

As an example of performing calculation and displaying results, the user can run a load flow on the selected

project. If no study case has been activated with the project activation, the program activates the first one

encountered or creates a new one if none has been defined in the project.


Voltage at each bus bar is then displayed as text.

Figure 11. Running Load flows

powerfactory api v3

Documents