656 Kreag Road - Pittsford, NY 14534-3730 - USA
PHONE: (US)-585-385-3810

FAX: (US)-585-385-6822

EMAIL: click here

FileMerlin™ Conversion Library and API for Developers

Introduction
What is the Conversion Library?
Multiple Instantiation
The Library DLLs
Progress Meter Options
Installation Directory Considerations
The Log file
Advanced Customization
Format Keywords
Test Programs
FileMerlin™ Retail Product FMN.EXE
Files included in this package
Footnotes

Introduction

The FileMerlin™ Conversion library described here is intended for Windows 95/98/Me/XP/NT/2000 software developers, programmers and OEMs who wish to incorporate this advanced conversion technology into their own products, without having to write code for reading and/or writing today's complex word processor native file formats. The host product(s) using this library may be for private use, or may be distributed under a license from Advanced Computer Innovations, Inc..

What is the Conversion Library?

This library consists of 32-bit DLLs and other support files that enable your Windows application to convert document files to HTML, Word, text and other formats. These DLLs are completely user-transparent, convert very accurately and integrate very easily with your Windows applications.

Your Windows application that calls these DLLs is called the host application. The host application may be written in any language or environment that permits DLL calls. This includes C, C++, Visual C++, Visual Basic, FoxPro, Delphi, Clarion and many others.

Multiple Instantiation

Normally, the functions included in the conversion library would be called by a single thread at a time. In other words, there would be only one instance of a library function runnning at a given time. This is the mode of operation supported by a Developer License.

In some cases, multiple threads, processes or applications may want to access a conversion library function at the same time. This situation may arise, for example, on a web server or conversion server which automatically converts documents on demand using asynchronous processes or applications running on the same machine. In other words, there can be more than one instance of the library function running at the same time. This is called multiple instantiation of the conversion library. This mode of operation is supported only under an AutoServe License. You should not use the conversion library with a developer license in this type of environment.

The Library DLLs

The DLLs and interface API described in this document are 32-bit. If you need 16-bit technology, please contact us. The DLLs that you need be directly concerned with are:

DETFILE.DLL -- This DLL is used to determine the type of an unknown file. It is not required if the file type is already known.
FlMn.DLL -- This DLL converts a file from one type to another. It creates a new file of the desired type.
GMETER.DLL -- This is provided as a sample but useable DLL to provide a visual progress meter as each file is being converted. You may ignore this file, or write your own DLL to provide a different kind of progress meter (the instructions to do so are given later).

This package also contains other DLLs and additional files which are not called directly by your application. These files must be installed in the same subdirectory as FlMn.DLL. Not all of these files may be required. These files are listed later, and you may remove the ones that you do not need.

DETFILE.DLL

This DLL determines the file format of an unknown file [1]. The C/C++ function prototype is:

extern "C" __declspec(dllimport) BOOL __stdcall detfile (
  const char FAR* lpszFileName,
  char FAR* lpszShortForm,
  char FAR* lpszLongForm);

The function arguments are:

lpszFileName -- the complete name (including drive and path if necessary) of the file whose type is to be determined.
lpszShortForm -- a 9-character buffer (8 characters plus 1 terminating 0-byte) to hold the returned file type keyword. This returned keyword is suitable for programmatic identification of the file type, and may also be passed directly to the FlMn.DLL if applicable.
lpszLongForm -- a 65-character buffer (64 characters plus 1 terminating 0-byte) to hold a long-form description of the file type. This returned result is suitable for display or documentation purposes in a form that is understandable to the user.

Correspondingly, the Visual Basic declaration for this function is:

Private Declare Function detfile Lib "detfile.dll" ( _
  ByVal FileName As String, _
  ByVal ShortForm As String, _
  ByVal LongForm As String) _
  As Integer

where the arguments correspond to the descriptions given above.

This DLL function always returns a value of TRUE (1). The result (source file identification) is determined by examining lpszShortForm. The possible keywords returned in lpszShortForm are:

KEYWORD	Description
!EMPTY	-- Empty file --
!FERR	File Open Error
!UNK	-- Could not identify --
123/2-	Lotus 1-2-3 1.x/2.x, Symphony 1.x/2.x or compatible spreadsheet
123/3	Lotus 1-2-3 3.x, Symphony 3.x or compatible spreadsheet
ABIL	Ability file
ALPHA	Alpha Works/Electric Desk document
AMDRAW	Ami Professional Draw file
AMI	Ami Pro document
ASC	ASCII (Dos text) file
BACKUP	File produced by Dos Backup
BROTD	Brother Word Processor (Daisy Wheel)
BROTN	Brother Word Processor (U.S. Notebook)
BROTU	Brother Word Processor (U.K. Notebook)
BROTF	Brother Word Processor (French Notebook)
BROTG	Brother Word Processor (InkJet)
CCOM	Complete Communicator/PC Switchboard fax file
CRLDRWx	Corel Draw version x file (x = 3, 4 or 5)
DBASE2	dBase-II data file
DBASE3+	dBase-III or dBase-IV data file
DBINX	dBase (or compatible) Index file
DBMEMO	dBase Memo file
DSW	IBM DisplayWrite document
DWA/PTS	IBM DisplayWrite Assistant or PTS document
ENABx	Enable WP document (version x = 1, 2, 3 or 4)
EXE	MS-Dos Executable program
FFT	IBM DCA (FFT) file
FXINX	FoxPro data base index file
FXMEMO	FoxPro data base Memo file
FXPRO	FoxPro data base
GEOWR	GeoWrite file
GEOCAL	GeoCalc file
HTML	HyperText Markup Language
IWA	IBM Writing Assistant document
LEWP	Leading Edge WP document
LMx	Lotus Manuscript document (version x = 1 or 2)
M11D	Mass-11 document
M11F	Mass-11 folder file
MSAC	Microsoft Access data base
MSPP	Microsoft PowerPoint Presentation
MSPUB	Microsoft Publisher document
MSWDxy	MS Word version x.y for Dos (x.y = 3.0, 4.0, 5.0, 5.5)
MSWKWx	Microsoft Works version x WP document
MSWKSx	Microsoft Works version x spreadsheet
MSWKDx	Microsoft Works version x data base
MSWR	Microsoft Write for Windows document
MSWWx	Microsoft Word for Windows x.0 document (x = 1, 2, 6, 7, 8)
MSWW2K	Microsoft Word 2000 or higher document
MSXL	Microsoft Excel Spreadsheet
MULx	Multimate document (version x)
MULxF	Multimate footnotes file (version x)
MYM	Managing Your Money data file
OFCPWR	OfficePower/PC document
OFW4-	OfficeWriter document (version 4 or earlier)
OFWx	OfficeWriter document (version x = 5 or 6)
OLE	Microsoft Windows Compound (OLE) file
PFSFC	pfs:First Choice document
PFSPW	pfs:Professional Write document
PFSW1	pfs:Write 1.x document
PFSW2	pfs:Write 2.x (Spinnaker) document
PFSWWD1	pfs:WindowWorks (Spinnaker) document
PFSWWD2	pfs:WindowWorks (SoftKey) document
PFSWWS1	pfs:WindowWorks (Spinnaker) spreadsheet
PFSWWS2	pfs:WindowWorks (SoftKey) spreadsheet
RFT	IBM DCA (RFT) file
RTF	Microsoft Rich Text Format
SAMNA	Samna Word/Plus document
SC4	SuperCalc-4 spreadsheet
SPJ	SuperProject Plus data file
VENPUB	Ventura Publisher file
WANG	Wang-IWP document
WMC	WordMarc Composer document
WPF4	WordPerfect 4.1 or 4.2 document
WPFxy	WordPerfect x.y document (Dos or Windows, x.y = 5.1, 5.2, 6.0, 6.1)
WPF7	WordPerfect (Corel) version 7, 8, 9, 2000 or higher
WPRO	Lotus WordPro
2WS	WordStar-2000 document
WSxy	WordStar document (version x.y = 5.0, 5.5, 6.0 or 7.0)

