Package com.rs.seagull.emulator.api

package com.rs.seagull.emulator.api

This package contains classes and interfaces needed to drive a host application programmatically via an emulator such as IBM 5250, IBM 3270, and VT (aka Ansi Plus). The following information is a high-level overview of the major concepts and classes and how they interact, as well as several detailed examples that show the best way to use the emulator API.

Introduction

Before we get into the details of the API, note that there are three different "audiences" for this documentation.
  1. Standalone Java Program
    Someone writing an ordinary Java program must create a host session, then use various APIs to drive the session through various screens, then close the session. Creating a host session usually involves knowledge of screen definition files and such.
  2. Microflow script for a Function action
    Someone writing a script for a microflow is "handed" a host session that's ready to use, so there's no need to create a session or deal with screen definition files.
  3. SeagullScript conversion
    Someone converting a Classic Screen API project (aka SIP2) to a current (NextGen) Screen API project will need to convert any existing scripts from SeagullScript to JavaScript, including converting Classic host APIs (e.g. HostFieldGetData) to the APIs described here.
Each of these audiences are addressed separately below, but note that the majority of the APIs documented here are equally applicable to all.

Overview

This emulator API is based on a model where a host application is a series of screens that are navigated through by sending text and keystrokes to the host. Each screen is typically comprised of fields represented by a rectangular area.

To interact with the host, you normally identify screens by name and define fields by name within each screen to create an application definition. Application definitions are created outside this API using the Rocket API builder tools. For more information, see the Rocket API Screen Developer Guide .

After you've created the application definition using the builder tools, you pass it in as a parameter to this API when creating a new host session. This allows you to address screens and fields by name without using low-level screen coordinates. For example, you can get the name of the current screen, session.getScreenName(). You can also get the contents of a field by name, session.getText("fieldA"), set the value of an input field by name, session.setText("fieldB", "someValue"), and send keystrokes, session.sendKey("ENTER"). Additional operations are also available.

If you do not have an application definition available and your host supports lower-level access (IBMi/5250 and IBMz/3270), you can access screens and fields by addressing areas of the screen using XY coordinates.

Classes

The central class of the whole API is Session. A Session provides access to secondary classes such as Screen, Cursor, Keyboard, and Field, but you can accomplish just about anything you would typically want to do using just Session and its superclass. Other useful helper classes include Conditions, Keys, Colors, and Emulators.

Note that Session, Screen, Field, and Cursor are used when an application definition is available. If you do not have an application definition, use the corresponding bare classes: BareSession, BareField, and so on. These classes are the superclasses for Session, Field, and so on, so therefore all the bare, or undefined, operations are also available to a defined object. For example, BareSession contains sendKey(String key), while Session contains sendKey(String field, String key). The operation in BareSession sends a keystroke to the host at the current cursor position, whereas the the operation in Session places the cursor in the named field before sending the keystroke. Session and Screen extend BareSession and BareScreen so all low-level APIs are available. Use the BareSession.waitFor(com.rs.seagull.emulator.api.Condition, com.seagullsw.common.toolbox.concurrent.Timeout) method in BareSession to wait for a variety of conditions to become true, including writing your own arbitrary conditions. A starter set of useful conditions are available in the Conditions class.

Audience Specific Intro

Standalone Java Program

A standalone Java program must create a session. Sessions are typically created using static methods in SessionFactory and BareSessions are created using BareSessionFactory). Here are some examples:

  1. Create a (defined) Session


    Session session = SessionFactory.create(Emulators.Ibm5250.SCHEME, "iSeriesHost", 23, null, "screens");
    • 1st parameter is the so-called "scheme", which is really just the type of emulator. You can see the available types in Emulators.
    • 2nd parameter is the name or IP address of the host system.
    • 3rd parameter is the socket port on the host system.
    • 4th parameter is an optional Map of connection properties. More on this below in other examples.
    • 5th parameter is a classpath-relative directory containing application definition files.

  2. Create a BareSession

    BareSession session = BareSessionFactory.create(Emulators.Ibm5250.SCHEME, "iSeriesHost", 23, null);

    Similar to the create in the first example, but with no application definition.

