Screen Native Access Sample Code 1

There are seven code samples available in this document. They are:

For details about Attachmate interfaces, see Javadocs for Attachmate Interfaces.

Configuring and Using the Screen Native Access Bean

Configuring the Screen Native Access Bean

  1. An execution sequence consists of setting the input properties, executing, and reading the output properties. After instantiating the Screen Native Access bean, you must set some parameters before execution. For general setup parameters, see the help topic Generating Interface Objects in the Task Builder for Screens component Help.

    Set the following methods:

    Caution If you get "ScreenChange" or "KeyboardLocked" exceptions when you execute the task, increase the settle time or use setScreenCount instead.
  2. To get the initial set of screen data, call setCommand with a INativeAccessConstants.CMD_REFRESH_NULL value.

  3. To use the same session on the host, use the transferContext method from the Screen Native Access bean (See Transferring Context). For XML, follow the configuration directions under Configuring and Using the Screen Native Access XML Interface Object and call the execute method with the transaction ID for the Screen Native Access transaction.

Initializing the Screen Native Access Bean

//initialize your task beanScreenNativeAccess
naBean = new ScreenNativeAccessEx( );
naBean.setSettleTime(2000);
naBean.setPreserveContext(ITask.PRESERVE_ALWAYS);
naBean.setShare ("MyPoolName");
naBean.setTimeout(30000);  //30 seconds
//call refresh to get the current screen information
naBean.setCommand( INativeAccessConstants.CMD_REFRESH_NULL );
naBean.executeSync();

Setting Field Text and Transmitting Data to the Host

Note Fields can be specified by either name or index. In the following example, if the field name were ProdNum, the first line of code would be naBean.setFieldInputText("ProdNum", "1");. 
//follow the instructions above for initializing the NAB

//set the text "1" in field index 35
naBean.setFieldInputText(35, "1");
naBean.setCommand( INativeAccessConstants.CMD_TRANSMIT );	//ENTER
naBean.executeSync();

Configuring and Using the Screen Native Access XML Interface Object

Note The Screen Native Access metadata is contained in NativeScreen.xml and located in the Attachmate\Eai\recordings directory.

Configuring the Screen Native Access XML Interface Object

  1. Copy the NativeScreenAccess transaction, (the information contained within <transaction id="NativeScreenAccess"></transaction>), from NativeScreen.xml to the MyConnector.xml file, where MyConnector is the name of your task file.

  2. Copy the ConfigData section from NativeScreen.xml to the ConfigData section of MyConnector.xml.

  3. After adding the second transaction, edit the map and resource attributes associated with it. These values must match the map and resource attributes associated with the first transaction of MyConnector.xml.

  4. Set the setScreenCount attribute. This is the number of records to wait before returning the screen, as indicated by the number of EORs (End Of Record) received. The ScreenCount value you should set depends on the number of EORs you expect to encounter for a particular screen. This overrides the global wait time associated with the NavMap and the setSettleTime attribute, if also specified.

    -or-

    Set the setSettleTime attribute. Settle time is the amount of wait time provided to the host screen to process changes.

    Caution If you get "ScreenChange" or "KeyboardLocked" exceptions when you execute the task, increase the settle time or use setScreenCount instead.
  5. To retrieve the information described in the ScreenOutputs section of the NativeScreen.xml metadata, set the commandValue attribute to 0 (INativeAccessConstants.CMD_REFRESH_NULL). The Command element invokes the Refresh method that retrieves all the fields and their attributes from the current screen.

    For example:

    <ScreenInputs>
    <Command commandValue="0" settleTime="1500"></Command>
     <Field id="" text=""></Field>
</ScreenInputs>

Configuring and Using the Screen Native Access XML Interface Object - Sample 1
Getting the Current Screen

//create a new connector and open your XML file
IConnectorAccess connector = new ScreenConnectorAccessImpl()
connector.open( "C:\\connectors\\MyConnector.xml" ); 

