Jaap's Psion II Page

Below is the version of the Comms Link manual used until 1988. When the LZ was released, a 4-line version of the Comms Link was released too. That version also had an updated manual:
Comms Link Manual (1989+)


Comms Link Manual


© Copyright Psion P.L.C. 1987

All rights reserved. This Comms Link manual and the programs referred to herein are copyrighted works of Psion Limited, London, England. Reproduction in whole or in part including utilisation in machines capable of reproduction or retrieval, without the express written permission of Psion Limited, is prohibited. Reverse engineering is also prohibited.

REGISTERED DESIGN APPLICATION NUMBERS 1019736 & 1019737.

 

Lotus is a registered trademark of Lotus Development Corporation. 1-2-3 is a registered trademark of Lotus Development Corporation. Symphony is a registered trademark of Lotus Development Corporation. DIF is a trademark or Software Arts Inc. IBM is a registered trademark of International Business Machines. Apple is a registered trademark of Apple Computer Inc. Macintosh is a registered trademark of Apple Computer Inc.

Typeset by Lotus Reprographic Services, London.
Printed by Premier Metropolis Limited, London.


CONTENTS

1. Introduction 1.1 Fitting The Comms Link Cable 1.2 Removing The Comms Link Cable 1.3 Backing-Up Your Comms Link Disk 1.4 Using This Manual 2. Connecting to A Printer 2.1 The RS232 Port 2.2 Setting The Communications Parameters 2.3 Using Setup 2.4 BAUD 2.5 PARITY, BITS And STOP 2.6 HAND 2.7 PROTOCOL 2.8 WIDTH 2.9 TIMEOUT 2.10 TEOL 2.11 TEOF 2.12 TTRN 2.13 AUTO 2.14 Printing With Comms Link 2.15 Printing Procedure Files 2.16 Printing Data Files 2.17 Printing The Capture Buffer 2.18 Printing From OPL 3. Connecting to A PC 3.1 The RS232 Port 3.2 Setting The Communications Parameters 3.3 Using Setup 3.4 BAUD 3.5 HAND 3.6 PROTOCOL 3.7 RTRN and TTRN 3.8 Leaving Setup 3.9 Making The Connection 3.10 Transferring Files 3.11 Transferring Diary Files 4. Connecting to Another Computer 4.1 The RS232 Port 4.2 Setting The Communications Parameters 4.3 Using Setup 4.4 BAUD 4.5 PARITY, BITS And STOP 4.6 HAND 4.7 PROTOCOL 4.8 REOL and TEOL 4.9 REOF and TEOF 4.10 RTRN and TTRN 4.11 Leaving Setup 4.12 Setting Up The Other Computer 4.13 Testing The Link 4.14 Transferring Files 4.15 File Transfer With No Protocol 4.16 Xmodem File Transfer 4.17 Using Modems 5. Terminal Emulation 5.1 Connecting Up 5.2 Setting The Communications Parameters 5.3 Using Setup 5.4 BAUD 5.5 PARITY, BITS and STOP 5.6 HAND 5.7 PROTOCOL 5.8 ECHO 5.9 WIDTH 5.10 TEOL 5.11 REOL 5.12 REOF and TEOF 5.13 RTRN And TTRN 5.14 Leaving Setup 5.15 TERM 5.16 File Transfer 5.17 CAPTURE 6. The Comms Menu 6.1 SETUP 6.2 Using Setup 6.3 BAUD 6.4 PARITY, BITS and STOP 6.5 HAND 6.6 XON/XOFF 6.7 RTS/CTS 6.8 DTR 6.9 PROTOCOL 6.10 ECHO 6.11 TIMEOUT 6.12 WIDTH 6.13 REOL and TEOL 6.14 REOF and TEOF 6.15 RTRN and TTRN 6.16 Leaving Setup 6.17 File Transfer 6.18 Terminal Emulation 6.19 Capture 6.20 Auto 6.21 Boot 7. Comms Link And OPL 7.1 LSET 7.2 LPRINT 7.3 LINPUT$ 7.4 TRIG$ 7.5 File Transfer Procedures 7.6 Remote File Access Procedures 8. Appendices A. ASCII Control Characters B. The Comms Link Interface Index


1. INTRODUCTION

The Psion Organiser II Comms Link connects your Organiser to a printer, desktop computer modem, or any device which has an RS232 or R5423 port. What you can do with Comms Link depends on the device that it connects to. Common uses are:

If you wish to connect to an IBM PC/XT/AT or compatible, Comms Link includes special software (on the floppy disk) which you can run on your PC. If you wish to communicate with any other kind of computer you may need a communications program for that computer.

The Comms Link software can be used in three different ways:

  1. directly from its own menu (the COMMS menu)
  2. via the Organiser's built in language - OPL
  3. via another Organiser application, for example the Psion Organiser Pocket Spreadsheet.

You can also access the power of the Comms Link from within the Organiser programming language, OPL. Accessing Comms Link via OPL gives you more power to perform a greater variety of tasks but requires more effort from you.

For example, the COMMS menu allows you send a data file to an attached printer, however, by writing an OPL procedure, you can print records which are selected on any criterion and exercise control over the print layout.

In the third kind of access, Comms Link provides facilities which allow software specially written for the Organiser, to transfer data to and from other devices via the Comms Link cable. An example is in the Organiser Spreadsheet (available as a separate product) which is capable of loading and saving Lotus 1-2-3, Symphony and DIF files from an attached IBM PC/XT/AT or compatible when used in conjunction with Comms Link.

1.1 FITTING THE COMMS LINK CABLE

The Comms Link cable consists of the industry-standard D25 socket at one end and a fitting to connect it to your Organiser at the other. Actually, this "cable" is more than just a cable because the Organiser-end housing contains the Organiser Comms Link software.

To use Comms Link, first switch off your Organiser by selecting OFF from the top-level menu. Slide open the door at the top of the Organiser and insert the plug on the cable into the socket, making sure it slides all the way in until you feel a click. The plug will only go in one way, with the Psion name at the top.

To load the communications software into the Organiser, press the ON/CLEAR key twice. The first press switches the Organiser on and the second press loads the software. Comms Link is now ready for use and a new menu option, COMMS, will have been inserted into the main Organiser menu, just before the last option, OFF.

The communications software occupies around 4K of memory, so if the internal memory of the machine is already nearly full, the OUT OF MEMORY message may be displayed. If this happens, delete any non-vital files or records or use the TIDY option in the DIARY to clear some memory space, or SAVE your files on a Datapak.

If no error message is displayed and the COMMS option does not appear, switch the machine off, remove the cable, carefully re-insert it and then try again.

The connector at the Organiser end contains a socket for the Mains Adaptor lead. You do not have to use a Mains Adaptor when using Comms Link but there are obvious advantages in doing so whenever you are conveniently near a mains socket. You are particularly advised to purchase and use a Mains Adaptor if you intend to regularly receive files to a datapack.

1.2 REMOVING THE COMMS LINK CABLE

After using Comms Link, switch off the Organiser by selecting OFF and unplug the cable. To remove the cable from the Organiser, press the click switch below the label and pull.

The software will still be stored in memory however, and should be removed by pressing ON/CLEAR to switch the machine back on and, at the top-level, pressing the ON/CLEAR key again. The COMMS option should now have disappeared from the main menu, and the memory used by Comms Link will have been freed for other uses.

If the cable is unplugged during use, a DEVICE MISSING error will be reported. For obvious reasons, this should be avoided.

1.3 BACKING-UP YOUR COMMS LINK DISK

If you have a PC and intend to connect it to your Organiser and to use the Comms Link on the disk, it is recommended that you make a copy of the Comms Link disk in case it is damaged or becomes corrupted. The original disk can then be put in a safe place, separate from the rest of your disks. When you want to use the Comms Link with the PC, you should use the copy, not the original.

If your computer has a hard disk, you might want to make a sub-directory for Comms Link called. for example, "/CL", and to copy the files on the Comms Link floppy disk to the sub-directory.

If you do not have a hard disk, you may find it more convenient to make your work disk an operating system disk, in which case you should use the "/s" option when formatting the blank disk which is to take the copy.

1.4 USING THIS MANUAL

This chapter has covered how to plug in the Organiser side of the Comms Link cable.

The following four chapters explain how to use Comms Link to connect to

  1. a printer;
  2. an IBM PC/XT/AT or compatible;
  3. any other computer with an RS232 port;
  4. a modem as a terminal to a dial-up system (e.g. Electronic Mail).

These four chapters intentionally duplicate information so that you only need to read the chapters that are relevant to you.

The final two chapters are reference-style chapters which contain a description of the software in Comms Link. Chapter 6 describes the operation of the COMMS menu and chapter 7 describes the facilities that are available via the OPL programming language. Additional technical information is provided in appendices at the end of this manual.


2. CONNECTING TO A PRINTER

2.1 THE RS232 PORT

Comms Link will connect the Organiser 2 to a printer with an RS232 or "serial" port.

Some printers (especially matrix printers) have a Centronics compatible parallel port (sometimes just called a "parallel" port and no serial port. The manufacturer of that printer may supply a card (a "serial card") which provides an RS232 port in addition to the parallel port.

As an alternative to converting your printer, you can purchase a "serial to parallel converter" which is a box with a parallel port at one end and a serial port at the other. Because the converter has to have its own power supply and housing, it will probably cost more than a serial card. However, it is an asset in its own right and may still be useful if you change printers. Converters sometimes have a reasonable amount of their own memory (called a "buffer") which will speed up the time that the organiser takes to transfer data to the printer.

Having established that you have an RS232 port on your print you need to check the type of connector on the RS232 port.

The Comms Link cable is terminated with a 25 pin D-type female connector which will plug in to the corresponding male connector (see figure 2.1).

RS232 Male and Female Connectors
Figure 2.1 Male and Female Connectors

If you have identified the serial port and it has a 25 pin D-type male connector, you may skip the rest of this section. For example, the Comms Link cable plugs straight into the connector on a Diablo 630 daisywheel printer with a serial port.

If the serial port on your printer has a 25 pin female connector, you will need an adaptor which has a 25 pin male connector at each end.

A Printer Adaptor is available from Psion, but should you wish to make up one yourself, or have one made for you, the wiring diagrams are given in appendix B, "The Comms Link Interface", at the back of this manual. This adaptor, also known as a "gender changer", converts the female connector on the printer to a male connector. Gender changers are widely available and will work with many printers. However, if your printer requires a "Carrier Detect" (pin 8 on the printer port), a simple gender changer may not work. See appendix B for more details.

If you have an RS232 printer cable which is used to connect your printer to a computer, it is unlikely to be directly suitable for use between the Comms Link connector and the printer, even if the cable will physically connect to the Comms Link connector. However, if you connect your Organiser to a modem and have a Modem Adaptor which will physically fit between the cable and the Comms Link connector, there is a good chance that the cable will be suitable. See chapter 5 or appendix B for a description of a Modem Adaptor)

2.2 SETTING THE COMMUNICATIONS PARAMETERS

At this stage, it is assumed that:

  1. you have fitted the Comms Link cable to the Organiser as described in chapter 1 and the menu item COMMS has been added to the top-level menu
  2. you have a printer with a serial port
  3. the printer either has a 25 pin D-type male connector or you have an adaptor which converts the printer connector
  4. and that the Organiser is physically connected to the printer via the Comms Link cable.

Before a printer can receive data from the Organiser, a number of basic communications parameters must be matched between the Organiser and the printer.

Select COMMS from the top-level menu and you will be presented with the COMMS menu which contains the following options:

TRANSMITTransmit a file or procedure
RECEIVEReceive a file or procedure
SETUPSet up communications parameters
TERMEnter terminal mode
AUTORun the automatic setup facility
CAPTUREEnter capture buffer menu
BOOTLoad and run a program stored on the PC

The values of the communications parameters can be set by using the SETUP option in the COMMS menu. You can find out the correct values of the communications parameters in three ways:

  1. By looking in the printer manual, understanding how to set the communications parameters on the printer, and comparing the settings of various switches with tables in the printer manual.
  2. By trying a few likely settings and seeing if they work.
  3. By using AUTO in the COMMS menu to determine most of the settings automatically and then using one of the above

The TERM test is not exhaustive, for example, it does not test that handshaking is operating between the printer and the Organiser. Handshaking is described below, under the heading of the associated parameter, HAND. If handshaking is not operating, you may lose data from the end of longer prints.

If, as is likely, the above test failed, the next section describes how to use SETUP to modify the communications parameters, followed by descriptions of the relevant parameters.

If the printer passed all the above tests, the default settings of the basic communications parameters are correct for your printer. You may wish to skip to the section, "Using Comms Link", to find out how you can use the connected printer before reading about the finer points of the relevant communications parameters. If you find that you lose data, you will probably need to change the setting of the HAND parameter.

2.3 USING SETUP

When you select the SETUP option. you are presented with a list of communications parameters with the name of the parameter on the left of the line and the current setting on the right. Initially, you will see only the first two parameters on the screen. To view the rest of the parameters, use the UP and DOWN cursor keys to scroll through the list.

The SETUP parameters and the things they set are as follows:

BAUDBaud rate
PARITYParity
BITSNumber of data bits
STOPNumber of stop bits
HANDHandshaking
PROTOCOLFile transfer protocol
ECHOLocal or remote character echo
WIDTHForced line length
TIMEOUTTime allowed waiting for connection
REOLReceive end of line character(s)
REOFReceive end of file character(s)
RTRNReceive translate character(s)
TEOLTransmit end of line character(s)
TEOFTransmit end of file character(s)
TTRNTransmit translate character(s)

The first parameter, BAUD, is the most important and nothing will work unless you get it right. You may also have to adjust PARITY, BITS and STOP before the printer will receive all characters correctly. The printer will lose data when you print a significant amount unless you correctly set HAND. Less important, but still relevant to a printer, are PROTOCOL, WIDTH, TIMEOUT, TEOL, TEOF and TTRN.

To get the printer connection working, adjust one or more of the above communications parameters using the guidance given below then try out the settings using TERM.

You can exit SETUP by pressing MODE to enter the SETUP menu, which contains the following items:

EXITExit SETUP keeping any changes
ABANDONExit SETUP discarding any changes
EDITReturn to the parameter list to continue editing
SAVESave the current SETUP
LOADLoad a previously saved SETUP
DIRRead the directory of saved SETUPs
ERASEErase a previously saved SETUP
RESETReset to the default SETUP settings

Pressing EXE selects the EXIT item which exits SETUP making the adjusted parameters current. If you wish to use the current values then it is a good idea to select the SAVE option first, to save your setup to a file. The values can then be restored at any time in the future by using the LOAD command.

If you have been experimenting within the SETUP parameter editor, it is a good idea to set all the parameters back to their original values, using the RESET command, before reading on.

To edit a parameter value, first select the parameter using the UP and DOWN keys. The selected parameter is indicated with the right arrow symbol after the parameter name. Change the selected parameter either by pressing RIGHT and LEFT to select a value from a list of values or by pressing EXE and then by entering a value. Which method you use depends upon which parameter you are changing; see below, under the relevant parameter heading. Pressing ON/CLEAR sets the selected parameter to its original value.

2.4 BAUD

The BAUD parameter specifies the Baud rate. This is the rate at which data is sent to the printer and it must be set to match the Baud rate of your printer. When BAUD is selected, press RIGHT and LEFT to change its value.

The Baud rate specifies the data transfer rate in bits per second. In most cases, dividing by 10 gives the transfer rate in characters per second. Using a faster Baud rate will not necessarily speed up printing from the Organiser. For example, 1200 Baud corresponds to 120 characters per second, which is a lot faster than most printers are able to print.

If you do not know the Baud rate on your printer or you are unable to figure it out from the printer manual, the most likely settings are 9600 and 1200.

2.5 PARITY, BITS And STOP

When data is sent down the RS232 line, it is sent one bit at a time (rather than a character at a time) and the PARITY, BITS and STOP parameters specify how each character is converted into a pattern of bits. You do not have to understand what these parameters mean (see chapter 7 if you are interested) but, as with BAUD, they have to match the corresponding parameters in your printer.

All three parameters are changed in the same way as for BAUD, by pressing RIGHT and LEFT.

The STOP parameter sets the number of stop bits and may be set to 1 or 2. Change the STOP parameter to 2. Even if your printer is set to use 1 stop bit, it will still work with 2. The converse is not true.

The BITS parameter specifies the number of data bits in each character and may be set to 7 or 8.

The PARITY parameter determines whether each character includes an additional bit (the parity bit) and, if so, what the rule is for its value. When used, the parity bit normally represents a simple form of error checking. Although the PARITY parameter may be set to five different values, MARK and SPACE are rarely used. The settings which you should try are NONE (which means there is no parity bit), EVEN and ODD in order of commonest use.

If you get the BITS and PARITY settings wrong, the printer should still print something but some characters (often about half the characters) are printed incorrectly.

A good strategy is to set STOP to 2, try out a few BAUD settings, and identify which one gives you some activity. Having established the Baud rate, try out a few settings for BITS and PARITY. The three most likely settings are:

BITSPARITY
8NONE
7ODD
7EVEN

Note that some manufacturers include the parity bit in their definition of the data bits. This means that they would call seven data bits and a parity bit eight data bits.

2.6 HAND

Printers cannot keep up with the rate at which the Organiser can transmit data and there needs to be a means of holding the Organiser up when the internal memory of the printer (its buffer) fills up. This is called "handshaking" or "flow control". The handshaking method used by the Organiser is set by the HAND parameter. Although the Organiser can be set to any combination of three different handshaking methods (8 choices in all), only two of these are in common use by serial printers.

The first is "DTR handshaking", so called because it uses the DTR (Data Terminal Ready) control pin on the RS232 port. The DTR pin is set high by the printer when it is ready to receive data and low when its buffer is too full.

The second is called "XON/XOFF handshaking" and is based on the printer sending control characters to pause (XOFF) and restart (XON) the Organiser. The ASCII names for the control characters used are DC1 and DC3 (the "DC" stands for "Device Control") and so "DC 1/DC3 handshaking" means the same thing.

Most serial printers support both the above methods of handshaking so, if you do not know which is set on your printer, the safest setting of HAND to use is XON+DTR. Setting HAND to NONE will not stop your printer from working at all but you will lose data when you transmit more than the printer can hold in its internal buffer.

2.7 PROTOCOL

The PROTOCOL parameter sets the file transfer protocol which is used by the TRANSMIT and RECEIVE commands. Although receiving a file is not possible with a printer, the TRANSMIT command may be used to print data files provided that the PROTOCOL parameter is set to NONE. Use LEFT and RIGHT to change the setting.

2.8 WIDTH

The WIDTH parameter can be used to stop your printer from printing off the right hand edge of the paper. By default, WIDTH is set to NONE and no checks are made on the length of a transmitted line. If you set WIDTH to, say, 70 the Organiser will insert a new line if the number of transmitted characters in one line reaches that limit.

You may find that your printer already performs this function or that you never output lines that long. In this case, you can leave WIDTH set to NONE.

The WIDTH parameter is one of the parameters which are not set by pressing the RIGHT and LEFT keys. To change WIDTH, press EXE when WIDTH is the selected parameter and enter the new value by typing the number followed by pressing EXE again. The maximum line length is 250 characters.

2.9 TIMEOUT

Assuming HAND is set properly, if you attempt any print operation while the printer is "off line" or out of paper, the Organiser will wait indefinitely if TIMEOUT is set to its initial value, NONE.

However, you can use the TIMEOUT parameter to make print operations, for example, the OPL command LPRINT, fail after the printer has been paused for a specified timeout interval. This feature is only really useful when you are writing a secure OPL program which will inform the program user when a printer has been paused for a suspiciously long time.

For normal use, you can leave the TIMEOUT parameter set to NONE. You may always escape by putting the printer "on line" by inserting more paper if necessary, or by pressing ON/CLEAR to abort the operation.

The TIMEOUT parameter is set in the same way as the WIDTH parameter. The number you enter should be between 1 and 255 and specifies an approximate timeout interval in seconds.

