\section{Q-register Manipulation}
\label{Q-register Manipulation}

     TECO provides data storage registers, called Q-registers, each of
     which  may  be  used  to  store  an  integral  numeric value and,
     simultaneously,  an  ASCII  character  string.   Q-registers  are
     described  in section Q-registers;  this section describes the commands
     used to load values into and retrieve values from Q-registers.

     An important kind of character string which may be stored in  the
     text  portion  of  a Q-register is a TECO command string.  Such a
     command is known as a macro, and is available for  execution  via
     the {\tt Mq} command, described in Table \ref{Macro Invocation Commands} 
	below.  (See also section
     \ref{Immediate ESCAPE-Sequence Commands}, 
     for a keypad  method  of
     macro  invocation,  and  section  \ref{Immediate Action Commands},  
	for the {\tt *q} command, which
     saves  the   last-typed   command   for   possible   editing   or
     re-execution.)

     TECO-10 allows additional Q-registers other than those  described
     in section Q-registers.  Consult Appendix I for further details.

     Table \ref{Q-register Loading Commands} lists the  commands  which  
	permit  characters  to  be
     loaded into the Q-registers.


\begin{table}[h]
\caption{\bf{Q-register Loading Commands}}
\label{Q-register Loading Commands}
\end{table}
\nopagebreak
            
\begin{list}{}{\labelsep 20pt}
     \item[COMMAND]        FUNCTION
