🚀 go-pugleaf

						      PPPPlllluuuussss FFFFiiiivvvveeee



	  subject: Error Trap Mechanism		      date: May	5, 1987

						      from: Hokey



				      _A_B_S_T_R_A_C_T



	  X11 Proposal:	A comprehensive	error trapping facility	for MUMPS.











































	  501-0.15		     May 5, 1987		     Page i







						      PPPPlllluuuussss FFFFiiiivvvveeee



	  subject: Error Trap Mechanism		      date: May	5, 1987

						      from: Hokey



				    _X_1_1__P_r_o_p_o_s_a_l



	  Document #501-0.15










































	  501-0.15		     May 5, 1987		     Page 1








		  Copyright 1987 Plus Five Computer Services, Inc.



	  1.  BBBBAAAACCCCKKKKGGGGRRRROOOOUUUUNNNNDDDD

	  Earlier error	trap proposals have not	had the	flexibility to
	  support all the common mechanisms in use by existing
	  (implementation-specific) routines.  Specifically, an	error trap
	  facility should support processing of	traps at:

	    1.	a "cleared" stack,

	    2.	particular DO/XECUTE levels,

	    3.	every DO/XECUTE	level.

	  Additionally,	different software packages should be able to
	  utilize any of the aforementioned mechanisms independently.

	  This proposal	supports these mechanisms, and additionally
	  supplies backtrace information.



































	  501-0.15		     May 5, 1987		     Page 2








		  Copyright 1987 Plus Five Computer Services, Inc.



	  2.  TTTTHHHHEEEE AAAAPPPPPPPPLLLLIIIICCCCAAAATTTTIIIIOOOONNNNSSSS LLLLEEEEVVVVEEEELLLL IIIINNNNTTTTEEEERRRRFFFFAAAACCCCEEEE

	  The following	special	variables are of immediate interest:

		  $ECode
		  $ELine
		  $EStack
		  $ETrap
		  $STacklevel

	  2.1  $$$$EEEECCCCooooddddeeee

	  When an error	occurs,	$ECode is loaded with information which
	  identifies the error condition.

	  $ECode can be	SET.  When $ECode is SET, the value of $ELine is
	  modified.  If	$ECode is set to the empty string, the value of
	  $ELine is updated to be 0, and any subscripts	of $Eline are
	  KILLed.  Otherwise, the value	of $ELine is updated to	be 2, any
	  existing subscripts of $ELine	are KILLed, and	the appropriate
	  data is loaded into the first	2 subscripts of	$ELine.

	  2.1.1	 SSSSyyyynnnnttttaaaaxxxx

	  $EC[ode] ::= , L <ecode> , | <SEP> <msgstring> | ...

	  <ecode> ::= {M,I,U}[ecodestring]
		      <ecode>s beginning with:
			  M are	reserved for the MDC
			  I are	reserved for the implementor
			  U are	reserved for the user
			  anything else	are reserved

	  <SEP>	::= _	  (Note: or something else.  A control character?)

	  <ecodestring>	::= <any graphic characters except comma and SEP>

	  <msgstring> ::= <any graphic characters except SEP>

	  2.1.2	 EEEExxxxaaaammmmpppplllleeeessss


		  $ECode=",ISyntax,_expected closing ')'"

		  $ECode=",IIO,_File Won't Open_Permission denied"








	  501-0.15		     May 5, 1987		     Page 3








		  Copyright 1987 Plus Five Computer Services, Inc.



	  2.2  $$$$EEEELLLLiiiinnnneeee

	  $ELine holds backtrace information regarding the point at which
	  an error condition occurred, and may contain code or data as
	  well.

	  $ELine takes initial values as the value of $ECode changes.  If
	  an error condition is	not being processed, $Eline is extended	as
	  DO, XECUTE, or indirection levels are	popped,	thereby	providing
	  backtrace information.

	  The value of $ELine is the last subscript which contains data	in
	  the subscripted form of $ELine.

	  The actual address information and code or data is stored in
	  subscripts of	$ELine.	 Odd numbered subscripts of $Eline contain
	  the <place> reporting	the error, while even numbered subscripts
	  contain the value (in	the case of indirection) or the	<line> (or
	  the empty string if the <line> is not	available) for which the
	  condition is being reported.

	  2.2.1	 SSSSyyyynnnnttttaaaaxxxx

			 | [[tag][+offset][^routine]][SP+offset] |
	     <place> ::= |					 |
			 | @[+offset]				 |

		     NOTE: regardless of the syntactic definition,
		     <place> will always resolve to a non-empty	string.

	  2.2.2	 EEEExxxxaaaammmmpppplllleeeessss

		       w @a    where a="b" and b is undefined:

		       $EL=4
		       $EL(1)="	+4"
		       $EL(2)="w @a"
		       $EL(3)="@+1"
		       $EL(4)="b"

	  2.3  $$$$EEEESSSSttttaaaacccckkkk

	  $EStack can be NEWed.	 NEW $EStack causes the	"old" value of
	  $EStack to be	saved and the "new" value of $EStack to	be zero.
	  The value of $EStack is incremented as DO/XECUTE levels are
	  encountered, and decremented or replaced from	the NEW	stack as
	  these	levels are exited.






	  501-0.15		     May 5, 1987		     Page 4








		  Copyright 1987 Plus Five Computer Services, Inc.



	  2.3.1	 SSSSyyyynnnnttttaaaaxxxx

	  2.3.2	 EEEExxxxaaaammmmpppplllleeeessss

			  New $EStack
			  Set $ETrap="Quit:'$EStack  Break"

	  2.4  $$$$EEEETTTTrrrraaaapppp

	  2.4.1	 SSSSEEEETTTT $$$$EEEETTTTrrrraaaapppp

	  $ETrap contains code which is	"executed" in the event	an error
	  condition occurs.  A "traditional" mumps routine might specify

				  S $ET="G ^etrap"

	  as its error trap function.

	  2.4.1.1  _S_y_n_t_a_x

	  Extend a <setargument> to include:

			       $ET[rap]	= <etrapvalue>

			       <etrapvalue> ::=	<expr>

	  2.4.1.2  _E_x_a_m_p_l_e_s

	  Set $ETrap="Quit:'$EStack  Goto tag^routine"

	  2.4.2	 NNNNEEEEWWWW $$$$EEEETTTTrrrraaaapppp

	  $ETrap can be	NEWed.	This is	the only mechanism provided for
	  stacking $ET.

	  (One of the following	should be specified):

	    1.	$ETrap (does not retain)/(retains) its value after being
		NEWed.

		  a.  specified	by MDC

		  b.  specified	by Implementor

		  c.  specified	by User	(changeable by user)

	    2.	NEW $ETrap:"[NO]KEEP"

	    3.	NEW $ETrap[:"[NO]KEEP"]	and choice 1




	  501-0.15		     May 5, 1987		     Page 5








		  Copyright 1987 Plus Five Computer Services, Inc.



	  Changing the value of	$ETrap instantiates a new trap;	it does	not
	  save the old trap.

	  A QUIT from $ETrap, either explicit or implicit (i.e., s $ET="d
	  ^etrap" has an implicit QUIT at its end) will	function as if a
	  QUIT had been	issued at the "current"	$STacklevel.  Behavior at
	  the "popped" level will be determined	by the value of	$ECode.	 If
	  $ECode is empty, execution proceeds normally.	 Otherwise, $ETrap
	  is invoked at	the new	level.

	  A HALT from $ETrap will pop the stack	back to	the most recent
	  direct mode level or NEWed $ETrap level, or, finally,	out of
	  mumps.

	  2.4.2.1  _S_y_n_t_a_x

	  2.4.2.2  _E_x_a_m_p_l_e_s

	  2.5  $$$$SSSSTTTTaaaacccckkkklllleeeevvvveeeellll

	  $STacklevel contains the current level of the	DO/XECUTE stack.

	  2.5.1	 SSSSyyyynnnnttttaaaaxxxx

	  2.5.2	 EEEExxxxaaaammmmpppplllleeeessss




























	  501-0.15		     May 5, 1987		     Page 6












			 X11 Proposal: Error Trap Mechanism
				  TABLE	OF CONTENTS



	  1.  BACKGROUND................................................  2

	  2.  THE APPLICATIONS LEVEL INTERFACE..........................  3

	  2.1  $ECode...................................................  3
	  2.1.1	 Syntax.................................................  3
	  2.1.2	 Examples...............................................  3

	  2.2  $ELine...................................................  4
	  2.2.1	 Syntax.................................................  4
	  2.2.2	 Examples...............................................  4

	  2.3  $EStack..................................................  4
	  2.3.1	 Syntax.................................................  5
	  2.3.2	 Examples...............................................  5

	  2.4  $ETrap...................................................  5
	  2.4.1	 SET $ETrap.............................................  5
	  2.4.1.1  Syntax...............................................  5
	  2.4.1.2  Examples.............................................  5
	  2.4.2	 NEW $ETrap.............................................  5
	  2.4.2.1  Syntax...............................................  6
	  2.4.2.2  Examples.............................................  6

	  2.5  $STacklevel..............................................  6
	  2.5.1	 Syntax.................................................  6
	  2.5.2	 Examples...............................................  6





















					- i -