LabMap® Handbook
The thirtieth edition
Dr. Dmitry A. Kazakov,
Rüdiger zum Beck
September 2007
 © Copyright cbb software GmbH

Table Of Contents

1. Preface

LabMap® is a 32-bit MS-Windows® multithreading application providing a high level interface for industrial communication, control, measurement, and logging. LabMap® allows asynchronous viewing and modification of the system variables from potentially unlimited number of applications running on same or different LAN/WAN network hosts. LabMap® has an open architecture supporting smooth integration of new hardware and software components. It has integrated support of measurement units and time stamping of the system variables. The software functions under Microsoft Windows® (x86 platform). This manual reflects the version 5.4 of LabMap®.

1.1. Hardware and software requirements

Depending on the actual system configuration and used components the following hardware and software are necessary: 

Option Required hardware Required Software
Basic system IBM PC® with an x86 processor

  • Operating system:

Windows 95® with Internet Explorer 4.0
Windows 98®
Windows me®
Windows NT® with Internet Explorer 4.0
Windows 2000®
Windows XP®
Windows Server 2003®
AK interface COM port
Cast interface

-

-
DiCom interface AVL DiCom 4000 device, COM port, Special serial cable
  • A serial driver running for the designated COM port
DMX interface Either of the following:
  • USB port and an USBDMX1/2 adapter of Soundlight;
  • LPT port LPT/DMX adapter as published in Elektor/Elektuur
  • For USBDMX1/2 the drivers of Soundlight are required as well as the dashard.dll (placed in the Windows system directory)
  • For LPT adapter, the lpt_dmx.dll (placed in the Windows system directory)
ExtFix interface COM port, the external fixation device
  • A serial driver running for the designated COM port
IAVCAN interface A CAN adapter card by IAV
  • Driver and libcan1.dll by IAV
FLG interface Any hardware supporting TCP/IP (such as an Ethernet adapter, modem, ISDN card)
  • FLG client library (flgcln.dll) by cbb software GmbH (delivered with the interface as a part of it)
  • Windows® network services installed (TCP/IP support)
  • Driver's aid unit (FLG) by cbb software GmbH
LSC interface -
  • Zoellner LSC software (AVL Zoellner GmbH)
MODBUS/TCP interface

Any hardware supporting TCP/IP (such as an Ethernet adapter, modem, ISDN card)
  • Windows® network services installed (TCP/IP support)
Net interface Any hardware supporting TCP/IP (such as an Ethernet adapter, modem, ISDN card)
  • Windows® network services installed (TCP/IP support)
  • Time synchronization software (optional, recommended for slow or numerous connections)
NI-CAN interface A CAN adapter card by National Instruments
  • NI-CAN driver and nican.dll by National Instruments. The version 1.5.1 or higher of the NI-CAN software is required.
ODBC interface

-
  • Windows® ODBC driver to the corresponding database
OPC interface (see)
 -
  • Windows NT® service pack 4 or higher
  • An OPC server
  • Softing (Softing GmbH) OPC client tool run-time libraries (shared ASCII)
PGMNet interface

Any hardware supporting PGM packets (such as an Ethernet adapter.)
  • Windows® network services installed (TCP/IP support)
  • Windows® PGM services installed
PLU interface Pierburg PLU 401
  • Serial driver running for the designated COM port
RC interface Volltronic's remote control device, COM port.
  • Serial driver running for the designated COM port
RRR interface AVL 6801A01 transputer link ISA card
User interface - -
VCI interface

A CAN adapter card compatible with IXXAT's virtual CAN interface

  • VCI V2 2.14 or higher (run-time support and CAN driver of IXXAT)

Virtual interface - -
VXL

 

A CAN adapter card of Vector Informatik GmbH supported by XL driver library

1.2. Architecture overview

LabMap® operates as a software bus system. It offers an abstraction of the application level from the hardware specific and decoupling the hardware interface modules from the application level. In other words there are two levels of abstraction supported by the bus system:

The application abstraction interface exposes LabMap® as a set of variables (registers). Each register has a type, value, timestamp and I/O direction. The four basic I/O requests are supported for each register:

LabMap® offers a variety of synchronization mechanisms to an application:

The hardware abstraction interface of LabMap® allows easy integration of new hardware devices and communication protocols into the system. Each class of hardware devices or communication protocol supported by LabMap® is represented by a hardware interface. The hardware interface is responsible for implementation of the basic I/O operations upon the registers assigned to it. LabMap® uses a messages mechanism for interacting with the hardware interfaces. A hardware interface is developed as dynamic-link library which code can be maintained independently from the LabMap® core.

1.3. Plug-ins

Additionally to the basic configuration cbb software GmbH offers different plug-ins.

1.3.1. Remote access interface

The remote access interface (LabNet.dll) allows LabMap® to manipulate registers of remote hosts also running LabMap®. The remote access functions over TCP/IP network protocol. LabMap® running as the server can limit the number of simultaneous client connections. Additionally it can maintain lists of allowed and denied hosts. The remote access interface supports register mapping mechanism. A screen shot of a MMI controlling a Zoellner dynamometer from a remote host accessed via modem internet connection is shown on fig.1.1:

Figure 1.1. Remote MMI

The dynamometer parameters on Fig 1.1 are indicated on-line in a graphical from using the on-line graphics plug-in. The remote access interface allows to integrate several LabMap® hosts into one distributed system. The system variables (registers) can be either shared by all hosts of the system or be local for each host. Each host may function as a server of an arbitrary number of remote host. A server usually maintains the system variables related to the hardware connected to the host. The clients may remotely access the variables maintained by the server. At the same time a server may access the system variables provided by other hosts. Typical configurations are shown on figures 1.2-4:

