Softerm Modular Communications and Terminal Emulation WREAD.TXT - Documentation Supplement September 2, 1992 This Windows Notepad file contains changes and additions to the printed manual. To obtain a hardcopy of this information, print the READ.ME file using a command similar to: COPY READ.ME LPT1 Contents: 1. Changes to Softerm Modular - Revisions to the installation program and procedure (including file decompression utility) - Name changes to menu options - Problem Determination (removed option) - Close Appended Capture (new option) - Profile data base not created automatically - "If File Exists" now supports Zmodem (see also topic 8) 2. Printing to a Network Printer 3. REDIRBUF.COM - If you receive memory error messages, you should try this memory resident network redirector buffer for Windows 4. Nationality Profile Character Representations 5. Script File Changes and Additions - Additions to the DIAL() function - Correction to the description of the Not (!) operator - New EXIT directive - Corrections to the HOST() function - Corrections to the READLINE() function - New RETRIES System Variable 6. Int14 Vendor-Specific Information 7. Softrans File Transfer Protocol Source Code 8. Zmodem File Transfer Protocol ***** I. Changes to Softerm Modular -------------------------- Please make a note of the following changes in the manual: 1. Pages INTRO.2 - 3 The Install program has been divided into INSTALL.EXE, which copies necessary installation files to the designated drive and directory and SETUP.EXE, which performs the main installation and program configuration. Quick Install has been renamed to Install All. In addition, Softerm's files are compressed, and the first character of the file extension is changed to a '$'. Should you want to manually decompress a file, the decompression utility, SFTUNARC.EXE, is supplied on Disk 4. Its syntax is: SFTUNARC [/L] InFileName [OutFileName] where: /L is an optional switch which will List the contents of a compressed file. InFileName is the name of the file to be decompressed. OutFileName is the optional decompressed file name. If not supplied, it defaults to '*.*'. (Currently, however, each archive contains only one file.) This parameter accepts templates, such as '*.dll', '*.hlp', 'wh*.dll'. Examples: SFTUNARC OHP2392.$LL SFTUNARC /L WHP2392.$LL SFTUNARC OHP2392.$LL HP*.HLP Compressed Extension Decompressed Extension .$OM .COM .$LL .DLL .$XE .EXE .$LP .HLP .$DB .MDB .$OD .MOD 2. Page INTRO.3 The Hide option has been renamed to GUI Disable. 3. Pages MO.1 - 2 (Session Manager: Options Menu) The Problem Determination option has been removed. 4. Page RF.9 (Session Window: File Menu) Please add the following information to Close Capture: a. The cascading menu now appears similar to: +------------------------+ | Save Capture | | Discard Capture | +------------------------+ | Close Appended Capture | +------------------------+ b. Close Appended Capture If the Terminal Emulation printer definition option Append Disk Printer File On Close (p. PE.8) is enabled and printer data has been redirected to a disk file, use this option to permanently close the file. Important: A capture cannot be active when this option is used. 5. Pages RO.1 and RO.5 (Session Window: Options Menu) The Problem Determination option has been removed. 6. Pages E.2 and E.3 (Appendix E: Startup Switches) If the named profile data base does not exist, it will not be created. 7. Page RF.5 (Session Window: File Menu) Please change the description of "If File Exists" to: If a file with the name you have assigned already exists on your PC, you can specify that you want to: - Resume the transfer (if you are using Zmodem); - Replace the existing file; - Append the received data to the end of the existing file, or; - Stop the file transfer. ***** II. Printing to a Network Printer ----------------------------- Softerm fully supports rerouting LPT1, LPT2 and LPT3 to network printers, but does not monitor the status of the printers. Serial printing is supported only on local ports unless the vendor's network software supports such cases. ***** III. REDIRBUF.COM ------------ You may need to use the REDIRBUF.COM utility if you receive memory error messages when adding a Connection Path profile or starting a session, and you use Softerm on one of these networks: Any Int 14 network Eicon Bridge BAPI NetWare ACS DEC LAT IBM ACS Softerm ACS REDIRBUF may be necessary because Windows cannot promise that buffer space will be available for network redirection. If running REDIRBUF.COM solves the problem, add the command to your AUTOEXEC.BAT file. REDIRBUF accepts two command line parameters: REDIRBUF [2 through 64] will install a buffer of that many kilobytes. If this parameter is not specified, REDIRBUF defaults to a 4k buffer. Specifying a number smaller than 2 will create a 2k buffer, and specifying a number larger than 64 will display an error message without installing the buffer. REDIRBUF /U will uninstall the buffer. ***** IV. Nationality Profile Character Representations --------------------------------------------- If you use the Nationality Profile to remap incoming or outgoing characters, you may see character descriptions which appear similar to: Character Description Hexadecimal [VT] NOTE:See READ.ME 0BH These characters cannot be displayed within the menu system. Locate the Hexadecimal value in the following list for a description of how the character is translated or print the READ.ME file which also displays the actual character: Hex Description 001H Single Line Horizontal 002H Single Line Vertical 003H Single Line Upper Left Corner 004H Single Line Upper Right Corner 005H Single Line Lower Left Corner 006H Single Line Lower Right Corner 007H Single Line Cross 008H Single Line Junction Left 009H Single Line Junction Right 00AH Single Line Junction Top 00BH Single Line Junction Bottom 00CH Double Line Horizontal 00DH Double Line Vertical 00EH Double Line Upper Left Corner 00FH Double Line Upper Right Corner 010H Double Line Lower Left Corner 011H Double Line Lower Right Corner 012H Double Line Cross 013H Double Line Junction Left 014H Double Line Junction Right 015H Double Line Junction Top 016H Double Line Junction Bottom 017H Communications Error Character 018H Up Arrow 019H Down Arrow 01AH Right Arrow 01BH Left Arrow 01CH Solid Block 01DH Solid Block, Lower Half 01EH Solid Block, Upper Half 01FH Solid Middle Block 087H Single To Double Upper Left Corner 088H Single To Double Upper Right Corner 089H Single To Double Lower Left Corner 08AH Single To Double Lower Right Corner 08BH Single To Double Cross 08CH Single To Double Junction Left 08DH Single To Double Junction Right 08EH Single To Double Junction Top 08FH Single To Double Junction Bottom 093H Solid Block, Left Half 094H Solid Block, Right Half 095H Greater Than Or Equal To 096H Less Than Or Equal To 097H Double To Single Upper Left Corner 098H Double To Single Upper Right Corner 099H Double To Single Lower Left Corner 09AH Double To Single Lower Right Corner 09BH Double To Single Cross 09CH Double To Single Junction Left 09DH Double To Single Junction Right 09EH Double To Single Junction Top 09FH Double To Single Junction Bottom ***** V. Script File Changes and Additions --------------------------------- 1. Please make the following additions to the DIAL() function on pages SF.22 and SF.23: DIAL (arg1,arg2,arg3,arg4) Function: Establish a communications connection Syntax: > DIAL (handshake_trans,phone_num1,telnet_id,phone_num2) where: PHONE_NUM2 is the second telephone number (or equivalent). For example, the IBM ACS connection lets you dial by specifying the CBX Datagroup and the Account ID. The DIAL() function might resemble: > DIAL (,CBXData_Group,,Accnt_ID) This example does not specify a handshake transmission or a telephone network profile name. 2. Please make the following corrections to the description of the Not (!) operator on page SF.9: A. Under the Operators heading, change: ! Arithmetic Not to: ! Logical Not B. Under the Unary Arithmetic Operators heading, change the description to read: ! invokes the NOT function, causing a boolean True/False evaluation of the expression following the not operator (!). A non-zero result is evaluated as False; a zero result is evaluated as True. For example, IF !EXIST (filename) will perform a set of instructions if the file is not found. 3. Add New EXIT Directive A. On page SF.15, please add the following description after EXIST(): EXIT Terminate the current script file and the current runtime session. B. On page SF.26, before FINDLINE(), please add the following: EXIT Function: Terminate the current script file and the current runtime session. Syntax: > EXIT This is similar to the END directive, except that EXIT also terminates the current runtime session. 4. Please make the following corrections to the HOST() function on page SF.31: Change the descriptions of IDLETIME and MAXTIME to indicate that their values are specified in minutes. 5. Please make the following correction to the READLINE() function on page SF.43: "The returned TXT will have a length of 1 and will contain a control-Z (26 decimal) character if the internal file pointer is at End-of-File." You can copy, profile and run the following script to demonstrate the READLINE() function: > windowpos (0,0) > windowtitle ('ReadLine Test - ' + sessionname) > windowsize (24,80) > windowprms (off,200,201) > watch (off,on,3) > windowshow () > delete ('\openold.000') > copy ('\config.sys','\openold.000',replace) > openold ('\openold.000',handle) > read: > text = readline (handle) > if ((getlength (text) == 1) && (chrtoval (text) == 26)) > message ('Press any key to terminate script') > timeout = 0 > watch (on) > wait () > close (handle) > delete ('\openold.000') > end > endif > message (text) > goto read 6. Add New RETRIES System Variable On page SF.12, please add the following description after PARITY: RETRIES Specify the maximum retry count for error conditions using all file transfer protocols except Character protocol. RETRIES defaults to 3. Possible error conditions include timeouts, block check errors, or any other error condition such as an inappropriate reply to a message. The maximum retry count is specified as an argument, such as > RETRIES 5. A value from 0 through 255 may be entered (although a value of 0 is equivalent to a value of 1). If an error condition occurs during a file transfer operation, and the RETRIES count is exhausted, the message Line Failure will be displayed. ***** VI. Int14 Vendor-Specific Information --------------------------------- A. Special instructions for use under Novell's LAN Workplace for DOS: At the Admittance Data dialog, for the Activation Command string, type the following command line: TSU_SOFT.BAT O DESTINATION 1 where: TSU_SOFT.BAT is a required batch file which was created when the Int14 driver was installed. O is used to Open the connection DESTINATION is the desired hostname or IP address 1 is the port number which will be used. This must match the connection path port number selected. At the Admittance Data dialog, for the Deactivation Command string, type the following command line: TSU_SOFT.BAT C 1 where: TSU_SOFT.BAT is a required batch file which was created when the Int14 driver was installed. C is used to Close the connection. 1 is the port number which needs to match the port specified during the activation process (above). ***** VII. Softrans File Transfer Protocol Source Code ------------------------------------------- Softrans, a file transfer protocol developed by Softronics, Inc., was designed to provide reliable file transmission over a wide variety of asynchronous communications connections, including switched packet networks and front end communications processors. Full binary file transparency automatically is provided by the protocol with no requirement for an 8-bit wide data path; standard 7-bit ASCII characters only are used within a data buffer. In addition, no control characters (00 hex thru 1F hex) occur within any Softrans block; the only control character used is carriage return (0D hex) which is the End of Message (EOM) character. The Fortran 77 source code is included in self-extracting archives on Disk 4 and can be uploaded to your host system and compiled with the appropriate Fortran compiler. The current files are: UNIX_V.EXE Source for Unix systems VAX_VMS.EXE Source for VAX systems DG.EXE Source for Data General systems To extract the source and document files, just type the name of the file and press Enter. ****** VIII. Zmodem File Transfer Protocol ----------------------------- The Zmodem protocol has been added to Softerm. Please add the following information: Page PX.15 (Profiles: File Transfer) ------------------------------------ Zmodem Protocol Parameters Retries Specify the maximum retry count for error conditions. Possible error conditions include timeouts and block check errors. If an error condition occurs during a file transfer operation and the Retries count is exhausted, a Line Failure message will be displayed on your screen. This parameter accepts values from 0 to 255. Transmit Packet Size This parameter determines the number of bytes contained by each packet of data. Set it to the size supported by the host (if you know what it is) or to Auto. If set to Auto, the packet size is determined by the speed of the connection. The faster the speed, the larger will be the packet size. Page B.12 (Appendix B: File Transfer Protocols) ----------------------------------------------- Zmodem Protocol Note: Zmodem was developed for the public domain by Omen Technology under a Telenet contract. The Zmodem protocol descriptions and the Unix rz/sz program source code are public domain. No licensing, trademark, or copyright restrictions apply to the use of the protocol, the Unix rz/sz source code and the Zmodem name. The Zmodem file transfer protocol provides reliable file transfers with complete end-to-end data integrity between application programs. Zmodem uses either a 16-bit or a 32-bit Cyclical Redundancy Check to detect errors. Zmodem accommodates network and timesharing system delays by continuously transmitting data unless the receiver interrupts the sender to request retransmission of garbled data. Softerm's implementation of Zmodem supports all functions except fallback to Ymodem transfer. File Transfer Initiation When the Zmodem receive program starts, it immediately sends an initiation header to start Zmodem file transfers, or a challenge header to verify the sending program. The sender may send an optional intitialization frame to define the receiving program's Attention sequence, or to specify complete control character escaping. The sender sends a header with Zmodem Conversion, Management, and Transport options followed by a data subpacket containing the file name, file length, modification date, and other information identical to that used by Ymodem Batch. The Zmodem Header The header contains a "frame type", four bytes of supervisory information, and its own CRC. Data frames consist of a header followed by 1 or more data subpackets. In the absence of transmission errors, an entire file can be sent in one data frame. Frame File Information Zmodem sends the same file information with the ZFILE frame data that Ymodem Batch sends in its block 0. Pathname The path name (conventionally, the file name) is sent as a null terminated ASCII string. Length The file length and each of the succeeding fields are optional. The length field is stored as an ASCII-coded octal string counting the number of data bytes in the file. The Zmodem receiver uses the file length as an estimate only. It may be used to display an estimate of the transmission time, and may be compared with the amount of free disk space. The actual length of the received file is determined by the data transfer. A file may grow after transmission commences, and all the data will be sent. Modification Date The modification date is 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 and should be left as the date the file is received. File Mode Unless the file originated from a Unix system, the file mode is set to 0. The receiver examines the file name, length, and date information provided by the sender in the context of the specified transfer options, the current state of its file system(s), and local security requirements. If the receiver has a file with the same name and length, it may respond with a CRC header, which requires the sender to perform a 32-bit CRC on the file and transmit the complement of the CRC in a header. The receiver uses this information to determine whether to accept the file or skip it. Error Recovery Normally the receiver specifies the data transfer to start at the beginning of the file, but may start the transfer further down in the file. This allows a file transfer interrupted by a loss of carrier or system crash to be completed on the next connection without requiring the entire file to be retransmitted. If downloading a file from a timesharing system that becomes sluggish, the transfer can be interrupted and resumed later with no loss of data. Normal Session Ending When the sender receives the acknowledging header, it sends two characters, "OO" (Over and Out) and exits to the operating system or application that invoked it. The receiver waits briefly for the "O" characters, then exits whether they were received or not. Session Cancel Sequence If the receiver is receiving data in streaming mode, the Attention sequence is executed to interrupt data transmission before the Cancel sequence is sent. The Cancel sequence consists of eight CAN characters and ten backspace characters. Zmodem only requires five Cancel characters, the other three are "insurance". The trailing backspace characters attempt to erase the effects of the CAN characters if they are received by a command interpreter. For complete information about the Zmodem protocol, please contact: Chuck Forsberg Omen Technology Inc. 17505-V Sauvie Island Road Portland, Oregon 97231 Phone: 503-621-3406 Modem: 503-621-3746