DIgSILENT PowerFactory

Manual

PowerFactory API
Date: September 2015
 DIgSILENT GmbH

Heinrich-Hertz-Str. 9
72810 - Gomaringen
Germany

Please contact
DIgSILENT
e-mail: info@digsilent.de

Copyright ©2015, DIgSILENT GmbH. Copyright of this document belongs to DIgSILENT GmbH.
No part of this document may be reproduced, copied, or transmitted in any form, by any means
electronic or mechanical, without the prior written permission of DIgSILENT GmbH.

PowerFactory API 1
Contents

Contents

1 Introduction 6

2 Overview 6

2.1 Interface Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.2 Related Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.3 Compiler Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.4 Loading digapi.dll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.5 Extracting Methods from digapi.dll . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.6 API Versioning Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.6.1 Migrating from API versions before 16.0 . . . . . . . . . . . . . . . . . . . 8

2.7 Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.7.1 Objects of Type Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.7.2 Objects of Type DataObject . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3 Working with an API Instance 10

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

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

4 Working with PowerFactory objects 10

4.1 Accessing Object Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.2 Modifying Objects and Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4.3 Creating and Deleting Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5 Executing Commands 12

6 Class Reference 13

6.1 api::v1::Api . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6.1.1 GetVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6.1.2 ReleaseObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6.1.3 ReleaseValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

6.1.4 GetApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

6.1.5 IsDebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

PowerFactory API 2
Contents

6.2 api::v1::Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

6.2.1 GetVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

6.2.2 GetTempDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

6.2.3 GetWorkingDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

6.2.4 GetOutputWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6.2.5 GetCurrentUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6.2.6 GetActiveProject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6.2.7 GetActiveStudyCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6.2.8 GetCalcRelevantObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6.2.9 GetClassId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6.2.10 GetClassDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6.2.11 AttributeMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6.2.12 SetAttributeMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6.2.13 GetAttributeMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6.2.14 SetWriteCacheEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6.2.15 IsWriteCacheEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6.2.16 GetAttributeType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6.2.17 GetAttributeDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6.2.18 GetAttributeUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6.2.19 GetAttributeSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6.2.20 Execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

6.2.21 WriteChangesToDb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

6.3 api::v1::OutputWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

6.3.1 MessageType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

6.3.2 Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

6.3.3 Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

6.4 api::v1::DataObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6.4.1 AttributeType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6.4.2 GetClassName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6.4.3 GetClassId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6.4.4 GetName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

6.4.5 GetFullName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

PowerFactory API 3
Contents

6.4.6 GetChildren . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

6.4.7 GetParent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

6.4.8 IsNetworkDataFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

6.4.9 IsHidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

6.4.10 IsDeleted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

6.4.11 GetAttributeType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

6.4.12 GetAttributeDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

6.4.13 GetAttributeUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

6.4.14 GetAttributeSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

6.4.15 GetAttributeInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.4.16 GetAttributeDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.4.17 GetAttributeObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

6.4.18 GetAttributeString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

6.4.19 SetAttributeObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

6.4.20 SetAttributeString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

6.4.21 SetAttributeDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

6.4.22 SetAttributeInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

6.4.23 ResizeAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

6.4.24 CreateObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

6.4.25 Execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

6.4.26 WriteChangesToDb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

6.5 Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

6.5.1 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

6.5.2 Constructor / Destructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.5.3 GetType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.5.4 GetInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.5.5 GetInteger64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.5.6 GetDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

6.5.7 GetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

6.5.8 GetDataObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

6.5.9 MatGetRowCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

6.5.10 MatGetColCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

PowerFactory API 4
Contents

6.5.11 MatSetDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

6.5.12 MatGetDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

6.5.13 SetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

6.5.14 VecGetInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.5.15 VecGetInteger64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.5.16 VecGetDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.5.17 VecGetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.5.18 VecGetDataObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

6.5.19 VecGetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

6.5.20 VecClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

6.5.21 VecGetSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

6.5.22 VecGetType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

6.5.23 VecInsertInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

6.5.24 VecInsertInt64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

6.5.25 VecInsertDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

6.5.26 VecInsertString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

6.5.27 VecInsertDataObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

6.5.28 VecInsertValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

PowerFactory API 5
2 Overview

1 Introduction

The DIgSILENT PowerFactory Application Programming interface (API) offers third party ap-
plications the possibility to embed PowerFactory functionality into their own program. It offers
direct access to the PowerFactory data model and gives access to the varied calculations and
its results.

The API is designed as an automation interface; hence it requires detailed knowledge of the
PowerFactory data model and how to achieve certain tasks manually, including knowledge about
the participating objects and commands. It does not provide a pure calculation engine which
can be fed with an abstract calculation topology.

Technically, the interface is realized in C++ and provided as a DLL that can dynamically be linked
to any external application. The design idea was to keep the interface as small as possible while
providing access to almost all PowerFactory data and function.

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

Experience with the internal scripting language DPL is helpful but not required.

Source Code snippets presented below are intended for demonstration only and are incomplete
in such as sense that they cannot be compiled independently. For a working example on how
to use the API please refer to the Visual Studio example project also contained in the package.

2 Overview

The PowerFactory API is a logical layer on top 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 close to the PowerFactory data model. The API takes
care about internal memory management and data persistency. It does not allow any external
applications to access PowerFactory directly, all interaction from a 3rd party application are
relayed via the API.

2.1 Interface Data Model

The API consists of 5 different classes

Api The entry point class
Application Exposes the single running instance of PowerFactory .
OutputWindow Allows to use the PowerFactory output window to display warnings,
errors, etc.
DataObject Encapsulates a PowerFactory object, e.g. an ElmTerm, ComImport,
etc. and acts as a Proxy.
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 in-
terface while respecting different memory managements on the Pow-
erFactory and external application side. The data stored in a Value
object can be of different type (i.e. string, double, vector, DataObject,
etc.).

PowerFactory API 6
2 Overview

2.2 Related Files

The interface consists of the following C++ include files

Api.hpp Contains the definition of the Api class

Application.hpp Contains the definition of the Application class
OutputWindow.hpp Contains the definition of the OutputWindow class
DataObject.hpp Contains the definition of the DataObject class
ApiValue.hpp Contains the definition of the Value class

and one static library which needs to be linked to the 3rd party application

digapivalue.lib Contains the implementation of the Value class

