INDEX:
1.0
Scope
1.1
Introduction
1.2
Abbreviations and Acronyms
1.3
Version list
2.0
Applicable Documents
3.0
API
3.1
Overview
3.2
Test programs
3.3
Return Values
3.4
Data Types
3.5
API class api_telnet
3.6
API class api_tn3270
3.7
API class api_tn5250
3.8
API use_display()
3.9
API do_connect()
3.10
API do_disconnect()
3.11
API do_read_all()
3.12
API do_write_text()
3.13
API do_aid_key()
3.14
API do_goto()
3.15
API get_xy()
3.16
API get_screen_size()
3.17
API do_goto_field()
3.18
API get_field_pos()
3.19
API do_wait_input()
3.20
API do_read_fifo()
3.21
API do_load_config()
3.22
API do_wait_user_action()
3.23
API do_search()
3.24
API do_get_connect_status()
3.25
API do_wait_position()
4.0
Miscellaneous
1.0 Scope
The purpose of this document is to specify
an API for the
JAVA version of Mocha TN3270/TN5250 and Mocha Telnet.
1.1 Introduction
TOP
To make it simpler to include the products
TN3270/TN5250 and Telnet into
larger systems, an API has been specified for the JAVA code.
This API will load the emulators, and hereafter
it is possible to redirect input/output over the new Interface.
The API will be the same for most parts of the Telnet and TN3270/TN5250
implementation, and therefore the documentation has been put into a single
paper.
The API is very low level. It gives access to data structures in the emulators,
but does not help with advanced validation and search operations.
1.2 Abbreviations and Acronyms
TOP
User programs : Java program which access the
API.
1.3 Version List
TOP
1.0 : First version
2.0 : added support for tn5250
2.0 Applicable Documents
TOP
[1] : Program design of Mocha TN3270/Telnet,
ref 1001
[2] : User Guide for Mocha TN3270
[3] : User Guide for Mocha Telnet
[4] : User Guide for Mocha TN5250
3.0 API
TOP
First is a short overview of how to put everything
together. Hereafter
follows the API functions in details.
3.1 Overview
TOP
-------- ------------------- ---------------------------
l User l l Telnet API l l Mocha Telnet l
l JAVA l --- l l --- l *.class files l
l CODE l l api_telnet.classl l l
-------- ------------------- ---------------------------
(1) (2)
-------- ------------------- ---------------------------
l User l l TN3270 API l l Mocha TN3270 l
l JAVA l --- l l --- l *.class files l
l CODE l l api_tn3270.classl l l
-------- ------------------- ---------------------------
(1) (2)
-------- ------------------- ---------------------------
l User l l TN5250 API l l Mocha TN5250 l
l JAVA l --- l l --- l *.class files. l
l CODE l l api_tn5250.classl l l
-------- ------------------- ---------------------------
(1) (2)
(1) API described in details at chapter 3.x
(2) Private interface, which should not be used from User programs, as
it can/will change between versions of Mocha TN3270/TN5250/Telnet.
Before looking at the API in details, a small example can give a quick
overview. This User program loads Mocha Telnet, and receives "Telnet"
data from a host.
import ...
public class userprogram {
main(String args[])
{
byte buf[][];
api_telnet a = new api_telnet(); (A)
a.do_load_config("config.cfg"); (B)
a.use_display(true,true); (C)
if (a.do_connect("unix",23) == true) { (D)
a.do_wait_input(0); (E)
buf = a.do_read_all(); (F)
// buf contains finger data,
...
a.do_disconnect(); (G)
}
}
}
Description of the example:
A: a version of the Telnet API is loaded, and named "a".
B: download parameters to the emulator. Should always be the first thing to
do.
C: start the emulator. The 2 parameters defines the mode. In this simple example
Mocha Telnet will not display anything
D: a connection is created to host unix, port 23
E: wait on data from the host
F: buf points to a copy of the screen buffer (24*132)
G: the connection to the host is closed.
Remark there are 3 different API classes. One for Telnet and another two for
TN3270/TN5250. A (TELNET) and/or (TN3270) and(or (TN5250) in the rest of chapters
3.x indicates which API the functions can be used for.
Mocha TN3270/TN5250/Telnet can when loaded from a browser only run as a pop-up
window, or in hidden mode. Mode 2 (Java Applet) (see ref [3], 2.1) is not possible
when running via the API interface.
3.2 Test Programs
TOP
A set of test programs has been included into
the API packet for use as examples of User Programs.
testap52.java : Tn5250 user program running as applet
testap32.java : Tn3270 user program running as applet
testap.java : Telnet user program running as applet
test52.java : Tn5250 user program running as stand alone program
test32.java : Tn3270 user program running as stand alone program
test.java : Telnet user program running as stand alone program
3.3 Return Values
TOP
All functions return "true" on success, otherwise
"false".
3.4 Data types
TOP
Both Telnet and Tn3270/tn5250 works with 1
character is 8 bit long, when talking the the host. Therefore the type "byte"
is used to hold a single character.
The "char" type in the JAVA language is of type Unicode, and is therefore a
2 byte value. If the User program uses Unicode types, it must translate all
characters to ASCII before calling any API functions.
3.5 API Function class api_telnet
(TELNET) TOP
Description:
Loads the class api_telnet
Syntax:
api_telnet my_emul = new api_telnet();
Parameters:
none
Return value:
a new api_telnet object.
3.6 API Function class api_tn3270
(TN3270) TOP
Description:
Loads the class api_tn3270
Syntax:
api_tn3270 my_emul = new api_tn3270();
Parameters:
none
Return value:
a new api_tn3270 object.
3.7 API Function class api_tn5250
(TN5250) TOP
Description:
Loads the class api_tn5250
Syntax:
api_tn5250 my_emul = new api_tn5250();
Parameters:
none
Return value:
a new api_tn5250 object.
3.8 API Function: use_display()
(TN3270) (TELNET) (TN5250)
TOP
Description:
Defines the display type of the emulator. Hereafter the emulator
is initialized, and is ready for use. All parameters should have been
loaded before calling this function.
Syntax:
boolean use_display(boolean hide,boolean standalone)
Parameters:
hide : true if nothing should be displayed.
standalone: true if NOT loaded from a browser.
Return value:
true/false.
3.9 API Function: do_connect()
(TN3270) (TN5250) (TELNET)
TOP
Description:
Creates a connection to a host. Returns "true" if a success. If proxy is
enabled, a connection is created to the proxy host, and hereafter the proxy
login sequence is issued.
This function returns before the connection has been created. Use do_wait_input()
to verify the connection is online.
Syntax:
boolean do_connect(String host, int port)
Parameters:
type:
host : host name.
port : port number (23 = Telnet)
Return value:
true/false.
3.10 API Function: do_disconnect()
(TN3270) (TN5250) (TELNET)
TOP
Description:
Close a connection
Syntax:
void do_disconnect()
Parameters:
none
Return value:
none
3.11 API Function: do_read_all()
(TN3270) (TN5250) (TELNET)
TOP
Description:
Returns a copy of the screen.
Telnet : 24*132
TN3270 : 32*80
TN5250 : 27 * 132
As to speed and to make the code more safe, the "pointer" returned is to a static
data area. If do_read_all is called again, the data area will be overwritten.
Only a call to do_read_all can overwrite this data area. Data from the host,
or data loaded with other API functions will not overwrite this static data
area. do_read_all() will clear the data_ready flag, meaning next call to do_wait_input()
will not return before new data has arrived from the host, or the timer has
expired.
Syntax:
byte[][] do_read_all()
Parameters:
none
Return value:
an array of ASCII characters. Graphic characters and attribute fields
will be shown as space characters. All data will be in ASCII.
byte[1][1] is upper left corner. byte[10][1] is the start of line 10.
3.12 API Function: do_write_text()
(TELNET) (TN3270) (TN5250)
TOP
Description:
For Telnet:
Writes a raw string of text direct to the host.
Example of how to emulate F6 key pressed:
String tmps = ((char)0x1b) + "[17~"; // F6 Key
byte [] response_data = new byte[tmps.length()];
tmps.getBytes(0, tmps.length(), response_data, 0);
do_emul.do_write_text(response_data)
or just
do_emul.do_write_text(tmps);
For TN3270/TN5250:
Writes a string of data to the tn3270 emulator. Only ASCII characters
can be used. This function cannot be used to move the cursor or
send TN3270/TN5250 AID keys.
a) Position the cursor with do_goto() or do_goto_field(),
b) Fill data into the field with do_write_text().
c) Send the screen to the host with function do_aid_key().
Syntax:
boolean do_write_text(byte[]
ary)
boolean do_write_text(String st)
Parameters:
ary : byte array to write.
st : String to write. Only LSB 8 bit is used for each character.
Return value:
false, if not possible (3270 on a protected field)
3.13 API Function: do_aid_key()
(TN3270) (TN5250) TOP
Description:
Works as if the user press a function key, which will force the emulator
to send data to the host. Also the local edit keys INSERT,ERASE FIELD and
ERASE INPUT can be activated with this function.
Syntax:
boolean do_aid_key(byte ch)
Parameters for TN3270:
ch : AID value to the host.
ENTER : 0x7d PF 16 : 0xc4
PF 1 : 0xf1 PF 17 : 0xc5
PF 2 : 0xf2 PF 18 : 0xc6
PF 3 : 0xf3 PF 19 : 0xc7
PF 4 : 0xf4 PF 20 : 0xc8
PF 5 : 0xf5 PF 21 : 0xc9
PF 6 : 0xf6 PF 22 : 0x4a
PF 7 : 0xf7 PF 23 : 0x4b
PF 8 : 0xf8 PF 24 : 0x4c
PF 9 : 0xf9 PA 1 : 0x6c
PF 10 : 0x7a PA 2 : 0x6e
PF 11 : 0x7b PA 3 : 0x6b
PF 12 : 0x7c CLEAR : 0x6d
PF 13 : 0xc1
PF 14 : 0xc2
PF 15 : 0xc3
Local edit keys:
INSERT : 0x1
ERASEINPUT : 0x2
ERASE FIELD : 0x3
Parameters for TN5250:
ch : AID value to the host.
ENTER : 0xf1 PF 16 : 0xb4
PF 1 : 0x31 PF 17 : 0xb5
PF 2 : 0x32 PF 18 : 0xb6
PF 3 : 0x33 PF 19 : 0xb7
PF 4 : 0x34 PF 20 : 0xb8
PF 5 : 0x35 PF 21 : 0xb9
PF 6 : 0x36 PF 22 : 0xba
PF 7 : 0x37 PF 23 : 0xbb
PF 8 : 0x38 PF 24 : 0xbc
PF 9 : 0x39 HELP : 0xf3
PF 10 : 0x3a ROLL DOWN : 0xf4
PF 11 : 0x3b ROLL UP : 0xf5
PF 12 : 0x3c CLEAR : 0xbd
PF 13 : 0xb1 RECORD : 0xf8
PF 14 : 0xb2 ATTN : 0x6
PF 15 : 0xb3 SYSREQ : 0x7
Local edit keys:
INSERT : 0x1
ERASEINPUT : 0x2
FIELD - : 0x3
FIELD + : 0x4
FIELD EXIT : 0x5
Return value:
true/false
3.14 API Function: do_goto()
(TN3270) (TN5250) TOP
Description:
Move the cursor to a new position. Upper left corner is (1,1)
Remark: Telnet must use function do_write_text(), to move the cursor.
Syntax:
boolean do_goto(int x,int y)
Parameters:
x,y : new position for the cursor
x = 1 - 80 (1 - 132)
y = 1 - 32 (1 - 27)
Return value:
false, if position is not legal
3.15 API Function: get_xy()
(TELNET) (TN3270) (TN5250)
TOP
Description:
Returns cursor position
Syntax:
int get_xy()
Parameters:
none
Return value:
cursor position as 0xYYXX, where bit 0 - 7 = X position
8 - 15 = Y position
3.16 API Function: get_screen_size()
(TELNET) (TN3270) (TN5250)
TOP
Description:
Returns current screen size
Syntax:
int get_screen_size()
Parameters:
none
Return value:
cursor position as 0xWWHH, where bit 0 - 7 = height
8 - 15 = width
3.17 API Function: do_goto_field()
(TN3270) (TN5250) TOP
Description:
Move cursor to the start of a field. First field on the screen is number 1.
If no fields are defined, false is returned.
Syntax:
boolean do_goto_field(int f_no);
Parameters:
f_no : field number.
Return value:
true/false
3.18 API Function: get_field_pos()
(TN3270) (TN5250) TOP
Description:
Returns current field number for the cursor.
Syntax:
int get_field_pos();
Parameters:
none
Return value:
field number, where the first field on the screen from the top is given
number 1, or the value 0 if cursor is not at an unprotected
field (input field) or no fields on the screen.
3.19 API Function: do_wait_input()
(TN3270) (TN5250) (TELNET)
TOP
Description:
Waits on data from the host. If the timer runs out false is returned.
As data from the host in most cases will arrive in large frames, this
function will return, when the full frame has been received, and computed
of the emulator.
Syntax:
boolean do_wait_input(int milli_time);
Parameters:
milli_time : time in 1/1000 second to wait before returning. If
0 is stated, the timer is not used, and the program
will hang until data, or a disconnect is received from
the host
Return value:
true/false
If false is returned, a call to get_connect_status() can check if
there is problems with the connection.
3.20 API Function: do_read_fifo()
(TELNET) TOP
Description:
A copy of all (latest) data from the host written on the "screen" is copied
to a FIFO of max. 4000 bytes.
do_read_fifo() will clear data_ready flag, if clear parameter us true,
meaning next call to do_wait_input() will not return before new data has
arrived from the host.
Syntax:
byte [] do_read_fifo(boolean clear);
Parameters:
clear : true and the API will remove all data from fifo.
Return value:
an array filled with data. If no data "new byte[0]" is returned.
3.21 API Function: do_load_config()
(TELNET) (TN3270) (TN5250)
TOP
Description:
The configuration is loaded from a file. This function call should be
the first call to the API. Se User Guide for Telnet/TN3270 (ref 2,3)
for the syntax of the configuration file. When running via the API,
this configuration file is used for all types of
Mocha TN3270/TN5250/Telnet: stand-alone or applet.
Syntax:
boolean do_load_config(String filename);
boolean do_load_config(URL url);
Parameters:
filename: name of the configuration file.
url : complete url for the configuration file.
Use the URL parameter if NOT running as a standalone application.
Return value:
true/false
3.22 API Function: do_wait_user_action()
(TN3270) (TN5250) (TELNET)
TOP
Description:
If not running in hidden mode, the user can use the keyboard. This
function returns when the user press any key or if data already
in the history buffer.
The history buffer contains the last 200 user actions.
Syntax:
int [] do_wait_user_action(int milli_time,boolean clear_before,
clear_after);
Parameters:
milli_time : time in 1/1000 second to wait before returning. If
0 is stated, the timer is not used, and the program
will hang until the user do something, or if there
were data waiting in the history buffer.
clear_before : true: only user input from calling this function should be
returned.
clear_after : delete all user data from history buffer when this function
returns.
Return value:
if TN3270/TN5250 :
0xAZZXXYY : A = 1 : ZZ is an AID (function key pressed)
ZZ : ASCII character typed or AID key. If 0
just a new cursor position.
XX : cursor position (X position)
YY : cursor position (Y position)
Values for AID keys can be seen in function do_aid_key();
if Telnet :
0xAA :
AA : ASCII character typed. If cursor left is pressed
the array returned could be 3 character long and look
as:
ary[0] = 0x1b
ary[1] = '['
ary[2] = 'D'
3.23 API Function: do_search()
(TN3270) (TN5250) (TELNET)
TOP
Description:
Simple search operation. Looks for a match of a String in an array of data.
Syntax:
boolean do_search(byte [] ary, String st);
Parameters:
ary : array of data
st : String
Return value:
true if match is found
3.24 API Function: do_connect_status()
(TN3270) (TN5250) (TELNET)
TOP
Description:
returns true if a valid connection to a host exists.
Syntax:
boolean do_connect_status();
Parameters:
none
Return value:
true if connected.
3.25 API Function: do_wait_position()
(TELNET) TOP
Description:
Waits on the cursor at position (x,y) or timeout
Parameters:
milli_time : time in 1/1000 second to wait before returning. If
0 is stated, the timer is not used, and the program
will hang until data, or a disconnect is received from
the host
x,y : position to wait for (x : 1 - 132
y : 1 - 80)
Return value:
true/false
Returns true if cursor at position (x,y). If false is returned, a call
to get_connect_status() can check if there is problems with the connection.
4.0 Miscellaneous
TOP
This chapter contains some of the known limitations
to the API.
1) Do not include host and port definitions in the configuration file.
The connection must be established with do_connect().
2) It is a good idea to include a call to do_connect_status() in the User
program, at a often passed place, as to verify everything is OK.
3) The API can only work in hidden mode, with a proper license key.
4) It is not possible to run as an applet. If started from a browser as
netscape, the mode will be as a frame (pop-up window).
|