The preceding examples embedded aXes sessions into a web browser page.

This section covers the basic techniques you can use to imbed aXes applications inside .NET applications – in other words, make a .NET application an external host to an aXes session.

To complete this tutorial you will need to create a .NET project and add the aXes interface (axexternalhost.dll) to it as a reference.

You will also need to create a .NET form to contain and manage the aXes session. A sample form is contained in the appendix of this tutorial (Form1.cs). Use this form as the main form in your .NET project.

Right at the start of the C# code you will see this area that needs to be changed for your site:

   private String protocol      = "http"; 
   private String host          = "vlfteam:8080";
   private String projectfolder = "aexternalhosting";

Change these values and compile your project.

You should be able to execute the .NET container form to get a display like this:

Image

The external host here is the very simple .NET form.

The aXes session will appear in the large white area at the bottom – embedded inside and controlled by the external .NET form.

The various .NET buttons demonstrate managing an aXes 5250 session from a .NET external host.

Opening an aXes session

Use the Open aXes Session button to get a display like this:

Image

When you click the Open aXes Session button this C# code in Form1.cs executes:

// ================================================================
// Open an Axes session 
// ================================================================

private void button_open_Click(object sender, EventArgs e)
{ oaXes.open(this.protocol, this.host, this.projectfolder, false); }

Monitoring Screen Arrivals and Departures

Note also the message A screen named MainLogon has arrived has appeared on the .NET form. This is because the .NET application is listening to events coming from the aXes interface indicating the arrival and departure of 5250 screens. The message appears because this C# event handler in Form1.cs is executed:

// ================================================================
// Handle arrival of an aXes screen
// ================================================================

private void ScreenArrived(object sender, ScreenArriveEventArgs evt)
{
ScreenInfo screen = evt.Screen;
if (screen.Name == "") textMessageInfo.Text = "The screen that has just arrived has no name.";
else textMessageInfo.Text = "A screen named " + screen.Name + " has arrived";
}

Sending Keys

Now type in an appropriate user profile and password and then click the Send Enter Key button. Your 5250 session should log on. This is an example of the most basic way that a .NET application can manage a 5250 session – by asking it to send key strokes.

The Send Enter Key button executes this C# code in Form1.cs:

private void button_enterkey_Click(object sender, EventArgs e)
{
oaXes.sendKey(Key.Enter);
}

Sharing Information

To try out the rest of the basic session management capabilities you first need to make some modifications to the System I Main Menu. These are:

  • Identify the System I Main Menu as a screen named MAIN.
  • Name the command entry field on the screen CommandLine.
  • Add some labels captioned Key and Value to the screen:
    Image
  • Add some new input fields to the screen. Name them Key and Value:
    Image
    Image
    Image
  • Add a new button to the screen captioned Send Value to .NET with this onClick scripting:
    var key = FIELDS("Key").getValue(); var value = FIELDS("Value").getValue(); var ua = USERENV.HOSTUSERAREA(); ua[key] = value;
  • Add a new button to the screen captioned Get Value from .NET with this onClick scripting:
    var key = FIELDS("Key").getValue(); var ua = USERENV.HOSTUSERAREA(); var value = ua[key]; if (value == null) value = "No value found"; FIELDS("Value").setValue(value);

The result of this should look like this:

Image

Save your changes.

If you did not do this in the preceding web browser examples, add this new functions to the USERENV object definition (copy/paste them is easiest):

HOSTUSERAREA : function()
{
if (AXES.HOSTSESSION == null) return(null);
if (AXES.HOSTSESSION.USERAREA == null) return(null);
return(AXES.HOSTSESSION.USERAREA);
},

Save your changes to update your project's USERENV.JS file. You may need to close and re-open your development session to pick up the changed USERENV object.

Now start your Form1.cs application running again and try these basic session management options:

Setting and Getting Screen Field Values

Start your .NET form and open an aXes session. Sign on the aXes session so that the System i Main menu appears.

Set the field name to CommandLine and the value to WRKJOB - then click the Set a Field Value button:

Image

You should see the command entry field in the aXes session change to WRKJOB.

Now click the Send Enter Key button:

Image

The axes 5250 screen should change to the Work With Job display.

This example demonstrates the basics of 5250 session management by a .NET application.

The middle entry field (containing a zero) is the field index. You only need to use that when you are dealing with a field that is in a sub-file on the 5250 screen.

By using the Get a Field Value button you can try out the reverse – retraining the value of a field from the aXes 5250 screen into the .NET application.

Sharing Information between the .NET container and the eXtension Scripts

Sometimes you want to exchange information between the .NET application and the aXes application that it not on the screen. For example the .NET application might want to tell the aXes scripting what the current order number is when it is not present on the screen.

Try this – change the name to CurrentOrder and the value to A762527 and click the Set a USERAREA button:

Image

The message area on the .NET screen should change – but the aXes screen will do nothing.

Now, on the aXes screen type in the key value CurrentOrder and click the Get Value from .NET button. The order value you input on the .NET screen should appear:

Image

This very simple example shows how information can be passed from a .NET application into an aXes extension script. The Get value from .NET button has this onClick script:

var key = FIELDS("Key").getValue();
var ua = USERENV.HOSTUSERAREA();
var value = ua[key];

where key contains the key that you typed in (“CurrentOrder”) and ua is a reference to the USERAREA that is shared between the .NET application and the aXes scripts.

The preceding web browser examples also user the USERAREA

By using the .NET Set a USERAREA and Get USERAREA buttons with the aXes Send value to .NET and Get value from .NET buttons along with various names you should be able to see how to passed information backwards and forwards between them.

By using a naming protocol for the things passed between .NET and the aXes extension it is easy to pass large amounts of data and even lists of data.

Getting and Setting Fields in a Subfile

In this part of the example the standard aXes demonstration program XHRRPGTRN is used for a subfile.

The subfile columns are named as Sel, Dept, BusUnit, Employee and Surname from the left:

Image

In Form1.cs the Set a USERAREA and Get USERAREA buttons are reassigned to be Set Sub-file Data and Get Sub-file Data.

The Set Sub-file Data buttons event handler is changed to this C# code:

private void button_setUSERAREA_Click(object sender, EventArgs e)
{
// Field definition for accessing the "Sel" subfile column
FieldInfo oField = new FieldInfo("Sel");
// Loop until all fields in column processed
do
{
// Move to next field, set the value to the first char of the index
oField.index++;
oField.value = oField.index.ToString().Substring(0, 1);
// Set the value
oaXes.setFieldValue(oField);
} while (oField.found);
}

When this new code is executed, it sets the selection column of the 5250 screen like this:

Image

The Get Sub-file Data buttons event handler is changed to this C# code:

// ================================================================
// Get a named value into the shared USERAREA
// ================================================================

private void button_getUSERAREA_Click(object sender, EventArgs e)
{
// Temporary holders for field values
FieldInfo oEmployee = new FieldInfo("Employee");
FieldInfo oSurname = new FieldInfo("Surname");
String Message = "";
// Read all fields in subfile and assemble message box details
do
{
oEmployee.index++;
oSurname.index++;
oaXes.getFieldValue(oEmployee);
oaXes.getFieldValue(oSurname);
if (oEmployee.found) Message += "Employee " + oEmployee.value + " Surname " + oSurname.value + "\r";
} while (oEmployee.found && (oEmployee.index < 20));
MessageBox.Show(Message);
}

When this new code is executed, it displays a message box fo subfile data like this:

Image

Summary

By working though this example and examining the C# code and the eXtension scripting you should understand how:

  • To open and close an aXes session imbedded inside a .NET application
  • To send function keys via the aXes session.
  • To get and set fields on the 5250 screens - including fields in a sub-file.
  • To exchange non-screen between .NET and eXtension scripts.

Administrators

Legal Mentions

aXes is brought to you by:

LANSA

Serving the IBM i community for 30 years.