PLCHandler Programming Guide - Esco Drives & Automation

PLCHandler Programming GuidePLCHandler Programming GuideDocument Version: 1.2Last update: 05.12.2008 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 1 of 17

PLCHandler Programming GuideCONTENTS1 INTRODUCTION 32 CPLCHANDLER CLASS 42.1 Constructor and Configuration of the PLCHandler 42.2 Destructor (and connection termination) 52.3 Connection establishment 52.4 Disconnection 62.5 Browsing all variables in the PLC 62.6 Getting a variables' description 72.7 Cyclic Update of Variables 72.7.1 Creating a cyclic list 72.7.2 Deleting a cyclic list 72.7.3 Reading the values of a cyclic list 82.8 Synchronous reading of variables 82.9 Synchronous writing of variables 82.10 General data transfer 92.11 Reading the directory structure on the PLC 92.12 Protected method for sending and receiving any services to/from the PLC 93 CONFIGURATION OF THE PARTICULAR INTERFACES 103.1 Simulation 103.2 ARTI 103.3 Gateway 103.4 Simplified configuration with the CEasyPLCHandler Class 10APPENDIX A: STRUCTURE OF THE INI-FILE FOR THE CONFIGURATION 11APPENDIX B: ERROR CODES 13APPENDIX C: STATUS REPORTS OF THE PLCHANDLER 14APPENDIX D: ACTIVEX-CONTROL OF THE PLCHANDLER UNDER WINDOWS 15 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 2 of 17

PLCHandler Programming Guide1 IntroductionThe PLCHandler is a C++-class which provides at a comfortable level services for the communicationbetween a client (e.g. visualization) and a 3S Automation-Alliance compliant PLC (controller).The following features and services are available:Establishing and terminating the communication with the PLCReading all variables on the PLCCyclic reading of variables' values from the PLCSynchronous reading of variables' values from the PLCSynchronous writing of variables' values to the PLCPossibility of instancing for the purpose of a simultaneous communication with several PLCsAutomatic reconnecting with the PLC after an break of the connectionAutomatic restart after a program download from CoDeSys to the PLCData transfer to and from PLCThus the PLCHandler can be used as a basic component for OPC Servers or visualizations.The communication to the PLC can be done via the following communication channels (named"interfaces" in the following):1. Simulation: The symbolic information of the PLC is read directly from SDB file 1 . Provided thisway all variables can be written to and read from the PLC like it is possible in a connection.2. ARTI: The ARTI-Interface already has been ported to various platforms (Windows NT,Windows CE, VxWorks, Linux) and serves as a communication layer concerning the PLC.The ARTI only supports communication via TCPIP and serial interface.3. Gateway: The Gateway is restricted to Windows 95/98/NT/2000/XP, but provides variouscommunication media and protocols (TCPIP, RS232, Shared-Memory, CANOpen, ...).The Handler is delivered as SDK 2 , i.e. all C++ header files, the static link library (PLCHandler.lib resp.PLCHandlerComplete.lib) and a sample program (main.cpp) are part of the package.The link library is provided in two different versions:1. PLCHandler.lib: Contains only PLCHandler (without ARTI resp. gateway dlls)2. PLCHandlerComplete.lib: Contains complete ARTI interface (no additional dlls needed)A Visual Studio C++ V6.0 workspace for compiling the sample program also is contained(PLCHandlerDemo.dsp).For the Windows Platform the PLCHandler additional is available as a dll (PLCHandler.dll with ANSIinterface)and as ActiveX-Control (PLCHandlerX.ocx).In the following the PLCHandler class and its methods will be described in detail.1 SDB = Symbolic Data Base; will be created by CoDeSys during project compilation if in Project /Options / Symbol configuration the export of variables is activated2 SDK: Source Development Kit 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 3 of 17

