TECHNICAL INFORMATION (c) Brian Stewart, 1983-2000 Release: March 2002 [PLEASE NOTE: Some of the characters in this file will probably not appear in your browser as the would on a DOS PC. I have tried to convert them or indicate the relevant ASCII codes where appropriate, but there will probably be some inconsistencies.] 0. INTRODUCTION 0.1. This file gives more technical information on some aspects of using and configuring the programs in the Credit Programs Link package and some of the problems you might encounter. You may find it is not necessary to read any of this, it is provided as a resource if you hit problems. 1. The Development Enviroment(s) 1.1. The PC versions of the programs are written using Richard Russell's PC BBC BASIC(86) Plus v4.82, some incorporate short sections in 8086 assembley code. They have been developed on an Acorn Archimedes or Risc PC under RISCOS 2.00, 3.10 and 3.7, running Acorn's PC Emulator v1.21 and 1.81 and MS-DOS 3.21, 3.30 and DR DOS Release 6.0 with 4DOS versions 4.02 to 5.50 and latterly under Windows98 on a Pentim card in the Risc PC. A lot of the development work was originally carried out on an Acorn 'Model B' BBC Micro and the PC versions created on an Acorn Master 512 running Digital Research DOS Plus 2.1. Although none of these machines are PCs or true compatibles, you should experience no problems - provided you are using PC BBC BASIC(86). Please note that the programs will not, in their present form, run (or at least not correctly) under other versions of BBC BASIC. 1.2. All the BASIC programs on this disc are provided in files with a .BBC extension in a compacted (CRUNCHed) form, which reduces their size and increases their speed. They are run using an executable "runtime module" RUN.EXE which was created using a licensed copy of BBCRUN, runtime BBC BASIC(86) Plus, as is permitted under the terms of its licence, so that working copies of this software can be distributed without the need for you to buy a copy of the interpreter. Running Programs from the DOS Prompt: 1.3. To start a .BBC program outside of this menu system enter `RUN ' at the DOS prompt. Brief documentation on RUN.EXE for BBC BASIC(86) programmers can be obtained by entering `RUN /H' ("h" for "help") at the DOS prompt. If you would like to write your own full scale BBC BASIC(86) programs to interface with those in the package, you will need to obtain a copy of the PC BBC BASIC(86) interpreter. Even with the interpreter, you will not be able to edit the crunched programs. I would not want programs which have been altered without my knowledge (but carrying my name) in circulation. Please also see the terms and conditions towards the end of the CREDIT.DOC file. Richard Russell's website is: http://www.rtrussell.co.uk/ 2. THE !LINK PROGRAM 2.1 From the December 1996 release, the Link is created by the program !Link which is a modified version of the general menu program !Menu. The details of the menu are held in the ASCII file LINK.INI and in general you should not alter this unless you are familiar with the operation of !Menu (details available on request - ask for a copy of the file !MENU.DOC). 2.2. !Link replaces the earlier program Credit. Some users may still have ad hoc programs from earlier releases of the package which expect to run Credit rather than !Link when they close down. To allow continued use of these, the package includes a patch in the form of a small program called CREDIT.BBC which CHAINs !LINK.BBC when it is run. If needed, this should be placed in the user's default directory (see section 8.2). 3. THE MAXIMUM.INI FILE - Data Space 3.1. From the November 1996 release the programs look for a file called MAXIMUM.INI in either your default or network directory (see section 8.2 below for details of these directories). If they find this file they read it and allocate space for data types accordingly. The programs check first in your default directory and then in the network directory, so you can provide all network users with a default MAXIMUM.INI setup which would be overridden by an individual setup in their default directory. 3.2. You could, for example, use this facility if faced with unusual cases where a loan has 3,000 extra payments. It might be advisable to, at the same time, reduce the space allocated to the other types of data, so you don't run out of room. 3.3. From the February 1998 release, the MAXIMUM.INI file should consist of ten lines of plain ASCII text, the first six giving decimal numbers indicating the space required (see the next section for details of the remaining four lines). If you are uncertain how to create a file like this, see paragraph 8.3.5 for an example. The default values (which will be allocated anyway if the file isn't found) would be defined as follows and relate to the allocations mentioned on the right: file line ... maximum number of .. 25 advances 25 advance levels 100 repayment levels 100 repayment series 1000 series repayment amounts 500 extra repayments 3.4. All the relevant programs will read these values and pick out the ones that are appropriate to them. So for example, only Trurate Two currently uses the second line, but it must be present for all the programs so that they all know that the maximum number of levels is specified by the third line. 3.5. Incidentally, with all the definition or (.INI) files in the package, only the numeric information at the start of the line is read by the programs when they look for a number, and non-numeric and subsequent characters are ignored. You can if you wish use this to include notes in the .INI files - eg, the text `advances', `advance levels' etc in the above example could be included in the MAXIMUM.INI file. However this will NOT work where the programs are looking for text. 4. THE MAXIMUM.INI FILE - Date Entry 4.1. The arrival of Year 2000 raises other issues for the programs than simple compliance: the use of auto-century input (where the program provides the first two figures of the current year for you) might not work correctly on systems where the hardware or operating system has problems with Year 2000 because they get these two digits from the computer's system clock. Also, these dates might not always be convenient in the 21st century, particularly in the case of rebate programs where most of the dates for the cases the user is examining are probably still in the 20th century. 4.2. For this reason some additional configuration options have been added to the programs with the February 1998 release. These also allow you to alter the minimum and maximum years the programs will accept from the user. The default values for these are 1600 and 2500 and the programs will also impose overriding limits of 1600 and 5 million. 4.3. For convenience, these configuration options are set by a further four lines in the MAXIMUM.INI file in the following order: file line ... option ... 1900 Minimum year 2200 Maximum year 20 General century 19 Rebate century 4.4. In this example the programs will only accept years in the range 1900 to 2200 and the last two options provide the two digits which will appear automatically when a year is entered, in this example `20' for most programs but `19' for rebate calculators, for the reason mentioned above - both can however be set to the same value if you wish. 4.5. As an alternative to giving digits for the last two options, you can specify either `##' which gives auto input taken from the clock (the default setting) or `??' which given no auto input (the user has to type all four digits). 4.6. General information on entering dates is given in CREDIT.DOC 5. PROBLEMS WITH THE PROGRAMS Running the programs: 5.1. If you have any problems getting the programs up and running you may have received a corrupted or incomplete copy, so please contact the address given under `Copyright' in CREDIT.DOC. I do not however have the resources to provide support in using the programs - this is what the instruction files are for, so please read them carefully. Monochrome displays and different screen modes: 5.2. The programs have been written assuming that the standard colour 80x25 character text mode is available. If you have a machine with a monochrome display you may find you can't use the programs at first. If the monitor (the screen) is monochrome you may be okay, but if the display adaptor (the circuitry inside the computer) is monochrome it probably won't support the mode the programs try to select and you will get an error message to that effect. 5.3. You can try to solve this by modifying the LINK.INI file with a text editor. The first line usually looks like this ... &10003000 ... and the last (eighth) digit on the first line can be changed from `0' to `1' to enable monochrome operation. This tells the Link not to issue the command which selects the colour text screen mode and tells all the programs to use only black and white, but they will still issue some highlight and inverse commands. Depending on how your video adaptor interprets them, this may still cause problems - eg displaying foreground and background in the same intensity or not highlighting part of the text. However, this has been tested successfully on a VGA system emulating an MDA mode and in an 80-column monochrome CGA mode. With some PCs (old Amstrads were an example), you might also find that some characters (particularly the pound sign and the box characters) don't appear as they should in some screen modes when you use a `1' here. You can try to solve this by using a `2' as the last character on the first line instead. This tells the Link to redefine the necessary characters before starting the menu in monochrome (`1') mode. 5.4. One user has reported a problem with the Link generating a `Bad mode' error on a machine which apparently did support the standard colour text mode. This may be a one-off problem caused by a particular PC or its setup but it prompted me to modify !Link slightly so that the programs could be instructed to avoid changing the screen mode but still issue colour commands. This can be done by starting the package with `3' as the last character in the first line of LINK.INI (in fact any value other than 0, 1 or 2 will have the same effect), this will enable you to select your preferred mode before starting the package and still get the full colour range. The text cursor: 5.5. Old versions of !Link (and its predecessor `Credit') used an incorrect method of switching off the text cursor. This could fail to work or even create a large, full character-height cursor on some machines. This has now been resolved and the sixth and seventh digits on the first line of LINK.INI are now used to allow user defined cursors, by specifying the start and end scan-lines as two `hexadecimal' digits (see below). If these are set to `00' default values of `67' are used. NB: One of my computers has some compatability problems with this which I solve by adding a CURSOR.INI file to my set of programs. DON'T add one to yours. Processor speed: 5.6. This is not generally an important consideration, even the very slow PC-Emulator software used to develop the programs is able to carry out most calculations without too much of a wait. In fact, in one or two instances, pauses have been introduced to give the user time to see displayed information on faster machines. As these are measured using the computer's internal real-time clock, they should be speed independant. 5.7 - 5.10. !Link's screen saver animations may however run too slowly on older PCs. There is a rather complicated way of solving this, I have removed the lengthy explanation from these notes because they are unlikely to be useful to most readers, but contact me if you want to know how. The printer: 5.11. The programs assume by default that your printer can be accessed via the standard printer output device PRN (which is usually the same thing as LPT1, `line printer 1'). If your printer is linked to another printer port or a serial port such as COM1, your PC may already be set up to cope with this so everything will be okay. If not, its probably best to set this up for general use rather than just these programs, so please see your user guide for details of DOS's MODE command. 5.12. Some users have reported problems with getting the programs to print to a network printer, this is probably because this is a second printer attached to another port such as LPT2, or at least appears to be as far as your PC is concerned. A simple work-around for occasional use is to log any program output instead and then use something like a wordprocessor to print the log file by first loading it as a plain ASCII text file. !Link may also be able to help because, from version 4.5, the Lister facility (usually on F2) will allow you to redirect the printing of a text file to another port. For example, you can log the results of a calculation and then view the log file with the Lister facility, then choose F4 (Redirect) and F2 (LPT2). 5.13. For a more permanent solution, see section 6 below on using FORMATS.INI to re-direct the printer. 5.14. The printouts use some `top bit set' characters, mainly the `' (ASCII code 156) and the bar character (`-' ASCII code 196) to rule across the page. If you find you are getting `#' where `pound' should be, or rows of `pound' or some other character at the bottom of your printouts, this probably means your printer is not set up correctly. To correct this you will need to read your printer manual and probably change some DIP-switch settings (little switches usually hidden on the back or underneath of the printer somewhere). Alternatively you might need to change your printer code page - see your manual and the related section on screen code pages below. Another soultion is to provide printer substitution characters as described in section 6 below. Memory: 5.14. As the programs use relatively little memory (generally not much more than 64K) they rely on the BBC BASIC interpreter checking to see if there is enough available and exiting if there isn't. Sometimes however, more memory is needed. For example, at work we used to use WordPerfect v5.1 most of the time and had a macro to call up the Link from there. This worked fine for carrying out calculations but, because WordPerfect used most of DOS's main 640K of memory, there wasn't enough left to run most of the Distribution Menu's options which required another copy of COMMAND.COM to be loaded. This could have been solved by re-configuring the wordprocessor so that is uses less main memory, but we simply ran the package from outside of the wordprocessor if we wanted to make copies. 5.15. From the revised version of the February 2000 release of the programs the `large memory model' of PC BBC BASIC(86) is use which allows for more than 500k of memory, which should allow for a large number of data items, if required. 6. THE FORMATS.INI FILE 6.1. From the December 1998 release the programs look for a file called FORMATS.INI in either your default or network directory (see section 8.2 for details of these directories). If they find this file, they read it and make some modifications to the programs' output, both to the screen and printer. The programs check first in your default directory and then in the network directory, so you can provide all network users with a default FORMATS.INI setup which could be overridden by an individual setup in their default directory. _________________________________________________________________ NOTE: From the third version (v.3) of the February 2000 release of the programs the format of this file was changed, although using the old format with newer programs may still work. The previous format included only the first four characters mentioned in 6.2-3 below with the re-directed printer name following immediately after them on the same line, eg: T0.LPT2 _________________________________________________________________ 6.2. The structure of the file is very simple, it is another plain ASCII file containing a few lines of text. Again, if you are uncertain how to create a file like this, see paragraph 8.3.5 for an example. The contents of the file which would produce the same effect as the default settings (ie the same as where there is no FORMATS.INI file present) would be as follows (NB: the "." is one of the four characters): T0.F (That's capital-T, pound-sign, zero, full-stop, capital-F.) 6.3. The meaning of these five characters is as follows: T This means display APRs truncated to one decimal place, alternative values for this character are "1" or "2" which tells the programs to display APRs rounded to one or two decimal places. Other values are ignored and the programs stay in the default format. This setting also determines how the package (APR and rebate programs) will deal with leap-years. The truncation setting will tell the programs to assume there are 365 days in a year in all cases (so a leap-year is actually 366/365ths of a year) in accordance with the pre-14 April 2000 Total Charge Regulations. Either rounding setting tells the programs to assume that a day is 1/365th of a normal year and 1/366th of a leap-year when the time periods are set to `Years', or 1/365.25th of a year when the user sets the time period to `Others' and enters a value of '1'. This change was introduced with the February 2000 release of the programs, earlier releases used 365 days in all cases and (contrary to earlier reports) would not deal adequately with dates under the new Regulations. This is the currency symbol to be used. You can replace it with any other character in the extended ASCII set such as "$" or "E". The ASCII set contains a passable representation of a Euro symbol "" as character 238 (it's not on the keyboard so hold down an Alt key, type 238 on the numeric keypad - not the main keyboard - and then release the Alt key to get it). This will be used anywhere a "" appears with the default setting. 0 This is the `currency separator' symbol, for example the "," when you write one thousand pounds as 1,000. You can use any character here as well, apart from `0' which tells the programs not to include a separator. To use other numbers would of course be silly, for example if you used "5", 1,000,000 would appear as "150005000.00". Most European states use the "," and "." the other way around from in the UK and scientific journals often use a space as a separator. Some accounting systems also use an apostrophe ("'"). . This is the `decimal place' symbol. Again, most European states use "," rather than ".". You might also like to note that character 249 ("") is a `proper' decimal point, placed above the line rather than on it. F This tells the programs that your printer needs a `form-feed' character sent to it to after each print job. Any other character (including `f') tells the programs not to send a form feed. Some laser printers only print whole pages at a time and need a form feed before they will print the text you have sent them. Others (such as inkjets and dot-matrix printers), print the text as it arrives and, with this option set, will always move to the start of the next page after a print job is finished. 6.4. There are some other things to note about separators: - the programs do not use separators in columns of figures: first, because the additional characters make it more difficult to fit the columns across the screen; second, because other programs (not part of the standard package) read the columns of figures in log files and would have to strip the separators out again to make sense of them, - generally only currency values and interest/charge rates will be formatted with separators, - there are no separators in the decimal places, if more than three are displayed - ie a typical output might be "1,234.5678", - numbers of 10,000,000 or more will not have separators, because generally only 12 character spaces are provided for printing a currency value and the separators would muck up the formatting of the output. In fact, if a program tries to format a number this large it switches off the separators completely, not just for that number. This is to stop the format being messed up by some numbers being separated and some not - but it might only encounter the big number part way through its output, so the earlier numbers will have separators. If this happens, to get a consistent format you should run the calculation again now the separators have been disabled. They will not be switched back on until you re-run the program and it reads FORMATS.INI again. 6.6. PLEASE NOTE: When making a new copy program set the !Distrib program looks for any FORMATS.INI file being used by the set of programs doing the copying - either in the `network' or `default' directory - and constructs a new FORMATS.INI file in the copy set. This is a default file, apart from the APR `trunctation or rounding' and `days in a year' setting, which it copies from the current set. This is so that, when a package is amended to cope with a change in the rules, all copies made by it will automatically have the same setting. If there is no FORMATS.INI file being used none will be included in the new set, and the copy APR programs will default to truncation and 365 days in a year. In this state, they conform to the current position at the time of writing. The onus untimately rests with the end user to ensure that they have the right setting for the current legislation. Re-directing the Printer with FORMATS.INI: 6.7. If you want to permanently re-direct the programs' printer output to something other than the PRN port (see 5.12 above) you can do this by adding the new destination as a second line after the five format characters in FORMATS.INI. So, for example, if you wanted to use the default format setup but wanted all your printer output to go to LPT2, you would use the following FORMATS.INI file: T0.F LPT2 6.8. You can usually just use device names such as PRN, LPT1, LPT2, LPT3, COM1, COM2, COM3 or COM4 here. You could however use NUL or a filename as a printer `sink' if there is no printer attached and you don't what the computer hung up if the user tries to print something. Note that, if you give a filename, it will only contain the last thing printed. 6.9. To minimise the changes I had to make to implement printer re-direction, the programs spool the output into a temporary file (called PRINTOUT.TMP, in the data directory - see section 8) and then copy this file to the specified port when the print job is complete, before deleting it. Substitution characters: 6.10. With the third version (v.3) of the February 2000 release of the programs an additonal facility was added to FORMATS.INI to make it simpler to deal with printers which print the wrong characters by specifying, in two further lines, the problem characters and the corresponding characters your printer should print instead. 6.11. Let's say for the sake of illustration that your printer prints $ instead of a pound-sign and a string of @'s instead of horizontal lines (the pound-sign and horizontal line are the characters most likely so go wrong, but it's very unlikely you'd get these characters instead). Here's how you'd fix it: Step 1: Make sure you have no FORMATS.INI file or a default version as described in 6.2 above. If not, delete it, edit it as necessary or copy that line from this file. Step 2: Make sure your printer is ready and run the utility program PRINTEST.BBC which is included with the package. You should do this from the `default' directory by entering `RUN PRINTEST' at the DOS prompt. If RUN.EXE and the `network' directory are located elsewhere, you will need to specify their locations in the DOS command - for example if RUN.EXE is in C:\UTILS and the network directory is F:\CREDIT you would have to type ... `C:\UTILS\RUN F:\CREDIT\PRINTEST' (See section 8.2 for details of default and network directories.) This program displays and prints a set of printable characters which should look like this: 0 1 2 3 4 5 6 7 8 9 30 ... ... ! " # $ % & ' 40 ( ) * + , - . / 0 1 50 2 3 4 5 6 7 8 9 : ; 60 < = > ? @ A B C D E 70 F G H I J K L M N O 80 P Q R S T U V W X Y 90 Z [ \ ] ^ _ ` a b c 100 d e f g h i j k l m 110 n o p q r s t u v w 120 x y z { | } ~ ... 130 140 150 160 170 180 190 200 210 220 230 240 250 ... ... ... ... Whether this looks the same on your computer screen and mine is uncertain, but the pound-sign should be character 156 and the horizontal line should be character 196. The version on your PRINTER, would of course have $ and @ in those positions instead. Step 3: Find the pound-sign and horizontal line characters, or acceptable equivalents, on the PRINTED version of the table. Let's say for illustration that the pound sign is at 36 (ie the pound and dollar signs are swapped on your printer - which happens sometimes) and you can't find a horizontal line so you opt to use a minus sign (which should be at 45) instead. Step 4: Add two lines to FORMATS.INI. The first contains the problem characters (you may need to type their codes into your editor by hokding down the Alt key and typing 1, 5, 6 and 1, 9, 6 on the numeric keypad) and the second contains the substitute characters your printer should print in their place. Note: in order for substitution to work you must specify a re-directed printer. If you are just using the normal printer port, specify PRN or LPT1. So, assuming you have an otherwise standard setup (and are now using truncation rather than rounding for the APR) your FORMATS.INI file might contain: 10.F PRN $- After setting this up (but using `real' substitutions, of course), you can check the effect by running PRINTEST again. Note: one `feature' of the new print system (feature - programmer-speak for `bug I couldn't be bothered to fix') when using a re-directed printer is that the first time you key F in a selector which offers an [FF] option, it will print the last job again. The second and other times you'll get the expected blank page. 7. MOUSE OPERATION 7.1. With effect from the November 1996 release of the package, the programs included code to respond to some basic mouse operations. Don't expect the mouse to be very useful though; you may be able to choose menu and selector items or cancel the Link's screen saver with it, but you'll soon have to go back to the keyboard to enter amounts, times etc. Some improvements were made in the December 1996 release. 7.2. Mouse Keyboard Emulation 7.2.1. To minimise the changes I would have to make to the programs to get them to respond to the mouse, I opted to have it emulate key presses. So for example, moving the mouse up is treated the same as pressing the up cursor key and the same goes for the other three directions. Pressing the left mouse button is treated as the RETURN/ENTER key, the right mouse button is treated as the SPACE bar and pressing both buttons together is treated as keying F7, which the programs' menus interpret as `Quit' or `Exit'. 7.2.2. If you have one, the programs ignore the third (centre) mouse button, because it does something entirely different on my computer to a proper PC (it switches the PC Emulator software from full-screen, single-tasking back into a multi-tasking RISC OS window), so I couldn't test its operation. Also, the DOS reference material I have doesn't mention a third button at all, so I could only guess at how to read it. 7.3. Setting Up the Mouse 7.3.1. When you first install the package it won't respond to the mouse at all. To make it go, you have to do two things: 1. Make sure you have a DOS mouse driver installed: see your PC or mouse manual for details of how to do this, it usually involves adding something to your CONFIG.SYS or AUTOEXEC.BAT file. 2. Make a file called MOUSE.INI in either your default or network directory (see section 8.2 for details of these directories). The programs check first in your default directory and then in the network directory, so you can provide all network users with a default MOUSE.INI setup which would be overridden by an individual setup in their default directory. 7.3.2. The MOUSE.INI file should consist of four lines of plain ASCII text giving four decimal numbers All four lines MUST be present. If you are uncertain how to create a file like this, see paragraph 8.3.5 for an example. The values I use are ... 64 64 32 8 ... the first two of these define the x- and y-sensitivity of the mouse movement detection. The DOS mouse driver function used to detect mouse movement (interrupt 33 hex, service 0B hex) returns values in the range 32,767 representing the number of screen positions moved by the mouse pointer since the last call to this interrupt, apparently these units represent about half a millimetre each, so the mouse can be very sensitive. The values returned by this interrupt are divided by the first two values in the file to reduce sensitivity, so bigger numbers in the file will give less sensitivity. Numbers bigger than 32767 will stop the programs detecting mouse movement at all, so you could use this to limit the mouse operations to button presses. 7.3.3. The third and fourth numbers in the file reflect the fact that the mouse is being used to emulate keystrokes and define the auto repeat delay and rate. If you hold down a key on your keyboard, you will notice that there is a pause before the character starts repeating then, usually, the character repeats more quickly than the pause between the first and second characters. These numbers determine the timing of a similar effect for the mouse. The third number determines the pause before the character repeats and the fourth number the delay between repeats, both in hundredths of a second. Playing with these values may also help you to make the mouse more useable, large values (ie 100 or more) are not recommended however, as they will slow everything down. 7.3.4. Remember not to confuse the package's MOUSE.INI file with other files of the same name belonging to other software (such as your mouse driver). The file you create should only be placed in one of the two locations mentioned. 7.4. Mouse Disabling 7.4.1. To detect mouse input, it was necessary to constantly scan the keyboard and mouse inputs and this meant changing most of the parts of the programs which read the keyboard from a function which waits until a key is pressed before returning the appropriate value to one which checks the keyboard `on the fly' before returning the value of any key being pressed at the time. 7.4.2. Unfortunately, this function doesn't accept input from a file, so it is necessary to switch back to the other function when a program is using file input (ie when one program is being run by another or loading an automatic or saved calculation). This in turn disables the mouse. 7.4.3. The relevant programs now warn you in their initialisation sequence if the mouse has had to be disabled (and also mention if auto-century entry has been disabled - see paragraph 2.8.3. of CREDIT.DOC) and the Link program has been modified to switch everything back on when it starts a program. In addition to the advice in paragraph 4.6.2.(v) of CREDIT.DOC therefore, it would be best if any automatic files you create go all the way back to the Link menu when they are finally finished. 7.5. The Mouse in Windows 7.5.1. You might like to note that, on the Windows 3.11 for Workgroups systems we used at work, it was not sufficient to run the programs through Windows for them to recognise that a mouse was being used we still had to install a DOS mouse driver in our CONFIG.SYS or AUTOEXEC.BAT sequence before running Windows. This doesn't seem to be a problem with Windows 95/98. 7.5.2. You will also discover that, if you run the programs in a Windows window, they will only respond to the mouse while its pointer is over the window. Also the movement of the pointer and the menu or selector highlights won't correspond exactly in either position or scale. You might be able to remedy some of this by playing around with the values in the MOUSE.INI file. 8. NETWORK OPERATION 8.1. Introduction 8.1.1. In the network we have at work users have access to a common drive which is used, among other things, to hold the programs and files forming the package. 8.1.2. From the July 1996 release, the programs were modified to enable them to operate with their files distributed across different locations in the drive and directory structure, so that the could make more effective use of a network environment. 8.1.3. It will also be possible to use these facilities to keep files in different directories on a stand-alone PCs. 8.2. Network Locations 8.2.1. It's assumed that four main drive/directory locations will be used by the programs, and for reference I'm going to call them the `default', `network', `user' and `data' directories. The `default directory': 8.2.2. The first location is the currently selected drive and directory from which the Link is run - for these notes I will assume that it is C:\CREDIT, which has always been the default location for installation of the package. The `network directory': 8.2.3. The second location is the one (we'll assume) on the network where the package's files (ie the .BBC program files, the .DOC documentation files, and so on) are kept. The main reason for keeping these on the network is that any changes or updates need only be made once rather than copied onto every PC using the programs. For these notes, I'll assume these are in F:\APPS\CREDIT. The `user directory': 8.2.4. The third is the location used for text files created by individual users in the course of using the programs (ie .LOG files). These could also be on a common or network drive (say F:\DATA\CREDIT\FRED for user Fred's files) so that users could have access one another's results, for these notes however I'll assume they're on the individual user's PC in location C:\DATA\CREDIT. ________________________________________________________________ Note: using the same location on the network for everyone's files will cause problems. For example, two or more users might try to make a SCHEDULE.LOG file at the same time, or one user might be reading a file while another is trying to write to it. This would produce an `Access denied' error, which the programs don't take any special steps to trap. Give each user their own subdirectory if user files are going to be kept on a common network drive. _________________________________________________________________ The `data directory': 8.2.5. This is where the programs store the data files they create for transfer of information between programs or user sessions (ie .SV? and .EXC files and the MEMORY.DAT file), for demonstration purposes I'll assume this is also C:\DATA\CREDIT. Again, this could be on a network drive so users can access one-another's results. 8.3. Defining Locations 8.3.1. The default directory is assumed, ie it's the currently selected drive and directory at the time the package is started. 8.3.2. The package has to be told the other three locations by including their full paths in a file called NETWORK.INI in the default directory. This file should be a plain ASCII text file the first three lines of which give the locations of, in order, the network, user and data directories. So in our example setup, the NETWORK.INI file should contain the following text: F:\APPS\CREDIT\ C:\DATA\CREDIT\ C:\DATA\CREDIT\ 8.3.3. All the programs work out where their files are by opening NETWORK.INI and reading its contents. They assume that the paths given will end in a `\' so that they can simply tack the name of the file they are looking for on to the end of what they find in here. 8.3.4. The programs also assume that each line is terminated by a carriage-return and line-feed. 8.3.5. If you don't already know how to construct a file like this with your text editor or wordprocessor, I'll describe a fairly simple method using just the DOS command line prompt (eg C:\>). To specify our example locations you would do the following: i) change to the default directory by entering `C:' and then `CD \CREDIT' at the DOS prompt, ii) enter `COPY CON NETWORK.INI' at the prompt, the cursor will move to the next line, perhaps after a brief message from DOS, and there will be no prompt, (the command means copy the output of the console `CON' - ie the keyboard - to the file NETWORK.INI), iii) type `F:\APPS\CREDIT\' and key RETURN/ENTER, then TWICE type C:\DATA\CREDIT\' and key RETURN/ENTER (once for the user directory and a second time for the data directory). iv) finally type Ctrl-Z (which will appear on screen as ^Z) and key RETURN/ENTER. DOS will respond with something like `1 File(s) Copied' and return you to the prompt. 8.4. What Files to Put Where Default directory: 8.4.1. The default directory the package's programs are started from (ie C:\CREDIT in our example) should generally contain at least these files: CREDIT.BAT !LINK.BBC LINK.INI NETWORK.INI RUN.EXE 8.4.2. The reason for having !LINK.BBC (the !Link program) and LINK.INI (its definition file) here rather than with the other programs which make up the package is that different users can have different menus, depending upon which programs they need to access, and all the programs return to the Link's menu by assuming that !LINK.BBC is present in the default directory when they want to run it. 8.4.3. You don't have to put RUN.EXE or CREDIT.BAT here, you could put them in a directory on your PATH, such as say, C:\DOS or C:\UTILS (these are just commonly used names, I don't know if they are right for your PCs). If you put CREDIT.BAT somewhere else on the PATH, make sure it switches to the default directory before trying to run the Link (see INSTALL.DOC for details). Network directory: 8.4.4 You should keep a complete and unaltered copy of all the package's files as installed from the distribution disc in the network directory (ie in F:\APPS\CREDIT in our example). This is important if you want to distribute copies to other users using the !Distrib program as it will only look in the network directory (or the default directory if you don't specify a network directory in NETWORK.INI) for files to copy to a floppy disc (you may not have !DISTRIB.BBC). User and Data directories: 8.4.5. You won't have to put anything in the user and data directories. These are where the user (and/or some of the programs) can look for files created by the programs, for example, results logged by a rebate calculator. 8.4.6. Note: the programs which provide options to list `their' files also use these directories, so you won't get the program (.BBC) and .DOC files listed as well if you have specified a user and/or data directory, this doesn't mean they've gone missing. Additional files: 8.4.6. Two previously `user specific' files, LINK.DOC (which gives additional information when the user chooses `Read Information' from the Link's menu) and SCHEDULE.INI (which automatically answers some of the Yes/No questions at the start of creating a schedule), are now searched for first in the default directory and then in the network directory. This enables you to provide files which are available to all users on the network but which can be overridden by versions on individual user's PCs. 8.5. OTHERS Programs and SELECT 8.5.1. The Select facility in Link lists the .BBC files in both an OTHERS subdirectory to the default directory and an OTHERS subdirectory to the network directory (ie first C:\CREDIT\OTHERS and then F:\APPS\CREDIT\OTHERS in our example). When the user enters a filename the OTHERS subdirectory to the default directory is checked first, so if there are programs with the same name in both OTHERS directories, the one on the user's machine is given preference over the one on the network. 8.5.2. Previously, the Select facility (in the form of a separate program SELECT.BBC) would change the currently selected directory to the OTHERS directory and leave it to the called program to change back. Now Select leaves the directory setting alone. The advantage of this is that a program which doesn't access any other files can just exit by CHAINing !LINK.BBC when done without worrying about finding the credit directory again. The disadvantage is that if it has any associated files (eg a .DOC file) it will now have to work out where they are. 8.5.3. If you write your own OTHERS programs intended for network use, they can read the network directory from the first line of NETWORK.INI and assume they are in the OTHERS subdirectory to the location they find there. Alternatively if they are intended for an individual user's PC they can just assume they are in an OTHERS subdirectory to the currently selected (default) one. The most complete approach would be for a program to look for its associated files in both these locations to find out where it is and act accordingly. Remember also that any files they write should go in either the user or data directory (both C:\DATA\CREDIT in our example). NB: For the record, any program CHAINing !LINK.BBC should make sure the BBC BASIC(86) integer variaible @% is set to &90A (the default value), otherwise !Link will try to run a different menu to LINK.INI. 8.5.4. If you have it, see SELECT.DOC for further details of using Select and OTHERS programs. 8.6. Non-network Use 8.6.1. If you put all the files in one directory and don't provide a NETWORK.INI file the programs should work exactly as before the July 1996 release - apart from any subsequent changes, of course. 8.6.2. You could however use a NETWORK.INI file on a stand-alone PC, for example to specify that the user directory should be somewhere other than where the rest of the files are, perhaps one of the directories used by your wordprocessor so that you can add calculation printouts (ie .LOG files) to correspondence easily. This also has the advantage that you won't have to hunt through all the similar .BBC, .DOC, .SV? etc filenames to find the .LOG file you want. 8.6.3. You could also specify a `network' directory on a stand-alone PC so that you can keep the more important files that shouldn't be altered or deleted somewhere safe - for example in a subidrectory to your default directory. 8.6.4. NETWORK.INI must have the first three lines of text present. To specify only one or two locations, say just a user directory, the other lines must be blank but end in a carriage-return and line-feed. For example, if you were going to keep all your program etc files in the usual default directory (C:\CREDIT) but wanted a user directory to hold results (say in D:\WPDATA\CALCS), you would follow the steps in 8.3.5 above but, at step (iii), you would key just RETURN/ENTER first (to enter a blank line), then type D:\WPDATA\CALCS\ and key RETURN/ENTER twice (once to end the user directory line and again to make the third (data directory) line blank as well). 8.6.5. Similarly if you are using a network directory (say F:\CREDIT) but don't mind your logs and data all going into the default directory, in step (iii) you would type F:\CREDIT\ and key RETURN/ENTER, and then key RETURN/ENTER twice again (to enter two further blank lines). 8.6.6. Note: Blank lines do not require a `\' at the end. You would only specify this as a location if the relevant files are to be placed in the root (top) directory of the current drive. 9. ACORN BBC MASTER 512 OPERATION 9.1. Introduction 9.1.1. This section gives some hints on using the programs on an Acorn Master 512. If that means nothing to you, you can skip it, it's mainly here for nostalgic reasons but you might find some of it useful or interesting. 9.1.2. The BBC Micro series of computers were all based on the 6502 microprocessor but most models had an interface called the `Tube' which could be used to connect `second processors' - essential a second computer (often also a 6502) which used the BBC Micro's keyboard, screen, disc drives and ports. Second processors were usually faster, had access to more memory and, to some extent processed in parallel with the BBC Micro's main processor. The last model of BBC Micro, The BBC Master, had an additional internal Tube interface. 9.1.3. The Acorn Master 512 was, as far as I can remember, Acorn's first dabble in the IBM/DOS compatable field. It took the form of an additional circuit board carrying an 80186 (yes, a 186) processor, a BIOS and 512K of RAM which plugged into the Master's internal Tube. It came with modified versions of DOSPlus, Digital Research's early multi-user rival to MS-DOS, and GEM, a graphical user interface pre-dating Windows. It provided approximate DOS 3.21 compatibility (although there were some memory and peripheral differences) and would run M-TEC's BBC BASIC(86) interpreter as well as a PD version of it by the same authors, known as Master 512 BASIC, which operated across the Tube to directly access the Master's hardware and machine operating system (MOS). 9.1.2. This provided an opportunity to port and develop software originally written under MOS to the DOS environment. As the bulk of the code in the package was originally developed on a Master 512, it seems appropriate, for posterity if nothing else, to document briefly how best to run it on that machine. 9.2. First Some `Don'ts' 9.2.1. The first rule is don't try to run the programs under the PD Master 512 BASIC. They will load and some will even run, but because they assume PC and DOS screen modes, character sets, keyboard codes etc, they won't look very good or work correctly. 9.2.2. You can use a NETWORK.INI file to put files in different locations but don't lock or write-protect anything. For reasons I am unable to track down, on the Master 512 this causes problems with running BBC BASIC(86) programs. 9.2.3. Don't use a MOUSE.INI file. The programs' mouse code is PC mouse driver specific and won't work with the Master's MOS mouse. 9.2.4. Incidentally, there are some program listings given later. Don't try to run those containing sections of 8086 machine code on a PC. Although they're written for the same class of processor, they won't work and may crash the PC. 9.3. Running On The 512 9.3.1 The following text contains some code listings. You can copy the sections of .BAT or .INI code from this document and save them on disc as plain ASCII text for use. You can do the same with the BASIC code and *EXEC it into BBC BASIC and then save it as a .BBC program. If you don't have BBC BASIC(86), I'm pretty sure you can also use Master 512 BASIC as an editor for BBC BASIC(86) programs. So you could *EXEC code into 512 BASIC and, even if it won't run properly under that version, when you save it as a .BBC file, it will run okay under RUN.EXE. The CREDIT.BAT File: 9.3.2. I use the following CREDIT.BAT file ... echo off cls rem SPECIAL VERSION FOR MASTER 512. if "%OS%"=="DOSPLUS" bluon run !link %link% if exist action.bat action if "%OS%"=="DOSPLUS" vidon cls ... the `if exist ...' line probably isn't strictly necessary in a small-scale installation. Unless you're using the more sophisticated menu facilities in the Link you can leave it out. Screen Colours: 9.3.3. The `if "%OS%"= ...' lines check that the Link is being run under DOSPlus (which kindly sets the `OS' environment variable for you) and run a couple of small .COM files to change the screen colours. BLUON.COM changes the background colour to blue to make it a little less stark and VIDON.COM restores the usual black and white when the package closes down. The code for these can be hexcode assembled by the following listing (which will run under 512 BASIC): 10 REM BLUON.COM and VIDON.COM hex assembler 20 : 30 RESTORE 40 PROChex_asm("BLUON.COM",&31) 50 PROChex_asm("VIDON.COM",&31) 60 END 70 : 80 DEF PROChex_asm(f$,x%) LOCAL h%,n%,b% 90 h%=OPENOUT(f$) 100 FOR n%=1 TO x%:READ b%:BPUT #h%,b%:NEXT 110 ENDPROC 120 : 130 REM hexcode for BLUON,COM 140 DATA &B0,&13,&CD,&49,&B0,&01,&CD,&49,&B0,&07,&CD,&49 150 DATA &B0,&00,&CD,&49,&B0,&00,&CD,&49,&B0,&00,&CD,&49 160 DATA &B0,&13,&CD,&49,&B0,&00,&CD,&49,&B0,&04,&CD,&49 170 DATA &B0,&00,&CD,&49,&B0,&00,&CD,&49,&B0,&00,&CD,&49 180 DATA &C3 190 : 200 REM hexcode for VIDON.COM 210 DATA &B0,&13,&CD,&49,&B0,&01,&CD,&49,&B0,&07,&CD,&49 220 DATA &B0,&00,&CD,&49,&B0,&00,&CD,&49,&B0,&00,&CD,&49 230 DATA &B0,&13,&CD,&49,&B0,&00,&CD,&49,&B0,&00,&CD,&49 240 DATA &B0,&00,&CD,&49,&B0,&00,&CD,&49,&B0,&00,&CD,&49 250 DATA &C3 9.3.4. All these programs consist of are a series of pairs of 8086 machine code instructions in the form MOV AL, followed by INT &49. Interrupt &49 is a special (ie non-standard) DOS one built into the Master 512 BIOS which sends the byte in the AL register straight through the Tube to the MOS's VDU drivers (a so-called `raw handler'). The bytes sent this way construct VDU 19 (change palette) commands to alter the screen colours. To use another foreground colour change the 10th byte in line 140 (that's the `&07' - white) to another value using the usual BBC BASIC colour codes (given below) to use another background colour similarly change the 10th byte in line 160 (that's the `&04' - blue). You might want to change the name to something more appropriate than `BLUON' too. The background colours are in the range 0 to 7 and the foreground colours are 0 to 15 (&0F). However, on the 512 foreground colours 8 to 15 just result in `bold' characters rather than a high intensity colour. The BBC colour codes are: 1 Red 2 Green 3 Yellow (not brown as on PCs) 4 Blue 5 Magenta 6 Cyan 7 White The LINK.INI File: 9.3.5. The LINK.INI file I use is as follows ... &00004001 &23000007 &30000000 xxAARRSSxxIIQQxx Credit Programs Link action.bat credit link ! ^A^PR Calculations %Trurate2 ^R^ebate Calculations %Rebates2 ^S^chedule Agreements %Schedule !^ Read ^I^nstructions %Link.Instruct ^Q^uit the Link @ ! %Link.Lister %Link.Select %ClearUp|Link.Select %MultiCal %RebCalc ... as you may be able to tell if you've read all the technical stuff above, the programs are run in mono mode because the Master only provides two-colour text. Access is only provided to the `Two' versions of the calculator programs as I only keep a subset of the programs on my Master 512 disc (see CREDIT.DOC and - if you have it - DISTRIB.DOC if any of this doesn't make sense). 9.3.6. The corresponding LINK.DOC file, explaining what the function keys do (it's the lines between the ---'s), is ... --- The following programs/facilities are available from the Link using function key combinations: F1 F2 F3 F4 - File Program ClearUp Lister Selector Facility +Ctrl MultiCal RebCalc - - --- Screen Savers: 9.3.8. (This bit won't make sense unless you've read !Menu.Doc.) The construction of !Menu or !Link screen savers needs to be slightly different on the Master. The one listed below is called 512DANCE.BBC and is a Master version of the SQRDANCE saver available for PCs ... 10 REM >512DANCE by Brian Stewart, 1998 20 REM !MENU Screensaver Overlay 30 REM Acorn Master 512 version 40 : 50 ON ERROR PROCfatal 60 Prog$="":Menu$="":Y%=0 70 IF @%<>&90A Prog$=$0:@%=&90A:Y%=INSTR(Prog$,".") 80 IF Y%>0 Menu$=MID$(Prog$,Y%+1,TRUE):Prog$=LEFT$(Prog$,Y%-1) 90 PROCinit 100 : 110 ON ERROR PROCend 120 OSCLI("ESC ON") 130 PROCsaver 140 PROCend 150 END 160 : 170 DEF PROCfatal CLOSE #0:@%=&90A 180 VDU 0,0,0,0,0,0,0,0,0,0,26,20,12,7 190 PRINT "512DANCE (c) Brian Stewart, 1998"' 200 PRINT "Fatal error : `";:REPORT 210 PRINT "' (Code: ";ERR;"/";ERL;")"' 220 PRINT "Key to exit: "; 230 IF GET PRINT':OSCLI("ESC ON"):END 240 : 250 DEF PROCend MODE 3:PROCcol(7,4) 260 IF Prog$<>"" $0=Menu$:CHAIN Prog$ 270 END 280 : 290 DEF PROCinit 300 ST$=Prog$:OV$=".Saver":TIME=0 310 PROCsetcol:ENDPROC 320 : 330 REM --- no mouse routines 340 DEF FNkey=INKEY(1) 350 : 360 REM --- screen saver 370 REM Author: M J Draper, BEEBUG December 1988 380 REM Rewritten for PC: B R Stewart, June 1989 390 REM CGA version for slower machines 400 : 410 DEF PROCsaver 420 LOCAL max%,step%,res%,x%,y%,xst%,yst%,k% 430 MODE 0:VDU 29,640;400; 440 : 450 REPEAT T%=TIME:CLS:PROCcol(RND(7),0) 460 max%=380:step%=4:res%=4 470 x%=RND(200/res%)*res% 480 y%=RND(200/res%)*res% 490 xst%=RND(step%)*res% 500 yst%=RND(step%)*res% 510 : 520 REPEAT 530 MOVE x%,y%:PLOT 6,x%,-y%:PLOT 6,-x%,-y% 540 PLOT 6,-x%,y%:PLOT 6,x%,y% 550 MOVE y%,x%:PLOT 6,y%,-x%:PLOT 6,-y%,-x% 560 PLOT 6,-y%,x%:PLOT 6,y%,x% 570 x%=x%+xst%:IF x%>max% OR x%<0 xst%=-xst% 580 y%=y%+yst%:IF y%>max% OR y%<0 yst%=-yst% 590 k%=FNkey:UNTIL k%<>-1 OR TIME>T%+6000 600 IF k%=13 THEN T%=TIME+6000:GOTO 630 610 IF k%=32 THEN T%=TIME:GOTO 520 620 IF TIME6E4 640 ENDPROC 650 : 660 DEF PROCsetcol LOCAL P% 670 DIM code 30:P%=code 680 [opt 2:mov al,19:int &49:mov al,0:int &49 690 mov al,0:int &49:mov al,0:int &49:mov al,0:int &49 700 mov al,0:int &49:retf:]:ENDPROC 710 : 720 DEF PROCcol(f%,b%) code?5=0:code?9=b%:CALL code 730 code?5=1:code?9=f%:CALL code:ENDPROC 9.3.9. This format is pretty much the same as the standard for !Menu screen savers on a PC, but the PC mouse routines don't work so I've stripped them out and this version doesn't bother to read the screen mode code at the start of SAVERS.INI. PROCsetcol and PROCcol at the end of the listing are Master specific (it's those VDU 19 codes across the Tube again, this time in 8086 assembler format, to provide some more colourful displays than available in the basic CGA mode). 9.3.10. If you want to write your own savers simply put your code into PROCsaver instead and change the name etc. You might find the display of graphic mode animations like this example a little jerky because the 512 sends updates to the Master's screen memory across the Tube to the Master's video circuitry in bursts, rather than as they are made. 9.3.11. You'll need to provide a SAVERS.INI file as well, for this one saver all that's needed is ... 0; NB: CGA 640x480 - one colour 512DANCE 9.4. Conclusion 9.4.1. Having said all that, the above is only fine tuning to my particular preferences. The package should run on a 512 `out of the box', after all, that's where most of it started life. 9.4.2. I hope that's helpful to anyone still using a 512. 10. DOS CODE PAGES 10.1. You might find that the DOS text screen character set is different from that referred to in these notes (eg ASCII code 238 doesn't give you something that looks like a Euro symbol). This is probably because your PC is set up to use a different DOS `code page' from that I assumed. Most DOS-based PCs are generally set to the `American' Extended ASCII set (code page 437 in the EGA.CPI file) whereas Windows PCs, perhaps because they are set up for UK use, often seem to use the `Latin I' character set (code page 850 in the same file). 10.2. There doesn't seem to be anything you can do about this when the package is run in a Windows window or `DOS box'. You might find that some of the screen saver effects look wrong and the supposed `Euro' symbol might look like something else entirely on your PC. 10.3. However, you may be able to do something about it when running the package under DOS or if the problem persists when it's run full-screen under Windows, by using the MODE command to change the code page. 10.4. First, you need to know where the EGA.CPI file is kept on your PC. Try C:\DOS or C:\MSDOS for a DOS or Windows 3.11 PC or C:\WINDOWS\COMMAND for a Windows95/98 PC. If you're really stuck, go to the root directory (type CD \ at the DOS prompt) and enter ATTRIB /S EGA.CPI, or you could use Windows Find File function (in the File Manager in Windows 3.11 or on the Start Menu in Windows 95/98). This should hunt out the location and display it for you. I'll assume C:\WINDOWS\COMMAND for this example and you should substitute your location for this below. 10.5. Next, you need to issue a command to prepare the system to use the new code page and then another to select it. These are: MODE CON CP PREPARE=((437)C:\WINDOWS\COMMAND\EGA.CPI) MODE CON CP SELECT=437 10.6. On a DOS or Windows 3.11 PC you could probably just put these in your AUTOEXEC.BAT file - unless this messes up the display for other DOS programs. 10.7. Another approach, probably the only appropriate one with Windows95/98 PCs, is putting these in a separate .BAT file which then runs CREDIT.BAT. Strictly, you probably only need to run the `prepare' command the first time you start the package after switching on, but running it every time is easier and doesn't seem to cause any problems (you could probably also put the MODE commands in CREDIT.BAT). 10.8. You might also need to select the Latin I set again before running other DOS programs so you could add a `MODE CON CP SELECT=850' command to their startup procedure or, perhaps, to the end of CREDIT.BAT. It's just possible that you will need to `prepare' this code page to start with as well. 10.9. The `prepare' command will sometimes warn you that your keyboard does not support the selected code page - it still works however and, again, doesn't seem to cause any problems (put `>NUL' on the end of the prepare command if it annoys you). 11. OTHER INFORMATION 11.1. Please also see INSTALL.DOC for details on installing the package on a hard drive or under Windows, and CREDIT.DOC for general information on using the programs. Other technical files, particularly DISTRIB.DOC on copying the programs for other users and SELECT.DOC on running `OTHERS' programs, may also be available. 12. USING WINDOWS 98ME, NT, 2000 AND XP 12.1. The package provides DOS programs and can also be run under Windows 3.11, 95 and 98. More recent versions of Windows such as 98ME, NT, 2000 and XP do not support DOS programs or at least do not support them as well, so you may have problems, although few have been encountered in practice. 12.2. Fortunately, BBC BASIC is not an operating system specific language and the recently released BBC BASIC for Windows has made it possible to produce a patch which will allow the programs to be used on more recent versions of Windows. Further details are available from the Credit Programs website at: http://brian-stewart.members.beeb.net/credit/ Brian Stewart March 2002