Jabp User Guide

First version: 3 August 2002
Last updated for version 1.12 on 13 Nov 2004
 

1.0 What is Jabp?

Jabp is an experiment. The idea is to design a simple banking program which can run unchanged on a number of different hardware platforms and operating systems, anything from Windows PCs to PDAs to Smartphones. The program is quite basic - certainly compared to PC programs like Microsoft Money or Quicken. But it does include functionality such as multiple accounts, categories, currencies and standing orders. It also supports importing and exporting of the standard QIF files used by other banking programs. So Jabp will enable you to keep track of your finances. And it is free software.

The program is still under development and I may provide new versions from time to time. Updated versions will be available through

http://www.freepoc.org.


Jabp is written in Personal Java. Consequently it has some limitations.  It can be a little slow on low-powered machines, and the user interface adopts a "lowest common denominator" approach - it is not optimised for a particular machine. It also requires a Java runtime to be installed and therefore needs a minimum of around 3 megabytes of available RAM in order to run.
 
 

1.1 Computers which can run Jabp

Here is a list of platforms on which Jabp has been tested:
 


Note: Due to the memory needed by the Java runtime, Nokia 9210 users will need to close all other applications before running Jabp.

Jabp does not run on smartphones running the MIDP version of Java.
 
 

1.2 A Brief History