Note that error conditions are denoted by an exclamation mark (!) in the first character of the returned lpszShortForm keyword.

FlMn.DLL

This DLL converts a document file to a different file format. The C/C++ function prototype is:

extern "C" __declspec(dllimport) int __stdcall FlMn (
  const char FAR* lpszSourceFormat,
  const char FAR* lpszSourceFileName,
  const char FAR* lpszDestFormat,
  const char FAR* lpszDestFileName,
  const char FAR* lpszConfFileName,
  const char FAR* lpszScratchPath,
  const char FAR* lpszMeterName);

The function arguments are:

lpszSourceFormat -- Source file format keyword. A valid keyword returned by detfile may directly be passed as this parameter provided it is supported by the conversion engine. The source format keywords supported by the conversion engine are listed later.
lpszSourceFileName -- The complete path and filename of the file to be converted.
lpszDestFormat -- Destination file format keyword, denoting the file format you wish to convert to. The destination format keywords supported by the conversion engine are listed later.
lpszDestFileName -- The complete path and filename of the new (destination) file. The destination path must exist before FlMn is called.
lpszConfFileName -- The complete path and filename of a "user-specified" customization file (see Advanced Customization in the FileMerlin™ user manual). If there is no such customization, this parameter may be NULL.
lpszScratchPath -- The complete path (without file name) of the drive and subdirectory to be used for scratch files. The conversion engine may create scratch files in this drive and directory, and automatically deletes them before returning to the host application.
lpszMeterName -- The name of the progress meter DLL (an extension of .DLL is assumed). If no meter is required, this argument may be passed as null or an empty string.

Correspondingly, the Visual Basic declaration for this function is:

Private Declare Function FlMn Lib "FlMn.dll" ( _
  ByVal SourceFormat As String, _
  ByVal SourceFileName As String, _
  ByVal DestFormat As String, _
  ByVal DestFileName As String, _
  ByVal ConfFileName As String, _
  ByVal ScratchPath As String, _
  ByVal MeterName As String) _
  As Integer

where the arguments correspond to the descriptions given above.

The return value shows if the conversion was successful as follows:

 0: normal return
 1: unrecognized source format keyword
 2: unrecognized destination format keyword
 3: could not create or open CONV_LOG.TXT on scratch drive
 4: could not write to or close CONV_LOG.TXT on scratch drive
 5: could not open a system configuration file
 6: one or more error(s) in configuration file(s)
 7: could not open WX.DTA
 8: could not create scratch file(s) on scratch drive
 9: could not open scratch file(s) on scratch drive
10: could not write to or close scratch file(s)
11: could not open source document
12: source file is not in the specified format
13: some other source file discrepancy
14: could not create new destination file
15: error writing or closing destination file
16: some other destination file discrepancy
17: insufficient memory
18: a required DLL is missing
19: a required DLL is corrupted
20: unusual error, normally would never occur
21: license type error

GMETER.DLL

This is a sample but useable "progress meter" that graphically displays the progress of a file conversion from 0% to 100%, as well as the source and destination file names and formats. Your host application does not directly call any function in this DLL. To use this DLL, simply make sure it resides in the directory where FlMn is installed, and pass "GMETER" as the lpszMeterName argument to FlMn. You do not have to do anything else.

Progress Meter Options

When converting a large document file, it is reassuring for the end user to know that something is happening and that the computer hasn't just locked up. To this end, the conversion DLLs in this package support a progress meter which can display the progress of a file conversion from 0% to 100%. Recognizing that the progress meter interfaces visually with your end user, this package gives you a great deal of flexibility and freedom in the design of this progress meter so that it integrates seamlessly with your application. Depending on how much of the meter DLL you want to design yourself, there are three levels of approach:

At the simplest level, simply use the file GMETER.DLL as described above. This will display a simple progress meter centered on the screen every time a file is being converted. Once the file has been fully converted, the meter disappears.
You may write your own stand-alone progress meter DLL (i.e., one that is completely independent of your host application). This lets you design the appearance and behavior of the progress meter, and provide more functionality. The meter DLL which you develop should provide the following three functions which are called by the conversion library:
- make_meter -- this function is called from FlMn.DLL to make (create) the progress meter window. FlMn.DLL passes character strings to this function, representing the source and destination file names and formats. Your meter DLL may use these as part of the progress meter display, or ignore them. This function should return TRUE if the progress meter was successfully created, else it should return FALSE.
- meter -- this function is called by FlMn.DLL repeatedly with a single integer argument representing the percentage of conversion completed (0 to 100). This function should update the progress window to show the new percentage of conversion. No return value is expected.
- kill_meter -- this function is called by FlMn.DLL after a file has been converted, in order to remove the progress meter window from the screen. No argument is passed, and no return value is expected.
The conversion DLLs assume that these three functions are prototyped (in C/C++ syntax) as follows:
```
extern "C" __declspec(dllimport) BOOL make_meter (
  const char FAR* lpszSourceFile,
  const char FAR* lpszSourceFormat,
  const char FAR* lpszDestFile,
  const char FAR* lpszDestFormat);
extern "C" __declspec(dllimport) void meter (int iPercent);
extern "C" __declspec(dllimport) void kill_meter (void);
```
The arguments to these functions are:
- lpszSourceFile -- name of the source file.
- lpszSourceFormat -- file format of the source file.
- lpszSourceFile -- name of the destination file.
- lpszSourceFormat -- file format of the destination file.
- iPercent -- percentage converted (0 to 100).
For maximum flexibility in integrating the progress meter with your host application, you may include functions in your meter DLL that are called not only by the FlMn DLL, but also directly by your application. This lets the progress meter window interact not only with the user and the conversion DLLs, but also with your host application. When configured in this manner, your meter DLL should still provide the function meter exactly as described above. However, you may elect to remove the functions make_meter and kill_meter, and instead include in your DLL other (differently-named) functions (called directly by your host application) to create and destroy the progress meter window.

Please note that the extra processing associated with updating and displaying a progress meter slows down the conversion somewhat. This is specially so when converting a large number of very small files; its proportionate impact is insignificant when converting large files.

Installation Directory Considerations

All the FileMerlin™ files required by your application should be installed in the same directory. This includes the DLL files and any other files in this package that your application requires. It is easiest to install them in the same directory as your host application. That way Windows knows where to look for them. If you install them in a different directory, you must ensure that Windows can find them.

Further, you must make sure that none of the DLL files exist in any other directory in the Windows search path. This is to ensure that Windows loads the DLLs only from the directory you intend it to load from. Otherwise, Windows may look for the subsidiary DLLs and supporting files in the wrong place and not find them.

The Log file

The conversion engine creates a log file in the scratch drive and directory. This is a standard ASCII text file. The conversion engine writes to it the date and time of conversion, the name and type of the source and destination files, and any discrepancies encountered during the conversion. For example, if some of the formatting features of the source file are not supported in the destination file format, this will be recorded in the log file. Typically, the host application may ignore and delete this log file, display it to the user after completing a conversion or let the user print it.

The log file is normally called CONV_LOG.TXT, and is placed in the scratch drive and directory passed as the lpszScratchPath argument to FlMn. In the case of a multiply instantiating autoserve license, the log file is called Conversion Log n.txt, where n stands for the instantiation number. The log file is created in the append mode, so the log accumulates over successive calls to FlMn, as well as over successive host application sessions. To display only the log for a single session, your application must delete a previously existing log (if any).

Advanced Customization

The conversion engine implemented in these DLLs is a very powerful and full-featured piece of software. It converts more accurately and completely than any alternative we know of. It has many elements that you may customize to exactly suit even very demanding applications. This is done by writing an InterScript™ file containing customization commands, and passing the name of that file as a parameter to the FlMn conversion DLL.

