COLEAT is the foundation of an interoperability tool for Windows to make it possible to use Collabora Office in-place of Microsoft Office in lots of line of business applications written in Visual Basic.
COLEAT: smoothing your migration
Many enterprises we deal with have many years of investment in line of business applications from small: printing parking ticket reminders to large patient record systems. This translates into tens to perhaps a hundred applications that require Microsoft Office and whose presence can block a complete migration to Collabora Office.
These applications are often un-documented, have no extant source code yet while old and unfortunate are still doing sterling work and helping some critical staff function to happen. While our team has worked on making VBA macros (which are embedded inside documents) work in the past (checkout Quantum VBA) – there are still large numbers of external VB applications that automate Office from outside that we need to help people with.
COLEAT is the foundation for finding and fixing the vital business tools left-over from the dawn of time that your staff need to keep everything running smoothly.
COLEAT: how do I use it ?
COLEAT sits between your legacy line of business application and provides a wrapper that allows it to talk to Collabora Office without modification:
It also allows you to trace all the relevant automation logic, to report any issues, see under the hood, and allow us to improve Collabora Office to support your application.
Just run coleat your-app.exe <your-app-arguments>...
A Video of COLEAT in action
Moving pictures can show a simple technical demonstration of a rather basic application becoming interoperable:
Where can I get it ?
Check out our GitHub repository git clone https://github.com/CollaboraOnline/COLEAT.gitfor the source – or Download the latest release and unpack the zip file; we will assume into C:\coleat
Don’t forget that you’ll also need to grab and install the latest Collabora Office 6.0 trial which has built-in support for COLEAT.
Try the Collabora Office 6.0 trial
What is “OLE Automation” anyway ?
OLE Automation is a way of using Office via a subset of the Windows Component Object Model (COM), often used to create a simple line of business applications. This is primarily used by Visual Basic and replaces the older Dynamic Data Exchange (DDE) mechanism for application control.
In a nut-shell, it is COM based inter-process communication that lets you create, edit, mail-merge, print, do data entry and more by re-using an Office application. Read more grisly historical detail at Wikipedia.
Can I be sure my app will work ?
In a word – no, we’re still working on this – extending our interoperable API coverage – which has the side-benefit of improving our VBA compatibility at the same time as our OLE Automation interop.
It’s best to test your app, and examine the trace to see what needs to be done to improve things.
How can I test my app ?
When you’ve downloaded COLEAT, simple start a DOS console and run:
coleat c:\path\to\myApp.exe
COLEAT will wrap itself gently around your application, and persuade it to use a nice Free Software alternative.
If it goes wrong
When things go pear shaped, it is really useful to be able to trace your app to generate a complete API dump. It is best to do this when running against Microsoft Office to ensure that everything completes in the expected way and all the right methods are called. Try out the tracing with our demo VB6 app, cf. the README:
coleat -v -o log.txt -t -n demo.exe
This will launch a small demo VB6 app using MS Office that will be traced resulting in a log.txt file, then try it with your application – ensuring you carefully exercise all of the functionality. If COLEAT doesn’t work – and you’re interested in helping to contribute to improving our API coverage – send us your trace with an idea of your budget at hello@collaboraoffice.com.
Or you can also try out tracing an existing VBScript sample like this:
coleat -v -o log2.txt -t -n cscript demo.vbs
FAQ
What versions of Visual Basic are supported ?
We generate stubs & skels to handle VB6 interfaces. We also support some deep legacy WordBasic compatibility interfaces. We run nicely with cscript, and should work with VB.Net – do have a play with your application and see.
What file formats do I need to use ?
Clearly Collabora Office has excellent ODF support, but there should be no need to change the implementation details of your code at least initially. We aim at transparent functioning – working with existing compiled programs.
What’s the difference between the VBA and VB APIs ?
Collabora/Libre Office has had limited VBA support for a decade or more, and it has evolved and improved with time. By exposing these methods to the world via OLE Automation compatible APIs we make it possible to simultaneously improve VBA and VB support with the same implementation work. So – not much difference.
I’m an ISV – can I avoid wrapping with COLEAT ?
That depends, for compile-time languages which embed the type information of the interfaces into the code eg. VB6 it is best to wrap with COLEAT.
For late binding VBscript style you can replace your component names thus
| Before | After |
|---|---|
Set w = Wscript.CreateObject("Word.Application") |
Set w = Wscript.CreateObject("Writer.Application") |
Set w = Wscript.CreateObject("Excel.Application") |
Set w = Wscript.CreateObject("Calc.Application") |
Then of course verify that your application continues to work. If functionality is missing in our Automation APIs – get in touch with us with some an idea of your budget at hello@collaboraoffice.com.
Does this work with LibreOffice too ?
Collabora releases all of our code-changes to LibreOffice, and has contributed them back; as we continue to extend and improve the core interoperable APIs this too will be contributed back. We expect an initial version of the bridging logic, and improved APIs to ship in the ‘Fresh’ release in LibreOffice 6.2 – ready to work with COLEAT.
However – if you have an Enterprise using OLE Automation, unless you have a team of engineers in-house to support you, you really should use a supported version of LibreOffice such as Collabora Office – and in doing so help contribute to LibreOffice’s growth and success.
How does it work under the hood ?
COLEAT starts your Line of Business application (LOB.EXE) paused, and then injects a DLL (injecteddll/injecteddll.cpp) into the process. This DLL examines and diverts various key functions inside the relevant DLLs that are loaded using Import Address Table (IAT) patching:
In essence (as described) – as DLLs are loaded, we look through the list of function pointers to functions we want to replace and pop our ones in instead. We do this for various OLE automation critical functions such as GetProcAddress, LoadLibraryW, and particularly CoCreateInstance and CoCreateInstanceEx. These methods then call instrumented versions under our control that can be used to select another interoperable component instead, and to interpose proxy objects between where necessary.
A more problematic aspect of VB6 is that in its compiled mode (ie. building self-standing exe files) instead of using IDispatch::Invoke to invoke methods the compiler includes the interface type information directly into the code and emits a direct function call to a vtable slot. As such we implement genproxy/genproxy.cpp to provide the same information in a more suitable generated form to allow those methods to be translated to a more helpful string based IDispatch::Invoke approach. Thus allowing us to trace and support compiled VB6 applications.
For more details, please see the source and/or send us patches.
How do I pronounce COLEAT ?
We say CO-LEAT – but of course, you’re welcome to say it as you wish.