v3caplog

V3CapLog - BNCS Network Capture Log

Description

V3CAPLOG.EXE is a 'Capture Log' utility, but also known as 'Captains Log'. It logs to screen and disk all BNCS commands and revertive traffic across the network.

Disk files are date/time stamped so that all the traffic for a single hour is in an individual file. The entries within the files are then time stamped.

CapLog will capture BNCS traffic from "version 2" or later drivers - this means from CSI 1.16 onwards including all current V2, V3, V4, V4.5, V4.6 modules.

CapLog will run from any directory.

V3Caplog Basics

BNCS network traffic

V3Caplog listens to the BNCS network traffic and logs all the commands and revertives to screen and disk.

Caplog can generate very large files containing every message sent on a busy network. Modern disk drives can hold a lot of data but use of automatic utilities to archive or delete old files after a reasonable period of time. There is a BNCS Utility called LogDelet.exe that can be used but read the instructions to ensure only the unwanted files are deleted. In a V4.5 system this deleting is achieved by Workstation Manager and the configuration in logdelete.xml.

Filter settings

Specific BNCS device numbers can be monitored or excluded using the Configuration tab. Filter settings can be saved and recalled.

By default all messages are logged and displayed, the Configuration menu tab allows filtering by device number. Noisy devices such a chattering GPIs, fluctuating levels etc can be excluded from the log if they generate a lot of network traffic making specific events difficult to see. Changes made using the configuration tab are not saved by default and the filter settings from the ini file can be recalled.

Pausing the screen

The screen can be paused by clicking the mouse within the window, or pressing the spacebar.

Log files continue to be saved to disk when the screen is paused. Click again in the screen area to resume display updating.

Screen clear

If the feature is enabled (menu item Window->Double Click Clear) a double touch will clear the screen and continue in un-pause mode, whether or not the screen was previously paused. This feature was introduced particularly for when CapLog is running on a touchscreen.

Always On Top

If this feature is enabled (menu item Window->Always On Top) CapLog will remain on top of other windows.

Log files

Log files are created in the C:\BNCSlogs directory, they can be opened with a standard text editor i.e. Notepad.

A new file is started each hour. Caplog file naming convention is ‘YYYYMMDD.HH’ where YYYY is the Year, MM is the Month, DD is the Date and HH is the hour of the day 0-23. The current log file name is shown in the application title. The default directory for the log files is ‘C:\BNCSlogs’, this is set in the caplog.ini file

The information contained in the log files can be searched with text utilities i.e. Windows GREP (shareware) for lines containing a specified Command or Revertive pattern and can display a number of lines either side of the match to convey the context of the event. This is a very useful technique for hunting down specific events in a folder full of large text files (set filetype to . or to the exact hour if known)

To import information into a spreadsheet – the log is a text file, the Delimiter is a ‘Space’ and the Text Qualifier is {none}. Refer to spreadsheet help file for import and filtering techniques. There are a number of other utilities written by the developer community for analysing the log files.

Command Line

From version 3.14.11 V3CapLog has the following command line options usually taken from csi.ini or bncs_system.ini:

Optional Command Line Parameter | Notes
/CHANNEL=0 | Override of channel number
/ADAPTOR=0 | Override of adaptor number

These were added so that more than one V3CapLog could be run on a single machine monitoring more than one network adaptor.

V3CapLog Advanced Features

Caplog.ini File

A CAPLOG.INI file contained in the appropriate location for your BNCS system will be created that allows commands and revertives for each driver to selectively filtered out. There are separate sections for both of these. CapLog should be restarted after any changes have been made to the INI file. A '0' against an entry will mean that the device will be ignored, a '1' means it will be logged. From version 1.00.11 there is a [WatchDog] in the CAPLOG.INI file. An InfoDriver Id and slot number can be specified. Every minute the date and time will be written to the InfoDriver indicating that CapLog is still functioning. If either of the parameters is set to zero then the feature is disabled.

Caplog.ini file can be viewed and edited using a simple text editor such as Notepad. An application restart is required after making changes.

