In this first part of modernization series we will introduce you to the first step - mapping the screens.
Whole process is based on few steps:
- screen mapping
- screen extract
- merge data and web template
- show generated HTML inside browser
- convert user action to terminal action (data submit or PFnn operations etc.)
Definition Location
All definitions are saved inside server configuration directory under folder etl and its corresponding subfolders.
Base location is [USER]/io.greenscreens/etl.
That location contains first configuration element definition.json. It is used as a root definition to define which mapping rules will be used.
For example, we can define default mapping rules for screen, spool or etl data extract. Later we can define custom rules for different environment based on UUID/host. This was required to support multiple different machines and their environments.
Whenever workstation operator opens web terminal with specific uuid/host enabled for modernization, root file (definition.json) will be loaded first. Modernization engine will detect which mapping definition to use.
{
"description": "",
"timestamp": 0,
"version": 0,
"type" : "root",
"default": {
"screen": "screen/definition.json",
"etl": "etl/definition.json",
"spool": "spool/definition.json"
},
"0": {
"webui": {
"screen": "screen/definition.json"
},
"auto": {
"screen": "screen/auto/detect.json"
},
"test": {
"screen": "screen/processing/detect.json"
}
}
}
In example shown above, whenever we open UUID:0 and HOST: AUTO, automatic detection engine will start. That definition will try t odetect type of screen and create web UI accordingly.
If we connect as UUID:0 and HOST: TEST, another engine will start which does not show UI but extracts data and send data to console. In real case scenario nthis can be ued t osend screen data to some server to save it into database.
Definition structure
Screen mapping is a way to define rules that will match for specific screen. Matching rule will contain link to extraction definition used to extract relevant data from screen into JSON object which will be used to populate HTML template.
Here is basic screen mapping definition:
{
"description": "",
"timestamp": 0,
"version": 0,
"type" : "detect",
"root": "screen/root.json",
"items": [
{
"fieldHash": "50E5078D23FA0AAD9CDDF74957B224F3E5740D95",
"attrHash": "50E5078D23FA0AAD9CDDF74957B224F3E5740D95",
"file": "screen/defs/blank.json"
},
{
"row": 0,
"col": 26,
"len": 27,
"hash" : 347536357,
"file" : "screen/defs/demo.json"
},
{
"row": 0,
"col": 35,
"text": "Sign On",
"rule": "exist",
"file": "screen/defs/signon.json"
},
{
"query": {
"main": "main0 || main1 || main2 || main3 || main4"
},
"segments": {
"main0": {
"row": 2,
"col": 1,
"text": "Select one of the following",
"rule": "exist"
},
"main1": {
"row": 4,
"col": 1,
"text": "Select one of the following",
"rule": "exist"
},
"main2": {
"row": 0,
"col": 32,
"text": "OS/400 Main Menu"
},
"main3": {
"row": 0,
"col": 32,
"text": "IBM i Main Menu "
},
"main4": {
"row": 0,
"col": 1,
"text": "LIMENU"
}
},
"detect": "main",
"file": "screen/defs/main.json"
},
{
"row": 0,
"col": 29,
"text": "Work with Active Jobs",
"file": "screen/defs/wrkactjob.json"
},
{
"row": 0,
"col": 29,
"text": "Work with Output Queue",
"file": "screen/defs/wrkoutq.json",
"rule": "exist"
}
]
}
Shown example maps first few IBM I system screens as singon screen, main menu, wrkactjob and wrkoutq screens showing all three available definition formats.
Definition formats
Definition formats are available formats for screen data recognition.
- screen hash based - use screen calculated hashes for field and color attributes map
- text ahsh based - use calulated text hash from row/col/len
- simple - use row / col position and text value to detect specific screen
- complex - use multiple "simple" rules as a query matching statement
What is unique to all definition formats is "file" attribute with virtual link to screen extraction definition which we will describe in part 2 of this tutorial.
TIP: Use Tn5250.Application.getConfig() which contains screen hashes.
Defining screen mappings
The most common approach is to use cursor position on terminal screen and extract text data from given position creating matching rule.
Here is sample mapping for sing on screen telling that at row 0 and col 35 "Sign On" value must exist. Add that rule to items list on mapping definition JSON shown above.
{
"row": 0,
"col": 35,
"text": "Sign On",
"rule": "exist",
"file": "screen/defs/signon.json"
}
Or use newer more prefered approach with text hashing
{
"row": 0,
"col": 35,
"hash": 451345234,
"file": "screen/defs/signon.json"
}
Root file
Root file is a link to root template definition used to load UI interface page containing all required resources.
Just as root definition.json file, and here we can define different UI templates based on UUID/host, browser type, environment type etc. For example, for production environment we could have template with one CSS design and for test environment another CSS design so when workstation operator connects to different server he will see different color scheme. Also, we can use this to load different UI frameworks.
The most common use is definition of different engines used for mobile and browser environment as shown in example below.
{
"description": "",
"timestamp": 0,
"version": 0,
"type" : "screen",
"templates": {
"default": {
"html" : "screen/web/default.html"
},
"os": {
"android": {
"html": "screen/mobile/default_dbg.html"
}
}
}
}
When modernization is on, one of matched html templates will be loaded initially into UI frame and shown over terminal screen. Next step for engine is to detect currently opened screen and if there is a mapping definition and template match, engine will render and injecte screen UI into loaded html page. If screen does not contain mapping, engine will hide UI layer and show web terminal.
Summary
Here we learned based location where all JSON and web template definitions exist. We learned about 2 main JSON definitions. Root definition that tells which mapping definition to load based on UUID/host and screen mapping definition format which tells modernization engine how to identify specific screen.
In next chapter we will show how to map screen data so that modernization engine can convert screen into JSON format which will be used to generate HTML page out of our screen.