The API itself is implemented in digapi.dll. This library needs to be run time dynamically linked
to your application. (See 2.5).

PowerFactory may at some point provide multiple versions of the API. The above listed head-
ers may change in future versions. To maintain binary compatibility for 3rd party applications
with future PowerFactory versions, namespaces and folders are used to separate them. This
document will omit the versioning aspect when functions or classes are mentioned (See 2.7).

2.3 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
• Calling Convention
cdecl

2.4 Loading digapi.dll

Run time dynamic linking is achieved by calling the Windows API method LoadLibraryEx. A
detailed documentation can be found in the MSDN. Below is a snippet showing the preferred
way of doing it.

v o i d LoadPowerFactoryApi ( )
{
HINSTANCE d l l H a n d l e = LoadLibraryEx (
TEXT ( ”E: \ \ \ p f \\ d i g a p i . d l l ” ) ,
NULL ,
LOAD WITH ALTERED SEARCH PATH ) ;
i f ( ! dllHandle ) {
throw s t d : : e x c e p t i o n ( ” d i g a p i . d l l c o u l d n o t be loaded ” ) ;
}
/ / use t h e handle
}

Using LoadLibraryEx with a full path to the digapi.dll has the benefit that the 3rd party application
does not need to reside in the PowerFactory installation directory.

PowerFactory API 7
2 Overview

The modifier LOAD˙WITH˙ALTERED˙SEARCH˙PATH is required because PowerFactory will in

turn load additional libraries that would not be found if this modifier is omitted.

2.5 Extracting Methods from digapi.dll

The PowerFactory API provides a handful of C methods defined in Api.hpp which serve as entry
point. They are located at the bottom of the file, wrapped in an extern ”C” section.

To access such a method from a dynamically loaded DLL the Windows API provides the method
GetProcAddress which is documented in the MSDN. The basic idea is to retrieve a function
pointer from the DLL and cast it to the desired function signature. From there on it can be called
like any other function. The snippet below shows the important steps, error handling has been
omitted.
e x t e r n ”C” {
t y p e d e f Api * ( c d e c l * CREATEAPI ) ( c o n s t char * username ,
c o n s t char * password ,
c o n s t char * commandLineArguments ) ;
}

Api * C r e a t e A p i I n s t a n c e ( c o n s t char * withUsername ,

c o n s t char * withPassword ,
c o n s t char * withCommandLineArguments ,
HINSTANCE f r o m D l l )
{
CREATEAPI c r e a t e A p i = ( CREATEAPI ) GetProcAddress (
fromDll ,
” CreateApiInstanceV1 ” ) ;
r e t u r n c r e a t e A p i ( withUsername ,
withPassword ,
withCommandLineArguments ) ;
}

2.6 API Versioning Concept

Beginning with PowerFactory 16, the API has been redesigned to guarantee binary compatibility
with future PowerFactory versions. This helps 3rd party application developers as they do not
need to rebuild their application just to be able to make use of a newer PowerFactory version.

A consequence of this is the introduction of namespaces and folders to separate PowerFactory

API versions from each other. Additionally all plain C functions defined in Api.hpp are suffixed
by the version they belong too.

We advise to use typedefs for our API classes in 3rd party code to make the transition to a new
API version as easy as possible, e.g.:
t y p e d e f a p i : : v1 : : DataObject DataObject ;
t y p e d e f a p i : : v1 : : A p p l i c a t i o n A p p l i c a t i o n ;
t y p e d e f a p i : : v1 : : Api Api ;

2.6.1 Migrating from API versions before 16.0

The API was split into multiple headers. Before recompiling any third party applications usage
of the new headers must be ensured.

PowerFactory API 8
2 Overview

Due to the introduction of a namespace to separate different API versions the above mentioned
typedefs should be introduced in third party applications. All compiler errors should be resolved
to use these typedefs.

Another change is the introduction of a DataObjectPtr return type for all methods of the Value
type which returned a DataObject in the old version. The Value type is version independent,
therefore it does not need to know anything about the specific API version it is currently used
with. All DataObjectPtr return values can be casted to the api version DataObject which is
currently used in the application.

2.7 Memory Management

PowerFactory has its own memory management. Therefore it must be guaranteed memory
allocated from PowerFactory will only be released by PowerFactory and memory allocated by
the 3rd party application will only be released by the 3rd party application.

2.7.1 Objects of Type Value

This leads to the requirement of having a transfer object for complex types between these
two worlds, the Value object. The Value object is a variant type and provides the necessary
methods to retrieve the stored content. A Value object returned by the API must not be deleted.
Ownership remains on the API side.

Likewise will the API never delete a Value object passed to it. It is therefore safe to create Value
objects on the stack and pass them to the API even though the API requires a pointer to the
object.

To clean up Value objects returned from the API the method ReleaseValue is provided on an
instance of the API object. Calling this method tells the API you do not need this object any more
and it can be destroyed. Accessing the Value object afterwards leads to undefined behaviour.

2.7.2 Objects of Type DataObject

A DataObject instance encapsulates a PowerFactory object and provides access to it. It is a

proxy object and also bound to the rules mentioned above. A DataObject returned by the API
must not be deleted directly. The API object provides the method ReleaseObject to tell the API
you do not need the proxy any more and it can be deleted. This will only release the proxy
object, the PowerFactory object itself remains.

DataObjects cannot be instantiated by 3rd party code directly.

DataObjects behave a bit differently than Value objects. By default, each request for a DataOb-
ject proxy for a specific PowerFactory object will return the very same proxy object until Re-
leaseObject is called for that proxy. DataObject instances are recycled as long as the same
PowerFactory object is requested. This is done for performance reasons and for convenience
regarding object identification by pointer comparison. However, it requires a careful thinking
about the responsibility for a DataObject proxy returned by the API.

Users feeling uncomfortable with this behaviour can use the method SetObjectReusingEnabled
to disable the object re-using. But this can have a negative impact on the API performance and
has to be evaluated individually.

Calling any method on a DataObject which was previously released leads to undefined be-
haviour.

PowerFactory API 9
4 Working with PowerFactory objects

3 Working with an API Instance

The entry point to PowerFactory is an instance of the API. It needs to be created via the C
method CreateApiInstance and should be destroyed by DestroyApiInstance.

3.1 Create an Instance of the API

Use the function CreateApiInstance to create an instance of the API; only one instance can be
created at the time. Trying to create multiple instances will lead to undefined behaviour. For an
example See 2.6.

CreateApiInstance parameters:

username Name of the user to log in to PowerFactory . Can be a nullptr to en-

force the default behaviour as if PowerFactory was started via short-
cut.
password The password for the user which should be logged in. Can be a
nullptr to omit the password.
commandLine Additional command line options. These need to be specified in the
same way as if PowerFactory was started via a command shell. Can
be a nullptr to omit the command line arguments.

In cases where it is not acceptable to have a password showing up in source code or configu-
ration files the CreateApiInstanceSecured function can be used.

CreateApiInstanceSecured parameters:

username Name of the user to log in to PowerFactory .

passwordHash The password hash for the user which should be logged in. The
hash value can be retrieved from the dialogue of the IntUser object in
PowerFactory . Only the Administrator or the user itself can see this
value.
commandLine Additional command line options. These need to be specified in the
same way as if PowerFactory was started via a command shell. Can
be a nullptr to omit the command line arguments.

3.2 Delete an Instance of the API

Using DestroyApiInstance, the corresponding instance of the API will be deleted and the mem-
ory occupied by the created objects within this instance of the API will be freed.

DestroyApiInstance parameters:

instance Pointer to a PowerFactory API instance which should be destroyed.

Please note, due to internal restrictions, calling this function will also terminate the whole pro-
cess via a system exit.

4 Working with PowerFactory objects

PowerFactory presents data and functionality encapsulated in objects. The class of an object
can be seen in PowerFactory as a suffix to an objects name in the dialogue title while editing an

PowerFactory API 10
4 Working with PowerFactory objects

object. Below is an example for a load flow command, whose class is ComLdf.

The class defines the attributes and operations an object provides.

Objects are organised in a tree structure, much like the folders of the Windows file system.
Navigating in the tree is done via GetChildren and GetParent of an object. These methods
are accessible on the DataObject proxy. Certain folders can be used as entry point for the
navigation, e.g. the current user or the active project. The Application class of the API provides
various methods to access specific folders.

4.1 Accessing Object Attributes

To access any attribute of an object, its type must be known. Therefore, the function GetAt-
tributeType returns the type of the corresponding attribute. The attribute types are defined in
DataObject.hpp
enum A t t r i b u t e T y p e {
TYPE INVALID = −1,

TYPE INTEGER = 0,
TYPE INTEGER VEC = 1,

TYPE DOUBLE = 2,
TYPE DOUBLE VEC = 3,
TYPE DOUBLE MAT = 4,

TYPE OBJECT = 5,
TYPE OBJECT VEC = 6,

TYPE STRING = 7,
TYPE STRING VEC = 8,

TYPE INTEGER64 = 9,
TYPE INTEGER64 VEC = 10 ,
};

Once the type has been identified, methods like GetAttributeInt, GetAttributeDouble, GetAttribu-
teObject, GetAttributeString return respectively the content of the attribute as an int, double,
DataObject or Value.

Container types can be accessed by using GetAttributeContainer or the appropriate overload of

the methods above which also accept indices. The size of a container can be determined by
calling GetAttributeSize.

A few DataObject methods will either return a Value object or require one as input. The Value
object encapsulates non-primitive types like strings or containers and provides methods to ac-
cess the encapsulated values.

Figure 4.1: Dialogue of load flow command (ComLdf)

PowerFactory API 11
5 Executing Commands

4.2 Modifying Objects and Attributes

Objects and their attributes can be modified using one of the type bound methods.

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, GetAt-

tributes and SetAttributes.

4.3 Creating and Deleting Objects

As PowerFactory stores all objects in a tree hierarchy objects need to be created with a parent
so they can be sorted into the right place in the tree. The DataObject provides the method
CreateObject which needs to be given a class name for the correct PowerFactory object to be
created.

The created object can be used immediately.

To delete an object the method DeleteObject must be called on itself.

After calling DeleteObject the DataObject pointer may no longer be used and should be released
See 2.7.2.

5 Executing Commands

The Application and DataObject classes contain an Execute method to execute generically
commands.

The syntax of the method is

Value * Execute ( c o n s t char * command , c o n s t Value * inArgs , i n t * e r r o r / * =NULL * / ) ;

where
command is the name of the function to be executed
inArgs is(are) the required argument(s), depending on the executed function
error is the returned error code (0 on success)

The available commands are listed in the Python Function Reference.

Commands with more then one argument can be executed with ’inArgs’ of type vector.

Example:
A p p l i c a t i o n * app ( a p i I n s t a n c e −>G e t A p p l i c a t i o n ( ) ) ;

/ / g e t t i n g a l l versions of the a c t i v e p r o j e c t
c o n s t Value * a c t i v e P r o j e c t ( app−>Execute ( ” G e t A c t i v e P r o j e c t ” , NULL , e r r o r ) ) ;
c o n s t Value * v e r s i o n s ( app−>Execute ( ” GetVersions ” , NULL , e r r o r ) ) ;

/ / collecting all lines

c o n s t Value * l i n e s ( app−>Execute ( ” GetCalcRelevantObjects ” , &Value ( ” * . ElmLne ” ) , e r r o r ) ) ;

/ / c o l l e c t i n g l i n e s which are n o t o u t o f s e r v i c e

PowerFactory API 12
6 Class Reference

Value arguments ( Value : : VECTOR ) ;

arguments . V e c I n s e r t S t r i n g ( ” * . ElmLne ” ) ;
arguments . V e c I n s e r t I n t e g e r ( 0 ) ;
c o n s t Value * l i n e s I n S e r v i c e ( app−>Execute ( ” GetCalcRelevantObjects ” , &arguments , e r r o r ) ) ;

/ / r e l e a s i n g received values
a p i I n s t a n c e −>ReleaseValue ( a c t i v e P r o j e c t )
a p i I n s t a n c e −>ReleaseValue ( v e r s i o n s )
a p i I n s t a n c e −>ReleaseValue ( l i n e s )
a p i I n s t a n c e −>ReleaseValue ( l i n e s I n S e r v i c e )

6 Class Reference

6.1 api::v1::Api

6.1.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.
a p i I n s t a n c e = C r e a t e A p i I n s t a n c e ( NULL , NULL , NULL ) ;
s t d : : c o u t << s t d : : e n d l
<< a p i I n s t a n c e −>GetVersion ()−> G e t S t r i n g ( )
<< s t d : : e n d l ;

6.1.2 ReleaseObject

i n t ReleaseObject ( c o n s t DataObject * o b j e c t )

