how to write a linx terminal serial communication program for almost ...

625 Digital Drive, Plano, TX 75075 Tel: (972) 964-7090 Fax: (972) 964-7643 Web Page: www.linxdata.com
HOW TO WRITE A LINX TERMINAL
SERIAL COMMUNICATION PROGRAM
FOR ALMOST ANY HOST COMPUTER
• Revision Date: October 2000
Article 14

INTRODUCTION
LINX II, III, and IV terminals can be attached to any host computer that has an RS-232
or RS-422 1 serial ASCII communications port.
LINX does not sell special assembly language "drivers" because they are rarely
needed! The exception to this rule is for Ethernet communications (LINX V
terminals). Refer to the TopSail literature to handle this type of host interface.
The LINX II, III, and IV terminals were specifically designed to communicate with any
device that can transmit and receive an asynchronous, serial, ASCII data stream. This
document describes some design criteria for a program that will run on the host computer
and allow it to collect data and control a single terminal or a network.
1.1 INTRODUCTION TO LINX COMMUNICATIONS
The first step in designing the LINX-to-Host interface program is to understand how
LINX terminals communicate. No amount of technical descriptions can replace the
knowledge gained from a short session with a terminal emulation program running on the
host. Even if your ultimate host will be a mainframe, you can connect a PC or a dumb
terminal to the LINX using a null-modem cable and see for yourself how the LINX talks.
We use HyperTerminal for our testing at LINX.
Another useful device is a Data Line Monitor, which, placed between the LINX and the
host computer, will display all data records going to and from each device.
1 The terminal must be ordered with one or the other

This simple program can be written in BASIC on a PC to receive data from a LINX that
is communicating in XON/XOFF comm mode. You can use it to see what the LINX data
records look like.
OPEN "COM1:9600" AS #1
DO
LINE INPUT #1, A$
PRINT A$
LOOP
'Use COM1 port, 9600 baud
'Read in a line from LINX
'Display what you got
'Go back and read another
The data you see will look something like this:
0101000100ON
0101000100MO
Next, read the section in the LINX III User's Guide entitled "Network Directives". Study
the various commands that are available, and the replies that are sent back for each one.
After you have experimented with communications between the LINX master terminal
and the host you will be in a much better position to tackle the details of making a host
program that can provide all of the required functions.

2.0 GENERAL DESIGN CRITERIA
The host program must be able to perform the following functions:
a) Get the status of each terminal on the network
b) Collect data from the LINX network
c) Send commands to one or more terminals
d) Download files to one or more terminals
Before designing the program, we must ask several questions of the intended application,
and of the host computer architecture:
a) Is the host operating system multi-tasking?
b) Is data to be collected in batch,
or will the host be sending replies to the network?
c) Does the collection program need to be embedded in
an application program, or can it be stand-alone?
d) Can the host tolerate unsolicited input from the
LINX master?
2.1 Single-task vs Multi-tasking
If the host operating system is multi-tasking, it will be possible to write a program that is
dedicated to communications with the LINX network. The program will store data in a
file, or in a memory location where other tasks can access it when they require data. This
makes the job of designing a communications program easier than it would be if the
application had to have the communications embedded in it.
2.2 Batch Collection vs Interactive
If the data which is collected from the LINX terminals is to be simply stored in a
sequential file, then the communications program can be relatively simple. It will read
data from the terminal and store it in a file. If records are received from the LINX
network during a program or file download, those records can simply be stored in the
destination file for later processing.
If, on the other hand, the program must perform lookups on a database and send back
replies to the network, then some this must be taken into consideration when designing
the communications routines.
For example, as you study the Polled Mode protocol, you will see that you could
potentially receive records from one LINX as you are downloading a file to another
LINX. These received records would have to be queued up in the host until they can be
processed.

