PyRAF ECL Support

Overview

PyRAF can now support the error handling constructs of IRAF's ECL scripting language. In addition to PyRAF's classic Python exception handling, PyRAF's ECL support enables certain errors to be trapped and to cause exception handling statements to execute.

PyRAF's ECL captures the following errors:

• System exceptions (FPE, segfault, etc) thrown by compiled tasks (i.e. SPP or C)
• error() calls from compiled tasks
• error() calls from CL scripts
• division by zero in CL scripts

Activating ECL Support

During it's introduction, PyRAF's ECL support is optional and is only activated by one of the following means:

pyraf -e

pyaf –ecl

epyraf

setenv PYRAF_USE_ECL 1

In the absence of the above methods, PyRAF runs without ECL support.

New ECL Keywords

PyRAF's ECL support uses the following words as keywords, i.e. words which are part of ECL and can no longer be used as program identifiers (i.e. variable, task, or procedure names):

• iferr

• ifnoerr

• then

ECL Grammar Extensions

PyRAF's support for ECL includes two new symmetric statements, iferr and ifnoerr. iferr is used to describe what should be done when an error occurs in a group of guarded statements, and ifnoerr is used to emphasize what should be done when an error does not occur in a group of guarded statements. A “guarded statement” is essentially a block of ordinary CL statements for which errors should be trapped. An “except action” are the statement(s) which should be executed when an error occurs (iferr) or does not occur (ifnoerr). An “else action” are the statement(s) which should be executed when an error occurs. Below is the section of the PyRAF grammar which describes ECL iferr statements; IFERR, IFNOERR, THEN, and ELSE denote keyword literals:

iferr_stmt    ::= if_kind guarded_stmt except_action
iferr_stmt    ::= if_kind guarded_stmt opt_newline THEN except_action
iferr_stmt    ::= if_kind guarded_stmt opt_newline THEN except_action opt_newline ELSE else_action
if_kind       ::= IFERR
if_kind       ::= IFNOERR                
guarded_stmt  ::=  { opt_newline statement_list }
except_action ::= compound_stmt
else_action   ::= compound_stmt

A compound statement can be a single statement or block of statements.

ECL Syntax Examples

The simplest form of ECL error statement is a block of guarded statements followed by a single handler statement which should execute when one or more of the guarded statements fail. The then keyword is optional in this form. A curious property of ECL error handling is that all guarded statements execute, even those following the first failed statement. This contrasts sharply with Python's exception handling model which performs it's traceback immediately following the first error.

iferr {
<guarded statements>
} <error-handler statement>


iferr {
<guarded statements>
} then
<error-handler statement>

When a block of error handler statements is desired, the then keyword should be used to be compatible with ECL. An optional else clause may be used to specify what to do when the guarded statements all succeed; either the then clause or the else clause is executed, but never both.

iferr {
<guarded statements>
} then {
<error-handler statements>
} else {
<non-error-handler statements>
}

There is a symmetric form of iferr which uses the keyword ifnoerr. It is perhaps most useful when one doesn't want to specify anything to handle an error, but only specify what to do when the guarded statements succeed. ifnoerr is effectively iferr with the error-handling and success-handling statements reversed.

ifnoerr {
<guarded statements>
} then {
<non-error statements>
} 



ifnoerr {
<guarded statements>
} then {
<non-error statements>
} else {
<error handling statements>
}

ECL Pseudo Variables

PyRAF in ECL mode defines the following pseudo variables which are associated with each task object:

$errno

$errtask

$errmsg

$err_dzvalue

Since pseudo variables are associated with a task object, they have several properties:

1. They are persistent, i.e. not cleared until a task is re-run, and only then based on erract's clear field. They are however overwritten with each new error.

2. They can be accessed in CL code as written in the table above.

3. They can be accessed from the command line using DOLLAR notation after a traceback has occurred:

   --> iraf.failed_task.DOLLARerrno

   57

   --> iraf.failed_task.DOLLARerrmsg

   'becuz something went wrong...'

   --> iraf.failed_task_caller.DOLLARerrtask

   failed_task

4. They are not re-entrant – i.e., recursive procedures using them are only referring to a single storage location and will interfere with one another, only recording the last error.

ECL Functions

PyRAF in ECL mode defines the following error handling functions which are analogous to the pseudo variables and easier to use.

error()

errno()

errmsg()

errtask()

Division By Zero

PyRAF's ECL mode now traps division by zero and either raises and ECL exception or returns the default result value contained in the variable $err_dzvalue.

So in ECL, the following guarded code:

iferr {
$err_dzvalue = 33
print 1/0
}

Outputs:

Warning on line 6 of 'nested5':  divide by zero - using $err_dzvalue = 33
33

While un-guarded code such as:

$err_dzvalue = 33
print 1/0

Generates a traceback and outputs:

ERROR (1): divide by zero
   'print 1/0'
      line 4: /home/jmiller/nested5.cl
Traceback (innermost last):
  File "<CL script CL1>", line 8, in <module>
IrafError: ERROR: divide by zero
                                                                                                                                                                                

Controlling ECL Behavior using erract

PyRAF's ECL mode behavior is controlled by a multi-field environment variable named erract. erract is set in PyRAF as a string containing one or more field modifiers.

--> show erract
abort trace flpr clear full ecl

Multiple fields may be changed with a single “set” command, and not all fields need be specified. Fields not mentioned in a set statement retain their old values.

--> set erract="noflpr noclear"

--> show erract
abort trace noflpr noclear full ecl

abort / noabort

trace / notrace

flpr / noflpr

clear / noclear

full / nofull

ecl  / noecl