Columbia Kermit/kermit.zip/old/ckermit4e/ckm834.doc

Text File | 2020-01-01 | 39KB | 776 lines

1. MACINTOSH KERMIT

Program:        Bill   Catchings,   Bill   Schilit,  Frank  da  Cruz  (Columbia
                University),
                Davide Cervone, University of Rochester
Language:       C (SUMACC)
Documentation:  Frank da Cruz, Bill Schilit
Version:        0.8(34)
Date:           March, 1986

Macintosh Kermit, or "MacKermit", is an implemtation of the Kermit file  trans-
fer  protocol for the Apple Macintosh (and Macintosh-XL) computer, developed at
Columbia University, based on C-Kermit (which also forms the  nucleus  of  Unix
Kermit).


MacKermit Capabilities At A Glance:

  Local operation:                   Yes
  Remote operation:                  Yes (server mode only)
  Login scripts:                     No
  Transfer text files:               Yes
  Transfer binary files:             Yes
  Wildcard send:                     No
  File transfer interruption:        Yes
  Filename collision avoidance:      Yes
  Can time out:                      Yes
  8th-bit prefixing:                 Yes
  Repeat count prefixing:            Yes
  Alternate block checks:            Yes
  Terminal emulation:                Yes (VT100,VT102)
  Communication settings:            Yes
  Transmit BREAK:                    Yes
  Support for dialout modems:        No
  IBM mainframe communication:       Yes
  Transaction logging:               No
  Session logging:                   No
  Debug logging:                     No
  Packet logging:                    No
  Act as server:                     Yes
  Talk to server:                    Yes
  Advanced server functions:         No
  Local file management:             Yes
  Command/Init files:                Yes
  File attributes packets:           No
  Command macros:                    No
  Raw file transmit:                 No

The main differences between MacKermit and other Kermit programs are:

   - In  MacKermit  you  are  always  connected  via  a  terminal emulator
     (VT102).

   - MacKermit commands are issued by means of pull-down menus that  over-
     lay your terminal session.

The  major  menus  are File, Settings, Remote, and Transfer.  The File menu in-
vokes Kermit's file transfer functions, allows settings to be  saved  and  res-
tored,  and  like  most Macintosh applications, includes a "quit" selection for
leaving the program.

The Settings menu provides dialog boxes for file, communications, and  protocol
settings.  The Remote menu has the commands that can be sent to Kermit servers,
as well as an option to turn Macintosh  Kermit  itself  into  a  server.    The
Transfer menu gives you a standard Macintosh file box, allowing you to transfer
directly to the selected application.


1.1. The Macintosh File System

The Macintosh file system consists of one or more disks, each  disk  containing
files.    All  files on a disk must have a unique name.  Files may be collected
together into "folders", but folders are not analogous to directories on  other
file systems, and no two folders on the same disk may contain files of the same
name.  Macintosh file names may contain practically any  printable  characters,
including  space  and punctuation -- but colon (":")  should be avoided because
it is used in device names.


1.2. File Transfer

Glossary:

   - Mode - Text or Binary.  Binary means the data is sent or stored with-
     out  modification.  Text  means  that every carriage return character
     (CR) in a Macintosh file is translated to a  carriage-return-linefeed
     (CRLF)  sequence  when sending, and every CRLF in an incoming file is
     turned into a CR when stored on  the  Mac  disk.    A  text  file  is
     produced when you save a file from MacWrite using the "text only" op-
     tion; text files are not associated with any particular Macintosh ap-
     plication  and can be sent in a useful fashion to other kinds of com-
     puters.

   - Fork - Data or Resource.  Macintosh files may have two "forks".   The
     data  fork  contains  data for an application; the resource fork con-
     tains icons, strings, dialog boxes, and so forth.   For  instance,  a
     MacWrite  document  contains  text  and formatting information in the
     data fork, and fonts in the resource fork.  For applications, the ex-
     ecutable code is stored in the resource fork.

Macintosh  Kermit  supports the standard Kermit commands for transferring files
-- Send, Receive, and Get.  Invocation of any  of  these  commands  produces  a
MacKermit file dialog box in which you specify the file name, the mode, and the
fork.  Defaults are determined from the selected file or taken from the current
file settings, described below.

