Jaxer.Process : Object
Return to: Jaxer Framework index

Used to execute operating system processes

Platform Support

Jaxer Server Framework Jaxer Client Framework
1.0 no

Constructors

Constructor Action Jaxer Server Framework Jaxer Client Framework
Jaxer.Process Constructor([String path,] [Boolean async]) : Jaxer.Process
The constructor for an object that wraps an operating system process. This also provides static functions for more easily executing operating system processes.
Show Details 1.0 no

Jaxer.Process([String path,] [Boolean async]) : Jaxer.Process

The constructor for an object that wraps an operating system process. This also provides static functions for more easily executing operating system processes.

Parameters
String path (optional)The absolute path to the executable file to execute. This must be specified before execution begins.
Boolean async (optional)By default, the process executes synchronously: it blocks until complete. If async is true, it will execute asynchronously, not blocking before completion. This can be specified at any time until execution begins.

Returns
Jaxer.Process The wrapper around the operating system process

Properties

Property Action Jaxer Server Framework Jaxer Client Framework
_proc : Object
The internal process handle

(Advanced)
No Details 1.0 no
Visibility
advanced
_status : Number
The internal status (state) of the process: one of Jaxer.Process.CREATED, Jaxer.Process.EXEC_BEGUN, Jaxer.Process.WRITE_ENED, and Jaxer.Process.EXEC_ENDED.

(Advanced)
No Details 1.0 no
Visibility
advanced
readBufferSize : Number
The size in bytes of the buffer to use when reading from STDOUT and STDERR. By default this is 1024 bytes.

