Choosing an Attachmate API

Deciding which interface to use is a process that depends on various inputs. Are you writing applications in Java, or are you writing native Win32 applications? Are you using Web services? What about J2EE? With which type of application server are you integrating? These decisions are frequently driven by the needs of your customers.

Before deciding which interface is appropriate for your situation, you'll need to create one or more tasks and be familiar with your client application requirements.

Available Interfaces

APIs are provided for the following development environments, applications, and component technologies:

Choosing a Java Interface

There are currently four Java interfaces available to you:

• IConnectorAccess - an XML-based API
• ITask - a Java bean-based API
• Service beans - Java beans that work well in J2EE environments.
• INativeAccessEx

A stateless task is one that does not maintain context information about previous executions; stateful tasks can pick up where the last task left off.

See the Javadocs for details about the Attachmate Java interfaces.

Solving Advanced Navigation Issues

Writing your own custom steps, from within Task Builder, provides a server-side solution to navigation problems that are either too difficult or impossible for a task, recorded using the standard design-time workflow, to solve. When you use custom steps and the server-side API you no longer have to rely on screen native access to deal with advanced navigation issues. See Using Custom Steps for information and instructions on using this solution for challenging workflows.

What is Native Access and When Should I Use It?

Screen native access is a client-side task, with pre-defined inputs and outputs, that provides you with direct access to the Runtime Service's internal view of the host screen. Using native access you can programmatically interact with the screen to solve problems that cannot be handled with simple tasks. In addition to getting field and screen attributes, you can query for information in the navigation map (NavMap) used to build the connection without having to create host specific beans.

All the field and screen attribute information plus commands have been normalized to generic constants defined in INativeAccessConstants. Native access support is provided via the ITask and IConnectorAccess APIs.

The INativeAccessEx interface supplies the screen view as a series of properties and get or set methods are used to access both field and screen information.

When should I use native access?

There are two reasons for using native access:

1. Provide access to host screen field data, which supplies programmers with not only a snapshot of the current host screen but the ability to interact with it dynamically by modifying fields and sending AID keys.

2. Native access can be a "backdoor" to the Runtime Service's navigation engine. This is a last resort scenario and should be used only when problems cannot be solved using standard techniques. For example, gathering data from an asymmetric table where fields are either non-uniform or the number of columns is dynamic could be done using native access.

Will native access work in a COM environment?  You can use native access via the COM bridge with XML-based IConnectorAccess. The ITask implementation of native access is Java only, but the IConnectorAccess implementation can be used in native Win32 environments because the COM bridge is just an IConnectorAccess wrapper.

What native access does not do

Native access does not supply "presentation" features such as field validation, field text formatting, field tab ordering, or OIA lines. Native access only supports commands or data that goes all the way to the host. Presentation features are only supported on the workstation (renderer) or controller and need to be supplied by the user application.

for detailed technical information on native access, as well as complete Javadocs for all the Attachmate Java interfaces, see Using Screen Native Access, Overview.

Points to remember

1. IConnectorAccess is XML-based, maintains state, supporting both task chaining and native access.

2. ITask is Java-bean based, maintains state, supporting task chaining and native access.

3. Service beans are stateless, and do not support task chaining or native access. Multiple tasks can be encapsulated in a single service bean in contrast to the task beans where one task is contained in a single bean.

Choosing a Native Win32 Interface

For more information, see Building Applications Using Native Win32 Technologies.

Points to remember

When deciding between the two native interfaces there are a few things to keep in mind:

1. The ScreenConnectorProxy Service provides a simplified API and executes stateless tasks out of process. It does not support task chaining or native access.

2. The COM interface maintains state and supports task chaining and native access. The COM interface is a native wrapper for ICA and executes stateful tasks in process.

3. To use the ScreenConnectorProxy Service, when calling the method Execute(...), you need to provide the value "com.attachmate.connector.screen.ScreenConnectorAccessImpl" as the first parameter. No other value will work.

4. Using the COM interface you get one JVM per process, while using the Proxy Service, you get one JVM per machine.

Choosing a Web Service