Script for a Microflow Function Action

Within a Rocket API microflow, you can write JavaScript to provide custom interaction with the host application. When a microflow is started and this JavaScript is invoked, the host session that is being navigated by the microflow is made available as a JavaScript variable. This variable is called hostSession and is an instance of Session. Also note that a host connector that is executing a microflow will have an application definition associated with it, so you will normally address screens and fields by name in your JavaScript, using methods from Session and associated classes. The JavaScript engine used by the API gateway provides seamless integration with Java and gives your JavaScript code access to the full emulator API described here. Currently, the JavaScript engine is Rhino. For additional information, see https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino/Documentation. In the following examples, both Java and JavaScript are provided.

SeagullScript Conversion

There are two rather separate aspects to converting SeagullScript scripts to JavaScript NextGen scripts, the language elements (i.e. JavaScript itself), and the emulator API elements (e.g. HostFieldGetData).

Language

The JavaScript language is well documented on the web. The particular variant that Rocket API uses is called Rhino, from Mozilla, documented here: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino/Documentation Mozilla has some nice JavaScript tutorial-ish documentation too, here: https://developer.mozilla.org/en-US/docs/Learn/JavaScript For SeagullScript in particular, here are some obvious "conversions":
SeagullScript and JavaScript
SeagullScriptJavaScript
if then endif if () {}
if x = y if (x == y)
and (in an if expression) &&
<> !=
for i = 0 to 3 ... next for (i = 0; i <= 3; i++) {}
while ... wend while () {}
dim x as string var x

Emulator APIs

The Classic/SIP2 emulator APIs have equivalents in these APIs. For example:
Old and New APIs
HostFieldGetData(field, variable) variable = hostSession.getText(field)
HostFieldGetLineData(field, offset, variable) variable = hostSession.getField(field).getText(offset)
HostScreenSendKey(key) hostSession.sendKey(key)
HostFieldPutData(field, value) hostSession.setText(field, value)

Examples

In the examples below, the Java examples assume you have a Session variable named 'session'. The JavaScript examples assume you have a Session variable named 'hostSession'.

  1. Get the name of the current screen

    Java:String screen = session.getScreenName();
    JavaScript:var screen = hostSession.getScreenName();

  2. Get the contents of a field

    Java:String value = session.getText("fieldA");
    JavaScript:var value = hostSession.getText("fieldA");

    This retrieves the textual content of the field named "fieldA" from the current screen.

  3. Set the contents of a field

    Java:session.setText("fieldA", "someText");
    JavaScript:hostSession.setText("fieldA", "someText");

    This sets the textual content of the field named "fieldA" on the current screen to "someText".

  4. Send a keystroke

    Java:session.sendKey(Keys.Ibm5250.ENTER);
    JavaScript:hostSession.sendKey(Keys.Ibm5250.ENTER);

    This sends an ENTER key to the host. Note the use of Keys which contains constants for all the allowable keys.

  5. Send a keystroke for a particular field

    Java:session.sendKey("fieldA", Keys.Ibm5250.ENTER);
    JavaScript:hostSession.sendKey("fieldA", Keys.Ibm5250.ENTER);

    This positions the cursor to fieldA, then sends an ENTER key to the host.

  6. Wait for a specific screen by name

    Java:session.waitFor(Conditions.screenNamed("MAINMENU"), Timeout.seconds(10));
    JavaScript:hostSession.waitFor(Conditions.screenNamed("MAINMENU"), Timeout.seconds(10));

    A number of other useful wait conditions are available in class Conditions.

  7. Get the contents of a portion of the screen

    Java:session.getText(new Point(34, 0), 9);
    JavaScript:hostSession.getText(new Point(34, 0), 9);

    This grabs 9 characters from the middle of the top line.