This is a very brief guide to configuring the Data Collector using its config file.
The Data Collector is started from a DOS Batch file or Unix Shell script. There are two batch files; one starts the Basic Data Collector; one the Complete GUI Data Collector. The files are in the directory c:\ashtree\bluebox\ and are named blueBoxBasic.bat and blueBoxComplete.bat -> we have no imagination.
The properties files are in the folder c:\ashtree\bluebox\#release number#\appSettings#OS#. Where #release number# is the release number of the product, 008, and #OS# is the type of operating system, WinXp (Windows), OSX (Apple Mac) and Linux (Linux). WinXp gives you an idea of how long we have been using the framework that underlies the Data Collector.
You can open the batch and properties files using Notepad on a Windows computer. If you damage the blueBoxBasic.bat and blueBoxComplete.bat files in this directory (it happens) you can retrieve a copy from the folder c:\ashtree\bluebox\#release number#\install.
Inspecting the batch files you will come to the line that starts the collector. In the basic collector startup batch file it looks like:
%JRE_HOME%\java -Xms524m -Xmx524m com.ashtree.bluebox.runBasicDataCollector %DB_NAME% %APP_NAME% %BLUEBOX_HOME% %OS% %SESSION_ID% -cp BlueBox.jar; GenericComponents.jar
This starts a Java runtime environment and passes in a number of parameters. The Java Runtime Enviroment (JRE) is a software execution environment that runs on your computer. All the software commands that the Data Collector issues are executed in the JRE. There is more information about the JRE at: Oracle Java FAQ.
There are a number of arguments passed to the Data Collector when it is started. These are passed using the command line we have highlighted above. The table below lists the arguments and what they can be used for.
||This is the base directory for the Data Collector installation. The default installation location is c:\ashtree\bluebox\#RELEASE NUMBER#
|| This operating system type for the Data Collector installation. This is primarily used to guide the Data Collector software to the correct properties file.
||This is the name of the application. The Data Collector uses the application name to determine which properties file to read its configuration from. So if the %APP_NAME% variable is set to JENGU_BASIC then the properties will be read from JENGU_BASIC.properties.
||This is the number of the session that you want to record data for. This property is only used by the Basic Data Collector. You specify the session Id to record against using the GUI in the Complete Data Collector. The startup script will prompt for the entry of this value when run. You have two options. Entry a session number for a session that already exists. This will append the data collected to the old sessions. The Data Collector will estimate the values between the end of the existing recorded data for a session and the point at which it is restarted. If you originally started recording this session a couple of days ago it probably makes sense to start a new session. The alternative option is to enter a new Session ID altogether.
||This defines the amount of computer memory you want the Java runtime environment to use. If you have a computer with a lot of memory 8-16GByte you can increase this setting to improve the performance of the application. The default setting should be OK most applications.
||This identifies the database connection properties that the Data Collector uses to connect to the database. The value assigned to the %DB_NAME% variable maps to a set of variables in the properties file. The properties file variables are discussed in more detail in the next section.
In the default installation the collector connects to the database defined in the set of properties that have BlueBoxMySQL in their name.
If you wanted for whatever reason to connect to a database server somewhere other than the local computer you could create a new set of settings for that server.
Looking at the settings:
DBType is the type of database you are connecting to. You could setup a copy of the Data Collector to run on MS SQL Server in which case you would have a value of jdbc:SQL2005. There are other options for this setting. Please contact us if you require further information.
connection_type is the type of connection. In this case database. We also have Web service based connection. The other option for this is WEBSERVICE but this is not used in the deployed version of the Data Collector.
dbuser is the name of the database user that the software is connecting to.
dbpassword is the password for the database user that the software is connecting to. If you change the default user password you will need to update this value.
user is the name of the application user that the software is connecting to. This should not change as the software is setup to use a default application user. If this were the multi user Web Service based implementation then this would be the username for the user logging in.
password is the password for the application user that the software is connecting to. If you change the default user password you will need to update this value. This should not change as the software is setup to use a default application user. If this were the multi user Web Service based implementation then this would be the username for the user logging in.
internal_date_format this is the date format used by the database server that the collector is connecting to. MySQL uses yyyy-MM-dd kk:mm:ss as opposed to SQL Server that uses dd MMM yyyy. You will not normally need to change this setting.
url this is the server, port and database name that the Data Collector is connecting to.
driver this is the name of the java driver file that the collector is using to connect to the database. So if you were to connect to SQL Server instead of MySQL this value would be com.microsoft.sqlserver.jdbc.SQLServerDriver
schema_owner this is the name of the user that owns the actual Data Collector tables. So if you wanted an increased level of security you could set the Data Collector to connect to a user other than the schema owner. This value is required to ensure the Data Collector is selecting data from the correct schema objects.
namespace is defaulted here to be the same as the schema_owner but in practice only takes an effect when you are using a Web Service based connection.
The NMEA Data Collector is built on a Java framework that we have developed and used in a number of applications. So some of the parameters above are not generally used in this application. They do however need to be present in the properties file for the application to start successfully.
How do I Control The Basic Data Collector ?
When using the basic Data Collector the information about the source of the NMEA 0183 data is held in the properties file. The default properties file contains two different connections, one for a TCP/IP data source and one for a COM(serial) data source. (one is commented out)
The properties in the file usually come in the format of a comment followed by the actual value.
#Data Collector Connection Properties
# Protocol: TCP or UDP or COM
A # character will comment out a single line in the file so the segment above is;
a comment (Data Collector Connection Properties)
followed by another comment (Protocol: TCP or UDP or COM)
followed by the actual variable itself (collector_protocol)
The variables are recorded as keyword value pairs. In this case collector_protocol = TCP. The = defines collector_protocol to be equal to TCP. The next table lists all the parameters used to define the data collection for the Basic Data Collector. Its important to match the case of the values when editing the properties file; TCP not tcp.
||Collection method. Protocol: Valid values are : TCP or UDP or COM.
||Give the interface a name : something you can choose for instance ; Bills Data Collector
||The name of the host from which the data is being collected. This can be the either a hostname, ip address or localhost depending on the scenario
||The port on the host that the Data Collector needs to connect on. You will need to read the instructions for your NMEA 0183 data source to find out what this should be.
||The size of the timeslots to use in minutes min 1 max 99 as an integer. The Data Collector is averaging over a variable time period. You can average over anything from 1 to 99 minutes.
||Baud rate that the data source is communicating at. Check your data source documentation for what this should be set to.
||Number of stop bits for the data source. Check your data source documentation for what this should be set to – this is generally not required for TCP connections.
|| Number of data bits. . Check your data source documentation for what this should be set to – this is generally not required for TCP connections.
||Parity indicator. Check your data source documentation for what this should be set to – this is generally not required for TCP connections.
||Flag to indicate just to listen don’t collect so that you can test the interface. This is moderately useful when you are trying to work out why you aren’t getting any data through from your data source.
That’s about it.
Run the installation of the software
Setup the database – you don’t need a license key
Set the connection properties in the properties file.
Start the Data Collector from the Basic Data Icon on the desktop.
Enter the session id when prompted.
Press enter to accept the displayed information.
To get the basic collector to work all you need to do is:
Once its up and running you will see a stream of data collection messages coming down the screen that looks something like that in the image below. These are the same messages that appear in the interface console window on the complete Data Collector.
What else can I control ?
The Data Collector reads a lot of information from the properties file besides that highlighted above.
The table below details some of the more useful properties.
||Set the amount of information that is output to the screen.
Levels 1 to 4
1=Exceptions/Certain status updates
2=Exception/Stop messages/Certain status updates
3=Exception/Stop/Executed SQL/Test output messages/certain status updates
Its worth noting that if you set the level 3 you won’t get Executed SQL unless the property Write_Executed_SQL is set to TRUE.
If you are having issues and can’t work out whats going wrong trying to get the Data Collector working set the debug_mode=4 and the other values in this section to TRUE. That will give you a lot of debug information.
The underlying framework will produce a stack trace if there is an error condition. These will be written to the file C:\ashtree\bluebox\#RELEASE NUMBER#\logs\bluebox.log
||Write to log file. TRUE or FALSE. See the comments above. These will be written to the file C:\ashtree\bluebox\#RELEASE NUMBER#\logs\ generally with a connection name and the date/time stamp.
||Write to console tells the application to write information to the console that the basic Data Collector opens. TRUE or FALSE.
||Put up a dialog message on the screen for Stop and exception messages. TRUE or FALSE. This will suppress any message would otherwise appear on the screen; this is more useful during system testing.
|| Control output from the generic db bean. TRUE or FALSE. The Data Collector uses a database cache to read and write to the database; This property will turn this information off. Its useful for debugging the application and we might ask you to switch this on if we are trying to diagnose a problem.
||Control output from the connection bean. TRUE or FALSE. The connection bean is the part of the Data Collector that talks to the database. Turning this on with the appropriate debug_level value makes the Data Collector display all the SQL (database commands) it sends to the database. This is another we might ask you to switch if we are trying to diagnose a problem.
||Turn on or off the date of the message string for all message other than exceptions. TRUE or FALSE.
||Turn on or off the date of the message string for all message other than exceptions. TRUE or FALSE.
These are the most useful properties on a day to day basis.
How Do I Change The Data Collectors Appearance ?
The final section of the properties file sets the colours of the windows and other components within the application. So for instance the section:
# Colours for UI
Formats the buttons within the application including the colour and font. All the properties are coloured based on Red/Red/Blue values in the range 0-255.
This article gives more information about the way it works and has a handy slider app so you can pick your own colours.
This means that in our properties file the sample below will give all the the buttons in the application a black background and a red foreground.
You need to restart the application for the colour changes to effect.
The colours can only be changed in the Complete GUI based Data Collector.
Black foreground and Black background doesn’t work.
You will need to experiment – a lot – we spent a weeks going from our original Blue prototype to the Black palette that we have today.
Make sure you backup the properties file before you start making changes.
You can mess around with the colours as much as you like but you need to bear a few things in mind.
You can also change the JRE’s look and feel setting but that is probably best left to the experts.
Thats it. If you have any questions about this or any of the other articles we have written please feel free to comment.