request response linx interface protocol - LINX Data Terminals

625 Digital Drive, Plano, TX 75075 Tel: (972) 964-7090 Fax: (972) 964-7643 Web Page: www.linxdata.comREQUEST RESPONSE LINX INTERFACEPROTOCOL• Revision Date: January 11, 2000Article 16

TABLE OF CONTENTSOverview............................................................................................................ 3How to Set Request Response Mode................................................................. 4Control Characters ............................................................................................. 4Host Transmitted Data Records ......................................................................... 4LINX Transmitted Data Records ....................................................................... 5Initiation of Communications ............................................................................ 6Polling the Master LINX for Data ..................................................................... 7Sending Data to the Master LINX Data Terminals, Inc. ................................... 8Notes for Proper Implementation....................................................................... 9Appendix A: Host Request Response State Table............................................. 10Appendix B: LINX Master Request Response State Table ............................... 13Appendix C: Implementing a Protocol Using State Tables ............................... 162

OVERVIEWThe REQUEST RESPONSE PROTOCOL is a secure protocol used to connect a LINX Masterterminal o a Host Computer via an RS232 or RS422 port. This is a more robust protocol than thePOLLED MODE PROTOCOL which is commonly used for LINX communication. Thisdocument describes this protocol in detail to allow you to implement a program which cancommunicate with a Master LINX terminal in this manner.The POLLED MODE protocol is unsuitable for noisy communications lines since it does notperform error checking of the data. The REQUEST RESPONSE protocol does error checkingand retransmission of all data blocks, so it is better suited to use between modems and in noisyenvironments.So, why doesn’t everyone use the REQUEST RESPONSE protocol instead of the POLLEDMODE? Two reasons come to mind; the POLLED MODE is entirely adequate for directconnection between the Master LINX terminal and the Host computer, and the REQUESTRESPONSE protocol is considerably more complex to implement on the host computer.3

HOW TO SET REQUEST RESPONSE MODERequest Response Mode is invoked by entering the Network MENU of your Master LINXterminal by the method described in your LINX Reference Manual. We are integrated in theHost Mode entry.The valid HOST MODEs are “XON/XOFF”, “POLLED”, and “REQUEST”. Select REQUESTand then press ENTER.Note that once your Master LINX terminal is configured for Request Response Mode, it MUSTcommunicate with a program on your host which uses the REQUEST RESPONSE PROTOCOL.CONTROL CHARACTERSIn order to use Request Response Mode, your host computer must be able to send and receivecontrol characters. The control characters used by Request Response are as follows:Name Decimal Value Hex Value UsageENQ 5 05 Request for retransmissionACK 6 06 Response to a good recordFAIL 7 07 Response to a protocol violationCR 13 0D End of a data recordWACK 15 0F Wait acknowledge of good recordNAK 21 15 Response to a bad record or characterSYN 22 16 Synchronize protocol startupEXIT 26 1A Exit interactive menu modeHOST TRANSMITTED DATA RECORDSThe data records transmitted by the host computer are in the same format as described in theLINX Reference Manual, with ONE EXCEPTION: The last printable character of the datarecord is a CHECKSUM character. Host transmitted records are of the form: is “mm-nn:”, where nn is the terminal number of the LINX to receive the data, andmm is the number of the Master LINX or Submaster LINX to which the addressed LINXis attached. “:” is an ASCII colon (decimal value 58). may be any printable ASCII characters from space through “}”. The “~” (decimal 126)and delete (decimal 127) must NOT be used. NO CONTROL CHARACTERS SHOULDBE EMBEDDED IN THE DATA.4

