+-----------------------------------------------------------------------------+ ¦ TECHNICAL NOTES on the Ansible APE Plus emulator ¦ +-----------------------------------------------------------------------------+ Nothing in this file is absolutely essential to normal use of APE Plus. We offer it in order to provide more advanced information for people who are interested in exploring APE, have run into offbeat problems, or want to know more about its limitations. Most of the material dates from the early 1990s and has been updated mainly by deleting statements which no longer apply. No further development of APE Plus is intended. (2002) CONTENTS LIST ------------- When scanning this with a word processor or display utility, use the search/find feature for quick location of the required section. E.g. to find a section number when using the APE Plus text lister program (called by the CONFIGURATION menu when you ask for technical information), press F for Find and enter 1.2 or whatever, followed by Return. Pressing A for Again repeats the search. Main headings in the text are preceded by stars, so that searching for *6.1 would take you straight there and omit cross-references. DOS 6 users: where we refer you to your DOS manual, you may often find that the information in question has been relegated to the on-screen HELP system. Type HELP at the C:\> prompt instead. 1. APE PLUS AND PC-DOS 1.1 Batch files--bypassing the APEPLUS.EXE Menu 1.2 Memory used by APE Plus 1.3 The APE Plus menu tree: WHICH FILES ARE NEEDED? 2. APE PLUS AND THE KEYBOARD 2.1 Apricot's BIOS Key-Reprogramming 2.2 Apricot Keyboard-Loader COM Files 2.3 Editing the DOS Command Line: IBM and Apricot Function Keys 3. OBSCURE ERRORS AND THEIR CURES 3.1 From within APE Plus 3.2 With APEDRIVE 3.3 APAC accounts 3.4 dBase II and Friday 3.5 Delta 3.6 Estimaster (Sirius) 3.7 File'n'Find (Mimex) 3.8 Finax Gold (see also 5.2) 3.9 GWBASIC 3.10 MSBASIC 3.11 Sage Accounts and Payroll 3.12 SuperCalc 2 3.13 SuperWriter and printer problems in general 3.14 Timax (see also 5.2) 3.15 Windows 3.0 and 3.1 3.16 WordPerfect macro editor (Ansible) 3.17 WordPerfect (especially 4.0) 3.18 WordStar 4. THE MSDEV.SYS `MICROSCREEN' 4.1 What is it? 4.2 Possible problems 4.3 The Apricot Xen-Xi 5. THE SPECIAL `Z' OPTIONS IN APE 5.1 Why? 5.2 The complete list: Z1 for Orchard Finax Gold Z2 for programs which mess up your APE keyboard Z3 alternative printer handling Z4 disable APE critical error handler Z5 "super-enable" APE critical error handler 6. PROGRAMS APE WILL NOT RUN, AND WHY 6.1 Graphics 6.2 Communications 6.3 Miscellaneous [End of contents list.] The information in this text file is copyright (c) Ansible Information Ltd, 1989-2002 and may not be legally disseminated to others without written permission. *1. APE PLUS AND PC-DOS ------------------------ *1.1 Batch files--bypassing the APEPLUS.EXE Menu If you have an old IBM with not much memory and would like to avoid the memory overhead of our APEPLUS.EXE menu--or if you just prefer to do everything from the DOS command line--you can use the `minimalist' APE.COM alone. (APE.COM is used by the APEPLUS.EXE Menu.) APE can be installed as a resident program with the command APE, or asked to run an Apricot program directly. An example of the first approach: ECHO OFF APE C ! L SW SW %1 APE X APE is loaded with keyboard SW.KB (L SW), the IBM underline cursor (C) and the calculator (!). Then SuperWriter is run, and APE de-instals itself with X. Installing APE like this saves having to instal it again if several programs are to be run in succession. The second approach is more streamlined. APE Plus allows you to squeeze the essentials into one command line if required, using the extra command character * (`run program whose name follows'). An example: @ECHO OFF APE C ! L SW/ * SW.COM %1 This tells APE to (in order): select the IBM cursor, load the calculator, load the SW.KB keyboard (note the / marking the end of the keyboard name), and run SW.COM ... that is, SuperWriter--the full name with .COM is needed. With *, APE does not linger in memory: here it vanishes as you exit from SuperWriter. For those unacquainted with batch files: the %1 allows you to pass a document file name to SuperWriter when you load up. E.g. if the above four lines constituted a batch file called W.BAT, typing W would just run SuperWriter, but W MYDOC would also load the file MYDOC for editing (if it can be found). The @ECHO OFF with which each file begins is to suppress the appearance of every batch file line on the screen (i.e., stop the lines being `echoed'). In DOS version 3.20 or earlier, the @ should be omitted: this is a later `tidiness' facility which allows you to suppress the echoing of the ECHO OFF line itself. If you use batch files rather than the APEPLUS.EXE Menu, you are deprived of many menu facilities such as EGA/VGA fonts, automatic program installation (be sure to check program needs, such as special loaders and keyboards), automatic directory changing (use the CD commands in your DOS manual if you want programs to run in a directory other than APE's), the `Divert from A or B' options (instead see SUBST in your DOS manual), etc. When using both APE.COM and APEDRIVE.COM, always instal APEDRIVE first and `remove' it last. If APE.COM alone hangs your computer, see the note in READ.ME about APEFIX.COM (for problems with non-standard BIOS versions). *1.2 Memory used by APE Plus `Will it gobble up huge chunks of my computer's memory?' we are asked by nervous but technically aware enquirers. No. We've worked hard to make APE a highly compact program. APE.COM, current size approximately 20k, contains within itself all the required data space for things like keyboard tables and print buffers. The memory used up when APE alone is installed will always be less than the size of APE.COM. APE 4.01 uses less than 16K. The MSDEV.SYS `MicroScreen' is tiny and needs barely more memory than the size of the .SYS file. APECAL.EXE is more of a memory-gobbler than APE, weighing in at 20-30K of actual memory use depending on how it's installed. APEDRIVE uses less than 7K. Loading all four thus absorbs about 55k at most. More likely, you'll be using the APE Plus menu ... with which APEDRIVE is not needed. Total memory use rises to about 100-110K, a relatively small chunk of a typical IBM 512k or 640k system. This drops to under 100k if you don't load the calculator--the first thing to try if an Apricot program ever complains of memory shortage. BUT PLEASE NOTE THAT AS FAR AS WE KNOW THIS HAS NEVER HAPPENED! (`Memory allocation error' is something else ... see 3.8.) All these figures are for program versions on the APE 4.01 disk; they tend to increase as APE is further refined, but only slightly. We won't repeat the calculation *every* time another 20 bytes are added.... To put this in perspective, we once tackled the problem of why the A86 shareware assembler would apparently not run on an unexpanded 256K Apricot but would on a 256K IBM. The trouble was that the Apricot luxury features (printer buffers, soft keyboards, multiple fonts, huge graphics area, etc.) soaked up an awful lot of memory. By a process of experiment, we found that an expanded Apricot PC/Xi would begin to run the problem program when its RAM was increased by 77k over that of a `nominal 256K' PC/Xi. In other words, you could very roughly say that by moving from a `256k' Apricot PC to a `256k' IBM clone, you gain some 77k of available RAM, which caters for most of APE Plus's memory use even at maximum. And it's impossible to buy a new IBM with a mere 256k nowadays: 1Mb is the bare minimum. *1.3 The APE Plus menu tree: which files are needed? If you're pruning your hard disk, you can throw out quite a lot of APE Plus. Any .COM program loader or .KB keyboard file not actually being used can be omitted, for example--see manual and READ.ME. Here is the calling structure of the main APE Plus menu: APEPLUS.BAT (created in your root directory on installation) changes to the \APE directory and runs: APEPLUS.COM (actually needed only with certain nonstandard BIOS versions) which runs: APEPLUS.EXE (the main menu) which reads setup information from: MENU.APE (configuration and installed programs) CONFIG.APE (screen colour and RS232 settings) AUTO.APE (Auto installation menu data) AUTO1.APE (Auto installation sub-menu data) and, as initially set up, uses: T.EXE (display utility) which then shows: URGENT.DOC unless you've told APE not to ... after which the CONFIGURATION menu options of APEPLUS.EXE run: 2 AICOPY.EXE (for Apricot file copying, but only when selected; the file copy menu itself is an integral part of APEPLUS.EXE) 3 CONFIG.EXE (screen colour and serial port editor) which modifies: CONFIG.APE 4 KEYEDIT.EXE (keyboard editor ... creates/edits .KB files) 5 KB.EXE (Apricot keyboard converter) which can in turn load: KEYEDIT.EXE 6 FONTEDIT.EXE (font editor ... creates/edits .C14 and/or .C16 files) [or, depending on your selection and video system] FONTTABL.EXE (font table editor for non EGA/VGA systems) which modifies: FONT.APE 7 T.EXE (display utility) which then shows: READ.ME 8 T.EXE which then shows: TECHDATA.DOC The PROGRAMS menu of APEPLUS.EXE can be set up to run almost anything, and normally makes use of: APE.COM (the heart of the emulator) which reads setup information from: CONFIG.APE APECAL.EXE (the Apricot-like calculator, when requested) ... but not APEDRIVE.COM (APEPLUS.EXE contains its own version of this) You can delete some of the configuration editors if they are not needed: e.g. deleting CONFIG.EXE, FONTEDIT, FONTTABL or KEYEDIT will simply disable the relevant CONFIGURATION menu options. You can probably delete APEDRIVE.COM and APEFIX.COM if you intend to work only from the main APEPLUS menu (rather than batch files in DOS). APEPLUS.PIF, .ICO and .GRP can be deleted if you do not wish to run our software from horrible old Windows. All .C14 fonts can go if you have a VGA or better system; all .C16 fonts can go if you use an EGA monitor; both can be dropped if you don't want variable fonts at all (or if your machine doesn't support them). Any of the following can go if, after consulting the manual and READ.ME, you feel you'll never need the facility (obviously you'll keep a reserve copy on your backup floppy!): HELP.BAT (uses T.EXE to show READ.ME from the DOS prompt) READ.ME and all .DOC files MK.COM AIBAK.EXE AICHOP.EXE and AICHOP.DOC AICOPY.EXE (if you have 5.25" drives or find that Apricot copying works without selecting this last-resort option) AIREST.EXE ANEW.EXE APEFORM.EXE NEWS.EXE and NEWS.DAT (our on-disk newsletter) SCOPY.EXE TODAI.EXE MSDEV.SYS (if you don't want the MicroScreen facility) For example, a minimum selection to run SuperWriter alone and use Apricot-format disks would be APEDRIVE.COM, APE.COM (always load this after installing APEDRIVE) and SW.KB. Plus CONFIG.APE if you've changed the default screen colours, and APECAL.EXE if you want the calculator. *2. APE PLUS AND THE KEYBOARD ------------------------------ *2.1 Apricot's BIOS Key-Reprogramming Another arcane point. APE will recognize and obey the weird Apricot ESC 4 sequence which allows reprogramming of keys through the BIOS screen driver. But, very obviously, the IBM has no MicroScreen keys: attempts to program the `normal' positions of these keys with ESC 4 will affect the Alt positions of the numerical `typewriter' keys 1-6. Similarly the Apricot keys CLEAR and SCROLL are `mapped' on to the IBM's End and PgDn: a program's attempt to alter CLEAR will affect End. Programs which change keys with this command and don't change them back can be checked for with the APE S[filename] command, which will write a FILENAME.KB including any ESC 4 modifications. For cases when you've worked out your own keyboard and *don't* want a program's ESC 4 keyboard changes to muck it up, we allow the command to be disabled with APE Z2...see section 5.1 below. This support is geared to the *Apricot* and not the slightly different Sirius key coding. See the notes on Sirius Estimaster, section 3.5. It is reported that with some BIOS variants, holding down SHIFT and the grey Insert key with APE installed can occasionally throw the keyboard into a peculiar shift-locked state (which can persist even after APE has been removed from memory). Press Shift and the End key on the number pad -- not the grey one -- to clear this keyboard state. *2.2 Apricot Keyboard-Loader COM Files If an Apricot program comes as a small (around 2-3K) COM file plus other, much larger files, the first is probably a keyboard loader. Typically it will contain a specialist keyboard table and will (a) reset the Apricot keyboard pointer to use this keyboard; (b) possibly label the MicroScreen or issue a message; (c) run the main program file; (d) when the program has finished, restore the old keyboard. Operation (a) can overwrite parts of IBM DOS, producing hangups or failed disk access when loading or saving. As a safety measure, APE Plus monitors program loads and watches for programs having the characteristic size and content of a dangerous keyboard loader... in which case, the loader operation is automatically bypassed and control transferred directly to the program which the loader would, after its fatal keyboard work, have loaded. A harmless message is issued to let you know what's happened. WordPerfect's WP.COM and WP.EXE are a good example of the above. WP.COM merely labels our `fake' MicroScreen if MSDEV.SYS has been installed: it can be omitted and WP.EXE run directly. *2.3 Editing the DOS Command Line: IBM and Apricot Function Keys If you were a practised user of the Apricot you might have been accustomed to such short cuts as pressing ESC and capital U to restore the previous command. (This normally worked only at the DOS prompt and in a few MicroSoft specials like DEBUG.) E.g. if you'd just done DIR \THIS\THAT\*.* and found so many files that they scrolled off the screen, you could cause the whole tedious command to reappear with ESC U, allowing /P to be typed at the end for a DIR listing which pauses at each full screen. On an IBM, provided no intercept programs are messing this up, pressing F3 repeats the former command line as ESC U did on the Apricot, and the other function keys do associated things ... F1, for example, restoring one letter only of the command. Of course APE *does* normally intercept and modify all the function keys. But the `set function key' facility (see keyboard editor instructions) makes the IBM functions available when APE is loaded with its default keyboard: the Alt positions of F1 to F10 will return the `normal' IBM function. In brief: to repeat a DOS command line with APE loaded, press Alt plus F3 instead of the usual (on IBMs) F3. *3. OBSCURE ERRORS AND THEIR CURES ----------------------------------- *3.1 From within APE Plus APE Plus provides its own error message if the printer is unready or not connected. See option Z4 in section 5.2 below. When the Debug option has been set from the DOS command line with APE D ... or by putting D in `Enter optional APE commands' when using APE menu setup ... APE reports three categories of `unsupported call' on the status line (Line 25 of the screen). These are: unsupported Escape sequences (screen control command sequences not supported in APE), unsupported Control Device calls followed by DEV (device) and COM (command) information, and unsupported `INT EC' calls followed by register contents information. The Control Device call (INT FC) was Apricot's all-purpose BIOS interface for a multitude of odd facilities; INT EC is the extended screen/graphics handler from the final BIOS versions. As we frequently mention, APE does not support any graphics calls. In each case: if you run into such an error message, always let us know all the reported information. The most important BIOS `devices' to be completely unsupported in APE are those concerned with low-level disk access. This is very dangerous since the systems aren't compatible at this level. Only programs like FORMAT are liable to run into this problem, and you should always use the IBM FORMAT and DISKCOPY rather than moving across incompatible Apricot utilities. (NB: Apricot's references to `devices', as echoed above, are misleading. These are BIOS input/output control channels, and have nothing to do with the devices and device drivers of MS-DOS terminology. Our MSDEV.SYS is an example of the latter.) *3.2 With APEDRIVE When reading Apricot disks in an IBM drive via the APE Plus menu or APEDRIVE, we have noted two or three rare oddities. A `General Failure' error message (normal when you try the trick without APE Plus or APEDRIVE) may result from a clone BIOS which fails to act on APEDRIVE's `this disk is now different, honest' signals. There are two things to try: select R for Retry once or twice, and if this fails, select A for Abort and repeat the whole operation after physically removing and replacing the Apricot disk. WARNING: R for Retry, when APE Plus or APEDRIVE is not installed, may on some more `liberal' IBM operating systems give you a correct-looking disk directory. BEWARE OF COPYING FILES OR RUNNING PROGRAMS. The different Apricot disk layout is overwhelmingly likely to cause drastic misreadings of files. *3.3 APAC (Apricot Accountant)...an odd case. On closer examination, it emerges that this package's APAC.COM program file as supplied runs on the Apricot using a standard IBM emulator! `I should really have known that Apricot would do things the hard way,' comments our customer. To run this on the IBM, get rid of EMIBM.EXE (the emulator) and simply run it without APE. [Later] We have since encountered the APAC.EXE stock control etc. system, which is a true Apricot program and halts with a maddening error message when transferred to IBM. When items 5 or 6 are selected from the menu (Data Analysis or Stock Control), mysterious security checks are made and the program stops with the message that one is ATTEPTING (sic) to run a non-network version of the program on a networked system. Yes, we can fix this, but it's more of a bother than usual. We need to have a working copy of your program, in order to make slight changes to the files which will eliminate this spurious error message. The first time this arose, it took four days of diagnostics to locate the problem and then 15 minutes to fix it. We'll be as quick as we can. You will of course keep a copy of the old Apricot version as backup and in case it needs to be run on the Apricot. [This offer now withdrawn.] APAC.EXE also needs `Divert from A' set in the APE PROGRAMS menu. *3.4 DBASE II VERSION 2.4x, and no doubt earlier versions: here Ashton- Tate made the classic mistake of assuming that unofficial quirks of DOS would be preserved in later MicroSoft releases. In fact there are several levels of problem to be reckoned with here. All involve file handling, and produce errors ranging from zero-byte DBF files through `Unexpected end of file' messages to fatal DOS errors: `FCB unavailable'. To be on the safe side, use our DB.COM loader program to run any version of dBase which has been transferred from an Apricot or Sirius. See READ.ME (`Latest general information') for the alternative DB0.COM. *3.5 DELTA databases. These may give an unexpected `disk full' error when your hard disk is patently not full but has huge amounts of space. The usual symptom is perfect working until you try to add a new record, and then the error message. It's the large disk space that's the problem. Delta was written when 20Mb was as large as a hard disk ever got; at 32Mb up, we think, it interprets the high `disk free space' value computerishly as a negative number! One solution is to run Delta from a floppy; another is to ballast your hard disk with space-consuming junk files until the space is reduced (you can always delete them later when the room is needed); a third is to run Delta on the DOS 6 Drive H (or whatever) `host drive' for Double Space, which is small enough not to bother Delta and usually has enough room for it. *3.6 ESTIMASTER for Sirius: for some weird reason this program alters the Esc key to generate a different character (ASCII 15), and refuses to accept the normal ESC character (ASCII 27) as the exit command in certain submenus. This would be no problem if Estimaster were an Apricot program, but although the Sirius `screen control' sequence which reprograms a key is much the same as the Apricot one, the keyboard layout was different enough to result in different effects. Instead of changing the Esc key to generate the chosen character, Estimaster-with-APE changes the `MicroScreen' key combination Alt-4 (on the top row of the typewriter keyboard). There are two ways to cope: (1) When Esc fails, escape from the problem menu by pressing Alt-4 *or* Control-O. (2) Make up a modified keyboard with KEYEDIT, based on SIRIUS.KB with the normal position of the Esc key changed to give Control-O. See also section 5.2 concerning the Z2 option. *3.7 FILE'N'FIND (Mimex): what a horrid little program this is, with a uniquely nasty means of going wrong. It insists on writing the registration info to disk, cleverly trying to put it in a file called *.* to make life harder for you, the user. (This file name cannot be copied, etc.) In modern versions of DOS the loophole has been closed: trying to write a file with this name will instead--and very logically-- overwrite the first file in the directory. If this is the main database program FF.EXE, the program shoots itself unerringly in the foot. We have omitted the program from `Auto installation' because we want you to read this warning first! Solution: make sure the first file in the directory to which you copy your File'n'Find program is a dummy. (For example: start with an empty directory and enter COPY CON DUMMY followed by a few Returns and Control-Z.) This file will be messed up by F&F's installation. Bad news: you have to give the code number and user name every time you use it. Good news: we can fix this on request by writing a loader program (but are disinclined to do at present, since we know of no one who wants to use the wretched software). *3.8 FINAX GOLD: see section 5.2 concerning the Z1 option. Version 986.1 should be loaded using the FINAX.COM loader--see manual. Use the End key for the `exit' functions performed by the missing Apricot CLEAR. *3.9 MSBASIC: `Memory allocation error...cannot load COMMAND.COM', followed by a complete hang-up, is caused by printer trouble! Apparently, when an LPRINT command fails because the printer isn't on-line, the obsolete MSBASIC tries to pass control back to COMMAND.COM but does not exit in the proper modern way; the resulting snarl-up produces the disaster. (APE is actually not involved--it happens with MSBASIC running alone.) Again, check that the printer is up and running. We've met MSBASIC programs which rather annoyingly send many initialization codes to the printer when they start up--that is, *before* any actual command to print has been given. You are warned. Solution: APE now provides its own `critical error handler' which substitutes a sensible Retry query in the event of printer trouble as above. With MSBASIC, always get the printer on-line and select Retry (or reboot). Asking for Abort will crash the system as before, since MSBASIC does not--as described above--abort in a way that allows more recent versions of COMMAND.COM to load. We were exceedingly vexed to be accused of an `APE cursor handling bug' which is in fact an MSBASIC quirk the customer hadn't noticed on his Apricot. Typically, this takes the form of a unwanted new line being started for no apparent reason. The normal cause is heavy use of ESC sequences which move the cursor (this includes screen clearing with ESC E or ESC z). What is happening: MSBASIC tries to keep track of how many characters have been printed on a line, and starts a new line when it feels one is needed. ESC sequences confuse it doubly, first by not (usually) producing actual characters, and second by (often) changing the cursor position, so the character count has little relation to reality. Solution: (a) Preface ESC cursor movements with a Return, which will reset MSBASIC's `characters on line' count. For example, defining CL$=CHR$(13)+CHR$(27)+"E" means that PRINT CL$; will clear the screen *and* convince MSBASIC that it's back at the start of a line. (b) Set WIDTH to a big value early in your program--say WIDTH 200. This alone could solve the problem unless your program does most cursor positioning via ESC sequences and rarely or never issues a plain PRINT `text' with no final semicolon. A large WIDTH is advisable in any case to prevent MSBASIC being upset by text lines which fit on the screen all right, but contain non-printing sequences like `underline on/off' etc...these still affect the MSBASIC character count. *3.10 GWBASIC. The Apricot GWBASIC won't function on an IBM even under APE Plus ... sorry. (It uses a complex graphics screen format even to show text, and APE does not support graphics.) Compiled GWBASIC programs are usually untransferrable. Interpreted ones--which come as .BAS files and need GWBASIC.EXE to operate--can normally be transferred by moving only the actual program files and running them with the GWBASIC.EXE supplied with IBM DOS 3 and 4. *3.11 SAGE ACCOUNTS and PAYROLL. Sage Accounts version 1 has so far defeated us: it programs the Apricot PC/Xi hardware in a way which is not only untransferable (even to other Apricots) but flatly contradicts Apricot's own programming guidelines. Other versions work well without real problems, but note that these packages like to load program information from drive A; PAYROLL also insists that its data be in drive B. `Auto installation' in the AI Menu will select the `Divert from A' options. To have them run entirely on the hard disk, you may need to select `Divert from B' as well. Batch file fanatics can use SUBST commands instead. A suitable batch file for all purposes would be: SUBST A: C:\APE [or C:\SAGE etc.] SUBST B: C:\APE [or C:\SAGE etc.] SAGE [or PAYROLL] SUBST A: /D SUBST B: /D This assumes that the program was installed to use two drives (using Sage INSTALL.EXE). If it's been set up for a single floppy drive, there will be repeated--though harmless--prompts to change disks. Better to use INSTALL again, picking the twin-floppy or single-hard- disk option. (In the latter case, A is assumed and the diversion or SUBST commands referring to B can presumably be omitted.) *3.12 SUPERCALC: the RSC2.COM file (if present) is a keyboard loader for SuperCalc 2--see section 2.4. Remember to use the IBM End key when required to press the missing Apricot CLEAR. *3.13 SUPERWRITER: `Disk error' and a return to the system prompt usually meant that the printer wasn't connected, or wasn't switched on, or wasn't set to `on line'. What was happening was that SuperWriter bypassed the IBM DOS error handler, which would give you a chance to activate the printer and select Retry, and substituted a nasty little routine of its own which did nothing but halt with the `disk error' message. Solution: no action should be needed now that APE Plus provides its own, much more friendly error handler. A status line message in plain English offers the chance to Retry (after readying the printer) or Abort (halt SuperWriter). `Too many documents on your disk already': this error message can appear incorrectly when you Save a document from SuperWriter, leading to loud cries of anger since you will almost certainly be using a hard disk with oodles of space. It is usually caused by picking a new document name which is also the name of an existing subdirectory: DOS won't let SW save an ordinary file with the directory name, and SW, dating as it does from before subdirectories were much used, interprets the message as best it can. Easy solution: pick another name. *3.14 TIMAX: see section 5.2 concerning the Z1 option. Version 1086.1 should be loaded using the TIMAX.COM loader--see manual. *3.15 MicroSoft WINDOWS 3. This appears not quite bright enough to work out that APE.COM removes itself entirely from memory and restore the system to its former state: if you run an Apricot program from a batch file invoked from Windows, say, and then return to Windows you get a mysterious Windows message about `your pop-up program' having been installed (despite the fact that it has also been removed). This is harmless. Press Ctrl-C as requested. APE Plus has a way around this hindrance, used by the APEPLUS.EXE Menu and available for your own batch files. You simply use the APE command line option `*' to run a program *without actually installing APE itself as a resident program*. This placates Windows and avoids its request for Ctrl-C to be pressed. A sample command line to load the SuperWriter keyboard and then run SuperWriter directly from APE is shown as the `second approach' to batch file use in section 1.1 above. Using Windows, any program which runs successfully with APE can be run in a window by specifying this in Windows set-up or by pressing Alt-Enter (see Windows manual). This is not actually that useful--screen handling is slowed down and at its largest the window won't show quite the full screen width--but if you're a complete Windows addict this does allow you to shrink Apricot programs, toggle between them with mouse clicks, and other horrid things. *3.16 WORDPERFECT MACRO EDITOR: for Apricots there was only our own. WM.COM is a keyboard loader (see section 2.4) and can be discarded for IBM use. In this case the main macro editor program WM.OVL should be *renamed* as WM.COM for IBM command line/batch file use. Additionally, WM expects the Apricot WordPerfect keyboard. Load APE with APE L WP or specify the WP keyboard in the APE 90 menu. The APEPLUS.EXE Menu runs WM.OVL directly, and `Auto installation' selects this plus the WP.KB keyboard. Of course, if you transfer to the IBM version of our PARAGON utilities for WordPerfect 4.1/4.2, APE won't be needed to run the macro editor. There is a special discount for conversion of Apricot to IBM PARAGON. *3.17 WORDPERFECT. WP.COM is a keyboard loader. See section 2.4. Apricot WordPerfect 4.0 has a serious problem on any machine other than the old PC/Xi--this includes the other Apricot models. Although it appears to run OK on Apricot F-series machines and on IBMs with APE, printing will always fail in some way. (We have recorded a blunt `Printer not accepting characters' on an XT clone, a crash with `Internal stack failure' on a Tandon AT, and a complete hang-up on an Apricot F10.) Apparently some clown in WordPerfect Corp decided to program the PC/Xi printer port by direct hardware access. *3.18 WORDSTAR: the RWS.COM file (if present) is a keyboard loader. See section 2.4. *3.19 NETWORKS. It is reported that the APE/dbase II loader combination fails when used on the LANtastic network. Nobody has yet given us a free LANtastic setup on which to test and diagnose this.... As a general rule we do not recommend use of APE on networks ... although the only known problem is with LANtastic as above. In order to provide a true emulation of the Apricot, APE necessarily simulates the Apricot's handling of a number of non-IBM-standard software interrupts. If a network requires the same interrupts, there is a fatal clash. *4. THE MSDEV.SYS `MICROSCREEN' -------------------------------- *4.1 What is it? If the word MicroScreen means nothing to you, and has been a constant source of bafflement, your old Apricot was presumably an F-series or Portable model. The PC, Xi and Xen MicroScreen consisted of a liquid crystal display (40 columns x 2 rows) arranged so that messages on the display could form labels for six special keys (horrible membrane keys on the PC/Xi, decent keys on the Xen). The idea was of course that clever programs could dynamically re-label the keys. Most programmers had the sense not to rely on this, as such programs became incomprehensible on F-series machines and unusable on PC/Xi models where, as so often, the flimsy membrane keys had failed. APE.COM by itself doesn't support the BIOS MicroScreen `device' or more than a fraction of the relevant screen-driver escape sequences. The one thing APE does is to suppress screen output when all text has been diverted to the MicroScreen. Any MicroScreen output is thrown away without comment (irrespective of whether the `Debug' option has been set)--unless MSDEV.SYS has been installed, in which case the output is passed to this device handler. Background: Apricots support MSCREEN as a `DOS character-output device', while IBMs don't. A DOS character device can be written to exactly as though it were a file. So if a file called MSCREEN materializes on your IBM disk during an APE session, it almost certainly means that an Apricot program has tried to write to the MicroScreen by this slightly devious route. This is a hint that you should instal our spurious IBM MicroScreen device, MSDEV.SYS. This `MicroScreen' simply simulates the 40x2-character liquid crystal display as a single 80-character line--the normally unused (on Apricots) Line 25 or status line. *4.2 Possible problems When using MSDEV.SYS, watch for those rare programs which do actually use the status line for other output. The clash will be harmless but might look messy. Device names behave like filenames: you can use the COPY command to send text to MSCREEN. But devices take precedence over files. For example, you cannot create a DOS file called NUL, as NUL is a built-in `black hole' device--any output written to it is thrown away. This also applies to the device name followed by any extension whatever: NUL.COM, NUL.DOC, NUL.TXT etc. are all `impossible' file names. Thus, should you ever try to create a file called MSCREEN or MSCREEN.DOC (etc.), be warned that if MSDEV is installed, the output will go to the MSCREEN device and *not* to a file. (This is also why the device driver file is called MSDEV.SYS and not MSCREEN.SYS. If the file had the same name as the device name, it could not be referred to once the device had been installed.) You may need to reshuffle (mentally) the `MicroScreen' labelling when programs rely on alignment of the two rows. For example, SuperWriter labels the first special key as INS MODE. (Alt-1 on the top row, in our default APE keyboard.) The INS should appear above the MODE. Of course when the lines are put side by side, you get INS, then the top half of each other key label, then MODE, and so on. *4.3 The Apricot Xen-Xi The Xen-Xi is or was a curious transitional Apricot model, nominally IBM-compatible but with a MicroScreen. We never bought one so have no direct experience of using its MicroScreen display. Installing MSDEV.SYS won't help, except insofar as that this will create the fake MicroScreen on Line 25 as described. Our information (thank you, Eddie Bromhead) is that this machine is supplied with a program called MS.EXE, similar if not identical to that which came with the old PC/Xi, and that this can be used both to label the LCD display and to program its keys. Here without any guarantee of accuracy is Apricot's own MS.TXT message file, which goes with MS.EXE: Apricot MicroScreen Editor VR 1.1.0 17th July 86 Correct Usage is: MS /E [d:][filename] MS [d:][filename] MS - Number in the range 1 - 6. - Text to appear on microscreen, MUST BE CONTAINED WITHIN DOUBLE QUOTES. - String to be assigned to key, MUST BE CONTAINED WITHIN DOUBLE QUOTES. The optional @ character will be replaced by a carriage return character Apparently the [filename] can contain a complete set of instructions *in a different format from MS command line instructions*, allowing the LCD labels, lights and key assignments to be set at a stroke. We have some examples courtesy of Mr Bromhead, if required. Good luck with this, Xen-Xi owners. Remember, the information does not apply to IBMs in general! *5. THE SPECIAL `Z' OPTIONS IN APE ----------------------------------- *5.1 Why? When trying to reconcile hardware and operating systems as different as the Apricot and IBM are (despite superficial similarity), we keep running into quirks and oddities, and need to make compromises. The Z options are a series of special APE `switches' intended to handle the peculiar demands made by certain programs, which are however not appropriate as *permanent* features of APE. The Z commands are all issued with Z followed by a digit as a special command to APE. E.g., in the APE Plus PROGRAMS setup menu: Enter optional APE commands >Z1 Or at the DOS prompt: C>APE Z1 [CR] More than one Z option can be invoked at the same time: Z1Z2. And they can also be combined with other APE commands: APE CZ1DZ2L SW, to give a somewhat clotted example (load APE, request small cursor, set debug mode, load the SW.KB keyboard, and set Z options 1 and 2). The APE Plus menu of course handles the C and L options as separate queries about the cursor and keyboard, leaving Z1DZ2 as `optional APE commands'. *5.2 The complete list Z0 ... turns off *all* special Z options listed below. You will not need this when using the APEPLUS.EXE menu, as the emulator APE.COM is not left installed on return to the menu. Z1 ... modifies the Apricot INT ECh text display command for writing a block to the screen. Reason: the Orchard Finax Gold accounts program clears defined rectangles of the screen by a misuse of this command which thanks to an obscure Apricot quirk does normally work, but which on IBMs will usually write blocks of gibberish instead of clearing the area. Z1 alters the `write block' command so that for the duration it is interpreted as `clear block'. Orchard's TIMAX should also be loaded with Z1. Both FINAX GOLD and TIMAX also need the optional I command (see manual). Z2 ... disables the ESC 4 facility which allows programs to modify the keyboard via escape sequences sent to the BIOS. There are two reasons for wishing to do this: to prevent Sirius programs making incorrect changes to APE's Apricot keyboard (see section 3.5 on Estimaster, above), and to protect your own customized keyboard against programs like SuperPlanner which force their own bizarre changes. Z3 ... invokes the Apricot printer buffer and diverts both Apricot (Control Device) and DOS printer calls through this 2K store. It can speed up things like SuperWriter by letting the printing outrun the printer so that you come back to the menu 2048 printed characters sooner. But we have had a bit of trouble with this feature, which seems acutely hardware-sensitive: certain BIOS versions, combined with slow (12/13 cpi) daisywheel printers, may result in your losing the occasional character in labour-intensive jobs such as justified proportional spacing. Research continues. Meanwhile, the default is normal printing through DOS unless you actively select Z3. This is a change from the practice in older APE versions (2.48 to 3.02), where the options were reversed and Z3 turned the printer buffer *off*. (Once again, do remember the sensitivity of IBMs to printer errors: always check that your printer is CONNECTED and TURNED ON and SWITCHED TO `ON-LINE' and also CONTAINS PAPER, before printing with APE. See next paragraph!) Z4 ... turns off APE's built-in `critical error handler'. As of APE 3.11, this error handler will normally be active, watching for `sensitive' printer errors and bypassing the error handlers of programs which do a poor job in this area when transplanted to IBMs--notably, SuperWriter (which halts) and MSBASIC (which crashes). Instead, APE offers a status line message suggesting that you ready the printer and then select R for Retry or A for Abort (halt the whole program). Any text formerly on the status line will be restored after a successful Retry. We provide the Z4 option just in case some Apricot program particularly needs its own error handler and gets upset when--as normally--APE retains control. We don't actually know of any such programs, but it's possible.... Z5 ... forces APE's error handler into operation even when a program tries to circumvent it. This was added in response to a compiled BASIC package which persistently gave Disk Media Error messages when the printer was offline and printing was attempted, and circumvented our own error handler by direct mucking with the interrupt table. Z5 uses brute force to overcome this kind of thing; theoretically it may slow DOS response time by a trifle, but usually it seems undetectable. (Technical point: the APE error handler deals only with printer errors, arbitrarily defined as any critical error in writing to a DOS character device whose name begins with P [PRN] or L [LPT1 etc.]. Other critical errors are passed immediately to the default DOS error handler.) *6. PROGRAMS APE WILL NOT RUN, AND WHY --------------------------------------- *6.1 Graphics The Apricot PC/Xi/Xen graphics system is wholly incompatible with IBM graphics. Since Apricot graphics programs are rather few, APE simply does not support graphics functions. The commonest program affected is GWBASIC (use an IBM GWBASIC instead--ask us if you can't find one). Compiled GWBASIC programs are all unusable with APE for this reason. SuperCalc 3 and Delta with the DeltaGraph package can be used if you avoid the graphics facilities. Some programs use special fonts to produce pseudo-graphics: if the font file is in normal Apricot CHR format it can be converted, adapted as necessary and selected in APE. One difference you'll see is that many graphics characters won't `join up' like the Apricot's, but have narrow vertical lines separating them. Apricot fonts are designed to `join up', and right-hand pixels are left blank to separate non-joining characters. IBM fonts are shown with a blank vertical line of pixels between each character ... with a special exception for graphics characters 179-223 in the ASCII table, which do `join up'. This is faked on the screen by copying the right-hand column of pixels of these characters (only) into the normally blank column on the video display. So Apricot characters not in this range can't be made to join up, and non-graphics characters in this range will develop odd protrusions on their right. *6.2 Communications Apricots were luxury machines as far as serial communications were concerned; 1993 IBMs still didn't come with all the features that were standard on the Apricot, and thus there were basic difficulties with emulation. In general we advise against trying to transfer `comms' programs ... better to acquire a state-of-the-art system that is tailor-made for IBMs. APE does what it can, usually enough for a serial printer connection. Busipost and Communiqué are two packages known not to run with APE. *6.3 Miscellaneous Some programs are beyond APE's emulation, usually because they make special hardware checks, are copy-protected, or are simply too big and complex to be analyzed so that a corrective loader can be written: Lotus 1-2-3 1a, Orchard Finax and Finax Plus, Psion Xchange, Perfect Filer. Some crash the IBM by tricks like loading font data directly into `Apricot font memory', which usually overwrites and destroys vital parts of an IBM operating system (rebooting will cure this. Microsoft Word plays this trick, but in this case we were able to write a loader program that skips the font-tampering). In one or two cases like FormatPC we have never had a fully working copy of the program to allow completion of a corrective loader. Memory-resident Apricot programs are also unsuitable for APE use. +-----------------------------------------------------------------------------+ ¦ APE Technical Notes Copyright (c) Ansible Information, 1993-2002 ¦ +-----------------------------------------------------------------------------+