CIMserver Message Exchange
This document provides late breaking or other information that is relevant to CIMserver Message Exchange (CSME) version 1.2, and is current as of the date above. After that date, you may find more current information and resources in BarcoVision's Document Repository System, in the branch Sensors & Systems/Products/CIMnet/CIMserver Message Exchange. To view the ReadMe file on-screen in Windows Notepad, maximize the Notepad window. On the Edit menu, click Word Wrap.
CIMserver Message Exchange (CSME) provides application communication services for exchanging messages with CIMservers and other units of the SYCOnet network. CSME supports a variety of communication needs, including application registration, receipt of automatic messages, sending messages (unconfirmed, confirmed), and requesting information.
The primary benefits of CSME are ease of use, built-in confirmed message exchange, full proof information requesting, exchange of express messages, message identification through identifier and service, access to all address levels, built-in flow control, asynchronous communication, exchange of big data volumes, and transparent session management. CSME provides an easy-to-use interface, using a familiar metaphor--the COM Automation interface--available from most Rapid Application Development (RAD) tools, and languages.
Installing CIMserver Message Exchange
The installation of CIMserver Message Exchange is supported on following platforms:
- Microsoft Windows
- Microsoft Windows
To install CSME, run setup.exe on the first distribution disk of CSME. You must uninstall previous versions of CSME before you install this version. When all components are selected, following files are installed on the default path C:\Program Files\Barco\CIMnet:
- CSME ReadMe.txt: this ReadMe file.
- CSMessageExchange.dll: in-process registered COM server exposing the
message exchange objects.
- CSMessageExchange.chm (optional): CSME developer's guide and reference.
- Samples (optional): directory with programming samples.
- Debug (optional): directory with debug files (dll and pdb). The debug
CSMessageExchange dll is not registered by the setup.
Following system files are installed in the windows system folder if your
system contains older versions:
Note that CSME can coexist (on the same computer) with the older
communication entity CIMserver Message Exchange (CSMSG) that was installed with the CIMserver Utilities. To modify, repair or remove the CSME installation, run Add/Remove Programs
from the Control Panel and select CIMserver Message Exchange.
CIMserver Message Exchange (CSME) is not a completely new entity. It builds on the CIMserver Message (CSMSG) entity that was released for several years on different platforms. The CSMSG entity came as part of the CIMserver Application Entity (CSAE), containing several modules used by applications for CIMserver communication. For more information on CSMSG's history, see also "History of CSMSG".
To avoid naming confusion with previous versions of CSMSG, this reworked version has been given the new name CIMserver Message Exchange (CSME). The main purpose of this new release is to provide application developers with a COM Automation interface for exchanging messages with SYCOnet. This allows to implement message exchange from all tools and languages that support COM implementations. The CSME interface layers on the message exchange kernel that was not re-implemented, to keep its stability and performance obtained through years of testing and deployment. Not cutting off any of the available message exchange functionality, was one of the major design objectives for this new interface. As a result, the new interface supports both synchronous and asynchronous calls for all communication services. For those knowing the CSMSG interfaces, the CSME interface closely matches--from a functional point of view--the C interface of CSMSG.
Although CSME builds on the existing message exchange entity, this first release of CSME introduces several changes and enhancements that were implemented to overcome some known problems and shortcomings of CSMSG.
Improved Protocol Support
CIMservers and M-Servers can be configured to communicate the TCP/IP or NetBEUI protocol. On Windows NT, CSMSG required you to set LANA number zero to the network route that corresponded with the protocol of the CIMservers you wanted to communicate with (in Control Panel, Network, Services, NetBIOS Interface). CSMSG didn't allow communication from one application computer to both TCP/IP and NetBEUI CIMservers. On Windows 2000, it isn't possible anymore to change the LANA number settings.
The implementation of CSME is changed according to Microsoft's guidelines for NetBIOS mplementation. For each CIMserver connection CSME establishes, it tries to connect the CIMserver on all available network routes. As a result, it isn't required anymore to change LANA number settings when using CSME. In addition, CSME can simultaneously connect TCP/IP and NetBEUI CIMservers.
Improved Network Registration
Before an application can communicate with CIMservers it needs to register a unique name on the network. Depending on the size of the network, it can take from a second, to several seconds, to even a minute before the name is validated on the network.
The registration logic of CSME is tuned to register applications more efficient. If the application specifies a name of three or less characters, CSME appends twelve characters with the computer's MAC address (hexadecimal encoded) to the name. Since a MAC address is supposed to be unique on the network, this name is guaranteed to be unique.Applications still can take full control of the name registration by specifying an application name of more than three characters. Such applications need to implement registration retries for cases where name conflicts occur.The problem of CSMSG not allowing to run several instances of the same communicating application on a computer is solved in CSME. If the application uses the auto-registration mechanism as explained above, CSME reuses the first application registration for all other instances. This speeds up the network registration from the second instance on.
Reduced Length of Application Name
CSMSG allowed to specify an application name of sixteen characters. This length corresponds with the maximum length NetBIOS allows for a network name. However, NetBIOS uses the last character of a name for typing the name. If the last character is blank, NetBIOS types the name to the default type UNIQUE (code 0x20).
To prevent an application from interfering with this name typing of NetBIOS, CSME limits the length of an application name to fifteen characters.
Removed Limitations for Regular Applications
CSMSG distinguished regular from management applications. Regular applications were not allowed to communicate with modules on the CIMserver and CIMserver controller, or with the management modules on other units.CSME removes all these restrictions, allowing all applications to communicate with all modules on all units.
Multiple Application Registrations
CSME allows one application instance (process) to perform several registrations. This feature simplifies the development of reusable communication components. Such a component can independently implement all its communication functions, including application registration. If an application instantiates several of such components, it doesn't need to foresee a single registration used by all these components.Note that CSME optimizes application registration by internally sharing one registration for all component registrations. CSME uses the name delivered by the first component that registers.
Improved Application Closing
When an application is removed from CSME, CSME closes all pending communications before returning a succeeded removal to the application. If an application registered several components, only the communication of the removing component is closed.
CSME completes pending service requests with the status "cancelled". For example, consider an application that launched a message receipt and that is waiting for the next message to be received. This receipt is cancelled the moment the application is removed from CSME. This way the application doesn't need to wait on a receipt time-out before it can close.
Synchronous and Asynchronous Communication
The C++ interface of CSMSG didn't allow asynchronous communication for ll services. As in the C interface of CSMSG, CSME supports synchronous and asynchronous communication for all communication services.An application can mix synchronous and asynchronous communications. For example, a receiving application typically synchronously registers and removes the application, ynchronously adds units, but asynchronously receives messages.
Keeping User Interface Responsive
When CSME waits for the completion of synchronous service requests, it executes a message loop to peek and dispatch the window messages. This causes a user-interface application that performs synchronous communication to remain responsive to user interaction.
Simplified Address Specification
Instead of specifying an integer value for each address level, addresses are exchanged with CSME using concatenated strings. The general format for this address string is:
Only those parts in the string required for addressing a unit of a
type are filled:
for a CIMserver
. for a
CIMserver controller ("MSERV4.0").
. . for a data unit
CSME uses a default time-out of five seconds for all service requests. This default time-out can easily be changed through a property in the interface.In addition, you can specify a time-out per sending or receiving service request. If you specify a time-out for a service request, CSME will use this time-out instead of the default time-out.
Simplified Adding and Removing Units
A receiving application needs to add the units for which it wants to receive the automatic messages. The adding and removal of units has been simplified by implementing these functions in an "overwrite mode".When an application adds the same unit twice, CSME doesn't return an error but assumes the application still wants to receive messages for this unit. When an application removes a unit that wasn't added, CSME doesn't return an error but assumes the application doesn't want to receive messages for this unit.Since an application can remove all units at once by specifying a wildcard address ("*"), it doesn't need to remember all units it added.
Simplified Message Filtering
A receiving application default receives all normal and express messages for the units it added. Through properties in the interface, an application can request to receive only normal or express messages.Note that CSMSG also allowed to filter on the service class (confirmed request, unconfirmed) of a message. Since this feature was never used, it isn't supported by CSME anymore.
Returning Received Data
CSME takes a different approach for returning received data. Data is received when receiving automatic messages, or when requesting information. With CSMSG, an application needed to deliver a data buffer of a certain size for these services.CSME creates its own resources for receiving message data. By default it can receive messages of maximum 1024 data bytes. If an application expects to receive larger messages, it can change this maximum through a property in the interface.If CSME receives a message that is larger than the preset maximum, it returns the first portion of the data to the application. CSME indicates that the data is incomplete by setting the return code to a specific success code "message incomplete". Note that CSME doesn't consider this as an error condition. When an application receives an incomplete message, it can decide to receive the remaining data with a "receive data" service or to flush it with the "flush data" service.
The error codes returned by CSME are included in an enumeration in the type library. In addition, you can ask CSME for a brief description (English only) of a returned error.
Returning Events to Applications
With CSMSG, an application could request CSMSG to log internal events directly into the Windows NT event log. This didn't allow an application to handle CSMSG events with the same mechanism used to log other application events. CSME has abandoned this approach.An application can ask CSME to return internal events in a callback interface the application delivers to CSME. The application can select to receive information, warning, and error events.An application can also ask CSME to return significant events such as filter conflicts, connections, and disconnections. A significant event will return specific information on the event. For example, the connection event returns the name of the CIMserver with which the connection is established.
History of CSMSG
The first versions of CSMSG were developed and released for the VMS and OpenVMS platforms in the years 1994 and 1995. They came with a C application interface, giving applications access to the CSMSG services through C functions and structures. Later a FORTRAN application interface was added, allowing usage of CSMSG in VMS FORTRAN applications.The last release of CSMSG for the VMS platform was issued in April 1996
The first port of CSMSG to Windows NT was implemented in 1995 and came with a C interface only.During the port of the PCMS monitoring system from DOS to Windows NT (1996, 1997), a C++ interface was added to CSMSG. The purpose of this interface was to give Visual C++ developers a more object-oriented programming interface. However, this interface was never documented.To allow implementation of message exchange from other development tools and languages, a beginning was made with the development of a COM interface in 1999. An alpha version of this interface was released, but the interface was never used in a released product. Since this interface was too much oriented to Visual C++ applications, its development was discontinued.To make the message exchange entity more suited for other development tools as well (Visual Basic, Delphi), the development of a new COM Automation interface was started in 2000 and resulted in the new CIMserver Message Exchange (CSME) entity.
List of Releases
- The receive logic now times out if it's longer than 30 seconds waiting for
the data to receive. In previous version the logic would wait forever and
resulted in a communication deadlock.
- Improvement to the disconnection logic to solve following problem:
In some rare cases a session closed by the CIMserver keeps pending in the local session table (LST) of the PC. The status of this session is 'aborted'. If the maximum of 16 sessions is reached, no new session can be accomplished. Now, the improved logic forces to close an aborted session.
- Message descriptions for the Windows NT eventlog system added to CSME as
Improvement to reconnection logic to solve following problem:
When the TCP/IP protocol is used on Windows 2000 to communicate over a cross-cable, CSME can't reconnect when an abnormal disconnection occurs.
- When a PC is disconnected from the network and then reconnected again, CSME repairs the communication channel so the communication works as before. In previous builds of CSME this functionality didn't work for the TCP/IP protocol on Windows 2000 or higher. Now, CSME also repairs the communication channel for the latter case. When the TCP/IP network connection is broken or disabled on a PC running Windows 2000 or higher, CSME return a new error: 'CSMENetworkNotAvailable' (85 or 0x0055).
- The ReceivedDataPresentation parameter is set to the value returned from
the devices. In previous builds this parameter was always set to 0. The
ReceivedDataPresentation parameter is returned from the following
functions: Request, Receive, ReceiveData, OnRequest, OnReceive and
- If LaunchRemoveApplication is called without an attached callback interface, the error 'CSMEInterfaceError' (752 or 0x02F0) is returned. In the previous builds this call made CSME crash.
- The performance of asynchronous communication services is improved.
- The RespondError method sets the error code and application error code correctly. In the previous build the error code was always set to 'CSMEServicePending' (65535 or 0xFFFF) and the application error code was always set to 0.
- When CSME waits for the completion of a synchronous communication service, it executes a message loop to peek and dispatch the window messages. This causes a user-interface application that performs synchronous communication to remain responsive to user interaction. In the previous build however, some messages were not dispatched. In this build all messages are dispatched during synchronous communication services.