. is a single character checksum for all of the characters in and .This checksum value is (the summation of all of the ASCII values of all characters in and MODULO 64) + 32. The following BASIC fragment computesthe checksum character and appends it to a record:‘ r$ contains and c = 0FOR i = 1 to LEN (r$)c = (c + ASC(MID$(r$, i, 1))) MOD 64NEXT ir$ = r$ + CHR$(c+32) is an ASCII carriage return (decimal 13). NO LINE FEED FOLLOWS THE CARRIAGERETURN.LINX TRANSMITTED DATA RECORDSThe data records transmitted by the master LINX are in the same format as described in the LINXReference Manual, with ONE EXCEPTION: the last printable character of the data record is aCHECKSUM character. LINX transmitted records are of the form: is “mmnnrrqqtt”, where mm is the number of the Master LINX or Submaster LINX towhich the LINX that sent the data; rr is the number of retries that were required totransmit the record (usually “00”); qq is a sequence number which is used internally bythe network; and tt is the transaction number of the sending transaction. may be any printable ASCII characters from space through “}”. The “~” (decimal 126)and delete (decimal 127) must NOT be used. NO CONTROL CHARACTERS SHOULDBE EMBEDDED IN THE DATA. is a single character checksum for all of the characters in and .This checksum value is calculated in the same manner as described in the previoussection. is an ASCII carriage return (decimal 13). A LINE FEED WILL FOLLOW THECARRIAGE RETURN ONLY IF CRLF is enabled in the Comm Port Menu of the MasterLINX.5

INITIATION OF COMMUNICATIONSThe HOST computer initiates communications with the LINX master when the HostCommunications Program is executed. The normal sequence of initiation is as follows:HOST ACTIONEXIT - - - >wait 1 secondEXIT - - - >wait 1 secondEXIT - - - >wait 1 secondpurge comm receive bufferSYN - - - >SYN - - - >SYN - - - >LINX ACTIONexits any current activityup to 3 EXITs are required< --- ACK< --- ACK< --- ACKSending the initial 3 EXITs and waiting is optional. This will assure that the LINX is not insome other mode which can prevent communications from starting properly. The LINX may beplaced in other modes either from other communications programs, or in rare cases by spuriouscharacters sent over the communications line.Only the first SYN is required. Others are optional.Your host program must be able to purge the comm receive buffer. This consists of reading allcharacters which are currently available and throwing them away.6

POLLING THE MASTER LINX FOR DATAMost of the time your host program will be polling the master LINX for incoming data. This isillustrated by the following dialogue between a LINX and the host.HOST ACTION LINX ACTION COMMENTENQ - - - >ENQ - - - >ENQ - - - >ACK - - - >ENQ - - - >NAK - - ->ENQ - - - >ACK - - - >ENQ - - - >ENQ - - - >Host asks for data< - - - ACK No data is available.< - - - ACK< - - - 0101000200ON! Master is online.Checksum is OK.< - - - 0101xt@^0ON! Error in dataChecksum is bad.< - - - 0101000300MO! Data is good now.Checksum is OK.< - - - ACK No data is available.. . . response is entirely lost . . .timeout after 1 secondENQ - - - >ENQ - - - >< - - - ACK Reply gets through.< - - - ACKIn the preceding sequence note that the HOST must be able to time out if no characters arereceived in 1 second. The timeout may be longer than one second if necessary.The HOST should always check the checksum on data blocks to determine whether the data hasbeen received correctly.7

SENDING DATA TO THE MASTER LINXHOST ACTION LINX ACTION COMMENTENQ - - - >Host asks for data< - - - ACK No data is available.01-01:T 1.\ - - - >Host sends a record.< --- ACK The LINX reads it.ENQ - - - >Always ask for data< - - - ACK between sending records.01-01:1:BEGIN WHEN RESTART.3 - - - >Host sends next record.< --- WACK The LINX is not ready yet.ENQ --- >See if LINX is ready yet.< - - - WACK LINX is still not ready.ENQ --- >See if LINX is ready yet.< - - - ACK The data has been buffered.01-01:1 D /EN#s@rbaDGE/.[ - - - > Host sends the next record.< - - - NAK The record was garbled.01-01:1 D /ENTER BADGE/.[ - - - > Host re-sends the record.< - - - ACK The LINX accepts it.ENQ - - - >Always ask for data< - - - ACK between sending records.01-01:2 SELECT.I - - - > Hosts sends the next record.< - - - 0102009106 Data record 1.K - Data replyACK - - - >The host must poll for dataENQ - - - >until it receives an ACK< - - - 0102000706 Data record 2.IACK - - - >The host continues to pollENQ - - - >for more data.< - - - 01020ssdfwmm%%^2 Data record 3.N - GarbledACK --- >Checksum was bad.ENQ --- >Ask again.< - - - 0102000706 Data record 3.NACK - - - >Record received OKENQ - - - >Finally the host sends an< - - - ACK ENQ and gets the ACK01-01:3 GOTO 1.T - - - > Hosts sends the next record.< - - - ACK Record is read OK.ENQ - - - >Always ask for data< - - - ACK between sending records.As you can see sending data to the LINX is somewhat more involved than polling for data. Thekey element is that the LINX must always be able to send data to the HOST.In addition the LINX may reply to a data record sent by the host with one of its own. When thisoccurs then HOST should read data until an ACK is received.8