Releases a DataObject instance. All DataObject pointers returned by 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. Each object must only be released once.

Arguments:

const DataObject* the pointer to the object to be released

Return value:

0 on success, non-zero on error

Example:

PowerFactory API 13
6 Class Reference

DataObject * user ( a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−> GetCurrentUser ( ) ) ;

a p i I n s t a n c e −>ReleaseObject ( user ) ;

6.1.3 ReleaseValue

i n t ReleaseValue ( c o n s t Value * o b j e c t )

Releases an API value instance. All API value pointers returned by the 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* pointer to the object to be released

Return value:

0 on success, non-zero on error

Example:
DataObject * user ( a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−> GetCurrentUser ( ) ) ;
Value * name = user−>GetName ( ) ;
a p i I n s t a n c e −>ReleaseValue ( name ) ;
a p i I n s t a n c e −>ReleaseObject ( user ) ;

6.1.4 GetApplication

Application * GetApplication ( )

The function returns an instance of Application. There exists only one Application object per Api
instance. This 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 .
a p i I n s t a n c e = C r e a t e A p i I n s t a n c e ( NULL , NULL , NULL ) ;
s t d : : c o u t << ” PowerFactory v e r s i o n : ”
<< a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−> GetVersion ()−> G e t S t r i n g ( )
<< s t d : : e n d l ;

6.1.5 IsDebug

b o o l IsDebug ( )

Arguments:

None

Return value:

PowerFactory API 14
6 Class Reference

True if PowerFactory is in debug mode; false otherwise.

Example:
a p i I n s t a n c e = C r e a t e A p i I n s t a n c e ( NULL , NULL , NULL ) ;
i f ( a p i I n s t a n c e −>IsDebug ( ) )
{
s t d : : c o u t << ” PowerFactory r u n n i n g i n debug mode ” << s t d : : e n d l ;
}

6.2 api::v1::Application

6.2.1 GetVersion

c o n s t Value * GetVersion ( )

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

Arguments:

None

Return value:

Pointer to a Value object holding version information of PowerFactory application; returned string
is never null and must be released when no longer in use.

Example:

The following example displays in the command window the version of the running instance of
PowerFactory .
a p i I n s t a n c e = C r e a t e A p i I n s t a n c e ( NULL , NULL , NULL ) ;
s t d : : c o u t << ” PowerFactory v e r s i o n : ”
<< a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−> GetVersion ()−> G e t S t r i n g ( )
<< s t d : : e n d l ;

6.2.2 GetTempDirectory

c o n s t 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:
s t d : : c o u t << a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−> GetTempDirectory ()−> G e t S t r i n g ( )
<< s t d : : e n d l ;

6.2.3 GetWorkingDirectory

c o n s t Value * G e t W o r k i n g D i r e c t o r y ( )

PowerFactory API 15
6 Class Reference

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

Arguments:

None

Return value:

A pointer of type Value holding a string string with the working directory of PowerFactory .

Example:
A p p l i c a t i o n * a p p l i c a t i o n ( a p i I n s t a n c e −>G e t A p p l i c a t i o n ( ) ) ;
s t d : : c o u t << a p p l i c a t i o n −>G e t W o r k i n g D i r e c t o r y ()−> G e t S t r i n g ( )
<< s t d : : e n d l ;

6.2.4 GetOutputWindow

OutputWindow * GetOutputWindow ( )

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

Arguments:

None

Return value:

Returns a pointer to an instance of OutputWindow, never NULL

6.2.5 GetCurrentUser

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.
i n t error = 0;
DataObject * user = a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−> GetCurrentUser ( ) ;
s t d : : c o u t << * ( user−>G e t A t t r i b u t e S t r i n g ( ” loc name ” , e r r o r ) ) << s t d : : e n d l ;

6.2.6 GetActiveProject

DataObject * G e t A c t i v e P r o j e c t ( )

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

Arguments:

PowerFactory API 16
6 Class Reference

None

Return value:

Pointer to the currently active PowerFactory project

6.2.7 GetActiveStudyCase

DataObject * GetActiveStudyCase ( )

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

Arguments:

None

Return value:

Pointer of type Value to the currently active study case

6.2.8 GetCalcRelevantObjects

c o n s t Value * GetCalcRelevantObjects ( )

This function returns all objects that are currently relevant for calculation: lines, nodes, switches,
transformers, etc. and their types.

Arguments:

None

Return value:

Returns a pointer of type Value to a vector of objects relevant for calculation, never NULL. The
container must be released if no longer in use.

6.2.9 GetClassId