Figure 1.2. Star topology: one server - several clients

Here the server runs a man-machine interface software (MMI) and communicates with the hardware attached to it. Several client hosts monitor the system state. This configuration is used when the hardware is shared by several hosts. Actually each of the hosts may run MMI. However, only one at time should have control (have access to) the hardware. The arrows on the figure indicate the client-server relations. Connections between server and client are point-to-point. Note also that the actual topology of the underlying network can be any, as long it supports TCP/IP.

Figure 1.3. Star topology: several servers - one client

Here several hosts are connected to the hardware. They work as servers for the single client that runs MMI. This configuration is usual when the hardware is scattered over the network hosts. In the shown example RRR and SPS are connected to different hosts. Being servers these hosts provide the corresponding hardware specific registers for the client running MMI.

Figure 1.4. Gateway

In this case a host is simultaneously a server and a client. It works as a gateway to access some remote host having a hardware attached to it. This is the typical situation when some hosts of the network are connected over slow communication lines like modem link. The gateway host controls the communication to the remote host, so that network traffic over the slow line remains bearable. It mirrors all necessary registers of the remote host for other hosts of the network.

1.3.2. On-line graphics (oscillograph)

The on-line graphics plug-in allows µs precision timings measurements of system parameters and their graphical representation on-line (fig.1.2).

Figure 1.2. On-line graphics plug-in

Features:

1.3.3. XY-graph

The on-line graphics plug-in allows µs precision timings measurements of system parameters and their graphical representation on-line (fig.1.3).

Figure 1.3. XY-graph plug-in

Features:

1.3.4. On-line log

The on-line log allows to log values of the selected registers. Features:

1.3.5. On-line monitor

The on-line monitor allows to watch the integral state of the registers. Screen shot is shown on Fig.1.4:

Figure 1.4. On-line monitor

1.3.6. Bus messages monitor

The bus messages monitor allows to watch the raw data of some messages-oriented interfaces. Screen shot is shown on Fig.1.5:

Figure 1.5. Bus messages monitor

Features:

1.3.7. Multicast server

The multicast server plug-in provides an efficient efficient one-to-many IP communication, conserving bandwidth by reducing traffic between hosts through filtering out the packets required by the hosts
accessible along the routing path.

Multicast groups. Traffic control is based on the multicast group concept. A multicast group contains all receivers interested in particular multicast stream. The group can stretch across local network borders. Hosts declare their wish to attend a group using IGMP (Internet Group Management Protocol: RFC 3376.) For this reason all the routers and switches between the producer and all receiver hosts, have to support IGMP to get advantage of filtering. This in particular requires the hosts to run at least Windows 2003 Server® Server. When a host wishes to join a multicast group, its request propagates up to the producer host. This causes IGMP-capable devices to start routing the IP packets of the group down to the receiver. Otherwise multicast packets are dropped. When the receiver leaves the group, and there are no other receivers along the path, the IGMP-capable device stops routing and thus the packets of the group get dropped again. This policy allows effective filtering of the multicast IP packets  Multicast IP packets have the class D of IP addresses. The Internet Numbers Authority (IANA) controls assignment of IP multicast addresses. The addresses 224.0.0.0 to 238.255.255.255 can be used for implementation of proprietary protocols. Though among this range some addresses are reserved. Each multicast group has a unique address of the above class. Further the number of groups can be limited by the hardware. It is important to note that within one group there can be many multiplexed packet streams. So the group determines the topology of routing and filtering and not the content. Multiplexing is achieved on the port basis.

Multicast transport. Differently to broadcasting, multicasting was designed with reliability in mind. LabMap® uses reliable multicasting protocol PGM (Pragmatic General Multicast: RFC 3208.) The network packets used are neither TCP nor UDP. The protocol takes responsibility for resending lost packets as necessary. Technically the multicast stream is buffered in the routing nodes. The negative acknowledgements from clients propagate up to the last routing node, which has the lost packet. The packet is then resent down to the client. Therefore PGM has no typical drawbacks of UDP communication, yet provides an efficient one-to-many connection.

The LabMap® multicast server supports and unlimited number of multicast groups and an unlimited number of ports multiplexed in a group. Note that as was stated above, traffic filtering is based solely on the group basis. The packets of all ports within a group are routed together. Each configured port in a group has a corresponding publisher. Any LabMap® register can be published by any of publishers. The publisher is responsible for broadcasting the events associated with changing the state of the published registers as well as for periodic broadcasting the information about the registers published. The clients can connect to the publisher's broadcasting at any time. Within the broadcasting period described above any new client receives the whole information about all published registers. The data sent within this period are called frame. The frame length determines how quickly a client can connect to the publisher. Shorter frames require wider bandwidth and have bigger overhead, because within one frame register state is updated incrementally, allowing to reduce the traffic.

Windows 2003 Server® by default does not have PGM installed. The Fig 1.5 represents a network properties dialog called using Start → Settings → Network connection →  some connection. The component Reliable Multicast Protocol must be installed and enabled there.

Figure 1.6. Network connection properties dialog of Windows 2003 Server®

The LabMap® multicast server can be configured on-line. The user dialog is invoked from the system menu as shown on the fig. 1.7.

Figure 1.7. Multicast server configuration in LabMap® menu

The configuration dialog is shown on fig. 1.8.

Figure 1.8. Multicast server configuration dialog

The configuration dialog allows creation and deletion multicast publishers. Publishers are automatically organized into multicast groups according to its addresses. The publisher properties dialog is shown on the fig. 1.9.

