Synchronet v3.19b-Win32 (install) has been released (Jan-2022).

You can donate to the Synchronet project using PayPal.

This is an old revision of the document!


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]

available opts:

    -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=8388608 bytes)
    -s<bytes>      set context stack size (default=16384 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 message to stdout
    -A<filename>   send all message 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             debugs the script

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.

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.

FIXME

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