2.10 TEOL

The TEOL parameter specifies the one or two characters which are sent by the Organiser to indicate the end of a line. Initially, this is set to <CR><LF> (a carriage return followed by line feed) and this will be correct for most printers.

It is possible that your printer will be set to automatically perform a line feed whenever it receives a carriage return, in which case you will get two line feeds at the end of each line and your printed output will be double spaced. If you prefer not to change the setting on your printer, you can change TEOL from <CR><LF> to just <CR>.

TEOL is changed in a similar way to WIDTH and TIMEOUT. Press EXE when TEOL is the selected parameter and enter the number 13 (the ASCII code for <CR>) followed by pressing EXE again.

2.11 TEOF

The TEOF parameter specifies the one or two characters which are sent by the Organiser to indicate the end of a file when using TRANSMIT under the COMMS menu. Initially, this is set to <SUB> (also called CONTROL-Z) and has the ASCII value of 26.

If you wish to use TRANSMIT to print data files (as described at the end of this chapter), you should set TEOF to NONE.

To clear TEOF, press EXE when TEOF is the selected parameter and press EXE again without entering any data.

TTRN

The TTRN parameter provides the means to translate a particular transmitted character to another character or to remove transmitted characters Initially, TTRN is set to NONE and no translation occurs.

The most common use of TTRN is to translate the <TAB> control character (with ASCII code 9) which is used to separate fields in Organiser data files into a printable character, for example, a comma.

To set TTRN to translate every occurrence of <TAB> to a comma (ASCII 44), press EXE when TTRN is the selected parameter and enter 9,44 EXE

AUTO

If you have failed to find a set of communications parameters which works with your printer, the AUTO command provides an aid to determining BAUD, PARITY, BITS and STOP. The command cycles through all combinations of BAUD, PARITY, BITS and STOP (omitting only MARK and SPACE parity) transmitting a line of text for each combination. The text contains a message which identifies the four parameters so that if your printer receives the text without corruption, you can read the correct values of the parameters to use in SETUP.

While the program is running, the display continuously shows the combination of the parameters which is currently being transmitted. Press ON/CLEAR to abort AUTO when you are satisfied that you have the correct values, then enter these using SETUP. If you leave AUTO running, it will return to the COMMS menu when it has tried every combination.

AUTO does nothing to help set the handshake parameter, HAND. Getting the HAND parameter wrong will not stop the printer from working altogether - you will just lose data from the end of longer prints.

2.14 PRINTING WITH COMMS LINK

When the communications parameters have been set up correctly so that text can be successfully sent to the printer, you can use the printer in the following ways:

  1. to print procedure files
  2. to print data files
  3. to print the contents of the capture buffer
  4. to print using an OPL program

2.15 PRINTING PROCEDURE FILES

To print the text of an OPL procedure, use the LIST item in the PROG menu. You cannot print a procedure file which has been copied as "object only".

From the top-level menu, select PROG to view the PROG menu, and then select LIST. The screen will show:

LIST A:

If necessary, press MODE to change the device shown and type the name of a procedure you wish to print. When you press EXE the text of the procedure will be sent via the Comms Link cable to the printer. If the file does not exist on the device shown, or if only the object code of the procedure is saved, then an error message will be displayed. In this case, press SPACE to return to the PROG menu.

If the file is found and transmitted successfully, you will be returned to the PROG menu.

2.16 PRINTING DATA FILES

To print any data file stored in the Organiser, including the file MAIN which is used by the top-level FIND and SAVE facilities, use TRANSMIT from the COMMS menu. As described above, both the PROTOCOL and TEOF parameters must be set to NONE.

Select FILE to transmit a data file and the screen will show:

FILE PROCEDURE

Select FILE to transmit a data file and the screen will show:

SEND A:MAIN

The default file name will be MAIN unless you have previously specified a file name in file transfer, in which case that name will be given instead. If necessary, press MODE to change the device shown and edit the name of the file to be printed.

Press EXE and the file will be sent to the printer.

Data files are stored in the Organiser using a TAB character to separate adjacent fields within records. When you print a file, the TAB character will be printed in between the fields in each record. Depending on the content of your data tile and the way your printer responds to TABs, this may produce an unacceptable layout. You can change the way data files appear on the printed page by setting TTRN such that TAB characters are translated into another character, as was described under TTRN, above.

If you require more control than is possible using TTRN, you can use LPRINT statements in an OPL procedure to produce any layout required. An example OPL procedure is given at the end of this chapter.

2.17 PRINTING THE CAPTURE BUFFER

The capture buffer is normally used when the Organiser is acting as a terminal to a multi-user computer, for example, an electronic mail service. The capture buffer may be used to store a previously prepared message which can then be transmitted. This usage is described in chapter 5, "Terminal Emulation".

To print the contents of the capture buffer, select CAPTURE from the COMMS menu and the CAPTURE menu will be displayed. Select TRANSMIT from this menu and the contents of the capture buffer will be sent to the printer. You will then be returned to the CAPTURE menu.

Press ON/CLEAR to return to the COMMS menu.

2.18 PRINTING FROM OPL

As you saw earlier, it is quite simple to send a data file to the printer using the TRANSMIT option in the COMMS menu. However, this does not produce a neatly formatted print-out. The way to exercise control over the format of the printing of data files is to use the LPRINT command in OPL.

Below is an example of a program which will operate on the data file with name "MAIN" (the file used by the top-level FIND and SAVE facilities) stored either in the internal memory or on a Datapak. To use the program, type it in, translate and save it as described in chapter 18 of your main Organiser user manual.

When the program is run, it first prompts for the device containing the MAIN file to be printed. You should enter A, B or C. Given a device name it then prints all the records in the MAIN file on that device with the fields of each record on separate lines. Records are separated by a blank line.

This program is designed for printing out an unstructured data file where the number of fields and the meaning of each field varies from record to record. This is often the case for the MAIN file. The program assumes that no record contains more than eight fields. Blank fields are not printed.

You can either use the program directly or use it as a basis for a more refined program which is more suited to the structure of your data. For example, you may wish to change the maximum number of fields or to include a selection criterion to print only the records which satisfy a particular condition.

MPRINT: LOCAL A$( 1) PRINT "Device:"; INPUT A$ OPEN A$+":MAIN",A,F1$,F2$,F3$,F4$,F5$,F6$,F7$,F8$ DO IF LEN(A.F1$) :LPRINT A.F1$ :ENDIF IF LEN(A.F2$) :LPRINT A.F2$ :ENDIF IF LEN(A.F3$) :LPRINT A.F3$ :ENDIF IF LEN(A.F4$) :LPRINT A.F4$ :ENDIF IF LEN(A.F5$) :LPRINT A.F5$ :ENDIF IF LEN(A.F6$) :LPRINT A.F6$ :ENDIF IF LEN(A.F7$) :LPRINT A.F7$ :ENDIF IF LEN(A.F8$) :LPRINT A.F8$ :ENDIF LPRINT NEXT UNTIL EOF CLOSE


3. CONNECTING TO A PC

This chapter describes how Comms Link may be used to connect your Organiser to an IBM PC/XT/AT or compatible which is running the supplied Comms Link software. If your computer does not fall into this category you should skip to the following chapter.

The advantages of using the Comms Link software on the PC, compared to some other communications program, are:

  1. There are fewer communications parameters to set.
  2. The communication is based on an error-checked framing protocol with a negligible chance of receiving corrupted data even when using modems over a dial-up line.
  3. The advanced protocol allows communication to be controlled entirely from the Organiser so that you can, for example receive a tile from an unattended PC which is running the Comms Link software.
  4. Comms Link provides the basis for advanced communications applications such as loading spreadsheet files from your PC (when used with the Organiser Pocket Spreadsheet).
  5. Comms Link allows you to write OPL programs which transfer files (including binary files) between the Organiser and the PC, or to access remote PC files directly from the Organiser.

The facilities which are available via OPL are described in chapter 7, "Comms Link and OPL".

3.1 THE RS232 PORT

Check that your PC has an RS232 port. The term "serial port" is often used, and means the same thing.

The IBM PC, XT and AT do not have an RS232 port as standard, it is an optional extra. If your PC does not have an RS232 port, you can buy one from your dealer on a plug-in "card". Some IBM compatibles also do not have an RS232 port as standard - these too may be fitted with one on a plug-in card. If in doubt, see your dealer for details. Many IBM compatibles, however, are supplied with an RS232 port as a standard fitting.

Having established that you have an RS232 port on your PC, you need to check the type of connector on the RS232 port.

The IBM PC and XT RS232 port, and that on almost all compatibles, has a 25 pin D-type male connector and the Comms Link cable is designed to connect directly to these computers.

The IBM AT RS232 port, and that of some AT compatibles, has a 9 pin D-type male connector.

If you have an IBM AT or a compatible with a 9 pin RS232 connector, you will need an AT Adaptor. The AT Adaptor is a cable with a 25 pin male connector at one end and a 9 pin female connector at the other.

The AT Adaptor is available from Psion, but should you wish to make up one yourself, or have one made for you, the wiring diagrams are shown in an appendix at the back of this manual. If you already use your AT or compatible with a modem, you can use the same cable to connect it to the Organiser.

3.2 SETTING THE COMMUNICATIONS PARAMETERS

You should have fitted the Comms Link cable to the Organiser as described in the Introduction to this manual. This will add a new item, COMMS, to the top-level menu.

Select COMMS from the top-level menu and you will be presented with the COMMS menu which contains the following options:

TRANSMITTransmit a file or procedure
RECEIVEReceive a file or procedure
SETUPSet up communications parameters
TERMEnter terminal mode
AUTORun the automatic setup facility
CAPTUREEnter capture buffer menu
BOOTLoad and run a program stored on the PC

3.3 USING SETUP

Before attempting to communicate with the PC, select the SETUP option from the COMMS menu. When you select SETUP, you are presented with a list of communications parameters. The list is arranged with the name of the parameter on the left of the line and the current setting on the right. Use the UP and DOWN cursor keys to scroll up and down the list.

The SETUP parameters and the things they set are as follows:

BAUDBaud rate
PARITYParity
BITSNumber of data bits
STOPNumber of stop bits
HANDHandshaking
PROTOCOLFile transfer protocol
ECHOLocal or remote character echo
WIDTHForced line length
TIMEOUTTime allowed waiting for connection
REOLReceive end of line character
REOFReceive end of file character
RTRNReceive translate character
TEOLTransmit end of line character
TEOFTransmit end of file character
TTRNTransmit translate character

To edit a parameter value, first select the parameter using the UP and DOWN keys. The selected parameter is indicated with the right arrow symbol after the parameter name. Change the selected parameter either by pressing RIGHT and LEFT to select a value from a list of values or by pressing EXE and then by entering a value. Which method you use depends upon which parameter you are changing. This is described below under the relevant parameter heading.

Pressing ON/CLEAR sets the selected parameter to its original value.

Only five of the SETUP parameters are relevant to communications with a PC running the Comms Link software. The relevant parameters are BAUD, HAND, PROTOCOL, RTRN and TTRN.

3.4 BAUD

The BAUD parameter specifies the Baud rate. This is the rate at which data is transferred between the Organiser and the PC and it must be set to match the Baud rate used by the Comms Link program (CL) on the PC.

If you are connecting the Organiser direct to the PC, rather than via a pair of modems, the BAUD parameter should be set to 9600 (the highest value).

If you are connecting to the PC via modems, the BAUD parameter must be set to the Baud rate at which the modems are set to operate. If the modems are operating over a dial-up line, the Baud rate will typically be either 2400, 1200 or 300.

Make sure BAUD is selected, then press RIGHT and LEFT to change it to the desired value.

The Baud rate specifies the data transfer rate in bits per second. Dividing by 10 gives the approximate transfer rate in characters per second.

3.5 HAND

The Comms Link protocol contains its own flow control, so handshaking is only required to provide the necessary control signals for modem operation.

Setting the HAND parameter to RTS+DTR (by using LEFT and RIGHT to change the setting) will work both when connected directly and when connected via a modem.

3.6 PROTOCOL

The PROTOCOL parameter sets the file transfer protocol which is used by the TRANSMIT and RECEIVE commands and should be set to PSION (by using LEFT and RIGHT to change the setting).

3.7 RTRN And TTRN

RTRN and TTRN stand for Receive Translate and Transmit Translate and, in communications involving the Comms Link PC software, are only applied to file transfers to and from data files and procedure files on the Organiser. RTRN and TTRN are ignored in transfers involving binary files.

RTRN and TTRN are typically used to translate <TAB> characters in data files, which separate adjacent fields in a record, to a more convenient delimiter, For example, to convert <TAB>s to a comma and vice versa, set TTRN to translate <TAB> to comma (ASCII 44) by pressing EXE when TTRN is the selected parameter. Then type:

9,44 EXE

Now select RTRN to translate comma to <TAB>. Press EXE and type:

44,9 EXE

Initially, RTRN and TTRN are set to NONE and no translation occurs.

3.8 LEAVING SETUP

When BAUD, HAND, PROTOCOL, RTRN and TTRN have been set, press the MODE key and a menu containing the following items is presented:

EXITExit SETUP keeping any changes
ABANDONExit SETUP discarding any changes
EDITReturn to the parameter list to continue editing
SAVESave the current SETUP
LOADLoad a previously saved SETUP
DIRRead the directory of saved SETUPs
ERASEErase a previously saved SETUP
RESETReset to the default SETUP settings

Select EXIT from this menu and you will be returned to the COMMS menu. However, you may wish to select the SAVE option first, to save your setup to a file. The values can then be restored at any time in the future by using the LOAD command.

3.9 MAKING THE CONNECTION

At this stage, it is assumed that:

  1. you have a PC with a serial port
  2. the PC has a 25 pin D-type male connector or you have an adaptor which converts it to that connector
  3. you have copied the Comms Link program from the supplied disk to either a new floppy disk or to a hard disk
  4. you have set the communications parameters under the SETUP option in the COMMS menu as described above

Direct Connection

Plug the Comms Link cable into the PC. Run the Comms Link program on the PC in the normal way by typing: CL ENTER where the current drive (and directory, if you have a hard disk) contains the Comms Link software. If you have a hard disk, you may find it more convenient to use the DOS command PATH to set up a path to the Comms Link directory. The PATH command should be used in your AUTOEXEC.BAT file which will then allow you to run CL from any directory. See your DOS manual for details on how to do this.

After a short pause, the program display will appear and the PC and your Organiser are ready to communicate.

As a general rule, when running the Comms Link program from a floppy disk, you should not remove the floppy disk containing the Comms Link program at any time.

When you have finished communicating with the PC, press Q on the PC keyboard to quit the Comms Link program. You will be prompted to confirm that you want to exit the program altogether; press Y to quit or N to continue using Comms Link.

Note that you cannot quit the Comms Link program on the PC while a file is being transmitted or received.

Connecting Via A Modem

A typical connection between a PC and an Organiser via a telephone is illustrated in figure 3.1:

Connecting via Modems
Figure 3.1 Connecting via Modems

The modems are necessary to convert the data from the PC and the Organiser into a form suitable for transmission over a telephone line.

An arrangement like this, where the PC is attached to a modem and a telephone line, say, at the office, allows you to dial in to the PC from another telephone and transfer files between the PC and your Organiser. In this case, you would leave your PC switched on and running the CL program and leave the modem connected to your PC in auto answer mode. The modem which is connected to the Organiser may be an acoustic coupled modem (where the connection to the telephone line is made via a pair of rubber cups which fit over the telephone handset) or it may plug directly into a telephone socket.

To connect the Comms Link cable to the modem you will need a Modem Adaptor. These are available from Psion. Alternatively, if you want to make one up yourself, or have one made for you, the wiring details may be found in an appendix at the back of this manual.

When you run the Comms Link program on the PC, you must specify the Baud rate that the modems are set to. For example, to run the Comms Link program with a Baud rate of 1200, type:

CL 1200 ENTER

If you do not specify a Baud rate when running the Comms Link program, the default setting is 9600.

3.10 TRANSFERRING FILES

At this stage, it is assumed that:

  1. your PC is running the CL program
  2. your Organiser is either connected directly to the PC or it is connected to a modem and you have successfully dialled up the modem which is connected to your PC.

You may now use the TRANSMIT and RECEIVE options in the COMMS menu to transfer files between the two computers. The only file transfer available using the RECEIVE and TRANSMIT commands is between simple text files on the PC and either data files or procedure files on the Organiser. (On the PC, text files consist of a number of lines where each line is terminated by <CR><LF>.)

Binary files, for example DIARY files, can be transferred using the PSION protocol but you have to write an OPL program to make the transfer. See chapter 7, "Comms Link and OPL", for a description of using Comms Link facilities from OPL. A simple example of using OPL to backup DIARY files to a PC and to restore them is given at the end of this chapter.

When you select either RECEIVE or TRANSMIT, the screen will show

FILE PROCEDURE

This is a small menu, from which a selection can be made in the usual way. Select FILE to receive or transmit a data file and PROCEDURE to receive or transmit a procedure file.

Data Files

Data files consist of a number of records where each record may be split into fields. Records contain up to 254 characters and fields are delimited by the <TAB> character (ASCII 9). Each data file record corresponds to a line within the text file on the PC.

If, when receiving a data file, the remote file contains lines longer than 254 characters, the RECEIVE command will fail. Incoming <TAB> characters will divide the records into separate fields. Alternatively, the <TAB> characters may be generated by the RTRN option as was described earlier.

An Organiser data file record may not be empty. Any received blank lines are saved as a record containing a single space character (ASCII 32).

Procedure Files

When procedure files are transmitted using the TRANSMIT command, only the source is transmitted. When procedure files are received using the RECEIVE command, a file is created which contains the source only (i.e., no object). You have to translate the procedure (using the IRAN option in the procedure editor under the PROG menu) before you can run a received procedure.

The first line of a procedure consists of a procedure name followed by a colon and optionally followed by the procedure parameters. When procedures are created under the top-level PROG command, the procedure file name will match the name on the first line. When you receive a procedure, however, the file name may not match the name on the first line.

It is the procedure file name which is significant when you invoke a procedure in an OPL program, not the name which appears on the first line. (When you edit a procedure on the Organiser, the name of the fist line is changed, if necessary, to agree with the procedure file name.) When receiving a procedure you should be mindful of the significance of the file name when choosing it.

RECEIVE

When using RECEIVE and after selecting PROCEDURE, the screen will show the prompt:

RECV A:

Press the MODE key to change the device shown, if necessary. You may now type in the name of the file which is to take the received data. The file name must, as usual, be no longer than eight characters. If you have previously specified a file name in file transfer, that name will be given as a default.

If you specify a file name which already exists, the display will show:

A:FNAME EXISTS   DELETE Y/N

where FNAME is the procedure file name which was specified. If you press N you are returned to the previous screen and may now type in a different file name, or press ON/CLEAR to abort the transfer. Press Y and the old procedure will be deleted and replaced by the incoming file.

If, when receiving a procedure, the first line does not contain a colon, a first line is inserted consisting of a question mark followed by a colon. If the received data contains one or more ASCII control characters (i.e. with ASCII codes which are less than 32) and except for REOL and REOF characters, the RECEIVE command will fail with a BAD PROCEDURE message.

When using RECEIVE and after selecting FILE, the screen will show the prompt:

RECV A:MAIN

The default file name will be MAIN unless you have previously specified a file name in file transfer, in which case that name will be given instead. You can either accept the default or press ON/CLEAR to clear the input and type another name in.

If you select the FILE option and you specify a file name which already exists and which contains data, the display will show:

ERASE APPEND

This is another small menu. If ERASE is selected, the incoming file will replace the old data file of that name and its original contents will be lost. If the file being erased contains a large number of records, this may take some time. If the APPEND option is selected, the data in the incoming file will be appended to the original file.

After you enter the file name, the display will then prompt for the name of the file on the PC:

RECV A:FNAME   FROM:FNAME

