|
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:
you can specify where the program should save it's resurces and data using the 'Start in' setting in the properties if the shortcut you use to run DualCalc:
if the system provides a location for the 'Documents and Settings/All Users/Application Data' folder, DualCalc assumes that it's data should be stored in a folder called 'Dualcalc' in there. if the system does not return a location for this folder ...
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):
| Name |
Function |
| display |
This forces the program to 'ungrey' all the elements in its main dialogue, you will receive an alert about this when the program starts. This is purely so that you can take a screen-shot of the dialogue without any elements greyed-out, eg for documentation such as the 'quick help' facility in this help file. If you begin to use the program in this mode, boxes will become greyed in the usual way as you switch modes. |
| load: |
This forces the program to load a saved calculation on startup. The name of the saved calculation file should be given after the ':' (colon) in the switch, preferably as a full filename. If the name includes spaces you should enclose it in double quotes, eg: -load:"C:\My Calcs\loadme.txt"
This is intended mainly for use by external tools which build calculations and then get DualCalc to carry them out.
Note: the program also automatically loads a calculation file called auto.txt in the Resources folder when it starts.
|
| size: |
This tells the program to adjust the size of the dialogue's characters to increase the size of the display. This is intended for use in demonstrations, and by those with some loss of visual acuity or for use with higher screen resolutions, although it is likely that such users will already have their screen set to provide larger characters etc and DualCalc should use their preferred settings by default.
A value in the range 1-6 should be given after the ':' in the switch, 1 being normal size and 2-6 giving progressively larger displays, eg: -size:2 will give a noticeably larger display. |
| euro |
As described above, this tells the program to use Euro symbols in place of Pound/Punt symbols.
The program's Resources folder contains a file called 'DualCalcIcons.ico' which provides some alternative icons, including one where the Pound/Punt sign is replaced by a Euro symbol. You can use this in shortcuts by right-clicking on them, selecting Properties, clicking the 'Change Icon...' button, navigating to the .ico file in Resources, and selecting the Euro alternative.
|
| itlog |
This stands for 'iteration log' and tells the program to record the details of the progress of an APR iteration in the file 'itlog.txt' in its 'Resources' folder.
If the user prints or logs a calculation with this switch and the 'Analyse' check box in Options set, the information will also be recorded in the program's output.
Abbreviations
The information output is quite brief, this is what the abbreviations mean:
| Method | the method being used (Newton's or Bisection) |
| iter | iteration N using the method |
| x | the PV of a payment is Ax^t where A is the actual amount and t is the time in years/periods |
| sPV | sum of the present values at this x |
| sDV | sum of derivatives in Newton's method |
| lox and hix | low and high x of the current range in the Bisection method |
| diff | adjustment to x for next iteration in Newton's method |
| range | the length of the current range in Bisection (hix-lox) |
Here's an example of a log (note the numbers may wrap or get pushed together if displayed in too narrow a browser window) ...
| | | | | | |
| Iteration Log: |
| |
| Method |
| iter | x | sPV | sDV or lox | hix | diff or range |
| Newton's |
| 0 | 1.0001 | 0 | 0 | - | 0 |
| 1 | 0.97437780771 | 20.0780286071 | 780.572214865 | - | 0.0257221922902 |
| 2 | 0.971629418805 | 1.77736343425 | 646.692842807 | - | 0.00274838890521 |
| 3 | 0.971601508616 | 0.0176912455232 | 633.863346754 | - | 2.79101885506E-5 |
| 4 | 0.971601505777 | 1.79919564403E-6 | 633.734423768 | - | 2.83903726316E-9 |
| 5 | 0.971601505777 | -8.52651282912E-14 | 633.734410655 | - | -1.34543945946E-16 |
And the 'spooled' equivalent will look like this ...
Iteration Log:
Method
iter, x, sPV, sDV or lox, hix, diff or range
Newton's
0, 1.0001, 0, 0, -, 0
1, 0.97437780771, 20.0780286071, 780.572214865, -, 0.0257221922902
2, 0.971629418805, 1.77736343425, 646.692842807, -, 0.00274838890521
3, 0.971601508616, 0.0176912455232, 633.863346754, -, 2.79101885506E-5
4, 0.971601505777, 1.79919564403E-6, 633.734423768, -, 2.83903726316E-9
5, 0.971601505777, -8.52651282912E-14, 633.734410655, -, -1.34543945946E-16
For the raw output in itlog.txt, you need to know the order of the data:
| Newton's | Bisection |
| iter | iter |
| x | x |
| sPV | sPV |
| sDV | lox |
| - | hix |
| diff | range |
Here's an example of the raw output ...
Newton's
0
1.0001
0
0
-
0
Newton's
1
0.97437780771
20.0780286071
780.572214865
-
0.0257221922902
Newton's
2
0.971629418805
1.77736343425
646.692842807
-
0.00274838890521
Newton's
3
0.971601508616
0.0176912455232
633.863346754
-
2.79101885506E-5
Newton's
4
0.971601505777
1.79919564403E-6
633.734423768
-
2.83903726316E-9
Newton's
5
0.971601505777
-8.52651282912E-14
633.734410655
-
-1.34543945946E-16
|
| local |
this switch forces the program to use the current directory (set by 'Start in' in its shortcut) evem if it is the same folder as the program's and there is a 'Documents and Settings\All Users\Applications Data' folder.
You can use this to ensure the program's data is stored where you want it to be.
|
Customising the Program
Customising Logs:
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.
Bear in mind that the intention is that logs should be transferable to others, eg by email, as a record of a calculation. This means that they should ideally be a single, self-contained web page without external scripts or objects. Any scripting (JavaScript code, CSS definitions, etc) you want to should be included in the template and the use of images should be avoided. If you are not able to do that, you could save your logs as a single Web Archive (.mht) file in order to send the to others, but remember that this is an IE format and users with other browsers may not be able to read them (eg Firefox) or view all the formatting or effects you have included (eg Opera).
Customising Printouts:
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
Hopefully this and the following section is mostly superseded by the introduction of the built-in [input] and [import] tools in version 1.02, but ...
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:
| Describe= |
The description text for the calculation entered by the user (if any), enclosed in double-quotes,
|
| Price= |
this value indicates whether the calculation is in Loan or Price mode, Price=1 for price mode, Price=0 for loan mode, the program defaults to Loan mode if this is not present
|
| Simple= |
this value indicates whether the calculation is in Simple or Complex mode, Simple=1 for simple mode, Simple=0 for complex mode, the program defaults to Complex mode if this is not present
|
| APRcalc= |
this value indicates whether the calculation is an APR or Rebate calculation, APRcalc=1 for APR mode, APRcalc=0 for Rebate mode, the program defaults to Rebate mode if this is not present
|
| Round= |
this value indicates whether the APR will be rounded or truncated to 1 decimal place, Round=1 for rounding, Round=0 for truncation, the program defaults to Truncate mode if this is not present
|
| Exact= |
The program generally rounds the financial amounts you enter to the nearest penny in its calculations. Setting this value to Exact=1 makes it use their exact amounts instead. Rounding will be switched on again next time DualCalc is started, if you load a calculation which doesn't include an 'Exact=1' value, or if you run the 'Use exact financial amounts' tool and choose 'Cancel'
|
| Loan= |
the amount of the Loan
|
| Initial= |
the amount of the Initial sum
|
| Final= |
the amount of the Final sum
|
| DIY= |
the number days in a year, 365, 365.25 or 365&366 - the last one must be in exactly that format, other non-statutory values can be used
|
| PPA= |
the periods in a year (PPA), 1 (for years and days), 12 (months), or 52 (weeks), other non-statutory values can be used
|
| RelDate= |
the 'relevant date' - generally this will either be zero or the date in DD/MM/YYYY format
|
| The following values apply only to rebate calculations ... |
| Method= |
the method of calculating a rebate to be used. This is recorded as a number, currently Method=1 is reserved for future use and the valid values are:
2 ... Actuarial Rule
3 ... Rule of 78
4 ... Pro-rata Rule
|
| Defer= |
the deferment to be applied to the rebate calculation. This can be stored either as a number (in periods) or as one of the four statutory deferments, in which case the number is preceded by 'Stat_'. The valid statutory deferments are:
Stat_0 ... no deferment
Stat_1 ... one calendar month
Stat_2 ... two calendar months
Stat_30 ... thirty days
|
| SetDate= |
the settlement date, stored either as a number (in periods) or a date in DD/MM/YYYY format
|
| Exclude= |
the sum of the charges to be excluded from the TCC in the rebate calculation - only relevant to Rule of 78 and Pro-rata calculations
|
| PER= |
the Period Effective Rate to be used in an Actuarial rebate calculation - this will be over-ridden by an APR value, if given as well
|
| APR= |
the Annual Percentage Rate to be used in an Actuarial rebate calculation
|
| The following values describe the repayments to be used in the calculation ... |
| Regular= |
the amount of the equal, regular repayments in a Simple calculation
|
| Number= |
the number of equal, regular repayments in a Simple calculation
|
| Levels= |
the number of Levels in a Complex calculation
|
| Level_N= |
the amount of the repayments in row 'N' of the Levels panel - eg Level_5=123.45 means the amount of the repayments in row 5 is £123.45
|
| Length_N= |
the length of the repayments in row 'N' of the levels panel
|
| Extras= |
the number of Extras in a Complex calculation
|
| Extra_N= |
the amount of the repayment in row 'N' of the Extras panel
|
| ExtraTime_N= |
the time (in periods) or the date (in DD/MM/YYYY format) of the repayment in row 'N' of the Extras panel
|
| Advances= |
the number of Advances in a Complex calculation
|
| Advance_N= |
the amount of the advance in row 'N' of the Advances panel
|
| AdvanceTime_N= |
the time (in periods) or the date (in DD/MM/YYYY format) of the advance in row 'N' of the Advances panel
|
| The following values are used to control carrying out and logging calculations automatically ... |
| Run= |
if the value following 'Run=' is '1' the program will carry out the calculation described in the saved file after loading it. This is really intended for use with add-in programs and Auto.txt (see here).
|
| Log= |
the value following 'Log=' should be a filename. If you provide a filename here (which should preferably be a full filename) the program will carry out the calculation described in the saved file after loading it and then log the result in the named file.
|
| Chain= |
the value following 'Chain=' should be a filename. If you provide a filename here (which should preferably be a full filename) the program will, after carrying out the calculation described in the saved file and logging the result, load the named file as a further saved 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.
Notes
- if the filenames you wish to use in 'Log=' or 'Chain=' contains spaces, you should put double-quotes around them
- currently each calculation loaded with 'Chain=' needs to be held in a separate file, you cannot put several calculations in the same file
- there is no need to specify 'Run=1' if you give a 'Log=' value, sensibly the program will carry out the calculation before trying to log it.
- using 'Chain=' with 'Run=' is pretty pointless, the calculation will be carried out (by 'Run=') and then immediately lost when a new calculation is loaded (with 'Chain='). You should use 'Log=' to save the results rather than 'Run='
- the warnings you would normally receive during a calculation (the sort of thing which would produce a 'Query from DualCalc: You are doing the calculation in a non-standard way, do you want to continue?' -type message) are switched off while calculations are carried out automatically, so that the program doesn't stop to wait for the user to confirm that they want to continue and completes all the named calculations, even if they are in a non-standard format (so in effect the program automatically clicks 'Yes' in response to any such queries),
- any errors which would prevent the calculation being carried out (the sort of thing which would produce, eg, an 'Alert: There is something wrong here!' -type message) will prevent the particular calculation being carried out and logged - so it will simply be missing from the sequence in the final log,
- any fatal errors (the sort of thing which would produce an 'Error from DualCalc: Very bad thing (99/100)' -type message) will end the automatic process,
- there is no easy way to stop a series of automatic calculations once started (you have to terminate DualCalc from the Windows list of running tasks),
- DualCalc will not reload the current saved calculation with 'Chain=' (to avoid an infinite loop) but you can still create one with two or more files which chain one another, so you should avoid doing this.
Examples:
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
Any process which can save a plain text file in the correct format can be used to build a calculation - as an (admittedly slightly contrived) illustration, I have provided an example which uses the browser you are reading this help file with. If you know, or can learn, a little JavaScript it should be possible to adapt this example to real calculations, the information you need is either given in the example or in more detail the first few chapters of most books on JavaScript - eg Michael Moncur's 'Teach Yourself JavaScript in 24 Hours', Published by SAMS or David Flanagan's 'JavaScript, The Definitive Guide', Published by O'Reilly.
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.
The small web page linked to below contains a JavaScript program which asks a series of questions in prompt dialogues and then writes the text of a corresponding saved calculation into the, initially blank, page. Unfortunately, apart from making 'cookies', JavaScript in a web page cannot write information to your disc drives (actually, given the potential for havoc from malicious web pages, that should read 'fortunately').
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).
Simple Calculation Generator
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.
Essentially the script is made up a series of simple commands to prompt the user for information, write information to the web page, and a simple loop to calculate and write the changing repayments. The script has been annotated and hopefully you may be able to adapt this to solve other problems without needing to fully understand JavaScript - although this isn't necessarily very easy.
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).
Adding Tools
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:
VDU 23,22,640;384;8,12,16,1,26
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:
DEF PROCend
IF Z%=TRUE THEN
SYS "ShowWindow",@hwnd%,0
CHAIN @dir$+"Resources\DualCalc.BBC"
ENDIF
QUIT
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
DualCalc Tools
Tool=Loan Scheduler v5.7
File=schedule.bbc -show [note 1]
Tool=Schedule Builder v2.1
File=builder.bbc -show
Tool=Multi-Calculator 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]
Notes:
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).
.Add Files:
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:
DualCalc Tools
Tool=Period Rate Converter
File=Period.bbc -save
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.
Removing Add-ins
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.
Dialogue.txt:
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:
| Badge |
|
Help |
| Rebate |
Inp7 |
| LnTx |
Inp1 |
Days in year |
Inp4 |
Deferment |
Inp8 |
[Loan] |
| InTx |
Inp2 |
Periods |
Inp5 |
Settlement |
Inp9 |
[Complex] |
| Final sum £ |
Inp3 |
RdTx |
Inp6 |
Exclude sum |
InpA |
[APR] |
| LvTx |
LnTx |
Extra £ |
Time/date |
Advance £ |
Time/date |
Series |
| Lidx | LvA1 |
LvN1 |
Eidx | ExA1 |
ExT1 |
Aidx | AdA1 |
AdT1 |
Tidy |
| LvA2 |
LvN2 |
ExA2 |
ExT2 |
AdA2 |
AdT2 |
Save |
| LvA3 |
LvN3 |
ExA3 |
ExT3 |
AdA3 |
AdT3 |
Load |
| LvA4 |
LvN4 |
ExA4 |
ExT4 |
AdA4 |
AdT4 |
Reset |
| LvA5 |
LvN5 |
ExA5 |
ExT5 |
AdA5 |
AdT5 |
Tools |
| LvA6 |
LvN6 |
ExA6 |
ExT6 |
AdA6 |
AdT6 |
View Log |
| LvA7 |
LvN7 |
ExA7 |
ExT7 |
AdA7 |
AdT7 |
[Round] |
| LvA8 |
LvN8 |
ExA8 |
ExT8 |
AdA8 |
AdT8 |
Options |
| LvA9 |
LvN9 |
ExA9 |
ExT9 |
AdA9 |
AdT9 |
Log |
| LvAA |
LvNA |
ExAA |
ExTA |
AdAA |
AdTA |
Print |
| << | < |
> | >> |
<< | < |
> | >> |
<< | < |
> | >> |
Calculate |
| OTx1 |
Rebate results |
| Total amount advanced £ |
Out1 |
Total remaining to be paid £ |
Out8 |
| Total amount payable £ |
Out2 |
Statutory rebate of charges £ |
Out9 |
| Total charge for credit £ |
Out3 |
Final settlement amount £ |
OutA |
| OTx2 |
Out4 |
Total paid before settlement £ |
OutB |
| OTx3 |
Out5 |
Total paid including settlement £ |
OutC |
| OTx4 |
Out6 |
Settlement plus last payment £ |
OutD |
| OTx5 |
Out7 |
Calculator |
Calendar |
Intervals |
Rates |
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.
Reporting Problems
If you encounter any problems or errors while using the program you can report them by emailing here:
credit-programs@oft.gsi.gov.uk
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:
Please don't report something which is already explained in these pages - this is really just a plea for you to read the help files carefully before reporting something so it doesn't waste our time. Please feel free to report both 'technical' errors or problems - eg 'the program wouldn't do x in situation y', and interpretational errors - eg where the program works but you think the result doesn't comply with the Regulations. Please also feel free to report any difficulties with the 'look and feel' of the program - eg 'it's a real pain to have to do x every time I need y' or 'I couldn't find any way to deal with situation z.' The program (and these pages) may be updated. Please check the version number (and time/date) at the top of the help page. If you don't have the latest version download and try it, you might be reporting something we've already fixed. Please try to make sure that you can replicate the error and let us have as much detail as possible about what you were doing when it occurred. It would also help if you could save a calculation which demonstrates the problem and attach it to your mail, a log demonstrating a problem with a result would be equally helpful and, if the error is technical in nature, the 'dialogue.txt' file from the program's 'Resources' folder might help too - please send all three if possible.
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.
Brian Stewart
Office of Fair Trading
|
