
                  -----------------------------            
                          MOCHA TELNET 

                           USER GUIDE

                          Version 1.00
             
                  -----------------------------            

Contents
========

1.0 Product Overview
1.1   Functionality
1.2   Mark and Copy
1.3   Connect
1.4   Function keys
1.5   Focus

2.0 Modes 
2.1   Java Application 
2.2   Java Applet 
2.3   Java pop-up Applet

3.0 Limitations 
3.1   Which hosts to connect
3.2   Control the size and position of pop-up windows
3.3   Character Set
 
4.0 Parameters
4.1   Configuration file
4.2   HTML page
4.3   Parameter type 
4.4   Parameter keyfile 
4.5   Parameter license 
4.6   Parameter license_key 
4.7   Parameters script1 and script2
4.8   Parameter negotiate
4.9   Parameter local_echo
4.10  Parameter auto_wrap
4.11  Parameter new_line
4.12  Parameter keyboard_bar
4.13  Parameter scroll_bar
4.14  Parameter color_bg
4.15  Parameter color_fg
4.16  Parameter color_blink
4.17  Parameter color_cursor
4.18  Parameter page_color
4.19  Parameters screen_width and screen_height
4.20  Parameters screen_x and screen_y
4.21  Parameters host and port
4.22  Parameter auto_stop
4.23  Parameter termtype
4.24  parameter debug
4.25  parameters proxy_host, proxy_port and proxy_syntax

5.0 Keyboard mapping
5.1   Default keyboard
5.2   Transmitted Codes

6.0 License System

7.0 Files 

1.0 Product overview
================
Mocha Telnet is a telnet emulator written in java, which makes it possible
from a java enabled browser, as Microsoft Internet Explorer or Netscape 
Navigator, to connect a UNIX server.

1.1 Functionality
=================
 - Supports VT100/VT220/ANSI emulation. 
 - Layout as a Windows'95 application.. 
 - Automatic resize of applet window
 - Mark/copy with the mouse.
 - Scroll Bar (as Xterm).
 - User defined functions keys.
 - Functions keys can also be shown as push buttons.
 - Autologin with scripting parameter.
 - Many trim parameters. 
 - Can run either as
     - Java Application.
     - Applet.
     - Applet pop-up window. 

1.2 Mark and Copy
=================
It is possible inside the applet to mark part of a text, and save it in a 
paste buffer. Later it can be copied.

To mark a text, place the cursor at the upper left corner of the text. Press
left mouse button down and drag the cursor. A box is show. When the left mouse
button is released the marked text is copied to the paste buffer. 

The contents of the paste buffer can be copied to the cursor position, either
with right mouse button or from the menu (edit-paste).

 
1.3 Connect
===========
It is possible to connect to a host from the File menu. A pop-up window is 
shown. Enter a host name and a port number . The port number for telnet is 
default 23. How to use a proxy host, see parameter proxy_host, 4.25. 
If the name service is not running correct or the host does not response, some 
workstations can hang for a minute or more. Mocha Telnet can do nothing about
it. It is not possible to cancel a started request in the current version
of Java.

1.4 Function keys
=================
As the layout of a Java keyboard is different from a VT220 keyboard, some
changes has been necessary.

- Only keypad 1,2,3,4,6,7,8,9,pf1,pf2,pf3,pf4 can be used.
- Function keys F1 to F12 can be pressed either in normal, shifted or 
  ctrl mode.
- Function keys F1 - F20 can be pressed with the mouse.
- Key F10 is controlled from some browsers, meaning if key F10 is pressed
  the browser takes control, and Mocha Telnet lose its focus for the keyboard.

See chapter 5 for a description of how to use and define function keys

1.5 Focus
=========
As with normal Microsoft windows the title bar of the window will have
the color blue when in focus and grey when not in focus.

2.0 Modes
=========
It is possible to start Mocha Telnet in different layout modes.
The mode number will be used in chapter 4, (parameters) to indicate when 
the parameter is valid.
The most useful mode will in most cases be mode 2 (applet).


