System Function ES - Revision history

Robert Wallick: minor wording

2015-02-20T23:28:14Z

minor wording

← Older revision		Revision as of 19:28, 20 February 2015
Line 54:		Line 54:
	When is ⎕ES useful?		When is ⎕ES useful?
	* You want to specifically get the user's attention when a certain error, input error, or other frequent error condition can/could occur.		* You want to specifically get the user's attention when a certain error, input error, or other frequent error condition can/could occur.
	* You want to show a More Detailed Error Message ~~show~~ when a known error occurs.		* You want to show a More Detailed Error Message when a known error occurs.
	* You are debugging a certain area of APL user-function code and want to test simulating the error condition(s).		* You are debugging a certain area of APL user-function code and want to test simulating the error condition(s).
	* Since program/code suspension occurs at the CALLING POINT, not within the defined operation/user function per se, it translates to more focus on the input or arguments which may have caused the event to occur.		* Since program/code suspension occurs at the CALLING POINT, not within the defined operation/user function per se, it translates to more focus on the input or arguments which may have caused/triggered the event to occur.
	* It can be used, for example, to generate various return codes on system resource limitations encountered, see ⎕ET.<br>		* It can be used, for example, to generate various return codes on system resource limitations encountered, see ⎕ET.<br>

Robert Wallick: minor wording

2015-02-20T23:24:59Z

minor wording

Robert Wallick: created system function quad Event Simulate ⎕ES page

2015-02-20T23:17:16Z

created system function quad Event Simulate ⎕ES page

New page

<h1>Quad ES - Event Simulate - '''⎕ES'''     System Function</h1>

Event Simulate [with either Error Message(⎕EM) or Event Type(⎕ET)] - for debugging, user alerts, detailed at-length error messaging purposes.

==Monadic Function==
<table border="1" cellpadding="5" cellspacing="0" rules="none" summary="">
<tr>
<td>
<table border="0" cellpadding="5" cellspacing="0" summary="">
<tr>
<td valign="top"><apll>⎕ES R</apll></td>
<td></td>
<td></td>
<td></td>
</tr>
</table>
</td>
</tr>
<tr>
<td><apll>R</apll> may frequently be one of three distinct Cases: 1) Simple character scalar or vector; 2) Simple two-item vector of integers, 'normally' between -32767 and 32767; or 3) An empty vector.</td>
</tr>
<tr>
<td><apll>⎕ES</apll> does not have a Z type return argument. It's effect on the APL interpreter is to show on the user's display, certain debugging information, depending on how the call to ⎕ES was made.</td>
</tr>

</table>
<br />
'''Quad ES''' ⎕ES Event Simulate - sample ''monadic'' use/user session(with comments using ⍝ symbol):
<pre>
⎕VR 'ErrorSim' ⍝Virtual representation of user-function ErrorSim. It has one right argument, A.
∇ ErrorSim A
[1] ⍝Simulate an error. If the test inside the parentheses evaluate to True then Event IS simulated.
[2] ⎕ES(0=A)/'ZERO INVALID' ⍝Event Simulate occurs here, if A=0 then a user/SysOp error message will appear(in System Variable ⎕EM).
[3] '⎕ET(Event Type) = ',⎕ET ⍝ ⎕ES frequently affects sys var quad Event Type ⎕ET, although not in presently in NARS.
[4] '⍴⎕EM(Error Message) = ',(⍴⎕EM),' ⎕EM:' ⍝ ⎕EM IS affected in NARS - IF the Error Condition evaluate to True(1).
[5] ⎕EM
∇ 2015 2 20 22 31 5 647 (UTC)

ErrorSim 45 ⍝ <<< In this event simulation(user types in ErrorSim 45), there should be NO EFFECT since 45 is not equal to 0.
⎕ET(Event Type) = 0 0 ⍝ As mentioned ⎕ET remains unaffected = {0 0}
⍴⎕EM(Error Message) = 3 0 ⎕EM: ⍝ ⎕EM is also unaffected - it has 3 empty rows(0 cols).

