MOCHA TN5250
USER GUIDE

Mocha TN5250 is an TN5250 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 TN5250.

1.1 Functionality

Uses Java Version 1.0/1.1

Supports all standard 5250 emulation features

Alternate screen size (24x80 or 27x132)

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 TN5250 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 TN5250 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 5250 keyboard, some changes has been necessary.

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

PF1 - PF24, DUP, ERASE, CLEAR, ATTN, SYSREQ, HELP and INSERT 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 5250 screen the status of the session. The layout is:

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

TN

Connected to a host supporting the TN5250 protocol

Line state

REQUEST : Mocha Tn5250 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 5250 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.

Message light(M)

A M is displayed if message light is activated from the host.

Last key

Shows last function key pressed: PF1 - PF24, ENTER, CLEAR ,HELP, SYSREQ or ATTN.

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 TN5250 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 TN5250 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 TN5250exe host [configuration file]

where

host : name of Unix host to connect.

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

Mocha TN5250 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 TN5250 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 TN5250 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 TN5250.

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 TN5250 request to another host. A better solution is to install Mocha TN5250 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.

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 5250 elements have not been implemented:

blinking

graphics

sound alarm

light pen

4.0 Parameters

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

# This is a comment line
name=value

Example of a simple file:

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

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

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 TN5250 example </TITLE>
</HEAD>
<BODY>
<APPLET CODE="tn5250.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 "tn5250.class". It is the name of the master file for the binary Mocha TN5250 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 5250 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 TN5250. 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 TN5250, 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 TN5250 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 + other keys should be displayed as buttons.

Syntax:

name=keyboard_bar value="true|false"

Default is true.

4.9 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 tn5250.ebc

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_XXXX (mode 1,2,3)

It is possible to change the default colors. 5250 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.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 TN5250 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 TN5250 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 TN5250 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 TN5250 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-3477-FC : 27 * 132 color display

IBM-3179-2 : 24 * 80 color display

Syntax:

name=termtype value=<type of terminal emulation>

Default is IBM-3179-2

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 27>

Default is 24

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, proxy_syntax and proxy_socks(mode 1,2,3)

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

Either Mocha W32 TN5250 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 TN5250 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.9 of Mocha TN5250 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 font (mode 1,2,3)

Possible to define the display font

SYNTAX:

name=font value="font name"

Default is Courier

4.23 Parameter typeahead (mode 1,2,3)

Use this command to define if it should be legal to enter data for the next screen, without waiting for the host to send a response.

SYNTAX:

name=typeahead value="true|false"

Default is false

4.24 Parameter alive (mode 1,2,3)

Use this command to force tn5250 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 "keys52", and should exist in the same catalog as the *.class files of Mocha TN5250.

Syntax for file "keys":

Comments starts with #

<pc-key> <5250-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 5250 keys are:

PF1 - PF24
INSERT
ERASEINPUT	(erase all input fields)
RECORD	(record Backspace (Home)
FIELDEXIT
FIELD-
FIELD+
PGUP	(roll down)
PGDN	(roll up)
HELP	(send help request to the host)
ATTN
SYSREQ
DUP
CLEAR	(send clear request to the host)
RESET	(reset keyboard)
ENTER

Example of a "keys" file:

# TN5250  keymap
#     
# <pc - key>  <5250 key> 
f1   PF1
f2   PF2
cf5  INSERT
cf6  RECORD
cf7  ERASEINPUT
cf8  CLEAR
..

5.1 Default keyboard

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

  pc-Key       5250-key       pc-key              5250-key  
-----------------------      -----------------------------    
  f1              PF1          crtl f1              FIELD-      
  f2              PF2          ctrl f2              FIELD+      
  f3              PF3          ctrl f3              FIELDEXIT   
  f4              PF4          ctrl f4              ATTN-       
  f5              PF5          ctrl f5              SYSREQ      
  f6              PF6          ctrl f6              INSERT      
  f7              PF7          ctrl f7              ERASE INPUT 
  f8              PF8          ctrl f8              DUP         
  f9              PF9          ctrl f9              -          
  f10             PF10         ctrl f10             -          
  f11             PF11         ctrl f11             PF10       
  f12             PF12         ctrl f12             PF22       
                                                                
  pc-Key       5250-key       pc-key              5250-key  
-----------------------      -----------------------------    
  shift f1        PF13         crtl shift f1        HELP         
  shift f2        PF14         ctrl shift f2        CLEAR         
  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       5250-key    
------------------------
  HOME         RECORD
  END          FIELDEXIT
  PGUP         PGUP
  PGDN         PGDN
  ESC          RESET KEYBOARD
  RETURN       ENTER

6.0 ASCII - EBCDIC tables

As IBM hosts uses different codepages, it is not possible to include all possible types of layout in Mocha TN5250. File tn5250.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.

The Mocha TN5250 product contains:

tn5250.ebc : US,Canada,Netherlands layout

7.0 License System

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

tn5250.jar

keys52

tn5250.cfg (only for mode 1)

tn5250.ebc (US ASCII - EBCDIC table)

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

MOCHA TN5250 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

Message light(M)

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 ebcdic_file (mode 1,2,3)

4.10 Parameter color_bg (mode 1,2,3)

4.11 Parameter color_XXXX (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, proxy_syntax and proxy_socks(mode 1,2,3)

4.22 Parameter font (mode 1,2,3)

4.23 Parameter typeahead (mode 1,2,3)

4.24 Parameter alive (mode 1,2,3)

5.0 Keyboard mapping

5.1 Default keyboard

6.0 ASCII - EBCDIC tables

7.0 License System

8.0 Files

MOCHA TN5250
USER GUIDE