i n t GetClassId ( c o n s t 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 accord-
ing 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:
i n t f i l t e r I D = a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−> GetClassId ( ” i n t P r j ” ) ;
s t d : : c o u t << ” P r o j e c t ID ( i n t P r j ) : ” << f i l t e r I D << s t d : : e n d l ;

PowerFactory API 17
6 Class Reference

6.2.10 GetClassDescription

c o n s t Value * G e t C l a s s D e s c r i p t i o n ( c o n s t char * className )

Returns the description of a PowerFactory class.

Arguments:

const char* className name of the considered PowerFactory class

Return value:

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

Example:

The following example displays the description text of the class intPrj
Application * a p p l i c a t i o n ( a p i I n s t a n c e −>G e t A p p l i c a t i o n ( ) ) ;
s t d : : c o u t << ” intPrj description text : ”
<< a p p l i c a t i o n −>G e t C l a s s D e s c r i p t i o n ( ” i n t P r j ” )−>G e t S t r i n g ( )
<< std : : endl ;

6.2.11 AttributeMode

enum A t t r i b u t e M o d e {
MODE DISPLAYED = 0,
MODE INTERNAL = 1
};

Enumerated type for accessing object attributes in PowerFactory .

MODE˙DISPLAYED as displayed in PF (unit conversion applied)

MODE˙INTERNAL as internally stored

6.2.12 SetAttributeMode

v o i d S e t A t t r i b u t e M o d e ( A t t r i b u t e M o d e mode )

Changes the way how attribute values are accessed

Arguments:

AttributeMode mode the way the attribute values should be accessed

Return value:

void

6.2.13 GetAttributeMode

AttributeMode GetAttributeMode ( )

Returns the mode how object attributes are accessed.

Arguments:

None

Return value:

PowerFactory API 18
6 Class Reference

Current mode as AttributeMode

6.2.14 SetWriteCacheEnabled

v o i d SetWriteCacheEnabled ( b o o l 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 is called.

Default value: disabled.

Arguments:

bool enabled true = enabled; false = disabled

Return value:

void

Example:
a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−>SetWriteCacheEnabled ( t r u e ) ;

6.2.15 IsWriteCacheEnabled

b o o l IsWriteCacheEnabled ( )

Returns whether or not the cache method for optimizing performances is enabled.

Arguments:

None

Return value:

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

Example:
b o o l cacheEnabled ;
cacheEnabled = a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−> IsWriteCacheEnabled ( ) ;

6.2.16 GetAttributeType

DataObject : : A t t r i b u t e T y p e G e t A t t r i b u t e T y p e ( c o n s t char * classname ,

c o n s t char * a t t r i b u t e )

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)

PowerFactory API 19
6 Class Reference

TYPE˙INVALID error
TYPE˙INTEGER int
TYPE˙INTEGER˙VEC vector of type int
TYPE˙DOUBLE double
TYPE˙DOUBLE˙VEC vector of double
TYPE˙DOUBLE˙MAT 2D matrix of double
TYPE˙OBJECT DataObject
TYPE˙OBJECT˙VEC vector of DataObject
TYPE˙STRING string literal
TYPE˙STRING˙VEC vector of string litarals
TYPE˙INTEGER64 ˙˙int64
TYPE˙INTEGER64˙VEC vector of ˙˙int64

6.2.17 GetAttributeDescription

c o n s t Value * G e t A t t r i b u t e D e s c r i p t i o n ( c o n s t char * classname ,

c o n s t char * a t t r i b u t e )

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

Arguments:

const char* classname class name for which the attribute type is considered
const char* attribute attribute which description must be returned

Return value:

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

6.2.18 GetAttributeUnit

c o n s t Value * G e t A t t r i b u t e U n i t ( c o n s t char * classname , c o n s t char * a t t r i b u t e )

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

Arguments:

const char* classname class name for which the attribute type is considered
const char* attribute attribute which description must be returned

Return value:

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

6.2.19 GetAttributeSize

v o i d G e t A t t r i b u t e S i z e ( c o n s t char * name ,
c o n s t char * a t t r i b u t e ,
i n t & countRows ,
i n t & countCols )

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

Arguments:

const char* classname class name for which the attribute type is considered
const char* attribute attribute which description must be returned
int& countRows the returned number of rows
int& countCols the returned number of columns

PowerFactory API 20
6 Class Reference

Return value:

void

6.2.20 Execute

Value * Execute ( c o n s t char * command , c o n s t Value * inArgs , i n t * e r r o r )

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

The available commands are listed in the Python Function Reference. Commands with more
then one argument can be executed with ’inArgs’ of type vector.

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 (0 on success)

Return value:

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

Example:
A p p l i c a t i o n * app ( a p i I n s t a n c e −>G e t A p p l i c a t i o n ( ) ) ;

/ / g e t t i n g the a c t i v e p r o j e c t
c o n s t Value * a c t i v e P r o j e c t ( app−>Execute ( ” G e t A c t i v e P r o j e c t ” , NULL , e r r o r ) ) ;

/ / collecting all lines

c o n s t Value * l i n e s ( app−>Execute ( ” GetCalcRelevantObjects ” , &Value ( ” * . ElmLne ” ) , e r r o r ) ) ;

/ / c o l l e c t i n g l i n e s which are n o t o u t o f s e r v i c e
Value arguments ( Value : : VECTOR ) ;
arguments . V e c I n s e r t S t r i n g ( ” * . ElmLne ” ) ;
arguments . V e c I n s e r t I n t e g e r ( 0 ) ;
c o n s t Value * l i n e s I n S e r v i c e ( app−>Execute ( ” GetCalcRelevantObjects ” , &arguments , e r r o r ) ) ;

/ / r e l e a s i n g received values
a p i I n s t a n c e −>ReleaseValue ( a c t i v e P r o j e c t )
a p i I n s t a n c e −>ReleaseValue ( l i n e s )
a p i I n s t a n c e −>ReleaseValue ( l i n e s I n S e r v i c e )

6.2.21 WriteChangesToDb

v o i d WriteChangesToDb ( )

This function combined with SetWriteCacheEnabled is meant to optimize performances. If the

write cache flag is enabled all objects remain in edit mode until WriteChangesToDb is called
and all the modifications made to the objects are saved into the database.

Arguments:

None

Return value:

PowerFactory API 21
6 Class Reference

void

6.3 api::v1::OutputWindow

6.3.1 MessageType

enum MessageType
{
M PLAIN = 0 ,
M ERROR = 1 ,
M WARN = 2 ,
M INFO = 4
};

Enumerated type which defines the message type.

M˙PLAIN message not prepended by any text

M˙ERROR message prepended by error prefix, will also popup as error di-
alog
M˙WARN message prepended by warning prefix
M˙INFO message prepended by info prefix

6.3.2 Print

v o i d P r i n t ( MessageType type , c o n s t char * msg )

This function prints a message to the PowerFactory output window.

Arguments:

MessageType type type of message

const char* msg the actual message to be displayed

Return value:

void

Example:

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

OutputWindow * outWindow = a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−>GetOutputWindow ( ) ;
outWindow−>P r i n t ( OutputWindow : : M INFO , ” Running PowerFactory from t h e API ” ) ;

6.3.3 Clear

void Clear ( )

Empties the content of the output window.

Arguments:

None

Return value:

void

Example:

PowerFactory API 22
6 Class Reference

The following example displays a message in the PowerFactory output window and clears it.
OutputWindow * outWindow = a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−>GetOutputWindow ( ) ;
outWindow−>P r i n t ( OutputWindow : : M INFO , ” Running PowerFactory from t h e API ” ) ;
outWindow−>C l e a r ( ) ;

6.4 api::v1::DataObject

6.4.1 AttributeType

enum A t t r i b u t e T y p e {
TYPE INVALID = −1,
TYPE INTEGER = 0 ,
TYPE INTEGER VEC = 1 ,
TYPE DOUBLE = 2 ,
TYPE DOUBLE VEC = 3 ,
TYPE DOUBLE MAT = 4 ,
TYPE OBJECT = 5 ,
TYPE OBJECT VEC = 6 ,
TYPE STRING = 7 ,
TYPE STRING VEC = 8 ,
TYPE INTEGER64 = 9 ,
TYPE INTEGER64 VEC = 10 ,
};

Enumerated type for defining the type of object attributes

TYPE˙INVALID error or not existing attribute

TYPE˙INTEGER integer
TYPE˙INTEGER˙VEC vector of integers
TYPE˙DOUBLE double
TYPE˙DOUBLE˙VEC vector of double
TYPE˙DOUBLE˙MAT matrix of doubles
TYPE˙OBJECT DataObject
TYPE˙OBJECT˙VEC vector of DataObject
TYPE˙STRING string literal
TYPE˙STRING˙VEC vector of string literals
TYPE˙INTEGER64 ˙˙int64
TYPE˙INTEGER64˙VEC vector of ˙˙int64

6.4.2 GetClassName

c o n s t 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.

6.4.3 GetClassId

i n t GetClassId ( )

Returns the id of the class of the current object.

PowerFactory API 23
6 Class Reference

Arguments:

None

Return value:

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

6.4.4 GetName

c o n s t 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

6.4.5 GetFullName

c o n s t Value * GetFullName ( DataObject * r e l P a r e n t )

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

Arguments:

DataObject* relParent starting point of the path

Return value:

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

6.4.6 GetChildren

c o n s t Value * G e t C h i l d r e n ( b o o l r e c u r s i v e )

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.

Arguments:

bool recursive false: only direct children are returned; true: the complete de-
scendant tree is returned.

Return value:

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

6.4.7 GetParent

DataObject * GetParent ( )

Returns the parent object of the current object.

Arguments:

PowerFactory API 24
6 Class Reference

None

Return value:

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

6.4.8 IsNetworkDataFolder

b o o l I s N et wo rk Dat aF ol de r ( )

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.

6.4.9 IsHidden

b o o l 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 in-active variation stage or deleted in the current
stage)

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

