Tutorial 10


This document describes how you move files from your development system to your target system and how you provide your end-users access to the application (URL or icon).


Ø  That deployment using these instructions is to a complete and operational production aXes system of the correct version and that no aXes screen development of any kind will be carried out with the deployed definition set.

Ø  That at least Tutorials 0 through to 3 have been completed.

Ø  That you have carefully considered how to Establish the Deployment Model as described in Tutorial 7 Best Practices.

Ø  That in addition to the modified files listed in the Files that need to be Deployed section, all required unmodified files as outlined in Tutorial 0 - Getting Started are also deployed to the target application folder.


Deployment of Files to the Target Application Folder

To deploy all required files from an aXes development project follow these steps:


Deployment Step



On the target system, create an application folder as a subfolder of the \axes\ts\screens folder using the ibm i CRTDIR command.


For example to create folder MyApplication1 in \axes\ts\screens\ folder:


CRTDIR DIR('axes\ts\screens\myapplication1')


The name for this folder:

v  Should not contain blanks. 

v  Should contain only letters from the English alphabet or numbers.

v  Is referred to as your application's Definition Set.


Remember, like aXes development projects, aXes deployed applications are discrete and indivisible:

Ø  You cannot merge definition sets together.

Ø  You cannot copy a definition set into another definition set. 

Ø  You cannot split a definition set up into other definition sets.


It is normal to have multiple users using the same definition set.       




Use the IBM i WRKLNK command and make sure that folder MyApplication1 has *R rights for user *PUBLIC and no other rights.


For example: Use WRKLNK OBJ('axes\ts\screens\ MyApplication1') then use option 9=Work with authority to display and alter the authority to folder MyApplication1. It should look like this when displayed by the WRKLNK command: 




Check that any static or dynamic table definitions used for testing have been removed from the respective definition files, Tables_Static.txt and Tables_Dynamic.txt.


These would typically be unused in the application now - and may fail if they are deployed to a production environment.



Check that the user the aXes server is executing under has READ authorisation to any required SQL/database tables.


SQL commands may be used to load static or dynamic tables in your application.

The commands execute under the user profile that the aXes server is executing under.


You should authorise that user profile for read access to the SQL tables required for this purpose. This user does not need any rights to other data base tables that may be on the system.



Next, copy the files listed in the Files That Need to be Deployed section from your project folder to the application folder on the target system.


Use the IBM i CPY commands and/or save/restore commands (using Windows copy commands can cause code page errors). You need to save the files to a save file and move the save file onto a PC to move it and then restore it to the target iSeries.


For example this command saves the contents of the  /axes directory to a save file:

    SAV DEV('/qsys.lib/savefilelib.lib/saveFile.file') OBJ(('/axes')) 


This command saves the contents of /axes and /axesdemo directory:

    SAV DEV('/qsys.lib/savefilelib.lib/saveFile.file') OBJ(('/axes') ('/axesdemo')) -


To restore the save file:

    RST DEV('/qsys.lib/savefilelib.lib/saveFile.file') OBJ(('/axes')) 


CPY examples:

    CPY  OBJ('/axesbuild/build/110/default_FCGI.conf') TODIR(/TGT_PATH)  






Finally, copy the application launch page, /axes/index.html, and the icon used in the browser and on desktops, /axes/favicon.ico, to the corresponding folder in the target aXes instance if these files have been customized. Note that this step is only required when deploying to a different aXes instance.






Files That Need to be Deployed

The following files need to be copied from the aXes development project folder to the application folder on the target aXes server. Some of these may not exist in the project folder.


v  application_definition.css (plus application_definition_*.css)

v  application_definition.js

v  Extension_*.js

v  screen_*.js

v  screens.jsn

v  Tables_Static.txt (see note 3)

v  Tables_Dynamic.txt (see note 3)

v  Userenv.js

v  *.xml



o   The *.scn files and the count.txt file do not need to be deployed from the development project folder into PRODUCTION application folders because these files are amalgamated into the screens.jsn file. No aXes screen development can be carried out within production application folders because the absence of *.scr files will cause all previously deployed screen definitions to be lost.

If the application is to be displayed in a language other than English the modified text files, Texts_Cust_*.txt also need to be copied. See the Application Internationalization section for the location of these files and additional deployment steps. Note that if you change a Texts_Cust_ll.txt file you should clear your browser cache to pick up the new file version.


o   If you have used additional static or dynamic table definition files - deploy these files as well. If you have changed the names of these files - deploy the renamed files instead.  


aXes eXtension Files

When aXes starts up, eXtensions are loaded from the axes\ts\screens folder first. Then eXtensions are loaded from the application definition set if present.


This means that the following extra steps need to be taken for deployment of aXes eXtensions:




aXes eXtensions that are specific for this application only are to be copied to the application folder (as previously described).



aXes eXtensions that are to be used by all applications on this system are to be copied from the axes/ts/screens folder of the development system to the axes/ts/screens folder of this system.


NOTE:  If the same eXtension exists in the screens folder and the application folder, the eXtension in the application folder should take precedence. However, this cannot be guaranteed and you should check which version is being used.



Starting aXes on the Target System

You will remember from a previous tutorial that to start aXes to access applications without eXtensions, you use a URL of the following format to get you to your Server:





<aXes_Host>  with the Host Name of your aXes Server

<aXes_Port_Number>  with the Port Number required to access your aXes Server


Using aXes to access an application on your Server that has been modernized with aXes eXtensions, you use a URL with a different format:





<aXes_Host>  with the Host Name or IP Address of your aXes Server

<aXes_Port_Number>  with the Port Number required to access your aXes Server

<application_folder> with the name of the folder that contains your application’s Definition Set (see later)

<LL>  with the appropriate language code from the Language Codes table. If not specified it will default to the Windows default language on the PC.


Note that when you start aXes using ts_basic.html, you are starting an aXes-TS 5250 terminal session without access to the aXes-WS Web Spooler capability.


To start a full aXes-TS terminal session which allows the viewing of spool files as HTML, PDF, XML or Text documents, start aXes using ts.html:





The above URL applies to the aXes-TS engine. If you are using the aXes-TS2 engine, the url is:





When the deployed application is to be used in IE, you can choose whether to use the aXes-TS or the aXes-TS2 engine. However, if your end-users' browser is Firefox, Google Chrome or Safari you must use the aXes-TS2 engine.



Put a Start Icon on End User Desktops

As a convenient way to start the completed aXes application you can provide a start icon for the end user's desk top.  The shortcut doesn't need to be created from scratch: it can simply be emailed to the user and dragged on to the user's desktop.


Ensure that the shortcut location correctly refers to the deployed application folder.


Don’t forget that the format of the URL required to access the application that you have modernized with aXes eXtensions is:





URL Parameters

You can specify parameters such as the user id and the device in the aXes URL:




Applicable to TS2 only


IBM i library



The name of the folder that contains your application’s definition set.



Turns on developer mode. Currently developer mode supports defining screen ids and changing AutoGUI settings.


Extension design must be done in TS1.




Device to connect to



The appropriate language code from the Language Codes table. If not specified it will default to the Windows default language on the PC.



Initial IBM i menu



By default, all files loaded by aXes (that are not expected to change) are cached by the browser to make future loads faster. Adding the noexpires parameter tells aXes not to do this (can be useful during development). 


This affects long-term caching by controlling whether the server sets an "expires" header on the files it sends.  Browsers may do some internal session level caching of their own that may still result in changes not being loaded. Even clearing the cache may not fix this (Google Chrome). Quitting and re-launching the browser usually will.




This parameter can have one of these values:


0 – Off all enhanced window handling.

1 – Turns on the detection of degraded DDS windows only. 

2 – Turns on the “keep the previous screen background” behaviour only.

3 – Turns on both.


From version 2.11 onwards, 3 is the default value used if this parameter is omitted.


See PopUp Windows and Screen Rendering in aXes-TS2.




Initial IBM i program



Password. For security reasons you need to consider carefully whether you want to expose a password in a url.



Reconnect to a previously disconnected session. Can be true or false.



IBM API screen type identifier



Automatically sign on. Can be true or false.



Turn on tracing and set the level. Valid values are:





Specifies and prefills the user profile to be used in the aXes logon dialog. If the user and password are both specified then the log on is performed automatically. 



This URL assigns user, password, device and auto-signon: http://<aXes_Host>:<aXes_Port_Number>/ts/skins/ts.html?device=ARB&user=alick&pwd=XXXX&signon=true


The URL parameters correspond to the options you can specify when logging on to aXes:


Note that the LUA tslogonexit.lua on the server controls whether client overrides are allowed. If the LUA variable allowClientOverride is set to False, the URL parameters are ignored.


Tracing Your Application


If you have a problem with a deployed application, you may want to trace it by adding the Trace parameter to the URL. For example:




Possible values of the trace parameter are:



Displays both system trace messages and application trace messages.


Displays only system trace messages


Displays only application trace messages


No trace messages are displayed. You can use this value by default to make it quick to turn on tracing:





System trace messages are those that are outputted by aXes core system.


Application trace messages are generated for eXtensions when TRACE commands are encountered in aXes code:


TRACE("The value in the job title field is: ", value, " more text ", " and more text" ); 


To trace aXes outside extensions use AXES.Trace. For example:


AXES.Trace.output(“This is an application trace”);



Application Internationalization

During the development of an aXes project designed to be executed in languages other than English, any customer visible text must be defined into the aXes TEXT object.  


Note that if you change a Texts_Cust_ll.txt file you should clear your browser cache to pick up the new file version.


Follow these steps as a guide to application internationalization:


Internationalization Step



All application text that is to be visible to the end user is defined in the file Texts_Cust_en.txt using the prescribed "key" : "text" format.


Note that if you change a Texts_Cust_ll.txt file you should clear your browser cache to pick up the new file version.


NOTE: See Tutorial 3 for an example of this technique.



All application text that is to be visible to the end user is displayed using the TEXT object.


For example


CTEXT("<text key>")


Where  <text key> is substituted with the key of the required text in the Texts_Cust_en.txt file



The Texts_Cust_en.txt file is translated in the required language and the translations are stored in a file named Texts_Cust_LL.txt where LL is substituted with the appropriate language code from the table in the Language Codes section.



The file Texts_Cust_en.txt plus any translated versions of this file, e.g. Texts_Cust_fr.txt for French translations, need to be copied from the  \axes\ts\lang folder on the development system to the corresponding folder of the target system.



Include the appropriate language code in the start icon for the end-user’s desktop or any aXes URL used to start the application.


For example:





<aXes_Host>  with the Host Name or IP Address of your aXes Server

<aXes_Port_Number>  with the Port Number required to access your aXes Server

<application_folder> with the name of the folder that contains your application’s Definition Set

<LL>  with the appropriate language code from the Language Codes table. If not specified it will default to the Windows default language on the PC.






Language Codes

The following is a list of language codes to be used with internationalised applications. They are always lowercase:


af Afrikaans

sq Albanian

ar-sa Arabic (Saudi Arabia)

ar-iq Arabic (Iraq)

ar-eg Arabic (Egypt)

ar-ly Arabic (Libya)

ar-dz Arabic (Algeria)

ar-ma Arabic (Morocco)

ar-tn Arabic (Tunisia)

ar-om Arabic (Oman)

ar-ye Arabic (Yemen)

ar-sy Arabic (Syria)

ar-jo Arabic (Jordan)

ar-lb Arabic (Lebanon)

ar-kw Arabic (Kuwait)

ar-ae Arabic (U.A.E.)

ar-bh Arabic (Bahrain)

ar-qa Arabic (Qatar)

eu Basque

bg Bulgarian

be Belarusian

ca Catalan

zh-tw Chinese (Taiwan)

zh-cn Chinese (PRC)

zh-hk Chinese (Hong Kong SAR)

zh-sg Chinese (Singapore)

hr Croatian

cs Czech

da Danish

nl Dutch (Standard)

nl-be Dutch (Belgium)

en English

en-us English (United States)

en-gb English (United Kingdom)

en-au English (Australia)

en-ca English (Canada)

en-nz English (New Zealand)

en-ie English (Ireland)

en-za English (South Africa)

en-jm English (Jamaica)

en English (Caribbean)

en-bz English (Belize)

en-tt English (Trinidad)

et Estonian

fo Faeroese

fa Farsi

fi Finnish

fr French (Standard)

fr-be French (Belgium)

fr-ca French (Canada)

fr-ch French (Switzerland)

fr-lu French (Luxembourg)

gd Gaelic (Scotland)

gd-ie Gaelic (Ireland)

de German (Standard)

de-ch German (Switzerland)

de-at German (Austria)

de-lu German (Luxembourg)

de-li German (Liechtenstein)

el Greek

he Hebrew

hi Hindi

hu Hungarian

is Icelandic

id Indonesian

it Italian (Standard)

it-ch Italian (Switzerland)

ja Japanese

ko Korean

ko Korean (Johab)

lv Latvian

lt Lithuanian

Macedonian (FYROM)

ms Malaysian

mt Maltese

no Norwegian (Bokmal)

no Norwegian (Nynorsk)

pl Polish

pt-br Portuguese (Brazil)

pt Portuguese (Portugal)

rm Rhaeto-Romanic

ro Romanian

ro-mo Romanian (Moldavia)

ru Russian

ru-mo Russian (Moldavia)

sz Sami (Lappish)

sr Serbian (Cyrillic)

sr Serbian (Latin)

sk Slovak

sl Slovenian

sb Sorbian

es Spanish (Spain ? Traditional)

es-mx Spanish (Mexico)

es Spanish (Spain ? Modern)

es-gt Spanish (Guatemala)

es-cr Spanish (Costa Rica)

es-pa Spanish (Panama)

es-do Spanish (Dominican Republic)

es-ve Spanish (Venezuela)

es-co Spanish (Colombia)

es-pe Spanish (Peru)

es-ar Spanish (Argentina)

es-ec Spanish (Ecuador)

es-cl Spanish (Chile)

es-uy Spanish (Uruguay)

es-py Spanish (Paraguay)

es-bo Spanish (Bolivia)

es-sv Spanish (El Salvador)

es-hn Spanish (Honduras)

es-ni Spanish (Nicaragua)

es-pr Spanish (Puerto Rico)

sx Sutu

sv Swedish

sv-fi Swedish (Finland)

th Thai

ts Tsonga

tn Tswana

tr Turkish

uk Ukrainian

ur Urdu

ve Venda

vi Vietnamese

xh Xhosa

ji Yiddish

zu Zulu