2.1 Java Application - mode 1
=============================
It is possible to start Mocha Telnet direct with an interpreter. It can be 
useful in some configurations, as a pure NC environment. If the interpreter
is named java the syntax is:

  java telnetexe <host> [<configuration file>]

where 

  host                : name of Unix host to connect.
  configuration file  : name of configuration file. If omitted telnet.cfg
                        will be used.

Mocha Telnet will pop up as a window frame, which can be moved and scaled
on the page.

2.2 Java Applet - mode 2
========================
Mocha Telnet is started as part of a HTML page. It will have a fixed 
position and size. 

2.3 Java pop-up Applet - mode 3
===============================
As mode 2 but Mocha Telnet runs as a window frame, which can be moved and 
scaled on the page. A Warning message will be displayed at the bottom of the
window. Microsoft Internet Explorer shows : "Warning: Applet Window"

3.0 Limitations
===============
As to the strict security issue for java applets there is some limitations
on the functionality for Mocha Telnet.

3.1 Which hosts to connect
==========================
It is only possible to create a connection on the host, from where the applet 
has been downloaded. This limitation is build into the browser.
It is possible to install a proxy server on the host, which could route the 
telnet request to another host. A better solution is to install Mocha Telnet
on all the hosts, to which the workstation wants to connect.

It is not possible for an Internet user, who hides behind a firewall to connect
to a host with a Mocha Telnet applet. Anyway who wants to run telnet over the 
slow internet. 

3.2 Control the size and position of pop-up windows
=================================================
Some browsers does not give the possibility for an applet to define where and 
the size of a window applet. Therefore the parameters screen_width/
screen_height and screen_x/screen_y could give less meaning in some cases.

3.3 Character Set
=================
Some browsers does not support semi-grafic in all font sizes. Instead a
dummy character is shown (a small box). Try another size of the applet, or
start Mocha Telnet as a frame and resize the window, until a font with
support of semi-grafic is shown.
 
4.0 Parameters
==============
Parameters to Mocha Telnet is given in a file if running in mode 1
(application), and in mode 2 and 3 as parameters in HTML format.

Following syntax is used in this chapter: 

 <text>      : don't include < > as part of the parameter
 text1|text2 : use either text1 or text2

4.1 Configuration file
================================
The configuration file is as default named telnet.cfg. The syntax is:

# This is a comment line
name=value

Example of a simple file:

  #Configuration file for Mocha telnet
  color_cursor=#203048    
  keyboard_bar=true
  keyfile=keys.new

The different types of names are given in chapter 4.3 - 4.24.

4.2 HTML page
=========================
An applet is defined in a HTML page with label <APPLET>. See other source of 
information for how to write HTML.

An example of a HTML page:

<HTML>
<HEAD>
<TITLE> Mocha Telnet example </TITLE>
</HEAD>
<BODY>
<APPLET CODE="telnet.class" WIDTH=700 HEIGHT=500>
<param name=host value="unix">
<param name=port value="23">
<param name=color_cursor value="#203047">
<param name=keyboard_bar value="true">
<param name=type value="applet">
<param name=script1 value="login:=guest">
<param name=script2 value="Password:=anonymous">
</APPLET>
</BODY>
</HTML>

CODE parameter must always be "telnet.class". It is the name of the master file
for the binary Mocha Telnet product.
WIDTH and HEIGHT gives the size of the applet. If running in mode 3 as a 
pop-up window, state the WIDTH and HEIGHT to 1. 

Just as for the configuration file in chapter 4.1, each parameter is build of
a name and a value. In the example above parameter host is given value unix.
It is very important to remember <> around each line, and the value must be 
surrounded with "".

4.3 Parameter type (mode 2,3)
===============================
gives the type of the applet. A pop-up window or an "normal" applet.

Syntax:

  name=applet value="frame|applet"

  Frame is a pop-up window.

