Defining a Database Connection Class

By default, VR-Forces will not perform any database logging. Database logging can be enabled by editing the appData\settings\databaseConfig.mtl file to specify a valid database logger and database connection.

The database logger is the class the sim engine code will interface with in order to log events. It stores events in a queue. See the DtVrfDatabaseLogger class for more details. To enable the database logger, specify "standard-database-logger" as the database-logger-type in databaseConfig.mtl.

The database connection is responsible for popping events off of this queue and logging them to the database. The database connection will spawn a new thread which runs in the background, popping events as they become available and then sending them to the database. See the DtVrfDatabaseConnection class for more details.

The only built-in database connection is for SQLite, which will log all events to a local SQLite database file. This is implemented by the DtVrfSqliteDatabaseConnection subclass of DtVrfDatabaseConnection. It is configured by specifying "sqlite-database-connection" for your database-connection-type in databaseConfig.mtl.

This plugin adds a new database connection type for MySQL server. It is a fully functioning example and can be used as-is to connect to a MySQL server and log events. It also provides a starting point for you to develop your own plugins to connect to other SQL server implementations. To use this connection, you need to load the plugin and specify a database-connection-type of "mysql-database-connection". See the DtVrfMySqlDatabaseConnection class in this example for more details.

In addition to specifying the names of the database logger and database connection to use, the databaseConfig.mtl file also contains settings about how the connection should connect to the server or log to the database file. Some settings are only relevant to one implementation or another.

Database Events

VR-Forces defines several different types of database events. Events are logged to the databse logger whenever something occurs in the sim that should be logged. Events include things such as the start of a new scenario run, the creation of an entity, the usage of a resource, a detonation, undertaking damage, or detecting other entities. Each event type maps to a table in the database. As events occur, they are logged to their matching database table. For more on database events, see the DtVrfDatabaseEvent class as well as the list of default events defined in the section VR-Forces Database Events.

How to Run the Example

Building

In order to build this example you will need the MySQL Community Client, which is not included with VR-Forces. VR-Forces builds against version 8.0.37. See the following website for downlaods: https://dev.mysql.com/downloads/c-api/

Configuring

First, you must setup a MySQL server. Please visit the MySQL website to download the MySQL Community Server. MAK has tested this with version 8.0.37.

The appData\settings\databaseConfig.mtl file set the following: (database-logger-type "standard-database-logger") (database-connection-type "mysql-database-connection")

Note if using one of the python scripts, make sure python has the mysql-connector-python installed

Set the host-ip, port, username, and password settings in order to connect to your MySQL database server.

Running

Since this example is loaded as a plugin, it will need to be enabled in the Launcher. In the Launcher, click the Plug-ins button to bring up the Plug-ins Selection dialog. Enable the plugin.

Start vrfGui.
Start vrfSim.
Create or load a scenario.
Events will be logged to the database as they occur.
View the database with your own client applications or using one of our simple Python examples. See the Database Clients (databaseClients) examples for more information.

Plugin Entry Points

/*******************************************************************************
** Copyright (c) 2024 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/

#include <vrfcgf/vrfPluginExtension.h>
#include <vrfcgf/cgf.h>
#include <vrfMsgTransport/vrfDatabaseLogger.h>
#include <vrfMsgTransport/vrfDatabaseEvent.h>
#include <tbb/task.h>
#include <mysql.h>
#include "vrfMySqlDatabaseConnection.h"

extern "C" {

   DT_VRF_DLL_PLUGIN void DtPluginInformation(DtVrfPluginInformation& info)
   {
      info.pluginName = "MySQL Database Connection";
      info.pluginVersion = "1.00";
      info.pluginCreator = "MAK Technologies";
      info.pluginCreatorEmail = "sales@mak.com";
      info.pluginContactWebPage = "www.mak.com";
      info.pluginContactMailingAddress = "10 Fawcett Street, Suite 204, Cambridge, MA 02138 USA";
      info.pluginContactPhone = "(617) 876 8085";
   }

   DT_VRF_DLL_PLUGIN bool DtInitializeVrfPlugin(DtCgf* cgf)
   {
      // The following line registers a new type of database connection for a MySQL server.
      // In order to tell VRF to use this new connection type, you must configure it in
      // /appData/settings/databseConfig.mtl. Set the following line:
      // (database-connection-type "mysql-database-connection")
      // Then make sure the server host IP address, port, login, and database name are set
      // as you want them. (A blank database name will create one based on the VRF version).
      DtVrfDatabaseLoggerCreator::setDatabaseConnectionCreatorFcn(
         DtVrfMySqlDatabaseConnection::type(),
         DtVrfMySqlDatabaseConnection::create);
      return true;
   }
}

Table of Contents