//create your input xml. Set your commandValue and settleTime here
String inputsXml = "<ScreenInputs><Command commandValue=\"" +
INativeAccessConstants.CMD_REFRESH_NULL + "\" settleTime=\"2000\" cursorRow=\"0\"
cursorColumn=\"0\" currentPage=\"\" ></Command><Field id=\"\" text=\"\" ></Field></ScreenInputs>";

//execute the ScreenNativeAccess transaction
connector.execute( "NativeScreenAccess", inputsXml );

//get the output
String outputXml = connector.getData();

Configuring and Using the Screen Native Access XML Interface Object - Sample 2
Setting Field Data and Transmitting to Host

Note While the bean uses the field index (zero based) or name to identify a particular field, the XML uses a field ID based on the position of the field on the screen. For example, if a field starts on row 20, column 7, and has 80 columns on the screen, the field position is 19x80+7=1527. When calculating the position, count the 19 rows before the 20th row, then add the number of column positions to get the screen position. Use the Task Builder for Screens to get the required information about a particular screen. 
//create a new connector and open your XML file
IConnectorAccess connector = new ScreenConnectorAccessImpl()
connector.open( "C:\\connectors\\MyConnector.xml" ); 

//create your input xml for setting the field text "1" in the field that
//starts on row 20, column 7 (on a screen with 80 columns).
String inputsXml = "<ScreenInputs><Command commandValue=\"" +
INativeAccessConstants.CMD_TRANSMIT + "\" settleTime=\"2000\" cursorRow=\"0\"
cursorColumn=\"0\" currentPage=\"\" ></Command><Field id=\"1527\"
text=\"1\"></Field></ScreenInputs>";

//execute the ScreenNativeAccess transaction
connector.execute( "NativeScreenAccess", inputsXml );

//get the output
String outputXml = connector.getData();

Transferring Context

Transferring context applies only to a Screen Native Access Bean. Transferring context may be useful if you have a Task1—> NAB—> Task2 type of scenario.

Transferring Context with a Bean

Note Fields can be specified by either name or index. 
//initialize your bean
ScreenNativeAccessEx naBean = new ScreenNativeAccessEx( );
naBean.setScreenCount(4);
naBean.setPreserveContext(ITask.PRESERVE_ALWAYS);
naBean.setShare ("MyPoolName");
naBean.setTimeout(30000);

//create your Task1 bean
Task1 task1 = new Task1();

//Preserve the context to prevent the bean from releasing the context
task1.setPreserveContext(ITask.PRESERVE_ALWAYS);

//execute task1
task1.executeSync();

//tranfer context from task1 to the Native Access Bean
naBean.transferContext( task1 );

//This example assumes that the destination screen is defined in the NavMap.
//In this example, we are setting the text "test" in field UserName, transmitting 
//"@E" to the host, and then verifying that we are on screen "TheRightScreen" when 
//it returns.
naBean.setFieldInputText("UserName", "test");
naBean.setCommand(INativeAccessConstants.CMD_TRANSMIT); //Enter
naBean.executeSync( );

if (naBean.getScreenName ( )==null||
!naBean.getScreenName ( ).equals ("TheRightScreen"))
{
	//ERROR - we are not on the screen we expected to be on and we need to handle the error.
}

//create Task2 and transfer context.

Task2 task2 = new Task2 ( );
Task2.setPreserveContext (Itask.PRESERVE_ALWAYS);

//transfer context from naBean to Task 2 and execute task2
task2.transferContext(naBean);
task2.executeSync ( );"
Note To set the field text, the developer must have full screen knowledge, (field indexes or names, field count, protected/unprotected fields, etc). This information is available by opening the map being used for these tasks in Task Builder and viewing the desired screen.
  • If the screen is not part of the map being used, getScreenName returns null.
  • It may be necessary to check the attributes of a field before acting on it. See Screen Attributes for more information.

