Javascript Engine

Latest revision as of 14:25, 8 December 2022

Javascript static Engine object.
This object is frozen.

[edit] Methods

• output([value1 [, value2 [, ...]]])

Output data to console / log.
Concatenate parameters. Put a space between them.
Does nothing if the resulting string is empty.

Engine.output("1",1,"test");
Engine.output("1" + " " + 1 + " test");
// Output: "1 1 test"

• debug([level, ][value1 [, value2 [, ...]]])

Put a debug message in console / log.
Concatenate values. Put a space between them.
Does nothing if the resulting string is empty.
Debug level is handled if the first parameter is an integer value. Defaults to Engine.DebugNote otherwise.

// The following calls will produce the same debug message:
Engine.debug(Engine.DebugNote,"test","out");
Engine.debug(8,"test out");
Engine.debug("test" + " out");

• alarm([info, ]level, value1 [, value2 [, ...]])

Put a debug message. Emits an alarm if a callback is installed.
Concatenate values. Put a space between them.
Does nothing if the resulting string is empty.
Parameters:
info: Optional alarm extra information
level: Debug/Alarm level

Engine.alarm("myscript",Engine.DebugWarn,"Some warning");
// Run time error:
Engine.alarm("some text");
Engine.alarm("myscript",Engine.DebugWarn);
// No alarm, no debug message:
Engine.alarm("myscript",Engine.DebugWarn,"");

• sleep(seconds)

Sleep for a number of seconds.

• usleep(microseconds)

Sleep for a number of microseconds.

• yield()

Give up the currently running timeslice. Note that on some platforms it also sleeps for the operating system's scheduler resolution.

• idle()

Sleep for a system dependent period adequate for an idle thread.
On most operating systems this is a 5 msec sleep.

• restart([code [,gracefull]])

Stop and restart the engine and the entire program.
Parameters:
code: Optional return code of the program. Defaults to 0
gracefull: Optional. Attempt to wait until no plugin is busy
Return:
TRUE if restart was initiated, FALSE if exiting or no supervisor or 'allow_abort' is disabled in javascript.conf.

• dump_r([what])
• print_r([what])

Dump (recursive) current context or specified item methods and properties.
dump_r: Dump to string
print_r: Dump to output
Parameters:
what: Optional item (variable) to dump. Dump current context if missing
Return:
dump_r returns the string containing dumped data.

• dump_var_r(what[,flags])
• print_var_r(what[,flags])

Dump (recursive) specified item methods and/or properties.
dump_var_r: Dump to string
print_var_r: Dump to output
Parameters:
what: Variable to dump
flags: Configure dump contents
May be an ORed combination of the following values:
Engine.DumpProp: Dump object properties
Engine.DumpFunc: Dump object functions
Engine.DumpRecursive: Dump contained objects also
Engine.DumpType: Dump type (applies to functions also)
Engine.DumpProto: Dump object prototype
Engine.DumpPropObjType: Dump non basic type if the following conditions are met: Engine.DumpProp flag is set, Engine.DumpFunc is not set, Engine.DumpType is not set
Predefined combinations:
Engine.DumpPropOnly: Engine.DumpRecursive | Engine.DumpPropObjType | Engine.DumpProp
Engine.DumpFuncOnly: Engine.DumpRecursive | Engine.DumpProto | Engine.DumpFunc
Defaults to Engine.DumpPropOnly
Return:
dump_var_r returns the string containing dumped data.

• dump_root_r([flags])
• print_root_r([flags])

Same as dump_var_r / print_var_r. obj is the script context

• dump_t(table[,hdrpMap[,params]])
• print_t(table[,hdrpMap[,params]])

Dump table to string or output.
The table may be an array of objects or an object containing arrays.
Array:
- Array of objects: each entry describe a new row. Object fields are column names.
- Array of arrays: Each entry describe a new row. First array contains column names.
Object: Each array field describe a column. Field name is the column name.
Parameters:
table: Table to dump
hdrMap: Header name mapping. Object with prop[header name in table]=value[new header display name]. Fields will be re-arranged as found in header mapping. New header display name may be empty if the list is only used to re-arrange fields
params: Dump parameters parameters

• force_empty: Boolean (default: false). Dump table with empty contents (no rows). Ignored if there are no header names
• all_headers: Boolean (default: false). Add the rest of the headers not found in 'hdrMap'. Ignored if 'hdrpMap' is not given

Return:
dump_t returns the string containing dumped data.

a = [{name1:"val11", name2:"val12"}, {name1:"val21", name3:"val23"}];
a2 = [["name1","name2","name3"], ["val11","val12" ],["val21",undefined,"val23"]];
o = {name1:["val11","val21"], name2:["val12"], name3:[null,"val23"]};
Engine.print_t(a);
Engine.print_t(a2);
Engine.print_t(o);
// Same output:
// name1 name2 name3
// ----- ----- -----
// val11 val12
// val21       val23

• debugName([name])

Set the debug name.
Retrieve debug name if no parameter is given.
Parameters:
name: Debug name to set

• debugLevel([level])

Set the debug level.
Retrieve the debug level if no parameter is given.
Parameters:
level: Debug level to set. Ignored if not an integer value

• debugEnabled([on])

Toggle (set) the debug enabled flag.
Retrieve the debug enabled flag if no parameter is given.
Parameters:
on: TRUE to enable debug output, FALSE to disable it

• debugAt(level)

Check if the current debug level of the module/script is greater or equal to requested level.
Parameters:
level: Integer value to check
Return:
TRUE if the current debug level greater than or equal to level, FALSE otherwise.

