DP Tool Club 8

home *** CD-ROM | disk | FTP | other *** search

/ DP Tool Club 8 / CDASC08.ISO / VRAC / PPL4C11.ZIP / PPL4C.USR < prev next >

Wrap

Text File | 1993-01-10 | 50.2 KB | 1,322 lines

Personal Protocol Library For the C Language (PPL4C) USERS MANUAL Version 1.1 Jan 4, 1993 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1993 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Phone (205) 881-4630 PPL4C Users Manual Page 1 C O N T E N T S Chapter Page 1.0 Introduction..............................................3 1.1 Compiling the Library.................................3 1.2 User Support..........................................4 1.3 Installation..........................................5 2.0 State Drivers.............................................6 3.0 File Transfer Protocols...................................7 3.1 XMODEM................................................7 3.2 XMODEM-CRC............................................9 3.3 XMODEM-1K.............................................9 3.4 XMODEM-G.............................................10 3.5 YMODEM...............................................10 3.6 YMODEM-G.............................................10 4.0 Protocol Library Functions...............................11 4.1 xyAbort..............................................11 4.2 xyDriver.............................................11 4.3 xyGetErrorCode.......................................12 4.4 xyGetErrorState......................................12 4.5 xyGetFilename........................................12 4.6 xyGetNAKs............................................12 4.7 xyGetPacket..........................................12 4.8 xyGetState...........................................12 4.9 xyInit...............................................13 4.10 xyStartRx...........................................13 4.11 xyStartTx...........................................13 5.0 The FILEXFER.C Demonstration Program.....................14 5.1 Introduction.........................................14 5.2 The FILEXFER.H Parameter File........................15 5.3 Running FILEXFER.....................................16 6.0 Using The Protocol Library...............................17 6.1 Keyboard Input.......................................17 6.2 Disk I/O.............................................18 6.3 Serial I/O...........................................18 6.4 Other Events.........................................18 7.0 Problems.................................................19 8.0 Legal Issues.............................................20 8.1 Registration.........................................21 8.2 License..............................................21 8.3 Warranty.............................................21 9.0 Revision History.........................................21 10.0 Other MarshallSoft Computing Products....................22 10.1 The Personal Communications Library for C...........22 10.2 The LZW Data Compression Library for C..............22 PPL4C Users Manual Page 2 1.0 Introduction The Personal Protocol Library (PPL) consist of a state driven library which implements the XMODEM, XMODEM-CRC, XMODEM-1K, XMODEM-G, YMODEM, and YMODEM-G file transfer protocols. This allows the programmer to run multiple protocol transfers simultaneously while interacting with the user at the keyboard. The PPL requires the Personal Protocol Library (PCL), also available from MarshallSoft Computing. The user should be familiar with PCL before attempting to understand the protocol driver. Refer to section "Other MarshallSoft Computing Products". What are the advantages of a state driven protocol library ? The answer is any type of communications program which requires "background" protocol file transfers. A few examples are: (1) EXAMPLE-1: A program that can read incoming stock market data continuously while the main application is doing technical analysis. (2) EXAMPLE-2: A custom BBS program that can handle two file transfers simultaneously. See the section 8.1 "Registration" for an offer who might not want to refuse! 1.1 Compiling the Library There are three small model library files provided: ppl4c_sb.lib -- Borland Turbo C library. ppl4c_sm.lib -- Microsoft C library. ppl4c_sx.mix -- MIX Power C library. The registered user can recompile the source code (source code is provided in the registered version only) for the library using one of the three provided batch files: make_sb.bat -- make small Borland Turbo C library (ppl4c_sb.lib). make_sm.bat -- make small Micrsoft C library (ppl4c_sm.lib). make_sx.bat -- make small MIX Power C library (ppl4c_sx.mix). PPL4C Users Manual Page 3 1.2 User Support We want you to be successful in developing your applications using PPL4C! We depend on our customers to let us know what they need in a protocol library. This means we are committed to providing the best communications library that we can. If you have any suggestions or comments, please write to us or give us a call. If you are having a problem using PPL4C, call (205) 881-4630 between 5 PM and 9 PM CST Monday through Saturday. You can call at other times and leave a message, and call back later during our regular business hours for a reply. You can also FAX us at this same number at any time. You may also call our 24 hour BBS (2400 baud, no parity, 8 data bits, 1 stop bit) at any time. The BBS will contain the latest shareware version of PPL4C, messages, and other related files. All files are in standard ZIP format. You can leave a message on the BBS, and we will usually have a reply ready for you within 24 hours. The dedicated telephone number is 205-880-9748. Set your modem for 2400 baud, 8 data bits, no parity, one stop bit. The MarshallSoft Computing, Inc. newsletter "Comm Talk" is published quarterly. It discusses various communications problems and solutions using PCL4C (the communications library) and PPL4C (the protocol library) as well as related information. Registered users receive a one year complimentary subscription when first registering and for each update purchased. Of course, you can always write to us. You should receive a reply within one to two weeks. PPL4C Users Manual Page 4 1.3 Installation (1) Before installation of PPL4C, your C compiler should already be installed on your system and tested. If you are not familiar with makefiles, refer to your compiler manual. If you are using the interactive environment for Quick C or Turbo C, be sure to compile with the memory model corresponding to the PPL4C library used. Examine the file "FILES.LST" for a list of all the distribution files. (2) Make a backup copy of your distribution disk. Put your original distribution disk in a safe place. (3) Create a work directory on your work disk (normally your harddisk). For example, to create a work directory named PPL4C, we first log onto the work disk and then type: MKDIR PPL4C (4) Copy all the files from your backup copy of the distribution disk to your work directory. For example, to copy from the A: drive to your work directory, we type: CD PPL4C COPY A:*.* (5) [OPTIONAL] Delete the makefiles that you won't need. For example, if you use the Microsoft C compiler, then you want to keep all makefiles ending *._M_ but can delete those for Turbo C (*._T_), Quick C (*._Q_), and MIX Power C (X_*.BAT). You may also delete any libraries that you won't need. (6) Compile FILEXFER.C and link with the appropriate PPL4C library (PPL4C_SM.LIB for Microsoft C, PPL4C_SB.LIB for Borland Turbo C, and PPL4C_SX.MIX for MIX Power C). MAKEFILES (or project files) are provided for each of the supported compilers. a) Microsoft C: Type MAKE FILEXFER._M_ b) Microsoft Quick C: Type MAKE FILEXFER._Q_ c) Borland Turbo C: Type MAKE -FFILEXFER._T_ d) MIX Power C: Type X_FILEXFER FILEXFER.C should compile without any problems as all example code has been tested with each of the supported compilers. (7) The recommended way to test FILEXFER is to run it on two computers connected by a null modem cable. See section "Problems" for a recommended approach to testing FILEXFER. PPL4C Users Manual Page 5 2.0 State Drivers A state driver is a programming technique in which a typically complex task in broken down into small steps known as states. Each state can be executed relatively quickly, and in particular never does any waiting. The main application program calls the state driver whenever it is waiting for a user keypress, or at any other arbitrary time. The effect is that the state driven code executes whenever the main application code is not working. The Microsoft Windows operating system uses a variation on the state driven technique. Think of each running program as a state. The operating system calls each state in turn (unlike the protocol driver, the states are independent). Each state (or program) must yield the processor (by getting the next input event) or by explicitly calling a yield function. The operating system cannot force any running program to yield the processor. Coding a file transfer protocol as a state driver allows simultaneous file transfers to occur. Although the driver is written for a maximum of two ports since the their are at most 2 serial interrupts available on standard PCs, there is no reason that the driver could not handle more than two simultaneous transfers. The central difficulty is using a state driver for XMODEM and YMODEM is that those protocols time out if they have to wait too long for a response. The solution is to call the driver at approriate times. In other words, the state driver must be called often enough to prevent a protocol timeout. The XMODEM and YMODEM protocol timeout values in the state driver are longer than a strict implementation of the protocol standards. This eases the timing requirements somewhat. However, if the other side of the transfer is running a strict implementation of XMODEM or YMODEM then we can still have protocol timeout problems. The following section "File Transfer Protocols" provides a general understanding of XMODEM and YMODEM. In particular, pay attention to the timeout requirements. PPL4C Users Manual Page 6 3.0 File Transfer Protocols 3.1 XMODEM XMODEM refers to the file transfer protocol introduced by Ward Christensen in 1977. XMODEM is widely supported on most all bulletin board systems. The following ASCII character definitions are used in XMODEM. <SOH> = 01H Is always the first byte in each block. <EOT> = 04H Sent instead of SOH to mark the end of transmission. <ACK> = 06H Positive acknowledgment. <NAK> = 15H Negative acknowledgment. <CAN> = 18H Cancel transfer. XMODEM is a receiver driven, asynchronous, 8 data bit protocol. Each packet looks like the following: <SOH> <packet #> <compliment #> <data> <checksum> where <SOH> = 01H. <packet #> = Packet number, starting at 01, incrementing by 1, and wraps from 0FFH to 00H (not to 01H). <compliment #> = 255 minus the packet number. <data> = 128 bytes of binary data. <checksum> = The sum of the data bytes. Starting with a zero add each data byte to the checksum. Use only the rightmost 8 bits. When the receiver is ready, it sends a NAK every 10 seconds ( up to one minute ) until the NAK is ackowledged by the transmitter by sending the first packet. The transmitter continues by sending each packet in turn, always waiting for the packet to be ackowleged before sending the next. Finally, when the transmitter has no more data, it sends an EOT instead of a SOH to complete the transfer. Each packet is sent by the transmitter as follows: (1) Each packet always starts with a SOH. (2) The packet number is sent next, starting with 01H, and incrementing by 1. The packet number wraps from 0FFH to 00H. (3) The packet number compliment is sent next. It is always calculated a 255 minus the packet number. (4) Exactly 128 bytes of data is sent. If the transmitter doesn't have 128 bytes of data to send, then control-Z's (1AH) are padded to the data block. PPL4C Users Manual Page 7 (5) The checksum is calculated by added together all 128 data bytes and sending the least significant 8 bits. (6) The transmitter waits ( up to 10 seconds ) for a response. If the response is an ACK, then the transmitter goes on to the next packet. If the response is a NAK, then the transmitter re-sends the entire packet. If the response is a CAN, then all further transmission is cancelled. Each packet is handled by the receiver as follows: (1) If the first character is an EOT then the transfer is now complete, and the receiver should ACK the EOT before exiting. If the first character is a CAN, then all further action is cancelled. If the first character is a SOH, then this is the first character of the next packet. (2) If the packet number is not correct ( the first packet is 1 ), then this is a fatal error, and the receiver should send a CAN to the transmitter in order to cancel further transmission. (3) If the packet number compliment is not correct, this is also a fatal error and the receiver sends a CAN to the transmitter. (4) Exactly 128 bytes of data are received. (5) The checksum is received. It is compared with the value obtained by computing the checksum from the just received data. If the checksum values are the same, an ACK to sent to the transmitter. Otherwise, a NAK is sent. Here is a XMODEM example of the data flow. It includes the two most common line hits: a garbaged block, and an <ACK> reply getting garbaged. <data> represent 128 bytes of data. <CS> represents the checksum byte. SENDER RECEIVER ====== ======== <--- <NAK> <SOH> 01 FE <data> <CS> ---> <--- <ACK> <SOH> 02 FD <data> <CS> ---> (data gets line hit) <--- <NAK> <SOH> 02 FD <data> <CS> ---> <--- <ACK> <SOH> 03 FC <data> <CS> ---> (ACK gets garbaged) <--- <ACK> <SOH> 03 FC <data> <CS> ---> <ACK> <EOT> ---> <--- <anything except ACK> <EOT> ---> <--- <ACK> PPL4C Users Manual Page 8 3.2 XMODEM-CRC The XMODEM-CRC protocol is similar to the XMODEM protocol, except that the receiver specifies CRC-16 by sending C (Hex 43) instead of NAK when requesting the FIRST block. A two byte CRC is sent in place of the one byte arithmetic checksum. 3.3 XMODEM-1K The XMODEM-1K protocol is identical to XMODEM-CRC, except that 1024 byte data blocks in addition to 128 byte data blocks can be sent. An STX (02H) replaces the SOH (01H) at the beginning of the transmitted block to notify the receiver of the longer block length. The transmitted block contains 1024 bytes of data. The receiver should be able to accept any mixture of 128 and 1024 byte blocks. The block number (in the second and third bytes of the block) is incremented by one for each block regardless of the block length. The sender must not change between 128 and 1024 byte block lengths if it has not received a valid ACK for the current block. Here is an example of XMODEM-1K with 1024 blocks: SENDER RECEIVER ====== ======== C STX 01 FE Data[1024] CRC CRC ACK STX 02 FD Data[1024] CRC CRC ACK STX 03 FC Data[1000] ^Z[24] CRC CRC ACK EOT ACK Mixed 1024 and 128 byte Blocks SENDER RECEIVER ====== ======== C STX 01 FE Data[1024] CRC CRC ACK STX 02 FD Data[1024] CRC CRC ACK SOH 03 FC Data[128] CRC CRC ACK SOH 04 FB Data[100] ^Z[28] CRC CRC ACK EOT ACK PPL4C Users Manual Page 9 3.4 XMODEM-G The XMODEM-G protocol works like XMODEM-1K except that the sender never waits for a packet ACK. This results in a faster transfer than would otherwise occur. However, hardware flow control (RTS - CTS) must be turned on. Be carefull if you are using a null modem cable for PC to PC transfer since many null modem cables do not exchange RTS and CTS as required. Refer to the Personal Communication Library Users Manual for a discussion of flow control. 3.5 YMODEM The YMODEM Batch protocol is an extension to the XMODEM-1K protocol that allows 0 or more files to be transmitted in a single session. YMODEM always sends an information packet (number 0) with each file containing the filename and the file length. The filename is sent as a null terminated ASCII string. This is the filename format used by the handle MSDOS oriented functions. The length field is sent as a decimal ASCII string counting the number of data bytes in the file. The file length does not include any ^Z or other characters used to pad the last block. All unused bytes in packet 0 must be set to 0. After the file has been transmitted, the receiver asks for the next file by sending a 'C'. Transmission of a null pathname terminates the YMODEM protocol. An EOT is not transmitted after a null pathname. Here is an example of YMODEM: SENDER RECEIVER ====== ======== C C SOH 00 FF Filename NULs CRC CRC ACK C STX 01 FE Data[1024] CRC CRC ACK STX 02 FD Data[1024] CRC CRC ACK SOH 03 FC Data[128] CRC CRC ACK SOH 04 FB Data[100] ^Z[28] CRC CRC ACK EOT ACK C SOH 00 FF NUL[128] CRC CRC ACK 3.6 YMODEM-G YMODEM-G is similiar to XMODEM-G in that the sender never waits for a packet ACK. Refer to the section "XMODEM-G". PPL4C Users Manual Page 10 4.0 Protocol Library Functions There are 11 protocol library functions. Their prototypes are in file xyDriver.h and are as follows: int xyAbort(int); int xyDriver(int); int xyGetErrorCode(int); int xyGetErrorState(int); char *xyGetFilename(int); int xyGetNAKs(int); int xyGetPacket(int); int xyGetState(int); int xyInit(int,int); int xyStartTx(int,char *,int,int); int xyStartRX(int,char *,char,int); All state driver functions return a negative value for a communications error. See the PCL4C manuals for a list of these errors. The function xyInit should be called after initializing the selected port with SioReset. Then, either xyStartTx or xyStartRx should be called to initiate file transfer. The file transfer is done when xyDriver return a 0 (NO_ERROR). Examine the library test program FILXFER.C for an example of the proper use of the state driver functions. 4.1 xyAbort int xyAbort(C) int C; /* channel (0 to 3) */ The xyAbort functions aborts any file transfer occuring on channel C and return the channel to the idle state. The protocol driver will send a cancel command to the other end. 4.2 xyDriver int xyDriver(C) int C; /* channel (0 to 3) */ The xyDriver function should be called as often as possible. Typically there are two places that it is called. The first is whenever the main application is waiting for a keypress. This should be implemented by forcing all keyboard input to go through a user written keyboard input routine. Refer to the section "Using the Protocol Library" for an example. xyDriver should also be called periodically during any long operation such as disk I/O. PPL4C Users Manual Page 11 4.3 xyGetErrorCode int xyGetErrorCode(C) int C; /* channel (0 to 3) */ The xyGetErrorCode function is called once xyDriver returns a positive value indicating that it is complete. The user should then call xyGetErrorCode to determine if there was an error in the transfer and if so, what the error was. 4.4 xyGetErrorState int xyGetErrorState(C) int C; /* channel (0 to 3) */ The xyGetErrorState function is called to determine the state that the protocol driver was in when the error occured. Don't call xyGetErrorState unless an error has occured as determined by calling xyGetErrorCode. 4.5 xyGetFilename char *xyGetFilename(C) int C; /* channel (0 to 3) */ The xyGetFilename function returns the name of the file that the protocol driver is transfering. This is particularly useful when multiple files are being transfered by YMODEM. 4.6 xyGetNAKs int xyGetNAKs(C) int C; /* channel (0 to 3) */ The xyGetNAKs function is used to return the accumulative number of NAKed packets. 4.7 xyGetPacket int xyGetPacket(C) int C; /* channel (0 to 3) */ The xyGetPacket function returns the current packet number while a protocol transfer is underway. Otherwise it return a -1. 4.8 xyGetState int xyState(C) int C; /* channel (0 to 3) */ The xyState function returns the current state of the protocol driver. Refer to xyDriver.h for a list of all driver states and their values. PPL4C Users Manual Page 12 4.9 xyInit int xyInit(C,Port) int C; /* channel (0 to 3) */ int Port; /* Port (COM1 to COM4) */ The xyInit function should be called after initializing the selected serial port. The first port should be assigned to channel 0 and the second, if defined, should be assigned to channel 1. The channel number is used to identify the port in all subsequent calls to state driver functions. Recall that ports COM1 and COM3 can not be used simultaneously, and that ports COM2 and COM4 cannot be used simultaneously -- unless PCL4C has been configured for 4 simultaneous ports. Refer to the PCL4C Users's Manual for more information. 4.10 xyStartRx int xyStartRx(C,Filename,NCGchar,BatchFlag) int C; /* channel (0 to 3) */ char *Filename; /* filename */ char NCGchar; /* startup character */ int BatchFlag; /* TRUE for YMODEM */ The xyStartRx function is called to start XMODEM / YMODEM as the receiver. The correct flag values are as follows: Protocol NCGchar BatchFlag XMODEM NAK FALSE XMODEM-CRC 'C' FALSE XMODEM-1K 'C' FALSE XMODEM-G 'G' FALSE YMODEM 'C' TRUE YMODEM-G 'G' TRUE 4.11 xyStartTx int xyStartTx(C,Filename,OneKflag,BatchFlag) int C; /* channel (0 to 3) */ char *Filename; /* filename */ int OneKflag; /* TRUE for XMODEM-1K and YMODEM */ int BatchFlag; /* TRUE for YMODEM */ The xyStartTx function is called to start XMODEM / YMODEM as the sender. The correct flag values are as follows: Protocol OneKflag BatchFlag XMODEM FALSE FALSE XMODEM-CRC FALSE FALSE XMODEM-1K TRUE FALSE XMODEM-G FALSE FALSE YMODEM TRUE TRUE YMODEM-G TRUE TRUE PPL4C Users Manual Page 13 5.0 The FILEXFER Demonstration Program 5.1 Introduction The FILEXFER demonstration program is capable of doing two simultaneous protocol file transfers while interacting with the user at the keyboard. This is accomplished by coding the protocol transfer code as a state driver (refer to the previous section on State Drivers). The best way to run FILEXFER is to connect two PCs running a communications program (such as the TERM program on the PCL4C distribution diskette) to a third PC running FILEXFER, connected by null modem cables. If you only have two PCs, you can still run the FILEXFER program with just one channel. The FILEXFER demonstration program requires the Personal Communications Library (PCL4C) to run. If you don't already have a copy, you can find it on most of the larger information services and bulletin boards such as CompuServe, GENIE, and Exec-PC. You also can usually find it in the larger shareware disk distributor libraries. Lastly, you can always download it from our 24 hour BBS (205-880-9748 at 2400 baud, 8 data bits, no parity, 1 stop bit). Before attempting to run FILEXFER, try transfering files using the TERM program on the PCL4C distribution disk. Start by transfering files via XMODEM between two machines connected by a null modem cable at 9600 baud. Once you have TERM working on both sides, replace TERM by FILEXFER on one side. FILEXFER has been found to run at speeds up to 38400 baud using one channel and up to 19200 baud using two channels simultaneously on a 386 machine. If PCL4C has been configured for 4 ports, you should be able to run 4 concurrent file transfers at 9600 baud. You may run faster (or slower) depending on your hardware. If you will be running 4 ports concurrently, installing INS16550 UARTS will allow you to run at the fastest possible baud rate. Refer to the PCL4C User's Manual for a discussion of 16550 UARTS. PPL4C Users Manual Page 14 5.2 The FILEXFER.H Parameter File The FILEXFER.H include file contains all the user changeable parameters for the FILEXFER.C demonstration program. Be sure to read the comments in the FILEXFER.H file. 5.2.1 The AT_COMMAND_SET parameter The AT_COMMAND_SET parameter is used to specify that a Hayes AT command set compatible modem will be connected to each port being used (one or two as specified by NBR_OF_CHANNELS). 5.2.2 The RTS_CTS_CONTROL Parameter The RTS_CTS_CONTROL parameter is used to specify if hardware flow control is being used on all channels as specified by NBR_OF_CHANNELS. If you define this parameter to be TRUE and you are using a Null modem cable to connect two PC's together, be sure that RTS and CTS are swapped just like TX and RX are swapped. In many Null Modem cables, this is not the case. 5.2.3 The NBR_OF_CHANNELS Parameter The NBR_OF_CHANNELS parameter specifies the number of concurrent ports that can be run. NBR_OF_CHANNELS should be set to the number of ports that can be run concurrently. Refer to the PCL4C manual for port configurations. 5.2.4 The FIRST_PORT Parameter The FIRST_PORT parameter specifies the first port, which can be COM1, COM2, COM3, or COM4. The 'first' port is associated with channel 0 and is typically assigned to COM1. 5.2.5 The SECOND_PORT Parameter The SECOND_PORT parameter specifies the second port. This parameter is used provided that NBR_OF_CHANNELS is defined to be 2 or above. The secondary port is associated with channel 1 and is typically assigned to COM2. 5.2.6 The THIRD_PORT Parameter The THIRD_PORT parameter specifies the third port. This parameter is used provided that NBR_OF_CHANNELS is defined to be 3 or above. The third port is associated with channel 2 and is typically assigned to COM3 (3 or 4 concurrent port PCL4C configuration). 5.2.7 The FOURTH_PORT Parameter The FOURTH_PORT parameter specifies the fourth port. This parameter is used provided that NBR_OF_CHANNELS is defined to be 4. The fourth port is associated with channel 3 and is typically assigned to COM4 (3 or 4 concurrent port PCL4C configuration). PPL4C Users Manual Page 15 5.2.8 The FIRST_BAUD Parameter The FIRST_BAUD parameter specifies the baud rate associated with the first port (channel 0). Limit the baud rate to 19200 if you are running two or more ports simultaneously. 5.2.9 The SECOND_BAUD Parameter The SECOND_BAUD parameter specifies the baud rate associated with the second port (channel 1). 5.2.10 The THIRD_BAUD Parameter The THIRD_BAUD parameter specifies the baud rate associated with the third port (channel 2). 5.2.11 The FOURTH_BAUD Parameter The FOURTH_BAUD parameter specifies the baud rate associated with the fourth port (channel 3). 5.3 Running FILEXFER To run the FILEXFER program, follow these steps: (1) Edit the FILEXFER.H parameters file. Be conservative the first time you run FILEXFER. Use one channel and a baud rate of 9600. After you have run FILEXFER successfully with one port, then you can try two ( or more ) ports. (2) Compile FILEXFER and link with the PPL and PCL libraries. Use the provided makefile: FILEXFER._T_ for the Borland Turbo C compiler. FILEXFER._M_ for the Microsoft Optimizing compiler. FILEXFER._Q_ for the Microsoft Quick C compiler. X_FILEXF.BAT for the MIX Power C compiler. (3) Run FILEFER on one PC connected to one or two other PCs running a communications program such as TERM. (4) Start XMODEM receive in FILEXFER, then start XMODEM send on the connected PCs. As the file protocol progresses, you can monitor it's state by selected the "C)omm Status" choice from the FILEXFER menu. The one line FILEXFER menu is: Q)uit P)rotocol S)end R)eceive A)bort C)omm Status The menu line allows the user to: (1) Quit FILEXFER. (2) Set the protocol (XMODEM,XMODEM-CRC,XMODEM-1K,YMODEM,YMODEM-G) (3) Send a file (wildcards accepted). Channel must be idle. (4) Receive a file. (5) Abort a file transfer. Returns channel to idle state. (6) Get driver status. Reports current state and packet. PPL4C Users Manual Page 16 6.0 Using The Protocol Library Before attempting to use the protocol library, be sure to run the demonstration program FILEXFER. Only when you are satisfied that FILEXFER runs correctly should you attempt to use the protocol library in your own application. There are only a few hard rules to follow in order to use the protocol library successfully. The first is that you absolutely must call xyDriver often. There is no way that the state driver library can operate without timing out if you don't. 6.1 Keyboard Input You must always call xyDriver when waiting for a keypress. This means that all keyboard input should be called through a central keyboard input routine. For example, if you are running two channels: int ReadKey() {while(!SioKeyPress()) {xyDriver(0); xyDriver(1); } return( SioKeyPress() ); } /* end ReadKey */ #define CR 0x0d int ReadString(String) char String[]; {char x; int i; for(i=0;;i++) {x = ReadKey(); if(x==CR) {String[i] = '\0'; return(i); } else String[i++] = x; } /* end for */ } /* end ReadString */ int ReadInteger() {char Buffer[40]; int Length; Length = ReadString(Buffer); return(atoi(Buffer)); } /* end ReadInteger */ float ReadFloat() {char Buffer[40]; int Length; Length = ReadString(Buffer); return(atof(Buffer)); } /* end ReadInteger */ PPL4C Users Manual Page 17 6.2 Disk I/O In general, reading from a harddisk is not a problem if you call xyDriver after after 1000 bytes or so. Don't attempt to read or write too large a block of data. Don't do disk I/O to a floppy while the protocol driver is running (not in the idle state). However, it is OK to let the protocol driver read and write to a floppy disk provided that the other channel is not also doing floppy disk I/O. 6.3 Serial I/O You can do serial I/O while the protocol driver is running provided that you are using a port (and interrupt) different from the one that the protocol driver is using. However, you must not wait for any input. This means that you should not attempt to read more characters from the input buffer than is returned by SioRxQue. And, remember to call the protocol driver often. Don't read or write more than 1000 bytes without calling xyDriver. 6.4 Other Events In general, you can process any event provided that you don't take too long ! Remember that when the protocol driver is transfering files, it is expecting certain handshaking operations to be performed in a certain maximum amout of time. If that time is exceeded, then a protocol timeout error occurs. Even though we have relaxed the timeing restrictions within the protocol driver, the other end of the serial line (another XMODEM or YMODEM program) expects not to have to wait too long before cancelling a transfer session. Just remember to call xyDriver often. If you are experiencing timeout errors, insert more calls to xyDriver. A faster machine and 16550 UARTS also improve performance! PPL4C Users Manual Page 18 7.0 Problems If you can't get FILEXFER to run, try the following procedure: (1) Connect two PCs together using a null modem cable. Run the TERM program (from the PCL distribution diskette) on both machines at 2400 baud. If you can't get TERM to run, refer to your PCL (Personal Communications Library) manuals for help. (2) Once TERM is running correcly, try transferring files using XMODEM. Start the receiver side first. (3) Replace TERM on one machine with FILEXFER. Be sure to set the baud rate and port in the FILEXFER.H file and re-compile as necessary. (4) Try a XMODEM transfer first. If this works, then try a YMODEM transfer. Once the above is working, you might try adding a third machine and have FILEXFER do two file transfers simulaneously. If you can get FILEXFER to work correctly at 2400 baud but not at a higher baud rate, you might consider using 16550 UARTs. They can be programmed (using SioFIFO) to buffer up to 14 characters before generating an interrupt. We can help you get FILEXFER running, but we cannot help you debug your application. The central difficulty is in calling xyDriver in time to prevent a protocol timeout. This can be a tough problem. Study FILEXFER to see how it can be done. PPL4C Users Manual Page 19 8.0 Legal Issues 8.1 Registration The shareware version of PPL4C.LIB is provided so that you may personally determine the usefulness of the product for yourself. If you can use the Personal Protocol Library for C, please register your use with us. Send $35 plus $3 S&H ($6 outside of North America) to: MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 The user may also order both the Personal Communications Library (PCL4C) and the Personal Protocol Library (PPL4C) at the same time for $75. Registered users of PCL4C can order the protocol library PPL4P for $25 and also receive the latest version of PCL4C for no extra charge. We accept American Express (account number, expiration date, exact name on your card, and AmEx billing address required), checks in US dollars drawn on a US bank, purchase orders (POs) from recognized US schools and companies listed in Dun & Bradstreet, and COD (street address and phone number required) within the USA (plus a $3 COD charge). Print the file PCL4C.INV if an invoice is needed. The registered package is mailed first class US Mail (packet air mail overseas). The registered package includes: o No shareware screen. o C source code for the library. o Printed Users Manual. o Telephone / FAX / BBS support for one year. o One year subscription (quarterly) to MSC newsletter. o All updates (with printed manuals) are $15 plus $3 S&H ($6 outside of North America). Updates for PCL4C and PPL4C together are $25. PPL4C.C is the source code for the library. The source code is copyrighted by MarshallSoft Computing, Inc. The user is granted a license to use the PPL4C object code in his own application only. PPL4C.C is not shareware and may not be sold or given away to anyone. The registered user will receive the latest version of PPL4C by return mail. A 5.25" diskette is provided unless a 3.5" diskette is requested. PPL4C Users Manual Page 20 8.2 License MarshallSoft Computing, Inc. grants the registered user of PPL4C the right to use the PPL4C library (in object form) in the development of any software product without any royalties. However, the source code for the library may not be released in whole or in part. 8.3 Warranty MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE. Some states do not allow the exclusion of the limit of liability for consequential or incidental damages, so the above limitation may not apply to you. This agreement shall be governed by the laws of the State of Alabama and shall inure to the benefit of Marshallsoft Computing, Inc. and any successors, administrators, heirs and assigns. Any action or proceeding brought by either party against the other arising out of or related to this agreement shall be brought only in a STATE or FEDERAL COURT of competent jurisdiction located in Madison County, Alabama. The parties hereby consent to in personam jurisdiction of said courts. 9.0 Revision History Version 1.0 -- 10 August 1992 -- original release. Version 1.1 -- 4 Jan 1993 o Added support for 4 simultaneous channels. (Requires version 3.4 of PCL4C). PPL4C Users Manual Page 21 10.0 Other MarshallSoft Computing Products 10.1 The Personal Communications Library for C The Personal Communications Library for the C Language (PCL4C) is an asynchronous communications library designed for experienced software developers programming in C. Four compilers are supported: Microsoft Optimizing C, Microsoft Quick C, Borland Turbo C, and MIX Power C. An IBM PC/XT/AT or compatible is required. The PCL features: o SMALL, COMPACT, MEDIUM & LARGE memory models. o 32 communications and support functions. o Support for the high performance INS16550 UART. o Supports hardware (RTS/CTS) flow control. o Interrupt driven receiver. o Supports 300 baud to 115,200 baud. o Supports COM1, COM2, COM3, and COM4. o Adjustable receive queues from 8 bytes to 32 KB. o Control-BREAK error exit. o 17 communications error conditions trapped. o Allows 4 ports to run concurrently. o Complete modem control & status. o Written in assembly language for small size & high speed. o Terminal program featuring XMODEM, YMODEM, & YMODEM-G. The Personal Communications Library for C (PCL4C) is available for $55 plus $3 S&H ($6 S&H overseas). It may be ordered at the same time as the Personal Protocol Library for $65 plus $3.50 S&H ($7 overseas). 10.2 The LZW Data Compression Library for C LZW4C is an implementation of the LZW (Lempel-Ziv-Welch) algorithm for compressing and decompressing data. LZW does particularly well on text files, achieving better than a 50 % compression ratio for many files. The LZW algorithm is considered to be one of the best general purpose algorithms available today. The new high speed modems that employ on-the-fly data compression (such as MNP 5.0 & the V.42 bis international standard) use the LZW algorithm, as well as such well known utility programs such as PKZIP. The LZW Data Compression Library for C is available for $35 plus $3 S&H ($6 S&H overseas). PPL4C Users Manual Page 22