bncs_log

Log Controls

Overview

This document describes 3 controls for use on BNCS user interfaces, these are:

Log Control

A relatively complex component specifically designed to display log information written to a database by the Alarms Databse output module.
This is not a general purpose database display component.

Database Table Viewer

A general purpose component to display and edit an SQL database table.

Database Form Control

A general purpose component to get data from an SQL database and display it in other controls.

Description

All of these controls obtain data from an SQL database via the Qt SQL database components. At the time of writing the following drivers have been confirmed to work (there is some driver-specific handling present, so other drivers may not work): -

  • QODBC3 – ODBC driver, including Microsoft SQL Server
  • QMYSQL3 – MySQL driver

Log Client

Description

This control provides a display of items logged to an alarms log database, along with dynamic updates communicated using the alarms database module’s infodriver interface.
The control may be configured to only show a single message for each process, thus showing only the current state rather than the history.
Various filters can also be applied to the data to restrict what is shown.

Configuring the Control

The control can be configured entirely at panel design time using the BNCS Visual Editor, or at run-time, by setting parameters from a BNCS client.
Changing the settings at run time, for instance changing the filtering, may be done by sending the relevant command from a script.
The following table lists the commands that may be sent to the control using the textPut function in a script.

Database settings

Name | Values | Description
dbDriver | QMYSQL3 QODBC3 Default is blank | Database Driver type QMYSQL3 – for MySql QODBC3 – for ODBC main
Host | 192.168.0.1 (example) Default is blank | Name or address of the computer running the database server
Database | bncs_alm (example) Default is blank | Database name
User | Bncs (example) Default is blank | User name to access the database
Password | Bncs (example) Default is blank | Password used to access the database
dbEnable | true (default) false | Whether to use the main database.
dbDriver_reserve | QMYSQL3 QODBC3 Default is blank | Database Driver type QMYSQL3 – for MySql QODBC3 – for ODBC reserve
Host_reserve | 192.168.0.1 (example) Default is blank | Name or address of the computer running the database
Database_reserve | bncs_alm (example) Default is blank | Database name
User_reserve | Bncs (example) Default is blank | User name to access the database
Password_reserve | Bncs (example) Default is blank | Password used to access the database
dbEnable_reserve | true (default) false | Whether to use the reserve database.

Display Settings

Name | Values | Description
ShowDateTime | true (default) false | Display the date & time column
ShowMsec | true (default) false | Display milliseconds with time
ShowGroup | true (default) false | Display the group column
ShowDevice | true (default) false | Display the device column
ShowLocation | true false (default) | Display the location column Data for this is retrieved from instances.xml using the device field value as the instance name.
ShowProcess | true (default) false | Display the process column
ShowState | true (default) false | Display the state column
ShowLevel | true (default) false | Display the level column
ShowText | true (default) false | Display the text column
ShowSingleInstance | true (default) false | Selects which table is displayed. True for process_data. False for historical_log.
MaxShow | 500 | Maximum number of lines to be shown
scrollMode | Auto (default) Never Always | Sets the scroll mode, options are Auto - when a user selects an entry, stops scrolling for 30 seconds. Never - doesn’t scroll. Always - always scrolls so that new log items are visible.
SortAscending | true (default) false | Sets the display order True – ascending False - descedning
OrderBy | Date & Time (default) Group Device Process State Level Text | Sets the column to order by.
notify.pressed | true (default) false | Enables notify messages to be sent when the control is pressed.
notify.changed | true (default) false | Enables notify messages when the current selected item changes. This may be because of user action, or an item added to the log.
width.dateTime | Integer (default is 200) | The width of the Date & Time column Widths are in pixels
width.group | Integer (default is 100) | The width of the group column
width.device | Integer (default is 100) | The width of the device column
width.location | Integer (default is 100) | The width of the device column
width.process | Integer (default is 100) | The width of the process column
width.state | Integer (default is 50) | The width of the state column
width.level | Integer (default is 100) | The width of the level column

Filter commands

All filter commands should start with Filter, which is not shown here.
Examples:

Filter.Level.Info=true
Filter=Clear
Filter.Devices.set=a;b;c
Name | Values | Description
=Clear |  | Clear the filter
.Devices .Groups .Processes .Text |  | The following three commands apply to these four fields
set | set=a;b;c (example) | Clears the current filter and sets the filter string list to only display a or b or c
add | add=d (example) | Adds d to the current filter list
subtract | subtract=c (example) | Removes c from the current filter list
.Level.All | true (default) false | Show entries with this level. All means show all levels. All other values means show the stated value. These may be mixed in any combination. Setting All to true will set all the individual level filter values to true. Setting All to false will not change the individual level filter values.
.Level.Info | true (default) false |
.Level.Minor.Warning | true (default) false |
.Level.Major.Warning | true (default) false |
.Level.Minor.Alarm | true (default) false |
.Level.Major.Alarm | true (default) false |
.State.All | true (default) false | Show entries with this state. All means show all states. All other values means show the stated value. These may be mixed in any combination. Setting All to true will set all the individual state filter values to true. Setting All to false will not change the individual state filter values.
.State.On | true (default) false |
.State.ForceOn | true (default) false |
.State.Off | true (default) false |
.State.ForceOff | true (default) false |
.State.Ack | true (default) false |
.State.Ignore | true (default) false |
.State.Latched | true (default) false |
.State.Unknowntrue (default) false |
.Date=Clear |  | Clear the date filter
.Date.Before=yyyy-MM-dd | A date | Show items before this date
.Date.After=yyyy-MM-dd | A date | Show items after this date
.Date.Between=yyyy-MM-dd + yyyy-MM-dd | Two dates | Show items between the two given dates. ‘+’ should be used to separate the two dates.
.Date.DaysBack=n | Integer | Show items up-to n days back
.Date.CompareMode | Inclusive Exclusive (default) | Selects whether date comparisons (before, after, between, days-back) are inclusive or exclusive. Inclusive means use <= and >=. In this case “After” a date means “on or after” the date, etc. Exclusive means use < and >. In this case “after” a date means strictly after it, ie a time on the specified date will be rejected by the filter.
.DateTime=Clear |  | Clear the date/time filter
.DateTime.Before=yyyy-MM-dd hh:mm:ss | A date and time | Show items before this date/time
.DateTime.After=yyyy-MM-dd hh:mm:ss | A date and time | Show items after this date/time
.DateTime.Between=yyyy-MM-dd hh:mm:ss + yyyy-MM-dd hh:mm:ss | Two dates and times | Show items between the two given date/times. ‘+’ should be used to separate the two date/times.
.DateTime.CompareMode | Inclusive Exclusive (default) | Selects whether date/time comparisons (before, after, between) are inclusive or exclusive. Inclusive means use <= and >=. In this case “After” a date/time means “on or after” the date/time, etc. Exclusive means use < and >. In this case “after” a date/time means strictly after it, ie a date/time the same as the specified date/time will be rejected by the filter.

Miscellaneous

Name | Values | Description
reset |  | Resets all settings to the default
BncsDriver | Integer, or comma-separated list of integers. | BNCS Driver, or drivers, from which dynamic updates will be received.
stylesheet.style | A style name. Default is blank – no style specified. | Sets the style sheet for fonts etc., these need setting in stylesheet.xml, if not found the default will be used.
stylesheet.states | A style name. Default is blank – no style specified. | Sets the style sheet for colours, these need setting in stylesheet.xml, if not found the default will be used.
Slave.Navigate | A button name. Default is blank – no button specified. | Slave button for navigation. When a line this control is selected, if slave.navigate is set to the name of another control that other control will have its “navigatedest” parameter set to the device name field of the newly selected line.
Slave.Form.Device=form1 | A button name. Default is blank – no button specified. | Database form to show device details. When a line this control is selected, if slave.form.device is set to the name of another control that other control will have its “Filter.Set=device_name” parameter set to the device name field of the newly selected line.
PrintAll |  | Prints all of the log table
Print=+-10 |  | The currently selected item +- 10, options are +-n, +n or –n.

Returns

Name | Description
return=<setting> | Returns the setting, i.e. return=BncsDriver will return the BNCS driver number. This may be used with any of the settings listed above.
Return=all | Returns all non-default settings in a single string with the settings each terminated by a new-line character.
return=Log.Device | Returns the device field of the currently selected line.
return=Log.Process | Returns the process field of the currently selected line.
return=Log.Group | Returns the group field of the currently selected line.
return=Log.All | Returns the entire currently selected line item in the form : Date/time,millisecond time,process ID, Device name,group,level,state,text

