CDAL Data Access Layer

• CDAL Data Access Layer
• • Custom SQL
  • Tips

The Comlabs Data Access Layer (CDAL) is an object/relational mapper, data access layer that MineMarket uses to interact with the database. This code handles populating and persisting object changes between users and the database.

Add-ins and scripts must use CDAL for interacting with the database; therefore, a knowledge of CDAL is essential when creating add-ins and scripts.

This section is an introduction to CDAL and the MineMarket object model. Refer to the MineMarket source code for more complex examples.

CDAL returns populated objects from the database; not record sets like traditional SQL queries.

The BTNamedBusinessObject and BTBusinessObject classes in MineMarket inherit from the CDAL PersistentObject abstract class. BTNamedBusinessObject inherits from BTBusinessObject and to be a 'CDAL' object, MineMarket objects must inherit from one of these two classes. BTNamedBusinessObject and BTBusinessObject provide a number of common properties and methods.

Custom SQL

Core MineMarket code only uses custom (hardcoded) SQL in very special circumstances. Custom SQL is discouraged because:

• CDAL populates objects and persists changes to and from the database.
• CDAL is the only way to update the MineMarket database.
• CDAL Provides unique numbers used for every object in MineMarket.
• Using CDAL reveals object model changes at compile time and allow the add-in to be updated before releasing to the customer. However, the add-in must be compiled against each release even if the add-in has not changed.
• CDAL runs against both Oracle and SQL Server.
• CDAL provides access to associated objects and complex processing without the need to write extra code.
• CDAL is easier to maintain.

Nevertheless, CDAL does provide an object called CustomSQLQuery for custom SQL, which is used in very limited circumstances. This object has a method called IHaveCheckedToMakeSureThatICanUseThisMethod and must be set to true before the custom SQL can be executed.

Only use this method when trying to retrieve a dataset. You may need to use this functionality to retrieve objects using custom SQL that is shown to be faster than a query constructed using CDAL. For examples, search for CustomSQLQuery in the MineMarket source code.

Tips

To navigate through the MineMarket object model in Visual Studio, place the cursor over the object name and press F12 to go to the definition of the object.

If CDAL is not returning the expected result, you can obtain the actual SQL query that CDAL has constructed using SQL profiler and run a trace.