PLCHandler Programming Guide2 CPLCHandler Class2.1 Constructor and Configuration of the PLCHandlerA PLCHandler object of the CPLCHandler class always is assigned to a single PLC. Thus at creationof the object it has to be configured, with which PLC resp. which communication interface thePLCHandler should work. The configuration is specified in chapter 3.There are various constructors for creating the PLCHandler object:1. CPLCHandler(unsigned long ulId, char *pszIniFile,SysLog *pLogFile = NULL):Parameter ulId designates the index of the PLCHandler assumed that more instances areused.An ini-file for reading the configuration will be handed over to the constructor. The SDKprovides two sample files (OPCServerARTI.ini and OPCServerSimu.ini). The structure isdescribed in detail in the Appendix of this guide.Optionally a log file can be specified for recording all errors and internal states. The SysLogclass is contained in the PLCHandler.2. CPLCHandler(PlcConfig *pPlcConfig, PlcDeviceDesc *pDeviceDesc,SysLog *pLogFile = NULL):The parameters on the one hand define general configuration data in the PLCHandler(pPlcConfig) and on the other hand the communication settings for the (pDeviceDesc). Thedata are identic with the entries in the ini-file. Thus both constructors can be used according tothe actual requirements.Optionally also here a log file can be specified for recording all errors and internal states. TheSysLog class is contained in the PLCHandler.The PlcConfig structure contains the configuration data for the PLCHandler:struct PlcConfig{PlcConfig(void);~PlcConfig(void);unsigned long ulId;unique ID for every PLCchar *pszName; name of the PLCItfType it; interface type of the PLC (IT_ARTI, IT_GATEWAY, ...)char ulSize; size of the variablechar bActive; flag if the PLC is active or notchar bMotorola; flag if data has to be swapt for motorola byte orderchar bLogin; flag if the application can do a loginchar bLogToFile; flag if the application should log to a filechar bPreCheckIdentity; flag if the project identity will be checkedbefore every read / write of variablesunsigned long ulTimeout; communication timeout in msunsigned long ulNumTries; number of tries of receive's before throwing aCOMM_FATAL errorunsigned long ulWaitTime; total time in ms to wait for a reconnection to the PLCunsigned long ulReconnectTime; time interval in ms to try for a reconnectionchar *pszHwType; HW type of the PLC (PLCC_HW_STANDARD,PLCC_HW_MAX4)unsigned long ulHwVersion;unsigned long ulBufferSize;HW versioncommunication buffersize of the runtime systemrunning on the PLC; 0 = default sizechar *pszProjectName; name of the CoDeSys project running on theruntime system; only of interest in simulationchar *pszDllDirectory; directory where to find the (Sym-)ARTI Dll'sGatewayConnection *gwc; pointer to the gateway connection if using thegateway interface 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 4 of 17

PLCHandler Programming Guideunsigned long ulLogFilter; Filter for log actions};The PlcDeviceDesc structure contains data to connect to a device:struct PlcDeviceDesc{PlcDeviceDesc(void);~PlcDeviceDesc(void);char* pszName; name of the device / protocolchar* pszInstance; instance name of the devicechar* pszProject; name of the project running on that device (only ofinterest for gateway)unsigned long ulNumParams; number of the device parametersPlcParameterDesc* ppd; pointer to an array of parameter descriptions};To get the definition of the PlcParameterDesc please have a look at the PLCHandler headerPlcConfig.h.3. CPLCHandler(SysLog *pLogFile = NULL):This constructor is used to create a PLCHandler object with default configuration (Interface:ARTI).But in each case before connection establishment the communication device must beconfigured (with SetConfig() or directly by opening the configuration with GetConfig() andsetting the appropriate values).2.2 Destructor (and connection termination)As soon as the PLCHandler object has been deleted, the connection to the PLC gets terminated (ifthere was one), all resources are deallocated and all internal threads are terminated.2.3 Connection establishmentMethod: long ::Connect(unsigned long ulTimeout = PLCHANDLER_USE_DEFAULT,unsigned long hStateChangedEvent = 0, int bLoadSymbols = 1)After the configuration has been done, via this method a connection to the PLC can be established.The method will return RESULT_OK (=0) as soon as the connection has been built up successfully. Incase of an error the current state of the communication resp. The last occurred error can be get by theGetStatus() resp. GetLastError().If a connection could not be established, the method returns an error and internally a thread will bestarted, trying to reconnect to the PLC in the defined reconnect interval.ulTimeout: This value specifies how long the connection establishment maximally can take,before the function returns. At 0 the value set actually in the configuration will be used (see:WaitTime). At ulTimeout = –1 the method will not return until a connection to the PLC will be set upsuccessfully. This can take any time.hStateChangedEvent: Here optionally the handle of an event can be passed which can be used toinform the client at each status change.bLoadSymbols: This parameter can be used to specify whether at a connection establishment thesymbols of the PLC should be loaded or not.Return value: If no error occurs, the function returns RESULT_OK. Otherwise, it returns …RESULT_FAILED: common error in the underlying interfaces. A specific error code can beretrieved by GetStatus() resp. GetLastError().RESULT_NO_CONFIGURATION: no configuration for this PLCHandler instance (Id unknown). 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 5 of 17

