CKLKER.DOC          Documentation for C-Kermit Version 7.0

			     Stratus VOS VERSION

Applies to version:     7.0.196
This file last updated: Sat Feb 19 17:13:45 2000

Authors: Kernie Brashier <kernie@stratosphere.com>
         David Lane <lane@watsun.cc.columbia.edu>
         Frank da Cruz, Christine M. Gianone, Columbia University.

  Copyright (C) 1985, 2000,
    Trustees of Columbia University in the City of New York.
    All rights reserved.  See the C-Kermit COPYING.TXT file or the 
    copyright text in the ckcmai.c module for disclaimer and permissions.


Report problems, suggestions, fixes, etc, to:

  kermit-support@columbia.edu (Internet)

or:
 
  The Kermit Project
  Columbia University 
  612 West 115th Street
  New York, NY  10025-7799
  USA


DOCUMENTATION

Frank da Cruz and Christine M. Gianone, "Using C-Kermit", Second Edition,
1997, Digital Press / Butterworth-Heinemann, Woburn, MA, ISBN 1-55558-164-1
US single-copy price: $44.95; quantity discounts available.  Available in
computer bookstores or directly from Columbia University:

  http://www.columbia.edu/kermit/manuals.html

Features added after version 6.0 was released are documented in the text file,
ckermit2.txt.


FILES

File naming conventions are listed in ckaaaa.txt.

VOS installation instructions are in the cklins.txt file.


INTRODUCTION

This document describes how to use C-Kermit on a Stratus Computer, Inc.,
computer running VOS.  For a current list of limitations and restrictions of
VOS C-Kermit, also read the files ckcbwr.txt and cklbwr.txt files provided
with the VOS C-Kermit distribution files.  For Stratus users running FTX, use
the FTX version of C-Kermit.  For Stratus users of Fault-Tolerant HP-UX,
use the HP-UX version of C-Kermit.

VOS (Virtual Operating System) is the operating system for Stratus Computer,
Inc.'s fault-tolerant systems. VOS is a multi-user, symmetric multi-processing
OS, targeted toward on-line transaction processing environments.  VOS
currently runs on proprietary hardware using three major processor types, the
Motorola 680x0 series (sometimes referred to as VOS-CISC), the Intel i860
(referred to as VOS-RISC), and the newer Continuum processor (HP PA-RISC 7100
and 8000).  Other than the processors, VOS is the same on all three platforms
and VOS C-Kermit runs on all three kinds of processors.  VOS C-Kermit has been
successfully tested on VOS releases from 10.5 to 14.2.0.


INSTALLATION

Instructions for building and installing VOS C-Kermit are given in the file
cklins.txt in the C-Kermit distribution and in the cklmak.cm command macro.
In general, collect all the files from the C-Kermit distribution and run the
command macro.  The macro compiles the sources, builds a bind control file,
and runs the binder.  The result is a group of program modules, including
kermit.pm, the VOS C-Kermit program for the architecture upon which you built
it.  After checking for errors in the build process and testing C-Kermit, you
may install it in a system-wide application directory.


USING VOS C-KERMIT

 . Preparing Your VOS Session for C-Kermit

   . Setting Your Terminal Type

Since VOS C-Kermit does not currently provide the FULLSCREEN file transfer 
display, your actual VOS terminal type does not matter to C-Kermit.  If you 
are using a TCP/IP network connection with C-Kermit in local mode, however, 
the TELNET negotiations will send your VOS terminal type to the remote host, 
unless you tell C-Kermit to send another terminal type.  For more information 
about this, see the section on TCP/IP network connections later in this 
document.

To set your terminal type, use a command such as:

set_terminal_parameters -terminal_type vt100

You can find out your current terminal type by using the 
display_terminal_parameters command, and you can get a list of terminal types 
supported on your system with the list_terminal_types command.

  . Checking and Setting Your Communications Speed

When you use C-Kermit to transfer files in remote mode, it bases its packet 
time-outs on the communications speed of your login terminal as reported by 
VOS.  If you have dialed in at (say) 2400 bps and VOS thinks your speed is 
19200 bps, file transfers might not work well, or at all.

VOS knows your communication speed if your terminal or PC is connected
directly, or through a modem, to a communication port on the VOS system.  If
you give the display_terminal_parameters command, you will see a display.

If you have entered the VOS system through a network connection such as a
terminal server or X.25 PAD, or from another host, you are not attached to a
real communications port, so VOS might not know your true communications
speed.  If the speed shown by the display_terminal_parameters command is not
your true communications speed, you should adjust the time-outs used by
C-Kermit before doing remote mode file transfers.  There is more information on
this in the section on file transfers later in this document.