Style Settings

The following settings may also be used to set colours and fonts, but their intended use is by the stylesheet. The colours may be expressed as RGB levels (#RRGGBB) or colour names recognised by Qt.

colour.info.background=#00ffff
colour.info.text=#cccccc
colour.ok.minor.warning.background=#cccccc
colour.ok.minor.warning.text=#448844
colour.ok.major.warning.background=#ddccdd
colour.ok.major.warning.text=#44ff44
colour.ok.minor.alarm.background=darkGreen
colour.ok.minor.alarm.text=blue
colour.ok.major.alarm.background=#ff88dd
colour.ok.major.alarm.text=#yellow
colour.fail.minor.warning.background=#ffff8
colour.fail.minor.warning.text=#880080
colour.fail.major.warning.background=#80fff
colour.fail.major.warning.text=#ff0080
colour.fail.minor.alarm.background=darkBlue
colour.fail.minor.alarm.text=dddddd
colour.fail.major.alarm.background=#ff0f00
colour.fail.major.alarm.text=#ff80ff
colour.latched.alarm.text=#ffffff
colour.latched.alarm.background=#808000
colour.latched.warning.text=#808000
colour.latched.warning.background=#ffffff
colour.ack.alarm.text=#ffffff
colour.ack.alarm.background=#ff8000
colour.ack.warning.text=#ff8000
colour.ack.warning.background=#ffffff
colour.other.background=#cccccc
colour.other.text=#000000
font=arial
fontsize=12 (or relative e.g. –2)

Defaults and Returning All

Where a setting is set to its default value a subsequent call to read all values (ie “return=all”) will not return any data for that setting.
The following will always be returned, even if not set: dbEnable, dbDriver, Database, Host, User, Password, dbEnable_reserve, dbDriver_reserve, Database_reserve, Host_reserve, User_reserve, Password_reserve.

Examples

The following examples show setting the control to show a limited set of information.
Show all items from the database.

textPut("Filter","Clear",1,5);

Show only active alarms, i.e. those with state equal to On.

textPut("Filter","Clear",1,5);
textPut("Filter.State.On","true",1,5);

Show only alarms in the ‘Network’ group.

textPut("Filter","Clear",1,5);
textPut("Filter.Groups.set",”Network”,1,5);

Show alarms from any ARC device.

textPut("Filter","Clear",1,5);
textPut("Filter.Device.set",”ARC%”,1,5);

Using a regular expression to select specific ARCs, in tnis case 1-5

textPut("Filter.Device.set",”ARC[1-5]”,1,5);

Notifications

The following notification messages are emitted if the control is configured to do so.

Parameter | Notes
button.<name>=pressed | The control has been pressed. <name> is the name of the log control.
button.<name>=logItemChanged | The current log item has changed, this may be because the user has changed the selection, or an item has been added to the log. <name> is the name of the log control.

Enabling use in the BNCS Visual Editor

In order that controls of this type may be created in the Visual Editor, an element must be present in config/vised/buttons.xml with the “class” attribute set to “bncs_log”.
The “name” attribute selects the name that will appear in the Buttons tab.
For example:

<control class="bncs_log" name="Log" />

Data Form (db Form)

Description

This control allows a user to traverse a database table showing only the required fields in a single entry. This is done by using other standard buttons to display/edit the data.

Configuring the Control

The control can be configured entirely at panel design time using the BNCS Visual Editor.
Changing the settings at run time, for instance changing the filtering, may be done by sending the relevant command from a script.
The following table lists the commands that may be sent to the control using the textPut function in a script.

Database Settings

Name | Values | Description
dbDriver | QMYSQL3 QODBC3 Default is blank | Database Driver type QMYSQL3 – for MySql QODBC3 – for ODBC
Host | 192.168.0.1 (example) Default is blank | Name or address of the computer running the database server
Database | bncs_alm (example) Default is blank | Database name
User | Bncs (example) Default is blank | User name to access the database
Password | Bncs (example) Default is blank | Password used to access the database
Table | Names (example) Default is blank | Database table to display
reset |  | Resets all settings to the default

Slave Settings

Name | Values | Description
Slave.Field.Add | <field>,<button> | Display database field <field> in button <button>.
Slave.Field.Clear | true | Clear all fields.

Filter commands

Name | Description
Filter=Clear | Clear the filter
Filter.Set=”device_name=’SAT1’” | Sets the filter only to show what is entered. This accepts standard SQL query conditions that may be entered in a WHERE clause, i.e device_name LIKE ‘SAT%’. Note that % is used as the multiple character wild card (zero or more characters) and ‘_’ is the single character wildcard.

Enabling use in the BNCS Visual Editor

In order that controls of this type may be created in the Visual Editor, an element must be present in config/vised/buttons.xml with the “class” attribute set to “bncs_data_form”.
The “name” attribute selects the name that will appear in the Buttons tab.
For example:

<control class="bncs_data_form" name="db Form" />

Data Table (db Table)

Description

This control shows the entire contents of a database table in a table view, and can allow the user to edit the table.
This control displays a column for every field defined in the table.

Configuring the Control

The control can be configured entirely at panel design time using using the BNCS Visual Editor.
Changing the settings at run time, for instance changing the filtering, may be done by sending the relevant command from a script.
The following table lists the commands that may be sent to the control using the textPut function in a script.

Name | Values | Description
dbDriver | QMYSQL3 QODBC3 Default is blank | Database Driver type QMYSQL3 – for MySql QODBC3 – for ODBC
Host | 192.168.0.1 (example) Default is blank | Name or address of the computer running the database server
Database | bncs_alm (example) Default is blank | Database name
User | Bncs (example) Default is blank User name to access the database
Password | Bncs (example) Default is blank | Password used to access the database
Table | Names (example) Default is blank | Database table to display
reset |  | Resets all settings to the default
ReadOnly | true (default) false | Sets the table to read only.

Enabling use in the BNCS Visual Editor

In order that controls of this type may be created in the Visual Editor, an element must be present in config/vised/buttons.xml with the “class” attribute set to “bncs_data_Table”. The “name” attribute selects the name that will appear in the Buttons tab.
For example:

<control class="bncs_data_Table" name="db Table" />

Developer Notes

There are now a number of test applications associated with this control, existing in subprojects. Two of these – TestApp and TestApp4 –are focussed on testing the filtering aspect of the library.
TestApp – tests include:

  • caption setting and getting
  • “update” filter logic
  • Sql query statement generation (confirms operation of decodecaptionstring – not of continued usefulness)

TestApp4 – tests include:

  • Actual SQL queries on a real database. This uses the same test data as TestApp so will confirm that the two achieve the same results.

These two should be used to confirm that existing behaviour is not affected by any further development of filtering. They should be updated to cover any new functionality in any further development of filtering.

The other projects – TestApp2 and TestApp3 – are not of continued usefulness.
TestApp2 does the minimum to create a Log Control and display it.
TestApp3 was used to confirm how to programatically access the Sql database.

Version Control

Version | Date | Author | Comments
1.0.0.8 | 22/9/2004 |  | Set not to get blank entries from the database, these would are not displayed anyway!
4.5.0.1 | 04/10/2004 |  | Temporary version to stop crashing when there are slow database connections, this does not allow the database to be changed once set!!!!! Use only in W12
4.5.0.2 | 12/10/2004 |  | Fixed fault known in 4.5.0.1. Displays detail about the host while attempting connection.
4.5.2.0 | 23/10/2007 |  | Fixed SQL statement error for MS SQL server.
4.5.3.0 | 24/10/2007 |  | Removes old database connection when changing types.
4.5.4.0 | 08/11/2007 |  | Fixes sorting issues.
4.5.5.0 | 19/02/2008 |  | Horizontal scroll bar inhibited in the log. Regular expression filtering added to the log.
 | ??? |  | Dunno No record
4.5.11.0 | 27/10/2008 |  | Rebuilt using new shim (based on ccClient)
 | 02/07/2013 |  | Corrections to document.
4.5.18 | 10/06/2015 | Richard Kerry | Log Control will now show data from the Database Output module that arrives from the InfoDriver without the database itself needing to be connected. This may arise when there are problems with connectivity, or a fault in the configuration meaning the database can’t be opened.
4.5.19 | 01/09/2015 | Richard Kerry | Date/Time filtering added. Between added for dates or date/times. Mode added for dates or date/times – search may be inclusiove or exculsive. (Tests added to confirm expected behaviour)
4.5.20 | 27/02/2017 | David Yates | Conversion to markdown minor revisions
Build: master 3586 0d983c63 Atos © 2018