Receiving Screen Events

The bean is initialized in a similar way to the example, Transferring Context with a Bean, that is, creating a ScreenNativeAccessEx and setting its options. In addition, the ScreenNativeAccessEx object must establish itself as a listener for screen events. That is done by implementing the IHostUpdateListener interface and calling its addHostUpdateListener() method.

The IHostUpdateListener interface has four methods, one for each type of event that can be received by the client:

The client must implement all of the methods. The methods can be empty for events that are not needed.

//initialize your bean
ScreenNativeAccessEx naBean = new ScreenNativeAccessEx( ); 
naBean.setSettleTime(1500); //time in msec
naBean.setScreenCount(4);   //this is optional; ScreenCount has priority over SettleTime
naBean.setPreserveContext(ITask.PRESERVE_ALWAYS);
naBean.setShare ("MyPoolName");
naBean.setTimeout(30000);

//add this client as a listener for screen events;
//Notes: 
//	The client must implement IHostUpdateListener.
//	Before terminating, the client removes the listener with removeHostUpdateListener().
try
{
	naBean.addHostUpdateListener(this);
}
catch (Exception e)
{
	//ERROR: an exception occurs if a TCP/IP connection cannot be established with the Runtime Service for Screens server
	//process the exception, e.g log the exception and/or terminate the client
}

//call refresh to get the current screen information
//Note: The first INativeAccessConstants.CMD_REFRESH_NULL command allocates a pool session.  
naBean.setCommand( INativeAccessConstants.CMD_REFRESH_NULL ); naBean.executeSync();

//perform some useful operations with the host, e.g.
//set fields data, navigate to a different screen, get data from the screen
int fieldIndex = naBean.getFieldIndex("CommandInput");
naBean.setFieldText ( fieldIndex, "someValue");
naBean.setCommand( INativeAccessConstants.CMD_TRANSMIT );	//ENTER
naBean.executeSync();
if (naBean.getScreenName()==null || !naBean.getScreenName().equals("TheRightScreen"))
{
	//ERROR - we are not on the screen we expected to be on and we need to handle the error.
}

//in the same client class implement the IHostUpdateListener methods
//and use the events that are needed
public void hostScreenChanged(ScreenChangedEvent e) 
{
	//process the screen change event
}
public void hostScreenShapeChangeChanged(ScreenShapeChangeEvent e) {}
public void hostScreenTypeChanged(ScreenTypeChangeEvent e) {}
public void hostEndOfRecord() {}

Screen Attributes

Screen attributes and command constants are provided in a separate interface, INativeAccessConstants, located in the Javadocs in Attachmate\EAI\documentation\connector_screens\sdk\client\javadocs\index.html.

Using the Bean to get the Field Attribute

The example uses a bean to get the field attribute for field with index 5. If you are using IConnectorAccess, the field attribute is an attribute of the field element in the XML output. To retrieve a field attribute from a particular field, use an XML parser to extract the value.

Note While the bean uses the field index (zero based) or name to identify a particular field, the XML uses a field ID based on the position of the field on the screen. For example, if a field starts on row 20, column 7, and has 80 columns on the screen, the field position is 19x80+7=1527. Use the Task Builder for Screens to get the required information about a particular screen. 
//Get the field attribute for the field with index 5
long attr=naBean.getFieldAttr(5);

//To check if a field is protected
If ( (attr & INativeAccessConstants.FIELD_MODE_PROTECTED)==
INativeAccessConstants.FIELD_MODE_PROTECTED)
{
  	//The field is protected
}

//To check if a field is numeric only
If ( (attr & INativeAccessConstants.FIELD_NUMERIC_ONLY)==
INativeAccessConstants.FIELD_NUMERIC_ONLY)
{
  	//The field is numeric
}
Related Topics
Bullet Using Screen Native Access, Overview
Bullet Javadocs for Attachmate Interfaces
  Attachmate