The forerunner of Jabp was a program for the Symbian range of computers which was imaginatively called ABP - A Banking Program. I started this program in 1997 and issued periodic updates via the internet. By 2002, it had several thousand users worldwide. ABP became an indispensable program for many Symbian users, so much so that many people stopped using their PC financial programs altogether - after all, it is so much easier to keep track of things on your PDA (which travels with you) than your PC (which generally doesn't). ABP is still going strong and is available from http://www.freepoc.org. It runs on all Symbian computers including the Nokia 9210 phone.

But ABP has one drawback - it is written in Symbian's proprietary OPL language. OPL is no longer being developed by Symbian, so that means that ABP is unlikely to run on the next generation of PDA/Phone hardware. So early in 2002 I decided to write another banking application. This time, I wanted the program to be somewhat "future-proof", so I selected Java as the programming language as it runs on a variety of hardware.  However Jabp has fewer features at this point than ABP.
 

1.3 Installing Java

In order to run Jabp, your computer has to have a Java runtime which conforms to or exceeds the Personal Java standard. Brief details are as follows:

PCs running MS Windows: some PCs may already have Java installed. To check, try double-clicking the file Jabp.jar in Windows Explorer. If Jabp does not run then go to the Java homepage (http://java.sun.com) and download the Java Standard Edition (J2SE). You only need the JRE runtime environment, not the full SDK. It is free.

Symbian computers/phones: Older Symbian computers may have Java runtime distributed on a CD supplied with the machine. Follow the installation instructions.  Smartphones such as the Sony Ericsson P800 have the Java runtime pre-installed in ROM.

iPAQ with Pocket PC 2002: Install the Jeode Java runtime, supplied with the machine.

Sharp Zaurus: The Jeode Java runtime is already installed.
 

1.4 Installing Jabp
 

Once you have a Personal Java runtime on your machine, you can install Jabp as follows:

PCs running MS Windows: copy the file Jabp.jar to any directory.  Double-clicking on this file in Windows Explorer will launch Jabp. You can set up a Windows shortcut to launch the program from the main screen.

Symbian computers/phones: if you have a Psion machine (netBook, Series 7, Series 5mx, Revo Plus) then unzip JabpPsion.zip. If you have a "Communicator" machine (Nokia 9210/9290) then unzip JabpCommunicator.zip. Install the file Jabp.sis, which will create the correct directories. Copy Jabp.jar to the directory \system\apps\Jabp\ on the c: or d: drive where you installed the sis file. Note: once Jabp has been installed, then for subsequent upgrades you only need to copy the new Jabp.jar file. You do not need to re-install the Jabp.sis file.

Special note for UIQ machines (for example the P800): I have included a full implementation since there is no easy way to manually copy Jabp.jar to the correct directory.

iPAQ running Pocket PC 2002 with Jeode Java runtime: Create a directory c:\Java\ on your Pocket PC and copy Jabp.jar there. Follow the instructions supplied with the Jeode runtime to create a shortcut that can launch the program. The command line for the shortcut is as follows:
 

18#"\Windows\evm.exe" -cp \java\Jabp.jar Jabp.Jabp


You can place Jabp.jar in a different location than c:\Java\. If you do, then change the command line accordingly. Alternatively, just unzip JabpIPAQ.zip and copy Jabp.lnk to the iPAQ in the c:\Java directory. Note: once Jabp has been installed, then for subsequent upgrades you only need to copy the new Jabp.jar file. You do not need to re-install the Jabp.lnk file.

Sharp Zaurus with Jeode Java runtime: unzip the file JabpZaurus.zip and install the file Jabp.ipk which will create the correct directories. Then copy Jabp.jar to the machine in the directory:
 

/opt/QtPalmtop/java/jabp
or
/mnt/cf/opt/QtPalmtop/java/jabp (if you installed to Flash disk)
or
/mnt/card/opt/QtPalmtop/java/jabp (if you installed to SD card)


Note: once Jabp has been installed, then for subsequent upgrades you only need to copy the new Jabp.jar file. You do not need to re-install the Jabp.ipk file.
 
 

1.5 Basic navigation

Jabp is designed to be used primarily with a pen or with a mouse. All options can be navigated to and selected in this way. Alternatively you can move between items by using the Tab key (forward movement) or Shift+Tab (backwards movement).

A number of menu items are available. These can be selected by pressing the Menu key (where available), or from the on-screen menu.

When viewing a screen, such as the Accounts View, then tap or click on an entry to bring up various relevant options. This same method applies in all Jabp screens. Some machines use a double-click, others use a single-click.
 
 

1.6 Getting Started with Jabp

When you first run Jabp, it will provide some on-screen instructions, as follows:
 


Step 1. You will be shown a file selector box. On some systems this might be a File Save dialog. Navigate to a suitable directory and specify a filename.
 

Ø Tip: you may want to keep the filename quite short, since Jabp extends it to create various files. For example, a name MyAccounts would lead to MyAccounts_TransactionFile.jabp, MyAccounts_TransactionIndex.jabp and so on. You don't need to end the name with ‘.jabp’. Avoid using an underscore character in the filename.


Step 2. Enter your home currency code. This might be a code like "£" or "gbp". You can also supply a fuller description.

Step 3. Enter your first account. Enter the account name and an optional description. The home currency will already be shown. Enter the opening balance for this account and select the account type.

Once you have been through these 3 steps, you will be presented with the Accounts View. It will show the account that you have just set up. Tap or click on this entry to show further options, namely New, Edit, Entries, Delete or Sort. Click on Entries to go to the Transactions View. You can now enter a transaction, by clicking on the "No transactions in this account" message. To return to the Accounts View then press CTRL+A or navigate there from the Menu.

The next section deals with the various Menu options.
 
 

2.0 The Files Menu

2.0.1 New. Use this option to start a new Jabp data file. Your current data will be saved first. You will be presented with a File Save dialog - this is simply inviting you to give a filename. You will find that Jabp creates a directory called Jabp (except on Pocket PC) - you may wish to use this directory to store your data files. When you set up a new file, for example "Mydata", the following files will be created:
 


The files ending in “File.jabp” contain your data. The files ending in “Index.jabp” contain an index to your data. You may also see another file called
 


The IntegrityCheck file simply shows whether Jabp successfully closed last time. If it is missing, then Jabp did not close properly and when you next run the program, there will be a small delay while the index files are rebuilt.
 

2.0.2 Open. This option will bring up a standard file selector. You can navigate to your data files and select one. Note that you can select any of the Jabp files shown above.
 
 

2.0.3 Import QIF. You can import any standard QIF file which has been produced by another banking program. Select Import from the Files menu or use CTRL+I. You will be presented with a standard file selector dialog, from which you can select your QIF file. Once you have selected the QIF file, you can choose the account, the start and end dates and whether an opening balance is used. Jabp will then import the entries. Depending on the size of the file, this may take some time.

If the QIF file contains an opening balance, Jabp will set the Open Balance accordingly - providing you have selected this option. If the QIF file contains an account transfer, Jabp will import only one side - it will not create the entry in the other account. This is to avoid the potential duplication of entries if you subsequently import the other account.
 

Ø Tip: Jabp expects a QIF file which contains only account transactions. QIF files containing investments or a list of categories will not work.

Ø Tip: check the date format which appears in your QIF file. The dates will either be European format (dd/mm/yy or dd.mm.yy), American format (mm/dd/yy or mm.dd.yy) or Universal format (yyyy-mm-dd). Ensure that you choose the correct date option when importing into Jabp.


2.0.4 Export QIF. This option produces a QIF file which can be read by other banking programs. Alternatively, you can export to a comma separated value (CSV) file or a tab-delimited (TAB) file - these formats can be read by most spreadsheet programs.  Select Export from the Files menu or use CTRL+X. You will be presented with a standard "file save" dialog - specify the name for your export file. You do not need to add ".qif", ".csv" or ".tab" since the program does that automatically.

You can choose the account and dates for the export. Entries between these dates will be written to the export file. Depending on the size of the file, this may take some time.
 

Ø Tip: if you intend to use the QIF file in another financial program then check which date format the other program uses. The dates will either be European format (dd/mm/yy or dd.mm.yy), American format (mm/dd/yy or mm.dd.yy) or Universal format (yyyy-mm-dd). Ensure that you choose the correct date option when exporting from Jabp.


2.0.5 Split Files. At some point you will want to archive the older entries in your data files. Select Split Files from the Files menu or CTRL+Z. You will be asked to specify a new filename to store the older entries. You will then be asked for a date - any entry before this date will be moved to the file that you have just created. Any entries on or after this date will remain in the current file.

Once you have split the files, you will find that your opening balances have changed, but your current, today and reconciled balances should be the same.

Note that the Split Files option can take several minutes to complete on low-powered machines.
 

Ø Tip: make sure that you backup your data before using this option.


2.0.6 Import JabpLite.   This option imports data from JabpLite.  JabpLite is a personal finance program written in Java MIDP and available from FreEPOC.  When using this option, your current Jabp data will be saved and you will be asked to specify a new filename.

JabpLite comes with a sister program called JabpBT which allows data to be exchanged with a Windows PC via Bluetooth.  Use the Export Data feature in JabpBT to create a backup file on your PC (see the documentation which is provided with JabpLite).  This backup file is then read by the Import JabpLite option in Jabp.  For this reason, the Import JabpLite option is only relevant when you are running Jabp on a PC.

When using this option all Accounts, Categories, Currencies, Investments, Standing Orders and Transactions from JabpLite will be imported into a new Jabp data file.  In the unlikely event that your imported data in Jabp shows different transaction dates from JabpLite, this is probably because of different default timezones.  Use the Time Offset option to adjust by the appropriate number of hours so that the dates agree.
 

2.1 The View menu

2.1.1 Account View. This is the main screen where your accounts are shown. There should always be at least one account showing in this screen. Each account shows on a single line and the information shown will vary depending on the size of the screen on your computer. For wider screens, the Opening, Current, Today and Reconciled balances are shown. For narrower screens, just the Current, Today and Reconciled balances are shown. The definitions are as follows:
 

 
Ø Tip: you can vary the spacing on the screen using the Preferences option in the Tools menu or CTRL+Q.


If you click or tap on an entry, the following options will pop up:
 


If you change the name of an account using the Edit option, then there will be a small delay while Jabp updates the relevant transactions with the new name.
 

2.1.2 Category View. This is the main screen where your categories are shown. There should always be at least three categories showing in this screen: namely the special categories None, Split and Transfer. See Transaction View for more details about these 3 categories. Clicking on one of these categories will bring up a dialog with the following details:
 


If you change the name of a category using the Edit option, then there will be a small delay while Jabp updates the relevant transactions with the new name.

If you create a large number of categories, then you may notice a small delay on slow machines when you first open the Category View while Jabp builds the category list. If you subsequently return to this view then the display should refresh immediately.
 
 

2.1.3 Standing Order View. The first time you use this view, it will show that no standing orders have been set up. Clicking on this message will bring up the following options:
 


Entering a new standing order requires you to fill in the following details:
 


If you create a new standing order which is a Transfer, then Jabp will prompt you for the transfer account.  It will then set up two separate standing orders, one for each account.

Standing orders are checked each time Jabp runs. If a standing order is due, you will be given the option to either Defer or Process.
 
 

2.1.4 Investment View. Jabp allows you to track the current value of your investments.  These will be shown, along with your bank, credit card and other accounts in the Net Worth option.  The first time you use the Investment View, it will show that no investments have been set up. Clicking on this message will bring up the following options:
 


Entering a new investment requires you to fill in the following details:
 


2.1.5 Transaction View. This view shows transactions for the currently-selected account. To maintain acceptable response time only a limited number of transactions will be shown - by default this is the most recent 20. You can vary the default via the Preferences menu option. On fast computers you may want to increase this limit. On slow machines you may want to reduce it.

The balances in this account are shown at the bottom of the screen. The current balance is shown as C:, today's balance is shown as T: and the reconciled balance is shown as R:. If this account is based in a currency which is not your home currency, then the foreign currency balances will be shown with an asterisk following.

When you select this view for a new account, there will initially be no transactions shown. Click on the message to bring up a dialog with thefollowing options:
 


When you enter a new transaction, one of the fields will be Category. You can select any valid category from the list, but note the three special categories None, Split and Transfer. The purpose of these categories is as follows:
 


If you selected Split, then after tapping OK to create the transaction you will be shown a new screen for the split (multiple) entries. These multiple entries must sum to the original amount of your transaction. When you have finished entering splits, tap on the list and select Close.
 

Ø Tip: ensure that your splits agree to the total of the original transaction. If you go to another view without balancing the splits, then Jabp will show a warning message. Return to the original transaction and edit it, so that the total of the splits agree to the original transaction.


If you selected Transfer, then after tapping OK to create the transaction you will be shown an extra dialog where you can enter the offsetting account.
 

2.1.5.1 Regular transactions. When you enter a new transaction, you will see an extra button called "Regular" or "Reg". This button is used to record regularly-used transaction details. For example: if you have certain transactions that occur frequently, you can store the details and bring them up again with a couple of pen taps/mouse clicks. It works as follows.

1) Complete the relevant fields in the New Transaction dialog, then press the Regular button.

2) Store the details as a new "regular transaction".

