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: [email protected]

PowerFactory API Published by DIgSILENT GmbH, Germany Copyright 2011. All rights reserved. Unauthorised copying or publishing of this or any part of this document is prohibited. 18 November 2011

PowerFactory API

2

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

3

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

4

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

5

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

6

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

7

1 Introduction

1 Introduction The DIgSILENT PowerFactory Application Programming interface (API) offers third party applications the possibility to embed PowerFactory’s functionality into their own program. It offers direct access to the PowerFactory data model and gives access to the varied calculations and its results. It has been designed to be reasonable small and consistent while being as powerful as possible. Based on one single dll, the idea is to keep the interface as small as possible while providing all the necessary functions to manipulate objects and execute commands. Technically, the interface is realized in C++ and provided as a DLL that can dynamically be linked to any external application. This document presents the structure of the API, and how to include it in third party applications. Available instructions and commands, methods to access objects and their parameters are illustrated by short examples. A full application example is presented in appendix: importing and exporting DIgSILENT PowerFactory projects from and to kml files that can be interpreted by GoogleEarth. This example also includes a wrapper implementation that allows using the API within managed code (managed C++, C#, etc.).

PowerFactory API

8

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

9

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 using api::Api; api::Api* apiInstance = CreateApiInstance(null, null);

Note: The executable file must be copied inside PowerFatory installation directory, else the link to the library is not done and dllHandle returns NULL. To use the API from an executable installed outside PowerFactory installation directory, a solution would be to create a start-up dll that can be called from outside the installation directory to start the api.

3.2 Delete an Instance of the API Using DestroyApiInstance, the corresponding instance of the API will be deleted and the memory occupied by the created objects within this instance of the API will be freed. DestroyApiInstance(apiInstance);

PowerFactory API

12

4 Accessing Objects and Attributes

4 Accessing Objects and Attributes 4.1 Accessing specific objects and browsing the database Specific objects can be accessed by using different methods on an instance of class “Application”: GetCurrentUser, GetActiveProject, GetActiveStudyCase, GetCalcRelevantObjects combined with DataObject’s methods GetChildren and GetParent to browse up and down the database. Examples: Value* user = apiInstance->GetApplication()->GetCurrentUser() will return a pointer of the generic type “Value” (see 6.6, for a description of this class), pointing to the current user in the PowerFactory database. Value* userProjects = user->GetDataObject()->GetChildren(false) returns a vector containing the objects (projects or folders) at the first level below the current user.

4.2 Accessing Object Attributes To access any attribute of an object (DataObject), its type must be known. The method GetAttributeType(name of the attribute) returns the type of the corresponding attribute. Attribute types are for instance: •

TYPE_INVALID in case of error

•

TYPE_INTEGER for attributes of type “int32”

•

TYPE_ INTEGER_VEC for vectors of int32

•

TYPE_DOUBLE for attributes of type “double”

•

TYPE_DOUBLE_VEC for vectors of doubles

•

TYPE_DOUBLE_MAT for matrices of doubles

•

TYPE_OBJECT for an attribute of type “object”

•

TYPE_OBJECT_VEC for vectors of objects

•

TYPE_STRING for an attribute of type string

•

TYPE_STRING_VEC for vectors of strings

•

TYPE_INTEGER64 for attributes of type “int64”

•

TYPE_ INTEGER64_VEC for vectors of int64

Once the type has been identified, methods like GetAttributeInt, GetAttributeDouble, GetAttributeObject, GetAttributeString return respectively the content of the attribute as an integer, double, DataObject or string. For manipulating matrices and vectors, their size can be identified using GetAttributeSize (see 6.5.14 for calling convention). GetAttributeInt, GetAttributeDouble, GetAttributeObject, GetAttributeString offer an overloaded method allowing to access specific objects in the matrix or the vector referring at its row and columns indices.

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

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 GetTerminals(DataObject* obj) { std::vector terms; if (obj->GetClassId() != 0 CLASSID_ELMTERM) { int error (0); Value* count = obj->Execute("GetConnectionCount", NULL, error); for(int i=0; iGetInteger(); ++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 GetCubicles(DataObject* obj) { std::vector cubs; if (obj->GetClassId() != 0 CLASSID_ELMTERM) { int error (0); Value* count = obj->Execute("GetConnectionCount", NULL, error); for(int i=0; iGetInteger(); ++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 Executing Commands 5.1 On an instance of the class “Application” The “Application” class contains an “Execute” method to execute a set of generic commands like “Activate” to activate a project “ExecuteCmd” allows reproducing commands like they would be entered in PowerFactory input window. Example: To show PowerFactory user interface api::Value cmd ("rcom/show"); apiInstance->GetApplication()->Execute("ExecuteCmd", &cmd, error); To hide PowerFactory user interface api::Value cmd ("rcom/hide"); apiInstance->GetApplication()->Execute("ExecuteCmd", &cmd, error);

5.2 On an instance of a “DataObject” Commands can also be executed on an object level by the method “Execute”. (See also 5.5 and 6.5.25) Example: executing a DPL script comdpl->Execute("Execute", NULL, error);

5.3 Running Calculations Calculations can be run by using the “Execute” method on a command object. The following example runs a short-circuit calculation with a short-circuit at a specific terminal: if (comShc == null) { comShc = actStdyCase->CreateObject("ComShc", "Short-Circuit"); } comShc->SetAttributeObject("shcobj", elmTerm); comShc->Execute("Execute", NULL); Where comShc is an “ComShc” object (short-circuit command), elmTerm is the terminal where the shortcircuit has to be performed.

Once again, the generic function “ExecuteCmd” can also be used for running calculations like load-flows, shortcircuits or rms/transient simulation even this is not the recommended way of performing calculations. Example: running a load-flow calculation api::Value cmd ("ldf/notopo/disp"); apiInstance->GetApplication()->Execute("ExecuteCmd", &cmd, error); For a short-circuit calculation:

PowerFactory API

17


api::Value cmd ("shc/iec/3psc/max/agi/all/asc"); apiInstance->GetApplication()->Execute("ExecuteCmd", &cmd, error);

5.4 Available Generic Functions on api::Application instance api->GetApplication()->Execute(string command, const Value* inArgs, int* error) Where “command” can be one of the following:

5.4.1 SearchFull Description: Searches and returns an object specified by path. Arguments: Value::VECTOR [0]: string, full path of object to search (e.g. .\Digsi.intUser\MyPrj.intPrj) [1]: optional DataObject, parent from which to start search (default is database root) Return value: Value::DataObject Returned Value* is never NULL but contained DataObject might be NULL if no object was found.

5.4.2 GetDefaultLocation Description: Gets default location where objects of given class name are stored. e.g. Library for Typ* Arguments: Value::VECTOR [0]: string, class name for which the default location is searched [1]: optional integer, create location if not exist (0 = no create, default; 1 = create) Return value: Value::DataObject Returned Value* is never NULL but contained DataObject might be NULL if location exists

5.4.3 NewProject Description: Creates a new project (using copy template in PF) and returns it. Arguments:

PowerFactory API

18


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

5.4.15 GetActiveRecordingStage Description: Returns the active system stage object. Arguments: NULL Return value: Value::DataObject Returned Value* is never NULL but contained DataObject might be null if folder or no active object found

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

PowerFactory API

22


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

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

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

PowerFactory API

23


5.5 Available Generic Functions on api::DataObject instance DataObject_Instance->Execute(string command, const Value* inArgs, int* error) Where “command” can be one of the following:

5.5.1 SlotUpdate Description: Performs a slot update for objects of class ElmComp Arguments: NULL Return value: None

5.5.2 IsBlockEncrypted Description: For objects of class BlkDef only, checks if block is encrypted Arguments: NULL Return value: Value::INTEGER, 0=false, >0=true

5.5.3 IsTransformer Description: Checks if current object is a transformer, Tr2, Tr2n, Tr3 Arguments: NULL Return value: Value::INTEGER, 0=false, >0=true

5.5.4 IsOutOfCalculation Description: Checks if current object is out of calculation. This status is determined by outserv flag and (optionally) automatic out-of-calc detection. Arguments:

PowerFactory API

24


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

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

5.5.6 GetConnectionCount Description: Number of connections for given object, e.g. ElmLne->2 Arguments: NULL Return value: Value::INTEGER

5.5.7 GetActiveGrids Description: Returns all currently active grids (ElmNet objects). Returned value might be empty, but is never null. Arguments: NULL Return value: Value::VECTOR, entries of type DataObject

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

PowerFactory API

25


Value::STRING = folder type or Value::VECTOR [0]: Value::STRING = folder type [1]: Value::INTEGER = 1 create if don't exists, 0 do not create Return value: Value::DATAOBJECT, IntPrjFolder of given type

PowerFactory API

26

6 References: Classes, Objects and Methods

6 References: Classes, Objects and Methods 6.1 Classes The API offers 5 different classes: -

Api: one single instance of the API

-

Application: one single instance of PowerFactory (running PowerFactory instance is related to the dll “digapi.dll” that has been loaded)

-

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

-

DataObject: any PowerFactory object

-

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

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

Figure 3. Only one instance of the API can be created at the time (CreateApiInstance). An instance of the Application is automatically linked to the instance of the API. One single OutputWindow is attached to the application instance. PowerFactory objects (grid elements, etc.) are represented as DataObject, as many as necessary DataObject can be created. Values represent arguments or attributes of an API instance, an application or DataObjects. For each of the above objects or instance of classes, once the program is done using it, the memory should be released in order to avoid memory leaks (see 6.2.2 ReleaseObject, 6.2.3 ReleaseValue). When the API is released, the memory is automatically freed; all remaining objects are released.

PowerFactory API

27


6.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. apiInstance = CreateApiInstance(); std::cout << "PowerFactory version:" << apiInstance->GetApplication()->GetVersion()->GetString() << std::endl;

6.2.5 IsDebug bool IsDebug() Arguments: None Return value: True if PowerFactory is in debug mode; false otherwise. Example: apiInstance = CreateApiInstance(); if(apiInstance->IsDebug()) { std::cout << "PowerFactory running in debug mode" << std::endl; }

6.3 Application 6.3.1 GetVersion const Value* GetVersion() The function returns the version of the currently running PowerFactory, e.g. "14.0.505"

PowerFactory API

29


Arguments: None Return value: Pointer to a Value object holding version information of PowerFactory application; returned string is never null and must be released when no longer in use. Example: The following example displays in the command window the version of the running instance of PowerFactory. apiInstance = CreateApiInstance(); std::cout << "PowerFactory version:" << apiInstance->GetApplication()->GetVersion()->GetString() << std::endl;

6.3.2 GetTempDirectory const Value* GetTempDirectory() Returns the path to the temporary directory of the running instance of PowerFactory Arguments: None Return value: A pointer of type Value pointing to a string with the temporary directory of PowerFactory Example: std::cout << apiInstance->GetApplication()->GetTempDirectory()->GetString() << std::endl;

6.3.3 GetWorkingDirectory const Value* GetWorkingDirectory() Returns the path to the working directory of the running instance of PowerFactory Arguments: None Returns A pointer of type Value pointing to a string with the working directory of PowerFactory Example: std::cout << apiInstance->GetApplication()->GetWorkingDirectory()->GetString() << std::endl;

6.3.4 GetOutputWindow OutputWindow* GetOutputWindow()

PowerFactory API

30


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: MODE_DISPLAYED = as displayed in PF (unit conversion applied) MODE_INTERNAL = as internally stored Arguments: AttributeMode mode: the way the attribute values should be accessed Return value: void Example:

6.3.13 GetAttributeMode AttributeMode GetAttributeMode() Returns the mode how object attributes are accessed. Return value of type AttributeMode (see 6.3.11) Arguments: None Return value:

PowerFactory API

34


AttributeMode MODE_DISPLAYED = as displayed in PF (unit conversion applied) MODE_INTERNAL = as internally stored Example: This example displays in a textbox the attribute mode api::Application::AttributeMode mode = apiInstance->GetApplication()->GetAttributeMode(); const char* strAttributeMode[]={"MODE_DISPLAYED","MODE_INTERNAL"}; printf("Attribute mode: %s \n", strAttributeMode[mode]);

6.3.14 SetWriteCacheEnabled void SetWriteCacheEnabled(bool enabled) This function intends to optimize performances. In order to modify objects in PowerFactory, those must be set in a special edit mode before any value can be changed. Switching back and forth between edit mode and stored mode is time consuming; enabling the write cache flag will set objects in edit mode and they will not be switched back until WriteChangeToDb (see 6.3.21) is called. Default value: disabled. Arguments: Bool enabled: true = enabled; false = disabled Return value: void Example: apiInstance->GetApplication()->SetWriteCacheEnabled(true);

6.3.15 IsWriteCacheEnabled bool IsWriteCacheEnabled() Returns whether or not the cache method for optimizing performances is enabled (see 6.3.14) Arguments: None Return value: Boolean: whether or not the cache method for optimizing performances is enabled Example: bool cacheEnabled; cacheEnabled = apiInstance->GetApplication()->IsWriteCacheEnabled();

PowerFactory API

35


6.3.16 GetAttributeType DataObject::AttributeType GetAttributeType(const char* classname, const char* attribute) This function returns the actual type of an object attribute. Arguments: const char* classname: class name for which the attribute type is considered const char* attribute: attribute which type must be returned Return value: Returns the type of the attribute or TYPE_INVALID on error (no attribute of that name exists) • •

TYPE_INVALID in case of error TYPE_INTEGER for attributes of type “int”

•

TYPE_INTEGER_VEC for a vector of type “int”

•

TYPE_DOUBLE for attributes of type “double”

•

TYPE_DOUBLE_VEC for vectors of doubles

•

TYPE_DOUBLE_MAT for a 2D matrix of doubles

•

TYPE_OBJECT for an attribute of type “object”

•

TYPE_OBJECT_VEC for a vector of objects

•

TYPE_STRING for an attribute of type string

•

TYPE_STRING_VEC for a vector of strings

•

TYPE_INTEGER64 for attributes of type 64bit integer

•

TYPE_INTEGER64_VEC for vector of 64bit integers

Example: The following example displays the attribute type for a given class and attribute (entered in textboxes) in a textbox. DataObject::AttributeType type = apiInstance->GetApplication()->GetAttributeType( textBoxAttributeClass) textBoxAttributeAttr); const char* strAttributeType[]={ "TYPE_INVALID","TYPE_INTEGER","TYPE_INTEGER_VEC","TYPE_DOUBLE", "TYPE_DOUBLE_VEC","TYPE_DOUBLE_MAT","TYPE_OBJECT","TYPE_OBJECT_VEC","TYPE_STRING", "TYPE_STRING_VEC","TYPE_INTEGER64","TYPE_INTEGER64_VEC"}; printf("Attribute %s for class %s: %s", textBoxAttributeAttr, textBoxAttributeClass, strAttributeType[type+1]);

6.3.17 GetAttributeDescription const Value* GetAttributeDescription(const char* classname, const char* attribute) Returns the description of an attribute, NULL if the attribute does not exist Arguments: const char* classname: class name for which the attribute type is considered

PowerFactory API

36


const char* attribute: attribute which description must be returned Return value: Pointer of type Value to the current attribute description (=string) Example: This example displays in a textbox the type, the description, the units and the size of a given attribute for a given class. DataObject::AttributeType type = apiInstance->GetApplication()->GetAttributeType( textBoxAttributeClass, textBoxAttributeAttr); const char* strAttributeType[]={ "TYPE_INVALID","TYPE_INTEGER","TYPE_INTEGER_VEC","TYPE_DOUBLE", "TYPE_DOUBLE_VEC","TYPE_DOUBLE_MAT","TYPE_OBJECT","TYPE_OBJECT_VEC","TYPE_STRING", "TYPE_STRING_VEC","TYPE_INTEGER64","TYPE_INTEGER64_VEC"}; const Value* descr = apiInstance->GetApplication()->GetAttributeDescription( textBoxAttributeClass, textBoxAttributeAttr); const Value* unit = apiInstance->GetApplication()->GetAttributeUnit( textBoxAttributeClass, textBoxAttributeAttr); int countRow; int countCol; apiInstance->GetApplication()->GetAttributeSize( textBoxAttributeClass, textBoxAttributeAttr, countRow, countCol); printf("Attribute %s for class %s: %s – Description: %s – Units: %s – Size: %d"’ textBoxAttributeAttr, textBoxAttributeClass, strAttributeType[type+1],descr->GetString(), unit->GetString(), countRow, countCol);

6.3.18 GetAttributeUnit const Value* GetAttributeUnit(const char* classname, const char* attribute) Returns the unit of an attribute, e.g. km, MW...; NULL if the given attribute name does not exist; the string is empty for attributes without units Arguments: const char* classname: class name for which the attribute type is considered const char* attribute: attribute which description must be returned Return value: Pointer of type Value to the units of the considered attribute (=string) Example: This example displays in a textbox the type, the description, the units and the size of a given attribute for a given class.

PowerFactory API

37


DataObject::AttributeType type = apiInstance->GetApplication()->GetAttributeType( textBoxAttributeClass, textBoxAttributeAttr); const char* strAttributeType[]={ "TYPE_INVALID","TYPE_INTEGER","TYPE_INTEGER_VEC","TYPE_DOUBLE", "TYPE_DOUBLE_VEC","TYPE_DOUBLE_MAT","TYPE_OBJECT","TYPE_OBJECT_VEC","TYPE_STRING", "TYPE_STRING_VEC","TYPE_INTEGER64","TYPE_INTEGER64_VEC"}; const Value* descr = apiInstance->GetApplication()->GetAttributeDescription( textBoxAttributeClass, textBoxAttributeAttr); const Value* unit = apiInstance->GetApplication()->GetAttributeUnit( textBoxAttributeClass, textBoxAttributeAttr); int countRow; int countCol; apiInstance->GetApplication()->GetAttributeSize( textBoxAttributeClass, textBoxAttributeAttr, countRow, countCol); textBoxCmd->Text = sprintf("Attribute %s for class %s: %s – Description: %s – Units: %s – Size: %d"’ textBoxAttributeAttr, textBoxAttributeClass, strAttributeType[type+1],descr->GetString(), unit->GetString(), countRow, countCol);

6.3.19 GetAttributeSize void GetAttributeSize(const char* name, const char* attribute, int& countRows, int& countCols) This function returns the size of object attribute if this attribute is a vector or a matrix. Arguments: const char* classname: class name for which the attribute type is considered const char* attribute: attribute which description must be returned int& countRows: the returned number of rows int& countCols: the returned number of columns Return value: void Example: This example displays in a textbox the type, the description, the units and the size of a given attribute for a given class. DataObject::AttributeType type = apiInstance->GetApplication()->GetAttributeType( textBoxAttributeClass, textBoxAttributeAttr); const char* strAttributeType[]={ "TYPE_INVALID","TYPE_INTEGER","TYPE_INTEGER_VEC","TYPE_DOUBLE", "TYPE_DOUBLE_VEC","TYPE_DOUBLE_MAT","TYPE_OBJECT","TYPE_OBJECT_VEC","TYPE_STRING", "TYPE_STRING_VEC","TYPE_INTEGER64","TYPE_INTEGER64_VEC"};

PowerFactory API

38


const Value* descr = apiInstance->GetApplication()->GetAttributeDescription( textBoxAttributeClass, textBoxAttributeAttr); const Value* unit = apiInstance->GetApplication()->GetAttributeUnit( textBoxAttributeClass, textBoxAttributeAttr); int countRow; int countCol; apiInstance->GetApplication()->GetAttributeSize( textBoxAttributeClass, textBoxAttributeAttr, countRow, countCol); printf("Attribute %s for class %s: %s – Description: %s – Units: %s – Size: %d"’ textBoxAttributeAttr, textBoxAttributeClass, strAttributeType[type+1],descr->GetString(), unit->GetString(), countRow, countCol);

6.3.20 Execute Value* Execute(const char* command, const Value* inArgs, int* error) This function executes a command on the instance of the application. Arguments: const char* command: the command that should be executed const Value* inArgs: input arguments for the command to be executed int* error: returned error code Return value: The function returns a pointer of type Value to the result of the command if applicable. Example: The following example displays the running PowerFactory instance to the screen by executing “ExecuteCmd” which executes a line of command as it would be entered in PowerFactory input window.6 int* error; api::Value cmd ("rcom/show"); apiInstance->GetApplication()->Execute("ExecuteCmd", &cmd, error);

6.3.21 WriteChangesToDb void WriteChangesToDb() This function combined with “SetWriteCacheEnabled” (see 6.3.14) is meant to optimize performances. If the write cache flag is enabled all objects remain in “edit mode” until “WriteChangesToDb” is called and all the modifications made to the objects are saved into the database. Arguments: None

PowerFactory API

39


Return value: void Example: apiInstance->GetApplication()->WriteChangeToDb();

6.4 OutputWindow 6.4.1 MessageType Enumerated type to define the type of message that should be displayed in PowerFactory output window: plain, error, warning, info. enum MessageType { M_PLAIN = 0, ///message not prepended by any text M_ERROR = 1, ///message prepended by error prefix, will also popup as error dialog M_WARN = 2, ///message prepended by warning prefix M_INFO = 4 ///message prepended by info prefix };

6.4.2 Print void Print(MessageType type, const char* msg) This function prints a message to the PowerFactory output window. Arguments: MessageType type: type of message: plain, error, warning, info (see 6.4.1) const char* msg: the actual message to be displayed Return value: void Example: The following example displays a message in the PowerFactory output window. api::OutputWindow* outWindow = apiInstance->GetApplication()->GetOutputWindow(); outWindow->Print(api::OutputWindow::M_INFO,"Running PowerFactory from the API");

6.4.3 Clear void Clear() Empties the content of the output window. Arguments: None

PowerFactory API

40


Return value: void Example: The following example displays a message in the PowerFactory output window and clears it. api::OutputWindow* outWindow = apiInstance->GetApplication()->GetOutputWindow(); outWindow->Print(api::OutputWindow::M_INFO,"Running PowerFactory from the API"); outWindow->Clear();

6.5 DataObject 6.5.1 AttributeType Enumerated type for defining the type of object attributes enum AttributeType { TYPE_INVALID

= -1, //error or inexisting attribute

TYPE_INTEGER = 0, //integer TYPE_INTEGER_VEC = 1, //vector of integers TYPE_DOUBLE = 2, //double TYPE_DOUBLE_VEC = 3, //vector of double TYPE_DOUBLE_MAT = 4, //matrix of doubles TYPE_OBJECT TYPE_OBJECT_VEC

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

TYPE_STRING TYPE_STRING_VEC

= 7, //string = 8, //vector of strings

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

6.5.2 GetClassName const Value* GetClassName() Returns the class name of the considered DataObject (ex: ElmTerm, etc.) Arguments: None Return value: Pointer of type Value to the class name of the object, never NULL. Example: This example iterates through the vector of the relevant objects for calculation and displays them and their classes in a treeview object.

PowerFactory API

41


int* error; const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects(); if(relevantObj) { printf("Getting relevant object for calculation... \n"); for (size_t i = 0, count = relevantObj->VecGetSize(error); i < count; ++i) { DataObject* obj = relevantObj->VecGetDataObject(i); treeViewCalcRelevant->Nodes->Add( gcnew String(obj->GetName()->GetString(error)) + " (" + gcnew String(obj->GetClassName()->GetString()) + ")"); } } else { Printf("No relevant object for calculation"); }

6.5.3 GetClassId int GetClassId() Returns the index of the class of the current object (see 6.3.9) Arguments: None Return value: integer representing the index number of the class of the considered object Example: This example iterates through the vector of the relevant objects for calculation and displays them and their classes id in a treeview object. int* error; const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects(); if(relevantObj) { textBoxCmd->Text = "Getting relevant object for calculation..." + System::Environment::NewLine + textBoxCmd->Text; for (size_t i = 0, count = relevantObj->VecGetSize(error); i < count; ++i) { DataObject* obj = relevantObj->VecGetDataObject(i); treeViewCalcRelevant->Nodes->Add( gcnew String(obj->GetName()->GetString(error)) + " (" + gcnew String(obj->GetClassId()) + ")"); } } else { textBoxCmd->Text = "No relevant object for calculation" + System::Environment::NewLine + textBoxCmd->Text;

PowerFactory API

42


}

6.5.4 GetName const Value* GetName() Returns the name of the object = attribute “loc_name” in PowerFactory; Arguments: None Return value: Pointer of type value with the name of the object (=string); never NULL Example: This example iterates through the vector of the relevant objects for calculation and displays them and their classes in a treeview object. int* error; const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects(); if(relevantObj) { textBoxCmd->Text = "Getting relevant object for calculation..." + System::Environment::NewLine + textBoxCmd->Text; for (size_t i = 0, count = relevantObj->VecGetSize(error); i < count; ++i) { DataObject* obj = relevantObj->VecGetDataObject(i); treeViewCalcRelevant->Nodes->Add( gcnew String(obj->GetName()->GetString(error)) + " (" + gcnew String(obj->GetClassName()->GetString()) + ")"); } } else { textBoxCmd->Text = "No relevant object for calculation" + System::Environment::NewLine + textBoxCmd->Text; }

6.5.5 GetFullName const Value* GetFullName(DataObject* relParent) Returns the name, including the path, of the current object relative to a parent object Arguments: DataObject* relParent: relative parent = start point of the path Return value: Pointer of type value with the full path to the object (=string); never NULL Example:

PowerFactory API

43


This example iterates through the vector of the relevant objects for calculation and displays the full name path (starting at the database level) in a treeview object. int* error; const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects(); if(relevantObj) { textBoxCmd->Text = "Getting relevant object for calculation..." + System::Environment::NewLine + textBoxCmd->Text; for (size_t i = 0, count = relevantObj->VecGetSize(error); i < count; ++i) { DataObject* obj = relevantObj->VecGetDataObject(i); treeViewCalcRelevant->Nodes->Add( gcnew String(obj->GetFullName(NULL)->GetString(error)) + " (" + gcnew String(obj->GetClassName()->GetString()) + ")"); } } else { textBoxCmd->Text = "No relevant object for calculation" + System::Environment::NewLine + textBoxCmd->Text; }

6.5.6 GetChildren const Value* GetChildren(bool recursive) Returns a collection of children objects for the current object. If the recursive flag is set to false, only the direct children of the object are returned else the function explores the full tree starting at the considered object. The returned value is a vector of DataObject; it is never NULL. Arguments Bool recursive: false only direct children are returned; true the complete descendant tree is returned. Return value: The returned value is pointer of type value pointing to a vector of DataObject; it is never NULL. Example: The following code displays the project of the current user into a tree view const Value* user(apiInstance->GetApplication()->GetCurrentUser()); TreeNode^ nodeUser = treeView1->Nodes->Add(gcnew String(user->GetDataObject()->GetName()>GetString())); const Value* children(user->GetDataObject()->GetChildren(false)); for (size_t i = 0, count = children->VecGetSize(); i < count; ++i) { DataObject* child = children->VecGetDataObject(i); nodeUser->Nodes->Add(gcnew String(child->GetName()->GetString()));

6.5.7 GetParent DataObject* GetParent()

PowerFactory API

44


Returns the parent object of the current object. Arguments: None Return value: the parent object of the current object; NULL if the object has no parent. Example: This example iterates through the vector of the relevant objects for calculation and displays them and their direct parent in a treeview object. int* error; const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects(); if(relevantObj) { textBoxCmd->Text = "Getting relevant object for calculation..." + System::Environment::NewLine + textBoxCmd->Text; for (size_t i = 0, count = relevantObj->VecGetSize(error); i < count; ++i) { DataObject* obj = relevantObj->VecGetDataObject(i); treeViewCalcRelevant->Nodes->Add( gcnew String(obj->GetName()->GetString(error)) + " (" + gcnew String(obj->GetParent()->GetName()->GetString()) + ")"); } } else { textBoxCmd->Text = "No relevant object for calculation" + System::Environment::NewLine + textBoxCmd->Text; }

6.5.8 IsNetworkDataFolder bool IsNetworkDataFolder() Checks whether the object is a network data folder (intBmu, intZone, etc.) Arguments: None Return value: Returns “true” if the object is a network data folder, false otherwise. Example: #define BOOL_STR(b) (b?"true":"false") int* error; const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects(); if(relevantObj)

PowerFactory API

45


{ textBoxCmd->Text = "Getting relevant object for calculation..." + System::Environment::NewLine + textBoxCmd->Text; for (size_t i = 0, count = relevantObj->VecGetSize(error); i < count; ++i) { DataObject* obj = relevantObj->VecGetDataObject(i); treeViewCalcRelevant->Nodes->Add( gcnew String(obj->GetName()->GetString(error)) + " (" + gcnew String(BOOL_STR(obj->IsNetworkDataFolder())) + ")"); } } else { textBoxCmd->Text = "No relevant object for calculation" + System::Environment::NewLine + textBoxCmd->Text; }

6.5.9 IsHidden bool IsHidden() Checks whether the object is active or not (depending on currently activated variation stage) Arguments: None Return value: Returns “true” if the object is inactive (stored in a inactive variation stage or deleted in the current stage) Example: This example iterates through the vector of the relevant objects for calculation and displays them and if they are hidden or not in a treeview object. #define BOOL_STR(b) (b?"true":"false") int* error; const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects(); if(relevantObj) { textBoxCmd->Text = "Getting relevant object for calculation..." + System::Environment::NewLine + textBoxCmd->Text; for (size_t i = 0, count = relevantObj->VecGetSize(error); i < count; ++i) { DataObject* obj = relevantObj->VecGetDataObject(i); treeViewCalcRelevant->Nodes->Add( gcnew String(obj->GetName()->GetString(error)) + " (" + gcnew String(BOOL_STR(obj->IsHidden())) + ")"); } } else {

PowerFactory API

46


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

6.5.10 IsDeleted bool IsDeleted() Checks whether the object is deleted (stored in the recycle bin). Arguments: None Return value: Returns “true” if the object is in the recycled bin; “false” otherwise. Example: #define BOOL_STR(b) (b?"true":"false") int* error; const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects(); if(relevantObj) { textBoxCmd->Text = "Getting relevant object for calculation..." + System::Environment::NewLine + textBoxCmd->Text; for (size_t i = 0, count = relevantObj->VecGetSize(error); i < count; ++i) { DataObject* obj = relevantObj->VecGetDataObject(i); treeViewCalcRelevant->Nodes->Add( gcnew String(obj->GetName()->GetString(error)) + " (" + gcnew String(BOOL_STR(obj->IsDeleted())) + ")"); } } else { textBoxCmd->Text = "No relevant object for calculation" + System::Environment::NewLine + textBoxCmd->Text; }

6.5.11 GetAttributeType DataObject::AttributeType GetAttributeType(const char* attribute) Returns the type of an attribute; “TYPE_INVALID” on error or for wrong attribute names (see 6.5.1 for type definition). Arguments: const char* attribute: the considered attribute for which the type must be returned Return value:

PowerFactory API

47


Returns a value of type AttributeType with the type of the considered attribute Example: This example returns the type of the “Project settings” (pPrjSettings) attribute of the active project const Value* activProj = apiInstance->GetApplication()->GetActiveProject(); const DataObject* prj = activProj->GetDataObject(); DataObject::AttributeType type = prj->GetAttributeType("pPrjSettings"); const char* strAttributeType[]={ "TYPE_INVALID","TYPE_INTEGER","TYPE_INTEGER_VEC","TYPE_DOUBLE", "TYPE_DOUBLE_VEC","TYPE_DOUBLE_MAT","TYPE_OBJECT","TYPE_OBJECT_VEC","TYPE_STRING", "TYPE_STRING_VEC","TYPE_INTEGER64","TYPE_INTEGER64_VEC"}; printf( "Project settings attribute type (pPrjSettings): %s \n", strAttributeType[type+1]);

6.5.12 GetAttributeDescription const Value* GetAttributeDescription(const char* attribute) Returns the description of an attribute of the current object; null if the required attribute does not exist. Arguments: const char* attribute: the considered attribute Return value: A pointer of type Value to the description of the attribute (=string) Example: This example returns the description of the “Project settings” (pPrjSettings) attribute of the active project const Value* activProj = apiInstance->GetApplication()->GetActiveProject(); const DataObject* prj = activProj->GetDataObject(); const Value* descr = prj->GetAttributeDescription("pPrjSettings"); printf("Project settings attribute description (pPrjSettings): %s\n", descr->GetString());

6.5.13 GetAttributeUnit const Value* GetAttributeUnit(const char* attribute) Returns the unit of an attribute of the considered object (km, MW, etc.); NULL if the attribute does not exist; empty string for attributes without units. Arguments: const char* attribute: the considered attribute Return value: Pointer of type Value to the units of the given attribute of the considered object (=string) Example: The following example displays the units of the attribute “Retention period” const Value* activProj = apiInstance->GetApplication()->GetActiveProject(); if(activProj)

PowerFactory API

48


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

6.5.14 GetAttributeSize void GetAttributeSize(const char* attribute, int& countRows, int& countCols) Returns the number of rows and columns for attributes of type matrix and vector. Arguments: const char* attribute: the considered attribute int& countRows: number of rows (return value) int& countCols: number of columns (return value) Return value: void Example: DataObject* myMatrix; int* row; int* col; myMatrix->GetAttributeSize(“matrix”, row, col);

6.5.15 GetAttributeInt int GetAttributeInt(const char* attribute, int* error) int GetAttributeInt(const char* attribute, int row, int col, int* error) Returns the value of an attribute as an integer. Arguments: const char* attribute: the considered attribute int row (optional): the row index of the element to be extracted if attribute is a matrix or a vector int col (optional): the row index of the element to be extracted if attribute is a matrix int* error (optional): returned error code Return value: Value of the considered attribute as an integer Example: The following example displays the value and the units of the attribute “Retention period” const Value* activProj = apiInstance->GetApplication()->GetActiveProject(); if(activProj)

PowerFactory API

49


{ const Value* units = activProj->GetDataObject()->GetAttributeUnit("st_retention"); int nbDays = activProj->GetDataObject()->GetAttributeInt("st_retention"); printf(“retention period: %d %s”, nbDays, units->GetString()); }

6.5.16 GetAttributeDouble double GetAttributeDouble(const char* attribute, int* error) double GetAttributeDouble(const char* attribute, int row, int col, int* error) Returns the value of an attribute as a double. Arguments: const char* attribute: the considered attribute int row (optional): the row index of the element to be extracted if attribute is a matrix or a vector int col (optional): the row index of the element to be extracted if attribute is a matrix int* error (optional): returned error code Return value: Value of the considered attribute as a double Example: DataObject* generator; double P = generator->GetAttributeDouble(“pgini”);

6.5.17 GetAttributeObject DataObject* GetAttributeObject(const char* attribute, int* error) DataObject* GetAttributeObject(const char* attribute, int row, int* error) Returns the value of an attribute as a pointer to a DataObject. Arguments: const char* attribute: the considered attribute int row (optional): the row index of the element to be extracted if attribute is a matrix or a vector int* error (optional): the returned error code Return value: Pointer to DataObject containing the corresponding attribute The data object must be released when no longer in use Example: DataObject* generator; DataObject* bus1 = generator->GetAttributeObject(“bus1”);

PowerFactory API

50


6.5.18 GetAttributeString const Value* GetAttributeString(const char* attribute, int* error) const Value* GetAttributeString(const char* attribute, int row, int* error) Returns the value of an string attribute. Arguments: const char* attribute: the considered attribute int row (optional): the row index of the element to be extracted if attribute is a matrix or a vector int* error (optional): returned error code Return value: Pointer of type “Value” to the attribute Example: DataObject* generator; char* name = generator->GetAttributeString(“loc_name”);

6.5.19 SetAttributeObject void SetAttributeObject(const char* attribute, DataObject* obj, int* error) void SetAttributeObject(const char* attribute, DataObject* obj, int row, int* error) Sets the corresponding object attribute. Arguments: const char* attribute: the considered attribute DataObject* obj: the new value of the attribute int row (optional): the row index of the element to be extracted if attribute is a vector int* error (optional): returned error code Return value: void Example: DataObject* generator; DataObject* newbus; generator->SetAttributeObject(“bus1”, newbus);

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

PowerFactory API

51


Sets the corresponding string attribute. Arguments: const char* attribute: the considered attribute const char* value: the new value of the attribute int row (optional): the row index of the element to be extracted if attribute is a vector or a matrix int col (optional): the column index of the element to be extracted if attribute is a vector or a matrix int* error (optional): returned error code Return value: void Example: DataObject* generator; generator->SetAttributeString(“loc_name”, “new name”);

6.5.21 SetAttributeDouble void SetAttributeDouble(const char* attribute, double value, int* error) void SetAttributeDouble(const char* attribute, double value, int row, int col, int* error) Sets the corresponding double attribute. Arguments: const char* attribute: the considered attribute double value: the new value of the attribute int row (optional): the row index of the element to be extracted if attribute is a vector or a matrix int col (optional): the column index of the element to be extracted if attribute is a vector or a matrix int* error (optional): returned error code Return value: void Example: DataObject* generator; generator->SetAttributeDouble(“pgini”, 1.600);

6.5.22 SetAttributeInt void SetAttributeInt(const char* attribute, int value, int* error) void SetAttributeInt(const char* attribute, int value, int row, int col, int* error) Sets the corresponding double attribute.

PowerFactory API

52


Arguments: const char* attribute: the considered attribute int value: the new value of the attribute int row (optional): the row index of the element to be extracted if attribute is a vector or a matrix int col (optional): the column index of the element to be extracted if attribute is a vector or a matrix int* error (optional): returned error code Return value: void Example:

6.5.23 ResizeAttribute void ResizeAttribute(const char* attribute, int rowSize, int colSize, int* error) Resize an attribute of the current object if this attribute is a matrix or a vector Arguments: const char* attribute: the considered attribute int rowSize: the new number of rows for the element int colSize: the new number of columns for the element int* error (optional): returned error code Return value: void Example: obj->ResizeAttribute(“matrix”, 1, 4);

6.5.24 CreateObject DataObject* CreateObject(const char* className, const char* locname) Create a new object of a given class inside the considered object (if this one can hold the new object) Returns a DataObject pointer to the newly created object if successful; NULL otherwise. Arguments: const char* className: the class name of the object to be created const char* locname: the name of the new object Return value:

PowerFactory API

53


Pointer to the newly created DataObject Example: The following example creates a new object of class “textBoxobjClass->Text” and name “textBoxobjName->Text” in the active project. if(apiInstance->GetApplication()->GetActiveProject()) { DataObject* prj = apiInstance->GetApplication()->GetActiveProject()->GetDataObject(); DataObject* newObject = prj->CreateObject(textBoxobjClass->Text, textBoxobjName->Text); }

6.5.25 Execute Value* Execute(const char* command, const Value* inArgs, int* error) This function executes a command on the instance of the object. Arguments: const char* command: the command that should be executed const Value* inArgs: input arguments for the command to be executed int* error (optional): returned error code Return value: The function returns a pointer of type Value to the result of the command if applicable. Example: The following example executes a dpl script void RunDplScript(char* name) { int error = 0; int filterID = apiInstance->GetApplication()->GetClassId("ComDpl"); DataObject* comdpl = NULL; if(apiInstance->GetApplication()->GetActiveProject()) { DataObject* prj = apiInstance->GetApplication()->GetActiveProject()->GetDataObject(); const Value* children = prj->GetChildren(false); for (size_t i = 0, count = children->VecGetSize(); i < count; ++i) { DataObject* child = children->VecGetDataObject(i); if (child->GetClassId() == filterID && strcmp(child->GetName()->GetString(), name) == 0) { comdpl = child; break; } } } if (!comdpl) { error = 1; printf("Cannot run dpl script %s\n",name); } else { printf("Running dpl script %s\ …n", name);

PowerFactory API

54


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 Value* activProj = apiInstance->GetApplication()->GetActiveProject(); const api::Value::Type typ = activProj->GetType(); const char* strType[]={ "UNKNOWN”, “INTEGER”, “DOUBLE”, “STRING”, “VECTOR_OLD2”, “INTEGER64”, “DATAOBJECT”, “VECTOR”, “DOUBLEMATRIX”, “VALUE"}; if(activProj) { printf("Active Project: %s Type: %s \n", activProj->GetDataObject(error)->GetName()->GetString(), strType[typ]); }

6.6.4 GetInteger int GetInteger(int* error) Returns an integer if the “Value” object is of integer type, otherwise returns 0. Arguments: int* error (optional): returned error code Return value: Returns an integer if the “Value” object is of integer type, otherwise returns 0.

PowerFactory API

56


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

6.6.5 GetInteger64 __int64 GetInteger64(int* error) Returns a long integer if the “Value” object is of long integer type, otherwise returns 0. Arguments: int* error (optional): returned error code Return value: Returns a long integer if the “Value” object is of long integer type, otherwise returns 0. Example: Value* val; __int64 iret = val->GetInteger64();

6.6.6 GetDouble double GetDouble(int* error) Returns a double if the “Value” object is of type double, otherwise returns 0. Arguments: int* error (optional): returned error code Return value: Returns a double if the “Value” object is of type double, otherwise returns 0. Example: Value* val; double iret = val->Getdouble();

6.6.7 GetString const char* GetString(int* error) Returns a string if the “Value” object is of type string, otherwise returns NULL. Arguments: int* error (optional): returned error code Return value: Returns a string if the “Value” object is of type string, otherwise returns NULL. Example:

PowerFactory API

57


const Value* descr = apiInstance->GetApplication()->GetAttributeDescription( textBoxAttributeClass, textBoxAttributeAttr); printf("Description: %s", descr->GetString())

6.6.8 GetDataObject DataObject* GetDataObject(int* error) Returns a pointer to a “DataObject” if the “Value” object is of type DataObject, NULL otherwise. DataObject must be released when no longer in use. Arguments: int* error (optional): returned error code Return value: Returns a pointer to a “DataObject” if the “Value” object is of type DataObject, NULL otherwise. Example: This example returns the description of the “Project settings” (pPrjSettings) attribute of the active project const Value* activProj = apiInstance->GetApplication()->GetActiveProject(); const DataObject* prj = activProj->GetDataObject(); const Value* descr = prj->GetAttributeDescription("pPrjSettings"); printf("Project settings attribute description (pPrjSettings): %s\n", descr->GetString());

6.6.9 MatGetRowCount unsigned int MatGetRowCount(int* error=0) returns the number of rows/elements if the “Value” is matrix/vector Arguments: int* error (optional): returned error code Return value: Number of rows as unsigned int Example: Value* val; int row = val->MatGetRowCount();

6.6.10 MatGetColCount unsigned int MatGetColCount(int* error=0) returns the number of columns if the “Value” is a matrix Arguments: int* error (optional): returned error code

PowerFactory API

58


Return value: Number of columns as unsigned int Example: Value* val; int col = val->MatGetColCount();

6.6.11 MatSetDouble void MatSetDouble(const unsigned int row, const unsigned int col, const double val, int* error=0) set the value of a double in a matrix at position (row, col) Arguments: const unsigned int row: row index const unsigned int col: column index const double val: double value to be inserted in the matrix int* error (optional): returned error code Return value: void Example: Value* val; val->MatSetDouble(1,1,2.5);

6.6.12 MatGetDouble double MatGetDouble(const unsigned int row, const unsigned int col, int* error=0) returns the value of the double in the considered matrix at position (row, col) Arguments: const unsigned int row: row index of the considered matrix element const unsigned int col: column index of the considered matrix element int* error (optional): returned error code Return value: The value of the double at position (row, col) Example: double d = val->MatGetDouble(1,1);

6.6.13 SetValue void SetValue(const int val)

PowerFactory API

59


void SetValue(const __int64 val) void SetValue(const double val) void SetValue(const char* val) void SetValue(DataObject* val) Set the value of a “Value” type object; value can be of types int, __int64, double, char* and DataObject* Arguments: According to the type of the value to be set: const int val: if the value to be set is an integer const __int64 val: if the value to be set is a long integer const double val: if the value to be set is a double const char* val: if the value to be set is a string const DataObject* val: if the value to be set is a DataObject Return value: void Example: double d = 5.5; Value* val; val->SetValue(d);

6.6.14 VecGetInteger int VecGetInteger(const unsigned int index, int* error) Returns the integer stored in a vector at position index Arguments: const unsigned int index: index of the element to be read int* error (optional): returned error code Return value: integer stored in a vector at position index Example: Value* val; int iret = val->VecGetInteger(1);

6.6.15 VecGetInteger64 __int64 VecGetInteger64(const unsigned int index, int* error) Returns a long integer stored in a vector at position “index”

PowerFactory API

60


Arguments: const unsigned int index: index of the element to be read int* error (optional): returned error code Return value: Returns a long integer stored in a vector at position “index” Example: Value* val; __int64 iret = val->VecGetInteger64(1);

6.6.16 VecGetDouble double VecGetDouble(const unsigned int index, int* error) Returns a double stored in a vector a position “index” Arguments: const unsigned int index: index of the element to be read int* error (optional): returned error code Return value: Returns a double stored in a vector a position “index” Example: Value* val; double iret = val->VecGetDouble(1);

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

PowerFactory API

61


6.6.18 VecGetDataObject DataObject* VecGetDataObject(const unsigned int index, int* error) Returns an object stored in a vector at position “index” Arguments: const unsigned int index: index of the element to be read int* error (optional): returned error code Return value: Returns an object stored in a vector at position “index” if the considered element is a “DataObject”, NULL otherwise. Example: This example iterates through the vector of the relevant objects for calculation and displays them and their direct parent in a treeview object. int* error; const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects(); if(relevantObj) { printf("Getting relevant object for calculation...\n"); for (size_t i = 0, count = relevantObj->VecGetSize(error); i < count; ++i) { DataObject* obj = relevantObj->VecGetDataObject(i); treeViewCalcRelevant->Nodes->Add( gcnew String(obj->GetName()->GetString(error)) + " (" + gcnew String(obj->GetParent()->GetName()->GetString()) + ")"); } } else { printf("No relevant object for calculation"); }

6.6.19 VecGetValue const Value* VecGetValue(const unsigned int idx, int* error=0) Returns a pointer to a “Value” stored in a vector at position “idx” Arguments: const unsigned int index: index of the element to be read int* error (optional): returned error code Return value: Returns a pointer to a “Value” if the considered element is a “Value”, NULL otherwise. Example:

PowerFactory API

62


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

6.6.20 VecClear void VecClear(int* error=0) empties the considered vector Arguments: int* error (optional): returned error code Return value: void Example: Value* val; Val->VecClear();

6.6.21 VecGetSize unsigned int VecGetSize(int* error) Returns the size of the considered vector Arguments: int* error (optional): returned error code Return value: the size of the considered vector Example: This example iterates through the vector of the relevant objects for calculation and displays them and their direct parent in a treeview object. int* error; const Value* relevantObj = apiInstance->GetApplication()->GetCalcRelevantObjects(); if(relevantObj) { textBoxCmd->Text = "Getting relevant object for calculation..." + System::Environment::NewLine + textBoxCmd->Text; for (size_t i = 0, count = relevantObj->VecGetSize(error); i < count; ++i) { DataObject* obj = relevantObj->VecGetDataObject(i); treeViewCalcRelevant->Nodes->Add( gcnew String(obj->GetName()->GetString(error)) + " (" + gcnew String(obj->GetParent()->GetName()->GetString()) + ")"); } } else {

PowerFactory API

63


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

6.6.22 VecGetType Type VecGetType(const unsigned int index, int* error) returns the type (integer, string, etc.) of an element stored in a vector at position “index” Arguments: const unsigned int index: index of the element to be read int* error (optional): returned error code Return value: Type = UNKNOWN, INTEGER, DOUBLE, STRING, VECTOR_OLD2, INTEGER64, DATAOBJECT, VECTOR, DOUBLEMATRIX, VALUE Example: Value* val; Type elType = val->VecGetType(1);

6.6.23 VecInsertInteger void VecInsertInteger(const int val, int* error=0) inserts an integer into a vector (at the end) Arguments: const int val: integer value to be inserted in the vector int* error (optional): returned error code Return value: void Example: Value* val(VECTOR); val->VecInsertInteger(1);

6.6.24 VecInsertInt64 void VecInsertInt64(const __int64 val, int* error=0) inserts an 64-bit integer into a vector (at the end) Arguments: const __int64 val: integer value to be inserted in the vector

PowerFactory API

64


int* error (optional): returned error code Return value: void Example: Value* val(VECTOR); val->VecInsertInt64(1);

6.6.25 VecInsertDouble void VecInsertDouble(const double val, int* error=0) inserts double at the end of a vector Arguments: const double val: double value to be inserted in the vector int* error (optional): returned error code Return value: void Example: Value* val(VECTOR); val->VecInsertDouble(1.5);

6.6.26 VecInsertString void VecInsertString(const char* val, int* error=0) inserts a string at the end of a vector Arguments: const char* val: string to be inserted in the vector int* error (optional): returned error code Return value: void Example: Value* val(VECTOR); val->VecInsertString(“test string”);

6.6.27 VecInsertDataObject void VecInsertDataObject(DataObject* val, int* error=0) inserts a pointer to a DataObject at the end of a vector

PowerFactory API

65


Arguments: DataObject* val: pointer to the DataObject to be inserted in the vector int* error (optional): returned error code Return value: void Example: Value* val(VECTOR); DataObject* obj; val->VecInsertDataObject(obj);

6.6.28 VecInsertValue void VecInsertValue(const Value* val, int* error=0) inserts a pointer to a Value at the end of a vector Arguments: const Value* val: pointer to the “Value” to be inserted in the vector int* error (optional): returned error code Return value: void Example: Value* val(VECTOR); Value* v(1); val->VecInsertValue(v);

PowerFactory API

66

Annexes

PowerFactory API

67

Annex A-1 : Application – interface with Google Earth

1 Introduction The purpose of this application is to illustrate how DIgSILENT PowerFactory API can be used, especially within GIS systems.

PowerFactory API

68

This simple toolbar allows the user to export PowerFactory diagrams to KML files, which are immediately displayed in Google Earth, import KML files as PowerFactory projects, show and hide PowerFactory GUI and run load flows and display the voltages at all bus bars. The application has been written in C#. To achieve this goal, a wrapper for the API functions and classes had had to be written first.

PowerFactory API

69

2 Managed Code Wrapper 2.1 Definition A wrapper class is a class that has no functionality of its own. Its member functions hide the use of a third party software component or an object with the non-compatible interface or a non-object-oriented implementation. It allows the use of unmanaged code (C++ native code) with managed code (C#). The wrapper in this application is a dll called “digApiWrapper.dll” that is included as a reference in all the projects of this application (importing to PowerFactory, exporting to kml, etc.) The principle is to encapsulate the unmanaged objects into managed functions and classes.

2.2 Example: Wrapping “Application” class The wrapper for Application class of digapi.dll is called WApplication.

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

C++/CLI

pointer

*

^

New element

new

gcnew

reference

&

%

NULL

NULL

nullptr

2.2.2 Calls in C# The new WApplication class can simply be called as if it was written directly in C#. Example: The following code gets the running PowerFactory application from the current api object (WApi is the wrapper for the class “Api”) and returns the active project as a WValue (the wrappel for the class “Value”). WApplication myPowerFactory = WApi.GetApplication(); WValue activeProj = myPowerFactory.GetActiveProject();

2.2.3 Code This document contains only code snippets that might be helpful for understanding. The whole source code for the wrapper is part of the following Google Earth example and can be obtained separately.

PowerFactory API

70

3 KML and PowerFactory Projects To interface PowerFactory with KML language, a match must be done between objects and types of both programs (PowerFactory and Google Earth). PowerFactory

KML

Project

Document

Grid

Folder

Object

Placemark

KML “Extended Data” field is used to store all the PowerFactory objects specific values and attributes (e.g. Type (typ_id), parent, etc.). The choice of exported objects and attributes mostly depends on the desired use of the exported data; in this example, as the second goal was to import kml files to PowerFactory, we have exported all possible objects and attributes in order for the imported project to look like the original one. The position of the object on the map is given by the coordinates of the “placemark”; objects like substations or terminals are represented as kml “Point” and lines are represented by kml “LineString”. For this application, a dll “DigKml.dll” has been written to manage, read and write kml objects from/to text files. This dll does not include the full kml standard and all its features but only the aspects that are useful for the purpose of this project. Below a simple example for representing one line “Line 2” in a grid “Nine_Bus” from a project called “example1” in kml format: Example1 Nine_Bus 1 Line 2 Parent __Network Model_intPrjfolder_Network Data_intPrjfolder_Nine_Bus_ElmNet_System Stage Mag-A-Stat_intVariant Class ElmBranch Id bus1 __Network Model_intPrjfolder_Network Data_intPrjfolder_Nine_Bus_ElmNet_System Stage Mag-A-Stat_intVariant_Bus 7_ElmTerm_Cub_1_StaCubic Id bus2 __Network Model_intPrjfolder_Network Data_intPrjfolder_Nine_Bus_ElmNet_System Stage Mag-A-Stat_intVariant_Bus 5_ElmTerm_Cub_3_StaCubic

PowerFactory API

71

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

Recommend Documents