When  you select the Send command, you get a MacKermit file open box, which in-
cludes the standard Macintosh dialog items -- a file list, Disk and Eject  but-
tons,  etc.    You can only send one file at a time, by clicking on its name in
the file list.  Clicking the Disk button will switch the file list  to  another
physical disk.  If desired, you can type an alternate name to send the file un-
der.  When you select a file, MacKermit examines its type; if the type is APPL,
then  MacKermit expects to send the resource fork in binary mode, otherwise the
data fork in text mode.  The Mode and Fork radio  buttons  will  display  these
choices; you may change them before clicking the Send button.

You can receive or get multiple files, providing the opposite Kermit is capable
of sending multiple files in a single transaction (most are).  As files arrive,
they will be decoded according to the current mode (text or binary), and stored
in the default fork (data or resource) under either the name they  arrive  with
(overwriting  existing files of the same names) or under new unique names (when
name conflicts occur), according to the current default  for  name  collisions.
You  may  also elect to perform an "attended" receive, in which you have an op-
portunity to override all file defaults on a per-file basis.  But  this  option
must be used with caution -- if you take too long (more than about a minute) to
execute an incoming file's dialog box, the opposite Kermit could time  out  and
terminate the transaction.

The  folder  for new files is the same as the location of the settings file, or
if no settings file was used then the new files appear on the desktop.  If  you
are  transferring  a  lot  of  files  and  want to keep them together, create a
folder, drag the settings file into it, and double click on the settings  file;
all created files will appear in that folder.

File  transfers can be cancelled by clicking on the Cancel File or Cancel Group
buttons.  These will always work when sending.  When receiving, they will  work
if the opposite Kermit honors this (optional) feature of the protocol.

In  any  case,  an "emergency exit" from any protocol operation can be taken at
any time by typing  "Command-."  --  that  is,  hold  down  the  Command  (Fan,
Cloverleaf) key and type period.


1.3. Remote Commands

The  Remote  menu allows you to send commands to a Kermit server.  The response
from these  commands  (if  any)  is  displayed  in  a  special  pop-up  window.
Responses  to  multiple  Remote  commands  are separated by a dashed line.  The
response window can be scrolled, sized, and positioned, and can  be  hidden  by
clicking  the  menu  item "Hide Response" or the window's go-away box; all text
remains intact and will be appended to the next time you do a  Remote  command;
it  can  also  be  brought to the foreground by clicking the Show Response menu
item.  Note that typein to the terminal emulator will not take effect when  the
response window -- or any other window -- is up front.

If  the  response window gets too full (i.e. fills up the free memory available
to the MacKermit application), the program will probably bomb.

If the remote Kermit server is in binary mode, its responses to Remote commands
may  look strange.  For instance, a Unix Kermit server in binary mode will send
lines of text separated by only linefeeds, rather than CRLFs.

A Remote command can be cancelled by taking the Emergency Exit (Command-.).


1.4. Settings

You can change File, Communications, and Protocol settings by  using  the  Set-
tings  pull-down menu.  You can save and restore these settings by invoking the
appropriate selection in the File menu.  If the bundle bit has  been  correctly
set on your version of MacKermit you can double-click on the resulting document
to start MacKermit with those settings.

The File settings establish the defaults for file transfer:

   - Mode: text or binary.  Used for received files only.   When  sending,
     MacKermit  tries to figure out an appropriate mode for the file being
     sent (but then lets you override it the Send File dialog).

   - Fork: which fork -- data or resource -- to send, or to store  an  in-
     coming file into.

   - Naming: Whether incoming files should supersede existing files of the
     same name, or a new unique name should be assigned to them.   If  the
     latter,  the  new  name is formed by adding a dot and a number to the
     end.  For instance, if a file called FOO exists and a file called FOO
     arrives,  MacKermit  will  store the arriving file as FOO.1; if FOO.1
     exists, then FOO.2, etc.

   - Attended versus Unattended operation for incoming files.

The Communications settings allow you to set the baud  rate  (anywhere  between
300  baud and 57.6K baud), parity (odd, even, mark, space, or none), and duplex
(full - remote echo, half - local echo).

The Protocol settings allow you to set packet parameters for both incoming  and
outbound  packets.  These include the block check type (1 or 2 character check-
sum, 3-character 16-bit CRC-CCITT), line turnaround  handshake  character  (for
file  transfer with half duplex systems), packet start and end characters, pad-
ding, packet length, timeout interval, and  so  forth  (Refer  to  Kermit  User
Guide).    Characters  are  specified by entering their ASCII value in decimal,
e.g. 1 for Control-A, 13 for Control-M (Carriage Return), etc.