3) Next time you press the Regular button, you can select this transaction and bring the details forward without needing to re-enter them.

You also can edit, sort and delete Regular transactions using the displayed options.
 

2.1.5.2 New category. When you are entering a new transaction, you may wish to create a new category. To do this, press on the "New category" or "Cat" button. This is more convenient and quicker than creating the category in the Category View.
 

2.1.6 Currency View. This simple view will allow you to enter additional currencies. When you first select the Currency View, only your home currency will be shown. Click on the list to bring up the following options:
 


When entering a new (foreign) currency you will be asked to specify an amount of the foreign currency and an amount of your home currency. These two amounts are used to calculate the exchange rate for the foreign currency. If you then enter a transaction using the foreign currency, the amount will automatically be converted and stored in your home currency.

If you change the name of a currency using the Edit option, then there will be a small delay while Jabp updates the relevant transactions with the new name. Also, if you change the rate for a currency then the program will check if there is any account based in that currency. If so, the program will create an FX adjustment entry so that the correct total in the foreign currency is maintained.
 

2.1.7 Graph View.  There are 3 possible graphs to choose from.  You can select a bar chart which shows your top expense categories, a line graph which projects the future balance for an account, or a line graph which shows historical balances in an account.  The 'historical balance' option can take a long time to complete for large files on low-powered machines.  In the category expense graph, tapping on the legends will bring up a dialog with the top expense categories.  In the future balance and account graphs, tapping to the left of the Y axis or below the X axis will show the maximum and minimum values and the dates on which they occurred.
 

