PowerFactory API v3

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: mail@digsilent.de
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.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
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
}
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
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.1 On an instance of the class Application
The Application class contains an Execute method to execute a set of generic commands like Activate to
activate a project
ExecuteCmd allows reproducing commands like they would be entered in PowerFactory input window.
Example:
To show PowerFactory user interface
api::Value cmd ("rcom/show");
apiInstance->GetApplication()->Execute("ExecuteCmd", &cmd, error);
To hide PowerFactory user interface
api::Value cmd ("rcom/hide");
5.2 On an instance of a DataObject

Commands can also be executed on an object level by the method Execute. (See also 5.5 and 6.5.25)
Example: executing a DPL script
comdpl->Execute("Execute", NULL, error);
5.3 Running Calculations

Calculations can be run by using the Execute method on a command object. The following example runs a
short-circuit calculation with a short-circuit at a specific terminal:
if (comShc == null)
{
comShc = actStdyCase->CreateObject("ComShc", "Short-Circuit");
}
comShc->SetAttributeObject("shcobj", elmTerm);
comShc->Execute("Execute", NULL);
Where comShc is an ComShc object (short-circuit command), elmTerm is the terminal where the 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");
For a short-circuit calculation:
PowerFactory API
17
api::Value cmd ("shc/iec/3psc/max/agi/all/asc");

5.4 Available Generic Functions on api::Application instance

api->GetApplication()->Execute(string command, const Value* inArgs, int* error)
Where command can be one of the following:
5.4.1 SearchFull
Description:
Searches and returns an object specified by path.
Arguments:
Value::VECTOR
[0]: string, full path of object to search (e.g. .\Digsi.intUser\MyPrj.intPrj)
[1]: optional DataObject, parent from which to start search (default is database root)
Return value:
Value::DataObject
Returned Value* is never NULL but contained DataObject might be NULL if no object was found.
5.4.2 GetDefaultLocation
Description:
Gets default location where objects of given class name are stored. e.g. Library for Typ*
Arguments:
Value::VECTOR
[0]: string, class name for which the default location is searched
[1]: optional integer, create location if not exist (0 = no create, default; 1 = create)
Return value:
Value::DataObject
Returned Value* is never NULL but contained DataObject might be NULL if location exists
5.4.3 NewProject
Description:
Creates a new project (using copy template in PF) and returns it.
Arguments:
PowerFactory API
18
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
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
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
Return value:
Value::DataObject
Returned Value* is never NULL but contained DataObject might be null if folder or no active object found
5.4.14 GetActiveScenario
Description:
Returns the active scenario object.
Arguments:
NULL
Return value:
Value::DataObject
5.4.15 GetActiveRecordingStage
Description:
Returns the active system stage object.
Arguments:
NULL
Return value:
Value::DataObject
5.4.16 IsLdfValid
Description:
Identical to DPL routines, checks if valid results are available.
Arguments:
NULL
Return value:
Value::INTEGER
0 = false
1 = true
PowerFactory API
22
5.4.17 IsRmsValid
Description:
Arguments:
NULL
Return value:
Value::INTEGER
0 = false
1 = true
5.4.18 IsShcValid
Description:
Arguments:
NULL
Return value:
Value::INTEGER
0 = false
1 = true
5.4.19 IsSimValid
Description:
Arguments:
NULL
Return value:
Value::INTEGER
0 = false
1 = true
PowerFactory API
23
5.5 Available Generic Functions on api::DataObject instance

