QHACC_ROOT is the only environment variable that cannot be overridden
from the command line. This is because by the time the command line is
parsed, QHacc already has to know about its plugins. The QHacc
executable is run from a script, which can accommodate a changed
QHACC_ROOT variable.
Environment Variables
QHacc utilizes a few environmental variables to get itself going. For
the most part, QHacc doesn't need any of these environment variables to
operate, but they are useful. The variables are:
Option | Arguments | Description |
---|---|---|
-f or --home | QHACC_HOME1 | Using this switch will override whatever value is currently stored in the QHACC_HOME environment variable, if any. This options allows multiple QHACC_HOMEs to be used for different purposes. |
-w or --warranty | none | show warranty information |
-l | QHACC_LANGDIR | Using this switch will point to a non-default language file for i18n support. |
--debug | debug level (0-6) | set runtime debugging information level |
--cron2 | scheduled transaction filename | see Scheduled Transactions below |
--archive2 | a date string3, or account identifier4 | see Archiving below |
--restore | archive file | see Archiving below |
--preport | account identifier4 | "Totals by Payee" report. seeReporting below |
--breport | account identifier4 | "Monthly Balances" report. seeReporting below |
--dreport | account identifier4 | "Monthly Deltas" report. seeReporting below |
--areport | account identifier4 | "Averages" report. seeReporting below |
--budget | account identifier4 | "Budget" report. seeReporting below |
--journal | ledger identifier5 | "Journal" report. seeReporting below |
--accounts | none | display account names, balances, and number of transactions |
--transactions | account identifier4 | display all the transactions in a particular account |
--import | QHACC_HOME1 | import data from the given QHACC_HOME into the current QHACC_HOME |
--export | QHACC_HOME1 | export the current data to the given QHACC_HOME location |
--create | QHACC_HOME1 | display commands for creating a functional QHACC_HOME from scratch |
--reconcile | QHACC_HOME1 | reconcile all transactions that are duplicated in the given QHACC_HOME |
--verifydb | none | verify that QHacc's database is in a consistent state |
--fixdb | none | make QHacc's database consistent |
--plugins | none | display the information about the available plugins |
--help | none | show these options |
qhacc
--archive 29-02-2000
would archive all transactions before 1 March,
2000.
If you are not using a mouse, the Account Chooser is navigable with the
up and down arrows. Pressing the spacebar will open the account.
In both cases, the selected account will be printed in bold font and a
colored highlight bar will illuminate the account in the Chooser.
The popup menu available in the Account Chooser allows you to reconcile,
edit, add, or delete an account. It is not necessary to open an account
in order to use these functions. (i.e., You can be viewing your checking
account, and open your savings account for reconciling.) Please be
careful when using this liberty to make sure you don't delete the wrong
account. The popup also allows you to toggle the Account Chooser's view,
to show or hide categories. If you are not using a mouse, these
functions are available from the Account or Preferences
menubar.
The Account Viewer window has a popup menu to work on the transactions
in the viewer. There are standard functions like add, reconcile, and
memorize. Please see the section below for more
details on memorizing transactions.
The Viewer and Chooser can be sorted on any column. Clicking on a column
header sorts the data on that field. Clicking on the same field resorts
the column in reverse order. Unlike previous versions of QHacc, these
preferences are saved for future use.
QHACC_HOME
Before running QHacc, the program must know where it is going to save
files, and where to look for already-saved ones. It does this through
the use of the QHACC_HOME environment variable. This is usually set
before running QHacc, but it can be passed via the command line with the
-f option. By default, QHacc will assumes the QHACC_HOME is located in a
local directory, but various plugins can override that
assumption. Regardless of where QHACC_HOME is, QHacc will only write
data into that location. It will not create that location for you if it
doesn't exist.
Local Files
"Out of the box," QHacc only supports writing to a directory on the
local filesystem. In this case, QHacc will look into the specified
directory for all its files. In addition, when saving files, it will
change their permissions so that only the user running QHacc can open
them later. This avoids having possibly sensitive information available
to anyone on the system. If you really, really know what you are doing,
you can set the "KEEPFILEPERMS" preference manually to keep QHacc from
changing its files' permissions. This is highly discouraged.
Multiple Personalities
QHacc keeps all the information about a set of accounts in QHACC_HOME,
but it also allows a user to switch QHACC_HOME during execution. This
functionality may be useful if, for example, a user has a set of
business accounts in addition to a set of personal accounts, and wishes
to keep both sets exclusive. Thus, each QHACC_HOME can be thought of as
a different personality. When requested to switch personalities, QHacc
closes the old set of accounts without saving them and then opens
the new set of accounts.
Interface Layout
The QHacc window consists of just three main parts: the Account
Chooser, the Account Viewer, and the Status Bar. The Account
Chooser starts on the left side of the screen, and displays all your
accounts and their balances. The rest of the screen is devoted to the
Account Viewer. The Account Viewer displays all the transactions in a
specific account. The Status Bar runs below the Account Viewer and the
Account Chooser. It displays information about the currently-opened
account such as it name, type of account, number of transactions, and
account balance. It also notifies the user if any information has been
changed since the last save.
The Account Chooser
The Account Chooser is the navigator and maintenance hub for
accounts. Clicking on an account will open that account, and display all
its transactions in the Account Viewer. Double-clicking on an account
will bring up the Account Edit Dialog box. More about that later.
The Account Viewer
The Account Viewer displays all the transactions in the opened
account. It looks vaguely like a spreadsheet display, with serveral
columns and resizeable column headers. Underneath the headers are all
the transactions in the account. Clicking on a transaction will open
the Transaction Editor. Alternately, you can click on the "<new>"
transaction to insert a totally new transaction. Alternately
alternately, you can use the keyboard to navigate the Viewer. Using
the up and down arrows will select transactions. As with the Account
Chooser, pressing the spacebar will open the transaction for editing.
Key | Scope | Function |
---|---|---|
CTRL-S | Global | Save files. |
CTRL-H | Global | Change QHacc Home |
CTRL-T | Global | Save files and exit QHacc. |
CTRL-Q | Global | Quit QHacc without saving files. |
CTRL-V | Global | Toggle category view of account chooser. |
CTRL-B | Global | Open a subset of transactions for the highlighted account. |
CTRL-R | Global | Open a reconcile window for the highlighted account. |
CTRL-L | Global | Toggle the reconcile balance display in status bar. |
CTRL-N | Global | Create a new account. |
CTRL-E | Global | Open the Account Editor dialog. |
CTRL-SHIFT-X | Global | Delete the highlighted account. |
CTRL-G | Global | Open the Graphing dialog. |
CTRL-Y | Global | Open the Reporting dialog. |
CTRL-F | Global | Open the Preferences dialog. |
CTRL-W | Global, if a transaction is hilighted in the Viewer | Write the hilighted transaction to a schedule file. |
spacebar | Chooser | Open the hilighted account in the Viewer. |
del | Chooser | Delete the account hilighted in bold. |
del | Viewer | Delete the transaction hilighted in bold. |
CTRL-C | Viewer | Copy the hilighted transaction. |
CTRL-P | Viewer | Paste the previously-copied transaction. |
CTRL-X | Global | Cut the highlighted transaction. |
i | Viewer | Insert a transaction. This new transaction will have the same date as the previously-hilighted transaction. |
e | Viewer | Edit the hilighted transaction. |
spacebar | Viewer | Open the Transaction Editor for the hilighted transaction. |
spacebar | Reconcile Window | Mark the hilighted transaction as reconciled. |
ASSET |
LIABILITY |
EQUITY |
EXPENSE |
REVENUE |
You can get more information about how to use these accounts in the Accounting Primer.
Accounts can also be made into categories. A category is an account in every sense of the word, but just a little different. Categories are not included when computing a personalities' total equity. There is also a preference item to exclude Categories from the Account Chooser. This preference is available through the Preferences Dialog or the Chooser's popup. This feature allows a user to maintain a eyeball on those accounts that are most important to him/her, while hiding the ones that are less important.
Double-Entry transactions are just like single-entry transactions,
except that each transaction must be part of two accounts. Double-Entry
transactions are generally split between an income and expense account,
though this rule is not a requirement. In any event, when you specify
double entry bookkeeping, the Transaction Editor will get one more
field--the double entry account field.
Split Transactions are a special type of transaction where one
transaction has many different double-entry pairs. The most common use
of this type of transaction is probably for entering your paycheck, I
think. Your employer generally pays you one sum, but also pays taxes on
your behalf, or splits your paycheck between several different accounts,
like a checking and savings account. All these splits can be entered
into a different account, but still only take up one transaction in your
"job" account, for example. Is that clear?
In order to change a regular double-entry transaction into a good
old-fashioned split transaction, one just needs to push the "split"
button in the Transaction Editor. This will open the Split Editor, and
you can go merrily on your way. If, on the other hand, you have a split
transaction that you would like to make into a double-entry transaction,
set its sum to "0" or just leave the appropriate sum field blank. When
the transaction is saved, splits with 0 balance will be removed.
When using the Split Editor, it is important to remember that
transactions are not modified until the Enter key or the "Enter"
button is pressed. When the "Okay" button is pressed in the Split
Editor, the transaction editor will display updated values, but the
transaction is not modified. Opening the Split Editor again will
display only the updated values. To get back to the original values of
the transaction, hit "Cancel" in the Split Editor. This will reset all
the splits to the transaction's original values.
To remove a transaction from the "memorized" list, select it from the
"unmemorize" part of the popup.
QHacc supports copying and pasting transactions as well. The mechanism
is exactly the same as for memorized transactions, but the only one
transaction can be pasted at a time. Ctrl-C and Ctrl-P are the cut and
paste shortcuts, respectively.
In addition to scheduling a flat dollar value when using scheduled
transactions, QHacc supports scheduled transactions whose sum is based
on a percentage of the account's balance at the time of entry. See the
schedule format section of the manual for details.
The reconcile window is a fully-capable Account Viewer. That is,
transactions can be added, removed, or edited just as they can be in the
main Account Viewer. Both displays will remain synchronized while the
reconcile window is open. Any transactions added while the reconcile
window is open will automatically be marked as reconciled, regardless of
which display is used to enter it. The reconcile window is modeless, so
several accounts be reconciled at once.
Reconciling from the command line is also supported. Running qhacc with
the --reconcile argument will compare the given QHACC_HOME's data with
the already-loaded data and reconcile any duplicate transactions. A
transaction is determined to be duplicated if the date and sum are
identical. Also see the plugins section, below.
The opposite of
Archiving and restoring files usually alters the accounts so that the
current balance is consistent before and after archiving or restoring,
but this behavior is customizable.
The scheme is simple: every plugin has an identifier that tells the
QHacc engine what data it expects to see. To use a plugin, just give
QHacc the identifier as part of the QHACC_HOME. For example, if I want
to have QHacc export its data in XML instead of its native format, I
just run
There is even one plugin, which I like to call "The Cliimp," which
basically supplants the
For the memory conscious, it should be noted that plugins are not
actually loaded until they are used. When QHacc first starts, it cycles
through the plugin directories to figure out what plugins are available,
but then doesn't load any until they are specifically called for. The
goal for plugins was to have as much functionality as possible without
increasing the memory requirements of the project.
Some graphs allow expanded viewing via "click-throughs." Clicking on a
section of the graph will open a subset view of the given account for
the appropriate month. The subset view also reports several attributes
of the transaction set.
When using the GUI for graphs and reports, multiple accounts can be
selected at once. Select an account, and then hold the shift- or
ctrl-key to select either a range of accounts, or individual accounts,
respectively.
When switching bookkeeping styles, QHacc performs what I will call
"lazy" updating. That is, if you used to use double-entry bookkeeping
and you switched to single-entry, none of the links will break. The
links between transactions remain intact until the transaction is opened
and then resaved. Likewise, single-entry transactions will remain
pairless until they are opened as double-entry transactions. This is
true even across saves.
Transaction Operations
QHacc has a number of different types of transactions. They all work in
the same way, so using them is easy. All transactions have five main
fields:
Normal Transactions
If you use single-entry bookkeeping, most of the transactions you will
probably enter into QHacc will be classified as normal transactions. They
contain only the fields listed above. As described above, clicking on the
"<new>" part of the Account Viewer is the usual way to enter a new
transaction. An opened transaction can be saved by hitting the enter
key. The changes can be discarded by pressing esc.
Market Transactions
As of v2.0, QHacc does not support market transactions. Support may be
readded at a later date. However, any market transactions you currently
have added in QHacc will be upgraded safely.
Split/Double-Entry Transactions
Split and Double-Entry transactions are handled the same way in
QHacc. In order to use this transaction type, you must specify double
entry bookkeeping from the Preferences Dialog.
Memorized Transactions
Memorized Transactions are a feature of QHacc aimed at reducing the
number of times you must enter the same transaction. If you have a
transaction that you enter into an account regularly (or just often),
you can memorize it. From the transaction popup, select "memorize."
Then, you can re-enter the same transaction as often as you like by
selecting it from the "memorized" part of the popup. Everytime you enter
a memorized transaction, the new one will be identical to the old one,
except for the date. the date of the new transaction will be the same as
the hilighted transaction at the time of insertion. This feature works
for normal, market, double-entry, and split transactions, so use it 'til
your heart's content.
Scheduled Transactions
Scheduled transactions are the only type of transaction that QHacc
cannot insert from the GUI. In fact, QHacc has no native scheduling
facility at all, so scheduled transactions are not really scheduled by
QHacc. Instead, scheduled transactions can be inserted into QHacc's
database by creating a file in a particular format (see
schedule format), and running QHacc from
cron with the --cron
argument and filename. The
--cron
argument is a shorthand way of calling the CRON
import filter, which starts the command line version of QHacc and
enters a single transaction before saving everything and exiting. In
this mode, errors are written to standard error, but nothing else is
written to the screen. The necessary transaction file can be written by
hand, or created for you by QHacc from a transaction already entered. To
have QHacc generate the file, just highlight the file in the account
viewer, and select "write to trans" from the pulldown or press CTRL-W on
the keyboard.
Reconciling
Reconciling is one of the most important functions of any accounting
program. It is the way to compare your balance to your bank's
balance. In QHacc, you can open a reconcile window by right-clicking
"reconcile" from either the Account Chooser popup or the Account
pulldown. The reconcile window allows you to enter the ending date and
ending balance for the account. When opening the window, the current
date and current balance of the account are pre-entered in their
respective fields. Changing the date will recalculate the expected
balance. The reconcile window has a Account Viewer as well, but
selecting a transaction will simply mark it as reconciled, and not open
it for editing.
Archiving and Restoring
QHacc provides a method for clearing out old transactions from
accounts. The mode is similar to the --cron mode
(above). This mode can be entered from by specifying
--archive
on the command line. The --archive argument must
be followed by an account identifier or the date of the last transaction
to prune. Account names are matched first, so if your account name
happens to be the same as a valid datestring, the account will get
archived. Why you would ever be in this situation is beyond
me. In any event, the archived transactions are put in the QHACC_HOME
directory, in a datestamped file. If an account is archived, it is
removed from the Chooser display. In this mode, just like
--cron
mode errors are written to standard error, but
nothing else is written to the screen.
--archive
is --restore
. It
must be followed by the filename from which to read the archived
transactions. If a transaction references an archived account, that
account is also restored.
Exporting and Importing
Besides archiving and restoring transactions, QHacc provides a means of
transferring data between QHACC_HOMEs. That mechanism is the --export
and --import command line options. Both options take a QHACC_HOME
argument to operate. When exporting, the entire contents of the current
QHACC_HOME are dumped into the given QHACC_HOME. When importing, the
entire contents of the given QHACC_HOME are merged with the current
QHACC_HOME. This merge tries to avoid duplicate transactions, and is
quite a bit more stringent in finding duplicates than --import (above). For example, for two transactions to be
determined to be duplicates, they must have the same date, payee, sum,
and parent account. Accounts are merged by name. Any unique data is
merged with the old data. See the plugins section,
below, for more functionality.
Plugins
As of version 2.8, QHacc has started using plugins to provide increased
functionality. At the moment, this functionality is limited to the
reading and writing of data to a QHACC_HOME. Still, this architecture
extends the possible functionality of QHacc immensly.
qhacc --export XML:<QHACC_HOME>
. If I then
want to import it into an empty MySQL database structure, I run
qhacc -f MYSQL:<QHACC_HOME> --import
XML:<export>
.
--cron
option for the command
line. It allows a user to enter transactions interactively from the
command line, thus making the GUI unnecessary. In the future, there will
likely be more additions to this type of functionality.
Reporting
QHacc supports limited reporting from the GUI and the command line. The
reports are available through the Graphs menu, or in the popup of the
Account Chooser. The Report Dialog allows for reports from any date
range and for any account or group of accounts. From the command line, the
reports are slightly more restricted. Date ranges are not supported from
the command line, though a dedicated user can create similar
functionalty by creatively using the archive and restore functionailty
in combination with the reports. In any event, the reports can be
accessed from the command line using the --breport, --dreport,
--areport
, and --preport
options followed by the
account identifier. The Journal report is also available via the
journal command line switch. This report shows each transaction
entered in QHacc and its changes to its constituent accounts.
Preferences
The preferences object is perhaps the most widely used object in
QHacc. It defines how dates are displayed, how currencies are marked,
which colors and fonts are used, and which type of bookkeeping you
prefer. Any character can be used for a currency symbol, or for the
date element separator but I wouldn't recommend using a numerical value
for either one (the default of "/" should be good for most dates). The
preferences dialog also allows a user to choose the name to display in
the titlebar of the program. This is extremely useful when using
different personalities, since using different
titles for different personalities minimizes confusion.