2.1.8 Find View. This option allows you to find all entries which match your specified criteria. This can be for a single account or for all accounts and for a range of dates. You can search by:
 


On low-powered machines there may be a small delay while Jabp searches your data file. When the results are shown, you can click on an entry and press Close to end the Find View. You cannot edit any entries shown in this view.
 

2.1.9 Go To View. When selecting this option you will be asked to choose an account. You will then be taken to the Transactions View for the account you have chosen.
 

Ø Tip: using Go To (CTRL+G) is often the quickest way to move between the Transaction Views for different accounts.

 

2.2 The Tools menu

2.2.1 Preferences. This option will allow you to change the screen layout for Jabp. The program is designed to run on a range of different machines, from Windows PCs to smartphones. When you first run Jabp, it will self-configure to the size of the machine that it is running on. Using Preferences, you can further customise the display. There are general options and machine-specific options (the latter are generally to code
around bugs in the Java implementations on those machines).

The general options are:
 

The machine-specific options are:

1) Symbian
 


2) Nokia 9210
 


2.2.2 Compress. When Jabp deletes or updates an entry, that entry is marked as deleted but is not immediately purged from the data file. You can periodically reclaim this space by using the Compress option.  You can see how much space is reclaimable in the Information option.
 

2.2.3 Regenerate. In the unlikely event that your balances appear to be incorrect, you can use this option to recalculate all your account and category balances. The option may take a considerable time to run for large files on low powered machines.
 

