The Shipped 5250 Basic Themes and Customized Styles

aXes ships with a set of basic 5250 themes. These are accessible from the aXes menu:


Once you start to customize an application you should stop using the basic 5250 themes and develop your own customized role based styles and themes. Tutorial 3 introduced this concept. The following tutorial covers it in much more depth.

Initially some of this material may seem complex to you. However the time you invest in understanding it will greatly improve the final appearance of your application.

Using Role Based Styles

By now you should have encountered the concept of using role based styles for screen elements.

This means you might create a style called Instruction that uses the Verdana font, in blue, using 10 pt italics.

On customized 5250 screens, rather than specify style elements over and over for screen instructions, you simply associated the style Instruction with the screen instructions.

The role based approach is faster, more accurate and much easier to change than applying individual style elements to the screen fields.

Here's a list of some of the common roles that information on a 5250 screen has:

Panel Identifier

Panel Title


Field Label

Field Column Heading

Group Heading

Normal Text

Emphasised Text

Input field – Normal

Input Field – Emphasised

Output field – Normal

Output field - Emphasised

Scrolling Information


Function Key

Error Message

This basic list of screen element roles is traceable right back to the IBM CUA (Common User Access) standards developed in the late 1980s. Role based styling is not a new idea.

Do not have too many styles

You may end up with 10, 20 or even 30 individual role based styles.

If you have more than 30, you may be misinterpreting how to use them.

Using Themes

A further refinement of the style approach is to define overarching themes for your whole application.

Themes are just names, and typically they reflect an overall theme or style of appearance across a whole application.

You might dream up exotic theme names like Midnight, Sunset and Moonlight, but commonly designers use themes that are influenced by Microsoft - like their Blue, Silver and Olive themes. First introduced with Windows XP these themes are known to millions of people throughout the world.

In this example we are going to use 4 themes:





Usually the first thing you want to associate with a theme is a primary background color - so here is what we are going to use in this example:













In the application properties you would then define 4 basic styles like this (In ts2, name should be unique):







Application Window

Background-color: #A9CAF7



Application Window

Background-color: #E7E8EB



Application Window

Background-color: #CDDCC5



Application Window

Background-color: #B8BABE


Next the basic application property defaultTheme is set to indicate the default theme is blue:


Note that the default theme is a property that can be derived from script - so you can change the defaultTheme at application start up.

Note: If you are using aXes with RAMP-TS you would normally not bother to set up screen background colors. RAMP-TS will set the background color of its own current theme automatically.

Dynamically Changing Themes

You can also change the theme being used dynamically.

In this example a quick pick menu extension has been added to the System i Main Menu like this:


The quick pick menu's onItemSelection property has this script:

var sTheme = "";

switch (ENV.itemNumber)


case 2: sTheme = "SILVER"; break;

case 3: sTheme = "OLIVE"; break;

case 4: sTheme = "GRAPHITE"; break;

default: sTheme = "BLUE"; break;



This script is using the function SETAXESTHEME() to alter the theme that is being used dynamically.

If you do this you will see the main system menu dynamically change color.

You can also use var sTheme = GETAXESTHEME() to find out what the current theme is in your scripts.

Note: If you are using aXes with RAMP-TS you should not dynamically change themes this way. Instead you should follow the theme that RAMP-TS is using. It can be accessed in an eXtension script as RAMP.GLOBAL_VL_Theme. It will contain one of strings "BLUE", "OLIVE", "SILVER" or "GRAPHITE". Additionally the background color that RAMP-TS is using can be accessed as RAMP.GLOBAL_HTML_BackColor which will contain a #RRGGBB style color value.

Applying Themes to Screen Elements

Next we are going to use the same approach to handle a role based screen element.

A new style named InstructionColor (in all 4 themes) is defined like this:







color: red



color: green



color: blue



color: white

font-weight: bold


