Jabp User Guide

First version: 3 August 2002
Last updated for version 2.36 on 8 December 2010
 

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.  There are known bugs in the Java implementation on the Nokia 9300/9500 devices which prevent Jabp from running properly.
 
 

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.

Windows Mobile 5 and 6: Go to the main IBM website www.ibm.com.  Select Support & downloads > Downloads > Trials and demos.  In the Search field select Windows Pocket PC then Websphere Everyplace Micro Environment then the Windows Pocket PC version.  It will say 90 day trial, but in fact the Java runtime is unlimited use.  Note, you will have to register at this point, but it is free.  Follow the instructions to download the IBM Java runtime, open the zip file and install the \bin, \lib and \examples directories as explained in the IBM documentation. Check that you have installed everything correctly by running the supplied golf game. [UPDATE 25 May 2008: IBM have removed the Windows Mobile Java runtime from their website.  Please contact me at malcolm@freepoc.org or through http://www.freepoc.org/forum if you wish to use Jabp with Windows Mobile devices]
 
 

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.

Windows Mobile 5 and 6: Copy Jabp.jar and Jabp.lnk from the Jabp distribution zip to the \examples directory.   You should now be able to run the Jabp program.

eeePC running Xandros: extract Jabp.jar to a suitable directory.  Open a console window and navigate to the directory containing Jabp.jar.  Type java -jar Jabp.jar.
 
 

1.5 Basic navigation

Jabp is designed to be used primarily with a pen or with a mouse. Menu options are available, as described in this Help file. Also, you can tap on any entry within a View to bring up a series of options.  Within the View screens, you can select some options from the keyboard.  So, for example, pressing the 'n' key will select the 'New' option.

A number of menu items are available. These can be selected by pressing the Menu key (where available), or from the on-screen menu. Tapping on the header panel will go up a page, tapping on the footer panel will go down a page.

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/OFX. You can import any standard QIF, OFX or OFC 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/OFX/OFC file. Once you have selected the 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.

QIF or OFX files downloaded from internet banking sites will create transactions with a category of 'None'.
 

Ø 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. The date format field is irrelevant when importing OFX files and is ignored.


2.0.4 Export QIF/CSV. This option produces a QIF file which can be read by other banking programs. Alternatively, you can export transactions or an income/expense report 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.

You can also merge older transactions into your current Jabp file. Select Merge and specify the Jabp filename containing your older transactions. The old transactions will be merged into your current file. Note that old Investments, Standing Orders and Currencies are not merged.

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


2.0.6 Sync JabpLite.   This option synchronises data with JabpLite.  JabpLite is a personal finance program designed for mobile phones written in Java MIDP and available from FreEPOC.  When using this option, changes that been made in JabpLite are imported into Jabp from the file JabpLite.sync.  Normally JabpLite.sync will be stored on the memory card of your mobile phone and can be accessed by Jabp when connected via a USB lead.  You will be asked for a directory which will typically be something like J:/document/ where J: is the drive for your phone's memory card (mounted on your PC) and /document/ is the first writeable directory.  You will also need to use JabpSync on your mobile phone.  For full instructions, see the extra documentation in the distribution zip file.

2.0.7 Import/Export JabpLite.   This option does a full data import from, or export to, 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 exported to c:\\JabpLite\\JabpLite.dat (you can change the directory).

JabpLite comes with a sister program called JabpFile which allows data to be exchanged with a Windows PC via a memory card.  Use the Export option to create JabpLite.dat and then copy to your phone's memory card.  Use the Import Data feature in JabpFile to load the file on your phone (see the documentation which is provided with JabpLite).  This backup file can also be 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 Jabp will be imported into JabpLite.  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.  When using the Filter option, there will be a small delay while the Jabp calculates totals for the date period you have specified.

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.

You can also create a new standing order from an existing transaction.  In the Transaction View, highlight a transaction and select Show.  Then select the Create S.O. option.
 
 

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. 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 the following 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 Category. When you are entering a new transaction, you may wish to create a new category. To do this, press on the "Category" or "Cat" button. This is more convenient and quicker than creating the category in the Category View.
 

2.1.5.3 Match Description. When you are entering a new transaction, you can type a few characters into the description field and press Match.  Jabp will match to the most recent transaction in this account.  Press Match again to match to a previous transaction, and so on.
 

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:
 


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.
Ø Tip: users of UIQ3 devices can access files on the memorystick directly from a PC.  You can then run Jabp either on your PC or on your UIQ3 device working from the same data files - no need to transfer files between the two.  Firstly, go through the set-up process on your UIQ3 device.  When asked where to save your Jabp data files, choose a directory on the memorystick: for example, d:/Jabp/.  Once done, close Jabp on your UIQ3 device and then connect your device to your PC via the USB lead (P990i owners can 'dock' the phone).  Ensure that you have set Connections>USB to 'File transfer' mode.  Now run Jabp on your PC by double-clicking on Jabp.jar in Windows Explorer.  Specify your home currency, then you will be asked for a data file name.  Type the same filename as you used on your UIQ3 device.  Then navigate to the Jabp directory on your UIQ3 device (which should be showing as a USB drive).  Select any one of the Jabp files which appear in the directory (they were already created from your phone).  When asked if you want to overwrite the file, answer Yes.  You should now see your Jabp data appear on your PC's screen. You can directly use your PC's screen and keyboard to update Jabp's files :-))  You only have to go through this set-up process once - Jabp will remember these settings for the future.

3.2 Known bugs or issues

3.2.1  On some devices the redraw of the screen can be slow, or be re-drawn twice.  Sometimes not all the previous display is cleared when the screen is refreshed.  This particularly impacts UIQ2 devices.

3.2.2 On UIQ3 devices, the File>Open option will not show Jabp's files.  This is a serious bug in the Java implementation.  A workaround is to use the File>Open(UIQ3) option which, though not very elegant, will enable you to select Jabp data files.
 

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