The Modem Manager ref. file ModemManagerToolSet.zip After downloading, unzip using WinZIP or a similar utility. Resulting file is MODEMMGR.SHK After transferring MODEMMGR.SHK to your Apple IIgs, unShrink using GS.ShrinkIt ("GSHK", "ShrinkIt.GS", ...). ============================================================ The Modem Manager A telecommunications Tool Set for the Apple //gs Copyright 1990, Jawaid Bazyar April 23, 1990 ============================================================ Permission is given to freely distribute, as long as the original Shrinkit file maintains intact. This contains the follwing files: TOOL.MM A TOL file containing Modem Manager MODEMMGR.DOC This file MODEMMGR.H C Header file (ORCA/C) MODEMMGR.MAC ORCA/APW Assembler macro file SAMPLE.C C sample program (ORCA/C) The C files will work under APW, but the language type must be changed using the CHANGE command. (APW users see the comment in the SAMPLE.C file about portability.) The Modem Manager (hereafter referred to as MM) is an Apple //gs Tool Set that handles common communications tasks, considerably simplifying the design of communications programs. MM is configured as a user tool set, i.e. the user program is responsible for loading the tool and installing it in the system. Fortunately, this is a simple task and sample source code and interface files are provided to help those using MM. MM's design is based around Channels, an abstract construct representing a means of data input/output. Theoretically channels can be serial ports, ethernet ports, pipes to other processes, and just about any conceivable I/O method. Right now, however, only the modem port on the Apple //gs is supported, and the channel specification is ignored. For practical use, however, channel number 2 should be used. The implementation of MM is likely to be somewhat volatile in the next few months, so take care to use only the provided interfaces. Otherwise, incompatibility may exist when MM is updated for full channel support. Even with these current limitations, MM is a very useful tool. Following is a description of the programmer interface to the MM. Note that the calls are described using C function declaration syntax. However, these calls can be used equally well from C and assembly- a C *.h header file and an assembler MACRO file are provided. A Pascal interface is not provided, as I have no experience with the Pascal tool interfaces. If anyone develops interface files for TML II and/or ORCA Pascal, please send them to me so I can make MM a more complete product. ============================================================================== void ModemMBootInit(void) ModemMBootInit should never be called by an application. It is called by the Tool Locator when MM is installed. ============================================================================== void ModemMStartUp(dPageAddr) word dPageAddr; This call must be made before any other MM calls are made. Performs some miscellaneous initializations (initializes the timer code). The only input needed is the address of a 256 byte direct page in bank zero, which must be obtained thru the memory manager (see sample source code). Errors: none ============================================================================== void ModemMShutDown(void) This must be called before your program exits. It cleans up after itself (removes timer code from Heartbeat queue), and input: none output: none errors: none ============================================================================== word ModemMVersion(void) Returns the current version number assigned to this copy of MM. See the Toolbox Reference Manual for a description of the version number. input: none output: version number (word) errors: none ============================================================================== void ModemMReset(void) This currently does nothing, as there is nothing that would need to be reset. ============================================================================== word ModemMStatus(void) Returns the status of ModemMgr (whether it is started up or not) input: none output: status (word) 1 = active, 0 = inactive errors: none ============================================================================== void DisableModem(channelID) int channelID; Performs a shutdown of the firmware controlling this particular channel. input: channelID (word) output: none errors: none ============================================================================== void InitModem(channelID) int channelID; Initializes Channel n for use. Channel 2 is the GS modem port. Future versions will support other modem types and more channels may or may not be present on a particular system. input: channelID (word) output: none errors: none ============================================================================== void SetDTR(channelID,status) int channelID; int status; Turns the Data Terminal Ready signal on or off depending on the value of _status_. input: channelID : channel to set status : Status = 1, DTR on, status = 0, DTR off output: none errors: none ============================================================================== int GetByte(channelID,timeout) int channelID; int timeout; Waits timeout/10 seconds for a character to arrive from the specified channel. If none arrives within that time, a -1 is returned. This code is re-entrant. This call modifies the channel checksum if activated. input: channelID : channel to get char from timeout : time to wait for char, in tenths of seconds output: -1 if no character arrived before timeout, otherwise a character errors: none ============================================================================== void SendByte(ch,channelID) byte ch; int channelID; Sends the specified character out thru the channel. This call modifies the channel checksum if activated. ============================================================================== void WrStr2Modem(str,channel) char *str; int channel; Sends the contents of a C-string to the channel. A C-string is ascii text ended by a hex value $00. ============================================================================== void Pause(tenths) unsigned tenths; Waits for the specified amount of time to pass, then returns. This is a very accurate delay. ============================================================================== void PushBackChar(ch,channelID) int ch; int channelID; int WaitForChar(channelID); int channelID; /* returns a character from the specified channel */ WaitForChar is similar to GetByte, except it will wait until a character comes, with no time limit. If no character comes, WaitForChar will not return, causing the machine to "hang". PushBackChar places a character back in the input stream, so that the next call to WaitForChar will return that character. This is similar to C's ungetchar routine. These functions are provided primarily for those writing terminal emulations. They come in handy when parsing terminal ESCape commands and the like. ============================================================================== void SendBytes(loc,size,channel) byte *loc; unsigned size; int channel; Sends a block of data thru the channel. A pointer to the block and the size of the block (word) are passed to the function. Using this routine instead of using SendByte to send each individual character greatly increases performance at high baud rates because of the somewhat high overhead experienced using tool calls. This call modifies the channel checksum if activated. ============================================================================== int GetBytes(loc,size,timeout,channel) byte *loc; unsigned size; unsigned timeout; channelID channel; Gets _size_ bytes from the _channel_, storing them sequentially at a memory block pointed to by _loc_. The timeout is specified in tenths of seconds, and it is the maximum amount of time GetBytes will wait for each character before returning a timeout error. If a timeout occurs, the number of bytes received before the timeout will be returned. If no timeout occurs, the number of bytes requested (size) will be returned. ============================================================================== void FlushInput(channel) Clears the input buffer of any characters that have not yet been read. ============================================================================== int SCCInput(cp, channel) char *cp; int channel; SCCInput is a variation of GetChar and WaitForChar. It checks to see if a character is available from the modem. If one is, that character is read and stored in the location pointed to by _cp_, and a 1 is returned as the result of SCCInput. If no character is available, SCCInput returns immediately with a 0. This function is designed for programming an event-driven loop. ============================================================================== int SetBaud(bRate, channel) int bRate; int channel; Sets the baud rate of the specified channel. bRate is an integer between 0 and 15. The codes and their real rates are listed below. 0 Default (as set in control panel) 1 50 6 300 11 3600 2 75 7 600 12 4800 3 110 8 1200 13 7200 4 134.5 9 1800 14 9600 5 150 10 2400 15 19200 ============================================================================== SendBreak(channelID); Transmits a 233-millisecond break (all zeros) thru the port. This is used by some timesharing systems as a "stop program" or "reset connection" signal. ============================================================================== void ResetChecksum(n) ChannelID n; Reset's channel n's checksum to a state which represents 0 characters. This must be used before any characters are checksummed if a valid checksum is to be obtained. ============================================================================== longword GetChecksum(n) ChannelID n; Returns the current value of the checksum for a particular channel. With 8-bit additive checksum and 16-bit CRC, simply use the low 8 or 16 bits of the long value returned. For 32-bit CRC, the entire value is significant. ============================================================================== void SetCheckType(n,type) ChannelID n; word type; Sets the type of automatic checksumming routine for a particular channel: none - 0, CRC - 1, Add - 2, XOR - 3, Custom - 4 The routines which modify the channel checksum are: GetBytes,SendBytes, GetByte, SendByte. ============================================================================== Credits: I would like to thank David Whitney for his help in getting this started and Jason Blochowiak for his ideas on implementation (particularly channels). To you I owe my gratitude. This program is ShareWare. If you like and use this program, please send US $20 to the following address: Procyon Software 1120 Maple Street Mt. Vernon, IL 62864 The ShareWare registration will entitle you to future updates of this program. If you are using MM in a communications project, I'd be interested in hearing from you. E-Mail to jb10320@uxa.cso.uiuc.edu or USSnail to the above address. Thanks for trying Modem Manager, and I hope you find it useful.