Tutorial 10

Deployment

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).

Assumptions

Ø  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

Okay

 

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)  

    CPY  OBJ(/WRKPATH/*) TODIR(/TOPATH) SUBTREE(*ALL) REPLACE(*YES) OWNER(*KEEP)         

 

 

 

 

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

 

NOTES:

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:

 

Check

Okay

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:

 

http://<aXes_Host>:<aXes_Port_Number>/ts/skins/ts_basic.html

 

Replacing

<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:

 

http://<aXes_Host>:<aXes_Port_Number>/ts/skins/ts_basic.html?definitionset=<Application_folder>&lang=<LL>

 

Replacing

<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:

 

http://<aXes_Host>:<aXes_Port_Number>/ts/skins/ts.html?definitionset=<Application_folder>&lang=<LL>

 

 

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

 

http://<axes_host>>:<aXes_Port_Number>/ts/ts2/index.html?definitionSet=<Application_folder>&lang=<LL>

 

 

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:

 

http://<aXes_Host>:<aXes_Port_Number>/ts/skins/ts_basic.html?definitionset=<Application_folder>&lang=<LL>

 

 


URL Parameters

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

 

Parameter

Description

Applicable to TS2 only

curlib

IBM i library

 

definitionset

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

 

dev

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

 

Extension design must be done in TS1.

 

Yes

device

Device to connect to

 

lang

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

 

menu

Initial IBM i menu

 

noexpires

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.

 

 

popups

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.

 

Yes

Program

Initial IBM i program

 

pwd

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

 

reconnect

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

 

screentype

IBM API screen type identifier

 

signon

Automatically sign on. Can be true or false.

 

trace

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

s/sys/system
u/user/app/application
1/y/a/all/true

 

 

user

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:

 

http://lxsteam:8080/ts/skins/ts_basic.html?definitionset=myfolder&trace=all

 

Possible values of the trace parameter are:

 

ALL

Displays both system trace messages and application trace messages.

SYS

Displays only system trace messages

APP

Displays only application trace messages

NO

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

 

http://lxsteam:8080/ts/skins/ts_basic.html?definitionset=myfolder&trace=no

 

 

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

Okay

 

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:

 

http://<aXes_Host>:<aXes_Port_Number>/ts/skins/ts_basic.html?definitionset=<Application_folder>&lang=<LL>

 

Replacing

<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