Data-Sharing API User Manual - Pro
Contents
1. 1 Table Ebudldicpt 2 GIOSSHEV eiesicaeiisstv eise siseste shsneossveanecbecenstcosencenens ieencevueneccunssntuacevenscadundesteonsavecsuesexcseepencice 4 CHAPTER1 OVERVIEW 1 1 MEME DID m 1 1 ji 1 2 CHAPTER2 SYSTEM DESIGN 2 1 2 1 Operating Environment cccsssssesssssrsscassissscsoncscesonaasssencesecssansscenssaasssacossassoansies 2 1 2 2 How to Use Data Sharing Functions eee ecce ee ee ee eee eerte eee e seen nae 2 1 CHAPTER3 FEATURE DEFINITIONS 3 1 3 1 Data Sharing Variables siccicsscsccsscsssescicssvestecssnseecevivccsesoavssstecsvenseessnecsieessacsensss 3 1 3 2 Server Client Connections cscsessicecssssnsvsscoveeecssesseevsesocecvsossvenssssenavsstonssssonsss 3 1 3 3 Communication PrOGCESS sccccsssssscasessssacsosnsiasscnsisasscssciussesesnassassonsasssascusssnescusinss 3 1 CHAPTER4 PERFORMANCE SPECIFICATIONS 1 O1 I I i CHAPTER5 STEPS USING DATA SHARING API CHAPTER6 SET UP PRO DESIGNER 6 1 6 1 Target DataSharing Property ccccssssssssssssscssscssssssssssssssscssssssssscssssenses 6 1 6 2 Target IPAddress and Port Properties cccscccssssssccsssssscccssssssccsessceees 6 1 6 3 Shared Variable Reference Format uscosssonsssssesnnssnnnsnonsssnnennnssnnnsnunsnsnne 6 1 6 4 Ac2. Pro Designer Runtime Pro Designer Runtime Pro Designer Runtime When you use data sharing m Target machines can share variables with other target machines m Target machines can share variables with Data Sharing API applications Data Sharing API User Manual 1 1 Chapter 1 Overview 1 2 Features m Dataexchange can occur between a Pro Designer Runtime target machine and a Data Sharing API application m Noadditional setup or configuration is required in Pro Designer to support data sharing which means that Noextra hardware such as a server is required or affected Nosetup of PLCs is required Variable data can be transferred at higher speeds and with lower overhead costs m Because the software does not affect other hardware the setup takes place in only one location 1 3 Data Sharing API User Manual 1 Operating Environment 2 How to Use Data Sharing Functions Chapter 2 System Design 2 1 Operating Environment Pro Designer Runtime uses the Data Sharing protocol to communicate with user applications on other target machines The protocol is designed to run within the Pro Designer Runtime communication system as an event driven protocol For data sharmg to occur the protocol enables other target machines to use the variables shared by a user application In addition to working within the Pro Designer Runtime system you can use the Data Sharing API to create an application that uses the pro
3. RegUpdateDataCallback Registers the function called when the Data Sharing APl application receives updated data Ends the Data Sharing API application ste m When defining the path of Project cfg for Na InitRuntimeAdapterEx name the complete path includ ing the filename m When using Pro Designer Runtime and the Data Sharing API application on the same machine the IP address passed to the ConnectToVars function should be INET 127 0 0 1 xxxx where xxxx is the Port number of the user application on the server target machine The 127 0 0 1 IP address enables access to Pro Designer Runtime without going through the network even though the target machine has a different IP address Data Sharing API User Manual 8 3 Chapter 8 Operation 8 4 8 4 Steps to Access Shared Data 8 4 1 Initialize the Data Sharing API m Use InitRuntimeAdapterEx to initialize the Data Sharing API and the project configu ration file Before making this call set up the system path required for loading the kernel configuration and error system Once the Data Sharing API is initialized use the RegConnectErrorInformCallback and RegUpdateDataCallback functions in the Data Sharing API application to register the functions that handles errors and vari able updates 8 4 2 Read Data m Use RegisterUpdateDataCallback to register the function that handles data updates with the Data Sharing API RegisterUpdateDataCallback is called whenever the
4. Data Sharing API receives new data from the server target machine ConnectToVars is asynchronous This function immediately returns an empty variable handle which is populated when the server target machine responds with the re quested variable data If an error has occurred such as the variable is not available the Data Sharing API notifies the application by calling the function registered with RegConnectErrorInformCallback 8 4 3 Write Data m The Data Sharing API application can write data to a shared variable at any time using the WriteDataTo function When data from a variable is no longer required you can release the connection to the variable in the Data Sharing API application by calling DisconnectFrom Vars Or to shutdown the Data Sharing API altogether call ShutdownRuntimeA dapter Data Sharing API User Manual Chapter 8 Operation 8 5 Examples Data Sharing API The following examples show how to use the Data Sharing API in specific situations Example 1 Data Sharing API Application Reads Data from Pro Designer Runtime Panel 1 Data Sharing API Application INT1 INT2 i INT3 Data Sharing Pro Designer x Data Sharing Protocol Runtime Panel 2 AP t 4 INT4 INT5 B InitRuntimeAdapterEx runtime directory configuration file m Called once per process initializes the Data Sharing API m Runtime directory is the root direct
5. the server provides the client with the requested variables Whenever changes occur to a server s data shared vari ables the values are updated on all the clients that use those variables B Client Server 2 Way Communication The client server two way communication process is a peer to peer relationship be tween two target machines Client Server Two Way Communication CLIENT SERVER CLIENT SERVER Target Machine A SS Target Machine B 1 Target Machine A requests data thin line from Target Machine B Target Machine B responds thick line by sharing the requested variable data with Target Machine A In this case Target Machine A is the client and Target Machine B is the server 2 In the second communication which can occur simultaneously with the first commu nication the roles are reversed Target Machine B is now the client and Target Machine A is the server Target Machine B requests data thin line from Target Machine A which responds by sharing the requested variable data with Target Machine B 39 Data Sharing API User Manual Functional Specifications B Multi Client 1 Way Communication Two types of clients can communicate with the server Target machines running a user application in Pro Designer Runtime Machines running a Data Sharing API application Multi Client One Way Communication SERVER P ro Designer R untim e TargetM achine Client writes variables to and reads variables from
6. PS Series Type P targetmachine targetmachine In the diagram above three target machines are simultanously sharing and accessing variables The significant aspect of this communication process is that the platforms of each target machine is different There is a PC AT PL Series target machine a PS Series Type G target machine and a PS Series Type P target machine Communication occurs seamlessly between the different platforms Data Sharing API User Manual 3 5 3 6 Data Sharing API User Manual Chapter 4 Performance Specifications A target machine can act as a Data Sharing server a client or both A machine running a Data Sharing API application can act only as a client Multiple clients can access the same variables Like any communication system for data sharing to run efficiently certain criteria must be met One of the criteria is limiting the number of shared variables The suggested maximum number of variables depends on e The number of variables that a client accesses from all other servers i e clients can access variables from more than one server The number of variables shared by the server The suggested maximum number of variables shared by each type of target machine is e PC AT PL Series 400 e PS Series TypeG 150 e PS Series TypeP 150 e GP 2000 Series 150 e Factory Gateway 75 B Suggested Maximum Number of Variables Shared by the Server In the following example the
7. applications m Onthetarget machine Pro Designer user applications can act as server client or both m Data Sharing API applications can act only as clients 3 2 Server Client Connections A connection can be defined as an access point from a target machine to either a client or a server In the client server communication process each target machine has a limited maximum number of connections e PC AT PL Series 32 e PS Series TypeG 16 e PS Series Type P 8 e GP 2000 Series 8 e Factory Gateway 4 3 3 Communication Process The diagram below illustrates the client server communication process whereby 1 The client requests variables from the server 2 The server responds by sharing the requested variables with the client Client Server Communication Client requests server s data SERVER E acc E CLIENT Target Machine Target Machine Server responds with data Data Sharing API User Manual 3 1 Functional Specifications In the following examples the direction of each arrow represents the flow of shared data from server to client during the communication process B Client Server 1 Way Communication During one way communication 1 The client requests data from the server thin line 2 The server responds by sharing the requested data thick line with the client Client Server One Way Communication SERVER Target Machine Target Machine Stes When a client initially connects to the server
8. server s data shared variables A target machine that shares its variables with client target machines An application file created in Pro Designer which runs on Pro Designer Runtime Data placeholders Data Sharing API User Manual 1 Operation 2 Features Chapter 1 Overview This chapter provides a general explanation of the role of the Data Sharing API The Data Sharing APl is the instruction set available to the user so they can create custom applications that can communicate with Pro Designer user applications When the user application is sharing its variables the Data Sharing API provides a gateway for the custom application to read and write to these variables Please read this Data Sharing API User Manual before using the Data Sharing API programming set 1 1 Operation Use the Data Sharing API to create an application that can access shared variables on target machines Variables must be shared in the user application for other machines to access the data This process known as data sharing enables target machines to share variables with other target machines and to share variables with Data Sharing API applications see diagram below Windows NT PS Series Type G Windows 2000 Data Sharing API application Windows XP Data Sharing API application Ethernet Network Windows NT Windows 2000 PS Series PS Series GP 2000 Windows XP Type G Type P Series Pro Designer Runtime
9. the server Clientwrites variables to and reads variables from the server CLIENT CLIENT P ro Designer Runtime Data S haring AP TargetM achine application The only difference between the multi client and client server one way communication processes is that during multi client one way communication the server target machine shares its variables with more than one client B Multi Target 2 Way Communication Process Multi target communication is a simultaneous two way communication process where the target machines can act as both server and client Each target machine can play the role of client and request data from the other target machines which play the role of servers In addition to playing the role of client each target machine can also fill the role of server and share its variables with other target machines In this communication process the target machines operate in a peer to peer relation ship Inthe following diagram the first three scenarios show the data sharing process be tween three target machines as a one way communication process between server and client Then in the the fourth scenario during the multi target two way communication process all target machines communicate simultaneously not only as servers but also as clients with the other client server target machines Data Sharing API User Manual 33 Functional Specifications 34 Multi Target Two Way Communication One way commu
10. Data Sharing API Client User Application Client Data Sharing API Data Sharing API Application Data Sharing Protocol Pro Designer Editor Pro Designer Runtime A target machine that can read from and write to the server s data shared variables A machine that runs a Data Sharing API application created using Data Sharing APIs A target machine that runs a user application created in Pro Designer A user application client can also act as a server The Data Sharing Application Programming Interface API provides functions that allow programmers to create applications that can access or use variables provided by a Server Target Machine An application created with Data Sharing APIs and that interacts with Pro Designer Runtime A Data Sharing API Application unlike a user application cannot act as a Server The language used by target machines clients and servers to communicate with each other Pro Designer the HMI editor software used to create user applications that run in Pro Designer Runtime The program that executes the user application and runs on a target machine Server Target Machine Server A target machine that shares its variables with client Target Machines Client Target Machine Server Target Machine User Application Variables target machines A platform that Pro Designer Runtime uses to execute the application file A target machine that can read and write to the
11. ONNECT STATUS ConnectionStatus Shows the operation or error status of the asynchronous connection UINTI6 NumOfHandles When the ConnectionStatus 1s an error this parameter defines the number of handles in AppHandleList UINT32 AppHandleList When the ConnectionStatus is an error this parameter defines the list of application handles with errors void Data Sharing API User Manual 8 13 Chapter 8 Operation Comments Use this function to create the function ErrorInformCallback that will handle error conditions when attempting to make variable connections The function must use the defined parameters and return a bool CONNECT_STATUS ConnectionStatus UINT16 NumOfHandles UINT32 AppHandleList The user defined function shows the status of connections RTA CONNECTING RTA CONNECTED RTA TAGNAME ERROR RTA TOO MANY TAGS ERROR RTA VERSION ERROR When establishing a connection or when a connection is cut RTA CONNECTING RTA CONNECTED the Data Sharing API populates the AppHandleList with pointers to the IP address and port number UNICODE text strings of the target machine that was con nected or disconnected When you try to access more than the number of connections the server target machine can support ConnectionStatus is RTA TOO MANY TAGS ERROR This error can also result when multiple client target machines access variables on the server When you try to access a variable that isn t available on the s
12. Pro face Human Machine Interface Data Sharing API User Manual Preface Thank you for purchasing the Pro Designer graphical editing software from Pro face Please note that the PS Series Type P target machines used in this manual s examples can be interchanged with the GP 2000 Series target machines Please read this manual thoroughly to understand the correct and safe use of this prod uct and its features lt Note gt Itis forbidden to copy the contents of this manual in whole or in part except for the user s personal use without the express permission of Digital Electornics Corporation of Japan The information provided in this manual is subject to change without notice 3 This manual has been written with care and attention to detail However should you find any errors or ommissions please contact Digital Electronics Corporation and inform us of your findings Please be aware that Digital Electronics Corporation shall not be held liable by the user for any damages losses or third party claims arising from the uses of this product All company manufacturer names used in this manual are the registered trademarks of those companies 2003 Digital Electronics Corporation Flex Network is a registered trademark of Digital Electronics Corooration Data Sharing API User Manual 1 Preface Table of Contents Preface
13. Use this function to create the function UpdateDataCallback that will handle variable updates from the Data Sharing API The function must use the defined parameters UINT32 AppHandle UINT16 DataByteLen void Data The function must return a bool value ShutdownRuntimeAdapter bool ShutdownRuntimeAdapter void bool Returns TRUE when the Data Sharing API is shut down successfully Data Sharing API User Manual 8 15 Data Sharing API User Manual Chapter 9 Sample Code Code samples for a working Data Sharing API application are located in installed directory pro face docs sample Files in the folder are as follows e Dsapi main cpp e Dsapi Dsapi dsw e Dsapi Dsapi dsp e Dsapi RuntimeAdapter h e Dsapi Debug e Dsapi Release Data Sharing API User Manual Sample code Project work space Project file Header file Stores the debug application Stores the production ready application 9 2 Data Sharing API User Manual
14. a script in the user application createProcess 62 Data Sharing API User Manual Chapter 1 Pro Designer Runtime Errors 2 Changing IP Address at Runtime 7 Pro Designer Runtime This chapter describes Pro Designer Runtime features related to shared variables 7 1 The following table lists error conditions Pro Designer Runtime Errors Condition Problem JEnor Confirmation Server target machine does notstart up No communication with server target machine i e unable to read from or write to data shared variables Data Sharing API User Manual Pro Designer Runtime does not startup on the server connects the server targetmachine and the PLC was disconnected during the startup of P ro Designer Runtime The cable that connects the server targetmachine and the PLC has been disconnected Pro Designer Runtime has shut down on the server disconnected An error message displays on the client target machine and only the display area of Value animations is visible When the data type for the Value animation is string then the display area and the defined string are visible APLC communication error message displays on the server target machine On the client target machine an error message displays initially but then the user application runs with variable values of 0 Floatand integer variables are 0 and discrete variables are displayed with the OFF label When a value animation displays a str
15. ars function You can write only to one variable at a time Call this function multiple times to write to more than one variable B DisconnectFromVars m This function breaks connections to the specified variables B ShutdownRuntimeAdapter m This function is called once per process to end the Data Sharing API when exiting the process Example 3 Data Sharing API Application Reads Writes Data to Pro Designer Runtime Panel 1 Data Sharing API Application INT1 INT2 INT3 x Data Sharing Bios ro Designer s i Protocol Data Sharing Runtime Panel 2 API INTA INT5 B InitRuntimeAdapterEx runtime directory configuration file m Called once per process initializes the Data Sharing API m Runtime directory is the root directory of Pro Designer Runtime e g installation directoryNpro facePro Runtime public m The configuration file is the Project cfg file used to configure the Data Sharing API Data Sharing API User Manual 8 7 Chapter 8 Operation B RegUpdateDataCallback UpdateDataCallback m Inthis example UpdateDataCallback is the function defined by the user to handle data updates from the Data Sharing API m Whenconnecting the variables this function is called once for each variable so their values are initialized B ConnectToVars m TheData Sharing API application connects to all the variables in the Pro Designer Runtime user application and
16. cess Group DataSharing Property ccccsscccsssscccssssssccssssccssssscsccssesees 6 2 CHAPTER 7 PRO DESIGNER RUNTIME 7 1 7 1 Pro Desiener Runtime Errors ccsicisssvessisssesisscesstsivesaesssaseesscguenascesssesnasiaecenssie 7 1 7 2 Changing IP Address at Runtime sesesssoscessoccssoccesseccsssccsssoccsssecesssesesoosseso 7 2 CHAPTER8 OPERATION 8 1 8 1 Data Sharing API Setup ssciccciessscsssccscssccssesssccsssessecseessiesseseconesoeconsesesancnssounses 8 1 8 1 1 Connecting Data Sharing API and Pro Designer Runtime 8 1 8 1 2 Data Sharing API and Protocol Setup u nn 8 1 8 2 Starting to use the Data Sharing APT 00sssc00ss000000002000000n00002n000n00000n0000 8 2 8 3 Data Sharmg APT scssissscciscsssessesssescossvescsvavsececoscseduansscesossvencsessessseseesscopenseccsers 8 3 N Data Sharing API User Manual Preface 8 4 Steps to Access Shared Data sissicsscsssccsssveccssonecssocssssosesssosesssosesssonsseccessocesses 8 4 8 4 1 Initialize the Data Sharing APL do etti ue 8 4 8 4 2 Read Data sie rere oie erret 8 4 8 43 Write Data s soiree ee repo oce et vae me ttes clics ren 8 4 8 5 Examples Data Sharing API einer 8 5 8 6 Connection from One Pro Designer Runtime to Another 8 9 8 7 APU Det ahs eR 8 10 CHAPTER9 SAMPLE CODE 9 1 Data Sharing API User Manual 3 Preface Glossary Client Target Machine Client
17. e 2 Data Sharing API Application Writes Data to Pro Designer Runtime Panel 1 Data Sharing API Application m INT2 JT INT3 Data Sharing Ban 2 Protocol ee Data Sharing TOTOCO a Runtime Panel 2 API INT4 INT5 B InitRuntimeAdapterEx runtime directory configuration file m Calledonce per process initializes the Data Sharing API m Runtime directory is the root directory of Pro Designer Runtime e g installation directoryNpro faceWPro Runtime public m The configuration file is the Project cfg file used to configure the Data Sharing API B ConnectToVars m TheData Sharing API application connects to all the variables in the Pro Designer Runtime user application and uses VAR READ ONLY ATTRIB RuntimeAdapterh m ConnectToVars returns immediately and when there is an error such as the defined variable name does not exist an error is passed to the user defined function ErrorInformCallback 8 6 Data Sharing API User Manual Chapter 8 Operation B RegConnectErrorInformCallback ErrorInformCallback m ErrorInformCallback a function defined in the Data Sharing application is called by the Data Sharing API when it could not connect to a Pro Designer variable B WriteDataToVar m The Data Sharing API application uses this function to write values to variables in Pro Designer Runtime Identify the variable by using the handle returned by the ConnectToV
18. e Data Sharing API application is trying to access UNIT16 NumOfTags Defines the number of variables to connect UNICHAR RemoteVariableNameList Lists the names of the variables to connect in the server target machine BYTE DataTypeList Lists the data types of the variables requested Integer Discrete Float or String BYTE DirAttribList Lists the variable read write control R W R W Data Sharing API User Manual 8 11 Chapter 8 Operation Return Comments Name Parameters Return Comments UINT32 AssignAppHandleList Lists the handles for each variable provided by the Data Sharing API application When a variable value is updated it uses the variable handle defined here CONNECTHANDLE RetAdapterHandleList Lists the handles for each variable returned by the Data Sharing API The corresponding variable handle is used when the Data Sharing API application makes a read or write request to the shared variable bool Uses the Data Sharing API to make connections to the defined list of variables in the server target machine A connection handle is returned for each variable that successfully connects Otherwise an invalid handle L is returned The caller is responsible for allocating and releasing the buffer for the connection handle list DisconnectFromVars bool DisconnectFromVars UINT16 NumOfHandles CONNECTHANDLE AppHandleList UINT16 NumOfHandles Defines the number of connection handles to
19. erver target machine ConnectionStatus is RT A TAGNAME ERROR When you try to access a server target machine that is using a different version of the Data Sharing protocol then ConnectionStatus is RTA VERSION ERROR When there is a connection error every heartbeat ConnectTo Vars attempts to connect to the server target machine and RTA CONNECTING is passed to this error function When the connection is successful with all the defined variables ConnectionStatus is RTA CONNECTED When the connection is successful with a portion of the variables then ConnectionStatus is RT A TAGNAME ERROR and AppHandleList contains the variable connections that failed When there is a problem with the connection ErrorInformCallback returns RTA CONNECTING when the connection is successful returns RT A CONNECTED 8 14 Data Sharing API User Manual Name Parameters Return Comments Name Parameters Return Comments Chapter 8 Operation RegUpdateDataCallback void RegUpdateDataCallback bool UINT32 AppHandle UINT16 DataByteLen void Data bool UpdateDataCallback User created method that s called by the Data Sharing API when it receives updated variable data from the server target machine Use the defined parameters and return type UINT32 AppHandle A valid variable handle from the list of handles UINT16 DataByteLen Total byte length of the data void Data Data that is updated by UpdateDataCallback void
20. es used in the Data Sharing API B Touse the Data Sharing API the user created application must load the RuntimeAdapter dll file and get a pointer to the process LoadLibrary 8 2 Data Sharing API User Manual Chapter 8 Operation 8 3 Data Sharing API Name Description h InitRuntime Adapter Initializes the Data Sharing APIs Must be called before any other Data Sharing API calls InitRuntime AdapterEx An extended Data Sharing API initialization function thatenables running a Data Sharing API application on the same platform as Pro Designer Runtime To ensure the same Projectcfg file and thus the same port number is not used for both the second parameter defines the location ofthe configuration file for the Data Sharing API application ConnectToVars Connects the Data Sharing API application s variable list with the server targetmachine s variable list A connection handle is returned for each variable thatis successfully connected Otherwise an invalid handle 1 is returned The Data Sharing API application is responsible for allocating and releasing the buffer for the listof handles DisconnectFromVars Releases all the variable connections from the list of handles WriteDataToVar Uses the defined connection to write a value to the shared variable Returns TRUE when the operation is successful RegConnectErrorinformCallback Registers the function called when a variable connection cannotbe established
21. ing variable only the display area is visible APLC communication error message displays on the server target machine On the client target machine an error message displays initially but processing continues with previously polled values On the client target machine an error message initially displays but processing continues with previously polled values On the client target machine an error message initially displays but processing continues with previously polled values 7 1 7 2 Changing IP Address at Runtime When using Data Sharing and you change the network address on a server target machine the client target machines cannot find the server anymore This error occurs even when you change the IP address using Pro Designer Runtime s configuration menu When you want to change the IP address of a server target machine make sure you also change the user application s IP address in the Pro Designer editor Define the new IP address in the Target properties and rebuild all the targets that refer to the user application s variables That means that user applications on all the client target machines must be built and downloaded again so they refer to the server s new IP address te NA Changing the IP address of one target machine may seem like an innocent change but if the target machine is acting as a server then the change has ramifications on multiple tar get machines and the user applications for all of
22. mbly7 Overflow Tank write itemp Data Sharing API User Manual 6 1 Chapter 6 Pro Designer Editor 6 4 Access Group DataSharing Property From the Navigator window s Project tab expand Target and I O Manager then click the AccessGroup node In the Inspector set the DataSharing property to define whether the variables assigned to the access group are always monitored Always or are monitored only when being used on the target machine Dynamic Inspector AccessGraup Name Access roup03 PollRate Dateshaing Dynamic Always Inspector Dynamic An access group is set to Dynamic by default so that updates will occur e when a variable is used in the current panel of either the target machine or a remote machine whena variable s KeepHistory property is set to True e when a variable is used in trend graphs whena variable alarm is enabled e when a variable is used in scripts Pro face recommends that you use the default setting Dynamic in the DataSharing property Always Pro face recommends that you set only the highest priority variables to Always Otherwise system performance will decline kom To run both Pro Designer Runtime and a Data Sharing NA API application on the same machine start Pro Designer Runtime before starting the Data Sharing API application To start the Data Sharing API application insert a short cut to Pro Designer Runtime in the Windows Startup menu then create
23. mments Initializes the Data Sharing API with the Pro Designer Runtime system This call must be made prior to any other calls in the Data Sharing API application After successfully initializing the API with the runtime sys tem returns TRUE 8 10 Data Sharing API User Manual Name Parameters Return Comments Name Parameters Chapter 8 Operation InitRuntimeAdapterEx bool InitRuntimeAdapter UNICHAR SystemPath UNICHAR ConfigFilename UNICHAR SystemPath Path of Pro Designer Runtime system NT or 2000 path is installation directorylpro face pro runtime public bin Win CE path is installa tion directory public bin WinCE UNICHAR ConfigFilename Entire path of configuration file including the filename bool Expands on InitRuntimeAdapter In addition to initializing the Data Sharing API with the Pro Designer Runtime system this method also identifies the configuration file This call must be made prior to any other calls in the Data Sharing API application After successfully initializing the API with the runtime system and pointing to the configuration file returns TRUE ConnectToVars bool InitRuntimeAdapter UNICHAR ServerAddr UINT16 NumOfVars UNICHAR VarNameList BYTE DataTypeList BYTE DirAtribList UINT32 AssignAppHandleList CONNECTHANDLES RetAdapterHandleList UNICHAR ServerAddr Identifies the IP address and Port number of the server target machine th
24. ng Protocol Network Protocol Protocol PLC X Protocol PLC X Protocol PLC X PLC Y All the necessary Java configuration and communication data files are generated by the Pro Designer editor so no extra setup is required by the user m InPro Designer Runtime 1 Variable A reads and writes data to and from PLC X m In Pro Designer Runtime 2 Variable B reads and writes data to and from PLC Y m Inaddition Variable A and Variable B share their data with the other runtime Data Sharing API User Manual 8 9 Chapter 8 Operation 8 7 API Details B Details of RuntimeAdapter h m Some ofthe data types used by the functions listed in this section are defined in RuntimeAdapter h see table below wsgeicar J poe unsignedshot oome unsigned nt D LL signed char W amp signed shor nn signed nt ar Write Only VAR WRITE ONLY ATTRIB Read Only VAR_READ_ONLY_ATTRIB Read Write VAR_READ_WRITE_ATTRIB Integer 0 VAR TYPE INT Float VAR TYPE FLOAT Sting VAR TYPE STRING Discrete VAR TYPE DISCRETE Name InitRuntimeAdapter bool InitRuntimeAdapter UNICHAR SystemPath Parameters UNICHAR SystemPath Path of Pro Designer Runtime system NT or 2000 path is installation directory pro face pro runtime public bin Win CE path is installa tion directory public bin WinCE Return bool Co
25. nication C lien SERVER CLIENT S erver between Target Machine A TargetM achine TargetM achine acting as server and Target Machines B and C both acting as clients CLIENTS erver TargetM achine One way communication CLIENT S erver Clien SERVER between Target Machine B TargetM achine TargetM achine acting as server and Target Machines A and C both acting as clients CLIENT S erver Target M achine One way communication CLIENT S erver CLIENT S erver between Target Machine C TargetM achine TargetM achine acting as server and Target Machines B and C both acting as clients Clien SERVER TargetM achine CLIENT CLIENT Two way communication SERVER SERVER between Target Machines A B TargetM achine TargetM achine and C each acting as both client CLIENT C SERVER TargetM achine and server Data Sharing API User Manual Functional Specifications B Multi Platform Multi Target 2 Way Communication The multi platform multi target two way communication process refers to two way communication between multiple types of target machines Multi Platform Multi Target Two Way Communication CLIENT SERVER P ro Designer Runtime PC AT PL Series targetmachine Clientserver targetmachines write variables tp and read variables from other client server target machines CLIENT SERVER qt CLIENT SERVER P ro Designer Runtime P ro Designer Runtime PS Series Type G
26. ory of Pro Designer Runtime e g installation directory pro face Pro Runtime public m The configuration file is the Project cfg file used to configure the Data Sharing API B RegUpdateDataCallback UpdateDataCallback m Inthisexample UpdateDataCallback is the function defined by the user to handle data updates from the Data Sharing API m When connecting this function is called once for each variable so its value is initial ized B ConnectToVars m The Data Sharing API application connects to all the variables in the Pro Designer Runtime user application and uses VAR READ ONLY ATTRIB RuntimeAdapter h m When the connection is established UpdateDataCallback is called once for each variable to initialize the variable values in the connection list m ConnectToVars returns immediately and when there is an error such as the defined variable name does not exist an error is passed to the user defined function ErrorInformCallback Data Sharing API User Manual 8 5 Chapter 8 Operation B RegConnectErrorInformCallback ErrorInformCallback m ErrorInformCallback a function defined in the Data Sharing API application is called by the Data Sharing API when it could not connect to a Pro Designer variable B DisconnectFromVars m This function breaks connections to the specified variables B ShutdownRuntimeAdapter m This function is called once per process to end the Data Sharing API when exiting the process Exampl
27. perty Sharing property to TRUE 42 Suggested ee Select he variables to share Maximum Number of p and assign them to the same Shared Variables and a aS Chapter 6 Setup Pro Designer Build the user application Bight clei a and click Build To run the Data Sharing API application on Windows NT Setup the Windows 8 1 Data Sharing API 2000 or XP set the system system path Setup path of the Data Sharing API Use the Data Sharing API to 8 2 Starting to use the create an application in C or SEE pala anng A Data Sharing API and C and use the shared user application 8 3 Data Sharing API application variables Insertthe Data Sharing API Set the system path to the application in the appropriate folder Data Sharing API or put the Windows NT 2000 and XP Data Sharing API application pro face Pro R untime public Bin file in the appropriate folder Windows CE pro face Pro Runtime public Bin WinCE Download and start the user StartPro Designer R wire application in Pro Designer Runtime m 1 1 Pro Designer Run the Data Sharing API application 3 Runtime Errors Data sharing begins Data Sharing API User Manual 5 1 Data Sharing API User Manual 1 Target DataSharing Property 3 Shared Variable Reference 2 Target IPAddress and Port Format Properties 4 Access Group DataSharing Chapter eons 6 Set up Pro Designer 6 1 Target DataSharing P
28. remove CONNECTHANDLE AdapterHandleList The handle list returned when ConnectToVars is used to establish variable connections bool Removes all the variable connections in this list of handles Data Sharing API User Manual Name Parameters Return Comments Name Parameters Return Chapter 8 Operation WriteDataToVar bool WriteDataToVar CONNECTHANDLE AdapterHandle UINT16 DataLen void Data CONNECTHANDLE AdapterHandle Defines the variable data for the write operation by passing the corre sponding connection handle UINT16 DataLen Defines the length of the data in bytes Discretes are 1 byte integers and floats are 4 bytes and strings can be any number of bytes void Data The actual data written to the variable on the server target machine bool Uses the variable connection handle to write data to a shared variable on the server target machine After successfully writing the data to the variable returns TRUE otherwise returns FALSE Writing a value that is the same as the one currently set to a variable will not cause a data change operation in Pro Designer Runtime RegConnectErrorInformCallback void RegConnectErrorInformCallback bool CONNECT STATUS ConnectionStatus UINT16 NumOfHandles UINT32 AppHandleList bool ErrorInformCallback User created method that s called when there is an error Use the defined parameters and return type for ErrorInformCallback C
29. roperty To enable data sharing on a target machine in the Pro Designer editor select the Target node and in the Inspector set the DataSharing property to TRUE The DataSharing property changes operations as follows _____ PataSharing TRUE PataSharing FALSE Functionality Variables in the user application Variables in the user application can are notshared be shared with other T argets in the Pro Designer project and with Data Sharing API applications Accessing Can read to write from variables in Can read to write from variables in variables in other other target machines other target machines user applications 6 2 Target IPAddress and Port Properties The IPAddress property is available when you click the Target node Enter the IP address of the target machine where this user application will be running The defined IP address is used by data sharing to enable other target machines to access this target s variables When the Target node s DataSharing property is TRUE the Port property becomes available Port defines the communication port number used by the Data Sharing protocol If you don t define a port number 6000 is used 6 3 Shared Variable Reference Format To reference a shared variable enter the target and variable name Target Name Variable Name For example Assembly7 OverflowTank refers to the variable OverflowTank in the target Assembly7 Script Example intitemp itemp 123 Asse
30. t 400 variables SERVER PC AT PL Series 400 variables 150 variables 150 variables CLIENT CLIENT CLIENT PC AT PL Series PS Series Type G PS Series T ype P variables accessed bythe PC AT only 150 variables accessed bythe PC AT and the PS G 100 variables accessed bythe PC AT and the PS P 100 variables accessed byall three clients 50 400 total number of variables shared by the server In this example 400 is the total number of variables that the server shares with the clients However because each client accesses each variable separately the server s processing load is the same as if 700 variables are shared The number of variables that any one type of target machine can share is limited not by design but by the speed required to process variables The suggested maximum number of variables shared between two target machines depends on The type of target machines The number of variables shared by the server e The number of variables that a client is accessing from other servers Processing load on clients and servers Data Sharing API User Manual Chapter 5 Steps Using Data Sharing API Follow the steps in the flowchart to use the Data Sharing API and access the variables shared by a Pro Designer Runtime user application Pro Designer Data Sharing API Application Setup data sharing in the user In Pro Designer sebol the 6 1 Target Data application Target node and set its Data Sharing Pro
31. tab scroll down the System Variables listbox and click the Path variable 3 Add the path installed directory pro face Pro Runtime public bin to the Value box and click Set This path is also used as a parameter when initializing the Data Sharing API 1 e InitRuntimeAdapter InitRuntimeAdapterEx Windows CE Place the application file exe created with the Data Sharing API into installed directorylpublic bin WinCE B Project Configuration The second parameter used by the InitRuntimeAdapterEx function defines the project configuration The project configuration is a text file which among other things identifies the port number used by the Data Sharing protocol To create the configuration file for the Data Sharing API application copy the Project cfg installed directory Pro face Docs Cfg Project cfg into the directory of the Data Sharing API application Define two parameters when you start InitRuntimeAdapterEx In the first parameter define the complete path of Pro Designer Runtime installed directory pro face Pro Runtime public bin In the second parameter define the complete path of the project configuration file 8 2 Starting to use the Data Sharing API The Data Sharing API is provided as a Windows dll file The following is an introduction to use of the API 8 7 API Details B RuntimeAdapter h is located in installed directory Pro face Docs Include This header file lists all the data typ
32. them must be rebuilt and downloaded Data Sharing API User Manual 1 Data Sharing API Setup 4 Steps to Access Shared Data 2 Starting to use the Data 5 Examples Data Sharing API Sharing API 6 Connections between Pro C h a pte r 3 Data Sharing API Designer Runtime 7 API Details 8 Operation 8 1 Data Sharing API Setup 8 1 1 Connecting Data Sharing API and Pro Designer Runtime Using the the Data Sharing API you can create applications in C or C that access variable or PLC register values in Pro Designer Runtime The Data Sharing API dll files are required to run the application PC Data Sharing API Application Pro Designer Runtime Variable B Data Sharing API dil I Network I Data Sharing F Data Sharing nz CS 8 1 2 Data Sharing API and Protocol Setup The following settings are required to use the Data Sharing API and Data Sharing protocol from an application B System Path Windows NT Windows 2000 or Windows XP When using the Data Sharing API setting up the system path is required so access is available to all sub directories in Pro Designer Runtime The system path is used to load the kernel configuration and error system Data Sharing API User Manual 8 1 Chapter 8 Operation To set up the system path Windows NT Windows 2000 or Windows XP 1 Open the Windows Control Panel and click the System icon 2 Inthe System Properties dialog box click the Environment
33. tocol to access the shared vari ables on another target machine The following table lists the target machines that support Data Sharing or the Data Sharing API arget Machine Data Sharing Data Sharing API C AT Windows NT 2000 XP S Series Type G Windows CE X S Series T ype P P 2000 Series on GE EEG SEHEN 2 2 How to Use Data Sharing Functions You can use data sharing in the following ways m Connect to Pro Designer Runtime from a Data Sharing API application An application created using the Data Sharing API can access variables shared by a Pro Designer Runtime user application m Connectto Pro Designer Runtime from Pro Designer Runtime A Pro Designer Runtime user application can access variables shared by another Pro Designer Runtime user application Chapter 8 Operation Data Sharing API User Manual 2 1 Data Sharing API User Manual 1 Data Shared Variables 2 Server Client Connections Chapter 3 Communication Process 3 Feature Definitions 3 1 Data Sharing Variables m A server is any target machine that shares variables with other target machines On the server whenever the value of a shared variable changes the updated value is sent to all the clients that use that variable m client can both read from and write to the a server s shared variables and include Target machines that run Pro Designer Runtime Machines such as PCs that run Data Sharing API
34. uses VAR READ ONLY ATTRIB RuntimeAdapter h m Whenthe connection is established UpdateDataCallback is called once for each variable to initialize the variable values in the connection list m ConnectToVars returns immediately and when there is an error such as the defined variable name does not exist an error is passed to the user defined function ErrorInformCallback B RegConnectErrorInformCallback ErrorInformCallback m ErrorInformCallback is the user created function called by the Data Sharing API when a variable is not found on the Pro Designer Runtime B WriteDataToVar m The Data Sharing API application calls this function to write values to a variable in the Pro Designer Runtime user application Identify the variable by using the handle returned by the ConnectToVars function You can write only to one variable at a time Call this function multiple times to write more than one variable B DisconnectFromVars m This function breaks connections to the specified variables B ShutdownRuntimeAdapter m This function is called once per process to end the Data Sharing API when exiting the process Data Sharing API User Manual Chapter 8 Operation 8 6 Connection from One Pro Designer Runtime to Another The following diagram shows how Pro Designer Runtime connects to another instance of Pro Designer Runtime Pro Designer Runtime 1 Pro Designer Runtime 2 De Var B i Link ource B I Data Sharing Data Shari
35. variables accessed by each client are not accessed by any of the other clients Of its 400 variables the server shares e 175 with the PC AT client e 125 with the PS Series Type G client e 100 with the PS Series Type P client 400 variables ee EEE 175 1 125 1 100 SERVER PC AT PL Series 175 variables 125 variables 100 variables Suggested Max 400 variables M ax 150 variables Max 150 variables PT I CLIENT CLIENT CLIENT PC AT PL Series PS Series T ype G PS Series T ype P Data Sharing API User Manual 4 1 4 2 B Suggested Maximum Number of Variables Accessible by Each Client The following diagram is an example of the suggested maximum number of variables that each client can access from the server 3 2 Communication Process In this example each client accesses the suggested maximum number of variables from the same server Some or all of the variables accessed by each client are also being accessed by the other two clients The PC AT PL Series client accesses 400 variables 250 of which are accessed by the other two clients The PS Series Type G client accesses 150 variables all of which are accessed by the PC AT PL Series client and 50 of which are accessed by the PS Series Type P client The PS Series Type P client accesses 150 variables all of which are accessed by the PC AT PL Series client and 50 of which are accessed by the PS Series Type G clien
Download Pdf Manuals
Related Search