6.4.11 GetAttributeType

DataObject : : A t t r i b u t e T y p e G e t A t t r i b u t e T y p e ( c o n s t char * a t t r i b u t e )

Returns the type of an attribute;

Arguments:

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

Return value:

PowerFactory API 25
6 Class Reference

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

6.4.12 GetAttributeDescription

c o n s t Value * G e t A t t r i b u t e D e s c r i p t i o n ( c o n s t char * a t t r i b u t e )

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
c o n s t Value * a c t i v P r o j = a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−> G e t A c t i v e P r o j e c t ( ) ;
c o n s t DataObject * p r j = a c t i v P r o j −>GetDataObject ( ) ;
c o n s t Value * descr = p r j −>G e t A t t r i b u t e D e s c r i p t i o n ( ” p P r j S e t t i n g s ” ) ;
p r i n t f ( ” A t t r i b u t e d e s c r i p t i o n ( p P r j S e t t i n g s ) : %s\n ” , descr−>G e t S t r i n g ( ) ) ;

6.4.13 GetAttributeUnit

c o n s t Value * G e t A t t r i b u t e U n i t ( c o n s t char * a t t r i b u t e )

Returns the unit of an attribute of the considered object (km, MW, etc.); NULL if the attribute
does not exist; empty string for attributes without units.

Arguments:

const char* attribute the attribute name whose unit is requested

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
c o n s t Value * a c t i v P r o j = a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−> G e t A c t i v e P r o j e c t ( ) ;

i f ( activProj )
{
DataObject * p r o j e c t P r o x y = a c t i v P r o j −>GetDataObject ( ) ;
c o n s t Value * u n i t s = p r o j e c t P r o x y −>G e t A t t r i b u t e U n i t ( ” s t r e t e n t i o n ” ) ;
p r i n t f ( ” r e t e n t i o n p e r i o d u n i t s : %s\n ” , u n i t s −>G e t S t r i n g ( ) ) ;
}

6.4.14 GetAttributeSize

v o i d G e t A t t r i b u t e S i z e ( c o n s t char * a t t r i b u t e , i n t & countRows , i n t & countCols )

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

PowerFactory API 26
6 Class Reference

Arguments:

const char* attribute the considered attribute

int& countRows number of rows (return value)
int& countCols number of columns (return value)

Return value:

void

Example:
DataObject * myMatrix ;
i n t * row ;
i n t * col ;
myMatrix−>G e t A t t r i b u t e S i z e ( matrix , row , c o l ) ;

6.4.15 GetAttributeInt

i n t G e t A t t r i b u t e I n t ( c o n s t char * a t t r i b u t e , i n t * e r r o r )
i n t G e t A t t r i b u t e I n t ( c o n s t char * a t t r i b u t e , i n t row , i n t c o l , i n t * e r r o r )

Returns the value of an attribute as an integer.

Arguments:

const char* attribute the attribute name

int row the row index of the element to be extracted if attribute is a matrix
or a vector
int col the row index of the element to be extracted if attribute is a matrix
int* error 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
c o n s t Value * a c t i v P r o j = a p i I n s t a n c e −>G e t A p p l i c a t i o n ()−> G e t A c t i v e P r o j e c t ( ) ;

i f ( activProj )
{
DataObject * p r o j e c t P r o x y = a c t i v P r o j −>GetDataObject ( ) ;
c o n s t Value * u n i t s = p r o j e c t P r o x y −>G e t A t t r i b u t e U n i t ( ” s t r e t e n t i o n ” ) ;
i n t nbDays = a c t i v P r o j −>GetDataObject ()−> G e t A t t r i b u t e I n t ( ” s t r e t e n t i o n ” ) ;
p r i n t f ( r e t e n t i o n p e r i o d : %d % s , nbDays , u n i t s −>G e t S t r i n g ( ) ) ;
}

6.4.16 GetAttributeDouble

double G e t A t t r i b u t e D o u b l e ( c o n s t char * a t t r i b u t e , i n t * e r r o r )
double G e t A t t r i b u t e D o u b l e ( c o n s t char * a t t r i b u t e ,
int row ,
int col ,
int * error )

Returns the value of an attribute as a double.

Arguments:

PowerFactory API 27
6 Class Reference

const char* attribute the considered attribute

int row the row index of the element to be extracted if attribute is a matrix
or a vector
int col the row index of the element to be extracted if attribute is a matrix
int* error returned error code

Return value:

Value of the considered attribute as a double

6.4.17 GetAttributeObject

DataObject * G e t A t t r i b u t e O b j e c t ( c o n s t char * a t t r i b u t e , i n t * e r r o r )
DataObject * G e t A t t r i b u t e O b j e c t ( c o n s t char * a t t r i b u t e , i n t row , i n t * e r r o r )

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

