Command
	exit

Purpose
	Exits (terminates) the inner-most script.

Aliases
	exit, ext

Syntax
	exit [<options>] [ <code> [ <message>] ]


Options
	-o	Write the <message>, if any, to stream output instead of stream error.
		If a <message> is specified, it is written to stream error without this option.
		With this option, the <message> is written to stream output instead.

Arguments
	<code>	An integer value. This code is called exit code and if specified, is assigned to
		the system variable $exitcode.

		This argument can be specified using either a constant, variable, function call,
		inline command, or an expression consisting of any of these.
		In all cases, the argument must result in a value of type integer.

	<message>	A string value. This string is written to either stream error or
		stream output depending on whether option -o is specified.

		This argument can be specified using either a constant, variable, function call,
		inline command, or an expression consisting of any of these.
		In all cases, the argument must result in a value of type string. If a string
		constant is used, it must be enclosed in double quotes.

		<message> can be specified only if <code> is specified.

Stream Input	
	Ignored.

Stream Output
	If the -o option is specified, and <message> is specified, a message in the following format
	is written to stream output.

	exit <code>: <message>

Stream Error
	Any errors encountered are written here.

	In addition, if the -o option is not specified, and <message> is specified,
	a message in the following format is written to stream error.

	exit <code>: <message>

	Such messages to stream error can be used for tracing execution of nested scripts.

Description
	When an exit command is encountered within a script, the script terminates.
	Execution resumes at the command immediately following the script command that invoked
	the terminated script, if one exists. The following is a simple example.

	# Script square.txt
	var int num
	if ($num > 5)
	    exit
	endif
	echo ($num*$num)

	The above script is saved in the script file "C:/Scripts/square.txt". This script is
	then called in the following while loop.

	var integer i
	while ($i < 10)
	do
	    set $i = $i + 1
	    script "C:/Scripts/square.txt" num($i)
	done

	This will print squares of numbers from 1 to 5. For each number greater than 5, the
	script square.txt will exit, and execution will resume at the command immediately
	following the script command, which is the done command.

	It is important to note that the exit command terminates only the inner-most
	script. When two or more scripts are nested, the script immediately outside
	the exit command will terminate. The outer script(s) will continue to execute.

	When an exit command is executed, and <code> is specified, the value of <code> is
	assigned to the system variable $exitcode. This system variable always contains the
	<code> from the last executed exit command. If no exit command has executed
	yet, or if the last executed exit command did not specify <code>, this value is 0.

	The value of $exitcode can be used later for determining which exit command
	executed.

	exit command is allowed outside scripts. When an exit command is encountered outside
	of a script, all the previously entered commands terminate. biterScripting Interactive
	itself does NOT exit.
		
Restrictions
	This command is not allowed inside a function. This is done for the following reason.
	A function is declared only once, and called many times from any other part of the code,
	including from any scripts. If an exit command were to be allowed to be executed inside
	a function, it may, sometimes, cause an un-intended script to exit.

Valid Examples
	
	Consider the following script stored in script file "C:/Scripts/FileSearch.txt".

	# Script FileSearch.txt
	var string file, content
	if ($file=="")
	    exit 1 "Error: file is not specified."
	endif

	cat $file > $content
	if ( { sen "^abc^" $content } < 0 )
	    exit 2 ("Error: string abc does not exist in file "+$file)
	else
	    exit 0 ("Success: string "abc" exists in file "+$file)
	endif

	The above script checks if the string "abc" exists inside the specified file. It can
	be now called in any of the following ways.

	script "C:/Scripts/FileSearch.txt"

	will print

	exit 1: Error: file is not specified.

	script "C:/Scripts/FileSearch.txt" file("X.txt")

	If the file X.txt contains the string "abc", the following message will be produced.

	exit 0: Success: string "abc" exists in file X.txt

	If the file x.txt does not containt the strting "abc", the following message will be produced.

	exit 2: Error: string abc does not exist in file X.txt

	The error messages from the script can be consolidated by calling the script in the following
	manner.

	script "C:/Scripts/FileSearch.txt" file("X.txt") 2>null
	if ($exitcode <> 0)
	    echo "Script failed"
	endif


Invalid Examples

	exit "Exiting script FileSearch.txt"

	Will produce error. The <message> can be specified only if the <code> is specified.
	If the code is not important, simply use 0 for <code>, as follows.

	exit 0 "Exiting script FileSearch.txt"

	Consider the following command.

	exit 0 Exiting script FileSearch.txt

	This is not quite invalid, however, it will print the following.

	exit 0: Exiting

	The rest of the <message> will be lost. This is because the entire <message> is not
	enclosed in double quotes. Always enclose all constant string values in double quotes.

See Also
script
continue
break
systemvar