Power System Analysis Engine DIgSILENT PowerFactory Version 13.

DIgSILENT GmbH Gomaringen, Germany December 2004

Table of Contents
Introduction .......................................................................................................................................3 1 Remote Procedure Calls..............................................................................................................3 2 Engine Mode ..............................................................................................................................5 2.1 Auto Log-on .........................................................................................................................5 2.2 Command rcom....................................................................................................................6 3 Commands .................................................................................................................................7 4 Example .....................................................................................................................................9

Introduction
DIgSILENT PowerFactory can be fully remote controlled. All functions and DPL scripts are available for easy integration with any other application, e.g. GIS and SCADA systems. Remote Procedure Calls (RPC) are used for client/server communication even in heterogeneous network environment. DIgSILENT PowerFactory provides command server functionality, the standard GUI may be visible (e.g. for graphical result output) or invisible (full engine mode, background operation). This document describes the usage of the PowerFactory engine. The next chapter explains the RPC interface. Chapter 2 explains how to use the PowerFactory engine mode. The last chapter contains a complete example (data import, calculation and result export).

1 Remote Procedure Calls

The following text is part of the Microsoft platform SDK description:

Purpose
Microsoft Remote Procedure Call (RPC) defines a powerful technology for creating distributed client/server programs. The RPC run-time stubs and libraries manage most of the details relating to network protocols and communication. This enables you to focus on the details of the application rather than the details of the network.

Where Applicable
RPC can be used in all client/server applications based on Microsoft Windows operating systems. It can also be used to create client and server programs for heterogeneous network environments that include such operating systems as Unix and Apple.

Developer Audience
RPC is designed to be used by C/C++ programmers. Familiarity with the Microsoft Interface Definition Language (MIDL) and the MIDL compiler are required.

Run-time Requirements
The RPC run-time libraries are included with Windows 95/98/ME and Windows NT/2000/XP. The components of the RPC development environment are installed when you install the Platform SDK. For details, see Installing the RPC Programming Environment. More details can be found in the Microsoft Developer Network Library (MSDN) or in the online help of the Microsoft Developer Studio. The client side of the PowerFactory engine is available as source code example. The executable digrcom.exe can be found in the subdirectory DOLE of any PowerFactory installation. It works as follows: There is one remote procedure defined for sending commands to the engine (see digrcom.idl):
int DIGCALL RCOM_Execute_Command([in] ,[in] ,[in, ,[in] ,[in, ); int iClientID int reclen ref, size_is(reclen)] char* command int retvallen out, ref, size_is(retvallen)] double* dRetVal

The

parameters are int iClientID: int reclen: char* command: int retvallen: double* dRetVal:

not yet used, default value 1 current string length of parameter command command which is transferred to the engine not yet used, default value 5 not yet used, default value 0 , default size dRetVal[5]

The return code is 0 for successful execution or not 0 in case of error. The console application digrcom.exe provides the following main arguments: -p protocol_sequence (e.g. ncacn_ip_tcp) -n network_address (e.g. 180.170.1.1) -e endpoint (e.g. 2001) -o options -d debug -c="command" (e.g. "ac \Demo\DSL-Example") -f="file" (e.g. "c:\digsi\command files\file1.cmd") The first four arguments are used to specify the RPC environment (see Microsoft help), the switch-d emits some debug messages, -c can be used to transfer one command only, -f specifies a command file. When neither -c nor -f is specified the executable is in interactive mode, commands can be entered, RC_stop will stop digrcom. Example: digrcom -d -p ncacn_ip_tcp -n 180.170.1.1 -e 2001 -f="example.cmd"

2 Engine Mode
The DIgSILENT PowerFactory program comes with sophisticated multi-user database facilities and with an accompanying user accounts managing system. Separate accounts may be created for all users of the same PowerFactory database. Because of the user account managing system, it is required to log on to the PowerFactory program at startup. The log-on dialog also offers options to change the basic program settings. Logging on requires the combination of a user account and a password. Details about the user account managing system are described in the PowerFactory Users manual. This chapter described how to avoid the log-on dialog and put PowerFactory in engine mode.

2.1

Auto Log-on