Section/Entry/Default | Notes
[Network] |
Channel=0 | Use same channel setting as CSI
ShowURheader=1 | Hide/Show Universal Revertive header & message count
ShowNxMessages=1 | Hide/Show background network messages
ShowPacketSerial=1 | Hide/show packet serial numbers
ShowHeartbeats=1 | Hide/show heartbeat packets
ShowPacketRecovery=1 | Hide/show packet recovery traffic
SavePackets=0 | Save message packet to file
CommandReplayEnabled=0 | Enable Command checkbox for replay selection from packet file
RevertiveReplayEnabled=0 | Enable Revertive checkbox for replay selection from packet file
MillisecondDisplay=0 | Enable display of time in milliseconds.
[Watchdog] | An Infodriver slot can be updated every minute with Date and Time, used to indicate Caplog still functioning.
InfoDriver=0 |
InfoSlot=0 |
[Paths] |
LogFilePath=c:\bncslogs | Default path to log file directory
[Commands] |
Device_nnn=1 | Hide/Show device commands (also set by Menu Configure tab) - where nnn is device number 1 - 999
[Revertives] |
Device_nnn=1 | Hide/Show device revertives (also set by Menu Configure tab) - where nnn is device number 1 - 999
[Time] |
SetSystemTime=1 | Whether to set the system time from incoming TS messages (generated from CSI where time server is enabled). It was found that if you run CapLog on a machine that is also the time server, Windows can get confused and would apply the DST autumn offset (an hour back) at the end of every hour meaning it would repeat the 0100-0159 hour ad infinitum

Note - the Command and Revertive filter settings can be modified using the Configure panel without requiring Caplog restart. Changes are not saved by default.

Temporary Information

Temporary information about the windows position is (from version 3.11) located in the file Caplog.tmp in the "temp" folder.

Section/Entry | Notes
[Coordinate] |
XCoord=xxx | coordinate of the caplog window.
YCoord=yyy | Y coordinate of the caplog window
Width=www | width of the caplog window
Height=hhh | height of the caplog window

Analyse log and packet files

Analysing a selected log file shows the timestamps when caplog and the packet data files where opened and closed etc during the logging period but not the actual message data.

Packet Analysis

Entire message packets can be saved for detailed examination offline

Caplog will save packet data files in the specified logs directory if the ini file setting for ‘SavePackets’ is changed from default ‘0’ to ‘1’ and Caplog restarted. The packet data files can get extremely large.

A selected packet data file can be opened from the Packet menu tab and viewed for detailed system analysis.

Command and Revertive packets can be replayed from a predetermined point either in Single Steps or as a continuous sequential Replay at a preset Rate (set time in ms)

The ini file settings for Command and Revertive Replay Enable/Disable the ‘Cmds’ and ‘Revs’ replay option checkboxes. The default is for them to be disabled.

Warning - On a live system the packet replay feature of Caplog should be left in the disabled mode and files taken for examination offline, the replay of commands out of time and context could have unexpected side effects!

Watchdog

There is an option to send Date and Time stamp to a specified infodriver slot every minute.

Enter valid Infodriver and Slot numbers into Watchdog section of caplog.ini file and Caplog will update the slot every minute with a Date and semi colon delimited time stamp eg:

IW 100 '29-10-2007 - 14;38;31' 1

This can be used by an alarm system to determine that Caplog is still active and functioning.

Copy screen to clipboard

Version 3.14.03 introduces a "copy to clipboard" function where hitting the 'C' key will copy the currently displayed text to the clipboard.

CapLog Dependencies

CapLog looks for BNCS_CC.dll (custom control buttons) in the usual system directory for the BNCS version you are using.

From V3CapLog 3.15 the external DLL packetRecoveryListener.dll is no longer required. Packet recovery traffic monitoring is also supported on 64 bit OSs with this version.

Known Issues

CapLog has issues displaying/recording "version1 " device messages - this refers to devices that were written before introduction of CSI 1.16 (which curiously supports version 2 messaging).

There are no currently supported "version 1" network devices.

Caplog External Message Rewriting/Filtering

CapLog filtering/analysis can be extended with external module.

CapLog has a couple of simple hooks to allow data to be manipulated before it hits the screen and disk log.

Mechanism