4.4 Parameter keyfile (mode 1,2,3)
===============================
It is possible to define values for all Function keys (F1-F20). These values 
are defined in a file with default name "keys". With this parameter another 
file can be used.

Syntax:

  name=keyfile value="<a file name>"


4.5 Parameter license (mode 1,2,3)
===============================
Name of the company using Mocha Telnet. Should only be included together 
with parameter "license_key".

SYNTAX:

  name=license value="<name of a company>" 
 
4.6 Parameter license_key (mode 1,2,3)
===============================
When ordering Mocha Telnet, an encrypted license code will be received. Use
this together with parameter "license" to clear the DEMO warning in the
title line.

SYNTAX:

  name=license_key value="<encrypted key>"

 
4.7 Parameter script1 and script2  (mode 1,2,3)
===============================================
Use these two script options to perform auto login, when the applet is loaded.
Of course it can not be recommended to include a secret login and password 
in a HTML page, as everyone can read the source from a browser.

Also only use the script option for login and password, as it cost a lot of 
cpu to scan all text from the host for a match.

SYNTAX:

  name=script1 value="<text to find>=<text to answer with>
  name=script2 value="<text to find>=<text to answer with>

Example:

  name=script1 value="Login=guest"
  name=script2 value="Password=funny"

 
4.8 Parameter negotiate (mode 1,2,3)
====================================
When a telnet session is created to a host, a negotiation takes place, where 
the setup of endpoints is agreed on. If this parameter is used, the negotiation
will be displayed.

SYNTAX:

  name=negotiate value="true|false"

Default is false.

4.9 Parameter local_echo (mode 1,2,3)
=====================================
It is possible to let all characters typed on the keyboard be displayed on the
screen as default. Normally this is not a good idea. 
It the host wants to run in this mode, it can ask Mocha Telnet direct.
Most hosts will overwrite this parameter in the startup negotiation.

SYNTAX:

  name=local_echo value="true|false"

Default is false.

4.10 Parameter auto_wrap (mode 1,2,3)
=====================================
Auto_wrap defines, if the cursor should jump to the start of the next line,
when it exceeds the end of a line.

SYNTAX:

  name=auto_wrap value="true|false"

Default is true.

4.11 Parameter new_line (mode 1,2,3)
====================================
The new_line parameter defines if <RETURN> key should send <cr> <lf> or
just <cr>.

SYNTAX:

  name= new_line value="true|false"

Default is false, which means only <cr>.

4.12 Parameter keyboard_bar (mode 1,2,3)
========================================
Defines if function keys F1 - F20 should be displayed as buttons.

SYNTAX:

 name=keyboard_bar value="true|false"

Default is true.

4.13 Parameter scroll_bar (mode 1,2,3)
======================================
Defines if a scroll bar should be displayed.

SYNTAX:

 name=scroll_bar value="true|false"

Default is true.

4.14 Parameter color_bg (mode 1,2,3)
====================================
The color of the background can be defined with this parameter.

SYNTAX:

  name=color_bg value="#rrggbb"

where rr is red color in hex (0-FF).
      gg is green color in hex (0-FF).
      bb is blue color in hex (0-FF).

The syntax is the same as used in the HTML language.

Example:

  name=color_bg value="#20f030"

4.15 Parameter color_fg (mode 1,2,3)
====================================
The color of the foreground (characters) can be defined with this parameter.

SYNTAX:

  name=color_fg value="#rrggbb"

where rr is red color in hex (0-FF).
      gg is green color in hex (0-FF).
      bb is blue color in hex (0-FF).

The syntax is the same as used in the HTML language.

 
4.16 Parameter color_blink (mode 1,2,3)
=======================================
To save CPU, Mocha Telnet will not show blinking text. Instead a color can be
used to highlight this type of text.

SYNTAX:

  name=color_blink value="#rrggbb"

where rr is red color in hex (0-FF).
      gg is green color in hex (0-FF).
      bb is blue color in hex (0-FF).