2.2.4 Password. Use this option to set a password to protect your data. The password will be requested each time you open the data file.
 

2.2.5 Future Balance. This option will calculate the future balance in your account(s) at some date that you specify. All future-dated transactions and future-dated standing orders will be included. Typically you would use this option to calculate your future balance out a couple of months. If you specify a date that is very far in the future, then the program will take a long time to complete the calculation.
 

2.2.6 Net Worth. This option shows the total balances in each different type of account (banks, credit cards etc) and the current value of any investments plus a total net worth number.
 

2.2.7 Information. This option shows the name of your data file and the number of accounts, categories, transactions, standing orders and currencies.  It will also show you how much space can be reclaimed by using the Compress option.
 

2.2.8 Help.  The Help option displays some of the text from this User Guide.
 

2.2.9 About. This gives brief details of the program and author.
 
 

3.0 A brief word about double-entry book-keeping
 

Jabp uses double-entry book-keeping. In plain language, this means that every debit has an equal and opposite credit. In Jabp you will either enter
 

Debit Bank account, Credit Category


or
 

Debit Category, Credit Bank account


For example, I pay £20 for petrol on my Visa card. In Jabp I will show
 

Debit Account Visa £20, Credit Category Petrol £20


If I receive a cheque for £100, then I will
 

Debit Category Receipts £100, Credit Account Mybank £100

 

In the above examples, I would already have set up accounts Visa and Mybank in the Accounts View and categories Petrol and Receipts in the Category View.
 
 

3.1 Transferring your data between machines

Your data files can be directly transferred between different machines. All the files referred to in section 2.0.1 should be moved together. They should all reside in the same directory. On the new machine, run Jabp (you may need to go through the new file set-up process the first time) then use the File>Open (CTRL+O) option to navigate to the files that you have just transferred. Jabp always remembers your last-used file, so you can move data files between (say) a PC and a smartphone and, providing you keep the same filename, Jabp will open the file automatically.
 

Ø Tip: options which take a long time on a PDA or smartphone - such as using Regenerate or Split File - can generally be completed in a few seconds on a Java-enabled PC.


3.2 Known bugs or issues

3.2.1 On Symbian R5 machines, for scrolling dialogs, the last item is sometimes not brought into view.
 

3.2.2 On narrow screens, the main view can be scrolled horizontally but the header remains stationary.
 

3.2.3 On Symbian machines after you have edited an entry, the cursor moves to the top of the display instead of staying on the entry. This is a rather irritating "feature" of the Symbian Java implementation. The program then returns the cursor to the correct entry but, if the entry is someway down the list, it may not immediately be visible. Pressing the up or down arrow key will refresh the list.
 

3.2.4 When opening an existing file which is password-protected, the password prompt seems to require the Enter key or OK button to be tapped twice. I don't know why this is.
 

3.2.5 The program icons for Jabp on Symbian machines are "minimalist", and non-existent for other machines.
 

3.2.6 On some screens, the dialog headers are too long and may be truncated.
 

3.2.7 On the Sharp Zaurus, Popup menus can be partly off-screen. This seems to be a bug in the Java implementation on this machine. Jabp therefore shows options with Buttons by default.
 

3.2.8 On the Pocket PC, it is not possible to create a c:\Jabp directory from within the program. Jabp data files are therefore created in the Documents directory by default.

3.2.9 On Windows PCs when viewing a graph, pressing the Esc key should exit - but doesn't.  Click the mouse anywhere on the screen instead.

3.2.10 The Nokia 9210/9210i/9290 machines require the Tab key to be pressed before Jabp's dialogs are in focus.  This is a quirk of the Java implementation on these machines.
 
 

3.3 Troubleshooting

3.3.1 On PDA's or smartphones with limited memory, it is possible for Jabp to run out of memory. You could get an error message, or the program might not respond to your request. Try closing down other running applications to free up memory. If you can close Jabp using the Close option (CTRL+E), then do so. Check available memory and re-launch Jabp. Jabp can require around 700K of memory plus the Java runtime. For example, it is best to have around 3 megabytes of free memory to run Jabp on Symbian machines.
 

3.3.2 In the unlikely event that a program error occurs, your data should be safe. Here are the recommended steps:
 


 

Malcolm Bryant

malcolm@freepoc.org

http://www.freepoc.org