• Getting started
  • Introduction
  • Requirements
  • Installation and using other QL ROMs
• Features
  • Main features
  • Overview
  • Full screen modes
• Files
  • QDOS Files
  • Access to QDOS formatted floppy disks
  • Format QL floppy disks (Windows NT only)
  • Access to QXL.WIN files
• Devices
  • Keyboard
  • Ram disk
  • Sound
  • Mouse support
  • Real time clock
  • Serial ports
  • Parallel ports
• Configurations
  • The QL Configuration dialog
  • Configuration files
  • Installing 16K expansion ROMs
• Appendices
  • Appendix I - Format of .QCF files
  • Appendix II - Format of QL files stored in the PC file system
  • Appendix III - Q-emuLator support site
  • Appendix IV - Address for feedback

Q-emuLator is a software emulator of the Sinclair QL home computer.

Originally written in 1994/95 for the Mac OS, Q-emuLator was ported to Windows three years later, and is still being improved.

Q-emuLator emulates the QL processor (the Motorola M68008) and redirects the QL I/O (video, keyboard, mouse, mass storage, sound, parallel and serial ports) to the PC hardware. Putting a QL ROM in this virtual environment makes it possible to run QDOS without its noticing that it's not running in a QL black case.

Q-emuLator runs like any other applications in the Windows environment, without taking over all the machine. You can switch to other active applications, and Q-emuLator can also run (more slowly) in the background.

A 486 or better system with Windows 95, Windows 98, Windows ME, Windows NT 4, Windows 2000 or later.

Sound emulation and full screen graphics are available if DirectX is installed on your system. (Recent Windows installations usually already include DirectX).

Formatting of QL disks is available only when running on Windows NT 4 or later (including Windows 2000).

No special installation is required before running Q-emuLator: run the program and start the emulation by choosing "Start" from the 'QL' menu, or just by clicking over the QL picture!

Have fun!

The emulator needs a file with a 48K QL rom image to work, but such a file is already provided with Q-emuLator. The provided ROM is a Minerva 1.89 ROM, compatible with the original Sinclair ROMs, but faster and with more features. Minerva version 1.89 and earlier is public domain. It duplicates all standard QL commands and firmware features. A disk version of an up-to-date Minerva, with disk manual documenting extra features (currently 1.97 with 1.99 in preparation) is being compiled for sale. Enquiries to Tony Firshman, TF Services, 29 Longfield Road, TRING, Herts, HP23 4 DG, UK. Tel: 01442-828254. Fax: 01442-828255. Email: tony@firshman.demon.co.uk.
Other QL ROMs are not included in the Q-emuLator's package for copyright reasons. If you like, you can find a Sinclair ROM image on the Internet (follow the link from the 'Q-emuLator for Windows' www page), or you can create it on your QL with the "SBYTES FLP1_QL_ROM,0,49152" command. This command doesn't work on Gold Card and Super Gold Card systems, as you get a modified ROM image instead of the original one. Therefore, if you have a (Super) Gold Card, you must disconnect it before using the SBYTES SuperBASIC command and copy the ROM to a microdrive, then from there to a floppy after reconnecting the card.

Once you have the ROM file on a QDOS floppy disk you can read it from Q-emuLator on your PC. Follow these steps:

1. Launch Q-emuLator.
2. Insert the QDOS floppy disk with the ROM file image in the PC drive (A: or B:).
3. Click on the gray rectangle representing the left microdrive slot (below the window with the QL picture); choose 'QDOS Floppy Disk' from the pop-up menu that appears, and choose either 'A:' or 'B:' from the sub-menu, depending on where you inserted the floppy disk. Q-emuLator looks at the disk and displays its name on the microdrive slot.
4. Choose the 'Install QL ROM from disk...' command from the 'File' menu. This instructs Q-emuLator to copy the ROM image in its directory and use it for emulation. (Warning: this command requires Q-emuLator to reside in a writable directory and not on CD-ROM or other read-only media).