1.5. Terminal Emulation

MacKermit provides a subset of the features of  the  DEC  VT102  terminal;  the
VT102  is  a  VT100 with line and character insert/delete functions added.  The
functions provided are sufficient to allow MacKermit to act as a  terminal  for
EMACS  as it exists on the DEC-20, VAX (CCA EMACS on VMS or UNIX), and for most
host-resident display-oriented applications that expect to do cursor  position-
ing  and editing on the VT100 screen.  MacKermit does not currently support the
following VT100/102 functions:

   - double height or double width lines
   - smooth scrolling
   - 132 columns
   - Interpretation of multiple parameters in a single escape sequence
   - etc

(this is not an exhaustive list)

The keyboard is set up by default as follows: The COMMAND (Fan, Cloverleaf) key
is used as the Control key.  The CAPS LOCK key forces all alphabetic characters
to upper case, and causes keys on the numeric keypad to send VT100  keypad  es-
cape  sequences.  The OPTION key is "Control-Meta" (explained below).  The ter-
minal emulator sends ESC (escape) when the "`" key is pressed unshifted.    The
character  "`"  can  be sent by typing Control (Command) and the same key.  The
Backspace key sends a Delete (Rubout) and Control-Backspace sends a  Backspace.
The  main keypad Enter key sends a "short" (250ms) BREAK signal.  The Mac+ does
not have a main keypad Enter key, so the BREAK function must be  reassigned  to
another  key.    Use  CKMKEY  (see  below) to do this.  The short break is F126
(function number 126) and long break is F127.

MacKermit (V0.8 and later) comes with a  separate  key  configuration  program,
CKMKEY,  which  lets you change the behavior of the keys, define function keys,
and so forth.  CKMKEY is described in detail below.

MacKermit (V0.8(43A) and later) includes a mouse-controlled  cursor  postioning
feature  for  use  during terminal emulation.  When the mouse button is pressed
while the Option and Command keys are held down, the program  acts  as  if  you
typed the keypad arrow keys to move the terminal cursor to where the mouse cur-
sor is.  You must have already defined the keypad arrow keys to  send  the  ap-
propriate  character sequences for your host application.  The Catch-22 here is
that if you don't have a keypad, there's no way for you to  define  the  keypad
keys  using  MacKermit's  keyboard configurator.  In that case, you can use the
VT100 startup file provided with MacKermit, which assigns the normal VT100  ar-
row  key  sequences  to  the  keypad  arrow  keys,  and  therefore  also to the
mouse-cursor feature.

MacKermit honors your parity communications setting by using built-in functions
of  the Mac's serial i/o chip.  Unfortunately, the chip has an unpleasant quirk
-- arriving characters that do not have  the  specified  parity  are  discarded
rather  than  passed to the requesting application.  Thus, if you are connected
as a terminal using MacKermit to a device that requires,  say,  odd  parity  on
characters  sent  to  it, but does not put odd parity on characters it sends to
you, then many incoming characters will not appear on your screen.

To allow useful coexistence of desk accessories and Kermit, the terminal emula-
tion  may  be  dragged  using the drag bar.  A desk accessory that overlays the
Kermit window can be clicked upon to move it behind the Kermit window, and then
the Kermit window can be dragged to reveal the hidden desk accessory so that it
can be restored to the foreground.  The same thing can be  done  with  Kermit's
own  remote response window.  Note that Kermit's terminal emulation window does
not accept input when any other window is in the foreground.

The following features are missing from the MacKermit  terminal  emulator,  and
may be added in subsequent releases:

   - capturing text from the screen (e.g. cutting to clipboard, saving off
     top)
   - screen rollback, sizing
   - modem or dialer control
   - login scripts
   - transmission of raw text to host (e.g. pasting to screen)
   - printer support

MacKermit does not use XON/XOFF flow control during terminal emulation or  file
transfer.    The terminal emulator can normally keep up at 9600 baud, but after
several continuous scrolling screens at this  speed,  some  characters  may  be
lost.    In the present version, when running at high baud rates keep your ter-
minal in page mode, or use "more", or view text  with  a  non-scrolling  screen
editor.    Also,  don't drag the terminal emulation window while characters are
arriving; if you do, the characters will be lost and the  display  will  become
confused.


1.6. Installation

