DualCalc > Technical Help
Quite technical details ...
(Page last updated: 15th December 2006)
This section provides additional technical details.
Some of this material is quite complex and of limited use, most users probably won't want to bother with it.
Anomalies in the Program
The way the program has been written presents the user with a few minor anomalies:
The 'toggling' and 'tumbling' option buttons are not a standard way of doing things in Windows so they may initially confuse some users, but they are pretty intuitive once you've used them a few times. The only problem is that they display the program's current setting, not what the button will do when you click on it - for example, you have to remember that you need to click on the button that says '[ Rebate ]' to do an APR calculation.
The 'selection' or 'focus' indication on the dialogue's buttons (a dotted line around the edge of the button's face) can sometimes obscure the text on the button - this is because the buttons have been kept quite small to keep the dialogue compact. With XP Visual Styles enabled the text on the buttons can sometime be clipped or very close to the bottom of the button
The program will allow the user to type nonsense into it's text boxes, eg Loan amount £: [ Wibble ] - Windows only seems to have two basic modes of entry - numbers only (and that doesn't even permit a decimal point) or everything. In order to allow the entry of amounts, calculations and dates, it was necessary to allow everything through. This is however resolved when the program validates the user's input.
There is nothing to prevent you running multiple copies of DualCalc, as it was thought this might be a useful facility (although, from v1.02 you do get a warning). Different copies will however all share the same options and templates. There may be disc access errors if, for example, the user tries to use two copies to log calculations in the same file at the same time. If this presents a problem, you could avoid it simply by installing DualCalc twice in different locations, so you have two completely independent copies. It would probably be simpler to do this by using the Dualcalc Archive installer [see here for details]. You can also tell one copy of DualCalc to use different folder locations using the 'Start in' entry in a shortcut.
Note: prior to version 1.03 of the program, this section also referred to 'issues' connected with DualCalc using a 'windowless' dialogue for it's interface. These have been resolved by using a dialogue docked to a window.
Anomalies in the 2004 Early Settlement Regulations
There are a few of issues with the 2004 Early Settlement Regulations as they are currently written which have had to be reflected in the way the program operates, use the links below to read further details:
Note: prior to version 1.00e of the program, this section also referred to another 'issue' concerning the treatment of multiple advances by the new Early Settlement Regulations. This has now been found to be wrong.
Anomalies in the Calculation of Periods
[text to follow]
Program File Locations
The Dualcalc program is not terribly bothered about where on disc you save or run it from, provided it's in a location where the user has rights to save and run programs. It's probably a good idea to use the special 'Program Files' folder as this is a standard location and to use a folder in there called 'DualCalc' so that all the program's files are kept separate. This is what the program's installers do by default.
Things are a little more difficult when it comes to where to store the resources Dualcalc need to save somewhere (settings, templates, lists of add-in tools, etc) and where you save the data you create with the program (saved calculations, or logs of calculation results).
Different versions of Windows present different problems for a program which wants to save it's information on disc and where it wants make some of that information available to other programs such as a web browser or text editor. Under Windows XP and Vista there are limitation on a program or user accessing the 'Program Files' folder for security reasons. In those systems it makes more sense for DualCalc to to use the special 'Documents and Settings' folder which provides 'Applications Data' folders. In Windows 95 and 98 however, generally there is no 'Documents and Settings' special folder and the same restrictions don't apply, so it is probably okay for DualCalc to use the same folder as the program is sitting in inside 'Program Files'.
You may also want to specify where to save the data yourself, for example because you want to use a particular drive or folder, or because several users want to share one copy of DualCalc across a network but retain their own settings and data.
DualCalc deals with these issues as follows:
Command Line Switches
The program provides some additional options and settings via 'command line switches'.
The 'command line' is the text command which calls the program. Once you have installed the program and created a shortcut as per the instructions in 'Getting Started', you can right-click on the shortcut and select 'Properties' from the context menu. The 'Shortcut' or 'Program' tab in the resulting Properties dialogue contains the text of the command line in the entry marked 'Target:' - the Properties dialogue will probably open with this tab and the Target item already selected.
The switches in question are just particular words, preceded by a hyphen (minus sign), added to the command line, for example, as enforcement colleagues in Eire and Malta have expressed an interest in the program, it can be modified to display in Euros with a 'euro' switch by adding '-euro' to the command line.
To add a switch simply edit the 'Target' in the shortcut's properties. You will probably find that the current contents of the Target is in quotes and switches should be added after the closing quote, and separated by spaces, eg:
Target: [ "...\DualCalc.exe" -euro -display ]
Having added any required switches, just click on Apply and Close/Okay and re-start DualCalc. For example, when you run the program with the above switches it will now start with none of the display greyed-out (see 'display' below) and using Euro rather than Pound/Punt signs.
Listed more or less in the order they were added to the program, the available switches are as follows (remember to precede the names below by a hyphen):
Customising the Program
The program uses an HTML template for the layout of it's log files. If there is none already present, it builds it's own default version during startup. You can modify the template to customise the way your logs look - eg to include your name or the logo of your organisation - but this requires some knowledge of HTML and, perhaps, CSS. If the program sees that the template file is already present it does not overwrite it, so your modifications will be retained (installations now come with the default template already present and this may overwrite your customised version, so keep a backup).
To change the log, all you need to do is modify the script in the file Template.htm, you will find in the 'Resources' folder which is inside the folder in which DualCalc is installed. NOTE: The script contains a marker <!--DualCalc--> which indicates where the text and table containing the logged calculation should be inserted into the page. Your revised template must retain this marker or DualCalc will complain that it can't find it.
DualCalc also uses an HTML template for its 'Print via the browser' facility (tick 'Use browser' in the output group in 'Options'). This is kept in a file called Printing.htm in the 'Resources' folder, so an advantage of this facility is that you can modify this too and change the printed layout. Again you should retain the <!--DualCalc--> marker in the body of the page and the opening body tag should additionally contain a onLoad="print()" command to tell the browser to print the page once it's rendered. As printouts are only intended to be produced on the user's own PC (I don't recommend sending the printing version to others, they might be annoyed that it tried to print as soon as they open it), the above comments about using a single file don't really apply with Printing.htm, but it may make sense to keep the two templates looking the same.
There is no way to alter the basic format for printing direct to the printer as this is 'hard-wired' in the program's code and broadly follows the layout for default log. You can however specify settings for the font (including style and size) and the page margins in 'Options'.
Changing the 'badge':
The image top left of the main dialogue is a taken from the file badge.bmp in the 'Resources' folder, and you could change this for your own organisation's 'badge'. We have no objection in principle to you doing this provided you don't, for example, use it to imply any form of endorsement by the OFT or other enforcement agencies for your products if you are a commercial organisation, or to claim or imply ownership of the program or its copyright.
The format for the badge is a Windows bitmap file 326 x 24 pixels in size with a colour depth of 24 bits, a number of alternative 'OFT' badges are included in the file 'badges.zip' inside 'Resources' - they have different names so you will have to delete the current badge.bmp (there's a backup copy among the alternatives in badges.zip) and rename your choice to badge.bmp to use it.
You should be able to produce your own badge with the basic facilities of Paint (usually somewhere in: Start button, All Programs, Accessories), but you may get a better result with more sophisticated image editors. Alternatively, you can simply delete 'badge.bmp' and leave the space at the top of the dialogue blank.
The program does not cater for different size badges for larger display sizes (ie those using the '-size' switch).
You cannot change the copyright message in the 'information line' at the bottom of the main dialogue.
Changing the icon:
The program's Resources folder contains a file called 'DualCalcIcons.ico' which provides some alternative DualCalc icons. You can use these in shortcuts by right-clicking on them, selecting Properties, clicking the 'Change Icon...' button, navigating to the .ico file in Resources, and selecting an alternative.
You can install another icon of your own choosing in the same way by looking for alternatives already on your PC (there's often a selection in 'C:\WINDOWS\system32\SHELL32.dll' or other .dll, .exe or .ico files) or designing your own with one of the many free icon design packages available on the Web (try this one).
Although the opportunity for abuse in a 32 x 32 pixel icon is limited, the provisos mentioned above in relation to badges apply here too.
Building Saved Calculations
Exceptionally you may come across a calculation which is very difficult or tedious to enter. If you have, or are able to produce, the details of the calculation in an electronic format, you may be able to save yourself a lot of time by producing a 'Saved Calculation' file which DualCalc can load.
The sort of thing you can do if, for example, you have the details of a long random set of repayments in a spreadsheet or document, is simply copy them into a text editor or word processor, format them as a saved calculation, and then save that and load it into DualCalc - this might not only save you time but also mean you're more likely to enter the correct values.
If it is possible to calculate the repayments in question (eg because they relate to some sort of model or example agreement) you may also be able to use a spreadsheet or program to actually produce the repayment etc details required and either transfer them to a text file or write a saved calculation directly - although if you have the necessary skills to do this you may equally want to do the actual calculation in your spreadsheet or program and avoid DualCalc altogether.
Saved File Format
To produce your own saved calculation file (as opposed to one saved by DualCalc), you need to know the correct format. A saved calculation is a plain text file (the sort of thing you can write with Notepad) and DualCalc expects it to have a '.txt' file extension. If you are using a word processor, it is important to save the text of the calculation in plain text (or ASCII) format in a file with a '.txt' extension.
The saved information must start with the words 'DualCalc Calculation' as the first text on the first line, a file which does not contain this text will be rejected.
The general format is 'Variable=Value' where 'Variable' is one of the items of information making up the details of the calculation (as shown in the table below) and 'Value' is its value for the particular calculation (eg Loan=1000). There should be no space either side of the '=' sign and each variable and its value should either be specified on separate lines or separated by TAB characters, commas, semi-colons or spaces.
The program will not try to read variables that are not relevant to the type of calculation you have specified (eg it won't try to read information on a rebate calculation from a file which indicates that it relates to an APR calculation).
The program initially starts at the beginning of your saved file, and checks for the 'DualCalc Calculation' text on the first line, then it looks, starting after that, for the first variable, after that for the second, and so on. If it gets to the end of the file without finding the next variable it will start again from the beginning and only give up and set the values to zero if it still can't find it. So it will still find variables if they are not in the order given below but it will however speed up loading of calculations (possibly considerably) if you stick to that order and make sure you specify all the relevant variables, rather than just omit them if they are zero.
The following variables can be used to describe a calculation:
Using 'Log=' and 'Chain=' together you can carry out a series of calculations automatically and record the results in a log without further user intervention.
This is a fairly straightforward example of a calculation saved by the program:
Describe="Saved example" Price=0 Simple=0 APRcalc=1 Round=1 Exact=0 Loan=5000 Initial=0 Final=0 PPA=12 DIY=365.25 RelDate=0 Levels=3 Level_1=100 Length_1=3 Level_2=102.23 Length_2=9 Level_3=103.41 Length_3=48
The problem solved by the example is the unlikely one where an agreement has repayments which increase at regular intervals - eg a loan with 120 repayments where the repayments increase by £2.75 every 3 months. This would be a bit of a pain to work out and enter, even using levels or the series facility ... however you could now do it with the input tool.
However, the text in a page can be copied from the browser (in IE, right-click on it and choose 'Select all' from the menu, then right-click again and choose 'Copy', or just key Ctrl-A, Ctrl-C). You can then paste it into, eg Notepad (you should find this listed under 'Accessories' in 'All programs' on the 'Start' button) where it can be saved as a .txt file and then loaded into DualCalc. You could also paste and save it using a word processor such as word, but remember to save the file in plain text format with a .txt extension (in some word processors this format might be called DOS text or ASCII text).
You can read the source code of the example to see how it's done by using your browser's 'view source' option (in IE, right-click on the page and select 'View Source' from the menu) - you'll have to let the page run through the program first, answering or cancelling all the prompts.
It might help to know that some browsers aren't very helpful in telling you what's wrong if you mess up the script, often if you simply leave out a semi-colon or bracket the page just does nothing. It helps to make sure your browser's option to display script errors is turned on (in IE this in the 'Tools' menu, choose 'Internet options' and it's one of the options listed under 'Browsing' in the 'Advanced' tab in the dialogue - look for 'Display a notification about every script error' - you may also want to turn this off again after you get your script working as there are quite a lot of pages on the Internet with script errors and it can become annoying).
Please note, you probably won't want to bother with reading this section unless you're a programmer intending to write tools to add in to DualCalc ...
To add tools to the 'Add-ins' list in the 'Tools' dialogue you have to create or modify the file 'Toolset.txt' in the Resources folder inside DualCalc's folder. The format is similar to saved calculation files and should start with a line containing the text 'DualCalc Tools'
After that, there should be pairs of lines specifying 'Tool=' followed by the text you want to appear in the Add-ins list in the Tools dialogue and a second line 'File=' specifying the file which will be run when the user chooses that tool.
Add-ins - BBC BASIC programs:
Probably the best way to write your own add-ins is with BBC BASIC, and files with a .bbc extension are recognised as BBC BASIC for Windows programs and get special treatment. There are a number of points which might help with integrating your own BBC BASIC programs with DualCalc:
DualCalc will 'CHAIN' other BBC BASIC programs, so you don't have to have a copy of BBC BASIC installed on the PC in question to run them. In practice, this means that DualCalc quits before the add-in .bbc program is run (see the information on Auto.txt and '-quit' below). Note: You must provide a '.bbc' extension to the name for DualCalc to work in this way.
DualCalc operates with a hidden program window, using dialogue boxes to communicate with the user. If you want your program to use a window rather than just dialogues, you may need to include a '-show' switch in the filename in 'File='. This tells DualCalc to reveal and maximise the window before CHAINing the .bbc program. The window is maximised rather than restored because I have noticed that this seems to avoid problems with the colour palette in 256-colour screen modes. Your .bbc program should also make sure it chooses an appropriate screen mode in it's initialisation sequence, for example by using the following:
DualCalc sets the static integer variable Z% to 'TRUE' (-1) as a flag indicating that the add-in program has been CHAINed from DualCalc. Your program can make a note of this value (or just avoid using Z%) and CHAIN DualCalc when it closes if it is 'TRUE', allowing you to switch between DualCalc and your add-in program. Note: BASIC programs can't CHAIN the DualCalc.exe file, so DualCalc saves a .bbc version of it's code in the Resources folder and your add-in should CHAIN this instead. Your .bbc program should also hide the program window when re-starting DualCalc. You could do this, for example, with:
IF Z%=TRUE THEN
From the introduction of network operation in version 1.01a, if your program changes, or allows the user to change, the working folder, for example by including a file browse dialogue, it should also ensure that the working folder is reset to DualCalc's folder before it quits, otherwise DualCalc will assume is in its own folder and try to build its default files and folders in the new location when it restarts. The BBC Basic for Windows manual provides a routine for locating the working folder and this could be used to record the location when an add-in starts up.
When DualCalc starts up again it looks for a file called Auto.txt in the Resources folder inside it's own folder. If it finds one, it loads it as a saved calculation and also loads the content of dialogue.txt [see below] from the same folder. It then deletes Auto.txt to prevent it being run again. Your add-in can create or amend these files to produce a calculation which DualCalc will carry out when it is CHAINed by your add-in.
If you want to experiment with BBC BASIC for Windows there is generally a free, restricted memory, version available from the BBC BASIC for Windows Website.
Add-ins - All Types:
There are also some general points which might help with integrating .bbc and other add-ins with DualCalc:
if you don't specify a path in 'File=' DualCalc will automatically assume your file is in the 'Tools' folder inside DualCalc's folder.
For non .bbc files the filename specified in 'File=' is generally passed to Windows to execute, so it needs to be something the user's PC knows how to handle, based on its file extension - for example, .exe files will be run as Windows (or possibly DOS) programs, .txt files will probably be opened in the user's text editor, .htm, .html, etc. files will hopefully be opened in the web browser, and so on.
The purpose of an add-in might be to modify the current calculation or user input in some way, so it needs access to this information. You can get DualCalc to save the current information before running an add-in by including a '-save' switch in the filename in 'File='. The current calculation will then be saved in Auto.txt and the dialogue content will also be saved in Dialogue.txt. The add-in can modify these files so that they can be loaded by DualCalc.
Alternatively, the purpose of an add-in might be to create an entirely new calculation which DualCalc should then load on a re-start. Either way, you need to get DualCalc to quit when your add-in is run and you can make it do this by including a '-quit' switch in the filename in 'File=' (NB: this is not necessary for .bbc programs as DualCalc will quit before running them anyway).
NOTE: programs compiled to .exe files from BBC BASIC are not recognised as such by DualCalc but also seem to be run by BBC BASIC for Windows with a window which remains hidden. Even if you use -show to reveal and maximise the window before setting it's own screen mode there may be problems with screen colours in 256-colour modes. It may be preferable to load such .exe files with a '-call' switch in the filename, which triggers a different method of calling the program. Alternatively, from version 1.01a, you could try the new -run switch.
Even so it is probably best to run the .bbc file itself as this offers better integration with DualCalc and takes less disc space.
Here's an example of a Toolset.txt file
Tool=Loan Scheduler v5.7
File=schedule.bbc -show [note 1]
Tool=Schedule Builder v2.1
File=multical.bbc -show -save [note 2]
Tool=Some other Add-in
File=c:\program files\my progs\addin.exe -save -quit [note 3]
1. The schedule.bbc program uses an old DOS-style display so -show needs to be specified. It also CHAINs DualCalc when it quits and can create an Auto.txt file which DualCalc will load when re-started. It doesn't need to modify the existing calculation so '-save' isn't used and, because it's a .bbc program, you don't need to specify '-quit', DualCalc will quit anyway.
2. I've assumed here that Multical.bbc (which also uses an old DOS-style display) modifies the existing calculation in some way (actually it doesn't, this is just an illustration) and so uses '-save'. Again, because it's a .bbc program, DualCalc will quit anyway.
3. The fictitious program addin.exe is also assumed to modify the existing calculation. Because '-save' and '-quit' are specified DualCalc will save the current calculation and close after running it. It is assumed that addin.exe is capable of running DualCalc.exe when it's finished (eg by using a Windows 'ShellExecute' command).
From version 1.01 DualCalc recognises .add files distributed along with add-ins. These will generally have the same name as the .bbc add-in program file and should take the same format as a Toolset.txt file for a single program, eg:
Tool=Period Rate Converter
When DualCalc sees one of these files in the Tools folder, it checks through the current Toolset.txt file and either replaces an existing entry if the Tool= or File= information is the same, or adds the new information to the end of the Toolset.txt file if there's no match. It then deletes the .add file to avoid having to check it every time it starts.
All you have to do to remove an add-in is look in DualCalc's 'Tools' folder and remove the program you no longer need. If you're not sure which file to remove (or if it seems to be somewhere else) check in the toolset.txt file in DualCalc's Resources folder which should indicate where it is (see above).
Remember to keep a back up, or a copy of the installer, if you think you might need the add-in again in the future.
When DualCalc starts it looks through the toolset.txt file and checks that all the files referred to in the 'File=' lines are actually there. If they are not, the user will be warned and the toolset.txt file will be modified to remove the missing tool.
The format of saved calculations is explained here. DualCalc also saves a reference file containing the text actually sitting in it's main dialogue every time the user click a button in the dialogue - it does this in an effort (not always successful) to restore the dialogue if the user closes it and then decides to cancel the close.
It shouldn't normally be necessary for your add-in to modify Dialogue.txt, because it will largely be replaced by the details in any re-loaded Auto.txt calculation your add-in creates or modifies (in fact, the most you are likely to need to do is ensure it's contents is discarded by deleting it), but if the need does arise, for example because you want your add-in to insert a value in DualCalc's dialogue rather than generate a complete calculation, the format of Dialogue.txt needs some explanation:
First, the file format is simpler than saved calculations: it has no identifying text such as 'DualCalc Calculation' at the start; it is read sequentially from the start, so the variables have to be in the right order; it's assumed that all the variables are present even if their values are blank; and the program does not actually look at the variable names describe below, just the bit after the '=' sign up to the next carriage-return.
Second, the variable names are rather obscure and some refer to the position in the dialogue rather than what they represent. Probably the best way to illustrate this is with the following table which approximates the dialogue itself:
Where a cell in the table above contains the same text as the dialogue it's content is static and isn't saved in Dialogue.txt.
The '?idx' (index) values relate to the top row currently selected in the relevant panel, as the spaces containing the row numbers have not been shown above, the indexes are shown in the same space as the first amount in the panel.
The specific order in which the variables are saved is as follows:
The descriptive text which the program might change: LoTx, InTx, RdTx, LvTx, LnTx, OTx1, OTx2, OTx3, OTx4, OTx5,
The loan inputs: Inp1, Inp2, Inp3, Inp4, Inp5, Inp6, Inp7, Inp8, Inp9, InpA,
The levels panel data: Lidx, LvA1, LvN1, LvA2, LvN2, LvA3, LvN3, LvA4, LvN4, LvA5, LvN5, LvA6, LvN6, LvA7, LvN7, LvA8, LvN8, LvA9, LvN9, LvAA, LvNA,
The extras panel data: Eidx, ExA1, ExT1, ExA2, ExT2, ExA3, ExT3, ExA4, ExT4, ExA5, ExT5, ExA6, ExT6, ExA7, ExT7, ExA8, ExT8, ExA9, ExT9, ExAA, ExTA,
The advances panel data: Aidx, AdA1, AdT1, AdA2, AdT2, AdA3, AdT3, AdA4, AdT4, AdA5, AdT5, AdA6, AdT6, AdA7, AdT7, AdA8, AdT8, AdA9, AdT9, AdAA, AdTA,
The calculation outputs: Out1, Out2, Out3, Out4, Out5, Out6, Out7, Out8, Out9, OutA, OutB, OutC, OutD.
Finally, just to complicate things further, those names with a number in them use hexadecimal digits (this is to keep all the variable names the same length), so, eg 'Out?' goes from 'Out1' to 'OutD', not 'Out13'.
If you need to manipulate this file, it would probably be an idea to look at the copy in the Resources folder beforehand.
If you encounter any problems or errors while using the program you can report them by emailing here:
Both myself and the credit team have access to emails sent to that address.
The resources we are able to continue devoting to developing the program are limited so we'd like to lay down a few common-sense ground rules to keep the work to a minimum:
Millennium (Year-2000) Compliance
With legislation for APR calculation first published in 1977 and some agreements having terms in excess of 25 years (not to mention the possibility that you may have to deal with past or future agreements), Year-2000 compliance has always been an issue for credit calculators - ie we didn't have to suddenly panic about it in 1998. The date handling routines used in DualCalc were first developed back in the early 1980s but, even then, it was necessary to be able to deal with dates in the next century. Consequently the routines have always provided four-digit date entry, been aware of the Gregorian calendar rules on leap years, and so have been, and remain, Year-2000 compliant.
DualCalc additionally uses an inferred century facility where the user enters two digit years, generating a date within +/- fifty years of the date at the time of entry, according to the system clock.
The routines store and manipulate dates in signed four-byte integers as the number of days since an arbitrary date (31 December 1599 by the current calendar), potentially allowing for a range of dates in excess of 5.8 million years (ie &7FFFFFFF days) from that date. However the program currently limits dates to the year range 1600 to 99999.