MOCHA TN3270
USER GUIDE

Mocha TN3270 is an TN3270 emulator written in java, which makes it possible from a java enabled browser, as Microsoft Internet Explorer or Netscape Navigator, to connect an IBM Mainframe, which supports TN3270.

1.1 Functionality

Supports Extended Field Attributes

Alternate screen size (24x80 or 32x80)

Unprotected fields can be shown in a different color

User defined color values

Layout as a Windows'95 application..

Pop down menu's

Keyboard mapping help window

Automatic resize of applet window

User defined keyboard layout

Functions keys can also be shown as push buttons.

Many trim parameters.

Can run either as

Java Application.

Applet.

Applet pop-up window.

1.2 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 TN3270 is default 23. How to use a proxy host, see parameter proxy_host, 4.21. If the name service is not running correct or the host does not response, some workstations can hang for a minute or more. Mocha TN3270 can do nothing about it. It is not possible to cancel a started request in the current version of Java.

1.3 Function keys

As the layout of a Java keyboard is different from a 3270 keyboard, some changes has been necessary.

Function keys F1 to F12 can be pressed either in normal, shifted or ctrl mode.

PF1 - PF24, PA1, PA2, PA3, INSERT, CLEAR, DUP and FM can be pressed with the mouse.

Key F10 cannot be used in all browser environments.

Ins/Insert keys on the pc-keyboard cannot be used.

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

1.4 Status line

Last line in the applet shows, as on a real IBM 3270 screen the status of the session. The layout is:

-------------------------------------------------------------------------
  TN    <line state>   <session state>      <insert mode>  <last key>
-------------------------------------------------------------------------

TN

Connected to a host supporting the TN3270 protocol

Line state

REQUEST : Mocha Tn3270 asks host for a connection
ONLINE : Connection has been established
OFFLINE : No connection

Session state

X-WAIT:
A request has been send to the host, and the user must wait on a response. RESET key (ESC) can clear this state.

X-WRONG INPUT :
User enters data which is not legal. As an example if the cursor is not placed on an input field. If non numeric data is entered in a numeric field the text "(numeric)" is added to X-WRONG INPUT. Move the cursor or press RESET, to release the error situation. On a real 3270 screen, the user must press the RESET key.

Insert mode

INSERT:
data is inserted at the cursor position, and characters after the cursor moves to the right. Use the INSERT key (not Insert on the pc keyboard!) to select/release this option.

Last key

Shows last function key pressed: PF1 - PF24, ENTER, CLEAR ,PA1 PA2 or PA3.

1.5 Focus

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

2.0 Modes

It is possible to start Mocha TN3270 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 TN3270 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 TN3270exe host [configuration file]

where

host : name of Unix host to connect.

configuration file : name of configuration file. If omitted TN3270.cfg will be used.

Mocha TN3270 will pop up as a window frame, which is movable, and also can be scaled on the page.

2.2 Java Applet - mode 2

Mocha TN3270 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 TN3270 runs as a window frame, which is movable, and also can be 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 TN3270.

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 TN3270 request to another host. A better solution is to install Mocha TN3270 on all the hosts, to which the workstation wants to connect.

If the signed CAB file version is use, it is possible with IE 4/5 to overrule the security limitation. See file TN32703.HTML

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 Known Restrictions

The following 3270 elements have not been implemented:

blinking

programmed symbols

sound alarm

light pen

file transfer (IND$FILE)

4.0 Parameters

Parameters to Mocha TN3270 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 TN3270.cfg. The syntax is:

# This is a comment line
name=value

Example of a simple file:

#Configuration file for Mocha TN3270
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 TN3270 example </TITLE>
</HEAD>
<BODY>
<APPLET CODE="tn3270.class" WIDTH=700 HEIGHT=500>
<param name=host value="ibm">
<param name=port value="23">
<param name=color_cursor value="#203047">
<param name=keyboard_bar value="true">
<param name=type value="applet">
</APPLET>
</BODY>
</HTML>

CODE parameter must always be "tn3270.class". It is the name of the master file for the binary Mocha TN3270 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 ibm. 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)

Keyboard mapping between pc-key board and 3270 keyboard 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 TN3270. 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 TN3270, 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 negotiate (mode 1,2,3)