What if you would like to install a new ROM image that is already on your PC, instead? (For example a ROM that you downloaded from Internet.) In this case you need to point Q-emuLator to the ROM image: go to the 'QL Configuration' dialog (Choose 'QL Configuration...' from the 'QL' menu), click the uppermost 'Select...' button and find the ROM image file in the file selection dialog that appears. Done! Close the 'QL Configuration' dialog by clicking the 'OK' button.

• original QL with up to 16M of RAM
• supports Sinclair and Minerva ROMs
• up to two 16K expansion ROMs
• up to 8 virtual microdrives, each mapped to a Windows directory, a floppy disk drive or a QXL.WIN file
• access to QDOS formatted floppy disks
• support for subdirectories
• format QL floppy disks (Windows NT only)
• original QL screen (mode 4, mode 8) and second screen (used by some games and by the Minerva ROM)
• the QL screen can be displayed in a window or full screen
• should be compatible with any PC keyboard layout
• built-in ram disk
• sound emulation
• mouse support (when the Pointer Environment is installed)
• serial ports
• parallel ports
• QL and Q-emuLator settings can be stored in configuration files and later retrieved
• QL and Q-emuLator settings easily editable through a user-friendly interface
• acceleration of some QDOS graphics routines
• paste text from the Windows clipboard

The program main window has two parts: the upper part shows the QL display, and the lower part the virtual microdrives.

You can attach a Windows directory, a disk drive or a QXL.WIN file to a microdrive slot by clicking in it (in the microdrive slot gray rectangle) and selecting a command from a popup menu.

To transfer files from your QL system to the PC you can use QDOS formatted floppy disks and read them from Q-emuLator.

When the emulation is running, you can enter one of the two Q-emuLator full screen modes. Full screen mode are available only if DirectDraw (a DirectX component) is installed.

Press the F12 key to enter the 640x480 full screen mode, where the QL display occupies most of the screen. This is the fastest graphics mode. Press F12 again to return to window mode.

Press the Shift+F12 keys to enter the 1024x768 full screen mode. This mode is slow, because each QL pixel is mapped to multiple PC pixels, but the QL display takes the whole screen. This is the only mode that emulates flashing in the QL 8 colors display mode. To return to window mode, press F12.

In full screen mode, menus and microdrive slots are not available. To access them, return to window mode by pressing F12.

Executable files (and some other kind of files) are stored on the PC in a special format containing QDOS-specific information.

The compressed "FileUtil_zip" archive contains some utilities that can be used on a QL, should you ever need to translate files with a QL between QDOS and Q-emuLator for Windows formats. The translation is automatically carried over for you on your PC when you use Q-emuLator to copy files between a Windows directory and a QDOS formatted disk. To translate (on a QL) QDOS files to the Windows format you can use the "QLToWin_exe" utility. The archive contains two other utilities: "MdvToWin_exe" translates to the Windows format files stored on copy protected microdrives, while "WinToQL_exe" translates back from the Windows format to the QL's.

Note: most non-executable files don't need to store extra QDOS information; therefore they have the same format both in the QDOS and in the Windows environment.

You can attach QDOS formatted floppy disks to the virtual microdrive slots. When you click on a slot you can choose to attach it to a Windows directory, to a QXL.WIN file or to a floppy disk drive with a QDOS formatted disk in it, or you can empty the slot if it was already filled. Note that you access each of the eight virtual MDV slots with all of the MDV, FLP and WIN device names, regardless of what type of medium is attached to a slot.

Note: FLP1 and FLP2 refer to slot 1 and slot 2, NOT to drive A: and B:. Of course, if you like you can attach drive A: to slot 1 and drive B: to slot 2, but you are not required to do so.

The FORMAT command is available only on Windows NT4 or Windows 2000 or later.

For example, if you want to format a floppy disk in QL format you could proceed as follows: 1) start Q-emuLator, and start emulation by clicking on the QL picture and then pressing F1 at the QL F1/F2 prompt; 2) click on the first microdrive slot and select QDOS Floppy Disk and then A: from the menu; 3) insert the disk in drive A: and finally enter the SuperBASIC command FORMAT FLP1_.

