Currently, the sample for C++ is a hidden gem in the form of the “Print and Design Reports (SQL data source)” sample. If you’re about to start your development in C++, this is the recommended starting point. That’s also the reason why we removed and deprecated several other C++ samples in LL21. Of course, we’ll fully support the “old” way of working with List & Label with your custom print loop. However, if you’re looking for advanced features, the IDataProvider interface will be the way to go.
This is what the interface looks like:
interface ILLDataProvider
: public IUnknown
// IID_ILLDATAPROVIDER 0x3cbae450,0x8880,0x11d2,0x96,0xa3,0x00,0x60,0x08,0x6f,0xef,0xff
{
virtual HRESULT _stdcall OpenTable(LPCWSTR pszTableName, IUnknown** ppUnkOfNewDataProvider) = 0;
virtual HRESULT _stdcall OpenChildTable(LPCWSTR pszRelation, IUnknown** ppUnkOfNewDataProvider) = 0;
virtual HRESULT _stdcall GetRowCount(INT* pnRows) = 0;
virtual HRESULT _stdcall DefineDelayedInfo(enDefineDelayedInfo nInfo) = 0;
virtual HRESULT _stdcall MoveNext() = 0;
virtual HRESULT _stdcall DefineRow(enDefineRowMode, const VARIANT* arvRelations) = 0;
virtual HRESULT _stdcall Dispose() = 0;
virtual HRESULT _stdcall SetUsedIdentifiers(const VARIANT* arvFieldRestriction) = 0;
virtual HRESULT _stdcall ApplySortOrder(LPCWSTR pszSortOrder) = 0;
virtual HRESULT _stdcall ApplyFilter(const VARIANT* arvFields, const VARIANT* arvValues) = 0;
virtual HRESULT _stdcall ApplyAdvancedFilter(LPCWSTR pszFilter, const VARIANT* arvValues) = 0;
virtual HRESULT _stdcall SetOption(enOptionIndex nIndex, const VARIANT* pvValue) = 0;
virtual HRESULT _stdcall GetOption(enOptionIndex nIndex, VARIANT* pvValue) = 0;
};
Your code needs to implement this interface and pass it via option to List & Label – just like in the screenshot from this tweet: https://twitter.com/jbartlau/status/649907919241244672. The sample shows an implementation for SQLite databases that will quite easily translate to other relational database systems.
The interface functions are quite easy to understand:
| Method | Purpose |
| OpenTable | Requests an interface to the table pszTableName. The tables are passed using the usual LlDbAddTable(Ex)() APIs before printing and designing. This is the only method that will be called on your “root” provider, i.e. the interface instance you’re passing in the first place. In the second parameter, you need to return a new IDataProvider instance. The other methods will all be called on this or other sub instances. |
| OpenChildTable | Requests an interface to the child table that is identified by pszRelation. The relations are passed using the usual LlDbAddTableRelation() API before printing and designing. You need to make sure that the filter on the child table matches the current record of the table on which this method is called. |
| GetRowCount | Requests the row count for the table. Used for the progress meter. You may safely return S_FALSE if your data source does not support counting rows. |
| DefineDelayedInfo | If Option LL_OPTION_SUPPORT_DELAYEDFIELDEFINITION is set, the defintions of sort orders are requested. |
| MoveNext | Requests to move the cursor to the next row. Return S_FALSE if you’ve reached the end of the table. Important: for pristine instances of tables, the first MoveNext() expects you to move the cursor to the first record. |
| DefineRow | Requests to define the current row using the usual LlDefine…() APIs. |
| Dispose | Can be used for clean up purposes. Will be called just before the IDataProvider is released. |
| SetUsedIdentifiers | Called to inform the data provider which fields are required. |
| ApplySortOrder | Requests to apply the sort order pszSortOrder to the table. The sort orders are passed using the usual LlDbAddTableSortOrder() API before printing and designing. |
| ApplyFilter | Requests to apply the passed filter to the records. You receive an array of field names and a corresponding array of values. This method is called during drilldown. |
| ApplyAdvancedFilter | Reserved for future use, currently you can just provide an empty implementation. |
| SetOption | Provides additional information about the status of the data provider. These can be used in the implementation for optimizations. |
| GetOption | Additional information is queried. |
The actual print loop is dead simple in this case – you just keep on calling LlPrint() until the result is not LL_WRN_REPEAT_DATA anymore.
This interface enables List & Label to hold several database cursors simultaneously and traverse them independently from each other. It is this feature that is required for multiple report containers and nested tables to work. For the actual implementation just take a look at the sample that ships with List & Label 21. A detailed overview about the complete interface could be found within the Programmer’s Manual in chapter Using the ILLDataProvider Interface.
We’re looking at extending support for this interface to other languages as well. Which would you think would be the most important ones? In addition, this would be a very good opportunity for community involvement. Admittedly, we don’t have deep enough knowledge of all programming languages to actually support this feature. Like the preview support for Xbase++ or our cooperations for DataFlex, Clarion or dBASE PLUS, we’d be more than willing to support a community effort here. Would you be willing to cooperate with us?
Jochen Bartlau leads the development at combit as Managing Director. He’s a Microsoft .NET enthusiast driving innovation & agile project management. The mobile devices geek who used to be a physicist in his first life loves to spend his spare time with his family.
