DIgSILENT Technical

Documentation

PowerFactory API

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

PowerFactory API

Table of Contents

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

PowerFactory API

Table of Contents

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

PowerFactory API

Table of Contents

6.3.10
6.3.11
6.3.12
6.3.13
6.3.14
6.3.15
6.3.16
6.3.17
6.3.18
6.3.19
6.3.20
6.3.21

GetClassDescription ....................................................................................................................... 33
AttributeMode ............................................................................................................................... 34
SetAttributeMode ........................................................................................................................... 34
GetAttributeMode .......................................................................................................................... 34
SetWriteCacheEnabled ................................................................................................................... 35
IsWriteCacheEnabled ..................................................................................................................... 35
GetAttributeType ........................................................................................................................... 36
GetAttributeDescription .................................................................................................................. 36
GetAttributeUnit ............................................................................................................................ 37
GetAttributeSize ............................................................................................................................ 38
Execute ........................................................................................................................................ 39
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

PowerFactory API

Table of Contents

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

PowerFactory API

Table of Contents

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

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

6 Show/Hide PowerFactory ................................................................................................ 79
7 Running load flows .......................................................................................................... 79

PowerFactory API

1 Introduction

1 Introduction
The DIgSILENT PowerFactory Application Programming interface (API) offers third party applications the
possibility to embed PowerFactorys 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.).

PowerFactory API

2 Overview

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.

PowerFactory
Application
3rd Party
Application

API

Figure 1.

PowerFactory API

2 Overview

2.2 Physical Structure

digapl.dl
l
digadm.dl
l

digapi.dll
void Function1();
void Function2();
void Function3();
...

digcal.dl
l

dig*.dl

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

PowerFactory API

10

2 Overview

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)

PowerFactory API

11

3 Create and Destroy an Instance of the API

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

PowerFactory API

12

4 Accessing Objects and Attributes

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 DataObjects
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:

PowerFactory API

13

4 Accessing Objects and Attributes

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

PowerFactory API

14

4 Accessing Objects and Attributes

}
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);
}

PowerFactory API

15

4 Accessing Objects and Attributes

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 (
variables appearing in the Load-Flow/Short-Circuit tab.

) and then check the

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

PowerFactory API

16

5 Executing Commands

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");
apiInstance->GetApplication()->Execute("ExecuteCmd", &cmd, error);

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 shortcircuit has to be performed.

Once again, the generic function ExecuteCmd can also be used for running calculations like load-flows, shortcircuits 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:

PowerFactory API

17

5 Executing Commands

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

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

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:

PowerFactory API

18

5 Executing Commands

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:

PowerFactory API

19

5 Executing Commands

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

PowerFactory API

20

5 Executing Commands

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

PowerFactory API

21

5 Executing Commands

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
Returned Value* is never NULL but contained DataObject might be null if folder or no active object found

5.4.15 GetActiveRecordingStage
Description:
Returns the active system stage 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.16 IsLdfValid
Description:
Identical to DPL routines, checks if valid results are available.
Arguments:
NULL
Return value:
Value::INTEGER
Returned Value* is never NULL
0 = false
1 = true

PowerFactory API

22

5 Executing Commands

5.4.17 IsRmsValid
Description:
Identical to DPL routines, checks if valid results are available.
Arguments:
NULL
Return value:
Value::INTEGER
Returned Value* is never NULL
0 = false
1 = true

5.4.18 IsShcValid
Description:
Identical to DPL routines, checks if valid results are available.
Arguments:
NULL
Return value:
Value::INTEGER
Returned Value* is never NULL
0 = false
1 = true

5.4.19 IsSimValid
Description:
Identical to DPL routines, checks if valid results are available.
Arguments:
NULL
Return value:
Value::INTEGER
Returned Value* is never NULL
0 = false
1 = true

PowerFactory API

23

5 Executing Commands

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:
Value::INTEGER, 0=false, >0=true

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:

PowerFactory API

24

5 Executing Commands

NULL
Return value:
Value::INTEGER, 0=false, >0=true

5.5.5 HasResults
Description:
Checks if current object has calculation results.
Arguments:
NULL
Return value:
Value::INTEGER, 0=false, >0=true

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

PowerFactory API

25

5 Executing Commands

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

PowerFactory API

26

6 References: Classes, Objects and Methods

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.

PowerFactory API

27

6 References: Classes, Objects and Methods

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:

PowerFactory API

28

6 References: Classes, Objects and Methods

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.
apiInstance = CreateApiInstance();
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:
apiInstance = CreateApiInstance();
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"

PowerFactory API

29

6 References: Classes, Objects and Methods

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.
apiInstance = CreateApiInstance();
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()

PowerFactory API

30

6 References: Classes, Objects and Methods

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

PowerFactory API

31

6 References: Classes, Objects and Methods

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.

PowerFactory API

32

6 References: Classes, Objects and Methods

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:

PowerFactory API

33

6 References: Classes, Objects and Methods

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
MODE_INTERNAL
};

= 0,
=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:
MODE_DISPLAYED = as displayed in PF (unit conversion applied)
MODE_INTERNAL = as internally stored
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:

PowerFactory API

34

6 References: Classes, Objects and Methods

AttributeMode
MODE_DISPLAYED = as displayed in PF (unit conversion applied)
MODE_INTERNAL = as internally stored
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();

PowerFactory API

35

6 References: Classes, Objects and Methods

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* classname: class name for which the attribute type is considered

PowerFactory API

36

