# QHacc FAQ

This is the QHacc Frequently Asked Questions section of the manual. It is been updated for QHacc v3.1, and should stay reasonably up-to-date. If you find anything in the questions or answers that is vague or just plain-old wrong, please write to ryan@ostrich-emulators.com. If you have a question you do not see in this list, please write to the same address to have it added.

## Questions:

1. I just started QHacc, what do I need to do now?
2. Is there an easier way to enter a lot of old transactions?
3. Why does the account viewer get all funky during resizing?
4. How do I graph more than one account at a time?
5. How do I upgrade from version X to version Y?
6. What happened to `--enable-debug`?
7. How can I translate QHacc / How do I make my language work?
8. What's with the qm files instead of po files?
9. Can I run QHacc on Windows?
10. Can QHacc import Quicken's .qif files?
11. How can I use database X as a backend to QHacc?
12. Which backend is the fastest?
13. What's the biggest transaction QHacc can handle?
14. How can I write my own plugin for QHacc?
15. How do I install QHacc to a non-default location, or move it to one?
16. Does the existance of the `--verifydb` and `--fixdb` command line arguments mean that QHacc might lose some of my data?
17. Can I keep my data files in CVS?

## Answers:

Q I just started QHacc, what do I need to do now?
A Unlike some accounting programs, QHacc does not automatically start with a ready-made setup. If you just unpacked QHacc, a complete and operational setup is available in the qhacc/contrib/easysetup directory. The easiest way to get started is to copy this directory somewhere, say /home/ryan/.qhacc, and start QHacc with the `--home` option. The steps are simple:

- cp -r qhacc/contrib/easysetup /home/ryan/.qhacc
- qhacc --home /home/ryan/.qhacc

Obviously, you should really try to use your own login name instead of mine.

If you don't like using the --home option, you can alternately set a QHACC_HOME environment variable in your shell. If you use any of the bourne-like shells, then type

- `export QHACC_HOME=/home/ryan/.qhacc`

If you're a csh person, the command might look something like

- `setenv QHACC_HOME /home/ryan/.qhacc`

Finally, if you don't want to do any of this, you don't strictly have to. QHacc will assume your QHACC_HOME is in the .qhacc subdirectory of your home directory. You'll still have to create this directory, but once you do, QHacc will do the rest.

Q Is there an easier way to enter a lot of old transactions?
A QHacc provides a number of plugins for importing data from a variety of formats, including Quicken's QIF, and the much more popular and current OFX format. Simply run QHacc with the `--import` option.

If you keep your old transactions in a checkbook, then there isn't any way around entering them manually. However, QHacc has many useful features for speeding the process. First, change your preferences to use "Auto-Complete on" all or new transactions. With this option, QHacc will try to use data from already-entered transactions on the new transactions. After typing in the payee, QHacc will supply the sum, memo, and double-entry account field automatically. If there is some ambiguity for a payee, you can go to the sum field and press the up and down arrows for other payments from that payee. Another useful feature is to highlight the last transaction entered, and use the "i" key instead of hitting the spacebar over "<new>" button to create a new transactions. This makes the transaction editor use the date from the already-entered transaction as the date for the new transaction. Hitting the spacebar uses the current date, which is probably annoying if you're trying to enter old transactions.

Q Why does the account viewer get all funky during resizing?
A This question originally pertained to an older version of QHacc that didn't work well with opaque, or "show contents of window during resizing" resizing. The solution was to make QHacc quit trying to work. More recent versions resize windows much more gracefully, and I believe that as of version 3.1 or so, the problem is fixed.

Q How do I graph more than one account at a time?
A You can graph more than one account at a time by holding down the control key and selecting another account, or by holding the shift key and selecting a whole range of accounts.

Q How do I upgrade from version X to version Y?
A Usually, different versions of QHacc remain backward compatible. Unfortunately things do change occasionally, and datafiles can become incompatible between versions. Upgrading is (hopefully) painless. The first step is to make a backup of all your datafiles. Seriously. The process is very straightforward, but nothing beats a good backup when everything goes wrong. After the backup, follow these steps:

1. Restore any archives you have taken. The upgrade plugin may change the structure of the datafiles, which can in turn affect the structure of the archived files. If you don't restore the archives before upgrading, the archives may not be compatible with the new files, so later restoration may lead to undefined results.
2. Export your data (`qhacc --export /tmp`). The upgrade plugin only works against QHacc's native file format, so if you use some other database, you must create a native export.
3. Run QHacc with the upgrade plugin as its home (`qhacc --home UPG:/tmp`). This will upgrade your old data and start a new instance of QHacc for you to check the results of the upgrade. Save and close the application if everything looks okay.
4. If necessary, recreate your datastore (`qhacc --create PSQL:qhacc`). This is a good practice for all upgrades because the upgrade process may change the structure of the data. If you use a database backend, for example, the table structures may change, any these changes must be accounted for.
5. Import your data to your datastore (`qhacc --import /tmp`). This completes the upgrade.

Upgrade plugins work from one revision to the next, but they do not work for more than one revision. That is, if the data format changes from version 1 to version 2 and from version 2 to version 3, the plugin provided in version 3 assumes the datafiles are in the format of version 2.

Note: It has been brought to my attention that upgrading from v2.4.5 to v3.0 can be problematic for people using a decimal separator other than "." in their datafiles. To fix this, run the following script before using the upgrade plugin: `sed -e 's/\([0-9]\),\([0-9][0-9]\)/\1.\2/g' transactions > tmp && mv tmp transactions`. This code simply looks for comma-delimited sums and converts them to decimal-delimited ones. If you are using something besides a comma, make the appropriate changes to the script.

Note also that there is a bug in v2.4 when using single-entry bookkeeping that also prevents the upgrade plugin from working satisfactorily. This bug can be overcome with the following command: `awk -F\| '{printf "%s||%s||%s||%s||%s||%s||%s||%s||%d||1\n",$1,$3,$5,$7,$9,$11,$13,$15,NR}' transactions > tmp && mv tmp transactions`. This code simply updates the transactions file and assigns a new splitgroup to each transaction. (QHacc no longer uses splitgroups, but some older versions do.) This is not safe to run if you are using double-entry bookkeeping, but the program behaves correctly in that case anyway.

Q What happened to `--enable-debug`?
A QHacc used to have an `--enable-debug` option to configure. That option was removed in version 2.0. The reason is that debugging information is now controlled at runtime instead of compile-time, and that control is much more fine-grained than the `--enable-debug` provided. There are currently 6 levels of debugging/error handling information:
0: no debugging nor errors
1: fatal errors only
2: errors that affect operation
3: errors requiring default values to be used
4: major debugging information
5: minor debugging information
6: for the curiosity cat
To make the output a little more customizable, errors are printed to standard error while debugging information is printed to standard out.

`--enable-debug` also used to enable compilation with the `-g` option to gcc. That option made the compiler include debug information in the executable. The same behaviour can be obtained directly through make by using: make CXXFLAGS="-O2 -g"

Q How can I translate QHacc / How do I make my language work?
A QHacc has the beginnings of internationalization (i18n) support included. As with most aspects of QHacc, I don't know how it's "supposed" to be done, so I'm feeling my way along. However, Qt has some excellent support for i18n. (By the way--just because I only recently found out--internationalization is called i18n because there are 18 letters between the i and n in internationalization. I still don't know why localization is called l10n, though.) In any event, creating a translation for QHacc is rather easy if you have the Qt tools. You'll need lupdate and linguist (or lrelease), all of which are available for free in the Qt sources.

First, you need to start with a .ts file. This can be created using the lupdate.info file included with the sources in the src directory. Edit that file to include your i18n code. (i.e., qhacc_de_DE for German; qhacc_en_US for American English.) Then, run lupdate on lupdate.info to create the ts file. If you have trouble, contact me, and I'll be happy to make the ts file for you. If you followed the example, running lupdate should create a qhacc_de_DE.ts file.

