• Decisions Before Running
• Time to Extract Data
• Running As ActiveX Automation Library
• Running Interactive - Normal
• Saving Data to a .QQT to Process Later
• Interactive - Authorize File Only
• ISV Considerations

OfficeQ is very easy to use - but there are a few topics you should understand first. Some of this information also applies to the sample Excel and/or Access programs supplied by DataBlox.

Decisions Before Running

Before running OfficeQ - even for the first time - you will be more productive if you first answer the following questions:

• What QuickBooks file am I going to extract the data from? When initially running OfficeQ, it is often easier to use one of the sample files supplied with QuickBooks than your real data file. Sample files are typically small (and fast) and can walk through the whole process very quickly - a few times if necessary so you're comfortable with it.
• Where is the data going? Will you simply save the extracted data to a .QQT file (QQT file description) for later processing or will you create an .MDB database file with the data that you can run queries against later using Excel or Access?
• Are you familiar with the QuickBooks file authorization process and do you know how to set the options. If the file you will read has never been authorized for data access, QuickBooks will show the form below (authorization form) when you attempt to read the data.

Time Required to Extract Data

OfficeQ6 can take a considerable amount of time to extract the data from the customer data file (time spend in the ReadFile call). This can be a critical issue with larger files. We've had medium-large files (>200MB) that have taken over an hour on a typical computer and can envision scenarios much worse than this - especially with older computers.

Over 90% of the time OfficeQ6 is collecting data (while ReadFile is executing) is spent internally in QuickBooks assembling query output data. We've tried several different strategies and there is nothing more we can do to speed this up. The best approach is to either run the extraction in the background until it completes or start the extraction when the computer won't be used for a while (like at night).

For programmers, there are several options available at the API level to ensure that time is not wasted extracting data that's not needed.

Running As ActiveX Automation Library

The main way most end users will use OfficeQ is as an ActiveX automation library. This is invisible - you see the application you are running, but you do not see OfficeQ. If this is how you will use OfficeQ, you can skip the remainder of this page.

If you are a programmer and you instantiate the "OfficeQ6.Reader" object using any programming language, OfficeQ6 will be started in background mode (no user interface) and all it's functionality will be available from the API. See the programming example in this file. The type library must have been registered with the system first.

Running as an interactive, stand alone, normal Windows program.

When OfficeQ6 is installed using a DataBlox install file, a menu item called "OfficeQ6 Direct (for testing)" is installed. This will run OfficeQ6 as a stand alone program. It can be used for viewing any .QBW data file without committing to where data will be transferred. It is a very useful tool for learning what the data looks like and how different data relates to each other.

When you start running OfficeQ6 interactively (such as from the start menu or command prompt), it will immediately look for a file in the same directory as the OfficeQ6.exe file with the name OfficeQ6.txt (renamed if exe has also been renamed). If that file does not exist, the program will immediately stop running. In some cases, software vendors who license OfficeQ from DataBlox do not want the complication of supporting interactive use. They have the option of not including the OfficeQ6.txt file. They can also substitute different text for what DataBlox supplies in the OfficeQ6.txt file, which is somewhat like a mini help file.

If the .txt file does exist, it will open it and display the text file's contents in the large display area. The contents is expected to be normal, non formatted text. OfficeQ6 can then be run interactively.

These options allow you to either prevent OfficeQ6 from being run interactively, or allow you to insert whatever you want as the initially displayed text.

Saving Data to a .QQT File to Process Later

When OfficeQ6 is run interactively, after a QuickBooks file has been read - a button with the caption 'Save all records to a .QQT file for later processing' will appear. If you click this button, a file dialog fill be presented so you can specify a file to save the data in. If you don't specify otherwise - the file will have the same primary name as the QuickBooks .QBW file and will be in the same folder.

There are several reasons for doing this:

• The computer containing the QuickBooks data and the computer to process the QuickBooks data are different.  The computer processing the QuickBooks data could be in a different location and use a completely different operating system (such as Linux or Mac OS).
• The data may need to be processed multiple times for different purposes.  As explained above, extracting the data from a large .QBW file can be a very slow process - possibly taking several hours.
• The data may need to be saved for the future.  Some applications (like a thorough audit trail) require complete data that can be compare with other data in the future.

Running to Authorize Extraction of Data

QuickBooks requires that the user authorize the file for access by OfficeQ. There are also other options - such as whether or not the external application can access 'private' data and whether or not the external application can access the file automatically (without additional user authorization) in the future.

Following is the dialog form that needs to be filled to complete this process.

Unless you have a good reason to do otherwise, you should check the following:

• Yes, whenever this QuickBooks company file is open.
• Allow this application to access personal data such as Social Security Numbers and customer credit card information. This is needed to extract payroll, even though they don't mention payroll. Also, customer credit card information is not available from QuickBooks - even if this box is checked.

If you have previously filled out this form for the current file, but it was filled out incorrectly, it will need to be deleted and recreated. QuickBooks appears to allow the record to be modified - but modification does not work.  Open QuickBooks, find the 3rd party app record, and delete it.  Then start again like new.

We have seen cases where this procedure must be redone after the file is moved from an earlier Windows operating system to Vista or Windows 7.

ISV Considerations

The following are advanced topics that don't easily fit elsewhere.

Running OfficeQ6 to only update the registry (not run as a normal program)

If the OfficeQ6.exe program is run from the Windows command line with /regserver as it's only command line argument, it will update the registry, then exit. If OfficeQ6.exe is installed manually (not an install program), then this needs to be done on any individual computer before ActiveX Automation code can be used to start OfficeQ6.exe.

This should not be necessary because OfficeQ6 is normally installed using a DataBlox created install program.

Opening the .QBW file - programmatically or by the user

We strongly recommend having the user open the appropriate QuickBooks (.QBW) file - then running OfficeQ6 (without specifying a file) while the user's file is open. This avoids a lot of problems.

There are interactive dialogs that are often presented to the user when the file is opened (such as new version available, to do lists, promotion of Intuit services, etc.) that are unpredictable. Also, if several versions of QuickBooks exist on a single computer, the QuickBooks module that decides which version of QuickBooks to run for a particular .QBW file is unreliable. It will sometimes prompt to convert the file to a different version of QuickBooks.

User permissions

QuickBooks, OfficeQ6, and the application calling OfficeQ6 should be run with standard user permissions (NOT elevated to run as administrator)

File Locations

File locations can be critical. The QuickBooks data file (*.qbw) needs to be in a location that Windows sees as proper - especially when using a local area network.