You can easily modify your aXes application to make use of the features on the device such as camera, bar code scanning, geolocation etc. You can also make the device upload files to the IFS, and store information locally.

Modifying aXes Project to Use Features on the Device

To modify your aXes project, you need a basic knowledge of aXes screen customization and development with extensions.

If you do not have this basic knowledge, do the aXes tutorials 0, 1, 2 and 5 in the aXes Extensions Guide.

  • To start, create an aXes project for testing on your PC.
  • Start the project in Developer mode and display a screen that you can add buttons to and that has at least one input field. You could, for example, use the main menu if it has a command line. /p>
  • Use the suggest button to identify the screen:
  • And name an input field on it as "cmdline".
  • Save your changes.

You can now start customizing the screen

Now, in the aXes app on your device (smart phone, iPad etc.):

Touch Plus to add an aXes Terminal that points to your project. (Create the aXes Terminal the same way as you did before. Your project name goes in the "The aXes Definition Set" property.)

Check that you can start the session and navigate to the screen you want to use.

Note: When making changes to the aXes project it is usually sufficient to close the aXes Mobile Terminal session and restart it to pick up the project changes. But at some point you may need to clear the cache on the device – See Appendix 3 – Clearing the Cache during Development.

Taking a Picture and Uploading It

You can modify your aXes project so that an aXes Mobile user can touch a button on an aXes screen, and make the device take a photo.

You could use this feature to, for example, allow employees that have a smart phone to update their own photos on the IBM i.

Taking a Picture

Start with a simple button that takes a picture and puts it in the Photos gallery on your device.

On your PC, in aXes developer mode:

  • Go to your screen, edit the screen, and add a new element.
  • Make the new element a push button element (extension), with an onclick script like this:

var options ={imageName : "Photo_abc.jpg",annotate : true,width: "300" ,height : "300",saveToGallery : true}; try{LRSV.imageBasic(options);}catch (Error) { alert("problem setting photo name")};

Note how the parameters for the imageBasic service are passed as properties of an object named options.

You could also write the above in this way, if you prefer:

LRSV.imageBasic({ imageName : "Photo_abc.jpg", annotate : true, width: "300" , height : "300", saveToGallery : true });

LRSV stands for LongRange Services. It is the short way of writing LONGRANGE.Services.

So you could also write the statement this way:

LONGRANGE.Services.imageBasic({ imageName : "Photo_abc.jpg", annotate : true, width: "300" , height : "300", saveToGallery : true });

Next try out the button in the aXes App on your device:

  • Run your aXes project and navigate to your chosen screen.
  • Locate the button you added. If you touch it you should be able to take, and annotate, a picture.
  • Minimize the aXes App, and check that the photo has been added to the device's gallery of photos.

Note: If you are not sure that you are seeing the latest version of your button script on your mobile device, you can check it by adding a line like this at the start of the script:

alert("version 1");

Then when you run your aXes project in your aXes Mobile app and touch the button, you will see the alert message.

Uploading the Picture

Extend the example to make the device take the photo AND upload the photo to the IFS on the IBM i

You must have LongReach installed and working to be able to do this. The credential being used for the terminal session must have the LongReach URL in its Host List to do the upload.

On your PC, in aXes developer mode:

  • Add another push button to your aXes screen with an onclick script like this:

var config =

{

serverUrl: "http://<>:<>/service/longreach.jsp",

credential: "<>

};

LONGRANGE.FileTransfer.setDefaultConfig(config);

Where:

<<ip address>> The ip address of the IBM i you want to upload to

<<port>> The port for the LongReach server (usually 6563)

<,credential identifier>> The identifier of the user profile you have defined earlier.

 

If you want to look up the credential identifier, it is under Settings à Manage Credentials à Description tab.

This tells LONGRANGE which server to upload to and what user profile to use.

Then add the script to take the picture and do the upload using imageUpload:

var options =
{
    imageName : "Photo_abc.jpg ",     
    annotate : true,           
    toIFSfolder : <<IFS location>>
};
try {
      LRSV.imageUpload(options);
}
catch (Error) { alert("problem uploading photo"); }

where <<IFS location>> is the directory on the IFS where you want to upload to.

The location that you upload to has to be in a location that the LongReach configuration file authorises you to access. Usually you are authorised to: "/longreachdata/user/<<your user profile>>/"

  • So change the IFS location to, for example, "/longreachdata/user/MYPROFILE/"

Note: If you need to check the LongReach configuration settings, they are usually on the IFS in: \longreach\jsm\instance\system\httpd.xml.

More details  about LongReach configuration are available in the LongReach_Administrator_Guide_V1.2.pdf

  • Make the button caption "Take and Upload a Photo".
  • Save your changes.

Now, in aXes Mobile on the device:

  • Sign off in the session you were in, and then start the session again.
  • Navigate to your screen, and touch the button. You can now take and annotate a picture.

When you have finished, the picture will be automatically uploaded to the IFS in the /longreachdata/user/<<your user profile>>/  directory.

  • Check on the IFS that your image has been uploaded.