NOTES FOR PROPER IMPLEMENTATIONNOTE that if the HOST receives characters which are not valid control characters then theyshould be discarded. The receipt of a data record is indicated by the CR (decimal 13) at the endof the record. If a control character is received during the receipt of a data record, BEFORE theCR, then the initial characters of the record should be discarded.Be sure that your program does not “get behind” in reading characters from the comm line. It ispossible to have extra characters buffered up and not be aware of it. This can result in some verystrange protocol problems. It is best to always read the full contents of the communication bufferinstead of just reading until you receive a character which your program can deal with. Onemethod for doing this is to read until you have not received characters for at least 3 charactertransmission times. Unfortunalty, with this can be quite difficult to do in most high levellanguages so you will often have to make do wit what you have.USE A LINE MONITOR TO SEE THE INTERACTION BETWEEN THE LINX AND THEHOST COMPUTER DURING DEVELOPMENT OF YOUR HOST PROGRAM. If you do nothave a line monitor rent one for use during your development process.9

APPENDIX A: HOST REQUEST RESPONSE STATE TABLEThis state table is used to fully describe the operation of the HOST COMPUTER. You may usethis as an aid in implementing your HOST Request Response Protocol.The HOST Request Response Protocol has 4 possible states. These are:STATE 0:STATE 1:STATE 2:STATE 3:The HOST is trying to establish communications with the MASTER LINXterminal.The HOST is polling for data from the MASTER LINX terminal.The HOST is ready to send a record to the MASTER LINX terminal.The HOST has sent a record to the MASTER LINX terminal and is waiting forresponse.STATE 0 - Initializing the LINX MASTERState entry preparation : syn=0EVENT ACTION COMMENTTIMEOUT < - - - SYN, syn ++ Waiting for connection.ACK - - - - > < - - - ENQ , STATE 1 Connected.other !abortSTATE 1 - Polling for data from LINX MASTERState entry preparation : wak=0, nak=0, tmt=0EVENT ACTION COMMENTTXREADY STATE 2 Data to send to LINX.TIMEOUT < - - - ENQ , tmt++ACK - - - > < - - - ENQ, tmt=0nak=0, wak=0DATA - - - > < - - - ACK&ENQ , store Get the normal data.other - - > < - - - NAK&ENQ, nak++10