2.3 Embedded vs Stand-alone
There are two ways in which an application program might communicate with a LINX
network:
1. Access the communications port directly
2. Call an independent program to do the communications
If the language used for the application program does not provide access to the
communications port to the LINX terminal network, then a stand-alone program must be
used to collect the data and store it in a file or memory buffer. The application program
must periodically check that file or buffer to see if any data has been collected. For
example, a dBase program running on a PC under MS-DOS could collect data by calling
a TSR comm program, since dBase does not have the ability to talk to the COM port
directly.
2.4 Unsolicited Input and Host Log-in Programs
If the LINX Master terminal is in XON/XOFF mode, it will transmit unsolicited status
records whenever any terminal is taken offline or placed online (See LINX III User's
Guide). The Master terminal also notifies the host that it is the master, as do Sub-masters
and other terminals with network personalities. The host computer must be able to take
this unsolicited input and handle the data appropriately.
If the Master terminal is in POLLED mode (see section 3.1 below), then this is not quite
as much of a problem, because the LINX will not transmit anything until it receives a
carriage return. But if the host has a penchant for broadcasting signon screens that
contain carriage returns, then the LINX will reply with a data record for every carriage
return. The host will be unwittingly sending polls for data, but not storing the replies,
and the LINX network will lose data records as a result.
For example, you cannot attach a LINX terminal to a terminal port on a CICS system
without setting the appropriate tables to automatically log in the terminal. If that is not
done, then the status records transmitted by the LINX network will be sent to the login
program, which will not know what to do with them. On IBM mainframes running
CICS, this can be done with table parameters in VTAM and CICS that specify what
userid to log into, and what TRANSID to append in front of each status record.
On a UNIX system, the line should be DISABLEd to prevent incoming records from
being sent to the login program, rather than an application program designed to process
and store them.

On DEC systems running RSTS/E, if a program OPENs a KBD, then the system
automatically disables the usual login functions, and the line is "owned" by the
application program.
On other systems it is possible to treat the port as a simple communications line, so that
incoming unsolicited records do not get sent to any login program.
If the host computer is unable to handle unsolicited records, then some other device
(a PC) must be placed between the Master LINX and the host computer to filter
these status records.
3.0 DESIGN DETAILS
The specific combination of subroutines necessary to write a network management and
data collection program depends upon the criteria established in Section 2. If the
program needs to have an interactive user interface, then attention must be paid to the
design of formatted screens, graphics, and error messages. If, on the other hand, the
program is going to be running unattended, or be called from a different application
program, then the program can be more spartan.
3.1 COMMUNICATIONS PROTOCOLS
The basis of any network management and data collection program is its communications
subroutines. The LINX master can communicate with the host in one of the following
protocols:
- XON/XOFF
- POLLED
- REQUEST RESPONSE
Note that an archaic protocol called DSR mode may still show up in the COMM PORT
menu of older terminals. This protocol was discontinued as of Version V3.1 of the
LINXBasic terminal firmware (V7.5 for terminals with 128K+ of memory), and should
never be used in older terminals or BARCON terminals.

3.1.1 XON/XOFF
In XON/XOFF protocol, the LINX master terminal sends records to the host whether the
host is ready for them or not. It is therefore best used in an interactive environment,
where each transmission from the LINX is answered with an acknowledgement from the
host.
Example:
LINX Sends
Host Replies
Employee Number Employee name looked up
(garbled record)
Non-Acknowledgement
(re-send) Employee # Employee name looked up
Example:
LINX Sends
Host Replies
15 records "I got your 15 records OK"
15 records (garbled) "I got only 10 records"
(re-send) 15 records "I got your 15 records OK"
XON/XOFF is only suitable for batch data collection if the LINX Master terminal is
guaranteed to be constantly connected to a functional host. In this mode the LINX master
will dump any records collected by the network to the host until it receives an XOFF (hex
13). It will wait for an XON (hex 11) before continuing to transmit. Obviously, if the
host crashes and does not send an XOFF, or if the cable is yanked out of the host, the
LINX network will merrily dump all its data records onto the floor, where they will be
lost forever.
XON/XOFF is the simplest way to hook up a terminal emulator, send some commands to
the LINX network, download programs, and otherwise perform routine maintenance on
the network. It is not, however, recommended for long-term, secure communications
where the loss of data is intolerable.