6 References: Classes, Objects and Methods

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:
const char* classname: class name for which the attribute type is considered
const char* attribute: attribute which description must be returned
Return value:
Pointer of type Value to the units of the considered attribute (=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.

PowerFactory API

37

6 References: Classes, Objects and Methods

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);
textBoxCmd->Text = sprintf("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.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:
const char* classname: class name for which the attribute type is considered
const char* attribute: attribute which description must be returned
int& countRows: the returned number of rows
int& countCols: the returned number of columns
Return value:
void
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"};

PowerFactory API

38

6 References: Classes, Objects and Methods

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

PowerFactory API

39

6 References: Classes, Objects and Methods

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

PowerFactory API

40

6 References: Classes, Objects and Methods

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
TYPE_OBJECT_VEC

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

TYPE_STRING
TYPE_STRING_VEC

= 7, //string
= 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.

PowerFactory API

41

6 References: Classes, Objects and Methods

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->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:
This example iterates through the vector of the relevant objects for calculation and displays them and their
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;
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->GetClassId()) + ")");
}
}
else
{
textBoxCmd->Text = "No relevant object for calculation"
+ System::Environment::NewLine
+ textBoxCmd->Text;

PowerFactory API

42

6 References: Classes, Objects and Methods

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:
This example iterates through the vector of the relevant objects for calculation and displays them and their
classes 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;
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:

PowerFactory API

43

6 References: Classes, Objects and Methods

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;
const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects();
if(relevantObj)
{
textBoxCmd->Text = "Getting relevant object for calculation..."
+ System::Environment::NewLine
+ 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->GetFullName(NULL)->GetString(error))
+ " (" + gcnew String(obj->GetClassName()->GetString()) + ")");
}
}
else
{
textBoxCmd->Text = "No relevant object for calculation"
+ System::Environment::NewLine
+ 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()

PowerFactory API

44

6 References: Classes, Objects and Methods

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;
const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects();
if(relevantObj)
{
textBoxCmd->Text = "Getting relevant object for calculation..."
+ System::Environment::NewLine
+ 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->GetParent()->GetName()->GetString()) + ")");
}
}
else
{
textBoxCmd->Text = "No relevant object for calculation"
+ System::Environment::NewLine
+ 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")
int* error;
const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects();
if(relevantObj)

PowerFactory API

45

6 References: Classes, Objects and Methods

{
textBoxCmd->Text = "Getting relevant object for calculation..."
+ System::Environment::NewLine
+ 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(BOOL_STR(obj->IsNetworkDataFolder())) + ")");
}
}
else
{
textBoxCmd->Text = "No relevant object for calculation"
+ System::Environment::NewLine
+ textBoxCmd->Text;
}

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.
#define BOOL_STR(b) (b?"true":"false")
int* error;
const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects();
if(relevantObj)
{
textBoxCmd->Text = "Getting relevant object for calculation..."
+ System::Environment::NewLine
+ 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(BOOL_STR(obj->IsHidden())) + ")");
}
}
else
{

PowerFactory API

46

6 References: Classes, Objects and Methods

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

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

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:
#define BOOL_STR(b) (b?"true":"false")
int* error;
const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects();
if(relevantObj)
{
textBoxCmd->Text = "Getting relevant object for calculation..."
+ System::Environment::NewLine
+ 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(BOOL_STR(obj->IsDeleted())) + ")");
}
}
else
{
textBoxCmd->Text = "No relevant object for calculation"
+ System::Environment::NewLine
+ 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:

PowerFactory API

47

6 References: Classes, Objects and Methods

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");
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( "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 Value* activProj = apiInstance->GetApplication()->GetActiveProject();
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:
const char* attribute: the considered attribute
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
const Value* activProj = apiInstance->GetApplication()->GetActiveProject();
if(activProj)

PowerFactory API

48

6 References: Classes, Objects and Methods

{
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:
const char* attribute: the considered attribute
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:
const char* attribute: the considered attribute
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
const Value* activProj = apiInstance->GetApplication()->GetActiveProject();
if(activProj)

PowerFactory API

49

6 References: Classes, Objects and Methods

{
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:
const char* attribute: the considered attribute
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 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:
const char* attribute: the considered attribute
int row (optional): the row index of the element to be extracted if attribute is a matrix or a vector
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);

PowerFactory API

50

6 References: Classes, Objects and Methods

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:
const char* attribute: the considered attribute
int row (optional): the row index of the element to be extracted if attribute is a matrix or a vector
int* error (optional): returned error code
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:
const char* attribute: the considered attribute
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
int* error (optional): returned error code
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)

PowerFactory API

51

6 References: Classes, Objects and Methods

Sets the corresponding string attribute.

Arguments:
const char* attribute: the considered attribute
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
int* error (optional): returned error code
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:
const char* attribute: the considered attribute
double 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
int* error (optional): returned error code
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.

PowerFactory API

52

6 References: Classes, Objects and Methods

Arguments:
const char* attribute: the considered attribute
int 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
int* error (optional): returned error code
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:
const char* attribute: the considered attribute
int rowSize: the new number of rows for the element
int colSize: the new number of columns for the element
int* error (optional): returned error code
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:

PowerFactory API

53

6 References: Classes, Objects and Methods

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
int* error (optional): 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 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);

PowerFactory API

54

6 References: Classes, Objects and Methods

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;
};

PowerFactory API

55

6 References: Classes, Objects and Methods

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 Value* activProj = apiInstance->GetApplication()->GetActiveProject();
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:
int* error (optional): returned error code
Return value:
Returns an integer if the Value object is of integer type, otherwise returns 0.

PowerFactory API

56

6 References: Classes, Objects and Methods

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:
int* error (optional): returned error code
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:
int* error (optional): returned error code
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:
int* error (optional): returned error code
Return value:
Returns a string if the Value object is of type string, otherwise returns NULL.
Example:

PowerFactory API

57

6 References: Classes, Objects and Methods

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

textBoxAttributeClass,
textBoxAttributeAttr);
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:
int* error (optional): returned error code
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 Value* activProj = apiInstance->GetApplication()->GetActiveProject();
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:
int* error (optional): returned error code
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:
int* error (optional): returned error code

