\section{Branching Commands}
\label{Branching Commands}

     TECO provides an  unconditional  branch  command  and  a  set  of
     conditional  execution  commands.   To  branch  within  a command
     string, you must be able to name  locations  inside  the  string.
     TECO permits location tags of the form:

\centerline{\tt !tag!}

     to be placed between any two commands in a command  string.   The
     name {\tt tag}  will be associated with this location when the command
     string is  executed.   Tags  may  contain  any  number  of  ASCII
     characters  and  any character except an exclamation mark.  (When
     using the {\tt @} form  of  this  command,  any  character  except  the
     delimiter is legal.) Since tags are ignored by TECO except when a
     branch command references the tagged location, they may  also  be
     used as comments within complicated command strings.

     The unconditional branch command is the {\tt O} command which  has  the
     form:

\centerline{\tt Otag\escape}

     where {\tt tag} is a location named elsewhere in the  command  string
     and  {\tt \escape} signifies a {\tt <DELIM>}.  When an {\tt O} command is executed, the
     next command to be executed will be the one that follows the  tag
     referenced   by  the  {\tt O}  command.   Command  execution  continues
     normally from this point.

     Use of the {\tt O} command is subject to two restrictions.   First,  if
     an  {\tt O}  command  is  stored  in  a Q-register as part of a command
     string which  is  to  be  executed  by  an  {\tt M}  command,  the  tag
     referenced by the {\tt O} command must reside in the same Q-register.

     Second, an {\tt O} command which is  inside  a  command  loop  may  not
     branch to a tagged location preceding the command loop.  However,
     it is always possible to branch  out  of  a  command  loop  to  a
     location  which  follows  the command loop and then branch to the
     desired tag.

     The string argument in the {\tt O} command has the same format  as  the
     string  arguments  in  the  search  and {\tt E} commands.  String build
     characters such as \caret {\tt EQq} can be  embedded  within  the  string  in
     TECO-11.   Also,  in  TECO-11  and  TECO-10, the {\tt O} command may be
     {\tt \@}-sign modified.  In that case, the syntax of the  command  would
     be  {\tt \@O/tag/} where {\tt /} represents any delimiting character that 
	does
     not appear within the tag.

     Branching into a conditional poses  no  problems,  but  branching
     into a command loop will causes unpredictable results.

     Although tags may contain any sequence of ASCII characters,  good
     programming  practice  dictates  that  tags  should  not  contain
     unusual characters (such as space, comma, ESCAPE, etc.) and  that
     they  should  be  mnemonic  for  the  piece of code to which they
     refer.

     There are many other  branching  commands.   Most  of  these  are
     considerably  faster  than  the  {\tt O}  command  and  should  be used
     wherever convenient.  They are all described in the table below.

\begin{table}[h]
\caption{\bf Branching Commands}
\end{table}
\nopagebreak

\begin{list}{}{\labelsep 20pt}

     \item[{\em COMMAND}]        {\em FUNCTION}

     \item[{\tt Otag} \escape]     This  command  causes  TECO  to  branch  
	to  the  first
               occurrence  of the specified label {\tt tag} in the current
               macro level.  In TECO-8 and TECO-11, branching  to  the
               left  of  the  start  of  the  current iteration is not
               permitted, and this  command  will  only  look  for  an
               occurrence  of the specified tag following the {\tt <} of the
               current iteration, if you are in an iteration.  In  any
               case, branching out of an iteration is poor programming
               practice.   Command  execution  resumes  at  the  first
               character after the delimiter terminating the specified
               tag.  Using this syntax, any character except {\tt <ESC>}  is
               permitted  in  the tag specification.  The usual string
               build characters are permitted when specifying the tag.

\ifnotintecoeight
     \item[{\tt @}{\tt O/tag/}]   Equivalent to {\tt Otag}\escape except that a 
	delimiter (shown here
               as  {\tt /}) is used before and after the specified tag.  Any
               character other than that delimiter is permitted inside
               the   tag.   The  usual  string  build  characters  are
               permitted when specifying the tag.
               {\em [Not in TECO-8]}
\fi

