News combit Dev Blog

Introducing C++ Support for Multiple Report Containers

Posted: Wednesday, November 18, 2015 | 0 comment(s)
 
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 MoveNext()=0;
  virtual HRESULT _stdcall DefineRow()=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(INT nIndex, const VARIANT* vValue)=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.
 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 Reserved for future use, currently you can just provide an empty implementation.
 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.
 
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.
 
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?




Author: Jochen Bartlau
Head of Development List & Label

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.


  

+1 800 256 3608 (toll-free North America only)