PowerFactory API

58

6 References: Classes, Objects and Methods

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
int* error (optional): returned error code
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
int* error (optional): returned error code
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)

PowerFactory API

59

6 References: Classes, Objects and Methods

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
int* error (optional): returned error code
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

PowerFactory API

60

6 References: Classes, Objects and Methods

Arguments:
const unsigned int index: index of the element to be read
int* error (optional): returned error code
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:
const unsigned int index: index of the element to be read
int* error (optional): returned error code
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:
const unsigned int index: index of the element to be read
int* error (optional): returned error code
Return value:
Returns a string of characters stored in a vector at position index
Example:
Value* val;
char* iret = val->VecGetString(1);

PowerFactory API

61

6 References: Classes, Objects and Methods

6.6.18 VecGetDataObject
DataObject* VecGetDataObject(const unsigned int index, int* error)
Returns an object stored in a vector at position index
Arguments:
const unsigned int index: index of the element to be read
int* error (optional): returned error code
Return value:
Returns an object stored in a vector at position index if the considered element is a DataObject, NULL
otherwise.
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;
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->VecGetDataObject(i);
treeViewCalcRelevant->Nodes->Add(
gcnew String(obj->GetName()->GetString(error))
+ " (" + gcnew String(obj->GetParent()->GetName()->GetString()) + ")");
}
}
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:
const unsigned int index: index of the element to be read
int* error (optional): returned error code
Return value:
Returns a pointer to a Value if the considered element is a Value, NULL otherwise.
Example:

PowerFactory API

62

6 References: Classes, Objects and Methods

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

6.6.20 VecClear
void VecClear(int* error=0)
empties the considered vector
Arguments:
int* error (optional): returned error code
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:
int* error (optional): returned error code
Return value:
the size of the considered vector
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;
const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects();
if(relevantObj)
{
textBoxCmd->Text = "Getting relevant object for calculation..."
+ System::Environment::NewLine
+ 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->GetParent()->GetName()->GetString()) + ")");
}
}
else
{

PowerFactory API

63

6 References: Classes, Objects and Methods

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

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

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:
const unsigned int index: index of the element to be read
int* error (optional): returned error code
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
int* error (optional): returned error code
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

PowerFactory API

64

6 References: Classes, Objects and Methods

int* error (optional): returned error code

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
int* error (optional): returned error code
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
int* error (optional): returned error code
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

PowerFactory API

65

6 References: Classes, Objects and Methods

Arguments:
DataObject* val: pointer to the DataObject to be inserted in the vector
int* error (optional): returned error code
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
int* error (optional): returned error code
Return value:
void
Example:
Value* val(VECTOR);
Value* v(1);
val->VecInsertValue(v);

PowerFactory API

66

Annexes

PowerFactory API

67

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.

PowerFactory API

68

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.

PowerFactory API

69

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.

PowerFactory API

70

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).
PowerFactory

KML

Project

Document

Grid

Folder

Object

Placemark

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>
<value>__Network Model_intPrjfolder_Network
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>
<value>__Network Model_intPrjfolder_Network
Data_intPrjfolder_Nine_Bus_ElmNet_System Stage Mag-A-Stat_intVariant_Bus
5_ElmTerm_Cub_3_StaCubic</value>

PowerFactory API

71

</Data>
</ExtendedData>
</Placemark>
</Folder>
</Document>

PowerFactory API

72

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

PowerFactory API

73

Figure 5. Diagram to be exported

PowerFactory API

74

Figure 6. Coordinates of the corners

PowerFactory API

75

Figure 7. Exported diagram

PowerFactory API

76

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

PowerFactory API

77

Figure 9. Re-imported diagram

PowerFactory API

78

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.

PowerFactory API

79

Voltage at each bus bar is then displayed as text.

Figure 11. Running Load flows

PowerFactory API

80