Accessing Toolpack DB

Latest revision as of 11:06, 20 November 2012

The CAF library provides DAOs (Data Access Objects) for all tables in the Toolpack configuration database.

Where to find these DAOs

These DAO objects are defined in the "tbcmc" source packages (tbcmc_2.5.89_common.tgz for example), under:

• tb/inc/tbcaf/dao/oam

Pre-requisites to use these DAOs

To access the Toolpack database, an application needs to:

• Attach to Toolpack OAM "CM" (configuration management), by binding an object of type CTBCAFServiceCmMgmtClient to the application
• Connect to the database using object of type CTBCAFDb initialized using the DB connection string received on OnReloadConfig (see CTBCAFServiceCmMgmtClient)
• Use appropriate DAO access object to query the desired table
• Optionally use a custom SQL query string to query specific elements from a table

How to use the DAOs

• Initialize the DAO access object that corresponds to the table you want to read from (CTBCAFOam_virtual_adapters_db_acc for example)

CTBCAFOam_virtual_adapters_db_acc   AccessVirtualAdapters;
AccessVirtualAdapters.Init( pConfigDb );

• Use one of the DAO functions to retrieve one or multiple entries:

CTBCAFOam_virtual_adapters  VirtualAdapter = AccessVirtualAdapters.GetById( un32MyVirtualAdapterId );
std::vector<CTBCAFOam_virtual_adapters>  AllVirtualAdapters = AccessVirtualAdapters.GetAllBy_configuration_id( un32ConfigurationId );

• Access the information from returned classes

VirtualAdapter.str_serial
VirtualAdapter.un32_last_upgrade_time
...

Example code

Here is some example code that show how to use these DAO objects, taken from the "simple_call" sample application:

TBX_RESULT CTBS2GWSimpleCall::ExampleDbAccess()
{
	TBX_RESULT								Result;
	TBX_UINT32								un32Index;

	CTBCAFOam_configurations_db_acc			ConfigurationsAdapters;
	CTBCAFOam_configurations				CurrentConfiguration;

	CTBCAFOam_virtual_adapters_db_acc		AccessVirtualAdapters;
	std::vector<CTBCAFOam_virtual_adapters>	AllVirtualAdapters;

	CTBCAFOam_line_services_db_acc			AccessLineServices;

	/*---------------------------------------------------------------------------------------------------------------------------
	 |  Code section
	 *--------------------------------------------------------------------------------------------------------------------------*/
	CAFCODE( CTBS2GWSimpleCall::ExampleDbAccess )
	{
		// Initialize the DAO access objects
		Result = ConfigurationsAdapters.Init( mpConfigDb );
		TBCAF_EXIT_ON_ERROR( Result, "Cannot init ConfigurationsAdapters" );

		Result = AccessVirtualAdapters.Init( mpConfigDb );
		TBCAF_EXIT_ON_ERROR( Result, "Cannot init AccessVirtualAdapters" );

		Result = AccessLineServices.Init( mpConfigDb );
		TBCAF_EXIT_ON_ERROR( Result, "Cannot init AccessVirtualAdapters" );

		// Implementation note:
		// Database queries below should be done "in background" using a background thread of this application, outside 
		// the lock of mMutex, in order to avoid blocking the whole application in case the database is
		// temporarily unavailable (backup database about to be activated, for example).
		// In this simple example, we do it inline, however...

		// Example get the name of current configuration (this function will 'throw' if not found)
		CurrentConfiguration = ConfigurationsAdapters.GetById( mun32ConfigurationId );

		// Example: Get all virtual adapters from current configuration
		AllVirtualAdapters = AccessVirtualAdapters.GetAllBy_configuration_id( mun32ConfigurationId );

		// Example: Print the serial number of all adapters of current configuration
		LogTrace
		(
			TBCAF_TRACE_LEVEL_ALWAYS,
			"Adapters from current configuration %s",
			CurrentConfiguration.str_name.c_str()
		);
		for( un32Index = 0; un32Index < AllVirtualAdapters.size(); un32Index++ )
		{
			CTBCAFString strQuery;
			std::vector<CTBCAFOam_line_services>	AllE1LineServices;
			std::vector<CTBCAFOam_line_services>	AllT1LineServices;

			// Example custom SQL query to get E1 line services in current configuration
			strQuery.Format
			(
				"SELECT * FROM %s WHERE %s=\"E1LineService\"",
				TBTBL_LINE_SERVICES,
				TBCOL_LINE_SERVICES_COMMON_LINE_SERVICE_TYPE
			);
			AllE1LineServices = AccessLineServices.GetAll( strQuery );

			// Example custom SQL query to get T1 line services in current configuration
			strQuery.Format
			(
				"SELECT * FROM %s WHERE %s=\"T1LineService\"",
				TBTBL_LINE_SERVICES,
				TBCOL_LINE_SERVICES_COMMON_LINE_SERVICE_TYPE
			);
			AllT1LineServices = AccessLineServices.GetAll( strQuery );

			LogTrace
			(
				TBCAF_TRACE_LEVEL_ALWAYS,
				"    %s (%u E1, %u T1 line services)",
				AllVirtualAdapters[ un32Index ].str_serial.c_str(),
				AllE1LineServices.size(),
				AllT1LineServices.size()
			);
		}

		ExampleDbQuery();
		
		TBX_EXIT_SUCCESS( TBX_RESULT_OK );
	}

	/*---------------------------------------------------------------------------------------------------------------------------
	 |  Exception handling section
	 *--------------------------------------------------------------------------------------------------------------------------*/
	CAF_EXCEPTION_HANDLING

	/*---------------------------------------------------------------------------------------------------------------------------
	 |  Error handling section
	 *--------------------------------------------------------------------------------------------------------------------------*/
	CAF_ERROR_HANDLING( CAF_VERBOSE )
	{
	}

	/*---------------------------------------------------------------------------------------------------------------------------
	 |  Cleanup section
	 *--------------------------------------------------------------------------------------------------------------------------*/
	CAF_CLEANUP
	{
		AccessLineServices.Uninit();
		AccessVirtualAdapters.Uninit();
		ConfigurationsAdapters.Uninit();
	}

	RETURN;
}