where you are offered the same name as a default file name for the PC. Either accept the default or enter a different PC file name (and path name, if required). If you do not include a path name, the directory which was current when you ran Comms Link will be used on the PC. Since PC path names use the backslash character (\) which cannot be entered from the Organiser keyboard, you should use the forward slash (/) instead. Forward slashes are converted to backslashes by the PC software. Also, as the default name may contain a percent character (%), which is not allowed in PC file names, the PC software converts any percent characters in the file name to an underscore character (_). If the file does not exist on the PC, a FILE NOT FOUND error is displayed and you are given another opportunity to enter the PC file name.

While data is being received, the screen will show:

Receiving...

If the file transfer is unsuccessful, one of the following error messages will be displayed:

TIMEOUT - a timeout occurred waiting for a response, possibly indicating that a lead is disconnected, that CL is not running on the PC, or that there have been too many transmission errors (due to a very noisy line).

SERVER FAILURE - some other server (i.e. the CL program) failure occurred. For example, a disk door is open.

If possible, look at the PC display for further details of any failure.

TRANSMIT

When using TRANSMIT and after selecting PROCEDURE, the screen will show the prompt:

SEND A:

If you have previously specified a file name in file transfer, that name will be given as a default. Press the MODE key to change the device, if necessary, and enter the name of the file which is to be transmitted.

As with RECEIVE, selecting TRANSMIT then FILE offers as a default the file name you have most recently specified in file transfer. If it is your first file transfer operation the default file name MAIN is offered:

SEND A:MAIN

Press EXE to accept the default or press ON/CLEAR to clear the input and enter another name.

If the file is not found, a FILE NOT FOUND message will be displayed.

After you enter the Organiser file name, the display will then prompt for the PC file name:

SEND A:FNAME   TO:FNAME

where you are offered the same name as a default file name for the PC. Either accept the default or enter a PC file name (and path name, if required). If you do not include a path name, the directory which was current when you ran Comms Link will be used on the PC. Since PC path names use the backslash character (\) which cannot be entered from the Organiser keyboard, the forward slash (/) should be used instead. All forward slashes are converted into backslashes by the PC software. Also, as the default name may contain a percent character (%), which is not allowed in PC file names, the PC software converts any percent characters in the file name to an underscore character (_).

If the file already exists, the display will show:

FNAME EXISTS   DELETE Y/N

Press Y and the existing file will be replaced. If you press N you are given another opportunity to enter the PC file name; type in a different file name or press ON/CLEAR to escape.

While data is being transmitted, the screen will show:

Sending...

If the file transfer is unsuccessful, it will display one of the following error messages:

TIMEOUT - a timeout occurred waiting for a response, possibly indicating that a lead is disconnected, that CL is not running on the PC, or that there have been too many transmission errors (due to a very noisy line).

SERVER FAILURE - some other server (i.e. the CL program) failure occurred. For example, a disk door is open.

If possible, look at the PC display for further details of any failure.

3.11 TRANSFERRING DIARY FILES

The following example procedure, DBACK, may be used to backup and restore saved DIARY files to and from the PC. The current contents of the diary may be saved to a file using the SAVE option in the DIARY menu (see the main Organiser operating manual for more details).

When you wish to view the diary file, transfer the file back to the Organiser and use the RESTORE option in the DIARY menu (remember to SAVE you current diary first)

To use the program, type it in, translate and save it as described in chapter 18 of your main Organiser user manual.

When the program is run, it first presents the two item menu BACKUP or RESTORE. When you have made your selection it prompts for the local (Organiser) and remote (PC) file names, in the appropriate order. For the local name, you should enter the device, A, B or C, followed by a colon and the saved diary file name.

Pressing ON/CLEAR during the input stage will abort the program.

DBACK: LOCAL lname$(8),rname$(8),m% m%=MENU("BACKUP,RESTORE") IF m%=1 PRINT "FROM"; TRAP INPUT lname$ :IF ERR=206 :RETURN :ENDIF PRINT "TO"; TRAP INPUT rname$ :IF ERR=206 :RETURN :ENDIF XTSEND:(rname$,lname$,2) ELSEIF m%=2 PRINT "TO"; TRAP INPUT lname$ :IF ERR=206 :RETURN :ENDIF PRINT "FROM"; TRAP INPUT rname$ :IF ERR=206 :RETURN :ENDIF XTRECV:(rname$,lname$,2) ENDIF


4. CONNECTING TO ANY COMPUTER

This chapter describes how Comms Link may be used to connect to any computer which has an RS232 port. Although the IBM PC/XT/AT and compatibles fall into this category and everything in this chapter does apply to these computers, you are better off using the facilities which are available when the supplied Comms Link PC software is used, as described in the previous chapter.

Before you can use Comms Link to transfer files between the organiser and your computer, you will need communications software for your computer. That communications software should support one or preferably both of the following services:

  1. Terminal emulation with the ability to upload and capture files
  2. XMODEM file transfer

These services may be provided by a specialised communications program or as part of an integrated software package. As an alternative to the first item above, and if the operating system on your computer is sufficiently advanced, you may be able to configure the serial port and to copy to and from the serial port using the operating system commands.

4.1 THE RS232 PORT

Check that your computer has an RS232 port. The term "serial port" is often used, and means the same thing.

If your computer does not have an RS232 port as standard, you may be able to buy one from your dealer as an add-on or a plug-in "card".

Having established that you have an RS232 port on your computer, you need to check the type of connector on the RS232 port.

The Comms Link cable is terminated with a 25 pin D-type female connector which will plug into the corresponding male connector (see figure 4.1).

RS232 Male and Female Connectors
Figure 4.1 MALE and FEMALE Connectors

If the RS232 on your computer has a 25 pin female connector, you will need an adaptor which has a 25 pin male connector at each end. Such an adaptor, which converts a female connector to a male connector, is called a "gender changer" and is widely available. Psion supplies a suitable adaptor under the name "Printer Adaptor", as many printers require an identical adaptor when connecting to the Organiser.

If the RS232 port is not a 25 pin D-type connector of either gender, you will need an adaptor, specific to your computer, which converts its RS232 to a 25 pin D-type male connector. Psion produce a range of adaptors (including one for the Apple Macintosh), one of which may be right for your computer. Otherwise your dealer may be able to supply a suitable adaptor or make up an adaptor for you. The Comms Link cable presents the same interface as a modem, and a cable which is suitable for use between your computer and a modem will also be suitable for connecting to Comms Link. The required pin assignments for the Organiser are given in an appendix at the back of this manual.

When you have an appropriate connector to make the physical connection between the Organiser and the other computer, plug the two together. The next job is to set up the communications software at each end of the Comms Link cable.

4.2 SETTING THE COMMUNICATIONS PARAMETERS

Before communication can take place with the other computer, various communications parameters must be set at both ends of the communications link.

You should have fitted the Comms Link cable to the Organiser as described in the Introduction to this manual. This will add a new item, COMMS, to the top-level menu.

Select COMMS from the top-level menu and you will be presented with the COMMS menu which contains the following options:

TRANSMITTransmit a file or procedure
RECEIVEReceive a file or procedure
SETUPSet up communications parameters
TERMEnter terminal mode
AUTORun the automatic setup facility
CAPTUREEnter capture buffer menu
BOOTLoad and run a program stored on the PC

4.3 USING SETUP

Select the SETUP option from the COMMS menu and you are presented with a list of communications parameters. The list is arranged with the name of the parameter on the left of the line and the current setting on the right. Use the UP and DOWN cursor keys to scroll up and down the list.

The SETUP parameters and the things they set are as follows:

BAUDBaud rate
PARITYParity
BITSNumber of data bits
STOPNumber of stop bits
HANDHandshaking
PROTOCOLFile transfer protocol
ECHOLocal or remote character echo
WIDTHForced line length
TIMEOUTTime allowed waiting for connection
REOLReceive end of line character(s)
REOFReceive end of file character(s)
RTRNReceive translate character(s)
TEOLTransmit end of line character(s)
TEOFTransmit end of file character(s)
TTRNTransmit translate character(s)

To edit a parameter value, first select the parameter using the UP and DOWN keys. The selected parameter is indicated with the right arrow symbol after the parameter name. Change the selected parameter either by pressing RIGHT and LEFT to select a value from a list of values or by pressing EXE and then by entering a value. Which method you use depends upon which parameter you are changing. This is described below under the relevant parameter heading.

Pressing ON/CLEAR sets the selected parameter to its original value.

Most of the SETUP parameters are relevant to communications with a computer. The parameters you are unlikely to be concerned with are ECHO, WIDTH and TIMEOUT. If you do need to use or change them, they are described chapter 6, "The Comms Menu".

4.4 BAUD

The BAUD parameter specifies the Baud rate. This is the rate at which data is transferred between the Organiser and the computer and it must be set to match the Baud rate on the communications program you are using.

If you are connecting the Organiser direct to the computer, rather than via a pair of modems, the BAUD parameter should be set to 9600 (the highest value).

If you are connecting to the computer via modems, the BAUD parameter must be set to the Baud rate at which the modems are set to operate. If the modems are operating over a dial-up line, the Baud rate will typically be either 2400, 1200 or 300.

When BAUD is selected, press RIGHT and LEFT to change its value.

The Baud rate specifies the data transfer rate in bits per second. Dividing it by 10 gives the approximate transfer rate in characters per second.

4.5 PARITY, BITS AND STOP

When data is sent down the RS232 line, it is sent one bit at a time (rather than a character at a time) and the PARITY, BITS and STOP parameters specify how each character is converted into a pattern of bits. You do not have to understand what these parameters mean (see chapter 7 if you are interested) but, as with BAUD, they have to match the corresponding parameters set by the communications program which you are using.

All three parameters are changed in the same way as for BAUD, by pressing RIGHT and LEFT.

The STOP parameter sets the number of stop bits and may be set to 1 or 2.

The BITS parameter specifies the number of data bits in each character and may be set to 7 or 8.

The PARITY parameter determines whether each character includes an additional bit (the parity bit) and, if so, what the rule is for its value. When used, the parity bit normally represents a simple form of error checking. Although the PARITY parameter may be set to five different values, MARK and SPACE are rarely used.

Since you have the freedom to modify PARITY, BITS and STOP on both sides of the link, you can use any values you like. We recommend that you use the Comms Link default values:

PARITYNONE
BITS8
STOP1

Note that some manufacturers include the parity bit in their definition of the data bits. This means that they would call seven data bits and a parity bit eight data bits.

4.6 HAND

The HAND parameter controls the handshaking methods to be used by the Organiser. Handshaking (also called "flow control" or "buffer control") is a means by which either end of the communications link can pause and restart data transmission from the other.

The Organiser supports three different kinds of handshaking; XON/XOFF, RTS/CTS and DTR. Each of these may be enabled or disabled.

DTR handshaking is only suitable for printers so, for Organiser to computer communications, either XON/XOFF or RTS/CTS handshaking should be used, particularly when XMODEM file transfer is not being used. The choice may be made by hardware limitations on the computer; for example, the Apple Macintosh does not support RTS/CTS handshaking. If the Organiser is connected to the computer via modems, RTS/CTS handshaking only operates between the Organiser and the modem and XON/XOFF handshaking should also be used to provide "end to end" handshaking.

The XMODEM file transfer protocol does provide its own flow control and will operate when the HAND parameter is set to NONE. When the Organiser is connected directly to the computer, RTS/CTS handshaking is still recommended as the file transfer will be more efficient.

Press the RIGHT and LEFT cursor keys to change the value of the HAND parameter. When HAND is set to NONE, no handshaking takes place. When HAND is set to ALL, all three handshaking modes are enabled. Otherwise one or two are enabled, as suggested by the value.

See chapter 6, "The Comms Menu", for more details on the handshaking methods.

4.7 PROTOCOL

The PROTOCOL parameter selects the file transfer protocol which is used by the TRANSMIT and RECEIVE commands and should either be set to NONE or XMODEM (use LEFT and RIGHT to change the setting).

The XMODEM protocol provides the better file transfer service, since it includes error checking, but can only be used if your communications program supports XMODEM file transfer. Error checking is a significant advantage when the transfer occurs over dial-up lines, using modems.

Using PROTOCOL set to NONE provides a more primitive file transfer with no error checking.

4.8 REOL and TEOL

REOL and TEOL stand for Receive End Of Line and Transmit End Of Line. They both define the ASCII sequence of characters which define an end of line. During file transfer, TEOL is sent at the end of transmitted data records and procedure lines and REOL is used to recognise the end of received data records and procedure lines.

You should set both REOL and TEOL to the line terminator which is used by text files on your computer. TEOL and REOL would normally be set to a combination of <CR> (ASCII 13) and <LF> (ASCII 10) and it is likely that the default value of <CR><LF> is correct for your computer.

To change TEOL or REOL, press EXE when TEOL or REOL is the selected parameter and enter the new value by typing the ASCII code of the new terminator followed by pressing EXE again. If the required terminator contains two characters rather than a single character, enter the ASCII codes of the two characters, separated by a comma.

4.9 REOF and TEOF

REOF and TEOF stand for Receive End Of File and Transmit End Of File. They both define the ASCII sequence of characters which define an end of file when using file transfer.

The REOF sequence is used by the Organiser to recognise an end of file when receiving a file using the RECEIVE command. The TEOF sequence is sent by the Organiser to signal an end of file to the communicating device when transmitting a file using the TRANSMIT command.

The correct values for REOF and TEOF depends on the computer and the communications software. However, it is likely that the <SUB> (ASCII 26), default value of both REOF and TEOF, is correct for your computer. Setting REOF and TEOF to NONE may be appropriate for file transfers which use the XMODEM protocol.

REOF and TEOF are set in the same way as for REOL and TEOL, described above. To set REOF or TEOF to NONE, press EXE a twice without entering a value.

4.10 RTRN and TTRN

RTRN and TTRN stand for Receive Translate and Transmit Translate.

See chapter 6, "The Comms Menu", for more details on the handshaking methods.

RTRN and TTRN provide the means to translate any character to another character or to remove a character on input and output respectively. When RTRN or TTRN is set to NONE (the default), no translation occurs. When set to only one character, that character is removed. When set to two characters, the first character is translated to the second character.

RTRN and TTRN are typically used to translate <TAB> characters in data files, which separate adjacent fields in a record, to a more convenient field delimiter for use on the computer.

For example, to convert <TAB>s to a comma and vice versa, set TTRN to translate <TAB> to comma (ASCII 44) by pressing EXE when TTRN is the selected parameter. Then type:

9,44 EXE

Now select RTRN to translate comma to <TAB>. Press EXE and type:

44,9 EXE

Initially, RTRN and TTRN are set to NONE and no translation occurs.

4.11 LEAVING SETUP

After setting the above parameters to your satisfaction, exit SETUP by pressing MODE to enter the SETUP menu. A menu containing the following items is presented:

EXITExit SETUP keeping any changes
ABANDONExit SETUP discarding any changes
EDITReturn to the parameter list to continue editing
SAVESave the current SETUP
LOADLoad a previously saved SETUP
DIRRead the directory of saved SETUPs
ERASEErase a previously saved SETUP
RESETReset to the default SETUP settings

Select EXIT from this menu and you will be returned to the COMMS menu. However, you may wish to select the SAVE option first, to save your setup to a file. The values can then be restored at any time in the future by using the LOAD command.

4.12 SETTING UP THE OTHER COMPUTER

Run the communications program on the other computer as described in the user documentation and set the corresponding communications parameters to the values you have chosen for the Organiser.

4.13 TESTING THE LINK

When setting up a connection between the Organiser and another computer for the first time, it is a good idea to first enter terminal mode on the two machines to check that communication is working as it should.

Select TERM from the COMMS menu on the Organiser and enter terminal mode (or its equivalent) in the communications software on the other machine.

Type a few characters at each end of the connection and ensure that they are appearing correctly on the screen of the other machine. If this is not the case, you have probably set the communications parameters incorrectly and you may wish to use the AUTO command in the COMMS menu to check the basic communications parameters BAUD, PARITY, BITS and STOP.

The AUTO command cycles through all combinations of BAUD, PARITY, BITS and STOP (omitting only MARK and SPACE parity) transmitting a line of text for each combination. The text contains a message which identifies the four parameters so that if the computer receives the text without corruption, you can read the correct values of the parameters to use in SETUP.

While the program is running, the Organiser display continuously shows the combination of the parameters which is currently being transmitted. Press ON/CLEAR to abort AUTO when you are satisfied that you have the correct values, then enter these using SETUP. If you leave AUTO running, it will return to the COMMS menu when it has tried every combination.

4.14 TRANSFERRING FILES

Having achieved basic communications between the Organiser and the computer, you may now use the TRANSMIT and RECEIVE options in the COMMS menu to transfer files between the two computers.

When you select either RECEIVE or TRANSMIT, the screen will show:

FILE PROCEDURE  

This is a small menu, from which a selection can be made in the usual way. Select FILE to receive or transmit a data file and PROCEDURE to receive or transmit a procedure file.

Data Files

Data files consist of a number of records where each record may be split into fields. Records contain up to 254 characters and fields are delimited by the <TAB> character (ASCII 9). Each data file record corresponds to a line within the text file on the PC.

If, when receiving a data file, the incoming file contains lines longer than 254 characters, they are split into records of that length with the remainder of the line being written to successive records. Normally, a new record begins whenever the REOL sequence is detected. Incoming <TAB> characters will divide the records into separate fields. Alternatively, the <TAB> characters may be generated by the RTRN option as was described earlier.

An Organiser data file record may not be empty. Any received blank lines are saved as a record containing a single space character (ASCII 32).

Procedure Files

When procedure files are transmitted using the TRANSMIT command, only the source is transmitted. When procedure files are received using the RECEIVE command, a file is created which contains the source only (i.e. no object). You have to translate the procedure (using the TRAN option in the procedure editor under the PROG menu) before you can run a received procedure.

The first line of a procedure consists of a procedure name followed by a colon and optionally followed by the procedure parameters. When procedures are created under the top-level PROG command, the procedure file name will match the name on the first line. When you receive a procedure, however, the file name may not match the name on the first line.

It is the procedure file name which is significant when you invoke a procedure in an OPL program, not the name which appears on the first line. (When you edit a procedure on the Organiser, the name of the fist line is changed. if necessary to agree with the procedure file name.) When receiving a procedure, you should be mindful of the significance of the file name when choosing it.

4.15 FILE TRANSFER WITH NO PROTOCOL

When transferring files between two computers with PROTOCOL set to NONE, you should initiate the RECEIVE end before the TRANSMlT end. Otherwise, if the TRANSMIT begins before the other computer is ready to RECEIVE, part of the start of the file may be missed.

RECEIVE

Before starting the process of sending the file from the other computer, prepare the Organiser to receive the file.

Select RECEIVE from the COMMS menu and then select either FILE or PROCEDURE.

If you select PROCEDURE. the screen will show the prompt:

RECV A:         

Press the MODE key to change the device shown, if necessary. You may now type in the name of the file which is to take the received data. The file name must, as usual, be no longer than eight characters. If you have previously specified a file name in file transfer, that name will be given as a default.

If you specify a file name which already exists, the display will show:

A:FNAME EXISTS   DELETE Y/N

where FNAME is the procedure file name which was specified. If you press N, you are returned to the previous screen and may now type in a different file name or press ON/CLEAR to abort the transfer. Press Y and the old procedure will be deleted and replaced by the incoming file.

When using RECEIVE and after selecting FILE, the screen will show the prompt:

RECV A:MAIN     

The default file name will be MAIN unless you have previously specified a file name in file transfer, in which case that name will be given instead. You can either accept the default or press ON/CLEAR to clear the input and type another name in.

If you select the FILE option and you specify a file name which already exists and which contains data, the display will show:

ERASE APPEND    

This is another small menu. If ERASE is selected, the incoming file will replace the old data file of that name and its original contents will be lost. If the file being erased contains a large number of records, this may take some time. If the APPEND option is selected, the data in the incoming file will be appended to the original file.

