ST-Link 5 What is STLink 5 STLink 5 is a communications package to allow files to be transfered between the Psion Series 5 palmtop computer and the Atari ST series of desktop machines. STLink can transfer individual files, complete directories or even the complete contents of a C.F. in a single operation. Like PsiWin, the official P.C. communications software, all transfers are controlled by the desktop computer. How it works STLink uses a dual file-selector type of interface, similar to that used by several archiving utilities. Copying a file from one computer to the other is simply a matter of selecting the file in the appropriate file selector, and clicking on COPY. Installation STLink is in two parts, the program for the Atari, and the Application for the Psion. The contents of the Atari folder should be placed into an appropriate location on the Atari disc drive. The contents of the System folder should be placed onto the Psion. If you unzipped this archive with 'Recurse subdirectories' selected, the files should already be within the correct folders. If not, create a directory called 'STLink' within your \System\Apps directory, and place the application files within it. Of course, until you have installed STLink you may have no method of installing the files on the Psion. To overcome this the Installation program INSTALL5.PRG will transfer the application on the Psion for you. See 'Installation Program' later. Files README.1ST - Read this first STLINK.TXT - This document (in plain ASCII). STLINK.WRD - This document in Psion Word format. INSTALL5.PRG - The installation program INSTALL5.RSC - The resource file for installation INSTALL - The OPL file for installation In the Atari folder:- STLINK55.PRG - The STLink programme for the Atari. STLINK55.RSC - The Resource file for STLink. In the Convert folder within the Atari folder:- PSIRTF.TTP - File conversion utility by Jeremy Smith PSICLIP.TTP - Clipboard conversion utility (see text) CLIPPSI.TTP - Clipboard conversion utility In the System folder:- STLink.app - The application for the Psion Series 5 STLink.aif - The Icon for STLink STLink.mbm - Graphics used by the application Running STLink Once STLink has been installed, connect the Psion link cable between the Psion and the Atari. This will plug directly into an Atari Falcon, but will need a 9-pin to 25-pin adapter for use on the ST. Start STLink by touching the STLink icon in the Psion extras bar. Next run STLINK55.PRG on the Atari. After a short copyright notice, you should see the main screen showing the two file selectors. Whilst not essential, I recommend always running STLink on the Psion first, as the Atari end of STLink will time-out after 10 seconds. The file selector The main screen for STLink is a dialogue containing two file selectors, one showing files on the Atari, the other showing files on the connected Psion. The operation of the file selectors is similar to that of the standard Atari file selector, although due to the different directory handling of the Psion, there are some differences as explained below. Selecting files: To select a file, click on it with the mouse. You can select as many files as you can see in the file window. If a filename is scrolled out of the window it becomes de- selected. Several files may be selected in one operation by clicking and dragging. To de-select a file click on it again. To find a file quickly in a large directory, enter the initial letter of the filename on the keyboard. The file selectors will scroll to show the files beginning with this letter. Selecting folders: As well as selecting files it is possible to select folders (sub-directories) for copying. To open a folder to see its contents it is therefore necessary to double-click on it, as you would in the Atari desktop. To return to the previous directory, click on the 'close' icon at the top left corner of the selector. Selecting discs: To select between disc drives/partitions on the Atari, click on the drive letter with the mouse. When opening a new partition it will always open at the root directory. This is therefore a quick way of returning to the root directory of any partition. On the Psion you may select from the internal RAM (C), the CF slot (D) or the internal ROM (Z). There is also a button to select an E drive, should that become available in the future. File masks: The STLink file selector does not handle complex file masks, but file extensions can be selected by clicking on the buttons in the lower half of the dialogue. To use a different file mask to those shown, you may modify the contents of a button by pressing Shift, Control or Alternate whilst clicking on the button. You can now enter the new file extension. If you have changed a file extension it can be saved for future use by selecting Save from the Preferences menu. Unlike the normal Atari file selector, when a file mask is selected, the selector no longer shows sub-directories (unless they also match the file mask). To reshow these directories, click on the *.* button. Because of this the file mask is automatically deselected when navigating up and down the directory tree. For consistency, the Atari and Psion file selectors operate identically. Copying files To copy a file from one machine to the other, select the file (or files) in the appropriate selector. Set the other selector to show the directory you wish to copy the file to, and click on the appropriate COPY button. The top button copies from the Psion to the Atari and the bottom button does the reverse. If, when you attempt to copy the file, a file of the same name already exists in the destination directory, STLink will warn you of the fact. You can then choose from the three options: Copy - Copy the file anyway, overwriting the original. Skip - Ignore this file and copy the next (if any). Cancel - Cancel the copying process completely. Alternatively you can edit the filename in the dialogue and copy the file under the new name. If this filename also exists, STLink will again tell you. Copying directories As well as copying files you may also copy directories. If you have selected a folder, STLink will ask you whether you wish to copy the directory empty or with its contents. If you select "With Contents" then all the contents of that directory will be copied including any subdirectories and their contents. If you have selected several folders, your selection will apply to them all. If you try and copy a directory which already exists, the new directory will not be created. Instead the existing directory will be opened and any contents copied into it. Bulk copying If you click on a copy button without selecting any files or folders, STLink will assume that you wish to copy the whole of the displayed directory. Before doing do however, STLink will ask you to confirm this. You may then change the selection in the following way:- Files - Copies all the files in the directory without copying any of the sub-directories. If you have selected a file mask, only those files which match the mask will be copied. Folders - Copies all the folders in the directory as empty subdirectories in the destination. Tree - Copies all the files and folders including their contents and any subdirectories (subject to the file mask). You may also modify these commands as follows: All - Copies all files (subject to the file mask) whether they exist in the destination directory or not. Any files which already exist will be overwritten. New - Only copies files if they do not already exist in the destination directory or the copy in the source directory is newer than that in the destination. This facility allows true incremental backups to be carried out. Ask - If a file exists, STLink asks whether to overwrite it. not, as in normal copying. Using the above you can copy the complete contents of a drive in a single operation. Open files It is quite common on the Psion when trying to copy a file, to find that it is open in another application. If this should happen STLink will ask you whether or not you wish to close the file. If you click on 'Close all' STLink will automatically close any other open files it finds during the transfer. When you Quit STLink it will ask you whether you wish to restart the files that the program closed. Note that STLink is not guaranteed to successfully open all files it closed. This will depend to a large extent on the application which created them. Local copying For convenience STLink also gives you the ability to copy files locally within either computer. If you wish to copy a file within the Psion, say, select the file(s) you wish to copy in the normal manner and click on the left Copy button. The Atari file selector will then 'grey out' and the Copy button will change to say "OK". The QUIT button will also change to say "CANCEL". Select the directory you wish to copy the file(s) to and click on OK. The file(s) will then be copied. You can copy directories in exactly the same manner as copying between both machines. Bulk copying is not however supported. Erasing files Files may be erased by selecting and clicking on the appropriate Delete button. You will be asked to confirm that you wish to delete the files you have selected. You may also delete Directories. In this case you will be presented with a confirm dialogue for each directory you have selected. If you click on 'Delete' the directory will be deleted with all its contents including any subdirectories. You may also click on 'Files' in which case only the files within the directory will be deleted. Any subdirectories and their contents will be left intact. Renaming files Files may be renamed by clicking on the Rename button. Edit the filename in the dialogue box to enter the new name. You can also rename folders if you wish. Note: You cannot rename folders on the ST with early versions of TOS. Creating new folders If you wish to create a new folder, you can do so by clicking on the Rename button without selecting a file first. The new folder will be created in the directory which was displayed in the file selector. File Conversion STLink now has the ability to support file conversion whilst transferring a file. At present the only file conversion supported is from Psion 5 Word to RTF (for import into Calligrapher or Papyrus). The conversion software is installed into a folder called "CONVERT" in the same directory on the Atari as STLink itself. In order to convert files, the conversion option should be ticked in the "Conversion" menu. There are seperate options for conversions whilst transferring from Psion to Atari, and from Atari to Psion (the latter option is currently 'greyed out' as there are no conversions available in that direction). All conversions take place on the Atari machine, consequently when a file is transferred. both the original format file and the converted format will be found on the Atari. If "Delete original" is ticked the Psion format file will be deleted from the Atari, leaving just the converted file. (If the transfer is from the Atari to Psion, the Psion version will be deleted leaving just the Atari format original). The only conversion currently available is PSIRTF written by Jeremy Smith, which converts from the Psion 5 Word format to RTF. this is currently a beta test version which has some known faults:- 1. It does not support Objects within the Word file. If an object is encountered, the conversion will halt, and PSIRTF will have to be exited via the desktop (Alt-Cntrl-Esc under Magic). 2. The converter assumes that the file has a heading, either underlined or in bold type. If this is not the case, the converted file is blank, containing only the RTF header. An update of this software should soon be available. Converting in situ Occasionally it may be useful to convert a file locally on the Atari, perhaps to access a file from your Psion back-up directory. As the conversion utility is a TTP program, it may be run from the desktop. Double click on the TTP file then enter the following information into the command line dialogue:- Source_file_name Destination_file_name If no command line is entered, copyright information will be displayed. Cut and Paste Cut and Paste provides an alternative method of transferring textual data between the two machines without the need to convert files. Cut and Paste makes use of the system scratchpad on both machines. To transfer data, first select it in the appropriate application on the source computer then Copy (or Cut) it to the clipboard. Connect the two machines via STLink, then select the appropriate direction from the Cut and Paste menu. Once the file has been transferred, you should be able to Paste the data directly into your target application. If you are running a multitasking system on the Atari, you may keep STLink running whilst transferring a series of clipboards between applications on the two machines. Note that some programmes on the Atari (Such as Everest) need the Gem clipboard to be specifically selected before Cut and Paste will work. At present Cut and Paste has problems with data transferred from the Psion spreadsheet. This is because the clipboard data includes formatting information. I hope to cure this soon, however until then, Paste the data into a Psion Word file first, then copy from there to the Atari. Importing data into the Psion Spreadsheet works perfectly, especially if the data is Tab delimited. Speed STLink can operate at one of four speeds depending on the type of hardware you are using: 19200 baud - suitable for basic unmodified Atari STs 38400 baud - suitable for TTs and STs with a modified serial port 57600 baud - suitable for Atari Falcons 115200 baud : suitable for accelerated Falcons and faster machines Note that due to limitations of the Atari operating system, speeds above 19200 baud cannot be selected unless HSModem or another serial port accelerator is installed. To change the link speed, select the new speed from the Speed menu. The speed may be changed at any time, although if selected during a file transfer, the rate will not change until the transfer has completed. The Tick in the menu indicates the current rate, not that which you have just selected. Once you have selected the appropriate speed for your hardware, you should Save Preferences. The link will then start at this rate next time the program is run. Note that actual transfer speed is not totally dependant on the serial data rate. There is some processing 'overhead' which will differ depending on the type of machine you are running. Too fast? If the link speed is set too fast for your hardware, errors in the link will occur. These may take the form of a Link Failed dialogue, or you may get corrupted filenames in the file selector. If the rate is only slightly too fast, you may find that a file transfer starts but fails with an error dialogue containing a string of data from the file. In any of these events, you need to reduce the speed, but this may be difficult if the link has failed. You can solve this by one of two methods. Either delete the settings file "STLINK.SET" and start again, or start the Atari end of the link first, quickly select the correct rate, then start the Psion end of the link. Remember you only have a few seconds to do this before the link times out. The Menu bar Desk Menu Allows access to Desk accessories and displays STLink's 'About' screen. Note: If calling up the Control Panel accessory do not change the Modem settings as this will cause STLink to 'hang'. Preferences Menu Allows current preferences to be saved. These include the conversion settings, link speed and file extensions Speed Menu Allows the link speed to be adjusted to match your hardware. Conversion Menu Allows conversions to be selected as required. Cut and Paste menu Allows clipboard data to be transferred between the two machines. Aborting a transfer If you need to abort a process you have started you may do so by clicking on the 'close' icon of the STLink window. This will display an error dialogue with the message "Process interrupted". Clicking on OK will allow the process to continue as before. Clicking on Cancel will allow the current file transfer to complete, then return to the main dialogue. As with other errors, clicking on Quit will quit STLink completely. Multitasking STLink is written to be compatible with multitasking operating systems such as MagiC or Multitos. All dialogues (except the About info box) are movable by dragging their title bars. The Main file selector dialogue is also amodal, allowing you access to other programmes or desk accessories. The file selector cannot currently be iconised, but it may be hidden by the operating system. The progress window can also be moved. On the Psion, you may run STLink in the background, however if too many tasks are running simultaneously, the Psion may miss characters on the link, which will cause STLink to 'hang'. If possible make STLink the foreground task on the Psion. Errors With a link programme such as STLink, two types of error may occur: errors on the Psion and errors on the Atari. In both cases you should see an error dialogue, and you can tell which machine the error has occurred on from the symbols in the dialogue. I hope that I have trapped all likely errors. Errors on the Psion When an error occurs on the Psion, the error message displayed in the error dialogue is generated by the Psion. For the meanings of these messages, consult the Psion manual. Some errors may be transitory (e.g you may be trying to copy a file whilst it is open in an application which is busy). In this case pressing OK will continue with copying the next file. Other errors may be more serious and you may have to Cancel the transfer. Finally some errors may be fatal (e.g. Batteries too low) in which case you may have to hit Quit. Clicking on Quit exits the program on both machines, although closed filed will not be reopened. Errors on the Atari Errors occurring on the Atari are handled similarly to those on the Psion except that in the event of a fatal error, STLink will only allow you to click on the Quit button. In this case STLink assumes that the link with the Psion has failed, and you will have to exit the Psion end of the link from the system screen. Note: If an error occurs during the copying of a file, it will nearly always result in the presence of a zero length file in the destination directory. Bugs and other problems The most likely other problem to occur with STLink is one of "hanging". This is caused when both computers are waiting for a valid reply from the other. If the link does fail, STLink will time-out with an error message after 10 seconds. The most likely cause of this problem is faulty handshaking. If this occurs, check that any interconnecting cables (if any) you have between the Atari and Psion have the RTS and CTS lines connected. Also check that you have any necessary serial patch programmes installed in the Atari. The Psion is also not totally bug-free in this respect, so ensure that you do not have too many other active applications running beside STLink as this can also cause loss of characters over the link. Long file names STLink 5 is fully compatible with long file names up to 40 characters in length (full path up to 255 characters), however unless you use a recent version of MagiC or MiNT, it is unlikely that your Atari is capable of retaining these names once the files have been transferred. In most cases, the Atari operating system will truncate the file names to the standard DOS 8.3 system. This should not be a problem unless two files with different names truncate to the same name. For this reason I recommend that you try and keep filenames short. File names will also be converted to upper case on the Atari. Greater problems occur where filenames include spaces. In this case, the name is normally truncated at the space. Once again this should not be a problem unless two filenames are truncated to the same 8 characters, however if you have file names like "My notes" and "My letters" problems will definitely occur. Spaces in folder names can create serious problems as the Atari will try and create a folder with an invalid name. Further attempts to access this folder result in 'access denied' errors. Take particular care that a folder name does not truncate to the same name as a folder already existing on the Atari, as data loss can result. Note that none of these problems are a result of bugs in STLink. I cannot be held responsible for any problems resulting from incompatible file names. The Installation Program The installation program INSTALL5.PRG installs the Psion part of the link onto your Psion using the Psion's internal comms program and OPL. Before running Install, your files need to be in the correct respective directories as in the zip - i.e., INSTALL5.PRG in the top directory and the files STLINK.APP, STLINK.AIF and STLINK.MBM inside a SYSTEM\APPS\STLINK\ directory structure. To install the software, connect your Psion and Atari machines then run INSTALL5.PRG. The screens will guide you through using the Psion Comms program to load a small OPL file, which you then Translate. When it is run. the OPL program takes over the task of completing your installation. Once STLink has been installed, exit (Ctrl-E) the OPL editor and erase the two installation files 'Install' and 'Install.opo'. Gary Bainbridge (gbainbridge@cix.co.uk)