Figure 1.9. Multicast publisher properties dialog

The registers to publish can be selected using the register publishing dialog (fig. 1.10):

Figure 1.10. Register publishing dialog

The publishing period when non-zero limits the publishing rate of the register to the specified number of milliseconds. Otherwise, the register state change is published as soon as possible.

1.4. Utilities

1.4.1. AK server

LabMap® can be remotely accessed using the AK protocol. LabAKSrv is an application implementing the AK server for LabMap®.

1.4.2. Log files converter

LabMap® log files conversion utility can be used to obtain text files from.

1.4.3. Remote registers mapper

The utility program LabNetMap provides a simplified way of automatic network registers creation. The registers are mapped to the registers of some remote LabMap® host. When possible the utility creates the network registers with the same numbers as the remote registers have. The created registers will have the names of the remote ones. The utility has the following arguments:

labnetmap <host-handle> <timeout> [<message-handle>] "<prefix>"  [<first-temp-handle>]

where:

For instance, the command

labnetmap 10 1000 "Exported"

Here the host register is 10, the connection timeout is 1s, the prefix is "Exported". When using shell command lines, make sure that the standard error stream is redirected to the terminal. Alternatively one can store it into a file:

labnetmap 10 1000 "Exported" 2> error.txt

2. Installation and Components

The general structure of LabMap® is shown on the fig.2.1:

Figure 2.1. The software structure

The software structure allows user-written applications to access the system variables and parameters over the standard interface independently from the actual hardware configuration. The programmer interface is provided by LabMap.dll. It implements user requests using the hardware specific interfaces. The software has an open architecture. Hardware interfaces can be added at needs without modification of LabMap.dll and user applications. The following hardware interfaces are presently supported:

Intrface name

 Hardware

Implemented by

C/C++ Prototypes
AK Devices supporting the AK protocol LabAK.dll LabAK.h
Cast Operating system LabCast.dll  
DiCom AVL® DiCom 4000 device LabDiCom.dll LabDiCom.h
DMX DMX-512 devices LabDMX.dll LabDMX.h
ExtFix The external fixation device used in the Medizinishe Universität zu Lübeck LabExtFix.dll LabExtFix.h
FLG Ergo-drive FLG servers (driver aid unit) LabFLG.dll LabFLG.h
IAVACAN CAN-bus (the Controller Area Network) via adapters cards by IAV LabIAVCAN.dll LabIAVCAN.h
Net Allows building systems distributed over TCP/IP sockets LabNet.dll LabNet.h
LSC  The LSC application maintained by AVL Zoellner GmbH LabLSC.dll LabLSC.h
Map It responds no hardware directly, rather uses other interfaces to implement complex operation visible for other application as simple variables LabMap.dll LabMap.h
ModBus MODBUS/TCP hosts LabModBus.dll LabModBus.h
NI-CAN CAN-bus (the Controller Area Network) via adapter cards by National Instruments LabNICAN.dll LabNICAN.h
ODBC ODBC-complaint database LabODBC.dll  
PGMNet IGMP-capable routing devices. Additionally Windows Server 2003® is required LabPGMNet.dll LabPGMNet.h
PLU Pierburg PLU 401 devices LabPLU.dll LabPLU.h
RC Volltronic's remote control device LabRC.dll LabRC.h
RRR RRR (German abbreviation of "dynamometer controlling computer") is a computer (based on the inmos® T805 processor) controlling in real-time the roller dynamometer. The RRR is connected to the host computer via transputer link using AVL® 6801A01 transputer link card. For more information, please, refer Zoellner documentation LabMap.dll LabMap.h
SPS OPC interface to communicate with the devices controlled by an OPC server. For the interface description see. LabSPS.dll  
VCI

CAN-bus (the Controller Area Network) via adapter cards by IXXAT

 LabVCI.dll LabVCI.h
Virt

On-line evaluated registers

LabVirt.dll LabVirt.h
User

Memory (user variables)

 LabUser.dll LabUser.h
VXL

CAN-bus (the Controller Area Network) via adapter cards by Vector Informatik GmbH

LabVXL.dll LabVXL.h

LabMap.exe provides dialogue based user interface. The executable and DLL files should be placed into the Windows home directory and the system registry should be configured. The LabMap® may be started either manually by invoking the LabMap.exe or automatically by starting an application that uses any of interface DLLs.

3. User Interface

3.1.Main panel

LabMap.exe always starts minimized. If one opens its main panel it looks as shown on the fig.3.1:

Figure 3.1. The main panel

The main panel contains the following elements:

The main panel menu has the following additional items defined:

3.2. Log panel

The log panel of LabMap® appears when user clicks on the Log button of the main panel. The log panel is shown on the fig.3.2:

Figure 3.2. The log panel

Each message on the log panel occupies exactly one line and consists of four fields:

3.3. Data flow panel

The data flow panel appears on clicking on the Data button of the main panel. The data flow panel is shown on fig.3.3:

Figure 3.3. Data flow panel

The data flow panel contains the following elements:

3.4. Handle watch panel

To watch over a register one should open the handle watch panel by typing a number in the edit box of the main panel and pressing ENTER. The handle watch panel is shown on fig 3.4-6:

Figure 3.4. Output register watch panel

Figure 3.5. Input register watch panel

Figure 3.6. Record register watch panel

Input registers accept values from the host computer. The values can be set by the operator using the watch panel and/or by an application over the programmer interface. Output registers read-only values to the host computer. Record registers are place holders for grouped input registers periodically requested by the host computer. A watch panel contains the following elements:

gray
     
The register is not marked for logging
blue
 