You may now send the file from the other computer. Depending on the communications software you are using, the process may be called TRANSMIT or SEND, or some other name. Refer to the user documentation for the communications software for details of sending files.

Select the appropriate command to send the file then type the name the file is stored under on the other computer.

Data is displayed on the screen as it is received. At the higher Baud rates, this will not be readable but it will indicate that data transfer is taking place. The RECEIVE command terminates when the REOF sequence is received. Pressing ON/CLEAR at any time aborts the transfer, saving all the information so far received. This is useful if you have not been able to set the communications program on the other computer to send an REOF sequence.

TRANSMIT

Before starting the process of sending a file from the Organiser, prepare the other computer to receive the file. Depending on the communications software you are using, the process may be called RECEIVE, CAPTURE, DOWNLOAD, or some other name. Refer to the user documentation for the communications software for details of receiving files.

To capture the file as it arrives from the Organiser, you will have to enter a name for the incoming file. When you have given the file name and the computer is ready to receive all incoming data to that file, you can send the file from the Organiser.

On the Organiser, select TRANSMIT from the COMMS menu and then select either FILE or PROCEDURE.

If you select PROCEDURE, the screen will show the prompt:

SEND A:         

Press the MODE key to change the device, if necessary, and enter the name 0 the file which is to be transmitted. If you have previously specified a file name in file transfer, that name will be given as a default.

If you select FILE, TRANSMIT offers the default file name MAIN (used by the top-level menu commands FIND and SAVE):

SEND A:MAIN     

The default file name will be MAIN unless you have previously specified a file name in file transfer, in which case that name will be given instead. Press EXE to accept the default or press ON/CLEAR to clear the input and enter another name.

If the file is not found, a FILE NOT FOUND message will be displayed.

Transmitted data is displayed on the screen as it is transmitted. At the higher Baud rates, this will not be readable but it will indicate that data transfer is taking place.

When all the file data has been sent, the TEOF sequence is transmitted and the command terminates. Pressing ON/CLEAR at any time aborts the transfer.

At the other end of the connection, the corresponding file capture should terminate when the Organiser sends the TEOF sequence. If not, and the other computer is still waiting for more data to add to the file, you have probably set TEOF incorrectly.

4.16 XMODEM FILE TRANSFER

To use XMODEM file transfer, the PROTOCOL parameter must be set to XMODEM.

RECEIVE

To send a file from the other computer to the Organiser, set the other computer to send a file (selecting the appropriate XMODEM command and giving the name of the file on the other computer) and set the Organiser to receive using the RECEIVE command in the COMMS menu. With XMODEM file transfer, you can set up each end in either order.

Select RECEIVE from the COMMS menu and then select either FILE or PROCEDURE.

If you select PROCEDURE, the screen will show the prompt:

RECV A:         

Press the MODE key to change the device shown, if necessary. You may now type in the name of the file which is to take the received data. The file name must, as usual, be no longer than eight characters. If you have previously specified a file name in file transfer, that name will be given as a default.

If you specify a file name which already exists, the display will show:

A:FNAME EXISTS   DELETE Y/N

where FNAME is the procedure file name which was specified. If you press N, you are returned to the previous screen and may now type in a different file name or press ON/CLEAR to abort the transfer. Press Y and the old procedure will be deleted and replaced by the incoming file.

When using RECEIVE and after selecting FILE, the screen will show the prompt:

RECV A:MAIN     

The default file name will be MAIN unless you have previously specified a file name in file transfer, in which case that name will be given instead. You can either accept the default or press ON/CLEAR to clear the input and type another name in.

If you select the FILE option and you specify a file name which already exists and which contains data, the display will show;

ERASE APPEND    

This is another small menu. If ERASE is selected, the incoming file will overwrite the old data file of that name and its original contents will be lost. If the file being erased contains a large number of records, this may take some time. If the APPEND option is selected. the data in the incoming file will be appended to the original file.

After completing the RECEIVE dialogue, the screen will initially show:

Connecting      

When the XMODEM program on the other computer starts to transmit the file, the screen will change to:

Received nn     

where nn indicates the number of blocks successfully received. If all goes well, the block count will steadily increase until a RECEIVE OK message is displayed. At this point, press any key to continue.

The following messages may also be shown:

Error in nnAn error was detected when receiving block nn
Duplicate nnReceived a duplicate of a block already received
Failed in nnA fatal error was detected

The RECEIVE command terminates when the file is received successfully or if a fatal error occurs.

TRANSMIT

To send a tile from the Organiser to the other computer, set the other computer to receive a file (selecting the appropriate XMODEM command and giving the name of the file to be created on the other computer) and set the Organiser to transmit using the TRANSMIT command in the COMMS menu. With XMODEM file transfer, you can set up each end in either order.

Select TRANSMIT from the COMMS menu and then select either FILE or PROCEDURE.

If you select PROCEDURE. the screen will show the prompt:

SEND A:         

Press the MODE key to change the device, if necessary, and enter the name of the file which is to be transmitted. If you have previously specified a file name in file transfer, that name will be given as a default.

As with RECEIVE. selecting TRANSMIT then FILE offers as a default the file name you have most recently specified in file transfer. If it is your first file transfer operation the default file name MAIN is offered:

SEND A:MAIN     

Press EXE to accept the default or press ON/CLEAR to clear the input and enter another name.

If the file is not found, a FILE NOT FOUND message will be displayed. If the file exists, the screen will initially show:

Connecting      

Provided that the XMODEM program on the other computer has been set up to receive a file, the screen will change to:

Sending nn      

where nn indicates the number of the block currently being sent. If all goes well, the block count will steadily increase until a SEND OK message is displayed. At this point, press any key to continue.

The following messages may also be shown:

Resending nnResending an unacknowledged block
Failed in nnA fatal error was detected

4.17 USING MODEMS

In principle, there is no reason why the Organiser and the other computer should not be connected over a dial-up line using a pair of modems. However, in practice, this may be inconvenient because when PROTOCOL is set to either NONE or XMODEM, you have to type on both the Organiser and the other computer when performing a file transfer. (Compare this with the unattended file transfer which is available when PROTOCOL is PSION, as described in the previous chapter.) Since you obviously cannot type on both machines yourself, you would normally need an accomplice who would enter the necessary commands for you at the other end.

Because XMODEM is error correcting, you should use XMODEM file transfer if possible.

To connect the Comms Link cable to the modem you will need a Modem Adaptor. These are available from Psion. Alternatively, if you want to make one up yourself, or have one made for you, the wiring details may be found in an appendix at the back of this manual.


5. TERMINAL EMULATION

This chapter describes how TERM and CAPTURE in the COMMS menu may be used to access electronic mail and other dial-up services In this role, the Organiser is emulating a terminal.

For terminal emulation, the Organiser does not seek to compete with devices with full displays and you should not normally use Comms Link terminal emulation in situations where you could use a purpose-built terminal or a desktop PC with terminal emulation software. However, in contrast to a PC, the combination of an Organiser Comms Link and a portable modem can be carried with you, for accessing electronic mail services when you are away from your desk.

The facilities within Comms Link terminal emulation are more advanced than a simple terminal provides. Comms Link terminal emulation includes the ability to capture data from the buffer (within the internal memory of the Organiser). Data within the buffer can then be manipulated with a set of associated commands. This makes it possible for you to log on to an electronic mail system, view your mail with the capture buffer in operation and then log off again. When you are "off-line" you may edit the capture buffer, which contains a 'transcription' of the on-line session, and remove any unwanted system messages or prompts. You may then save the mail item as a file or a procedure. Alternatively, you may leave the capture buffer data exactly where it is. Then, at a later time, when you return home or to the office perhaps, you may send the contents of the capture buffer to a printer or to your desktop PC.

You do not have to capture data before you use the capture buffer editor. You may, for example, prepare a mail item or telex in the capture buffer, log on to a system when you are able to get to a telephone and then transmit the pre-prepared message.

In this chapter it is assumed that you are already familiar with the process of using a modem and logging on to the electronic mail (or other) system from a terminal or a desktop PC.

5.1 CONNECTING UP

Any modem you use will almost certainly have a D-type, 25 pin female connector. To connect the Comms Link cable to the modem you will need a Modem Adaptor. These are available from Psion. Alternatively, if you want to make one up yourself, or have one made for you, the wiring details may be found in an appendix at the back of this manual.

5.2 SETTING THE COMMUNICATIONS PARAMETERS

Before attempting to log on to the system, various communications parameters should be set using the SETUP option from the COMMS menu.

You should have fitted the Comms Link cable to the Organiser as described in the Introduction to this manual. This will add a new item, COMMS, to the top-level menu.

Select COMMS from the top-level menu and you will be presented with the COMMS menu which contains the following options:

TRANSMITTransmit a file or procedure
RECEIVEReceive a file or procedure
SETUPSet up communications parameters
TERMEnter terminal mode
AUTORun the automatic setup facility
CAPTUREEnter capture buffer menu
BOOTLoad and run a program stored on the PC

5.3 USING SETUP

When you select the SETUP option, you are presented with a list of communications parameters. The list is arranged with the name of the parameter on the left of the line and the current setting on the right. Use the UP and DOWN cursor keys to scroll up and down the list.

The SETUP parameters and the things they set are as follows:

BAUDBaud rate
PARITYParity
BITSNumber of data bits
STOPNumber of stop bits
HANDHandshaking
PROTOCOLFile transfer protocol
ECHOLocal or remote character echo
WIDTHForced line length
TIMEOUTTime allowed waiting for connection
REOLReceive end of line character(s)
REOFReceive end of file character(s)
RTRNReceive translate character(s)
TEOLTransmit end of line character(s)
TEOFTransmit end of file character(s)
TTRNTransmit translate character(s)

To edit a parameter value, first select the parameter using the UP and DOWN keys. The selected parameter is indicated with the right arrow symbol after the parameter name. Change the selected parameter either by pressing RIGHT and LEFT to select a value from a list of values or by pressing EXE and then by entering a value. Which method you use depends upon which parameter you are changing; see below, under the relevant parameter heading.

Pressing ON/CLEAR sets the selected parameter to its original value.

5.4 BAUD

The BAUD parameter specifies the Baud rate and must be set to match the Baud rate on your modem.

It is not possible to set a different rate for transferred data and received data on the Organiser. If you wish to communicate with a split speed host (e.g. using the V23 7511200 standard) you should use a modem which buffers the data and presents a single speed at the RS232 interface.

When BAUD is selected, press RIGHT and LEFT to change its value.

5.5 PARITY, BITS and STOP

When data is sent down the RS232 line, it is sent one bit at a time (rather than a character at a time) and the PARITY, BITS and STOP parameters specify how each character is converted into a pattern of bits. You do not have to understand what these parameters mean (see chapter 7 if you are interested) but their values should match the corresponding parameters used by the host and you should set these parameters to the equivalent settings that you use when you connect using a PC.

All three parameters are changed in the same way as for BAUD. by pressing RIGHT and LEFT.

The STOP parameter sets the number of stop bits and may be set to 1 or 2.

The BITS parameter specifies the number of data bits in each character and may be set to 7 or 8.

The PARITY parameter determines whether each character includes an additional bit (the parity bit) and, if so, what the rule is for its value. When used. the parity bit normally represents a simple form of error checking. Although the PARITY parameter may be set to five different values, MARK and SPACE are rarely used.

Note that some manufacturers include the parity bit in their definition of the data bits. This means that they would call seven data bits and a parity bit eight data bits.

5.6 HAND

The HAND parameter controls the handshaking methods to be used by the Organiser.

The Organiser supports three different kinds of handshaking. XON/XOFF, RTS/CTS and DTR. Each of these may be enabled or disabled. Press the RIGHT and LEFT cursor keys to change the value of the HAND parameter. When HAND is set to NONE. no handshaking takes place. When HAND Is set to ALL, alt three handshaking modes are enabled. Otherwise one or two are enabled. as suggested by the value.

DTR handshaking is only suitable for printers and, when using terminal emulation via a modem, HAND should be set to XON+RTS. RTS/CTS handshaking operates between the Organiser and the modem and XON/XOFF handshaking provides "end to end" handshaking.

See chapter 6, "The Comms Menu", for more details on the handshaking methods.

5.7 PROTOCOL

The PROTOCOL parameter selects the file transfer protocol which is used by the TRANSMIT and RECEIVE commands and should be set to NONE when using terminal emulation (by using the RIGHT and LEFT cursor keys to change the value).

5.8 ECHO

In terminal emulation, characters corresponding to the keys being pressed are transmitted to the host and characters which are received are displayed on the Organiser screen (and optionally saved in the capture buffer).

When ECHO is LOCAL, transmitted characters are also displayed (and recorded in the capture buffer if capture is enabled).

Usually, the host will echo characters as they are typed and ECHO should be set to HOST. If the host does not echo its input, ECHO should be set to LOCAL so that you can see what you type. Press the RIGHT and LEFT cursor keys to change the value.

If ECHO is set to LOCAL and the host is also echoing its input, you will see each character displayed twice. Set ECHO to HOST to remedy this.

5.9 WIDTH

In terminal emulation, the WIDTH parameter is used to force an end of line (as if the REOL sequence had been received) when the received line length becomes greater than the number of characters specified.

Setting WIDTH to 16, the width of the Organiser display, will cause lines longer than 16 characters to be continued on new display lines rather than scrolling the display horizontally.

The WIDTH parameter is one of the parameters which are not set by pressing the RIGHT and LEFT keys. To change WIDTH, press EXE when WIDTH is the selected parameter and enter the new value by typing the number followed by pressing EXE again. Note that the keyboard will automatically be in numeric mode.

The maximum WIDTH that you can specify is 250.

5.10 TEOL

TEOL stands for Transmit End Of Line. During terminal emulation, pressing the EXE key transmits the TEOL sequence. The TEOL sequence is also sent to terminate each line when transmitting a file.

By default, TEOL is set to <CR><LF> which is almost always inappropriate for terminal emulation and you should set TEOL to <CR> ASCII 13, the Carriage Return character). It is very important that you set this parameter, otherwise you will almost certainly be unable to log on to a remote system.

To set the TEOL character, first press the UP or DOWN cursor keys until TEOL is the selected parameter. Press EXE and type:

13 EXE

The top line will now show the TEOL character as <CR>.

5.11 REOL

REOL stands for Receive End Of Line. During terminal emulation, when the REOL sequence is received, the display continues on a new line (and the screen scrolls). When receiving a file, REOL is used to recognise received data records and procedure lines.

You should set REOL to the sequence which is sent by the host at the end of each line. This would normally be a combination of <CR> (ASCII 13) and <LF> (ASCII 10), which is the default value of REOL.

To change REOL, press EXE when REOL is the selected parameter and enter the new value by typing the ASCII code of the new terminator followed by pressing EXE again. If the required terminator contains two characters rather than a single character, enter the ASCII codes of the two characters, separated by a comma.

5.12 REOF and TEOF

REOF and TEOF stand for Receive End Of File and Transmit End Of File. They both define the ASCII sequence of characters which define an end of file when using file transfer.

The REOF sequence is used by the Organiser to recognise an end of file when receiving a file using the RECEIVE command.

The TEOF sequence is sent by the Organiser to signal an end of file to the host when transmitting a file using the TRANSMIT command, or when transmitting the capture buffer.

The correct values for REOF and TEOF depends on the host and the software which it is running, but it is likely that the default values of REOF and TEOF will be correct.

REOF and TEOF can be set in the same way as REOL, described above. To set REOF or TEOF to NONE, press EXE twice after selecting the parameter.

5.13 RTRN And TTRN

RTRN and TTRN stand for Receive Translate and Transmit Translate.

RTRN and TTRN provide the means to translate any character to another character or to remove a character on input and output respectively. When RTRN or TTRN is set to NONE (the default), no translation occurs. When set to only one character, that character is removed. When set to two characters, the first character is translated to the second character.

RTRN and TTRN are typically used to translate <TAB> characters in data files, which separate adjacent fields in a record, to a more convenient field delimiter for use on the host.

For example, you might wish to convert a <TAB> on the Organiser to a comma on the PC, and vice versa. To do so, set TTRN to translate <TAB> to comma (ASCII 44) by pressing EXE when TTRN is the selected parameter and entering:

9,44 EXE

and select RTRN to translate comma to <TAB> by pressing EXE when RTRN is the selected parameter and entering:

44,9 EXE

Initially, RTRN and TTRN are set to NONE and no translation occurs.

5.14 LEAVING SETUP

When the above communications parameters have been set to your satisfaction, press the MODE key and a menu containing the following items is presented:

EXITExit SETUP keeping any changes
ABANDONExit SETUP discarding any changes
EDITReturn to the parameter list to continue editing
SAVESave the current SETUP
LOADLoad a previously saved SETUP
DIRRead the directory of saved SETUPs
ERASEErase a previously saved SETUP
RESETReset to the default SETUP settings

Select EXIT from this menu to return to the COMMS menu. You may, if you wish, select the SAVE option first, to save your setup to a file. The values can then be restored at any time in the future by using the LOAD command.

You are now ready to use the TERM option to log on to the system.

5.15 TERM

Selecting the TERM option in the COMMS menu enters terminal emulation. If your modem has auto-dial facilities, you would normally type the number to dial from the Organiser keyboard and wait for the modem to indicate that the call has been connected. Otherwise dial the host manually and switch the modem to data when you hear the whistle of the modem at the other end. When you have a connection (the "carrier" indicator on your modem will have lit up), press EXE repeatedly until you see the expected system prompt and log on to the system in the normal way.

If all seems to be working but the host mysteriously will not accept your log on, check that you have changed TEOL to just <CR>, as described above.

As data is sent by the host, the lower display line scrolls horizontally if the line length exceeds 16 characters. When an end of line sequence (as set by the REOL parameter) is received or if the line width (as set by the WIDTH parameter) is exceeded. the display scrolls vertically showing the first 16 characters of the line in the upper display line. Either a horizontal or a vertical scroll delay is applied to give you a chance of viewing the data received. You can disable horizontal scrolling by setting the WIDTH parameter to 16. Comms Link terminal emulation does not process any escape codes.

Selecting the TERM option in the CAPTURE menu. has the same effect as selecting TERM in the COMMS menu except that displayed characters are recorded in the capture buffer (in the internal memory of the Organiser) and that the scroll delays are switched off. The CAPTURE command is described later in this chapter.

In terminal emulation, the SHIFT, CAP and NUM keys allow the usual full range of upper and lower case letters, numbers, operators and punctuation to be produced. However, the cursor keys behave differently to normal.

The LEFT and RIGHT cursor keys operate like shift keys.

The LEFT cursor key acts like the CONTROL key on a PC keyboard, enabling you to send the control characters such as <SUB>, or CONTROL-Z (ASCII 26) for end of file, <DC3>, or CONTROLS (ASCII 19) for pause, <DC 1>, or CONTROL-Q (ASCII 17) for continue and so on.

The RIGHT cursor key acts a "special" shift key which allows you to send characters which cannot normally be typed on the keyboard. The additional characters which are made available by the LEFT and RIGHT cursor keys are shown in a table in the next chapter, in the section on terminal emulation.

The DOWN cursor key pauses the display and the UP cursor key starts the display again. You will not lose any data provided you are using handshaking.

To exit terminal emulation and return to the COMMS menu, press ON/CLEAR. You will not lose any data when you exit and re-enter terminal emulation, provided you are using handshaking.

Except for <NUL> (ASCII 0) and <TAB> (ASCII 9), received characters below ASCII 32 are displayed as ^A for ASCII 1, ^B for ASCII 2, ^C for ASCII 3 and so on. All received <NUL>s and are discarded. A received REOL will scroll the display, and is then discarded. A received REOF is also discarded. If you see the same control characters at the beginning or end of each line this may indicate that you have set REOL incorrectly. Received <TAB> characters (which are used to delimit fields in data records) are displayed using a special <TAB> graphic (a diagram of which is shown in the terminal emulation section in the next chapter). Any received REOF characters will be discarded.

