Tutorial 6

The USERENV object

What is the USRENV object? 

 

The aXes ENV (Environment) object contains common properties and functions that you use in your eXtension scripting.  

 

The USERENV (User Environment) object is a JavaScript object. It extends the concept of the ENV object by acting as a container for properties and functions that are uniquely part of your project.

What is USRENV used for? 

USERENV's main uses are:

  • Allows definition and change of common values in just one place.
  • Define common logic to encourage reuse and minimize coding.
  • As a session persistent container of eXtension state values.
  • As a way of exchanging information between eXtension scripts.
  • As a way of signalling custom events between eXtension scripts.

How and where is it defined? 

The USERENV object is defined in the userenv.js file.

The userenv.js file resides in your definition set / project folder.

 

Open the Projects Home Page. Select your project and then use the Edit USERENV Object option. The resulting NOTEPAD display should look something like this:

 

 

 

The warning is very important.

 

When customizing this file, make sure you keep versions to avoid loss of your work when upgrading aXes or if you need to re-install.

 

Looking at the userenv.js file content you will see this non-comment JavaScript:

 

var USERENV =

{

 

   /* ------------------------------------------------ */

   /* Properties defined as part of the USERENV object */ 

   /* ------------------------------------------------ */

 

   staticTablesFile    : "tables_static.txt",  /* Default name for file …

   dynamicTablesFile   : "tables_dynamic.txt", /* Default name for file …

  

This code declares a JavaScript object called USERENV. 

It contains properties named staticTablesFile and dynamicTablesFile.

 

This means that you can refer to USERENV.staticTablesFile and USERENV.dynamicTablesFile anywhere in JavaScript code that you add to an eXtension. 

Adding a property to the USERENV object 

Try adding two properties of your own to USERENV.

 

Open the Projects Home Page. Select your project and then use the Edit USERENV Object option to open file userenv.js in your project folder in NOTEPAD.

 

Add the two highlighted property declarations to

 

var USERENV =

{

   /* ------------------------------------------------ */

   /* Properties defined as part of the USERENV object */ 

   /* ------------------------------------------------ */

 

   companyName : "My Test Company",

   messageLine : 22,

 

  

   staticTablesFile    :  …… etc, etc

 

Now save the updated userenv.js file.

 

In one of the extensions you created in a preceding tutorial, add code that does this:

 

    alert(USERENV.companyName);

    alert(USERENV.messageLine.toString());

    USERENV.messageLine = USERENV.messageLine + 27;

    alert(USERENV.messageLine.toString());

  

By causing the code to execute in your eXtension you should be able to see that these new properties that you have created can be read from and written to the USERENV object.

 

Hint: If you change userenv.js, you need to stop and restart your aXes 5250 session to pick up the new version. Userenv.js is read just once as the 5250 session is initialized.

Adding a function to the USERENV object 

Now, add a new function to the USERENV object.

 

Open the Projects Home Page. Select your project and then use the Edit USERENV Object option to open file userenv.js in your project folder.

 

In the body of the USERENV object declare function addNumbers like this:

 

   addNumbers : function(a,b,c)

   {

      var result = a + b + c;

      return(result); 

   }, /* ç Note the comma */

 

Now save the updated userenv.js file. In one of the extensions you created in a preceding tutorial, add scripting code that does this:

   

var x = USERENV.addNumbers(4,5,6);   

alert("Result = " + x.toString());

 

By causing the code to execute in your eXtension you should be able to see that this new function can be used anywhere by eXtension logic.

Extending and Organizing the USERENV namespace 

The style of JavaScript coding used to define the USERENV object is primarily used to reserve the USERENV namespace.

 

This means you can confidently create a new USERENV function called myNewFunction() knowing that there will be no such function already in the aXes namespace, nor will there ever be one in the future - because it will be called USERENV.myNewFunction(). 

 

You can extend this approach to subdivide the USERENV name space itself.

 

For example, if this code is added right at the end of the userenv.js file (after the closure of the USERENV object definition):

 

USERENV.Print =

{

   testProperty1 : "Hello",

   testProperty2 :  300,  

 

   test : function(a)

   {

   } /* ç Note no comma as this is the last member of USERENV.Print */

};

 

Now the object and namespace USERENV.Print has been created, presumably to contain things related to printing.

 

You can now reference properties USERENV.Print.testProperty1 or USERENV.Print.testProperty2 and function USERENV.Print.test() in any eXtension scripting.

 

Hint: You can actually imbed the USERENV.Print object declaration inside the USERENV base definition, but sometimes the syntax gets a bit cryptic and hard to follow. 

 

Using a common USERENV and SHARED object (RAMP-TS) 

If you are using the RAMP-TS product from LANSA, you may know that its scripting support contains a SHARED object namespace. Its intended purpose is virtually identical to the USERENV namespace.

 

In RAMP-TS applications you can share a single common object by executing this code: 

 

var SHARED = { };

 

in the RAMP-TS UF_SY420_RTS.js file.

This declares the SHARED object as an empty object.

 

Then in your RAMP-TS logon script, execute the JavaScript code:

 

SHARED = USERENV;

 

making the RAMP-TS SHARED object and the eXtensions USERENV object one and the same thing.