\nopagebreak
     \item[{\tt nUq}]       Put {\tt n} in the numeric storage area of Q-register q.

     \item[{\tt m,nUq}]     Equivalent to the {\tt nUqm} command.  That is, 
		this  command
               puts  the  number  {\tt n}  into  the numeric storage area of
               Q-register q and then returns the number {\tt m} as a  value.
               The  command {\tt UAUB} is useful at the beginning of a macro
               to save the two arguments specified on the macro  call.
               (See the {\tt m,nMq} command below.)

     \item[{\tt n\%q}]       Add {\tt n} to the contents of the  number  
	storage  area  of
               Q-register q.  The updated contents of Q-register q are
               also returned as a value  to  be  passed  to  the  next
               command.

               If your intent is only to update the  Q-register,  good
               programming practice suggests following the {\tt n\%q} command
               with a {\tt <DELIM>} or \caret {\tt [} to prevent the 
		returned value from
               unintentionally affecting the following command.

     \item[{\tt n\%q\escape}]      Same as {\tt n\%q} but discards the 
	value returned.

     \item {\tt \%q}        Equivalent to {\tt 1\%q}.

     \item [\caret {\tt Uqstring} \escape]
               This command inserts character string {\tt string} into the
               text  storage  area  of  Q-register q.  When entering a
               command string from the terminal, you must  specify  \caret 
		{\tt U}
               using  the caret/ {\tt U} format, since the {\tt<CTRL/U>} 
		character
               is the line erase immediate action command.

\ifnotintecoeight
     \item [{\tt :}\caret {\tt Uqstring}\escape]
               This command appends character string {\tt string}  to  the
               text storage area of Q-register {\tt q}.
               {\em [Not in TECO-8]}
\fi

\ifnotintecoeight
     \item [{\tt n} \caret {\tt Uq}\escape]     This form  of  the  \caret 
		{\tt Uq}\escape  command  inserts  the  single
               character  whose  ASCII code is {\tt n} into the text storage
               area of Q-register {\tt q}.  (n  is  taken  modulo  256  in
               TECO-11, modulo 128 in other TECOs.)
               {\em [Not in TECO-8]}
\fi

\ifnotintecoeight
     \item [{\tt n:} \caret {\tt Uq}\escape]    This form of  the  
	{\tt :}\caret {\tt Uq}\escape  command  appends  the  single
               character  whose  ASCII  code  is {\tt n} to the text storage
               area of Q-register {\tt q}.  ({\tt n}  is  taken  modulo  256  in
               TECO-11, modulo 128 in other TECOs.)
               {\em [Not in TECO-8]}
\fi

     \item [{\tt @}\caret {\tt Uq/string/}]
     \item [{\tt @:} \caret {\tt Uq/string/}]
     \item [{\tt n@}\caret {\tt Uq//}]
     \item [{\tt n@:}\caret {\tt Uq//}]  Equivalent,   respectively,    to    
	the    \caret {\tt Uqstring}\escape,
               {\tt :}\caret {\tt Uqstring}\escape,  {\tt n}\caret 
	{\tt Uq}\escape,  and  {\tt n:}\caret {\tt Uq}\escape commands, 
	except that
               alternate delimiters are used and no {\tt <DELIM>} characters
               are necessary.

     \item [{\tt nXq}]       Clear Q-register q and move {\tt n} lines 
	into it, where {\tt n} is
               a  signed  integer.   If  {\tt n}  is  positive,  the 
	{\tt n} lines
               following the current pointer position are copied  into
               the  text  storage  area  of  Q-register  q.   If  {\tt n} is
               negative, the {\tt n} lines preceding the pointer are copied.
               If  {\tt n}  is  zero,  the  contents  of the buffer from the
               beginning of the line on which the pointer  is  located
               up to the pointer is copied.  The pointer is not moved.
               The text is not deleted.

     \item [{\tt Xq}]        Equivalent to {\tt 1Xq}.

     \item [{\tt -Xq}]       Equivalent to {\tt -1Xq}.

     \item [{\tt m,nXq}]     Copy  the  contents  of  the  buffer  from  
		the   {\tt m}+1th
               character  through and including the {\tt n}th character into
               the text storage area of Q-register q.  {\tt m} and {\tt n} 
		must be
               positive, and {\tt m} should be less than {\tt n}.

     \item [{\tt .,.+nXq}]   Copy the {\tt n} characters immediately following 
	the  buffer
               pointer  into the text storage area of Q-register q.  {\tt N}
               should be greater than zero.

     \item [{\tt .-n,.Xq}]   Copy the {\tt n} characters immediately 
	preceeding the buffer
               pointer  into the text storage area of Q-register q.  {\tt N}
               should be greater than zero.

\ifnotintecoeight
     \item [{\tt n:Xq}]      Append {\tt n} lines to Q-register q, where  
	{\tt n}  is  a  signed
               integer with the same functions as {\tt n} in the {\tt nXq} command
               above.  The pointer is not moved.
               {\em [Not in TECO-8]}
\fi

               The colon construct for appending to a  Q-register  can
               be used with all forms of the {\tt X} command.

\ifnotintecoeight
     \item [{\tt ]q}]        Pop from the Q-register push-down list into  
	Q-register
               q.    Any   previous   contents  of  Q-register  q  are
               destroyed.  Both the numeric  and  text  parts  of  the
               Q-register  are loaded by this command.  The Q-register
               push-down list is a last-in  first-out  (LIFO)  storage
               area.   (See  section  \ref{Q-register Push-down List}  for  a description of the
               push-down list.) This command does not  use  or  affect
               numeric values.  Numeric values are passed through this
               command transparently.  This allows macros  to  restore
               Q-registers and still return numeric values.
               {\em [Not in TECO-8]}

     \item [{\tt :]q}]       Execute the {\tt ]q} command and return a 
		numeric  value.   A
               -1  indicates  that  there  was  another  item  on  the
               Q-register push-down list to be popped.  A 0  indicates
               that  the  Q-register  push-down  list  was  empty,  so
               Q-register q was not modified.
               {\em [Not in TECO-8]}
\fi

     \item [{\tt *q}]        Save last-typed command string.  See section 
	\ref{Immediate Action Commands}.
\end{list}

     Table \ref{Q-register Retrieval Commands} lists the commands which 
	permit data to  be  retrieved
     from the Q-registers.


\begin{table}[h]
\caption{\bf{Q-register Retrieval Commands}}
\label{Q-register Retrieval Commands}
\end{table}
\nopagebreak
            
\begin{list}{}{\labelsep 20pt}

     \item [COMMAND]        FUNCTION

     \item [{\tt Qq}]        Use the integer stored in the number  storage  
	area  of
               Q-register q as the argument of the next command.

     \item [{\tt nQq}]       Return the ASCII value  of  the  {\em (n+1)}th  
		character  in
               Q-register q.  The argument {\tt n} must be between 0 and the
               Q-register's size minus 1.  If {\tt n} is  out  of  range,  a
               value   of   -1   is  returned.   Characters  within  a
               Q-register are numbered the same way that characters in
               the text buffer are numbered.  The initial character is
               at character position  0,  the  next  character  is  at
               character  position 1, etc.  Therefore, if Q-register A
               contains {\tt xyz} then {\tt 0QA} will return the ASCII code for
               {\tt x} and {\tt 1QA} will return the ASCII code for {\tt y}.

     \item [{\tt :Qq}]       Use the number of characters stored in the 
	text storage
               area  of  Q-register  q  as  the  argument  of the next
               command.

     \item [{\tt Gq}]        Copy  the  contents  of  the  text  storage   
	area   of
               Q-register q into the buffer at the current position of
               the buffer  pointer,  leaving  the  pointer  positioned
               after the last character copied.

     \item [{\tt :Gq}]       Print  the  contents  of  the  text  storage  area   of
               Q-register  q on the terminal.  Neither the text buffer
               nor the buffer pointer is changed by this command.

\ifnotintecoeight
     \item [{\tt [q}]        Copy the contents of the numeric and text storage areas
               of  Q-register  q  into  the Q-register push-down list.
               This command does not alter either the numeric or  text
               storage  areas  of  Q-register  q.   It does not use or
               affect  numeric  values.   Numeric  values  are  passed
               through  this command transparently, allowing macros to
               save temporary Q-registers  and  still  accept  numeric
               values.   (Note,  however,  macros written to use local
               Q-registers, available in TECO-11, may be able to avoid
               saving  and  restoring Q-registers via the the pushdown
               list.) The command sequence {\tt[A]B} replicates  the  text
               string   and  numeric  value  from  Q-register  {\tt A}  into
               Q-register {\tt B}.
               {\em [Not in TECO-8]}
\fi

\end{list}

     Table \ref{Macro Invocation Commands} lists the commands which cause macros (strings  stored
     in Q-registers) to be executed.

     Macro invocations can be nested recursively;  the limit is set by
     the amount of pushdown storage TECO has available.

     In this table only,  a  distinction  is  made  between  a  global
     Q-register  name  (indicated below by {\tt q}) and a local Q-register
     name (indicated below by {\tt .q}).  Elsewhere in  this  manual,  {\tt q}
     indicates either a global or local Q-register name.


\begin{table}[h]
\caption{\bf{Macro Invocation Commands}}
\label{Macro Invocation Commands}
\end{table}
\nopagebreak

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

     \item [COMMAND]        FUNCTION
\nopagebreak
     \item [{\tt Mq}]        Execute the contents of the text storage area 
	of global
               Q-register  q  as  a command string.  In TECO-11, a new
               set of local Q-registers is created before the macro is
               invoked.

     \item [{\tt nMq}]       Execute the {\tt Mq} command as above, 
	using {\tt n} as  a  numeric
               argument  for  the  first  command  contained in global
               Q-register  q.   In  TECO-11,  a  new  set   of   local
               Q-registers is created.

     \item [{\tt m,nMq}]     Execute the {\tt Mq} command as above, 
	using {\tt m,n}  as  numeric
               arguments  for  the  first  command contained in global
               Q-register  q.   In  TECO-11,  a  new  set   of   local
               Q-registers is created.

     \item [{\tt :Mq}]       Execute the contents of the text storage area 
		of global
               Q-register  q  as  a  command  string.  In TECO-11, the
               current set of local Q-registers remains  available  to
               the invoked macro;  no new set is created.

     \item [{\tt n:Mq}]      Execute the {\tt :Mq} command as above, 
	using {\tt n} as a  numeric
               argument  for  the  first  command  contained in global
               Q-register  q.   In  TECO-11,  no  new  set  of   local
               Q-registers is created.

     \item [{\tt m,n:Mq}]    Execute the {\tt :Mq} command as above, 
	using {\tt m,n} as  numeric
               arguments  for  the  first  command contained in global
               Q-register  q.   In  TECO-11,  no  new  set  of   local
               Q-registers is created.

     \item [{\tt M.q}]       Execute the contents of the text storage area 
		of  local
               Q-register  .q as a command string.  In TECO-11, no new
               set of local Q-registers is created.

     \item [{\tt nM.q}]      Execute the {\tt M.q} command as above, 
	using {\tt n} as a  numeric
               argument  for  the  first  command  contained  in local
               Q-register  .q.   In  TECO-11,  no  new  set  of  local
               Q-registers is created.

     \item [{\tt m,nM.q}]    Execute the {\tt M.q} command as above, 
	using {\tt m,n} as  numeric
               arguments  for  the  first  command  contained in local
               Q-register  .q.   In  TECO-11,  no  new  set  of  local
               Q-registers is created.

     \item [{\tt :M.q}]      Execute the contents of the text storage area 
	of  local
               Q-register  .q as a command string.  In TECO-11, no new
               set of local Q-registers is created.

     \item [{\tt n:M.q}]     Execute the {\tt :M.q} command as above, 
	using {\tt n} as a numeric
               argument  for  the  first  command  contained  in local
               Q-register  .q.   In  TECO-11,  no  new  set  of  local
               Q-registers is created.

     \item [{\tt m,n:M.q}]   Execute the {\tt :M.q} command as above, 
	using {\tt m,n} as numeric
               arguments  for  the  first  command  contained in local
               Q-register  .q.   In  TECO-11,  no  new  set  of  local
               Q-registers is created.
\end{list}