Reading a Bar Code into an IBM i Field

Suppose your company has barcoded products, and you want your employees to be able to look up on the IBM i the details of a product (such as identifier, model number, dimensions or stock levels). You can set up the aXes screen so that the camera of the device reads the bar code and feeds the number into an IBM i field. In this example we will use the field that you previously identified as cmdline.

On your PC, in aXes Developer mode:

  • Add a button to your aXes screen with an onclick script like this:

try

{

LRSV.scanPaste( { pasteTo : "cmdline" } );

}

catch (Error) { alert("Error using scanPaste service: ", Error.message); }

  • Make the button caption "Scan a barcode".
  • Save your changes.

 

On your smartphone:

  • Run your aXes project in your aXes Mobile app and touch the button.
  • Point the camera of the device at the bar code. When the camera recognises it, the bar code number is loaded into the cmdline field.

Entering the Number into an IBM i Field

You might want to modify this example so that the number would be sent to a product identifier field in your own application, and the Enter key would be pressed. However, you cannot do this because LongRange Services (LRSV) are asynchronous, which means you can't make use of the barcode value by directly scripting anything immediately following this line:

LRSV.scanPaste( { pasteTo : "cmdline" } );

In order to code something to happen after the bar code value is returned, your script needs to wait for the scanPaste to finish, and then use the value if the scan was successful.

The way to do this is to use a callback function. A callback function is a property of the options object. It executes when the scanPaste finishes:

if (window.LRSV)

{

/* Using a callback function to alert and press Enter */

var callBackFunction = function (result)

{

if ( result.success )

{

alert("callback function running. userInfo was:" + result.userInfo);

SENDKEY(ENV.defaultKey);

}

else

{

alert("there was an error:" + result.message);

}

};

 

var options =

{

pasteTo : "cmdline",

callBack : callBackFunction

};

 

try {

LRSV.scanPaste( options );

}

catch (Error) { alert("Error using scanPaste service: ", Error.message); }

}

 

The part in blue is the callback function. In this example of a callback function, the user touches the button, the barcode scanning and pasting occurs at some point, and then when it is finished, the Enter key on the aXes screen is pressed.

Note that the callback function can also detect if an error occurred, and the result.message value will indicate what the error was.

Note also that it is a good idea for scripts to check whether LongRange Services are available before they start using:

if (window.LRSV)

This is because the aXes script may be running in an environment like a PC where LongRange Services are not available, or even if it is running in aXes Mobile, the LongRange services may not yet be ready at the time the button is pressed.

Sending an Email when a Button Is Touched

On your PC, in aXes Developer mode:

  • Add a button to your aXes screen with an onclick script like this:

 if (window.LRSV)

{

var options =

{

text : ( "the command line contains:" + FIELDS("cmdline").getValue() ),

subject : "This is my email subject",

recipient : "This email address is being protected from spambots. You need JavaScript enabled to view it."

};

LRSV.sendEmail( options );

}

 (Replace This email address is being protected from spambots. You need JavaScript enabled to view it. with your own email address)

  • Make the button caption "Send an Email".
  • Save your changes.

On your device:

  • Run your aXes project, add some text to the cmdline field, and touch the button.

 An email with the text from the command line is sent.

Sending a Text Message (SMS) When a Button Is Touched

On your PC, in aXes Developer mode:

  • Add a button to your aXes screen with an onclick script like this:

 if (window.LRSV)

{

var options =

{

messageText : ( "the command line contains:" + FIELDS("cmdline").getValue() ),

recipient : "123456789"

};

LRSV.sendTextMessage( options );

}

(Replace 123456789 with your own mobile number)

  • Make the button caption "Send an SMS".
  • Save your changes.

On your device (smart phone or tablet if it can send text messages):

  • Run your aXes project in aXes Mobile, add some text to the cmdline field, and touch the button.

 A SMS with the text from the command line is sent.

 

Putting Screen Data on the Clipboard When the User Touches a Button

If the user wants to put data from a screen field onto the clipboard and allow it to be pasted onto other screens or other applications, they can always use the standard Copy and Paste.

However, sometimes you might want to make it easier for the user to copy data from a group of fields to the clipboard.

On your PC, in aXes Developer mode:

  • Add a button to your aXes screen with an onclick script like this:

var clipText = FIELDS("cmdline").getValue();

var items = [ { text : clipText } ];

var options = { arrayItems:items } ;

try { LRSV.copyToClipboard( options ); }

catch (Error) { alert("problem in clipboard " + Error.message ); }

  • Make the button caption "Copy cmdline to Clipboard".

On your device:

  • Run the aXes Mobile App and go to your screen, type a value into the cmdline field and touch the button. aXes will put the data on the clipboard.
  • Paste what was in the command line into a field on another aXes screen, or into another application on the device, like notes or the email client.