You may use the end-user FileMerlin™ interface to easily create the customization InterScript™ file. Start the end-user FileMerlin™ program, click Customization and set up the various options the way you would like them. Then exit the program. In the FileMerlin™ directory, you will find a file named CUSTOPT.ISC. This contains the InterScript™ customization commands required for your settings. You may use this file as is or copy it to a new file, then pass its name as the customization file to the FlMn conversion DLL. The default CUSTOPT.ISC, as shipped, contains some settings which are required in normal operation. Therefore, you should pass the name of this file or its copy to the FlMn conversion DLL even if you haven't changed any of the customization settings.

Format Keywords

     Format keywords are used to specify the source and destination file formats to the FlMn DLL. They are also used to support filetype-specific customization as described in the Advanced Customization section of the FileMerlin™ user manual.

     As mentioned earlier, a format keyword returned by detfile may be passed directly to FlMn to specify a source file format if it is supported by the conversion package. However, not all file formats can be autorecognized. The FileMerlin™ user manual lists the source format keywords recognized by FlMn, and wildcard characters "*" and "?" are permitted in source format keywords as described therein. However conversions from Brother Word Processors and GeoWrite are not available via the Developer API.

     Destination format keywords supported by FlMn are also listed in the FileMerlin™ user manual. As mentioned therein, wild card characters "*" and "?" are not allowed in destination format keywords.

Test Programs

     This package includes a very simple and self-explanatory test program, DllTest.EXE, which lets you easily issue calls to the DLLs in this package. It lets you manually enter arguments for the detfile and FlMn functions, and call these functions by clicking a button. It then displays the returned results and codes. It does not perform any error-checking on its own, so it reflects exactly the performance of these DLLs in your particular environment.

     Unlike the FileMerlin™ retail end-user interface, DllTest.exe is developer-oriented and permits multiple instantiation. In other words, you can launch several copies of DllTest at the same time. This lets you test multiple instantiation of the conversion library. Note however, that multiple instantiation support is not available in trial mode, nor under any license other than an AutoServe license.

     The package also includes a simple but fully functional application written in Visual Basic that demonstrates calls to library. The relevant files are TEST.VBP and TEST.FRM.

FileMerlin™ Retail Product FMN.EXE

This package also includes a copy of the FileMerlin™ retail product implemented in the file FMN.EXE. This product basically uses the same conversion library, and provides a handy means for checking out the capabilities of the conversion library DLLs. The file FMN.EXE may not be distributed with your product.

Files included in this package

The files included in this package are listed below, along with their purpose. You need install only the ones you need.

FlMn.DLL, FMN.SYS, FMNG4.DLL, STARTUP.ISC, FONTXLT.TXT -- These files are always required.
DETFILE.DLL -- This file need be installed only if you need to recognize the file format of unknown files (auto-recognition capability); otherwise it is not required.
GMETER.DLL -- A generic progress meter that you may directly use to display the progress of conversions.
DETFILE.LIB, FlMn.LIB -- These are import libraries required by some development environments to provide linkage to DETFILE.DLL and FlMn.DLL at compile/link time. They are not required at run time, and are not required by all environments.
DECL_C.TXT -- For C/C++ language developers, this file supplies the prototypes and return codes for the DLL functions your application interfaces with. If you wish, you may include this file into your application source code.
DECL_VB.TXT -- For Visual BASIC developers, this file supplies the prototypes codes for the functions your application interfaces with. If you wish, you may include this file into your application source code.
DllTest.EXE -- This is a very simple Windows program to demonstrate and test the DLLs in this package.
TEST.VBP, TEST.FRM -- These are Visual Basic project and form files, and serve as an example of a fully functional application written in Visual Basic that calls the FileMerlin™ DLLs.

All other files belong with the retail FileMerlin™ product, and may not be distributed with your product.

Footnotes

[1]: The DetFile DLL determines the format of an unknown file by examining its contents rather than by simply looking at its filename extension. Therefore, it can recognize file types that do not use a unique extension.