MacKermit  is  distributed  in source form for building on Unix (or VMS/Eunice)
systems that have the Stanford SUMACC  Macintosh  cross-development  tools,  in
.HQX  "binhex"  form,  and sometimes also as a binary resource file.  Those who
want to work from the source are referred to the file CKMKER.BLD  for  instruc-
tions.

If  you  have the binary resource file available (its name will be CKMKER.RSRC,
ckmker.rsrc, CKMKER.RSR, ckmker.rsr, or some variation on these,  depending  on
what  system  it's stored on and how it got there), AND if you have "MacPut" on
your system and MacTerminal on your Mac, AND if  you  have  an  8-bit-wide  (no
parity)  data path between your Mac and your system, use MacPut to download the
binary resource file to MacTerminal's XMODEM option on your Mac.   After  doing
this  you  must  use  SetFile on the Mac to set the author to KERM, the type to
APPL, and turn on the bundle bit.  For CKMKEY, the author should be KERK.

If you have an earlier release of Columbia MacKermit, you  may  use  Kermit  in
place of MacTerminal and MacPut.

If  you  don't  have  the  binary resource file available, you can download the
CKMKER.HQX file in the same manner, then run "binhex" (version 4) on it.


1.7. CKMKEY - Macintosh Kermit's Keyboard Configurator

This describes CKMKEY V0.8(0), May 1985.

The version number of CKMKEY indicates compatability with the like  version  of
CKMKER  --  Macintosh Kermit, referred to simply as "Kermit" from now on.  Edit
numbers (within parentheses) may differ.  If Kermit is  used  with  a  settings
file  containing  a  key  configuration  produced by an incompatible version of
CKMKEY, then that configuration will be ignored.


1.7.1. What is CKMKEY?

CKMKEY is a  keyboard  configurator  program  for  use  with  Macintosh  Kermit
(versions 0.8 and greater). CKMKEY allows:

   - Redefinitions of keys

   - Definitions of multicharacter function keys

   - Selection of long and short BREAK keys

CKMKEY  is  a  separate program from Kermit.  It may be thought of as an editor
for Kermit's terminal emulator key definition resource, which is kept in a Ker-
mit  settings file.  Before you can use CKMKEY, you must already have used Ker-
mit to create a settings file to operate on.

The reason CKMKEY is separate from Kermit is that there is not enough  room  in
the memory of a 128K Macintosh to hold a program that can do both.  CKMKEY dis-
plays and changes key settings, Kermit uses them.  Once you have started Kermit
with a given set of key definitions, there is no way to examine or change them.

Some  familiarity  with  the ASCII alphabet is assumed in the following discus-
sion.


1.7.2. Modifier vs Normal Keys

The Macintosh keyboard is composed of normal keys and modifier keys.   Modifier
keys are SHIFT, CAPS LOCK, OPTION, and COMMAND (also known as APPLE, CLOVER, or
FAN).  Only one normal key can be selected at a time, but one or more  modifier
keys can be depressed along with it.


1.7.3. Key Maps

When  a key on the keyboard or numeric keypad is depressed the result is a scan
code -- a number between 0 and 127 (see Inside Mac Event Manager for details if
you're interested).  A table indexed by scan code resulting in the character to
be displayed or transmitted will be referred to as a "keymap" or "key mapping."

On the standard Mac many keymaps exist -- the modifier  keys  (such  as  SHIFT)
specify  which  keymap  is  selected.    For  example, when no modifer keys are
depressed the keymap contains the lowercase alphabet, numbers and some punctua-
tion.  The keymap in use when the SHIFT modifer is depressed contains the capi-
tal letters and special characters.

All in all it is possible to select 16 different  keymaps  by  depressing  from
zero  to  four  modifier keys.  Normally however, 6 or so distinct keymaps will
suffice.

CKMKEY allows you to redefine 6 keymaps: shifted and unshifted combinations  of
keymaps   named  "normal",  "capslock",  and  "control".    These  keymaps  are
predefined with the expected values -- the control map is preloaded  with  con-
trol  codes, the capslock preloaded with the unmodifed keymap but with all let-
ters uppercase.

In this document modifier keys are written in capital letters and key map names
are  written  in lowercase.  SHIFT, CAPS LOCK, COMMAND, and OPTION are modifier
keys, "normal" "capslock" and "control" are key maps internal to CKMKER.  Since
one  of  the  major  functions  of CKMKEY is to change maps invoked by modifier
keys, it is important to keep this distinction in mind.


1.7.4. What's in CKMKEY's Keymaps

A keymap is a list of 128 numbers.  Which keymap is selected depends upon which
modifier  keys are depressed, and the entry within the key map is determined by
the scan code.  A keymap entry is an 8-bit quantity:  if the high order bit  is
0,  then  the  entry is the 7-bit ASCII character to be transmitted through the
serial port; if the high bit is 1, then the remaining 7 bits are an index  into
the function-key table.

Notice  that  only  single  7-bit values can be directly translated through the
CKMKEY keymap.  If you want a single key to transmit multiple characters,  then
you can designate that key to be a "function key", and the key map will contain
an indirect reference to the function-key table.  If you want a key to transmit
an 8-bit value, assign the "meta" operation to one of the modifier keys and use
the meta key together with the desired key (see below).

Functions are numbered 0-127 with the highest few being  reserved  for  special
use.  Currently functions 126 and 127 send a short 250 millisecond BREAK signal
and a long 3.5 second BREAK respectively.  In the future more special functions
may  be  allocated  so  (since  it is arbitrary anyway) please use low numbered
functions when defining your own.


1.7.5. Menus

CKMKEY has two menus, File and Set.  First you must use the File menu to select
and open a Macintosh Kermit settings file, which in turn has been created using
the Kermit Save Settings option from its own File menu.  Then use the Set  menu
to establish or alter key definitions, then use the File menu again to save the
settings file back for Kermit.  A variety of Kermit settings files can be kept,
each  with  its  own  collection of settings and key definitions; Kermit can be
started with the desired settings by double clicking on one of  these  settings
files from the Macintosh desktop.

Menus  consist  of  options.    If  an option is followed by an ellipsis (three
dots...) then clicking it will produce a dialog box of  some  kind;  otherwise,
clicking it causes the indicated action to be performed immediately.  If an op-
tion is dimmed then it is not available for some reason --  for  instance,  you
can't set any keys until you open a settings file.


1.7.6. MENU: Set

The  Set  menu includes dialogs for setting keys, defining functions, and reas-
signing modifier keys.


1.7.6.1. DIALOG: Set Modifer Keys

Background:

Skip ahead to the next section if you already know  about  things  like  SHIFT,
CAPS LOCK, CONTROL, and META.

On  a  typewriter  the  only modifier key is SHIFT.  Typing a character with no
modifier key depressed selects a lowercase letter or the character  printed  on
the  lower  face  of  the keytop (say, the digit "4").  Typing a character with
SHIFT depressed selects an uppercase letter or the character printed on the up-
per  face of the keytop (say, a dollar sign).  Some keyboards also have a SHIFT
LOCK key, which stays down once pressed and pops up the next time it's pressed;
its  operation  is equivalent to holding down SHIFT.  And some keyboards have a
CAPS lock key which operates like SHIFT LOCK, but only upon letters.

Computer terminals also have a modifier key called  CONTROL  (or  CTRL).    Its
function  is  a  little  less  obvious: it is intended to produce one of the 33
characters in the "control range" of the ASCII alphabet.    Control  characters
are not graphic -- they are intended for use as format effectors (like carriage
return, formfeed, tab, backspace), for transmission control, or for device con-
trol.    The remaining 95 characters -- letters, digits, and punctuation -- are
the graphic characters.  When a character is typed with  the  CONTROL  modifier
pressed,  its  "control equivalent" is transmitted.  By convention, the control
equivalent of A is Control-A, B is Control-B, etc, and  there  are  also  seven
special  control characters generally associated with punctuation characters or
special keys.   For  the  "alphabetic"  control  characters  Control-A  through
Control-Z,  SHIFT or CAPS LOCK modifiers are ignored; for the others, operation
varies from terminal to terminal.

The SHIFT and CONTROL modifiers allow all 128 ASCII characters to be sent  from
a  normal  typewriter-like  keyboard  that has about 50 keys.  However, certain
host-resident computer applications -- notably  the  full  screen  text  editor
EMACS  and  its  descendents  --  can  be  used to greater advantage with a 256
character alphabet (EMACS responds to single-character commands, and  the  more
characters a terminal can send, the more commands are directly available).  For
this purpose, some terminals also provide a META modifier key.  This key simply
causes  the  high-order  ("8th") bit of the selected ASCII value to be set to 1
upon transmission.  META characters can only be transmitted when the communica-
tion  path  allows all 8 bits to pass transparently; when this is not possible,
software like EMACS  allows  a  sequence  of  two  7-bit  ASCII  characters  to
represent  a  single  meta  character.    The  advantage  of having a real META
modifier key is that it can be  held  down  while  the  actual  key  is  struck
repeatedly  or even autorepeats, whereas a use of a "meta prefix" requires much
more typing.  To illustrate, suppose META-F is the command to  go  forward  one
word.    If  you want to execute this operation repeatedly, just hold down META
and F and let it autorepeat.  If you don't have a META key, then  you  have  to
use  a "meta prefix" character (usually escape), and to enter META-F repeatedly
in this case, you'd have to type <escape>F<escape>F<escape>F...etc.

Macintosh Kermit Modifier Keys:

You can define the modifier key to keymap correspondence in CKMKEY by selecting
the  "Modifer Keys..." menu item under SET, or by double clicking on a modifier
key while in the SET KEYS dialog.

The SET MODIFIERS dialog lets you define what map OPTION, CAPS LOCK and COMMAND
refer  to.  Notice that SHIFT is missing -- SHIFT always references the shifted
equivalents to the normal, control and caps lock maps.

The dialog is layed out in columns with the three modifier keys as column head-
ings  and  the three map names below.  Also under each column is a "pseudo" key
map for "meta."

Meta is not a map, but an operation: it augments the  value  being  transmitted
after  it  has been read from its map.  Meta can either be set to send a prefix
string before the character or to turn the high  order  (8th)  bit  on  in  the
transmitted  character.  The default prefix for meta is set to be 033 (escape).
If a meta modifier key is depressed and the key results in a function reference
then  no  modification occurs; functions are not "metized".  However, functions
can be defined to include 8-bit values.

Notice that meta can be set in conjunction with a key map.  Since  meta  is  an
operation  as described above there is no ambiguity.  Consider for example set-
ting OPTION to reference the  "control"  map  and  selecting  "meta"  for  this
modifier key as well.  The result is a control-meta key.

    CAUTION:  If  you  have  used  Kermit's communications settings menu to
    select any parity other than "none", then any high order bits that  may
    be  set  by CKMKER's key mapping will be superseded when Kermit applies
    the selected parity to outbound characters.

The SET MODIFIER KEYS dialog  also  lets  you  select  your  meta  preferences:
whether you want to use the 8th bit toggled on, or a prefix string.  The prefix
string is entered in the same manner as a function definition  (backslash  fol-
lowed by 3 octal digits for non-printable characters, see below).

Note that it is possible to cause ambiguities when selecting and using modifier
keys.  For example say you set OPTION to refer to the control map, and you  set
CAPS  LOCK  to refer to the caps map; at this point if you hold both OPTION and
CAPS LOCK down it is unclear which map you want your character  to  come  from.
To  try to prevent this type of ambiguity the SET KEY dialog will beep when you
are holding down or mousing an ambigous set of modifier keys.

The Kermit code itself references maps in this precendence: if  a  control  map
modifier  is  depressed  then  use  control map, else if a capslock modifier is
depressed use capslock, otherwise use the normal map.

A sample modifier key configuration is shown in Figure -MACMKEY.

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

                     OPTION          COMMAND         CAPS LOCK

                     o  Normal       *  Normal       o  Normal
                     *  Control      o  Control      *  Control
                     o  Caps         o  Caps         o  Caps
                    [X] Meta        [X] Meta        [ ] Meta

              Figure 1-1:   Macintosh Kermit Modifier Key Dialog

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

Here the CAPS LOCK key is used to reference "control", the COMMAND  key  to  do
the  "meta"  operation, and OPTION is "control-meta".  Holding down COMMAND and
CAPS LOCK together will also result in control-meta.


1.7.6.2. DIALOG: Set Function Definitions

Background:

Skip to next section if you know what function keys are.

Many popular terminals have "function  keys"  in  addition  to  the  alpabetic,
numeric,  punctuation,  and  modifier  keys described above.  Function keys are
usually labeled F0, F1, F2, ..., or PF1, PF2, ...  On some terminals, like  the
DEC VT100, the function keys send predefined sequences of characters -- for in-
stance PF1 sends three characters: ESCAPE (ASCII 033),  followed  by  "O",  and
"P".  On others, the function keys may have arbitrary strings assigned to them.
For instance, if you find yourself typing "Aaaarrrgggghhh!!!  Sigh..."  a  lot,
you  can  assign  this  string to function key F1, and then pressing the F1 key
will cause this entire character string to be transmitted.

Macintosh Kermit Function Keys:

The Macintosh has no physical function keys -- no keys are marked F0,  F1,  F2,
etc.    However,  any key (modified by any combination of modifier keys) may be
designated as a "soft" function key.

Selecting "Function Definitions..." from the SET menu brings  you  to  the  SET
FUNCTIONS  dialog (it would be nice if you could double click on a function key
in the SET KEYS dialog but that is not yet available).

Use SET FUNCTIONS to declare a function definition string.  Scroll through  the
function  definition  list and select a function to define, preferably starting
with F0, though this is not required (high numbered functions are reserved  for
special  uses).  Type in the function definition; non printable characters must
be entered with a backslash ("\") followed by exactly (yes exactly) three octal
characters  representing  the  ASCII  value,  for  instance "\015" for carriage
return.  A backslash itself is entered as "\134".  The function definition  has
to fit in the box.

Having  defined a function, you must use SET KEYS to actually associate it with
a key.  Note that it is possible to associate a function  with  more  than  one
key.


1.7.6.3. DIALOG: Set Keys

Selecting  the  "Keys..." menu item under SET initiates the SET KEYS dialog for
redefining individual keys.

SET KEYS displays a picture of the keyboard.  You  can  either  hold  down  the
modifier  and key you wish to define or click on the displayed picture with the
mouse (double clicking on one of the modifier keys brings up the  SET  MODIFIER
KEYS  dialog).    Once a key is selected, it and any modifiers are highlighted,
the name of the key and its value are displayed in the  lower  portion  of  the
dialog.    You  may  enter the new value in the little box by selecting the box
with the mouse and then typing a DECIMAL (yes decimal) number from  0  to  127.
Then  you should click on either SET KEY or else SET FUNCTION KEY.  Clicking on
SET KEY means that the key should transmit the ASCII character corresponding to
the  given  value (subject to modification by the meta key); clicking SET FUNC-
TION KEY means the number you entered in the box is a function number and  that
the key should transmit the character string associated with that function.

SET KEYS does not display a picture of the numeric keypad, but may be used with
the keypad anyway -- just select the desired key by pressing it and then define
it as above.


1.7.7. MENU: File

The  File  menu  must be used to Open a Kermit settings file before CKMKEY will
allow you do perform any other operations.   You  may  also  Quit  from  CKMKEY
through  the File menu, and you can save your work.  The Save option allows you
to save the settings file back under its own name, replacing the previous copy.
If you need to make copies of settings files, you can use Kermit itself to save
them under different names, or else you can use the Finder.

There is also a Decompile option, that is of use only to programmers working on
Macintosh  Kermit -- it decompiles the key definition resource into a form that
can be included in a C program.


1.7.8. CKMKEY Known Limitations, Restrictions, Bugs

   - There is no picture of the numeric keypad in Set Keys.

   - In Set Keys, when you strike a key on the numeric keypad, its name is
     not displayed.  You can still make assignments to the key.

   - There  is  no  way to define a key from the numeric keypad unless you
     actually have a numeric keypad.

   - You can't save from CKMKEY under a different name.  Use the Finder or
     Kermit to do that.

   - You  must  use  decimal  numbers in the SET KEY dialog, and backslash
     followed by 3 octal digits in function definitions, which can be con-
     fusing.

   - You  may  have  problems  on a 128K mac if you define many long func-
     tions.

   - CKMKEY doesn't deal with write protected diskettes very well.


1.7.9. Unlocking CAPS LOCK

(Adapted   from   directions   posted   by   David   Chase    <rbbb@rice>    on
INFO-MAC@SUMEX-AIM, Friday 14 December 1984.  Follow these instructions at your
own risk.  Not the authors, nor David Chase, nor Columbia University, nor  Rice
University  provide  any  warranty,  nor  acknowledge  any liability or respon-
sibility for damage, injury, inconvenience, or loss of Apple or  other  service
warranty sufferred as a result of the publication of these directions.)

A  major  impediment to using the Macintosh as a terminal is that the CAPS LOCK
key is where you would normally  expect  to  find  the  CONTROL  key.    A  key
redefinition  package,  such  as CKMKEY, can assign the CONTROL function to the
COMMAND or OPTION keys but these keys are not easy to reach.  CONTROL can  also
be assigned to the CAPS LOCK key using software, but the CAPS LOCK key includes
a mechanical locking device.  The following directions tell how to  remove  the
locking  device  so  that  the CAPS LOCK key will go up and down like the other
keys.  PROCEED AT YOUR OWN RISK.

Tools you'll need:

   - Phillips screwdriver for screws on bottom of the keyboard.
   - Solder sucker/wick.
   - Soldering iron.
   - Small prying tools (jewelers screwdrivers, small knife blade, etc).
   - Tweezers/small needlenose pliers.
   - Some paper clips or straight pins.

Now follow these steps:

   1. Remove the five screws.  The keyboard should fall into three pieces.

   2. GENTLY pry off the Caps Lock keycap.  This takes a little patience.

   3. Remove the restoring spring so it doesn't get in the way.

   4. Locate the two connections to the Caps Lock key on the back  of  the
      PC  board, and remove all solder from them using wick or sucker.  Be
      careful not to overheat the solder pads, since they can  be  damaged
      (come loose from the PC board).

   5. Pry  back  the  plastic locking clips holding the key in, and remove
      it.  (All the keys are clipped into a metal  frame.    Removing  the
      metal  frame is not possible, since all the keys are soldered to the
      PC board, and clipped to the frame.  The clips are  located  "north"
      and  "south"  of  the  key,  where the number row is "north" and the
      space bar "south".)  There are four clips holding the bottom of  the
      key on; pry these back, and, WHILE HOLDING THE KEY BOTTOM UP, remove
      the bottom of the key.  You may have to use  some  makeshift  tools,
      like a couple of unbent paper clips, to hold the four clips open.

   6. Two   pieces  should  be  ready  to  fall  out;  a  small  piece  of
      PC-board-like material (about 7/16 by 3/32 inch, with two notches on
      one edge and a tiny hole in the center), and a tiny piece of wire (a
      small, beefy staple with short legs).  Let them fall  out.  (It  may
      help  to  toggle the key).  These two pieces are the locking device,
      they should be removed and left out of the reassembly.

   7. Replace the restoring spring, snap the key back into place, resolder
      the two leads, screw the keyboard back together, and replace the key
      cap.  You may wish to experiment with the spring to reduce the key's
      springiness  (this  can  be done with the keyboard assembled, though
      removing the cap is more difficult).

For those who want to map the CAPS LOCK key to CTRL, but don't  want  to  alter
the  keyboard as described in the manual, but still want to inhibit the locking
function, the following suggestion is offered:

Pry off the key using a small screwdriver.  There is a spring  whose  end  goes
through the plastic support.  Stick a very small wad of paper or soft putty be-
tween the tip and the bottom of the keyboard.  This will prevent the  key  from
depressing  all the way and locking, but still allow contact of the key.  Even-
tually, the paper will work loose and you will need to find it and  repeat  the
procedure.



Index

,
          Binhex   1

          CKMKER   0
          CKMKEY   1

          Macintosh Kermit   0
          META Key   2

          Setfile   1



                               Table of Contents

1. MACINTOSH KERMIT                                                           0

   1.1. The Macintosh File System                                             0
   1.2. File Transfer                                                         0
   1.3. Remote Commands                                                       0
   1.4. Settings                                                              0
   1.5. Terminal Emulation                                                    1
   1.6. Installation                                                          1
   1.7. CKMKEY - Macintosh Kermit's Keyboard Configurator                     1
       1.7.1. What is CKMKEY?                                                 1
       1.7.2. Modifier vs Normal Keys                                         1
       1.7.3. Key Maps                                                        1
       1.7.4. What's in CKMKEY's Keymaps                                      1
       1.7.5. Menus                                                           2
       1.7.6. MENU: Set                                                       2
           1.7.6.1. DIALOG: Set Modifer Keys                                  2
           1.7.6.2. DIALOG: Set Function Definitions                          2
           1.7.6.3. DIALOG: Set Keys                                          3
       1.7.7. MENU: File                                                      3
       1.7.8. CKMKEY Known Limitations, Restrictions, Bugs                    3
       1.7.9. Unlocking CAPS LOCK                                             3

Index                                                                         i



                                List of Figures

   Figure 1-1:   Macintosh Kermit Modifier Key Dialog                         2