At startup CapLog looks to see if it can load an external DLL called "caplogMessageRewriter.dll" - if it can it enables the appropriate menu item: Show->Interpret Messages.

When this menu item is selected it loads the DLL and resolves the function with the name "MessageRewrite". This has the signature:

int MessageRewrite( const char* in, char ** out )

Where the parameters are:

Param | in/out | Notes
in | input | pointer to the single line to be written to the log
out | input / output | pointer to array of 32 pointers of values to write to the log

Return value of this function is the number of values set in the out array - corresponding to the number of lines to write to the log. This can be zero so nothing is written.

Before writing any line to the log CapLog calls this function.

The following is a very simple example of its use:

int MessageRewrite( const char* in, char ** out )
{
    // this is the number of things we're returning - this might remain zero if we want to filter a message out
    int count = 0;

    // retain the original message
    out[ count++ ] = (char*) in;

    // append an additional line - NOTE: pointers must remain in scope when this function exits
    out[ count++ ] = "blibble";
    return count;
}

Runtime Edit

There is a second exported function which enables run-time editing of the settings for this extension DLL:

This has the following signature:

void MessageRewriteEdit( HWND hWndParent )

Where the parameters are:

Param | in/out | Notes
hWndParent | input | Handle of the parent application

Typically this would have an implementation something like this:

// this is our exported function that V3caplog will call to initiate the editor
void MessageRewriteEdit( HWND hWndParent )
{
    DialogBox( ghInstance, MAKEINTRESOURCE( IDD_DIALOG1 ), hWndParent, (DLGPROC) DialogProc );
}

Note that it's important to use a DialogBox with parent set so that the dialog retains focus - otherwise the user can deselect the Show->Interpret Messages menu item and unload the DLL causing a crash.

DLL File Location

"caplogMessageRewriter.dll" is loaded from "the usual" DLL path for your system:

Version | Path
V2 | c:\windows
V3 | Value set by: [Config] SystemPath=w:\v3 entry in c:\bncs_config.ini
V4.5 | %CC_ROOT%\%CC_SYSTEM%\windows\lib

Version Control