When you FORMAT a disk, Q-emuLator automatically detects the disk density and formats the disk with the appropriate number of sectors, resulting in 720KB of free space for a DD (double density) disk and 1.4MB of free space for a HD (high density) disk.

A window pops up asking you to choose between Full Format and Fast Format modes, or you can cancel the operation. Full Format completely erases the disk, while Fast Format just empties an already formatted disk, but is extremely fast.

IMPORTANT: Use the Fast Format option only to quickly erase all the files from an already formatted disk (either in PC or QL format). If the disk is unformatted and you use Fast Format, you may lose all the data that you subsequently store on the disk. With both the Full and Fast types of format, any data stored on the disk is completely erased and there's no way to recover it after the format operation!

You can use the Fast Format option to quickly erase a formatted PC disk and convert it to the QL disk format.

During a Full Format operation, a window shows its progress and offers the option to abort it by pressing the Cancel button. However, even if you press Cancel at this point, any data previously present on the disk are lost.

In this manual the term 'QXL.WIN file' refers to the DOS files used by the QXL (a hardware QL emulator for DOS) and by QPC (a software QL emulator for DOS) to store the emulated QL file system. These files are similar to images of QL hard disks stored in a single DOS file.

Q-emuLator allows you to attach QXL.WIN files to microdrive slots to access their content. However, the access is read-only: Q-emuLator can't write to or alter QXL.WIN files in any way. The reason is that there's no official standard available for the QXL.WIN format, so writing to QXL.WIN files might corrupt them in the event that the structure of QXL.WIN files changes. Access to QXL.WIN files is provided as a convenience to read QL programs stored in archives with this format, but if you need to write to QL files, using the Windows file system is a better option.

Q-emuLator is compatible with all types of PC keyboards.

The keyboard type-ahead buffer has been expanded from the QL's 7 characters to over 1000 characters.

Some PC keys not available originally on the QL are used as a shortcut for common combinations of QL keys:

• Backspace: ctrl+left arrow
• Delete: ctrl+right arrow
• F6 to F10: shift+F1 to shift+F5
• Page Up: shift+up arrow
• Page Down: shift+down arrow
• Home: alt+left arrow
• End: alt+right arrow
• Scroll Lock: ctrl+F5 (freeze screen); both Scroll Lock and ctrl+F5 can be used to freeze/unfreeze the QL display output; the Scroll Lock led on the keyboard is on when the QL screen is frozen.

Two other PC keys have special functions :

• F12 and shift-F12: toggle between window and full screen mode
• Insert: paste up to 1KB of text from the Windows clipboard

Q-emuLator provides a built-in ram disk device driver. If you use it instead of loading a QL software ram disk driver (like 'ramprt') you will gain in speed.

The device name is 'ram' (but you can change it in the 'QL Configuration' dialog) and it has eight drives, 'ram1_' through 'ram8_'.

You can use the ram disk both in dynamic and static mode. In dynamic mode you can freely copy files to the ram disk and more ram will be allocated for it every time it is needed, up to filling the whole QL's memory. In static mode you assign a fixed memory amount to each drive, by formatting the drive and specifying the requested number of blocks as the medium name: for example, the command 'FORMAT ram1_400' assigns a fixed amount of 200K (as each block is 512 bytes long) to the first ram drive.

To erase a whole ram disk drive at once use the 'FORMAT' command without specifying a file name: for example 'FORMAT ram4_'.

In static mode all the memory needed by the driver is allocated when you format the drive. This means that you are sure that no other job can take away that memory before the ram driver needs it, but also that the ram driver is not allowed to use more memory than the amount specified.

While dynamic mode is easier to use, you are encouraged to use static mode whenever it is possible, because it is a lot faster: in dynamic mode the driver has to call emulated QDOS routines every time that it wants to allocate or release a block of memory, whereas in static mode all the memory is allocated at the beginning and QDOS is no longer called.