The register is marked for logging. Note that this does not mean that the register is being logged. It only means that it will be logged if the logging will be active.
gray
     
There was no operation on the register, hence its state is undefined
green
 
The last operation was successful
yellow
 
An operation is in progress. Notice that an operation is always in progress for a handles sent automatically each n ms (see discussion concerning output handle properties below)
red
 
The last operation failed

Figure 3.7. Manual value set

All the applications communicating working with LabMap® will be notified that the value has been changed exactly the same way as it would be if the value were actually changed by the hardware. 

In most cases changing value of an output handle has no sense and could be potentially very dangerous, because the value would no more respond to the actual value held by the hardware

One can quickly switch a watch panel from one handle to another. Clicking on the handle number field pops up the panel shown on the fig.3.8. One can choose the desired handle to watch out of the list by simple mouse click. The list contains all the known (declared) registers.

Figure 3.8. Handle selection panel

The registers in the selection panel can be sorted by name, handler and number. One can also directly type the register number or name using the keyboard. If the input unambiguously identifies a register it will be shown. Alternatively one can use the arrows and enter key to select a register. LabMap® members desktop locations of all watch panels that were not closed before terminating LabMap®. So that they reappear on the same places by next start of LabMap®.

3.5. Modifying handle properties

The properties panels are shown on fig. 3.9-10:

 Figure 3.9. Output handle properties

Figure 3.10.  Input handle properties

A register has the following properties:

Default timeout The default timeout is one for all handles. The timeout is set in milliseconds. Changing it affects all registers having default timeout 
Specific timeout The specific timeout is unique for each register. The timeout is set in milliseconds
No time limit When selected, all operations on the register are not time limited
Upon request The value should be explicitly requested 
On change The value is automatically updated when it is changed, but not oftener than each n ms
Each The value is automatically updated each n ms. The effective timeout for handles requested to be sent each n ms, is calculated as the specified_timeout + n

The properties dialog may contain additional interface-specific information as discussed below.

3.6. Creating new handles

When user attempts to watch an unknown register, LabMap® opens the handle creation panel shown on fig.3.11:

Figure 3.11. Handle creation panel

There are four types of registers supported:

The record registers are place holders for grouping other registers to speed up data transmission. The groups are automatically filled by LabMap® to achieve optimal performance. Currently only the RRR supports records. For floating-point registers input (software) and output (hardware) measurement units can be set. See LabMapSetUnits for further information.

3.7. Properties of CAN handles (IAV, NICAN, VCI, VXL interfaces)

The properties panel for a CAN-bus handle is shown on fig. 3.12:

Figure 3.12. CAN-Handle properties panel

The adapter / port configuration panels are specific to the interface. Usually they contain settings for the baud rate, polling intervals etc. For a NICAN CAN-port the configuration panle is shown on fig. 3.13:

                    Figure 3.13. CAN configuration panel

The CAN-message configuration dialogs are shown on fig 3.14-16

         

Figure 3.14. CAN message advanced configuration mode

Figure 3.15. CAN message slice configuration

                    Figure 3.16. CAN message as-is configuration

3.8. Properties of ModBus handles (MODBUS/TCP)

The properties panel for a ModBus handle is shown on fig. 3.17:

Figure 3.17. ModBus-Handle properties panel

3.9. Properties of Net handles (Network TCP/IP interface)

The properties panel for a network handle is shown on fig. 3.18:

Figure 3.18. Net-Handle properties panel

The properties panel for a Net handle with browse dialog is shown on fig. 3.19:

Figure 3.19. Net-handle properties panel with browse dialog

The configuration/properties panel for the remote server configuration is shown on fig. 3.20:

Figure 3.20. Net-Handle remote server configuration dialog

3.9. Properties of User handles (User registers interface)

The properties panel for a User handle is shown on fig. 3.21:

Figure 3.21. User-Handle properties panel

3.10. Properties of Virt handles (Virtual registers interface)

The properties panel for a Virt handle is shown on fig. 3.22:

 

Figure 3.22. Virt-handles properties panel

3.11. Properties of PGMNet handles (Pragmatic Generic Multicast interface)

The properties panel for a PGMNet register is shown on fig. 3.23:

Figure 3.23. PGMNet register properties panel

The configuration/properties panel for the remote server configuration is shown on fig. 3.24:

Figure 3.24. PGMNet remote server configuration dialog

4. Programmer's interface

LabMap® provides bindings to other programming languages. The bindings are available for:

Further bindings are provided to engineering frameworks:

This document describes C/C++ bindings.

The programmer interface consists of two large parts:

Hardware specific interfaces are not recommended for use unless you exactly understand and know what you are going to do with them. An application using a hardware dependent interface looses an advantage of being hardware independent.

LabMap.dll exports the following functions (all of them have C call conventions):  

LabMapAcceptMessage   LabMapGetRealSIEx     LabMapSetBits  
LabMapAccess     LabMapGetSequenceNo
  LabMapSetBitsEx  
LabMapBottomOf     LabMapGetStatistics   LabMapSetError  
LabMapCanExit     LabMapGetStatus     LabMapSetErrorEx  
LabMapCatchAll     LabMapGetString     LabMapSetInt  
LabMapCheckBounds     LabMapGetStringBounds     LabMapSetIntBounds  
LabMapCreate     LabMapGetStringEx     LabMapSetIntCallBack  
LabMapDeaccess     LabMapGetStringLength     LabMapSetIntEx  
LabMapDelete     LabMapGetTimeStamp     LabMapSetName  
LabMapDeleteBounds
  LabMapGetUnitMessage     LabMapSetReal  
LabMapDisableCallBack     LabMapGetVersion     LabMapSetRealBounds  
LabMapDispatcher   LabMapGetWaitCount
  LabMapSetRealCallBack  
LabMapEnableCallBack     LabMapGetWaitForUpdateCount     LabMapSetRealEx  
LabMapFindHandle     LabMapGetWindowMessage     LabMapSetRealSI  
LabMapFirstHandle
  LabMapLastHandle     LabMapSetRealSIBounds  
LabMapGenStatus
  LabMapLeftOf     LabMapSetRealSIEx  
LabMapGetError     LabMapLogEvent   LabMapSetSignalCallBack  
LabMapGetErrorText   LabMapLogIn     LabMapSetString  
LabMapGetBase     LabMapRaise     LabMapSetStringBounds  
LabMapGetInt     LabMapRaiseEx
  LabMapSetStringCallBack  
LabMapGetIntBounds     LabMapRegAccess     LabMapSetStringEx  
LabMapGetInterfaceName     LabMapRegDeaccess     LabMapSetTimeOut  
LabMapGetIntEx     LabMapRegConfig   LabMapSetUnits  
LabMapGetInUnits     LabMapRegGetOwner   LabMapTopOf  
LabMapGetName     LabMapRequest   LabMapUnitConfig  
LabMapGetOutUnits

LabMapRightOf
LabMapWait
LabMapGetOwner

LabMapSend
LabMapWaitEx
LabMapGetReal     LabMapSendInt   LabMapWaitForUpdate  
LabMapGetRealBounds     LabMapSendMessage   LabMapWaitFroUpdateEx  
LabMapGetRealEx     LabMapSendReal   LabMapWatch  
LabMapGetRealSI     LabMapSendRealSI      
LabMapGetRealSIBounds     LabMapSendString      

The functions marked by the icon  are implemented by all interface DLLs, i.e. they exist in both hardware-independent and hardware-specific forms. For instance, when you use LabMapSendInt, it has the effect that a new value will be sent down to the hardware responsible for the specified register, say, to RRR. Then the same effect will have also a call to LabMapSendInt. As for send commands, you should be very careful, because sending a value via a hardware dependent interface which is not responsible for the register may cause undesired side effects (apart from malfunction).

LabIAVCAN.dll additionally (to the functions marked by ) exports the following functions (all of them have C call conventions):  

LabIAVCANGetPortName

LabNet.dll additionally exports the following functions (all of them have C call conventions):  

LabNetConnect

LabNetConnectEx
LabNetDisconnect
LabNetGetConnectionInfo
LabNetGetHandleInfo
LabNetMapHandle

The header files for hardware interfaces are listed in the interfaces table. The header files can be used with an ANSI C or ISO C++ compiler. When using Microsoft Visual C++ compiler, make sure that the run-time libraries are linked in the shared (DLL) form. LabMap® is MFC (Microsoft Foundation Class library) free. However, you are free to use MFC in applications linked to LabMap®. Doing so, remember that MFC run-time library must be linked as a DLL (shared). Make sure that multithreaded versions of the DLLs are used.

4.1. Return codes

If other not stated the result of an interface function is encoded as follows:

Code Meaning
< 0 (negative) Failure. The result value encodes the error reason:  
Symbolic name No. Description
ResRRRWrongHandle -1 The specified register number indicates a not-existing  register or the type of the register is invalid for the requested operation
ResRRRBusy -2 The operation cannot be executed without blocking. The reason is that the input messages queue has no free place for the incoming packet
ResRRRDataOverrun -3 The user buffer is too short to accept the message data
ResRRRWrongUnits -4 Some error related to measurement units
ResRRRNotHandled -5 The operation requested from an interface library is not defined in there
ResRRRSystemFault -6 The operation failed due to an system error
ResRRRAccessDenied -7 The operation failed due to lack of access to an exclusive register involved in the operation. Exclusively accessed registers may be modified  (see LabMapSetError, LabMapSetInt, LabMapSetReal, LabMapSetRealSI, LabMapSetString) or sent to the hardware (see LabMapSend, LabMapSendInt, LabMapSendReal, LabMapSendRealSI, LabMapSendString) only if the application gained the access to them (see LabMapAccess). Otherwise, the corresponding function will fail with this return code
ResRRRWrongUserName -8 Incorrect user name specified
ResRRRTypeError -9 The value data type does not match one of the register
ResRRRTimedOut -10 A wait operation was cancelled due to time limit expiration. See LabMapWaitEx and LabMapWaitForUpdateEx.
ResRRRNoLogFileOpen -11 It is returned by some logging operations which require an open on-line log file
ResRRRLogCreationFault -12 It is returned by some logging operations failed to create an on-line log file
ResRRRNotLogged -13 The requested data are not in the log file
ResRRRWrongTimeInterval -14 The specified time interval is incorrect (low boundary is greater than high boundary)
ResRRROutOfMemory -15 System resources are exhausted
ResRRRCorruptedLogFile -16 The log file format is illegal
ResRRRWrongLogFileIndex -17 The specified log file index does not correspond to an open log file
ResRRRLoadFailure -18 The specified hardware interface cannot be loaded
ResRRRWrongPolicy -19 An illegal combination of register policy bits specified while register creation
ResRRRNoHandlesLeft -20 The number of free register handles is exhausted
ResRRRWrongValue -21 The operation tried to set an illegal value into a register. For instance, NaN for a floating-point register
ResRRRWrongBounds -22 The operation attempted to set or request wrong register values bounds
ResRRRNoUnitExists -23 A non-existing device unit is requested for configuration
0 Success
> 0 (positive) Success (and result if any). Value 1 has ResRRRSuspicious code which indicates that the operation perhaps returned an erroneous value. However there is no way to determine this. For instance, log read operations return this code when the returned value was obtained by an extrapolation of the log data