During terminal emulation (when using the TERM command in the COMMS menu or in the CAPTURE menu), in addition to responding to key presses, the Organiser must always be able to receive characters from the host. Because of this, the Organiser cannot employ its usual power conserving technique of switching off the ports when waiting for a key press. Unless you are using a Mains Adaptor, you should avoid leaving the Organiser for long periods within terminal emulation.

5.16 FILE TRANSFER

You may use the TRANSMIT and RECEIVE commands from the COMMS menu in conjunction with terminal emulation to upload data to a host and capture data from it.

When you select either RECEIVE or TRANSMIT, the screen will show:

FILE PROCEDURE  

This is a small menu, from which a selection can be made in the usual way. Select FILE to receive or transmit a data file and PROCEDURE to receive or transmit a procedure file.

Data Files

Data files consist of a number of records where each record may be split into fields. Records contain up to 254 characters and fields are delimited by the <TAB> character (ASCII 9). Each data file record corresponds to a line within the text file on the PC.

If, when receiving a data file, the incoming file contains lines longer than 254 characters, they are split into records of that length with the remainder of the line being written to successive records. Normally, a new record begins whenever the REOL sequence is detected. Incoming <TAB> characters will divide the records into separate fields. Alternatively, the <TAB> characters may be generated by the RTRN option as was described earlier.

An Organiser data file record may not be empty. Any received blank lines are saved as a record containing a single space character (ASCII 32).

Procedure Files

When procedure files are transmitted using the TRANSMIT command, only the source is transmitted. When procedure files are received using the RECEIVE command, a file is created which contains the source only (i.e., no object). You have to translate the procedure (using the TRAN option in the procedure editor under the PROG menu) before you can run a received procedure.

The first line of a procedure consists of a procedure name followed by a colon and optionally followed by the procedure parameters. When procedures are created under the top-level PROG command, the procedure file name will match the name on the first line. When you receive a procedure, however, the file name may not match the name on the first line.

It is the procedure file name which is significant when you invoke a procedure in an OPL program, not the name which appears on the first line. (When you edit a procedure on the Organiser, the name of the fist line is changed, if necessary, to agree with the procedure file name.) When receiving a procedure, you should be mindful of the significance of the file name when choosing it.

RECEIVE

To receive data from a host, use the TERM option and type a command which would display the data you want to receive followed by the REOF sequence. Before pressing EXE to enter this command on the host, hold down the RIGHT key and press S to send an XOFF character to the host which will pause the output until you are ready to receive it. Now press EXE to complete the command for the host to send the file. The host is still paused for the moment, so it will not send any data. Press ON/CLEAR to get the COMMS menu, select RECEIVE from the COMMS menu and then select either FILE or PROCEDURE.

If you select PROCEDURE, the screen will show the prompt:

RECV A:         

Press the MODE key to change the device shown, if necessary You may now type in the name of the file which is to take the received data. The file name must, as usual, be no longer than eight characters. If you have previously specified a file name in file transfer, that name will be given as a default.

If you specify a file name which already exists, the display will show:

A:FNAME EXISTS   DELETE Y/N

where FNAME is the procedure file name which was specified. If you press N, you are returned to the previous screen and may now type in a different file name or press ON/CLEAR to abort the transfer. Press Y and the old procedure will be deleted and replaced by the incoming file.

When using RECEIVE and after selecting FILE, the screen will show the prompt:

RECV A:MAIN     

The default file name will be MAIN unless you have previously specified a file name in file transfer, in which case that name will be given instead. You can either accept the default or press ON/CLEAR to clear the input and type another name in.

If you select the FILE option and you specify a file name which already exists and which contains data, the display will show:

ERASE APPEND    

This is another small menu. If ERASE is selected, the incoming file will replace the old data file of that name and its original contents will be lost. If the file being erased contains a large number of records, this may take some time. If the APPEND option is selected, the data in the incoming file will be appended to the original file.

When the RECEIVE command starts, it sends an XON and the host starts transmission.

Data is displayed on the screen as it is received. At the higher Baud rates, this will not be readable but it will indicate that data transfer is taking place. The RECEIVE command terminates when the REOF sequence is received. Pressing ON/CLEAR aborts the transfer, saving all the information so received. This is useful if you have not been able to persuade the host to send an REOF sequence.

TRANSMIT

To send a file to a host, use the TERM option to enter terminal emulation and type to the host in the normal way. At the point where the software on the host is expecting you to type in the data, press ON/CLEAR, to return to the COMMS menu, select TRANSMIT from the COMMS menu and then select either FILE or PROCEDURE.

If you select PROCEDURE, the screen will show the prompt:

SEND A:         

Press the MODE key to change the device, if necessary, and enter the name of the file which is to be transmitted. If you have previously specified a file name in file transfer, that name will be given as a default.

As with RECEIVE, selecting TRANSMIT then FILE offers as a default the file name you have most recently specified in file transfer. If it is your first file transfer operation the default file name MAIN is offered:

SEND A:MAIN     

Press EXE to accept the default or press ON/CLEAR to clear the input and enter another name.

If the file is not found, a FILE NOT FOUND message will be displayed.

Transmitted data is displayed on the screen as it is transmitted. At the higher Baud rates, this will not be readable but it will indicate that data transfer is taking place.

At the other end of the connection, the corresponding file capture should terminate when the Organiser sends the TEOF sequence. If not, and the other computer is still waiting for more data to add to the file, you may have set TEOF incorrectly. However, you can always re-enter terminal emulation to type the sequence which indicates to the host that the data is complete.

An alternative way of capturing data and of sending data is to use the CAPTURE command, which is described in the next section.

CAPTURE

Selecting the CAPTURE command presents a menu of commands which are associated with the capture buffer. The CAPTURE menu contains the following items:

TERMenter terminal emulation with capture enabled
EDITenter the capture buffer editor
SAVEsave capture buffer data to data file or procedure
TRANSMITtransmit the data in the capture buffer
CLEARclear the capture buffer

To exit from the CAPTURE menu back to the COMMS menu, press ON/CLEAR while the CAPTURE menu is displayed.

SAVE, TRANSMIT and CLEAR will only operate when the capture buffer contains data. A BUFFER IS EMPTY message will be displayed if this is not the case.

TERM

Selecting TERM in the CAPTURE menu (just press EXE) enters terminal emulation with the same effect as selecting TERM in the COMMS menu except that displayed characters are recorded in the capture buffer and that the scroll delays are switched off. Pressing ON/CLEAR returns to the CAPTURE menu.

Using TERM under CAPTURE can rapidly consume your free memory and you should not be too casual about leaving large amounts of data in the capture buffer or you may find that various operations on the Organiser will fail with an OUT OF MEMORY message.

If the Organiser runs out of memory while data is being captured, terminal emulation is aborted and an OUT OF MEMORY message is displayed. Press SPACE to exit to the CAPTURE menu. You may take the opportunity to release some memory (for example, by deleting some or all of the data in the capture buffer) before returning to terminal emulation. Provided that handshaking is in use, you will not miss any data in the meantime.

EDIT

Selecting EDIT enters the capture buffer editor which lets you view and modify the contents of the capture buffer. If you select EDIT from the CAPTURE menu before you have captured any data, the screen will show:

CAPTURE:        

The capture buffer is empty, and you may enter text into it. EDIT behaves almost identically to the procedure editor under the top-level menu PROG command. The UP and DOWN cursor keys scan through captured lines; the LEFT and RIGHT cursor keys move the cursor within a line; ON/CLEAR deletes a line; EXE splits a line at the cursor position; DEL and SHIFT DEL delete left and right respectively and key presses corresponding to printable characters insert at the cursor position.

The differences are that received <TAB> characters are displayed with a special <TAB> graphic and that the MODE key returns to the CAPTURE menu.

The EDIT command can also be used to prepare data "off line" for subsequent transfer to a host, but remember that Comms Link must be plugged into the Organiser while you use any facilities under the COMMS menu.

The capture buffer will hold as much data as the free memory of the Organiser can hold.

SAVE

When you have some data in the capture buffer, you can save it to either a data file or a procedure file.

When SAVE is selected, the screen displays a menu containing the items FILE and PROCEDURE, and things proceed exactly as if you were preparing to receive a file or procedure from another computer or a host, as described above.

After the SAVE is carried out, the data will still be in the capture buffer. If you intend to save the contents of the buffer to the internal memory of the Organiser, the buffer must not occupy more than half of the available free memory of the machine, otherwise when attempting to save the contents of the buffer, an OUT OF MEMORY message will be displayed and the SAVE will be abandoned.

TRANSMIT

The TRANSMIT option in the CAPTURE menu behaves in the some way as TRANSMIT under the COMMS menu except that it transmits the contents of the capture buffer without prompting for FILE or PROCEDURE or for a file name on the Organiser.

TEOL, TEOF and TTRN are all applied to the transmitted data. See the sections on these parameters, earlier in this chapter.

CLEAR

The only way the contents of the capture buffer can be cleared is by either deleting each line individually from within the EDIT option, or by using the CLEAR option. When you select CLEAR from the CAPTURE menu, you will be prompted to confirm that you wish to clear the buffer.

If there is data in the buffer and you exit from the COMMS option altogether, and even if you remove the Comms Link plug and software from the Organiser, the capture buffer will still remain intact. This means you can download some data, say from an electronic mail service, then disconnect, unplug the cable and return home or to the office, to print out the contents of the capture buffer.


6. THE COMMS MENU

This chapter describes what Comms Link can do from the COMMS menu. The menu contains the following items:

TRANSMITTransmit a file or procedure
RECEIVEReceive a file or procedure
SETUPSet up communications parameters
TERMEnter terminal mode
AUTORun the automatic setup facility
CAPTUREEnter capture buffer menu
BOOTLoad and run a program stored on the PC

6.1 SETUP

Comms Link contains a set of communications parameters (the SETUP parameters) which is used by the software. The SETUP command is used to review and edit these SETUP parameters.

In this section, the SETUP editor and the meaning and usage of the parameters themselves are described.

At any time, the Comms Link software uses the current SETUP parameters. The current SETUP parameters will be initialised to the default parameter values at the following times:

  1. when Comms Link is first inserted;
  2. when the RESET command in the SETUP menu is used (see below);
  3. when the Organiser is reset using the RESET command in the top-level menu;
  4. when the Organiser is powered off (e.g. when the battery is removed for longer than 90 seconds).

Other than the above, and excluding direct action to change the SETUP parameters, the current parameters remain unchanged and it is not necessary to use SETUP each time you remove and insert the Comms Link cable.

The SETUP command effectively makes a copy of the current parameters which you can view and modify. When you exit the SETUP command, the current parameters are replaced by the edited copy (although you can choose to abandon the edit in which case the current parameters are unaffected). Within the SETUP command you can create and maintain saved SETUP parameter files which you can use to replace the current parameters at will.

6.2 USING SETUP

When the SETUP option is selected from the COMMS menu, the screen shows:

BAUD >      9600 PARITY      NONE

The top line shows the Baud rate, and the bottom line the parity setting. These are just two out of 15 parameters which may be altered.

The selected parameter (BAUD initially) is indicated by the right arrow symbol after the parameter name. To select one of the other parameters, use the UP and DOWN cursor keys to scroll through the list.

Pressing ON/CLEAR sets the selected parameter to its default value.

When the selected parameter may only take its value from a list of allowable values, you change the value by pressing the LEFT and RIGHT cursor keys. The SETUP parameters may be changed in this way are BAUD, PARITY, BITS, STOP, HAND, PROTOCOL and ECHO.

When the selected parameter can take a more open-ended set of values, the value is entered directly. (You can assume a parameter is of this type when nothing happens when you press the LEFT or RIGHT cursor keys.) Pressing EXE clears the old parameter value at the right of the display and enters the normal Organiser line editor. After typing the new parameter value, pressing EXE inserts the new value which, if accepted, is then displayed. If the new parameter value is invalid, the data is cleared and you remain within the line editor. Pressing ON/CLEAR when there is no input data abandons the parameter edit and the old value is restored. (Remember that pressing ON/CLEAR a further time would restore the parameter to its default value.)

The SETUP parameters which are specified in this way are WIDTH, TIMEOUT, REOL, REOF, RTRN, TEOL, TEOF and TTRN.

In practice, parameters of this type take as their value either a number or a short list of numbers, separated by commas. A number is interpreted as a decimal number unless it is prefixed by a dollar ($) when it is taken to be hexadecimal (base 16). For example, the ASCII carriage return code may be entered as 13 or as $D.

When the parameter consists of an ASCII code or a list of ASCII codes, the character corresponding to that code is displayed instead of the code; for example, entering 42 displays an asterisk (since the ASCII code for "*" is 42). Non-printable control characters (with ASCII codes 0 to 31 and 127) are shown with their ASCII names in angle brackets. For example, when the ASCII code sequence 13,10 is entered, <CR><LF> is displayed. Characters with codes greater than 127 will have the hexadecimal value displayed in angle brackets, so 128 will be shown as <$80>. An appendix to this manual gives the names of the ASCII control codes. See appendix A in the Organiser 2 Operating Manual for the printable character set.

The SETUP parameters, their names and allowable values are as follows:

PARAMETERNAMEOPTIONS
Data transfer rateBAUD50, 75, 110, 150, 300, 600, 1200, 2400, 4800, (9600)
ParityPARITY(NONE), ODD, EVEN, MARK, SPACE
No. of data bitsBITS7, (8)
No. of stop bitsSTOP(1), 2
HandshakingHANDNONE, (XON), RTS, XON+RTS, DTR, XON+DTR, RTS+DTR, ALL
File transfer protocolPROTOCOL(NONE), XMODEM, PSION
EchoECHOLOCAL, (HOST)
Forced line lengthWIDTH(NONE), 1 to 250
Output timeoutTIMEOUT(NONE), 1 to 255
Receive EOLREOLNONE, 1 or 2 characters
Receive EOFREOFNONE, 1 or 2 characters
Receive translateRTRN(NONE), 1 or 2 characters
Transmit EOLTEOLNONE, 1 or 2 characters
Transmit EOFTEOFNONE, 1 or 2 characters
Transmit translateTTRN(NONE), 1 or 2 characters

Where possible, the default value is shown in brackets. For the remaining parameters, the default values are:

PARAMETERDISPLAYED ASINPUT AS
REOL and TEOL<CR><LF>13,10
REOF and TEOF<SUB>26

6.3 BAUD

The BAUD parameter specifies the data transfer rate for both transmitted and received data.

It is not possible to set a different rate for transferred data and received data on the Organiser. If you wish to communicate with a split speed host (e.g. the V23 75/1200 standard) you have to use a modem which buffers the data and presents a single speed interface at the RS232 interface.

The Baud rate specifies the data transfer rate in bits per second. In most cases, dividing by 10 gives the transfer rate in bytes per second.

BAUD is used by every aspect of the Comms Link software and is the most important parameter to get right. The Baud rate on the organiser must agree with the Baud rate which has been set on the communicating device.

6.4 PARITY, BITS And STOP

The Organiser transmits and receives data in groups (known as frames) of 10 or 11 bits. One character, or byte, of data is included in each frame.

The first bit of a frame is the start bit and is always present.

The next 7 or 8 bits (specified by the BITS parameter) contain the actual data which makes up the byte. When there are only 7 data bits in the frame, the missing most significant bit (there are 8 bits in a byte) is effectively set to zero.

After the data bits there is an optional parity bit. If the PARITY parameter is NONE, there is no parity bit. Otherwise the parity bit is present and the rule for its value (0 or 1) is specified by the PARITY parameter, as follows:

MARKalways 1
SPACEalways 0
ODD or EVENdepends on the data bits

With ODD and EVEN parity, the parity bit is set depending on whether there is an odd or even number of 1's in the 7 or 8 data bits. This provides a primitive form of error checking.

Finally, there will be one or two stop bits (specified by the STOP parameter).

Because the hardware used by the Organiser can only transfer and receive 10 or 11 bit frames, combinations which would lead to a frame of other than 10 or 11 bits are not allowed. The software does this by overriding the STOP parameter value under the following circumstances:

  1. When BITS is set to 7 and PARITY set to NONE (7 data bits with no parity), the Organiser will add 2 stop bits regardless of the STOP setting.
  2. When BITS is set to 8 and PARITY is not NONE (8 data bits with a parity bit), the Organiser will add 1 stop bit regardless of the STOP setting.

Some manufacturers include the parity bit in their definition of the data bits. This means that they would call seven data bits and a parity bit eight data bits. Check the definition of data bits used by your target device in its documentation.

As with the BAUD parameter, the important aspect about PARITY, BITS and STOP is that they agree with the corresponding settings on the communicating device. If the PARITY, BITS and STOP settings do not agree, then the communicating device will almost certainly incorrectly receive data sent to it, and the Organiser will incorrectly interpret received data.

In terminal emulation, characters which are received with an error are set to ASCII 255 which is displayed as a solid block. In other cases (e.g. file transfer or an OPL procedure), a DEVICE READ ERROR is reported. If the parameter values do not match those of the correspondents but are not too dissimilar, you may receive some characters (sometimes as much as half the characters) without error.

Although there are many PARITY settings on the Organiser, MARK and SPACE parity are rarely used.

Setting 2 stop bits is normally associated with slow Baud rates (300 or lower) and mechanical devices. Having 2 stop bits rather than 1 will never cause an error - it will just slow down the byte transfer rate. The converse, however, is not true.

The setting of PARITY, BITS and STOP are ignored in communications involving the PSION protocol, where 8 data bits, no panty and 1 stop bit are used. Other than this case, the PARITY, BITS and STOP parameters are used by all aspects of the Comms Link software, including XMODEM file transfer.

6.5 HAND

The HAND parameter controls the handshaking methods to be used by the Organiser.

Devices can rarely cope with an uninterrupted stream of data, especially at the higher Baud rates, and handshaking (also called "flow control" or "buffer control") is a means by which the receiving device can pause and restart the transmitting device.

For example, mechanical printers cannot print at the higher Baud rates and, as their internal buffer fills, they need to pause the Organiser. As another example, the Organiser applies vertical and horizontal scroll delays during terminal emulation (to give you a chance of seeing the received data) and, as a result of these delays, the Organiser will need to pause the host if it continuously transmits more than a hundred or so bytes of data.

The Organiser supports three different kinds of handshaking, XON/XOFF, RTS/CTS and DTR each of which may be enabled or disabled. When HAND is NONE, no handshaking takes place. When HAND is ALL, all three handshaking modes are enabled. Otherwise one or two are enabled, as suggested by the value.

6.6 XON/XOFF

XON/XOFF handshaking is based on using two control characters to pause and restart data transfer. The receiver sends an XOFF to pause the transmitter when its input buffer is getting too full and sends an XON when its buffer is sufficiently empty. The control characters used by XON/XOFF handshaking have the ASCII names DC1 and DC3 (the "DC" stands for "Device Control") and so "DC1/DC3 handshaking" means the same thing.

When XON/XOFF handshaking is enabled, the Organiser will pause and restart transmission in response to received XON and XOFF characters and the Organiser will also transmit XOFFs and XONs to manage the capacity of its own receive buffer.

XON/XOFF handshaking is typically used in terminal emulation and is also supported by some printers.

6.7 RTS/CTS

RTS/CTS handshaking is named after the RS232 control lines (Request to Send, Clear to Send) on which it is based. On the Organiser, the detailed operation of these lines is quite complicated - see the appendix on the Comms Link interface if you need to know exactly how these lines operate.

RTS/CTS handshaking is usually required when the Organiser is connected to a modem.

6.8 DTR

DTR handshaking is named after the RS232 control line (Data Terminal Ready) on which it is based. The DTR line is output low by the communicating device (usually a printer) when its receive buffer is too full, and output high again as the buffer empties.

XON/XOFF and RTS/CTS handshaking are used to control the flow of data in either direction. DTR handshaking, however, is only used to control the flow of data from the Organiser to the communicating device.

