Enterprise Manager Java App: Session Pinning

In BBj 13.0 and higher, the Enterprise Manager Java app has been superseded by a new browser Enterprise Manager and Eclipse plug-in. See Enterprise Manager - BBj Services: Settings.

Overview

In BBj 6.0 and higher, session pinning provides a new level of reliability and predictability within BBj interpreter sessions. Session pinning allows the BBj developer to modify files within a single session and remain unaffected by modifications made outside of that session.

Session pinning provides a more predictable alternative to the existing notion of pinning, referred to as "server-wide pinning" and available in BBj 5.0 and higher. With server-wide pinning enabled, programs will remain in the program cache most of the time. However, when memory use begins to increase, there is a greater likelihood that BBjServices will release a less frequently used program from the cache. One portion of an application may reside in memory and the other on disk. If an administrator or developer changes or replaces related files from both an on-disk portion and an in-memory portion of an application, inconsistencies may appear at runtime.

Consider a case where a developer modifies a CALL and ENTER statement to take a different number of parameters. Even assuming both the program that contains the CALL and the program containing the ENTER reflect the same number of parameters, the cache may have released its reference to one of the programs while maintaining its reference to the other. If a running instance of the program executes an old version of the program still in memory when processing the CALL statement, but executes the new version of the program that contains the ENTER statement, an error will occur in that instance of the program.

When the user has enabled session pinning, BBj ensures that once it loads a version of a program in a given session through the LOAD, CALL, or RUN verbs, that session will continue to refer to that version until the application explicitly unpins it or performs a SAVE. The next time BBj loads that program, it will retrieve the version that exists on the disk.

Using Custom Objects can often produce program files that depend upon each other's structure more frequently than in traditional BBx programming models. Each instance of a Custom Object depends on the program file that contains the class definition. An unintentional or inconsistent change to a Custom Object program file at runtime could potentially have undesirable side effects if a running interpreter session uses an instance of a Custom Object while the program file containing its class definition is in an inconsistent state.

With Custom Objects, where every method call acts much like a CALL/ENTER pair, these kinds of dependencies may become much more common. BASIS' introduction of session pinning reduces the likelihood of errors due to modifying method argument lists and CALL/ENTER pairs at run time by isolating the modifications a session knows about to modifications within that session. Session pinning also enables future optimizations with Custom Objects to increase the speed of code that uses them.

Usage

It is possible to enable and disable session pinning in a running interpreter session by using either the STBL() function or the setOptionSetting() method of BBjConfig.

To view the current setting via STBL():

value$ = STBL("!OPTIONS", "SESSION_PINNING")

The value$ will be either "TRUE" or "FALSE".

To enable via STBL():

dummy$ = STBL("!OPTIONS", "SESSION_PINNING=TRUE") dummy$ = STBL("!OPTIONS", "SESSION_PINNING=FALSE")

To enable via BBjAPI:

myApi! = BBjAPI() myConfig! = myApi!.getConfig() myConfig!.setOptionSetting("SESSION_PINNING", 1) myConfig!.setOptionSetting("SESSION_PINNING", 0)

Necessarily, this is set on a per-interpreter basis. However, the developer may enable the !OPTIONS STBL string from the config.bbx file as follows:

!OPTIONS="SESSION_PINNING=TRUE"

Note: This will not affect any of the other !OPTIONS settings.

BASIS also provides a way to set the default value of this through the Performance node in the Enterprise Manager. Marking the checkbox labeled Pin by BBj Session enables session pinning for all subsequent BBj sessions by default. Disable individual sessions using the config.bbx !OPTIONS variable, STBL(), or the BBjConfig.setOptionSetting() method.

 

Because developers may desire to obtain changes from disk, session pinning can also explicitly reload programs that have pinned in a session. For example:

myApi! = BBjAPI() myConfig! = myApi!.getConfig() myConfig!.unpinSession()

To reload a specific program or resource:

myApi! = BBjAPI() myConfig! = myApi!.getConfig() program$ = PGM(-1) myConfig!.unpinSessionEntity(program$)

In reviewing the API, the existing method BBjAdminEnvironment.unpinAllPrograms() does not correctly describe its action and is now deprecated. Use the replacement method BBjAdminEnvironment.unpinServer() to perform this task. BASIS recommends updating all code to use this new method for clarity.

Additional Notes

• The [Unpin Programs] button in Enterprise Manager does not unpin session pinned programs; it only affects programs pinned server-wide.

• Changes to a program file or resource file on disk will not load into an interpreter session without executing either unpinSession() or unpinSessionEntity().

• ADDR supersedes session pinning. Session pinning effectively performs an ADDR on all programs, but avoids reserving memory in BBjServices unless an interpreter is actively using the program.

• Setting Pin Programs and Resources to Production does not affect BBj sessions with session pinning enabled. However, if an application disables session pinning while running, a subsequent load request will respect the server-wide setting.