Ovation NetDDE Server User Guide
Section Title Page Summary of Changes
Section 1. Introduction
1-1. Overview...... 1-1 1-2. NetDDE Server Features...... 1-1 1-3. DDE Overview ...... 1-2 1-3.1. Application or Service Name...... 1-2 1-3.2. Topic ...... 1-2 1-3.3. Item ...... 1-3 1-3.4. Network DDE ...... 1-4 1-4. Limitations ...... 1-5
Section 2. Getting Started
2-1. Section Overview ...... 2-1 2-2. Requirements ...... 2-1 2-2.1. System ...... 2-1 2-2.2. Hardware ...... 2-1 2-2.3. Software ...... 2-2 2-2.4. License Server ...... 2-2 2-3. Setup ...... 2-4 2-3.1. Environment Variables Required for Setup...... 2-5 2-3.2. Linked Libraries...... 2-6 2-3.3. Files Installed During Setup...... 2-7 2-3.4. Registry Entries ...... 2-8 2-3.5. Security ...... 2-10 2-4. Setup Procedure ...... 2-10 2-5. Configuration ...... 2-11 2-5.1. Permissions ...... 2-11 2-6. Un-installation...... 2-11
Section 3. Using NetDDE
3-1. Section Overview ...... 3-1 3-2. Syntax for Calls...... 3-1
Glossary
Index
12/00 i U3-1033 (Rev 1) Westinghouse Process Control, Inc. Proprietary Class 2C Summary of Changes
This revision of “Ovation NetDDE Server User Guide” (U3-1033) reflects the following changes: • System topic has now been changed to wwwdde_system. • DataCreate and DataOriginate topics are removed from the WDPF NetDDE Server. • The machine name must appear when the point information (or Item) link is created on the WDPF NetDDE Server machine or accessed remotely in Excel or any other DDE supported application. • DDEShare.exe is no longer needed by the user. • wx_elmd.dll was replaced by wx_slmd.dll. • Registry entries now include the Log Viewer application. • Un-installation is now automatic (see Section 2). • All sections include various corrections and changes.
12/00 Changes-1 U3-1033 (Rev 1) Westinghouse Process Control, Inc. Proprietary Class 2C Section 1. Introduction
1-1. Overview
This manual describes the installation, configuration, and operation of the Ovation Network Dynamic Data Exchange (NetDDE) Server.
The Westinghouse Ovation NetDDE Server provides an open, standards-based interface to system process data. The continuous bi-directional transfer of real-time process data between an Ovation control system and Microsoft Windows applications is made possible using NetDDE technology.
NetDDE is a data interchange protocol supported by Microsoft — which extends the capability of Microsoft’s DDE technology across a computer network. Information exchange is accomplished by communications between the NetDDE Server and NetDDE clients located either locally or elsewhere on an authorized network. This enables users to develop spreadsheets, reports and custom applications for their desktop PCs, which will contain up-to-date information from their Ovation process control system.
Decision makers in the process industries rely on accurate and up-to-date information. Now end-users can review current conditions using the desktop applications they use everyday for their data analysis and reporting.
Widely used PC tools such as word processors, spreadsheets and database management systems, are NetDDE enabled to provide a standard way to automatically import data from external data sources. This combination of software tools results in the fast development of powerful end-user applications.
In addition, developers are able to build application solutions with their own familiar tools—minimizing the training requirements for MIS personnel.
1-2. NetDDE Server Features
The NetDDE Server provides the following features: • Supports the transfer of 1000 data items every second. • Provides bi-directional data transfer. • Communicates with several third-party office and process control applications. • Logs transmission and other errors.
12/00 1-1 U3-1033 (Rev 1) Westinghouse Process Control, Inc. Proprietary Class 2C 1-3. DDE Overview
1-3. DDE Overview
DDE, developed by Microsoft, is a communication protocol that uses shared memory to exchange information between two or more applications running simultaneously. Applications use DDE for one-time data transfers, control, and ongoing data exchanges.
Three pieces of information are needed in order to use DDE. These three pieces of information together uniquely identify a unit for data transfer between programs: • Application or Service name • Topic • Item
1-3.1. Application or Service Name
A program that uses DDE has an Application or Service name. For example, the Application name for the Microsoft Excel spreadsheet is ‘Excel’. The Ovation NetDDE Server’s application name is wwwdde. A client specifies the Application name to establish a conversation with the DDE server.
1-3.2. Topic
A Topic is a logical data context and is specific to a particular DDE server. The Ovation NetDDE Server supports these Topics: • DataGet — Retrieves information from the Ovation highway. • DataPut — Modifies point information (used to change the values of point record fields). • wwwdde_system — Provides administrative and status information about the wwwdde application.
U3-1033 (Rev 1) 1-2 12/00 Westinghouse Process Control, Inc. Proprietary Class 2C 1-3. DDE Overview
1-3.3. Item
An Item is a string that names the specific piece of information. For the Ovation NetDDE Server, the Item names are formed from the name of the Data Point Name, the particular field, and an optional bit position. Each of the parts of the Ovation NetDDE items are separated by a delimiter (a configurable character that defaults to an exclamation point).
Examples
‘LA222T03!HL’ — The Point Name is ‘LA222T03’ and the field is the HL or high limit field.
‘LP222T03!A2!3’ — The Point Name is ‘LP222T03’ and is assumed to be a Packed point type (LP); bit 3 is requested.
The System Topic( wwwdde_system) supports additional administration and status items. The supported items for wwwdde_system are: • Format (supported formats) - This will return ‘TEXT’ but the Wonderware DDE toolkit supports additional data formats. • Status - This will always return “Ready”. • SysItems - This returns the list of items supported by wwwdde_system. • ReturnMessage - This will always return “OK”. • Help - This returns a short message describing the Ovation NetDDE Server. • Topics - This will return the non-wwwdde_system names which are DataGet and DataPut. • TopicItemList - This returns the same list as the “Topics” item. DataGet and DataPut Topics support the “TopicItemList” item which is a list of in- use items for that particular topic.
12/00 1-3 U3-1033 (Rev 1) Westinghouse Process Control, Inc. Proprietary Class 2C 1-3. DDE Overview
1-3.4. Network DDE
DDE is able to run in a network environment by the addition of the Network DDE service. The addition of network capabilities has added some requirements for operation: • Instead of connecting directly to a DDE server by using the Application or Server Name, you connect to the Network DDE (NDDE) application on the target machine. • The ddeshare.exe utility associates DDE shares with specific Application and Topic names.
Example
For a machine named “FlyingFish”, the Network DDE Service Name is:
\\FlyingFish\NDDE$
The Topicname is the name of a DDE share. For the Ovation NetDDE Server, the DDE shares are:
DDE Share Name DDE Service DDE Topic
DataGet wwwdde DataGet DataPut wwwdde DataPut
U3-1033 (Rev 1) 1-4 12/00 Westinghouse Process Control, Inc. Proprietary Class 2C 1-4. Limitations
1-4. Limitations
This program has been tested with Windows NT 4.0 and Service Pack 5.
This program will not run on Windows 95 or Windows 98.
12/00 1-5 U3-1033 (Rev 1) Westinghouse Process Control, Inc. Proprietary Class 2C Section 2. Getting Started
2-1. Section Overview
This section describes the requirements, setup, and configuration needed to get started using the Ovation NetDDE Server.
2-2. Requirements
2-2.1. System
The minimum system requirements for an Ovation NetDDE Client are: • Windows NT Version 4.0 Operating System • NetDDE Client Application (for example, Microsoft Excel, Word, and Access) • Configured Ovation NetDDE Service
2-2.2. Hardware
The typical hardware requirements for an Ovation NetDDE Server are: • Minimum of 200 MHz Pentium II or compatible Personal Computer with available ISA slot • 64 MB of RAM • 2 GB Hard Disk (Program use is 5 MB) • Monitor, keyboard and mouse • FDDI/CDDI network card for connection to the Ovation network • Network Interface compatible with Windows NT 4.0 (for example, Ethernet - this may be a separate card)
12/00 2-1 U3-1033 (Rev 1) Westinghouse Process Control, Inc. Proprietary Class 2C 2-2. Requirements
2-2.3. Software
The minimum software requirements for an Ovation NetDDE Server are: • Windows NT Version 4.0 Operating System • Ovation Network software • Westinghouse License Manager Server must be installed (see Section 2-2.4) • Ovation NetDDE software
2-2.4. License Server
The NetDDE Server requires a license to operate. If the Westinghouse License Server is not running, the Ovation NetDDE Server will not allow any data operations.
The NetDDE Server interacts with a License Server to determine if proper administrative requirements have been met before it can operate. Multiple license servers can run on a heterogeneous network, but each License Server must contain all of the license file information.
The License Server must be running on the Ethernet network to which the Ovation NetDDE Server is attached. In order to ensure adequate operation of the Ovation NetDDE Server, the License Server should be run on the same machine. Thus, if the computer is running both the License Server and the Ovation NetDDE Server, this will ensure that a license can be acquired for an operating NetDDE Server.
The Westinghouse License Server has its own log file to indicate license operations. It also has a control applet to set parameters. Refer to the License Server help files and documentation for more information on the operation of the license server(s).
The license server is consulted every time a new distinct point is requested. Licenses are issued on the basis of distinct DDE Items.
Examples
LA222T03!AV (an analog value of a point) is a single DDE item.
LA222T03!HL (the high limit for the same point record) is a second DDE item.
U3-1033 (Rev 1) 2-2 12/00 Westinghouse Process Control, Inc. Proprietary Class 2C 2-2. Requirements
License Limits
All DDE Topics share the same license. Each item that is requested consumes one license. The license limits are determined when the software is purchased. The License Server consults a license feature file that has encrypted data about license limits and applicability.
The License Server allows for two types of license limits: • Soft limit. If more DDE Items are licensed than the value of the license limit, a drop fault is generated. However, the License Server will still grant licenses above the soft license limit. • Hard limit. An attempt to exceed the hard limit will also generate a drop fault. The License Server will NOT grant licenses in excess of the hard limit.
Procedure
Use the following procedure to configure licenses for a NetDDE Server:
1. On the License Server, run the program called wlmadmin.exe.
2. This program will display the following: • Location of the key directory (where the license files go). If this is the first time this is run, the directory will need to be input. Typically, it is in C:\Program Files\Westinghouse\wx_slm\keys. • Computer name. • Server Code (an ASCII string). 3. Provide the Server Code to Westinghouse.
Westinghouse will use the Server Code to produce the “Key code” (another ASCII string). Westinghouse will give the Key code to you.
4. Enter the Key code into the appropriate field on the wlmadmin.exe program.
5. Press OK.
You will get a confirmation message that the license file has been added to the key directory.
12/00 2-3 U3-1033 (Rev 1) Westinghouse Process Control, Inc. Proprietary Class 2C 2-3. Setup
2-3. Setup
The Ovation NetDDE server is a Windows NT service. The Windows NT service is installed by a Microsoft Windows setup.exe program (see Section 2-4 for procedure).
Note
Installation must be performed while logged in with Administrator privileges. This setup.exe program performs the following: • Installs the Ovation NetDDE program onto the computer that will be the server. • Sets the environment variables (described in Section 2-3.1). • Installs various dynamically linked libraries (see Section 2-3.2). • Sets the location of files (see Section 2-3.3). • Sets the values in the registry (see Section 2-3.4). • Assigns default security parameters to the NetDDE share items (see Section 2-3.5). • Sets the Advise period for DDE operations. • Produces a common program group to contain the various programs. • Installs the Ovation NetDDE service and configures it for automatic operation. • Installs configuration and help files.
U3-1033 (Rev 1) 2-4 12/00 Westinghouse Process Control, Inc. Proprietary Class 2C 2-3. Setup
2-3.1. Environment Variables Required for Setup
Two environment variables are required by the setup program. These variables are described in Table 2-1.
Table 2-1. Environment Variables
Variable Description WDPF_HOME Base location of Westinghouse software. This is traditionally under a directory called Ovation.
Example
SET WDPF_HOME=c:\Ovation WDPF_PDIR Location of the point directory.
Example
SET WDPF_PDIR=%WDPF_HOME%\shc\config\spd.config
Under the Windows NT system, environment variables are specified under this key:
\\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment
12/00 2-5 U3-1033 (Rev 1) Westinghouse Process Control, Inc. Proprietary Class 2C 2-3. Setup
2-3.2. Linked Libraries
The following libraries must be accessible to the setup program. Together these dynamic linked libraries constitute the Ovation library.
Table 2-2. Dynamic Linked Libraries (DLLs)
Library Description shclib.dll WESAPI library spdapi.dll Point Directory functions wwdlg32.dll Wonderware NetDDE toolkit functions wsock32.dll Winsock library kernel32.dll Windows library user32.dll Windows library gdi32.dll Windows library advapi32.dll Windows library NDdeApi32.dll NetDDE library wx_slmd.dll Client license functions msvcrt.dll Microsoft runtime library routines
U3-1033 (Rev 1) 2-6 12/00 Westinghouse Process Control, Inc. Proprietary Class 2C 2-3. Setup
2-3.3. Files Installed During Setup
The setup program will install most files under the “Program Files\Westinghouse\wwwdde” directory.
The installation directory can be modified during the setup program; however, Microsoft Windows standards recommend that the “Program Files\
Some configuration and data files are installed under the directory tree specified by the WDPF_HOME environment variable.
These files are installed during setup.
Table 2-3. Programs and Files Filename Path Description wwwdde.txt Program Files\Westinghouse\wwwdde\wwwdde Text file containing information about NetDDE wwwdde.exe Program Files\Westinghouse\wwwdde\program Ovation NetDDE Server (runs as a Windows NT service) Program Files\Westinghouse\wwwdde\system Dynamic linked library for wwdlg32.dll Wonderware related dialog boxes
wx_slmd.dll Dynamic linked library for license server
12/00 2-7 U3-1033 (Rev 1) Westinghouse Process Control, Inc. Proprietary Class 2C 2-3. Setup
2-3.4. Registry Entries
Due to requirements of the Wonderware DDE Toolkit software on which the Ovation NetDDE Server is based; some entries are required in the win.ini file. The entries in win.ini are based on equivalent entries in the registry. On program startup, the win.ini entries are overwritten with the equivalent values in the registry; therefore, changing win.ini directly will not change the program operation.
Under the Windows NT system, registry values are specified under this key:
\\HKEY_LOCAL_MACHINE\SOFTWARE\Westinghouse\WwwDdeService\1.0 where
1.0 is the current software version
These entries are described in Table 2-4.
Table 2-4. Registry Entries
Registry Entry Description Configuration File Not used, but required by Wonderware DDE Toolkit. Debug Flag to control operation of Windows NT service. When set to TRUE, window is visible. Default = FALSE Description Descriptive string to describe the Ovation NetDDE Server. Delimiter Character used to mark boundaries of parts of item name. For example, (point!field!bit_number) where an exclamation point (!) is used as the delimiter. Flag Flag to control whether DDE transactions are logged in the server window. Default = FALSE InstallDate Date when software was installed. LicenseData Proprietary license information. LogFile Filename for logging purposes. LogViewApp LogViewer application path and file name. Period Period in milliseconds for the server to update ADVISE items (minimum recommended period is 100 milliseconds). Default = 1000 milliseconds ScreenData Historical screen position, size and display parameters. TimeOut Amount of time allowed before new requested items are marked as unacknowledged.
U3-1033 (Rev 1) 2-8 12/00 Westinghouse Process Control, Inc. Proprietary Class 2C 2-3. Setup
Table 2-4. Registry Entries (Cont’d)
Registry Entry Description Title Title for window; also used by Service Control Manager. Version Version data (proprietary). WriteAlways Data is marked as changed each time it is read. Normally, the Ovation system does not attempt to call the DDE Toolkit to write the value when no data change has occurred. This improves efficiency. For system loading and debugging purposes, you can set the system to always write the value. Default = FALSE The following registry items are mapped to equivalent values in win.ini [WWWDDE] section. This is done to ensure that configuration operates correctly and consistently. ConfigurationFile Required by Wonderware DDE Toolkit (not used in this release). ConfigurationDirectory Required by Wonderware DDE Toolkit (not used in this release). WonderWareNetDDE Wonderware version of NetDDE installed. WriteRetryIndefinitely Controls whether write requests (DataPut) are tried indefinitely. Default = TRUE
12/00 2-9 U3-1033 (Rev 1) Westinghouse Process Control, Inc. Proprietary Class 2C 2-4. Setup Procedure
2-3.5. Security
Windows NT 4.0 security is certified to the C2 level. There are no security restrictions for local DDE access to the Ovation NetDDE server.
The Ovation NetDDE Server provides security to users by implementation of user privileges for desired operations. There are two access levels based on the equivalent DDE topics: • Read access • Change Attribute access The NetDDE program creates NetDDE shares to allow remote access to the data. These shares are created by the installation program with universal access allowed. The Administrator can use the ddeshare.exe program to modify the security access for the DDE topics. Access is controlled by user rights.
2-4. Setup Procedure
Use the following procedure to run the setup.exe program.
1. Insert the Ovation NetDDE CDROM containing the setup.exe program into the computer that will be the NetDDE Server.
2. Use Windows Explorer and navigate to the root directory of the installation CD. Double click on the SETUP.EXE file.
U3-1033 (Rev 1) 2-10 12/00 Westinghouse Process Control, Inc. Proprietary Class 2C 2-5. Configuration
2-5. Configuration
There is a control panel applet to change operating values of the system. You must have Administrator ‘Load Driver’ privileges to modify system parameters for the Ovation NetDDE Server. Users can view the control panel applet data but cannot change the information.
2-5.1. Permissions
The user must configure the NetDDE access permissions for the server using the ddeshare.exe program. This is normally done by a system administrator during program setup. A DDE share for each of the following topics is created by the setup with universal access: • DataGet allows data retrieval • DataPut allows change attributes The system administrator then modifies the access permissions of the created DDE shares with the ddeshare.exe program.
2-6. Un-installation
There is an un-installation program that removes Ovation NetDDE files from the system. To access this program, follow the steps below:
1. Access the Control Panel.
2. Select the Add/Remove icon.
3. Scroll to the Ovation NetDDe entry and double click on it.
The Ovation NetDDE files will be removed automatically.
12/00 2-11 U3-1033 (Rev 1) Westinghouse Process Control, Inc. Proprietary Class 2C Section 3. Using NetDDE
3-1. Section Overview
This section describes how to access data in DDE compliant programs and in user applications.
3-2. Syntax for Calls
Use the following syntax in calls:
PointName!Field[!Bit]
where
PointName = ASCII name of the point from the System Point Directory (SPD)
Field = Two letter identifier of the particular field
Bit number = Optional entry with the following values:
Long fields (4 bytes) = Value between 0 - 31 Short fields (2 bytes) = Value between 0 - 16 Char fields (1 byte) = Value between 0 - 7
Example
To read a point value into a Microsoft Excel Spreadsheet, use this syntax:
Local Access: = ‘\\
Remote Access: = ’\\
where:
NDDE$ = Name of the Network DDE application.
Note the single quotes around ‘\\
12/00 3-1 U3-1033 (Rev 1) Westinghouse Process Control, Inc. Proprietary Class 2C 3-2. Syntax for Calls
Note that the exclamation point is used in two different contexts in this example: • As a separator = The Excel spreadsheet defines the exclamation point to be the separator between the name of the topic (DataGet) and the name of the item (ai222t03!av). • As part of the item name = The item is enclosed in single quotes so that the imbedded exclamation point and other control characters do not confuse the Excel spreadsheet.
Word Basic Code Sample
The following Microsoft Word sample code is used to request a value:
' ' Inserts the value of an analog point high limit at the ' insertion point ' Sub Highlimit (ItemName$ as String) channel = DDEInitiate("\\DROP135\NDDE$", "DataGet") If (0 < channel) Then DdeReturn$ = DDERequest$(channel, ItemName$) dot = InStr (ItemName$, “!”) PointName$ = Left$ (ItemName$, dot - 1) FieldName$ = Right$ (ItemName$, len (ItemName$) - dot) Message$ = PointName$ + “ field “ + FieldName$ + “ is “ + lTrim$(DdeReturn$) DDETerminate channel Insert Message$ EndIf End Sub
Example: LA222T03 field HL is 54
U3-1033 (Rev 1) 3-2 12/00 Westinghouse Process Control, Inc. Proprietary Class 2C Index
A L access levels 2-10 libraries 2-6 Add/Remove icon 2-11 license limits 2-3 Application information 1-2 License Server 2-2 limitations 1-5 C Changes M Summary of 1-1 Microsoft 1-1 Client (Ovation NetDDE) 2-1 code sample 3-2 N configuration 2-11 NetDDE permissions 2-11 overview 1-1 syntax 3-1 D using 3-1 DataGet 1-2, 2-11 NetDDE Server 1-1 DataPut 1-2, 2-11 environment variables 2-5 DDE features 1-1 Application or Service name 1-2 getting started 2-1 Examples 1-3, 1-4 limitations 1-5 information needed for use 1-2 linked libraries 2-6 Item 1-3 overview 1-1 Network 1-4 requirements 2-1 overview 1-2 setup 2-4 Topic 1-2 Network DDE service 1-4 ddeshare.exe program 1-4, 2-10 O E Overview (of NetDDE Server) 1-1 environment variables 2-5 P F permissions 2-11 features of NetDDe Server 1-1 DataGet 2-11 files installed during setup 2-7 DataPut 2-11 ddeshare.exe program 2-11 G procedure for setup 2-10 getting started 2-1 R H registry entries 2-8 hard license limit 2-3 Configuration File 2-8 hardware requirements 2-1 ConfigurationDirectory 2-9 ConfigurationFile 2-9 I Debug 2-8 Item information 1-3 Delimiter 2-8 Description 2-8 K Flag 2-8 Key code 2-3 InstallDate 2-8
12/00 Index-1 U3-1033 (Rev 1) Westinghouse Process Control, Inc. Proprietary Class 2C Index
LicenseData 2-8 W LogFile 2-8 win.ini file 2-8 LogViewer Application 2-8 wlmadmin.exe program 2-3 Period 2-8 Wonderware 2-8 ScreenData 2-8 Word Basic code sample 3-2 TimeOut 2-8 wwwdde_system 1-2 Title 2-9 wwwdde_system topic 1-2 Version 2-9 WonderWareNetDDE 2-9 WriteAlways 2-9 WriteRetryIndefinitely 2-9 requirements 2-1 hardware 2-1 license 2-2 software 2-2 system 2-1 S security 2-10 Server Code 2-3 Service name information 1-2 setup 2-4 files installed 2-7 linked libraries 2-6 procedure 2-10 registry entries 2-8 security 2-10 variables required 2-5 setup.exe program 2-4, 2-10 soft license limit 2-3 software requirements 2-2 Summary of changes 1-1 Syntax for NetDDE 3-1 System requirements 2-1 T Topic information 1-2 DataGet 1-2 DataPut 1-2 wwwdde_system 1-2 U un-installation 2-11 add/remove icon 2-11 V variables 2-5
U3-1033 (Rev 1) Index-2 12/00 Westinghouse Process Control, Inc. Proprietary Class 2C