4.2. Messages

To avoid blocking LabMap® uses messages technique. A potentially blocking operation is not executed on the caller's context. Instead of this it causes sending some message to the interface implementing the operation. Figure 4.1 illustrates execution of LabMapSendInt on the example of the SPS interface:

Figure 4.1. Execution of a blocking operation

The caller might belong to any system process. The messages technique allows to cross the process borders when the operation cannot be executed on the caller's context. Usually there is no necessity to send a message explicitly. It is recommended to use higher level interface functions instead. Note also that hardware-dependent interfaces support only a subset of messages listed below:

Message (symbolic name) Event (sent when) Data
CmdRRRCloseHandle A system handle injected into LabMap.exe should be closed to release the system resource. The message is sent when it is not possible to do from the caller's context. This message also serves synchronization purpose upon exit. LabMap.exe sends it to each hardware interface as a notification upon exit. After that it waits for the handle, which usually is the handle of the dispatcher thread of the interface (gets signaled upon thread completion). The handle is returned by LabMapDispatcher call. If it is zero, then the CmdRRRCloseHandle will not be sent. HANDLE to be closed
CmdRRRCompleted This message is sent to LabMap.dll upon operation completion (usually failed) for a remotely accessed register. The register's state and error code are scheduled to be sent to the remote clients. Pointer to the remote host caused operation completion (can be 0)
CmdRRRConfigure This message is sent to an interface when the interface gets selected in the register properties dialog box. The interface may subclass the dialog box to show additional configuration fields. The message can be ignored if the interface does not support interactive register configuration. Handle to the dialog box (HWND)
CmdRRRDelete It is sent to an interface when a register served by the interface is being deleted. The message is processed internally, so an interface should not processes it.  
CmdRRRGotAccess A user has gained access to the exclusive registers. All connected remote hosts will be notified upon this message. unsigned number: user ID, pointer to the remote host  (can be 0 or missing)
CmdRRRInterfaceLoad This message is sent to LabMap.dll to notify it that a new interface was loaded (possibly in a process other than LabMap.exe). The data packet contains the name of the interface (as a null-terminated string). The interface name (null-terminated)
CmdRRRLogCease This message is sent upon graceful deactivation of logging.   
CmdRRRLogCreate This message is sent to indicate that a log file should be created. The data packet contains the name of the log file (as a null terminated string). It can be empty to indicate that the current log file should be closed without opening a new one.  The log file name (null-terminated)
CmdRRRLogStart This message is sent upon logging activation.  
CmdRRRLogStop This message is sent upon logging deactivation.  
CmdRRRLogout Notifies that a user has logged out. User name (not null-terminated)
CmdRRRLostAccess A user has lost access to the exclusive registers.  All connected remote hosts will be notified upon this message. unsigned number: user ID, pointer to the remote host  (can be 0 or missing)
CmdRRRModified Modification of a remotely accessed register that changes the value of the register. The register's value and time stamp are scheduled to be sent to remote clients. Pointer to the remote host caused operation completion (can be 0).
CmdRRRRefreshed Modification of a remotely accessed register that does not change the value of the register, i.e. when the new value is equal to the old one. The register's value time stamp is scheduled to be sent to remote clients. Pointer to the remote host caused operation completion (can be 0)
CmdRRRRegisterConfig  Register configuration request. It is sent to subclass a window with a register configuration subdialog. The message is used only
internally. The data packet contains a handle to the window to subclass (HWND), the window area used to place the register configuration controls (RECT), and the unit name. The last can be empty. When the interface rejects the configuration attempt it should post WM_RRRFinalized to the parent window with WPARAM set to ResRRRNotHandled.		 1) Handle to the parent window (HWND); 2) Rectangle to put the device unit configuration controls (RECT); 3) Null-terminated device unit name.
CmdRRRRemoteDelete Notifies that a remotely connected register has been deleted. This message is sent to LabMap.dll.  
CmdRRRRendezvous Notifies an interface that about a rendezvous request pending. Rendezvous are used internally for synchronous calls to the interfaces. This mechanism is never used by LabMap.dll itself and provided for interface developers. It is upon an interface to choose which kind of rendezvous it will use. If it does, its dispatcher thread need not to react to the message, because it is processed internally, so that the dispatcher will not be directly aware of it.  
CmdRRRRequest  The value of a register has been requested. The receiver initiates asynchronous I/O to get the register's value from the hardware  
CmdRRRSend  The new value of a register has been set. The receiver initiates asynchronous I/O to send the register's value to the hardware  
CmdRRRStart  The hardware configuration start. Usually this command is followed by a sequence of CmdRRRStartHandle commands ended by the CmdRRRStartFinal command  
CmdRRRStartFinal  The hardware configuration end. This command follows a sequence of CmdRRRStartHandle commands. This is the last command of the configuration sequence  
CmdRRRStartHandle  A register should be configured. Depending on the way the register is requested the hardware is configured. Upon start this command is sent for each known register except for ones included in records. The data packet contains two unsigned numbers Two unsigned numbers: 1) copy of the register's status field; 2) copy of the register's request policy field
CmdRRRStop  End of closing the connection to the hardware. This command ends a sequence of CmdStopHandle commands  
CmdRRRStopHandle  The hardware should disconnect a register. For each  CmdRRRStartHandle sent upon start a corresponding CmdRRRStopHandle will be sent upon stop Two unsigned numbers: 1) copy of the register's status field; 2) copy of the register's request policy field
CmdRRRStopInitial  Start of closing the connection to the hardware. This command begins a sequence of CmdStopHandle commands  
CmdRRRUnitConfig  Device unit configuration request. It is sent to subclass a window with a unit configuration subdialog (see LabMapUnitConfig). The message is used only internally. When sent to LabMap.dll (the first stage of message processing), the data packet contains, a handle to window to subclass, the window area, interface name and optional, unit name. LabMap.dll dispatches the message to the interface responsible for the unit dialog. At this stage its data/ packet contains no interface name. When the interface rejects the configuration attempt it should post WM_RRRFinalized to the parent window with WPARAM set to ResRRRNotHandled. 1) Handle to the parent window (HWND); 2) Rectangle to put the device unit configuration controls (RECT); 3) Null-terminated interface name; 4) Null-terminated device unit name.
CmdRRRUpdateState The status fields of register's watch panel has to be refreshed  
CmdRRRUpdateValue The value field of register's watch panel has to be refreshed  
CmdRRRUpdateWatch Entire register's watch panel has to be refreshed  
CmdRRRWatch Register's watch panel has to be shown. The X, Y coordinates are sent as the message data. When one of the coordinates is negative, the register panel is closed. When both X and Y are positive it is opened if does not exist. Otherwise, the existing panel gains focus and the coordinates are ignored. Two signed numbers: 1) the X coordinate of the watch panel; 2) the Y coordinate.

