Tutorial 8

Best Practices


Develop Standards Early

You should develop a naming standard for screens, screen fields and scripting variables before commencing a screen modernization project. For example:


Type of Object

Naming Standard



Alpha Field in Screen


Numeric Field in Screen


Alpha Field in Subfile


Numeric Field in Subfile


Special fields repeated on many screens such as error message fields, page/up down "+", markers, titles, etc. 




Script string 


Script integer / whole number 


Script floating point / number with decimals


Script boolean


Script object 


Script object referring to HTML element


Script function



Prefix with additional a

Private member / object

Prefix with additional _ (underscore)


Where XXXXXXXXXXX is a meaningful name with precise case (e.g.: ProductNumber, not Productnumber) using letters from the English alphabet and 0 -> 9 only.

Avoid specifying fonts and colors for individual elements 

Avoid specifying fonts and colors for individual screen elements. Create application styling items based on the field's role in the application and use it instead. Refer to Tutorial 3 - Advanced Screen Enhancement and Tutorial 10 - 5250 Screen Styling for more details and examples.

Treat screen Modernization as a Project 

It's advisable to treat the modernization and customization of a 5250 applications as real IT project, rather than ad-hoc or part time activities. This means that all the normal IT project activities like end user consultation, detailed design, specifications, test planning, defined goals, etc should be brought into play. Remember the old saying "If you don't have a plan then you are planning to fail".     

Define your modernization "Value Proposition"  

Modernizing the appearance of a 5250 screen is one thing, but adding real value to a 5250 application is another. If you focus on appearance only, the early enthusiasm and support you may receive from your customers and users could fade as they realize that nothing has been done to make their working lives easier, better, faster or smarter (i.e.: more modern). It's worth spending some time at the start of a project to define exactly what value you will add to the existing 5250 application.     

Follow the 80/20 rule  

In most commercial 5250 applications 20% of the application accounts for 80% of the use. Focus on modernizing and customizing the 20% that is most used, not the 80% that is less used. You are probably better to modernize the Order Entry screens or the Insurance Policy Master Update screens rather than the Country Code Maintenance screens. 

Use an Incremental Delivery Plan  

If you have a large 5250 application consider using a staged and incremental delivery plan of gradual improvement rather than trying to deliver everything as a single "big bang" project. Typically this encourages earlier feedback from your users and customers, and a more gradual learning and experience curve for your developers.

Use static DBMS code tables in XML documents   

Relatively static DBMS content used for field codes and decodes can be (re)published when it changes as XML documents on the IFS. These documents can then be used as static table input to fill drop downs, service scripts, etc. This may be more efficient than using SQL to access the DBMS data.    

Always assess screen customizations as a user 

You should always test and assess your screen customizations and eXtension scripting signed on as a user. While you can conduct tests logged on as an aXes developer, the tests are not valid because they do not reflect a real execution environment.  

Use Two Discrete Cycles: Identify and Customize 

In eXtension projects it is best if two clearly separated cycles are used.


-          Identify the screens that you intend to enhance and name the fields on them. Verify that all variations of the screen(s) involved are correctly identified. 


-          Then, individually customize and test the screens.


Mixing the identification and customization cycles together is not a recommended approach.    

Document/Communicate USERENV content

The USERENV object is a useful way to reuse and share common properties and logic. If you spend time documenting and communicating the details to all the project team members, this encourages re-use and helps to enforce standards.


Versioning aXes projects

This section outlines some general notes about versioning any product, not just aXes. It does not represent anything that is officially supported or sanctioned by LANSA or aXes.


The advice is folder based. Disk space is cheap and getting cheaper. People’s time is expensive and getting more expensive. You can be too clever with elaborate folder structures designed to save space and end up confusing people and causing unnecessary mistakes - KISS is best.   


A simple way and low cost way to version aXes projects

Use project folders named like SSS_PPPPP_NNNN_FFF where

SSS = System Type – one of DEV, TST or PRD meaning development, test, production,

PPPPP = Project Name

NNNN = Project Build of Version Number

FFF = Optional hotfix or branch number


Development -> Test -> Production flow

When a development version is completed it is promoted to testing.

For example:


DEV_ProjectName_0001  is promoted to  TST_ProjectName_0001

This flow is repeated until version 0001 is considered to be tested and ready.


When testing is complete it is promoted to production: TST_ProjectName_0001  is promoted to  PRD_ProjectName_0001. Users directly (or indirectly via a launch page) use PRD_ProjectName_0001 on their start up URLs.


Starting to work on a New Version

When work and testing completes on a project version a new version is started.

 For example:

DEV_ProjectName_0001 is procedurally locked and possibly archived.

DEV_ProjectName_0001  is copied to DEV_ProjectName_0002