Attachmate Synapta Services Builder for Screens provides support for Web services. Web services, which are generated by Task Builders, can be used in a variety of development environments to expose host access tasks as Web services and then be made available as resources to other applications and application components.

What Web service you decide to use is based on your application server.

Points to remember

1. Installers may be generated for your Web services platform.

2. The Web service platform creates a Web Services Description Language (WSDL) file, which your development environment can use to interact with the Web service.

3. Web services only support "stateless" tasks, meaning they do not support task chaining or native access.

4. When Web services are generated they are custom-tailored for one particular project or task so the APIs will vary. However, a Web service API will always define the following in some manner:
   • A ScreenInputs interface with properties for setting task inputs
   • A ScreenOutputs interface with properties for getting task outputs
   • A service interface for executing tasks. Typically there will be one method per task. Each method takes a single ScreenInputs argument and returns a ScreenOutputs object.

There are installation and deployment instructions for each supported application server in this Product Guide, under Using Tasks in Your Applications.

Building Applications using Attachmate's J2EE Supported Architecture

Before the J2EE Connector Architecture (JCA) was introduced, there was no standardized method to integrate enterprise systems with legacy data. However, the advent of JCA and Attachmate's J2EE-compliant architecture made it possible to access host data and integrate with supported application servers, including BEA WebLogic, IBM WebSphere, Sun Microsystem SunONE, and Oracle AS.

Building Applications using J2EE Session EJBs

Session EJBs are efficient, lightweight, Java beans that work well in J2EE environments. As a part of an enterprise application, along with the J2EE connectors, they are deployed as an EAR file to your selected application server. Characteristics are:

• Built to the Enterprise JavaBeans specification v1.1.
• Task-specific methods and helper classes for task inputs and task outputs.
• Stateful and stateless EJBs.
• Multiple tasks included in one bean.
• Available in MCS.

A stateless task is one that does not maintain context information about previous executions; stateful tasks can pick up where the last task left off.

Example:

In this example, you set task inputs, execute the task, and get task outputs.

	//create screen inputs object, define screen outputs variable 
        AccountQueryStateful.AccountLookupTaskInput.ScreenInputs si = new AccountQueryStateful.AccountLookupTaskInput.ScreenInputs();
        AccountQueryStateful.AccountLookupTaskOutput.ScreenOutputs so = null;

        // set task input(s)
        si.setAccountNumber(AccountNumber);

        // execute task with inputs and collect outputs
        so = ejb.AccountLookupTask(si);

        // get task output(s)
        Balance = so.getBalance();    

Building Applications using J2EE Connectors

The Synapta Services Builder provide two JCA-compliant resource adapters.

Attachmate JCA adapter for WebLogic uses Web services generated in the task builder component and BEA WebLogic Integration (WLI) extensions.

• Built to the JCA 1.0 specification
• Provides BEA WLI extensions
• Configured in the design-time component

Attachmate J2EE connectors, as a part of a packaged session EJB, implement the JCA Common Client Interface (CCI), and are managed and deployed as an enterprise application to selected application servers through your Synapta Services Builder management component.

• Built to the JCA 1.0 specification
• Complies to the CCI standard
• Available from MCS

Accessing Data with the J2EE Connectors

The Attachmate J2EE connector implementation returns Record objects, which mimic a hierarchical XML structure and use combinations of MappedRecords and IndexedRecords. (Input or output data is referred to as a Record.)

The RecordFactory is part of the J2EE connector architecture. To obtain a particular Record from the RecordFactory, you must ask for it by name. The format of the name is:

TASK/MODE[/CHILD]

where TASK is the name of the task you are going to execute, MODE is either input or output, and CHILD is an optional child record.

For example, if you have a task named "test" and you want to get the input record, use the name "test/input". If the root element of the task "test input" has a child element, "bar," that is complexType, and therefore a MappedRecord, you access that Record as "test/input/bar".

The actual name of the root element is never specified and is assumed to be the first top-level element in the task schema.

For more information about implementing J2EE solutions, see How to Deploy and Manage J2EE Session Beans.

	Using Tasks in Your Applications, Overview
	Configuring Your Development Environment