Arguments:

const char* attribute the considered attribute

int row (optional) the row index of the element to be extracted if attribute is a matrix
or a vector
int* error (optional) the returned error code

Return value:

Pointer to DataObject containing the corresponding attribute

6.4.18 GetAttributeString

c o n s t Value * G e t A t t r i b u t e S t r i n g ( c o n s t char * a t t r i b u t e , i n t * e r r o r )
c o n s t Value * G e t A t t r i b u t e S t r i n g ( c o n s t char * a t t r i b u t e , i n t row , i n t * e r r o r )

Returns the value of an string attribute.

Arguments:

const char* attribute the considered attribute

int row (optional) the row index of the element to be extracted if attribute is a matrix
or a vector
int* error (optional) returned error code

Return value:

Pointer of type Value to the attribute.

6.4.19 SetAttributeObject

v o i d S e t A t t r i b u t e O b j e c t ( c o n s t char * a t t r i b u t e , DataObject * obj , i n t * e r r o r )

v o i d S e t A t t r i b u t e O b j e c t ( c o n s t char * attribute ,
DataObject * obj ,
int row ,
int * error )

Sets the corresponding object attribute.

Arguments:

PowerFactory API 28
6 Class Reference

const char* attribute the considered attribute

DataObject* obj the new value of the attribute
int row the row index of the element to be extracted if attribute is a vector
int* error returned error code

Return value:

void

6.4.20 SetAttributeString

v o i d S e t A t t r i b u t e S t r i n g ( c o n s t char * a t t r i b u t e , c o n s t char * value , i n t * e r r o r )

v o i d S e t A t t r i b u t e S t r i n g ( c o n s t char * a t t r i b u t e ,
c o n s t char * value ,
int row ,
int col ,
int * error )

Sets the corresponding string attribute.

Arguments:

const char* attribute the considered attribute

const char* value the new value of the attribute
int row the row index of the element to be extracted if attribute is a vector
or a matrix
int col the column index of the element to be extracted if attribute is a
vector or a matrix
int* error returned error code

Return value:

void

6.4.21 SetAttributeDouble

v o i d S e t A t t r i b u t e D o u b l e ( c o n s t char * a t t r i b u t e , double value , i n t * e r r o r )

v o i d S e t A t t r i b u t e D o u b l e ( c o n s t char * attribute ,
double value ,
int row ,
int col ,
int * error )

Sets the corresponding double attribute.

Arguments:

const char* attribute the considered attribute

double value the new value of the attribute
int row the row index of the element to be extracted if attribute is a vector
or a matrix
int col the column index of the element to be extracted if attribute is a
vector or a matrix
int* error returned error code

Return value:

void

6.4.22 SetAttributeInt

PowerFactory API 29
6 Class Reference

v o i d S e t A t t r i b u t e I n t ( c o n s t char * a t t r i b u t e , i n t value , i n t * e r r o r )
v o i d S e t A t t r i b u t e I n t ( c o n s t char * a t t r i b u t e ,
int value ,
int row ,
int col ,
int * error )

Sets the corresponding double attribute.

Arguments:

const char* attribute the considered attribute

int value the new value of the attribute
int row the row index of the element to be extracted if attribute is a vector
or a matrix
int col the column index of the element to be extracted if attribute is a
vector or a matrix
int* error returned error code

Return value:

void

6.4.23 ResizeAttribute
v o i d R e s i z e A t t r i b u t e ( c o n s t char * attribute ,
int rowSize ,
int colSize ,
int * error )

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

Arguments:

const char* attribute the considered attribute

int rowSize the new number of rows for the element
int colSize the new number of columns for the element
int* error returned error code

Return value:

void

6.4.24 CreateObject
DataObject * C re a te O b je c t ( c o n s t char * className , c o n s t char * locname )

Create a new object of a given class inside the considered object (if this one can hold the new
object) Returns a DataObject pointer to the newly created object if successful; NULL otherwise.

Arguments:

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

const char* locname the name of the new object

Return value:

Pointer to the newly created DataObject

6.4.25 Execute

PowerFactory API 30
6 Class Reference

Value * Execute ( c o n s t char * command , c o n s t Value * inArgs , i n t * e r r o r )

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

The available commands are listed in the Python Function Reference. Commands with more
then one argument can be executed with ’inArgs’ of type vector.

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 (0 on success)

Return value:

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

Example:
A p p l i c a t i o n * app ( a p i I n s t a n c e −>G e t A p p l i c a t i o n ( ) ) ;

/ / g e t t i n g a l l versions of the a c t i v e p r o j e c t
c o n s t Value * a c t i v e P r o j e c t ( app−>Execute ( ” G e t A c t i v e P r o j e c t ” , NULL , e r r o r ) ) ;
c o n s t Value * v e r s i o n s ( app−>Execute ( ” GetVersions ” , NULL , e r r o r ) ) ;

/ / r e l e a s i n g received values
a p i I n s t a n c e −>ReleaseValue ( a c t i v e P r o j e c t )
a p i I n s t a n c e −>ReleaseValue ( v e r s i o n s )

6.4.26 WriteChangesToDb

v o i d WriteChangesToDb ( )

This function combined with SetWriteCacheEnabled is meant to optimize performances. If the

write cache flag is enabled all objects remain in edit mode until WriteChangesToDb is called
and all the modifications made to the objects are saved into the database.

Arguments:

None

Return value:

void

6.5 Value

The Value type is a variant type which can hold values of various types. It is used to transport
data between the API and the 3rd party application.

6.5.1 Type

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

PowerFactory API 31
6 Class Reference

VECTOR,
DOUBLEMATRIX,
VALUE
};

Enumerated type to define the type of a Value object.

6.5.2 Constructor / Destructor

Value ( c o n s t i n t v a l )
Value ( c o n s t int64 val )
Value ( c o n s t double v a l )
Value ( c o n s t char * v a l )
Value ( DataObject * v a l )
Value ( Type t y p e )
˜ Value ( )

Constructs Value objects of passed type.

6.5.3 GetType

c o n s t Type GetType ( )

Returns the actual type of the Value object.

Arguments:

None

Return value Type of the value object encoded as Type.

6.5.4 GetInteger

i n t GetInteger ( i n t * error )

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

Arguments:

int* error returned error code

Return value:

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

6.5.5 GetInteger64

i n t 6 4 GetInteger64 ( i n t * e r r o r )

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

Arguments:

int* error returned error code