The ts file is a simple XML script that contains the needed translations and their translated texts. You can edit it by hand, though Qt provides a tool called linguist that significanly enhances the experience. When you are done with the translation, call lrelease to make a .qm file. If you used linguist, there is an option to create a release from the open ts file. This qm file contains your translation QHacc. So how do you use it?

Using the qm file is a bit clunky at this time, though it does work. To use the qm file, just set your LANG and QHACC_LANGDIR variables. The LANG variable should be whatever your international code is, and QHACC_LANGDIR is where the qm file is. To continue our example, a German user would set LANG=de_DE, and QHACC_LANGDIR to /usr/local/qhacc/share, assuming that is where they put the qm file. Restart QHacc, and it should be in your language. (Localization--things like decimal point and currency symbol--is slightly different from internationalization. Right now, QHacc's support for l10n is limited to the options in the preferences dialog. There is no automatic l10n support.) By default, QHacc will install the available qm files into /usr/local/qhacc/share.

QHacc is currently available in English, Spanish, and Bulgarian. I'll stand by the English translation, since that's the only language I can reasonably speak. I also wrote the Spanish translation, but that's a bit more of a stretch for me. The Bulgarian translation was kindly contributed by a user, and I can only assume it is correct. I am very grateful for it, that's for sure.

If you are interested in translating QHacc, I would love to hear from you. If you're a bit worried about the amount of work, it is VERY easy to make a translation.

Q What's with the qm files instead of po files?
A Qt's native translation file is a .qm file. GNU uses .po files, but that requires the gettext package. One of the goals of QHacc has always been to require the fewest possible number of dependencies. Even though nearly every system around has gettext, I decided to stick with Qt, since I'm reasonably certain if you can install QHacc, you have Qt on your system.

Q Can I run QHacc on Windows?
A Yes, but it's a bit more limited than on X11. In the past, this was accomplished with the use of the freely-available Cygwin libraries and the Qt port available on the web. Now, QHacc can be compiled and run on Windows natively. Trolltech has released a non-commerical version of Qt 3.2 for Windows, which includes everything you need to compile QHacc on that platform.

As for QHacc, the instructions are a bit hokey, but they work:

1. Unpack the installation.
2. Copy all the files from the lib, plugins/reports, and plugins/graphs directories of the distribution into the src directory.
3. Copy the Makefile.windows and src.pro from the contrib directory to the src directory, too.
4. Rename Makefile.windows to Makefile
5. Run make from the src directory to create the QHacc executable (qhacc.exe)
6. Set your QHACC_HOME and QHACC_ROOT environment variables as you would for running QHacc on X11.

On Windows, QHacc gets built as one monolithic program instead of the nice, lean, dynamic one that gets built on X11 systems. For this reason, QHACC_ROOT can pretty much point anywhere, as it's basically ignored. (QHACC_HOME is just as important as ever, though.) You might also notice that the instructions only cover the graphing and reporting plugins, and not any of the database ones. This means you have to use the native database on Windows. It's a perfectly capable option in my opinion, and what's more, that's life.

Note: If all this smacks of a massive kludge to get QHacc running on a totally unfamiliar platform, I'll level with you: I'm not really a Windows programming master, but I can get by.
Note 2: Porting QHacc to Windows was actually extremely easy. It took me a grand total of one evening to do it. Qt is a fantastic toolkit.

Q Can QHacc import Quicken's .qif files?
A Currently, there is a preliminary process for converting Quicken's .qif files to QHacc datafiles. The file format is pretty well documented, but it seems that not even Quicken creates valid .qifs all the time. In fact, Intuit, Quicken's maker, apparently discourages using .qifs for all but the most rudimentary backups. QHacc provides QIF support via an import plugin. Simply install the plugin and run

- `qhacc --import QIF:<account name>:<qif filename>`

to import the data into QHacc. If you can download your statements from your banking institution, you can also run

- `qhacc --reconcile QIF:<account name>:<qif filename>`

to automatically reconcile those transactions.

Q How can I use database X as a backend to QHacc?
A QHacc supports a pretty wide range of databases on the backend. Using them is actually specific to which one it is, but they all have a several features in common.

1. They are all more complicated to set up than QHacc's native database structure.
2. They have a `--create` option for displaying the commands necessary for creating a database from scratch.
3. They are accessed from QHacc via a plugin of some sort.
4. There is no concept of "saving" data when using a plugin database. Databases tend to save things ("commit" them) after every transaction, so you can't quit the program after making a mistake and expect the mistake to be undone.

That said, there is no operational distinction when accessing a plugin database. In fact, QHacc only accesses databases through its database abstraction layer, so the native database is a plugin just like any other. Once you have your database of choice installed, there are some easy steps to get up and running.

- run `qhacc --create <plugin id>:<databasename>` to create a script that can create the QHacc database. (QHacc won't do this automatically.)
- Use the same <plugin id> as your QHACC_HOME

So what are the <plugin ids> supported by QHacc? Check out the plugins page. To use them, simply substitute the given line for your QHACC_HOME environment variable or `--home` option. I will note that the SQLite/LocalFile Hybrid plugin is the easiest to setup because reads and writes to QHacc's native savefiles. After loading the files, however, it uses an in-memory instance of SQLite to do all the querying and updating, and writes the data to disk on saves.

Q Which backend is the fastest?
A I've run some completely unscientific performance tests on the six different database plugins using the "time" command. I ran `qhacc --accounts` against an identical dataset 83 times. The dataset had 33 accounts, 6,000 transactions, and 12,000 splits. Here are the unofficial average results, for the curious:

Plugin | User Time (s) | System Time (s)
--- | --- | ---
Native | 19.50 | 0.05
XML | 22.37 | 0.08
PostgreSQL | 0.69 | 0.02
MySQL | 0.69 | 0.03
SQLite | 3.01 | 0.20
Hybrid | 6.96 | 0.05

As you can see, the native database is a perfectly acceptable option for general use (6,000 transactions is approximately four years' worth of data for me), but there may be some better options out there. I'm happy to report that with the latest release, the SQLite and Hybrid plugins' performance has been dramtically improved, and they are are now excellent choices once again.

Q What's the biggest transaction QHacc can handle?
A QHacc secretly converts all values to integers when counting them. This strategy helps reduce the rounding errors that computers sometimes make when dealing with decimal points. How big the transaction can be depends on how your particular system stores integers. On this Slackware Linux system, an integer is 4 bytes long, which translates to 31 bits for the number and one bit for the sign. 231 is 2147483648, so the largest transaction could be $21,474,836.48, but that's only if you had one. You could still get an error if you tried to add transactions of, say, $10,000,000.00 and $12,000,000.00, as you might if you were generating a report.

So, why use an integer instead of a long integer (which would allow transactions of up to $92,233,720,368,547,758.08)? There's no particular reason, other than QHacc is the "Q Home Accountant," not the "Q More Money Than Has Ever Been On The Earth Ever Accountant." I'm perfectly willing to limit QHacc's scope of use to people and families that have less than $20M in working capital.

Q How can I write my own plugin for QHacc?
A As of v2.7 or so, QHacc relies on plugins to provide all database access. The plugin interface is defined by plugins.h of the lib source directory. Also in that directory is a sqldbplugin.h and sqldbplugin.cpp which is a good example of customizing the plugin interface for working with databases. localfileplugin.h and localfileplugin.cpp provide a working example of writing a plugin from scratch. There are three avenues for writing a database plugin:

1. A plugin derived from localfileplugin: Write your plugin by overloading the functions in localfileplugin.h. Link your plugin to the localfileio and dbbase libraries.
2. A plugin derived using QHacc's native table layout but not using localfileplugin: Write your plugin by overloading the functions in sqldbplugin.h. Link your plugin to the nativedbio and dbbase libraries. (Look at the MySQL plugin for a model.)
3. A plugin created in any other format: Write your plugin by overloading the functions in plugins.h. Link your plugin to the dbbase library.

To give you an estimate of how long a plugin takes to write, I added support for SQLite databases in the span of two hours one night. I had no knowledge of SQLite previous to starting coding. There were a total of three non-trivial functions to write, consisting of a total of 50 lines of code. It's that easy.

Of course, QHacc uses plugins for graphing and reporting support as well. The interfaces for these plugins are also in the plugins.h header file, and samples can be found in the plugins directory of the distribution.

Q How do I install QHacc to a non-default location or move it to one?
A By default, QHacc installs itself in a pretty reasonable tree. It looks like this:

      /usr/local/qhacc
      /usr/local/qhacc/bin
      /usr/local/qhacc/lib
      /usr/local/qhacc/lib/plugins
      /usr/local/qhacc/lib/plugins/db
      /usr/local/qhacc/lib/plugins/import
      /usr/local/qhacc/lib/plugins/export
      /usr/local/qhacc/include
      /usr/local/qhacc/share
      /usr/local/qhacc/share/html

But QHacc uses Autoconf, so just about all the locations can change. For the most part, that's not a problem, except when it comes to plugins. Currently, plugins get installed into the lib directory and links get created in the appropriate plugin directory. However, if you change where the libraries go, the links may not work, and none of the plugins will be loaded.

The solution to this problem is the preconf file. More information about it can be found here. This file goes in the root of the QHacc installation (you can find this easily by running `qhacc-config --qhaccroot`), and can include the token "PLUGINDIR" to point to where the plugins can be found. You'll probably also need to recreate the links or move the libraries from the library directory.

So what if you installed the binaries one place, the libs somewhere else, and you deleted everything else? That's a little more complicated, but still doable. Just find your qhacc executable. It's actually just a shell script, so you can edit it directly to change the QHACC_ROOT variable. Point that to the new installation directory (where the preconf file can be found), and change the LD_LIBRARY_PATH variable to point to the lib directory. Again, if the plugins aren't where QHacc's expecting them, you'll have to recreate the links or move the libraries.

I guess I should note that relocating QHacc isn't exactly for beginners. You should be familiar with your system and administering it in general before attempting these procedures.

Q Does the existance of the `--verifydb` and `--fixdb` command line arguments mean that QHacc might lose some of my data?
A NO! `--verifydb` and `--fixdb` are modes I created for use during testing. I noticed that I was corrupting my data when I would manually enter things into the datafiles that didn't synch up to what was in the other datafiles, so I wrote the functions to tell me when I had made such a mistake, and I figured they were simple enough the leave in the code once it was released. In normal operations (using stable releases), it is extremely unlikely that your database will become corrupted. If it does, it's a serious bug.

At this point, I will note one thing in favor of PostgreSQL: it makes the `--verifydb` and `--fixdb` command line arguments totally superfluous. PostgreSQL enforces referential integrity in its data, so it cannot become corrupted in the same manner as some of the other plugin databases can, even if you're trying to corrupt it.

Q Can I keep my data files in CVS?
A Yes. QHacc doesn't provide a CVS plugin exactly, but it does come complete with a script for interfacing with CVS. It's distributed in the /contrib directory of the package, and called qhacccvs.sh. Using it is easy: first, setup up your CVS repository as usual, and add QHacc's datafiles to it. Then, use `--home extprg:</path/to/qhacccvs.sh>:<QHACC_HOME>` as your QHACC_HOME. (The qhacccvs.sh script assumes the repository name is "home," so you may want to change that before using it.) Using the External Program plugin in conjunction with the qhacccvs.sh script will force QHacc to check out your QHACC_HOME from CVS before starting up, and save it back to CVS on every save.