3.1.2 POLLED
POLLED mode is the next most secure protocol. It is the most popular mode, because it
is both simple and, in most environments, entirely adequate from a data security
standpoint.
LINX Technical Information Document, LINX Polled Mode Protocol, describes this
protocol in detail. Ask for this free document before you attempt to write a polling
program!
In this mode, the LINX master only speaks when spoken to. The host sends a Carriage
Return (CR) to the LINX to request data. There are only 3 valid replies from the LINX:
1. Data record from any terminal in the network;
2. Status record from any terminal in the network;
3. Asterisk (*) if nothing to reply;
No error checking other than character parity is performed, so this protocol is suited for
direct-connect environments where no checksums are not required. (However,
LinxBASIC programs contain their own checksums which are tested by the interpreter.
Therefore, you can assume that no invalid programs will be accepted or run by the LINX,
and any errors which occur during downloading of programs will cause an error message
to be sent back to the host.)
A record will be re-transmitted if the Host sends a (hex 21 or Control/U) to the
LINX.
SPECIAL NOTES:
a. Network Directives constitute a valid POLL for data, so your program should
perform a READ for data after you send each Network Directive.
b. Always poll any available data from a LINX before downloading any new line of
program or data. The host should always send a Carriage Return to the LINX before
each line of command or download file, and should retrieve ALL data records waiting
(keep polling until you receive an asterisk) before sending the next line!

c. ECHO must be disabled! If ECHO is enabled (via the Comm Port Menu), then each
record sent by the Host will first be echoed back to the host, and will then be followed by
the data record. This will cause an out of sync condition to occur which will eventually
crash the LINX! Make sure you have ECHO disabled on the LINX! You will
occasionally see references in this document to POLLED mode using a Question Mark
("?") followed by Carriage Return for its polling sequence. This is permissible, and can
be useful in determining if the LINX has its ECHO enabled.
d. If you receive a garbled record, send a (hex 21 or Control/U) instead of a
, and the LINX Master will re-transmit the record.
e. Just because you receive an asterisk does not mean all the terminals are empty. It
is possible to have data queued up in terminals, and still get a series of several asterisks
due to network polling speeds and other conditions. We suggest you keep polling until
you get several seconds' worth of asterisks before assuming the terminals are all empty.
3.1.3 REQUEST-RESPONSE
It is axiomatic that the most secure protocols are very complex and difficult to implement
and test. The LINX REQUEST-RESPONSE protocol is very secure! This is a true
protocol which involves transmitting ENQ's and receiving ACK's, NAK's, and WACK's.
It is ideal for environments where data is being transmitted via modems or could
otherwise become corrupted by noise on the comm line.
If you have never written a datacomm protocol before, you will find this a lengthy
development and testing process. Since this is a non-trivial matter, we have a 14-page
manual devoted to it. The manual is entitled Request Response LINX Interface Protocol,
and is available from LINX Data Terminals free of charge.

4.0 MACHINE-SPECIFIC HINTS
4.1 UNIX/XENIX
UNIX or XENIX systems, being multi-tasking, can be set up to have a dedicated program
running as a task, communicating with the LINX network. Other tasks can then access
the data once it is stored in a file. Make sure to DISABLE the particular tty port being
used, so that unsolicited status records from the LINX do not trigger the login program.
Set RESPAWN=OFF (no /etc/getty running on the port).
Also use these parameters on the stty command for the LINX port:
parenb -parodd cs7 -cstopb hupcl cread clocal -ignbrk -brkint -ignpar -parmrk -inpck -
istrip -inlcr -igncr -icrnl -iuclc ixon -ixany ixoff -ascedit -isig -icanon -xcase -echo -echoe
-echok -echonl noflsh -opost -olcuc -onlcr -ocrnl -onocr -onlret -ofill -ofdel -page
4.2 VAX
It is important on these systems to build in a 1/4 second or longer time delay between
LINX network polls, to prevent the CPU from being hogged by the data collection
program. The BLC.bas program, distributed as part of the LINX I/O package, was
patterned after a working VAX data collector for LINX terminals.

4.3 IBM Mid-Range Computers
The IBM System 36 and 38 are not capable of communicating via RS-232 without an
intervening protocol converter. This can be either a 5250-to-RS232 black box, or a PC
with both a 5250 emulator card and some software to transfer data to and from its RS-232
COM port. Some vendors are IBM, Black Box, and Emerald Technologies.
An RS-232 port is available on IBM AS/400 computers, which can be used to
communicate directly with LINX networks. LINX distributes a software product for the
AS/400 called LinxASCIIplus 2 which is a set of CL commands that perform all the
network management and data collection functions described in this document. Contact
our Sales and Marketing department for further information.
4.4 Other Computers
LINX resellers have interfaced a wide variety of computers. We will be glad to put you
in touch with others who may have developed programs for the particular machine you
are working with. Contact the Technical Support department at LINX Data Terminals,
Inc.
2 LinxASCIIplus is a trademark of DCS