GuiXT offers two JavaScript interface options: the IE mode and the Chromium mode.
Recommendation:
Suggested steps:
We use Chromium mode for the following examples. Unless otherwise specified, the examples can also be used in IE mode.
For each package xxx of JavaScript functions, create an HTML file xxx.html with the following structure:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>GuiXT JavaScript functions, package xxx</title>
</head>
<body>
<script>
// JavaScript functions to be called from GuiXT scripts
function function1() {
}
function function2() {
}
// ...
</script>
</body>
</html>
As an example, we implement a JavaScript function that returns the current date in a format that includes the day of the week and month name. Our JavaScript package is called "jsutilities" and the name of the function is "dateTodayLong":
<!doctype html>
<html>
<head>
<title>Example functions for CallJS</title>
</head>
<body>
<script>
// return current date in given language
function dateTodayLong(language) {
// set default language
if (!language) language = 'en';
var d = Intl.DateTimeFormat(language, { dateStyle: 'full' });
return d.format(new Date());
};
</script>
</body>
</html>
CallJS mydate = jsutilities.dateTodayLong
Message "&V[mydate]"
CallJS mydate = jsutilities.dateTodayLong "ja"
Message "&V[mydate]"
Since GuiXT loads the HTML code only once per SAP GUI session, you can open a new SAP GUI session with /O to test changes in the JavaScript code. An easier option (only for Chromium mode) is to use the following ProcessingOption statement before the call:
ProcessingOption reloadJS="On"
Use the following ProcessingOption statement before the call to invoke the Chromium Debugger:
ProcessingOption debugJS="On"
CallJS mydate = jsutilities.dateTodayLong
Message "&V[mydate]"
CallJS mydate = jsutilities.dateTodayLong "ja"
Message "&V[mydate]"
The easiest way to start JavaScript debugging in IE mode is to use Visual Studio’s “Attach to Process†feature.
Select the process “saplogon.exe†and choose “Script Code†in the code type dropdown.
You now have two options to run your JavaScript function in the debugger. The simplest method is to activate:
Debugging -> Break all
in Visual Studio. Then execute your JavaScript function through the GuiXT script. The debugger will stop at the first executable line of the function.
Alternatively, you can insert the JavaScript 'debugger' statement at the point where you want execution to pause. WHen the debugger is active, you can:
Note:
If on your PC (common starting with Windows 11), you must enable script debugging directly in the Windows Registry:
HKEY_CURRENT_USER\Software\Microsoft\Internet Explorer\Main Disable Script Debugger="no"
When you add new parameters to a JavaScript function later, it can be inconvenient to update all existing code that calls this function.
To avoid this, you can define default values for new parameters. This means: if no value is provided when the function is called, the function will automatically use a predefined value.
You can do this by checking whether a parameter is undefined:
function split(s, delimiter){
// set default delimiter
if (typeof (delimiter) == 'undefined'){
delimiter = ";";
};
// split string ...
}
function split(s, delimiter = ";") {
// split string ...
}
Sometimes you want to call a JavaScript function with any number of arguments, without defining them explicitly in the function signature.
This can be done using the built-in 'arguments' object which contains all values passed to the function.
It behaves like an array (you can access items via arguments[0], arguments[1], etc.)
But it is not a real array, so methods like .map() or .join() cannot be used directly.
If needed, you can convert it into a real array first.
Example: The following function can be called with a variable number of strings. It returns the strings in the form of a list (x,y,...):
function buildList()
{
// array
var a = [];
// convert arguments list to array
for (var i = 0; i < arguments.length; ++i)
{
a.push(arguments[i]);
};
// return list via "join"
return "(" + a.join(",") + ")";
}
In Chromium mode, you can use the three-dot notation (...) within a function's parameter list, called 'rest' parameters.
Rest parameters allow a function to accept an indefinite number of arguments as an array. This makes it easy to handle functions where you don't know beforehand how many values will be passed.
Syntax: function myFunction(a, b, ...restOfArgs) { ... }.
Key Rules:
Example:
function buildList(...items) {
return "(" + items.join(",") + ")";
}
In addition to parameter transfer and value return, GuiXT offers a special interface for exchanging information with GuiXT.
The description of the "guixt" interface object can be found in
Object GuiXT in JavaScript
As an example, we set the user's login language as the default language value in our date output function.
// return current date in given language
function dateTodayLong(language) {
// guixt interface object
var guixt = window.guixthost;
// set SAP logon language as default language
if (!language) language = guixt.get("_language2").toLowerCase();
var d = Intl.DateTimeFormat(language, { dateStyle: 'full' });
return d.format(new Date());
};
In modern JavaScript, functions can be declared as asynchronous by using the async keyword before the function keyword. This is syntactically required whenever the function itself calls other asynchronous functions using await. When working with modern Web APIs, most example code you will find is based on asynchronous processing. Therefore, it is common to encounter async functions when integrating external JavaScript functionality into GuiXT. This section explains what happens when an async JavaScript function is called from GuiXT, what limitations exist, and which patterns can be used to synchronize asynchronous JavaScript execution with GuiXT script processing.
Calling an async JavaScript function from GuiXT using CallJS is completely legal. However, it is important to understand the execution model:async function api7() {
return 7;
};
Clear V[result]
CallJS result = mytests.api7
Message "Result: &V[result]"
async function api7() {
// set result
window.guixthost.set("result", 7);
};
Clear V[result]
Clear V[result]
CallJS mytests.api7
Message "Result: &V[result]"
async function api7() {
// wait 50 ms
await sleep(50);
// set result
window.guixthost.set("result", 7);
};
// sleep, time in milliseconds
function sleep(time) {
return new Promise((resolve) => setTimeout(resolve, time));
}
async function api7() {
// wait 50 ms
await sleep(50);
// set result
window.guixthost.set("result", 7);
// indicate: processing done
window.guixthost.set("js_done", "X");
};
// sleep, time in milliseconds
function sleep(time) {
return new Promise((resolve) => setTimeout(resolve, time));
}
Clear V[result]
Clear V[js_done]
CallJS mytests.api7
// wait for JS completion
label wait_for_api7
if not V[js_done]
ConnectHTML wait=1
goto wait_for_api7
endif
Message "Result: &V[result]"
This loop waits until the JavaScript code signals completion by setting V[js_done], and we obtain the correct result:.
Notes on ConnectHTML wait=1
The statement ConnectHTML wait=1
This makes it suitable for short polling loops in GuiXT.
To avoid an infinite loop if the called function never sets the indicator variable, you can use a counter and an appropriate upper limit:
Clear V[result]
Clear V[js_done]
CallJS mytests.api7
// wait for JS completion
Set V[k] 0
label wait_for_api7
if not V[js_done]
ConnectHTML wait=1
Set V[k] &V[k] + 1
if V[k<1000]
goto wait_for_api7
endif
// after a wait time of > 1 sec we terminate with an error message
Message "api7 did not respond in time, function terminated"
goto my_error_handling
endif
Message "Result: &V[result]"
Alternative approach: Callback into GuiXT
Another synchronization method avoids polling loops altogether. Instead, the JavaScript function explicitly calls a GuiXT script once processing is complete:
async function api7() {
// wait 50 sec
await sleep(50);
// process result
window.guixthost.process("show_result", 7);
};
CallJS mytests.api7
Parameter result
Message "Result: &V[result]"
Return
async function api7() {
// wait 50 ms
await sleep(50);
// produce exception
throw new Error("Web Server xyz not reached");
// set result
window.guixthost.set("result", 7);
// indicate: processing done
window.guixthost.set("js_done", "X");
};
Clear V[result]
Clear V[js_done]
Clear V[js_error]
CallJS mytests.api7_wrapper
// wait for JS completion
Set V[k] 0
label wait_for_api7
if not V[js_done]
ConnectHTML wait=1
Set V[k] &V[k] + 1
if V[k<1000]
goto wait_for_api7
endif
// after a wait time of > 1 sec we terminate with an error message
Set V[js_error] "api7 did not respond in time, function terminated"
endif
if V[js_error]
Message "&V[js_error]" _
title="Exception in JavaScript function 'api7' " type="E"
else
Message "Result: &V[result]"
endif
async function api7_wrapper() {
try {
await api7();
} catch (err) {
console.error("Exception in api7:", err);
window.guixthost.set("js_error", err.message);
}
// indicate: processing done
window.guixthost.set("js_done", "X");
};
async function api7() {
// wait 50 sec
await sleep(50);
throw new Error("Web Server xyz not reached");
// set result
window.guixthost.set("result", 7);
};
// sleep, time in milliseconds
function sleep(time) {
return new Promise((resolve) => setTimeout(resolve, time));
}
With guixt.process() you can call a GuiXT function from JavaScript. This is useful in the following situations:
- Calling GuiXT at the end of an 'async' JavaScript function in order to continue GuiXT processing
- Displaying a status message during long‑running JavaScript processing
- Reading data using an RFC call
In the example below, we demonstrate how to display a status message. We simulate a long‑running operation using a JavaScript sleep function.
CallJS jsutilities.webservicedemo
// process_statusmessage.txt
Parameter option
Parameter value ""
if V[option=remove]
StatusMessage -remove
Return
endif
if V[option=title]
StatusMessage title="&V[value]"
Return
endif
if V[option=addstring]
StatusMessage addString="&V[value]"
Return
endif
Return
// Calling a web service with status messages in GuiXT
async function webservicedemo() {
// guixt interface object
var guixt = window.guixthost;
guixt.process("statusmessage", "title", "Web Service active");
guixt.process("statusmessage", "addstring", "We start..");
await sleep(1000);
guixt.process("statusmessage", "addstring", "Sending data...");
await sleep(1000);
guixt.process("statusmessage", "addstring", "Receiving results...");
await sleep(1000);
guixt.process("statusmessage", "addstring", "Done");
await sleep(1000);
guixt.process("statusmessage", "remove");
};
// sleep, time in milliseconds
function sleep(time) {
return new Promise((resolve) => setTimeout(resolve, time));
}
The recommended method for processing GuiXT table and structure variables in JavaScript is to read them in with guixt.Get() and write them back with guixt.Set().
GuiXT automatically uses a JSON format for transfer, which can be conveniently used in JavaScript for conversion to and from JavaScript objects.
We will demonstrate the procedure using a small example in which we call a JavaScript routine to filter the rows of a table; in our case, we only select customers with the location "Vancouver":
// customer table
Table (1,1) (15,86) name="customers" fixedColumns=4
Column "Account" size=10 name="account"
Column "Name" size=30 name="name"
Column "City" size=20 name="city"
Column "Country" size=20 name="country"
// filter city Vancouver
PushButton (1,93) "Vancouver only" process="filter_customers.txt"
Using city = "Vancouver"
// filter_customers.txt
Parameter city
// pass the table name and the city to our JavaScript filter function
CallJS jsutilities.tabledemo "customers" "&U[city]"
Return
function tabledemo(ctabname, filtercity) {
// GuiXT interface object
var guixt = window.guixthost;
// read GuiXT table in JSON format
var ctabjson = guixt.Get(ctabname);
// transform it into a JavaScript object
var ctab = JSON.parse(ctabjson);
// filter the array by the given city name
var ctabnew = ctab.filter((customer) => customer.city == filtercity);
// set the new GuiXT table content
guixt.Set(ctabname, JSON.stringify(ctabnew));
}