ATARI 8 BIT HARD DISK EMULATOR Version 1.2 USER GUIDE November 1991 Acknowledgements: I would like to acknowledge the excellent work of Nick Kennedy in pioneering the design of the hardware to connect the ATARI to a PC and without which this program could never have been started. Whilst this program contains entirely different code to Nicks' SIO2PC software it retains the look and feel of his original program so all praise to him for the original idea. The main menu program was written and compiled using the Microsoft BASIC Professional Development System and uses Microsoft run time library code during its execution. The serial port handler and command interpreter were developed using Borland Turbo Assembler. Debugging would not have been possible without the extensive use of Microsofts' Code View product. 1 1. Overview . . . . . . . . . . . . . . . . . . . . . . . 3 2. Installation. . . . . . . . . . . . . . . . . . . . . 4 3. Starting the Emulator. . . . . . . . . . . . . . . . . 4 3.1 No configuration files. . . . . . . . . . . . . 5 3.2 Default configuration file exists. . . . . . . . 5 3.3 Named configuration file. . . . . . . . . . . . 5 4. Screen Display . . . . . . . . . . . . . . . . . . . . 5 5. The Main Menu. . . . . . . . . . . . . . . . . . . . . 6 5.1 F - Create Floppy Disk. . . . . . . . . . . . . 6 5.2 H - Create Hard Disk. . . . . . . . . . . . . . 7 5.2.1 SpartaDos X. . . . . . . . . . . . . . . 7 5.2.2 SpartaDos 3. . . . . . . . . . . . . . . 8 5.2.3 MyDos 4.50. . . . . . . . . . . . . . . 8 5.3 L - Load Disk . . . . . . . . . . . . . . . . . 8 5.4 U - Unload Disk. . . . . . . . . . . . . . . . . 9 5.5 X - Exchange Disk. . . . . . . . . . . . . . . . 9 5.6 R - Make Disk Read Only. . . . . . . . . . . . . 9 5.7 W - Enable Write to disk. . . . . . . . . . . . 9 5.8 S - Set Port Number. . . . . . . . . . . . . . . 9 5.9 D - Display directory. . . . . . . . . . . . . . 9 5.10 Q - Quit Program. . . . . . . . . . . . . . . . 10 5.11 T - Toggle Line Status Display. . . . . . . . 10 5.12 C - Create/Amend Configuration . . . . . . . . 10 5.13 P - Print Through Mode. . . . . . . . . . . . . 10 6. Configuration Files. . . . . . . . . . . . . . . . . . 11 6.1 Creating a Configuration File. . . . . . . . . . 12 6.1.1 Set port address. . . . . . . . . . . . . 12 6.1.2 Load drives D1: - D8:. . . . . . . . . . 12 6.1.3 Default Directory Specification. . . . . 12 6.1.4 Time-outs. . . . . . . . . . . . . . . . 13 6.1.4 Display Status Line. . . . . . . . . . . 14 6.1.5 Loading an existing configuration file. . 14 6.1.6 Saving your changes. . . . . . . . . . . 14 6.1.7 Exit. . . . . . . . . . . . . . . . . . . 14 7. Time and Date Support. . . . . . . . . . . . . . . . . 15 8.File Transfer Utilities. . . . . . . . . . . . . . . . 16 8.1 The PCTFR program. . . . . . . . . . . . . . . . 16 8.2 The File Transfer Interface. . . . . . . . . . . 17 9.Problems . . . . . . . . . . . . . . . . . . . . . . . 19 2 1. Overview HDEMUL is a program which runs on an IBM PC or compatible and uses the hard disk of your PC to provide between 1 and 8 disk drives for your 8 bit ATARI. Connection between the ATARI and PC is made through the SIO2PC hardware adapter which joins the ATARI SIO port to the PC serial port. This hardware was designed by a guy called Nick Kennedy and is described in the SIO2PC distribution pack. Please note that the SIO2PC software and hardware are Shareware products and the appropriate royalties (currently $10) should be sent to Nick Kennedy, 300 South Vancouver, Russellville, AR 72801 before using them. HDEMUL is different to SIO2PC in one important respect. SIO2PC uses PC RAM to provide simulated disk drives up to 184K. This restricts the user to 3 or 4 drives depending on the amount of spare RAM available. HDEMUL actually reads and writes to the hard disk of the PC. It can provide up to 8 drives and each drive can support a disk up to 16 Megabytes in size. The size of the free space on your PC disk is the only limitation with HDEMUL. The interface runs at 19.2 KBits per second, which is the standard ATARI SIO rate. Its performance (on my PC at least) is faster than a 1050 drive but very much slower than a proper parallel hard disk interface. The program performs ALL disk accesses via MSDOS interfaces and should not represent a hazard to the rest of your PC software. It will support any valid MSDOS path name and can be used with PC floppy drives. The program will require MSDOS 2.0 or later. It was tested using both MSDOS 3.3 and DRDOS 5 running on an 80386 processor at 16 MHz. It was also tested with the clock rate slowed to 8MHz without significant loss of performance. At the ATARI end no additional software is required for normal disk operations. The interface is at the level provided by a standard drive e.g. read sector, write sector, etc. It should thus be compatible with all normal software and all versions of DOS. The program will NOT support ultra speed IO or any form of copy protection (bad sectors, phantom sectors, sector skewing etc.). It will support all 1050 drive commands together with extensions to allow double density and hard disk working. The program was tested with DOS 2.0, DOS 2.5, SpartaDos 3.1, SpartaDOS X and MYDOS 4.5. It has been used with a fair range of word processors, sector editors and unprotected games programs without problems. I do not own an XF551 drive and have absolutely no idea whether the program is compatible with this device. The emulator can be used in conjunction with real drives on the same SIO chain provided there is no clash between the drive number of a real and emulated drive. 3 The following facilities are available within the HDEMUL program:- Emulation of 92K single, 133K Dual and 184K double density drives. Hard disk emulations of 1, 5, 10 or 16Mbyte disks with SpartaDos or MyDos. Up to 8 simultaneous drives in any combination of sizes. Print through from your ATARI to an attached PC printer, the PC screen or a PC file. Write protect (via MSDOS) of your disk images. Configuration files to allow you to start up with your preferred options preset. Ability to load, unload or interchange disk files while the program is running. The ability to automatically set your SpartaDos clock from the PC clock. File transfer from MSDOS to ATARI format and vice versa. If you have access to a PC with free disk space then this program will provide an alternative to using real 810, 1050 or hard disk drives without loss of compatibility with anything other than copy protected disks. 2. Installation. The software is distributed in MSDOS format and is contained within the self extracting archive file HDINST.EXE. To install the program copy the HDINST.EXE file into your chosen PC directory and simply type HDINST. The files contained within HDINST.EXE will now be extracted automatically and should appear as:- HDEMUL.EXE The main program HDEMUL.UG This user guide MYDOS.DSK The MYDOS 4.50 disk image The HDINST.EXE archive file may now be removed from the working directory. 3. Starting the Emulator. The emulator can start up in 3 ways depending on whether any configuration files exist in the working directory. Configuration files have the file extension .CFG and are used to preset the emulators' working parameters. Details of how to create a configuration file and which parameters it affects are in section 6. When you start the emulator for the first time there will be no configuration files available. 4 3.1 No configuration files. Type HDEMUL in the working directory and the emulator will load and start. The main menu screen will appear followed by a prompt at the bottom of the screen asking you to enter the COM (serial) port number that you wish to use. Only numbers between 1 and 4 or M will be accepted. Enter the number appropriate to the port to which your SIO2PC hardware is attached. If you have a non standard PC whose serial port address does not correspond to the normal values (COM1=03F8h 2=02F8h 3=03E8h 4=02E8h) then type M. Typing 1 to 4 will cause the program to initialise the appropriate port and enter the main program. Typing M will bring up a second prompt asking for the four digit hexadecimal value of your port address. All 4 digits are required, so use leading zeros if necessary. Only the values 1 to 9 and A to F will be accepted. After the fourth digit the program will initialise the port and enter the main program. 3.2 Default configuration file exists. When the emulator is started by typing HDEMUL on its own it first searches the working directory for a default configuration file called HDEMUL.CFG. ( See section 6 for instructions on how to create such a file). The program will start up, initialise the COM port,load any identified disk files and then move to the main program loop automatically if the default file is found. It will behave as in 3.1 if no file is found. 3.3 Named configuration file. Configuration files can be created with any valid filename in order to allow you to start the program with a variety of parameters (see section 6). To use a different configuration file simply type HDEMUL FILENAME and the program will behave as in 3.2 but will use the FILENAME.CFG parameters. With this facility you may create a number of .CFG files for different purposes. For example you may create one which loads your word processor into D1, your text files into D2 and sets the COM port. If you then name this WP.CFG you can type HDEMUL WP and the emulator will set itself up ready to start your word processing session without any intervention from yourself. 4. Screen Display. The screen may be divided into 4 areas. The top part contains all of the main menu options (see section 5). The next part contains the drive numbers. When a file is loaded into a drive the filename, size and density will be displayed against the drive number. In addition the letters RO will appear if the file is write protected. 5 The apparently empty area below the drive numbers is used for two purposes. All prompts to which you must respond will appear in this area and any error messages detected within the emulator program will also be shown here. The error messages will display for a time between 1 and 59 seconds before disappearing. The default is 1 second but this may be changed from the configuration menu (see section 6). Note that these errors refer to the operation of the PC program and do not relate to the ATARI or the SIO bus. Typically they will be cheerful little missives like disk full or invalid filename and will occur when you least want them. The final area is the line status display. This tells you what the ATARI has just sent to the PC in its command buffer. The first entry is the command number (in hex and as an ASCII character), the second is the device identity to which it refers, the third and fourth are the values of AUX2 and AUX1 respectively and finally the command line status (high or low) is displayed. Device identity and auxiliary values are displayed in hex. The purpose of the status display is to keep you abreast of the SIO bus activity. Note that AUX2 deliberately appears before AUX1. This is simply because these fields are predominately used as sector identities with AUX2 containing the most significant part. By displaying AUX2 first you can determine the sector address without having to make a mental juxtaposition. Typically you will see Command:52 (R) Device:31 Aux2: 01 Aux1:68 Command Line: H which means the ATARI is trying to read from drive 1, sector 168h. The Command line actually flickers very rapidly between H and L. In practice the display will be predominately H but will flick onto L momentarily in time with the command frames. If it ever shows L consistently then you have lost contact with the ATARI bus. 5. The Main Menu. The main menu options are available at any time once the COM port has been initialised. They should NOT be used while an SIO data transfer is in progress. The main menu routines run independently of the SIO handler and the program will stop polling the SIO line while the menu options are being actioned which will result in loss of data. Many of the options require additional input. If you wish to abandon an action during the input sequence then press ESCAPE to return you to the main menu and cancel the action. 5.1 F - Create Floppy Disk. Each pseudo floppy disk that you create is actually an MSDOS file which will be 16 bytes longer than the capacity of the disk that you specify. The first 16 bytes contain header information for the emulator to use and is 6 normally transparent to you. To create a floppy disk choose the F option. You will then be prompted for the drive number that you wish to assign to the disk. Enter a number between 1 and 8. If you choose a drive which already has a disk assigned to it then the new disk will replace the existing one without damage to the original. The emulator then asks you to choose 1 of 3 sizes for the disk. Type 1 for a 92K single density, 2 for a 133K dual density or 3 for a 184K double density disk. Next the program will ask you to assign a name to the disk. As this name will be the MSDOS filename for the disk image it is necessary to obey the normal MSDOS rules in choosing the name. It is also very sensible to give it a meaningful name and to use a standard extension (.DSK for example) such that you can readily distinguish the disks in your directory listings. Complete your filename with a carriage return and the program will set up the MSDOS file, clear all the entries in it to zero (the progress of which will be displayed on a thermometer) and load the file into the chosen disk drive. At this stage you MUST use your ATARI based DOS to format the disk as if you had just put a new disk into a physical drive. The actual ATARI format request will be ignored by the emulator but your ATARI DOS will then go on to build a directory structure on the disk without which it will be unusable. Take care to match the format request to the size of the floppy disk or you will encounter problems. 5.2 H - Create Hard Disk. To create a hard disk image type H. The program will ask which drive you wish to assign to the disk and then prompt you for the size of the disk. Choose 1 for a 1 Mbyte disk, 2 for 5Mbytes, 3 for 10Mbytes and 4 for 16 Megabytes. Remember that the disk image will be created at full size so make sure that you have enough room on your PC disk for the new file. The program will then prompt for the disk file name which must obey the normal MSDOS rules for file names. Once this is entered the program will create the MSDOS file and clear the entries to zero. A thermometer will display the progress of the clearing operation which will take quite a long time, especially for a 16MByte disk. Be patient, as long as the thermometer is rising you can be sure that the program has not stalled. Once the file has been initialised it MUST have a directory structure written to it. This is achieved by using either the format or build directory command of your ATARI DOS. Obviously you must be using a DOS which will support hard disks (ie not ATARI DOS 2.5). The method for SpartaDos X, SpartaDOS 3.2 and MYDOS is described below. 5.2.1 SpartaDos X. Users of the SpartaDos X cartridge should type FORMAT and wait for the fancy box to appear. Identify the disk unit number for the hard drive and you should see, 7 for a 1 Meg disk, 4096 sectors, 1048576 Bytes and Format n/a appear in the box. Obviously for other sizes of disk the values will vary. Set the Volume name if desired and then press B to Build Directory and you will get the message: "Unit is NOT a floppy disk. Are you sure?". Press Y for Yes and you will get the message: "Caution. Destroys Old Data. Are You sure?" Press Y again and SpartaDos will then write out the appropriate sectors to make the disk useable. 5.2.2 SpartaDos 3.2 SpartaDos 3.2 users should run the HDINIT.COM program. The program will prompt with: "Hard Drive to Format (3 or 4)?". If your drive is neither 3 nor 4 then use the eXchange disk option on the emulator so that it is. Respond with the appropriate drive number and the program will ask: "Volume Name?". Type in the volume name and you will see: "Initialize - Are you sure?". Respond with Y and SpartaDos will initialize the disk and build the directory structure for you. 5.2.3 MyDos 4.50. This method probably works with other versions of MYDOS which support high capacity drives but I can only verify it for 4.50. Choose O - Change Configuration from the menu and follow this sequence: Drive No. or return? type in drive number Remove Drive? type N for no. Is Drive Configurable? type Y for yes High Capacity Drive? type Y for yes Drive Size (sectors) type 4096 for 1 MByte 20480 for 5 Mbyte 40960 for 10 MByte 65535 for 16MByte Now choose I- Initialize Disk from the menu, choose the appropriate drive and type Y to format and it should all happen for you. 5.3 L - Load Disk The load disk option allows you to mount your MSDOS file images on one of the 8 drives. The protocol is simple, specify the drive number and MSDOS filename when asked. Note that the file name can contain a full path specification if you want to load a file from other than the current directory. You may load files from any PC drive, including floppies. If the file specified is not an HDEMUL or SIO2PC disk file then an error message will be displayed and the load aborted. If the file does not exist you will be re- prompted for the file name. Escape will return you to the main menu from the filename prompt. 8 5.4 U - Unload Disk. Unload disk will prompt you for a drive number and then close the associated MSDOS file. The drive display will be cleared and the emulator will no longer respond to commands for that drive. 5.5 X - Exchange Disk. Typing X for exchange disk will cause the emulator to prompt you separately for the two drive numbers on which the disks that you want swapped are mounted. The emulator will close both files and re-open them on the designated drives. It is permissible to swap with an empty drive or even swap two empty drives if you have got time to waste. 5.6 R - Make Disk Read Only. With all these disk drives floating about it is very easy to write to the wrong drive from time to time. To protect your program disks from being over-written select option R from the menu. This option will prompt you for a drive number and then make the MSDOS file currently loaded on that drive read only. This will permanently change the MSDOS file attribute and the file will remain read-only until you explicitly change it. The file will display the letters RO after it whenever it is loaded to remind you that it is read only. The action is the same as executing the MSDOS command: ATTRIB +R filename 5.7 W - Enable Write to disk. Option W provides you with a means of reversing the effect of option R. Writing to the MSDOS file is enabled and the file attributes are permanently changed. The action is the same as the MSDOS command: ATTRIB -R filename 5.8 S - Set Port Number. Option S allows you to change the serial port address during a session. You will be prompted to enter the new COM port number (between 1 and 4) or type M if you have a non-standard PC and wish to set the port address manually. Typing 1 to 4 will cause the new port to be initialised immediately and return you to the main menu. Typing M will bring up a second prompt inviting you to type in the 4 digit hexadecimal address of the COM port. Only the digits 1 to 9 or A to F will be accepted. You must type all 4 digits so use leading zeroes if necessary. On the fourth digit the program will initialise the address and return to the main menu. 5.9 D - Display directory. The directory option is provided to allow you to look at the contents of the PC disk(s). The default filespec is preset in the emulator and is equivalent to 9 current directory:*.*. That is you will see all of the files in the current directory. Having pressed D a screen will appear that tells you what the current filespec is set to and inviting you to accept it with a carriage return or type in a new filespec. Once you have changed or accepted the filespec the screen will be replaced by a standard MSDOS directory listing satisfying that filespec. Press any key to return to the main menu once you have finished with the directory listing. The default filespec is one of the items which may be changed from the configuration file (see section 6). By adopting a standard convention for disk file extension naming (filename.DSK for example) and setting the filespec to only report files conforming to that extension ( *.DSK in this example) you can reduce the clutter on the screen and see only the available disk files. 5.10 Q - Quit Program. Pretty well self explanatory. Note that all files, including any print-through file, will be automatically closed when you quit. It is unnecessary to unload your disks before quitting. Always try to quit from the program rather than exit by any other means in order to maintain the integrity of your file data. 5.11 T - Toggle Line Status Display. At the bottom of the screen is the line status display. It shows the current (or last) command processed, the device ID for that command, the values of AUX2 and AUX1 in that command and the status of the command line (high or low). The information is provided to give you an insight into what is happening on the SIO bus. If you do not wish to see this display or your PC is having trouble keeping up with the ATARI then press T to toggle the display off. Subsequent presses of T will toggle the display on or off. 5.12 C - Create/Amend Configuration. Use this option to create or change the .CFG configuration files. For details see section 6. 5.13 P - Print Through Mode. The emulator will accept commands for the ATARI P: device (40h) if you enable the print through mode by pressing P. There are a number of questions to be answered in order to set the print through mode. First it will ask whether you want to print to the PC printer port (P), the screen (S) or a disk file (F). If you choose to print to a file then you will be asked for the MSDOS filename. This must follow the normal MSDOS naming rules. If the file already exists you will be asked whether you wish to overwrite it (O), in which case the file will be erased and then re-created, reselect the filename (R) which will take you back to the filename prompt to choose a different name, or append (A) 10 which will add the print output to the end of the existing file. Whatever the choice the question "DOS text conversion required" will then appear. If you select Y for yes then all the ATARI EOL character (9Bh) will be converted to the DOS carriage return, line feed sequence (0Dh,0Ah). In addition ATARI tabs (7Fh) will be changed to DOS tabs (09h) and the high bit which the ATARI uses for inverse characters will be stripped off. Other control codes will be allowed through and can have funny effects so be prepared. Selecting N for no at the conversion prompt causes the emulator to pass everything straight through to the chosen destination. It is unlikely that you will have any success in displaying or printing this output in the MSDOS environment but it is useful for copying machine code files to an MSDOS file. There are two further points to bear in mind when printing to the PC. The P for printer option will spool data to LPT1: so make sure that is where your printer is sitting. The control Z character (1Ah or 26 decimal) is used by the ATARI as a graphics character which is very useful as the bottom left hand corner of a box. In the MSDOS world it means end of file. Even with DOS text conversion turned on the control Z will appear in the MSDOS file. Subsequent attempts to use MSDOS commands like type, copy or print will stop when MSDOS encounters the control Z. The rest of the file will be on disk but you will have trouble finding it with an MSDOS command. With print-through enabled the main menu display will change to: Printing to (destination). Text conversion on (or off). where destination is either printer, screen or the filename. All print output will be directed to that destination until you press P again. The second P will close the destination device and disable the print through mode. While printing to the screen the display will remain on the printer output until you press any PC key. The main menu will then be restored. If you press a valid option key that option will be actioned. If this was not your intention then escape will cancel most of them. Hitting the space bar is probably the best way to return to the main menu without disruption, or use P if you also want to close the printer stream. 6. Configuration Files. Configuration files allow the pre-setting of many of the parameters which the emulator uses when it starts up. When a configuration file is used it is unnecessary to set the port number or load any disk files into drives. If you create a configuration files with the name of HDEMUL.CFG the emulator will find it and use the values within it whenever HDEMUL is typed to start the program. Creating lots of configuration files means you can start the emulator with the set of disk files most appropriate 11 to the task at hand. For example you might create a WP.CFG file for word processing, a MAC65.CFG file for assembler language programming with the MAC65 cartridge or a MYDOS45.CFG or SDOS32.CFG to enable you to boot under different DOS versions. Starting the emulator with the command HDEMUL MAC65 will automatically load your drives with all the files specified within the .CFG file. This can then taken one stage further by creating a MAC65.BAT file containing the HDEMUL MAC65 command which will get the whole thing going just by typing MAC65. In addition it is possible to fine tune some of the time out values, set the default directory filespec and determine whether the status line will be displayed. 6.1 Creating a Configuration File. Configuration files can be created by selecting option 'C' from the main menu. This takes you to a new menu screen with the configuration options displayed. Use the cursor up and down keys to move through the options and press the return key when you get to one that you want to alter. The display will initially show the current options in force on the emulator. 6.1.1 Set port address. Selecting this entry brings up the familiar prompt to select the port address (1-4) or M for manual. Selecting 1 to 4 will immediately insert the port number into the menu and return you to the menu level. M will cause the program to prompt for a 4 digit hexadecimal address which you should enter. Only digits 1 to 9 and A to F will be accepted. You must enter all 4 digits so use leading zeroes if necessary. 6.1.2 Load drives D1: - D8:. Selecting any of the lines from D1: to D8: will bring up a prompt to enter the disk filename that you want loaded onto the drive. Type in the file name and press Return. If the file does not exist the program will prompt with: File does not exist Continue anyway? Type Y if you intend to create the file later or N if you have made a mistake. The program does not check that the specified file is a valid disk file. If it is invalid the emulator will simply error the load when it is run with this configuration file and continue without loading anything. Similarly if you use a non-existent filename the emulator will ignore the entry next time it is run. To delete a file from the list select the drive and press return at the filename prompt. 6.1.3 Default Directory Specification. When you select the D option from the main menu the emulator will display a file specification which it 12 will use in the directory search. To alter the default value select this option and type the new file spec when prompted. 6.1.4 Time-outs. A number of time-outs exist within the emulator, most of which default to zero. The time-outs are used to at stages of the command sequence when it is possible for the PC to respond to the ATARI so quickly that the ATARI is not ready to accept the response. Various constant values are built in to the emulator already and the values given on the configuration menu are added to the in-built values to give a crude tuning facility if you happen to have a 'slow' ATARI. To appreciate the significance of the time-outs let us use the examples of the read sector and write sector commands from the ATARI: 1) Command line goes low and Read command is transmitted to the emulator. 2) Command line goes high and the emulator responds with ACK. No time-out is used within the emulator because this action is tied to the raising of the command line. 3) The ATARI now waits. The emulator prepares the sector data. Applies the TIME TO COMPLETE time-out and then sends COMPLETE to the ATARI. 4) The ATARI still waits. The emulator applies the SEND DATA TIMEOUT and then sends the sector contents. The sequence is now finished. Similarly on a Write sector command: 1) The ATARI lowers the Command line and sends the Write Sector command. 2) The ATARI raises the command line and the emulator respond with ACK using no timeout. 3) The ATARI sends the sector data and the PC applies the TIME TO ACK timeout before sending ACK again. 4) The emulator writes the sector and then applies the TIME TO COMPLETE timeout before sending COMPLETE to the ATARI. The sequence is now finished. The TXDATA TIMEOUT is applied between each byte of transmitted data on every PC to ATARI message. The effect of lengthening this is to slow down the message transmission rate by introducing pauses between each byte. The bit rate remains, of course, at 19.2K. 13 Because of the way that the low level PC timer works the values entered for the protocol time-outs actually give you 85*value microseconds of delay ie. 1 gives you 85 microseconds, 2 gives you 170 microseconds and so on. Given that the values that you will be entering are likely to be guesswork anyway I doubt that this will represent a serious impediment. The ERROR DISPLAY TIMEOUT determines how long emulator error messages remain on the screen. The value is in seconds and may be set between 1 and 59. To set any timeout, highlight it with the cursor up/down keys, select it with return and type in the new value when prompted. 6.1.4 Display Status Line. You may predetermine whether the status line is displayed by setting this value to Y for yes it is displayed or N for no it is not. It is preset to Yes. 6.1.5 Loading an existing configuration file. If you want to change the emulator settings from a configuration file without restarting the program or, if a configuration file already exists which is similar to the one that you wish to create, you can load an existing file by typing L. You will be prompted for the new filename which will then be loaded and its parameters will replace those on display. If you have changed anything on the displayed menu prior to loading the file you will be asked if you want to save your changes before the load over- writes them. The new parameters will not come into force until you exit the configuration menu. 6.1.6 Saving your changes. You may save your configuration file at any time by pressing S. You will then be prompted for the save filename. There is no need to add any extension to the filename, but if you do then make sure it is .CFG or you may forget its purpose. Remember that a file saved as HDEMUL.CFG will form the default load file provided it exists in the same directory as the emulator program. After saving the file you will be returned to the configuration menu. 6.1.7 Exit. It is necessary to type E for exit in order to return to the main menu. If you have made no changes since you entered the configuration menu, loaded a file or last saved then you will be given three choices: 14 1) Exit and use new parameters. Use this if you wish to invoke the configuration values which are currently displayed on the menu. 2) Exit. Returns to the emulator which will use the values it had before you entered the configuration menu. 3) Return to configuration menu. Cancels the exit routine. If you have unsaved changes on the screen when you exit there are 4 actions you may take: 1) Lose changes and exit. Choose this if you want to abandon your edits and return to the emulator to use the original values. 2) Save changes and exit. Use this if you want to save your edits but do not wish to use the new values when you return to the emulator. 3) Save changes, exit and use new parameters. Use this if you wish to save the edits and load the new values into the emulator for immediate use. 4) Return to configuration menu. This option cancels the exit routine. 7. Time and Date Support. HDEMUL provides a special interface which allows a program running on the ATARI to get the time of day and the date from the PC clock. The MYDOS450.DSK disk file contains a program called SDTIM.COM which may be run under SpartaDos to set the time and date for SpartaDos. By placing it in your start-up file it should provide an alternative to the RTIME8 cartridge. The details of the time/date interface follow for users who wish to write their own programs. Command from ATARI to PC: Command=52h (Read), Device=3Fh, AUX1=0, AUX2=0. This will return a 128 byte buffer with the following contents: Byte 0 Year (hundreds) e.g. 19 Byte 1 Year (tens) e.g. 92 Byte 2 Month (1-12) e.g. 1 = January. Byte 3 Day (1-31) Byte 4 Day (0=Sunday, e.g. 3=Wednesday 1=Monday) Byte 5 Hours (0-23) Byte 6 Minutes (0-59) Byte 7 Seconds (0-59) Byte 8 Hundredths of seconds (0-99) Byte 9-127 Unused. The file SDTIM.TXT on disk MYDOS.DSK is the source for SDTIM.COM and will give you an example of how the interface is used. 15 8.File Transfer Utilities. To enable the transfer of files between the MSDOS format and ATARI Dos format and vice versa a program called PCTFR.COM has been provided on the disk MYDOS.DSK. The program will run under any type of DOS so that you are not restricted in your choice of ATARI format. The program uses a special file transfer protocol built into the emulator and thus can only be used in conjunction with HDEMUL. The PCTFR.COM program was written with PL65 from NOAHSOFT and uses their run time routines. 8.1 The PCTFR program. Run the PCTFR.COM program from the run binary file option of you favourite ATARI DOS (option L for DOS 2.5). A menu will be displayed on your ATARI screen with the following options. A) Transfer file from PC B) Transfer file to PC C) Text Conversion D) List Atari Directory E) Exit to DOS Before you get stuck into transferring files you need to consider whether you require DOS text conversion. Without it the file will be transferred as is. This is the default and should be used for all binary file transfers (i.e. programs that run on the ATARI rather than text files). With text conversion turned on the following substitutions will be made: Transferring a file from the PC to the ATARI - MSDOS CR LF sequences will be converted to Atari EOL. Transferring a file from the ATARI to the PC - ATARI EOL converted to CR LF. ATARI TAB (127) becomes DOS TAB (09) ATARI control codes (ATASCII values < 31) become spaces (32) ATASCII inverse characters (>127) have the high bit stripped. This is a more severe translation than using the emulator Print to file option (with DOS text conversion) since all the Atari control characters are stripped out and replaced by spaces. To toggle the text translation option press C. The current status is denoted by Yes its on or No its not on after the menu entry. The rest of the program is hopefully self evident. Select A to transfer a file from the PC to the ATARI and give both filenames when asked. You may include a drive spec and path name in the PC filename if the file is not in the same directory as HDEMUL (eg A:\ATARI\DOWNLOAD\NEWGAME.ARC). The file will transfer 16 and report success or failure as appropriate. Option B will move a file from the ATARI to the PC. Again give both the ATARI and PC filenames when asked and sit back and hope while the data is transferred. Option D prompts you for an ATARI drive number and then gives you a directory listing of that drive. If you want to know what is on the PC use the emulator option D. Same command, different keyboard. Option E will return you to DOS. The most probable error messages will be translated to English and the rest will display the ATARI DOS error code for you to look up and correct. Transfers may be made from any combination of physical and emulated drives provided all transactions are via HDEMUL. Note that files will be overwritten without warning if you use an existing filename. The ATARI escape key will abort a transfer tidily if you change your mind after the process has started. I have not disabled break or reset but it would not be advisable to press either during a transfer unless you really want some practice unscrambling your disk. 8.2 The File Transfer Interface. A series of special commands have been included in the emulator to allow the file transfer mechanism to work. For the technically minded these, and the sequence which they must follow, are described below. Skip this section unless you have intentions to write your own file transfer program. All commands are sent with Device ID = 3Ah. This is what tells the emulator that it is a file transfer command. The commands are: Command: Status Aux1: 'I' Aux2: 'R' Initiates a read from PC sequence. PC transfer state must be idle. Response: Ack if OK otherwise Nack or Err. Command: Status Aux1: 'I' Aux2: 'W' Initiates a write to PC sequence. PC transfer state must be idle. Response: Ack if OK otherwise Nack or Err. 17 Command: Status Aux1: 'L' Aux2: 'R' Request for PC file length. Valid only after a "Write Filename" in a read sequence. Response: 4 byte status response containing 32 bit integer file length. Bytes 0 & 1 are most significant, bytes 2 & 3 least significant. Command: Status Aux1: 'A' Aux2: - Aborts transfer sequence, closes file and returns PC to idle state. Valid at anytime. Response: Ack if OK. Nack or Err otherwise. Command: Status Aux1: '?' Aux2: - Request for PC to send last error code. Response: 4 byte status response with error code in byte 0. Valid codes are: 250 File read failure. 251 Emulator transfer sequence error. 252 File write failure. 253 Unable to open file. 254 Incoming message not recognised. 255 General error (i.e failed to categorise failure) Command: Write Aux1: 'F' Aux2: - Followed by a 256 byte data buffer. Transmits the filename from or to which data is to be read or written so that the PC can open the file. The file name must obey normal MSDOS rules and must be terminated with an ATARI EOL (155) character. If the file is to be written to then any existing file of the same name will be lost. The file name may include a full directory and path specification. Valid only after an initiate message. Response: Ack, Nack or Err. Command: Write Aux1: 'D' Aux2: Byte count (0=256 bytes) Followed by a 256 byte buffer containing the number of valid bytes specified in Aux2. Data to be written to the PC file. Valid only after the filename has been received. Note that a partial buffer full of data does not lead to termination of the transfer. This must be done explicitly with a Status Abort message. Response: Ack, Nack or Err. Command: Read Aux1: - Aux2: - Request for next buffer full of file data. The emulator will return 256 bytes of data even if the end of file is reached before the buffer is filled. It is the ATARIs' 18 responsibility to keep track of the valid byte count. The transfer will not end when the end of file is reached. It must be explicitly terminated with a Status Abort message. Valid in a read sequence after Write Filename. Response: Ack followed by a 256 byte data buffer, Nack or Err. 9.Problems Obviously there are many different PC clones available and a wide variety of hardware set-ups available which makes it difficult to guarantee that the emulator will always work. If you experience problems here are a few suggestions which might help. If none of these work then try and contact me on the City BBS (021-321-1610 Username Peter). Please try to describe ALL of the events which led to the failure as the sequence may well be important. HDEMUL fails to run on the PC: Remove any TSR programs and try again. Check that the EXE program is not corrupt. Re-install it if in doubt. HDEMUL starts but keyboard does not respond: This sometimes happens if the PC generates a spurious character on the COM port when it starts up. The emulator thinks it is receiving a command and loops waiting for the rest of the command frame. Re-booting the PC should clear it. If your ATARI is attached then turn it on. The ATARI boot sequence will then send commands to the PC which will unblock the tubes. The ATARI does not boot when turned on: Have a look at the emulator status line. If you have contact with the ATARI you should see the display changing as the ATARI boots. If the display is empty then check the COM port setting. If this is OK then suspect your SIO2PC hardware. Try running the SIO2PC programs if you have them. If this works then there must be a major emulator fault. If SIO2PC does not work either then you have a hardware problem. ATARI hangs and then reports device not available: During the 'hang' period try getting the PC to respond to a Directory command. If the PC responds then it obviously thinks that it has completed the ATARI command and is actually hanging around waiting for some action. The most common cause of this problem is that the PC has serviced the command and responded before the ATARI was ready to process the response. Try slugging the emulator response by playing with the time-outs in the configuration menu. The Time to Complete value is a good one to have a go at. Be generous and use high values (in the thousands) until you have proved the problem and then come back down again to a more sensible value 19 when you are confident that you have located the problem. If the PC does not respond to your key press then it is waiting for data from the ATARI to complete the command sequence. This may be due to a poor connection causing line noise, a very slow PC which is failing to keep up with the incoming data or poor programming on my part. Try thumping the hardware and then the programmer. Command values are unusual when used with an enhanced drive. This is quite normal and represents the enhanced command set of the drive. Note also that the status line will not display sector values when used in conjunction with an ultra-speed SIO set-up. General If your PC is caching disk writes then you may experience some problems. The problems are not caused by the cache itself but by the fact that the PC nips off to empty the cache onto the physical disk from time to time. While it is doing this the scan loop of the emulator is interrupted and it is possible to loose a command line transition or data. Normally the ATARI command repeat sequence will take care of this but it is possible that, with a very slow disk, the problem could become more serious. If you have problems which occur at about the same frequency as the hard disk drive light flickers then try disabling the caching. Read caching should not cause any problems and will probably be beneficial. The use of a disk drive on the SIO chain with the same drive number as an active emulated drive will cause unpredictable results. Unload the drive in HDEMUL or turn off the physical drive. If the PC is turned on and in use but has not run HDEMUL or SIO2PC since it was last booted then there will be a problem accessing devices on the ATARI SIO line. The PC port must be initialised before the ATARI kit will work. Either run HDEMUL briefly or unplug the SIO2PC hardware from the SIO chain to regain control of the ATARI. I have fitted a little switch to my SIO2PC hardware so that I can turn it off and avoid this situation. 20