DataObject_Instance->Execute(string command, const Value* inArgs, int* error)
Where command can be one of the following:
5.5.1 SlotUpdate
Description:
Performs a slot update for objects of class ElmComp
Arguments:
NULL
Return value:
None
5.5.2 IsBlockEncrypted
Description:
For objects of class BlkDef only, checks if block is encrypted
Arguments:
NULL
Return value:
Value::INTEGER, 0=false, >0=true
5.5.3 IsTransformer
Description:
Checks if current object is a transformer, Tr2, Tr2n, Tr3
Arguments:
NULL
Return value:
5.5.4 IsOutOfCalculation
Description:
Checks if current object is out of calculation. This status is determined by outserv flag and (optionally) automatic
out-of-calc detection.
Arguments:
PowerFactory API
24
NULL
Return value:
5.5.5 HasResults
Description:
Checks if current object has calculation results.
Arguments:
NULL
Return value:
5.5.6 GetConnectionCount
Description:
Number of connections for given object, e.g. ElmLne->2
Arguments:
NULL
Return value:
Value::INTEGER
5.5.7 GetActiveGrids
Description:
Returns all currently active grids (ElmNet objects). Returned value might be empty, but is never null.
Arguments:
NULL
Return value:
Value::VECTOR, entries of type DataObject
5.5.8 GetProjectFolder
Description:
Returns the project folder for given type, e.g. scen->Scenario. Same as DPL routine GetProjectFolder()
Arguments:
either
PowerFactory API
25
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.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.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
0 on success, >0 on error

