Introducing C++ Support for Multiple Report Containers

During our Roadshow this fall, the question I was asked the most was "why do you support certain features only for .NET". Most notably, multiple report containers (since LL20) and nested tables (since LL21) were only available for .NET databinding. The reason for this is the necessity to support a special and – until now – undocumented COM interface for passing the data to List & Label. We decided to leave this interface undocumented in version 20 in order to be free to apply changes without breaking customer code. We had to make sure the interface was ripe. Now we are and here we go.

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.

The interface functions are quite easy to understand:

OpenTableRequests 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.
 OpenChildTableRequests 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.
 GetRowCountRequests 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.
DefineDelayedInfoIf Option LL_OPTION_SUPPORT_DELAYEDFIELDEFINITION is set, the defintions of sort orders are requested.
 MoveNextRequests 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.
 DefineRowRequests to define the current row using the usual LlDefine…() APIs.
 DisposeCan be used for clean up purposes. Will be called just before the IDataProvider is released.
 SetUsedIdentifiersCalled to inform the data provider which fields are required.
 ApplySortOrderRequests to apply the sort order pszSortOrder to the table. The sort orders are passed using the usual LlDbAddTableSortOrder() API before printing and designing.
 ApplyFilterRequests 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.
 ApplyAdvancedFilterReserved for future use, currently you can just provide an empty implementation.
SetOptionProvides additional information about the status of the data provider. These can be used in the implementation for optimizations.
GetOptionAdditional 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?

Related Posts

Leave a Comment