Developers now all work on DEV_ProjectName_0002 

When development completes, repeat the preceding development -> test -> production cycle and then move on to DEV_ProjectName_0003. 


Back version Maintenance

The archived and procedurally locked back version is used to perform the change.

For example – a user reports an issue on version 0005 - but people are already testing version 0006 and the developers are already working on version 0007. 

DEV_ProjectName_0005 is restored (if required) and procedurally unlocked.

DEV_ProjectName_0005 is corrected.

DEV_ProjectName_0005 is promoted to TST_ProjectName_0005 for final test.

TST_ProjectName_0005 is promoted to PRD_ProjectName_0005 when ready for production

DEV_ProjectName_0005 is procedurally locked and re-archived.

The correction may need to "propagate to the tip". This means that product version 006 (in testing) and 0007 (under development) may also need to be corrected because they require the same correction. This is a very common IT back version correction issue and has nothing at all to do with aXes per se.   

The DEV_ProjectName_0007 developers continued to work through all this with no impact.


A  variation that tracks every fix made to every version may be:

DEV_ProjectName_0005 is promoted to DEV_ProjectName_0005_001 (fix number 001)

DEV_ProjectName_0005_001 is promoted to TST_ProjectName_0005 for final test.

TST_ProjectName_0005 is promoted to PRD_ProjectName_0005 when ready for production

This variation maintains version 0005 in its original "as shipped" state and each cumulative fix is also maintained as a complete working unit.   


Use the FFF prefix (or some other variation) in the folder name to also denote a branch as well as a fix. Branching is only usually required when a major feature or development needs to be back fitted into a preceding version for a special case or customer.

For example - branching may be required if a customer of your application refuses to upgrade to your latest version - but demands that a new version feature be made to work in their old version. This means you need to put a branch into the older product version.       

Going live with a new version

Let’s say you are using PRD_ProjectName_0005 and you are ready to go live with version 0006.

You can run versions 0005 and 0006 side by side for a while, gradually introducing the new version by selectively changing user desktop URLs to use PRD_ProjectName_0006 instead of PRD_ProjectName_0005.

To avoid changing desktop URLs, you can give users a "launch page" named, for example, ProjectName.htm. When ready to move from version 0005 to version 0006, change the launch URL in ProjectName.htm.       


Put the version/build and fix numbers into the USRENV object and make them visible on some screen when a button is clicked. This allows you to determine the exact build/version and fix level of your application that they are using.

Supporting Multiple Customer Bespoke Versions

Use alternative name components. For example DEV_CustomerName_ProjectName_0001.

Folder Storage

The folder names used here are logical more than physical. Their actual content can be copied to cheap mass storage space on a Windows servers and/or versioned and archived using many different PC systems – for example, Vault.


Establish the Deployment Model

aXes only allows one system (at the same version level) to be installed onto an IBM Server. An aXes system can run multiple separate instances. An instance can contain multiple definition sets - each containing a discrete and independent application.


The three levels of separation (system, instance and definition set) allow for many different deployment configuration models. The most typical of these are:



Here the users and developers all work within the same definition set, within the same instance, within the same system. This is a high risk configuration because the activities of the developers will almost certainly interfere with those of the users.    




Here the developers and users work from separate definition sets, even though they are still working within the same instance and system. This will reduce interference, except for occasions where developers may need to stop and restart their aXes instance.  




Here the users and developers work in different definition sets and different instances. The major risk in this configuration is of deploying something to a production user without first testing it in a dedicated tested environment.



The deployment risk in the preceding model can be reduced by introducing a dedicated test instance and definition set. Production material is bundled and deployed to the test environment for suite testing before it is finally deployed to the production environment.




This type of deployment model minimizes all risks, but requires two physical or logical (LPAR) IBM i servers.  


If You Use aXes-eXtensions with aXes-Cloud

aXes-Cloud comes with all of the features of aXes including aXes-eXtensions.

aXes-Cloud uses Telnet to connect with applications on remote servers and therefore aXes requires no installation of objects on remote servers that support the applications.

Screen identification characteristics differ when used on the local server and when used on remote servers via Telnet. Therefore developers must identify screens as they will appear in the production environment on the remote server, in other words in the same context as users will use the application.

This means developers must sign on to the cloud gateway server, connect and sign on to a remote server, start an application and then work on extending the screens. When users use the applications, aXes-Cloud applies the enhancements built with aXes-eXtensions in real time from the cloud gateway server.

The following table summarizes the policies for using aXes-eXtensions with aXes-Cloud:

The aXes-eXtensions projects must reside on the cloud gateway server.

Developers work on the projects on the cloud gateway server.

Developers must be connected to an application on a remote server when working on the projects.



Do not extend screens locally and assume they will operate as you expect when the applications run on remote servers.