JSexec

JSexec may be used to execute some Synchronet JavaScript files (e.g. *.js, *.ssjs) externally from Synchronet.

Uses

  • Persistent execution of static services (e.g. ircd) independent of Synchronet
  • Background execution of timed events (e.g. newslink)
  • Command-line execution of sysop functions (e.g. makeguest)
  • CGI generated dynamic HTML

Independence

A Synchronet installation is required for JSexec to function, though JSexec will execute scripts successfully even when Synchronet is not running.

Command Line

usage: jsexec [-opts] [[path/]module[.js] [args]
   or: jsexec [-opts] -r js-expression [args]
   or: jsexec -v

available opts:

    -r<expression> run (compile and execute) JavaScript expression
    -c<ctrl_dir>   specify path to Synchronet CTRL directory
    -C             do not change the current working directory (to CTRL dir)
    -d             run in background (daemonize)
    -m<bytes>      set maximum heap size (default=16777216 bytes)
    -t<limit>      set time limit (default=864000, 0=unlimited)
    -y<interval>   set yield interval (default=10000, 0=never)
    -g<interval>   set garbage collection interval (default=100, 0=never)
    -h[hostname]   use local or specified host name (instead of SCFG value)
    -u<mask>       set file creation permissions mask (in octal)
    -L<level>      set log level (default=6)
    -E<level>      set error log level threshold (default=4)
    -i<path_list>  set load() comma-sep search path list (default="load")
    -f             use non-buffered stream for console messages
    -a             append instead of overwriting message output files
    -A             send all messages to stdout
    -A<filename>   send all messages to file instead of stdout/stderr
    -e<filename>   send error messages to file in addition to stderr
    -o<filename>   send console messages to file instead of stdout
    -S<filename>   send status messages to file instead of stderr
    -S             send status messages to stdout
    -n             send status messages to /dev/null instead of stderr
    -q             send console messages to /dev/null instead of stdout
    -v             display version details and exit
    -x             disable auto-termination on local abort signal
    -l             loop until intentionally terminated
    -p             wait for keypress (pause) on exit
    -!             wait for keypress (pause) on error
    -D             load the script into an interactive debugger

Module

The module argument is optional if the standard input stream (stdin) is not a console (tty), allowing for shebang support on Unix-like operating systems.

Note: When JSexec starts up, it changes its current working directory to the Synchronet ctrl directory. If you pass filenames on the command-line to a module, the paths must be full/absolute paths or relative to the Synchronet ctrl directory.

Log Level

The log severity/output verbosity level can be controlled via the ctrl/jsexec.ini file or specified using the -L command-line option. The value following -L can either be the numeric log level (7 being the lowest-severity / most verbose output) or a word describing the log level (e.g. -Ldebug for debug-level logput).

Additional Properties

Additional properties available to JavaScript scripts running from JSexec:

Property Type Description
jsexec_revision stringCVS revision of JSexec (example: "1.135")
jsexec_revision_detail string Verbose details about the JSexec build (example: "JSexec 1.136 Debug Compiled Mar 15 2010 11:13:53 with GCC 3.4.2")
env Object Associative array of system environment variables (example: env["shell"]="/bin/bash")
stdin File Standard input stream
stdout File Standard output stream
stderr File Standard error output stream

Additional Functions

The following global methods (functions) are also available to JavaScript scripts running from JSexec:

Function Return Value Description
log String Log a message
read String Read from stdin
readln String Read line from stdin
write String Write a string to stdout
print String Write a line to stdout (a.k.a. writeln)
printf String Write a formatted string to stdout
alert String Print an alert message on the console
prompt String Prompt for user input
confirm String Get a yes/no confirmation
deny String Get a no/yes confirmation
chdir String Change the current working directory
putenv String Add or change an environment variable

conio

JSexec includes an instance of a special Console Input/Output class called conio.

FIXME

uifc

JSexec includes an instance of a special User Interface class called uifc.

See the UIFC reference page for more details.

shebang

JSexec for non-Windows platforms will ignore the first line of the interpreted script if it begins with #!, allowing for a shebang (Unix) style script file where the first line of the script is something like:

#!/sbbs/exec/jsexec -c/sbbs/ctrl

This allows JSexec scripts to be executed easily via CGI as well as other command-line conveniences on Unix-like operating systems.

Output

JSexec supports multiple output methods and streams:

  1. Error (default stream: stderr)
    JS log() messages with log-levels of LOG_ERR or lower
  2. Status (default stream: stderr)
    JS log() messages with log-levels higher than LOG_ERR
    JSexec startup/compile/shutdown progress messages
  3. Console (default stream: stdout)
    JS write() writeln() printf() alert() and prompt() messages

syslog

When JSexec is executed on *nix operating systems with the -d (Daemonize) option, all JS log() messages are directed to syslog.

Suppression

  • Status output is suppressed by default when JSexec is run without a controlling TTY. This behavior can be overridden with the -A and -S command-line options.
  • Status output can be manually suppressed with the -n (Null) command-line option.
  • Console output can be suppressed with the -q (Quiet) command-line option.

Redirection

  • The output streams may be redirected to specific filenames via command-line options.
  • Error output can be forked to both stderr and a specified filename via the -e command-line option.

See Also

util/jsexec.txt · Last modified: 2022/03/06 15:19 by digital man
Back to top
CC Attribution 4.0 International
Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0