====== 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

===== 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 =====
  * [[custom:javascript|JavaScript]]
  * [[:config:jsexec.ini]]
  * [[:howto:apache|How To Use Apache HTTP Server with Synchronet]]
  * [[:util:|Utilities]]

{{tag>javascript jsexec customization}}