TweetFollow Us on Twitter

XModem Transfer
Volume Number:2
Issue Number:12
Column Tag:Forth Forum

Batch Text File Transfer by XMODEM

By Jörg Langowski, MacTutor Editorial Board, Grenoble, France

If you don't happen to have a tape backup unit for your Macintosh, but access to some larger computer installation over a terminal line (with, usually, lots of disk space), there is a slow but secure way to keep backups of your files by uploading them to that machine. There are all sorts of communication utilities that help in doing so, most of them using the XMODEM protocol for up- and downloading files.

The telecommunications programs I am aware of at this moment are excellent tools for transferring single files to and from the Macintosh. If one wants to back up one full disk by such a file transfer, however, the task becomes a little tedious since one has to select one file at a time; particularly time-consuming if your disk has 327 short text files on it. The XMODEM standard does offer a batch transfer mode in which the filename is transferred followed by the file, and if anyone out there knows of a terminal program that has this mode implemented, please let me know.

For the time being, the transfer of one whole volume on a HFS disk from the Mac to another system by XMODEM batch transfer is a neat little project to implement in Forth. Besides being useful, it'll help us gain some insight into HFS file handling.

We will limit ourselves to transferring text files here. Since you all are aware that files on the Macintosh consist of the data and the resource fork, applications and other resource-containing files have to be changed into text files using a utility like BINHEX first. However based on our example, it is rather easy to implement the MacBinary format [a special standard combining both forks together with the Finder information into one structure: see MacTutor V2#1], and transfer files of any type automatically. At the present time, a text file backup system is fine for me, since the documents I most often have to back up, like manuscripts or current versions of Mach 2 and NEON source files, are text files anyway.

The XMODEM Batch Transfer Protocol

How does an XMODEM file transfer proceed? Each file is split up into sectors of 128 bytes each (a relic of old CP/M times), each sector starting at one. A simple file transfer (not batch mode) has the following protocol:

Simple File Transfer Protocol

Sender Receiver

waits for NAK,

80 sec timeout sends NAK at

10 sec intervals

Loop n times for n sectors

send header:

SOH ($01)

sector no. (0-255)

sector no. complement (255-0)

send sector data, 128 bytes

send checksum:

(header bytes + sector data ) mod 255

compute checksum and

compare with checksum

byte

send ACK ($06) if OK and

NAK if not

If ACK received, increment

sector no.

otherwise resend sector

End Loop

send EOT ($04)

send ACK

The transfer may be cancelled at any time by the sender or receiver transmitting a Ctrl-X ($24) to the other end.

In batch mode, there is an additional protocol defined to transmit the filename before the file transfer starts:

Batch Mode Protocol

Sender Receiver

waits for NAK,

80 sec timeout sends NAK at

10 sec intervals

sends ACK

awaits filename characters,

1 sec timeout

on error -> above NAK

Loop 11 times

send filename char

(bit 7=0, upper case)

add to checksum receive filename char

await ACK 1 sec timeout add to checksum

ACK

End Loop

send Ctrl-Z

add to checksum receive Ctrl-Z

add to checksum

send checksum

receive checksum +

verify

ACK if OK and "u" if not await ACK

- Normal file transfer starts -

NAK

SOH

.

.

.

EOT

ACK

expect NAK to start new

filename NAK

ACK for new file name

or EOT if finished

The routines necessary to implement this protocol are printed in Listing 1. [For the single file transfer protocol, I adapted some routines from an article by Robert Taylor in Dr. Dobbs Journal 83 (9/1983) p.66.]

The program in Listing 1 is best used by having some terminal emulation like Mockterminal running on the Macintosh at the same time. Mach2 users may append this code directly to the "Terminal Emulator" example on the Mach2 demo disk and then start the terminal emulator before doing the transfer. For other Forths, the program should be easily adaptable, you'll have to change the routines for setting the baud rate and for doing the modem input and output.

Look at the definition of the words send and send-filename and the inner loop of send for the implementation of the XMODEM protocol in Forth.

In order to be able to transfer one whole volume automatically, we must have some means for accessing the files on a volume one by one. The example contains some file and directory handling words for this purpose. I have also left in there some words I needed in testing (like $openWD) which are not used in the actual implementation, but could be useful at times.

The Mach2 word $open opens a file on the default volume, given a name string, and returns a file ID number. In order to access files in any arbitrary folder (= HFS volume), we have to get a volume ID number first and set the default volume to this ID. The word promptvolID calls the standard file package to prompt the user to select a file in the folder that is to be transferred. Then the volume ID of this folder is returned. Calling setvol with a volume ID sets the default volume. getidxfile takes as its input a volume ID and an index n and will look for the n-th file in the volume. The filename is returned in a global parameter block, parblock, and can be used to open the file with $open after setting the correct default volume. send-batch simply scans the default volume for all files and transfers them one by one. So far, for text files only. Have fun implementing the MacBinary standard.

Reader Feedback

I got several comments on the floating point routines that we published lately. Ed Moskowitz from Winfield, IL points out correctly that the routines will not work with the new Mach2 since they use D5 and D6. This is correct, and D5 and D6 have to be added to the MOVEM.L save and restore list at the routine entry and exits to fix this bug.

Mike Morton from Cambridge, MA had some useful comments to make about improving the speed of those routines. Excerpts from his letter:

"• If you're doing lots of _Pack4 calls, you can do a GetTrapAddress and call the package directly, saving 30 to 50 microseconds ( )

• Instead of BTST #7, D0, you can do TST.B D0 and use BMI to see if the bit is on.

...

• when you AND #$7FFFFF to both D3 and D1 in the division routine, it's faster to move the mask to a register just once and use it twice. ( )

• When you're doing multiplications [and divisions, JL], you might optimize for cases where some of the number is zero. So your four MULUs might test whether the operands are zero and handle that case explicitly. I spent some time writing 32-bit fixed-point multiply routines a while ago, and this helped a lot because many numbers don't have any bits on the bottom of the longword. If you expect many of the f.p. numbers to not have many significant bits, this helps some.

( ) "

Thanks, Ed and Mike, for your comments.

NEON News

One letter came clear from Tasmania, from Phil Barnard:

" I am suffering from the new ROM syndrome at the moment, although the faster and more spacious drives are very pleasant after the original units. Having to replace the interrupt vectors for the interrupt button was a nuisance. As you are no doubt aware the new ROM/System does not present the familiar bomb-box, but an 'empty' dialog.

It may be that the new dialog can be used to resume in the same fashion as the old one, but I don't yet know how. G <return> sends it back into any loop that you may wish to exit. Looking at the register contents by typing A0 through D7 is of limited debugging use. Can it do anything else?"

[Why, I even installed a control panel with flashing LEDs and toggle switches on the top of my Mac. Why do you want anything else? ... Well, G 40F6D8, of course, you probably know by now that that is the address of _Exittoshell and will (sometimes) send you straight back to the Finder. I don't use it for many other things. JL]

"The following routine brings back the old familiar bomb-box on interrupt."

\ installation of custom interrupt vectors; Phil Barnard
\  ** INTERRUPT VECTORS **
\ prints out the seven vectors from the interrupt table
: get.ints ( -- ) cr
 $ 64 -base @ . cr \ VIA
 $ 68 -base @ . cr \ SCC
 $ 6C -base @ . cr \ VIA & SCC
 $ 70 -base @ . cr \ Debugging Button
 $ 74 -base @ . cr \     "
 $ 78 -base @ . cr \     "
 $ 7C -base @ . cr \     "

CREATE RTS $ 4E75 NEXT,

\ installs RTS in the last four (debugging) vectors in the interrupt 
table

: put.ints ( -- )
 $ 80 $ 70 do 'c RTS +base i -base ! 4 +loop get.ints ;

Thanks, Phil. I'll deal with more NEON stuff in the next column where I'll also have some time to write about the new release of NEON, version 2.0. Here only a few headlines:

• NEON 2.0 is fully HFS and Switcher compatible; a new class pathlist has been added to specify HFS search paths. The assembler supports the new ROM calls.

• Applications install as a one piece file, no need to keep a copy of the installed NEON kernel on the disk.

• A decompiler has been added that will handle simple definitions, classes, objects and methods.

• A number of bugs, including the famous IC! have been fixed.

More details about NEON 2.0 and other NEON things later. Till then, good holidays.

Listing 1: XMODEM batch file downloader


( Implementation of Modem7 file transfer protocol, 
 © 9/86 J. Langowski  for MacTutor )

only forth also mac also i/o also assembler
decimal

60 user fileID

10 constant maxerr   0 constant nul24 constant can
4 constant eot   6 constant ack  21 constant nak
1 constant soh   26 constant ctrl-z
117 constant bdnmch

" Select file on volume to upload:" constant seldirtext

variable time-ct variable nak-ct variable cksum    
variable filename 128 vallot
variable xbuffer 128 vallot
variable replyrecord 74 vallot

header parblock 12 allot  ( 12 bytes junk )
header iocompl   4 allot  ( at PB + 12 )
header iores     8 allot  ( at PB + 16 )
header ioref#    4 allot  ( at PB + 24 )
header iomisc    4 allot  ( at PB + 28 )
100 allot ( some elbow room )

: long-timeout  1000 time-ct ! ; (  17 sec timeout )
: short-timeout 100  time-ct ! ; ( 1.7 sec timeout )

: baud-rate ( - )
 1CC0A COMM1 mode  ( 9600 BAUD Xon/Xoff )
 ABORT" Serial Driver Error" ;  (8 bit, No Par, 2Stop)
 
: modout comm1 output emit console output ;
: fin can modout ;  : fini fin close-file ;

: timed-read { | tstart -- char }
 call tickcount -> tstart
 comm1 input
 begin
 ?terminal if key console input exit then
 call tickcount tstart -  time-ct @ > 
 until 
 console input  -1
;

: ?contrlx ?terminal 
 if key 24 = 
 if fini 1 abort" Control-X abort" then
 then 
;

: wait-ack { | errs -- }
 0 -> errs 
 begin  errs maxerr >  nak-ct @ maxerr > or
 if fini 1 abort" Max error count exceeded." then
 ?contrlx 
 timed-read case
 -1  of errs 1+ -> errs ." Timeout" cr endof
 can of 1 abort" Remote Cancel" endof
 ack of 0 nak-ct !  exit endof
 nak of 1 nak-ct +! exit endof
 ( disp-chr 0 )
 endcase
 again
;

: send-setup
 long-timeout
 standard-getfile  0= 
 if fin 1 abort" Cancelled." then
 0 nak-ct !
;

: read-sect { sector# | sect-start -- }
 sector# 128 * -> sect-start
 128 0
 do i sect-start + virtual c@ i xbuffer + c! loop
;

: send-filename
 ack modout 0 cksum c!
 12 1 do filename i + 
 c@ 127 and dup 95 > if 32 - then
 dup modout dup emit
 cksum c@ + cksum c!
 wait-ack
 loop cr
 ctrl-z modout 
 cksum c@ ctrl-z + cksum c!
;
 
: send-hdr { sector# | -- }
 soh modout
 sector# 1+ 255 and dup modout 255 xor modout
 ." Sending " sector# . cr
;

: send-sect ( send sector in xbuffer via XMODEM )
 0 ( sum )
 128 0 do xbuffer i + c@ dup modout + 255 and loop
 cksum c!
;
 
: send-cksum cksum c@ modout ;

: end-send
 close-file
 begin cr ." Sending EOT -" eot modout wait-ack
 nak-ct @ 0= until
 ." ack'd"
;

: get-file-length ( -- sectors )
 fileID w@ ['] ioref# w!  0 ['] iocompl !
 ['] parblock call geteof . cr
 ['] iomisc @ 128 /mod swap 
 if 1+ then
 dup ." File has " . ."  sectors" cr 
;
 
: send ( current file via XMODEM, closes file on exit )
 get-file-length 0
 do
 begin
 i read-sect ( into xbuffer )
 i send-hdr send-sect send-cksum
 wait-ack nak-ct @ 0=
 until
 loop
 end-send
;

: prelude
 short-timeout  begin timed-read -1 = until
 long-timeout  ." Awaiting initial NAK: "
 wait-ack cr   short-timeout
;

: send-one send-setup prelude send ;

: end-batch ack modout eot modout ;

( *** file and directory  handling routines *** )

: getVolID { index | pb -- VRefNum / errcode 0 }
 ( ID for volume no. index )
   ['] parblock -> pb
 0 ['] iocompl !
 filename pb 18 + !
 index pb 28 + w!
 pb call getvolinfo
 ?dup if 0 else pb 22 + w@ then
;

CODE SFGetFile  ( x y prompt numTypes typeList ReplyRecord )
 MOVE.L (A6)+,A1 ( reply record )
 MOVE.L (A6)+,A0 ( type list )
 MOVE.L (A6)+,D3 ( numTypes )
 MOVE.L (A6)+,D2 ( prompt )
 MOVE.L (A6)+,D1 ( y-coord )
 MOVE.L (A6)+,D0 ( x-coord )

 MOVE.W D0,-(A7)
 MOVE.W D1,-(A7) ( where )
 MOVE.L D2,-(A7) ( prompt )
 MOVE.L #0,-(A7) ( no filter proc )
 MOVE.W D3,-(A7) ( num Types )
 MOVE.L A0,-(A7) ( type list )
 MOVE.L #0,-(A7) ( no dialog hook )
 MOVE.L A1,-(A7) ( reply record )

 MOVE.W #2,-(A7)
 _Pack3
 RTS
END-CODE

: promptvolID  ( -- VRefNum flag )
 100 50 seldirtext -1 0 replyrecord 
 SFGetfile
 replyrecord 6 + w@ l_ext
 replyrecord w@ l_ext
;

CODE SFPutFile
 MOVE.L (A6)+,A1
 MOVE.L (A6)+,A0
 MOVE.L (A6)+,D3
 MOVE.L (A6)+,D2
 MOVE.L (A6)+,D1
 MOVE.L (A6)+,D0

 MOVE.W D0,-(A7)
 MOVE.W D1,-(A7)
 MOVE.L D2,-(A7)
 MOVE.L D3,-(A7)
 MOVE.L A0,-(A7)
 MOVE.L A1,-(A7)

 MOVE.W #1,-(A7)
 _Pack3
 RTS
END-CODE

: $openWD { name | pb -- VRefNum / errcode 0 }
   ['] parblock -> pb
 0 ['] iocompl !
 name pb 18 + !
 0 pb 28 + w!
 pb 1 call HFSDispatch
 ?dup if 0 else pb 22 + w@ then
;

: closeWD { volume | pb -- rescode }
   ['] parblock -> pb
 0 ['] iocompl !
 volume pb 22 + w!
 pb 2 call HFSDispatch
;

: setVol { volume | pb -- res code }
   ['] parblock -> pb
 0 ['] iocompl !
 0 pb 18 + !
 volume pb 22 + w!
 pb call setVol
;
 
: getidxfile { volume index | pb -- res code }
   ['] parblock -> pb
 0 ['] iocompl !
 filename pb 18 + !( ioNamePtr )
 volume pb 22 + w! ( ioVRefNum ) 
 0 pb 26 + w!  ( ioFVersNum )
 index pb 28 + w!( ioFDirIndex )
 pb call getfileinfo 
 dup 0= if ." Found: " filename count type cr then
;

: openidxfile { volume index | -- res code }
 volume index getidxfile
 ?dup 0= if filename $open then
;

: find-files { | volume index -- }
 promptvolID 
 if -> volume 1 -> index
 begin 
 volume index getidxfile
 index 1+ -> index
 until
 else ." cancelled" . cr 
 then
;
( *** main definitions for batch file transfer *** )
: display-filename
 12 1 do filename i + c@ 127 and dup 95 > if 32 - then emit
 loop cr
;  
: send-batch{ volume | index }
 1 -> index  0 nak-ct ! 
 begin cr
 filename 1+ 11 32 fill
 volume index getidxfile 0= 
 while
 volume setvol drop 
 filename $open dup 0> 
 if   fileID w!
 begin 
 prelude send-filename
 timed-read cksum c@ <> 
 while 
 ." Checksum Error in filename, restarting" cr
 bdnmch modout
 repeat
 ack modout
 send ( closes file )
 else drop 
 then
 index 1+ -> index
 repeat
 wait-ack end-batch
;
: upload 
 promptvolID
 if send-batch 
 else cr ." Cancelled" cr
 then
;
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Dropbox 193.4.5594 - Cloud backup and sy...
Dropbox is a file hosting service that provides cloud storage, file synchronization, personal cloud, and client software. It is a modern workspace that allows you to get to all of your files, manage... Read more
Google Chrome 122.0.6261.57 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
Skype 8.113.0.210 - Voice-over-internet...
Skype is a telecommunications app that provides HD video calls, instant messaging, calling to any phone number or landline, and Skype for Business for productive cooperation on the projects. This... Read more
Tor Browser 13.0.10 - Anonymize Web brow...
Using Tor Browser you can protect yourself against tracking, surveillance, and censorship. Tor was originally designed, implemented, and deployed as a third-generation onion-routing project of the U.... Read more
Deeper 3.0.4 - Enable hidden features in...
Deeper is a personalization utility for macOS which allows you to enable and disable the hidden functions of the Finder, Dock, QuickTime, Safari, iTunes, login window, Spotlight, and many of Apple's... Read more
OnyX 4.5.5 - Maintenance and optimizatio...
OnyX is a multifunction utility that you can use to verify the startup disk and the structure of its system files, to run miscellaneous maintenance and cleaning tasks, to configure parameters in the... Read more

Latest Forum Discussions

See All

Zenless Zone Zero opens entries for its...
miHoYo, aka HoYoverse, has become such a big name in mobile gaming that it's hard to believe that arguably their flagship title, Genshin Impact, is only three and a half years old. Now, they continue the road to the next title in their world, with... | Read more »
Live, Playdate, Live! – The TouchArcade...
In this week’s episode of The TouchArcade Show we kick things off by talking about all the games I splurged on during the recent Playdate Catalog one-year anniversary sale, including the new Lucas Pope jam Mars After Midnight. We haven’t played any... | Read more »
TouchArcade Game of the Week: ‘Vroomies’
So here’s a thing: Vroomies from developer Alex Taber aka Unordered Games is the Game of the Week! Except… Vroomies came out an entire month ago. It wasn’t on my radar until this week, which is why I included it in our weekly new games round-up, but... | Read more »
SwitchArcade Round-Up: ‘MLB The Show 24’...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for March 15th, 2024. We’re closing out the week with a bunch of new games, with Sony’s baseball franchise MLB The Show up to bat yet again. There are several other interesting games to... | Read more »
Steam Deck Weekly: WWE 2K24 and Summerho...
Welcome to this week’s edition of the Steam Deck Weekly. The busy season has begun with games we’ve been looking forward to playing including Dragon’s Dogma 2, Horizon Forbidden West Complete Edition, and also console exclusives like Rise of the... | Read more »
Steam Spring Sale 2024 – The 10 Best Ste...
The Steam Spring Sale 2024 began last night, and while it isn’t as big of a deal as say the Steam Winter Sale, you may as well take advantage of it to save money on some games you were planning to buy. I obviously recommend checking out your own... | Read more »
New ‘SaGa Emerald Beyond’ Gameplay Showc...
Last month, Square Enix posted a Let’s Play video featuring SaGa Localization Director Neil Broadley who showcased the worlds, companions, and more from the upcoming and highly-anticipated RPG SaGa Emerald Beyond. | Read more »
Choose Your Side in the Latest ‘Marvel S...
Last month, Marvel Snap (Free) held its very first “imbalance" event in honor of Valentine’s Day. For a limited time, certain well-known couples were given special boosts when conditions were right. It must have gone over well, because we’ve got a... | Read more »
Warframe welcomes the arrival of a new s...
As a Warframe player one of the best things about it launching on iOS, despite it being arguably the best way to play the game if you have a controller, is that I can now be paid to talk about it. To whit, we are gearing up to receive the first... | Read more »
Apple Arcade Weekly Round-Up: Updates an...
Following the new releases earlier in the month and April 2024’s games being revealed by Apple, this week has seen some notable game updates and events go live for Apple Arcade. What The Golf? has an April Fool’s Day celebration event going live “... | Read more »

Price Scanner via MacPrices.net

Apple Education is offering $100 discounts on...
If you’re a student, teacher, or staff member at any educational institution, you can use your .edu email address when ordering at Apple Education to take $100 off the price of a new M3 MacBook Air.... Read more
Apple Watch Ultra 2 with Blood Oxygen feature...
Best Buy is offering Apple Watch Ultra 2 models for $50 off MSRP on their online store this week. Sale prices available for online orders only, in-store prices may vary. Order online, and choose... Read more
New promo at Sams Club: Apple HomePods for $2...
Sams Club has Apple HomePods on sale for $259 through March 31, 2024. Their price is $40 off Apple’s MSRP, and both Space Gray and White colors are available. Sale price is for online orders only, in... Read more
Get Apple’s 2nd generation Apple Pencil for $...
Apple’s Pencil (2nd generation) works with the 12″ iPad Pro (3rd, 4th, 5th, and 6th generation), 11″ iPad Pro (1st, 2nd, 3rd, and 4th generation), iPad Air (4th and 5th generation), and iPad mini (... Read more
10th generation Apple iPads on sale for $100...
Best Buy has Apple’s 10th-generation WiFi iPads back on sale for $100 off MSRP on their online store, starting at only $349. With the discount, Best Buy’s prices are the lowest currently available... Read more
iPad Airs on sale again starting at $449 on B...
Best Buy has 10.9″ M1 WiFi iPad Airs on record-low sale prices again for $150 off Apple’s MSRP, starting at $449. Sale prices for online orders only, in-store price may vary. Order online, and choose... Read more
Best Buy is blowing out clearance 13-inch M1...
Best Buy is blowing out clearance Apple 13″ M1 MacBook Airs this weekend for only $649.99, or $350 off Apple’s original MSRP. Sale prices for online orders only, in-store prices may vary. Order... Read more
Low price alert! You can now get a 13-inch M1...
Walmart has, for the first time, begun offering new Apple MacBooks for sale on their online store, albeit clearance previous-generation models. They now have the 13″ M1 MacBook Air (8GB RAM, 256GB... Read more
Best Apple MacBook deal this weekend: Get the...
Apple has 13″ M2 MacBook Airs available for only $849 today in their Certified Refurbished store. These are the cheapest M2-powered MacBooks for sale at Apple. Apple’s one-year warranty is included,... Read more
New 15-inch M3 MacBook Air (Midnight) on sale...
Amazon has the new 15″ M3 MacBook Air (8GB RAM/256GB SSD/Midnight) in stock and on sale today for $1249.99 including free shipping. Their price is $50 off MSRP, and it’s the lowest price currently... Read more

Jobs Board

Early Preschool Teacher - Glenda Drive/ *Appl...
Early Preschool Teacher - Glenda Drive/ Apple ValleyTeacher Share by Email Share on LinkedIn Share on Twitter Read more
Senior Software Engineer - *Apple* Fundamen...
…center of Microsoft's efforts to empower our users to do more. The Apple Fundamentals team focused on defining and improving the end-to-end developer experience in Read more
Relationship Banker *Apple* Valley Main - W...
…Alcohol Policy to learn more. **Company:** WELLS FARGO BANK **Req Number:** R-350696 **Updated:** Mon Mar 11 00:00:00 UTC 2024 **Location:** APPLE VALLEY,California Read more
Medical Assistant - Surgical Oncology- *Apple...
Medical Assistant - Surgical Oncology- Apple Hill WellSpan Medical Group, York, PA | Nursing | Nursing Support | FTE: 1 | Regular | Tracking Code: 200555 Apply Now Read more
Early Preschool Teacher - Glenda Drive/ *Appl...
Early Preschool Teacher - Glenda Drive/ Apple ValleyTeacher Share by Email Share on LinkedIn Share on Twitter Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.