BeepMe 1.00 docs BeepMe implements TAP (Telelocator Alphanumeric input Protocol) on a Newt. It allows the user to send alphanumeric pages from a Newt to alpanumeric pagers served by a system that will accept pages in TAP's manaual format. ------------------------------------------------------------- Revision history of documentation 07/2/94 Initial docs for 1.00 release. ------------------------------------------------------------- Contents Important cautions Legal stuff Introduction Support Price Using BeepMe Deleting BeepMe Known problems and limitations Plans for the future Revision history of the program Acknowledgments ------------------------------------------------------------- Important cautions TAP specifies two ways in which pages can be sent, a "manual" procedure and an "automatic" procedure. BeepMe implements TAP's manual mode since it's much simpler than the automatic prodecure (which, as far as I can tell, gives a new meaning to the word goofy). BeepMe works with my paging service's implementation of TAP's manual mode. I have no idea about how consistent paging systems' implementations of TAP's manual mode are. BeepMe may work for you "out of the box" or you may have to get the source code and hack around with it some. See the Price section below for information about getting the source code. Here's a transcript of a terminal session with my paging service's computer (numbers were changed to protect the innocent): atdt 5555555 CONNECT TDD's Enter M and RETURN ID= M Enter the Pager ID, then RETURN. 9999999 Enter the Message, then RETURN. test Thank You. Hangup now, or Enter the Pager ID, then RETURN. +++ OK ath OK Since my paging service can be relied on to behave this way (check if yours does with your terminal emulator), BeepMe expects it. Specifically, once the modem has connected, BeepMe sends a return and then waits for a line that ends with a return that contains "ID=". BeepMe then sends a "M" and a return. BeepMe then waits for a string ending in a period that contains "Pager". BeepMe then sends the pager number and a return, waits for a string that ends with a period and contains "Message", sends the message and a return, and disconnects. If your pager system ends its prompt lines with colons or happens not to use the word "pager" in the prompt for the pager number, or something like that, you'll have to do some hacking on BeepMe's source. Source is available for a modest sum. See the Price section below. BeepMe has not been throroughly tested. Unless you happen to use my paging service, it almost certainly hasn't been tested on your paging service. Please use it with caution and test it thoroughly yourself before you depend on it to send any important information. If you do have problems, please let me know (see the Support section below). ------------------------------------------------------------- Legal stuff BeepMe and Delete BeepMe Data (the software that this documentation describes) and this documentation are all Copyright 1994 Matthew Dixon Cowles and his licensors. All rights reserved. Apple and Newton are trademarks of Apple Computer, Inc., registered in the United States and other countries. NewtonMail and MessagePad are trademarks of Apple Computer, Inc. Here is the software license that Apple Computer, Inc. requires that Newton software written with the Newton Toolkit carry. It isn't exciting reading and it exhibits lawyers' curious use of capitalization, but I advise you to read it since it does apply to all users of BeepMe. 1. License. The application, demonstration, system and other software accompanying this License, whether on disk, in read only memory, or by any other media (the "Software"), the related documentation and fonts are licensed to you by Matthew Dixon Cowles. You own the media on which the Software and fonts are recorded but Matthew Dixon Cowles and/or Matthew Dixon Cowles's Licensor(s) retain title to the Software, related documentation and fonts. This License allows you to use the Software and fonts on a single Newton Product (which, for the purposes of this License, shall mean a product bearing Apple's Newton logo), and make one copy of the Software and fonts in machine-readable form for backup purposes only. You must reproduce on such copy Matthew Dixon Cowles's copyright notice and any other proprietary legends that were on the original copy of the Software and fonts. You may also transfer all your license rights in the Software and fonts, the backup copy of the Software and fonts, the related documentation and a copy of this License to another party, provided the other party reads and agrees to accept the terms and conditions of this License. 2. Restrictions. The Software contains copyrighted material, trade secrets and other proprietary material and in order to protect them you may not decompile, reverse engineer, disassemble or otherwise reduce the Software to a human-perceivable form (does not apply to users with source code licenses for BeepMe). You may not modify, network, rent, lease, loan, distribute or create derivative works based upon the Software in whole or in part. You may distribute BeepMe for a nominal download or duplication charge at most. Except for that exception, you may not electronically transmit the Software from one device to another or over a network. 3. Termination. This License is effective until terminated. You may terminate this License at any time by destroying the Software and related documentation and fonts. This License will terminate immediately without notice from Matthew Dixon Cowles if you fail to comply with any provision of this License. Upon termination you must destroy the Software, related documentation and fonts. 4. Export Law Assurances. You agree and certify that neither the Software nor any other technical data received from Matthew Dixon Cowles, nor the direct product thereof, will be exported outside the United States except as authorized and as permitted by the laws and regulations of the United States. If the software has been rightfully obtained by you outside of the United States, you agree that you will not re-export the Software nor any other technical data received from Matthew Dixon Cowles, nor the direct product thereof, except as permitted by the laws and regulations of the United States and the laws and regulations of the jurisdiction in which you obtained the Software. 5. Government End Users. If you are acquiring the Software and fonts on behalf of any unit or agency of the United States Government, the following provisions apply. The Government agrees: (i) if the Software and fonts are supplied to the Department of Defense (DoD), the Software and fonts are classified as "Commercial Computer Software" and the Government is acquiring only "restricted rights" in the Software, its documentation and fonts as that term is defined in Clause 252.227-7013(c)(1) of the DFARS; and (ii) if the software and fonts are supplied to any unit or agency of the United States Government other than the DoD, the Government's rights in the Software, its documentation and fonts will be as defined in Clause 52.227-19(c)(2) of the FAR or, in the case of NASA, in Clause 18-52.227-86(d) of the NASA Supplement to the FAR. 6. Disclaimer of Warranty on Software. You expressly acknowledge and agree that use of the Software and fonts is at your sole risk. The Software, related documentation and fonts are provided "AS IS" and without warranty of any kind and Matthew Dixon Cowles and Matthew Dixon Cowles's Licensor(s) (for the purposes of provisions 6 and 7, Matthew Dixon Cowles and Matthew Dixon Cowles's Licensor(s) shall be collectively referred to as "Matthew Dixon Cowles") EXPRESSLY DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. MATTHEW DIXON COWLES DOES NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE SOFTWARE WILL MEET YOUR REQUIREMENTS, OR THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT DEFECTS IN THE SOFTWARE AND THE FONTS WILL BE CORRECTED. FURTHERMORE, MATTHEW DIXON COWLES DOES NOT WARRANT OR MAKE ANY REPRESENTATIONS REGARDING THE USE OR THE RESULTS OF THE USE OF THE SOFTWARE AND FONTS OR RELATED DOCUMENTATION IN TERMS OF THEIR CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE. NO ORAL OR WRITTEN INFORMATION OR ADVICE GIVEN BY MATTHEW DIXON COWLES OR AN AUTHORIZED REPRESENTATIVE OF MATTHEW DIXON COWLES SHALL CREATE A WARRANTY OR IN ANY WAY INCREASE THE SCOPE OF THIS WARRANTY. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU (AND NOT MATTHEW DIXON COWLES OR AN AUTHORIZED REPRESENTATIVE OF MATTHEW DIXON COWLES) ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION IF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. 7. Limitation of liability. UNDER NO CIRCUMSTANCES INCLUDING NEGLIGENCE, SHALL MATTHEW DIXON COWLES BE LIABLE FOR ANY INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES THAT RESULT FROM THE USE OR INABILITY TO USE THE SOFTWARE OR RELATED DOCUMENTATION, EVEN IF MATTHEW DIXON COWLES OR AN AUTHORIZED REPRESENTATIVE OF MATTHEW DIXON COWLES HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME JURISDICTIONS DO NOT ALLOW THE LIMITATION OR EXCLUSION OF LIABILITY FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES SO THE ABOVE LIMITATION OR EXCLUSION MAY NOT APPLY TO YOU. In no event shall Matthew Dixon Cowles's total liability to you for all damages, losses, and causes of action (whether in contract, tort (including negligence) or otherwise) exceed the amount paid by you for the Software and fonts. 8. Controlling Law and Severability. This License shall be governed by and construed in accordance with the laws of the United States and the State of California, as applied to agreements entered into and to be performed entirely within California between California residents. If for any reason a court of competent jurisdiction finds any provision of this License, or portion thereof, to be unenforceable, that provision of the License shall be enforced to the maximum extent permissible so as to effect the intent of the parties, and the remainder of this License shall continue in full force and effect. 9. Complete Agreement. This License constitutes the entire agreement between the parties with respect to the use of the Software, related documentation and fonts, and supersedes all prior or conterporaneous understandings or agreements, written or oral, regarding such subject matter. No amendment to or modification of this License will be binding unless in writing and signed by a duly authorized representative of Matthew Dixon Cowles. ------------------------------------------------------------- Introduction You should bear in mind in reading this documentation that it is really a description of how I intend that BeepMe should work. As the license agreement above indicates, I don't promise that it does work as I've described. ------------------------------------------------------------- Support I am extremely interested in getting feedback from users. I would be delighted to hear comments, thoughts and suggestions about the documentation, feature requests, bug reports, expressions of praise, and lucrative job offers. If you are reporting a bug, please try to be as specific as possible about the actions that lead up to it. If you are expressing praise or making a job offer, please try to be as generous as possible. I can't promise to implement all features that are requested, but I will keep track of them and will be more likely to implement those that are requested most often. Support for BeepMe is currently only available by mail, preferably e-mail. My e-mail addresses are: NewtonMail, eWorld: MattC (@eworld.com) AppleLink: MONDO (@applelink.apple.com) CompuServe: 73134,2536 (73134.2536@compuserve.com) If you don't have an e-mail account, please send a note by the postal service to: Matthew Dixon Cowles 4501 Park Glen Road, no. 345 St Louis Park, MN 55416 USA ------------------------------------------------------------- Price BeepMe is free in binary form. Source code for BeepMe is available in case you need to change the communication protocol to suit your paging service or if you'd just like to see just how bad a programmer I am. Source code for BeepMe is available for 20 US Dollars, by mail only. Note that a source code license allows you to modify your own copy of BeepMe and to use the code for general inspiration, but it does not allow you to distribute derivative works. ------------------------------------------------------------- Using BeepMe -- Installation -- Getting started and entering numbers -- Sending a page -- Installation Install BeepMe just as you would any Newton package. Use Newton Connection Kit or any of the other programs that will send packages to your Newton. (Check the documentation that came with the program you use for details.) Once you have installed the app, you will see a new icon, a pager, in your extras drawer. Tap it to open BeepMe. -- Getting started and entering numbers When you first open BeepMe, it will show an (empty) list of people whose pager numbers it knows, a place in which to write the message you wish to send, a line describing the current communication status (idle) and a row of buttons. The first thing to do is to enter a pager number or two. To do that, tap the New button and the overview of people will change to an entry view. In the entry view, enter the name of the person you want to be able to page, the modem telephone number for the paging service (which you need to get from them), the person's pager number, and any notes you like. Note that when the entry view is shown, the New button changes to Forget. You can tap the Forget button to delete an entry. Once you have entered the required information, either tap Newt's overview button or tap the close box in the lower right corner of the entry view to return to the overview. To edit an entry that you have already made, double-tap it in the overview. -- Sending a page To send a page, write the text that you want to send in message field. The label for the message field will tell you how many characters there are in your message since paging systems are limited in the number of characters they will send. You'll have to find out how many yours allows. Then scroll (using Newt's scroll arrows) so that the person you want to page is visible in the overview. Tap once on the person's entry (it will be highlighted) and then tap the Send it button. The comm status line will let you know how the call is progressing and will return to "idle" when the page has been sent. You will notice that the Send it button changes its name to Abort while communication with the paging service is in progress. If, for any reason, you want to abort the call while it's in progress, tap the Abort button. See the Known problems and limitations section below for suggestions about checking that the abort worked correctly. If there has been a problem, BeepMe may show you an error message or an error number. If the number is from BeepMe, I don't know what it means (except that there has been a communications error) -- I've used text messages when I knew what the error numbers meant. ------------------------------------------------------------- Deleting BeepMe Of course, I hope that no one will ever want to delete his or her copy of BeepMe. On the off chance that some poor benighted soul will want to, here's what one has to do in order to delete the application and the data it stores in your Newt. Of course, deleting the program is easy enough -- just tap Prefs then Memory or else Card, and then tap Remove Software and pick BeepMe:MONDO from the list of packages to delete. Deleting the data that BeepMe has stored on your Newt and making it stay deleted is just a little more complex. At the moment, there is no good way for a Newton application to delete the data it has stored on a Newton automatically when it is being deleted. For that matter, a user might possibly not want to have his or her data deleted when a the application that created the data is deleted. I understand that Apple is working on a way of handling this situation. Since BeepMe can't delete its data automatically, I include another application called Delete BeepMe Data. Delete BeepMe Data does not actually delete the program. It deletes the permanent data that BeepMe stores in a user's Newton. There is no need to install Delete BeepMe Data until and unless you want to delete the data that BeepMe has installed. (Delete BeepMe Data is intended as in interim solution until there is a good way to have an app delete its own data, if the user wishes, when the application is being deleted or at some other time. The source code for Delete BeepMe Data is distributed along with the package that you install in your Newton to delete the data. The source code for Delete BeepMe Data is freeware and may be modified and redistributed freely as long as only a nominal download or duplication charge is made, though it remains copyrighted by Matthew Dixon Cowles. Other than the right to modify and redistribute Delete BeepMe Data, all aspects of the licence agreement above apply to Delete BeepMe Data.) In order to actually delete that data that BeepMe has stored on your Newt, first back up the data in your Newt. Then install the Delete BeepMe Data package. Tap the icon labeled "Del BeepMe Data" and read the cautions that appear on the screen. Note that undo is NOT supported. To do the delete, tap the button at the bottom and tap the "OK" buttons on the confirm slips that open. If, for some reason, you have stored data from BeepMe on more than one PCMCIA card, you will need to run Delete BeepMe Data and tap the delete button once with each card that has data from BeepMe installed. At this point, you can delete Delete BeepMe Data in the usual fashion. At this point, you're not quite done. If you have synchronized your Newton with Newton Connection, the next time you synchronize it, Newton Connection will notice that it knows about some data (BeepMe's) that your Newton doesn't have. Connection will, then, copy that data back to your Newton. In order to prevent its doing that, move the folder (or directory) that Newton Connection creates for your Newton out of the folder (or directory) that contains Newton Connection (or you can rename it). Then synchronize again. The new files will not contain any data from BeepMe. Be sure that everything is fine on your Newton before deleting the old files that you moved or renamed. What does Delete BeepMe Data remove? BeepMe creates a soup (permanent storage "file") on your Newton's internal store and on any PCMCIA card that is installed and writable when it is run. Delete BeepMe Data removes these soups. (Of course, if you are adept at using a soup utility such as Stew Pot, it will work just fine too.) ------------------------------------------------------------- Known problems and limitations Modem communication can be kind of goony by nature. Since TAP specifies 300 bps, 7-E-1 (!), there shouldn't be too much trouble with line noise, but you never know. In any case, BeepMe doesn't work very hard to try to figure out whether or not things are going well. If the modems connect, the only check on whether things are working out is that if the message hasn't been transmitted 25 seconds after you tapped the Send it button, BeepMe tries to abort the connection. It would surprise me if aborts (on account of timeouts or on account of tapping the Abort button) were uniformly successful. I strongly recommend checking the modem line to make sure that Newt's modem has hung up after any abort. If Newt appears to have problems with other kinds of communication (printing, faxing, synchronizing, etc.) after using BeepMe, performing a soft reset (by pressing the button in the battery compartment with your pen) should make Newt happy again. Of course, if things go really badly (or you have the wrong pager number entered) and you insist on continuing to try to use BeepMe, your pager service may get mad at you. As the licence agreement above mentions, that's your own problem. ------------------------------------------------------------- Plans for the future Well -- in five years, I'd like to be retired and living on a tropical.... Only kidding. I'm considering implementing TAP's "automatic" protocol. If I find that other folks like BeepMe and that a fair number of other pager systems' implementations of TAP's "manual" protocol vary enough to prevent BeepMe from working with them, I may well implement it. ------------------------------------------------------------- Revision history of the program 06/29/94 Release 1.0 Sent BeepMe out into the world. ------------------------------------------------------------- Acknowledgments My thanks go to: Todd Courtois for his excellent example app AgroModem and to Kent Sandvik for his excellent example app SerialPro. Most of the serial code in BeepMe comes straight from those apps. Heck, I haven't even bothered to rename most of the variables. If anyone at PIE would like source for the app, I'll be delighted to give it to him or her. Kent Sandvik, Mike Engber, Bob Ebert, Maurice Sharp, and the rest of the PIE DTS team, who have saint-like patience.