See the appendix on the Comms Link interface for more information on the use of the DTR/DSR lines on the Organiser.

If your target device does not support any of the above types of handshaking, set the handshake parameter to NONE. However, in this case, you may have difficulty receiving any but the shortest files or procedures. At low Baud rates it may work provided that no access is made to a datapack (i.e., files are received to A:). You will still be able to transmit data to the other device provided that it can save the data as fast as the Organiser is transmitting. Using a slow Baud rate will clearly help.

Communications involving the PSION protocol will override (i.e. disable) XON/XOFF handshaking. Except for this case, the handshaking specified by XON/XOFF. RTS/CTS and DTR parameters is used by all aspects of the Comms Link software, including XMODEM file transfer.

6.9 PROTOCOL

The PROTOCOL parameter specifies the file transfer protocol used by the COMMS menu items TRANSMIT and RECEIVE and by the TRANSMIT command in the CAPTURE menu. It has no affect on any OPL communications procedures.

When PROTOCOL is set to NONE, the RECEIVE command just captures received data without any error checking. The TRANSFER command just sends file data down the RS232 connection, again without any error checking. The communicating device normally has to be persuaded independently to perform the corresponding capture or transmission of data. In the case of a host, this could be achieved using terminal emulation (the TERM command, described later) on the Organiser.

When PROTOCOL is set to XMODEM, TRANSMIT and RECEIVE assume that the communicating device is running an XMODEM program. In this case, file transfers are error checked, but the corresponding transfers (TRANSMIT at one end and RECEIVE at the other) must be independently and manually initiated.

When PROTOCOL is PSION, TRANSMIT and RECEIVE work on the assumption that the communicating device is a PC running the Comms Link communications server program (CL). File transfers are error checked and, once the CL program is running, the transfer is controlled entirely from the Organiser.

6.10 ECHO

The ECHO parameter only affects terminal emulation (TERM and CAPTURE in the COMMS menu).

In terminal emulation, characters corresponding to the keys being pressed are transmitted to the host and characters which are received are displayed on the Organiser screen (and optionally saved in the capture buffer).