Note: These color choices are to make this example clear. They are not good choices for a real application because they are not sympathetic to the overall theme, with the possible exception of the Graphite one.

Next, the instruction line on the System i Main menu has the style Instruction associated with it, like this:


Now as the theme is changed by the quick pick menu, the style of the instruction line changes as well:

Blue Theme


Silver Theme


Olive Theme


Graphite Theme


Next, we are going to create a new style named Title.

This time we are going to just define these 2 entries:







color: blue;

font-weight: bold;

font-style: italic;


color: white;

font-weight: bold;

font-style: normal;


Title is defined once with no theme - and again, but only for the theme Graphite.

Next the style Title is associated with the title on the IBM i Main Menu.

As the 4 themes are cycled it appears as:

Blue Theme


Silver Theme


Olive Theme


Graphite Theme


Where most of the themes use the same style elements - you only need to define the styles that are different. Here blue, silver and olive all use the Title style that has no associated theme.

Setting Styles Dynamically – Basic Concepts

The starting point for this example is the System I Main Menu, where:

v  The 5250 screen is named MAIN

v  The selection or command field is named CommandLine.

v  Two push button eXtensions, captioned Red and Black, have been added.


The onClick property of the Red push button is set to this:

var oStyle = { "color":"yellow", "background-color":"red" };


var cmdfld= FIELDS("CommandLine");





The onClick property of the Black push button is set to this:

var oStyle = new Object();

oStyle["color"] = "white";

oStyle["background-color"] = "black";


var cmdfld= FIELDS("CommandLine");





These button click scripts first create a script object (named oStyle here) that specifies a text color and a background color.

Next they get a reference to the field CommandLine on the screen and alter its style (in fact the style of axdv - its default visualization).

Finally the command line field is then instructed to refresh its visualization.

If you click the Red button the command line entry field should look like this:


If you click the Black button the command line entry field should look like this:


In eXtension scripting styles are defined in JavaScript objects.

So to create a style dynamically you could code this:

var oStyle = { "color":"yellow", "background-color":"red" };

or you could code this - which may be more familiar:

var oStyle = new Object();


oStyle["color"] = "white";


oStyle["background-color"] = "black";

Note: The style element names like color and background-color that you use are identical to those you see when you set up a style and correspond to the standard CSS style names. They are case sensitive names.

Both these style object construction techniques are functionally identical, but the second technique generally makes it easier to put if/else logic into the set up.

You can also mix and match the techniques like this:

var oStyle = { "background-color":"red" };


if (condition) oStyle["color"] = "white";

else oStyle["color"] = "palestraw";

Setting Styles Dynamically – Self Styling

The preceding Basic Concepts example uses two push buttons to alter the style of the command line. This is typical of the situation where a user’s action like clicking the Save button may cause screen elements to change their style.

Another way to style screen style elements is to let them style themselves. This is only applicable to TS 1.

Typically they do this by looking at their own content and style themselves to attract the user’s attention.

For example, a YES/NO field related to whether a customer should be extended more credit might change itself to red when it contains NO.

Self styling can be demonstrated by altering the example started in the preceding Basic Concepts section as follows.

First, the CommandLine field is selected, and the Style property of its Default Visualization is changed to be evaluated by executing script:


Where the script used is like this:

/* Create a default style with a white background */


var oStyle = {"background-color":"white"};


/* See what is in this field (ie: CommandLine) */


var sValue = FIELD.getValue().toUpperCase();


/* If it contains blue or green make it the background color */


if ((sValue == "BLUE") || (sValue == "GREEN")) oStyle["background-color"] = sValue;


/* Return the style object to be used for this field (ie: CommandLine) */


ENV.returnValue = oStyle;

This change is saved and then the System I Main Menu is executed.

If you type the word green or blue into the command line and press enter (or any key that causes the screen to be redisplayed by the server), you should see the style change like this:


Or like this:


Type anything else into the command area and the default background color of white will be used:


For TS2, since the Style property of the element does not allow script (only through list of attributes or JSON format) to style themselves, you can put the above code in screen event like onArrive or in button’s onClick event or any other event that must be triggered.

Setting Styles Dynamically – Using the USERENV object

The preceding Basic Concepts example used hard coded style elements for the color and background color.

By using the USERENV object you can centralize and abstract style logic.

First, edit your USERENV object.

Add the highlighted code:




REDStyle : { "color" : "yellow", "background-color" : "red" },

BLACKStyle : { "color" : "white", "background-color" : "black" },

This code defines new objects USERENV.REDStyle and USERENV.BLACKStyle.

Save your USERENV object changes. Then start a new aXes developer session to make sure you pick up the modified USERENV.JS file.

Change the onClick property of the Red push button to this:

var cmdfld= FIELDS("CommandLine");







Change the onClick property of the Black push button to this:

var cmdfld= FIELDS("CommandLine");





It's worth noting this about this new code:

·         USERENV.REDStyle and USERENV.BLACKStyle are defined in one place. Where many scripts refer to them this makes changing them much simpler.

·         This code version is marginally more efficient. The original version had to repeatedly create style objects. This version just refers to a pre-existing style - eliminating the cost of creating objects.

·         Using style names like RED and BLACK is not recommended - but they suit the purpose of making this example simple.

In a real application your style names should generally not reflect the physical characteristics of the style, such as its color.

Instead they should reflect its role - like EMPHASIZED or ERROR. Using the role based approach abstracts the definition of how an ERROR is actually visualized away from individual scripts.

·         You can probably start to see how you can reduce your scripting even more by putting progressively more compound functions into the USERENV object.

You should be able to reduce the scripting required for the Red button to a single line like this:


And to this for the black button:


Setting Styles Dynamically – Using Application Styles/Themes

The preceding Basic Concepts example used hard coded style elements for the color and background color.

A better solution may be to use application level styles.

This approach also allows the styles to be dynamically themed.

If the application level styles named RedBoard and BlackBoard are defined as:

image024 image025

Then the code for the Red button could be changed to this better code:

var oStyle = { _base : "RedBoard" };


var cmdfld= FIELDS("CommandLine");





and for the black button:

var cmdfld= FIELDS("CommandLine");


cmdfld.setProperty("", { _base : "BlackBoard" } );



Here the special property _base in the style object is used to specify the application level style name.

Generally using an application level style is better because it centralizes the definition of the style and it performs slightly better.

Understanding Screen Sizing and the Thin Red Line

aXes is designed to display 5250 screens, which are typically 24x80 or 27x132 lines of characters/columns. By default aXes will display an area that represents this type of screen size (also see the next section about row / column size to understand how the default 5250 screen size is calculated).

When enhancing screens you can create more screen space - but before doing this it is best to understand how the screen sizing process works.

Display the System i Main Menu (named MAIN).

Set the aXes zoom factor to 100% using the drop-down in the right top corner of the screen.


Stretch the browser window out so that what you are seeing is much larger than the 5250 screen display area.

Put the screen in edit mode by clicking on Lock Screen icon.

Initially the area inside the thin red line represents the "5250 size" of this screen.

In TS2, you can no longer position the elements beyond the thin red line.

However, you can make more space on enhanced 5250 screens.

Select the Auto Zoom Screen Size extension from Extension Toolbox then drag and drop it on to the screen panel.


Then the screen customization window will now look like this:


The width and height properties of the Auto Zoom Screen Size extension allow you to specify the logical dimensions of this enhanced screen. In effect these properties allow you to move the thin red line boundary.

Specify width and height properties, something like this:


Note: These values are logical sizes, in pixels. It does not mean you have to have a screen that wide or high to display the screen. The auto zoom feature will zoom your screen in or out to fit the available browser display space at any time, no matter how large or how small it is. Refer to Screen Size documentation for the description of other properties such as zoom and lock zoom.

