Differences

This shows you the differences between two versions of the page.

--- util:jsexec [2010/03/18 01:18] – digitalman
+++ util:jsexec [2022/03/06 15:19] (current) – [Module] Add Log Level section digital man
@@ Line 1: / Line 1: @@
 ====== JSexec ======
-JSexec may be used to execute some Synchronet JavaScript files (e.g. ''*.js'', ''*.ssjs'') externally from Synchronet
+JSexec may be used to execute some Synchronet JavaScript files (e.g. ''*.js'', ''*.ssjs'') externally from Synchronet.
-:!: Note: a Synchronet installation is required, though JSexec will execute scripts successfully even when Synchronet is not running.
+===== 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]
+usage: jsexec [-opts] [[path/]module[.js] [args]
+   or: jsexec [-opts] -r js-expression [args]
+   or: jsexec -v
 available opts:
-        -c<ctrl_dir>   specify path to Synchronet CTRL directory
+    -r<expression> run (compile and execute) JavaScript expression
-        -m<bytes>      set maximum heap size (default=8388608 bytes)
+    -c<ctrl_dir>   specify path to Synchronet CTRL directory
-        -s<bytes>      set context stack size (default=16384 bytes)
+    -C             do not change the current working directory (to CTRL dir)
-        -S<bytes>      set thread stack limit (default=262144, 0=unlimited)
+    -d             run in background (daemonize)
-        -b<limit>      set branch limit (default=99999999, 0=unlimited)
+    -m<bytes>      set maximum heap size (default=16777216 bytes)
-        -y<interval>   set yield interval (default=10000, 0=never)
+    -t<limit>      set time limit (default=864000, 0=unlimited)
-        -g<interval>   set garbage collection interval (default=100, 0=never)
+    -y<interval>   set yield interval (default=10000, 0=never)
-        -h[hostname]   use local or specified host name (instead of SCFG value)
+    -g<interval>   set garbage collection interval (default=100, 0=never)
-        -u<mask>       set file creation permissions mask (in octal)
+    -h[hostname]   use local or specified host name (instead of SCFG value)
-        -L<level>      set log level (default=7)
+    -u<mask>       set file creation permissions mask (in octal)
-        -E<level>      set error log level threshold (default=4)
+    -L<level>      set log level (default=6)
-        -i<path_list>  set load() comma-sep search path list (default="load")
+    -E<level>      set error log level threshold (default=4)
-        -f             use non-buffered stream for console messages
+    -i<path_list>  set load() comma-sep search path list (default="load")
-        -a             append instead of overwriting message output files
+    -f             use non-buffered stream for console messages
-        -e<filename>   send error messages to file in addition to stderr
+    -a             append instead of overwriting message output files
-        -o<filename>   send console messages to file instead of stdout
+    -A             send all messages to stdout
-        -n             send status messages to NUL instead of stderr
+    -A<filename>   send all messages to file instead of stdout/stderr
-        -q             send console messages to NUL instead of stdout
+    -e<filename>   send error messages to file in addition to stderr
-        -v             display version details and exit
+    -o<filename>   send console messages to file instead of stdout
-        -x             disable auto-termination on local abort signal
+    -S<filename>   send status messages to file instead of stderr
-        -l             loop until intentionally terminated
+    -S             send status messages to stdout
-        -p             wait for keypress (pause) on exit
+    -n             send status messages to /dev/null instead of stderr
-        -!             wait for keypress (pause) on error
+    -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^
+^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'' |string[] |Associative array of system environment variables (example: ''%%env["shell"]="/bin/bash"%%'')|
+|''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''.
@@ Line 54: / Line 99: @@
 JSexec includes an instance of a special User Interface class called ''uifc''.
-FIXME
+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:js|JavaScript]]
+  * [[custom:javascript|JavaScript]]
+  * [[:config:jsexec.ini]]
   * [[:howto:apache|How To Use Apache HTTP Server with Synchronet]]
   * [[:util:|Utilities]]
 {{tag>javascript jsexec customization}}

Trace:

Differences

Navigation

Search

Toolbox