Example:
api::Value* user = apiInstance->GetApplication()->GetCurrentUser();
apiInstance->ReleaseValue(user);
6.2.4 GetApplication
Application* GetApplication()
The function returns an instance of the application. There exists only one application object per Api instance. This
application object must not be deleted.
Arguments:
None
Return value:
Pointer to the instance of an application object, never NULL
Example:
The following example displays in the command window the version of the running instance of PowerFactory.
std::cout << "PowerFactory version:" << apiInstance->GetApplication()->GetVersion()->GetString() <<
std::endl;
6.2.5 IsDebug
bool IsDebug()
Arguments:
None
Return value:
True if PowerFactory is in debug mode; false otherwise.
Example:
if(apiInstance->IsDebug())
{
std::cout << "PowerFactory running in debug mode" << std::endl;
}
6.3 Application
6.3.1 GetVersion
const Value* GetVersion()
The function returns the version of the currently running PowerFactory, e.g. "14.0.505"
PowerFactory API
29
Arguments:
None
Return value:
Pointer to a Value object holding version information of PowerFactory application; returned string is never null
and must be released when no longer in use.
Example:
The following example displays in the command window the version of the running instance of PowerFactory.
std::cout << "PowerFactory version:" << apiInstance->GetApplication()->GetVersion()->GetString() <<
std::endl;
6.3.2 GetTempDirectory
const Value* GetTempDirectory()
Returns the path to the temporary directory of the running instance of PowerFactory
Arguments:
None
Return value:
A pointer of type Value pointing to a string with the temporary directory of PowerFactory
Example:
std::cout << apiInstance->GetApplication()->GetTempDirectory()->GetString() << std::endl;
6.3.3 GetWorkingDirectory
const Value* GetWorkingDirectory()
Returns the path to the working directory of the running instance of PowerFactory
Arguments:
None
Returns
A pointer of type Value pointing to a string with the working directory of PowerFactory
Example:
std::cout << apiInstance->GetApplication()->GetWorkingDirectory()->GetString() << std::endl;
6.3.4 GetOutputWindow
OutputWindow* GetOutputWindow()
PowerFactory API
30
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
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
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
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:
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
AttributeMode
Example:
This example displays in a textbox the attribute mode
api::Application::AttributeMode mode = apiInstance->GetApplication()->GetAttributeMode();
const char* strAttributeMode[]={"MODE_DISPLAYED","MODE_INTERNAL"};
printf("Attribute mode: %s \n", strAttributeMode[mode]);
6.3.14 SetWriteCacheEnabled
void SetWriteCacheEnabled(bool enabled)
This function intends to optimize performances. In order to modify objects in PowerFactory, those must be set in
a special edit mode before any value can be changed. Switching back and forth between edit mode and stored
mode is time consuming; enabling the write cache flag will set objects in edit mode and they will not be switched
back until WriteChangeToDb (see 6.3.21) is called.
Default value: disabled.
Arguments:
Bool enabled: true = enabled; false = disabled
Return value:
void
Example:
apiInstance->GetApplication()->SetWriteCacheEnabled(true);
6.3.15 IsWriteCacheEnabled
bool IsWriteCacheEnabled()
Returns whether or not the cache method for optimizing performances is enabled (see 6.3.14)
Arguments:
None
Return value:
Boolean: whether or not the cache method for optimizing performances is enabled
Example:
bool cacheEnabled;
cacheEnabled = apiInstance->GetApplication()->IsWriteCacheEnabled();
PowerFactory API
35
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:
PowerFactory API
36
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.
const Value* descr = apiInstance->GetApplication()->GetAttributeDescription(
const Value* unit = apiInstance->GetApplication()->GetAttributeUnit(
int countRow;
int countCol;
apiInstance->GetApplication()->GetAttributeSize(
textBoxAttributeAttr,
countRow, countCol);
printf("Attribute %s for class %s: %s Description: %s Units: %s Size: %d" textBoxAttributeAttr,
textBoxAttributeClass, strAttributeType[type+1],descr->GetString(), unit->GetString(), countRow, countCol);
6.3.18 GetAttributeUnit
const Value* GetAttributeUnit(const char* classname, const char* attribute)
Returns the unit of an attribute, e.g. km, MW...; NULL if the given attribute name does not exist; the string is
empty for attributes without units
Arguments:
Return value:
Pointer of type Value to the units of the considered attribute (=string)
Example:
class.
PowerFactory API
37

int countRow;
int countCol;
textBoxCmd->Text = sprintf("Attribute %s for class %s: %s Description: %s Units: %s Size: %d"
textBoxAttributeAttr, textBoxAttributeClass, strAttributeType[type+1],descr->GetString(), unit->GetString(),
6.3.19 GetAttributeSize
void GetAttributeSize(const char* name, const char* attribute, int& countRows, int& countCols)
This function returns the size of object attribute if this attribute is a vector or a matrix.
Arguments:
int& countRows: the returned number of rows
int& countCols: the returned number of columns
Return value:
void
Example:
class.
PowerFactory API
38

int countRow;
int 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");
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
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.
6.4.3 Clear
void Clear()
Empties the content of the output window.
Arguments:
None
PowerFactory API
40
Return value:
void
Example:
The following example displays a message in the PowerFactory output window and clears it.
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
int* error;
if(relevantObj)
{
printf("Getting relevant object for calculation... \n");
{
DataObject* obj = relevantObj->VecGetDataObject(i);
treeViewCalcRelevant->Nodes->Add(
gcnew String(obj->GetName()->GetString(error))
+ " (" + gcnew String(obj->GetClassName()->GetString()) + ")");
}
}
else
{
Printf("No relevant object for calculation");
}
6.5.3 GetClassId
int GetClassId()
Returns the index of the class of the current object (see 6.3.9)
Arguments:
None
Return value:
integer representing the index number of the class of the considered object
Example:
classes id in a treeview object.
int* error;
if(relevantObj)
{
textBoxCmd->Text = "Getting relevant object for calculation..."
+ System::Environment::NewLine
+ textBoxCmd->Text;
{
+ " (" + gcnew String(obj->GetClassId()) + ")");
}
}
else
{
textBoxCmd->Text = "No relevant object for calculation"
+ textBoxCmd->Text;
PowerFactory API
42
6.5.4 GetName
const Value* GetName()
Returns the name of the object = attribute loc_name in PowerFactory;
Arguments:
None
Return value:
Pointer of type value with the name of the object (=string); never NULL
Example:
classes in a treeview object.
int* error;
if(relevantObj)
{
+ textBoxCmd->Text;
{
}
}
else
{
+ 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
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;
if(relevantObj)
{
+ textBoxCmd->Text;
{
gcnew String(obj->GetFullName(NULL)->GetString(error))
}
}
else
{
+ textBoxCmd->Text;
}
6.5.6 GetChildren
const Value* GetChildren(bool recursive)
Returns a collection of children objects for the current object. If the recursive flag is set to false, only the direct
children of the object are returned else the function explores the full tree starting at the considered object.
The returned value is a vector of DataObject; it is never NULL.
Arguments
Bool recursive: false only direct children are returned; true the complete descendant tree is returned.
Return value:
The returned value is pointer of type value pointing to a vector of DataObject; it is never NULL.
Example:
The following code displays the project of the current user into a tree view
const Value* user(apiInstance->GetApplication()->GetCurrentUser());
TreeNode^ nodeUser = treeView1->Nodes->Add(gcnew String(user->GetDataObject()->GetName()>GetString()));
const Value* children(user->GetDataObject()->GetChildren(false));
for (size_t i = 0, count = children->VecGetSize(); i < count; ++i) {
DataObject* child = children->VecGetDataObject(i);
nodeUser->Nodes->Add(gcnew String(child->GetName()->GetString()));
6.5.7 GetParent
DataObject* GetParent()
PowerFactory API
44
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;
if(relevantObj)
{
+ textBoxCmd->Text;
{
+ " (" + gcnew String(obj->GetParent()->GetName()->GetString()) + ")");
}
}
else
{
+ textBoxCmd->Text;
}
6.5.8 IsNetworkDataFolder
bool IsNetworkDataFolder()
Checks whether the object is a network data folder (intBmu, intZone, etc.)
Arguments:
None
Return value:
Returns true if the object is a network data folder, false otherwise.
Example:
#define BOOL_STR(b) (b?"true":"false")
int* error;
if(relevantObj)
PowerFactory API
45
{
+ textBoxCmd->Text;
{
+ " (" + gcnew String(BOOL_STR(obj->IsNetworkDataFolder())) + ")");
}
}
else
{
+ 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.
int* error;
if(relevantObj)
{
+ textBoxCmd->Text;
{
+ " (" + gcnew String(BOOL_STR(obj->IsHidden())) + ")");
}
}
else
{
PowerFactory API
46

+ 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:
int* error;
if(relevantObj)
{
+ textBoxCmd->Text;
{
+ " (" + gcnew String(BOOL_STR(obj->IsDeleted())) + ")");
}
}
else
{
+ textBoxCmd->Text;
}
6.5.11 GetAttributeType
DataObject::AttributeType GetAttributeType(const char* attribute)
Returns the type of an attribute; TYPE_INVALID on error or for wrong attribute names (see 6.5.1 for type
definition).
Arguments:
const char* attribute: the considered attribute for which the type must be returned
Return value:
PowerFactory API
47
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");
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* descr = prj->GetAttributeDescription("pPrjSettings");
printf("Project settings attribute description (pPrjSettings): %s\n", descr->GetString());
6.5.13 GetAttributeUnit
const Value* GetAttributeUnit(const char* attribute)
Returns the unit of an attribute of the considered object (km, MW, etc.); NULL if the attribute does not exist;
empty string for attributes without units.
Arguments:
Return value:
Pointer of type Value to the units of the given attribute of the considered object (=string)
Example:
The following example displays the units of the attribute Retention period
if(activProj)
PowerFactory API
48
{
const Value* units = activProj->GetDataObject()->GetAttributeUnit("st_retention");
printf("retention period units: %s\n",units->GetString());
}
6.5.14 GetAttributeSize
void GetAttributeSize(const char* attribute, int& countRows, int& countCols)
Returns the number of rows and columns for attributes of type matrix and vector.
Arguments:
int& countRows: number of rows (return value)
int& countCols: number of columns (return value)
Return value:
void
Example:
DataObject* myMatrix;
int* row;
int* col;
myMatrix->GetAttributeSize(matrix, row, col);
6.5.15 GetAttributeInt
int GetAttributeInt(const char* attribute, int* error)
int GetAttributeInt(const char* attribute, int row, int col, int* error)
Returns the value of an attribute as an integer.
Arguments:
int row (optional): the row index of the element to be extracted if attribute is a matrix or a vector
int col (optional): the row index of the element to be extracted if attribute is a matrix
int* error (optional): returned error code
Return value:
Value of the considered attribute as an integer
Example:
The following example displays the value and the units of the attribute Retention period
if(activProj)
PowerFactory API
49
{
const Value* units = activProj->GetDataObject()->GetAttributeUnit("st_retention");
int nbDays = activProj->GetDataObject()->GetAttributeInt("st_retention");
printf(retention period: %d %s, nbDays, units->GetString());
}
6.5.16 GetAttributeDouble
double GetAttributeDouble(const char* attribute, int* error)
double GetAttributeDouble(const char* attribute, int row, int col, int* error)
Returns the value of an attribute as a double.
Arguments:
int col (optional): the row index of the element to be extracted if attribute is a matrix
Return value:
Value of the considered attribute as a double
Example:
DataObject* generator;
double P = generator->GetAttributeDouble(pgini);
6.5.17 GetAttributeObject
DataObject* GetAttributeObject(const char* attribute, int* error)
DataObject* GetAttributeObject(const char* attribute, int row, int* error)
Returns the value of an attribute as a pointer to a DataObject.
Arguments:
int* error (optional): the returned error code
Return value:
Pointer to DataObject containing the corresponding attribute
The data object must be released when no longer in use
Example:
DataObject* bus1 = generator->GetAttributeObject(bus1);
PowerFactory API
50
6.5.18 GetAttributeString
const Value* GetAttributeString(const char* attribute, int* error)
const Value* GetAttributeString(const char* attribute, int row, int* error)
Returns the value of an string attribute.
Arguments:
Return value:
Pointer of type Value to the attribute
Example:
char* name = generator->GetAttributeString(loc_name);
6.5.19 SetAttributeObject
void SetAttributeObject(const char* attribute, DataObject* obj, int* error)
void SetAttributeObject(const char* attribute, DataObject* obj, int row, int* error)
Sets the corresponding object attribute.
Arguments:
DataObject* obj: the new value of the attribute
int row (optional): the row index of the element to be extracted if attribute is a vector
Return value:
void
Example:
DataObject* 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
Sets the corresponding string attribute.

Arguments:
const char* value: the new value of the attribute
int row (optional): the row index of the element to be extracted if attribute is a vector or a matrix
int col (optional): the column index of the element to be extracted if attribute is a vector or a matrix
Return value:
void
Example:
generator->SetAttributeString(loc_name, new name);
6.5.21 SetAttributeDouble
void SetAttributeDouble(const char* attribute, double value, int* error)
void SetAttributeDouble(const char* attribute, double value, int row, int col, int* error)
Sets the corresponding double attribute.
Arguments:
double value: the new value of the attribute
Return value:
void
Example:
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
Arguments:
int value: the new value of the attribute
Return value:
void
Example:
6.5.23 ResizeAttribute
void ResizeAttribute(const char* attribute, int rowSize, int colSize, int* error)
Resize an attribute of the current object if this attribute is a matrix or a vector
Arguments:
int rowSize: the new number of rows for the element
int colSize: the new number of columns for the element
Return value:
void
Example:
obj->ResizeAttribute(matrix, 1, 4);
6.5.24 CreateObject
DataObject* CreateObject(const char* className, const char* locname)
Create a new object of a given class inside the considered object (if this one can hold the new object)
Returns a DataObject pointer to the newly created object if successful; NULL otherwise.
Arguments:
const char* className: the class name of the object to be created
const char* locname: the name of the new object
Return value:
PowerFactory API
53
Pointer to the newly created DataObject

Example:
The following example creates a new object of class textBoxobjClass->Text and name textBoxobjName->Text
in the active project.
if(apiInstance->GetApplication()->GetActiveProject())
{
DataObject* prj = apiInstance->GetApplication()->GetActiveProject()->GetDataObject();
DataObject* newObject = prj->CreateObject(textBoxobjClass->Text, textBoxobjName->Text);
}
6.5.25 Execute
Value* Execute(const char* command, const Value* inArgs, int* error)
This function executes a command on the instance of the object.
Arguments:
const char* command: the command that should be executed
const Value* inArgs: input arguments for the command to be executed
Return value:
The function returns a pointer of type Value to the result of the command if applicable.
Example:
The following example executes a dpl script
void RunDplScript(char* name)
{
int error = 0;
int filterID = apiInstance->GetApplication()->GetClassId("ComDpl");
DataObject* comdpl = NULL;
if(apiInstance->GetApplication()->GetActiveProject())
{
DataObject* prj = apiInstance->GetApplication()->GetActiveProject()->GetDataObject();
const Value* children = prj->GetChildren(false);
for (size_t i = 0, count = children->VecGetSize(); i < count; ++i) {
DataObject* child = children->VecGetDataObject(i);
if (child->GetClassId() == filterID && strcmp(child->GetName()->GetString(), name) == 0) {
comdpl = child;
break;
}
}
}
if (!comdpl) {
error = 1;
printf("Cannot run dpl script %s\n",name);
}
else {
printf("Running dpl script %s\ n", name);
PowerFactory API
54
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.6.2 Constructor / Destructor

Value(const int val)
Value(const __int64 val)
Value(const double val)
Value(const char* val)
Value(DataObject* val)
Value(Type type)
~Value()
6.6.3 GetType
const Type GetType()
Returns the actual type of the Value object (see 6.6.1.1 for available types)
Arguments:
None
Return value
Type =actual type of the value object
Example:
const api::Value::Type typ = activProj->GetType();
const char* strType[]={ "UNKNOWN, INTEGER, DOUBLE, STRING, VECTOR_OLD2, INTEGER64,
DATAOBJECT, VECTOR, DOUBLEMATRIX, VALUE"};
if(activProj)
{
printf("Active Project: %s Type: %s \n",
activProj->GetDataObject(error)->GetName()->GetString(),
strType[typ]);
}
6.6.4 GetInteger
int GetInteger(int* error)
Returns an integer if the Value object is of integer type, otherwise returns 0.
Arguments:
Return value:
Returns an integer if the Value object is of integer type, otherwise returns 0.
PowerFactory API
56
Example:
Value* val;
int iret = val->GetInteger();
6.6.5 GetInteger64
__int64 GetInteger64(int* error)
Returns a long integer if the Value object is of long integer type, otherwise returns 0.
Arguments:
Return value:
Returns a long integer if the Value object is of long integer type, otherwise returns 0.
Example:
Value* val;
__int64 iret = val->GetInteger64();
6.6.6 GetDouble
double GetDouble(int* error)
Returns a double if the Value object is of type double, otherwise returns 0.
Arguments:
Return value:
Returns a double if the Value object is of type double, otherwise returns 0.
Example:
Value* val;
double iret = val->Getdouble();
6.6.7 GetString
const char* GetString(int* error)
Returns a string if the Value object is of type string, otherwise returns NULL.
Arguments:
Return value:
Returns a string if the Value object is of type string, otherwise returns NULL.
Example:
PowerFactory API
57

printf("Description: %s", descr->GetString())
6.6.8 GetDataObject
DataObject* GetDataObject(int* error)
Returns a pointer to a DataObject if the Value object is of type DataObject, NULL otherwise.
DataObject must be released when no longer in use.
Arguments:
Return value:
Returns a pointer to a DataObject if the Value object is of type DataObject, NULL otherwise.
Example:
This example returns the description of the Project settings (pPrjSettings) attribute of the active project
const Value* descr = prj->GetAttributeDescription("pPrjSettings");
printf("Project settings attribute description (pPrjSettings): %s\n", descr->GetString());
6.6.9 MatGetRowCount
unsigned int MatGetRowCount(int* error=0)
returns the number of rows/elements if the Value is matrix/vector
Arguments:
Return value:
Number of rows as unsigned int
Example:
Value* val;
int row = val->MatGetRowCount();
6.6.10 MatGetColCount
unsigned int MatGetColCount(int* error=0)
returns the number of columns if the Value is a matrix
Arguments:
PowerFactory API
58
Return value:
Number of columns as unsigned int
Example:
Value* val;
int col = val->MatGetColCount();
6.6.11 MatSetDouble
void MatSetDouble(const unsigned int row, const unsigned int col, const double val, int* error=0)
set the value of a double in a matrix at position (row, col)
Arguments:
const unsigned int row: row index
const unsigned int col: column index
const double val: double value to be inserted in the matrix
Return value:
void
Example:
Value* val;
val->MatSetDouble(1,1,2.5);
6.6.12 MatGetDouble
double MatGetDouble(const unsigned int row, const unsigned int col, int* error=0)
returns the value of the double in the considered matrix at position (row, col)
Arguments:
const unsigned int row: row index of the considered matrix element
const unsigned int col: column index of the considered matrix element
Return value:
The value of the double at position (row, col)
Example:
double d = val->MatGetDouble(1,1);
6.6.13 SetValue
void SetValue(const int val)
PowerFactory API
59
void SetValue(const __int64 val)

void SetValue(const double val)
void SetValue(const char* val)
void SetValue(DataObject* val)
Set the value of a Value type object; value can be of types int, __int64, double, char* and DataObject*
Arguments:
According to the type of the value to be set:
const int val: if the value to be set is an integer
const __int64 val: if the value to be set is a long integer
const double val: if the value to be set is a double
const char* val: if the value to be set is a string
const DataObject* val: if the value to be set is a DataObject
Return value:
void
Example:
double d = 5.5;
Value* val;
val->SetValue(d);
6.6.14 VecGetInteger
int VecGetInteger(const unsigned int index, int* error)
Returns the integer stored in a vector at position index
Arguments:
const unsigned int index: index of the element to be read
Return value:
integer stored in a vector at position index
Example:
Value* val;
int iret = val->VecGetInteger(1);
6.6.15 VecGetInteger64
__int64 VecGetInteger64(const unsigned int index, int* error)
Returns a long integer stored in a vector at position index
PowerFactory API
60
Arguments:
Return value:
Returns a long integer stored in a vector at position index
Example:
Value* val;
__int64 iret = val->VecGetInteger64(1);
6.6.16 VecGetDouble
double VecGetDouble(const unsigned int index, int* error)
Returns a double stored in a vector a position index
Arguments:
Return value:
Returns a double stored in a vector a position index
Example:
Value* val;
double iret = val->VecGetDouble(1);
6.6.17 VecGetString
const char* VecGetString(const unsigned int index, int* error)
Returns a string of characters stored in a vector at position index
Arguments:
Return value:
Returns a string of characters stored in a vector at position index
Example:
Value* val;
char* iret = val->VecGetString(1);
PowerFactory API
61
6.6.18 VecGetDataObject
DataObject* VecGetDataObject(const unsigned int index, int* error)
Returns an object stored in a vector at position index
Arguments:
Return value:
Returns an object stored in a vector at position index if the considered element is a DataObject, NULL
otherwise.
Example:
int* error;
if(relevantObj)
{
printf("Getting relevant object for calculation...\n");
{
}
}
else
{
printf("No relevant object for calculation");
}
6.6.19 VecGetValue
const Value* VecGetValue(const unsigned int idx, int* error=0)
Returns a pointer to a Value stored in a vector at position idx
Arguments:
Return value:
Returns a pointer to a Value if the considered element is a Value, NULL otherwise.
Example:
PowerFactory API
62
Value* val;
Value* v = val->VecGetValue(1);
6.6.20 VecClear
void VecClear(int* error=0)
empties the considered vector
Arguments:
Return value:
void
Example:
Value* val;
Val->VecClear();
6.6.21 VecGetSize
unsigned int VecGetSize(int* error)
Returns the size of the considered vector
Arguments:
Return value:
the size of the considered vector
Example:
int* error;
if(relevantObj)
{
+ textBoxCmd->Text;
{
}
}
else
{
PowerFactory API
63

+ 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:
Return value:
Type = UNKNOWN, INTEGER, DOUBLE, STRING, VECTOR_OLD2, INTEGER64, DATAOBJECT, VECTOR,
DOUBLEMATRIX, VALUE
Example:
Value* val;
Type elType = val->VecGetType(1);
6.6.23 VecInsertInteger
void VecInsertInteger(const int val, int* error=0)
inserts an integer into a vector (at the end)
Arguments:
const int val: integer value to be inserted in the vector
Return value:
void
Example:
Value* val(VECTOR);
val->VecInsertInteger(1);
6.6.24 VecInsertInt64
void VecInsertInt64(const __int64 val, int* error=0)
inserts an 64-bit integer into a vector (at the end)
Arguments:
const __int64 val: integer value to be inserted in the vector
PowerFactory API
64

Return value:
void
Example:
Value* val(VECTOR);
val->VecInsertInt64(1);
6.6.25 VecInsertDouble
void VecInsertDouble(const double val, int* error=0)
inserts double at the end of a vector
Arguments:
const double val: double value to be inserted in the vector
Return value:
void
Example:
Value* val(VECTOR);
val->VecInsertDouble(1.5);
6.6.26 VecInsertString
void VecInsertString(const char* val, int* error=0)
inserts a string at the end of a vector
Arguments:
const char* val: string to be inserted in the vector
Return value:
void
Example:
Value* val(VECTOR);
val->VecInsertString(test string);
6.6.27 VecInsertDataObject
void VecInsertDataObject(DataObject* val, int* error=0)
inserts a pointer to a DataObject at the end of a vector
PowerFactory API
65
Arguments:
DataObject* val: pointer to the DataObject to be inserted in the vector
Return value:
void
Example:
Value* val(VECTOR);
DataObject* obj;
val->VecInsertDataObject(obj);
6.6.28 VecInsertValue
void VecInsertValue(const Value* val, int* error=0)
inserts a pointer to a Value at the end of a vector
Arguments:
const Value* val: pointer to the Value to be inserted in the vector
Return value:
void
Example:
Value* val(VECTOR);
Value* v(1);
val->VecInsertValue(v);
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>
Data_intPrjfolder_Nine_Bus_ElmNet_System Stage Mag-A-Stat_intVariant_Bus
7_ElmTerm_Cub_1_StaCubic</value>
</Data>
<Data name="bus2">
<displayName>Id bus2</displayName>
Data_intPrjfolder_Nine_Bus_ElmNet_System Stage Mag-A-Stat_intVariant_Bus
5_ElmTerm_Cub_3_StaCubic</value>
PowerFactory 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

PowerFactory API v3

Caricato da

Informazioni sul documento

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

PowerFactory API v3

Caricato da

Copyright:

Formati disponibili

DIgSILENT Technical

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

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

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

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

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

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

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

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

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

2.2 Physical Structure

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

2.3 Interface Data Model

Api: instance of the API

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

DataObject: any PowerFactory object

2.4 Compiler Settings

MS Visual Studio Project Property:

Calling Convention: cdecl

MS Visual Studio Project Property:

3 Create and Destroy an Instance of the API

3 Create and Destroy an Instance of the API

3.1 Create an Instance of the API

3.2 Delete an Instance of the API

4 Accessing Objects and Attributes

4 Accessing Objects and Attributes

4.2 Accessing Object Attributes

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

4.3 Modifying Objects and Attributes

4 Accessing Objects and Attributes

SetAttributeInt, SetAttributeDouble, SetAttributeString and SetAttributeObject

4.4 Creating and Deleting Objects

4.5 Topological Routines

4.5.1 Example for GetConnectionCount

4 Accessing Objects and Attributes

4.5.2 Example for GetTerminal

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

4.5.3 Example for GetCubicle

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

4 Accessing Objects and Attributes

4.6 Accessing and Post-processing Results

) and then check the

4.6.2 Dynamic simulation results

5.2 On an instance of a DataObject

5.3 Running Calculations

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

5.4 Available Generic Functions on api::Application instance

5.5 Available Generic Functions on api::DataObject instance

Value::STRING = folder type

6 References: Classes, Objects and Methods

6 References: Classes, Objects and Methods

Api: one single instance of the API

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

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

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