Only messages marked by the  icon are sent to all interface DLLs. Others are processed by the LabMap.dll only.

4.3. Access to shared data

The values of registers can be accessed asynchronously by several processes scattered over the network. The access concept is user-based. Any process using LabMap® should log in as a user (see LabMapLogIn). User names are global for the network. User list is maintained by LabMap®. Any user may read register values. In contrary to this write access is restricted. Figure 4.2 illustrates register access: 

Figure 4.2. Accessing registers

All registers can be subdivided into two classes

Not only writing to exclusive registers is restricted by this way. Here is the full list of actions that will fail without having an access to the register:

There are two ways of accessing an exclusive register:

Accessing register in a networking environment should be considered more carefully. Each host running LabMap® has its own copy of all register values and user list. When a register is accessed (written for instance) the local host decides whether the access is accepted or denied. For performance sake the local host relies on its own information, remote hosts are not asked. LabMap® software tries to synchronize register owning information, so that each host would have it same. Similarly the updated value or state of a register is sent to all other hosts viewing the register. Only remote registers (ones handled by LabNet.dll interface) or registers viewed by some remote hosts are subject of synchronization. Such registers are global, i.e. their copies in each of LabMap®s have same values and owners. Other registers remain local, i.e. each LabMap® has its own unsynchronized copy of it with possible different values and owners. Values of registers are provided with time stamp in universal coordinated time (UTC). Clocks of all hosts viewing the global registers should be synchronized as precise as possible.

The interface LabNet.dll has several operating modes:

When hosts are linked in read-only mode they remain isolated in terms of register owning. It means that different users may simultaneously access them. They still may share some registers, however exclusively accessed registers may neither be sent nor requested remotely. Note also that if a read-write connection is established in parallel to the read-only one, the isolation would be lost.

4.4. The blackboard

The blackboard is a ring buffer allocated in the shared memory that contains the most recent updates of the register values and the signals raised for the registers. An application may periodically inspect the blackboard contents to figure out whether a value of a register was changed. Unlike the way the subroutine LabMapWaitForUpdate acts, the blackboard. mechanism allows catching all value updates. See LabMapSetIntCallBack, LabMapSetRealCallBack, LabMapSetSignalCallBack and LabMapSetStringCallBack for further information.

4.5. Bounds checking

LabMap® offers an option of constraining the register values by setting value bounds. A value constraint is a pair of bounds defining a contiguous interval of register values. For string registers the bounds limit the string length. Several constraints can be set independently on the same register with the restriction that the constraints comprise a set of nested intervals of values. For each constraint one can define one of the following reactions on bounds violation:

Reaction (symbolic name) Description Effects on virtual registers
Bounds Bounds error
in out
BoundsRRRPass The value is set into the register as-is. The special registers named "Bounds in", "Bounds out", "Bounds over", "Bounds under" handled by LabMap.dll monitor bounds entering and leaving. One can use LabMapSetIntCallBack to monitor such events without polling. Additionally the function LabMapCheckBounds provides an easy way of checking which bounds have been violated by the current register value. register number register number -
BoundsRRRSaturate The value is saturated to the corresponding bound and the result is set into the register. - - -
BoundsRRRDiscard The value is ignored, the register state and value remain unchanged. The special LabMap.dll register "Bounds error" monitors the values discarded due to bounds violation. Its value is set to the register number which value was discarded accompanied by the discarded value. Usually this register is marked for logging to track down unfeasible values. - - register number and value
BoundsRRRSignal The register sate is set to StatusRRR*BoundError depending on which bound has been violated. The register value is not changed. The special LabMap.dll register "Bounds error" monitors the values discarded due to bounds violation as in the case of BoundsRRRDiscard. - - register number and value

The bounds are checked for all operations which might change the register value. This includes the register handlers. So an output register bounds can be used to prevent unfeasible values received from the hardware. Similarly, bounds set on an input register will prevent sending illegal values to the hardware as a result of a software fault. Bounds are set using the following calls: LabMapSetIntBounds, LabMapSetRealBounds, LabMapSetRealSIBounds, LabMapSetStringBounds. Note that no bounds can be set on any of the virtual registers handled by LabMap.dll (see). The register bounds can be removed using the function LabMapDeleteBounds.

