List & Label Reporting Tool
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.


  

RSS
combit Development BlogRSS
What’s this blog for?
A place to share updates about the ongoing development of our products. General musings on the software industry included.
Archive
December 2018 (1)
November 2018 (2)
October 2018 (4)
September 2018 (4)
August 2018 (2)
July 2018 (2)
June 2018 (2)
May 2018 (1)
April 2018 (1)
March 2018 (1)
February 2018 (2)
January 2018 (1)
December 2017 (1)
November 2017 (2)
October 2017 (3)
September 2017 (3)
August 2017 (2)
July 2017 (2)
June 2017 (1)
May 2017 (2)
April 2017 (1)
March 2017 (1)
February 2017 (1)
January 2017 (2)
December 2016 (1)
November 2016 (1)
October 2016 (4)
September 2016 (5)
August 2016 (2)
July 2016 (2)
June 2016 (3)
May 2016 (2)
April 2016 (3)
March 2016 (3)
February 2016 (1)
January 2016 (2)
December 2015 (2)
November 2015 (1)
October 2015 (4)
September 2015 (5)
August 2015 (2)
July 2015 (2)
June 2015 (2)
May 2015 (1)
April 2015 (2)
March 2015 (1)
February 2015 (1)
January 2015 (1)
December 2014 (2)
November 2014 (1)
October 2014 (1)
September 2014 (2)
August 2014 (1)
July 2014 (2)
June 2014 (1)
May 2014 (2)
April 2014 (1)
March 2014 (2)
+1 800 256 3608 (toll-free North America only)