The OPC Gateway is a WindowsNT service that allows CORBA access to an OPC server. The gateway consists of several parts: the Remote Device Access (RDA) system using CORBA, the server framework (SFW) for adapter-independent work and the OPC adapter for the actual access to the OPC server.
The OPC Gateway is part of the Controls Middleware, described here:
http://proj-cmw.web.cern.ch/proj-cmw/documents/whitepaper.pdf
It can be seen as a green box at the bottom of the the architecture overview figure:
http://proj-cmw.web.cern.ch/proj-cmw/drawings/architecture.pdf
All parts of the OPC Gateway are written in C++. Consult the documentation for the RDA and the SFW for detailed information about how they work. For technical information about the OPC Adapter, see the OPC Adapter Technical Documentation. For reference documentation for the OPC Adapter, generated from source files comments, see the OPC Adapter Reference Manual HTML/RTF.
All necessary files are located in the \bin\ directory of the OPC Gateway distribution, together with a file called INSTALLATION.txt. This file contains some very brief information on how the OPC Gateway is normally installed.
It is actually only a matter of copying the OPC Gateway folder, copying two DLLs to the WINNT\SYSTEM32 folder, running OPCGateway.exe -install to install the gateway as an NT service, and then net start OPCGateway to start it. Batch files for these operations are available.
This documentation contains more verbose information.
The OPC Gateway is implemented as an WindowsNT service - meaning that it runs on WindowsNT 4.0 as well as Windows2000. The service can be installed or uninstalled (note that installation of services requires local administrator privileges on WindowsNT) on the command-line as follows:
Installation:
X:\GatewayPath> opcgateway.exe -install OPC Gateway installed.
Uninstallation:
X:\GatewayPath> opcgateway.exe -remove OPC Gateway removed.
The executable requires MSVCP60.DLL and MSVCRT.DLL (v6+ of both) because it uses the Standard C++ iostreams. Unfortunately, these DLLs are not available on a pure WindowsNT installation, and must therefore be distributed with the executable or retrieved from a computer which has them - they are distributed with many programs: MSVC++ v6 or later, all Office 2000 programs, Windows2000/WinME, and more. They should be placed in the SYSTEM32 folder of the machine. (If these files are in use, use a command-line prompt to rename them and then copy the updated versions there. Note that it is not possible to rename them using the Explorer GUI.)
When the service is installed, it can be run as a service or from the console, the latter with the command-line option -debug. This might be useful for troubleshooting as it prints messages at startup about which config file and settings are active, and where log output goes.
Note that the same executable acts as service installer/uninstaller and as the actual OPC Gateway.
After the service has been installed, it is available under Control Panel->Services with the name "OPC Gateway". It is by default set to be started manually, but this can be changed with the Services application. Bear in mind that the OPC server must be ready to start or already started when the OPC Gateway is started.
The OPC Gateway can also be started or stopped from the command-line using the net start/stop command:
Start service:
X:\Anywhere> net start opcgateway The OPC Gateway service is starting. The OPC Gateway service was started successfully.
or, for debug/command-line mode:
X:\GatewayPath> opcgateway.exe -debug -config test.cfg Debugging OPC Gateway. Ctrl-C is mapped to 'Stop service'. The config file name option is: (...)
Stop service:
X:\Anywhere> net stop opcgateway The OPC Gateway service is stopping. The OPC Gateway service was stopped successfully.
When started, it will put an entry in the Application system log, reachable via Program->Administrative Tools->Event Viewer, Log->Application. The entry will inform about a successful as well as failed startup. Make sure that the entry of a successful start is there before you proceed. It is also possible to use the Gateway Monitor (described below) to check that the service is running and functioning correctly.
Gateway Monitor in System Tray
Together with the OPC Gateway comes a small separate program that communicates with the Gateway via a local named pipe. It places an icon in the Windows System Tray (lower right-hand corner) which indicates the status of the gateway. Simply run this program, GatewayMonitor.exe, and a small "O" will appear in the system tray. It can be filled with four different colours:
This program can for example be placed in the Startup folder, so that it starts automatically when a user logs in.
Changing log level with the Gateway Monitor
By right-clicking the icon, a small menu will pop up and allow the setting of verbose or brief logging from the OPC Gateway. This can be handy if a running OPC Gateway needs to be examined more closely, causing a temporary need for more verbose logging.
Also included is a small program (a couple of lines of C++) that allows sending commands via the pipe to the OPC Gateway service. This program is self-explanatory.
The OPC Gateway is configured in two ways:
The config file contains settings for log file output, Corba Name Server and similar things. The OPC Gateway contains defaults for these settings, but for clarity they should preferably be specified explicitly.
The default name for the config file is cmw.cfg, located in the same directory as the OPC Gateway executable.
It is possible to use another config file than the default one by specifying the command-line option "-config filename" to the service. Normally also "-debug" would be specified.
Also, the RDA will use the settings in this config file. It will retrieve settings for its threading model and many other things from there. See the ORBacus manual for information about concurrency models, and the RDA documentation for the recommended choice. Normally, a standard cmw.cfg file should be available from the Controls Middleware team.
Config file structure and contents
The config file structure is that of ORBacus config files, which in turn mimics Java property files. It is the ORBacus functions that are used to read the file.
The format of the file is lines of the form "key=value". A '#' first on the line starts a line comment. Values start after the '=' and end with the line (including whitespace, even at the end).
An example of a config file, which defines all available settings for the OPC Gateway and a couple of ORB settings, follows:
# OPC Gateway config file. Settings for other CMW systems are # normally also present. # Name of logfile. Specify full path - current dir when started as # a service is %WINNT%\SYSTEM32. # Default is: opc_gateway_logfile.txt, same dir as executable cmw.opcgw.logfile=X:\AdapterPath\debug_logfile.txt # Disable (for debugging) the seperate thread for log writes # Default is enabled: "yes" cmw.opcgw.log_writer_thread=no # Disable (for debugging) the bounding of log file size # Default is enabled: "yes" cmw.opcgw.bounded_log_file=no # Set the name of the Corba object registered with the Naming service # Default is "RDA-TEST". cmw.opcgw.rda_server_name=RDA-TEST # Set log level threshold at startup to 4: Quite verbose # Default is 5, almost no threshold. cmw.opcgw.log_level_startup=4 # Set log level threshold after 1 minute to 9: Brief # Default is 10, normal log threshold level. cmw.opcgw.log_level=9 # Disable all set/write operations for the OPC Gateway, so that the # gateway will only act as an observer. # Default is not disabled: "no" cmw.opcgw.disable_set_operations=yes # Set RDA log level to 20: Very verbose (Note: inverse meaning: low is brief) # Note: This is the only cmw.rda setting that affects the temp RDA # Default is 0, almost no logging. cmw.rda.traceLevel=20 # Set the Corba Name Server, like below or with IOR # Example: ooc.orb.service.NameService=IOR:00f21[...]6500 # Default is corbaloc::pcslux8:5020/NameService. ooc.orb.service.NameService=corbaloc::pcslux8:5020/NameService # Set OA and ORB to be 'threaded' (does not require thread-safe RDA) # See ORBacus manual, 17.3.1 for information about this concurrency model ooc.orb.conc_model=threaded ooc.orb.oa.conc_model=threaded
And use of this config file:
X:\GatewayPath> opcgateway.exe -debug -config X:\test_config.cfg Debugging OPC Gateway. Ctrl-C is mapped to 'Stop service'. The config file name option is: -ORBconfig X:\test_config.cfg (...)
If you have problems with privileges to install the OPC Gateway service, either log in as Administrator or add local Administrator privileges to the current user. The latter is done, as Administrator, by adding the user to the Administrator group using the User Manager in the Administrative Tools group in the Start menu.
Also note that it is possible to specify as which user the service should run, by running the Services application in Control Panel. By default the service is set to run as the System Account, just like almost all other services.
The OPC Gateway produces a log file. The log file contains a bounded number of messages, and only one old file is kept. This guarantees that it will not fill up the disk with log output if left unattended.
The most recent log file entry is, with default settings, at the end of the file opc_gateway_logfile.txt in the same directory as the OPC Gateway executable.
Use the Gateway Monitor to determine if the OPC Gateway service is running correctly, and if not, consult the log file for more details. It could be helpful to use the Gateway Monitor to set verbose logging first, if there is problems with an OPC Gateway in operation.
To locate log messages in the source code, first check which class has emitted the log message. RDA log messages begin with "RDA: ", while log messages coming from the OPC Adapter begin with "[classname]: ".
If the Gateway service stops responding due to a serious error (which should normally not happen, but could be a common situation during development), it will not be possible to kill the process with the NT Task Manager. Instead, use pslist and pskill from the Pstools package (see http://www.sysinternals.com), which does not have this unnecessary limitation.
OPC Gateway fails when stopping
Should the OPC Gateway be modified in a way so that it does not stop without errors - especially when stopped from Services in the Control Panel, the reason might be that the shutdown procedure is taking too long time, and the Services application times out. Check the service code for information about this, especially the call to ReportStatusToSCMgr. If your new, modified, shutdown procedure takes several seconds, you might need to adjust this.
A likely reason for failed subscriptions is that the opcproxy.dll DLL file has been overwritten with an old DLL. Subscription is done using the OPC Data Access 2.0 method (which the OPC server needs to support), and if the DLL only supports Data Access 1.0, it will not be possible to start subscriptions. Check the version of the opcproxy.dll file on your computer, and compare it with the version in \src\OPC_Foundation\OPCProxy.
If OPC items can't be added to the server, check the log file for errors. It is possible that if they exist, their DataConverter object is requesting a Variant type that the OPC server is not able to supply. For example, a date can't be retrieved as a byte.
Complete source code for the OPC Gateway is available in the distribution, together with source code for the version of the RDA and the SFW used with the adapter.
It should compile correctly with MSVC++ v6.0 if it is in an unchanged state and ORBacus, JTC and OPC include paths has been added to the compiler environment.
The information below is intended to help the programmer to set up a similar project, and to explain how the OPC Gateway is built. Please note that it is a somewhat complex procedure to change and recompile the entire application, if one is not acquainted to the OPC Gateway and MSVC++. Hints about where certain compiler settings are located via the menus are provided in some, but not all, places below.
The project should compile without errors if the same project files are used. However, this section describes what settings need to be used if re-creating the projects from scratch. Note the path settings mentioned under "Common settings" as this is set for each MSVC++ environment and need to be applied to yours as well, if you haven't already done so.
All parts of the OPC Gateway should be compiled to:
CMWFW_WINDOWSNT preprocessor directive (see below)Make.rules.mak file of ORBacus: setting WITH_JTC=yes and JTC_DIR to the appropriate directory.
The paths for ORBacus, JTC and Naming include/library files should be added to the default search paths in MSVC++ (Tools, Options, Directories):
Include files:
(path)\ob\include, (path)\jtc\include, (path)\naming\include
Library files:
(path)\ob\lib, (path)\jtc\lib, (path)\naming\lib
It is also recommended to specify the path of the OPC include files here:
(path)\OPCGateway_v1_0\src\OPC_Foundation
The suggested way is to create one Visual Studio workspace, with four projects: OPC, RDA, SFW and GatewayService (for service and startup code). This is the way the sources are organized in the distribution.
Remember to specify Additional Include Directories (Project, Settings, C/C++, Preprocessor) for each project so that it can reach the include files it needs from the others. A dependency graph is presented later.
opcproxy.dll. (The proxy DLL for OPC Data Access 2.0 is v2.0.0.1, size 76 KB.)
The OPC files are included by the OPC Adapter.
#ifdef CMWFW_WINDOWSNT preprocessor directives. This symbol should be defined when they are compiled under WindowsNT. It is defined under project settings (Project, Settings, C/C++, Preprocessor, Preprocessor definitions) in the MSVC++ project files. Make sure that the RDA header files can be reached by both the SFW and the OPC Adapter, and that the SFW header files can be reached by the OPC Adapter.
For the RDA, the compiler parameter /J should be in use (Project, Settings, C/C++, Project Options), to make unsigned chars the default chars.
The RDA is compiled to a Win32 static library. (Project Type when created)
The SFW is compiled to a Win32 static library. (Project Type when created)
ORBacus and JTC are compiled by the batch files in their distribution into Win32 static libraries called ob.lib and jtc.lib.
The COSNaming package of ORBacus is compiled to a seperate static library called cosnaming.lib.
_WIN32_DCOM, which is Windows way of making sure that we are aware that we use COM or DCOM functionality. (Project, Settings, C/C++, Preprocessor, Preprocessor definitions)
The OPC Adapter is compiled to a Win32 static library. (Project Type when created)
main() function in the SFW.
This figure describes the major dependencies for include files of the various parts. Implicit transitive dependencies have been excluded.
Dependencies between RDA, SFW, OPC Adapter, ORBacus and JTC.
When compiling the service body, several libraries must be included (Project, Settings, Link) to avoid unresolved externals.
Specifically, the following should be linked in, apart from the standard libraries:
To try out the OPC Gateway, the recommended way is to use the RDA test programs by Nikolai Trofimov (SyncGetTest, MonTest, ...) to access an OPC server.
The documentation consists of the OPC Gateway Documentation (this file: general description, how to use, how to compile, how to troubleshoot), the OPC Adapter Technical Documentation (how it works, how to modify) and the OPC Adapter Reference Manual - HTML/RTF (generated from JavaDoc-like comments, for reference use on screen/on paper).
The documentation is written in a text file (for the first two parts) or contained within the source code as comments (for the OPC Adapter Reference Manual). Doxygen is used to generate RTF/TeX/HTML/man output.
All parts of the documentation can be regenerated with Doxygen, and it is later described how this is done for the HTML/RTF Reference documentation extracted from the source files. This document and the OPC Adapter Technical Documentation are regenerated in a similar way.
A quick way to regenerate all documentation is to run the batch file regenerate_doc.cmd in the \doc folder. This will update everything except the PDF versions, which must be generated with the help of a LaTeX package, for example MiKTeX 2.0 which is included in \tools\Extras.
How to read the HTML/RTF documentation
There is HTML/RTF documentation available, generated from JavaDoc-like comments within the source files of the OPC Adapter.
It is recommended that the RTF file is used for printing and off-line reading, and that the HTML files, starting from index.html, are used for on-line browsing.
The HTML and RTF documentation contain exactly the same information.
How to re-generate the HTML/RTF documentation
The HTML/RTF documentation can easily be re-generated after changes in the source files with the help of for example the tool "Doxygen".
An configuration file for Doxygen is included, and is named OPC_doc.cfg. Make sure that the settings in this file are correct. Most important and likely to change are 1) the location of source files and 2) the location of the tool dot.exe from the Graphviz package. To compare the settings with the default Doxygen settings, run a "diff" (using, for example, the WinDiff program that comes with MSVC++) on OPC_doc.cfg and Doxygen_defaults.cfg.
When you are ready to re-generate the documentation, just run Doxygen with the configuration file as the parameter:
X:\Doxygen\bin> doxygen OPC_doc.cfg
Consult the manual of Doxygen for more information about Doxygen and how to configure it. Be sure to keep dot.exe from the Graphviz package either in your PATH, or in the place specified by the OPC_doc.cfg file.
- HTML Documentation after re-generation
The HTML documentation will now be available in OPC_Adapter_Doc\html.
- RTF Documentation after re-generation
The RTF documentation will now be available in OPC_Adapter_Doc\rtf. However, MS Word does not update the fields automatically, so this has to be done manually. It is easy, though: Open the document, select everything (Ctrl-A) and press F9 (update field). Then print or save the documentation in another format.