4.6. LabMapAcceptMessage 

int LabMapAcceptMessage
(
   unsigned char * Command,
   unsigned      * HandleNo,
   void          * Data,
   int           * Size
);

This function is used by interface handlers to pick up a message from the queue of the handler. When the queue is empty the handler enters wait state. The Command parameter receipts the operation code. The HandleNo parameter accepts the number of the register. Note that some messages do not related to any specific register. In this case zero is returned. The Data parameter points to the buffer to store the message data. The Size parameter initially contains the size of the data buffer. After successful completion it will have the actual size of the data packet. If the function fails with the ResRRRDataOverrun code, the Command and HandleNo parameters would be properly set according to the actual packet in the queue. The packet itself remains in the queue. 

  1. The operation is not process-safe. It means that one and only one process may use it, however, from possibly several threads,
  2. The function must be never called for the interfaces which process the messages. Calls to LabMapAcceptMessage, LabMapAcceptMessage, LabSPSAcceptMessage may severely damage running system

4.7. LabMapAccess

int LabMapAccess (void);

This function is used to gain the access to the exclusively accessed registers. The operation fails when some other user already has the access. See also: LabMapDeaccess, LabMapGetOwner, LabMapLogIn.

4.8. LabMapBottomOf

RECT LabMapBottomOf (void);

This function returns a pointer to the rectangle corresponding the area bottom of the window subclassed by LabMapUnitConfig. When specified there it causes the parent window to be extended downwards with unit configuration controls.

4.9. LabMapCanExit

int LabMapCanExit (void);

This function checks if the LabMap.exe is the single application that uses the software. If yes (return value is not zero) the LabMap.exe could be terminated.

Return value
0 The LabMap.exe cannot be terminated 
other It can be terminated

4.10. LabMapCatchAll

int LabMapCatchAll (unsinged HandleNo, int CatchAllFlag);

This  function is used to control the callbacks for the register HandleNo. The callback subroutine is set using the functions LabMapSetIntCallBack, LabMapSetRealCallBack, LabMapSetStringCallBack. By default the callback subroutine [when enabled see LabMapEnableCallBack, LabMapDisableCallBack] is called only when the new value differs from the old one. This behavior can be changed to catch all value changes. The parameter HandleNo is the register number. The parameter CatchAllFlag indicates the desired behavior. If CatchAllFlag is zero the callback will be called only when the new value differs from the old one. Otherwise it will be called always.

4.11. LabMapCheckBounds

int LabMapCheckBounds (unsinged HandleNo);

This function is used to check the current register value against the bounds set upon the register HandleNo. Upon successful completion the result is the number of an interval of values violated by the current register value. It is the most enclosing (wide) interval if several of them do not contain the value. The result is zero if the current value is within all bounds. Note that newly set bounds are initially violated no matter which value the register has.

4.12. LabMapCreate

int LabMapCreate
(
   unsigned   * HandleNo,
   const char * Name,
   const char * Server,
   unsigned     Status,
   unsigned     TimeOut,
   unsigned     Each,
   const char * InputUnit,
   const char * OutputUnit
);

This function creates a new register. The created register number is returned via the parameter HandleNo. The parameter Name specifies the register name. Note that some hardware interfaces may impose additional requirements on the name appearance. Usually it is a set of parameters in square brackets at the name end. Further, the hardware may support no on-fly register creation. Refer the corresponding hardware interface documentation. The parameter Server specifies the name of the interface that serves the register. The interface is loaded if necessary. The parameter Status contains the desired status bits. The following bits can be used: 

Bits group Description
HandleInteger, HandleReal, HandleString. These bits specify the register type. Exactly one of these bits shall be set. If no HandleReal bit applied, then the parameters InputUnit and OutputUnit are ignored. 
HandleInput This bit indicates the register I/O direction. When set, the register is designated for send data operations. In this case the parameter Each is ignored. Otherwise it is a output register, i.e. one designated for request operations. 
HandleDefaultTimeout, HandleNoTimeout These bits are mutually exclusive. If one of them is set then the parameter TimeOut is ignored. If none of these bits is set the parameter TimeOut specifies the time limit for I/O operations.
HandleOnChange, HandleUponRequest These bits determine the register's policy. They are mutually exclusive and cannot be applied when the bit HandleInput is set. The parameter Each limits the frequency the data updates / requests happens. It is ignored if HandleUponRequest is applied. 
HandleExclusive This bit is set to limit access to the register.
HandleInUse When this bit is set, the newly created register will be accessed by the application as if LabMapRegAccess were called immediately after the register creation. This bit is ignored when the bit HandleExclusive is not set.
HandleTemp This bit is set to disable register persistence. A persistent register will reappear after the system restart. 
HandleNewFromRRR This bit is set to enable callbacks for the register immediately after its creation. It has the effect as if LabMapEnableCallBack were called for the register before any I/O operation on it. It is preferable to an explicit call to LabMapEnableCallBack.

The parameter TimeOut specifies the register operation time limit in ms. It is ignored if no specific time limit is used (see above). The parameter Each limits the register I/O frequency (see above). It is specified in ms. The parameters {Input|Output}Unit specify the measurement units of the register. They shall be compatible. Both parameters are ignored (and thus can be zeros) if the created register is not a floating-point one.

4.13. LabMapDeaccess

int LabMapDeaccess (void);

This  function is used to allow other users to access the exclusive registers. The user may lose general access either by calling LabMapDeaccess, or when LabMapAccess  is called by a user named 'supervisor', or when LabMapRegAccess is called by another user or when all applications of the user exit. See also: LabMapAccess, LabMapGetOwner, LabMapLogIn.

4.