The Advanced page of the log-on dialog contains the option Log On Automatically. If this option is checked, the last account and password will be used to log-on without pop-up of the log-on dialog. Additionally the input field Startup Commands can be used to specify commands, which are executed directly after log -on. The following figure shows the Advanced page already configured for engine mode:

The log-on dialog will reappear when the option Log On Automatically is switched off. The log-on dialog can be edited when the PowerFactory executable is called with the main argument /config. This works since version 13.1 build 253. Example for the English version: digpfe.exe /config the Spanish version: digpfs.exe /config the German version: digpfd.exe /config

2.2

Command rcom

The PowerFactory command server is controlled with the command rcom. The following options can be used to start and stop the command server, to switch between batch and interactive mode and for application window control: rcom/start cengnam=2001 cprotoc=ncacn_ip_tcp cengnam defines the RPC endpoint, default 2001 cprotoc defines the protocol sequence, default ncacn_ip_tcp rcom/stop Stops the command server rcom/show Show the application window rcom/hide Hide the application w indow rcom/erroff Batch mode, do not pop up message boxes rcom/erron Interactive mode, pop up message boxes The dialog box of the remote control command rcom is depicted below:

3 Commands
In principle, everything that can be done in DIgSILENT PowerFactory , can be done from the command line in the input window. This includes creating objects, setting parameters, performing loadflow or shortcircuit calculations. Some commands that are available are typically meant for command line use or for batch commands. These commands are listed below: ac (activate/deactivate) Activates or deactivates a project or study case. Example: ac \USER\DSL-example ac/de all The keyword USER is substituted for the currently logged on user (e.g. Demo). The command ac/de all deactivates any active project. cd (c hange directory) Moves around in the database tree by opening another folder at absolute position or a relative position from the currently open folder. Example: cd ..\gridB\Load1 cd \Demo\IEC 909 Example 1 cd \USER\IEC 909 Example 1 cl (close) Stops the redirection of the output window to either a file or to a printer. All following messages will again be shown only in the output window. cl/out stops redirection to a file cl/prn stops redirection to a printer cls (clear window) Clears the output or input window. cls/out clears output window cls/inp clears input window cls clear input and output window copy Copy objects in the database. c opy source=\USER\DPL\dpl1 target=\USER\Example\Study Case copy/scase source=\USER\DPL\dpl1 The option /scase sets the target automatically to the active study case. dir (directory) Displays the contents of a folder. Example: dir Study Case ed (edit) Pops up the dialog of a default command, i.e. "ldf'', "shc'', etc. Example: ed ldf

exit Exits the program immediately without further confirmation. export DGS-export, e.g. results. grp/abi (graphic command) This command draws automatically all branches of a single line graphic as direct connections between already existing busbars/terminals. import DGS-import, e.g. permanent data. man (variable manager) Queries or sets a variable. Example: man/set obj=Load_1.ElmLod variable=plini value=0.2 op (redirect output) Redirects output to either a file or a printer. Example: op/out f=train3.out pause Interrupts the execution of the command pipe until a next pause command is executed. pr (print) Prints either the contents of the output window or the currently active graphics window. rd (read file) Opens and reads a file. Example: rd/dat f=D:\ Test\Project.dz stop Stops the running calculation, e.g. a simulation. sys (system call) Executes a dos command. wr (write) Writes to a file.

The dialog box of each command includes all available options and can be opened with the ed command, e.g. ed rd. The calculation commands are described in detail in the Users Manual. DPL scripts stored in the active study case or the DPL scripts included in the global library can be executed by the name, e.g. OptimizeOpenTie

4 Example
DIgSILENT PowerFactory is shipped with a complete example for data import, load flow calculation and export. The example can be found as batch file engine.bat in the subdirectory engine. The network address has to be adapted if PowerFactory and the remote command client digrcom.exe run on different machines. After starting PowerFactory engine (auto log-on and rcom as described in chapter 2) the batch file can be executed. It will send the following command sequence to the engine: cls/inp cls/out ac/de all rd/dat f=.\DGS\ResultVarSet.dz cd \USER del \USER\example1.IntPrj import targname=example1 targpath=\USER fFile=.\DGS\example1.dgs ldf export/res/comment pRes=\USER\VariableSets\Results fFile=.\ENGINE\results.dgs

For background operation the command rcom/hide can be added as first line.