ErrorSim 0 ⍝ <<< In this event simulation(user types in ErrorSim 0), there SHOULD BE an EFFECT since 0 = 0.
ZERO INVALID ⍝ Sure enough, the Error Message ⎕EM is returned by NARS/APL with ⎕EM = 'ZERO INVALID'
ErrorSim 0 ⍝ Normally APL would also return the user-function line number which 'failed' here ⎕ES returns zero.
∧
⎕EM ⍝ Sure enough, ⎕EM when typed in by user, shows the most recent simulated error message from ⎕ES.
ZERO INVALID
ErrorSim 0
∧
⎕ET ⍝ Also note that ⎕ET was not affected even though in some APL implementations ⎕ES can/will affect ⎕ET.
0 0
</pre>
When is ⎕ES useful?
* You want to specifically get the user's attention when a certain error, input error, or other frequent error condition can/could occur.
* You want to show a More Detailed Error Message show when a known error occurs.
* You are debugging a certain area of APL user-function code and want to test simulating the error condition(s).
* Since program/code suspension occurs at the CALLING POINT, not within the defined operation/user function per se, it translates to more focus on the input or arguments which may have caused the event to occur.
* It can be used, for example, to generate various return codes on system resource limitations encountered, see ⎕ET.<br>

==Dyadic Function==
Not Currently Documented - Although Dyadic Event Simulate ⎕ES Use is implemented in some APL versions.<br><br>
{{SFDM|ES}}

← Older revision		Revision as of 19:24, 20 February 2015
Line 30:		Line 30:
	⎕VR 'ErrorSim' ⍝Virtual representation of user-function ErrorSim. It has one right argument, A.		⎕VR 'ErrorSim' ⍝Virtual representation of user-function ErrorSim. It has one right argument, A.
	∇ ErrorSim A		∇ ErrorSim A
	[1] ⍝Simulate an error. If the test inside the parentheses evaluate to True then Event IS simulated.		[1] ⍝Simulate an error. If the test (next line, just below) inside the parentheses evaluate to True then Event IS simulated.
	[2] ⎕ES(0=A)/'ZERO INVALID' ⍝Event Simulate occurs here, if A=0 then a user/SysOp error message will appear(in System Variable ⎕EM).		[2] ⎕ES(0=A)/'ZERO INVALID' ⍝Event Simulate occurs here, if A=0 then a user/SysOp error message will appear(in System Variable ⎕EM).
	[3] '⎕ET(Event Type) = ',⎕ET ⍝ ⎕ES frequently affects sys var quad Event Type ⎕ET, although not in presently in NARS.		[3] '⎕ET(Event Type) = ',⎕ET ⍝ ⎕ES frequently affects sys var quad Event Type ⎕ET, although not presently in NARS.
	[4] '⍴⎕EM(Error Message) = ',(⍴⎕EM),' ⎕EM:' ⍝ ⎕EM IS affected in NARS - IF the Error Condition evaluate to True(1).		[4] '⍴⎕EM(Error Message) = ',(⍴⎕EM),' ⎕EM:' ⍝ ⎕EM IS affected in NARS - IF the Error Condition evaluate to True(1).
	[5] ⎕EM		[5] ⎕EM
Line 39:		Line 39:
	ErrorSim 45 ⍝ <<< In this event simulation(user types in ErrorSim 45), there should be NO EFFECT since 45 is not equal to 0.		ErrorSim 45 ⍝ <<< In this event simulation(user types in ErrorSim 45), there should be NO EFFECT since 45 is not equal to 0.
	⎕ET(Event Type) = 0 0 ⍝ As mentioned ⎕ET remains unaffected = {0 0}		⎕ET(Event Type) = 0 0 ⍝ As mentioned ⎕ET remains unaffected = {0 0}
	⍴⎕EM(Error Message) = 3 0 ⎕EM: ⍝ ⎕EM is also unaffected - it has 3 empty rows(0 cols).		⍴⎕EM(Error Message) = 3 0 ⎕EM: ⍝ Since there was NO error(no event simulation) ⎕EM is also unaffected - it has 3 empty rows(0 cols).

	ErrorSim 0 ⍝ <<< In this event simulation(user types in ErrorSim 0), there SHOULD BE an EFFECT ~~since 0~~ = 0.		ErrorSim 0 ⍝ <<< In this event simulation(user types in ErrorSim 0); there SHOULD BE an EFFECT; A = 0 (test evaluates to True).
	ZERO INVALID ⍝ Sure enough, the Error Message ⎕EM is returned by NARS/APL with ⎕EM = 'ZERO INVALID'		ZERO INVALID ⍝ Sure enough, the Error Message ⎕EM is returned by NARS/APL with ⎕EM = 'ZERO INVALID'
	ErrorSim 0 ⍝ Normally APL would also return the user-function line number which 'failed' here ⎕ES returns zero.		ErrorSim 0 ⍝ Normally APL would also return the user-function line number which 'failed' here ⎕ES returns zero.