ECN-4662 New atw-script control for use with AcuToWeb

Product: ACUCOBOL-GT

Module: Compiler, Runtime

Machines Affected: All

DESCRIPTION:

The new atw-script control, for use with AcuToWeb, enables scripting in the browser used as the user interface for your application.

ATW-SCRIPT is a hidden screen control that can execute Javascript code and can be controlled by the COBOL program just like other screen controls. You can establish links to:

Common Properties

Because ATW-SCRIPT is a hidden control, meaning it is not visible in the user interface, it has no common properties.

Special Properties

You can include the atw-script control in the COBOL program Screen Section, or by using Display syntax in the Procedure Division. This control ignores all common properties, such as position, visible, title, etc. The control is not visible, meaning it has no position, and the user cannot interact with the control directly.

The COBOL program can Modify the control to execute browser supported scripting such as JavaScript. This control has six special properties, two of which can be inquired. The control has an event, NTF-ATW-EVENT. There is a new AcuToWeb Gateway configuration "path_resources", this variable is used to indicate the path used for return all css and js file requested from COBOL code.

For the syntax below, js1 is defined as the handle for the atw-script control. EVALUATE takes a single string. That script is executed on the browser immediately. For example:

           move  "document.getElementById(""demo"").innerHTML = ""Paragr
      -          "aph changed."";" to js_str
           modify js1 evaluate(js_str)

ADD takes two strings - an identifier and a script. This associates the script with that identifier, in order to reference that script later. The script is not immediately executed. For example:

           move "function myFunction() {document.getElementById(""demo""
      -         ").innerHTML = ""Paragraph changed.""; }" to js_str
           modify js1 add("this-is-my-id", js_str)
modify js1 add("chartsJS", "[SRC]:https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.3/Chart.js") giving addJSCharts

The prefix [SRC]: means that the client browser looks for resources. In this case, it describes that the content is a URL and the content is not JavaScript.

modify js1 add("myscript", "[SRC]:/resources/js/myscript.js") giving addJSVal

In this case, the file requested is a local file in web folder – the gateway web folder. The resources matches with the PATH defined in path_resources, which is configurable in gateway.conf.

Notes:

When you use ADD to add a custom function, you must consider the name translation. For example:
```
modify js1 add("myfunc", "function f1(msg){ alert(msg); }") giving addJSVal
```
While this is formally correct syntax, due to the architecture of atw-script, the function f1 won't be reachable from any further CALL statement. The correct format for an inline function, which is a function that is not defined into a script added with the [SRC] sintax, is:
```
modify js1 add("myfunc", "f1:function (msg){ alert(msg); }") giving addJSVal
```
Then, call the function as follows:
```
modify js1 call("myfunc.f1(""hello world"")") giving addJSVal
```
The giving value is important because return provides the number identified by ATW-SCRIPT-EVENT in DATA-EVENT-2 when DATA-EVENT-1 is equal to 1.

VARIABLE can be used to get or set variables in the script. Modify this property to set a variable, and inquire this property to get the value of the variable. For example:

           move "var price1; var price2; var total; function myFunction(
      -         ") { total = price1 + price2; }" to js_str
           modify js1 add("another-id", js_str)
           modify js1 variable("price1", num1)
           modify js1 variable("price2", num2)
           modify js1 call("myFunction()")
           inquire js1 variable("total") in result

CALL takes at least one string – the name of the function to call. If that function takes parameters, you can include them as part of the string you create to modify the CALL parameter. Alternatively, you can specify multiple strings. The extra strings are the parameters passed to the function. For example:

           move "function myFunction(name,job) {document.getElementById(
      -         """demo"").innerHTML = ""Welcome "" + name + "", the ""
      -         "+ job + ""."";}" to js_str
           modify js1 add("this-is-my-id", js_str)
           modify js1 call("myFunction('Harry Potter','Wizard')")
           move "Harry Potter" to par1
           move "Wizard" to par2
           modify js1 call("myFunction()", par1, par2)

Alternative ways to use the CALL property:

       Move 1 to var1
       Move 2 to var2
       Move “test” to var3

       Modify js1 call(“myFunction(1, 2, “”test””);”).

Or:

       Modify js1 call(“myFunction()”, var1, var2, var3).

NTF-ATW-EVENT

NTF-ATW-EVENT this event will trigger when there is an event that has been received by the JS, when the JS has been injected via the ATW-SCRIPT. Note that only the code that has been inserted via ATW-SCRIPT will eventually trigger this event.

	EVALUATE EVENT-TYPE
           WHEN NTF-ATW-EVENT
             EVALUATE event-data-1
               WHEN 1
                     modify js1 CALL("googleMaps")
                     modify js1 add("script2",
                            "[SRC]:/js/myscript2.js")

LAST-ERROR

LAST-ERROR can be inquired and contains the last error the Javasctipt engine returned. There could be many errors as these depends on what your JS code does. Normally these errors goes into the JS console of the browser, but this property provide a means to COBOL program to be aware of such error message. The AcuToWeb will queue all the error messages that originate from the code injected by AcuToWeb into a FIFO list and will delete the message once COBOL inquires this property.

 inquire js1 last-error value in valuefromJS

LAST-RESULT

LAST-RESULT can be inquired to get any character result from the last script called, and is available when an EVALUATE returns a positive value.

REMOVE

REMOVE takes a single string, which is an identifier used with the ADD property. This removes that script from the browser, so it can no longer be referenced. For example:

 modify js1 remove ("this-is-my-id")

Events

NTF-ATW-EVENT is triggered when an event is received by the JavaScript, when the JavaScript has been injected via the ATW-SCRIPT.

                EVALUATE EVENT-TYPE
           WHEN NTF-ATW-EVENT
             EVALUATE event-data-1
               WHEN 1
                     modify js1 CALL("googleMaps")
                     modify js1 add("script2",
                            "[SRC]:/js/myscript2.js")LAST-ERROR

Note: The only event triggered by AcuToWeb occurs when the ADDed script has finished loading.

If you want to notify to the COBOL program of any other event, you can use the CustomJSHelper.event helper in your JavaScript code as follows:

getData: function(_url) {    $.ajax({url:_url}).then( function(data)
        { getDataObj.dataReturn = JSON.stringify(data);
        CustomJSHelper.event("getDataObj", CustomJSHelper.DATA_LOADED, 1);     }); 
        },getReturn: function(){ return getDataObj.dataReturn; }

Values for EVENT-DATA-1 can be:

`ATW_SCRIPT_LOADED = 1`	Script loaded
`ATW_SCRIPT_CUSTOM_EVENT = 2`	Custom event; the JavaScript developer can generate a custom event from JavaScript to COBOL
`ATW_JSON_DATA_LOADED = 3`	JSON is loaded; the JavaScript developer can use it when the ajax function returns a value from the webservice call
`ATW_JSON_ERROR_DATA_LOADED = 4`	JSON is error loaded; the JavaScript developer can use it when the ajax function returns an error from the webservice call

When the value of EVENT-DATA-1 is CUSTOM_EVENT or DATA_LOADED or ERROR_DATA_LOADED

EVENT-DATA-2 is a number, defined by the JavaScript developer, that identifies the number of AJAX operations contained in the JavaScript code.