Command
	break

Purpose
	Breaks (terminates) the inner-most while loop.

Aliases
	break, brk

Syntax
	break [<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 break code and if specified, is assigned to
		the system variable $breakcode.

		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.

	break <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.

	break <code>: <message>

	Such messages to stream error can be used for tracing execution of a script.

Description
	While is a programming construct that allows grouping of commands into what is
	known as a while loop. Such group of commands within the while loop executes repeatedly
	as long as certain condition is met. This condition is specified in the while command and
	is called the while condition.

	If a break command is encountered within a while loop, the while loop terminates.
	Execution resumes at the command immediately following the while loop, if one exists.
	The following is a simple example.

	var integer i
	while ($i <= 10)
	do
	    set $i=$i+1
	    if ($i > 5)
	        break
	    endif
	    echo ($i*$i)
	done

	This will print squares of numbers from 1 to 5. When the value of integer variable $i
	exceeds 5, the break command is executed, and the while loop terminates.

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

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

	The value of $breakcode can be used later for determining which break command
	executed.
		
Restrictions
	This command is not allowed outside a while loop.

Valid Examples
	var string content
	var integer instance
	cat "C:/test/sample.txt" > $content
	while ( { sen "^abc^" $content } > 0 )
	do
	    # Found the next instance of string "abc".
	    set $instance = $instance + 1

	    # If $instance is more than 3, terminate the while loop.
	    if ( $instance > 3 )
	        break 1 "Completed file C:/test/sample.txt"
	    endif

	    # Change this instance of "abc" to "XYZ".
	    sal "^abc^" "XYZ" $content > null
	done
	echo $content > "C:/test/sample.txt"

	This code reads the contents of the text file "C:/test/sample.txt" (if it exists)
	into the string variable $content. It then changes the first 3 instances of string
	"abc" (if they exist) to string "XYZ". When the fourth instance of string "abc" is
	encountered, the while loop is terminated and the following message is printed to
	stream error.

	break 1: Completed file C:/test/sample.txt

	Finally, the $content, thus altered, is written back to file "C:/test/sample.txt".


Invalid Examples

	break "Completed file C:/test/sample.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.

	break 0 "Completed file C:/test/sample.txt"

	Consider the following command.

	break 0 Completed file C:/test/sample.txt

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

	break 0: Completed

	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
while
continue
exit
systemvar