If you want the user to be able to copy multiple fields to the clipboard you can format the pasted data in various ways.

 By concatenating field data with tabs "\t" and newlines "\n", you can output the data in a way that suits the user when it is pasted.

 To copy multiple fields at once, you can send multiple field data in "items" like this:

var clipText1 = FIELDS("field1").getValue();

var clipText2 = FIELDS("field2").getValue();

var clipText3 = FIELDS("field3").getValue();

 var items = [ { text : clipText1}, { text : clipText2}, { text : clipText3} ];

Sharing Data across All Sessions

Say the user has located a customer they want to work with on aXes Terminal Session A and they now want to work with purchase orders for that customer.

They have purchase order maintenance open in aXes Terminal Session B. What we need is a way to get the selected customer id over to Session B.

If the customer id is in a field named myCustField in aXes in Session A, the button script to make it available to all sessions is:

var options =

{

name: "Shared_customer",

value: FIELDS("myCustField").getValue()

};

LONGRANGE.Form.setSharedState(options);

 

In session B, a button script can get that data under the name "Shared_customer", and write it to a field named myCustField_B on the purchase order maintenance screen like this:

var options =

{

name: "Shared_customer",

onCompleted: function(obj) { FIELDS("myCustField_B").setValue(obj.result); }

};

LONGRANGE.Form.getSharedState(options);

 

The session B button script could also be coded to press a function key or Enter, and do the purchase order search using the customer number from session A.

Programmatic Switching to Another aXes Terminal Session

To programmatically switch to another aXes terminal session you need to know the identifier of the aXes session you want the user to be switched to.

 

On your device:

  • Start the aXes-App, and go to Edit Mode.
  • Edit the details of the session you want to switch to
  • Touch Settings for that session
  • Ensure that your Switch-to session has a unique identifier (e.g. mySessionId)
  • Save your changes by touching Done twice.

 

On your PC, in your aXes project:

  • Locate the switch-from screen and ensure it is in Developer mode.
  • Add a button that does this:

var options =

{

name:"mySessionId",

replaceSession: false // Specifies whether open session should be closed first

};

LONGRANGE.Form.open(options);

 

On your device:

  • Start the aXes app.
  • Go to the switch-from session, and the switch-from screen, and touch the button you created.
  •  

You will see the switch-to session start up automatically.

 

Getting Your Current Location

On your PC, in aXes Developer mode:

  • Add a button to your aXes screen, with an onclick script like this:

 if (window.LRSV)

{

 var callBackFunction = function(result)

{

alert("Longitude: " + result.userInfo.LONGITUDE + " Latitude: " + result.userInfo.LATITUDE + " Altitude: " + result.userInfo.ALTITUDE );

};

var options =

{

callBack : callBackFunction

};

LRSV.getGeolocation( options );

}

 

  • Make the button caption "Get my current location".
  • Save your changes.

 On your device:

 Run your aXes project in aXes Mobile on your device, and touch the button.

 You will see your current location:latitude, longitude, and altitude. (This is the location of the device).

 

Other Things You Can Do to Modernize Your Existing 5250 Application

You can:

  • Include maps when displaying location information – It is possible to show an html window that displays a google map of a location whenever the IBM i displays a street address. This can give the end-user a better idea of where something is, or even directions on how to get there. If Google street view is available, the user can also get an idea of what the location looks like on the ground.
  • Make navigation much easier, especially for mobile phones and iPads, by adding large buttons for common navigation tasks. These buttons can set fields to values, and/or execute commands in the command line, and press any key.
  • Allow users to work off-site using a mobile phone, or a phone enabled iPad.
  • Allow users to download and store relevant information on the device when they are off-site and cannot get an internet connection.
  • Add graphs to show the screen data in a more meaningful way.
  • Switch to another session and pass information to it:

Say the user has located which customer they want to work with on aXes Terminal Session A.

So if, say, Session B shows the purchase order search screen, the screen can be set up to automatically load the selected customer from Session A into the customer search field, and press Enter, and display the purchase orders for that customer.

You could use a separate Session and project for each kind of switch – One session for Show_Purchase_Orders_for_a_Customer, one session for Show_Accounts_for_Customer etc.

Or you could set up one session and aXes project as the common point for all switches, and pass it the required action and identifier data, and make it handle it. Whenever switching to that session, you would tell it to close and restart the session if it was already open. In this way it would always start on the same screen after the switch.

If your IBM i application has a way of navigating to different parts of the system from the command line, you could put a script on a timer on the screen to write a call to the command line and press Enter to go where the user needs to go.

 

switch( myAction )

{

case "SHOW_ORDER":

/* Show the orders for a customer */

FIELDS("commandline").setValue("call pgm(ShowOrder) parms('" + myId + "')");

SENDKEY("Enter")

break;

 

case "SHOW_ACCOUNT":

/* Show the accounts for a customer */

FIELDS("commandline").setValue("call pgm(ShowAccount) parms('" + myId + "')");

SENDKEY("Enter")

break;

}

Administrators

Legal Mentions

aXes is brought to you by:

LANSA

Serving the IBM i community for 30 years.