Batch-YMODEM for HP48 S/SX/G/GX Version 2.2 (C)1996 Laurent Bernard Sorry: I'm a french student, english is not my native language, and so my english is not very good. But I hope that you'll understand the simple words and sentences used. 0 WHAT'S NEW ? 1 INTRODUCTION 2 INFO ABOUT YMODEM LIB 3 GETTING STARTED 4 USING THE HP48 YMODEM LIBRARY 5 USING Y.EXE ON MS-DOS COMPUTERS 6 YMODEM PACKET #0 FORMAT 7 REGISTRATION PROCEDURE 8 DISCLAIMER 9 LIST OF FILES 0 WHAT'S NEW ? -------------- Changes from version 2.1: Many people reported me troubles with the CRC. So I tried to find the reason and I finally found. If I were a honest programmer, I would say it is a bug... but if I were in a software company, I would say it is a feature! So what happened ? It is just a problem of CRC calculation. In fact, there are many possible 16 bits CRC, and the only problem is to know the one used by the transfer protocol. I did not want to spend time on it, and I downloaded a Borland Pascal 7.0 compatible ZMODEM implementation. I re-used the module that was calculating CRC, and for me it was OK. But in fact ZMODEM 16 bits CRC is not the same as YMODEM 16 bits CRC ! My programs worked well when used together, because it was the same CRC calculation... I took another CRC, implemented it, and tested it with XYSRVR 1.7(written by Jim Daniels, aka Double Delta Industries). It worked well when sending from HP 48 to IBM PC, but when sending from IBM PC to HP 48, a problem arose: when the file sended was not a HP file, then all right, but when the file is an HP file, apparently YSRVR doesn't use the right synchro char ( I get a space instead of SOH or STX ) Is that a feature of XYSRVR ? Anyway, I think I got the right CRC, since I was able to receive files. Now it depends on YSRVR, and I hope it implements the right CRC... Something surprising me is that when calculating CRCs with a fast table driven method, only the equation changes, the table is the same for the version 2.1 crc and the version 2.2 crc. So what ? I really need a program implementing True-YMODEM protocol. Unfortunately, I was unable to find a comm program that would allow me to use a NULL modem link (all those I've seen require modem! ). I hope this new version will be much more YMODEM compatible. BTW, I noticed that with version 2.1, when running in port 2, sometimes the HP 48 did a warmstart or worse, crashed ( no memory clear, but, because the interrupts are down, you have to use a paper clip to do a warmstart). Not much user friendly. I added a GARBAGE statement and it seemed to work: I was then unable to crash it. I also shrinked the code, so it weighs about 100 bytes less... And I apologize for the inconvenience caused by those features... 1 INTRODUCTION -------------- The story of YMODEM started a few years ago, when I needed to backup my 128k RAM card regularly because of some programming. Using Kermit was not acceptable, because it spent really too much time, even though the transfers were reliable. After having written a 3D vector demo that was beautiful, but was not very useful, I wanted to write a program that would be worth using. At that period, I had a HP48sx, and I bought a magazine in which they described the YMODEM Batch file transfer protocol. I then poked in the internals of the HP48, and wrote the lib LMODEM, that provided fast transfers, CRC protected, and was very similar to YMODEM, except for the coding of the first packet. This lib just worked fine, I never had a problem with it, and some friends used LMODEM and did not report any bug to me. And then , I gained access to the Internet through my school, and the first thing that I did was to dowload XYMODEM.ZIP, the file containing the protocol description ( the article I had was not very precise and took liberties with the original protocol ). And I wrote what you can use now, that is YMODEM Batch file transfer protocol for HP48 S/SX/G/GX. It is fast ( about 1k per second ), quite secure ( using CRC16 to detect errors ), and it even works with the infrared port, between two HP48. I spent some time on this product, and so I'd like to have some feedback. So I decided to make YMODEM.LIB a shareware, with a modest contribution (FF 50 or USD 10). For registration, see the corresponding section. 2 INFO ABOUT YMODEM LIB ----------------------- Lib number: 996 ( I hope this doesn't conflict with others...) Lib version: 2.2 BYTES Output: Size 5108 bytes CRC #2EA2h 3 GETTING STARTED ----------------- First, upload YMODEM.LIB to your HP48 using Kermit ( if you don't know how to do, there should be a faq, or just read the manual ). Then put the lib in any port you like.( even ports 2 or higher on GX!) Set your IO parameters to: Speed 9600 bauds 8 data bits none parity ( 0 ) Connect the HP48 and the PC compatible with your serial cable. On the PC, echo Y S FileName where FileName is the name of the file you want to send. ( Y.EXE is the name of the program that handles YMODEM transfers) On the HP48, type in YRECV The transfer should then initiate, and finish. For uploading from the HP48, on the HP48, put in the stack the name of the var you want to send, then type YSEND on the PC, type Y R Those are the most common uses of the YMODEM lib and the Y.EXE program. You can use the same syntax for transferring between two HPs... ( select the IR port, then HP #1: VARS YSEND HP #2: YRECV ) 4 USING THE HP48 YMODEM LIBRARY ------------------------------- Here are the commands available in the YMODEM library. RC2 This program does the same thing as RCL, and takes the same arguments. But it has a big advantage: it can RCL in ROM or RAM Cards, so you don't have to change your card switch when sending objects that are in protected ports. This is quite simple to achieve, and I suggest you to take a look at the code to see how simply it is done. EXTR Sometimes when you use YMODEM, you will get strings beginning with the "HPHP48-?" header instead of the object you expected to receive ( I explain the reasons of this effect in YCONF item ). When you want to get the object, just run EXTR on the string, and, if the object is not too corrupted, you should readily see it on the first level of the stack. ( cf ASCLOAD & others ) YSEND This command allows you to send files using the YMODEM ftp. Basically, the YMODEM protocol consists of 128 or 1024 bytes packets, transmitted with CRC or checksum, and the Batch informations are in packet #0 ( the filename and the size in bytes ). syntax There are four possible syntaxes: Sending a variable ( either global or local ): Put in stack level 1 the global/local name then execute YSEND. Sending a variable stored in a port: Put in stack level 1 the tagged name of the object, then YSEND. If the object is a backup, then YSEND will send it using its name. If the object is a library, then there are two possible cases: if the author respected HP specifications, i.e. seventh character of the title string is ":" , then YSEND will send the lib under the name "Title(1-6).LIB" , where Title(1-6) are the first six chars in the title of the lib. Otherwise, then the name will be "LxxID.LIB", where xxID is the number of the lib, as a 4 characters decimal value. Notes: You can even send objects that are in a RAM-Protected or ROM card. The error you can sometime encounter on HP48GX occurs when RCLing a var that is in port 2-up to 31, when there is not enough memory to copy it to the ram. In this case, you'll get an "Insufficient Memory" error. You can't send nullnamed objects ( the YMODEM protocol is confused because null names are used to indicate the end of a batch ). If you try to do so, you'll have an error ("Null name not allowed"). Sending an arbitrary object under an arbitrary name Put in level two the object you want to send, and in level the name under which it should be sent, as a string, then run YSEND. Batch operations Put a list in level 1, then run YSEND. The list should be made of either local names, global names, or tagged objects. EXAMPLES This section illustrates common uses of YSEND: Backing up RAM Simply execute << HOME PVARS YSEND >> Backing up a port << NbPort PVARS DROP YSEND >> Using arbitrary names/objects << 1 "REAL1" YSEND >> PARAMETERS There are several parameters to select the behaviour of the YSEND program. See YCONF for more details. YRECV Just run YRECV, and you should readily see the var appended to your current directory. YRECV uses the standard IO params, plus additional settings described in YCONF. YCONF This program was designed to allow easy modification of the YMODEM parameters. Running YCONF, you should see a menu and the current settings. Just press the appropriate key to switch the setting. Port Select IR/Wire Port Speed Choose between 1200,2400,4800, and 9600 bps. Just press the SPEED menu item to walk through the available speeds. Note: When using IR transfers, this setting is not taken into account, and the program automatically selects the highest possible speed for IR transfers. YSEND packet size YMODEM protocol allows sender to send 128 or 1024 bytes packets. By default, 1024 bytes packets are choosen, but you can switch to force 128 bytes packets. You can also execute 33 SF to use 128 bytes packets. This changes only the behaviour of YSEND.( YRECV automatically adapts to 128 or 1024 bytes packets. ) YRECV replaces This is the same option as the one used in kermit ( system flag -36 ). I tried to use the same format as the one used by HP for renaming variables, except that I start using value 0 ( for example, you can get a 'NAME.0' name) instead of 1. YRECV prefers YMODEM transfers can check the integrity of packets using two different methods: checksum or CRC. I recommend to use the CRC option ( that is the default value ), but an old YMODEM sender could still use Checksum checking, so I put it for compatibility. If you know that the sender will use checksum, then select checksum. Otherwise, if you don't, then select CRC, and YRECV will try to establish the link using CRC, and if it fails after 5 trials, will step down to checksum to establish the link. When user flag 34 is set, checksum will be preferred. YRECV always Ob-> Some objects that get damaged when stored in the hard disk won't be well transformed on your HP. But sometimes there are only a few bytes added to it ( for example, garbage added at the end of the file by XMODEM...). By default, when there is a problem of this kind with the size of the file, YRECV will put a string (beginning with the "HPHP48-?" header) in the variable. When user flag 35 is set, then YRECV will always try to extract the obj, regardless of the size of the file transferred. ABOUT996 Displays information on the lib, and reminds the syntax and arguments of the progs of YMODEM.LIB. Important: You can abort YSEND/YRECV at any time by pressing the ON key. At the end of transfers, wether successful or not, the IO port is closed. 5 USING Y.EXE ON MS-DOS COMPUTERS --------------------------------- Y.EXE is an example of a program implementing the YMODEM ftp on computers running MS-DOS. Y.EXE was written using Turbo Pascal 7.0, and I leave Y.EXE in the public domain, with its sources. In fact, I am furnishing the source to show you how to interface with YMODEM.LIB. I hope you will be able to write compatible software for your hardware. Y.EXE is a command line oriented program, but the default parameters are compatible with the default parameters of the HP48, so you should not have to do any configuration (except maybe the number of the port). To send a file to the HP48, just type Y S parameters filespec To receive a file, use Y R Here are some explanations: parameters:(xxx is a numeric value) -sxxx: choose the speed. xxx may be 110,150,300,600,1200,2400, 4800,9600; by default,speed is 9600 bps. -dxxx: data bits. xxx may be 7 or 8 (default 8) -txxx stop bits. xxx may be 1 or 2 (default 1) -pxxx parity. xxx may be 0 (none), 1 (odd), 2 (even) (default none) -#xxx select the COM port. xxx may be 0 or 1. -r when receiving, using the -r switch allows Y.EXE to overwrite existing file (by default, Y.EXE renames the file). filespec: are just the normal MSDOS file specifications, with ?,* and so on... To remind you of the main switches, just type Y H or Y Important: You can abort Y.EXE at any time by pressing the ESC key. I tried to follow as much as possible the YMODEM protocol (as described in Chuck Forsberg's XYMODEM.ZIP description). However, I'm not perfect, and there are maybe some bugs, or some misinterpretations of the protocol. The YMODEM lib and the Y.EXE are equivalent: if there is a protocol error in Y.EXE, then the same error is in the lib. That's is one of the reasons why I'm furnishing the source for Y.EXE: if you find an error in it, then please email me so I can fix it as soon as possible, both in Y.EXE and in YMODEM.LIB. Thanks in advance. ( By the way, to compile Y.EXE, if you have Turbo Pascal installed, use make -f y.mak ) 6 YMODEM PACKET #0 FORMAT ------------------------- I'll descrive here the format used for the first packet, because it is usually the cause of many incompatibilities between ftp programs. I use only the name and size fields, and no pathname can be given in the name. On the HP48, all the sensible information should be in the first 128 bytes, otherwise you'll get an error. Here is a figure: Byte #0: First char of name Byte #1: Second char of name ... Byte #n: Last char of name Byte #(n+1): should be a null char Byte #(n+2): First char of size ... Byte #m: Last char of size Byte #(m+1): Either a null char or a space ... The following bytes are not taken into account. Note: the size is converted in ascii, and sent as a sequence of characters. For an implementation example, see the file UYMODEM.PAS. 7 REGISTRATION PROCEDURE ------------------------ I decided to distribute YMODEM.LIB as a shareware. ( Note that Y.EXE and the associated files are in the public domain, you can do anything you want with them, as long as you do give credit where credit is due...) This is not in my habits to limit the library functions: the library coming with this package is fully operational. But, if you use it regularly, then you have to register. I fixed the registration fee to FF 50 , I think that most people can afford it. Remember that I'm a student, and that I spent precious time writing this software, so I'd like you to realize that I did my best to write a good transfer protocol, and I think it is a program worth using, so if you like YMODEM.LIB, then go ahead and register. With users' support, I can improve the lib, correct bugs and maybe write a ZMODEM.LIB. So how can you register ? Just send a FF 50 (check/cash) or USD 10 (cash) to me Laurent BERNARD-GUTH 37, rue de Lille 75007 PARIS FRANCE You can reach me using E-mail (comments, bugs, suggestions): laurent.bernard@iota-eso.u-psud.fr (valid up to November 1997) What about me ? I'm currently studying in a top level french engineering school highly specialized in optics (it depends on the Institut d'Optique, in Orsay). I've been programming since my early years, and I'm interested in neural networks, communication (with optics fibers), optical computers, image synthesis (I'm currently implementing a radiosity method) and processing. By the way, coming to the end of my scholarship, I have to find an internship, and I'd like to do it in a foreign country, so the question is: would there be someone out there who could propose me such an internship ? The subject of the internship should have a link with optics (otherwise my professors won't accept...), the duration should be >= 3 months, and it could start in May 1997. If you've got something for me, then contact me please. I think that I have to end this request with something like: '' I look forward to hearing from you... '' 8 DISCLAIMER ------------ These routines are provided "as is" with no expressed or implied warrantees. Any damage or losses caused by the use of these programs is solely the responsibility of the user. (standard disclaimer...) About the HP48 library, I used ONLY SUPPORTED ENTRY POINTS (except in RC2), so the program should run well on all versions ( I tested it on Rev P and Rev C). However, I can't give you any guarantee of any kind, so if you have essential data in your HP, then use the built-in protocols. For the others, back up, just in case... You can distribute the HPYMODEM package as long as you don't alter any file, and that you don't take a charge for distributing the HPYMODEM package (except for shipping/handling ). 9 LIST OF FILES --------------- YMODEM.LIB ( 5116 bytes ): The HP48 S/G library Y.EXE ( 22064 bytes ) : The MSDOS main program HPYMODEM.DOC ( 18903 bytes ) : The file you're reading now The sources of Y.EXE: Y.MAK ( 165 bytes ) COMPDIR.PAS ( 276 bytes ) Y.PAS ( 8634 bytes ) UYMODEM.PAS ( 23525 bytes ) RS232.PAS ( 2288 bytes ) RS232.ASM ( 7050 bytes ) UCRC.PAS ( 877 bytes ) UEZCOMM.PAS ( 3253 bytes ) UJUMP.PAS ( 1710 bytes )