\iftecoelevenonly
     \item[{\tt nOtag0,tag1,tag2,...}\escape]
               This command causes TECO to branch to the tag specified
               by  the  {\tt n}th  tag in the accompanying list.  The string
               argument to this command consists of a sequence of tags
               separated   by   commas.   The  tags  may  contain  any
               characters other than comma or  {\tt <ESC>};   however,  good
               programming  practice  suggests  that  the  tags should
               consist only of letters and digits.  There must  be  no
               intervening spaces since these would be considered part
               of the tag.  If {\tt n} is out of range, or if  {\tt n}  selects  a
               null  tag,  then  command  execution continues with the
               first command following the {\tt <DELIM>} that delimits  this
               command.  (A null tag would be signified in the list by
               two adjacent commas.)
               {\em [TECO-11 only]}

     \item[{\tt n@O/tag0,tag1,tag2,.../}]
               Same as the preceding command except that the  list  of
               tags  is  bracketed  by  a delimiter shown here as {\tt /}.
               The delimiter can be any character that does not appear
               within  the  list  of tags.  In particular, using comma
               for the delimiter would not be very useful.
               {\em [TECO-11 only]}
\fi

     \item[{\tt ;}]         This command causes TECO to branch out of  the  current
               iteration,  if  the  immediately  preceding  search (or
               search and replace)  command  failed.   In  that  case,
               control resumes at the character following the matching
               {\tt >} at the end of the current iteration.   On  the  other
               hand,   if  the  preceding  search  succeeded,  command
               execution continues with the character following the {\tt ;}.
               If  this  command  is  encountered  from  outside of an
               iteration (in the current macro level), then  the  {\tt ?SNI}
               error message is issued.

     \item[{\tt n;}]        This command causes TECO to branch out of  the  current
               iteration if the value of {\tt n} is greater than or equal to
               0.  In that case,  command  execution  resumes  at  the
               character  following  the  matching {\tt >} at the end of the
               current iteration.  On the other hand,  if  {\tt n}  is  less
               than  0, command execution continues with the character
               following the {\tt ;}.  If this command is  encountered  from
               outside  of  an iteration (in the current macro level),
               then the {\tt ?SNI} error message is issued.

\iftecoelevenonly
     \item[{\tt :;}]        This command causes TECO to branch out of  the  current
               iteration  if  the  immediately  preceding  search  (or
               search and replace) command succeeded.  In  that  case,
               control resumes at the character following the matching
               {\tt >} at the end of the current iteration.   On  the  other
               hand, if the preceding search failed, command execution
               continues with the character following the {\tt ;}.  If  this
               command is encountered from outside of an iteration (in
               the current macro level), then the {\tt ?SNI}  error  message
               is issued.
               {\em [TECO-11 only]}

     \item[{\tt n:;}]       This command causes TECO to branch out of  the  current
               iteration  if  the  value of {\tt n} is less than 0.  In that
               case,  command  execution  resumes  at  the   character
               following  the  matching  {\tt >}  at  the end of the current
               iteration.  On the other hand, if {\tt n} is greater than  or
               equal  to  0,  command  execution  continues  with  the
               character  following  the  {\tt ;}.   If  this   command   is
               encountered  from  outside  of  an  iteration  (in  the
               current macro level), then the {\tt ?SNI}  error  message  is
               issued.
               {\em [TECO-11 only]}