When ECHO is LOCAL. transmitted characters are also displayed (and recorded in the capture buffer if capture is enabled.

Usually, the host will echo characters as they are typed and ECHO should be set to HOST. If the host does not echo its input, ECHO should be set to LOCAL so that you can see what you type.

If ECHO is set to LOCAL and the host is also echoing its input. you will see each character displayed twice. Set ECHO to HOST to remedy this.

An example of a "host" which does not echo its input is a printer. If you are using terminal emulation to test a printer, you may find it helpful to set ECHO to LOCAL.

6.11 TIMEOUT

The TIMEOUT parameter may be used to set a time out for the LIST command under the top-level PROG menu, the OPL LPRINT command, and the output stage of the Comms Link TRIGS procedure.

The TIMEOUT parameter is only meaningful when handshaking is in use where the communicating device can pause the output from the Organiser. When TIMEOUT is set to NONE, the output operation (LIST, LPRINT or TRIG$) can be paused indefinitely. An indefinite pause can be avoided by setting the TIMEOUT parameter to a time out value of between 1 and 255 seconds. It the communicating device (e.g. printer) pauses the Organiser for more than the timeout period. the operation will abort with a DEVICE WRITE ERR (error number 192).

In practice. the TIMEOUT parameter is usually used to detect a device being left "off line" and to recover gracefully after the timeout period rather than "hang" forever.

6.12 WIDTH

The WIDTH parameter is used to break up long lines.

In terminal emulation (TERM and CAPTURE in the COMMS menu). the WIDTH parameter is used to force an end of line (as if the REOL sequence had been received) when the received line length is greater than the number of characters specified.

Apart from terminal emulation. the width command affects certain RS232 output operations in that a TEOL (Transmit End Of Line) sequence is inserted into the output stream when the length of the line being transmitted exceeds the WIDTH specified. If WIDTH is NONE. no TEOL insertion takes place. When receiving data. WIDTH equal to NONE is equivalent to a width of 250 characters. The output operations which use WIDTH are the OPL command LPRINT. the Comms Link device procedure TRIG$, and the LIST command under the PROG menu. The file transfer commands do not use the WIDTH parameter.

This feature is useful when sending data to a printer which does not insert its own new line when the print position exceeds the right margin.

6.13 REOL and TEOL

REOL and TEOL stand for Receive End Of Line and Transmit End Of Line. They both define the ASCII sequence of characters which define an end of line. The REOL sequence is used by the Organiser to recognise an end of line on input. The TEOL sequence is transmitted by the Organiser to signal an end of line to the communicating device.

Both the REOL and TEOL sequence may be set to no characters (NONE), one character, or two characters. TEOL and REOL would normally be set to a combination of <CR> (ASCII 13) and <LF> (ASCII 10).

Except for communications involving the PSION protocol, where the end of line sequence is always <CR><LF>, the TEOL and REOL parameters are used by all aspects of Comms Link.

In terminal emulation, pressing the EXE key transmits the TEOL sequence. When the REOL sequence is received, the display continues on a new line (and the screen scrolls).

In the tile transfer commands TRANSMIT and RECEIVE, when PROTOCOL is either NONE or XMODEM. TEOL is sent at the end of transmitted data records and procedure lines and REOL is used to recognise received data records and procedure lines.

TEOL is transmitted by LPRINT (except where the command ends with a semicolon). TRIG$ and LIST (under the PROG menu). REOL is used by TRIG$ and LINPUT$.

If you are using the Organiser as a terminal to a host it is more likely that TEOL should be <CR> with REOL left at the default of <CR><LF>. If you are using the Organiser to transfer files to another microcomputer or to send data to a printer, you will probably find that the default settings are correct.

If you have a data file which contains the carriage return character (ASCII 13) within a record you may be surprised to see the record broken into two lines when transferred to a communicating device. This is because an end of line is implemented internally as a <CR> character, so any <CR> is translated to the TEOL sequence. This also means that carriage returns are removed if TEOL is set to NONE.

6.14 REOF And TEOF

REOF and TEOF stand for Receive End Of File and Transmit End Of File. They both define the ASCII sequence of characters which define an end of file when using file transfer when the PROTOCOL parameter is set to NONE or XMODEM (not PSION).

The REOF sequence is used by the Organiser to recognise an end of file when receiving a file using the RECEIVE command. The TEOF sequence is sent by the Organiser to signal an end of file to the communicating device when transmitting a file using the TRANSMIT command.

As for REOL and TEOL, the REOF and TEOF sequence may be set to no characters (NONE), one character, or two characters.

An end of file is implemented internally as a <SUB> character, so any <SUB> is translated to the TEOF sequence. This also means that any <SUB> character will be removed if TEOF is set to NONE.

6.15 RTRN and TTRN

RTRN and TTRN stand for Receive Translate and Transmit Translate.

RTRN and TTRN provide the means to translate any character to another character or to remove a character on input and output respectively. When RTRN or TTRN is set to NONE (the default). no translation occurs. When set to only one character, that character is removed. When set to two characters, the first character is translated to the second character.

On output, the transmit translate does not operate on <CR> and <SUB> characters - these are always transmitted as the current TEOL and TEOF sequences respectively. However, TTRN processing is performed before TEOL and TEOF processing so that if the specified TTRN translates a character to <CR> or <SUB>. this new character will then be translated a second time, either to the TEOL or TEOF sequence.

On input, REOL and REOF sequences are checked for before RTRN processing is done. In the cases of LINPUT$ and TRlG$, REOL and REOF sequences are treated as part of the received data and are passed through for RTRN processing. See the following chapter for descriptions of LINPUT$ and TRIG$.

An example of the usage of RTRN is to convert <BELL> (ASCII 7) into, say, an asterisk (ASCII 42). (The <BELL> control code normally sounds a bell on a terminal.)

Another example, which applies to both RTRN and TTRN, is to translate to and from the <TAB> (ASCII 9) character, used as a field delimiter in Organiser data files. For example, if RTRN is set to translate the "/" character (ASCII 47) to <TAB> (ASCII 9), the received line (using the RECEIVE option to receive a data file):

Psion Limited/Psion House/Harcourt Street/LONDON/W1H 1DT<CR><LF>

will produce a record with 5 separate fields on the Organiser.

For communications involving the PSION protocol, the RTRN and TTRN parameters are only used in file transfers to and from data files on the Organiser (RTRN and TTRN are ignored in transfers involving procedure files and binary files). Except for this case, RTRN and TTRN are used by all aspects of Comms Link.

LEAVING SETUP

Pressing the MODE key exits the SETUP parameter editor into the SETUP menu:

EXITExit SETUP keeping any changes
ABANDONExit SETUP discarding any changes
EDITReturn to the parameter list to continue editing
SAVESave the current SETUP
LOADLoad a previously saved SETUP
DIRRead the directory of saved SETUPs
ERASEErase a previously saved SETUP
RESETReset to the default SETUP settings

Selecting EXIT or ABANDON exits the SETUP command; selecting EDIT returns to the parameter editor. The remaining commands return to the SETUP menu on completion.

If you use your Organiser to connect to more than a single device, it is useful to be able to recall a previously defined SETUP. The SAVE, LOAD, DIR and ERASE commands are used to maintain a set of custom SETUP files.

When you select the SAVE option from the SETUP menu, the screen will show:

SAVE A:         

Press the MODE key to change the device, if you wish, and then enter the name you wish to save the current setup under. The edited SETUP parameter values are saved, even if you have not yet made them the current parameter values by selecting EXIT.

The procedure for entering the filename for LOAD and ERASE is the same. Like the SAVE command, the LOAD command does not replace the current parameter values, only the edited parameters.

To view a directory of SETUP files, select the DIR option from the SETUP menu. Press the MODE to change the current device, if necessary. Press the EXE key repeatedly to view the names of SETUP files which are stored on the specified device. After the last SETUP file, the END OF PACK message will be displayed. Press the ON/CLEAR key to return to the SETUP menu.

The RESET command sets all the SETUP parameters to their default values. However, only the edited parameters are affected and EXIT must be used to replace the current parameters.

6.17 FILE TRANSFER

The TRANSMIT and RECEIVE commands are used to transfer data files and procedures to and from the Organiser.

The type of file transfer which is used and the behaviour of the RECEIVE and TRANSMIT commands depend upon the setting of the PROTOCOL parameter (as set by the SETUP command). The PROTOCOL parameter can take the values NONE, XMODEM or PSION.

The PSION protocol provides the best file transfer service but relies on the communicating device being an IBM PC/XT/AT or compatible running the PC communications program CL (supplied with Comms Link).

The XMODEM protocol provides a better file transfer service than NONE but assumes that the communicating device is running an XMODEM program (not supplied with Comms Link).

Using PROTOCOL set to NONE provides the most primitive file transfer (no error checking) but makes the least demands upon the communicating device. With PROTOCOL set to NONE, the TRANSMIT command may be used to send data files and procedure files to a printer.

For all three protocols, the only file transfer available using the RECEIVE and TRANSMIT commands is between simple text files on the communicating device and either data files or procedure files on the Organiser.

Binary files (e.g. DIARY files) can be transferred using the PSION protocol but you have to write an OPL program (see the following chapter).

When you select either RECEIVE or TRANSMIT, the screen will show:

This is a small menu, from which a selection can be made in the usual way. Select FILE to receive or transmit a data file (see the Organiser 2 Operating Manual for a description of data files) and PROCEDURE to receive or transmit a procedure file.

Data Files

Data files consist of a number of records where each record may be split into fields. Records contain up to 254 characters and fields are delimited by the <TAB> character (ASCII 9). Each data file record corresponds to a line within the text file on the communicating device.

When receiving data files with PROTOCOL set to NONE or XMODEM, if the incoming file contains lines longer than 254 characters, they are split into records of that length with the remainder of the line being written to successive records. Normally, a new record begins whenever the REOL sequence is detected.

Incoming <TAB> characters will divide the records into separate fields. Alternatively, the <TAB> characters may be generated by the RTRN option as described above under SETUP.

On the Organiser. a data file record may not be empty. Any received blank lines are saved as a record containing a single space character.

Procedure Files

When procedure files are transmitted using the TRANSMIT command, only the source is transmitted. When procedure files are received using the RECEIVE command, a file is created which contains the source only (no object). You have to translate the procedure (using the TRAN option in the procedure editor under the PROG menu) before you can run a received procedure.

The first line of an Organiser procedure consists of a procedure name followed by a colon and optionally followed by the procedure parameters. When procedures are created under the top-level PROG command, the procedure file name will match the name on the first line. When you receive a procedure, however, the file name may not match the name on the first line. It is the procedure file name which is significant when you invoke a procedure in an OPL program, not the name which appears on the first line. (When you edit a procedure on the Organiser the name of the fist line is changed, if necessary, to agree with the procedure file name.) When receiving a procedure, you should be mindful of the significance of the file name when choosing it.

When receiving a procedure, if the first line does not contain a colon, a first line is inserted consisting of a question mark followed by a colon. If the received data contains one or more ASCII control characters (i.e. with ASCII codes which are less than 32) and except for REOL and REOF characters, the RECEIVE command will fail with a BAD PROCEDURE message.

When receiving a procedure with the PROTOCOL set to either NONE or XMODEM, the whole procedure is held in a buffer in memory before being saved to the file. In this case, there must be sufficient free memory to hold the entire procedure. If the procedure is being received to A: (the internal memory of the Organiser), there must be sufficient room for two copies of the procedure.

RECEIVE

When using RECEIVE and after selecting PROCEDURE, the screen will show the prompt:

RECV A:         

Press the MODE key to change the device shown, if necessary. You may now type in the name of the file which is to take the received data. The file name must, as usual, be no longer than eight characters. If you have previously specified a file name in file transfer, that name will be given as a default.

If you specify a file name which already exists, the display will show:

A:FNAME EXISTS   DELETE Y/N

where FNAME is the procedure file name which was specified. If you press N you are returned to the previous screen and may now type in a different file name or press ON/CLEAR to abort the transfer. Press Y and the old procedure will be deleted and replaced by the incoming file.

When using RECEIVE and after selecting FILE, the screen will show the prompt:

RECV A:MAIN     

The default file name will be MAIN unless you have previously specified a file name in file transfer, in which case that name will be given instead. You can either accept the default or press ON/CLEAR to clear the input and type another name in.

If you select the FILE option and you specify a file name which already exists and which contains data, the display will show:

ERASE APPEND    

This is another small menu. If ERASE is selected, the incoming file will replace the old data file of that name and its original contents will be lost. If the file being erased contains a large number of records, this may take some time. If the APPEND option is selected, the data in the incoming file will be appended to the original file.

The subsequent behaviour of the RECEIVE command depends on the setting of the PROTOCOL parameter.

Receiving files with the PSION protocol

If the PROTOCOL parameter is set to PSION, the display will prompt for the PC file name:

RECV A:FNAME     FROM:FNAME

where you are offered the default of the same name for the PC. Either accept the default or enter a different PC file name (and path name, if required). If you do not include a path name, the current directory (when you ran Comms Link) will be used on the PC. Since path names use the backslash character (\) (which cannot be entered from the Organiser keyboard), any "/"in the name is converted to a "\", by the PC software. Also, as the default name may contain a percent character (%), which is not allowed in PC file names, the PC software converts any percent characters in the file name to an underscore character (_). If the file does not exist on the PC, a FILE NOT FOUND error is displayed and you are given another opportunity to enter the "FROM:" file name.

While data is being received, the screen will show:

receiving...    

If the file transfer is unsuccessful, it will display one of the following error messages:

TIMEOUT - a timeout occurred waiting for a response, possibly indicating that a lead is disconnected, that CL is not running on the PC, or that there have been too many transmission errors (due to a very noisy line).

SERVER FAILURE - some other server failure occurred. For example, a disk door is open.

If possible, look at the PC display for further details of any failure.

Receiving files with no protocol

When PROTOCOL is set to NONE, the received data is displayed on the screen as it downloads. At the higher Baud rates, this will not be readable but it will indicate that data transfer is taking place. The RECEIVE command terminates when the REOF sequence is received. Pressing ON/CLEAR aborts the transfer, saving all the information so receive This is useful if the communicating device has sent all its data and cannot send an REOF sequence.

Receiving files with the XMODEM protocol

When PROTOCOL is set to XMODEM, the screen will initially show:

connecting      

Provided that the XMODEM program on the communicating device has been set up to transmit a file, the screen will change to:

Received nn     

where nn indicates the number of blocks received successfully. If all goes well, the block count will steadily increase until a RECEIVE OK message is displayed. At this point, press any key to continue.

The following messages may also be shown:

Error in nn - An error was detected when receiving block nn
Duplicate nn - Received a duplicate of a block already received
Failed in nn - A fatal error was detected

The RECEIVE command terminates when the file is received successfully or if a fatal error occurs.

TRANSMIT

When using TRANSMIT and after selecting PROCEDURE, the screen will show the prompt:

SEND A:         

Press the MODE key to change the device, if necessary, and enter the name of the file which is to be transmitted. If you have previously specified a file name in file transfer, that name will be given as a default.

As with RECEIVE, selecting TRANSMIT then FILE offers as a default the file name you have most recently specified in file transfer. If it is your first file transfer operation the default file name MAIN is offered:

RECV A:MAIN     

Press EXE to accept the default or press ON/CLEAR to clear the input and enter another name.

If the file is not found, a FILE NOT FOUND message will be displayed.

Transmitting files with the PSION protocol

If the PROTOCOL parameter is set to PSION, the display will prompt for the PC file name:

SEND A:FNAME     TO:FNAME

where you are offered the default of the same name for the PC. Either accept the default or enter a PC file name (and path name, if required). If you do not include a path name, the current directory (when you ran Comms Link) will be used on the PC. Since path names use the backslash character (\) (which cannot be entered from the Organiser keyboard), any "/" in the name is converted to a "\" by the PC software. Also, as the default name may contain a percent character (%), which is not allowed in PC file names, the PC software converts any percent characters in the file name to an underscore character (_).

If the file already exists, the display will show:

FNAME EXISTS     DELETE Y/N

If you press N you are returned to the previous screen and may now type in a different file name or press ON/CLEAR to escape. Press Y and the existing file will be replaced.

While data is being transmitted the screen will show:

Sending...      

If the file transfer is unsuccessful, it will display one of the following error messages:

TIMEOUT - a timeout occurred waiting for a response, possibly indicating that a lead is disconnected, that CL is not running on the PC, or that there have been too many transmission errors (due to a very noisy line).

SERVER FAILURE - some other server failure occurred. For example, a disk door is open.

If possible, look at the PC display for further details of any failure.

Transmitting files with no protocol

When PROTOCOL is set to NONE, transmitted data is displayed on the screen as it is transmitted. At the higher Baud rates, this will not be readable but it will indicate that data transfer is taking place.

When all the file data has been sent the TEOF sequence is transmitted and the command terminates. Pressing ON/CLEAR aborts the transfer.

Transmitting files with the XMODEM protocol

When PROTOCOL is set to XMODEM, the screen will initially show:

connecting      

Provided that the XMODEM program on the communicating device has been set up to receive a file, the screen will change to:

Sending nn      

where nn indicates the number of the block currently being sent. If all goes well, the block count will steadily increase until a SEND OK message is displayed. At this point, press any key to continue.

The following messages may also be shown:

Resending nn - Resending an unacknowledged block
Failed in nn - A fatal error was detected

6.18 TERMINAL EMULATION

Selecting the TERM option in the COMMS menu enters terminal emulation, where key presses transmit the corresponding character and received characters are displayed as they arrive - emulating the basic features of a terminal. If the SETUP parameter ECHO is set to LOCAL, characters are also displayed as they are transmitted.

As data is echoed, the lower display line scrolls horizontally if the line length exceeds 16 characters. When an end of line sequence (as set by the REOL parameter) is received or if the line width (as set by the WIDTH parameter) is exceeded, the display scrolls vertically showing the first 16 characters of the line in the upper display line. Either a horizontal or a vertical scroll delay is applied to give you a chance of viewing the data received. You can disable horizontal scrolling by setting the WIDTH parameter to 16. Comms Link terminal emulation does not process any escape codes.

Normally, you use terminal emulation to access a multi-user RS232-based minicomputer or mainframe (for example, to use an Electronic Mail service), often via a modem and a dialled connection. Terminal emulation can also be used when connected to a printer to confirm that the SETUP parameters are correct and that the printer is able to receive data from the Organiser.

Selecting the TERM option in the CAPTURE menu (described below) has the same effect as selecting TERM in the COMMS menu except that displayed characters are recorded in the capture buffer (in the internal memory of the Organiser) and that the scroll delays are switched off. The CAPTURE command is described in the next section.

In terminal emulation, the SHIFT, CAP and NUM keys produce the usual full range of upper an lower case letters, numbers, operators and punctuation. However, the cursor keys behave differently within terminal emulation.

The LEFT and RIGHT cursor keys operate like shift keys.

The LEFT cursor key acts like the CONTROL key on a PC enabling you to send the control characters such as <SUB>, or CONTROL-Z (ASCII 26) for end of file, <DC3>, or CONTROL-S (ASCII 19) for pause, <DC 1>, or CONTROL-O (ASCII 17) for continue and so on.

The RIGHT cursor key acts a "special" shift key which allows you to send characters which cannot otherwise be sent with normal keyboard behaviour. The additional characters which are made available by the LEFT and RIGHT cursor keys are shown in the table below.

LEFTwith:ASCII CHARRIGHTwith:ASCII CHAR
A01^AA1B^[
B02^BB1C^\
C03^CC1D^]
D04^DD1E^^
E05^EE1F^_
F06^FF21!
G07bellG23#
H08backspaceH26&
I09tabI27'
J0Aline feedJ3F?
K0B^KK40@
L0Cform feedL5B[
M0Dcarr. returnM5C\
N0E^NN5D]
O0F^OO5E^
P10^PP5F_
Q11XONQ60`
R12^RR7B{
S13XOFFS7C|
T14^TT7D}
U15^UU7E~
V16^VV7Fdel left
W17^WW3F?
X18^XX3F?
Y19^YY3F?
Z1A^ZZ3F?

Note that on the Organiser, the ASCII \ character is displayed as a Yen sign and the ASCII ~ character is displayed as a right arrow sign.

The DOWN cursor keys pauses the display and the UP cursor starts the display again. You will not lose any data provided you are using handshaking.

To exit terminal emulation and return to the COMMS menu, press ON/CLEAR. You will not lose any data when you exit and re-enter terminal emulation, provided you are using handshaking.

Except for <NUL> (ASCII 0) and <TAB> (ASCII 9), received characters below ASCII 32 are displayed as ^A for ASCII 1, ^B for ASCII 2, ^C for ASCII 3 and so on. All received <NUL>s are discarded. A received REOL will scroll the display, and is then discarded. A received REOF will also be discarded. Received <TAB> characters (which are used to delimit fields in data records) are displayed using a special <TAB> graphic, shown in figure 6.1.

         
         
         
         
         
         
         
         

Figure 6.1 The <TAB> Graphic

File Transfer During Terminal Emulation

You can still use TRANSMIT and RECEIVE with PROTOCOL set to NONE to upload data to a host and capture data from it.

For example, to send a file to a host, such as an electronic mail file, enter terminal emulation and type to the host in the normal way. At the point where the software on the host is expecting you to type in the data, press ON/CLEAR to return to the COMMS menu and then use TRANSMIT to send the data. You can either re-enter terminal emulation to type the sequence which indicates to the host that the data is complete or set the TEOF parameter to the correct sequence (you may find that the default is correct).

To receive data from a host, type a command which would display the data you want to receive followed by the REOF sequence. Before pressing EXE to enter this command on the host, hold down the RIGHT key and press S to send an XOFF character to the host, pausing the output until you are ready to receive it. Now press EXE to complete the command for the host to send the file. Press ON/CLEAR to get the COMMS menu and then use RECEIVE to capture the data. When the RECEIVE command starts, it sends an XON and the host starts transmission.

If the data you are receiving does not end with your REOF sequence, press ON/CLEAR to save the data when the transmission has finished.

An alternative way of capturing data is to enter terminal emulation via the CAPTURE command, as described in the next section.

6.19 CAPTURE

Selecting the CAPTURE command presents a menu of commands which are associated with the capture buffer. The CAPTURE menu contains the following items:

TERMenters terminal emulation with capture enabled
EDITenters the capture buffer editor
CLEARclears the capture buffer
SAVEsaves capture buffer data to data file or procedure
TRANSMITtransmits the data in the capture buffer

SAVE, TRANSMIT and CLEAR will only operate when the capture buffer contains data. A BUFFER IS EMPTY message will be displayed if this is not the case.

Selecting TERM (just press EXE) enters terminal emulation such that displayed data is recorded in the capture buffer. Pressing ON/CLEAR returns to the CAPTURE menu.

Using TERM under CAPTURE can rapidly consume your free memory and you should not be too casual about leaving large amounts of data in the capture buffer as you may find that various operations on the Organiser will fail with an OUT OF MEMORY message.

If the Organiser runs out of memory while data is being captured, terminal emulation is aborted and an OUT OF MEMORY message is displayed. Press SPACE to exit to the CAPTURE menu. You may take the opportunity to release memory (for example, by deleting some or all of the data in the capture buffer) before returning to terminal emulation. Provided that handshaking is in use, you will not miss any received data.

Selecting EDIT enters the capture buffer editor from which you can view and modify the contents of the capture buffer. EDIT behaves almost identically to the procedure editor under the top-level menu PROG command. The cursor scan through captured lines; the LEFT and RIGHT arrow keys move the cursor within a line; ON/CLEAR deletes a line; EXE splits a line at the cursor position; DEL and SHIFT DEL delete left and right respectively and key presses corresponding to printable characters insert at the cursor position.

The differences are that received <TAB> characters are displayed with a special <TAB> graphic and that the MODE key returns to the CAPTURE menu.

The EDIT command can also be used to prepare data "off line" for subsequent transfer to a host (but remember that Comms Link must be plugged into the Organiser while you use any facilities under the COMMS menu).

The CLEAR command requests confirmation before it erases the entire contents of the capture buffer.

The SAVE option behaves similarly to the COMMS menu RECEIVE command (when PROTOCOL is set to NONE) and presents the PROCEDURE or FILE menu followed by a request for the file name to save to.

The TRANSMIT command under the CAPTURE menu behaves in the same way as TRANSMIT under the COMMS menu (including the way it depends on the PROTOCOL parameter) except that it transmits the contents of the capture buffer without prompting for FILE or PROCEDURE or for a file name on the Organiser. The data in the capture buffer is subject to TTRN processing as it is transmitted (even when the PROTOCOL parameter is PSION)

6.20 AUTO

The AUTO command is an aid to determining the SETUP parameters BAUD, PARITY, BITS and STOP (with the exception of MARK and SPACE parity) which agree with the setting on the communicating device (especially a printer).

The command cycles through all combinations of BAUD, PARITY, BITS and STOP transmitting a line of text for each combination. The text contains a message which identifies the four parameters so that if the device receives the text without corruption. you can read the correct values of the parameters to use in SETUP.

While the program is running. the display continuously shows the combination of the parameters which is currently being transmitted. Press ON/CLEAR to abort AUTO when you are satisfied that you know the correct values. If you leave AUTO running it will return to the COMMS menu when it has tried every combination. Either way. the settings that were in force before AUTO was selected will be restored.

The AUTO command does not aid the setting of the handshaking parameter, HAND.

6.21BOOT

The BOOT command only works when the Organiser is connected to an IBM PC/XT/AT or compatible running the supplied communications program CL. It is used to run communications (written in the Organiser processor's machine code) on the Organiser, which are saved as files on the PC.

Comms Link is not supplied with any applications of this type, but the BOOT command provides a "hook" for applications (particularly communications applications) to be provided on floppy disk alone.

When you enter the BOOT command. Comms Link prompts for the name of the application to run. The subsequent behaviour of the command depends upon the application.

If you accidentally enter the BOOT command press ON/CLEAR to abort the prompt for the application name and return to the COMMS menu. If you enter a name when you are not connected a PC running CL or if the application does not exist on the PC you will get an error message after a few seconds wait. You can then press SPACE to return to the COMMS menu.


7. COMMS LINK AND OPL

This chapter assumes that you are familiar with the Organiser programming language (OPL). OPL is described in detail in the Organiser 2 Operating Manual.

When Comms Link is fitted to the Organiser, OPL programs may use the LPRINT command to transmit data and also a number of communications procedures. These procedures are called in exactly the same way that you would call your own procedures and are loaded from the Comms Link device. You should avoid giving any of your own procedures the same name as any of the procedures described here.

In addition to the LPRINT command, the LSET, LINPUT$ and TRIG$ procedures may be used to communicate with any other device. They operate as follows:

LSETSet the communications parameters
LINPUT$Receive a line of data
TRIG$Transmit data then receive a line of data

Note that the user can abort the LPRINT, LINPUT$ and TRIG$ commands by pressing ON/CLEAR. This feature can be disabled by using the ESCAPE OFF command.

The remaining communications procedures are protocol based and may only be used when the Organiser is connected to a PC running the supplied communications program CL. If the Organiser is not connected to a PC which is running CL, the procedure will fail with a DEVICE READ ERR (error number 193) after a few seconds. Communication using protocol-based procedures is error checked and is generally more reliable than the non-protocol procedures.

Two procedures XTSEND and XTRECV allow OPL programs to exchange files (including binary files) with the PC. They are:

XTSENDSend a file to the PC
XTRECVReceive a file from the PC

You can directly access binary files, text files and "directory files" on the PC with a comprehensive set of file procedures. These are as follows:

XFOPENOpen a file
XFCLOSEClose the open file
XFGET$Read data from the open file
XFPUTWrite data to the open file
XFPOSSet the current file position
XFEOFReturn end of file status

Only one file may be open at a time.

The following procedure names are used internally:
XLCON
XLDIS
XLPUT
XLGET$
XMLOAD

and you should also avoid these names.

If an error occurs in any of the Comms Link procedures an error is "raised" in the normal way. See, the "Error Handling" chapter in Organiser 2 Operating Manual for a description of OPL error handling facilities. If the OPL program does not trap errors, the program will terminate when an error occurs, displaying an error message which corresponds to the error number.

When using the protocol based procedures, the error can be generated by the software on the PC (the server) rather than the Organiser. For example, the server might fail with a DISK FULL error on the PC. When this is the case, the error number will have a value from 190 downwards and an error message will be displayed on the PC screen. There is no message text stored in the Organiser which is associated with such error number's and, although the OPL function ERR will correctly return the error number, ERR$ will always return "*** ERROR ***" rather than a specific error message.

You should always trap errors (using the TRAP and ONERR commands) when using the protocol-based procedures, otherwise you will not get an informative error message when the program terminates.

7.1 LSET

The LSET procedure is used to set the current value of the communications parameters without having to use the SETUP option in the COMMS menu. Parameters which are changed by LSET remain changed when the OPL program terminates. The syntax is:

LSET:(BAUD%, PARITY%, BITS%, STOP%, HAND%, ECHO%, WIDTH%, REOL$, REOF$, RTRN$, TEOL$, TEOF$, TTRN$, TIMEOUT%, PROTOCOL%)

where the procedure parameters correspond to the communications parameters which appear in the SETUP command under the COMMS menu.

The meaning of the parameters are described fully in the previous chapter "The COMMS Menu" in the section on the SETUP command. Except for the trailing % or $, the names of the procedure parameter names used here correspond to the parameter names used by the SETUP command.

Any procedure parameter may be set to -1 in which case the current value of that parameter is not changed by the call to LSET. For example, the line:

LSET:(-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 3, -1)

sets the TIMEOUT parameter to 3 seconds without affecting the current setting of any of the other SETUP parameters.

If there are trailing parameters which you do not wish to change, they may be omitted. The line:

LSET:(-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 3)

has the same effect as the previous example, and, as another example:

LSET:(1200)

sets the Baud rate to 1200.

Omitting all the parameters to LSET is a special case and has the effect of restoring the complete set of communications parameters to their default values.

As in SETUP, the communications parameters may only take their value from a list of allowed values. The LSET parameters BAUD%, PARITY%, BITS%, STOP%, HAND%, ECHO%, and PROTOCOL% are specified in this way and the correctly ordered lists are:

ParameterRangeValue List
BAUD%50-960050, 75, 110, 150, 300, 600, 1200, 2400, 4800, 9600
PARITY%0-4NONE, ODD, EVEN, MARK, SPACE
BITS%7-87 BIT DATA, 8 BIT DATA
STOP%1-21 STOP BIT, 2 STOP BITS
HAND%0-7NONE, XON, RTS, XON+RTS, DTR, XON+DTR, RTS+DTR, ALL
ECHO%0-1LOCAL, HOST
PROTOCOL%0-2NONE, XMODEM, PSION

For example, the line:

LSET:(9600,2,8,1)

sets the communications parameters to 9600 Baud, even parity, 8 data bits and 1 stop bit.

The parameters WIDTH% and TIMEOUT% are set to zero to indicate NONE. WIDTH% should be an integer in the range 1 to 250 to specify the maximum line width and TIMEOUT% should be an integer in the range 1 to 255 to specify the transmission time out interval in seconds.

The remaining 6 parameters (REOL$, REOF$, RTRN$, TEOL$, TEOF$ and TTRN$) are a string of zero, one or two characters. A zero length string corresponds to the SETUP value NONE. A one or two character length string corresponds to the one or two characters of the corresponding SETUP parameter.

For example, the line:

LSET:(-1, -1, -1, -1, -1, -1, -1, -1, -1, "/"+CHR$(9), -1, -1, CHR$(9)+"/")

sets RTRN and TTRN such that "/" is converted to <TAB>on input and <TAB> is converted to "/" on output.

7.2 LPRINT

LPRINT is an OPL command which is built into the language. However, LPRINT will fail unless Comms Link is connected to the Organiser. LPRlNT has the same syntax as the PRINT command and operates in the same way except that output is transmitted to the connected device rather than to the display. Both PRINT and LPRINT are described in the Organiser 2 Operating Manual.

LPRINT data is subject to TTRN processing and, after TTRN processing, any occurrences of <CR> and <SUB> are converted to TEOL and TEOF sequences respectively. Note that a trailing <CR> is added by the LPRINT command if the command does not end with a semicolon.

The LPRINT command uses the following SETUP parameters:

BAUD, PARITY, BITS, STOP, HAND, WIDTH, TIMEOUT, TEOL TEOF, TTRN

7.3 LINPUT$

The LINPUT$ procedure is used to receive data from the communicating device. The use of the procedure is as follows:

data$=LINPUT$:(n%)

or:

data$=LINPUT$:(n%,t%)

where n% is an integer in the range 0 to 255. A special case of the command is when the value of n% is 0, when any received data in the input buffer is discarded. If n% is non-zero, LINPUT$ returns n% bytes or, if an REOL or REOF is received, the characters up to and including the REOL or REOF. Typically, the n% will match the length allocated to the string variable data$ which is to take the received data.

The optional parameter t% specifies a timeout in seconds. If this parameter is omitted or has the value zero, LINPUT$ will wait indefinitely until an REOL or REOF sequence or n% characters are received. If t% is in the range 1 to 255, specifying a timeout interval in seconds, LINPUT$ returns with as many characters as it had received when the timeout timer expired. The timer expires when no character has been received for the specified time.

If you have the choice, it is safer to use a one character REOL and REOF. A two character REOL or REOF can be split over two LINPUT procedure calls if the first character of the happens to arrived as the last character allowed by the n% parameter.

The LINPUT$ procedure uses the following SETUP parameters:

BAUD, PARITY, BITS, STOP, HAND, REOL, REOF, RTRN

7.4 TRIG$

The TRIG$ procedure is similar to the LINPUT$ procedure except that a string is first transmitted before waiting for received data. The use of the procedure is as follows:

data$=TRIG$:(n%, a$)

or:

data$=TRIG$:(n%, t%, a$)

The parameters n% and t% are as for LINPUT$, above.

The parameter a$ is the string to be transmitted before waiting for received data. The output string is subject to TTRN processing and any occurrences of <CR> and <SUB> are converted to TEOL and TEOF sequences respectively.

Using the TRIG$ procedure is equivalent to an LPRINT command followed by a call to LINPUT$ and is slightly faster.

The TRIG$ procedure uses the following SETUP parameters:

BAUD, PARITY, BITS, STOP, HAND, WIDTH, TIMEOUT, TEOL, TEOF, TTRN, REOL, REOF, RTRN

7.5 FILE TRANSFER PROCEDURES

The file transfer procedures, XTSEND and XTRECV, are used to send a file to and receive a file from a PC which is running the supplied communications program CL.

The procedure to send a file, XTSEND, has the syntax:

XTSEND: (remote$, local$, type%)

and the procedure to receive a file, XTRECV, has the same syntax:

XTRECV:(remote$, local$, type%)

XTSEND sends the Organiser file with file name local$ and of type type% to the PC, giving it the pathname remote$. Any existing file on the PC of the same name is replaced.

XTRECV provides the converse operation to XTSEND and restores the PC file with file name remote$ to the Organiser, giving the created file the file name loca1$. Any existing file on the Organiser of the same name is replaced.

The organiser file name local$ includes the device name (A, B, C or D) in the same way as, for example, the OPL OPEN command.

The PC file name remote$ may either give the full pathname of the file or just the file name, in which case the current directory (when CL was run) will be used. Any "/" character in remote$ is translated to a "\" character by the server, allowing pathnames to be easily specified. If the file name does not contain a file name extension, an extension is generated from the type% parameter and added to the file name. The generated extensions are:

type%Extension
0ODB
1OPL
2OB2
3OB3
4OB4
5OB5

The parameter type% specifies the Organiser file type and should be one of the following:

0 - a data file
1 - a procedure file (source only)
2 - a diary file
3 - a procedure file
4 - a Comms link setup file
5 - a spreadsheet file

File types 0 and 1 produce text files on the PC which can be manipulated directly on the PC. For example, you can edit a procedure file on the PC using your normal editor or word processor. Using XTSEND and XTRECV with file types 0 and 1 form the same functions as TRANSMIT and RECEIVE in the COMMS menu (as described in the previous chapter). In TRANSMIT and RECEIVE, the choice between FILE or PROCEDURE corresponds to file types 0 and 1 respectively.

File types 2 to 5 inclusive produce binary files on the IBM PC. These files are not directly usable on the PC except by the XTRECV procedure when restoring files to the Organiser.

File types 1 and 3 both deal with procedure files (which are binary files) on the Organiser. When using TRANSMIT or XTSEND with type% set to 1 the procedure source (i.e. the plain text version) is extracted from the binary procedure file to create an editable text file on the PC. When using RECEIVE or XTRECV with type% set to 1, the text file is converted to a binary procedure file on the Organiser which contains only the source (so you have to translate the procedure before you can call it). Transfers with type% set to 3, however, correspond to simply copying a binary file from one machine to another where the procedure file may contain the source only, the source plus the translated source or just the translated source.

Transfers using file type 3 can be used to save translated procedures on the IBM PC which can later be restored and called in the normal way, effectively providing a means of loading and running OPL programs which are stored on the IBM PC.

The XTSEND and XTRECV procedures use the following SETUP parameters:

BAUD, HAND, TTRN, RTRN

Note that XON/XOFF handshaking is disabled regardless of the value of HAND. TTRN is only used by XTSEND and only when type% is 0. RTRN is only used by XTRECV, and only when type% is 0.

Apart from the normal Organiser errors, the following server errors may raised by XTRECV or XTSEND:

190 (BAD PARAMETER) - the pathname remote$ is illegal.

189 (FILE NOT FOUND) - XTRECV could not find the file with pathname remote$ or the file with that name is of the wrong type.

186 (DISK FULL) - XTSEND failed to find room on the remote disk.

188 (SERVER ERROR) - a miscellaneous server error has occurred, for example, a disk door was open.

185 (RECORD TOO LONG) - XTRECV failed when reading a record which is longer than the maximum record length of 255 characters.

7.6 REMOTE FILE ACCESS PROCEDURES

The file access procedures provide access to one file at a time on an attached PC running the supplied communications program CL.

XFOPEN

The XFOPEN procedure is used to open a tile on the PC. The syntax is:

XFOPEN:(remote$, amode%, ftype%)

where remote$ is the pathname of the file on the PC, amode% specifies the file access mode, and ftype% specifies the remote file type.

Only one file may be open at a time. XFCLOSE must be used before another file may be opened using XFOPEN or before a file can be transferred using XTRECV or XTSEND (the procedure will fail with error number 199, FILE IN USE, if a remote file is already open).

The PC file name remote$ may either give the full path name of the file or just the file name, in which case the current directory (when CL was run) will be used. Any "/" character in remote$ is translated to a "\" character by the server, allowing pathnames to be easily specified.

The file type is specified by the parameter ftype% which is one of:

0 - BINARY
1 - TEXT
2 - DIRECTORY

Binary files are random access files which consist of a byte stream and have no record structure.

Text files are variable length record sequential tiles where each record normally contains characters with ASCII codes greater than 31 (although this is not enforced). The maximum record length (excluding any record terminator) is 254 bytes - the maximum string length in OPL. On the PC each record is terminated by <CR>,<LF>.

Directory files behave like sequential files which may only be read. The path name remote$ specifies a normal PCDOS directory search string. When a directory 'file' has been opened, the records made available to XFGET$ each contain the name of one file found in the path and directory given in remote$. When the last record has been accessed and EOF is returned, the file is automatically closed.

A file may be opened in one of five access modes, as specified by the parameter amode%:

0 - READ
1 - CREATE/REPLACE
2 - REPLACE
3 - CREATE
4 - UPDATE

When amode% is READ, the remote file is opened for reading only and XFOPEN will only fail if the file cannot be found.

When amode% is CREATE/REPLACE, a new file is created for writing and, if the file is a binary file (i.e. a random access file) reading. Any existing file of the same name is deleted.

When amode% is REPLACE, XFOPEN behaves as for CREATE/REPLACE except that it will fail if the file does not already exist.

When the amode% is CREATE, XFOPEN behaves as for CREATE/REPLACE except that it will fail is the file already exists.

When amode% is UPDATE, the file is opened for writing and, if the file is a binary file (i.e. a random access file), reading. XFOPEN will fail if the file does not already exist.

When ftype% is DIRECTORY, XFOPEN will fail unless amode% is READ. When ftype% is either BINARY or TEXT, any of the above values of amode% are valid. Setting amode% to UPDATE has a different meaning depending on whether ftype% is BINARY or TEXT.

When amode% is UPDATE and ftype% is TEXT, the file is positioned initially at the end of the file, allowing records to be appended to the file. When ftype% is BINARY, the file is positioned initially at the beginning of the file end you may read and write to the file.

Apart from the normal Organiser errors, the following server errors may be raised by XFOPEN:

190 (BAD PARAMETER) - the pathname remote$ is illegal or amode% or ftype% is not valid.

189 (FILE NOT FOUND) - amode% is 0.2 or 4 and XFOPEN could not find the file with pathname remote$.

187 (FILE ALREADY EXISTS) - amode% is 3 and the file with pathname remote$ already exists.

188 (SERVER ERROR) a miscellaneous server error has occurred, for example, a disk door was open.

XFCLOSE

Closes the open file and returns when the file has been closed. XFCLOSE has no parameters XFCLOSE is harmless and reports no error if there is no open file.

XFEOF

XFEOF returns zero (false) if a file is open and -1.0 (true) if a file is closed. When an end of file is reached by a call to XFGET$, described below, the file is closed and XFEOF will return true.

XFGET$

The XFGET$ procedure reads data from the current position in the file and returns the data as a string. The syntax is:

data$=XFGET$:(len%)

where the returned string is required to be of length len% or less. The parameter len% may be between 0 and 255 inclusive.

If the file is a binary file (ftype% was 0 in XFOPEN), XFGET$ reads len% bytes from the file and advances the file position by len% bytes. Unless the end of file is reached, the returned string is of length len%.

When an end of file is encountered, less than len% bytes may be read and a string which is shorter than len% will be returned. The file is then closed and the XFEOF procedure will return -1.0 (true).

If the file is a text file or a directory file (i.e. ftype% was 1 or 2 in XFOPEN), XFGET$ reads a record from the file and positions to the next record. The returned record data does not include the <CR><LF> record terminator. If XFGET$ is called after the last record has been read, a zero length string is returned, the file is closed and XFEOF will return -1.0 (true). Apart from the normal Organiser errors, the following server errors may be raised by XFGET$:

185 (RECORD TOO LONG) - ftype% is 1 and the record data length exceeds len%.

188 (SERVER ERROR) - a miscellaneous server error has occurred, for example, a disk door was open.

XFPUT

The XFPUT procedure writes data to the current position in the open file on the PC. The syntax is:

XFPUT:(data$)

XFPUT will fail if the file is open for reading only (i.e., amode% was 0 in XFOPEN).

If the file is a text file (ftype% was 1 in XFOPEN), a new record is appended to the file.

The file position is set to the end of the data written by XFPUT.

186 (DISK FULL) - XFPUT failed to find room on the remote disk.

188 (SERVER ERROR) - a miscellaneous server error has occurred, for example, a disk door was open.

XFPOS

XFPOS sets the current file position on binary files and returns the new position. XFPOS will fail if ftype% was not 0 in XFOPEN. The syntax is:

newpos=XFPOS:(mode%, pos)

The new position is specified by the parameters mode% and pos. Depending on whether mode% is 0, 1 or 2, the parameter pos is interpreted as follows:

0 - relative to the start of the file
1 - relative to the current position
2 - relative to the end of file

For example. when mode% is 1 and pos is 0, XFPOS returns the current position, leaving it unchanged.

The remote file access procedures use the following SETUP parameters:

BAUD, HAND

Note that XON/XOFF handshaking is disabled regardless of the value of HAND.

APPENDICES

APPENDIX A

ASCII CONTROL CHARACTERS

The names of the ASCII characters numbered 0 to 32 are shown below. For the printable ASCII character set, see appendix A of the Organiser 2 Operating Manual.

0NUL16DLE
1SOH17DC1 (XON)
2STX18DC2
3ETX19DC3 (XOFF)
4EOT20DC4
5ENQ21NAK
6ACK22SYN
7BEL23ETB
8BS24CAN
9HT25EM
10LF26SUB
11VT27ESC
12FF28FS
13CR29GS
14SO30RS
15SI31US

APPENDIX B

THE COMMS LINK INTERFACE

This appendix describes the hardware interface which is presented by the Comms Link cable and contains technical information which may be required for advanced communications applications or for building your own adaptor.

DCE INTERFACE

The RS232 standard is based on an assumption that communicating devices do so via a pair of modems as in figure B.1.

Connecting via Modems
Figure B.1 Connecting via Modems

In the standard, the more general terms DTE (Data Terminal Equipment) for computers and printers and DCE (Data Circuit Terminating Equipment) for modems are used.

If the DCE and DTE have standard RS232 sockets, the DTE will have a 25 pin D-type male connector and the DCE will have the corresponding female connector. The RS232 cable between the two is a regular "straight through" connector which is male at one end and female at the other. In fact, you only need a cable at all because the connectors are usually mounted on the chassis of the equipment and cannot be physically brought together.

Modems are used to transfer data over long distances using low grade wires which were designed for transferring speech rather than data. In practice, the RS232 standard is often used over short distances where there is no need for a pair of modems and the computers (or DTEs) are connected "back to back" as in figure B.2.

Direct Connection
Figure B.2 Direct Connection

In figure B.2, the cable between the computers (or DTEs) is not a simple "straight through" cable, as exists between the DCE (modem) and DTE (computer) in figure B.1. The cable in figure B.2 replaces the pair of modems and is called a "null modem cable". A standard null modem cable is female at both ends and is wired specially to simulate the effect of a modem link.

Although the Organiser is a DTE, the majority of Comms Link users will not be using a modem, so a null modem cable is "built in" such that the Comms Link cable will plug directly into most computers without requiring additional leads or adaptors. To the DTE (e.g. computer), the Organiser 25 pin D-type female connector emulates a DCE (modem) interface.

Emulating a DCE works when the DTE conforms strictly to the RS232 standard. This is true of most computers and some printers. For example, the IBM PC/XT and most compatibles conform to the standard and the Comms Link connector will plug directly into these computers. However, some computers and many printers do not conform and, for example, both the IBM AT and Apple Macintosh use non-standard 9 pin connectors. Other DTE's, particularly printers, may use a standard 25 pin connector but with a non-standard gender (female rather than male).

When the device you are trying to connect to does not present a 25 pin male DTE interface, either because it is a non-standard DTE or a DCE, you need an adaptor.

CONNECTOR PIN ASSIGNMENTS

Although there are 25 pins on the D-type socket, only eight are connected through to the Organiser. Because the built-in null modem cable swaps the active lines, it is easy to get confused about the names of the lines, depending on whether you take the view of the Organiser or the attached DTE. Figure B.3 shows the pin assignments on the Comms Link socket, the signal names from both points of view and the direction of signal flow for each pin.

ORGANISER   PIN   FLOW   ATTACHED DTE
FG1 FG
SG7 SG
RD2<-TD
TD3->RD
CTS4<-RTS
RTS5->CTS
DSR20<-DTR
DTR6->DSR

Figure B.3 Comms Link cable pin assignments

FG and SG stand for Frame Ground (earth) and Signal Ground (common return) respectively.

TD and RD stand for Transmitted Data and Received Data and carry the data signals.

RTS and CTS stand for Request To Send and Clear To Send and are the control lines which support RTS/CTS handshaking.

DSR and DTR stand for Data Terminal Ready and Data Set Ready. Although the Organiser can read pin 20, it cannot drive pin 6. However, pin 6 is connected to pin 20 via the Organiser so that if the DTE drives pin 20, it will see an asserted pin 6.

Pin 20 on the Organiser is also connected in a way which has the same effect as the ON/CLEAR key. The Organiser can be switched on by asserting pin 20 an it will not switch off while pin 20 is held high. The main application of this feature is when the Organiser is connected to an auto-answer modem which is waiting to be dialled. Connecting an Organiser to a modem is discussed in the following section.

ADAPTORS

An adaptor consists of two connectors which are wired back to back. One of the connectors is a 25 pin D-type male connector which plugs into the female connector on the Comms Link cable while the other end of the adaptor plugs into your computer, printer or modem. The wiring between the connectors may swap some lines (in the case of a modem adaptor), exclude unnecessary connections and correct for any non-standard pin assignments.

Computer With A Non-standard Connector

If the connector on your computer is a 25 pin female, rather than a male, you need a male-to-male gender changer. Gender changers which connect all 25 lines are widely available. If you make your own you need only connect the 8 pins (1-7 and 20) used by the Organiser. Psion supplies a printer adaptor which is a slightly embellished gender changer (described below) and which is suitable for computers with a female connector.

If the connector is not a standard 25 pin D-type, buying a modern cable for your computer (if you do not already have one) will give you a cable which will double as a suitable adaptor for the Organiser (since the Comms Link cable presents a DCE interface). If you want to build your own adaptor, from a 25 pin male connector and a connector which plugs into your computer, you should match the names in the right hand column of figure B.3 with the correspondingly labelled pins on the RS232 interface on your computer. Your computer manual (or the manual which came with your serial card) should have a diagram which gives the pin assignments.

The IBM AT uses a 9 pin miniature D-type male connector. Psion supplies an adaptor for the IBM AT which is based on figure B.4.

ORGANISER
(25 PIN MALE)   
IBM AT
(9 PIN FEMALE)
2--<--3      (TD)
3-->--2(RD)
4--<--7(RTS)
5-->--8(CTS)
6-->--6(DSR)
7-----5(SG)
20--<--4(DTR)

Figure B.4 IBM AT Adaptor

The Apple Macintosh uses a 9 pin miniature D-type female connector. The Mac Plus has a different non-standard connector but an adaptor which presents the same interface as the regular Macintosh is normally supplied with the Mac Plus. Psion supplies an adaptor for the Apple Macintosh which is based on figure B.5.

ORGANISER
(25 PIN MALE)   
MACINTOSH
(9 PIN MALE)
2--<--5      (TD-)
3-->--9(RD-)
4--<--6(DTR)
5-->--7(DSR)
7-----3,4(SG)

Figure B.5 Apple Macintosh Adaptor

The Macintosh hardware does not support the RTS and CTS handshake lines but it does Support DSR/DTR handshaking in the sense that it can be paused when it sees its DSR asserted (DTR on the Macintosh is a constant +12 Volts or SPACE state). Since the Organiser cannot drive DTR, DSR/DTR is swapped to RTS/CTS on the Macintosh adaptor so that hardware handshaking will take place if the Organiser has RIS/CIS handshaking enabled.

Connecting To A Printer

Many printers present a DTE female connector (rather than the standard male connector) and a gender changer will often suffice. However, some printers also require DCD (Data Carrier Detect) to be asserted and a printer adaptor may accomplish this by connecting pin 8 to pin 5. The printer adaptor supplied by Psion is reversible and is based on figure B.6.

ORGANISER
(25 PIN MALE)   
PRINTER
(25 PIN MALE)
1-----1      (FG)
2--<--2(ID)
3-->--3(RD)
4--<--4(RTS)
8,5-->--5,8(CTS+DCD)
6-->--6(DSR)
7-----7(SG)
20--<--20(DTR)

Figure B.6 Printer Adaptor

Connecting To A Modem

To connect the Comms Link interface to a modem (or to another Organiser), you need to swap the three pairs of signal lines (TD and RD. RTS and CTS, DSR and DTR) back from a DCE interface to a DTE interface.

If you wish to originate (i.e. dial from the Organiser), the link on the Organiser between DTR and DSR will stop the modem from working. If DTR and DSR pins are not connected on the modem, the modem circuitry will usually pull DTR to a state which will allow the modem to work. For simple modem use, it is advisable that pins 6 and 20 are not connected, and Psion supplies a modem adaptor which is based on figure B.7.

ORGANISER
(25 PIN MALE)   
MODEM
(25 PIN MALE)
1-----1   (FG)
2--<--3   (RD)
3-->--2   (TD)
4--<--5   (RTS)
620   (DTR)
7-----7   (SG)
206   (DSR)

Figure B.7 Modem Adaptor

If you wish to connect the Organiser to an auto-answer modem in such a way that it can wait in an "off" state (where it uses very little power) and be woken up when the modem answers a call, you should connect DSR (pin 6 on the modem to pin 20 on the Organiser). In this case, the adaptor will not be reversible and you should label the ends appropriately. Use the OPL command OFF to switch off the Organiser and pause until DSR is asserted by the modem when it answers a call.

RS232 OPERATION

Because the Comms Link cable contains the software on ROM and because of power conserving features of the Organiser, the operation of the RS232 port is more complex than for other computers.

In this section, the RS232 lines are described from the Organiser point of view and you should read the left hand column of figure B.3 when converting the pin names into pin numbers.

The RS232 port can be in one of three states, OFF, POWERED and SELECTED.

The OFF State

In the OFF state, no voltage is applied to any of the pins of Comms Link connector and the signals seen by the connected device will depend upon the hardware design of that device.

The RS232 port is OFF when no power is supplied to the top port. Actually, the Organiser architecture is such that power is either supplied to all three ports or to none of them.

Normally, in the interests of power conservation, the Organiser switches oft the ports whenever the software is waiting for a key press. In Comms Link terminal emulation, however, this effect is disabled.

When the Organiser is switched off, the ports are also off. The Organiser is switched off when the top-level menu OFF command is used, when the Organiser has automatically switched itself off after being left for five minutes without a key press (except in terminal emulation), or when the OPL command OFF is used.

The POWERED State

The RS232 port is in the POWERED state when power is supplied to the ports and the RS232 hardware is not selected.

In the POWERED state, the Organiser is unable to send or receive data, to set the state of RTS, or to read CTS or DTR. However, the hardware drives TD and RTS to the MARK state such that the communicating device will see no data and, provided that it is using RTS/CTS handshaking, it will not send any data to the Organiser. If XON/XOFF handshaking is enabled, the Comms Link software sends an XOFF followed by a delay (to give the communicating device a chance to respond to the XOFF) before entering into the POWERED state from the SELECTED state.

The RS232 port is in the POWERED state when a datapack is being accessed or when the Comms Link ROM is being accessed. For example, a procedure call to any of the extensions to OPL supplied by the Comms Link will put the RS232 port into a POWERED state.

The SELECTED State

The RS232 port is in the SELECTED state when power is supplied to the ports and the RS232 hardware is selected.

In the SELECTED state, the Organiser is able to send and receive data, drive RTS, and read CTS and DTR. Received data is stored in a receive buffer by an interrupt routine.

When the RS232 port is in the SELECTED state, RTS is output in the SPACE state and is only temporarily output in the MARK state when RTS/CTS handshaking is enabled and the receive buffer is nearly full. Also, when RTS/CTS handshaking is enabled, transmission is paused when CTS is in the MARK state (otherwise CTS is ignored). When CTS is not connected on the Organiser, it floats to the MARK state and RTS/CTS handshaking should not be enabled when CTS is not connected.

The RS232 port is in the SELECTED state during terminal emulation and when data is input or output to the RS232 port. It normally remains in the SELECTED state until something happens to move it to the POWERED state (e.g. a datapack access) or to the OFF state (e.g. waiting for a key press).

INDEX

A


Adaptor
Ascii codes, 2
Auto-answer modem

B


Backing up Comms Link disk
Binary files

C


CAPTURE
  AUTO
  menu
COMMS
  BOOT
  CAPTURE
  menu, 2
  RECEIVE, 2
  SETUP
  TERM
  TRANSMIT, 2
Comms Link
  fitting
  removing
Comms Link hardware
Connector wiring

D


Data files, 2
Disk
  backing up
DTR handshaking, 2, 3

E


Electronic mail

F


Fitting Comms Link

G


Gender changer, 2, 3

H


Handshaking, 2, 3
Hardware

L


Line length

M


Modem, 2, 3

N


Null modem

P


Pin assignments
Printer
  line length, 2
  setting up
Printer adaptor, 151
Printing
  capture buffer
  data files
  from OPL
  MAIN file
  procedure files
Procedure files, 2
PROTOCOL
  NONE, 2, 3, 4, 5
  PSION, 2, 3, 4
  XMODEM, 2, 3, 4, 5
protocol, 2, 3

R


Receive end of file (REOF), 2
Receive end of line (REOL), 2
Receive translate (RTRN), 2
Receiving files, 2, 3
Removing Comms Link
RS232 OFF state
RS232 POWERED state
RS232 SELECTED state
RTS/CTS handshaking, 3

S


Saving a SETUP
Screen scrolling
Sending files, 2, 3
SETUP, 2
  AUTO
  BAUD, 2, 3
  BITS, 2, 3
  changing parameters
  default values
  ECHO
  editing parameters
  HAND, 2, 3
  leaving
  parameters, 2
  PARITY, 2, 3
  PROTOCOL, 2, 3, 2
  REOF, 2
  REOL, 2
  RESET
  RTRN, 2
  STOP, 2, 2
  TEOF, 2, 3
  TEOL, 2, 3
  TIMEOUT, 2
  TTRN, 2, 3
  valid parameters
  WIDTH, 2

T


Terminal emulation
Transmit end of file (TEOF), 2, 3
Transmit end of line (TEOL), 2, 3
Transmit translate (TTRN), 2, 2
Transmitting files, 2, 3

X


XMODEM, 2
XMODEM protocol, 3
XON/XOFF handshaking, 2, 3