(Advanced)
No Details 1.0 no
Visibility
advanced
args : Array
The array of arguments to this process.
No Details 1.0 no
async : Boolean
If true, the process will be executed asynchronously (without blocking)
No Details 1.0 no
autoDetachIfAsync : String
Whether to detach the process (if it's asynchronous) after any writing to STDIN is complete. This is true by default Note that this property is only used by methods like exec and execAsync; you can always just explicitly detach by calling endExec.
No Details 1.0 no
exitStatus : Number
The exit status (i.e. return code) of the process, if any. For an async process this is null.
No Details 1.0 no
path : String
The absolute path to the executable file to execute
No Details 1.0 no
stderr : String
How to handle the standard error stream (STDERR) from the process. If this is a string, it read from STDERR as a character stream; otherwise no reading from STDERR is performed. Note that this property is only used by methods like exec and execAsync; you can always just explicitly read from STDERR using readErrString.
No Details 1.0 no
stdin : String
How to handle the standard input stream (STDIN) to the process. If this is a string, it is written to STDIN as a character stream; if this is an array, it is written to STDIN as a binary (byte array) stream; otherwise no writing to STDIN is performed. Note that this property is only used by methods like exec and execAsync; you can always just explicitly write to STDIN using writeString or writeBinary.
No Details 1.0 no
stdout : String
How to handle the standard output stream (STDOUT) from the process. If this is a string, it read from STDOUT as a character stream; if this is an array, it is read from STDOUT as a binary (byte array) stream; otherwise no reading from STDOUT is performed. Note that this property is only used by methods like exec and execAsync; you can always just explicitly read from STDOUT using readString or readBinary.
No Details 1.0 no
static CREATED : Number
The internal status indicating the process wrapper has been created but no execution has begun
No Details 1.0 no
static EXEC_BEGUN : Number
The internal status indicating the process has begun executing, but any writing to STDIN is not necessarily finished
No Details 1.0 no
static EXEC_ENDED : Number
The internal status indicating the process has finished executing or has been detached (if async)
No Details 1.0 no
static WRITE_ENDED : Number
The internal status indicating the process has begun executing and any writing to STDIN is finished
No Details 1.0 no

Functions

Method Action Jaxer Server Framework Jaxer Client Framework
beginExec() : void
Begins execution of the process. Any arguments to this method are treated as arguments to the process; if no arguments are given, and this.args has been set, it will be used instead. You can start to write to STDIN and read from STDOUT and STDERR after you call this method.
No Details 1.0 no
endExec() : Number
Completes the execution of the process (if synchronous) or detaches it (if asynchronous). A running process may be stopped via kill() anytime before endExec() is called.
Show Details 1.0 no

Returns
Number If the process is synchronous, its exit status (i.e. return code) is returned.

endWrite() : void
Closes STDIN for further writing, which may be needed by the process before it can proceed. This is automatically called by reading anything from STDOUT and STDERR and by endExec.
No Details 1.0 no
exec() : Number
Executes the process. The path to the executable file should already have been set when creating the Process or via the path property. The arguments to this method are used as the arguments to the process. By default, the process is executed synchronously (i.e. it blocks), and nothing is written to STDIN nor read from STDOUT or STDERR. To override these defaults, set any of the following properties before calling this: async, stdin, stdout, stderr, and autoDetachIfAsync. If any of these are set they will be used; for stdout and stderr they will be used only if the process is synchronous, in which case they'll be set to STDOUT/STDERR. If the process is asycnhronous and autoDetachIfAsync is false, it will not be detached until it falls out of scope, so you can still read STDOUT or STDERR and kill it until it falls out of scope, at which point it will be detached; otherwise it will be detached immediately (or after any STDIN is written).
Show Details 1.0 no

Returns
Number If the process is synchronous, its exit status (i.e. return code) is returned.

execAsync() : void
Executes the process asynchronously (i.e. without blocking). The path to the executable file should already have been set when creating the Process or via the path property. The arguments to this method are used as the arguments to the process. By default, nothing is written to STDIN, and the process is immediately detached after it is launched. To override these defaults, set stdin and/or autoDetachIfAsync on the process before calling this. If stdin is set, it will be used. If autoDetachIfAsync is not set (or set to the default value of true), the process will be detached immediately after any STDIN is written. If autoDetachIfAsync is set to false, the process will not be detached, so you can still read STDOUT or STDERR and kill it until it falls out of scope, at which point it will be detached.
No Details 1.0 no
kill() : void
Kills a running process. This can only be called before endExec() has been called.
No Details 1.0 no
readBinary([Number maxLength]) : Array<Number>
Reads the process's STDOUT stream as a byte array.
Show Details 1.0 no

Parameters
Number maxLength (optional)If specified, limits reading of STDOUT to maxLength bytes

Returns
Array<Number> The binary value of STDOUT as an array of integers

readErrString([Number maxLength]) : String
Reads the process's STDERR stream as a character string.
Show Details 1.0 no

Parameters
Number maxLength (optional)If specified, limits reading of STDERR to maxLength characters

Returns
String The string value of STDERR

readString([Number maxLength]) : String
Reads the process's STDOUT stream as a character string.
Show Details 1.0 no

Parameters
Number maxLength (optional)If specified, limits reading of STDOUT to maxLength characters

Returns
String The string value of STDOUT

writeBinary(Array<Number> data) : void
Writes the given byte array as a binary stream to the process's STDIN
Show Details 1.0 no

Parameters
Array<Number> data The byte array (array of integers)

writeString(String str) : void
Writes the given string as a character stream to the process's STDIN.
Show Details 1.0 no

Parameters
String str The string to write

static exec(String path) : String
Executes the process specified by the given absolute path. Any remaining arguments to this function are used as the arguments to the process, except possibly for the last argument if it is an object, in which case it's removed and used to set options. By default, the process is executed synchronously (i.e. it blocks), and nothing is written to STDIN. To override these defaults, pass as a final argument an object containing the properties to be overridden: async, stdin, stdout, stderr, autoDetachIfAsync. If any of these are set they will be used; for stdout and stderr they will be used only if the process is synchronous, in which case their values in your object will be set to STDOUT/STDERR. For a synchronous process, the return value will be the STDOUT of the process, unless you specify stdout in your options object, in which case the return value is the exitStatus; and unless you specify stderr, an error will be thrown if the process's exitStatus is non-zero or if it writes to STDERR. If the process is executed asynchronously and autoDetachIfAsync is false, it will not be detached until it falls out of scope; otherwise it will be detached immediately (or after any STDIN is written).
Show Details 1.0 no

Parameters
String path The absolute path of the executable file to execute

Returns
String For a synchronous process (without having a stdout property in an options object), returns the STDOUT of the process; otherwise does not return anything.

Examples
 document.write("The folder contains:\n" + Jaxer.Process.exec("/bin/ls")); var opts = { stdin : 'Hello world', stdout:
                        '', stderr: ''}; var exitStatus = Jaxer.Process.exec("/bin/cat", "-", opts); document.write("Finished /bin/cat with status
                        " + exitStatus + ": opts = " + uneval(opts)); 
static execAsync(String path) : void
Asynchronously executes the process specified by the given absolute path (so it does not block). Any remaining arguments to this function are used as the arguments to the process, except possibly for the last argument if it is an object, in which case it's removed and used to set options. By default, nothing is written to STDIN nor read from STDOUT or STDERR, and the process is immediately detached after it is launched. To override these defaults, pass as a final argument an object containing the properties to be overridden: stdin and/or autoDetachIfAsync. If stdin is set, it will be used. If autoDetachIfAsync is not set (or set to the default value of true), the process will be detached immediately after any STDIN is written. If autoDetachIfAsync is set to false, the process will not be detached until it falls out of scope, at which point it will be detached.
Show Details 1.0 no

Parameters
String path The absolute path of the executable file to execute

Examples
 Jaxer.Process.execAsync("/bin/sleep", 1, { autoDetachIfAsync : false } ); var opts = { stdout : ''}; Jaxer.Process.exec('/bin/ps',
                        '-ax', opts); print("Sleep is running? " + (Jaxer.Util.String.grep(opts.stdout, "/bin/sleep").length > 0)); Jaxer.Util.sleep(2000);
                        Jaxer.Process.exec('/bin/ps', '-ax', opts); print("Sleep is running? " + (Jaxer.Util.String.grep(opts.stdout, "/bin/sleep").length
                        > 0)); 
aptana_docs