Prima Shareware 3

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

/ Prima Shareware 3 / DuCom_Prima-Shareware-3_cd1.bin / PROGRAMO / C / PERSONPR / PPL4C.DOC < prev next >

Wrap

Text File | 1995-02-12 | 51.9 KB | 1,770 lines

Personal Protocol Library For C/C++ (PCL4C) USERS MANUAL Version 1.0 February 12, 1995 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1995 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Voice 205-881-4630 FAX 205|880|0925 BBS 205-880-9748 _______ ____|__ | (R) --+ | +------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals --+--+ | +--------------------- |___|___| MEMBER PPL4C Users Manual Page 1 C O N T E N T S Chapter Page 1.0 Introduction................................................3 1.1 User Support............................................3 1.2 ASP Ombudsman...........................................3 1.3 Installation............................................4 2.0 Library Organization........................................5 2.1 Performance.............................................5 3.0 Protocol Intefaces..........................................6 3.1 ASCII API...............................................6 3.2 XMODEM API..............................................7 3.3 YMODEM API..............................................8 3.4 ZMODEM API..............................................9 4.0 Protocol Demonstration Program (TERM)......................10 5.0 XMODEM Protocol Overview...................................11 5.1 XMODEM/CRC.............................................13 5.2 XMODEM/1K..............................................13 6.0 YMODEM Protocol Overview...................................14 7.0 ZMODEM Protocol Overview...................................15 7.1 Introduction...........................................15 7.2 Link Escape Encoding...................................15 7.3 ZMODEM Headers.........................................15 7.4 Binary Data Subpackets.................................16 7.5 ZMODEM Startup.........................................16 7.6 File Transmission......................................17 7.7 ZMODEM Termination.....................................17 7.8 ZMODEM Streaming.......................................17 7.9 ZMODEM Attention Sequence..............................18 7.10 Frame Types...........................................18 ZRQINT,ZRINIT,ZSINIT,ZACK.............................18 ZFILE.................................................19 ZSKIP,ZNAK,ZABORT,ZFIN,ZRPOS..........................20 ZDATA,ZEOF,ZFERR,ZCRC.................................20 ZCHALLENGE,ZCOMPL,ZCAN,ZFREECNT,ZCOMMAND..............21 7.11 Examples..............................................22 7.12 ZFILE Frame Information...............................22 8.0 Problems...................................................23 9.0 Legal Issues...............................................24 9.1 Registration...........................................24 9.2 License................................................25 9.3 Warranty...............................................25 10.1 Revision History...........................................26 11.0 Other MarshallSoft Computing products for Pascal...........26 11.1 The Personal Communications Library for Pascal........26 11.2 The LZW Data Compression Library for Pascal...........26 PPL4C Users Manual Page 2 1.0 Introduction The Personal Protocol Library for C/C++ (PPL4C) consists of ASCII, XMODEM, YMODEM, and ZMODEM protocol routines plus the example terminal program TERM and support routines such as CRC calculation codes. Source is supplied for all routines except for the ZMODEM code which requires registration for source code. The PPL4C also requires the Personal Communications Library (PCL4C). 1.1 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 protocol library that we can. If you have any suggestions or comments, please let us know! We provide customer support for registered customers by voice, FAX, BBS, and mail. We provide limited support for unregistered users by voice and BBS only. If you are having a problem using PPL4C, call us at 205-881-4630 between 1:30 PM and 9:30 PM (CST) Monday through Friday. You can also call at other times and leave a message, and call back later for a reply. Registered users (ONLY) can also FAX us at 205-880-0925 at any time (24 hours). However, we can only answer questions with respect to using the PPL4C library. We cannot help you program your application, but we'll be glad to discuss it with you. You may also call our User Support BBS (2400 to 14400 baud, no parity, 8 data bits, 1 stop bit) at 205-880-9748 and leave a message (address it to the SYSOP). We will usually have a reply ready for you within 24 hours. The BBS is available 24 hours per day. All files are in standard ZIP format. The BBS will contain the latest shareware version of all MarshallSoft Computing products as well as related files such as: BUGS.ZIP - Bug report. NEWS.ZIP | Latest news regarding our products. PRODUCTS.ZIP - List of all shareware products. The MarshallSoft Computing, Inc. newsletter "Comm Talk" is published quarterly. It discusses various communications problems and solutions using PPL4C as well as related information. Registered users (in the US) receive a one year complimentary subscription when first registering and for each update purchased. 1.2 ASP Ombudsman MarshallSoft Computing, Inc. is a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI USA 49442-9427, Fax 616-788-2765, or send a CompuServe message via CompuServe Mail to ASP Ombudsman 70007,3536. PPL4C Users Manual Page 3 1.3 Installation (1) PPL4C requires the Personal Communications Library for C/C++ (PCL4C). If you don't already have it, you may download it from our user support BBS at 205-880-9748. (2) Before installation of PPL4C, your compiler should already be installed on your system and tested. If you are not familiar with makefiles, refer to your compiler manual. (3) Make a backup copy of your distribution disk. Put your original distribution disk in a safe place. (4) Create a empty 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 (5) Copy all the files from your backup copy of the distribution disk to your PPL4C work directory. For example, to copy from the A: drive to your work directory, we type: CD PPL4C COPY A:*.* (6) Your must copy PCL4C_*.LIB (PCL4C_*.MIX if using Power C) and PCL4C.H to your PPL4C work directory from your PCL4C distribution disk in order to compile the TERM protocol demonstration program. Don't combine files from the PCL4C distribution disk and the PPL4C distribution disk other than coping PCL4C_*.LIB and PCL4C.H. (7) Compile the TERM.C protocol demonstration program. Note that the shareware version of ZMODEM.C is in "shrouded source" form. make -fterm._T_ (for Turbo C/C++) make -fterm._B_ (for Borland C/C++) make term._M_ (for Microsoft C/C++) pc/e term (for MIX Power C) (8) To test TERM type TERM followed by the port and baud rate. For example, to start TERM on COM1 at 38400 baud, type: TERM 1 38400 Test TERM by connecting COM1 to a modem or another PC with a null modem cable. PPL4C Users Manual Page 4 2.0 Library Organization The library is composed of two parts as follows: (1) The copyrighted XMODEM, YMODEM, and ZMODEM functions contained in the files: xymodem.c xypacket.c zmodem.c The shareware version of ZMODEM.C is in "shrouded source" form. This means that the source code can be compiled but not easily modified. The registered user will have "normal source". (2) The public domain example code contained in the files: term.c term_io.c amodem.c modem_io.c crc16.c crc32.c defines.c si.c opcodes.c zdate.c datetime.c dir_io.c 2.1 Performance XMODEM, YMODEM, and ZMODEM were timed in transfers between a 386 and a 486 using a null modem cable. The timed results for a 10,000 byte files in characters per second (CPS) transfered are as follows: 2400 9600 19200 38400 XMODEM 193 590 1256 2514 YMODEM 228 773 1671 3351 ZMODEM 220 860 1800 3004 Your results may vary depending on the type of hardware used, but the above should be fairly close. PPL4C Users Manual Page 5 3.0 Protocol Interfaces The API (Application Programming Interface) is documented for the following four protocols: ASCII, XMODEM, YMODEM, and ZMODEM. 3.1 ASCII API ASCII is not realy a "protocol" but rather a loosely agreed upon method of transferring ASCII files. The ASCII protocol is contained in AMODEM.C. int TxAscii( int Port, /* COM port [0..19] */ char *Filename, /* filename buffer */ int CharPace, /* delay between characters in tics */ char TermChar, /* termination character (0x00 if none) */ int TimeOut, /* delay after which assume sender is done */ int EchoFlag) /* local echo flag */ int RxAscii( int Port, /* COM port [0..19] */ char *Filename, /* filename buffer */ char TermChar, /* termination character (0x00 if none) */ int TimeOut, /* delay after which assume sender is done */ int EchoFlag) /* local echo flag */ Note the following: (1) The Filename must not contain any path information. (2) TermPace should in general be 1 to 5 timer tics (18.2 tics per second). (3) TermChar is often set to escape (0x1B) or control-X (0x18). If both sides don't agree, it is best not use a termination character. (4) TimeOut should be set to from 3 to 10 seconds. (5) The receiver side (RxAscii) should be started before the sender side. Refer to the TERM.C program for an example of calling TxAscii and RxAscii. PPL4C Users Manual Page 6 3.2 XMODEM API XMODEM is the first well accepted protocol. There are many places where it is still the only choice for transferring binary files. The XMODEM protocol is contained in XYMODEM.C and XYPACKET.C. There are two main variants of XMODEM in addition to standard XMODEM as follows: Protocol OneKflag NCGbyte XMODEM False NAK XMODEM-CRC False 'C' XMODEM-1K True 'C' int XmodemTx( int Port, /* COM port [0..19] */ char *Filename, /* filename buffer */ int OneKflag) /* 1K flag */ int XmodemRx( int Port, /* COM port [0..19] */ char *Filename, /* filename buffer */ char NCGbyte) /* NAK or 'C' */ Refer to the TERM.C program for an example of calling XMODEM. PPL4C Users Manual Page 7 3.3 YMODEM API The YMODEM protocol (also referred to as "YMODEM/BATCH") is a batch protocol capable of sending multiple files along with their filename, size, and date of last modification. It also can send 1024 byte packets in addition to 128 byte XMODEM packets. The YMODEM protocol is contained in XYMODEM.C and XYPACKET.C. There is one variant of YMODEM called YMODEM-G which is used with error correcting modems only. Flow control is also required in order to use YMODEM-G. Protocol OneKflag NCGbyte YMODEM True 'C' YMODEM-G True 'G' int YmodemTx( int Port, /* COM port [0..19] */ char *Filename, /* filename buffer */ int OneKflag) /* 1K flag */ int YmodemRx( int Port, /* COM port [0..19] */ char *Filename, /* filename buffer */ char NCGbyte) /* NAK or 'C' */ Refer to the TERM.C program for an example of calling YMODEM. PPL4C Users Manual Page 8 3.4 ZMODEM API The Stream variable controls rather Zmodem will attempt to send packets without any acknowlegement. Set Stream to false for high baud rates (38400 and above) or for noisy lines. The ZMODEM protocol is contained in ZMODEM.C. int ZmodemTx( int Port, /* COM port [0..19] */ char *Filename, /* filename buffer */ int Stream) /* Can do streaming ? */ int ZmodemRx( int Port, /* COM port [0..19] */ char *Filename, /* filename buffer */ int Stream) /* Can do streaming ? */ Refer to the TERM.C program for an example of calling ZMODEM. PPL4C Users Manual Page 9 4.0 Protocol Demonstration Program (TERM) TERM is an communications program suitable for calling up bulletin board systems (BBS) and performing as a PC to PC file copy program. TERM itself is not part of the communications library, but rather it is provided as an example of a communications application using PPL4C. TERM can send a standard Hayes standard AT command set string to your modem. An initialization string is sent by TERM provided that AT_COMMAND_SET is defined in TERM.CFG. #define AT_COMMAND_SET 1 Refer to the chapter "Modem Initialization" in the Personal Communications Library Users Manual for a discussion of initialization strings. TERM also supports hardware flow control (RTS/CTS). Hardware flow control is observed provided that the constant RTS_CTS_CONTROL is defined in the file TERM.CFG. #define RTS_CTS_CONTROL 1 Refer to the chapter "Flow Control" in the Personal Communications Library Users Manual for a discussion of hardware flow control. TERM can be configured to run script files by setting #define SCRIPTS 1 in TERM.CFG. Refer to the SCRIPTS.DOC file for information on scripts. TERM can exchange files using ASCII XMODEM, YMODEM and ZMODEM communications protocols. TERM can accept wildcards in the filename so that multiple files can be sent using YMODEM and ZMODEM. The protocol timing can also be adjusted (this should not be necessary) by modifying the constants SHORT_WAIT and LONG_WAIT in the PPL4C.C file. TERM can also be used as a PC to PC transfer program using a null modem cable. In this case, AT_COMMAND_SET and RTS_CTS_CONTROL should not be defined in the file TERM.CFG: Be advised that many null modem cables are do NOT swap RTS and CTS, which is necessary for hardware flow control. This means that RTS_CTS_CONTROL should never be defined when using a null modem cable unless you are absolutely sure that RTS and CTS are swapped. To start TERM, type TERM followed by the port (1 to 4) and the baud rate (300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, or 115200). For example, to start TERM at 2400 baud on port COM4: TERM 4 2400 The TERM program (but not the PPL4C protocol routines) are placed in the public domain by MarshallSoft Computing, Inc., and can be used in any way desired by the user. PPL4C Users Manual Page 10 5.0 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. (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. PPL4C Users Manual Page 11 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 exitting. 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 12 5.1 XMODEM/CRC Protocol 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. 5.2 XMODEM/1K Protocol 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 13 6.0 YMODEM Protocol 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 oriented MSDOS ints. 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. Here is an example of YMODEM: SENDER RECEIVER ACK C 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 NAK EOT ACK C SOH 00 FF NUL[128] CRC CRC ACK PPL4C Users Manual Page 14 7.0 ZMODEM ZMODEM was developed for UNIX by Chuck Forsberg of Omen Technology for the public domain under contract by Telenet. The ZMODEM protocol description and UNIX source code are public domain. Furthermore, no licensing, trademark, or copyright restrictions apply to the use of the ZMODEM protocol or the Unix source code. The following description is meant as an overview only of the ZMODEM protocol. A more complete description can be obtained on CompuServe (in the protocols library of the IBMCOM forum) or directly from Omen Technology, Inc. (503-621-3406 Voice). ZMODEM is complex. For PC to PC file transfers, it is certainly overkill. Our protocol library implements the original public domain UNIX based ZMODEM, with a few minor exceptions that have no impact for use between PCs. 7.2 Link Escape Encoding ZMODEM send and receives binary data without the use of a length count by using a technique known as "data escape encoding". A special character ZDLE (hex 18) is used to mark the beginning of frames. The receiving program decodes any sequence of ZDLE followed by a byte with bit 6 set and bit 5 clear to the control character consisting of the byte with bit 6 inverted. This allows the transmitter to escape any control character including ZDLE itself. 7.3 ZMODEM Headers ZMODEM frames begin with a hexidecimal or binary header. A header always begins with a frame type and is followed by either a 4 byte file position or 4 bytes of flags. The order of bytes in the header is as follows: 0x00 Type field: Frame type (1 byte) 0x01 Data bytes: F3 or P0 0x02 F2 or P1 0x03 F1 or P2 0x04 F0 or P3 where F = flags, P = file position 7.3.1 16-Bit CRC Binary Headers A binary header begins with the sequence ZPAD, ZDLE, ZBIN with the frame type byte and four flag or position bytes being ZDLE encoded. A two byte CRC is computed from the frame type through the flag/position bytes and is also ZDLE encoded. Zero or more 16 bit CRC binary data subpackets may follow. ZPAD ZDLE ZBIN TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC1 CRC2 7.3.2 32-Bit CRC Binary Headers A 32 bit CRC Binary header is identical to a 16 bit CRC Binary Header except ZBIN is replaced by ZBIN32 and four bytes of CRC are sent. Zero or more 32 bit CRC binary data subpackets may follow. ZPAD ZDLE ZBIN32 TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC1 CRC2 CRC3 CRC4 PPL4C Users Manual Page 15 7.3.3 Hexidecimal Headers The sender will use hexidecimal headers when they are not followed by binary data subpackets. The receiver will also send responses headers in hexidecimal. Any data packet following a hexidecimal header uses CRC-16. A carriage return and line feed are appended to hexidecimal header. An XON character is also appended except for ZACK and ZFIN headers. Zero or more data subpackets will follow depending on the frame type. ZPAD ZPAD ZDLE ZHEX TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC1 CRC2 CR LF XON Note that TYPE, F3...F0, CRC1, and CRC2 are each sent as two hexidecimal digits. 7.4 Binary Data Subpackets A binary data subpacket may immediately follow a binary header. A binary data packet will contain 1024 bytes of data or less. The data bytes are ZDLE encoded and are terminated by ZDLE, FrameEnd, and ZDLE encoded CRC bytes. The CRC is summed from the data bytes through the FrameEnd. 7.4.1 Frame Ends Data packets are terminated by one of several Frame End headers. 7.4.1.1 ZCRCG A ZCRCG data packet means "do not respond unless an error is detected". 7.4.1.2 ZCRCQ A ZCRCQ data packet requires a ZACK response with the file offset of the receiver if no error, otherwise a ZRPOS response with the last correct file offset. 7.4.1.3 ZCRCW A ZCRCW data packets expect a response before the next packet is sent. 7.4.1.4 ZCRCE A ZCRCE data subpacket is used to end the end of the file. It does not require a response unless an error is detected. 7.5 ZMODEM Startup ZMODEM timing is receiver driven. The sender may send a ZRQINIT header, which requests the receiver to immediately send a ZRINIT. The ZMODEM receiver transmits a ZRINIT header to initiate file transfers, or a ZCHALLENGE header to verify the idenity of the sending program. The receiver retransmits its header at 10 second intervals for up to one minute before aborting. If the receiver receives a ZRQINIT header, it responds by sending (again) a ZRINIT header. If the sender receives the ZCHALLENGE header, it responds with a ZACK using the data in P0...P3. The sender may also send a ZSINIT frame to define the receivers Attention sequence. PPL4C Users Manual Page 16 7.6 File Transmission A file transmission is initiated when the sender transmits a ZFILE header followed by a ZCRCW data subpacket containing the file name, file length, file modification date, and file modification time. If appropriate, the receiver responds with a ZSKIP header which directs the sender to skip to the next file. If the receiver already has a file with the same name and length, it will respond with a ZCRC header which requests that the sender perform a (32 bit) CRC on the file and transmit back to the receiver. The receiver then uses this information to determine whether to accept the file or not. The receiver initiates transmission of a file by sending a ZRPOS header which specifies the starting offset in bytes. This allows an interrupted file transfer to be resumed. The sender transmits a ZDATA binary header with file position followed by one or more data subpackets. The receiver compares the file position in the ZDATA header with the number of bytes already received. If they do not agree, a ZRPOS header is sent to resynchronize the sender at the right position in the file. After all data has been transmitted, a ZEOF header is sent containing the ending file offset. The receiver compares this number with the number of bytes received. If they match, the file is closed and the receiver reponds with a ZRINIT. If the receiver has not received all bytes, then the ZEOF is ignored since another ZDATA is coming. A ZFERR header is sent if the receiver cannot close the file. 7.7 ZMODEM Termination A ZFIN header is sent in order to close the session. which is acknowledged by a ZFIN header. Then the two characters "OO" are sent by the sender. The receiver waits briefly for the "OO" then exits even if not received. 7.7.1 Session Abort Sequence The Attention sequence is used to interrupt a data transmission so that a cancel sequence can be sent (8 CANs and 10 BSs). 7.8 ZMODEM Streaming Since PCs can overlap serial I/O and disk I/O, full streaming is possible. The sender begins its data transmission with a ZDATA header followed by ZCRCG data sub packets. If the receiver detects an error, it executes the Attention sequence and transmits a ZRPOS header. A ZACK header with an address that disagrees with the sender is ignored by the receiver A ZFIN, ZABORT, or TIMEOUT terminates the session, while a ZSKIP terminates the transmission of the file. PPL4C Users Manual Page 17 7.9 Attention Sequence The receiving program transmits the Attention sequence whenever it detects an error and needs to interrupt the sending program. The default Attention string value is empty. The receiver resets Attention sequence to empty before each transfer session. The sender specifies the Attention sequence in the ZSINIT frame. 7.10 Frame Types The numeric values for the values shown in boldface are given in zmodem.h. Unused bits and unused bytes in the header (ZP0...ZP3) are set to 0. 7.10.1 ZRQINIT Transmitted by the sender to request that the receiver transmits a ZRINIT header. ZF0 contains ZCOMMAND if the sender is attempting to send a command, 0 otherwise. 7.10.2 ZRINIT Transmitted by the receiver. ZF0 and ZF1 contain the bitwise OR of the receiver flag bytes. The receiver flag bits and PPL default settings are: CANCRY = 0x08 /* Can decrypt - NO */ CANFDX = 0x01 /* Can do full duplex - YES */ CANOVIO = 0x02 /* Can receive data during disk I/O -YES */ CANBRK = 0x04 /* Can send a break signal - YES */ CANCRY = 0x08 /* Can decrypt - NO */ CANLZW = 0x10 /* Can uncompress - NO */ CANFC32 = 0x20 /* Can use 32 bit Frame Check - YES */ ESCCTL = 0x40 /* Expects control chars to be escaped NO */ ESC8 = 0x80 /* Expects 8th bit to be escaped - NO */ ZP0 and ZP1 contain the size of the receiver's buffer in bytes, or 0 if nonstop I/O is allowed. 7.10.3 ZSINIT Transmitted by the sender. Contains the foloowing flags followed by a ZCRCW terminated binary data subpacket. /* ZF0 bit masks */ TESCCTL = 0x40 /* Expects control bytes to be escaped */ TESC8 = 0x80 /* Expects 8th bit to be escaped */ The data subpacket contains the (null terminated) Attention sequence. 7.10.4 ZACK Transmitted by the receiver. Acknowledges a ZSINIT frame, ZCHALLENGE header, or ZCRCQ / ZCRCW data subpacket. ZP0 to ZP3 contain the file offset. The response ZACK to a ZCHALLENGE contains the same 32 bit number received in the ZCHALLENGE header. PPL4C Users Manual Page 18 7.10.5 ZFILE Transmitted by the sender. This ZFILE frame signifies the beginning of a file transmission. ZF0, ZF1, and ZF2 flags contain options. A value of 0 in implies no special treatment. Options specified by the sender (to the receiver) over ride any options specified by the receiver except for ZCBIN. 7.10.5.1 ZF0: Conversion Option ZCBIN: "Binary" transfer - inhibit conversion unconditionally ZCNL: Convert received end of line to local end of line convention (CR/LF or NL). ZCRECOV: Resume interrupted file transfer. 7.10.5.2 ZF1: Management Option Transfer normally if the receiver can not recognize the Management Option. ZMSKNOLOC: Instructs the receiver to bypass the current file if the receiver does not have a file with the same name. One and only one of the following may be set (defined by ZMMASK). ZMNEWL: Transfer the file if the destination file is absent. Otherwise, transfer the file overwriting the destination if the source file is newer or longer. ZMCRC: Compare the source and destination files. Transfer the file if the source and destination file lengths or file polynomials are different. ZMAPND: Append the source file to the end of the existing destination file. ZMCLOB: Replace the existing destination file (if any). ZMDIFF: Transfer the file if destination file is missing. Otherwise, transfer the file overwriting destination if files have different lengths or dates. ZMPROT: Transfer the file only if the destination file is absent (protects destination file).. ZMNEW: Transfer the file if the destination file is absent. Otherwise, if the source file is newer, transfer the file overwriting the destination. 7.10.5.3 ZF2: Transport Option ZTLZW: Do Lempel-Ziv compression. (NOT supported). ZTCRYPT: Do encryption. (NOT supported). ZTRLE: Do run length encoding. (NOT supported). A data subpacket terminated by ZCRCW follows with file name, file length, and modification date. PPL4C Users Manual Page 19 7.10.5.4 ZF3: Extended Options ZTSPARS: Special processing for sparse files. (NOT supported). 7.10.6 ZSKIP Transmitted by the receiver. Used in response to ZFILE, requests that the sender skip the current file. 7.10.7 ZNAK Transmitted by the sender or the receiver. Indicates that the last header was unintelligible. 7.10.8 ZABORT Transmitted by receiver. Used to terminate batch file transfers when requested by the user. The sender responds with a ZFIN header. 7.10.9 ZFIN Transmitted by sender and receiver. Used by the sender to terminate the ZMODEM session. The receiver responds by also sending a ZFIN header. 7.10.10 ZRPOS Transmitted by receiver: Used to force file transfer to resume at the file offset specified in ZP0...ZP3. 7.10.11 ZDATA Transmitted by the sender. The ZP0...ZP3 flags contain file offset. One or more data subpackets follow. 7.10.12 ZEOF Transmitted by the sender. Used to report EOF (end of file). ZP0...ZP3 contain the ending file offset. 7.10.13 ZFERR Transmitted by the sender or receiver. Used to signify an error in reading or writing a file. 7.10.14 ZCRC Transmitted by both the sender and the receiver. Used by the receiver to request a file polynomial. Used by the sender to provide requested file polynomial (contained in ZP0...ZP3). PPL4C Users Manual Page 20 7.10.15 ZCHALLENGE Transmitted by the receiver. Used to request that the sender echo the (random) number in flags ZP0...ZP3 in a ZACK frame. 7.10.16 ZCOMPL Transmitted by both the sender and the receiver. Used to report that the request is now completed. 7.10.17 ZCAN Transmitted by both sender and receiver. Used to abort. 7.10.18 ZFREECNT Transmitted by the sender. Used to request a ZACK frame with the flags ZP0...ZP3 containing the number of free bytes on the current file system. A zero indicates an abritrarily large amount of free space. 7.10.19 ZCOMMAND Transmitted by sender or receiver. It is sent in a binary frame in which ZF0 contains zero or a ZCACK1. A ZCRCW data subpacket follows containing an zero terminated ASCII text command string. If the first character of the command is a !, then it is meant to be executed by the O/S, otherwise it it mean to be executed by the application program. If the receiver cannot decipher the command, then it immediately responds with a ZCOMPL header (with the error code in ZP0...ZP3). If ZF0 contained a ZCACK1, then the receiver responds immediately with a ZCOMPL header with 0 status. Otherwise, the receiver responds with a ZCOMPL header when the operation is completed with the exit status of the command in ZP0...ZP3. PPL4C Users Manual Page 21 7.11 Examples Example 1: One file, no errors, no CHALLENGE. SENDER RECEIVER ZRQINIT(0) ZRINIT ZFILE ZRPOS ZDATA data ... ZEOF ZRINIT ZFIN ZFIN OO Example 2: Challenge and Command Download SENDER RECEIVER ZRQINIT(ZCOMMAND) ZCHALLENGE(random-number) ZACK(same-number) ZRINIT ZCOMMAND ZDATA (Performs Command) ZCOMPL ZFIN ZFIN OO 7.12 ZFILE Frame Information 7.12.1 Filename Null terminated ASCII string. Path information is optional but not used. 7.12.2 File Length (optional) The file length is stored as a decimal string. Used by the ZMODEM receiver as an estimate only. 7.13.3 Modification Date (optional) The modification date is sent as an octal number giving the time the contents of the file were last changed measured in seconds from Jan 1 1970 Universal Coordinated Time (GMT). A date of 0 implies the modification date is unknown. A single space separates the modification date from the file length. The file information is terminated by a null. PPL4C Users Manual Page 22 8.0 Problems If you cannot get your application to run properly, first compile and run the demonstration program TERM provided on your distribution disk. If you are using a null modem cable or a non-programmable modem, be sure not to define AT_COMMAND_SET in TERM.CFG. If you are using a Hayes compatible modem, then do define AT_COMMAND_SET. If you are using a programmable modem which is not Hayes compatible, then you must modify the initialization string for your particular modem. If your application does not run but TERM runs correctly, then you have most likely made a programming mistake in your application. MarshallSoft Computing cannot debug your application, especially over the telephone! However, consider each of the following when searching for an error in your application. 1. Did you include the "uses PPL4C" statement ? 2. Is your receive buffer large enough ? If you are using 1K data blocks in YMODEM, then your receive buffer should be at least 1K (2K if baud rates above 38400 are to be used). 4. Have you selected too high a baud rate (if you are using a slow PC) ? If only one COM port is being run, you should be able to run at 38400 baud on 8088 machines and 115200 on most 286 and all 386 and 486 machines. 7. Are you attempting to run another application in the background ? Try running without any other programs running in the background (unload all TSR programs). 6. If you are running two COM ports simultaneously, are you using separate receive buffers ? (you should). 7. Did SioReset return a zero value ? If not, then you must call SioReset again. See TERM.C for an example. 8. Did you send the proper initialization string to your modem ? Did you set DTR and RTS ? (you should). 9. Do you have more than one COM1 port, etc. For example, if you have a COM1 port on your motherboard, you cannot add another COM1 port or modem board that uses COM1 without first disabling the COM1 on the motherboard. 10. Are you passing the proper segment of the receive (or transmit) buffer?. See SIMPLE.C or TERM.C for an example. 11. Is the other side running the same protocol? 12. Are you using 8 data bits. All the protocols except ASCII require 8 data bits. Registered users can call 205-881-4630 from 1:30 PM to 9:30 PM CST Monday through Friday for help. We are also often here on the weekend! PPL4C Users Manual Page 23 9.0 Legal Issues 9.1 Registration If you wish to register the PPL4C library, please send $40 plus $3 S&H ($6 outside of North America) to: MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Multiple copies are available: $35 for 3 to 9, $30 for 10 to 19, and $25 for 20 or more. A site license is also available for $495 (includes 5 sets of printed documentation). We pay shipping. We accept American Express (account number, expiration date, exact name on your card, and complete 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 PPL4C.INV if an invoice is needed. You can also order PPL4C from The Public Software Library (PSL) with your MC, Visa, AmEx, or Discover card by calling 800-242-4PSL (from overseas: 713-524-6394) or by FAX at 713-524-6398 or by CompuServe at [71355,470]. THESE NUMBERS ARE FOR ORDERING ONLY. The product number for PPL4C is 11782. If you wish to update from an older version of PPL4C, send $20 plus $3 S&H ($6 outside of North America). Updates must be ordered directly from MarshallSoft Computing. The registered package includes: o C/C++ source code for the library (including ZMODEM). o Printed Users Manual. o Telephone and BBS support for one year. o Script compiler & interpreter. o Script compiler (BUILDER) creates script binaries from source. o Script interpreter (SI) executes script binaries. Print the file INVOICE.DOC if an invoice is needed. The registered user will receive the latest version of PPL4C shipped by two day priority mail (packet airmail overseas). A 3.5" (720KB) diskette is provided unless a 5.25" (360KB) diskette is requested. PPL4C Users Manual Page 24 9.3 License MarshallSoft Computing, Inc. grants the registered user of PPL4C the right to use one copy of the PPL4C library (in object form) on a single computer in the development of any software product (other than libraries such as PPL4C). The user may not use the library on more than one computer at the same time. The source code for the library (XYMODEM.C and ZMODEM.C) is copyrighted by MarshallSoft and may not be released in whole or in part. Products developed using PPL4C can include the object form of the library and may be distributed without any royalty. 9.4 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. PPL4C Users Manual Page 25 11.0 Summary 11.1 Revision History Version 1.0 - 12 February 1995 - original release. XMODEM and YMODEM in PPL4C is based on version 4.2 of the Communications Library for C/C++ (PCL4C). ZMODEM is new. 12.0 Other MarshallSoft Computing Products for C/C++ 12.1 The Personal Communications Library for C/C++ The Personal Communications Library for C/C++ (PCL4C) is an asynchronous communications library designed for experienced software developers programming in C and/or C++. The PCL features: o 33+ communications and support functions. o Support for the high performance INS16550 UART. o Supports hardware (RTS/CTS) flow control. o Interrupt driven tranmitter (optionally) & receiver. o Supports 300 baud to 115,200 baud. o Supports COM1 through COM20. o Adjustable receive queues from 8 bytes to 32 KB. o Control-BREAK error exit. o 17 communications error conditions trapped. o Supports most dumb multiport board such as those by Digiboard, BOCA, and GTEK. o Allows 4 to 20 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/C++ (PCL4C) is available for $65 plus $3 S&H ($6 S&H overseas). 12.2 The LZW Data Compression Library for C/C++ LZW4C consists of a variable code size 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/C++ is available for $45 plus $3 S&H ($6 overseas). PPL4C Users Manual Page 26