When a TN3270 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.8 Parameter keyboard_bar (mode 1,2,3)

Defines if function keys PF1 - PF24, PA1, PA2, PA3, INSERT, CLEAR, DUP and FM should be displayed as buttons.

Syntax:

name=keyboard_bar value="true|false"

Default is true.

4.9 Parameter unprotected_show (mode 1,2,3)

Defines if unprotected fields (input fields) should be displayed in another color than the background color.

SYNTAX:

name=unprotected_show value="true|false"

Default is false.

4.10 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.11 Parameter color_unprotected (mode 1,2,3)

If parameter "unprotected_show" is enabled, this parameter defines the color for the background of unprotected fields. This parameter can also be trimmed from the menu.

Syntax:

name=color_unprotected 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_unprotected value="#20fd33"

4.12 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.13 Parameter page_color (mode 2)

When Mocha TN3270 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 TN3270 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.14 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.15 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.16 Parameters host and port (mode 2,3)

These parameters defines which host to connect, when the applet is loaded. The default port number for TN3270 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.17 Parameter auto_stop (mode 2,3)

Auto_stop selects if a TN3270 session should terminate when the user select another HTML page

Syntax:

name=auto_stop value="true|false"

Default is true.

4.18 Parameter termtype (mode 1,2,3)

The termtype is send to the host in the login phase. It defines the type of terminal supported.

IBM-3278-2-E : Model 2 screen size 24*80

IBM-3278-3-E : Model 3 screen size 32*80

Syntax:

name=termtype value=<type of terminal emulation>

Default is IBM-3278-2-E

4.19 Parameter alternate (mode 1,2,3)

The application on the IBM host can request for an alternate screen size. This parameter defines the size. Normally this parameter should follow the name define in termtype (4.19).

SYNTAX:

name=alternate value=<24 or 32>

Default is 32

4.20 Parameter debug (mode 1)

It is possible to copy all data coming from the host to a 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.21 Parameters proxy_host, proxy_port and proxy_syntax(mode 1,2,3)

It is possible to use a TN3270 proxy host as gateway to other hosts. Mocha TN3270 will connect to the proxy host, and issue a new connect sequence.

Either Mocha W32 TN3270 can be configurated to use SOCKS Version 4 protocol, or it can be defined to send an ASCII connect sequence to the Proxy Telnet Server.

SYNTAX:

name=proxy_host value=<proxy host name>

name=proxy_port value=<proxy port number>

name=proxy_socks value=<true or false>

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 TN3270 will connect to myproxy port 911, and send the connect sequence: <LF>Connect wintermute:23<CR><LF>

It is also possible to enter the login sequence to the proxy host from the keyboard. Just define the value of proxy_syntax as "\015" or " ".

From version 1.5 of Mocha TN3270 it is possible to use the SOCKS protocol.

Use parameters

proxy_socks=true

proxy_port=1080

If SOCKS protocol is used, Proxy Syntax can be left unused. Any text in this field is send as USERID in the SOCKS Connect request. Some proxy servers uses this field as identification, and Guest could be a possible entry.

As the use of a host name, which must use DNS to be resolved can give a security violation in the browser, it is a good idea to define the parameter host as a raw ip address, as 152.1.1.1.

4.22 Parameter ebcdic_file (mode 1,2,3)

It is possible to define which EBCDIC <--> ascii table to use.

SYNTAX:

name=ebcdic_file value=<file name>

Default is tn3270.ebc

4.23 Parameter color_XXXX (mode 1,2,3)

It is possible to change the default colors. 3270 uses the colors as:

green : unprotected normal intensity
red : unprotected intensified
blue : protected, normal intensity
white : protected, intensified

Modern applications can use extended attributes, which gives even more colors.

SYNTAX:

name=color_blue value="#rrggbb"

name=color_green value="#rrggbb"

name=color_white value="#rrggbb"

name=color_red value="#rrggbb"

name=color_yellow value="#rrggbb"

name=color_ping value="#rrggbb"

name=color_turquoise 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).

4.24 Parameter font (mode 1,2,3)

Possible to define the display font

SYNTAX:

name=font value="font name"

Default is Courier

4.25 Parameter alive (mode 1,2,3)

Use this command to force tn3270 to send keep alive (IAC 241) every 15 second

