System Function ES

From NARS2000
Jump to: navigation, search

Quad ES - Event Simulate - ⎕ES     System Function

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

Monadic Function

⎕ES R
R 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.
⎕ES 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.


Quad ES ⎕ES Event Simulate - sample monadic use/user session(with comments using ⍝ symbol):

      ⎕VR 'ErrorSim'  ⍝Virtual representation of user-function ErrorSim. It has one right argument, A.
    ∇ ErrorSim A
[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).
[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).
[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:   ⍝ 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; A = 0 (test evaluates to True).
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

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 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/triggered the event to occur.
  • It can be used, for example, to generate various return codes on system resource limitations encountered, see ⎕ET.

Dyadic Function

Not Currently Documented - Although Dyadic Event Simulate ⎕ES Use is implemented in some APL versions.


Note: ⎕ES is available as both a monadic and dyadic form system function, you cannot assign a value to it.

System Variables (A value may be assigned to these except for ⎕DM)
ALX CT DM DQ DT ELX FC FEATURE FPC IC
IO LX PP PR PW RL SA WSID
Niladic System Functions (a value cannot be assigned to these)
A AV EM ET LC NNAMES NNUMS SI SYSID SYSVER
T TC TCBEL TCBS TCESC TCFF TCHT TCLF TCNL TCNUL
TS WA
Monadic or dyadic system functions (a value cannot be assigned to these)
AT CR DC DL DR EA EC ERROR ES EX
FMT FX MF NAPPEND NC NCREATE NERASE NINFO NL NLOCK
NREAD NRENAME NREPLACE NRESIZE NSIZE NTIE NUNTIE STOP TF TRACE
UCS VR
Note that quad functions and variables are case insensitive