The MULTIPLEXER!
Version 1.1 04/05/90 By: Robert Puff
(C) Copyright 1990 by Computer Software Services
1350 Buffalo Rd. #2 Rochester, NY 14624
Telephone: (585) 429-5639
BBS Line: (585) 247-7157
INTRODUCTION
The MULTIPLEXER is the first readily-available product allowing Atari 8-bit computers to share disk drives and printers. It was inspired by the need of the author to test and debug BBS software: modifying it at the same time it was running. Since of course our computers are not equipped to truly multi-task, the idea of using two separate computers was entertained. But it required using a floppy drive for the programming system, and leaving the hard disk for the BBS. Since this was rather painful, especially when software needed to be updated on the hard disk, the MULTIPLEXER was developed.
The MULTIPLEXER (we'll call it MUX throughout this document) allows disk drives and printers to be shared by up to eight 'slave' machines. It does not multiplex serial data for a RS232 port, as this would require extensive processing time that would be impractical. The MUX also provides a PIPE area, where short packets of information may be exchanged between slaves. Many programming utilities are built-in to the MUX system, including a miniature ML monitor and disk & IOCB usage printouts.
The MUX accomplishes its task by redirecting low-level SIO calls to disk drives and printers to a Host, or Master computer. This host is a computer that is dedicated to maintaining the MUX network. It cannot run any user software; it must run the MASTER.COM program. Any disk drives or printers that are to be shared by the Slave computers (the slave computer is the one you will be using) should be hooked up to the host. Because most users will be using this to share hard disk(s), your hard disk host adapter (Black Box, MIO, or Supra interface) should be hooked up to the host computer. Because of this, you will need the host to be a 600XL, 800XL, or 130XE computer, since the others do not have a parallel bus connector.
Because the host has the hard disk connection, the slave machines do not need to be XL/XE units. In fact, any 8-bit may be used, as long as the MUX OS can be installed in it.
The MUX has certain tables maintained within the host that keep two slaves from wiping out a drive by writing to it at the same time. This unique 'locking' mechanism can be used for other applications as well.
HARDWARE DESCRIPTION
First, a description of a MUX system is on order. As already stated, there is one host computer that maintains the network. A 34 conductor cable runs from the host cartridge to all the slave cartridges. All slaves are connected in parallel with this cable. The cable length should not exceed 50 feet.
A MUX system is composed of one host unit, followed by one to eight slave units, all connected with 34 conductor ribbon cable. Every MUX board is capable of being either a slave or host unit; the strapping of the jumpers determines its function. Also, each slave unit must have its own ID. No order is necessary, just that each slave board have a unique ID. Once again, the ID is set by the jumpers.
The MUX boards plug into the cartridge port of the computer. If you desire to use a cartridge, simply plug it on top of the MUX board.
Each slave unit must also contain the MUX Operating System ROM. This has the necessary programs built in that redirect the computer's disk and printer operations through the MUX system. The host computer does NOT need a MUX ROM; it may stay "stock".
The MUX boards as shipped are labeled with either "MASTER" or "SLAVE" with the slave ID. Terminating resistor packs are installed in the host (master) unit, and in slave #2. Bear this in mind when reading this section, as you may need to change things around depending on your system. To change the jumpers or resistor packs, you will need to open the case of the unit.
The bottom four jumpers (J5-J8 in the picture below) determine whether the MUX board will function as a slave or host. They will be installed straight across for the slave boards, but criss-crossed for the host board.
The MUX boards located at the ends of the cable should have termination resistor packs installed in them. There is a socket just below the 34 pin connector on the MUX board for this resistor pack. Since the host board should be located on one of the cable ends (not in the middle), a resistor pack should be installed in it.
The board is supplied with a 16 pin socket so that 14 or 16 pin resistor packs may be used. Most likely you have been supplied with 14 pin parts, in which case the top two holes of the socket should be left open. The orientation of the resistor pack IS critical: it should be with the notch on the top end. The resistor packs used are 220/330 ohm dual in-line packages.
Each MUX slave board should have a unique ID. The ID is set by the top three jumpers as follows:
INSTALLATION - PART I
First, decide which computer you are going to use for your Host computer, and set it aside. No modifications need to be done to it. All the slave units need to be upgraded with the MUX OS ROM. This ROM is designed so that with the MUX board removed, it will act like the standard OS. It may not run software that checks for special operating systems, though. Typically these are protected games, but they are far and few between. If you do have a unit you want to be sure will run 100% of the software it ran before, call us. We can provide an OS selection switch for XL/XE computers. For the 400/800 computers, this is really not possible. But running a MUX system means you will most likely be running application software, not running protected games. And remember, since the Host computer will remain "stock", you could temporarily shut down the MUX system and run whatever program you desired on the host machine.
Before actually performing the installation, read through the rest of this document. You may want to install the Monitor button and/or MUX disable switch in one or more of your slaves. The Monitor button is a momentary Normally Open (NO) push switch that allows you to pop into the monitor at any time. The MUX disable switch is a simple SPST toggle switch that disables the MUX redirection, and makes the computer act like a stock machine. If you plan on using a slave as a stock computer often, you may want to install this switch so you won't have to keep removing the MUX cartridge.
Follow the installation instructions below for installing the MUX OS into each slave computer. If you already have a modified operating system installed in a computer you will be using as a slave, it will be replaced, as modified operating systems will not talk to the MUX. When you are finished, proceed to "INSTALLATION - PART II".
Some XL and all XE computers do not have a socketed OS chip. This means this chip must be desoldered from the circuit board. This requires a desoldering tool, and should not be attempted if you've never done it before. It is very easy to rip up traces, rendering the computer dead. Installation of the MUX on 400/800 machines is a bit involved, also. Usually there is at least one person in an Atari user group having the technical expertise to install this upgrade. However, Computer Software Services will install the MUX OS free! Just give us a call.
After installing the OS and any switches, power up your computer with no cartridges or peripherals connected. If you do not see the familiar blue screen, re-check your work. If you're really stuck, give us a call.
Installation for 65/130XE Computers
Installation for 600XL/800XL Computers
Installation for 1200XL Computers
Unfortunately, Atari used many different types of parts in the 1200XLs. It is necessary to add another chip to use one OS ROM instead of the two used. See the addendum for details on the 1200XL installation.
Installation for 400/800 Computers
Installation of the MUX OS is not possible in 400/800 computers. Please use an XL or XE computer.
INSTALLATION - PART II
Now place your computers where you desire them, and insert the proper MUX boards into their cartridge ports. Remember the order is not important, but the type of board (host or slave) does matter. Since the host computer is only booted once, you may want to place it on a shelf or other place that is not as accessible, to make room for the slave computers.
If the cable supplied with your system is sufficient, use it. Otherwise, you may construct your own cable. 34 pin ribbon cable and 34 pin crimp-on header connectors can be found at any Radio Shack store. When making up your own cable, measure the distance between each slave, and add a few feet. Be sure you crimp the connectors on to the same side of the cable, lining up pin 1 of the cable (usually a different color) with the marking on the connector. If you need to extend your cable length, it is HIGHLY recommended that you get another whole cable of the length needed, as splicing 34 wires can be very messy. Remember you can crimp on a connector anywhere on the cable.
Now connect the MUX cable to all the MUX boards. Remember to make sure the connector is inserted the proper way - pin 1 on the left side, looking in to the connector. This port is on the rear of the MUX board, so the board will have to be removed from XE computers when connecting the cable. Also remember the termination rule: the resistor packs should be installed on the MUX boards at both ENDS of the cable, NOT in the middle.
Now boot up DOS on the computer you have designated as the host. Copy the MASTER.COM and MUX.COM files on to your drive 1, if it is a hard disk partition (recommended). If you will be using SpartaDOS with your system, you need to use the SpartaDOS patcher program. If you are not using Sparta, skip the next two paragraphs.
SpartaDOS is one of the few DOSes that does not call the ROM vectors for talking to disk drives. Instead, it uses its own routines, with no provision for anything else. Because the MUX OS has the proper SIO handler to know how to talk to the host, it must be called. We have provided a patch program for SpartaDOS version 3.2D. Version 1.1 (not the HS version) is the only version that will run as-is. Other versions of SpartaDOS cannot be patched; version 3.2d can be obtained from ICD, Inc.
To make the patch, copy the file SPARTPAT.COM from the MUX disk to a drive that contains the file X32D.DOS in the root directory. Now run the patch program FROM THE DRIVE X32D.DOS resides. It will do its thing, and rename the new DOS to X32Z.DOS. Now copy this DOS file to any drives you boot from, and use the BOOT command on it. This patch replaces the high speed code with a routine that calls the standard OS, so you will lose the high speed capability, but gain the ability to use the MUX. If you have a floppy drive on the MUX, it will be accessed in high speed anyway. Also, the keyboard buffer defaults to OFF, instead of the usual ON. To turn it back on, simply type "KEY ON" at the command processor prompt.
Now binary load the file MASTER.COM. No cartridges should be in the host except the MUX host board. For this reason, there is no cartridge port on the host cartridge. You should see a four line display on your screen. This is the host's display of what it is doing; all the items will be discussed later.
Notice the Error Count field on the bottom line. If this is changing, check your MUX cable. It is probably inserted backwards in one or more of the boards.
Now turn on one of the slave computers. You should hear the beeps the MUX OS makes whenever it accesses the host. DOS should boot, coming from drive 1 on your host. If the screen is totally black, make sure the MUX board is inserted all the way into the cartridge port. If you see a blue screen but nothing happens (no sound), the MUX board is not connected to the MUX cable properly. Go through all your slaves and make sure they boot properly.
USING THE MUX
By default, all of the disk drives accessed on the slave computers will access the corresponding drive on the host. But all this may be changed. On a XL or XE slave, hold START while hitting RESET. On other machines, use your DOS to binary load the file MUX.COM. (MUX.COM is built-in to the ROM in place of the self-test code for the XL and XE computers.)
You will now see a whole series drive parameters, and miscellaneous parameters on the bottom. The drive configuration allows you to redefine drives, make them 'host' or 'slave', and write-protect them. There is an entry for all nine possible drives, plus the printer "P1:". Use the cursor arrows to move the cursor around to the desired item, then press [RETURN] to change it.
Refer to the sample screen below (or better yet, play with this on one of the slaves) while reading through this section.
In the Drive Configuration, the first parameter is the location of the drive. This defaults to "Host", but may be changed to "Slav", representing the slave. If for example you have a floppy drive #1 connected to the slave computer, you could set drive 2 to use slave drive #1. Now whenever drive 2 is accessed, it will look for a drive connected to the slave itself, not the host. Drive numbers can also be redefined on the host. You could set drive 3 to access drive 7 on the host. Remember that drives on a slave can only be accessed by that slave, but drives on the host can be accessed by any slave. When changing the drive number field, you may either keep pressing [RETURN] until the desired drive number appears, or simply type the number.
Drives can also be write-protected by the MUX. This even extends to local drives on the slave. Any PUT SECTOR or FORMAT commands will return an error #144 if the protect flag is set. Pressing [P] will change the protect status of all the drives, toggling between on and off.
The printer may be redefined to be any device number on the slave or on the host. Strangely enough, different printers respond to other IDs than P1:. A little experimentation is necessary, but you can have more than one printer hooked up to the SIO port. The protect flag for the printer is meaningless.
Sample MUX Menu Screen
Upon initially entering the menu, your slave ID will be displayed on the top of the screen. However, you may edit the configuration of any other slave. Press [N] to cycle through the slave numbers. A "*" will appear next to the "Editing Slave: x" line, alerting you to the fact that you are altering something other than the slave you are currently using.
The UPDATE MODE LOCK toggle in the bottom window is a special flag for SpartaDOS users. Normally when a disk file is opened for update, only the data in the file is affected, but the file length is not expanded. However, SpartaDOS does not follow this rule. Since the MUX needs to keep track of when a file is opened for output (which is explained below), it needs to know how to handle an open for update. Bottom line: Sparta users should set this flag to YES, all others should leave it OFF.
Once you establish the configuration you desire for each slave, type [S] to save the config. This will write a small file to drive 1 on the host called MUX.CFG. This will be read whenever the host is booted. Note that when you save the config, it saves whatever you have set for ALL slaves, not just the one you are using. Use the [L] command (load config) to get back to what you have stored, in case you played around quite a bit.
The Error count is a counter kept in the host. It increments every time a error is detected on the MUX bus. Errors are caused by stray RF and glitches picked up in the relatively long length of cable. All errors are retried up to 4 times, so the likelihood of a bus error actually causing a real error on the slave is very slim. If you see that errors are happening very frequently (i.e., more than a dozen an hour), inspect your mux cable. Re-seat the MUX boards into their computers. Also make sure the terminating resistor packs are installed in the proper places (in the MUX boards that are at the two ends of the MUX cable).
The Flags parameter is used more for programming, but can be useful in tracking down the source of MUX host errors. Pressing [RETURN] when the cursor is on this field will cause it to cycle through the eight possible combinations of the three flags: P, E, and D. The P flag is a debugging tool that will print a message to printer #1 on the host whenever a slave does any OPENs, CLOSEs, or XIOs involving the D: Disk device. The E flag, if enabled, will print to printer 1 on the host the slave number and type of MUX error that happened. This may be useful when trying to locate a possible bad slave. The D flag is another debugging tool that will print out every sector I/O operation of every slave, the sector number, and the status of the operation. This flag and the P flag should be used with caution, as normal computer operation could leave you with SEVERAL pages of paper behind your printer!
The Locked Drives line will display any drive numbers that are currently 'locked' from a slave. Any drive number that is locked on the slave you are currently using will be displayed in inverse. An explanation of the host locking logic is in order here.
One of the main situations to be dealt with in a multi-user environment is what will happen if two computers attempt to write to the same drive (partition). There is no problem if one computer is reading the same drive at the same time as one is writing, but if two are writing, they will be writing on top of each other, rendering both files useless. The MUX solves this dilemma by intercepting all OPEN calls to the disk device. If it sees that you will be writing to a drive, it puts a lock on that drive, so that the only slave that can write to that drive now is the one that opened the file. Others can read from the same disk, but if they attempt to write, an error 201 will be generated (or a timeout can be set, see the technical notes). Whenever the slave finishes writing and closes the file, the lock is removed. Note that locking is done at the CIO level, NOT SIO. Note that the MUX gets the drive number from the character immediately following the "D" in the filename, so "D:" is interpreted as drive 1.
On the host screen, the third status line displays the locks. It will put the slave number next to the drive that slave is locking, and erase it when it is done. On the MUX menu, only the drive numbers that are locked are displayed. If a drive is locked on the current slave config you are viewing, the drive number will be displayed in inverse video.
It is rare, but occasionally a programming error in a program running on a slave will cause a lock to stay on, even after the file has been closed. If this situation happens, there are two ways to clear the lock. One is to hit RESET on the slave that caused the lock. The second is to use the MUX menu, moving the cursor bar to RESET Errors and Locks, and hitting RETURN. This last function will also reset the error counter to 0. Remember, do this only when you are very sure that the lock is stuck on. Some programs will keep a file open as long as you are running the application, and the lock should remain on in these cases, to prevent any other slaves from writing to the same drive.
Note that this locking pertains to the drive numbers on the host, not necessarily one physical drive. For example, if you have a large hard disk split up into three partitions, you may write to partitions 2 and 3 even if partition 1 is locked. BBS Sysops may want to have upload areas on all partitions, so that if a partition is locked by one slave, a uploader can still send his file up, having it go to the second partition.
The Monitor toggle is a machine language debugging tool. If this is set to YES, the monitor will be entered anytime the processor hits a BRK instruction ($00). See "USING THE MONITOR" for details on operation. The monitor may also be entered from the MUX menu by pressing [CONTROL] [M].
ENHANCEMENTS IN THE MUX OS
The MUX OS installed in the slaves is based on the XL/XE OS. So those using a 400 or 800 will gain the functions of the new OS, plus the extra features the MUX OS affords. The international character set is not included, as the code necessary for the MUX took priority. All other functions of the XL/XE OS are present.
HELP + RESET or SHIFT ESC + RESET: Reboot. This will allow you to reboot the computer; that is, it will act just as if it were turned off, then back on. But since you have not lost power, any data in extra memory (above the 48k) will be retained. Thus if you have a 256k 800XL for example, you can always reboot (keeping your RAMdisk intact) even if the machine locks up by pressing HELP and RESET. SHIFT ESC was provided for 400/800 users, who do not have a help key. Note that hitting RESET will reboot if the last keypress was either HELP or SHIFT ESC; the RESET button does not clear the keyboard register. So after rebooting, press some other key if you want a subsequent RESET to simply warmstart. This method of coldstarting also will turn on any OSS SuperCartridges that were turned off.
SHIFT CONTROL 7: Noisy I/O flag. The sound you hear whenever accessing any serial device or drive on the MUX may be disabled by pressing these keys. Do it again, and the sound will be re-enabled. This sound flag defaults to ON.
SHIFT CONTROL 8: Toggle Screen DMA. It is well-known that turning the screen off will speed up program execution by 10-40%. You can temporarily turn the screen off by pressing these keys. The screen may be restored by pressing any other key (SHIFT CONTROL A is recommended, since this produces no key character).
CONTROL 8: Keyboard Lock. By pressing these two keys, the keyboard input (except the Start, Select, Option, and Reset keys) will be disabled. This is useful to prevent mischief if you need to leave the room for a little while. Press CONTROL 8 to enable the keyboard again.
CONTROL 9: Toggle Key Click. The clicking sound you hear whenever a key is pressed may be disabled with this key combination. Press it again, and it will be re-enabled. This defaults to ON.
The keyboard repeat rate (the rate at which a letter is repeated if you hold it down) has been increased. Also the default screen colors have been slightly enhanced to provide better contrast for text screens. The "BOOT ERROR" message has been replaced by "LINK ERROR".
Any I/O through the MUX will be accompanied by sound. The MUX OS produces a low tone for reads, and a high tone for writes. Now hard disk I/O can be heard! This may be disabled by the SHIFT CONTROL 7 toggle.
The self-test routines have been replaced with the MUX.COM configuration editor program, allowing easy access to the MUX config. If you are using a 400 or 800, this is not available. Instead, you will be given a MEMO PAD mode, just like the 400/800 OS. Note that if you are using a memory upgrade in a XL/XE computer that redefines the use of bit 7 of PORTB, the MUX OS will still work; but you will not have access to the built-in MUX menu.
You may enter the MUX menu by holding START while hitting RESET. Press [ESC] to exit back to your program. Note that if you have just come from a coldstart (caused by holding HELP as well), you will hear a beep upon exiting. This is from the Cassette Boot code (what you get in the standard OS if you hold down START while powering on). Simply press RESET again.
The MUX OS also contains a tiny machine language monitor program. See the section entitled "USING THE MONITOR" for details on its operation.
FEATURES IN THE HOST
The MASTER.COM program that is run on the host provides several fields of information on its display, plus a few features. The second status line displays four items: the Activity indicator, the last slave number that accessed the host, the last drive number (on the host) accessed, and the last pipe number accessed (in hexadecimal format). The activity indicator is composed of two characters. The first continually cycles through all the Atari characters, letting you know the system is running. Right next to that, a "*" character will appear whenever the host is being accessed.
The next line displays the lock status of the nine drives on the host. If any slave has opened a file for writing to a drive on the host, that slave number will be displayed next to the drive number being accessed by that slave. The slave number will disappear once the file is closed. Note that this is similar to the "Locked Drives" entry in the MUX menu. The difference is that on the host display, you can see immediately who is locking a drive; from the menu, you only see that a drive is locked, and if it is the current slave that owns the lock.
The third line contains the error message display and counter. There are two types of errors that occur in the communications between the host and the slaves: Checksum errors and Timeout errors. Both are generally caused by noise induced in the MUX cable, since this cable is quite long and unshielded. The slave will retry all errors up to four times in a row, so under normal situations, a burst of noise on the bus should never cause an error message to actually be returned by the slave. However, termination problems (having the terminating resistor packs lacking, installed in the wrong places, or installed up-side-down) and bad cable-to-connector junctions can cause many or constant errors, especially if they usually are related to one slave. As stated before, a dozen or so errors per day is acceptable; but if you see this counter increasing rapidly over a five minute period, it's time to find the cause. The MUX cable should not be curled or wound up at any place.
The debugging flags P, E, and D (described in the menu operation) may also be toggled on the host. Simply press the letter corresponding to the appropriate flag to turn it on or off. The status of the flags will be shown on the right side of the second status line.
The error counter and drive locks may all be cleared by pressing the SPACE BAR on the host. This is the same thing as the "RESET Errors and Locks" function of the MUX menu.
To terminate the host program, press RESET. Remember though that the slave computers will not perform any I/O if the host goes down; so for most applications, the host should be booted first, then left on.
That's all you need to know for normal use. The rest of this manual covers how special functions of the MUX can be accessed through software.
USING THE PIPE AREA
The MUX OS contains a built-in handler used to access the Pipes and other special functions of the host. It is called the 'pipe area' because it is through this that little packets of information may be channeled to the slaves.
The pipes are accessed through the M: device via CIO. The way they are accessed is as follows: an IOCB is opened for read/write to the M: device, an XIO is performed to set the packet number desired, and then data is read or written. When finished, the IOCB is closed. It may remain open for as long as you wish.
This section will list all of the calls to the M: device in Atari BASIC format. If you are using another language, refer to its manual for proper syntax.
Opening the Port
Syntax: OPEN #Channel,12,0,"M:"
Sample: OPEN #2,12,0,"M:"
This command opens an IOCB for access to the MUX M: handler. This must be done prior to doing anything with the pipe area. Note that input and output are specified. CHANNEL is any free IOCB, 1-7.
Closing the Port
Syntax: CLOSE #Channel
Sample: CLOSE #2
This closes the IOCB used for the M: handler. Note that a CLOSE does NOT 'purge' or store pending data to be written; a XIO 18 must be used prior to the Close.
Statusing the Port
Syntax: STATUS #Channel,Node
Sample: STATUS #2,X
The Status command performs two functions: it places into memory location 747 ($02EB) the number of bytes to be read in the packet specified by the last XIO, and it returns in the error code the slave number. The slave number will be a value between 1 and 8, established by the jumper configuration of the slave board plugged into the machine. The value in location 747 will be a 0 if there is no data in the packet, else it will be the number of bytes (including CR characters) in the packet. If you status a wraparound pipe, it will return the number of bytes in the next text line, but there may be more after that.
Setting the Packet Number
Syntax: XIO Packet_num,#Channel,0,Text_flag,"M:"
Sample: XIO 20,#2,0,128,"M:"
The XIO command is used to identify the pipe (packet) desired. There are two types of pipes available: 127 byte packets, and 1024 byte wraparound buffers. Packet numbers 20-27 are the eight 1k wraparound buffers, and 28-147 are the 120 small 127 byte packets.
The Text_flag parameter in the AUX2 byte informs the handler if you will be writing a text string or other data. If you will be using text strings with a RETURN character (#155, $9B) at the end, then set this parameter to 128. If you will be storing data in a pipe that may have RETURN characters in it, then set this parameter to 0, and use the FLUSH BUFFER command when you are finished writing data to the packet. Remember that the wraparound pipes must be text data terminated with a RETURN.
Flushing the Buffer
Syntax: XIO 18,#Channel,0,0,"M:"
Sample: XIO 18,#2,0,0,"M:"
This command is used for two functions: declaring an "End-of-File" after writing binary data to a 127 byte pipe, or purging a pipe (setting the number of bytes in it to 0). First, a little explanation.
When writing data to a packet, the M: device handles data one byte at a time. When it is in text mode, it waits till it receives a RETURN character, at which point it sends its buffer to the host. But in binary mode, it has no way of knowing when you are finished writing data. Here's where the Flush Buffer command comes in. It will cause the handler to send whatever is in its buffer to the host.
A feature generated by this function is the ability to clear out a packet (127 byte or wraparound). To do this, set the packet number desired (with an XIO), then perform this XIO 18.
Reading and Writing to the Pipes
You may use the GET, PUT, PRINT, and INPUT commands to read and write data in the pipes. Remember that INPUT will only work with text strings terminated with a RETURN, so it is easily used for the wraparound buffers.
When reading a pipe, this is the general format:
When writing a text string to a pipe, this is the format:
When writing a non-text string, use this format:
In the 127 byte pipes, data written will remain in there until another write is done, or the pipe is flushed. The wraparound pipes are different, however. Data written will be placed into a 1024 byte First-In-First-Out
(FIFO) buffer; it will be 'stacked up'. Successive reads of the packet will return the oldest data first. Only one line will be returned per XIO and read. If the buffer fills, the oldest string will be overwritten.
Miscellaneous Functions
Syntax: XIO Function,#Channel,0,0,"M:"
Sample: XIO 151,#2,0,0,"M:"
This is how some of the functions of the MUX menu can be performed. Here's a table of the functions possible:
The format for executing functions #149-179 is:
The procedure for testing the lock flags is as follows:
So to check to see if drive 3 was locked, you would look at the fourth byte of the table (buffer address+3). If it contained a 0, then the drive is free. If not, the number will be the slave number locking it. You may also see the IOCB number(s) used on the slave doing the writing. Each bit in the table of bytes 17-25 represents an IOCB, bit 0 meaning IOCB 0. If you lock a drive by using XIOs 171-179, they will show up here as using IOCB #0.
Be very careful when using the lock feature. If the lock is not turned off, it will prevent other slaves from writing to that drive till you reset it. That is why the ability to reset the host is present on the slave MUX utility.
Error Codes from the M: Handler
Number (hex) Meaning
1-8 $01-$08 Good status; the error number returned after a STATUS command is the slave ID number.
128 $80 Break Key was pressed in the middle of I/O.
129 $81 IOCB already open. IOCB was not closed, or is in use.
130 $82 Handler not found. A call to the M: device was made while the MUX was disabled or the MUX board was not plugged in.
136 $88 End of data. There is no more data to be read.
137 $89 Truncated Record: more than 127 bytes have been written to a pipe. The pipe will NOT be written unless a Flush Buffer command is executed.
138 $8A Multiplexer not responding. Make sure the MUX cartridge is fully inserted into the cart port.
200 $C8 MUX Host timeout. This could be caused by a bad MUX cable, improper termination, or a defective slave board.
202 $CA Slave connection timeout. See above error 200.
203 $CB MUX Checksum error. See above error 200.
USING THE MONITOR
The MUX OS has a built-in mini monitor program. This monitor is limited in features, yet can be a very useful debugging tool.
There are three ways the monitor may be entered: by pressing the momentary button described in the installations (this is optional), by the processor executing a BRK instruction if the monitor is enabled in the MUX menu, and by pressing [CONTROL] and [M] while in the MUX menu.
Once in the monitor, the top data line displays all the CPU registers prior to entering the menu. The bottom data line displays an address, the eight bytes in hexadecimal format starting at that location, and the ATASCII characters for those bytes. It initially sets the address of the data window to be that of the program counter, but this can be changed. Pressing the SELECT key will scroll up in memory; pressing OPTION will scroll down. Prior to scrolling, hit [RETURN] for fast scroll, or the SPACE BAR for slow scroll. The idea is to use the fast scroll to get roughly to the address desired, then hit the SPACE BAR to slow it down. In slow scroll mode, holding down START while pressing OPTION or SELECT will cause the address to scroll by 1 page instead of 8 bytes.
When the address is scrolled, the lower nybble will always be either a zero or an eight. This simplifies calculating the exact address of a byte on the screen. If the address ends with a zero, replace the last hex digit of the address with the first number of the two digit number above the byte. If it ends with an eight, replace the last digit with the second number above it.
There are two ways of exiting the monitor. If you entered with the hardware switch, then hold [SHIFT] and press [HELP]. If you entered via a BRK instruction, use [SHIFT] and the SPACE BAR. When you exit with [SHIFT] and [HELP], it returns from the interrupt directly. But when you return with [SHIFT] SPACE BAR, it jumps through the break vector, which usually points to a RTI instruction anyway. You may however find a few programs which actually make use of the BRK instruction, thus the need to disable the BRK entry. Also, debugging utility programs may not appreciate having the BRK vector stolen, so it is best not to have this enabled when running debugging programs.
PROGRAMMING NOTES
Whenever a disk file is opened for write, the MUX first checks with the host to see if the drive is locked by another slave. If it is free, then it locks the drive, and continues. If the drive was locked, its action will be based on the contents of memory location 719 ($02CF). If this location is zero, it will return an error #201 ($C9) immediately from the OPEN call. If it is non-zero, it will wait for a period of time specified by the value of this location for the drive to become unlocked. If it does become unlocked within the time period, everything proceeds as normal. Otherwise, the error 201 will be returned after the delay. The timeout period specified in this location is measured in units of 4.25 seconds; so for a one minute timeout, a value of 14 would be used. This location is initialized to zero upon system initialization and each RESET.
The wraparound pipes were designed specifically for a multi-user chat function. The 127 byte pipes can be used to hold the user names, while the wraparound pipes are used for the actual chat data. When using the pipe area for such a function, it is recommended to assign certain groups of pipes to each slave. The easiest way to do this is by grouping the pipes together in groups of eight, since there are eight possible slaves. In the sample chat program below, the user name is held in pipes 28-35, and their location in pipes 36-43. Now since we can find the current slave number we're on (using the STATUS command), just add that value (minus 1, since it ranges from 1-8) into an offset number for the desired group, and you now have the pipe number desired. This way the same program can be run on all machines, without having to be customized for each slave.
The following is a sample program to demonstrate how a multi-user chat routine may be done. It is not the only possible way, but probably the easiest. No claims are made to the elegance of this sample! It is in Atari BASIC. In a typical BBS application, the name and location pipes would be updated as the user moved to various areas of the board.
Many enhancements could be made to this program, such as 'private sends' to users, and using a get loop from the keyboard instead of an input.
POSSIBLE ERRORS WHEN USING THE MUX
There are four new error codes that may be generated from the MUX. These will be returned from the SIO routine, so you may see them as DOS errors.
Error 200 ($C8) - MUX Timeout. This error should not occur under normal circumstances. If you do get this error, check your MUX cable. Probably there is a problem with the handshake lines (pins 22-30).
Error 201 ($C9) - Drive locked. The drive to which you were about to write is being written to by another slave. Wait a little while, and retry the command. If no other slaves are writing, perhaps a programming error caused the lock to 'stick on'. In this case, use the 'RESET Errors and Locks' command on the MUX menu or host.
Error 202 ($CA) - Slave could not connect to host. This error is caused by another slave doing some function to tie up the host for more than one minute solid. Formatting a high capacity floppy is an example. If it ever happens, check to see if one of the slaves is indeed formatting a floppy, or perhaps the host is glitched.
Error 203 ($CB) - Checksum Error. This indicates a problem with the MUX cable in the data lines (pins 1-18). If the problem is evident on all slaves, then there is a short in the MUX cable.