SYNTAX:

name=alive value="true|false"

Default is false

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 TN3270.

Syntax for file "keys":

Comments starts with #

<pc-key> <3270-key>

The pc-key's are:

fxx	: xx is 1 .. 12	(function key f1 - f12)
Fxx	: xx is 1 .. 12	(shift + function key f1 - f12)
cfxx	: xx is 1 .. 12	(ctrl + function key f1 - f12)
CFxx	: xx is 1 .. 12	(shift + ctrl + function key f1 - f12)
HOME
END
PGUP
PGDN
ESC
RETURN

The 3270 keys are:

PF1 - PF24
INSERT
ERASEF	(erase current field)
ERASEINPUT	(erase all input fields)
CLEAR	(clear the screen, and inform the host about it)
STARTF	(go to start of current field)
ENDF	(go to end of current field)
BTAB	(go to previous field) (normal shift TAB will also work)
TAB	(go to next field) (normal TAB key will also work)
NL	(go to first field on next line)
RESET	(reset keyboard)
ENTER

Example of a "keys" file:

# TN3270  keymap
#     
# <pc - key>  <3270 key> 
f1   PF1
f2   PF2
cf5  INSERT
cf6  ERASEF
cf7  ERASEINPUT
cf8  CLEAR
..

5.1 Default keyboard

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

  pc-Key       3270-key       pc-key              3270-key  
-----------------------      -----------------------------    
  f1              PF1          crtl f1              PA1          
  f2              PF2          ctrl f2              PA2          
  f3              PF3          ctrl f3              PA3          
  f4              PF4          ctrl f4              -            
  f5              PF5          ctrl f5              INSERT       
  f6              PF6          ctrl f6              ERASE FIELD  
  f7              PF7          ctrl f7              ERASE INPUT  
  f8              PF8          ctrl f8              CLEAR        
  f9              PF9          ctrl f9              -
  f10             PF10         ctrl f10             -
  f11             PF11         ctrl f11             PF10        
  f12             PF12         ctrl f12             PF22        
                                                 
  pc-Key       3270-key       pc-key              3270-key  
-----------------------      -----------------------------    
  shift f1        PF13         crtl shift f1        -         
  shift f2        PF14         ctrl shift f2        -         
  shift f3        PF15         ctrl shift f3        -         
  shift f4        PF16         ctrl shift f4        -         
  shift f5        PF17         ctrl shift f5        -          
  shift f6        PF18         ctrl shift f6        -         
  shift f7        PF19         ctrl shift f7        -         
  shift f8        PF20         ctrl shift f8        -         
  shift f9        PF21         ctrl shift f9        -         
  shift f10       PF22         ctrl shift f10       -        
  shift f11       PF23         ctrl shift f11       -        
  shift f12       PF24         ctrl shift f12       -

'-' is not used.

  pc-Key       3270-key    
------------------------
  HOME         GOTO START FIELD
  END          GOTO END OF FIELD
  PGUP         BACK TAB
  PGDN         TAB
  ESC          RESET KEYBOARD

6.0 ASCII - EBCDIC tables

As IBM hosts uses different codepages, it is not possible to include all possible types of layout in Mocha TN3270. File tn3270.ebc contains an ascii - EBCDIC table which will work in most cases. If national characters are used, it is necessary to change this file. It can be done with any ascii editor.

The syntax of the file is :

# This is a comment
<ebcdic value> <ascii value>

Example:

 # part of a file
 40 20
 81 a
 82 b
 83 c
 84 d

Remark it is possible to write ASCII value either as a 2 digit hex number or an ASCII character. In the example a hex value 0x83 from the Host is translated to ascii character 'c'.

If identical ASCII values are defined for more than one ebcdic character, the last will be valid, when translating from ASCII to ebcdic. If as an example ebcdic 0x50 should be translated to an ASCII space it is important to put the line

0x50 0x20

before

0x40 0x20

Otherwise Users input when pressing the space bar will be wrong. A value of 0x40 should be expected.

Mocha TN3270 comes with 2 layouts:

tn3270.ebc : US layout (default)

tn3270.dan : Danish layout

6.1 File tn3270.ebc