Return value:

PowerFactory API 32
6 Class Reference

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

6.5.6 GetDouble
double GetDouble ( i n t * e r r o r )

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

Arguments:

int* error returned error code

Return value:

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

6.5.7 GetString
c o n s t char * G e t S t r i n g ( i n t * e r r o r )

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

Arguments:

int* error returned error code

Return value:

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

6.5.8 GetDataObject
DataObject * GetDataObject ( i n t * e r r o r )

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:
i n t * e r r o r ( o p t i o n a l ) : r e t u r n e d e r r o r code

Return value:

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

6.5.9 MatGetRowCount
unsigned i n t MatGetRowCount ( i n t * e r r o r =0)

Returns the number of rows/elements if the Value is matrix/vector

Arguments:

int* error returned error code

Return value:

Number of rows as unsigned int

6.5.10 MatGetColCount

PowerFactory API 33
6 Class Reference

unsigned i n t MatGetColCount ( i n t * e r r o r =0)

returns the number of columns if the Value is a matrix

Arguments:

int* error returned error code

Return value:

Number of columns as unsigned integer.

6.5.11 MatSetDouble

v o i d MatSetDouble ( c o n s t unsigned i n t row ,

c o n s t unsigned i n t col ,
c o n s t double val ,
int * e r r o r =0)

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

Arguments:

const unsigned int row row index

const unsigned int col column index
const double val double value to be inserted in the matrix
int* error returned error code

Return value:

void

6.5.12 MatGetDouble

double MatGetDouble ( c o n s t unsigned i n t row ,

c o n s t unsigned i n t c o l ,
int * e r r o r =0)

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

Arguments:

const unsigned int row row index of the considered matrix element
const unsigned int col column index of the considered matrix element
int* error returned error code

Return value:

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

6.5.13 SetValue

void SetValue ( c o n s t i n t v a l )
void SetValue ( c o n s t int64 val )
void SetValue ( c o n s t double v a l )
void SetValue ( c o n s t char * v a l )
void SetValue ( DataObject * v a l )

Set the value of a Value type object; value can be of types int, ˙˙int64, double, char* and DataOb-
ject*.

PowerFactory API 34
6 Class Reference

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

6.5.14 VecGetInteger
i n t VecGetInteger ( c o n s t unsigned i n t index , i n t * e r r o r )

Returns the integer stored in a vector at position index

Arguments:

const unsigned int index index of the element to be read

int* error returned error code

Return value:

integer stored in a vector at position index

6.5.15 VecGetInteger64
i n t 6 4 VecGetInteger64 ( c o n s t unsigned i n t index , i n t * e r r o r )

Returns a long integer stored in a vector at position index.

Arguments:

const unsigned int index index of the element to be read

int* error returned error code

Return value:

Returns a int64 stored in a vector at position index.

6.5.16 VecGetDouble
double VecGetDouble ( c o n s t unsigned i n t index , i n t * e r r o r )

Returns a double stored in a vector a position index.

Arguments:

const unsigned int index index of the element to be read

int* error returned error code

Return value:

Returns a double stored in a vector a position index

6.5.17 VecGetString

PowerFactory API 35
6 Class Reference

c o n s t char * VecGetString ( c o n s t unsigned i n t index , i n t * e r r o r )

Returns a string of characters stored in a vector at position index.

Arguments:

const unsigned int index index of the element to be read

int* error returned error code

Return value:

Returns a string of characters stored in a vector at position index.

6.5.18 VecGetDataObject

DataObject * VecGetDataObject ( c o n s t unsigned i n t index , i n t * e r r o r )

Returns an object stored in a vector at position index.

Arguments:

const unsigned int index index of the element to be read

int* error (optional) returned error code

Return value:

Returns an object stored in a vector at position index, NULL if the position does not hold a
DataObject.

6.5.19 VecGetValue

c o n s t Value * VecGetValue ( c o n s t unsigned i n t i d x , i n t * e r r o r =0)

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

Arguments:

const unsigned int index index of the element to be read

int* error returned error code

Return value:

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

6.5.20 VecClear

v o i d VecClear ( i n t * e r r o r =0)

Empties the considered vector

Arguments:

int* error returned error code

Return value:

void

6.5.21 VecGetSize

PowerFactory API 36
6 Class Reference

unsigned i n t VecGetSize ( i n t * e r r o r )

Returns the size of the considered vector.

Arguments:

int* error returned error code

Return value:

the size of the considered vector

6.5.22 VecGetType

Type VecGetType ( c o n s t unsigned i n t index , i n t * e r r o r )

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

Arguments:

const unsigned int index index of the element to be read

int* error (optional) returned error code

Return value:

The stored type encoded as Type

6.5.23 VecInsertInteger

v o i d V e c I n s e r t I n t e g e r ( c o n s t i n t v a l , i n t * e r r o r =0)

Pushes the new value to the end of the vector.

Arguments:

const int val integer value to be inserted in the vector

int* error (optional) returned error code

Return value:

void

6.5.24 VecInsertInt64

void VecInsertInt64 ( const i n t 6 4 v a l , i n t * e r r o r =0)

Pushes the new value to the end of the vector.

Arguments:

const ˙˙int64 val integer value to be inserted in the vector

int* error returned error code

Return value:

void

6.5.25 VecInsertDouble

v o i d V ec In se rt Do ub le ( c o n s t double v a l , i n t * e r r o r =0)

PowerFactory API 37
6 Class Reference

Pushes the new value to the end of the vector.

Arguments:

const double val: double

value to be inserted in the
vector int* error (optional):
returned error code

Return value:

void

6.5.26 VecInsertString

v o i d V e c I n s e r t S t r i n g ( c o n s t char * v a l , i n t * e r r o r =0)

Pushes the new value to the end of the vector.

Arguments:

const char* val string to be inserted in the vector

int* error (optional) returned error code

Return value:

void

6.5.27 VecInsertDataObject

v o i d V e c I n s e r t D a t a O b j e c t ( DataObject * v a l , i n t * e r r o r =0)

Pushes the new value to the end of the vector.

Arguments:

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

int* error returned error code

Return value:

void

6.5.28 VecInsertValue

v o i d V e c I n s e r t V a l u e ( c o n s t Value * v a l , i n t * e r r o r =0)

Pushes the new value to the end of the vector.

Arguments:

const Value* val pointer to the Value to be inserted in the vector

int* error returned error code

Return value:

void

PowerFactory API 38