Installation

Infodriver32 also requires that Inf32fix.exe and Info32fix.dll are available in the windows command path. They directly pass the external hook-in messages that are broadcast below the range that Microsoft applications can receive. A Microsoft runtime libraries msvcr100.dll and msvcp100.dll are also required to be in the command path and are included in the infodriver distribution package.

For V3 systems the Info32fix.dll file should be placed in the directory specified by “SystemPath” in c:\bncs_config.ini.

In a V4.5 system the Info32fix.dll file should be placed in the “windows\lib” directory within the project specified in the workstation 'CC_ROOT' and 'CC_SYSTEM' environment variables.

This help file 'infodriver32.chm' and Inf32fix.exe should be in the same directory as Infodriver32.exe. In V4.5 systems the drivers are stored in 'windows\bin' directory within the project, V3 systems usually have a designated directory for drivers in each project .

If you are using Windows XP and get the error message "The procedure entry point decodepointer could not be located in the dynamic link library KERNEL32.dll.", you will need to install Windows XP service pack 2 or 3.

Configuration

Infodrivers have a dedicated ini file, this takes the form of Dev_xxx.ini where xxx is the device number specified as a command line parameter. If this file does not exist then it is created when the Infodriver is first run up.

For V3 systems this file is held in the directory specified by “ConfigPath” in c:\bncs_config.ini.

In a V4.5 system it is in the “config\system” directory within the project specified in the workstation 'CC_ROOT' and 'CC_SYSTEM' environment variables.

If neither of these systems are defined, the default path for the configuration files is the OS system directory, i.e. c:\windows.

The configuration parameters used by the Infodriver are detailed in the table below:

Entry | Notes
[DEVICE]
Name=Device 123
SecondaryDATFilePath=NONE By replacing 'NONE' with the full path to the parent folder, (eg. \\File_Server\bncs\dat_files), a second DAT file can be generated. If the DAT file does not exist in that location one will be created.

Note - Do not put the file name in the path

DefaultDriverMode=INTERNAL INTERNAL – No external driver expected.
EXTERNAL - Expecting an external software connection. The driver mode label is coloured bright red and slot updates are inhibited when the external driver is not connected.

Setting this to External will allow the infodriver to go RxOnly when requested by another driver if the external driver is not present. It will remain RxOnly irrespective of the mode of any other drivers.

DefaultControlMode=INTERNAL INTERNAL – No external client control expected.
EXTERNAL - Expecting an external client control connection. The control mode label is coloured bright red and slot updates are inhibited when the external client/automatic is not connected.

Setting this to External will allow the infodriver to go RxOnly when requested by another driver if the external control client is not present. It will remain RxOnly irrespective of the mode of any other drivers.

StartupMode=TXRX | Defines the mode in which the driver starts up; this can be set to either TXRX or RXONLY. The mode may be subsequently changed by CSI
GoRXOnlyOnExternalFail=0 | Setting this value to 1 causes the infodriver to go RxOnly if the external driver or external client fails to respond to an 'IW' command.
EnableLocks=0 | If set to 1 infodriver slots can be locked, by default locking is disabled.
SendDelay(ms)=0 | Whether to defer sending until after a timeout period (see Delayed Output)
ImmediateRevertives=0 | If set to 1, slot updates from an External driver will be processed synchronously and not queued into a buffer
[DATA]
UpdateRxOnlyFromRevertive=0 Setting this value to 1 allows an External driver &/or slots to be updated from network revertives while the infodriver is RxOnly.
Warning: This feature has been added to address a Riedel specific issue. If misused there may be unexpected results including potential to synch in the wrong direction after drivers have been restarted
[SECURITY]
Access=ALL | Access can be limited to specific Workstations eg 1,17,38 a range of Workstations eg 200-257 or ALL Workstations
Steve Lowe. © Copyright Atos 2012


Credits

Simon Dowson

The original versions of InfoDriver including INFODRIV, V2INFDRV, V25INFO, V35INFO, V3InfDrv, V4InfDrv

David Yates

Inf32fix.exe and Info32fix.dll

Steve Lowe

InfoDriver32 - merged from V3InfDrv and V4InfDrv with a few other enhancements

This documentation includes original material from Simon, Mark Baldry and others in the BNCS team (past and present).
Steve Lowe. © Copyright Atos 2011


Document Template

Data Storage

The contents of an infodriver are stored to disk in Dev_xxx.DAT file, the lock status is held in Dev_xxx.LCK file where xxx is replaced with the driver number. For v3 systems, these files are held in the directory specified by “ConfigPath” in c:\bncs_config.ini, for v4 it is in the “data” directory within the system set by CC_ROOT and CC_SYSTEM environment variables.

Infodrivers always update their local data files from received network messages (IW), even when in RxOnly, and also with private messages from connected external devices/clients.

The 'free-form' of data in the slots is often used to store common information or configuration parameters for other devices, allowing them to be modified over the network. Backup copies of the DAT files are recommended where the data has not been generated automatically or has been entered manually and would be difficult to reproduce if lost.

If a secondary DAT file path is set in the configuration file the stored data is also written to that directory by the active driver, the file path is commonly set to be on the system server. The secondary DAT file is not read by the infodriver and must be copied to the local data directory prior to launching the infodriver. Note: external network events or restarting the system server may invalidate the secondary DAT file.

Another strategy is to use an external process to regularly make a backup copy of the local data file which is periodically closed and re-opened by the infodriver to update its file date and time.
Steve Lowe. © Copyright Atos 2011


Dialog

User Interface

The Title bar displays: Device No. - current interface mode - Version No. - "Device Name" (Delay mode)

The Driver status label will change to “External” on a dark red background when an external driver is connected. A bright red background indicates that a configured external driver is not connected.

The Control status label will change to “External” on a dark red background when an external client has connected. A bright red background indicates that a configured external client is not connected.

The Tx and Rx counters indicate the number of slot change messages sent to and from CSI, this does not include the other house keeping messages or those between externals.

If the Interface label shows ‘RxOnly’ it indicates that there is another device with the same device number on the network in ‘Tx/Rx’ mode.

Any information slot between 1 and 4096 can be selected from the index list using the keyboard navigation keys or mouse, the contents of the slot can be modified from the keyboard. The Store button saves the new slot contents to the dat file, if the driver is Tx/Rx and in a normal mode the slot contents will also be sent as a revertive (IR) on to the network. If a default external driver/client mode is configured, the Store button and slot updates will be disabled while the externals are not connected.

The Config menu calls a pop-up window with the configuration path used by the Infodriver with an option to open the configuration ini file in the default text editor.

The Keyboard menu allows the keyboard focus to be moved between the Index and Information Slot windows and to operate the Store function.

The Lock button and menu Lock tab toggle the lock status of the selected slot, the Lock controls are normally disabled (see Configuration section).

The File window displays a list of the messages that have been written to external files by the Info File (IF) command since the driver was started.

The Printer window shows the contents of the logging printer buffer.

The Help menu gives access to the integrated Help application.

Steve Lowe. © Copyright Atos 2012


Redundancy

Data Import / Export

Description

The import/export features were designed primarily to allow maintenance of the data in other tools.

There are two different approaches available

  • file
  • clipboard

File allows data to be opened in any editor, prepared or archived elsewhere.

Clipboard allows copy and paste of data direct with Excel.

Data Format

Data format has been chosen to allow data to be pasted direct into Excel - it's tab-delimited.

Data is the same format for both clipboard and file

For example:

0001	slot1
0002	slot2
0003 	3
0004	4
0005	5
0006	6
0007	7
0008	8
0009	9
0010	10
0011	test0011
0012	test0012
0013	test0013
0014	test0014
0015	test0015
0016	test0016

The first column does not have to be zero padded to 4 characters - but this makes the data sort properly.

The entry below is entirely valid for import and treated no differently to the example above:

1	1
2	2
3	3
4	4
5	5
6	6
7	7
8	8
9	9
10	10
11	test0011
12	test0012
13	test0013
14	test0014
15	test0015
16	test0016

Tabs within data

The import features are well-behaved in that they'll split the data on the first tab and leave the rest alone. Excel has of course got multiple columns so splits an individual item with a tab in it as two cells. This is (usually) not what we want.

Where tabs are detected on export they are enclosed within double quotes - this matches how Excel handles such data. If Excel detects data with tabs it too encloses them. For example

1	"with	tab"

Import

Important note. The import menu items never do anything directly - you always get a preview.

Import is exactly equivalent to entering the value on the UI and hitting the store button. The value is passed to the external if there is one and the slot updated if appropriate - i.e. if the external may determine not to directly update the slot - this is just normal operation.

Preview

This preview shows that an import of 4096 slots was loaded (see bottom left of dialog) but it was found that only two entries had changed.

Hitting Cancel simply closes the dialog without doing anything or having made any changes.

Hitting OK takes the list of changes shown and applies it to the Infodriver. Changes are applied in stages so that the network isn't flooded - for example 4096 slots containing 255 character values will emit 4096 network packets. The import feature is smart enough to limit the changes to 6 packets every 1/3rd of a second and works out from the size of the data how many packets to send. The maximum length of time it takes to import 4096 full-size slots is 225 seconds - by comparison, clearing the infodriver slots takes about 4 seconds because empty slots pack much better.

Export

Export is always all 4096 slots.

Clear

A bonus feature of the Import functions was the ability to clear the contents of the Infodriver. This effectively does a full import of blank slots. The usual preview is shown.

Driver Redundancy

As noted above the import feature is directly equivalent to entering the data on the Infodriver UI and hitting the store button.

Whilst functionally equivalent to receiving an Info Write it isn't an Info Write on the network. This means that it only affects this Infodriver. If you a bulk import on the "main" infodriver then you need to do the same thing on the "reserve".

Steve Lowe. © Copyright Atos 2012


InfoDriver32 Documentation

Please note that this is a guide to the BNCS Infodriver32 application only

Click on the lines below. Help is available for:

Introduction | Overview of the Infodriver32 and its modes of operation
Configuration | Installation notes and description of the ini file settings
Dialog | A guide to the user interface
Redundancy | Using Main and Reserve drivers
Data Storage | File types and locations
Data Import / Export | Taking or passing data via the clipboard or to file
External Driver Data Filtering | Filtering or rewriting of data passed from an external driver

Also included for reference:

Additional files | Use of inf32fix.exe and info32fix.dll
Full Version History | As lodged with the source code. Note that this is an internal document and may be useful but is not a polished, user-friendly document.
Credits
Steve Lowe. © Copyright Atos 2011


Info32fix Application

inf32fix.exe

Inf32fix.exe is required so that Infodriver32.exe can receive some broadcast messages (HWND_BROADCAST) that otherwise it would be unable to hear.

There is a difference between Borland compiler built applications and Microsoft in that Microsoft applications are totally deaf to certain ranges of messages sent from other applications with HWND_BROADCAST. Typically this is thought (not confirmed to be so…) any thing below WM_APP (0xc000).

Unfortunately some of these messages are the hook-in messages required to connect external drivers with ID_CONNECT.

The work around is to use a simple Borland-built application to receive these on behalf of the Microsoft application. All the Borland-built application does is then pass them direct onto the Microsoft application.

inf32fix.exe receives the messages, looks up the handle of the messaging window for the appropriate infodriver and passes the hook-in message on.

To know which numbered infodriver has which window handle they share this data with the info32fix.dll. This allows for cross-process sharing of simple data such as an array of window handles.

info32fix.dll

info32fix.dll is a very simple DLL that is used to share data between Infodriver32 and inf32fix.exe.

inf32fix.exe is required to listen for broadcast messages (HWND_BROADCAST) that Microsoft applications can’t hear. When it receives a ID_CONNECT message that it knows that Infodriver32 will not be able to receive it simply passes it on.

info32fix.dll shares the window handle of running Infodriver32 applications. It has a 1000 slot array of window handles and two functions to get and set data within that array.

Infodriver32.exe explicitly sets its own window handle in the array (via the calls in info32fix.dll) when it’s run.

inf32fix.exe pulls the data from the array when it needs it and validates the handles placed there with an IsWindow() API call.

Steve Lowe. © Copyright Atos 2011


Contents

1 Introduction

2 Interfacing using Classes

3 Interfacing using Windows Messaging

3.1 WM_COPYDATA

3.1.1 BNCSWM32.LIB

3.2 BBC_COPYDATA

3.3 Which scheme to use…?

3.4 Additional project files

4 External Driver Connection

4.1 BBC_IDCONNECT

4.2 BBC_IDCONNECT32

4.3 BBC_IDHANDLE

4.4 BBC_IDDISCONNECT

5 Infodriver Slot Data Exchange

5.1 BBC_IDREVINFO

5.2 BBC_IDSENDSLOTS

5.3 BBC_IDGETSLOT

5.4 BBC_IDSETSLOT

5.5 BBC_IDSETSLOTONLY

5.6 BBC_IDSLOTMSG

5.7 BBC_IDUSERSTR

6 Infodriver Resilience Messages

6.1 BBC_IDGETTXRXMODE

6.2 BBC_IDSETTXRXMODE

6.3 BBC_REQDEVGORXONLY

6.4 BBC_INQDEVGOTXRX

6.5 BBC_REQDEVGOTXRX

6.6 BBC_EXTCOMMANDMSG

6.7 BBC_DEVCOMMANDMSG

6.8 BBC_DEVSTATUSMSG

6.9 BBC_DEVICEIDINUSE

7 External Client Messages

7.1 BBC_CTRLCONNECT32

7.2 BBC_CTRLCONNECT32_DLL

7.3 BBC_HWNDDRV

7.4 BBC_CTRLDRIVERSTR

7.5 BBC_CTRLCLIENTSTR

7.6 BBC_IDREVINFO

7.7 BBC_CTRLGETDATA

7.8 BBC_CTRLDISCONNECT32

8 Miscellaneous Messages

8.1 BBC_CSICLOSING

8.2 BBC_SENDQUEUEDREVERTIVES

1 Introduction

This document covers the current 32-bit versions of the infodriver only. It details the infodriver external services available for developers of external drivers or clients and should be read in conjunction with the basic infodriver documentation. Please note that the release of this documentation is subject to the licence terms agreed between Atos and the BBC dated 30 September 2004, and in particular clause 2.2.3 thereof.

2 Interfacing using Classes

There are libraries that wrap-up a subset of the interfacing messages to make communicating with the infodriver a series of function calls rather than using the raw messages. See separate documentation on the BNCS Class Library and the External Infodriver Interface Class (extinfo.lib).

3 Interfacing using Windows Messaging

There are two 32-bit messaging schemes used to pass data between BNCS applications, these being referred to as WM_COPYDATA and BBC_COPYDATA.

3.1 WM_COPYDATA

The Windows operating system provides the WM_COPYDATA mechanism to share data between applications using shared memory. SendMessage() and PostMessage() are the most common methods.

LRESULT SendMessage(

HWND hWnd, // Handle to target window

WM_COPYDATA, // Message to be sent

WPARAM wParam, // Handle to this window (HWND)

LPARAM lParam // Data (PCOPYDATASTRUCT)

);

Reference

WM_COPYDATA

Type

Application -> Application

Parameters

wParam: - Handle to the window passing the data.

lParam: - Pointer to a COPYDATASTRUCT structure that contains the data to be passed.

Return Value: - If the receiving application processes this message, it should return TRUE; otherwise, it should return FALSE.

Remarks

The data being passed must not contain pointers or other references to objects not accessible to the application receiving the data.

While this message is being sent, the referenced data must not be changed by another thread of the sending process.

The receiving application should consider the data read-only. The lParam parameter is valid only during the processing of the message. The receiving application should not free the memory referenced by lParam. If the receiving application needs to access the data after SendMessage returns, it must copy the data into a local buffer.

3.1.1 BNCSWM32.LIB

The ‘bncswm32.lib’ provides BNCS library functions for processing the data in the shared memory used by WM_COPYDATA messaging. Add bncswm32.h and bncswm32.libs to the project. The additional message and length parameters are as defined in bncs32.h.

BNCS32SendMessage () is declared as

LRESULT BNCS32SendMessage(

HWND hWndThisApp,

HWND hWndTargetApp,

UINT uMsg, // BNCS message value (see bbc_mxc.h)

WPARAM wParam, // Message data

LPARAM lParam, // Message data

int iReturnDataLen, // CBDATA_SIZE_NUMERIC or CBDATA_SIZE_POINTER

int iDataType // CBDATA_TYPE_NUMERIC or CBDATA_TYPE_POINTER

);

BNCS32ReceiveMessage () is declared as

Void BNCS32ReceiveMessage(

HWND hWndThisApp,

HWND hWndTargetApp,

PCOPYDATASTRUCT lpCDS

);

To receive and process WM_COPYDATA messages add a suitable handler to the Main Window Procedure.

case WM_COPYDATA :

BNCS32ReceiveMessage ( hWndMain,(HWND) wParam, (PCOPYDATASTRUCT) lParam );

iResult=1;

break;

3.2 BBC_COPYDATA

BBC_COPYDATA and the BNCSIF32.dll provide a more efficient mechanism for BNCS inter-application messages. It allocates slots in a shared data segment and checks for slots that are still in use, it is limited to passing integer and string data types only. Add bncs32if32.h and bncsif32.libs to project, the BNCS32 message syntax is similar to the standard SendMessage() but with additional message and length parameters as defined in bncs32.h.

BNCS32TxMessage () is declared as

LRESULT BNCS32TxMessage (

HWND hWnd, // Target application

WORD wMsg, // BNCS message value (see bbc_mxc.h)

WPARAM wParam, // Message data

LPARAM lParam, // Message data

int iMsgType, // CBDATA_TYPE_NUMERIC or CBDATA_TYPE_POINTER

int iLen // CBDATA_SIZE_NUMERIC or CBDATA_SIZE_POINTER

);

BNCS32RxMessage () is declared as

LRESULT BNCS32RxMessage (

HWND hWnd, // This application

WPARAM wParam, // Message data

LPARAM lParam // Message data

);

Reference

BBC _COPYDATA

Type

Application -> Application

Parameters

wParam: - Handle to the window passing the data.

lParam: - Integer or Pointer to the data string

int: - Message Type (#defined in bncs32.h as)

CBDATA_TYPE_NUMERIC 0

or CBDATA_TYPE_POINTER 1

int: - Message Length (#defined in bncs32.h as)

CBDATA_SIZE_NUMERIC 16

or CBDATA_SIZE_POINTER 513

Return Value: - If the receiving application processes this message, it should return TRUE; otherwise, it should return FALSE.

Remarks

The data being passed must be an integer or a pointer to a string of maximum 512 chars. While this message is being sent, the referenced data must not be changed by another thread of the sending process.

The receiving application should consider the data read-only. The lParam parameter is valid only during the processing of the message. If the receiving application needs to access the data after BNCS32TxMessage returns, it must copy the data into a local buffer.

To receive and process BBC_COPYDATA messages add a suitable handler to the Main Window Procedure

case BBC_COPYDATA:

iResult=BNCS32RxMessage( hWndMain, wParam, lParam );

break;

3.3 Which scheme to use…?

External drivers and clients can use either scheme but should remain consistent.

All new BNCS applications built with current compilers should use BBC_COPYDATA.

The WM_COPYDATA scheme is less efficient as there are nested transactions to pass a message between processes which can breakdown under high load.

The functionality within the BNCSIF32.dll is under our control and not compiled into each application. It can be further enhanced in future without having to rebuild every module that uses it.

The initial connection message determines the default messaging scheme used thereafter by the Infodriver for passing messages between the applications.

Register with BBC_IDCONNECT - the default message scheme is WM_COPYDATA

Register with BBC_IDCONNECT32 - the default message scheme is BBC_COPYDATA (DLL)

Register as client with BBC_CTRLCONNECT32 - the default message scheme is WM_COPYDATA

Register as client with BBC_CTRLCONNECT32_DLL - the default message scheme is BBC_COPYDATA (DLL)

The infodriver has handlers for WM_COPYDATA and BBC_COPYDATA messages which set internal flags for the reply scheme to be used.

3.4 Additional project files

The ‘bbc_mxc.h’ file contains the defined message exchange constants used by BNCS applications

- defined message values are based on WM_USER = 0x400 and WM_BNCS = 0xC000

Other BNCS constants used in this document are defined in bncs.h and bncs32.h

4 External Driver Connection

4.1 BBC_IDCONNECT

Reference

BBC_IDCONNECT

Value

WM_USER+1700

Type

External Driver -> Infodriver

Parameter

wParam:- Handle of the external driver.

lParam:-Infodriver number to connect to, set the MSB if the external driver is 32-bit. (bncs.h #define DRIVER_32BIT 0x8000)

return:- FALSE

Description

Request from an external driver to the infodriver for its handle and to connect to it. The infodriver can only host one external driver connection whereas an external driver can connect to multiple infodrivers. The infodriver will send a BBC_IDHANDLE message before this message returns.

SendMessage( HWND_BROADCAST, BBC_IDCONNECT, (WPARAM) hWndMain, iDeviceId | DRIVER_32BIT );.

The infodriver dialog box has a Driver status label to indicate a successful connection from an external driver.

Note: Use BBC_IDCONNECT if you intend to use WM_COPYDATA messaging.

4.2 BBC_IDCONNECT32

Reference

BBC_IDCONNECT32

Value

WM_BNCS+2

Type

External Driver -> Infodriver

Parameter

wParam:- Handle of the external driver.

lParam:- Infodriver number to connect to, set the MSB if the external driver is 32-bit. (bncs.h #define DRIVER_32BIT 0x8000)

returns:- FALSE

Description

Request from an external driver to the infodriver for its handle and to connect to it. The infodriver can only host one external driver connection whereas an external driver can connect to multiple infodrivers. The infodriver will send a BBC_IDHANDLE message before this message returns.

SendMessage( HWND_BROADCAST, BBC_IDCONNECT32, (WPARAM) hWndMain ,

iDeviceId | DRIVER_32BIT );

The infodriver dialog box has a Driver status label to indicate a successful connection from an external driver.

Note: Use BBC_IDCONNECT32 if you intend to use BBC_COPYDATA (DLL) messaging.

4.3 BBC_IDHANDLE

Reference | BBC_IDHANDLE
Value | WM_USER+1705
Type | Infodriver -> External Driver
Parameter | wParam:- Handle of the infodriver lParam:- Infodriver number return:- Value not tested by infodriver
Description | Message from infodriver to external driver delivering its handle in the lower 16 bits of wParam for backwards compatibility. case BBC_IDHANDLE : hWndInfoDriver = (HWND) LOWORD ( wParam ) ; break;

4.4 BBC_IDDISCONNECT

Reference | BBC_IDDISCONNECT
Value | WM_USER+1701
Type | External Driver -> Infodriver
Parameter | wParam:- Handle of the external driver. lParam:- Infodriver number to disconnect from returns:- FALSE
Description | Message from external driver to infodriver to say that it is disconnecting. SendMessage( hWndInfoDriver, BBC_IDDISCONNECT, 0, iDeviceId );

5 Infodriver Slot Data Exchange

5.1 BBC_IDREVINFO

Reference | BBC_ IDREVINFO
Value | WM_USER+1698
Type | Infodriver -> External Driver
Parameter | wParam:- device number lParam:- slot number and data separated by a comma return:- Value not tested by infodriver
Description | Notification from Infodriver to external driver delivering a slot change message. The same message type is also sent to an external client (if connected). case BBC_IDREVINFO : Process_SlotChange( wParam, (LPSTR) lParam ); break;

5.2 BBC_IDSENDSLOTS

Reference | BBC_IDSENDSLOTS
Value | WM_USER+1699
Type | External Driver -> Infodriver
Parameter | wParam:- Minimum slot to be sent. lParam:- Maximum slot to be sent. returns:- FALSE
Description | Request from external driver to Infodriver to issue revertives for a range of slots. SendMessage( hWndInfoDriver, BBC_IDSENDSLOTS, (WPARAM) iMin, (LPARAM) iMax );

5.3 BBC_IDGETSLOT

Reference

BBC_IDGETSLOT

Value

WM_USER+1703

Type

External Driver -> Infodriver

Parameter

wParam:- Slot number to retrieve contents from

lParam:- Pointer to a string buffer for the returned string.

returns:- FALSE

Description

Message from external driver to infodriver to request the current contents of a specified slot. Ensure length of receive buffer > MAXSLOTSIZE.

WM_COPYDATA

BNCS32SendMessage( hWndMain, hWndInfoDriver, BBC_IDGETSLOT, (WPARAM) iSlot, (LPARAM) acBuffer, MAXSLOTSIZE, CBDATA_TYPE_POINTER );

BBC_COPYDATA

BNCS32TxMessage(hWndInfoDriver, BBC_IDGETSLOT, (WPARAM) iSlot, (LPARAM) acBuffer, CBDATA_SIZE_POINTER, strlen(acBuffer) +1 );

5.4 BBC_IDSETSLOT

Reference

BBC_IDSETSLOT

Value

WM_USER+1702

Type

External Driver -> Infodriver

Parameter

wParam:- Slot number to be changed.

lParam:- Pointer to string to be stored.

returns:- FALSE

Description

Message from external driver to Infodriver to set a slot and send the revertive message. For efficiency revertives are normally buffered by CSI, set the MSB of wParam for the revertives to be sent immediately.

WM_COPYDATA

BNCS32SendMessage( hWndMain, hWndInfoDriver, BBC_IDSETSLOT, (WPARAM) iSlot, (LPARAM) acBuffer, strlen( acBuffer ) +1, CBDATA_TYPE_POINTER );

BBC_COPYDATA

BNCS32TxMessage( hWndInfoDriver, BBC_IDSETSLOT, (WPARAM) iSlot, (LPARAM) acBuffer, CBDATA_SIZE_POINTER, strlen( acBuffer ) +1 );

5.5 BBC_IDSETSLOTONLY

Reference | BBC_IDSETSLOTONLY
Value | WM_USER+1707
Type | External Driver -> Infodriver
Parameter | wParam:- Slot number to be changed. lParam:- Pointer to string to be stored. returns:- FALSE
Description | Message from external driver to infodriver to set a slot but not to send the revertive. This allows an external driver to initialise or update large numbers of slots without generating unnecessary network traffic.

5.6 BBC_IDSLOTMSG

Reference

BBC_IDSLOTMSG

Value

WM_USER+1704

Type

Infodriver -> External Driver

Parameter

wParam:- Slot number.

lParam:- Pointer to the string contents.

return:- TRUE (confirms external driver running as a resilience check)

Description

Notification from Infodriver to external driver delivering slot content change message. This allows the external driver application to intercept messages sent to the Infodriver. The messages can then be processed, modified and returned using the BBC_IDSETSLOT message or discarded.

Note: A return value is expected; InfoDriver32 uses the result to detect failure of an external device and may go RxOnly. Check ini file device setting for ‘GoRXOnlyOnExternalFail’.

case BBC_IDSLOTMSG :

Process_SlotMessage( wParam, ( LPSTR ) lParam );

return (TRUE);

5.7 BBC_IDUSERSTR

Reference

BBC_IDUSERSTR

Value

WM_USER+1706

Type

Infodriver -> External Driver

Parameter

wParam:- 0

lParam:- Pointer to the string contents.

return:- Value not tested by infodriver

Description

Notification from Infodriver to external driver delivering the complete client message and also the toggle lock slot command from the infodriver dialog panel. Check device.ini file setting for ‘EnableLocks’.

case BBC_IDUSERSTR : Process_ClientMessage( ( LPSTR ) lParam ) ;

Note: The client messages are also parsed within the infodriver. The slot number and a pointer to the string contents of an Info Write command are sent separately to the external as a BBC_IDSLOTMSG.

6 Infodriver Resilience Messages

6.1 BBC_IDGETTXRXMODE

Reference | BBC_IDGETTXRXMODE
Value | WM_USER+1708
Type | External Driver -> Infodriver
Parameter | wParam:- 0 lParam:- Infodriver number returns:- Current interface mode, these values are defined in BNCS.H
Description | Message from external driver to Infodriver to requesting its interface mode status. iInterfaceMode = SendMessage( hWndInfoDriver, BBC_IDGETTXRXMODE, 0, iDeviceId );

6.2 BBC_IDSETTXRXMODE

Reference | BBC_IDSETTXRXMODE
Value | WM_USER+1709
Type | External Driver -> Infodriver
Parameter | wParam:- Interface mode to adopt, these values are defined in BNCS.H. lParam:- 0 returns:- Current interface mode
Description | Message from external driver to Infodriver requesting the infodriver to set its interface mode. If subsequently an objection is received from another InfoDriver already in TxRx mode with the same device number then the external driver will receive a BBC_DEVICEIDINUSE message and the interface mode will be returned to IFMODE_RXONLY. SendMessage( hWndInfoDriver, BBC_IDSETTXRXMODE, IFMODE_TXRX, 0 );

6.3 BBC_REQDEVGORXONLY

Reference | BBC_REQDEVGORXONLY
Value | WM_USER+1155
Type | Infodriver -> External Driver
Parameter | wParam:- 0 lParam:- Infodriver number return:- TRUE to confirm that the driver is prepared to go RxOnly, otherwise FALSE
Description | Request from the infodriver to the driver to go to RxOnly. Normally refused unless an error has been detected and driver functionality is impaired. case BBC_REQDEVGORXONLY : return !fCommsOK;

6.4 BBC_INQDEVGOTXRX

Reference | BBC_INQDEVGOTXRX
Value | WM_USER+1157
Type | Infodriver -> External Driver
Parameter | wParam:- 0 lParam:- Infodriver number return:- TRUE to confirm that the driver is prepared to go TxRx, otherwise FALSE
Description | Request via the infodriver to the external driver to see if it is able to go to TxRx, you should return FALSE if the device has comms or other errors. case BBC_INQDEVGOTXRX : return fCommsOK;

6.5 BBC_REQDEVGOTXRX

Reference | BBC_REQDEVGOTXRX
Value | WM_USER+1156
Type | Infodriver -> External Driver
Parameter | wParam:- 0 lParam:- Infodriver number return:- TRUE to confirm that the driver is prepared to go TxRx, otherwise FALSE
Description | Request sent via the infodriver for the external driver go to TxRx, you should return FALSE if the device has comms or other errors. case BBC_REQDEVGOTXRX : if ( fCommsOK ) { SetTxRxMode( IFMODE_TXRX ); return TRUE; } else return FALSE;

6.6 BBC_EXTCOMMANDMSG

Reference

BBC_EXTCOMMANDMSG

Value

WM_USER+1096

Type

External Driver -> Infodriver

Parameter

wParam:- 0

lParam:- Pointer to the message.

returns:- the result of the message processing; it depends on the message sent.

Description

Message from external driver to host driver delivering a command. This could be the message received in a BBC_DEVCOMMANDMSG, returned for further processing and status reporting by the infodriver

WM_COPYDATA

BNCS32SendMessage( hWndMain, hWndInfoDriver, BBC_EXTCOMMANDMSG, 0, (LPARAM) acBuffer, strlen(acBuffer) +1, CBDATA_TYPE_POINTER );

BBC_COPYDATA

BNCS32TxMessage( hWndInfoDriver, BBC_EXTCOMMANDMSG, 0, (LPARAM) acBuffer, CBDATA_SIZE_POINTER, strlen(acBuffer) +1 );

6.7 BBC_DEVCOMMANDMSG

Reference | BBC_DEVCOMMANDMSG
Value | WM_USER+1097
Type | Infodriver -> External Driver
Parameter | wParam:- 0 lParam:- Pointer to the message. return:- TRUE to confirm the driver can process the message. Otherwise the Infodriver will process the command internally and attempt to change the external driver interface mode using the BBC_SETDEVTXRXMODE message.
Description | Message from the infodriver to the driver forwarding an interface mode status message request/command (NS …) from a networked client. Any status replies to the originator should be sent via the Infodriver, using a BBC_DEVSTATUSMSG message. case BBC_DEVCOMMANDMSG : iResult = NetCmd_Parse( (char *) lParam ); break; See Resilience documentation for full details.

6.8 BBC_DEVSTATUSMSG

Reference

BBC_DEVSTATUSMSG

Value

WM_USER+1099

Type

External Driver -> Infodriver

Parameter

wParam:- 0

lParam:- Pointer to the message.

returns:- FALSE

Description

Message from the driver to the infodriver with a verbatim status message (NS ...) to be sent to a client on the network.

WM_COPYDATA

BNCS32SendMessage( hWndMain, hWndInfodriver, BBC_DEVSTATUSMSG, 0, (LPARAM) acBuffer, strlen(acBuffer) +1, CBDATA_TYPE_POINTER );

BBC_COPYDATA

BNCS32TxMessage( hWndInfoDriver, BBC_ DEVSTATUSMSG, 0, (LPARAM) acBuffer, CBDATA_SIZE_POINTER, strlen(acBuffer) +1 );

See Resilience documentation for full details

6.9 BBC_DEVICEIDINUSE

Reference | BBC_DEVICEIDINUSE
Value | WM_USER+1166
Type | Infodriver -> External Driver
Parameter | wParam:- Handle of the Infodriver lParam:- Infodriver number return:- Value not tested by Infodriver
Description | Message from CSI via the Infodriver indicating that there is another device with the same device number on the network in 'TxRx' mode. The host infodriver will have automatically gone to RxOnly, so there is just the local status to update. case BBC_DEVICEIDINUSE : SetTxRxMode( IFMODE_RXONLY); break;

7 External Client Messages

7.1 BBC_CTRLCONNECT32

Reference

BBC_CTRLCONNECT32

Value

WM_BNCS+12

Type

External Client -> Infodriver

Parameter

wParam:- Handle of the external client.

lParam:-Infodriver number to connect to, set the 2nd MSB if the external client is 32-bit. (bncs.h #define CTRL_32BIT 0x4000)

returns:- FALSE

Description

To connect to an infodriver as a Client External, broadcast a simple connection request from the client application.

SendMessage( HWND_BROADCAST, BBC_CTRLCONNECT32,

( WPARAM ) hWnd, iDevice | CTRL_32BIT );

The infodriver will send a BBC_HWNDDRV message containing the handle of the infodriver for all subsequent messages. Use the supplied handle to connect again directly to the infodriver using a WM_COPYDATA message

if( hWndInfDrv )

BNCS32SendMessage( hWndMain, hWndInfDrv, BBC_CTRLCONNECT32,

( WPARAM ) hWndMain, iDevice, 0, CBDATA_TYPE_NUMERIC );

This technique avoids strange effects when broadcasting this 32-bit message such as launching Outlook etc.

The infodriver dialog box has a Control status label to indicate a successful connection from an external client application.

Note: After connecting with BBC_CTRLCONNECT32 an external client should only use the WM_COPYDATA messaging scheme.

7.2 BBC_CTRLCONNECT32_DLL

Reference

BBC_CTRLCONNECT32_DLL

Value

WM_BNCS+112

Type

External Client -> Infodriver

Parameter

wParam:- Handle of the external client.

lParam:-Infodriver number to connect to, set the 2nd MSB if the external client is 32-bit. (bncs.h #define CTRL_32BIT 0x4000)

returns:- FALSE

Description

To connect to an infodriver as a Client External using BBC_COPYDATA messaging, broadcast a connection request from the client application.

SendMessage( HWND_BROADCAST, BBC_CTRLCONNECT32_DLL,

(WPARAM) hWnd , iDevice | CTRL_32BIT);

The infodriver will send a BBC_HWNDDRV message containing the handle of the infodriver for all subsequent messages.

The infodriver dialog box has a Control status label to indicate a successful connection from an external client application. The infodriver can only host one external client connection whereas an external client can connect to multiple infodrivers.

Note: After connecting with BBC_CTRLCONNECT32_DLL the external client should only use the BBC_COPYDATA messaging scheme.

7.3 BBC_HWNDDRV

Reference | BBC_HWNDDRV
Value | WM_USER+1018
Type | Infodriver -> External Client
Parameter | wParam:- Handle of the infodriver lParam:- Infodriver number return:- Value not tested by infodriver
Description | Message from Infodriver to external client delivering its handle. The device Id in lParam can be useful if the client is connecting to multiple drivers. case BBC_HWNDDRV : hWndExternal=( HWND ) LOWORD ( wParam ); break;

7.4 BBC_CTRLDRIVERSTR

Reference

BBC_ CTRLDRIVERSTR

Value

WM_USER+1752

Type

Infodriver -> External Client

Parameter

wParam:- 0

lParam:- Pointer to the message

return:- TRUE (confirms client running used for resilience check)

Description

When an external client is connected, the raw client message from the network is forwarded directly to the client as a BBC_CTRLDRIVERSTR message.

On receipt of a BBC_CTRLDRIVERSTR message the client application can process it or simply turn it around and send lParam back to the InfoDriver with a BBC_CTRLCLIENTSTR message.

Note: A return value is expected; InfoDriver32 uses the result to detect failure of an external device and may go RxOnly. Check ini file device setting for ‘GoRXOnlyOnExternalFail’.

case BBC_CTRLDRIVERSTR : Process_Message ( ( LPSTR ) lParam ) ;

return (TRUE);

7.5 BBC_CTRLCLIENTSTR

Reference

BBC_ CTRLCLIENTSTR

Value

WM_USER+1753

Type

External Client -> Infodriver

Parameter

wParam:- 0

lParam:- pointer to the string to be processed

returns:- FALSE

Description

The client application sends messages to the InfoDriver using a BBC_CTRLCLIENTSTR message.

WM_COPYDATA

BNCS32SendMessage( hWndMain, hWndInfoDriver, BBC_CTRLCLIENTSTR, 0 (LPARAM) acBuffer, strlen(acBuffer) +1, CBDATA_TYPE_POINTER );

BBC_COPYDATA

BNCS32TxMessage( hWndInfoDriver, BBC_CTRLCLIENTSTR, 0, (LPARAM) acBuffer, CBDATA_SIZE_POINTER, strlen(acBuffer) +1 );

7.6 BBC_IDREVINFO

Reference | BBC_ IDREVINFO
Value | WM_USER+1698
Type | Infodriver -> External Client
Parameter | wParam:- device number lParam:- slot and data separated by a comma return:- Value not tested by infodriver
Description | An external client application receives notification of slot changes with the BBC_IDREVINFO message. The same message type is also sent to an external driver (if connected). case BBC_IDREVINFO : Process_SlotChange( wParam, (LPSTR) lParam ); break;

7.7 BBC_CTRLGETDATA

Reference

BBC_ CTRLGETDATA

Value

WM_USER+1754

Type

External Client -> Infodriver

Parameter

wParam:- Slot number

lParam:- Pointer for the return data

returns:- FALSE

Description

The client can request the status of a slot using BBC_CTRLGETDATA.

WM_COPYDATA

BNCS32SendMessage( hWndMain, hWndInfoDriver, BBC_CTRLGETDATA, iSlot, (LPARAM)acStr, sizeof(acStr), CBDATA_TYPE_POINTER );

BBC_COPYDATA

BNCS32TxMessage( hWndInfoDriver, BBC_CTRLGETDATA, 0, (LPARAM) acBuffer, CBDATA_SIZE_POINTER, strlen(acBuffer) +1 );

7.8 BBC_CTRLDISCONNECT32

Reference | BBC_ CTRLDISCONNECT32
Value | WM_BNCS+13
Type | External Client -> Infodriver
Parameter | wParam:- 0 lParam:- Infodriver number returns:- FALSE
Description | Message from external client to InfoDriver to say that it is disconnecting. SendMessage( hWndInfoDriver, BBC_CTRLDISCONNECT32, 0, iDeviceId );

8 Miscellaneous Messages

8.1 BBC_CSICLOSING

Reference

BBC_CSICLOSING

Value

WM_USER+1151

Type

Infodriver -> External Driver

Parameter

wParam:- 0

lParam:- 0

return:- Value not tested by infodriver

Description

Message from the infodriver that it is closing. It is normal practice to trigger the application closedown procedure on receipt of this message.

case BBC_CSICLOSING : Main_Closedown();

break;

The external driver/client will need to re-connect and exchange window handles etc. if the infodriver is restarted independently.

8.2 BBC_SENDQUEUEDREVERTIVES

Reference | BBC_SENDQUEUEDREVERTIVES
Value | WM_BNCS+86
Type | External Driver -> CSI (Infodriver passthrough only)
Parameter | wParam:- 0 lParam:- 0 return:- none
Description | Force immediate send of queued revertives (rather than waiting or setting flag on last revertive). SendMessage( hWndInfoDriver, BBC_SENDQUEUEDREVERTIVES, 0, 0 );

Original document by Mark Baldry

Revised and updated by Steve Lowe


Introduction

An InfoDriver's primary function is to provide the mechanism for storing global system data, pass messages between client applications and act as interface for external drivers to CSI.

The InfoDriver is organised as 4096 slots, each slot can contain a string of up to 255 characters. The internal structures and data storage (a flat file, dimensioned to maximum proportions) preclude extending the capacity of this application (number of slots, or slot size) - but an Infodriver-like application might use the same basic principles.

Infodriver32 can run as device 1-32767, depending on the CSI it connects to (e.g. originally the limit was 999, csi32 was upgraded to do 4094[sic], and bncs_csi will do 32767 (the maximum size of the IPC messages of this vintage of application)

InfoDrivers have three modes of operation, 'Normal�, �External Driver (Host)� and �External Client�.

In Normal mode it behaves as described above as a data store between applications. In External Infodriver mode the InfoDriver acts as a host to another application. In External Client mode it has an external client connection for custom actions on slot change requests.

Normal Mode

In this mode the InfoDriver slot contents are directly manipulated by clients on the network. Whenever a slot is written to, a revertive message containing the new slot contents is sent back to the network via CSI and thus to all clients that are registered to receive those messages. A client can poll any slot at any time and will receive a message containing a copy of the current data stored in that slot.

External Driver (Host) Mode

In this mode the InfoDriver is taken over by another application that hooks into it using Windows messaging. The InfoDriver allows the external driver to read and write to its slots. When a client application writes to an InfoDriver slot, the message is passed to the external driver which has the opportunity to ignore, validate, modify or send to a 3rd party device before writing any data to the slot. A revertive message is only generated when the external driver writes to an InfoDriver slot. The external driver can change the contents of any slot at any time. The infodriver provides all of the interfacing to CSI as well as the data storage; poll requests are not passed on to the external driver but handled by the infodriver.

External Client Connection

The InfoDriver can accept client (control) externals. This is to allow direct interfacing with the InfoDriver from a single application running on the same PC. There are two separate aspects to client externals, these being speed issues and interception of other client commands. As the client external communicates directly with the infodriver the response times are reduced as there is no network jump, this allows user applications such as an automatic to be written connecting 2 drivers on the same machine with no network hops required. An example of use is when a GPI closure should make a slot change instantly. Client externals will be passed all the write commands sent to the infodriver. It is expected that normally these will be returned to the infodriver, but the client does have the option to modify or ignore the message. Figure 1 shows the flow of an InfoWrite command as well as all other commands and revertives. An example use here would be to allow a slot to be changed only when some other event is true. Applcore note: When an Applcore panel connects to an InfoDriver with the XR command the panel automatically intercepts all InfoWrite commands. Unless an XI command is issued then these InfoWrite commands are simply looped back into the InfoDriver for processing as normal. See Applcore documentation for all "X" series command information.

Simplified Infodriver command and revertive flow.

Delayed Output

Version 1.0.0.9 allows delayed sending of revertives. Instead of sending revertives directly, a timer is started - on timing out sends the current state. Any updates in the mean time sets the value on disk but neither sends the revertive nor resets the timer. This means that revertives are sent out no more frequently than the timeout period.

There are individual timeouts per slot.

This is a simple mechanism - it's always the current value that's sent on timeout, intermediate states are discarded. There is no averaging, no guaranteed toggle of a rapidly changing input. Both of these may be added as features in the future.

At the time of writing, delayed packets are always sent in slot number order.

Steve Lowe. Copyright Atos 2021


Redundancy

It may be desirable to have main and reserve drivers on the BNCS system so that in the event of hardware or driver failure a reserve driver can automatically take over the function of the main driver. This is achieved by having an active driver in TxRx and non-active drivers in RxOnly running on other workstations. The non-active drivers still receive, process and store messages from the network and also from any connected external devices/clients but are unable to transmit data back to the network.

CSI handles the driver redundancy mechanism on the network, passing messages between each other and to the driver applications, to negotiate the TxRx state of each of the drivers. This messaging also ensures that there can be no more than one active instance of a particular device number.

External drivers can use their comms status to influence the redundancy mechanism. Infodriver32 can be set to automatically go RxOnly if the External driver or client should fail (see Configuration section).

From version 1.0.0.17 redundancy can be controlled manually from menu items. Care should be taken where one infodriver is one of a set of many a driver hooks into - some drivers are well-behaved and will reconcile the TxRx state of all its Infodrivers....some are not!

Steve Lowe. © Copyright Atos 2012


Infodriver32.exe
v1.0.0.x	14/07/11	Development started by merging v3.05.00 and v4.1.1.24 into a new Visual Studio project.
                Config paths are obtained from environment variables (V4) or bncs_cfg.ini (V3) otherwise
                the default is to use Win OS system directory.
                GUI tweaks include V3 style coloured status labels, menu bar options for integrated Help
                and new dialog panel to view Config file path and open dev.ini file in default editor.
                Includes V3 periodic close/open of main and secondary DAT files to update timestamps.
                Includes V3 translation of unhandled NS commands into resilience messages for Externals.
                Includes V4 resilience options for Externals (DefaultDriverMode & GoRxOnlyOnExternalFail)
                Excludes V3 DDE (legacy?)- code ported to MS but found it was not initialised in V3.
                Adds integrated Help file (Infodriver32.chm) which should be placed in the same folder.

                New settings & functionality for V3 users:
                ID32 requires inf32fix.exe and info32fix.dll to be present, they directly pass the
                external hook-in messages that are broadcast below the range that Microsoft applications
                can receive.
                ID32 obtains the workstation number from CSI (V4CSI & CSI32)
                ID32 uses the V4 resilience options and checks for the presence of an external window.
                ID32 can go RxOnly if External not responding to messages (use GoRxOnlyOnExternalFail=1)
                ID32 can go RxOnly on request of another driver instance (& will remain so) if External
                is not running (use DefaultDriverMode = External)

v1.0.0.2	22/07/11	Project development environment moved into Visual Studio 2010
                Runtime library 'msvcr100.dll' is now required in the windows command path
                Tweaks - window maximize button disabled, moved View Config into new Config menu.
                Device 'Name' key from ini file added to titlebar.
                Added coloured border to active Lock button
                Added new SendMessage pass-through as applied to v4.1.2.25
                Help docs tidied and rebranded

v1.0.0.3	09/08/11	Dialog update now invalidates just the active Lock button and border to reduce
                visual disturbances.

v1.0.0.4	03/01/12	now buffers BBC_CLIENTMSG before doing any processing (IPC breakdown)

v1.0.0.5	24/01/12	rebuild of 1.0.0.4 but with consistent version numbers (no other changes)

v1.0.0.6	07/03/12	Adds resilience for External Client. Requires forwarded BBC_CTRLDRIVERSTR messages
                to be acknowledged with a non-zero return from external client otherwise checks if ext window exists.
                RxOnly_Broken (NB) message is issued if an external client or driver closes or 'disappears'.
                Slot updates from network and dialog are inhibited while configured driver and control externals
                are not connected.
                GoRxOnlyOnExternalFail default setting is 'O' as not all external drivers handle BBC_IDSLOTMSG.
                Adds secondary check that external driver window still exists if BBC_IDSLOTMSG is not acknowledged.
                Closedown message (BBC_CSICLOSING) also sent to external client window when host infodriver closes.
                Changes messaging scheme used with CSI from WM_COPYDATA to BBC_COPYDATA (DLL).
1.0.0.7		12/03/12	Adds new constant to set client messaging type at hook-in: BBC_CTRLCONNECT32_DLL (or BBC_CTRLCONNECT32 for the original WM)
1.0.0.8		15/03/12	Changes External mode text to include IPC type for controlling infodriver and external client
1.0.0.9		22/05/12	adds delayed send option so that intermediate states can be discarded and so that you can protect the network from sprouting devices

1.0.0.10	10/07/12	Messages BBC_CTRLCLIENTSTR, BBC_DEVCOMMANDMSG, BBC_DEVSTATUSMSG, BBC_EXTCOMMANDMSG, BBC_IDSETSLOT and BBC_IDSETSLOTONLY
                are now buffered before processing.
                Fixes buffer memory leak.
                Protects shared id window handle from being overwritten during abnormal closure (ie forced closure of a second instance).
                Version information for About window and titlebar now extracted from resource file.
                Build settings are confirmed as /MD which also requires runtime library 'msvcp100.dll' in the windows command path.
                msvcp100.dll has been added to the list of files gathered by ZipForDistribution.bat
1.0.0.11	20/07/12	Includes data import/export features, and clear function.
                adds edit config direct from menu item
1.0.0.12	070812		Changes text on buttons on import/clear feature (instead of just saying OK)
                        changes default buttons on import dialog and gives keyboard shortcuts
                fix to file open/save dialog title text
1.0.0.13	13/08/12	rebuild of 1.0.0.12 with consistent upper/lower block version numbers (no other changes)
1.0.0.14	040912		adds update rxonly slot from revertive feature
1.0.0.15	09/10/12	BBC_IDSETSLOT and BBC_IDSETSLOTONLY messages now partially processed (ie slot data written to disc immediately) before buffering.
                RxOnly_Broken (NB) message is only issued when an external client or driver closes normally if the default mode(s) are set to External.
                Corrects wParam value in forwarded BBC_DEVCOMMANDMSG.
1.0.0.16	10/10/12	Adds 'ImmediateRevertive' option to process BBC_IDSETSLOT and BBC_IDSETSLOTONLY messages synchronously, bypassing the buffering.
1.0.0.17	04/12/12	Adds redundancy switching menu items
                        fixes slot value when using send now flag
1.0.0.18	06/08/13	Revised WS Access string parsing - Bug #2376
                Adds WS access permission checking to the command processing
1.0.0.19	06/08/14	Mods for VS2013 compiler to remove explicit template arguments
1.0.0.20	01/05/15	changes icon
1.0.1.0		02/07/15	shuffles #define's about to use shared bncs.h version
                        changes version number to be 3 digits (major, minor, bugfix, branch)
1.0.2.0		11/01/16	Now uses handleshare DLL in preference to HWND_BROADCAST
1.0.3.0		29/01/16	f'f'f'f'foul-up with 1.0.2 wrt getting of handle
1.0.4.0		30/09/16	benign bug with missing break in switch/case statement
1.0.5.0		10/10/16	pass-through of BBC_SETREDUNDANCYMASTER
1.0.6.0 	??/??/?? 	New update slot API call
1.0.7.0 	21/02/18	Changes case of default DEV_xxx.INI filename to lowercase so as not to cause source control (git/svn) to get all confused at both lower and uppcase versions of the same file
1.0.8.0     06/03/18	range checking of workstation number (currently up to 999) before applying it to internal access table.
1.0.9.0		13/04/18    Oops...1.0.8 was correct, but the workstation number passed by the UI/import dialog was not set to a value so it was rejecting its own commands
1.0.10.0	20/04/18	now passes through workstation number supplied by CSI for BBC_REQDEVGORXONLY
1.0.11.0    24/04/18    Range-checking of 1.0.8 was well meaning, completely valid, but stopped historic code working properly. The pragmatic fix is to allow zero workstations to pass as they did before.
1.0.12.0    25/09/18    Lock checking extended to cover externals - otherwise there was an anomaly that a stand alone infodriver wouldn't allow you to write a value when locked, but with an external would
1.0.13.0    25/09/18    Fix to debug message in 1.0.12
1.0.14.0    26/09/18    Lock from the dialog wasn't working, for the same reason as 1.0.8 and with the same pragmatic fix as 1.0.11 applied
1.0.15.0    01/10/18	Trap of out-of-bounds workstation number at startup - otherwise it'll end up rejecting messages from even its own dialog
1.0.16.0    02/10/18	Blunt extension of workstation range support
1.0.17.0    26/11/18	Gentle massaging of NS handling to allow it to send when a target workstation has not been set
1.1.0.0		26/02/19	Adds filtering option for wayward external drivers
1.1.1.0     26/02/19    Adds "temporarily disable" checkbox to allow for evaluation of the effect of a rule
1.1.2.0     01/03/19    Adds run-time editor for filters. Adds help link on dialogs
1.1.3.0     03/03/19    Adds send-on-change filter
1.1.4.0     04/03/19    Massaging of the UI layout
1.1.5.0     05/03/19    Bugfix to key used to store filters (potential to reuse an old key when editing)
1.1.6.0     06/03/19    checks value of segmentationOffset before trying to use it. Rejection of % formatting for slot when setmentation offset has not been specified
1.1.7.0     07/03/19    adds more specific help to the filter UI
1.1.8.0     15/08/19	BST-547 PostMessage now checks return value to stop hanging memory allocations in extreme overload conditions
1.1.9.0		09/10/19	Typo on main dialog of "Mesage" corrected
1.1.10.0	06/11/19	BST-663 Client interface was wrongly implemented for reception of infodriver revertive messages (for UpdateRxOnlyFromRevertive feature)
1.1.11.0	05/06/20	BST-813 Allows sending of multiple different successive values from the same slot
1.1.12.0	11/08/20	BST-862 Early check of string size from external setslot request. Also makes GetArguments call length-safe.
1.1.13.0	12/08/20	BST-862 Reworking of 1.1.12 to crop rather than bin
1.1.14.0	30/11/20	Updating the UI counters with every operation was found to have an unexpectedly detrimental effect on performance. Now deferred, like so many other apps, to a timer-driven deferred update.
1.1.15.0    29/01/21    CORE-320 CSI will reject out of range device values, but infodriver32 itself needs to reject values more than IPC can convey. Otherwise, the IPC just crops the device number at the available number of bits and carries on.
1.1.16.0    03/02/21	Correction to CORE-320 to reject negative device numbers.
1.1.17.0    22/02/21	CORE-336 reject very seriously large messages (>510 bytes). The slot value would already be cropped at this overall message length anyway.


extdriver_filtering

Driver External Message Filtering

Overview

This mechanism applies only to messages from external drivers. It has no effect on stand-alone infodrivers, or setting values directly from the infodriver UI.

Drivers in BNCS are occasionally a little bit over-keen to deliver updates to the network, sometimes with parameters that the user is not using or at a rate disproportionate to the user's interest in them.

For example, a mains distribution unit delivering updates to current mains voltage which toggles regularly from 237, 238, 237, 238, 237, 238 etc. Put enough of those on a system and an underlying murmur of unnecessary traffic turns to a roar. What triggered the need for this feature was enough "background" messages to make 50 messages/second every second of every day.

So, rather than make assumptions about how a driver might be used, or the rate at which updates might be required infodriver adds the ability to filter messages by user configuration.

Values are always stored in the infodriver slot and the current value is returned by polling the device.

"Filters" fit into two catagories - those that just block (filter) the sending of data to the network, and those that rewrite the data.

Filtering options:

  • block - this parameter is not required. Never send a value to the network.
  • change - only send the value out if it's different from the last time we saw it.
  • window - this parameter is likely to wibble between a few values within a window, so only send values if the new value sits outside that window. In our example above you set a lower limit of 237, an upper of 238 no update will be sent to the network.

Rewriting options:

  • average - where the new sample is added to the last n and an average calculated.

For most flexibility more than one filter can be applied to a parameter - for example, considering our mains voltage example above, use "average" to smooth out occasional peaks, and "window" to ensure a general upward/downward trend is still recorded.

Configuration

Very often infodrivers are segmented to present multiple device-instances to the network. e.g. slots 1-100 is the first device, slots 101-200 the second device etc.

To this point, whilst a common feature, it has not been a setting in the infodriver. The filtering feature requires it so it's been added:

[Data]
SegmentationOffset=100

It's useful to configure as "nth" slot of a device, so say the 15th slot of the range has a filter applied (e.g. slot 15, 115, 215, 315 etc.)

So the following configuration would configure the 11th slot in the range to be an average of the last 10 values:

%11,average,10

The following configuration would configure the 12th slot in the range to be masked by a window that's a maximum of 2 (the range is a double precision value, but you can use integer or unsigned values too):

%12,window,2.0

The following configuration would block updates completely from slot 3042 only:

3042,block

Where multiple configurations apply to a slot from different rules, re-writers are applied before filters, then they are applied in the order they're configured. e.g.

%10,average,10.0,%1.3f
%100,window,2

So every 10th slot will have an average, every 100th an average then a window.

Filters

block

Really, never send an update (regardless of any other filter that might be applied). The value still gets stored in the info slot, and will be returned if you poll it.

change

Send an update only if the value has changed from the last time this filter saw it. This might mean first time reasserting a slot to the same value something will be sent to the network.

window

Send a value if it falls outside the window. When a value changes the filter compares against a minimum/maximum based on the window parameter supplied.

For the incoming value, with a window of 2, the config rules might look like one of these. The difference is the data type used (double, signed int, unsigned int):

%100,window,2.0
%100,window,2
%100,window,2u
Value | Min | Max | Output | Notes
100 | 100 | 102 | 100 | Initial value - set the min/max values. Assume (arbitrarily) that initial value is the minimum
101 | 100 | 102 | none | New value is within the window - send no update to the network
102 | 100 | 102 | none | New value is still within the window
103 | 101 | 103 | 103 | New value exceeds maximum - send the value and reset the min/max
102 | 101 | 103 | none | New value is within the window
100 | 100 | 102 | 100 | New value less than minimum - send the value and reset the min/max

So in the above example, we've halved the amount of traffic sent to the network, whilst preserving any significant deviation of values

average

Average takes the last n messages and produces an average.

Unlike "window" which merely selectively sends a value to the network, average actively re-writes it to a new value. To re-write a format parameter is required which follows usual "sprintf" rules. These rules follow the same pattern as "window" for data type of double, signed int, unsigned int:

%10,average,10.0,%1.2f
%10,average,10
%10,average,10u

Format is only required for double data type.

Example config

This is real-world sample config (of relevant fields only) taken from the dev_nnn.ini file for an infodriver device:

[Data]
SegmentationOffset=100
Filter_0001=%11,block
Filter_0002=%12,window,2
Filter_0003=%13,average,10.0,%1.2f
Filter_0004=%12,window,2.0

Rules are read until a blank/null Filter_xxxx line is reached. The suffix of the key to this field should be an ever incrementing number.

Build: bncs_4.7.5 5800 a1b48197a Atos|Syntel © 2021