KERMIT USER GUIDE Sixth Edition, Revision 2 Frank da Cruz, editor

KERMIT USER GUIDE Sixth Edition, Revision 2 Frank da Cruz, editor

KERMIT USER GUIDE

Sixth Edition, Revision 2

Frank da Cruz, editor

Columbia University Center for Computing Activities

New York, New York 10027

May 26, 1986

Copyright (C) 1981,1986

Trustees of Columbia University in the City of New York

Permission is granted to any individual or institution to use, copy,

or redistribute this document so long as it is not sold for profit, and

provided this copyright notice is retained.

Kermit User Guide

Page i

Table of Contents

How To Get Kermit

4

Organization of This Manual

5

1. Introduction

6

1.1. Why Kermit?

6

1.2. How Kermit Works

7

2. How to Use Kermit

9

2.1. Transferring a File

10

2.2. Basic Kermit Commands

10

2.3. Real Examples

11

2.3.1. PC to Host

12

2.3.2. Host to Host

13

2.3.3. Micro to Micro

15

2.4. Another Way -- The Kermit Server

16

3. When Things Go Wrong

19

3.1. Basic Connection Problems

19

3.2. Terminal Connection Works But The Transfer Won't Start

19

3.3. Special Characters

21

3.4. 3270 Protocol Emulators

21

3.5. The Transfer Starts But Then Gets Stuck

21

3.5.1. The Micro is Hung

22

3.5.2. The Connection is Broken

22

3.5.3. The Disk is Full

22

3.5.4. Message Interference

23

3.5.5. Transmission Delays

23

3.5.6. Noise Corruption

23

3.5.7. Host Errors

23

3.6. File is Garbage

23

3.7. Junk after End of File

24

4. Kermit Commands

25

4.1. Remote and Local Operation

25

4.2. The Command Dialog

25

4.3. Notation

27

4.4. Summary of Kermit Commands

28

4.5. The SEND Command

29

4.6. The RECEIVE Command

30

4.7. GET

31

4.8. SERVER

32

4.9. BYE

32

4.10. FINISH

32

4.11. REMOTE

32

Kermit User Guide

Page ii

4.12. LOCAL

33

4.13. CONNECT

34

4.14. HELP

35

4.15. TAKE

35

4.16. EXIT, QUIT

35

4.17. The SET Command

35

4.18. DEFINE

42

4.19. SHOW

43

4.20. STATISTICS

43

4.21. LOG

43

4.22. TRANSMIT

44

4.23. INPUT

44

4.24. OUTPUT

44

4.25. PAUSE

44

4.26. SCRIPT

44

5. Kermit Implementations

45

6. DECSYSTEM-20 KERMIT

46

6.1. The DEC-20 File System

46

6.2. Program Operation

51

6.3. Remote and Local Operation

52

6.4. Conditioning Your Job for Kermit

52

6.5. Kermit-20 Commands

53

6.5.1. Commands for File Transfer

54

6.5.2. Server Operation

58

6.5.3. Commands for Local File Management

59

6.5.4. The CONNECT Command

60

6.5.5. The SET, SHOW, and DEFINE Commands

61

6.5.6. Program Management Commands

67

6.6. Login Scripts: The INPUT, OUTPUT, CLEAR, and PAUSE Commands

69

6.7. Raw Download and Upload

76

6.8. Kermit-20 Examples

79

6.9. Installation of Kermit-20

81

7. VAX/VMS KERMIT

83

7.1. The VAX/VMS File System

84

7.2. Program Operation

87

7.3. Conditioning Your Job for Kermit

88

7.4. Kermit-32 Commands

89

7.4.1. Commands for File Transfer

89

7.4.2. Server Operation

92

7.4.3. Commands for Local File Management

94

7.4.4. The CONNECT Command

95

7.4.5. The SET and SHOW Commands

96

7.4.6. Program Management Commands

100

7.5. Raw Download

101

7.6. Installation of Kermit-32

102

Kermit User Guide

Page iii

8. IBM VM/CMS KERMIT

106

8.1. The VM/CMS File System

107

8.1.1. File Specifications

107

8.1.2. File Formats

108

8.2. Program Operation

108

8.3. Kermit-CMS Commands

110

8.4. Before Connecting to the Mainframe

115

8.5. How to build an executable version of Kermit-CMS

116

8.6. What's New

116

8.7. What's Missing

117

9. UNIX KERMIT

118

9.1. The Unix File System

119

9.2. File Transfer

119

9.3. Command Line Operation

120

9.4. Interactive Operation

126

9.5. UUCP Lock Files

144

9.6. C-Kermit under Berkeley or System III/V Unix:

145

9.7. C-Kermit on the DEC Pro-3xx with Pro/Venix Version 1

145

9.8. C-Kermit under VAX/VMS

146

9.9. C-Kermit on the Macintosh

146

9.10. C-Kermit Restrictions and Known Bugs

146

9.11. How to Build C-Kermit for a Unix System

148

9.12. Adapting C-Kermit to Other Systems

148

10. MACINTOSH KERMIT

153

10.1. The Macintosh File System

154

10.2. File Transfer

154

10.3. Remote Commands

155

10.4. Settings

156

10.5. Terminal Emulation

156

10.6. Installation

158

10.7. CKMKEY - Macintosh Kermit's Keyboard Configurator

158

10.7.1. What is CKMKEY?

158

10.7.2. Modifier vs Normal Keys

159

10.7.3. Key Maps

159

10.7.4. What's in CKMKEY's Keymaps

160

10.7.5. Menus

160

10.7.6. MENU: Set

160

10.7.6.1. DIALOG: Set Modifer Keys

160

10.7.6.2. DIALOG: Set Function Definitions

163

10.7.6.3. DIALOG: Set Keys

163

10.7.7. MENU: File

164

10.7.8. CKMKEY Known Limitations, Restrictions, Bugs

164

10.7.9. Unlocking CAPS LOCK

164

11. MS-DOS KERMIT

167

Kermit User Guide

Page iv

11.1. The MS-DOS File System

168

11.1.1. File Specifications

168

11.1.2. File Formats

170

11.2. Program Invocation

170

11.3. Kermit-MS Commands

174

11.3.1. Commands for Terminal Connection

175

11.3.2. Commands for File Transfer

175

11.3.3. Commands for Controlling Remote Kermit Servers

178

11.3.4. Commands for File Management

179

11.3.5. The SERVER Command

182

11.3.6. The SET Command

183

11.3.7. The SHOW Command

194

11.3.8. Command Macros

194

11.4. Terminal Emulation

195

11.5. Installation of Kermit-MS

199

11.5.1. Try Again To Find A Kermit Disk

200

11.5.2. Bootstrapping From the Communication Line

200

11.6. Compatibility with Older Versions of MS-DOS Kermit

205

11.7. What's Missing

205

11.8. Program Organization

206

11.9. Running Kermit on New Systems

207

11.10. IBM-PC MS Kermit Terminal Emulator Summary

208

11.10.1. Keyboard Layout and Characters Sent

208

11.10.2. Responses To Characters Received By the Terminal Emulator

210

11.10.3. DEC VT102 functions while in VT52 mode

212

11.10.4. Heath-19 functions while in non-ANSI mode

213

12. CP/M-80 KERMIT

215

12.1. Summary of CP/M

215

12.2. Kermit-80 Description

216

12.3. Kermit-80 Flavors

221

12.3.1. Generic Kermit-80

221

12.3.2. CP/M 3 Kermit

222

12.3.3. System-Specific Versions

222

12.4. Installation of Kermit-80

223

12.4.1. Organization of Kermit-80

224

12.4.2. Downloading Kermit-80

225

12.4.3. Assembling Kermit-80 from the sources

230

12.5. Adding Support For A New System

233

12.6. Notes on New Features in Kermit-80 Version 4

234

12.7. Future Work

235

13. CP/M-86 KERMIT

236

13.1. Kermit-86 Commands

237

13.2. Installation:

241

13.3. DEC Rainbow 100 Support

241

13.4. NEC Advanced Personal Computer Support

242

14. APPLE-DOS KERMIT

244

Kermit User Guide

Page v

14.1. The DOS 3.3 File System

244

14.2. Program Operation

246

14.3. Remote and Local Operation

248

14.4. KERMIT-65 Commands

248

14.5. Customizing, Building, and Installing KERMIT-65

255

I. The ASCII Character Set

262

Index i

Kermit User Guide

Page vi

List of Figures

Figure 1-1: A Kermit Packet

7

Figure 1-2: Kermit File Transfer

8

Figure 4-1: Local and Remote Kermits

26

Figure 6-1: DECSYSTEM-20 Word/Byte Organization

49

Figure 6-2: DEC-20 Kermit Local Operation

53

Figure 10-1: Macintosh Kermit Modifier Key Dialog

162

Kermit User Guide

Page vii

List of Tables

Table 11-1: Kermit-MS Screen Scroll Keys

197

Table 11-2: Kermit-MS Terminal Emulation Options

199

Table 12-1: Kermit-80 SET PORT Options

222

Table 12-2: Systems supported by Kermit-80

225

Table 12-3: Terminals known to Kermit-80

233

Preface to the 6th Edition, March 1985

Page 1

Preface to the 6th Edition, March 1985

Kermit is the name of a protocol for transferring files from one computer to another over ordinary asynchronous terminal connections. Kermit programs have been written for many different computers, and in general any two computers that have Kermit programs can exchange sequential files correctly and com- pletely. This manual describes use and installation of Kermit programs. A companion volume, the Kermit Protocol Manual, attempts to specify the protocol sufficiently to allow new Kermit programs to be written.

This manual describes an "ideal" Kermit program, one which has most of the fea- tures specified in the Kermit Protocol Manual, and then describes several real

Kermit programs in detail. Most real Kermit programs fall short of the ideal in some ways; a few may surpass it. The system-dependent portions of this manual may be dated; current information about any particular Kermit program can be found in the accompanying on-line help or documentation files or built-in internal help text distributed with the Kermit programs.

Since the publication of the Fifth Edition of the Kermit User Guide in July

1984, there have been new releases of most of the Kermit implementations described in this manual. The Sixth Edition includes new chapters for all these implementations. In addition, some material has been added to the front sections to describe some new facilities like login scripts, and to reflect new experiences as Kermit spreads to increasingly diverse environments.

Revision 1 of the Sixth Edition (June 1985) includes a new chapter for

Macin- tosh Kermit, and replacement chapters for several other Kermits, including

VAX/VMS, VM/CMS, UNIX, and MS-DOS.

Revision 2 of the Sixth Edition (May 1986) includes new chapters for

MS-DOS

Kermit 2.29, VAX/VMS Kermit 3.2, and Macintosh Kermit 0.8(34), and an improved bootstrapping procedure for CP/M-80 Kermit.

HISTORY AND ACKNOWLEDGEMENTS

The Kermit file transfer protocol was designed at the Columbia University

Cen- ter for Computing Activities (CUCCA) in 1981-82 mainly by Bill

Catchings and

Frank da Cruz. Bill wrote the first two programs, one for the DECSYSTEM-

20 and one for a CP/M-80 microcomputer.

The initial objective was to allow users of our DEC-20 and IBM timesharing sys- tems to archive their files on microcomputer floppy disks. The design owes much to the ANSI and ISO models, and ideas were borrowed from similar projects at Stanford University and the University of Utah. The protocol was designed to accommodate the "sensitive" communications front end of the fullduplex

DEC-20 system as well as the peculiarities of half-duplex IBM mainframe com- munications. The protocol was soon implemented successfully on our

IBM 4341 systems under VM/CMS by Daphne Tzoar of CUCCA.

Meanwhile it was becoming apparent that Kermit was useful for more than just file archiving; IBM PCs were beginning to appear in the offices and depart- ments, and there arose a general need for file transfer among all our systems.

Daphne soon had prepared an IBM PC implementation.

After our initial success with Kermit, we presented it at conferences of user

Preface to the 6th Edition, March 1985

Page 2 groups like DECUS and SHARE, and began to get requests for it from other sites.

Since we had written down a description of the protocol, some sites wrote their own implementations for new computers, or adapted one of our implementations to run on additional systems, and sent back these new versions to us so that we could share them with others. In this way, Kermit has grown to support more than 100 different systems; it has been sent on magnetic tape from

Columbia to thousands of sites in dozens of countries, and has reached hundreds or thousands more through various user groups and networks.

Thanks to the hundreds of individuals and institutions who have contributed to the Kermit storehouse over the years.

The Kermit protocol was named after Kermit the Frog, star of the television series THE MUPPET SHOW; the name Kermit is used by permission of

Henson As- sociates, Inc., New York.

FURTHER READING

- A two-part article describing the Kermit protocol appeared in the

June and July 1984 issues of BYTE Magazine: "Kermit, A File

Transfer

Protocol For Universities", by Frank da Cruz and Bill Catchings.

The

title (chosen by the BYTE editors to fit the theme of the June issue)

is a bit misleading, because there's nothing about Kermit that's par-

ticular to universities.

- The book "Kermit, A File Transfer Protocol," by Frank da Cruz,

Digi-

tal Press, Bedford MA (1986), ISBN 0-932376-88-6, DEC order number

EY-6705E-DP, describes Kermit in detail, from the points of view of

the user, of computer professionals who have to install

Kermit

programs or support their use, and of programmers who wish to write

new Kermit implementations, and also contains tutorials on data com-

munications, file organization, plus a detailed troubleshooting

guide, bootstrapping hints, and many illustrations and tables.

DISCLAIMER

Neither Columbia University, nor the editor, nor the authors of the individual chapters, nor any individual or institution contributing Kermit programs or documentation to the Columbia University Kermit Distribution, acknowledge any liability for any claims arising from use or misuse of Kermit programs or for inaccuracies in the documentation or bugs in the programs. Kermit programs are produced on a voluntary basis and contributed freely for public use in the hope that they will be useful, but without any kind of warranty or guarantee, or any commitment to address or fix problems. In practice, Kermit programs and documentation are contributed in good faith, and will be supported on a best- effort basis, time and other commitments permitting.

Preface to the 6th Edition, March 1985

Page 3

CUSTOMIZING THIS MANUAL

Although the Kermit User Guide was produced at Columbia University, all at- tempts have been made to keep it free of site-specific information.

However, due to the large number of Kermit implementations, descriptions of each one would make the manual unnecessarily thick. Therefore, the manual is sent from

Columbia with specific documentation about a selection of systems.

Some of these descriptions may not be of interest at your site, while others that are may be lacking.

Each site, upon receiving a Kermit tape, may decide which versions of

Kermit are important to it, and include the appropriate documentation in this manual.

This is most conveniently done if your site has the Scribe text formatting sys- tem (from UNILOGIC Ltd in Pittsburgh PA, USA), with which this manual was produced. Scribe runs on a wide variety of systems. There are also

Scribe subsets, such as Perfect Writer and Final Word, that run on various microcom- puters.

The system-specific parts of the Kermit User Guide are included with

"@INCLUDE" statements at the end of the Scribe source file for this manual, whose filename is KUSER.MSS. You may add or delete @INCLUDE statements to suit your needs, and run the result through the text formatter to produce a customized manual.

If you do this, you should include an indication on the title page that the manual has been customized for your site.

Not all system-specific documentation is provided in .MSS (Scribe input) for- mat, since some Kermit contributors do not have Scribe at their sites.

In that case, you will either have to add Scribe formatting commands, or else enclose the whole subfile in @BEGIN(VERBATIM)[email protected](VERBATIM) brackets (and replace

all atsigns (@) in the text with double atsigns (@@)).

If you do not have SCRIBE, you may still use an editor to delete or add sec- tions to the finished documentation file, though the results will not be as satisfactory -- the table of contents, index, and page numbers will not be automatically adjusted.

If you are running a version of Kermit for which adequate documentation has not been provided (after all, this is a distributed, volunteer effort!), please feel free to write some, preferably in Scribe input format, and send it back to

Columbia so that others may benefit from it. Likewise if you produce a new im- plementation of Kermit. If you don't know Scribe, you can use one of the ex- isting chapters as a model.

How To Get Kermit

Page 4

How To Get Kermit

Kermit is available to users of the BITNET network via a Kermit file server at host CUVMA. BITNET users may type ``SMSG RSCS MSG CUVMA KERMSRV

HELP'' for further information. Kermit is also available to users of the

Internet via anonymous FTP from host CU20B, in the area KER:, and to users of

UNIX(tm) sys- tems via UUCP from host "okstate" at the Oklahoma State University

Computer

Science department. And Kermit is distributed regularly by various computer user groups such as DECUS and SHARE. (This information in the paragraph is current as June 1985, but is subject to change.)

The Kermit software is free and available to all. Columbia

University, however, cannot afford to distribute free software on the scale required for

Kermit. Therefore, to defray our costs for media, printing, postage, materials, labor, and computing resources, we must request a moderate distribu- tion fee from sites that request Kermit directly from Columbia.

Other sites are free to redistribute Kermit on their own terms, and are en- couraged to do so, with the following stipulations: Kermit should not be sold for profit; credit should be given where it is due; and new material should be sent back to Columbia University at the address below so that we can maintain a definitive and comprehensive set of Kermit implementations for further dis- tribution.

Please note that although Kermit is free, it is not in the public domain.

The

Kermit manuals, and most Kermit programs, bear copyright notices.

This copyright notice is to protect Columbia University and the various contributors from having their work usurped by others and sold as a product. This is not to say that the Kermit file transfer protocol can never be included as a feature

of a commercial product; the conditions under which this may be done are spelled out in a flyer POLICY ON COMMERCIAL USE AND DISTRIBUTION OF

KERMIT.

To inquire about obtaining the Kermit distribution, write to:

Kermit Distribution

Columbia University Center for Computing Activities

612 West 115th Street

New York, N.Y. 10025

Since new Kermit programs are added -- and old ones improved -- so frequently, sites that use Kermit heavily are encouraged to contact Columbia for updates two or three times a year for news.

-- PLEASE USE KERMIT ONLY FOR PEACEFUL AND HUMANE PURPOSES --

Organization of This Manual

Page 5

Organization of This Manual

Section 2, How to Use Kermit, tells all you need to know to transfer text files in most cases, and shows some specific examples.

If you follow the examples in Section 2 but you can't make a terminal connec- tion or you can't transfer files successfully, consult Section 3, When

Things

Go Wrong.

If you expect to be a heavy user of Kermit, you should read Section 4,

Kermit

Commands, which describes all the features of Kermit in detail. You may find that familiarity with the material in this section will help you get past dif- ficulties that can crop up when you are making new kinds of connections or transferring unusual kinds of files. You will also find descriptions of some advanced file management features that have been omitted from the earlier sec- tions.

Section 5, Kermit Implementations, briefly lists the systems for which

Kermit is available as of this writing. The subsequent chapters describe selected particular implementations. You should read the appropriate section for each system with which you are using Kermit; each section describes the file naming conventions and other system features that are important to Kermit users, and lists the Kermit commands for that system mainly in terms of their differences from the "ideal" Kermit described in section 4.

Introduction

Page 6

1. Introduction

There is an ever-increasing need to move information from one computer to another. Information can be exchanged using magnetic media -- tapes or disks

-- or over networks. Networks are expensive, and when your computer is not connected to one (or to the right one), you must find other means to transfer information. In the early days of computing, magnetic media formats were rela- tively standardized, but with the arrival of microcomputers things have changed: most microcomputer users have no access to tapes, and disk formats are incompatible between most microcomputer makes and models. Even when disk for- mats agree, the disk must be physically moved from one system to the other in order for information to be exchanged -- the effort and delay can be sig- nificant if the systems are widely separated.

The telecommunication line provides an alternative to networks and magnetic media. Asynchronous telecommunication is the method used by most terminals to connect to most computers. When dedicated "hardwired" connections, such as those found between a timesharing computer and its local terminals, are not available, computer users can create their own connections with a telephone and a modem.

Most computers come equipped with asynchronous telecommunications interfaces, or "serial ports", which allow them to act as, or communicate with, terminals.

The question is how to use the serial port to exchange data.

Fortunately, the standards for connecting terminals to computers are almost universally fol- lowed: connector configuration (DB-25 or DB-9), transmission signals

(EIA

RS-232), a commonly accepted set of transmission speeds (baud rates), and a convention for encoding characters in storage and during transmission

(ASCII).

These standards provide the physical medium and the data format, but they do not specify a process for exchanging data.

1.1. Why Kermit?

When data is transmitted from one computer to another; the receiving computer has to be instructed to take in the data and put it somewhere, and it also needs a way of ensuring that the data has been received correctly and com- pletely in spite of several factors that will tend to interfere with this process:

1. Noise -- It is rarely safe to assume that there will be no electri-

cal interference on a line; any long or switched data communication

line will have occasional interference, or noise, which typically

results in garbled or extra characters. Noise corrupts data, per-

haps in subtle ways that might not be noticed until it's too late.

2. Timing -- Data must not come in faster than the receiving machine

can handle it. Although line speeds at the two ends of the connec-

tion must match before communication can take place, the receiving

machine might not be able to process a steady stream of input at

that speed. Its central processor may be too slow or too heavily

loaded, or its buffers too full or too small. The typical symptom

of a timing problem is lost data; most operating systems will simply

discard incoming data they are not prepared to receive.

3. Line Outages -- A line may stop working for short periods because of

Introduction

Page 7

a faulty connector, loss of power, or similar reason. On dialup or

switched connections, such intermittent failures may cause carrier

to drop and the connection to be closed, but for any connection in

which the carrier signal is not used, the symptom will be lost data.

To prevent corruption of data and to synchronize communication, cooperating computers can send special messages to one another along with the data.

Inter- mingling of control information with data together requires a set of rules for distinguishing messages from data, and specifying what the messages are and the actions associated with each message. Such a set of rules is called a protocol.

Kermit is a file transfer protocol. It is specifically designed for transfer of sequential files over ordinary serial telecommunication lines.

Kermit is not necessarily better than other terminal-oriented file transfer protocols but it is free, it is well documented, and it has been implemented compatibly on a wide variety of microcomputers and mainframes.

1.2. How Kermit Works

Kermit transfers data by encapsulating it in packets of control information.

This information includes a synchronization marker, a packet sequence number to allow detection of lost packets, a length indicator, and a "block check" to al- low verification of the data, as shown in Figure 1-1.

+------+------+------+------+--------- - - - -+-------+

| MARK | LEN | SEQ | TYPE | DATA | CHECK |

+------+------+------+------+--------- - - - -+-------+

Figure 1-1: A Kermit Packet

The MARK (usually an ASCII Control-A character) appears at the beginning of the

packet. The next character is a length field (LEN), specifying how long the rest of the packet is. The sequence number (SEQ) is used to detect lost or duplicated packets; retransmission is requested for lost packets and duplicate packets are discarded. The TYPE field specifies whether the packet contains data or control information. The CHECK field contains a quantity obtained by combining all the other characters in the packet together in one of several ways; the sender computes this value and sends it. The packet receiver also computes the value and checks it against the value sent; if they agree, the packet is accepted; if they disagree, then the packet has been corrupted and retransmission is requested. The DATA field contains up to 90 characters of data. All fields except the mark are encoded as printable ASCII characters, to prevent host or network interference. Figure 1-2 shows how a typical file transfer proceeds. Figure 1-2 does not show how Kermit recovers from errors.

Very briefly, here's how it works:

- If a packet is corrupted in transit by noise or loss of characters,

the block check will be wrong. A file receiver will NAK