PROGRAM CONTROL

VOS users might find C-Kermit's command processing to be somewhat unfamiliar.
It lacks a number of VOS features and has others that VOS does not.  For
example, it does not make use of the s$parse_command routine, but it does
provide command completion and help during command entry.  C-Kermit's user
interface is intended to be compatible with other Kermit programs, rather than
with any particular operating system.  This applies to the VAX/VMS, UNIX, and
other versions of C-Kermit as well as to the VOS version.  Once you have
learned to control one Kermit program, you will also be familiar with most
others, such as MS-DOS Kermit for PCs.

C-Kermit is a character-mode application designed to be used from a terminal.
If you are accessing your VOS system from a terminal or terminal emulator, you
can start the Kermit program just as you would most other programs, that is,
by typing "kermit" followed, optionally, by command line arguments.  Then you
can have an interactive dialog with C-Kermit, using your keyboard and screen.

Be aware that since C-Kermit does not use s$parse_command, it does not
recognize the -form or -usage arguments.  To get help on command line
arguments, use kermit -h.  To get help on interactive commands, type "help"
or "?" at the C-Kermit prompt.


C-KERMIT COMMAND-LINE ARGUMENTS

Uppercase command-line arguments are lowercased by VOS before passing them
to Kermit, which of course results in a parse error or the wrong command being
executed.  To prevent this, enclose uppercase command-line arguments in
single quotes, e.g.

  kermit '-Y'

Also use single quotes for grouping of multiple "words" into a single
command-line argument, e.g.:

  kermit '-C' 'take oofa.ksc, exit'


INTERRUPTING C-KERMIT

C-Kermit can be interrupted at its prompt, in the middle of typing a command, 
during execution of any command except CONNECT or remote-mode file transfer, 
and during local-mode file transfer by typing your interrupt key (usually 
Ctrl-C), if it is enabled.  C-Kermit can also be interrupted by the Break key 
at these times and during CONNECT, if the Break key is enabled.


RUNNING C-KERMIT IN COMMAND MACROS

C-Kermit reads its input from the terminal port of a process, not from 
command_input or default_input.  For this reason, the &attach_input directive 
in a command macro is not effective for C-Kermit.  C-Kermit will still try to 
read from your terminal.  The best way to have a command macro send commands 
to C-Kermit is to build a C-Kermit script file and have the command macro 
start C-Kermit with the script, using the -f command line argument.  This will
work in login and sub-process processes, and in batch (both started processes 
and batch queue processes).


C-KERMIT INITIALIZATION FILES

VOS C-Kermit uses the initialization file (home_dir)>ckermit.ini, but 
C-Kermit can be built with a system-wide initialization file.  For more 
information on this, see the ckccfg.doc file. 

The standard initialization file automatically executes the user's own 
customization file ckermod.ini, if it exists in the user's home directory, so 
each user can create a personalized C-Kermit environment without having to 
duplicate the common material from the standard initialization file.

If you have a dialing directory file, it should be installed in your home 
directory, with the name ckermit.kdd. If you have a services directory file, 
it goes in the same place under the name ckermit.ksd.