• setDebug(command)

Set debug according to command values.
Handled commands:
- level <level_value>: Set debug level to requested level value
- reset: Reset debug level to javascript module debug level
- engine: Reset debug level and debug enabled flag to yate engine settings
- boolean: Set debug enabled flag
All other values are ignored.

• started()

Check if engine is started at the time this method is called (engine.start message was sent).
Return:
TRUE if engine was started (all modules were loaded and initialized), FALSE if not.

• runParams([param])

Retrieve engine list of parameters specific to this run or a specified one.
Parameters:
param: Optional name of parameter to retrieve
Return:
Object with fields set to engine parameters or string with requested parameter value.

• configFile(name [,user])

Retrieve the full path of a configuration file. Add the '.conf' extension to name.
Parameters:
name: Configuration file name
user: Optional. Set it to TRUE to build the path from user settings
Return:
Path to requested file.

• setInterval(callback, milliseconds)
• setTimeout(callback, milliseconds)

Install a timer event. Request 'callback' function call on given interval.
setInterval: Repeat function call on requested interval.
setTimeout: Remove timer after first call.
Parameters:
callback: Function to call
milliseconds: Timer interval in milliseconds
Return:
Timer id.

• clearInterval(id)
• clearTimeout(id)

Remove requested timer.
Parameters:
id: Timer id to remove
Return:
TRUE on success, FALSE if not found.

• loadLibrary(name [,name1 ...])
• loadObject(name [,name1 ...])

Load an object (loadObject) or a set of objects (loadLibrary) into script context.
These methods can be used to load custom C++ objects exposed to javascript.
An example of such module can be found in modules/test/jsext.cpp.
Parameters:
name: Library of object name(s). Single name or comma separated list
Return:
TRUE on success, FALSE on failure (library/object) not given or not found.

// The following load objects defined in jsext module:
loadLibrary("jsext");
loadObject("ExtObj");
// Unsafe to check return value:
ok = loadLibrary("lib1","lib2","lib3");
if (!ok) {
    // Unsafe: the list may be partially loaded. e.g. lib1 and lib3 loaded but not lib2
}

• replaceParams(buf, params [,sqlEscape [,extraEsc]])

Replace ${paramname} instances in 'buf' string from 'params' field values.
Parameters:
buf: String containing the replacements
params: Object whose fields are used to replace
sqlEscape: Optional. True to apply SQL escaping to parameter values
extraEsc: Character to escape other than the SQL default ones
Return:
String with replacements done. 'buf' if 'params' is an invalid object.

 params = {a:"first", b:"second", c:"not found"};
 s = "Test a=${a} empty=${missing} b=${b}";
 repl = Engine.replaceParams(s,params);
 // repl: "Test a=first empty= b=second"

• atob

Decode Base64 data.
Parameters:
b64_str: Mandatory, Base64 encoded data
Return:
Decoded data, boolean false on failure (invalid Base64 data)

str = Engine.atob(b64_str)

• btoa

Encode string data to Base64.
Parameters:
str: Mandatory, data to encode
line_len: Optional line length (split encoded data, add end of line after each line_len chars)
add_eol: Optional, add an extra end of line after encoded data
Return:
Base64 encoded data

b64_str = Engine.btoa(str[,line_len[,add_eol]])

• atoh

Decode Base64 data.
Parameters:
b64_str: Mandatory, Base64 encoded data
hex_sep: Optional separator to use between octets. Set it to 'undefined' if not used and hex_upcase is given
hex_upcase: Optional, use upper case characters in hexa
Return:
Hexified string, boolean false on failure (invalid Base64 data)

hex_str = Engine.atoh(b64_str[,hex_sep[,hex_upcase]])

• htoa

Encode hexified binary (string) data to Base64.
Parameters:
hex_str: Mandatory, data to encode
line_len: Optional line length (split encoded data, add end of line after each line_len chars)
add_eol: Optional, add an extra end of line after encoded data
Return:
The string, boolean false on failure (invalid input string).

b64_str = Engine.htob(hex_str[,line_len[,add_eol]])

• btoh

Convert binary (string) data to hexified string.
Parameters:
str: Mandatory, data to hexify
hex_sep: Optional separator to use between octets. Set it to 'undefined' if not used and hex_upcase is given
hex_upcase: Optional, use upper case characters in hexa
Return:
Hexified string

hex_str = Engine.btoh(str[,hex_sep[,hex_upcase]])

• htob

Unhexify binary (string) data.
Parameters:
hex_str: Mandatory, data to unhexify
hex_sep: Optional separator between octets. Set it to 'undefined' if missing or unknown (autodetect)
Return:
The string, boolean false on failure (invalid input string).

str = Engine.htob(hex_str[,hex_sep])

[edit] Properties

• DebugFail, DebugTest, DebugGoOn, DebugConf, DebugStub, DebugWarn, DebugMild, DebugCall, DebugNote, DebugInfo, DebugAll

Debug levels to be used when calling Engine.debug() or Engine.alarm().
NOTE:: Debug level is clamped to interval [DebugTest .. DebugAll] unless 'allow_abort' is enabled in javascript.conf (in this case the debug level is clamped to interval [DebugFail .. DebugAll].

• shared

Provides access to Shared object.

• name

Script name. It may not be available.
This is the name assigned to the script.
This property is missing when running javascript eval command.
Example:

javascript.conf:
[scripts]
test=some_script.js

in some_script.js
Engine.name property value is "test"