You should be able to move the boundaries out, something like this:


Save your screen changes.

Navigate off this screen and back again to make sure the sizing information is reset, properly.

Now start changing the image031 screen zoom setting again.

You should also try logging on to aXes as a user and checking your screen there when using various zoom sizes.

You should find that your "big" 5250 screen is correctly visible at all zoom sizes, particularly the Auto and Fit sizes.

There are some important things to note:

1.       Do not make the boundaries smaller than the 5250 screen default size. This is not supported in any form. Note that the 5250 screen boundaries will depend on whether the 5250 displayed screen is 24x80 or 27x132.

2.       You can make your screen very wide and very high, but as you do this the real 5250 screen area will proportionally shrink. If it shrinks too much users may not be able to read it and the screen caret may stop displaying correctly.

3.       Try to avoid a plethora of different "big" screen sizes. Decide on a single "big" screen size, or on a small standard set of them. Use them selectively.

A simple way to do this is to change the defaults for the Auto Screen Size's height and width properties. Then all a developer needs to do is check the Auto Screen Size eXtension to get the correct default "big" screen size.

Alternatively, the Auto Zoom Screen Size property values could be set by invoking a USERENV function like USERENV.iscreenHeight("medium"), USERENV.iscreenHeight("large") and USERENV.iscreenHeight("xlarge"). This would allow 3 "big" screen sizes to be centrally defined.

Using wide screens (132 x 27)

When you have 5250 wide screens you should design and execute your applications in wide screen mode.

In effect, any 24x80 mode of operation that your application may support would no longer be used when it is displayed by aXes.

Using Extended/Enhanced 5250 DDS attributes

5250 DDS sometimes contain extended/enhanced DDS attributes to display fields as radio buttons, drop downs, etc in the limited range of products that support the options.

aXes supports these extended/enhanced DDS options - but you should not add eXtensions to such screens as the GUI capabilities are different and contradictory.

Leave the screens to be displayed natively by aXes, but do not add eXtensions to them.

Changing 5250 Row / Column Size

By default rows in AXES 5250 screens will be 15 pixel high and columns will be 8 pixel wide.

image032image033 image034

If for some reason you decided to use larger font and changed the global style font to Verdana, 12pt, your screen will look similar to the one below:


Reminder: you need to set the useTerminalStyles property of this screen to false to allow custom styles to take effect.


You can see in the screenshot above that the edit boxes adjust according to the specified font size.

Use an application-level eXtension Terminal Settings to allow you to easily change the default height of rows in 5250 screens.

Follow these steps to use this eXtension:

·         Go to the aXes Developer window.

·         Lock the screen to switch to edit mode.

·         Select Application from the Extendable Objects dropdown to view the Application Properties.


·         Even if you have never customized a screen before, the Application Terminal Settings eXtension is already included in the Application Properties.

The value of the Terminal Settings properties in the property sheet is default.

<< TODO Update this part!>>

Set the rowHeight to 25 and spaceBetweenRows to 5. Save the settings (click the Save button at the top of the window). You will see your screen changes immediately to the one below:


About Fonts and Font Sizes

We recommend that you do not change fonts or font sizes via shipped style sheets or use customized style sheets to change fonts or font sizes.

If you change a style sheet you may need to clear your browser cache to get the changes.

We also recommend that you do not use variable width fonts on un-customized screens because somewhere down the track you will encounter a problem on a screen with subfile content or headings that appear to become misaligned. 

—  In Arial, compare the widths:



The string of W's is almost 3 times as wide as the I's.

—  In Lucida Console, compare the widths:



They are the same width.

This is the essence of the variable width/pitch font problem.

—  If an RPG program puts out these subfile headings as a single text output field:

   Customer Product     Order    Quantity    Value

   18181818 6373737     8484848       700    1,234.56              

   18181818 6373737     8484848       700    1,234.56              