The syntax is the same as used in the HTML language.

 
4.17 Parameter color_cursor (mode 1,2,3)
========================================
The color of the cursor can be defined with this parameter.

SYNTAX:

  name=color_cursor value="#rrggbb"

where rr is red color in hex (0-FF).
      gg is green color in hex (0-FF).
      bb is blue color in hex (0-FF).

The syntax is the same as used in the HTML language.

 
4.18 Parameter page_color (mode 2)
==================================
When Mocha Telnet is loaded as an applet, it will resize to use the largest 
possible font given the size of the applet. As browsers and screen solutions
vary between different workstations there will always be some space left around
the Mocha Telnet applet which cannot be used. 
This parameter defines the color of this space and it should be set to the 
color of the HTML page.

SYNTAX:

  name=page_color value="#rrggbb"

where rr is red color in hex (0-FF).
      gg is green color in hex (0-FF).
      bb is blue color in hex (0-FF).

The syntax is the same as used in the HTML language.

 
4.19 Parameters screen_width and screen_height (mode 1,3)
=========================================================
If started as a frame window, these parameters defines the size of the window 
in pixels.

SYNTAX:

  name=screen_width value=<number>
  name=screen_height value=<number>

Default is 600 x 600. 
 
4.20 Parameters screen_x and screen_y (mode 1,3)
================================================
If started as a frame window, these parameters defines the upper left corner
of the window in pixels.

SYNTAX:

  name=screen_x value=<number>
  name=screen_y value=<number>

Default is 100,75. 

4.21 Parameters host and port (mode 2,3)
================================================
These parameters defines which host to connect, when the applet is loaded.
The default port number for telnet is 23. 

SYNTAX:

  name=host value=<a host name>
  name=port value=<number>

Default port is 23. The host name can either be a name or an internet
address as 198.66.23.11

4.22 Parameter auto_stop (mode 2,3)
================================================
Auto_stop selects if a telnet session should terminate when the
user select another HTML page
 
SYNTAX:

  name=auto_stop value=<true|false>

Default is true

4.23 Parameter termtype (mode 1,2,3)
================================================
Mocha Telnet can on request from host inform about the type of
terminal it emulates. (In unix it is the environment variable TERM)
 
SYNTAX:

  name=termtype value=<type of terminal emulation>

Default is vt220
 
4.24 Parameter debug (mode 1)
================================================
It is possible to copy all data coming from the host to a raw file.
This file can be used later for debug purpose. The name of the file
is always "trace". As to security, this parameter will only work in mode 1.
 
SYNTAX:

  name=debug value=<true|false>

Default is false

4.25 Parameters proxy_host, proxy_port and proxy_syntax (mode 1,2,3) 
====================================================================
It is possible to use a telnet proxy host as gateway to other hosts. Mocha
Telnet will connect to the proxy host, and issue a new connect sequence.
 
SYNTAX:

  name=proxy_host value=<proxy host name>
  name=proxy_port value=<proxy port number>
  name=proxy_syntax value=<syntax>
   
proxy_syntax defines how to format the Connect sequence send to the
proxy host. 

  $1 = proxy_host
  $2 = proxy_port
  \abc = octal value. (LF = \012 and CR = \015)

Example: 

  name=proxy_host value=myproxy
  name=proxy_port value=911
  name=host value=wintermute
  name=port value=23
  name=proxy_syntax value=\012Connnect $1:$2\015\012

  Mocha Telnet will connect to myproxy port 911, and send the connect
  sequence: <LF>Connect wintermute:23<CR><LF>
 
5.0 Keyboard mapping
====================
As it is individual how to map the keyboard, all function keys has
been made changeable.

The default configuration file is named "keys", and should exist in the same 
catalog as the *.class files of Mocha Telnet. 