Version | Date | Comments
1.00.00 | 22/05/97 | First release
1.00.01 | 06/10/97 | Bug fix to length of text scrolled
1.00.02 | 05/11/97 | Catches Universal Revertives Flying file handle implemented Improved revertive handler
1.00.03 | 17/02/98 | Added primitive filtering
1.00.04 | 03/03/98 | Bug fix to prevent long commands crashing
1.00.05 | 22/03/98 | Commands now split onto seperate lines Message index now printed out
1.00.06 | 25/03/98 | Pressing the space bar toggle printing to the screen
1.00.07 | 06/04/98 | Now reliably changes filename at date rollover
1.00.08 | 19/05/98 | Clicking on client area toggles screen writes Added packet header info
1.00.09 | 03/06/98 | Now locks time to CSI's time service messages
1.00.10 | 19/06/98 | Now opens new log file every hour
1.00.11 | 28/06/99 | Now sends the time and date to an InfoDriver slot as a watchdog every minute
1.00.12 | 21/02/00 | Added access to the 100 network channels feature in CSI 1.17.03
1.00.13 | 19/06/00 | Network Attention message now used by CSI 1.18.xx and later. Removed ambiguous message. Added CSCmd_NetInquire() and CSCmd_NetObject()
1.00.15 | 11/01/01 | Tidied up presentation of 'Network' (Nx) messages
1.00.16 | 16/08/01 | Added log file path to INI file.
1.00.17 | 03/10/01 | Added log analysis function
1.00.18 | 20/03/02 | Added option in INI file to toggle display of N series messages
1.00.19 | 07/05/02 | Mod to filtering of N series messages
1.00.20 | 03/09/02 | Now logs Network Loopback (NL) messages
1.00.21 | 02/05/03 | Now correctly logs commands to device 999
x.00.22 | 04/08/03 | Compiled to be 32 bit
x.00.23 | 10/11/03 | Added configure system
3.01.00 | 29/04/04 | Added packet saveing and replaying mechanisms
3.01.01 | 11/01/05 | Bug fix to CSCmd_UniRevertive() in filtered mode to not discard messages in a packet that follow a disabled Id messsage
3.02.00 | 25/05/05 | Added Net Status handler
3.02.01 | 24/06/05 | No longer crashes when pressing 'Cancel' in Packet Open File dialog Can now only open one instance of the Config & Packet dialogs Only displays that it cannot open log files once, then exits Attempts to create log file directory on start up On packet dialog pressing 'Previous' stops at packet 1
3.02.02 | 27/06/05 | Bug fix to repeat selection of Config & Packet dialogs
3.02.03 | 04/07/05 | Brings up a message box if BNCS_CC.DLL is missing and exits
3.03.00 | 19/09/05 | Reinitialises after network disconnection Now displays originating workstation in universal header message Now displays target workstation for each message in packet.
3.03.01 | 24/11/05 | WndProc definition changed to be LRESULT CALLBACK to correct painting corruption
3.03.02 | 07/12/05 | Now correctly decodes workstation Ids greater than 256
3.03.03 | 22/12/05 | Added NetBroken handler
3.04.00 | 15/02/06 | Now uses GetConfigDirectory in bncs_gcd.cpp/h wParam masked in Dialog procedures to correct list box selection problem
3.04.01 | 14/03/06 | GetConfigDirectory() now GetBNCSConfigDirectory()
3.04.02 | 29/03/06 | Now uses GetBNCSSystemDirectory for LoadLibrary() calls
3.04.03 | 06/06/04 | Bug fix to V1 revertive handlers
3.04.04 | 20/04/06 | Bug fix to correctly store packet length in PKT files
3.05.00 | 06/04/07 | Build from CVS
3.05.01 | 11/10/07 | Now uses v4/3 directories for config and libraries
3.06.00 | 21/08/08 | Bug fix to V1 GPI revertive handler to correct for maximum header size not having null terminator Uses import library from new BBCNB32B.DLL containing session status calls (not yet used in V3CapLog)
3.06.01 | 26/09/08 | Increased maximum length of dispayed line in scrolling window from 127 to 300 Now filters Router Modify messages as well as commands and revertives based upon device id filter
3.06.02 | 02/10/08 | Fixed memory leak caused by _fstrcpy copying excessive spaces without null terminator
3.07.01 | 16/03/09 | Shows serial number indication to revertive packets that support them
3.07.02 | 19/03/09 | Shows serial number indication to command packets that support them
3.08.00 | 08/06/09 | Menu items for UR, N and serial number display toggle
3.08.01 | 08/06/09 | Sets background brush for the class type to the same colour as the draw text - doesn't really reduce the flashing but makes it less objectionable
3.08.02 | 11/06/09 | Minor fix to explicitly set the state of the show packets flag properly on first run
3.08.03 | 27/08/09 | Writes log file configuration path AFTER setting the path variable as to where to write it
3.09.00 | 01/10/09 | Replaces newline chars in logged messages with spaces Has simple understanding of heartbeat messages for CSI32 enhancements
3.09.01 | 21/12/09 | Fixed the flickering of screen on resizing. The information in the generated log files goes as per the needs stated in bugs 1535, and, there is no resetting of network settings on closing the caplog (bug 1536).
3.10.01 | 19/01/10 | Has better understanding of heartbeat messages and reports heartbeat workstation number correctly (network byte ordering)
3.10.02 | 22/02/10 | adds workstation number to each individual serial number entry corrects handling of heartbeat header size
3.10.03 | 04/01/11 | removes copies of data that were of insufficient size (causing crash) massages a few buffer sizes to be things like MAXPATH rather than random values
3.10.04 | 11/02/11 | 1. csi.ini path issue is resolved [Bug id 1871] 2. Horizontal wrapping of text is implemented as per the requirement [Bug id 1710] 3. [Bug 331] window last size is remembered for next session. 4. [Bug 331] caplog.ini path is written below the title bar.
3.10.05 | 14/03/11 | [Bug 331] caplog.ini path is visible using the menu item help -> path.
3.10.06 | 29/03/11 | [Bug 2006] Double click screen clear for touchscreen use
3.10.07 | 30/03/11 | [Bug 2006] Improved Double Click to clear then continue in non pause mode
3.10.08 | 31/03/11 | Optimisation and performance improvements DGY
3.10.09 | 01/04.11 | Merged versions 3.10.07 and 3.10.08
3.10.10 | 02/05/11 | Resolved the path issues for the default adaptor for v3 and v4 system and add new msg box to display the default adaptor path using the menu item HELP->Default Adaptor Path.
3.11.00 | 19/05/11 | uses external DLL to add packet recovery messaging also has simple colouring for packet recovery and N messages
3.11.01 | 20/05/11 | adds understanding of close message in heartbeats
3.11.02 | 23/05/11 | fix to packet recovery listener so if the feature is enabled but the DLL not present it fails gracefully rather than popping up a msgbox
3.11.03 | 23/05/11 | Closedown heartbeat now marked as such rather than a "0 secs" update rate
3.11.04 | 01/09/11 | Bug2099 - Fixed - V3Caplog colours not consistent on multi-line entries (for network messages)
3.11.05 | 29/11/11 | Bug2161 - Fixed - V3Caplog text wrap colour (for heartbeat messages)
3.11.06 | 02/12/11 | Bug2171 - Fixed - Resize limit for V3Caplog window to prevent crash
3.11.07 | 05/01/12 | Now recalls window position on startup (path not set) and adds long overdue "always on top" menu option
3.11.08 | 25/03/12 | Validation of incoming heartbeat messages
3.12.00 | 11/03/12 | Hooks for external rewriter application (allows filtering, text replacement)
3.13 | ?????? | ?
3.14.00 | 14/06/12 | Changes compiler to MS (resource conversion Richard Kerry). Integrates Help. Reading/creating device filter optimised (virus checker issues with 2000 individual file operations)
3.14.01 | 15/06/12 | Clarifies version history for resources. Writing device filter now done with optimised code (when you hit the save button on the device filter dialog)
3.14.02 | 15/06/12 | Turns screen red when paused (a Tim Hall feature request). Also updates the title bar properly when you press the keyboard to pause the display
3.14.03 | 18/06/12 | Adds mouse wheel support. Adds support for keyboard up/down/pageup/pagedown. Adds copy-to-clipboard of whatever is currently displayed (hit c) Makes V scrollbar.....scroll....and tidies up how it's used
3.14.04 | 18/06/12 | makes device filter dialog a popup create dialog rather than a child dialog
3.14.05 | 19/06/12 | fix to ensure we don't randomly overwrite the end of message rewriter strings
3.14.06 | 26/06/12 | Now shows client and driver heartbeats and inserts serial numbers (if show serial numbers is enabled) First "proper" VS release
3.14.07 | 03/07/12 | Very silly mistake crossing day/month values in Borland/Microsoft date/time compatibility classes
3.14.08 | 03/07/12 | Speculative fix to trap divide by zero error (where values shouldn't be zero)
3.14.09 | 06/07/12 | Corrects inaccuracy in version history for 3.14.07 Timestamps are sent with hundredth values from Borland-based CSIs, and thousandths from Microsoft-based CSIs....CapLog always expecting hundredths so a conversion applied
3.14.10 | 14/12/12 | Makes max line display length 2048 to cope with expanded heartbeat strings
3.14.11 | 22/07/13 | allows command line override of channel and adaptor number
3.15.00 | 15/10/13 | now doesn't use external DLL for packet recovery messages but uses normal NetBIOS "buffers" - this means it'll work on Win7/64
3.15.01 | 11/11/13 | now filters RD messages according to the revertive filter
3.15.02 | 11/09/14 | Window position/size configuration file (caplog.tmp) now in "temp" folder. Option now available for times to be displayed in milliseconds - use [Network]MillisecondDisplay.
3.15.03 | 02/07/15 | Removes definition of max devices (twice) in CapLog's own header file in favour of the shared one in bncs.h
3.15.04 | 21/07/15 | Sticks a label across the top of the screen if the device filter has any devices filtered out
3.15.05 | 19/10/15 | Minor changes to keep the VS2013 build of this app happy. Adds map file
3.15.06 | 29/10/15 | New config setting (with legacy default) to allow turning off of setting local clock from incoming TS message
 | 27/02/2017 | Conversion to markdown
Build: trunk 4125 Atos © 2017