The ram disk device driver is not level 2 (i.e. it doesn't support subdirectories), and there are no SuperBASIC extensions to modify its behaviour (for example there is no RAM_USE keyword).

If you prefer to use another ram disk driver (although it will be slower, as it has to be emulated), just disable the built in device driver in the 'QL Configuration' dialog, and install your driver by installing an add-on rom containing it or by loading it from your boot file.

Note: For a ram disk drive used in dynamic mode, the DIR command reports a negative number of free sectors and zero total sectors. Zero is the number of sectors statically allocated to the ram drive (none if in dynamic mode). The number of free sectors is calculated as the total number of statically allocated sectors (zero for a dynamic ram drive) minus the number of used sectors, and it is therefore negative for a dynamic ram drive. Consider for example a ram drive with 100 sectors full of data; if in dynamic mode, DIR reports -100/0 free sectors; if the ram drive was statically formatted with 400 sectors, DIR reports 300/400 free sectors.

QL 'BEEP' emulation is available if DirectSound (a DirectX component) is installed on your system.

Sound is on by default. You can turn it off through a switch in the 'QL' menu.

There is still a minor problem with sound emulation: a click is sometimes heard if a BEEP command is issued when a previous BEEP command is still playing.

Mouse emulation is provided under the Pointer Environment through a special mouse driver, named 'MacMouse'.

To take advantage of it, install the 'MacMouse' mouse driver (included in the Q-emuLator package) JUST AFTER having installed the Pointer Environment (that is, the 'PTR_GEN' extension, not included in the Q-emuLator package).

To install the mouse driver use the following SuperBASIC command:

a=RESPR(1024):LBYTES mdv1_MacMousexy,a:CALL a

or, if Toolkit II is installed:

LRESPR mdv1_MacMousexy

The command assumes that the 'MacMousexy' file (replace x and y with the version number: for example 'MacMouse11' for the mouse driver version 1.1) is in the first Microdrive slot.

Once the mouse driver is installed, any active QL mouse cursor will be moved instead of the Windows pointer when it is over the QL display window (provided that the QL display window is the frontmost window).

Note that as the QL cursor follows the Windows' one, its speed is independent from any settings in the QL environment; on the PC, the mouse speed can be set in the Mouse Control Panel.

Unlike the left and right mouse buttons, the central button is not emulated.

The QL had a real time clock, but you had to set it every time you started the computer, because there was no battery to keep it working while the computer was powered off. On Q-emuLator there's no need to set the QL real time clock, as the current date and time is read from the PC clock every time the program starts.

Note: changing the QL clock settings doesn't affect the PC clock, and the change is limited to the duration of the current emulation session.

SER1 through SER4 are linked to COM1: through COM4:.

To open a serial port I/O channel you specify the device name and options with the following syntax:

SERnpft

n, p, f and t represent optional characters that you can add to the name to specify the port number and other parameters. The following table shows the possible values for these parameters:

You can omit any of the n, p, f and/or t parameters (the driver assumes default values), but if you specify them you can't invert their order. For example you can write SERHZ, but not SERZH.

The baud rate can be set to most of the usual QDOS values, plus many PC values not originally supported by the QL, up to 256000 baud, if your serial port supports it. For the higher transmission rates, however, it is recommended to use hardware handshake, as otherwise the emulated QL could be too slow to handle the data without losses.

The TRA command, present in JS and later ROM's versions, is not implemented. This command allows to specify a character translation table, but usually communication programs don't use this feature.

The Minerva and SMSQ extensions to the serial driver are not supported.

You can access to the LPT1: and LPT2: parallel ports of your PC through the PAR1 and PAR2 QL devices.

The driver supports bi-directional ports.

To open a parallel port I/O channel you specify the device name and options with the following syntax:

PARnt

n and t represent optional characters that you can add to the name to specify the port number and other parameters. The following table shows the possible values for these parameters:

You can omit the n and/or t parameter (the driver assumes default values), but if you specify them you can't invert their order. For example you can write PAR2Z, but not PARZ2.

You can disable the QL parallel device or change its name in the 'QL Configuration' dialog.

The term configuration denotes a set of Q-emuLator's preferences and of emulated QL's settings. Only one configuration can be active at any time. You can change some configuration settings through menus. For example you can change the QL's RAM amount through the 'RAM' menu. All the other settings that can't be changed through menus are editable in the 'QL Configuration' dialog

To recall the 'QL Configuration' window, choose the 'QL Configuration' command from the 'QL' menu.

The 'QL Configuration' window has five pages, named 'ROMs', 'Devices', 'Serial ports', 'Graphics' and 'Start-up'. You access each page by clicking on its label in the top part of the window.

The 'ROMs' page allows setting the names and locations of the QL ROM images to be used by the emulator. File paths can be absolute or relative. In the latter case they are relative to the directory containing the Q-emuLator application.

The 'Devices' page allows to enable or disable devices not present in the original QL (for example, the ram disk) and to change their names. Device names can be 1 to 9 characters long. You can also enable or disable support for QL subdirectories.

The 'Serial ports' page defines which PC COM port to attach to each of the four QL SER devices available (SER1 to SER4). A QL SER device can be disabled by setting its output to 'None'. You can route more than one QL SER device to the same COM port, provided you don't use all of them at the same time.

The 'Graphics' page allows to enable or disable acceleration of some QDOS graphics commands (cls, scroll, pan, block, mode). Enable graphics acceleration for maximum speed, disable it when you run emulation at original QL speed to play games or in case graphics acceleration turns out to be incompatible with your QL software.

The 'Start-up' page allows to specify an optional key to be automatically pressed at the initial QL F1/F2 prompt, which display mode to use when starting emulation and to enable or disable two more Q-emuLator preferences:

• If the 'Skip QL power-on memory test' option is checked, the QL will not execute the memory test at start-up. The memory test is the first thing that you see when you power on or reset a real QL and is responsible for the coloured dots that fill the screen before the F1/F2 prompt. Checking this option skips this test, so you go directly to the F1/F2 prompt. As a result, the QL's start-up is quite faster, especially with large QL RAM amounts.
• The 'Open QL session at start-up' option instructs Q-emuLator to immediately start a QL emulation session when starting or when reading the configuration from file.

Configuration files store the emulated QL's configuration and some other Q-emuLator's settings.

Configuration files have the ".QCF" suffix.

To start Q-emuLator with the settings specified in a particular configuration file, double-click its icon, or drag it onto the Q-emuLator's icon. If you start Q-emuLator without opening any configuration file, the program uses a default configuration. If you want to define your personal default configuration, you can do it by saving the desired settings into a configuration file named "default.qcf" and placing it in the Q-emuLator's directory.

You load and save configuration files through commands in the Q-emuLator's 'File' menu.

A 16K expansion ROM can also be optionally used by the emulator. If a 16K expansion ROM is installed on your QL, you can get an image of it with the "SBYTES FLP1_BACK_ROM,49152,16384" command. To tell Q-emuLator to use the ROM image, copy it to your hard disk, go to the 'QL Configuration' window, press the second 'Select...' button (that on the 'Back ROM' line) and select the ROM image on your hard disk.

A configuration file is a text file used to store the emulated QL's configuration and some other Q-emuLator's settings.

Configuration files are quite similar to Windows ".INI" files: each line of text describes a different preference or setting, identified by a keyword. The format of each line is:

Keyword = Value

You can, for instance, set the QL's ram amount to 640K with the following line in a configuration file:

Ram = 640K

Configuration files have the ".QCF" suffix. Unlike ".INI" files, you can have multiple configuration files, and you can store them anywhere you like.

Follows a description of the keywords you can find and use in configuration files. For each keyword the following table shows the possible values, their meaning, and the default value. The last column shows how you can alter the setting from within Q-emuLator.