Syntax for file "keys":

  Comments starts with #
  <key> <codes>  # comment

  Following keys can be defined:

    UP
    DOWN
    RIGHT
    LEFT
    HOME
    END
    PGUP
    PGDN
    fxx , where xx is 1 .. 20 (function key f1 - f20)
    Fxx , where xx is 1 .. 20 (shift + function key f1 - f20)
    cfxx , where xx is 1 .. 20 (ctrl + function key f1 - f20)
    CFxx , where xx is 1 .. 20 (shift + ctrl + function key f1 - f20)
 
Example of a "keys" file:

# VT220 keymap file
# \033 = ESC
UP   \033[A
DOWN \033[B
RIGHT \033[C
LEFT \033[D
f1   \033[11~
f2   \033[12~
f3   \033[13~  # a comment
....
 
remark none ASCII characters are written in octal as \xxx , where
xxx is the octal value.

5.1 Default keyboard
====================
The default file "keys", contains following mapping of the keyboard:

  Key           mapping        Key                mapping      
-----------------------      ----------------------------    
  f1              f1           crtl f1              f11          
  f2              f2           ctrl f2              f12          
  f3              f3           ctrl f3              f13          
  f4              f4           ctrl f4              f14          
  f5              f5           ctrl f5              f15          
  f6              f6           ctrl f6              f16          
  f7              f7           ctrl f7              f17          
  f8              f8           ctrl f8              f18          
  f9              f9           ctrl f9              f19          
  f10             f10          ctrl f10             f20         
  f11             f11          ctrl f11             f10         
  f12             f12          ctrl f12             f20         
                                                 
  Key           mapping        Key                mapping      
-----------------------      ----------------------------    
  shift f1        f1           crtl shift f1        pf1          
  shift f2        f2           ctrl shift f2        pf2          
  shift f3        f3           ctrl shift f3        pf3          
  shift f4        f4           ctrl shift f4        pf4          
  shift f5        f5           ctrl shift f5        f15          
  shift f6        f6           ctrl shift f6        f16          
  shift f7        f7           ctrl shift f7        f17          
  shift f8        f8           ctrl shift f8        f18          
  shift f9        f9           ctrl shift f9        f19          
  shift f10       f10          ctrl shift f10       f20         
  shift f11       f11          ctrl shift f11       f10         
  shift f12       f12          ctrl shift f12       f20         

Remark shifted function keys sends the same codes as unshifted. It
is up to the System Administrator to define a better use for these
keys, as they are not part of a standard vt220 terminal.
                                                 
Part of the auxiliary keypad can be used as:

  key           mapping        key                mapping
--------------------------   ----------------------------
  ctrl 1 (End)   keypad 1      crtl shift f1        PF1 
  ctrl 2 (down)  keypad 2      crtl shift f2        PF2
  ctrl 3 (pgdn)  keypad 3      crtl shift f3        PF3
  ctrl 4 (left)  keypad 4      crtl shift f4        PF4
  ctrl 6 (right) keypad 6
  ctrl 7 (home)  keypad 7
  ctrl 8 (up)    keypad 8
  ctrl 9 (pgup)  keypad 9
 
If other keys in the auxiliary keypad are needed, some function keys
must be changed in the "keys" file.

5.2 Transmitted Codes
=====================
When the default "keys" file is used the keyboard will transmit following
codes:

Editing Keys        
-------------       
 
key     codes
-----------------
HOME    CSI 1 ~     
END     CSI 2 ~
PGUP    CSI 5 ~
PGDN    CSI 6 ~

Cursor Control Keys
--------------------

key     normal   application     vt52
---------------------------------------
UP      CSI A    SS3 A           ESC A
DOWN    CSI B    SS3 B           ESC B
RIGHT   CSI C    SS3 C           ESC C
LEFT    CSI D    SS3 D           ESC D

Auxiliary keypad keys
----------------------

key    normal      vt52
----------------------------
0  *   SS3 p       ESC?p
1      SS3 q       ESC?q
2      SS3 r       ESC?r
3      SS3 s       ESC?s
4      SS3 t       ESC?t
5  *   SS3 u       ESC?u
6      SS3 v       ESC?v
7      SS3 w       ESC?w
8      SS3 x       ESC?x
9      SS3 y       ESC?y
-  *   SS3 m       ESC?m
,  *   SS3 l       ESC?l
.  *   SS3 n       ESC?n
enter* SS3 M       ESC?M
pf1    SS3 P       ESC?P
pf2    SS3 Q       ESC?Q
pf3    SS3 R       ESC?R
pf4    SS3 S       ESC?S 

(*) not implemented in Mocha Telnet, as the browser does not give
    access to the keys.

Function Keys
--------------

key             codes            key              codes
-------------------------        ---------------------------------
F1              \033[11~         shift F1         \033[11~ 
F2              \033[12~         shift F2         \033[12~ 
F3              \033[13~         shift F3         \033[13~ 
F4              \033[14~         shift F4         \033[14~ 
F5              \033[15~         shift F5         \033[15~ 
F6              \033[17~         shift F6         \033[17~ 
F7              \033[18~         shift F7         \033[18~ 
F8              \033[19~         shift F8         \033[19~ 
F9              \033[20~         shift F9         \033[20~ 
F10             \033[21~         shift F10        \033[21~ 
F11             \033[23~         shift F11        \033[23~ 
F12             \033[24~         shift F12        \033[24~ 
F13             \033[25~         shift F13        \033[25~ 
F14             \033[26~         shift F14        \033[26~ 
F15             \033[28~         shift F15        \033[28~ 
F16             \033[29~         shift F16        \033[29~ 
F17             \033[31~         shift F17        \033[31~ 
F18             \033[32~         shift F18        \033[32~ 
F19             \033[33~         shift F19        \033[33~ 
F20             \033[34~         shift F20        \033[34~ 

key             codes            key              codes
---------------------------      ------------------------------
ctrl F1         \033[23~         ctrl shift F1    \217P    
ctrl F2         \033[24~         ctrl shift F2    \217Q    
ctrl F3         \033[25~         ctrl shift F3    \217R    
ctrl F4         \033[26~         ctrl shift F4    \217S    
ctrl F5         \033[28~         ctrl shift F5    \033[28~ 
ctrl F6         \033[29~         ctrl shift F6    \033[29~ 
ctrl F7         \033[31~         ctrl shift F7    \033[31~ 
ctrl F8         \033[32~         ctrl shift F8    \033[32~ 
ctrl F9         \033[33~         ctrl shift F9    \033[33~ 
ctrl F10        \033[34~         ctrl shift F10   \033[34~ 
ctrl F11        \033[21~         ctrl shift F11   \033[21~ 
ctrl F12        \033[34~         ctrl shift F12   \033[34~ 
ctrl F13        \033[34~         ctrl shift F13   \033[34~ 
ctrl F14        \033[34~         ctrl shift F14   \033[34~ 
ctrl F15        \033[34~         ctrl shift F15   \033[34~ 
ctrl F16        \033[34~         ctrl shift F16   \033[34~ 
ctrl F17        \033[34~         ctrl shift F17   \033[34~ 
ctrl F18        \033[34~         ctrl shift F18   \033[34~ 
ctrl F19        \033[34~         ctrl shift F19   \033[34~ 
ctrl F20        \033[34~         ctrl shift F20   \033[34~ 
 

6.0 License System
=================
The license system for Mocha Telnet is very user friendly. The encrypted
parameter "license_key", together with parameter "license" gives a check for
legal use. Therefore it is not possible to change the company name in
"license", without ordering a new key from MochaSoft.

If parameter "license_key" is not given, the program will run in Demo mode, 
and display a banner in the title line. There will be no limitations on 
functionality.

7.0 Files
=========
Following files must exist together with the HTML page loading
Mocha Telnet

   telnet.class
   netsoc.class
   vttimer.class
   vtpop.class
   telnetexe.class (only for mode 1)
   vt.class
   vidram.class
   keys
   telnet.cfg (only for mode 1)