\fi

     \item[{\tt '}]         This ``command'' is actually part of the syntax  of  TECO
               conditionals.   It  has  no  affect if ``executed'' other
               than to signify termination of the current  conditional
               level.   If  an  argument is specified to this command,
               the result is not  defined.   (Arguments  pass  through
               this command on TECO-11.) Conditionals are described in
               section~\ref{Conditional Execution Commands}.

     \item[{\tt |}]         This ``command'' is actually part of the syntax  of  TECO
               conditionals.  If executed, it causes control to branch
               to the  end  of  the  conditional.   Command  execution
               resumes  with  the  character following the {\tt '} that ends
               the current conditional  with  the  ELSE  clause  being
               skipped.

     \item[{\tt >}]         This ``command'' is actually part of the syntax  of  TECO
               iterations.   If  executed,  it causes TECO to bump the
               current iteration count by 1 and test  to  see  if  the
               resulting count is equal to the maximum count permitted
               for the iteration (specified as an argument before  the
               matching  {\tt <}).   If the iteration count has not expired,
               then control returns to the command following the {\tt <}  at
               the   beginning  of  the  current  iteration.   If  the
               iteration has expired, then command execution continues
               with  the  character following this {\tt >}.  If this command
               is encountered outside  of  an  iteration  (within  the
               current  macro  level), then the {\tt ?BNI} error message (or
               its equivalent) is issued.

\iftecoelevenonly
     \item[{\tt F>}]        This command causes TECO to branch (flow) to the end of
               the   current   iteration.   TECO  effectively  resumes
               execution at the matching {\tt >}.  The  iteration  count  is
               tested  as  usual.   If  it  has  not  expired, control
               returns back to the start of  the  iteration  with  the
               count  having  been incremented by 1.  If the count was
               up, the iteration is exited and control continues  with
               the  first  command  after  the  {\tt >}.  If this command is
               encountered outside of an iteration, it  has  the  same
               effect as the {\tt <DELIM><DELIM>} command.
               {\em [TECO-11 only]}

     \item[{\tt F<}]        This command causes TECO to branch (flow) to the  start
               of  the  current  iteration.   TECO effectively resumes
               execution at the first command following the {\tt <}  at  the
               beginning  of  the  current  iteration.   The iteration
               count is not  affected.   If  this  command  is  issued
               outside  of an iteration, it causes TECO to branch back
               to the start of the  current  command  string  (in  the
               current macro level).
               {\em [TECO-11 only]}

     \item[{\tt F'}]        This command causes TECO to branch (flow) to the end of
               the  current  conditional.   TECO  effectively  resumes
               execution at the first command following the {\tt '}  at  the
               end  of the current conditional.  Numeric arguments are
               eaten up by this command.  If this  command  is  issued
               while  not  in  a  conditional,  the {\tt ?MAP} error (or its
               equivalent) is issued.
               {\em [TECO-11 only]}

     \item[{\tt F|}]        This command causes TECO to branch (flow) to  the  else
               clause  of  the  current conditional.  TECO effectively
               resumes execution at the first command following the  {\tt |}
               at  the end of the current THEN clause.  If the current
               conditional has no ELSE clause, or if an unmatched {\tt '} is
               encountered before an unmatched |, then control resumes
               at the command following the {\tt '} .  Numeric arguments are
               eaten  up  by  this command.  If this command is issued
               while not in a conditional,  the  {\tt ?MAP}  error  (or  its
               equivalent) is issued.  Well-structured programs should
               not need to use this command.
               {\em [TECO-11 only]}
\fi

     \item[{\tt \$\$}]        The {\tt <ESC><ESC>} command causes TECO  to  exit  from  the
               current  macro  level.   If this command is issued from
               top level (not from within a macro), then  the  command
               string  execution  is  terminated  and  TECO returns to
               prompt level.  Note that the second  {\tt <ESC>}  must  be  a
               true  ESCape and may not be a \caret {\tt [}.  Also, note that both
               ESCapes must be true TECO commands and not part of  the
               syntax  of  some  previous command.  That is, the first
               {\tt <ESC>} does not count if it is the delimiting ESCape  of
               a string.  Finally, note that these must be real ESCape
               characters,  and  not   the   user-designated   {\tt <DELIM>}
               character  (which  TECO  understands  as an ESCape only
               when typed at the console).

     \item[{\tt n\$\$}]       This command causes TECO to exit from the current macro
               level,  returning  the number {\tt n} as a value.  This value
               will be used as  the  numeric  argument  to  the  first
               command following the macro call.

     \item[{\tt m,n\$\$}]     This command causes TECO to exit from the current macro
               level,  returning  the  pair  of  values  m  and  {\tt n}  as
               arguments to the  first  command  following  the  macro
               call.  Good programming practice dictates that all ways
               of exiting a macro return the same number of arguments.

     \item[\caret{\tt C}]        The {\tt <CTRL/C>} (Caret-{\tt C}) command 
		when executed as a  TECO
               command,  causes  command execution to stop and control
               return to TECO's  prompt.   No  clean-up  of  push-down
               lists, flag settings, etc.  is done.  This command lets
               a macro abort TECO's command execution.
               [On TECO-8 and TECO-10, this command causes control  to
               return to the operating system.]
               [On TECO-11, this  command  returns  to  the  operating
               system if executed from the top level.]
               Consult the appendices for specific details  concerning
               your operating system.

     \item[\caret {\tt C <CTRL/C>}]
               This command causes TECO to unconditionally  abort  and
               control  exits  from  TECO.   Control  returns  to  the
               operating system.  The second {\tt <CTRL/C>} must be  a  true
               {\tt <CTRL/C>} and may not be a \caret{\tt C}.
\end{list}