You may end up with a display like this, when using a variable width font:

       Customer Product     Order    Quantity    Value

   18181818 6373737     8484848       700    1,234.56              

   18181818 6373737     8484848       700    1,234.56              

There is no resolution here. The 5250 DDS output strings …

'Customer Product     Order    Quantity    Value' (in Lucida Console)       

'Customer Product     Order    Quantity    Value'  (in Arial)

are exactly the same length – they simply have different display lengths.

If the program also outputs the subfile data columns as one long field instead of as individual fields (as some do) then the problem is even more exacerbated:

 Customer Product     Order    Quantity       Value

 1123     BOLTS       8484848         3        4.56 

 1123     NUTS        8484848       700    1,234.56 

 1123     HAMMER      8272         2000   11,234.56 

 Customer Product     Order    Quantity       Value

  1123     BOLTS       8484848         3        4.56 

  1123     NUTS        8484848       700    1,234.56 

  1123     HAMMER      8272         2000   11,234.56 

—  To change fonts or font sizes use the application definition eXtension. See Tutorial 3 – Setting up your Styles and also Tutorial 10 – 5250 screen styling. Changes you make to fonts and font sizes here may be applied to customized and non-customized screens. 

—  A 5250 screen is inherently a fixed width device which uses fixed width characters. A 5250 screen has 24 x 80 or 27 x 132 fixed width and height cells that may contain a character. Starting to use variable width characters in this model is always problematic and needs to be treated with care. aXes uses specific dimensions that indicate how wide and high a 5250 screen "cell"  is when it has to perform screen layout calculations.

—  <<TODO Edit – waiting for confirmation>>If you use a large font, or a font that is wider, you may need to adjust these cell sizes. This is done here:


If you change these values you need to check several customized and un-customized 5250 screens to see what impact your changes have made and how they operate in conjunction with your font and font size.

—  These cell size changes impact customized and non-customized screens. You should set your font and font size early and adjust the screen cell sizes accordingly. Changes made to these values when a project is in progress can impact the layout of screens already customized. 

5250 Attributes Bytes

The color and visual characteristics of fields on 5250 screens are controlled by attribute bytes. In a 5250 data stream the attribute byte (8 bits) precedes the field on the 5250 screen. An attribute byte will have one of these hexadecimal values:

x20 Green

x21 Green/Reverse Image

x22 White

x23 White/Reverse Image

x24 Green/Underscore

x25 Green/Underscore/Reverse Image

x26 White/Underscore

x27 Nondisplay

x28 Red

x29 Red/Reverse Image

x2A Red/Blink

x2B Red/Reverse Image/Blink

x2C Red/Underscore

x2D Red/Underscore/Reverse Image

x2E Red/Underscore/Blink

x2F Nondisplay

x30 Turquoise/Column Separators

x31 Turquoise/Column Separators/Reverse Image

x32 Yellow/Column Separators

x33 Yellow/Column Separators/Reverse Image

x34 Turquoise/Underscore

x35 Turquoise/Underscore/Reverse Image

x36 Yellow/Underscore

x37 Nondisplay

x38 Pink

x39 Pink/Reverse Image

x3A Blue

x3B Blue/Reverse Image

x3C Pink/Underscore

x3D Pink/Underscore/Reverse Image

x3E Blue/Underscore

x3F Nondisplay

When you use display file DDS keywords like underline - DSPATR(UL), reverse video - DSPATR(RI), or blue - COLOR(BLU) - you are telling the DDS display file compiler what attribute byte to put in front of the field on the 5250 screen.

5250 Attributes Bytes on Un-Customized 5250 screens

Note: This material applies to aXes-TS only.

When you display an un-customized screen the 5250 attribute bytes are mapped to web page characteristics by using a cascading style sheet, defined in a CSS document.

There is a cascading style sheet for each aXes theme.

For example - if you open axes\ts\skins\axes_blue.css with NOTEPAD you will see the style sheet used for the aXes blue theme.

