| Next revision | Previous revision |
| util:jsexec [2010/02/24 15:27] – created digitalman | util:jsexec [2022/03/06 15:19] (current) – [Module] Add Log Level section digital man |
|---|
| ====== JSexec ====== | ====== 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. [[:service:ircd]]) independent of Synchronet |
| | * Background execution of timed events (e.g. [[:module:newslink]]) |
| | * Command-line execution of sysop functions (e.g. [[:module:makeguest]]) |
| | * [[:howto:apache|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 ===== |
| | |
| | <file> |
| | 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 |
| | </file> |
| | |
| | ==== 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 ''[[dir: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 ''[[dir:ctrl]]'' directory. |
| | |
| | ==== Log Level ==== |
| | |
| | The log severity/output verbosity level can be controlled via the ''[[dir:ctrl]]/[[config: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 [[http://wiki.synchro.net/config:ini_files#enumerated_values|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'' |string|[[dev:CVS]] 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 | FIXME |
| |
| | ===== uifc ===== |
| | JSexec includes an instance of a special User Interface class called ''uifc''. |
| | |
| | See the [[ref: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 [[wp>shebang (Unix)]] style script file where the first line of the script is something like: |
| | <file> |
| | #!/sbbs/exec/jsexec -c/sbbs/ctrl |
| | </file> |
| | |
| | This allows JSexec scripts to be executed easily via [[:howto:apache|CGI]] as well as other command-line conveniences on Unix-like operating systems. |
| | |
| | ===== Output ===== |
| | |
| | JSexec supports multiple output methods and streams: |
| | |
| | - **Error** (default stream: ''stderr'')\\ JS ''log()'' messages with log-levels of ''LOG_ERR'' or lower |
| | - **Status** (default stream: ''stderr'')\\ JS ''log()'' messages with log-levels higher than ''LOG_ERR''\\ JSexec startup/compile/shutdown progress messages |
| | - **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 ===== | ===== See Also ===== |
| | * [[custom:javascript|JavaScript]] |
| | * [[:config:jsexec.ini]] |
| | * [[:howto:apache|How To Use Apache HTTP Server with Synchronet]] |
| * [[:util:|Utilities]] | * [[:util:|Utilities]] |
| |
| | {{tag>javascript jsexec customization}} |
