Arrival Scripting and Inter-Screen Communication
All screens have an arrival function.
Typically the arrival script of a screen defines a single default behaviour.
Typical single default behaviours are:
- Junction screens – do nothing
- Special screens - send key(s) to make the screen disappear
- Destination screens – display the underlying 5250 screen
However, you will from time to time need to alter an arrival script in a junction, special or destination screen to make it support multiple different behaviours.
The most structured way of doing this is to first decide what behaviours you want your arrival script to support, and then to clearly define and document them at the start of you screen’s script like this example:
RequestedArrivalBehaviour : 0,
ArrivalBehaviours :
{
Default : 0, /* Default behaviour */
SearchNext : 1, /* Handle scroll up request */
SearchLast : 2, /* Handle scroll down request */
ForcedNavigation : 3, /* Handle a forced navigation */
AutoConfirmation : 4 /* Handle auto confirnmation */
},
This very formally defines that this screen can support 5 different arrival behaviours.
Note 1: You do not have to define the behaviours this way and can use different names. This is an example of formal way to do this. This approach has documentation and debugging advantages. See the end of this section form notes about using simpler approaches.
Note 2: These behaviours and their names are mythical examples. You can have as many behaviours as you like with any names.
Next, you actually need to change your screen’s arrival script to handle these multiple behaviours. Again this can be done in a structured way, like this example arrival script for a destination screen:
vHandle_ARRIVE: function(oPayload, oPreviousForm)
{
/* Extract a copy of the requested behaviour */
var RequestedBehaviour = this.RequestedArrivalBehaviour;
/* Reset the requested behaviour back to the default behaviour */
this.RequestedArrivalBehaviour = this.ArrivalBehaviours.Default;
/* Now preform the requested behaviour */
switch (RequestedBehaviour)
{
case this.ArrivalBehaviours.Default:
SHOW_CURRENT_FORM(true);
HIDE_5250_BUTTONS();
SETBUSY(false);
break;
case this.ArrivalBehaviours.SearchNext:
/* Logic to handle search next page behaviour*/
break;
case this.ArrivalBehaviours.SearchLast:
/* Logic to handle search last page behaviour*/
break;
case this.ArrivalBehaviours.ForcedNavigation:
/* Logic to handle a forced navigation, whatever that may be */
break;
case this.ArrivalBehaviours.AutoConfirmation:
/* Logic to handle a an auto confirmation, whatever that may be */
break;
default:
ALERT_MESSAGE(this.vName,"arrival script – invalid behaviour requested",RequestedBehaviour.toString());
}
/* <ARRIVE /> - Do not remove or alter this line */
return(true);
},
Okay, you have now formally defined the different arrival behaviours that your screen supports and the code required to implement them.
How are they used?
Well first, you might use them within the screen’s own script instead of using payloads.
Imagine a button click that requests a page search operation like this …
SENDKEY(KeyPageUp,"SEARCHNEXT");
Classically this sends the key stroke to the server and includes a payload so that the arrival script knows what to do with when the form arrives back again.
Note: If you have done this you probably already have an arrival script exhibiting at least two different behaviours.
Now you would code this instead:
this.RequestedArrivalBehaviour = this.ArrivalBehaviours.SearchNext;
SENDKEY(KeyPageUp);
Note: Why do this? It seems like more work. Well you have already gained one advantage. Say you coded SENDKEY(KeyPageUp,"SEARCHNET") accidentally using the payload technique. It would take you a while to debug your program to find that "SEARCHNET" is wrong and it should be "SEARCHNEXT". If you coded ArrivalBehaviours.SeachNet your script will fail when you execute it, telling you something is wrong instantly.
The second place you would use this is in other screens.
Say another screen (named "AnotherScreen") is going to set in motion a set of events that it knows will ultimately arrive at, or pass through, your multi-behavioural screen (named "MultiScreen").
Imagine that it also needs to make sure that "MultiScreen" performs the "auto confirmation" behaviour when it arrives.
"AnotherScreen" can contain this code:
var oMS = SCREEN("MultiScreen"); /* Get a reference to "MultiScreen" */
oMS.RequestedArrivalBehaviour = oMS.ArrivalBehaviours.AutoConfirmation;
<< Now execute code to start events that will go to/though "MultiScreen" >>
In other words, "AnotherScreen" is setting a property in "MultiScreen" (named RequestedArrivalBehaviour) that says "When you arrive, I want you to perform the auto confirmation behaviour, instead of the usual default behaviour".
Note the "MultiScreen" does not have to be a destination screen. It could equally be a junction of special screen. All it needs to be is a screen whose arrival script needs to be capable of performing different behaviours.
This technique demonstrates a very formal and structured way for screens to communicate intention between themselves. You do not need to be so formal or structured, nor to use the long names suggested.
You could simply declare this in "MultiScreen":
Action : 0, /* Declare the action code for arriving scripts */
And structure the arrival script like this:
Switch (Action)
Case : 0
Case : 1
Case : 2
Case : 3
Other code would use this.Action = 2 or SCREEN("MultiScreen").Action = 3
You could even use strings like this:
Action : "Default", /* Declare the action code for arriving scripts */
And structure the arrival script like this:
Switch (Action)
Case : "Default"
Case : "Up"
Case : "Down"
Case : "Jump"
Other code would do this.Action = "Up" or SCREEN("MultiScreen").Action = "Jump".
The declaration technique you use is immaterial and long it is structured and documented. The advantage of the formal declaration (enumeration) technique is simply that it is a very formal documentation of capabilities and that code will always fail if an incorrect value is used.