If you search for X28 (the attribute byte for color RED) you will find the style details that define how a 5250 screen field with a X28 attribute byte is to be displayed by the web browser:

.x28, .Infield .x28


color: #cc0000 ;


This CSS definition says that the browser color #CC0000 image041 should be used for text in this field.

Note: Detailing the complete use of low level CSS attributes is beyond the scope of this tutorial. Extensive information is available from the W3C Schools link on the aXes Projects Home page.

The key things to understand about uncustomized screens and 5250 attribute bytes are:

·         Web browsers have no implicit understanding of 5250 attribute byte X28. What actually happens is that attribute byte X28 is mapped to a style that specifies the web browser characteristics to be used.

·         5250 colors are quite stark. Often the style sheets are used to map them to softer colors since the web browser has many more color possibilities.

·         Sometimes several 5250 colors are mapped to the same web color. For example, the 5250 colors blue and green may both map to web color black – often because it is unusual to find basic Windows GUI forms that make use of multi-colored text lines in the same way that 5250 screens do.

·         If you change an aXes shipped style sheet (CSS document) you should back up and also version your changes so that you can back out unwanted changes and won’t lose your changes when they are overwritten in an aXes upgrade.

5250 Attributes Bytes on Customized 5250 screens

When you customize a 5250 screen the CSS style sheets mentioned in the preceding section are normally not applied to the screen.

By customizing a screen you are indicating your intention to make it into a Windows style GUI form - often quite different to the original 5250 screen – so basic 5250 attribute bytes do not and cannot be applied in the same way.

The appearance of a customized screen is controlled purely by styles. Generally the use of styles and themes has many advantages over using 5250 attribute bytes.

However - for customized screens it is still possible to supply an attribute byte to style mapping - which will be automatically applied when it is possible to do so.

The process for doing this goes like this:

v  You define a normal eXtension style (as described in the preceding section).

v  You use the for5250Attributes property of the eXtension style to associate the style with one or more 5250 attribute bytes - in either an input and/or output field context.

v  When a 5250 field is presented on a customized form its attribute byte is used to decide whether an eXtension style should be automatically applied.

There are some key things to know about this process:

1.       The automatic application of a default style only makes sense when the 5250 field is still visualized like a 5250 field. Applying the style to a field that is visualized as something very different (eg: a drop down, radio buttons, a push button) is not possible.

2.       When a brand new element is added to a customized 5250 screen it has no 5250 attribute byte – so it is not possible to apply a style automatically. However - you can specify the style yourself, reusing one of the 5250 ones if you like.

3.       You can theme these styles just like any other style. So 5250 attribute COLOR(GRN) may automatically be interpreted differently if you are using a theme of blue or olive (say).

One of the key uses of this 5250 attribute mapping feature is in the handling of DSPATR(RI) – reverse video – which is often used to indicate an error state for a 5250 field.

Note: There is no such thing as an “error state” for a 5250 field. By convention many sites use DSPATR(RI) - but some sites alter a field’s color instead.

Here is an example of using this 5250 attribute byte mapping feature to handle DSPATR(RI) for error displays:

1. Open the styles property of the application:




2. Create a style called ErrorHighlighting as shown:


3. Click on the for5250Attributes property.

Add an item. Make it display attribute 25 - for an input field

(x25i - Input - Green/Underscore/Reverse Image)

This display attribute is commonly used by applications to indicate that a field is in error


4. Exit the style properties and save Application properties. You are now ready to test your change.

5. If you run the Axes demo program using commands ADDLIBLE AXESDEMO and then CALL XHRRPGTRN.

Select an employee, and edit their details, blank out the surname and press enter, you should see the field in error highlighted in red.


Now trying editing the ErrorHighlighting style.

Change the background color to Yellow an save your changes.

Restart the 5250 application again.

The background color should have changed from Red to Yellow.