STATE 2 - Ready to send a record to the LINX MASTEREVENT ACTION COMMENTTIMEOUT < - - - ENQ, tmt++ No reply to ENQ.ACK - - - - > < - - - DATA, STATE 3 Send the data record.DATA - - - > < - - - ACK&ENQ, store Get normal data.Other - - > < - - - NAK&ENQ, nak++STATE 3 – Waiting for response to a transmitted recordEVENT ACTION COMMENTTIMEOUT < - - - ENQ, nak++ No reply to data yet.ACK - - - - > < - - - DATA, fetch, STATE 1 LINX got the record.WACK - - - > < - - - ENQ, wak ++ Wait until ready.DATA - - > < - - - ACK&ENQ, store Conversational data.NAK - - - > < - - - DATA Resend the data.other - - - > < - - - NAK&ENQ, nak ++NotesTXREADY indicates that a record is available in the transmit queue. These are BARCONRECORDS, BASIC LXE records, or CONTROL records ( >xxx is receipt of a valid data record with a correct checksum.fetch indicates that the record in the transmit queue has been transmitted successfully and maynow be discarded.store indicates that the received record has been stored in the receive queue.tmt++ indicates incrementing of the timeout counter. If some arbitrary maximum number ofretries is exceeded (such as 10 or 15) then communications has failed.tmt=0, wak=0, etc indicates resetting of a counter.11

wak++ indicates incrementing of the wack counter. If the MASTER LINX terminal is never ableto send the record, then you must eventually abort the communications. This should occur afterabout 20 seconds or however many WACKs that it takes to get to about 20 seconds.nak++ indicates incrementing of the nak counter. If more than 10 or 15 naks are needed for arecord then you must abort the communications.Syn++ indicates incrementing of the sync counter. If the MASTER LINX terminal never repliesto the initial SYNs then you should abort the communications. You may make this long enoughNote that receiving a FAIL (ASCII BEL, decimal 7) should cause a total failure of the protocol.If your communications line is especially noisy then you may want to count FAILs andunexpected control characters and only abort after receiving 2 or 3 of them. The request responseprotocol is not bombproof if the communications line has a very high character substitution rate.Any EVENT which is not listed in the EVENTs column for a state should not be tested until astate is entered which uses that event.State entry preparations should be executed only when a STATE n action occurs.If you receive “*” then , you should abort communications with the message “MASTERLINX IS NOT IN REQUEST MODE!”12

APPENDIX B: MASTER LINX terminal REQUEST REPSONSE STATE TABLEThis state table is used to fully describe the operation of the LINX MASTER. You may use thisas an aid in debugging your HOST Request Response protocol.The MASTER LINX terminal has 6 possible states. These are:STATE 0:STATE 1:STATE 2:STATE 3:STATE 4:STATE 5:The MASTER LINX terminal is waiting for data to arrive from the HOSTCOMPUTER, or from a program running on the MASTER LINX terminal, orfrom some other terminal on the LINX NETWORK.The MASTER LINX terminal is waiting to come ON LINE. It has not beencommunicated with by the HOST COMPUTER since it was last reset.The MASTER LINX terminal has received a data record from either its ownprogram or from the network. It is waiting for the HOST COMPUTER to poll itso that the data can be sent to the HOST COMPUTER.The MASTER LINX terminal has received a date record from the HOSTCOMPUTER but is unable to store it due to a buffer full condition. It is sendingWACKs to the HOST COMPUTER until the data record can be buffered.The MASTER LINX terminal has received a data record from the HOSTCOMPUTER but is unable to store it due to a buffer full condition AND has alsoreceived a data record from its own program or from the network. It is sendingWACKs to the HOST COMPUTER until the host data record can be stored.When that occurs, the LINX data record will be sent to the HOST COMPUTER.The MASTER LINX terminal has sent a record to the HOST COMPUTER andneeds the HOST COMPUTER to acknowledge receipt of that record. It is waitinguntil the HOST COMPUTER either sends an ACK or implicitly acknowledges therecord by sending a data record to the MASTER LINX terminal.State 0 – Waiting for data from network or hostEVENT ACTION COMMENTNETDATA STATE 2 Data to send to HOSTSYN - - - > < - - - ACK, last=ACKNAK - - - > ignoreENQ - - - > < - - - lastACK - - - > last=ACKHOSTDATA - - - > < - - - ACK, last=ACK If buffer emptyHOSTDATA - - - > < - - - WACK, STATE 3 If buffer fullOther - - - > < - - - NAK, last=NAK13

State 1 - Waiting to come ONLINESYN - - - > < - - - ACKACK - - - > < - - - ONLINE, last=ONLINE, STATE 5NAK - - - > < - - - ONLINE, last=ONLINE, STATE 5ENQ - - - > < - - - ONLINE, last=ONLINE, STATE 5other - - - > < - - - FAIL Protocol violation!State 2 – Have data to send to hostState entry preparation : last=NETDATASYN - - - > < - - - ACKACK - - - > ignoreNAK - - - > ignoreENQ - - - > < - - - last (NETDATA), STATE 5HOSTDATA - - - > < - - - last (NETDATA), STATE 5 If buffer emptyHOSTDATA - - - > < - - - WACK, STATE 4 If buffer fullOther - - - > < - - - NAKSTATE 3 – WACKing the host with NO DATA to sendNETDATA STATE 4 Data to send to HOSTENQ - - - > < - - - ACK, last=ACK, STATE 0 If buffer emptyENQ - - - > < - - - WACK If buffer fullSYN - - - > < - - - ACK, STATE 0 ***Old host data lost!***Other - - - > < - - - NAK Data is not allowedState 4 – WACKing the host with data to send to hostState entry preparation : last=NETDATAENQ - - - > < - - - last (NETDATA), STATE 5 If buffer emptyENQ - - - > < - - - WACK If buffer fullSYN - - - > < - - - ACK, STATE 2 ***Old host data lost!***Other - - - > < - - - NAK Data is not allowedState 5 – Waiting for ACK to data sent to the hostSYN - - - > < - - - ACK, last=ACK, STATE 0ACK - - - > last=ACK, STATE 0NAK - - - > ignoreENQ - - - > < - - - lastHOSTDATA - - - > < - - - ACK, last=ACK, STATE 0 If buffer emptyHOSTDATA - - - > < - - - WACK, STATE 3 If buffer fullOther - - - > < - - - NAK, last=NAK14

Last=xxx indicates that when an “< - - - last” action is performed, then the record sent will be“xxx”.NETDATA event indicates that a record has been received by the MASTER LINX terminaleither from its own program or from another LINX on the network.STATE x action indicates that the state has been changed to the one specified. The state remainsunchanged otherwise.15

APPENDIX C : IMPLEMENTING A PROTOCOL USING STATE TABLESA state table is a description of a protocol in a form which can be unambiguously converted intoa program. The normal technique is to implement a CASE (Pascal), SWITCH (C) or SELECT(QuickBasic) statement for each state. A program implementing a state table is referred to as astate machine.Each ACTION performed by the state machine must execute immediately without any pauses.Any operation which may require pausing the program should be implemented as an EVENT.An EVENT is something that occurs which will require an action by the state machine. Typicalevents are:INPUT OF A CONTROL CHARACTER FROM THE LINXINPUT OF A DATA BLOCK FROM THE LINXEXPIRATION OF A TIMERA typical method of implementing a state machine is to make the entire protocol be a singleprocedure which is called by the "READ A KEYSTROKE” routine of the Host CommunicationProgram (note that by single procedure, I mean one main procedure and its many supportprocedures). The state machine then continues to execute until a key is pressed on the host’skeyboard (operating console). The disadvantage of this technique is that built in high levellanguage read routines (such as scanf, input, readln, etc.) must be replaced with calls to your ownimplementations of each routines.An alternative technique is to implement the state machine as an independent task.Unfortunately this only works on a multi-tasking operating system.Regardless of the implantation of the state machine, the major elements of your host programshould communicate with the state machine using two queues. These should be variable lengthFIFOs, one for transmit and one for receive. The receive queue should be of effectively infinitelength if you want to be able to transmit an indefinite number of records without having yourmain program examining the receive queue.Below is a template in Pascal to give you an idea of the structure of the state machine:VAR RRState : INTEGER; {Current state of the protocol}PROCEDURE RequestRepsonseStateMachine;VAR event : INTEGER;BEGINevent: = TestEvent; {Call a procedure which checks state}CASE RRstate OF0 : CASE event OFRxACK : … actions for ACK in state 0 …;RxNAK : … actions for NAK in state 0 …;16

RxWACK : …Timeout : …TxReady : …… actions for other events …ELSE : … actions for unexpected events …END {Evaluation of state 0}1: CASE event OFRxACK : … actions for ACK in state 1 …;RxNAK : … actions for NAK in state 1 …;RxWack……ELSE : … other actions …END {Evaluation of state 1}… more states …n: CASE event OFRxACK : … actions for ACK in state n …;RxNAK : … actions for NAK in state n …;…ELSE : … other actions …END {Evaluation of state n}END; {CASE}17