PLCHandler Programming GuideRESULT_PLCHANDLER_INACTIVE: PLCHandler instance isn’t set active (see IniFile).RESULT_RECONNECTTHREAD_STILL_ACTIVE: reconnect thread is still active.RESULT_ITF_NOT_SUPPORTED: the interface isn’t supported.RESULT_ITF_FAILED: the interface can’t start successfully (missing interface dependentDll’s).RESULT_PLC_NOT_CONNECTED: cannot open connection to the PLC.RESULT_PLC_NOT_CONNECTED_SYMBOLS_LOADED: cannot open connection to the PLC butcould load the symbol file offline.2.4 DisconnectionMethod: long ::Disconnect(void)At a call of this method the connection to the PLC will be terminated.Return value: If no error occurs, the function returns RESULT_OK. Otherwise, it returns …RESULT_FAILED: no corresponding interface which can be closed .2.5 Browsing all variables in the PLCMethod: long ::GetAllItems(PlcSymbolDesc **ppSymbolList, unsigned long *pulNumOfSymbols)This method can be used to read the list of all variables which are specified in the PLC.In ppSymbolList a list of all symbols will be returned. For each symbol the list provides name, datatype, address within PLC, variables size in bytes etc.In pulNumOfSymbols the number of variables will be returned.Return value: If no error occurs, the function returns RESULT_OK. Otherwise, it returns …RESULT_FAILED: common error in the underlying interfaces. A specific error code can beretrieved by GetStatus() resp. GetLastError().RESULT_PLC_NOT_CONNECTED: lost connection to the PLC.RESULT_INVALID_PARAMETER: invalid function parameters (for e.g. NULL).The PlcSymbolDesc structure contains the symbolic description of a variable:struct PlcSymbolDesc{char* pszName; symbol name of the variableunsigned long ulTypeId; reference into the symbol type tablechar* pszType; type name of the variableunsigned short usRefId; variable's type (input, output, global, …)unsigned long ulOffset; offset in the memory imageunsigned long ulSize; size of the variablechar szAccess[2]; access type of the variable (no, read, write access, both)unsigned char bySwapSize; basic swap size of the variable};Speciality: The size of a bit symbol is per definition 0 in the CoDeSys runtime system. So you haveto check the symbol's size for 0 and do a special bit coding (for e.g. memset() or memcpy()with parameter size=1 instead with the original symbol's size) 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 6 of 17

PLCHandler Programming Guide2.6 Getting a variables' descriptionMethod: long ::GetItem(char *pszSymbol, PlcSymbolDesc *pSymbol)pszSymbol specifies the variable, for which the description should be retrieved.In pSymbol the description (data type, size in bytes, address etc.) of the variable will be returned.Return value: If no error occurs, the function returns RESULT_OK. Otherwise, it returns …RESULT_FAILED: common error in the underlying interfaces. A specific error code can beretrieved by GetStatus() resp. GetLastError().RESULT_PLC_NOT_CONNECTED: lost connection to the PLC.RESULT_INVALID_PARAMETER: invalid function parameters (for e.g. NULL).2.7 Cyclic Update of Variables2.7.1 Creating a cyclic listMethod: HCYCLIST ::CycDefineVarList(char **ppszSymbols, unsigned long ulNumOfSymbols,unsigned long ulUpdateRate, unsigned long hUpdateReadyEvent = 0,unsigned long hDataChangeEvent = 0, unsigned long hUpdateEvent = 0)This method can be used to create a list of variables, whose values should be updated cyclically bythe PLCHandler and can be read at any time. The method returns a handle for the list. This handlemust be passed with all further method calls.ppszSymbols: Here a list of variable names will be passed.ulNumOfSymbols: This parameter specifies the number of variables in the list.ulUpdateRate: Specifies the update rate for the cyclic update of the variable values.hDataChangeEvent: Here optionally a handle on a event can be specified, referring to which aninformation should be sent at any value change.hUpdateEvent: Here the handle of an event can be passed, which then will be used to control thecyclic update.Return value: If no error occurs, the function returns a handle for the cyclic list. Otherwise, it returns …NULL: function failed. A specific error code can be retrieved by GetStatus() resp.GetLastError().2.7.2 Deleting a cyclic listMethod: long ::CycDeleteVarList(HCYCLIST hCycVarList, int bKeepalive = 1)This method is used to delete a list of variables which had been set up for cyclic update (see above).hCycVarList: Specifies the handle which has been passed by CycDefineVarList().BKeepalive: Here you define, whether the PLCHandler should start a so-called "Keepalive" if thecurrent list is the last cyclic list which gets deleted. In this case typically a thread will be started in thePLCHandler, sending a Keepalive service to the PLC every 2 seconds, in order that the PLC will notlog out if no further services are sent.Return value: If no error occurs, the function returns a handle for the cyclic list. Otherwise, it returns …RESULT_PLC_NO_CYCLIC_LIST_DEFINED: no list to delete. 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 7 of 17

PLCHandler Programming Guide2.7.3 Reading the values of a cyclic listMethods: long ::CycEnterVarAccess(HCYCLIST hCycVarList)long ::CycReadVars(HCYCLIST hCycVarList, PlcVarValue ***pppValues,unsigned long *pulNumOfValues)void ::CycLeaveVarAccess(HCYCLIST hCycVarList)The methods CycEnterVarAccess() and CycLeaveVarAccess() must enclose each read operation in acyclic list to synchronize access to the variables of the list.The method CycReadVars() can be used to access the values of a cyclic list. Those get updatedaccording to the time pattern defined by UpdateRate.Return value : If no error occurs, the function CycEnterVarAccess() return 1. Otherwise, it returns …0: the cyclic list is invalid.Return value: If no error occurs, the function CycReadVars() returns RESULT_OK. Otherwise, it returnsRESULT_FAILED: common error in the underlaying interfaces. A specific error code can beretrieved by GetStatus() resp. GetLastError().RESULT_PLC_NOT_CONNECTED: lost connection to the PLC.RESULT_INVALID_PARAMETER: invalid function parameters (for e.g. NULL).RESULT_PLC_NO_CYCLIC_LIST_DEFINED: invalid list or no list variables to read.2.8 Synchronous reading of variablesMethods:HVARLIST ::SyncReadVarsFromPlc(char **ppszSymbols,unsigned long ulNumOfSymbols, PlcVarValue ***pppValues,unsigned long *pulNumOfValues)long ::SyncReadVarsFromPlcReleaseValues(HVARLIST hSyncRead)The method SyncReadVarsFromPlc() can be used to read the values of a list of variables from thePLC.ppszSymbols: specifies the list of variablesulNumOfSymbols: number of variables in the listpppValues: returns the list of variables values after the callpulNumOfValues: Number of read valuesSyncReadVarsFromPlcReleaseValues() then can be used to deallocate the list of read variablesReturn value: If no error occurs, the function returns a handle for the list. Otherwise, it returns …NULL: function failed. A specific error code can be retrieved by GetStatus() resp.GetLastError().2.9 Synchronous writing of variablesMethod: long ::SyncWriteVarsToPlc(char **ppszSymbols, unsigned long ulNumOfSymbols,unsigned char **ppbyValues)This method can be used to transfer a list of variable values to the PLC.ppszSymbols: specifies the list of variablesulNumOfSymbols: number of variables in the listppbyValues: specifies the variables values which should be written to the PLC. Must match the list ofthe specified variables !Return value: If no error occurs, the function returns RESULT_OK. Otherwise, it returns … 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 8 of 17

PLCHandler Programming GuideRESULT_FAILED: common error in the underlying interfaces. A specific error code can beretrieved by GetStatus() resp. GetLastError().RESULT_PLC_NOT_CONNECTED: lost connection to the PLC.RESULT_EXCEPTION: an exception occurred in the underlying interface.2.10 General data transferMethods:long ::UploadFile(char *pszPlc, char *pszHost = NULL)long ::DownloadFile(char *pszHost, char *pszPlc = NULL)The method UploadFile() can be used to transfer files from the PLC to the client. pszPlc specifies thename of the file on the PLC, pszHost specifies the name of the file on the client.The method DownloadFile() can be used to transfer files from the client to the PLC. pszHost specifiesthe name of the file on the client, pszPlc specifies the name of the file on the PLC.The methods RenameFile() and DeleteFile() can be used to rename resp. delete files on the PLC.Return value: If no error occurs, the function returns RESULT_OK. Otherwise, it returns …RESULT_FAILED: common error in the underlying interfaces. A specific error code can beretrieved by GetStatus() resp. GetLastError().RESULT_PLC_NOT_CONNECTED: lost connection to the PLC.2.11 Reading the directory structure on the PLCMethod: long ::ReadDirectory(CDirInfo **ppdi, char *pszBaseDir = NULL)This method can be used to read the directory structure on the PLC. You can specify a basic folder inpszBaseDir.In object ppdi the complete directory structure is stored (including files and sub-directories).Return value: If no error occurs, the function returns RESULT_OK. Otherwise, it returns …RESULT_FAILED: common error in the underlying interfaces. A specific error code can beretrieved by GetStatus() resp. GetLastError().RESULT_PLC_NOT_CONNECTED: lost connection to the PLC.2.12 Protected method for sending and receiving any services to/from thePLCMethod: long ::SyncSendService(unsigned char *pbySend, unsigned long ulSendSize,unsigned char **ppbyRecv, unsigned long *pulRecvSize)This method can be used to transfer any runtime system service to the PLC.Return value: If no error occurs, the function returns RESULT_OK. Otherwise, it returns …RESULT_FAILED: common error in the underlying interfaces. A specific error code can beretrieved by GetStatus() resp. GetLastError().RESULT_PLC_NOT_CONNECTED: lost connection to the PLC.RESULT_EXCEPTION: an exception occurred in the underlying interface.ATTENTION: The structure of the service must be known in detail! An erroneous service might causea crash of the PLC! Due to this reason the method is only accessible in derivative classes and has notbeen published straightly. 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 9 of 17

PLCHandler Programming Guide3 Configuration of the particular interfacesThe PLCHandler allows to communicate with a PLC via two different interfaces (ARTI or Gateway)and it makes possible a simulation of the PLC variables if no PLC is connected.See In the following how the PLCHandler must be configured in order to be able to communicate viathe particular interfaces.3.1 Simulationwill be supplied in a future version of the document3.2 ARTIwill be supplied in a future version of the document3.3 Gatewaywill be supplied in a future version of the document3.4 Simplified configuration with the CEasyPLCHandler ClassThe PLCHandler contains a derived class CEasyPLCHandler. This class encapsulates the mostimportant and popular communication channels and applies the appropriate correct settings.The following methods are available in addition to the PLCHandler methods:Method: long ::ConnectTcpipViaGateway(char *pszGatewayIP, char *pszPlcIP,char *pszProtocol = PLCC_DN_TCPIP_L2ROUTE,int bMotorola = 0, int bLoadSymbols = 1,unsigned long ulTimeout = PLCHANDLER_USE_DEFAULT)This method can be used to set up a connection to a PLC via TCPIP and the Gateway on a Windowssystem. For this purpose only the IP address of the gateway as well as the IP address of the PLCmust be passed on. Default setting: Tcpip L2 Route Protocol.Method: long ::ConnectTcpipViaArti(char *pszPlcIP,char *pszProtocol = PLCC_DN_TCPIP_L2ROUTE,int bMotorola = 0, int bLoadSymbols = 1,unsigned long ulTimeout = PLCHANDLER_USE_DEFAULT);This method can be used to set up a connection to a PLC via TCPIP and ARTI. For this purpose onlythe IP address of the PLC must be passed on. Default setting: Tcpip L2 Route Protocol.Method: long ::ConnectRs232ViaArti(short sPort, unsigned long ulBaudrate,int bMotorola = 0, int bLoadSymbols = 1,unsigned long ulTimeout = PLCHANDLER_USE_DEFAULT);This method can be used to set up a connection to a PLC via ARTI and the serial interface. sPort = 1corresponds to COM1, etc.Method: long ::ConnectToSimulation(char *pszSdbFile, int bLoadSymbols = 1,unsigned long ulTimeout = PLCHANDLER_USE_DEFAULT);This method can be used to set up a connection to a simulation and to a SDB file. Only the name ofthe SDB file must be given. For this purpose also a complete path can be specified.Return value: These methods return same error values like the ::Connect() method. 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 10 of 17

PLCHandler Programming GuideAppendix A: Structure of the Ini-File for the Configuration[Server]PLCs=2PLC0=PLCWinNTPLC1=RTEPLCHandler-SectionNumber of configured PLCHandlers (for severalinstances/connections)Name of the first PLC; here e.g. PLCWinNTName of the second PLC; here e.g. RTE[PLC:PLCWinNT]interfacetype=ARTIlogevents=1active=1motorola=0nologin=0timeout=10000precheckidentity=0tries=3waittime=20reconnecttime=20buffersize=0max4version=0This section is assigned to a particular PLCHandlerinstance. The assignment is done by specifying theindex in the constructor of the PLCHandler object. Thisindex corresponds to the index in the above defined listof instances (PLC=…).Interface type: ARTI, SIMULATION, GATEWAY (gateway onlyunder WinNT/2000/XP)Activating/Deactivating the output of events in a log file(OPCServer.log). The file is in the same directory as theOPC-Server.Flag, defines whether the PLC is active (Establishingconnection) or notFlag, defines whether the data must be swapped (MotorolaByte order is used on the PLC) or notFlag, defines whether the PLCHandler should not log in onthe PLC; some runtime systems only allow a log-in of oneapplication !Special: ELAU, ABB -> nologin = 1Time in ms, defines how long the answer on a data packagefrom the PLC might take, before an error will be dumped.Flag, defines whether the symbol file should be checked forup-to-dateness by a separate runtime system service beforeeach reading/writing of variables.Regard: On runtime systems >= 2.3 at each write-/readservice it will be checked automatically, whether the symbolfile still are up to date. For this reason on those runtimesystems this entry can be 0.Number of communication trials in case the receiving of datafails.Total time in seconds in PLCHandler::Connect() for theconnection establishment. As soon as the time is exceeded,the routine returns with an error.Time slice in seconds according to which a reconnect is triedby Reconnect-Thread().Size of the communication buffer; must match with the usedruntime system. 0 = Default value for the currently usedcommunication protocol.Special: ELAU -> buffersize = 1500Please use only together with a ELAU-Max4 controller and inthis case set to the corresponding hardware version (1100,1200); with all other controllers this entry is not applicable! 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 11 of 17

PLCHandler Programming Guideproject= ProjektName.prodevice=Tcp/Ip (Level 2Route)instance=PLCWinNT_TCPIPparameters=4parameter0=Addressvalue0=localhostparameter1=PortOnly relevant in SIMULATION: in this case the PLCHandlerneeds no PLC, but simulates the PLC via the symbol file’ProjektName.sdb’.This entry also can be used in the ARTI Interface, if the SDBfile cannot be stored on the underlying PLC.Communication protocol; the most important settings are:Tcp/Ip (Level 4): TCP/IP Level 4 ProtocolTcp/Ip (Level 2): TCP/IP Level 2 ProtocolTcp/Ip (Level 2 Route): TCP/IP Level 2 RouteSerial (RS232): Serial connectionFor information on other protocols please see thecorresponding specification (see Gateway).Special: ELAU -> device = Tcp/IP (Level 4)Here you can assign a name to the package of configurationsettingsNumber of parameters for this protocol(here: TCP/IP Level 2 Route)Name of the first parameter: TCP/IP address of the PLCValue of first parameter: here: connection to localhostName of second parameter: Port Numbervalue1=1200 Value of second parameter: Default value 1200parameter2= TargetIdvalue2=0parameter3= Motorolabyteordervalue3=NoSpecial: ELAU -> value1 = 5000For TCP/IP (Level 2 Route): ID of the runtime system,to which the data should be routedFor TCP/IP (Level 2 Route): Default value 0 (norouting)Name of fourth parameter: Motorola byte order for thecommunication dataValue of fourth parameter: No -> no swapping necessary[PLC:RTE]interfacetype=GATEWAY...This is the second instance to be configuredInterface type: ARTI, SIMULATION, GATEWAY (gateway onlyunder WinNT/2000/XP) 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 12 of 17

PLCHandler Programming GuideAppendix B: Error codesDefine Value DescriptionRESULT_FAILED -1 Action erroneous.More exact error values canbe requested by::GetLastError() resp. by::GetState().RESULT_OK 0 Action successfulRESULT_PLC_NOT_CONNECTED 1 PLC not connectedRESULT_PLC_LOGIN_FAILED 2 Login to PLC has failedRESULT_PLC_NO_CYCLIC_LIST_DEFINED 3 No cyclic list has been foundRESULT_PLCHANDLER_INACTIVE 4 PLCHandler is inactiveRESULT_LOADING_SYMBOLS_FAILED 5 Loading of the symbols hasfailedRESULT_ITF_NOT_SUPPORTED 6 The defined communicationinterface is not valid or notsupportedRESULT_COMM_FATAL 7 Communication error occurredduring actionRESULT_NO_CONFIGURATION 8 Wrong or erroneousconfiguration of thePLCHandlerRESULT_INVALID_PARAMETER 9 Invalid parameterRESULT_ITF_FAILED 10 Communication interface notresp. incorrectly installed (e.g.Gateway Dlls not available)RESULT_NOT_SUPPORTED 11 Method not yet supportedresp. implementedRESULT_EXCEPTION 12 Exception occurred duringactionRESULT_TIMEOUT 13 Timeout wurde überschrittenRESULT_STILL_CONNECTED 14 PLC already connected (at afurther ::Connect() call)RESULT_RECONNECTTHREAD_STILL_ACTIVE 15 Reconnect Thread alreadyactiveRESULT_PLC_NOT_CONNECTED_SYMBOLS_LOADED16 Symbols available offline 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 13 of 17

PLCHandler Programming GuideAppendix C: Status reports of the PLCHandlerDefine Value DescriptionSTATE_TERMINATE -1 PLCHandler currently isterminating (Destructor)STATE_PLC_NOT_CONNECTED 0 PLC is not connected (init state)STATE_PLC_CONNECTED 1 PLC is connectedSTATE_NO_SYMBOLS 2 PLC is connected but symbolsare not yet loadedSTATE_SYMBOLS_LOADED 3 PLC is connected and symbolsare loadedSTATE_RUNNING 4 PLC is connected, symbols areloaded and all of them areverified. Now you can workcorrectly with the PLCHandlerobjectSTATE_DISCONNECT 5 Connection is just gettingterminatedSTATE_NO_CONFIGURATION 6 No valid configurationSTATE_PLC_NOT_CONNECTED_SYMBOLS_LOADED7 Symbols available offline 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 14 of 17

PLCHandler Programming GuideAppendix D: ActiveX-Control of the PLCHandler under WindowsThe PLCHandler also will be provided as ActiveX Control.Before first use the ActiveX-Control must be registered with the following command:regsvr32 plchandlerx.ocxThen the PLCHandlerX class can be used in a Visual-Basic, Delphi or C++ project.The following methods deviate from the methods in the PLCHandler:Connection establishment:Method: long ::ConnectByString(long lId, LPCTSTR pszConfigString, long lConfigLen,long StateChangedEvent, LPCTSTR pszLogFile);Parameter ulId specifies the index of the PLCHandler, if several instances are used.Parameter pszConfigString points to a string containing the content of the ini-file of theconfiguration. For information on the structure of this ini-file please see Fehler!Verweisquelle konnte nicht gefunden werden. lConfigLen specifies the length of theconfigurationstring.StateChangedEvent: Here optionally the handle of an event can be processed, via which theclient can be informed at each state change.pszLogFile is the name of a log file, where the PLCHandler optionally can record all importantactions.Method: long ::ConnectViaGateway(LPCTSTR pszGatewayIP, LPCTSTR pszPlcIP,LPCTSTR pszProtocol, LPCTSTR pszLogFile);This method can be used to establish a connection via TCPIP and the Gateway to a PLCunder Windows. For this purpose only the IP-address of the Gateway as well as the IPaddressof the PLC must be passed. Default setting is the Tcpip L2 Route Protocol („Tcp/Ip(Level 2 Route)“).Method: long ::ConnectViaArti(LPCTSTR pszPlcIP, LPCTSTR pszProtocol,LPCTSTR pszLogFile);Method:This method can be used to establish a connection via TCPIP and ARTI to a PLC. For thispurpose only the IP-address of the PLC must be passed. Default setting is Tcpip L2 RouteProtocol.long ::ConnectViaSimulation(LPCTSTR pszSdbFile, LPCTSTR pszLogFile);Via this method the connection to the simulation mode and to a SDB-file is established. Justthe name of the SDB-file must be specified. Thereby also a complete path can be defined.Browsing of variables:Method:Method:long ::GetNumberOfSymbols();Returns the number of available variables in the PLC.long ::GetSymbol(long lIndex, LPCTSTR pszSymbol, long lMaxLen);GetNumberOfSymbols() can be used to get the number of available variables.GetSymbol() can be used to get the name of the variable which is specified by the index.Synchronous Reading of variables:Method:long ::SyncReadVarFromPlc(LPCTSTR pszSymbol, long lAddressData, long lSize);lAddressData specifies the address, where the value of the variables is stored.pszSymbol specifies the name of one variable. 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 15 of 17

PLCHandler Programming GuideMethod:long :: SyncReadVarsFromPlc(LPCTSTR pszSymbols, long lAddressDataList, longlAddressSizeList, long lNumOfVars);lAddressData specifies the address, where the value of the variables is stored.pszSymbol specifies the names of several variables. LNumOfVars defines the number ofvariables.Synchronous Writing of variable values:Method: long SyncWriteVarToPlc(LPCTSTR pszSymbol, long lAddressData, long lSize);lAddressData specifies the address where the value of the variable to be written is stored.pszSymbol specifies the name of one variable.Method: long SyncWriteVarsToPlc(LPCTSTR pszSymbols, long lAddressDataList, longlAddressSizeList, long lNumOfVars);lAddressData specifies the address, where the value of the variables to be written is stored.pszSymbol specifies the names of several variables. LNumOfVars specifies the number ofvariables. 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 16 of 17

PLCHandler Programming GuideChange HistoryV1.0 27.02.04 Release VersionV1.1 15.10.04 VersionTcp/Ip (Level 4), Elau specialities added; some formatting and translationcorrectionsV1.2 08.02.05 PLCHandler methods updated and described (ActiveX-Control,App.D), Return andstatus values described (new App.B,C), ActiveX-Control (App.D) 3S - Smart Software Solutions GmbHPLCHandler Programmming Guide.doc Page 17 of 17