C-Kermit uses what other systems call environment variables, which do not 
exist under VOS.  To simulate this, VOS C-Kermit uses a file under the home 
directory called ckermit.env.  This file is a list of variables and their 
values, separated by an equals sign (don't put spaces around the equals).  An
example is included with the C-Kermit distribution.


TERMINAL CONNECTION

 . The CONNECT-Mode Escape Character

VOS C-Kermit's default CONNECT-mode escape character is Ctrl-\
(Control-Backslash).  Terminal emulation is provided by your terminal,
workstation terminal window, or terminal emulator.  VOS C-Kermit recognizes
keystrokes as single 7- or 8-bit bytes.  8-bit codes can be used if you have a
keyboard capable of generating them, if C-Kermit has a clean 8-bit path to the
keyboard, if you have told C-Kermit to SET COMMAND and TERMINAL BYTESIZE 8,
and if your VOS terminal has the bits_per_char attribute set to 8, as shown by
the update_channel_info command.  Be aware that VOS sometimes thinks you have
an 8-bit terminal connection when you do not; often this is because of a
network connection of which VOS is unaware.


NETWORK CONNECTIONS

VOS C-Kermit can be built with support for TCP/IP and X.25 network
connections.  To use either of these, you must have VOS support for that type
of network.  To see what software support you have on your system, use the
display_software_purchased command.  If C-Kermit is built with both TCP/IP and
X.25 network support, TCP/IP is the default.  If only one network type is
included in the build, then that one is the default.  To change the type of
network, use the SET NETWORK command.  The SET HOST command will use the
current network type to make a network connection.  Use the SHOW NETWORK
command to see what the network type is currently set to.

 . TCP/IP

The VOS support required for TCP/IP connections is the OS TCP/IP product set.
As a simple test, change directories to the run-time library using the 
command:

change_current_dir (master_disk)>system>tcp_os>object_library

If this directory exists on your system, you can build C-Kermit with TCP/IP 
support.  Note that C-Kermit uses the OS TCP/IP product, not the firmware 
resident TCP/IP product. The TCP/IP interpretation of the SET HOST command
is well documented in the "Using C-Kermit" book.

 . X.25

The VOS support required for X.25 connections is X.25 and X.29 networking. 
Almost every VOS system has this.  The simplest way is just to build C-Kermit 
with X.25 enabled and try it.

VOS C-Kermit supports both X.29 and STS connections.  To specify an X.29 
connection, use the gateway name and address for the host name, separating
them with a colon, like:

  set host sprintgate:311012300456789

For an STS connection, use the either the full module name to have StrataNet 
resolve the full module name, like:

  set host %s1#m1

or use just the system name but include a percent sign to get a system 
connection, like:

  set host %s1

If you leave out the percent sign, C-Kermit will interpret the system name as 
a gateway name with no address given, and it probably won't connect.  For STS
connections, you may use an optional extension separated by a colon, as:

  set host %s1#m1:100


FILE TRANSFER

 . Setting Time-outs

If you are accessing VOS through a network connection and VOS thinks your 
terminal communications speed is something other than what it really is, 
you should change the time-outs C-Kermit will use for remote mode file 
transfers.  The correct value depends on the communications speed and the size 
of the packets you are using.  As a rule of thumb, use twice the packet size 
in bytes divided by the communications speed in bytes per second.  To find the 
bytes per second speed of your line, just divide the bits per second value by 
ten.  It is better to err on the side of too long a time-out than too short, 
so if the result you get seems a little short or if your transfers keep 
failing with time-outs, add a few seconds.

 . File Organizations

VOS has a varied assortment of file organizations.  Kermit as a general rule 
only understands two types of files, text and binary.  You should tell 
C-Kermit which type of file, text or binary, you are working with, since it 
cannot tell with any deal of accuracy. Normally, text files created by EMACS
or EDIT are sequential.  Binary files under VOS can be fixed, relative, 
or stream.  Sequential files can be binary, and stream files can be text.
Fixed files can be created with "holes" if they are created in random access.
VOS C-Kermit does not understand indexes, character set files, extent files, 
or random files with missing records.  In practice, Kermit works well for text 
files, and for binary files from other systems.  Binary files that originated
on VOS may need some massaging when they make it back to a VOS system.

 . Sending Files

When sending, VOS C-Kermit opens any file organization and uses the current
Kermit file type (the default is text).  Use the SHOW FILE command to see what
C-Kermit thinks the current file type is.  For text files, VOS C-Kermit
appends a CRLF to the end of the result of each read operation.  This is
consistent with the Kermit "text" format.  When sending files in binary mode,
VOS C-Kermit does not add any information to the end of the record; the data
is simply sent without any conversions or translations.  For binary stream
files, VOS C-Kermit uses raw reads; for binary transfers of any other file
organization, and for text transfers of any file organization, sequential
reads are done.

There is a general problem with transfer of VOS files through non-VOS systems
(e.g. by ftp) that is not specific for Kermit.  The Stratus community has a
solution for this, called "bundle.cm," a utility that is available free from
ftp://ftp.stratus.com/pub/vos/utility.  This utility is only for
Stratus-to-Stratus use; it converts VOS files so they can pass through and be
stored on non-VOS systems.  Such bundles must eventually be transferred to an
Status destination where "unbundle.cm" extracts the original VOS files intact.

Note that ckltxt.cm and cklxtr.cm (and the corresponding .pm's) that come with
VOS C-Kermit are NOT suitable for this purpose; they work for executable
program images, but not necessarily for other kinds of files.

 . Receiving Files

When receiving files, C-Kermit creates text files as sequential, and binary
files as stream.  If the other Kermit can send attribute packets with file
types, this lets VOS C-Kermit create files reasonably for you.

If a file arrives that has the same name as an existing file, VOS C-Kermit may
rename one of the files, depending on the SET FILE COLLISION setting.  When
renaming files, VOS C-Kermit uses the "generation" numbering scheme similar to
UNIX C-Kermit.  For example if the file "oofa.txt" needed to be renamed,
C-Kermit would rename it to "oofa.txt.~1~" with increasing numbers until there
is no collision with an existing name.

(End of CKLKER.DOC)
