Working with sessions

Newlook must always have at least one session running. For this reason, each time Newlook* starts, a new session is automatically created and any 'startup' logic present in the solution is automatically executed. This session, which can be returned by the Sessions.StartupSession property, cannot be removed at runtime and remains running until Newlook is shutdown.

*Newlook, in this context, can mean Smartclient, the Smartframe Newlook control, the embedded Newlook control, or the Newlook Developer runtime client.

The Add method is used to create additional sessions at runtime. This method creates a new Session object in the Sessions collection.

Sessions created using this method do not execute 'startup' logic when they are initiated; instead, they execute whatever action is specified in the options argument of the Add method

Unlike the StartupSession, sessions created at runtime can be destroyed via the Remove method.

It is also possible to manually create sessions in the runtime client. This is useful if you need to quickly test multi-session logic. To do this, select the menu option Session | Add Session.

Enter a Name for your new session, and the startup action that you want to initiate when the session is created.

The options for Startup are:

• None - a new session will be created and is accessible in the Newlook DOM, but nothing else will happen. If the session is specified as the active session, the user will be presented with a blank screen.
• Connection - the session will connect to the specified connection when it is created. Select the desired connection from the drop-down list. Only connections defined in your solution are available.
• File - the specified .NL file will be opened when the session starts.
• Form - the specified Added Form will be opened when the session starts.
• Logic - the specified script or macro will be executed when the session starts.

The Make new session active option allows you to set the new session as the active session, which means it will visible in the client.

Any session that has been created using the Add method (or via the Session | Add Session menu), can be destroyed via the Remove method.

If you are testing your solution in the Runtime Client, it is also possible to manually remove the currently active session by selecting the menu option Session | Remove Active Session.

Removing a session using either method destroys all variables created within the session as well.

Note:

If the session you are destroying has an active connection, you will need to handle the sign off and disconnection process, if required, before removing the session.

Sessions.ActiveSession represents the session that is currently visible in the client. Use the SetActiveSession method to change the active session at runtime.

To manually switch active sessions in the runtime client, select the relevant session from the list in the Sessions menu. The current active session will be displayed with a tick next to it.

TIP:

Another way of returning the name of the current active session, is to configure your title bar to include the session name. You can do this by adding the &s parameter to the Caption Title in General Rules.

The Session object is itself a collection. Each session has its own instance of the App, Clipboard, Http, Sessions and System objects, plus any Newlook variables that were created in that session.

The App object is relative to the currently executing session. This is the session in which the current script/macro/expression was invoked, and can be returned via the ThisSession Property (App.ActiveForm is the equivalent of ThisSession.App.ActiveForm). If you are referencing an object or variable that belongs to a different session, you will need to explicitly reference the session by adding the prefix Sessions.(SessionName). If you are referencing an object or variable that exists within the executing session, you do not need this prefix.

Session.ThisSession versus Sessions.ActiveSession

Sessions.ActiveSession returns the currently visible session. It should not be confused with ThisSession, which returns the currently executing session (the one in which the current script/macro/expression was invoked). This is important to note, because while these two properties will often return the same session, there will be times when they are different. One of those times is immediately after you have changed the active session in a script. Calling Sessions.SetActiveSession does not change the value of 'App' or 'ThisSession' (within the context of any script or macro). If you wish to change the active session and then execute logic in that session, you will need to invoke the logic from an event that is triggered in the active session. The other scenario where these properties would return different sessions is one where you are executing logic from a session that is running in the background. In other words 'Sessions.ThisSession' is not the currently visible session.

The following examples show how scripts and macros are scoped to different sessions, and how to access Newlook variables from other sessions:

• Newlook session variable scope - By default, Newlook variables created in a session are scoped to that session and exist until it is destroyed. If you need to create a variable which will persist regardless of which sessions are created and removed, create it in the startup session (which always exists).
• Dialog visibility - Dialogs, like runtime errors or message boxes, will appear in the visible session regardless of what session they relate to. This is to ensure that when dialogs are generated in a session that is not currently visible, users are aware of their presence and can provide some input in order to progress. In the case of runtime error dialogs, from version 11.1 onwards, the dialog contains information to indicate the session that the error was generated in.

• Startup session status - The startup session cannot be removed at runtime, only sessions that are explicitly added can be removed.
• Top level App object does not refresh - The top level App object in Inspector is relative to the session that was active (visible) at the time Inspector was opened. It does not update when the active session changes. This is a known limitation. One way of updating the display when you switch sessions is to close and re-open Inspector. It is worth noting that this is slightly different to the way the App object is resolved in Scripts, where it is relative to the currently executing session. See Communicating between sessions section above. For solutions running in only one session, the Sessions collection in Inspector can be completely ignored and you can refer to the top level App object in exactly the same way as in previous versions.

Hidden session

One possible use of Newlook's multi-session feature is to create a hidden 'Helper' session. This is a session that is created on startup, and can sit ready in the background until you need it. You can use this session to navigate and obtain information from other screens in your application.

In a scenario like this, the code that creates the Helper session could be added to the startup macro or script:

The 'HelperStartup' script (called by the Add method above) connects the Helper session to the host. Because the script has been invoked by the Helper session, there is no need to prefix the App.Connect method with 'Sessions.Helper'. The Connect method call includes a call-back function, which can be used to provide a verification that the hidden session has connected:

From this point onwards, the helper session is available in the background and can be used to perform various actions. In the example below, the 'GetCustomerName' transaction is played in the Helper session to navigate to a specific screen and retrieve a value. That value will be used to populate a control on the active session's current screen.