Mocha TN3270 comes with an ASCII - EBCDIC layout as:

     0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
  0 SP          SP  &  -                 {  }  \  0
  1                    /     a  j  ~     A  J     1
  2                          b  k  s     B  K  S  2
  3                          c  l  t     C  L  T  3
  4                          d  m  u     D  M  U  4 
  5                          e  n  v     E  N  V  5  
  6                          f  o  w     F  O  W  6 
  7                          g  p  x     G  P  X  7 
  8                          h  q  y     H  Q  Y  8
  9                       `  i  r  z     I  R  Z  9
  A                !   |  :
  B              . $   ,  #
  C              < .   %  @
  D              ( )   _  '
  E              + ;   >  =
  F              | -   ?  "

SP = space
Above EBCDIC value 0xd4 = 'M'

6.2 File tn3270.dan

A Danish codepage has been included:

     0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
  0 SP          SP  &  -                 �  �  \  0
  1                    /     a  j        A  J     1
  2                          b  k  s     B  K  S  2
  3                          c  l  t     C  L  T  3
  4                          d  m  u     D  M  U  4 
  5                          e  n  v     E  N  V  5  
  6                          f  o  w     F  O  W  6 
  7                          g  p  x     G  P  X  7 
  8                          h  q  y     H  Q  Y  8
  9                       `  i  r  z     I  R  Z  9
  A              #     �  :
  B              . �   ,  �
  C              < *   %  �
  D              ( )   _  '
  E              + ;   >  =
  F              ! ^   ?  "

SP = space

7.0 License System

The license system for Mocha TN3270 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.

8.0 Files

Following files must exist together with the HTML page loading Mocha TN3270

tn3270.class

tnnet.class

tntimer.class

tnpop.class

tn3270exe.class (only for mode 1)

tnvt.class

tnvid.class

api_tn3270.class

keys

tn3270.cfg (only for mode 1)

tn3270.ebc (US ASCII - EBCDIC table)

tn3270.dan (Danish ASCII - EBCDIC table)

green	: unprotected normal intensity
red	: unprotected intensified
blue	: protected, normal intensity
white	: protected, intensified

MOCHA TN3270 USER GUIDE

Contents

1.0 Product overview

1.1 Functionality

1.2 Connect

1.3 Function keys

1.4 Status line

TN

Line state

Session state

Insert mode

Last key

1.5 Focus

2.0 Modes

2.1 Java Application - mode 1

2.2 Java Applet - mode 2

2.3 Java pop-up Applet - mode 3

3.0 Limitations

3.1 Which hosts to connect

3.2 Control the size and position of pop-up windows

3.3 Known Restrictions

4.0 Parameters

4.1 Configuration file

4.2 HTML page

4.3 Parameter type (mode 2,3)

4.4 Parameter keyfile (mode 1,2,3)

4.5 Parameter license (mode 1,2,3)

4.6 Parameter license_key (mode 1,2,3)

4.7 Parameter negotiate (mode 1,2,3)

4.8 Parameter keyboard_bar (mode 1,2,3)

4.9 Parameter unprotected_show (mode 1,2,3)

4.10 Parameter color_bg (mode 1,2,3)

4.11 Parameter color_unprotected (mode 1,2,3)

4.12 Parameter color_cursor (mode 1,2,3)

4.13 Parameter page_color (mode 2)

4.14 Parameters screen_width and screen_height (mode 1,3)

4.15 Parameters screen_x and screen_y (mode 1,3)

4.16 Parameters host and port (mode 2,3)

4.17 Parameter auto_stop (mode 2,3)

4.18 Parameter termtype (mode 1,2,3)

4.19 Parameter alternate (mode 1,2,3)

4.20 Parameter debug (mode 1)

4.21 Parameters proxy_host, proxy_port and proxy_syntax(mode 1,2,3)

4.22 Parameter ebcdic_file (mode 1,2,3)

4.23 Parameter color_XXXX (mode 1,2,3)

4.24 Parameter font (mode 1,2,3)

4.25 Parameter alive (mode 1,2,3)

5.0 Keyboard mapping

5.1 Default keyboard

6.0 ASCII - EBCDIC tables

6.1 File tn3270.ebc

6.2 File tn3270.dan

7.0 License System

8.0 Files

MOCHA TN3270
USER GUIDE