("negatively

acknowledge") a corrupted packet, which causes the sender to

retransmit the same packet. A file sender only receives ACKs and

NAKs from the receiver; a corrupted ACK or NAK from the receiver is

treated exactly the same as a NAK.

- If the file sender does not receive an ACK within the prescribed

Introduction

Page 8

Sender Receiver

Send-Init -------------> Sender and Receiver exchange greetings

<-------------------- ACK

File-Header -----------> Sender sends first file name to

Receiver

<-------------------- ACK Receiver acknowledges

File-Data -------------> Sender sends first file data packet

<-------------------- ACK

File-Data -------------> Sender sends second file data packet

<-------------------- ACK

File-Data --xx~~~p'''--> Third data packet is corrupted by noise

<-------------------- NAK and Receiver negatively acknowledges it

File-Data -------------> Sender retransmits third packet

<-------------------- ACK

File-Data packets are sent and acknowledged until the whole file is sent

End-Of-File -----------> Sender indicates first file is complete

<-------------------- ACK

File-Header -----------> Name second of file

<-------------------- ACK

File-Data -------------> First data packet for second file

<-------------------- ACK

File-Data packets are sent and ack'd until the whole file is sent

End-Of-File -----------> Sender indicates second file is complete

<-------------------- ACK

End-Of-Transaction ----> Sender indicates no more files to come

<------------------- ACK

Figure 1-2: Kermit File Transfer

timeout interval, it retransmits the same packet. If the file

receiver does not receive an expected packet within the timeout in-

terval, it sends a NAK for the expected packet.

Several encoding, compression, and block check options are provided.

Very few assumptions are made about the capabilities of either computer, so the

Kermit protocol can work between many different kinds of systems. The protocol is described in detail in the Kermit Protocol Manual, and in the BYTE

Magazine ar- ticle on Kermit, published in the June and July 1984 issues.

How to Use Kermit

Page 9

2. How to Use Kermit

Kermit embodies a set of rules for transferring files reliably between two com- puters. In general, one computer is a large system (a host, for instance a timesharing system with many terminals), and the other is a personal computer

(PC). The host believes that the PC is an ordinary terminal. In order for the

Kermit protocol to occur, a Kermit program must be running on each end of the communication line -- one on the host, one on the PC.

Your task is just to get the two Kermits started. You have to use a single keyboard and screen to talk to two different computers, two different programs.

Let's talk about a common case: you are sitting at a personal computer

(PC), which has a serial communication port. The serial port is connected to a host computer using, say, a dialup modem.

Normally, when you use your PC, you are "talking" directly to it; your commands are interpreted directly by the PC's operating system (CP/M, MS-DOS,

UNIX, whatever), or by some program that runs on the PC (an editor, a text formatter, space invaders...). The version of Kermit on your PC is a program like any other, but it has a special ability to either interpret your commands directly, like other programs, or to pass everything you type through to the other, remote computer. When you tell Kermit to CONNECT, it sends every character you type out the serial port, and it puts every character that comes in the serial port onto the screen. This is called virtual terminal service -- one computer acts "virtually" as though it were a terminal on another. You are now

"talking" to the remote computer, and the PC is "vitually" ignoring you.

Kermit, like most interactive programs, has a prompt. The prompt is a string of characters it types on the left margin to indicate that it is ready for you

to type a command. Kermit's prompt is normally "Kermit-xx>". The xx iden- tifies the implementation of Kermit; the Kermit that runs on the

DEC-20 is called "Kermit-20" and its prompt is "Kermit-20>"; the Kermit that runs on Z80 and 8080-based microcomputers is called "Kermit-80" and its prompt is

"Kermit-80>"; the Kermit that runs under CP/M-86 is "Kermit-86, and so forth.

If you become confused about which Kermit you are talking to, the prompt should provide a clue. In addition, most Kermits print an informative message like

[Connecting to remote host, type CTRL-]C to return] when you CONNECT, and type another message like

[Connection closed, back at PC] when you return.

Having "connected" to the host, there must be a way for you to "get back" to the PC. This is accomplished by an escape sequence. As Kermit passes your characters through to the host, it checks each one to see if it's a special predefined escape character. When the PC sees this character, it stops ignor- ing you -- you are once again "talking" to the PC, not the host. The escape character is normally chosen to be one that you will not need to type while talking to the host, and one that is hard to type by accident -- it's usually a control character, such as Control-], which is entered by holding down the key marked CTRL or CONTROL and typing the indicated character (in this case, a right bracket "]"). The CTRL key works just like a SHIFT key. Control charac- ters are written either as CTRL-A or ^A, where A is the character to be typed

How to Use Kermit

Page 10 while holding down CTRL.

2.1. Transferring a File

From system command level on your PC, first run the Kermit program.

Then tell

Kermit to CONNECT you to the host. Now you're talking to the remote host

-- at this point you must log in, and then run Kermit on the host.

Now you have a Kermit on each end of the wire. The next step is to tell each

Kermit what to do. Suppose you want to transfer a file from the host to the

PC; you would first tell the host Kermit to SEND the file, then

"escape" back to the PC Kermit and tell it to RECEIVE the file. The transfer begins -

- you can sit back and watch, or go make yourself a sandwich. The PC

Kermit will produce a running display on your screen as the transfer proceeds, and will notify you when it is complete.

The desired file is now on your PC's disk. The Kermit protocol has ensured that the file arrived correctly and completely. Now you must clean up after yourself: CONNECT back to the host, exit from Kermit on the host, log out from the host, "escape" back to PC Kermit and exit from it. Now you can do whatever you had planned for your file -- edit it, print it on your PC printer, etc.

Transferring a file in the other direction works the same way, but with the

SEND and RECEIVE commands exchanged.

The Kermit protocol, and most Kermit programs, allow you to send a file reli- ably from the host to the PC, from the PC to the host, from host to host, or PC to PC, usually without any special regard for the nature of the particular machines involved. Most implementations also allow files to be sent in groups, with a single command, such as "send *.*" The scenario for each of these is the

same as above -- only the details of how to establish the actual connection differ.

Kermit works best with "printable" files -- files composed only of letters, digits, punctuation marks, carriage returns, tabs, and so forth -- since these can be represented on almost any kind of computer. Kermit is also able to transfer "binary" files -- files such as executable programs -- composed of ar- bitrary bit patterns, but binary files normally are meaningful only to the kind of computer on which they are generated. Nevertheless, Kermit can usually move such files from system A to system B (where they are not much use) and back to system A in their original condition, although in most cases special measures must be taken to accomplish this.

Let's look at some more concrete examples. First you need to know what the basic Kermit commands are.

2.2. Basic Kermit Commands

These are generic descriptions of the most basic Kermit commands.

Detailed descriptions will come later. In these descriptions, local refers to the sys- tem that you are using directly, remote refers to the system to which you are

CONNECTed via Kermit. Commands may take one or more operands on the same line, and are terminated by a carriage return.

SEND filespec

How to Use Kermit

Page 11

Send the file or file group specified by filespec from this Kermit to the

other. The name of each file is passed to the other Kermit in a special

control packet, so it can be stored there with the same name. A file group

is usually specified by including "wildcard" characters like "*" in the

file specification. Examples:

send foo.txt

send *.for

Some implementations of Kermit may not support transfer of file groups;

these versions would require a separate SEND command for each file to be

transferred.

RECEIVE

Receive a file or file group from the other Kermit. If an incoming file

name is not legal, then attempt to transform it to a similar legal name.

Options are be provided for handling filename collisions.

CONNECT

Make a "virtual terminal" connection to the remote system. To

"escape"

from a virtual terminal connection, type Kermit's escape character

(e.g.

CTRL-], control-rightbracket), followed by the letter "C" for

"Close

Connection".

SET Establish various nonstandard settings, such as CONNECT escape character,

file characteristics, communication line number, speed, parity, or flow

control. All of these are explained later.

SHOW

Display the values of SET options.

HELP

Type a summary of Kermit commands and what they do.

EXIT

Exit from Kermit back to the host operating system.

? Typed almost anywhere within a Kermit command: List the commands, options,

or operands that are possible at this point. This command may or may not

require a carriage return, depending on the host operating system.

2.3. Real Examples

Kermit can be used in several ways: from a PC that is connected to a larger host computer; from a host computer which is connected to another host; from one PC to another.

How to Use Kermit

Page 12

2.3.1. PC to Host

In this example, the user is sitting at an IBM Personal Computer (PC), which is connected through its serial port to a DECSYSTEM-20 host computer. The

IBM PC is local, the DEC-20 is remote. This example will also apply almost literally to any other microcomputer implementation of Kermit.

You have started up your PC and have the Kermit program on your disk.

Begin by running Kermit on the PC. Use Kermit's CONNECT command to become a terminal to the DEC-20. In fact, the PC emulates the popular Heath-19 (or VT52) terminal, so it is desirable to tell the DEC-20 that your terminal is one of these.

Login on the DEC-20 and run Kermit there. Here is an example of this procedure with commands you type underlined; the material lined up on the right is com- mentary, not system typeout or part of a command:

A>Kermit Run Kermit on the PC.

Kermit-MS V2.27

Kermit-MS> This is the Kermit prompt for the PC.

Kermit-MS>connect Connect to the DEC-20.

[Connecting to host, type Control-] to return to PC]

You are now connected to the DEC-20.

CU20B The system prints its herald.

@terminal heath-19 Set your terminal type (optional.)

@login my-id password Login using normal login method.

(Various greeting or notice messages are displayed.)

@Kermit Run Kermit on the DEC-20.

TOPS-20 Kermit version 4.2(251)

Kermit-20> This is Kermit-20's prompt.

You are now ready to transfer files between the two machines.

The following example illustrates how to send files from the DEC-20 to the PC.

Note the use of the "*" wildcard character to denote a file group.

Kermit-20>send *.for Send all my FORTRAN files.

^]c Now return back to the PC by

typing the escape sequence, in this case

^]C (Control-] followed by "C")

[Back at PC.]

Kermit-MS>receive Tell the PC that files are coming.

If you take more than about 5 seconds to get back to Kermit-MS and issue the

RECEIVE command, the first packets from Kermit-20 may arrive prematurely and appear on your screen, but no harm will be done because the packet will be retransmitted by the DEC-20 until the PC acknowledges it.

Once the connection is established, the PC will show you what is happening -- it first clears the screen and waits for incoming packets; as packets arrive, the current file name and packet number will be continuously displayed on the screen. When the PC's "Kermit-MS>" prompt returns to your screen (with an ac- companying beep to catch your attention) the transfer is done.

Notice the

How to Use Kermit

Page 13 screen display; the status should be indicated as "complete". If not, an error has occurred and an appropriate message should be displayed to tell you why.

After you're finished transferring files, you must CONNECT back to the

DEC-20 host, EXIT from Kermit there, logout, and "escape back" to the PC as you did previously:

Kermit-MS>connect Get back to the DEC-20.

[Connecting to host. Type CTRL-]C to return to PC.]

Kermit-20> Here we are.

Kermit-20>exit Get out of Kermit-20.

@logout Logout from the DEC-20.

Logged out Job 55, User MY-ID, Account MY-ACCOUNT, TTY 146,

at 24-Oct-84 15:18:56, Used 0:00:17 in 0:21:55

^]c Now "escape" back to the PC,

[Back at PC.]

Kermit-MS>exit and exit from the PC's Kermit.

The files you transferred should now be on your PC disk.

To send files from the PC to the DEC-20, follow a similar procedure.

First follow the instructions in the previous section to log in to the DEC-20 through the PC. Then in response to the host Kermit's "Kermit-20>" prompt you type

RECEIVE rather than SEND. Now escape back to the PC and use the SEND command to send the local PC files to DEC-20 host. The PC will show you the progress of the transmission on its screen.

When the "Kermit-MS>" prompt indicates that the transmission is complete you should follow the procedure shown above to logout from the DEC-20 host, except that you may first wish to confirm that the files have been stored correctly in your directory on the DEC-20.

2.3.2. Host to Host

This section describes use of Kermit between two host computers. A

"host" is considered to be a large or multi-user system, whose distinguishing charac- teristic is that it has multiple terminals. Use of Kermit for hostto-host file transfers differs from the PC-to-host case in that the line your terminal is connected to is not the same as the line over which the data is being trans- ferred, and that some special SET commands may have to be issued to allow one

Kermit to conform to unusual requirements of the other host.

In this example, you are already logged in to a DEC-20, and you use an autodialer to connect to an IBM 370-series system running VM/CMS through

DEC-20

TTY port 12. The autodialer, in this example, is invoked from program called

DIAL (idealized here, for simplicity), to which you merely supply the phone number.

@dial 765-4321/baud:1200

Dialing your number, please hold...

Your party waiting is on TTY12:

@

How to Use Kermit

Page 14

Other methods exist for connecting two hosts with a serial line.

Dedicated hookups can be made simply by running an EIA cable between TTY ports on the two

1 systems. For connecting to remote systems when no autodialer is available, a

2 manual dialup connection is also possible, but tricky. If you have a microcomputer that supports Kermit, you may find it easier to first transfer from host A to the micro, then from the micro to host B.

The following procedure would be the same in any case, once a connection is made.

@

@Kermit Run Kermit on the DEC-20.

Kermit-20>set ibm Turn on handshaking, parity, local echo.

Kermit-20>set line (to tty) 12 ! Indicate the line we'll use.

Kermit-20>connect And connect to it.

[Kermit-20: Connecting over TTY12:, type <CTRL-Y>C to return.]

VM/370 ONLINE The IBM system prints its herald.

.login myuserid mypassword Login to IBM system.

LOGON AT 20:49:21 EST THURSDAY 01/20/84

CUVMB SP/CMS PUT 8210 01/19/84

.

.Kermit

Kermit-CMS>.send profile exec ! Send a file.

^\c Kermit-20's escape sequence typed here.

[Kermit-20: Connection Closed. Back at DEC-20.]

Kermit-20>receive Tell Kermit-20 to RECEIVE.

The transfer takes place now; Kermit-20 will print the names of incoming files, followed by dots or percents to indicate the packet traffic (a dot for every 5 packets successfully transferred, a percent for every timeout or retransmission). It is complete when when you see "[OK]", a beep is sounded, and the Kermit-20 prompt next appears. At that point we connect back to the remote IBM system, exit from the remote Kermit and log out.

.

PROFILE.EXEC.1 ..%%.[OK]

_______________

1

Such a connection, by the way, usually requires the receive and transmit leads (pins 2 and 3) be swapped in one of the RS-232 connectors; this is called a "null modem" cable. Such cables may also require certain other modem signals such as DTR held high.

2

Here's one way: log in on port x on your system, and assign another port, y, to which you have physical access. Unplug the terminal from port y, and connect the terminal to a dialup modem. Dial up the remote computer and log in on it. Now, using a null modem cable, connect the modem directly to port y.

Go back to your terminal on port x, run Kermit from it, and CONNECT to port y.

How to Use Kermit

Page 15

Kermit-20>connect Get back to IBM and clean up.

[Kermit-20: Connecting over TTY12:, type <CTRL-Y>C to return.]

Kermit-CMS>.

Kermit-CMS>.exit

R;

.

SP/CMS

.logout

CONNECT= 00:03:01 VIRTCPU= 000:00.12 TOTCPU= 000:00.60

LOGOFF AT 20:52:24 EST THURSDAY 01/20/84

^\c Type Kermit-20's escape sequence

[Kermit-20: Connection Closed. Back at DEC-20.]

Kermit-20>exit All done with Kermit.

That's the whole procedure. The file is in your DEC-20 directory, completely readable, as PROFILE.EXEC -- note that Kermit-CMS translated from the IBM

EBCDIC character encoding into standard ASCII, and converted the space between the file name and file type to a dot.

To send a file from the local host to the remote host, we would merely have reversed the SEND and RECEIVE commands in the example above.

2.3.3. Micro to Micro

Kermit also works between personal computers (microcomputers, workstations).

The difference here is that commands are typed on two keyboards, rather than a single one. This is because a personal computer normally only accepts commands from its own keyboard. If one PC Kermit CONNECTs to another, there will nor- mally be no program on the other side to listen.

Making the physical connection between two micros is tricky. If the two units

3 are in close proximity , you can connect their serial ports with a null modem cable. However, different micros have different requirements -- some may want

a male connector on their serial port, others a female; many require that cer-

4 tain of the RS-232 signals be held high or low . In any case, you must also make sure the port speeds are the same at both ends.

_______________

3

Why would you want to run Kermit between two PCs that are next to each other? One good reason is that if they are different models, their floppy disks are probably incompatible.

4

By wiring certain of the pins in the connector together; for instance, some micros want DTR (Data Terminal Ready, pin 20) to be held high, and this might be accomplished by connecting it to CTS (Clear To Send, pin 5).

See EIA

Standard RS-232-C, and the appropriate manuals for your micro.

How to Use Kermit

Page 16

Connections at longer distances can be made via dialup, providing the required modems are available (one side needs autoanswer capability), or using any kind of dedicated or switched circuit that may be available -- PBX, port contention unit, almost anything you can plug an EIA connector into.

In this example, a DEC VT180 "Robin" CP/M microcomputer is connected to a In- tertec "SuperBrain" CP/M micro, using a female-to-male null modem cable.

Get- ting the cable right is the hard part. The connection can be tested by running

Kermit and issuing the CONNECT command on both ends: typein from each micro should appear on the screen of the other.

Suppose you want to send a file FOO.HEX from the Robin to the

SuperBrain.

Proceed as follows:

1. Run Kermit on the SuperBrain, and give the RECEIVE command:

A>Kermit

Intertec SuperBrain Kermit-80 - V4.05

Kermit-80>receive

2. Run Kermit on the Robin, and give the SEND command for FOO.HEX.

A>Kermit

DEC VT18X Kermit-80 - V4.05

Kermit-80>send foo.hex

Watch the packets fly. When you get the next Kermit-80> prompt, the

transfer is done, and you can EXIT from both Kermits.

The key point is to start the receiving end first -- some microcomputer

Kermits do not include a timeout facility, and if the receiver is not ready to receive when the sender first sends, there will be a protocol deadlock.

2.4. Another Way -- The Kermit Server

So far, we have been describing the bare-bones version of the Kermit protocol.

An optional extension to the protocol includes the concept of a Kermit server.

A Kermit server is a Kermit program that does not interact directly with the user, but only with another Kermit program. You do not type commands to a Ker- mit server, you merely start it at one end of the connection, and then type all further commands at the other end.

Not all implementations of Kermit can be servers, and not all know how to talk to servers -- but most of the major ones can and do. The server is run on the remote computer, which would normally be a large host, such as the DEC-

20. You must still connect to the remote host to log in and start the server, but you no longer have to tell one side to SEND and the other to RECEIVE, nor must you connect back to the remote side to clean up and log out when you're done.

Using the server, you can do as many send and receive operations as you like without ever having to connect back to the remote host. Some servers also provide additional services, such as directory listings, file deletion, or disk usage inquiries.

A Kermit server is just a Kermit program running in a special say.

It acts much like ordinary Kermit does after you give it a RECEIVE command -- it waits

How to Use Kermit

Page 17 for a message from the other Kermit, but in this case the message is a command saying what to do, normally to send or to receive a file or group of files.

After escaping back to the local system, you can give as many SEND and

GET com- mands as you like, and when you're finished transferring files, you can give the BYE command, which sends a message to the remote Kermit server to log it- self out. You don't have to connect back to the remote host and clean up.

However, if you want to connect back to the host, you can use the

FINISH com- mand instead of BYE, to shut down the Kermit server on the remote host without logging it off, allowing you to CONNECT back to your job there.

Here's an example of the use of a Kermit server. The user is sitting at a

CP/M-80 microcomputer and a DEC-20 is the remote host.

A>Kermit Run Kermit on the micro.

Kermit-80 V4.05

Kermit-80> This is the micro Kermit's prompt.

Kermit-80>connect Connect to the DEC-20.

[Connecting to remote host. Type CTRL-]C to return to micro.]

CU20E The DEC-20 prints its herald.

@login my-id password Log in normally.

(The DEC-20 prints various login messages here.)

@Kermit Run Kermit-20 normally

Kermit-20>server Tell it to be a server.

Kermit Server running on DEC-20 host. Please type your escape

sequence to return to your local machine. Shut down the server by

typing the Kermit BYE command on your local machine.

^]c Now escape back to the micro.

[Connection closed, back at micro.]

Kermit-80>get *.pas Get all my DEC-20 Pascal programs.

Kermit-80>send foo.* Send all the "foo" files from my micro.

Kermit-80>exit Exit from Kermit back to CP/M.

A>

(Here you can do some work on the micro, edit files, whatever you like.)

A>Kermit Run Kermit-80 some more.

Kermit-80>send file.pas Send another file.

Kermit-80>bye That's all. Shut down the Kermit server.

A> Back at CP/M automatically.

This is much simpler. Note that once you've started the Kermit Server on the remote end, you can run Kermit as often as you like on the micro without having to go back and forth any more; just make sure to shut the server down when you're done by typing the BYE command.

Here are the basic commands available for talking to servers.

SEND filespec Sends a file or file group from the local host to the remote

host in the normal way.

How to Use Kermit

Page 18

GET filespec Ask the remote host to send a file or file group.

Example:

get *.c

This command is exactly equivalent to typing "send *.c" at the

remote host followed by "receive" on the local host.

Note that

the local Kermit does not attempt to validate the filespec. If

the server cannot parse it, or cannot access the specified

file(s), it will send back an appropriate error message.

REMOTE command [argument]

Ask the server to perform the specified command, and send the

results to your screen. Not all servers are capable of per-

forming REMOTE commands; those that can most commonly provide

REMOTE DIRECTORY, REMOTE DELETE, REMOTE SPACE, and similar file

management services.

BYE Shut down the remote server and exit from Kermit.

This will

cause the job at the remote end to log itself out. You need

not connect back and clean up unless you get an error message

in response to this command (for instance, if your logged-out

disk quota is exceeded on the remote host).

FINISH Shut down the server without having it log itself out, and

don't exit from Kermit. A subsequent CONNECT command will put

you back at your job on the remote host, at system command

level.

Server operation is not limited to mainframes. Some PC Kermit implementations can also act as servers, notably MS-DOS and Unix. For instance, an IBM

PC at the office with an autoanswer modem can be left in server mode at the end of

the day, and then dialed up from home in the evening for file transfer.

When Things Go Wrong

Page 19

3. When Things Go Wrong

Connecting two computers can be a tricky business, and many things can go wrong. Before you can transfer files at all, you must first establish terminal communication. But successful terminal connection does not necessarily mean that file transfer will also work. And even when file transfer seems to be working, things can happen to ruin it.

3.1. Basic Connection Problems

If you have a version of Kermit on your microcomputer, but the CONNECT command doesn't seem to work at all, please:

- Make sure all the required physical connections have been made and

have not wiggled loose. If you are using a modem, make sure the car-

rier light is on.

- If you have more than one connector on your micro, make sure you are

using the right one.

- Make sure that the port is set to the right communication speed, or

baud rate. Some versions of Kermit have a built-in SET BAUD or

SET

SPEED command, others require that you set the baud rate using a sys-

tem command or setup mode before you start the Kermit program.

Some

versions of Kermit have SHOW or STATUS commands that will tell you

what the current baud rate is.

- Make sure that the other communication line parameters, like parity,

bits per character, handshake, and flow control are set correctly.

You may have to consult the appropriate manuals for the systems and equipment in question.

If all settings and connections appear to be correct, and communication still does not take place, the fault may be in your modem. Internal modems

(i.e. those that plug in to a slot inside the microcomputer chassis) are not recom- mended for use with Kermit unless they totally mimic the asynchronous serial port hardware they purport to replace. Many microcomputer Kermit programs are written to control the communication hardware explicitly; internal modems can interfere with that control.

Even external modems can cause trouble -- the "smarter" they are, the more potential danger of disagreement between the modem and the microcomputer about settings of baud rate, character framing, echo, and so forth. Make sure your modem is set up correctly.

3.2. Terminal Connection Works But The Transfer Won't Start

Once you've made a terminal connection to the remote system, you will generally also be able to transfer files. But not always. If Kermit's terminal emula- tion seems to work correctly, but a file transfer will not start at all, then something in the communication path is probably interfering with the packet data.

When Things Go Wrong

Page 20

Kermit normally expects to have full control of the communication port.

However, it is sometimes the case that some communications equipment controls the line between the two computers on either end. In addition to modems, ex- amples include port contention or selection units, multiplexers, local net- works, and wide-area networks. Such equipment can interfere with the

Kermit file transfer protocol in various ways:

PARITY:

A device can impose parity upon the communication line. This means that

the 8th bit of each character is used by the equipment to check for correct

transmission. Use of parity will:

- Cause packet checksums to appear incorrect to the receiver and

foil any attempt at file transfer. In most cases, not even the

first packet will get through.

- Prevent the use of the 8th bit for binary file data.

If terminal connection works but file transfer does not, parity is the most

likely culprit. To overcome this impediment, you should find out what

parity is being used, and inform the Kermits on each side (using the SET

PARITY command) so that they can:

- Compose and interpret the checksums correctly.

- Employ a special encoding to allow 8-bit data to pass through the

7-bit communication channel.

Many packet-switched networks, such as GTE TELENET, require parity to be

set.

ECHOING:

Some communication processors, typically front ends, echo their input.

When this happens, every Kermit packet that is sent to it will bounce right

back, causing no end of confusion. Some Kermit programs have been designed

to ignore echoed packets, but most have not. If you encounter this

problem, there are several possible solutions:

- Disable the front end echoing by typing some special command, if

such a command is provided by the system.

- Some front ends respond to certain escape or control sequences as

commands to turn off echoing, either from that point onward, or

else on a per-line basis. In this case, the appropriate control

sequence can be inserted between packets by Kermit programs in-

structed to do so, for instance using the SET PAD command.

- If the echoing cannot be disabled, then the two Kermit programs

should be instructed to use differing packet start markers, using

the SET START-OF-PACKET command -- for instance, one Kermit uses

Control-A as usual, and the other uses Control-B. This can only

be done if both Kermits have this SET command.

When Things Go Wrong

Page 21

3.3. Special Characters

There is one problem that can prevent a file transfer from starting at all, or may crop up after the file transfer is underway. For instance, during a file transfer operation you might find your smart modem suddenly hanging up your current connection and placing a call to Tasmania. Or you might find that packets containing a certain character like "@" cannot be transmitted success- fully.

This is the problem of "special characters". Some device in the communication path -- a front end, a port switcher, a multiplexer, a "smart" modem -- inter- prets certain characters in the data stream as commands rather than as data to be passed them along to the other side. Usually such equipment interferes only with the transmission of ASCII control characters; so long as

Control-A and

Carriage Return -- Kermit's normal packet start and end delimiters -- are not molested, then Kermit can operate. However, equipment may exist which swallows even printable characters. Since Kermit assumes that ALL printable

ASCII characters (ASCII 40 through 176, octal) can be transmitted without inter- ference or modification, such equipment will prevent Kermit file transfer un- less its printable-character-swallowing features can be disabled.

3.4. 3270 Protocol Emulators

Connections to IBM mainframes through 3270 protocol emulation hardware or software cannot be used for file transfer with Kermit or any similar program.

Kermit requires an asynchronous stream ASCII telecommunications environment.

3270-style terminals operate in a block-mode bisynchronous EBCDIC environment.

Protocol converters change the EBCDIC screen data blocks into streams of

ASCII

characters with imbedded terminal control sequences. Packetized file transfer is impossible under these circumstances because the data is modified and the packet block check invalidated.

The only exception to this rule occurs on IBM mainframes with protocol emulators that can be put into transparent mode by a command from the host, and whose Kermit programs have been coded explicitly to do this. For instance, as of this writing there are IBM mainframe Kermit programs that allow file trans- fer through the Series/1 or 7171 front ends.

3.5. The Transfer Starts But Then Gets Stuck

Once a Kermit file transfer has begun, there are certain conditions under which it can become stuck. Since many hosts are capable of generating timeout inter- rupts when input doesn't appear within a reasonable interval, they can resend unacknowledged packets or request that missing packets be retransmitted. But since not all Kermit programs are capable of timing out, a means for manual in- tervention is provided in the local Kermit -- you can type a carriage return on the keyboard of most micros to wake up and continue the transfer.

The following sections discuss various reasons why a transfer in progress could become stuck. Before examining these, first make sure that you really have a

Kermit on the other end of the line, and you have issued the appropriate com- mand: SEND, RECEIVE, or SERVER. If the remote side is not a server, remember that you must connect back between each transfer and issue a new

SEND or

RECEIVE command.

When Things Go Wrong

Page 22

3.5.1. The Micro is Hung

The micro itself sometimes becomes hung for reasons beyond Kermit's control, such as power fluctuations. If the micro's screen has not been updated for a long time, then the micro may be hung. Try these steps (in the following order):

- Press RETURN to wake the micro up. This should clear up any protocol

deadlock. Several RETURNs might be necessary.

- If the problem was not a deadlock, restart Kermit, CONNECT back to

the host, get back to your job or login again, and restart the trans-

fer. You may have to stop and restart Kermit on the remote host.

3.5.2. The Connection is Broken

Check the connection. Make sure no connectors have wiggled loose from their sockets. If you're using a modem, make sure you still have a carrier signal.

Reestablish your connection if you have to.

If upon reconnection you get no response, maybe the remote host or the remote

Kermit program crashed. Get back to command level on the local

Kermit (on microcomputer implementations, you may be able to do this by typing about five

RETURNs, or one or more Control-C's). Issue the CONNECT command so that you can see what happened. If the remote system has crashed then you will have to wait for it to come back, and restart whatever file that was being transferred at the time.

3.5.3. The Disk is Full

If your local floppy disk or remote directory fills up, the Kermit on the machine where this occurs will inform you and then terminate the transfer. You

can continue the transfer by repeating the whole procedure either with a fresh floppy or after cleaning up your directory. Some Kermit programs allow you to continue the sequence where it left off, for instance on the DEC-20 by using the SEND command and including the name of the file that failed in the

"(INITIAL)" field:

Kermit-20>send *.for (initial) foo.for

See the Kermit-20 command summary for further information about the initial filespec. Some Kermits also have a feature that allows you to keep incom- pletely received files; this would allow you go back to the sending system, ex- tract the unsent portion of the file, and send it, and then append the two received portions together using an editor or other system utility.

Kermit does not provide the ability to switch disks during a file transfer.

When Things Go Wrong

Page 23

3.5.4. Message Interference

You may find that file transfers fail occasionally and upredictably.

One ex- planation could be that terminal messages are being mixed with your file packet data. These could include system broadcast messages (like "System is going down in 30 minutes"), messages from other users ("Hi Fred, what's that

Kermit program you're always running?"), notifications that you have requested

("It's

7:30, go home!" or "You have mail from..."). Most Kermit programs attempt to disable intrusive messages automatically, but not all can be guaranteed to do so. It may be necessary for you to "turn off" such messages before starting

Kermit.

3.5.5. Transmission Delays

Packet transmission can be delayed by various agents: congested timesharing systems or networks, earth satellites, etc. When transmission delay exceeds the per-packet timeout interval for a significant length of time, the transfer could fail. Most Kermit programs provide commands that allow you to adjust the timeout interval or the packet transmission retry threshhold in order to accom- modate to severe transmission delays.

3.5.6. Noise Corruption

If your connection is extremely noisy, packets will become corrupted -- and re- quire retransmission -- more often. The probability that successive retransmissions will fail because of corruption rises with the noise level un- til it exceeds the retry threshhold, at which point the file transfer fails.

There are several recourses. First, try to establish a new connection. If that is impractical, then use SET commands (when available) to reduce the

packet length and increase the retry threshhold. Shorter packets reduce the probability that a particular packet will be corrupted and the retransmission overhead when corruption does occur, but they also increase the overall protocol overhead. In a noisy environment, you should also request a higher level of error checking.

3.5.7. Host Errors

Various error conditions can occur on the remote host that could effect file transmission. Whenever any such error occurs, the remote Kermit normally at- tempts to send an informative error message to the local one, and then breaks transmission, putting you back at Kermit command level on the local system.

3.6. File is Garbage

There are certain conditions under which Kermit can believe it transferred a file correctly when in fact, it did not. The most likely cause has to do with the tricky business of file attributes, such as text vs binary, 7-bit vs

8-bit, blocked vs stream, and so forth. Each system has its own peculiarities, and each Kermit has special commands to allow you to specify how a file should be sent or stored. However, these difficulties usually crop up only when sending binary files. Textual files should normally present no problem between any two

Kermit programs.

When Things Go Wrong

Page 24

3.7. Junk after End of File

When transferring a text file from a microcomputer to a mainframe, sometimes you will find extraneous characters at the end of the file after it arrives on the target system. This is because many microcomputers don't have a consistent way of indicating the end of a file. CP/M is a good example. The minimum unit of storage on a CP/M floppy is a "block" of 128 bytes. Binary files always consist of a whole number of blocks, but a text file can end anywhere within a block. Since CP/M does not record a file's byte count, it uses the convention of marking the end with an imbedded Control-Z character. If your microcomputer version of Kermit is not looking for this character, it will send the entire last block, which may contain arbitrary junk after the "real" end of the file.

To circumvent this problem, most microcomputer Kermits have commands like SET

FILE ASCII or SET FILE TEXT to instruct Kermit to obey the CTRL-Z convention.

Some microcomputer Kermits operate in "text" mode by default, others in

"binary" or "block" mode.

To complicate matters, certain software on other microcomputer systems, such as

MS-DOS, follows the CP/M end-of-file convention. Under MS-DOS, certain editors and other programs use Control-Z for end-of-file, and other programs do not.

MS-DOS Kermit provides a SET command to choose the desired format.

Kermit Commands

Page 25

4. Kermit Commands

An "ideal" Kermit program will be described here, which has most of the fea- tures specified in the Kermit Protocol Manual. No Kermit program will have all these commands or support all these options. The exact form of some of the commands may differ from version to version. Some Kermit programs may support system-dependent options not described here. The intention of this description is to provide a base from which specific Kermit programs can be described in terms of their differences from the "ideal."

4.1. Remote and Local Operation

In any connection between two Kermit programs, one Kermit is remote and the other is local. The remote Kermit is usually running on a mainframe, which you have CONNECTed to through a PC or other computer. When Kermit runs remotely, all file transfer is done over the job's controlling terminal line -- the same line over which you logged in, and to which you would type interactive com- mands. What the system thinks is your terminal is really another computer, usually a microcomputer, running its own copy of Kermit.

When Kermit is in "local mode", file transfer is done over an external device, such as a microcomputer's serial communication port, or an assigned terminal line on a mainframe. The local Kermit is connected in some way (like a dialout mechanism) to another computer, again running its own copy of Kermit. A local

Kermit is in control of the screen, a remote Kermit has no direct access to it.

Microcomputer Kermits are run in local mode unless instructed otherwise; mainframe Kermits run remotely unless some special command places them in local mode. Some commands make sense only for remote Kermits, others only for local,

still others can be used with either. Local and remote operation of

Kermit is shown schematically here: The Kermit program on the PC is a local

Kermit. It can control the screen, the keyboard, and the port separately, thus it can up- date the screen with status information, watch for interrupt signals from the keyboard, and transfer packets on the communications port, all at the same time.

The Kermit program running on the mainframe is a remote Kermit. The user logs in to the mainframe through a terminal port. The host computer cannot tell that the user is really coming in through a microcomputer. The keyboard, screen, and port functions are all combined in user's mainframe terminal line.

Therefore a remote Kermit is cut off from your screen and keyboard during file transfer.

4.2. The Command Dialog

Most Kermit programs communicate with you through interactive keyword-style command dialog. The program issues a prompt, indicating that it is waiting for you to type a command. The prompt is usually of the form

Kermit-xx> where xx indicates the version of Kermit -- Kermit-MS> for MS-DOS

Kermit,

Kermit-86> for CP/M-86 Kermit, etc.

In response to the program's prompt you may type a keyword, such as

SEND,

Kermit Commands

Page 26

PC is Local, Mainframe is Remote:

Communication

Line (Packets)

+---------------/ /-----------------+ Other terminals

| | | | |

| | | | |

PC | LOCAL Mainframe | | | | REMOTE

+----------+----------+ +------------+--+--+--+--------+

| Serial Port | | | |

| | | | |

| | | | |

| +---------------+ | | Your job's |

| | Packets: 724 | | | terminal line |

| | Retries: 7 | | | |

| | File: FOO.BAR | | | |

| +---------------+ | | |

| Screen | | |

| | | |

+---------------+-----+ +------------------------------+

|

| (Commands)

|

+------------+---------+

\ Keyboard \

+----------------------+

You

Figure 4-1: Local and Remote Kermits

RECEIVE, or EXIT, possibly followed by additional keywords or operands, each of which is called a field. You can abbreviate keywords (but not file names) to any length that makes them distinguishable from any other keyword valid for that field. You can type a question mark at any time to get information about what's expected or valid at that point. The ESC and "?" features work best on full duplex systems (all but the IBM mainframe, so far), where the program can

"wake up" immediately and perform the required function. On half duplex or record-oriented systems, the ESC feature is not available, and the "?" re- quires a carriage return to follow.

In this example, the user types "set" and then a question mark to find out what

the SET options are. The user then continues the command at the point where the question mark was typed, adding a "d" and another question mark to see what set options start with "d". The user then adds a "u" to select "duplex"

(the only SET option that starts with "du") followed by an ESC (shown here by a dol- lar sign) to complete the current field, then another question mark to see what the possibilities are for the next field, and so forth. The command is finally terminated by a carriage return. Before carriage return is typed, however, the command can be edited or erased using RUBOUT or other command editing keys.

Finally, the same command is entered again with a minimum of keystrokes, with each field abbreviated to its shortest unique length. In the example, the parts the user types are underlined; all the rest is system typeout:

Kermit-20>set ? one of the following:

debugging delay duplex escape

Kermit Commands

Page 27

file handshake IBM line

parity receive send

Kermit-20>set d? one of the following:

debugging delay duplex

Kermit-20>set du$plex (to) ? one of the following:

full half

Kermit-20>set duplex (to) h$alf

Kermit-20>set du h

4.3. Notation

In the command descriptions, the following notation is used: italics A parameter - the symbol in italics is replaced by an argument of

the specified type (number, filename, etc).

[anything] A field enclosed in square brackets is optional. If omitted, the

field defaults to an appropriate value. You don't type the brack-

ets.

{x,y,z} A list of alternatives is enclosed in curly braces; you type one of

the alternatives. number A whole number, entered in prevailing notation of the system. character A single character, entered literally, or as a number

(perhaps oc-

tal or hexadecimal) representing the ASCII value of the character. floating-point-number

A "real" number, possibly containing a decimal point and a frac-

tional part. filespec A file specification, i.e. the name of a file, possibly including a

search path, device or directory name, or other qualifying infor-

mation, and possibly containing "wildcard" or patternmatching

characters to denote a group of files.

^X A control character may be written using "uparrow" or "caret" nota-

tion, since many systems display control characters this way.

Con-

trol characters are produced by holding down the key marked

CTRL or

Control and typing the appropriate character, e.g. X.

Commands are shown in upper case, but can be entered in any combination of up- per and lower case.

Kermit Commands

Page 28

4.4. Summary of Kermit Commands

Here is a brief list of Kermit commands as they are to be found in most

Kermit programs. The following sections will describe these commands in detail.

For exchanging files:

SEND, RECEIVE, GET

For connecting to a remote host:

CONNECT, SET LINE, SET PARITY, SET DUPLEX, SET HANDSHAKE, SET

ESCAPE,

SET FLOW-CONTROL, SET SPEED (or BAUD)

For acting as a server:

SERVER

For talking to a server:

BYE, FINISH, GET, SEND, REMOTE

Setting nonstandard transmission and file parameters:

SET BLOCK-CHECK, SET DEBUG, SET DELAY, SET FILE, SET

INCOMPLETE, SET

PARITY, SET RETRY;

SET SEND (or RECEIVE) END-OF-LINE, START-OF-PACKET, PACKET-LENGTH,

PAUSE,

TIMEOUT, PADDING

For defining "macros" of commands:

DEFINE

For interrupting transmission:

Control-X, Control-Z, Control-C, Control-E

Getting information:

HELP, STATISTICS, SHOW

Executing command files:

TAKE

For recording the history of a file transfer operation:

LOG TRANSACTIONS

For non-protocol file capture or transmission:

LOG SESSION, TRANSMIT, INPUT, OUTPUT, PAUSE, CLEAR, SCRIPT

For closing log files:

CLOSE

Leaving the program:

EXIT, QUIT

If you have a file called KERMIT.INI in your default or home disk,

Kermit will execute an automatic TAKE command on it upon initial startup.

KERMIT.INI may contain any Kermit commands, for instance SET commands, or DEFINEs for macros to configure Kermit to various systems or communications media. Note:

Your particular implementation of Kermit may use a different name for this file.

Kermit Commands

Page 29

4.5. The SEND Command

Syntax:

Sending a single file:

SEND nonwild-filespec1 [filespec2]

Sending multiple files:

SEND wild-filespec1 [filespec2]

The SEND command causes a file or file group to be sent to the other system.

There are two forms of the command, depending on whether filespec1 contains

"wildcard" characters. Use of wildcard characters is the most common method of indicating a group of files in a single file specification. For instance if

FOO.FOR is a single file, a FORTRAN program named FOO, then *.FOR might be a group of FORTRAN programs.

Sending a File Group --

If filespec1 contains wildcard characters then all matching files will be sent, in directory-listing order (according to the ASCII collating sequence) by name.

If a file can't be opened for read access, it will be skipped. Some

Kermit programs allow the initial file in a wildcard group to be specified with the optional filespec2. This allows a previously interrupted wildcard transfer to continue from where it left off, or it can be used to skip some files that would be transmitted first.

Sending a Single File --

If filespec1 does not contain any wildcard characters, then the single file specified by filespec1 will be sent. Optionally, filespec2 may be used to specify the name under which the file will arrive at the target system;

filespec2 is not parsed or validated locally in any way. If filespec2 is not specified, the file will be sent with its own name.

SEND Command General Operation --

Files will be sent with their filename and filetype (for instance

FOO.BAR, no device or directory field, no generation number or attributes). If communica- tion line parity is being used (see SET PARITY), the sending Kermit will re- quest that the other Kermit accept a special kind of prefix notation for binary files. This is an advanced feature, and not all Kermits have it; if the other

Kermit does not agree to use this feature, binary files cannot be sent cor- rectly.

The sending Kermit will also ask the other Kermit whether it can handle a spe- cial prefix encoding for repeated characters. If it can, then files with long strings of repeated characters will be transmitted very efficiently.

Columnar data, highly indented text, and binary files are the major beneficiaries of this technique.

Kermit Commands

Page 30

SEND Remote Operation --

If you are running Kermit remotely (for instance, from a microcomputer), you should "escape back" to your local Kermit within a reasonable amount of time and give the RECEIVE command. Don't take more than a minute or two to complete the switch, or Kermit may "time out" and give up (in that case, you'll have to

CONNECT back to the remote system and reissue the SEND command).

SEND Local Operation --

If you're running Kermit locally, for instance on a microcomputer, you should have already run Kermit on the remote system and issued either a

RECEIVE or a

SERVER command.

Once you give Kermit the SEND command, the name of each file will be printed on your screen as the transfer begins, and information will be displayed to in- dicate the packet traffic. When the specified operation is complete, the program will sound a beep, and the status of the operation will be indicated by a message like OK, Complete, Interrupted, or Failed.

If you see many packet retry indications, you are probably suffering from a noisy connection. You may be able to cut down on the retransmissions by using

SET SEND PACKET-LENGTH to decrease the packet length; this will reduce the probability that a given packet will be corrupted by noise, and reduce the time required to retransmit a corrupted packet.

If you notice a file being sent which you do not really want to send, you may cancel the operation immediately by typing either Control-X or Control-

Z. If your are sending a file group, Control-X will cause the current file to be skipped, and Kermit will go on to the next file, whereas Control-Z will cancel sending the entire group and return you to Kermit-20 command level.

4.6. The RECEIVE Command

Syntax: RECEIVE [filespec]

The RECEIVE command tells Kermit to wait for the arrival a file or file group sent by a SEND command from the other system. If only one file is being received, you may include the optional filespec as the name to store the incom- ing file under; otherwise, the name is taken from the incoming file header. If the name in the header is not a legal file name on the local system,

Kermit will attempt to transform it to a legal name.

If an incoming file has the same name as an existing file, Kermit will either overwrite the old file or else try to create a new unique name, depending on the setting of FILE WARNING.

If you have SET PARITY, then 8th-bit prefixing will be requested. If the other side cannot do this, binary files cannot be transferred correctly. The sending

Kermit may also request that repeated characters be compressed.

If an incoming file does not arrive in its entirety, Kermit will normally dis- card it; it will not appear in your directory. You may change this behavior by using the command SET INCOMPLETE KEEP, which will cause as much of the file as

Kermit Commands

Page 31 arrived to be saved in your directory.

RECEIVE Remote Operation --

If your are running Kermit remotely, you should escape back to your local

Ker- mit and give the SEND command. You should do this within about two minutes, or the protocol may time out and give up; if this happens, you can CONNECT back to the remote system and reissue the RECEIVE command.

RECEIVE Local Operation --

If you are running Kermit locally, you should already have issued a

SEND com- mand to the remote Kermit, and then escaped back to DEC-20 Kermit (you can not issue a RECEIVE command to a Kermit server, you must use the GET command for that).

As files arrive, their names will be shown on your screen, along with a con- tinuous display the packet traffic.

If a file begins to arrives that you don't really want, you can attempt to can- cel it by typing Control-X; this sends a cancellation request to the remote

Kermit. If the remote Kermit understands this request (not all implementations of Kermit support this feature), it will comply; otherwise it will continue to send. If a file group is being sent, you can request the entire group be can- celled by typing Control-Z.

4.7. GET

LOCAL ONLY -- Syntax: GET [remote-filespec]

The GET command requests a remote Kermit server to send the file or file group specified by remote-filespec. Note the distinction between the RECEIVE and GET

commands: RECEIVE instructs the program to wait passively, whereas GET actively sends a request to a server.

The GET command can be used only when Kermit is local, with a Kermit server on the other end of the line. This means that you must have CONNECTed to the other system, logged in, run Kermit there, issued the SERVER command, and es- caped back to the local Kermit.

The remote filespec is any string that can be a legal file specification for the remote system; it is not parsed or validated locally. As files arrive, their names will be displayed on your screen, along with a continuous indica- tion of the packet traffic. As in the RECEIVE command, you may type

Control-X to request that the current incoming file be cancelled, Control-Z to request that the entire incoming batch be cancelled.

Optional Syntax: If you are requesting a single file, you may type the

GET com- mand without a filespec. In that case, Kermit programs that implement the op- tional GET syntax will prompt you for the remote filespec on the subsequent line, and the name to store it under when it arrives on the line after that:

Kermit-MS>get

Kermit Commands

Page 32

Remote Source File: aux.txt

Local Destination File: auxfile.txt

4.8. SERVER

Syntax: SERVER

The SERVER command instructs Kermit to cease taking commands from the keyboard and to receive all further instructions in the form of Kermit packets from another system. The other Kermit must have commands for communicating with remote servers; these include GET, SEND, FINISH, and BYE.

After issuing this command, return to the "client" system and issue

SEND, GET,

BYE, FINISH, or other server-directed commands from there. If your local

Ker- mit does not have a BYE command, then it does not have the full ability to com- municate with a Kermit server and you should not put the remote Kermit into

SERVER mode. If your local Kermit does have a BYE command, use it to shut down and log out the Kermit server when you are done with it.

Any nonstandard parameters should be selected with SET commands before putting

Kermit in server mode.

4.9. BYE

LOCAL ONLY -- Syntax: BYE

When running as a local Kermit talking to a Kermit server, use the BYE command to shut down and log out the server. This will also close any debugging log files and exit from the local Kermit.

4.10. FINISH

LOCAL ONLY -- Syntax: FINISH

When running as a local Kermit talking to a remote Kermit server use the

FINISH

command to shut down the server without logging out the remote job, so that you can CONNECT back to it. Also, close any local debugging log file.

4.11. REMOTE

LOCAL ONLY -- Syntax: REMOTE command

When running as a local Kermit talking to a remote Kermit server, use the

REMOTE command to request special functions of the remote server. If the serv- er does not understand the command or offer the requested service (all of these commands and services are optional features of the Kermit protocol), it will reply with a message like "Unknown Kermit server command". If does understand, it will send the results back, and they will be displayed on the screen.

The

REMOTE commands are:

REMOTE CWD [directory]

Change Working Directory. If no directory name is provided, the server

Kermit Commands

Page 33

will change to the default directory. Otherwise, you will be prompted for

a password, and the server will attempt to change to the specified direc-

tory. If access is not granted, the server will provide a message to that

effect.

REMOTE DELETE filespec

Delete the specified file or files. The names of the files that are

deleted should be displayed on your screen.

REMOTE DIRECTORY [filespec]

The names of the files that match the given file specification will be dis-

played on your screen, possibly along with additional information about

file sizes and dates. If no file specification is given, all files from

the current directory will be listed.

REMOTE SPACE [directory]

Information about disk usage in the current remote directory -- quota, cur-

rent storage, or amount of remaining free space -- is displayed on your

screen.

REMOTE HELP

A list of available server functions is displayed.

REMOTE HOST [command]

The given command is passed to the server's host command processor, and the

resulting output is displayed on your screen.

REMOTE KERMIT [command]

The given command, which is expressed in the server

Kermit's own

interactive-mode command syntax, is passed to the server for execution.

This is useful for changing settings, logging, and other functions.

REMOTE RUN program-name [command-line-argument]

The remote Kermit is asked to run the indicated program with the indicated

command line; the program's terminal output is sent back to your screen.

REMOTE PROGRAM [command]

The command is sent to the program started by most recent

REMOTE RUN

program, and the program's response is displayed on the screen. If no com-

mand is given, a newline character is sent.

REMOTE TYPE filespec

The contents of the specified file is displayed on your screen.

4.12. LOCAL

Syntax: LOCAL command

Execute the specified command on the local system -- on the system where

Kermit to which your are typing this command is running. These commands provide some local file management capability without having to leave the Kermit program, which is particularly useful on microcomputers. The LOCAL prefix for these commands can be omitted.

CWD [directory]

Kermit Commands

Page 34

"Change Working Directory" to the specified directory.

DELETE filespec

Delete the specified file or files.

DIRECTORY [filespec]

Provide a directory listing of the specified files.

SPACE

Display local disk usage and/or free space.

RUN filespec [operands]

Run the indicated program with the supplied command-line operands.

PUSH Invoke the local system command interpreter in such a way that it can

return (or "pop" or "exit") back to Kermit.

Some Kermit programs may provide commands for these or other functions in the syntax of their own system, when this would cause no confusion. For instance,

CP/M Kermit may use ERA in place of LOCAL DELETE.

4.13. CONNECT

LOCAL ONLY -- Syntax: CONNECT [terminal-designator]

Establish a terminal connection to the system at the other end of the com- munication line. On a microcomputer, this is normally the serial port.

On a mainframe, you will have to specify a terminal line number or other identifier, either in the CONNECT command itself, or in a SET LINE command. Get back to the local Kermit by typing the escape character followed by a single character

"command". Several single-character commands are possible:

C Close the connection and return to the local Kermit.

S Show status of the connection.

B Send a BREAK signal.

0 (zero) Send a NUL (0) character.

D Drop the line, hangup the modem.

P Push to the local system command processor without breaking the connec-

tion.

Q Quit logging session transcript.

R Resume logging session transcript.

? List all the possible single-character arguments.

^] (or whatever you have set the escape character to be)

Typing the escape character twice sends one copy of it to the connected

host.

You can use the SET ESCAPE command to define a different escape character, and

SET PARITY, SET DUPLEX, SET FLOW-CONTROL, SET HANDSHAKE to establish or change those parameters.

Kermit Commands

Page 35

4.14. HELP

Syntax: HELP

Typing HELP alone prints a brief summary of Kermit and its commands, and pos- sibly instructions for obtaining more detailed help on particular topics.

Most

Kermit implementations also allow the use of "?" within a command to produce a short help message.

4.15. TAKE

Syntax: TAKE filespec

Execute Kermit commands from the specified file. The file may contain contain any valid Kermit commands, including other TAKE commands.

4.16. EXIT, QUIT

Exit from Kermit. QUIT is a synonym for EXIT.

4.17. The SET Command

Syntax: SET parameter [option] [value]

Establish or modify various parameters for file transfer or terminal connec- tion.

When a file transfer operation begins, the two Kermits automatically exchange special initialization messages, in which each program provides the other with certain information about itself. This information includes the maximum packet size it wants to receive, the timeout interval it wants the other

Kermit to use, the number and type of padding characters it needs, the endof-line character it needs to terminate each packet (if any), the block check type, the desired prefixes for control characters, characters with the "high bit" set,

and repeated characters. Each Kermit program has its own preset

"default" values for these parameters, and you normally need not concern yourself with them. You can examine their values with the SHOW command; the SET command is provided to allow you to change them in order to adapt to unusual conditions.

The following parameters may be SET:

BAUD-RATE Set the speed of the current communications port

BLOCK-CHECK Packet transmission error detection method

DEBUGGING Mode or log file

DELAY How long to wait before starting to send

DUPLEX For terminal connection, full (remote echo) or half (local echo)

ESCAPE Character for terminal connection

FILE For setting file parameters like name conversion and byte size

FLOW-CONTROL Selecting flow control method, like XON/XOFF

HANDSHAKE For turning around half duplex communication line

IBM Set things up for communicating with an IBM mainframe

INCOMPLETE What to do with an incomplete file

LINE Terminal line to use for terminal connection or file transfer

Kermit Commands

Page 36

MODEM Modem type or characteristics

PARITY Character parity to use

PORT For switching communication ports

PROMPT For changing the program's command prompt

RECEIVE Various parameters for receiving files

RETRY How many times to retry a packet before giving up

SEND Various parameters for sending files

TIMER Enable/disable timeouts

The DEFINE command may be used to compose "macros" by combining SET commands.

The SET commands are now described in detail.

SET BAUD-RATE

Set or change the baud rate (approximate translation: transmission speed in bits per second) on the currently selected communications device. Ten bits per second is equivalent to one character per second; 300 baud = 30 cps.

The way of specifying the baud rate varies from system to system; in most cases, the actual number (such as 1200 or 9600) is typed. Systems that do not provide this command generally expect that the speed of the line has already been set appropriately outside of Kermit. Common values are 300, 1200, 2400,

4800,

9600.

SET BLOCK-CHECK {1, 2, 3}

Kermit normally uses a 1-character block check, or "checksum", on each packet.

The sender of the packet computes the block check based on the other characters in the packet, and the receiver recomputes it the same way. If these quan- tities agree, the packet is accepted and transmission proceeds. If they dis- agree, the packet is rejected and retransmission is requsted.

However, the block check is not a foolproof method of error detection.

The normal single-character Kermit block check is only a 6-bit quantity

(the low

order 8 bits of the arithmetic sum folded upon itself). With only six bits of

6 accuracy, the chances are one in 2 -- that is, 1/64 -- that an error can occur which will not be detected in the checksum, assuming that all errors are equally likely.

You can decrease the probability that an error can slip through, at the expense of transmission efficiency, by using the SET BLOCK-CHECK command to select more rigorous block check methods. Note that all three methods will detect any single-bit error, or any error in an odd number of bits. The options are:

1-CHARACTER-CHECKSUM:

The normal single-character 6-bit checksum.

2-CHARACTER-CHECKSUM:

A 2-character, 12-bit checksum. Reduces the probability of an error going

undetected to 1/4096, but adds an extra character to each packet.

3-CHARACTER-CRC:

A 3-character, 16-bit Cyclic Redundancy Check, CCITT format. In addition

to errors in any odd number of bits, this method detects double bit errors,

Kermit Commands

Page 37

all error bursts of length 16 or less, and more than 99.99% of all possible

longer bursts. Adds two extra characters to each packet.

The single character checksum has proven to be quite adequate in practice, much more effective than straightforward analysis would indicate, since all errors are not equally likely, and a simple checksum is well suited to catching the kinds of errors that are typical of telecommunication lines. The other methods should be requested only when the connection is very noisy and/or when sending binary files.

Note that the 2- and 3-character block checks are not available in all versions of Kermit; if the other Kermit is not capable of performing the higherpreci- sion block checks, the transfer will automatically use the standard single- character method.

SET DEBUG {ON, OFF}

Syntax: SET DEBUG options

Record debugging information, either on your terminal or in a file.

Options are:

ON Turn on debugging.

OFF Don't display debugging information (this is the default). If debugging

was in effect, turn it off and close any log file.

Some Kermit programs may control debugging by use of the LOG DEBUG command.

SET DELAY

Syntax: SET DELAY number

Specify how many seconds to wait before sending the first packet after a SEND

command. Use when remote and SENDing files back to your local Kermit.

This gives you time to "escape" back and issue a RECEIVE command. The normal delay is 5 seconds. In local mode or server mode, Kermit does not delay before send- ing the first packet.

SET DUPLEX

Syntax: SET DUPLEX {FULL, HALF}

For use when CONNECTed to a remote system. The keyword choices are

FULL and

HALF. FULL means the remote system echoes the characters you type, HALF means the local system echoes them. FULL is the default, and is used by most hosts.

HALF is necessary when connecting to IBM mainframes. Half duplex is also called "local echo".

Kermit Commands

Page 38

SET ESCAPE

Syntax: SET ESCAPE character

Specify or change the character you want to use to "escape" from remote connec- tions back to Kermit. This would normally be a character you don't expect to be using on the remote system, perhaps a control character like ^\, ^],

^^, or

^_. Most versions of Kermit use one of these by default. After you type the escape character, you must follow it by a single-character "argument", such as

"C" for Close Connection. The arguments are listed above, under the descrip- tion of the CONNECT command.

SET FILE

Syntax: SET FILE parameter value

Establish file-related parameters. Depending on the characteristics of the system, it may be necessary to tell Kermit how to fetch an outbound file from the disk, or how to store an incoming file. The actual parameters you can specify in this command will vary from system to system, and you should consult the documentation for your particular version of Kermit. Some examples would be file type (text or binary), byte size (PDP-10 architecture), record length or block size (record oriented systems), end-of-file detection method (on microcomputers), file naming conversion option.

This can be a very important command if you intend to transfer binary files, but is normally unecessary for transmitting textual files.

SET FLOW-CONTROL

Syntax: SET FLOW-CONTROL {XON/XOFF,NONE}

For communicating with full duplex systems. System-level flow control is not

necessary to the Kermit protocol, but it can help to use it if the same method is available on both systems. The most common type of flow control on full duplex systems is XON/XOFF. When a system's input buffer comes close to being full, it will send an XOFF character (Control-S) to request the other system to stop sending. When it has emptied sufficient characters from its input buffer, it signals the other system to resume sending by transmitting an XON character

(Control-Q). This process operates in both directions simultaneously.

The op- tions for the Kermit SET FLOW command are usually restricted to

XON/XOFF and

NONE, which is used to disable this feature.

SET HANDSHAKE

Syntax: SET HANDSHAKE option

For communicating with half duplex systems. This lets you specify the line turnaround character sent by the half duplex host to indicate it has ended its transmission and is granting you permission to transmit. When a handshake is set, Kermit will not send a packet until the half duplex host has sent the specified character (or a timeout has occurred). The options may include:

Kermit Commands

Page 39

NONE No handshake; undo the effect of any previous SET HANDSHAKE.

XOFF Control-S.

XON Control-Q.

BELL Control-G.

CR Carriage Return, Control-M.

LF Linefeed, Control-J.

ESC Escape, Control-[.

Some Kermit programs may require the option to be specified by typing the character literally or entering its numeric ASCII value. If you use this com- mand to enable handshaking, you should also SET FLOW OFF.

SET INCOMPLETE

Syntax: SET INCOMPLETE {KEEP, DISCARD}

Specify what to do when a file transfer fails before it is completed.

The op- tions are DISCARD (the default) and KEEP. If you choose KEEP, then if a trans- fer fails to complete successfully, you will be able to keep the incomplete part that was received.

SET LINE

Syntax: SET LINE [terminal-designator]

Specify the terminal line to use for file transfer or CONNECT. This command is found on mainframe Kermits, which normally run in "remote mode" using their own controlling terminal for file transfer. Specifying a separate line puts the program in "local mode." If no line is specified, revert to the job's con- trolling terminal, i.e. go back to "remote mode."

SET PORT

Syntax: SET PORT terminal-designator

Specify the communications port for file transfer or CONNECT. This command is

found on microcomputer Kermits that run in "local" mode. SET PORT does not change the remote/local status but simply selects a different port for local operation.

SET PARITY

Syntax: SET PARITY {EVEN, ODD, MARK, SPACE, NONE}

Parity is a technique used by communications equipment for detecting errors on a per-character basis; the "8th bit" of each character acts as a check bit for the other seven bits. Kermit uses block checks to detect errors on a per- packet basis, and it does not use character parity. However, some systems that

Kermit runs on, or equipment through which these systems communicate, may be using character parity. If Kermit does not know about this, arriving data will have been modified and the block check will appear to be wrong, and packets will be rejected.

Kermit Commands

Page 40

If parity is being used on the communication line, you must inform both Ker- mits, so the desired parity can be added to outgoing characters, and stripped from incoming ones. SET PARITY should be used for communicating with hosts that require character parity (IBM mainframes are typical examples) or through devices or networks (like GTE TELENET) that add parity to characters that pass through them. Both Kermits should be set to the same parity. The specified parity is used both for terminal connection (CONNECT) and file transfer

(SEND,

RECEIVE, GET).

The choices for SET PARITY are:

NONE (the default) eight data bits and no parity bit.

MARK seven data bits with the parity bit set to one.

SPACE seven data bits with the parity bit set to zero.

EVEN seven data bits with the parity bit set to make the overall parity

even.

ODD seven data bits with the parity bit set to make the overall parity odd.

NONE means no parity processing is done, and the 8th bit of each character can be used for data when transmitting binary files.

If you have set parity to ODD, EVEN, MARK, or SPACE, then advanced versions of

Kermit will request that binary files will be transferred using

8th-bit-prefixing. If the Kermit on the other side knows how to do

8th-bit-prefixing (this is an optional feature of the Kermit protocol, and not all implementations of Kermit have it), then binary files can be transmitted successfully. If NONE is specified, 8th-bit-prefixing will not be requested.

SET PROMPT

Syntax: SET PROMPT string

This allows you to change the program's prompt. This is particularly useful if you are using Kermit to transfer files between two systems of the same kind, in which case you can change the prompts of the Kermit programs involved to in- clude appropriate distinguishing information.

SET SEND

SET SEND parameter value

Parameters for outgoing packets, as follows:

END-OF-LINE character

The ASCII character to be used as a line terminator for outbound pack-

ets, if one is required by the other system, carriage return by

default. You will only have to use this command for systems that re-

quire a line terminator other than carriage return.

PACKET-LENGTH number

Maximum packet length to send between 10 and 94 (decimal).

Shortening

the packets might allow more of them to get through through without er-

ror on noisy communication lines. Lengthening the packets increases

the throughput on clean lines.

Kermit Commands

Page 41

TIMEOUT number

How many seconds to wait for a packet before trying again. A value of

zero means don't time out -- wait forever.

PAUSE floating-point-number

How many seconds to pause before sending each data packet.

Setting

this to a nonzero value may allow a slow system enough time to con-

solidate itself before the next packet arrives.

Normally, no

per-packet pausing is done.

PADDING number, PADCHAR character

How much padding to send before a packet, if the other side needs pad-

ding, and what character to use for padding. Defaults are no padding,

and NUL (0) for the padding character. This command is also handy for

inserting special characters that may be required by communications

equipment.

QUOTE character

What printable character to use for quoting of control characters, "#"

(43) by default. There should be no reason to change this.

START-OF-PACKET character

The start-of-packet character is the only control character used

"bare"

by the Kermit protocol. It is Control-A by default. If a bare

Control-A causes problems for your communication hardware or software,

you can use this command to select a different control character to

mark the start of a packet. You must also issue the reciprocal command

(SET RECEIVE START-OF-PACKET) to the Kermit on the other system

(providing it has such a command).

SET RECEIVE

Syntax: SET RECEIVE parameter value

Parameters to request or expect for incoming packets, as follows:

END-OF-LINE character

Carriage return (15) by default.

PACKET-LENGTH number

Maximum length packet for the other side to send, decimal number, be-

tween 10 and 94, decimal.

TIMEOUT number

How many seconds the other Kermit should wait for a packet before as-

king for retransmission.

PAUSE floating-point-number

How many seconds to pause before acknowledging a packet. Setting this

to a nonzero value will slow down the rate at which data packets ar-

rive, which may be necessary for systems that have "sensitive" front

ends and cannot accept input at a high rate.

PADDING number, PADCHAR character

How many padding characters to request before each incoming packet, and

Kermit Commands

Page 42

what the padding character should be. No Kermits are known to need

padding, and if one did, it would request it without your having to

tell it to do so. This command would only be necessary, therefore, un-

der very unusual circumstances.

QUOTE character

What printable character to use for quoting of control characters, "#"

(43) by default. There should be no reason to change this.

START-OF-PACKET character

The control character to mark the beginning of incoming packets.

Nor-

mally SOH (Control-A, ASCII 1) (see SET SEND START-OF-PACKET, above).

SET RETRY

SET RETRY option number

Set the maximum number of retries allowed for:

INITIAL-CONNECTION

How many times to try establishing the initial protocol connection be-

fore giving up, normally something like 15.

PACKETS How many times to try sending a particular packet before giving up,

normally 5. If a line is very noisy, you might want to increase this

number.

4.18. DEFINE

DEFINE macroname [set-parameters]

Define a "SET macro" to allow convenient association of one or more SET parameters with a mnemonic keyword of your choice. The SET parameters are a list of one or more SET options, separated by commas. If you use

Kermit to communicate with several different kinds of systems, you may set up a macro for

each, for instance:

DEFINE IBM PARITY MARK, DUPLEX HALF, HANDSHAKE XON

DEFINE UNIX PARITY NONE, DUPLEX FULL, HANDSHAKE NONE

DEFINE TELENET PARITY MARK, RECEIVE TIMEOUT 20

You may then type SET IBM, SET UNIX, and so forth to set all the desired parameters with a single command. It is convenient to include these defini- tions in your KERMIT.INI file.

Another other handy use for SET macros would be for rapid adaptation to dif- ferent conditions of line noise:

DEFINE CLEAN BLOCK-CHECK 1, SEND PACKET-LENGTH 94, RETRY PACKET 5

DEFINE NOISY BLOCK-CHECK 2, SEND PACKET-LENGTH 60, RETRY PACKET 10

DEFINE VERY-NOISY BLOCK 3, SEND PACKET 40, RETRY PACKET 20

You may redefine an existing macro in the same manner as you defined it. You can undefine an existing macro by typing an empty DEFINE command for it, for

Kermit Commands

Page 43 instance:

DEFINE IBM

You can list all your macros and their definitions with the SHOW

MACROS com- mand. Some Kermit programs allow macro definitions to include any Kermit com- mand, not just SET commands.

4.19. SHOW

Syntax: SHOW [option]

The SHOW command displays the values of the parameters settable by the

SET com- mand. If a particular option is not requested, a complete display will be provided.

4.20. STATISTICS

Give statistics about the most recent file transfer, such as the total number of characters transmitted, the effective baud rate, and so forth.

4.21. LOG

Syntax: LOG [option] [filespec]

Log the specified entity to the specified log file.

TRANSACTIONS Direct Kermit to log transactions, such as files successfully

sent or received or files that could not be successfully sent

or received. A transaction is useful recording the progress of

a long, unattended multifile transfer.

SESSION Create a transcript of a CONNECT session, when running a local

Kermit connected to a remote system, in the specified file.

The log is closed when connection is closed. In some implemen-

tations, logging can be "toggled" by typing the connect escape

character followed by Q (Quit logging) or R (Resume logging) or

similar single-character commands. Session-logging is useful

for recording dialog with an interactive system, and for

"capturing" from systems that don't have Kermit. No guarantee

can be made that the file will arrive correctly or completely,

since no error checking takes place.

DEBUGGING Record debugging information in the specified file.

There may

be several options to select the desired information -- entire

packets, state transitions, internal program trace, etc --

available via the SET DEBUGGING command.

PACKETS Record packets, and all communication line traffice during file

transfer, in the specified file.

Kermit Commands

Page 44

4.22. TRANSMIT

Syntax: TRANSMIT filespec

Send the contents of the specified file to the other system "bare", without protocol, packets, error checking, or retransmission. This command is useful for sending standard logon or connection sequences, and for sending files to systems that don't have Kermit. No guarantee can be made that the target sys- tem will receive the file correctly and completely. When receiving a file, the target system would normally be running a text editor in text collection mode.

4.23. INPUT

Syntax: INPUT [interval] [string]

Input characters from the remote system for the specified interval, looking for the specified string. Terminate when the string is found or when the interval has expired, whichever comes first. Useful for synchronizing with remote sys- tem prompts.

4.24. OUTPUT

Syntax: OUTPUT [string]

Send the specified string to the remote system. Useful in conjunction with the

INPUT command to form "login scripts".

4.25. PAUSE

Syntax: PAUSE [interval]

Pause for the specified interval. Useful in login scripts.

4.26. SCRIPT

Syntax: SCRIPT [string]

The string is a "login script" in some system- or implementationdependent for- mat, such as the UNIX(tm) UUCP "expect-send" format.

Kermit Implementations

Page 45

5. Kermit Implementations

Kermit has been written for a wide variety of systems, both mainframes and microcomputers. Kermit is not written in a portable language; rather, each im- plementation is written in a language suited for the particular machine.

The specification, given in the Kermit Protocol Manual, is quite general and allows implementation on almost any machine.

Here's a brief table summarizing the known Kermit implementations, as of this writing. This list is constantly growing, and may be far out of date by the time you read it.

Versions for "Portable Operating Systems": OS; Language (Machines)

CP/M-80; ASM (Kaypro, H/Z-89, H/Z-100, Osborne, DEC VT180, many others)

CP/M-86; ASM86 (DEC Rainbow, NEC APC, others)

MS-DOS; MASM (IBM PC,XT,AT, DEC Rainbow, HP-150, NEC APC, others...)

MUMPS (PDP-11)

Software Tools; Ratfor (HP3000, Sperry-Univac 1100)

UCSD p-System; Pascal (IBM PC, Terak, HP98x6, Pascal Microengine)

UNIX v7,4.xBSD,Sys III/V,Venix,Xenix,PC/IX; C (VAX, PDP-11, SUN, many more)

Host Versions: Machine (OS; Language)

Burroughs B6800 (Algol)

Cray-1, Cray-XMP (CTSS; Fortran-77)

CDC Cyber 170 (NOS, NOS/BE; Fortran-77)

Data General Nova (RDOS; Fortran-5)

Data General Eclipse (AOS; Fortran-5), MV Series (AOS/VS; Pascal)

DEC PDP-11 (RT11, RSX11M(+), RSTS, P/OS, TSX+; Macro-11)

DEC VAX-11 (VMS; Bliss-32 or Macro-32 or Pascal/Fortran)

DECsystem-10 (TOPS-10; Bliss-36, Macro-10), DECSYSTEM-20 (TOPS-20;

Macro-20)

Harris 800 (VOS; Pascal)

Honeywell (MULTICS; PL/I), DPS-6,8 (GCOS; C)

Hewlett-Packard 1000 (RTE-6/VM; Fortran), HP3000 (MPE; SPL or Ratfor)

IBM 370 Series (VM/CMS, MVS/TSO, MVS/GUTS, MUSIC, MTS; Assembler)

Perkin Elmer 3200 Series (OS/32; Fortran)

PRIME (PRIMOS; PL/P)

Tandem (Nonstop; TAL)

Sperry/Univac-1100 (EXEC; Assembler or Ratfor or Pascal)

PC Versions: Machine (OS; Language)

Alpha Micro 68000 (Assembler)

Apollo (Aegis; Fortran or Pascal)

Apple II 6502 (Apple DOS; DEC-10/20 CROSS or Apple Assembler)

Apple Macintosh (SUMACC C)

Atari (DOS; Action!)

Commodore 64 (DEC-10/20 CROSS or FORTH)

DEC Pro-300 Series (P/OS; Bliss-16 or Macro-11), (Pro/RT; Macro),

(Venix; C)

Intel Development System (ISIS; PL/M)

Perq (Pascal)

TRS80 I, III, Model 4 (TRSDOS; ASM)

TRS-80 Color Computer (Radio Shack DOS)

The remainder of the Kermit User Guide is devoted to descriptions of selected

Kermit implementations. If a description of your version of Kermit does not appear, look in the Kermit area on your mainframe for an on-line documentation file. Even if your version is described below, the version of the manual you are reading may be out of date and the online information may be more current.

DECSYSTEM-20 KERMIT

Page 46

6. DECSYSTEM-20 KERMIT

Authors: Frank da Cruz, Bill Catchings, Columbia University

Language: MACRO-20

Version: 4.2(257)

Date: May 1985

Kermit-20 Capabilities At a Glance:

Local operation: Yes

Remote operation: Yes

Transfers text files: Yes

Transfers binary files: Yes

Wildcard send: Yes

^X/^Y interruption: Yes

Filename collision avoidance: Yes

Timeouts: Yes

8th-bit prefixing: Yes

Repeat character compression: Yes

Alternate block check types: Yes

Communication settings: Yes

Transmit BREAK: Yes

IBM mainframe communication: Yes

Transaction logging: Yes

Session logging: Yes

Debug logging: Yes

Raw transmit: Yes

Login scripts: Yes

Act as server: Yes

Talk to server: Yes

Advanced commands for servers: Yes

Local file management: Yes

Command/init files: Yes

Handle file attributes: No

Kermit-20 is a program that implements the Kermit file transfer protocol for the Digital Equipment Corporation DECSYSTEM-20 mainframe computer. It is writ- ten in MACRO-20 assembly language and should run on any DEC-20 system with ver- sion 4 of TOPS-20 or later.

The Kermit-20 section will describe the things you should know about the

DEC-20 file system in order to make effective use of Kermit, and then it will describe the special features of the Kermit-20 program.

6.1. The DEC-20 File System

The features of the DEC-20 file system of greatest interest to Kermit users are the form of the file specifications, and the distinctions between text and bi- nary files.

DECSYSTEM-20 KERMIT

Page 47

DEC-20 File Specifications

DEC-20 file specifications are of the form

DEVICE:<DIRECTORY>NAME.TYPE.GEN;ATTRIBUTES where the DIRECTORY, NAME, and TYPE may each be up to 39 characters in length,

GEN is a generation (version number), and various attributes are possible

(protection code, account, temporary, etc). Generation and attributes are nor- mally omitted. Device and directory, when omitted, default to the user's own

(or "connected") disk and directory. Thus NAME.TYPE is normally sufficient to specify a file, and only this information is sent along by Kermit-20 with an outgoing file.

The device, directory, name, and type fields may contain uppercase letters, digits, and the special characters "-" (dash), "_" (underscore), and "$"

(dollar sign). There are no imbedded or trailing spaces. Other characters may be included by prefixing them (each) with a Control-V. The fields of the file specification are set off from one another by the punctuation indicated above.

The device field specifies a physical or "logical" device upon which the file is resident. The directory field indicates the area on the device, for in- stance the area belonging to the owner of the file. Kermit-20 does not trans- mit the device or directory fields to the target system, and does not attempt to honor device or directory fields that may appear in incoming file names; for instance, it will not create new directories.

The name is the primary identifier for the file. The type, also called the

"extension", is an indicator which, by convention, tells what kind of file we have. For instance FOO.FOR is the source of a Fortran program named

FOO;

FOO.REL might be the relocatable object module produced by compiling

FOO.FOR;

FOO.EXE could an executable program produced by LOADing and SAVing

FOO.REL, and so forth.

The DEC-20 allows a group of files to be specified in a single file specifica- tion by including the special "wildcard" characters, "*" and "%".

A "*" matches any string of characters, including no characters at all; a "%" matches any single character. Here are some examples:

*.FOR All files of type FOR (all Fortran source files) in the connected

directory.

FOO.* Files of all types with name FOO.

F*.* All files whose names start with F.

F*X*.* All files whose names start with F and contain at least one X.

%.* All files whose names are exactly one character long.

*.%%%* All files whose types are at least three characters long.

Wildcard notation is used on many computer systems in similar ways, and it is the mechanism most commonly used to instruct Kermit to send a group of files.

DECSYSTEM-20 KERMIT

Page 48

TEXT FILES AND BINARY FILES

The DEC-20, like most computers, has a file system with its own peculiarities.

Like many other systems, the DEC-20 makes a distinction between text files and binary files. Text files are generally those composed only of printing charac- ters (letters, digits, and punctuation) and "carriage control" characters

(carriage return, line feed, form feed, tab). Text files are designed to be read by people. Binary files are designed to be read by a computer program, and may have any contents at all. If you use the DEC-20 TYPE command to dis- play a text file on your terminal, the result will be intelligible.

If you type a binary file on your terminal, you will probably see mainly gibberish.

You can not always tell a text file from a binary file by its name or directory information, though in general files with types like .TXT, .DOC, .HLP are tex- tual (as are "source files" for computer programs like text formatters and pro- gramming language compilers), and files with types like .EXE, .REL,

.BIN are binary.

The DEC-20 has an unusual word size, 36 bits. It differs from most other sys- tems by storing text in 7-bit, rather than 8-bit, bytes. Since text is encoded in the 7-bit ASCII character set, this allows more efficient use of storage.

However, the word size is not a multiple of the normal byte size. The

DEC-20 therefore stores five 7-bit characters per word, with one bit left over.

It is also possible to store files with other byte sizes. The common layouts of bytes within a word are shown in Figure 6-1.

The minimum unit of disk allocation on the DEC-20 is a page, 512 36-bit words, or 2560 7-bit characters, or 2048 8-bit bytes. Any file that contains at least one bit of information occupies at least a full page on the disk. The direc-

tory information for a file includes the number of pages occupied on the disk, the bytesize of the file, and the number of bytes of that size which are in the file. This information can be seen by using the DEC-20 VDIRECTORY command, for instance

@vdir foo.*

PS:<MY-DIRECTORY>

Name Protection Pages Bytes(Size) Creation

FOO.COM.1;P774242 1 384(8) 27-Dec-83

MAC.1;P774242 1 152(7) 27-Dec-83

.REL.1;P774242 1 39(36) 27-Dec-83

.EXE.1;P774242 2 1024(36) 27-Dec-83

Total of 5 pages in 4 files

In this example, FOO.MAC occupies 1 page, and is composed of 152 7-bit bytes.

This file is textual (program source for the MACRO assembler), 152 characters long. Programs which read text files (such as text editors, program compilers, the TYPE command, etc) determine the end of a file from the byte count specified in the directory. Kermit-20 determines the end of file in the same way, so although FOO.MAC occupies an entire 2560-byte page of storage, only the first 152 characters are transmitted. Binary files, such as FOO.EXE

(an ex- ecutable DEC-20 program), tend to occupy full pages. In this case too,

Kermit-20 uses the byte count to determine the end of file.

Why do you need to know all this? In most cases, you don't. It depends on

DECSYSTEM-20 KERMIT

Page 49

-------------------------------------------------------------------------

------

7: Text Files: Five 7-bit bytes per word.

+------+------+------+------+------++

| | | | | ||

+------+------+------+------+------++

0 7 14 21 28 35

Normally, bit 35 is unused and set to zero. However, in EDIT (or

SOS,

or OTTO) line-numbered files, bit 35 is set to 1 when the word contains

a line number.

8: "Foreign" binary files: Four 8-bit bytes per word.

+-------+-------+-------+-------+---+

| | | | | |

+-------+-------+-------+-------+---+

0 8 16 24 32 35

Bits 32-35 are unused.

36: "Native" binary files: One 36-bit byte per word.

+-----------------------------------+

| |

+-----------------------------------+

0 35

All bits are used.

Figure 6-1: DECSYSTEM-20 Word/Byte Organization

-------------------------------------------------------------------------

------ whether you are using the DEC-20 as your "home base".

USING A MICROCOMPUTER TO ARCHIVE DEC-20 FILES

Most computers (other than the DEC-10 and DEC-20) store characters in

8-bit

bytes. Let's call any such system an 8-bit-byte system. Microcomputers that run CP/M or MS-DOS or PC-DOS, and any computers than run Unix, store these

8-bit bytes in a linear sequence. Certain other 8-bit-byte systems (PDP-

11 or

VAX systems with FILES-11, IBM mainframes) have more complex file formats.

This discussion applies to all linear 8-bit-byte systems, including most popular microcomputers.

Kermit can send any "native" DEC-20 sequential file, text or binary, to an

8-bit-byte system and bring it back to the DEC-20 restored to its original form. If you are using a microcomputer to archive your DEC-20 files, you need never concern yourself with details of byte size or file format. The same

DECSYSTEM-20 KERMIT

Page 50 holds true between two DEC-20s, or a DEC-10 and a DEC-20.

There is, however, one special complication of which you should be aware.

Cer- tain microcomputer operating systems, notably CP/M, do not have an entirely satisfactory way of indicating the end of file. The file length is recorded in blocks rather than bytes. For text files, the end of file is marked within a block by inserting a Control-Z after the last data character. Binary files, however, might easily contain Control-Z characters as data. Therefore, in or- der not to lose data, these systems must transmit binary files in complete blocks. If the binary file is of foreign origin (for instance, from a

DEC-20), and it did not happen to fill up the last block when it was transferred to the micro, then when that file is sent back to the system of origin in

"binary mode," junk will appear at the end (if it is sent back in "text mode," it could be truncated at the first data byte that happened to correspond to

Control-Z).

For DEC-20 programs in .EXE format, this generally has no effect on the run- nability or behavior of the program. But for other binary files, particularly internal format numerical data or relocatable program object (.REL) files, the junk could have bad effects. For instance, extraneous data at the end of a

.REL file will generally cause LINK to fail to load the file.

Most microcomputer Kermit programs have commands to control end-of-file detec- tion -- commands like SET FILE TEXT, SET FILE BINARY, SET EOF CTRLZ.

USING THE DEC-20 TO ARCHIVE MICROCOMPUTER FILES

You can use Kermit to send textual files from a microcomputer or any 8bit sys- tem to the DEC-20 with no special provisions, since Kermit-20 stores incoming characters in 7-bit bytes as text unless you explicitly instruct it otherwise.

But Kermit-20 has no automatic way of distinguishing an incoming binary file

5 from an incoming text file. Binary files from 8-bit-byte systems generally contain significant data in the 8th bit, which would be lost if the incoming characters were stored in 7-bit bytes, rendering the file useless when sent back to the original system. Thus if you want to use Kermit to store foreign

8-bit binary data on the DEC-20, you must tell it to store such files with a bytesize of 8 rather than 7. This can be the source of much confusion and in- convenience. In particular, you cannot use a "wildcard send" command to send a mixture of text and binary files from an 8-bit-byte system to the

DEC-20; rather, you must send all text files with Kermit-20's file bytesize set to 7, and all 8-bit binary files with the bytesize set to 8.

Once you get the foreign binary file into the DEC-20, stored with the correct bytesize (as FOO.COM is stored in the example above), you need take no special measures to send it back to its system of origin. This is because

Kermit-20 honors the bytesize and byte count from the directory. For instance, if you told Kermit-20 to SEND FOO.*, every file in the example above would be trans- mitted in the correct manner, automatically.

The previous discussion assumes you want to store text files in usable form on the DEC-20. However, if you are using the DEC-20 purely as a repository for

_______________

5

Unless the incoming file has an "ITS Binary Header"; see below.

DECSYSTEM-20 KERMIT

Page 51 your microcomputer files, and you have no desire to display or share the con- tents of those files on the DEC-20, you can SET FILE BYTESIZE 8 for all incom- ing files, both text and binary. When the files are sent back to a microcom- puter, they will be stored correctly.

FILES KERMIT-20 CANNOT HANDLE

The Kermit protocol can only accommodate transfer of sequential files, files which are a linear sequence of bytes (or words).

Some files on the DEC-20 are not sequential, and cannot be successfully sent or received by Kermit-20. These include directory files, files with holes

(missing pages), ISAM files, and RMS files. These files require external in- formation (kept in the DEC-20's file descriptor block and/or index table) in order to be reconstructed; when sending files, Kermit-20 presently transmits only the file name and the contents of the file. External control information and file attributes are not transmitted.

6.2. Program Operation

Kermit-20's prompt is "Kermit-20>". Kermit-20 will accept a single command on the Exec command line, like this:

@

@Kermit send foo.bar

the file is sent

@ or you can run the program interactively to issue several commands, like this:

@

@Kermit

TOPS-20 Kermit version 4.2(257)

Kermit-20>send foo.*

files are sent

Kermit-20>statistics

performance statistics are printed

Kermit-20>receive

files are received

Kermit-20>exit

@

During interactive operation, you may use the TOPS-20 help

("?") and recognition (ESC) features freely while typing commands. A question mark typed

DECSYSTEM-20 KERMIT

Page 52 at any point in a command displays the options available at that point; typing an ESC character causes the current keyword or filename to be completed (or default value to be supplied), and a "guide word" in parentheses to be typed, prompting you for the next field. If you have not typed sufficient characters to uniquely specify the keyword or filename (or if there is no default value) then a beep will be sounded and you may continue typing.

Command keywords may be abbreviated to their shortest prefix that sets them apart from any other keyword valid in that field.

If you have a file called KERMIT.INI in your login directory, Kermit-

20 will execute an automatic TAKE command on it upon initial startup.

KERMIT.INI may contain any Kermit-20 commands, for instance SET commands, or DEFINEs for SET macros to configure Kermit-20 to various systems or communications media.

Kermit-20 provides most of the commands possible for an "ideal" Kermit program, as described in the main part of the Kermit User Guide. The following sections will concentrate on system-dependent aspects of Kermit-20.

6.3. Remote and Local Operation

Kermit-20 normally runs in remote mode, with the user sitting at a PC.

But

Kermit-20 can also run in local mode. Local operation of Kermit-20 is useful if the DEC-20 has an autodialer, or a hardwired connection to another computer.

When in local mode, file transfer takes place over an assigned TTY line, and

Kermit-20 is free to update your screen with status information, and to listen to your keyboard for interrupt characters.

Kermit-20 enters local mode when you issue a SET LINE n command, where n is the octal TTY number of any line other than your own controlling terminal.

6.4. Conditioning Your Job for Kermit

Kermit-20 does as much as it can to condition your line for file transfer. It saves all your terminal and link settings, and restores them after use.

However, there are some sources of interference over which Kermit-20 can have no control. In particular, messages issued by superior or parellel forks could become mingled with Kermit packets and slow things down or stop them entirely.

For this reason, before using Kermit-20 for any extended period, you should:

- Type the Exec commands SET NO MAIL-WATCH and SET NO ALERTS

- Make sure you don't have any print or batch jobs pending that were

submitted with the /NOTIFY option.

- Make sure you don't have any superior or parallel forks that have en-

abled terminal interrupts on Control-A; these could prevent

Kermit

packets (which start with Control-A) from getting through.

After running Kermit, you can restore your mail-watch and alerts by hand.

Al- ternatively, you could have an Exec command file for invoking Kermit like this:

set no alerts

set no mail-watch

DECSYSTEM-20 KERMIT

Page 53

-------------------------------------------------------------------------

------

Local Operation of Kermit-20:

DECSYSTEM-20

+---------------------------------------+

| |

| +--------------------+ |

| | Your Job | |

| | | |

| | +------------+ | <--Commands | Your Job's

| | | Kermit-20 +---+--------------+----------------- (-: You

| | | | | Display---> | Controlling TTY

| | | | | |

| | | | | |

| | | | | <--Packets | Kermit's

| | | +---+--------------+-----------------> Remote

| | +------------+ | Packets--> | Assigned TTY System

| | | |

| +--------------------+ |

| |

+---------------------------------------+

Figure 6-2: DEC-20 Kermit Local Operation

-------------------------------------------------------------------------

------

kermit

set mail-watch

set alert 1:00PM Go to lunch

set alert 6:00PM Go to dinner

set alert 11:30PM Go to sleep

6.5. Kermit-20 Commands

This section describes the Kermit-20 commands -- in detail where they differ from the "ideal" Kermit, briefly where they coincide. Kermit-20 has the fol- lowing commands:

BYE to remote server.

CLEAR a stuck connection

CLOSE log file and stop logging remote session.

CONNECT as terminal to remote system.

CWD change local working directory.

DEFINE macros of Kermit-20 commands.

DELETE local files.

DIRECTORY listing of local files.

ECHO a line of text.

EXIT from Kermit-20.

FINISH Shut down remote server.

GET remote files from server.

HELP about Kermit-20.

INPUT characters from communication line.

DECSYSTEM-20 KERMIT

Page 54

LOCAL prefix for local file management commands.

LOG remote terminal session.

OUTPUT characters to communication line.

PAUSE between commands.

PUSH to TOPS-20 command level.

QUIT from Kermit-20

RECEIVE files from remote Kermit.

REMOTE prefix for remote file management commands.

RUN a DEC-20 program.

SEND files to remote Kermit.

SERVER mode of remote operation.

SET various parameters.

SHOW various parameters.

SPACE inquiry.

STATISTICS about most recent file transfer.

TAKE commands from a file.

TRANSMIT a file "raw".

TYPE a local file.

6.5.1. Commands for File Transfer

Kermit-20 provides the standard SEND, RECEIVE, and GET commands for transfer- ring files using the Kermit protocol.

THE SEND COMMAND

Syntax:

Sending a single file:

SEND nonwild-filespec1 (AS) [filespec2]

Sending multiple files:

SEND wild-filespec1 (INITIAL) [filespec2]

The SEND command causes a file or file group to be sent from the DEC-20 to the other system. There are two forms of the command, depending on whether filespec1 contains wildcard characters ("*" or "%"). Kermit-20 automatically recognizes the two cases and issues the appropriate guide word,

(AS) or

(INITIAL), depending on the form of filespec1.

Sending a File Group

If filespec1 contains wildcard characters then all matching files will be sent, in alphabetical order (according to the ASCII collating sequence) by name. If a file can't be opened for read access, it will be skipped. The initial file in a wildcard group can be specified with the optional filespec2. This allows a previously interrupted wildcard transfer from where it left off, or it can be used to skip some files that would be transmitted first.

DECSYSTEM-20 KERMIT

Page 55

Sending a Single File

If filespec1 does not contain any wildcard characters, then the single file specified by filespec1 will be sent. Optionally, filespec2 may be used to specify the name under which the file will arrive at the target system; filespec2 is not parsed or validated in any way by Kermit-20, but lower case letters are raised to upper case, and leading "whitespace" (blanks and tabs) are discarded. If filespec2 is not specified, Kermit-20 will send the file

6 with its own name.

SEND Command General Operation:

Files will be sent with their DEC-20 filename and filetype (for instance

FOO.BAR, no device or directory field, no generation number or attributes). If you expect to be sending files whose names contain characters that would be il- legal in filenames on the target system, and you know that the Kermit on the target system does not have the ability to convert incoming filenames, you can issue the SET FILE NAMING NORMAL-FORM command to have Kermit-20 replace suspect characters by X's.

Each file will be sent according to its bytesize and byte count from the direc- tory unless you specify otherwise using SET FILE BYTESIZE, or unless the file has an "ITS Binary" header. If the bytesize is 8, then four 8-bit bytes will be sent from each DEC-20 36-bit word, and the low order four bits will be skipped. If other than 8, then five 7-bit bytes will be sent from each word, with the 8th bit of the 5th character set to the value of the remaining bit

7

("bit 35") from the word.

If communication line parity is being used (see SET PARITY), Kermit-20 will re- quest that the other Kermit accept a special kind of prefix notation for binary files. This is an advanced feature, and not all Kermits have it; if the other

Kermit does not agree to use this feature, binary files cannot be sent cor- rectly. This includes executable programs (like DEC-20 .EXE files,

CP/M .COM files), relocatable object modules (.REL files), as well as text files with line sequence numbers.

Kermit-20 will also ask the other Kermit whether it can handle a special prefix encoding for repeated characters. If it can, then files with long strings of repeated characters will be transmitted very efficiently. Columnar data, highly indented text, and binary files are the major beneficiaries of this technique.

_______________

6

Control-V's, which are used to quote otherwise illegal characters in

DEC-20 file specifications, are stripped.

7

This is the same method used by the DEC-20 to encode 36-bit data on

"ANSI-ASCII" tapes. It allows not only DEC-20 binary files, but also the line- sequence-numbered files produced by EDIT, SOS, or OTTO, which use bit

35 to distinguish line numbers from text, to be sent and retrieved correctly.

DECSYSTEM-20 KERMIT

Page 56

If you're running Kermit-20 locally, for instance dialing out from the

DEC-20 to another system using an autodialer, you should have already run

Kermit on the remote system and issued either a RECEIVE or a SERVER command.

Once you give Kermit-20 the SEND command, the name of each file will be displayed on your screen as the transfer begins; a "." will be displayed for every

5 data packets sucessfully sent, and a "%" for every retransmission or timeout that occurs (you may also elect other typeout options with the SET DEBUG command).

If the file is successfully transferred, you will see "[OK]", otherwise there will be an error message. When the specified operation is complete, the program will sound a beep. If you see many "%" characters, you are probably suffering from a noisy connection. You may be able to cut down on the retransmissions by using SET SEND PACKET-LENGTH to decrease the packet length; this will reduce the probability that a given packet will be corrupted by noise, and reduce the time required to retransmit a corrupted packet.

During local operation, you can type Control-A at any point during the transfer to get a brief status report. You may also type Control-X or Control-Z to in- terrupt the current file or file group.

THE RECEIVE COMMAND

Syntax: RECEIVE [filespec]

The RECEIVE command tells Kermit-20 to receive a file or file group from the other system. If only one file is being received, you may include the optional filespec as the name to store the incoming file under; otherwise, the name is taken from the incoming file header. Even if the name in the header is not a legal TOPS-20 file name, Kermit-20 will store it under that name, in which case

you can refer to it later only by quoting each illegal character

(spaces, con- trol characters, etc) with Control-V. If for some reason an incoming filename simply cannot be converted to legal form, the file will be saved as

-UNTRANSLATABLE-FILENAME-.KERMIT (new generation). You may also use SET

FILE

NAMING NORMAL-FORM to have Kermit-20 choose more conventional names for incom- ing files.

If an incoming file has the same name as an existing file, Kermit-20 just creates a new generation of the same name and type, for instance

FOO.BAR.3,

FOO.BAR.4. The oldest generation will be automatically deleted, but you can still UNDELETE it.

Incoming files will all be stored with the prevailing bytesize, 7 by default, which is appropriate for text files. If you are asking Kermit-20 to receive binary files from a microcomputer or other 8-bit system, you must first type

SET FILE BYTESIZE 8. Otherwise, the 8th bit of each byte will be lost and the file will be useless when sent back to the system of origin.

If you have SET PARITY, then 8th-bit prefixing will be requested. If the other side cannot do this, binary files cannot be transferred correctly.

In all cases, Kermit-20 will request the other Kermit to compress repeated characters; if the other side can do this (not all Kermits know how) there may be a sig- nificant improvement in transmission speed.

If an incoming file does not arrive in its entirety, Kermit-20 will normally discard it; it will not appear in your directory. You may change this behavior by using the command SET INCOMPLETE KEEP, which will cause as much of the file

DECSYSTEM-20 KERMIT

Page 57 as arrived to be saved in your directory.

If you are running Kermit-20 locally, you should already have issued a

SEND

8 command to the remote Kermit, and then escaped back to DEC-20

Kermit. As files arrive, their names will be displayed on your screen, along with

"." and

"%" characters to indicate the packet traffic; you can type Control-A during the transfer for a brief status report.

If a file arrives that you don't really want, you can attempt to cancel it by typing Control-X; this sends a cancellation request to the remote

Kermit. If the remote Kermit understands this request (not all implementations of

Kermit support this feature), it will comply; otherwise it will continue to send. If a file group is being sent, you can request the entire group be cancelled by typing Control-Z.

THE GET COMMAND

Syntax: GET [remote-filespec]

The GET command requests a remote Kermit server to send the file or file group specified by remote-filespec. This command can be used only when Kermit-

20 is local, with a Kermit server on the other end of the line specified by SET

LINE.

This means that you must have CONNECTed to the other system, logged in, run

Kermit there, issued the SERVER command, and escaped back to the DEC-20.

The remote filespec is any string that can be a legal file specification for the remote system; it is not parsed or validated locally. If you need to in- clude otherwise illegal characters such as "!" or ";" (the normal command com- ment delimeters), "?" (the command help character), "@" (the indirect command file indicator), or certain control characters, then you should precede each

such character by a Control-V. Kermit-20 will discard these Control-V quoting prefixes before sending the file specification to the remote host.

If you want to store the incoming file name with a different name than the remote host sends it with, just type GET alone on a line; Kermit-20 will prompt you separately for the source (remote) and destination (local) file specifica- tion. If more than one file arrives, only the first one will be stored under the name given; the rest will be stored under the names they are sent with.

Example:

Kermit-20>get

Remote Source File: profile exec a1

Local Destination File: profile.exec

As files arrive, their names will be displayed on your screen, along with "." and "%" characters to indicate the packet traffic. As in the RECEIVE command, you may type Control-A to get a brief status report, ^X to request that the current incoming file be cancelled, ^Z to request that the entire incoming batch be cancelled.

_______________

8

not SERVER -- use the GET command to receive files from a Kermit server.

DECSYSTEM-20 KERMIT

Page 58

If the remote Kermit is not capable of server functions, then you will probably get an error message back from it like "Illegal packet type". In this case, you must connect to the other Kermit, give a SEND command, escape back, and give a RECEIVE command.

THE STATISTICS COMMAND

Give statistics about the most recent file transfer. For instance, here's what

Kermit-20 displayed after transmitting a short binary file, using repeated- character compression:

Maximum number of characters in packet: 80 received; 80 sent

Number of characters transmitted in 2 seconds

Sent: 34 Overhead: 34

Received: 107 Overhead: -408

Total received: 141 Overhead: -374

Total characters transmitted per second: 70

Effective data rate: 2570 baud

Efficiency: 214.1667 per cent

Interpacket pause in effect: 0 sec

Timeouts: 0

NAKs: 0

Note that the data compression allowed the effective baud rate to exceed the actual speed of the communication line, which in this case happened to be

1200 baud. The efficiency is displayed only if the actual baud rate is known.

6.5.2. Server Operation

THE SERVER COMMAND

The SERVER command puts a remote Kermit-20 in "server mode", so that it receives all further commands in packets from the local Kermit. The

Kermit-20 server is capable (as of this writing) of executing the following remote server commands: SEND, GET, FINISH, BYE, REMOTE DIRECTORY, REMOTE CWD, REMOTE

SPACE,

REMOTE DELETE, REMOTE TYPE, REMOTE HELP.

Any nonstandard parameters should be selected with SET commands before putting

Kermit-20 into server mode, in particular the file bytesize. The DEC-20

Kermit server can send most files in the correct manner automatically, by recognizing the DEC-20 file bytesize. However, if you need to ask the DEC-20 Kermit server to receive binary files from an 8-bit-byte system (that is, from almost any system that's not a DEC-10 or DEC-20) you must issue the SET FILE

BYTESIZE 8 command before putting it into server mode, and then you must only send

8-bit binary files. You cannot send a mixture of text files and 8-bit binary files to a Kermit-20 server.

DECSYSTEM-20 KERMIT

Page 59

COMMANDS FOR SERVERS

When running in local mode, Kermit-20 allows you to give a wide range of com- mands to a remote Kermit server, with no guarantee the that the remote server can process them, since they are all optional features of the protocol.

Com- mands for servers include the standard SEND, GET, BYE, and FINISH commands, as well as the REMOTE command.

Syntax: REMOTE command

Send the specified command to the remote server. If the server does not under- stand the command (all of these commands are optional features of the

Kermit protocol), it will reply with a message like "Unknown Kermit server command".

If does understand, it will send the results back, and they will be displayed on the screen. The REMOTE commands are:

CWD [directory] Change Working Directory. If no directory name is provided,

the server will change to the default or home directory.

Otherwise, you will be prompted for a password, and the server

will attempt to change to the specified directory.

The

password is entered on a separate line, and does not echo as

you type it. If access is not granted, the server will provide

a message to that effect.

DELETE filespec Delete the specified file or files. The names of the files

that are deleted will appear on your screen.

DIRECTORY [filespec]

The names of the files that match the given file specification

will be displayed on your screen, perhaps along with size and

date information for each file. If no file specification is

given, all files from the current directory will be listed.

HELP Provide a list of the functions that are available from the

server.

HOST [command] Pass the given command to the server's host command processor,

and display the resulting output on your screen.

SPACE Provide information about disk usage in the current directory,

such as the quota, the current storage, the amount of remaining

free space.

TYPE filespec Display the contents of the specified file on your screen.

6.5.3. Commands for Local File Management

Syntax: LOCAL [command]

Execute the specified command on the local system -- on the DEC-20 where

Kermit-20 is running. These commands provide some local file management capability without having to leave the Kermit-20 program.

CWD [directory] Change working directory, or, in DEC-20 terminology,

CONNECT to

the specified directory.

DECSYSTEM-20 KERMIT

Page 60

DELETE filespec Delete the specified file or files, but do not expunge them

(unless you have SET EXPUNGE ON).

DIRECTORY [filespec]

Provide a directory listing of the specified files.

RUN [filespec] Attempts to run the specified file, which must be in

".EXE"

format (.EXE is the default filetype), in an inferior fork.

Control returns to Kermit-20 when the program terminates.

Once

you have used this command, you can restart the same program by

issuing a RUN command with no arguments. If you RUN

SYSTEM:EXEC, then you will be able to issue TOPS-20 commands

without leaving Kermit; you can get back to Kermit from the

EXEC by typing the EXEC POP command.

SPACE Show how much space is used and remaining in the current direc-

tory.

TYPE Display the contents of the specified file or files at your

terminal. This works like the DEC-20 TYPE command, except that

if a file has a bytesize of 8, Kermit-20 will do 8-bit input

from it rather than 7-bit. Also, the DEC-20 Control-O command

discards output only from the file currently being displayed;

if multiple files are being typed, then output will resume with

the next file.

The LOCAL commands may also be used without the "LOCAL" prefix.

6.5.4. The CONNECT Command

Syntax: CONNECT [number]

Establish a terminal connection to the system connected to the octal TTY number

specified here or in the most recent SET LINE command, using full duplex echo- ing and no parity unless otherwise specified in previous SET commands. Get back to Kermit-20 by typing the escape character followed by the letter

C. The escape character is Control-Backslash (^\) by default. When you type the es- cape character, several single-character commands are possible:

C Close the connection and return to Kermit-20.

S Show status of the connection; equivalent to SHOW LINE.

P Push to a new Exec. POP from the Exec to get back to the connection.

Q If a session log is active, temporarily Quit logging.

R Resume logging to the session log.

B Send a simulated BREAK signal.

? List all the possible single-character arguments.

^\ (or whatever you have set the escape character to be):

Typing the escape character twice sends one copy of it to the connected

host.

You can use the SET ESCAPE command to define a different escape character, and

SET PARITY, SET DUPLEX, SET HANDSHAKE, SET FLOW, and SET SPEED to change those communication-line-oriented parameters. In order for the simulated BREAK sig- nal to work, TOPS-20 must know the speed of the terminal. If it does not, you may use the SET SPEED command. Type the SHOW LINE command for information

DECSYSTEM-20 KERMIT

Page 61 about your current communication settings.

Kermit-20 does not have any special autodialer interface. It assumes that the connection has already been made and the line assigned.

6.5.5. The SET, SHOW, and DEFINE Commands

SET is used for establishing or changing parameters, DEFINE lets you group several SET commands together into a single "macro" command, and SHOW lets you examine current settings or macro definitions.

THE SET COMMAND

Syntax: SET parameter [option [value]]

Establish or modify various parameters for file transfer or terminal connec- tion. You can examine their values with the SHOW command. The following parameters may be SET:

BREAK Adjust the BREAK simulation parameter

BLOCK-CHECK Packet transmission error detection method

DEBUGGING Record or display state transitions or packets

DELAY How long to wait before starting to send

DUPLEX For terminal connection, FULL or HALF

ESCAPE Character for terminal connection

FILE For setting file parameters like byte size

FLOW-CONTROL For enabling or disabling XON/XOFF flow control

HANDSHAKE For turning around half duplex communication line

IBM For communicating with an IBM mainframe

INCOMPLETE What to do with an incomplete file

INPUT For specifying behavior of the INPUT command

ITS-BINARY For recognizing a special 8-bit binary file format

LINE TTY line to use for file transfer or CONNECT

PARITY Character parity to use

PROMPT Change the program's command prompt

RECEIVE Various parameters for receiving files

RETRY How many times to retry a packet before giving up

SEND Various parameters for sending files

SPEED Baud rate of communication line

TVT-BINARY For negotiating binary mode on ARPANET

The DEFINE command may be used to compose "macros" by combining SET commands.

Those SET commands which differ from the "ideal" Kermit are now described in detail.

SET BREAK

Syntax: SET BREAK n Specify the number of nulls to be sent at 50 baud to simu- late a BREAK signal when connected to a remote host via SET LINE and

CONNECT.

DECSYSTEM-20 KERMIT

Page 62

SET DEBUG

Syntax: SET DEBUG options

Record the packet traffic, either on your terminal or in a file. Some reasons for doing this would be to debug a version of Kermit that you are working on, to record a transaction in which an error occurred for evidence when reporting bugs, or simply to vary the display you get when running Kermit-20 in local mode. Options are:

STATES Show Kermit state transitions and packet numbers (brief).

PACKETS Display each incoming and outgoing packet (lengthy).

OFF Don't display or record debugging information (this is the nor-

mal mode). If debugging was in effect, turn it off and close

any log file.

The debugging information is recorded in the file specified by the most recent

LOG DEBUGGING command, DEBUGGING.LOG by default.

SET ESCAPE

SET ESCAPE octal-number

Specify the control character you want to use to "escape" from remote connec- tions back to Kermit-20. The default is 34 (Control-\). The number is the oc- tal value of the ASCII control character, 1 to 37 (or 177), for instance

2 is

Control-B. After you type the escape character, you must follow it by a one of the single-character "arguments" described under the CONNECT command, above.

SET EXPUNGE

SET EXPUNGE ON or OFF

Tell whether you want a DELETE command (either the LOCAL DELETE command or a

REMOTE DELETE command sent to a Kermit-20 server) to expunge files as it deletes them. On the DEC-20, a deleted file continues to take up space, and may be "undeleted" at a later time in the same session. To expunge a deleted file means to remove it completely and irrevocably, freeing its space for fur- ther use. EXPUNGE is OFF by default; deleted files are not automatically ex- punged. SET EXPUNGE applies only to files that are deleted explicitly by

Kermit-20, and not to files that are implicitly deleted when new generations of existing files are created.

SET FILE

Syntax: SET FILE parameter keyword

Establish file-related parameters:

BYTESIZE keyword or number

Byte size for DEC-20 file input/output. The choices are

SEVEN (7),

DECSYSTEM-20 KERMIT

Page 63

EIGHT (8), and AUTO.

SEVEN (or 7) Always store or retrieve five 7-bit bytes per word.

When sending a file, ignore the file bytesize and do 7bit in-

put from the file. There would be no reason to use this option

except to explicitly force an 8-bit file to be treated as a

7-bit file.

EIGHT (or 8) Always store or retrieve four 8-bit bytes per word.

When sending a file, ignore the file bytesize and do 8bit in-

put from the file. This command is necessary when receiving

binary files from 8-bit-byte systems, such as most microcom-

puters.

AUTO Equivalent to SEVEN for incoming files, and for outgoing files

means to use EIGHT if the DEC-20 file bytesize (as shown by the

Exec VDIR command) is 8, otherwise use SEVEN. The default is

AUTO.

The DEC-20 can send any mixture of file types in the correct way

automatically, but you must set the file bytesize to 8 for any incoming

8-bit binary files, and to AUTO (i.e. 7) for any incoming text files or

DEC-20 binary files.

NAMING UNTRANSLATED or NORMAL-FORM

If NORMAL-FORM the names of incoming or outgoing files will be con-

verted to contain only uppercase letters, digits, and at most one

period; any other characters will be translated to "X". If

UNTRANS-

LATED, filenames will be sent and used literally. UNTRANSLATED is the

default.

SET IBM

Syntax: SET IBM ON or OFF

SET IBM is really a predefined SET macro rather than a "hardwired" SET command; it can be redefined or undefined (see DEFINE); as distributed from

Columbia,

Kermit-20 defines IBM to be "parity mark, handshake XON, duplex half".

SET IBM should be used when running Kermit-20 in local mode, connected to an

IBM or similar mainframe. If you have redefined the SET IBM macro, then your parameters will be used instead.

SET ITS-BINARY

Syntax: SET ITS-BINARY ON or OFF

Specify whether ITS-Binary file headers are to be recognized or ignored. By default, they are recognized. ITS binary format is a way (devised at

MIT) of storing foreign 8-bit binary data on a 36-bit machine to allow automatic recog- nition of these files when sending them out again, so that you don't have to depend on the file byte size, or to issue explicit SET FILE BYTESIZE commands to Kermit.

DECSYSTEM-20 KERMIT

Page 64

An ITS format binary file contains the sixbit characters "DSK8" leftadjusted in the first 36-bit word. If ITS-BINARY is ON, then Kermit-20 will send any file starting with this "header word" using 8-bit input from the file even if the file bytesize is not 8, and will not send the header word itself.

Kermit-20 will also store any incoming file that begins with that header word using 8-bit bytesize, again discarding the header word itself. If ITS-

BINARY is OFF, then the header word, if any, will be sent or kept, and i/o will be ac- cording to the setting of FILE BYTESIZE.

This facility is provided for compatibility with the file formats used on cer- tain public-access CP/M libraries.

SET INPUT

Syntax: SET INPUT parameter value

The INPUT command is used in TAKE command files or DEC-20 Batch control files as part of the login script facility, which is explained in greater detail later. SET INPUT controls the behavior of the INPUT command. The parameters are as follows:

SET INPUT DEFAULT-TIMEOUT n

n is the number of seconds for an INPUT command to time out after not

receiving the requested input, when no interval is explicitly given in

the INPUT command. For instance, if the default timeout interval is 10

seconds, then the command

INPUT login:

will look for the "login:" prompt for 10 seconds. The default may be

overriden by including an explicit interval in the INPUT command:

INPUT 15 login:

The default timeout interval is 5 seconds.

SET INPUT TIMEOUT-ACTION PROCEED or QUIT

If the INPUT command comes from a Kermit-20 command file

(see TAKE

command) or a TOPS-20 Batch control file, then use this command to

specify whether processing of the command file should proceed or quit

after a timeout occurs. For TAKE files, the current command file is

terminated and control returns to the invoking level (Kermit-20 prompt

level, or a superior TAKE file). The default action is PROCEED.

SET INPUT CASE IGNORE or OBSERVE

Specify whether alphabetic case should be ignored ("a" matches

"A") or

observed ("a" does not match "A") when scanning the input for the

specified search string. By default, aphabetic case is ignored.

SET INPUT commands are "global"; the settings are not "pushed" and

"popped" when entering or leaving TAKE command files.

DECSYSTEM-20 KERMIT

Page 65

SET LINE

Syntax: SET LINE [octal-number]

Specify the octal TTY number to use for file transfer or CONNECT. If you issue this command, you will be running Kermit-20 locally, and you must log in to the remote system and run Kermit on that side in order to transfer a file.

If you don't issue this command, Kermit-20 assumes it is running remotely, and does file transfer over its job's controlling terminal line. You can also select the line directly in the CONNECT command; the command

CONNECT 12 is equivalent to

SET LINE 12

CONNECT

If you type SET LINE with no number argument, you will deassign any previous assigned line and revert to remote mode.

The SHOW LINE command will display the currently selected communication line and its charactistics, including parity, duplex, handshake, flow control, the speed if known, whether carrier is present (if it is a modem-controlled line), and whether Kermit-20 is in local or remote mode.

SET RECEIVE

In addition to the full complement of SET RECEIVE commands described in the main part of the Kermit User Guide, you may also SET RECEIVE SERVER-

TIMEOUT to a value between 0 and 94. This specifies the number of seconds between timeouts during server command wait, 0 specifies that no timeouts should occur during server command wait. When a Kermit server times out, it sends a NAK packet. Some systems cannot clear piled-up NAKs from their input buffers; if

you're using such a system to communicate with a Kermit-20 server, and you ex- pect to be leaving the server idle for long periods of time, you should use this command to turn off server command-wait timeouts.

SET SPEED

Syntax: SET SPEED n

Set the baud rate of the currently selected communication to n, the decimal baud rate, for instance 300, 1200, 4800. When operating in local mode, it may be necessary to issue this command in order to enable BREAK simulation.

SET TVT-BINARY

Syntax: SET TVT-BINARY ON or OFF

Only for users running Kermit-20 on an ARPANET DEC-20, signed on to an

ARPANET virtual terminal (TVT) from another host or through an ARPANET TAC. SET

TVT ON causes Kermit-20 to negotiate binary mode (8-bit) communication with the AR-

DECSYSTEM-20 KERMIT

Page 66

PANET during file transfer. Without this command, file transfer through a TVT would not work in most cases.

TVT-BINARY is OFF by default. If you normally use Kermit-20 through the AR-

PAnet, you can put the command SET TVT-BINARY ON into your KERMIT.INI file.

CAUTION: This facility requires certain features in the Release 5 TOPS-

20 AR-

PANET monitor, which may not be present in releases distributed by

DEC. See the Kermit-20 source code for details.

THE DEFINE COMMAND

Syntax: DEFINE macroname [set-option [, set-option [...]]]

The DEFINE command is available in Kermit-20 for building "macros" of SET com- mands. The macro name can be any keyword-style character string, and the set options are anything you would type after SET in a SET command; several set op- tions may be strung together, separated by commas. Example:

define notimeout send timeout 0, receive timeout 0, receive server 0

Macro definitions may not include macro names. You can list all your macros and their definitions with the SHOW MACROS command. You can list a particular macro definition with HELP SET macroname.

THE SHOW COMMAND

Syntax: SHOW [option]

The SHOW command displays various information:

DAYTIME Current date, time, phase of moon.

DEBUGGING Debugging mode in effect, if any.

FILE-INFO Byte size for DEC-20 file i/o, incomplete file disposition.

INPUT INPUT command parameters.

LINE TTY line, parity, duplex, flow control, handshake, escape

character, speed (if known), and session loggin information.

Note that before release 6.0 of TOPS-20, the DEC-20 does not

keep a record of the actual baud rate of a modemcontrolled or

"remote" TTY line.

MACROS Definitions for SET macros.

PACKET-INFO For incoming and outbound packets. Items under RECEIVE column

show parameters for packets Kermit-20 expects to receive, under

SEND shows parameters for outgoing packets.

TIMING-INFO Delays, retries, server NAK intervals.

VERSION Program version of Kermit-20. This is also displayed when

DECSYSTEM-20 KERMIT

Page 67

Kermit-20 is initially started.

ALL (default) All of the above.

6.5.6. Program Management Commands

THE TAKE COMMAND

Syntax: TAKE filespec

Execute Kermit-20 commands from the specified file. The file may contain con- tain any valid Kermit-20 commands, including other TAKE commands; command files may be nested up to a depth of 20. Default file type for the command file is

.CMD.

THE ECHO COMMAND

Syntax: ECHO line of text

The line of text is echoed at the terminal. This is useful when issued from within TAKE command files, to report progress or issue instructions.

THE HELP COMMAND

Syntax: HELP [topic [subtopic]]

Typing HELP alone prints a brief summary of Kermit-20 and its commands.

You can also type

HELP command for any Kermit-20 command, e.g. "help send" or "help set parity" to get more detailed information about a specific command. Type

HELP ? to see a list of the available help commands.

THE EXIT AND QUIT COMMANDS

Syntax: EXIT

Exit from Kermit-20. You can CONTINUE the program from the TOPS-20

Exec, provided you haven't run another program on top of it. You can also exit from

Kermit-20 by typing one or more control-C's, even if it's in the middle of transferring a file. Kermit-20 will always restore your terminal to its original condition, and you will be able to CONTINUE the program to get back to

"Kermit-20>" command level with current settings intact.

QUIT is a synonym for EXIT.

DECSYSTEM-20 KERMIT

Page 68

THE LOG COMMAND

Syntax: LOG [option [filespec]]

Log the specified option to the specified file:

SESSION During CONNECT or execution of a login script, log all charac-

ters that appear on the screen to the specified file.

During

CONNECT, the session log can be temporarily turned off during

the remote session by typing the escape character followed by Q

(for Quit logging), and turned on again by typing the escape

character followed by R (for Resume logging). Default log is

SESSION.LOG in the current directory.

TRANSACTIONS During file transfer, log the progress of each file. The

DEC-20 transaction log file looks like this:

Kermit-20 Transaction Log File, Monday 27-Feb-1984

18:40:13: Opened Log: PS:<TIMREK>SAMPLE.LOG.1

18:40:31: -- Send Begins --

8th bit prefixing: Off

Block check type: 1

18:40:31: Opened File: PS:<SY.FDC>LOGIN.CMD.6

Sending As "LOGIN.CMD"

Sent: 547 7-bit bytes

18:40:34: Closed PS:<SY.FDC>LOGIN.CMD.6

18:40:34: Send Complete

18:40:50: -- Receive Begins --

8th bit prefixing: Off

Block check type: 1

18:40:50: Opened: PS:<TIMREK>AUTOEXEC.BAT.1

Written: 186 7-bit bytes

18:40:51: Closed: PS:<TIMREK>AUTOEXEC.BAT.1

18:40:56: Closed Transaction Log

Transaction logging is recommended for long or unattended file

transfers, so that you don't have to watch the screen.

The log

may be inspected after the transfer is complete to see what

files were transferred and what errors may have occurred.

Default log is TRANSACTION.LOG in the current directory.

DEBUGGING Log STATES or PACKETS, as specified in the most recent SET

DEBUGGING command, to the specified file. If log file not

specified, then use TTY if local, or DEBUGGING.LOG in the cur-

rent directory if remote. If no SET DEBUGGING command was

previously issued, log STATES to the specified file.

Also al-

low specification of bytesize for the log file, 7

(normal,

default), or 8 (for debugging binary transfers when the parity

bit is being used for data), for instance

LOG DEBUGGING BINARY.LOG 8

A 7-bit log file can be typed, printed, or examined with a text

editor or searching program. An 8-bit log file can only be ex-

amined with a system utility like FILDDT. When logging pack-

DECSYSTEM-20 KERMIT

Page 69

ets, each packet is preceded by a timestamp, the current

timeout interval (preceded by a slash), and "R:" or "S:" to in-

dicate data being received and sent, respectively.

Packet for-

mat is described in the Kermit Protocol Manual.

SESSION is the default option. Thus the command "LOG" alone will cause

CONNECT sessions to be logged in SESSION.LOG in the current directory. Any log files are closed when you EXIT or QUIT from Kermit, and are reactivated if you CON-

TINUE the program. You may explicitly close a log file and terminate logging with the CLOSE command.

THE CLOSE COMMAND

Syntax: CLOSE option

Close the specified log file, SESSION, TRANSACTION, or DEBUGGING, and terminate logging to that file.

6.6. Login Scripts: The INPUT, OUTPUT, CLEAR, and PAUSE Commands

When running Kermit-20 in local mode, connecting from the DEC-20 to another system via an external TTY line (for instance, through an autodialer), you may use the Kermit-20 INPUT, OUTPUT, CLEAR, and PAUSE commands to carry on a dialog with the remote system. When combined into a "script" in a Kermit-20

TAKE com- mand file, or included in a Batch control file, these commands provide the ability to initially connect and log in to a remote system, and to set it up for file transfer. While you may do this yourself manually using the

CONNECT command, the login script facility allows this often tedious task to be automated, and more important, allows it to take place unattended -- perhaps late at night when the phone rates are low and the system is faster.

During script execution, session logging may be used to record the dialog.

THE CLEAR COMMAND

Syntax: CLEAR

Clear the input and output buffers of the currently selected line, and attempt to clear any XOFF deadlock.

THE PAUSE COMMAND

Syntax: PAUSE [interval]

Pause the specified number of seconds before executing the next command.

The default interval is one second.

DECSYSTEM-20 KERMIT

Page 70

THE INPUT COMMAND

Syntax: INPUT [interval] [string]

On the currently selected communication line, look for the given string for the specified interval of time, which is specified in seconds. If no interval is specified, then wait for the default interval, which may be specified by SET

INPUT DEFAULT-TIMEOUT, and is normally 5 seconds. Specifying an interval of 0

(or less) means no timeout -- wait forever for the specified string. An

INPUT command can by interrupted by typing one or more Control-C's, which will return you to Kermit-20> prompt level.

Characters coming in from the line will be scanned for the search string, and when a match is found, the command will terminate successfully; if the string is not found within the given interval, the command will terminate unsuccess- fully. While the INPUT command is active, all incoming characters will appear on your screen.

The search string may contain any printable characters. Control or other spe- cial characters that you could not normally type as part of a command may be included by preceding their octal ASCII values with a backslash, for instance foo\15 is "foo" followed by a carriage return (ASCII 15, octal). A backslash alone will be taken as is, unless it is followed by an octal digit (0-

7); if you want to actually specify a backslash in this context, double the backslash

(\\5 will be taken as \5).

While scanning, alphabetic case is ignored ("a" = "A") unless you have

SET IN-

PUT CASE OBSERVE. If no search string is given, then the INPUT command will simply display all incoming characters on your screen until it times out or is interrupted.

If the INPUT command finds the specified string within the alloted amount of time, it terminates immediately, without an error message, and the next command will be executed. If the INPUT command fails to find the requested string, it will "fail"; failure is only significant if the command was issued from a TAKE command file or a Batch control file, and INPUT TIMEOUT-ACTION is SET to

QUIT.

When a timeout occurs under these conditions, the command file is immediately terminated and control is returned to the invoking level, either

Kermit-20> prompt level or a superior command file, and an error message is issued at the terminal which begins with a "?", which signals the Batch controller to detect an error. If INPUT TIMEOUT-ACTION is SET to PROCEED, then the next command (if any) will be executed from the current command file, and any timeout error mes- sages will be issued starting with a "%", which does not signal an error to

Batch.

In addition to otherwise untypable control characters (like Control-C), certain printable characters in the search string may need to be "quoted" using the backslash mechanism:

@ (ASCII 100) If it is the first character in the string, atsign tells

TOPS-20 that the following characters will be the name of an

indirect command file, for instance

input 10 @foo.txt

tells Kermit to spend 10 seconds scanning the communication

DECSYSTEM-20 KERMIT

Page 71

line input for the string which is contained in the file

FOO.TXT. If you need to specify a string that starts with "@",

use \100 instead.

? (ASCII 77) A question mark tells TOPS-20 to provide a brief help message

about this part of the command; use \77 instead.

! (ASCII 41) If it is the first character in the string, an exclamation

point will cause TOPS-20 to ignore the rest of the string, i.e.

treat it as a comment, use \41.

; (ASCII 73) Same as exclamation mark, use \73.

( (ASCII 50) In first position, TOPS-20 will think this marks the beginning

of a "guide word"; use \50.

- (ASCII 55) In final position, a dash tells TOPS-20 that the command line

is to be continued, concatenated with the following line.

Use

\55 instead of a final dash. For instance, to specify the

string "More?--", use "More\77-\55".

THE OUTPUT COMMAND

Syntax: OUTPUT string

The given string is sent out the currently selected communication line.

The string is in the same form as the INPUT string; control or special characters may be included by prefacing their octal ASCII value with a backslash.

Note that any terminating carriage return must be included explicitly as

\15. The string will also be echoed at your terminal.

HOW TO USE LOGIN SCRIPTS

Login scripts are useful on DEC-20's that have autodialers or TTY ports

hardwired or otherwise connected to terminal ports on other systems.

Scripts can be used to automate the task of connecting and logging in. For instance, suppose your DEC-20 is connected to a VAX Unix system through a hardwired line on TTY port 13. To send a file to the VAX, you must connect to the VAX through the port, log in, run Unix Kermit, escape back to the DEC-20, and issue the ap- propriate file transfer commands, then connect back to the VAX and logout.

This may all be automated by means of the following "script" stored in a

DEC-20 file invoked by the Kermit-20 TAKE command:

set line 13

output \15

input login:

out myuserid\15

in 10 Password:

out mypassword\15

in 20 %

out kermit -r\15

send foo.bar

out \4

input

DECSYSTEM-20 KERMIT

Page 72

The first line points Kermit-20 at the communication line. The next line sends a carriage return, which makes Unix issue a "login:" prompt; the following IN-

PUT command waits for this prompt to appear. When it does, Kermit-20 outputs

"myuserid" followed by a carriage return. Unix then prompts for a password; after the prompt appears, Kermit-20 supplies the password. Then,

Kermit-20 waits up to 20 seconds for the Unix shell's "%" prompt; this allows time for various system messages to be displayed. When the shell prompt appears,

Kermit-20 sends the command "kermit -r", which tells Unix Kermit to receive a file; then a SEND command is given to Kermit-20. After the file is success- fully transferred, Kermit-20 sends a logout command (Control-D, "\4") to

Unix.

The final INPUT command causes Kermit-20 to display any typeout (in this case the Unix system's logout message) that occurs up to the default timeout inter- val.

The INPUT command is very important, because it ensures synchronization.

One might expect to be able to simply send all the characters out the communication line at once, and let the remote host's typeahead and buffering facilities take care of the synchronization. In rare or simple cases, this might work, but it assumes that (a) the remote host allows typeahead, (b) the remote host's typeahead buffers are big enough to accommate all the characters, and

(c) that the remote host never clears pending typeahead. These conditions rarely hold.

For instance, Unix clears its input buffer after issuing the

"Password:" prompt; any typeahead will be lost. Interactive users as well as login script facilities must wait for the prompt before entering the password. This is the function of the INPUT command. On half duplex systems, this function is criti- cal -- these systems cannot accept any input in advance of a prompt; there is

no typeahead.

Note, by the way, that it is not a good idea to store passwords in plain text in a file. The facilities of the TOPS-20 command parser make this unnecessary, so long as you are sitting at your terminal. Suppose the above login script is stored in the file UNIX.CMD. If you change the line

out mypassword\15 to

out @tty: you may enter the password from your terminal as follows:

login: myuserid

Password: mypassword\15^Z

That is, you type the password, a backslash-encoded carriage return, and then

Control-Z. This may be done even when executing commands from a TAKE file; after the ^Z, control returns to the TAKE file. In the OUTPUT command,

"@TTY: designates TTY: (your job's controlling terminal) to be an indirect command file; the ^Z is the "end of file" for a terminal. This same technique could have been used in the first script example to allow you to supply from the ter- minal the name of the file to be sent. It might be a good idea to for you to include an ECHO command in your script file to remind you to do this, for in- stance:

input password:

echo ^GType your password, followed by "\15" and then a CTRL-Z

DECSYSTEM-20 KERMIT

Page 73

output @tty:

The ^G is a Control-G, which should get your attention by sounding a beep at your terminal.

One might expect to be able to use the same indirect file mechanism with the

OUTPUT command to provide a crude "raw upload" facility, as in

output @foo.bar to send the contents of the file FOO.BAR to the remote system, with no synchronization or error checking. Unfortunately, there are two problems with this approach: first, TOPS-20 converts all carriage return / linefeeds in an indirect command file to spaces, and second, only very short files may be treated this way, because they must fit within TOPS-20's command "atom" buffer.

The Kermit-20 TRANSMIT command provides a synchronized raw uploading of files.

The Kermit script facility is not a programming language; there is no con- ditional execution of commands, no branching, no labels. Nevertheless, the SET

INPUT command provides a degree of control. If the Unix system were down in the sample script above, Kermit-20 would still proceed merrily through the en- tire script, sending its output into the void and waiting the entire timeout interval on each INPUT command, then attempting to send a file to a

Kermit that wasn't there. It could take several minutes of timing out to terminate the script. This could be avoided by including the command

SET INPUT TIMEOUT-ACTION QUIT at the top of the script. When the "login:" prompt failed to appear within the timeout interval, the rest of the script would be cancelled.

Kermit-20's nested command file capability combined with input timeout action

selection can be used to provide a kind of "if-then-else" feature.

Suppose you want to log in automatically to a system which sometimes asks you a question immediately after you log in. You don't want to always include the answer

(say, "no") because if you type the string "no" at normal system command level, it performs some undesirable function. You can handle the situation by writing a script that invokes another script. In this example, the system's prompt is

"%" and the question's prompt ends in "?".

set input def quit

output \15

input login:

out myuserid\15

in 10 password:

echo Type your password now^G

out @tty:

take question

in %

out who\15

Here, after logging in successfully, the Kermit command file

QUESTION.CMD is invoked from within this fragment of the UNIX.CMD file; QUESTION.CMD looks like this:

input \77

DECSYSTEM-20 KERMIT

Page 74

output no\15

If the question mark appears, Kermit-20 will answer no. If not, a timeout will occur, and the current command file will be terminated without outputting the

"no", returning control to the command file that invoked it.

The Kermit script facility allows complicated tasks to be performed routinely, since any Kermit commands can be included in a command file. For instance, at

Columbia all systems are reached through a port contention unit, which prompts you for a system and then connects you to it. That system may itself be another "front end" which prompts you for yet another system. Each of these systems may have different characteristics as to duplex, parity, and so forth:

set parity none

set duplex full

set flow none

input =>

pause

output cuvm\15

input valid-sw-chars are A B

pause

output B\15

set duplex half

set parity mark

set handshake xon

output \15

input .\21

output login myuserid\15

input .\21

echo ^G Type your password, \15, ^Z

output @tty:

In this fragment, we talk full duplex no parity to the port switcher, select the "cuvm" front end, then select the "b" system, then switch to mark parity, half duplex, XON handshaking, for system B. Then we log in to the half duplex B system, which always issues a prompt of "." followed by an XON (^Q,

ASCII 21 octal) when it is ready for input. Note the judicious use of the PAUSE com-

mand, to give these often slow switching devices enough time to prepare them- selves for input; the fact that they have issued a prompt is not necessarily enough.

The script facility allows Kermit-20 to operate under TOPS-20 Batch.

This is desirable for performing routine file transfer late at night, when systems are not as busy and phone rates are lower. Without scripts, there is no good way to log in to the remote system without encountering the typeahead problems men- tioned above. Login scripts provide the necessary synchronization.

Suppose a

Columbia University professor is collaborating on a research project with a colleague at the University of Saskatchewan, and there is no network link be- tween the two machines, which are both DEC-20's. The researcher in

Saskatoon has left new data in the directory called <PROJECT>. The cost-conscious

Colum- bia professor leaves the following batch job to be executed after 3:00

A.M. (by using the DEC-20 SUBMIT/AFTER command), and then goes home.

@dial saskatchewan

*

*Kermit

DECSYSTEM-20 KERMIT

Page 75

*set input take-action quit

! Look for an atsign prompt

*input \100

! Log in

*output login myuserid mypassword\15

! Wait for atsign prompt

*in \100

! Start up a Kermit server

*out Kermit server\15

! Let it print its startup message

*set input take-action proceed

*input 10

*pause

! Get the files from the remote server

*get <project>*.*

! Shut down and log out the remote server

*bye

! Done with Kermit

*exit

! Let's see what new files we have.

@vdirectory *.*.0,

@since today

@

@

The next day, the batch log file can be examined to determine the progress of the batch job. If any errors occurred (the phone number could not be dialed, an INPUT command timed out), the error messages will cause the batch job to terminate. It is also possible to construct the batch control file to resubmit itself to run, say, an hour later if it fails.

In the example above, the "\100" specifies an atsign (@), which is the

DEC-20's prompt. It can't be written as an atsign in the INPUT command, however, be- cause in that context it would denote an indirect command file; this is where the backslash mechanism can come in handy. The "dial" command invokes a program that looks up its "argument" (Saskatchewan in this case) in a phone list, dials the corresponding number on an autodial modem, and then invokes

Kermit-20 in a lower fork with the correct line number already set.

INPUT and

OUTPUT commands are then used to log in and start up a Kermit server on the remote end and then normal Kermit commands (GET, BYE) are used to get the desired files and disconnect.

Dialing programs are highly site-dependent, and therefore cannot be made part of Kermit-20. However, a DEC-20 that has a dialout modem connected to one of its ports can be controlled directly by Kermit-20, if the user can assign the port. Suppose, for example, such a modem is connected to TTY6:, and accepts commands of the form +++Dnnnnnnn, where the +++ is a special sequence of characters to get the modem's attention, and which must be preceeded and fol- lowed by at least a full second of "silence", and D is a command to the modem to dial the following number (which ends with a carriage return). If the num- ber is dialed successfully and is answered by a carrier signal, then the modem replies "-X" (in upper case) and makes the connection, otherwise it replies

"-x" (lower case). The following script could be used with such a modem:

set input take quit

set input case observe

DECSYSTEM-20 KERMIT

Page 76

set line 6

pause 1

output +++

pause 1

output D5551212\15

input 30 -X

set input case ignore

output \15

Here, SET commands are used to achieve the desired effects -- if the number can't be dialed, or a confirmation is not returned, execution of the script will stop. PAUSE commands delimit the "+++" by the required amount of silence.

6.7. Raw Download and Upload

"Raw Download" is the term commonly used to describe the capture of a remote file on the local system, without any kind of error detection or correction.

This allows you to obtain files from remote systems that do not have

Kermit, but with the risk of loss or corruption of data.

Kermit-20 provides raw downloading via the LOG SESSION command during

CONNECT to a remote system. The session log is described above. To use session log- ging to capture a file:

1. Run Kermit on the DEC-20.

2. SET LINE to the TTY number through which you will be connected to

the remote system.

3. Perform any required SET commands to condition Kermit for communica-

tion with the remote system. You may need SET PARITY, SET

DUPLEX,

SET FLOW, SET HANDSHAKE, etc., depending on the characteristics of

the remote system and the communication medium.

4. CONNECT to the remote system and log in.

5. Condition your job on the remote system not to pause at the end of a

screenful of text, and give whatever commands may be necessary to

achieve a "clean" terminal listing -- for instance, disable messages

from the system or other users.

6. Type the appropriate command to have the desired file displayed at

the terminal, but do not type the terminating carriage return.

On

most systems, the command would be "type", on Unix it's "cat".

7. Escape back to Kermit to the DEC-20 and give the LOG SESSION com-

mand.

8. CONNECT back to the remote system and type a carriage return.

The

file will be displayed on your screen and recorded in the session

log file.

9. Escape back to Kermit on the DEC-20 and give the CLOSE SESSION com-

mand.

DECSYSTEM-20 KERMIT

Page 77

The file will be in SESSION.LOG in your connected directory, unless you gave another name for it in your LOG SESSION command. You will probably find that some editing necessary to remove extraneous prompts, messages, padding charac- ters, or terminal escape sequences, or to fill in lost or garbled characters.

Here's an example showing how to capture a file foo.bar from a remote

Unix sys- tem:

@kermit

Kermit-20>set line 23

Kermit-20>connect

[KERMIT-20: Connecting to remote host over TTY23:,

type <CTRL-\>C to return.]

4.2 BSD UNIX

login: myuserid

Password: mypassword

% cat foo.bar^\C

[KERMIT-20: Connection Closed]

Kermit-20>log session foo.bar

Kermit-20>connect

[KERMIT-20: Connecting to remote host over TTY23:,

type <CTRL-\>C to return.]

[KERMIT-20: Logging to File FOO.BAR.1]

(Type carriage return now.)

This is the file foo.bar.

It has three lines.

This is the last line.

% ^\

[KERMIT-20: Closing Log File FOO.BAR.1>

[KERMIT-20: Connection Closed]

Kermit-20>close session

Note that in this case, the Unix "% " prompt at the end of the text will have to be edited out.

RAW UPLOAD

"Raw Upload" means sending a file from the local system to a remote one, again without error detection or correction. This allows you to send files from the

DEC-20 to remote systems that don't have Kermit. Kermit-20 provides the

TRANS-

MIT command for this purpose.

Syntax: TRANSMIT filespec [prompt]

For use in local mode only. Sends the specified text file a line at a time,

"raw" (as is, without using Kermit protocol), to the remote system, waiting for the specified prompt for each line. Only a single file may be sent with the

TRANSMIT command; wildcards are not allowed in the filespec. The file should be a text file, not a binary file. Since protocol is not being used, no as- surance can be given that the file will arrive at the destination correctly or completely.

The prompt is any string, for instance the prompt of a line editor in text in- sertion mode. The prompt string may include special characters by preceding their octal ASCII values with a backslash, e.g. \12 for linefeed, \21 for XON

DECSYSTEM-20 KERMIT

Page 78

(^Q). The syntax of the prompt string is explained in greater detail above, with the INPUT command.

If a prompt string is supplied, alphabetic case will be ignored in searching for it unless you SET INPUT CASE OBSERVE. If a prompt string is not supplied, then linefeed will be used by default, unless you have performed a SET

HAND-

SHAKE command, in which case the current handshake character will be used. If you really want to send the entire file without waiting for any prompts, specify a prompt of "\0" (ASCII zero, null) (this is not advised).

The file will be sent using the current settings for duplex, parity, and flow control. There are no timeouts on input, as there are with the INPUT command.

The TRANSMIT command waits forever for the prompt to appear. However, if you observe that the transfer is stuck, there are three things you can do:

- Type a Carriage Return to transmit the next line.

- Type a Control-P to retransmit the line that was just transmitted.

- Type two Control-C's to cancel the TRANSMIT command and get back to

Kermit-20> command level.

TRANSMIT should be used as follows: CONNECT to the remote system, login, and start up some kind of process on the remote system to store input from the ter- minal into a file. On a DEC-20 (that doesn't have Kermit), you could do

copy tty: foo.bar or you could start a line editor like EDIT or OTTO and put it into text inser- tion mode. On a Unix system, you could

cat /dev/tty > foo.bar or you could run "ed" and give it the "a" command.

The Kermit-20 TRANSMIT command will send the first line of the file im-

mediately. Then it will wait for a "prompt" from the remote system before sending the next line. When performing a copy operation from the terminal to a file, the "prompt" will probably be a linefeed, "\12" which is the default prompt -- most full duplex systems expect you to type a line of text terminated by a carriage return; they echo the characters you type and then output a linefeed. Half duplex systems, on the other hand, use some kind of line tur- naround handshake character, like XON (Control-Q), to let you know when they are ready for the next line of input. Line editors like EDIT and OTTO prompt you with a line number followed by a tab; in that case your prompt character would be "\11" (be careful -- if the remote DEC-20 doesn't think your terminal has hardware tabs, it will simulate them by outputting spaces). In any case, to assure synchronization, it is your responsibility to set up the target sys- tem to accept line-at-a-time textual input and to determine what the system's prompt will be when it is ready for the next line.

Each line is sent with a terminating carriage return; linefeeds are not sent, since these are supplied by the receiving system if it needs them. The

TRANS-

MIT command continues to send all the lines of the file in this manner until it reaches the end, or until you interrupt the operation by typing Control-

C's.

DECSYSTEM-20 KERMIT

Page 79

If you cannot make the TRANSMIT command work automatically, for instance be- cause the remote system's prompt changes for each line, you may

TRANSMIT manually by specifying a prompt string that will not appear, and then typing a carriage return at your keyboard for each line you want to send.

If the TRANSMIT command completes successfully (you'll get a message to the ef- fect that the transmission is complete), then you must connect back to the remote system and type whatever command it needs in orderto save and/or close the file there.

6.8. Kermit-20 Examples

Here are a few examples of the use of Kermit-20. Text entered by the user is underlined.

REMOTE OPERATION

The following example shows use of Kermit-20 as a server from an IBM

PC. In this example, the user runs Kermit on the PC, connects to the DEC-

20, and starts Kermit-20 in server mode. From that point on, the user need never con- nect to the DEC-20 again. In this example, the user gets a file from the

DEC-20, works on it locally at the PC, and then sends the results back to the

DEC-20. Note that the user can leave and restart Kermit on the PC as often as desired.

A>Kermit

Kermit-MS>connect

@

@Kermit

TOPS-20 Kermit version 4.2(257)

Kermit-20>server

Kermit Server running on DEC-20 host. Please type your escape

sequence to return to your local machine. Shut down the server by

typing the Kermit BYE command on your local machine.

^[C

Kermit-MS>get foo.txt

The transfer takes place.

Kermit-MS>exit

A>

A>edit foo.txt ; (or whatever...)

A>

A>Kermit

Kermit-MS>send foo.txt

The transfer takes place.

Kermit-MS>bye

A>

The next example shows the special procedure you would have to use in order to send a mixture of text and binary files from a PC (or an 8-bit-byte system) to the DEC-20. Note that in this case, it's more convenient to avoid server mode.

DECSYSTEM-20 KERMIT

Page 80

Kermit-MS>connect

@

@Kermit

TOPS-20 Kermit version 4.2(257)

Kermit-20>receive

^]C

Kermit-MS>send *.txt

Textual files are sent.

Kermit-MS>connect

Kermit-20>set file bytesize 8

Kermit-20>receive

^]C

Kermit-MS>send *.exe

Binary files are sent.

Kermit-MS>connect

Kermit-20>exit

@logout

^]C

Kermit-86>exit

A>

LOCAL OPERATION

In this example, a program DIAL is used to direct an autodialer to call another computer (a DECsystem-10); once the connection is made, DIAL starts

Kermit with an implicit CONNECT command for the appropriate communication line.

DIAL is not part of Kermit; if your system has an autodialer, there will be some site- specific procedure for using it.

@dial

Dial>dial stevens

STEVENS, 1-(201) 555-1234, baud:1200

[confirm]

Dialing your number, please hold...

Your party is waiting on TTY11:.

@

@Kermit

TOPS-20 Kermit version 4.2(257)

Kermit-20>connect 11

[Kermit-20: Connecting over TTY11:, type <CTRL-\>C to return]

CONNECTING TO HOST SYSTEM.

Stevens T/S 7.01A(10) 20:20:04 TTY41 system 1282

Connected to Node DN87S1(101) Line # 57

Please LOGIN or ATTACH

.log 10,35

JOB 51 Stevens T/S 7.01A(10) TTY41

Password:

20:20 15-Dec-83 Thur

DECSYSTEM-20 KERMIT

Page 81

.r new:Kermit

TOPS-10 Kermit version 2(106)

Kermit-10>server

[Kermit Server running on the DEC host. Please type your escape

sequence to return to your local machine. Shut down the server by

typing the Kermit BYE command on your local machine.]

^YC

[Kermit-20: Connection Closed. Back at DEC-20.]

Kermit-20>set file bytesize 8

Kermit-20>get setdtr.cmd

^A for status report, ^X to cancel file, ^Z to cancel batch.

SETDTR.CMD.7 ^A

Receiving SETDTR.CMD.7, file bytesize 8

(repeated character compression)

At page 1

Files: 0, packets: 1, chars: 66

NAKs: 0, timeouts: 0

.[OK]

Kermit-20>bye

Job 51 User F DA CRUZ [10,35]

Logged-off TTY41 at 20:22:58 on 15-Dec-83

Runtime: 0:00:01, KCS:33, Connect time: 0:02:39

Disk Reads:72, Writes:4, Blocks saved:160

....

Hangup? y

Click. Call duration was 193 seconds to area 201.

Dial>exit

Note the use of Control-A to get a status report during the transfer.

6.9. Installation of Kermit-20

Kermit-20 is built from a single MACRO-20 source file, K20MIT.MAC. It requires the standard DEC-distributed tools MONSYM, MACSYM, and CMD; the following files should be in SYS: -- MONSYM.UNV, MACSYM.UNV, MACREL.REL, CMD.UNV, and

CMD.REL.

The CMD package is also included with the Kermit distribution as

K20CMD.*, in case you can't find it on your system.

The program should work on all TOPS-20 systems as distributed, but many cus-

tomizations are possible. The site manager may wish to change various default parameters on a site-wide basis; this may be done simply by changing the definitions of the desired symbols, under "subttl Definitions", and reassem- bling.

The most notable site dependency is the definition of "SET IBM".

As dis- tributed from Columbia, Kermit-20 defines "SET IBM" in a built-in SET macro definition as "parity mark, duplex half, handshake xon". This definition may be found at MACTAB+1, near the end of the impure data section. It may be changed or deleted, and the program reassembled.

DECSYSTEM-20 KERMIT

Page 82

Sites that do not have ARPANET may wish to delete the TVT-BINARY entries from

SET command tables, SETABL and SETHLP.

VAX/VMS KERMIT

Page 83

7. VAX/VMS KERMIT

Authors: Robert C. McQueen, Nick Bush, Stevens Institute of Technology

Language: BLISS-32

Version: 3.2

Date: May 6, 1986

VAX/VMS Kermit-32 Capabilities At a Glance:

Local operation: Yes

Remote operation: Yes

Transfers text files: Yes

Transfers binary files: Yes

Wildcard send: Yes

^X/^Y interruption: Yes

Filename collision avoidance: Yes

Timeouts: Yes

8th-bit prefixing: Yes

Repeat character compression: Yes

Alternate block check types: Yes

Communication settings: Yes

Transmit BREAK: No

IBM mainframe communication: Yes

Transaction logging: Yes

Session logging: Yes

Debug logging: Yes

Raw transmit: No

Login scripts: No

Act as server: Yes

Talk to server: Yes

Advanced commands for servers: Yes

Local file management: Yes

Command/init files: Yes

Attribute packets: No

Kermit-32 is a program that implements the Kermit file transfer protocol for the Digital Equipment Corporation VAX series computers under the

VAX/VMS operating system. It is written in BLISS-32 and MACRO-32, with sources for all

BLISS modules also available as MACRO-32 sources. Kermit-32 should run on any

VAX/VMS system from version 3 on (Version 3.1 of Kermit-32 corrected some problems that appeared in earlier versions when run under VMS version 4).

The first section of this chapter will describe the things you need to know

about the VAX/VMS file system and how Kermit-32 uses it. The second section describes the special features of Kermit-32. The final section contains infor- mation of interest to those who need to install Kermit-32 on a system.

VAX/VMS KERMIT

Page 84

7.1. The VAX/VMS File System

The two main items of interest of the VAX/VMS file system (for the Kermit user) are the format of file specifications and the types of files and file data.

VAX/VMS File Specifications

VAX/VMS file specifications are of the form

NODE::DEVICE:[DIRECTORY]NAME.TYPE;VERSION

Under version 3.x of VMS, NAME may be up to 9 characters, TYPE may be up to 3 characters and each item in DIRECTORY may be up to 9 character long.

Only al- phanumeric characters may be used in DIRECTORY, NAME and TYPE.

VERSION is a decimal number indicating the version of the file (generation). DEVICE may be either a physical or logical device name. If it is a logical name, it may be up to 63 characters long and may contain alphanumeric characters plus dollar signs and underscores. NODE may be either a logical name which translates to a

DECnet node name or a physical DECnet node name. In either case, access infor- mation can be included (see the DECnet-VMS User's guide for more information).

The node name is not normally present, since most files are accessed on the same node where the user's job is running. The version number is not normally given (in fact, should not normally be given). When device and/or directory are not supplied, they default to the user's current default device and direc- tory. Therefore, NAME.TYPE is normally all that is needed to specify a file on the user's default device and directory. This is also all the Kermit-

32 will normally send as the name of a file being transferred.

The node field specifies the name (and access information) for the DECnet node where the file is located. Kermit-32 does not transmit the node field to the

target system, but will attempt to honor a node field in an incoming file name.

The device field specifies a physical or "logical" device upon which the file is resident. The directory field indicates the area on the device, for in- stance the area belonging to the owner of the file. Kermit-32 does not nor- mally transmit the device or directory fields to the target system, but will attempt to honor device or directory fields that may appear in incoming file names. It will not create new directories, however, so any directory must al- ready exist.

The name is the primary identifier for the file. The type, also called the

"extension", is an indicator which, by convention, tells what kind of file we have. For instance FOO.FOR is the source of a Fortran program named

FOO;

FOO.OBJ might be the relocatable object module produced by compiling

FOO.FOR;

FOO.EXE could an executable program produced by LINKing FOO.REL, and so forth.

VAX/VMS allows a group of files to be specified in a single file specification by including the special "wildcard" characters, "*" and "%". A "*" matches any string of characters, including no characters at all; a "%" matches any single character. Here are some examples:

*.FOR All files of type FOR (all Fortran source files) in the default direc-

tory.

FOO.* Files of all types with name FOO.

VAX/VMS KERMIT

Page 85

F*.* All files whose names start with F.

F*X*.* All files whose names start with F and contain at least one X.

%.* All files whose names are exactly one character long.

*.%%* All files whose types are at least two characters long.

Wildcard notation is used on many computer systems in similar ways, and it is the mechanism most commonly used to instruct Kermit to send a group of files.

TEXT FILES AND BINARY FILES

The file system used by VAX/VMS provides for a large number of attributes to be associated with each file. These attributes provide some indication of whether the file is a text file, or is some other type of non-text data. The two major attributes that affect Pro/Kermit are the record type and record attribute.

The record type describes how logical records are stored in the file.

Records may be of some fixed length (specified by another attribute), or variable length (specified within each record), or stream (implying no real record divisions). The record attributes describe how the breaks between records are to be treated. For example, a record attribute of implied carriage return means that any program reading the file with intentions of printing it out should add a carriage return/line feed sequence between each record.

Other at- tributes include FORTRAN carriage control and print file format.

The "standard" method of storing text in a file under VAX/VMS is to store one line of text per record (variable length records), with a carriage return/line feed sequence implied by the end of the record (implied carriage return).

This is the method Kermit-32 uses to store files it receives when using

FILE TYPE

TEXT. Note that there are other formats which are used to store text under

VAX/VMS, however, the one used be Kermit-32 is the only one which is handled correctly by all known utility programs under VAX/VMS. Also, most programs which work with text files (the editor EDT, for example) place some limit on the length of the lines which can be handled. Typically this is

255.

Kermit-32 can write files with up to 4095 characters on a line, which means a text file from another system may be transferred and stored correctly by

Kermit-32, but may still be unusable by certain VAX/VMS programs.

There is no standard format for storing binary files. Basically, any record format with no record attributes are used for binary files. Since programs which work with binary files under VAX/VMS expect to see some particular for- mat, more infomation is needed for transfer of binary files than for transfer of text files. The current version of Kermit-32 is not capable of transferring all types of binary files which were created on a VAX/VMS system to another system and retrieving them intact, nor is it capable of transferring all of types binary files created on a VAX/VMS system to another VAX/VMS,

P/OS, or

RSX-11M/M+ system intact. However, certain formats of binary files can be transferred, and binary files from some other systems may be transferred to a

VAX and recovered intact.

Binary files which are created on a VAX (or other Files-11 systems) with fixed

512 byte records (a fairly common format) can be transferred using

Kermit-32.

The only required action is to set the file type to "fixed" in the receiving

Kermit-32.

VAX/VMS KERMIT

Page 86

Using two programs supplied with Kermit-32, it is possible to transfer almost any type of sequential file between VAXen, or between a VAX and a

P/OS or

RSX-11M/M+ system. These two programs (VMSHEX and VMSDEH) will convert the bi- nary files to text (using a variation on Intel hex format). The resulting text file can be transferred like any other, and finally "dehexified" reproducing the original file, with the major attributes intact. Unfortunately, the text files tend to be about twice the size of the original binary files, so the transfers take a bit longer than regular text files. On the plus side, the text versions of the files can be transferred to any system with a

Kermit and still retrieved intact. They can also be transferred over 7-bit data paths without any problems. The bootstrap procedure (described below), makes use of hexified versions of the binary file which makes up Kermit-32.

USING THE VAX TO ARCHIVE MICROCOMPUTER FILES

You can use Kermit to send textual files from a microcomputer or any 8bit sys- tem to a VAX/VMS system with no special provisions, since Kermit-32 stores in- coming files as text files (variable length records with implied carriage returns) unless it is explicitly told otherwise. But Kermit-32 has no automatic way of distinguishing an incoming binary file from an incoming text file. It turns out that because of the method used by Kermit-32 for storing text files, a binary file can be stored like a text file so long as it does not contain a string of more than 4095 characters between carriage return, line feed sequences, and ends with a carriage return line feed. Since most binary files do not have these characteristics, you must inform Kermit-32 that a file it is about to receive is to be stored as a binary file. This is done using

the SET FILE TYPE BINARY command. This instructs Kermit-32 to store the data it receives in the file without checking for carriage return, line feed se- quences. The file it creates will be variable record length, with no record attributes. Each record will contain 510 bytes of data, except the last, which will contain whatever amount is left before the end of the file. This allows

Kermit-32 to correctly return exactly the data it was sent when the file is returned to the original system.

Note that because of the need to use a different file type for binary files, it is not possible to use a "wildcard send" command to send a mixture of text and binary files to a VAX system unless the text files are not intended for use on the VAX; rather, you must send all text files with Kermit-32's file type set to text, and all binary files with the file type set to binary.

Once you get the foreign file into the VAX system, stored with the correct file type, you need take no special measures to send it back to its system of origin. This is because Kermit-32 honors the record type and attributes of the file as it is stored on the VAX. In fact, SET FILE TYPE BINARY or

TEXT only affects how Kermit-32 receives files - it does not affect how Kermit-32 trans- mits files.

VAX/VMS KERMIT

Page 87

FILES KERMIT-32 CANNOT HANDLE

The Kermit protocol can only accommodate transfer of sequential files, files which are a linear sequence of bytes (or words).

Some files on a VAX/VMS system are not sequential, and cannot be successfully sent or received by Kermit-32. These are mainly indexed data files, but can also include other files which require more than just the data in the file to be completely reconstructed. External control information and file attributes are not transmitted.

7.2. Program Operation

Kermit-32's prompt is normally "Kermit-32>". If a foriegn command is defined to run Kermit-32 (eg. KERMIT := $KERMIT), Kermit-32 will accept a single com- mand on the command line, like this:

$

$ Kermit send foo.bar

the file is sent

$

$ MCR Kermit send foo.bar

the file is sent

$

You can run the program interactively to issue several commands, like this:

$

$ Run SYS$SYSTEM:Kermit

VMS Kermit-32 version 3.2

Default terminal for transfers is: _TTA1:

Kermit-32>send foo.*

files are sent

Kermit-32>statistics

performance statistics are printed

Kermit-32>receive

files are received

Kermit-32>exit

$

Command keywords may be abbreviated to their shortest prefix that sets them apart from any other keyword valid in that field.

Kermit-32 provides most of the commands possible for an "ideal" Kermit program,

VAX/VMS KERMIT

Page 88 as described in the main part of the Kermit User Guide. The following sections will concentrate on system-dependent aspects of Kermit-32.

7.3. Conditioning Your Job for Kermit

Kermit-32 does as much as it can to condition your line for file transfer. It saves all your terminal settings, and restores them after use. However, there are some sources of interference over which Kermit-32 has no control.

In par- ticular, messages issued by other processes in your job could become mingled with Kermit packets and slow things down or stop them entirely.

This is a fairly rare occurance and can be easily avoided by not running any other process which wishes to perform I/O to your terminal while you are running

Kermit-32.

Normally, when Kermit-32 is run, it assumes you wish to use it in remote mode and perform file transfers over the terminal line which controls your job.

This can be overridden, however, by defining a logical name which equates to some other terminal line in the system. The default terminal line to be used for file transfers is determined by the first of the following logical names which translates to a terminal line which is available for use by your process:

KER$COMM, SYS$INPUT, SYS$OUTPUT, and SYS$COMMAND. If none of these logical names translate to an available terminal line, there is no default terminal line and a SET LINE command must be used before any transfer command is per- formed. Note that this is the typical case in a batch job.

Kermit-32 will also default the type of parity to be used on the communication line to that which is set on its default terminal line when it is started.

This means that if all communication at a site is normally done using even parity (for example), Kermit-32 will also use even parity.

There are two things to keep in mind when using Kermit-32 in local mode

(where the file transfers are done over a different terminal line from where commands are typed):

- Under VAX/VMS, every terminal line has an owner UIC and protection

code associated with it. This UIC and protection is used to deter-

mine who can allocate (and therefore use) the terminal line when they

are not logged in on that line. Therefore, in order for Kermit-32 to

be able to perform file transfers over a terminal line other than the

one on which you are logged in, the field of the protection code for

the terminal which applies to your job (based on your UIC and the

owner UIC of the terminal) must allow your job access to the ter-

minal. You may need to request your system manager to change the

protection for a terminal line to allow you to use it with Kermit-

32

in local mode.

- Terminal lines which have been declared as modem control lines will

have the phone "hung up" whenever the terminal line becomes free

(deallocated). This means that if you do not use the DCL

ALLOCATE

command to allocate the terminal line to your job before entering

Kermit-32, exiting Kermit-32 will cause the terminal line to

"hang

up" the modem. If you do wish to get to DCL after having used

Kermit-32 to connect a modem control line which you do not have al-

located, you can use the PUSH command to spawn a subprocess running

DCL.

VAX/VMS KERMIT

Page 89

7.4. Kermit-32 Commands

This section describes the Kermit-32 commands -- in detail where they differ from the "ideal" Kermit, briefly where they coincide. Kermit-32 has the fol- lowing commands:

@ synonym for "take".

BYE to remote server.

CONNECT as terminal to remote system.

EXIT from Kermit-32.

FINISH Shut down remote server.

GET remote files from server.

HELP with Kermit-32.

LOCAL prefix for local file management commands.

LOG remote terminal session.

LOGOUT remote server.

PUSH to DCL command level.

QUIT from Kermit-32.

RECEIVE files from remote Kermit.

REMOTE prefix for remote file management commands.

SEND files to remote Kermit.

SERVER mode of remote operation.

SET various parameters.

SHOW various parameters.

STATISTICS about most recent file transfer.

TAKE Kermit-32 commands from a file.

7.4.1. Commands for File Transfer

Kermit-32 provides the standard SEND, RECEIVE, and GET commands for transfer- ring files using the Kermit protocol.

THE SEND COMMAND

Syntax:

Sending a file or files:

SEND filespec

The SEND command causes a file or file group to be sent from the VAX to the other system. If filespec contains wildcard characters then all matching files

will be sent, in alphabetical order (according to the ASCII collating sequence) by name. If filespec does not contain any wildcard characters, then the single file specified by filespec will be sent.

SEND Command General Operation:

Files will be sent with at least their VAX/VMS file name and type (for instance

FOO.BAR). If a SET FILE NAMING FULL command has been given, Kermit-32 will also send the device name, directory name and version number (for instance

USER$DISK:[JOE]FOO.BAR;25). If a SET FILE NAMING UNTRANSLATED command has been given, Kermit-32 will send the file name, type and version number (for instance

VAX/VMS KERMIT

Page 90

FOO.BAR;25). If a SET FILE NAMING NORMAL_FORM command has been given

(this is the initial default), Kermit-32 will only send the file name and type.

Each file will be sent according to the record type and attributes recorded in its file descriptor. Kermit-32 attempts to translate all formats of text file

(including those with FORTRAN or print carriage control) to a format usuable on any system. Note that there is no need to set the FILE TYPE parameter for sending files, since Kermit-32 always uses the information from the file descriptor to determine how to send the file.

If communication line parity is being used (see SET PARITY), Kermit-32 will re- quest that the other Kermit accept a special kind of prefix notation for binary files. This is an advanced feature, and not all Kermits have it; if the other

Kermit does not agree to use this feature, binary files cannot be sent cor- rectly. This includes executable programs (like .EXE files, CP/M .COM files), relocatable object modules (.OBJ files), as well as any text file containing characters with the eighth bit on.

Kermit-32 will also ask the other Kermit whether it can handle a special prefix encoding for repeated characters. If it can, then files with long strings of repeated characters will be transmitted very efficiently. Columnar data, highly indented text, and binary files are the major beneficiaries of this technique.

If you're running Kermit-32 locally, for instance dialing out from a

VAX to another system using an autodialer, you should have already run Kermit on the remote system and issued either a RECEIVE or a SERVER command. Once you give

Kermit-32 the SEND command, the name of each file will be displayed on your screen as the transfer begins. If the file is successfully transferred, you

will see "[OK]", otherwise there will be an error message.

During local operation, you can type Control-A at any point during the transfer to get a brief status report. You may also type Control-X or Control-Z to in- terrupt the current file or file group.

THE RECEIVE COMMAND

Syntax: RECEIVE [filespec]

The RECEIVE command tells Kermit-32 to receive a file or file group from the other system. If only one file is being received, you may include the optional filespec as the name to store the incoming file under; otherwise, the name is taken from the incoming file header. If the name in the header is not a legal

VAX/VMS file name, Kermit-32 will normally replace the illegal characters with

"X" (see SET FILE NAMING NORMAL_FORM).

If an incoming file has the same name as an existing file, Kermit-32 just creates a new version of the same name and type, for instance

FOO.BAR;3,

FOO.BAR;4.

Incoming files will all be stored with the prevailing file type,

ASCII by default, which is appropriate for text files. If you are asking

Kermit-32 to receive binary files from a microcomputer or other 8-bit system, you must first type SET FILE TYPE BINARY. Otherwise, an error may occur when receiving the file, or a carriage return, line feed will be added to the end of the file and

VAX/VMS KERMIT

Page 91 the file will be useless when sent back to the system of origin.

If parity is being used on the communications line, then 8th-bit prefixing will be requested. If the other side cannot do this, binary files cannot be trans- ferred correctly.

If an incoming file does not arrive in its entirety, Kermit-32 will normally discard it; it will not appear in your directory. You may change this behavior by using the command SET INCOMPLETE KEEP, which will cause as much of the file as arrived to be saved in your directory.

If you are running Kermit-32 locally, you should already have issued a

SEND

9 command to the remote Kermit, and then escaped back to Kermit-32. As files arrive, their names will be displayed on your screen. You can type

Control-A during the transfer for a brief status report.

If a file arrives that you don't really want, you can attempt to cancel it by typing Control-X; this sends a cancellation request to the remote Kermit.

If the remote Kermit understands this request (not all implementations of

Kermit support this feature), it will comply; otherwise it will continue to send. If a file group is being sent, you can request the entire group be cancelled by typing Control-Z.

THE GET COMMAND

Syntax: GET [remote-filespec]

The GET command requests a remote Kermit server to send the file or file group specified by remote-filespec. This command can be used only when

Kermit-32 is local, with a Kermit server on the other end of the line specified by SET

LINE.

This means that you must have CONNECTed to the other system, logged in, run

Kermit there, issued the SERVER command, and escaped back to the VAX.

The remote filespec is any string that can be a legal file specification for the remote system; it is not parsed or validated locally. Any leading spaces before the remote filespec are stripped, and lower case characters are raised to upper case.

As files arrive, their names will be displayed on your screen. As in the

RECEIVE command, you may type Control-A to get a brief status report, ^X to re- quest that the current incoming file be cancelled, ^Z to request that the en- tire incoming batch be cancelled.

If the remote Kermit is not capable of server functions, then you will probably get an error message back from it like "Illegal packet type". In this case, you must connect to the other Kermit, give a SEND command, escape back, and give a RECEIVE command.

_______________

9

not SERVER -- use the GET command to receive files from a Kermit server.

VAX/VMS KERMIT

Page 92

THE STATISTICS COMMAND

Give statistics about the most recent file transfer.

THE TAKE COMMAND

Syntax: TAKE filespec

The TAKE command tells Kermit-32 to execute commands from the specified file.

You may also use the VMS notation "@" to specify a command file.

7.4.2. Server Operation

THE SERVER COMMAND

The SERVER command puts a remote Kermit-32 in "server mode", so that it receives all further commands in packets from the local Kermit. The

Kermit-32 server is capable (as of this writing) of executing the following remote server commands: SEND, GET, FINISH, BYE, REMOTE DIRECTORY, REMOTE CWD, REMOTE

SPACE,

REMOTE DELETE, REMOTE TYPE, REMOTE HELP, REMOTE COPY, REMOTE RENAME,

REMOTE

SEND_MESSAGE, REMOTE WHO, and REMOTE HOST.

Any nonstandard parameters should be selected with SET commands before putting

Kermit-32 into server mode, in particular the file type. The Kermit-32 server can send all files in the correct manner automatically. However, if you need to ask Kermit-32 to receive binary files you must issue the SET FILE

TYPE BI-

NARY command before putting it into server mode, and then you must only send binary files. You cannot send a mixture of text files and 8-bit binary files to a Kermit-32 server unless the files are not for use on the VAX.

COMMANDS FOR SERVERS

When running in local mode, Kermit-32 allows you to give a wide range of com-

mands to a remote Kermit server, with no guarantee the that the remote server can process them, since they are all optional features of the protocol.

Com- mands for servers include the standard SEND, GET, BYE, LOGOUT and FINISH com- mands, as well as the REMOTE command.

Syntax: REMOTE command

Send the specified command to the remote server. If the server does not under- stand the command (all of these commands are optional features of the

Kermit protocol), it will reply with a message like "Unknown Kermit server command".

If does understand, it will send the results back, and they will be displayed on the screen. The REMOTE commands are:

COPY filespec Copy file. The server is asked to make a copy of the specified

file. Kermit-32 will prompt for the new file name on a

separate line. Both filespecs must be in the correct format

for the remote system. Kermit-32 does not parse or validate

the file specifications. Any leading spaces will be stripped

and lower case characters converted to upper case. Note that

VAX/VMS KERMIT

Page 93

this command simply provides for copying a file within the

server's system - it does not cause a file to be transferred.

CWD [directory] Change Working Directory. If no directory name is provided,

the server will change to the default or home directory.

Otherwise, you will be prompted for a password, and the server

will attempt to change to the specified directory.

The

password is entered on a separate line, and does not echo as

you type it. If access is not granted, the server will provide

a message to that effect. Note that while not all server

Ker-

mits require (or accept) a password to change the working

directory, Kermit-32 will always ask for one when a directory

name is provided.

DELETE filespec Delete the specified file or files. The names of the files

that are deleted will appear on your screen.

DIRECTORY [filespec]

The names of the files that match the given file specification

will be displayed on your screen, perhaps along with size and

date information for each file. If no file specification is

given, all files from the current directory will be listed.

DISK_USAGE [directory]

Display information about disk usage in the given directory (or

by the given user). If no directory is provided, disk usage

information is provided for the current working directory (or

user). This is the same as the REMOTE SPACE command.

EXIT Requests the server to leave Kermit, allowing the terminal to

be used for normal commands.

FINISH Requests the server to return to the Kermit prompt, allowing

statistics to be obtained about the transfers.

HELP [topic] Provide information about the given topic. If no topic is

given, provide a list of the functions that are available from

the server. Some servers may ignore the topic and always dis-

play the same information.

HOST [command] Pass the given command to the server's host command processor,

and display the resulting output on your screen.

LOGIN user-id Supply information to the server Kermit to indicate what

user-id, account and password are to be used. The server Ker-

mit may use this to validate the user's access to the system as

well as for billing purposes. It may also use this information

to provide the user with access to files on its system.

LOGOUT Request the server to exit Kermit and logout its job (or

process). This command is identical to the LOGOUT command.

RENAME filespec Change the name on the specified file (or files).

Kermit-32

will prompt for the new file specification on the next line.

Both file specifications must be valid for the server's system.

VAX/VMS KERMIT

Page 94

SEND_MESSAGE destination-address

Request the server to send a single line message to the

specified destination address (which might be a userid, ter-

minal designator, or some other item, depending upon the server

Kermit). Kermit-32 will prompt for the single line message on

the next line.

SPACE [directory]

Display information about disk usage in the given directory (or

by the given user). If no directory is provided, disk usage

information is provided for the current working directory (or

user). This is the same as the REMOTE DISK_USAGE command.

STATUS Display information about the status of the server.

TYPE filespec Display the contents of the specified file on your screen.

WHO [user-id] Display information about the given user. If no userid is

given, display information about the currently active users.

Kermit-32 will prompt for options for selecting what infor-

mation to display and/or formatting parameters. The format of

both the user-id and the options are dependent upon the server

Kermit.

7.4.3. Commands for Local File Management

Syntax: LOCAL [command]

Execute the specified command on the local system -- on the VAX/VMS system where Kermit-32 is running. These commands provide some local file management capability without having to leave the Kermit-32 program. These commands are

very similar to the REMOTE commands in function and syntax. They are all ex- ecuted locally, and are available when Kermit-32 is either local or remote.

The arguments to these commands are the same as the arguments expected from the user Kermit when Kermit-32 is processing a command in server mode.

COPY filespec Make a copy of the given file (or files). Kermit-

32 will

prompt for the new file specification. The command is actually

performed by using the DCL COPY command (COPY/LOG old-file

new-file), and any options which are valid on the DCL

COPY com-

mand may be included.

CWD [directory] Change working directory, or, in VAX/VMS terminology, change

the default device/directory. This command takes the same ar-

guments as the DCL SET DEFAULT command (i.e., a device and

directory, only a directory, or only a device). If no argument

is given, the default device and directory are reset to that in

effect when Kermit-32 was run. The new default device and

directory will be typed out.

DELETE filespec Delete the specified file or files. This command is performed

by using the DCL DELETE command (DELETE/LOG filespec).

There-

fore, any options which are valid on the DCL DELETE command may

be included.

VAX/VMS KERMIT

Page 95

DIRECTORY [filespec]

Provide a directory listing of the specified files.

This com-

mand is performed by using the DCL DIRECTORY command

(DIRECTORY

filespec), so any options valid for the DCL DIRECTORY command

may be included.

DISK_USAGE [uic]

Display disk usage information for the given UIC. If no

UIC is

given, display disk usage information for the process

UIC.

This command is performed by using the DCL SHOW QUOTA command

(SHOW QUOTA or SHOW QUOTA/USER=uic).

HELP Display the help message describing the server commands which

are available.

HOST DCL command

Perform the given DCL command. The command should not perform

any action which will require more input. Any output resulting

from the command will be typed on the terminal.

RENAME filespec Change the name of the specified file. Kermit-32 will prompt

for the new name on the next line. This command is performed

by using the DCL RENAME command (RENAME/LOG old-file newfile),

so any options which are valid on the DCL RENAME command may be

included.

SEND_MESSAGE terminal-name

Send a single line message to the given terminal.

Kermit-32

will prompt for the message on the next line. Since this com-

mand is performed using the DCL REPLY command

REPLY/TERMINAL=terminal-name "message"

OPER priveleges are needed to perform it.

TYPE filespec Display the contents of the specified file or files at your

terminal. Each file will be preceded by its name in angle

brackets.

7.4.4. The CONNECT Command

Syntax: CONNECT [terminal-name]

Establish a terminal connection to the system connected to the terminal line specified here or in the most recent SET LINE command, using full duplex echo- ing and no parity unless otherwise specified in previous SET commands. Get back to Kermit-32 by typing the escape character followed by the letter

C. The escape character is Control-Close-Square-Bracket (^]) by default.

When you type the escape character, several single-character commands are possible:

C Close the connection and return to Kermit-32.

Q If a session log is active, temporarily Quit logging.

R Resume logging to the session log.

S Show status of the connection.

0 Send a null character.

VAX/VMS KERMIT

Page 96

? List all the possible single-character arguments.

^] (or whatever you have set the escape character to be):

Typing the escape character twice sends one copy of it to the connected

host.

You can use the SET ESCAPE command to define a different escape character, and

SET PARITY, and SET LOCAL_ECHO to change those communication-lineoriented parameters. Type the SHOW LINE command for information about your current com- munication settings.

Kermit-32 does not have any special autodialer interface. It assumes that the connection has already been made and the line assigned.

7.4.5. The SET and SHOW Commands

THE SET COMMAND

Syntax: SET parameter [option [value]]

Establish or modify various parameters for file transfer or terminal connec- tion. You can examine their values with the SHOW command. The following parameters may be SET:

BLOCK_CHECK Packet transmission error detection method

DEBUGGING Record or display state transitions or packets

DELAY How long to wait before starting to send

ESCAPE Character for terminal connection

FILE For setting file parameters like file type

HANDSHAKE For establishing half duplex line turnaround handshake

IBM_MODE For communicating with an IBM mainframe

INCOMPLETE_FILE What to do with an incomplete file

LINE Terminal line to use for file transfer or CONNECT

LOCAL_ECHO For terminal connection, ON or OFF

MESSAGE The type of typeout to be done during transfers

PARITY Character parity to use

PROMPT Change the program's command prompt

RECEIVE Various parameters for receiving files

REPEAT_QUOTE Character to use for repeat compression

RETRY How many times to retry a packet before giving up

SEND Various parameters for sending files

Those SET commands which differ from the "ideal" Kermit are now described in detail.

SET DEBUGGING

Syntax: SET DEBUGGING options

Record the packet traffic, either on your terminal or in a file. Some reasons for doing this would be to debug a version of Kermit that you are working on, to record a transaction in which an error occurred for evidence when reporting bugs, or simply to vary the display you get when running Kermit-32 in local mode. Options are:

VAX/VMS KERMIT

Page 97

ON Display each incoming and outgoing packet (lengthy).

OFF Don't display or record debugging information (this is the nor-

mal mode). If debugging was in effect, turn it off.

The debugging information is recorded in the file specified by the most recent

LOG DEBUGGING command.

SET ESCAPE

SET ESCAPE octal-number

Specify the control character you want to use to "escape" from remote connec- tions back to Kermit-32. The default is 35 (Control-]). The number is the oc- tal value of the ASCII control character, 1 to 37 (or 177), for instance 2 is

Control-B. After you type the escape character, you must follow it by a one of the single-character "arguments" described under the CONNECT command, above.

SET FILE

Syntax: SET FILE parameter keyword

Establish file-related parameters:

TYPE keyword

Type of file for VAX/VMS file output. The choices are ASCII,

BINARY,

or FIXED.

ASCII Store the file as a standard VAX/VMS text file.

Any file

received is stored as variable length records with carriage

return, line feed sequences implied between records.

This is

the format preferred by most utility programs under

VAX/VMS.

An error will occur if any line is more than 4096 characters

long. Note that lines are only terminated by carriage return,

line feed sequences. A carriage return that is not followed by

a line feed or a line feed that is not preceded by a carriage

return is not considered the end of a line, and is included

within the body of a record.

BINARY Store the file as a binary file. Any file received is stored

as variable length records with no record attributes.

Kermit-32 actually will write 510 bytes in each record except

the last. This makes each record take up one disk block (510

data bytes plus two bytes of record length). The last record

is written containing only as much data is left to the end of

the file. Any file which is just a stream of bytes can be

stored as a BINARY file, and recovered intact later.

This is

the preferred file type for use in archiving files.

FIXED Store the file as a fixed length binary fle. Any file received

is stored as fixed length 512 byte records with no record at-

tributes. This is the format used for binary files such as

VAX/VMS "EXE" files and RSX-11M/M+ "TSK" files. Since even the

last record of the file is written with 512 bytes (even if it

VAX/VMS KERMIT

Page 98

is not filled), this format does not necessarily maintain the

correct length of a file. It should normally only be used for

files which are coming from a VAX/VMS system which are cur-

rently stored in fixed 512 byte records.

NAMING keyword

Determine the form of names to be sent with outgoing files and deter-

mine the translation performed on incoming file names. The choices are

FULL, NORMAL_FORM and UNTRANSLATED.

FULL Kermit-32 will send full file names (including device, direc-

tory, file name, file type and version number). When receiving

a file, Kermit-32 will perform no translation of the file name

(which must therefore be a legal VAX/VMS file specification).

NORMAL_FORM

Kermit-32 will send only the file name and file type. When

receiving a file, Kermit-32 will convert the file specification

received to contain only uppercase letters, digits, and at most

one period. Any other characters will be translated to

"X".

There will be at most 9 characters before the period (if any),

and at most 3 characters afterwards. This forces the file name

to be a valid VAX/VMS file specification. Note that standard

VAX/VMS file names and types are already normal form, and

therefore do not need translation. This is the default.

UNTRANSLATED

Kermit-32 will send only the file name and file type.

When

receiving a file, Kermit-32 will not perform any conversions on

the file specification, which therefore must be a legal

VAX/VMS

file specification.

SET HANDSHAKE

Syntax: SET HANDSHAKE o

Sets the half duplex line turnaround handshake character to the ASCII character whose octal value is o. Normally required for communication with half duplex systems like IBM mainframes.

SET IBM_MODE

Syntax: SET IBM_MODE ON or OFF

When IBM_MODE is set to ON, Kermit-32 will override the parity and local echo settings and use odd parity, local echo on, and also enable a handshake charac- ter of XON (control-Q, ASCII 021 octal). This feature allows Kermit-32 to talk with certain systems (notably some IBM mainframes), which require waiting for a

XON before sending data.

The various features selected by this command can be overriden subsequently by

SET PARITY, SET LOCAL_ECHO, and SET HANDSHAKE commands.

VAX/VMS KERMIT

Page 99

SET LINE

Syntax: SET LINE [terminal-name]

Specify the terminal name to use for file transfer or CONNECT; the terminal-name can be up to 16 characters long. If you issue this command using other than your job's controlling terminal, you will be running

Kermit-32 locally, and you must log in to the remote system and run Kermit on that side in order to transfer a file. If you don't issue this command, Kermit-32 deter- mines whether it is to run locally or remotely based on the default terminal line found when Kermit-32 is started. Kermit-32 uses a list of logical names to determine which terminal should be the default terminal line. The first of these names which translates to a terminal which is available (i.e., not al- located by some other process) is used. The logical names Kermit-32 tries are

KER$COMM, SYS$INPUT, SYS$$OUTPUT, and SYS$COMMAND. If none of these translate to an available terminal, Kermit-32 is running detached, and a terminal must be specified by the SET LINE command before any actions can be performed.

If a terminal is found, Kermit-32 is running locally if this is a terminal other than the one controlling the job (i.e., different from SYS$COMMAND), otherwise

Kermit-32 is running remotely. You can also select the line directly in the

CONNECT command; the command

CONNECT TTA0 is equivalent to

SET LINE TTA0

CONNECT

If you type SET LINE with no argument, you will deassign any previous assigned line and revert to remote mode.

SET SERVER_TIMOUT

Syntax: SET SERVER_TIMEOUT number

This specifies the number of seconds between timeouts during server command wait, 0 specifies that no timeouts should occur during server command wait.

When a Kermit server times out, it sends a NAK packet. Some systems cannot clear piled-up NAKs from their input buffers; if you're using such a system to communicate with a Kermit-32 server, and you expect to be leaving the server idle for long periods of time, you should use this command to turn off server command-wait timeouts.

THE SHOW COMMAND

Syntax: SHOW [option]

The SHOW command displays various information:

ALL All parameters.

BLOCK_CHECK_TYPE

The block check type being requested.

Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement