Menu
Simba Technologies
Simba Technologies

SimbaEngine X SDK 10.1.3
Developing Drivers for SQL-Capable Data Stores

SimbaEngine X SDK Documentation > Core Features > Fetching Metadata for Catalog Functions

Fetching Metadata for Catalog Functions

ODBC applications need to understand the structure of a data store in order to execute SQL queries against it. This information is provided using catalog functions. For example, an application might request a result set containing information about all the tables in the data store, or all the columns in a particular table. Each catalog function returns data as a result set.

Your custom ODBC driver uses metadata sources, provided by the SimbaEngine X SDK, to handle SQL catalog functions. Of the 13 DSIMetadataSource sub-classes, there is only one that you need to modify to make a basic driver work. This section describes the other metadata classes and under what circumstances you need to update them.

Implementation

Your CustomerDSIIDataEngine class has to derive from IDataEngine or DSIDataEngine. If it is derived from IDataEngine, then the following function has to be implemented:

Simba::DSI::IResult* MakeNewMetadataResult(

Simba::DSI::DSIMetadataTableID in_metadataTableID,

const std::vector<Variant>& in_filterValues,

const simba_wstring& in_escapeChar,

const simba_wstring& in_identifierQuoteChar,

bool in_filterAsIdentifier);

This function creates a new IResult* which contains a metadata data source and filters out rows in the metadata table that are not needed. If the driver does not support a metadata table, then the metadata source in the IResult* should be an empty metadata data source with no rows.

The function takes the following parameters:

  • in_metadataTableID: Identifier to create the appropriate metadata table. For a list of the possible identifiers, refer to the table below. For complete details on each identifier, refer to DSIMetadataTableID.h in the API guide.
  • in_filterValues: Filters to be applied to the metadata table. These filters are passed in by the application that calls the catalog function and cannot be modified. For example, the catalog function SQLTables contains the arguments CatalogName, SchemaName, TableName, and TableType. These arguments are extracted to the in_filterValues vector.
    While these values cannot be modified, if the CatalogName is NULL, the current catalog name is used.
  • in_escapeChar: Escape character used in filtering.
  • in_identifierQuoteChar: Quote identifier, which is the quotation mark that this filter recognizes.
  • in_filterAsIdentifier: Indicates if string filters are treated as identifiers. This can be set through the connection attribute SQL_ATTR_METADATA_ID.

If it is derived fromDSIDataEngine, then the following function has to be implemented:

Simba::DSI::DSIMetadataSource* MakeNewMetadataTable(

Simba::DSI::DSIMetadataTableID in_metadataTableID,

Simba::DSI::DSIMetadataRestrictions& in_restrictions,

const std::vector<Simba::Support::Variant>& in_filterValues,

const simba_wstring& in_escapeChar,

const simba_wstring& in_identifierQuoteChar,

bool in_filterAsIdentifier);

This function creates a new Metadatasource* which contains raw metadata. If the driver does not support a metadata table, then it should return an empty metadata source with no rows by returning a DSIEmptyMetadataSource object.

The function takes the following parameters:

  • in_metadataTableID: Identifier to create the appropriate metadata table. For a list of the possible identifiers refer to the table below. For complete details on each identifier refer to DSIMetadataTableID.h in the API guide.
  • in_restrictions: Restrictions that may be applied to the metadata table. Map of DSIOutputMetadataColumnTag that identify columns in the result set, to the restriction that apply to those columns. For example, if the DSIOutputMetadataColumnTag identifies a catalog name, then the restriction specifies that the result set should only contain rows with the same catalog name as the restriction. For a complete list and details of DSIOutputMetadataColumnTag values, refer to DSIMetadataColumnIdentifierDefns.h in the API guide.
  • in_filterValues: Filters to be applied to the metadata table. These filters are passed in by the application that calls the catalog function and cannot be modified. For example, the catalog function SQLTables contains the arguments CatalogName, SchemaName, TableName, and TableType. These arguments are extracted to the in_filterValues vector.
    While these values cannot be modified, if the CatalogName is NULL, the current catalog name is used.
  • in_escapeChar: Escape character used in filtering.
  • in_identifierQuoteChar: Quote identifier, which is the quotation mark that this filter recognizes.
  • in_filterAsIdentifier: Indicates if string filters are treated as identifiers. This can be set through the connection attribute SQL_ATTR_METADATA_ID.

If the metadata table is supported by the driver, then a new class should be implemented by deriving fromSimba::DSI::DSIMetadataSource and implementing all the functions.

Note:

The Ultralight driver is a sample driver derives ULDataEngine from DSIDataEngine. It implements classes for metadata tables for DSI_TABLES_METADATA, DSI_CATALOGONLY_METADATA, DSI_SCHEMAONLY_METADATA, DSI_TABLETYPEONLY_METADATA, DSI_COLUMNS_METADATA, and DSI_TYPE_INFO_METADATA metadata table identifiers.