Index | PAL Intro | Commands | Registers | Indices | Stack | Macros | Classes | Attributes | Errors

error/jmp - Adds or removes error traps

CONTENTS

Synopsis
Description
The Error Handler
Examples
See Also
Author

error/jmp #group, &[.codeptr], ![objectref] <, ![objectref] ... >

error/jmp &[.codeptr], ![objectref] <, ![objectref] ... >

error/jmp #group, ![objectref] <, ![objectref] ... >

error/jmp ![objectref] <, ![objectref] ... >

error/jmp #group, &[.codeptr]

error/jmp &[.codeptr]

error/jmp #group

error/jmp

This instruction can be used to define groups of errors that are to be caught by specific error handlers, or it can define default error handlers, or remove error trap definitions.

An error handler (or trap) is a section of code that will be called automatically if one of a set of error conditions occur. Which conditions cause which error handler to be called are defined by this instruction.

An error type is an object in the nexus that describes the error. A number of pre-defined system error types can be found under .prose.error.sys in the nexus, and which are described in the ps_errortypes(5) man page. New error types can be defined using the error/def instruction.

Group numbers are used to collect together a set of error types that can be be handled by a single error handler. When that error handler is called, due to one of these error types occurring, the group definition (and all those with higher group numbers) are deleted.

The group argument is a raw index that will match the last group number defined by this instruction, or the next consecutive group number. If it is omitted, the default of 0 is assumed.

If a codeptr argument is provided, then it points to the error handler code. If this argument is omitted, then the instruction will delete error traps instead of creating them.

The objectref arguments, of which one or more may be provided, point to the error type definitions in the nexus that should be added to the error handler. If this argument is omitted, then a default error handler is configured. A default error handler is called with all errors that have occurred that haven’t been specifically caught by another trap definition.

When an error condition is triggered, either by the PROSE engine, an API, or by use of the error/now instruction, the error handler is called if a trap has been defined that matches the error type, or if it has been defined as a default error handler.

Errors that are not caught by a trap defined within the scope of the group, will be passed on to the previous group, and the previous, until the top-most group (number 0) is reached. If the error is not trapped by group 0, then it is passed up to the previous function in the stack which will follow the same process, and so on until an error handler is found, or the thread exits. When untrapped errors cause an implied func/rtn (or local/rtn if in the ._init section), registers containing the type PSUNIT_TYPE_STRING, PSUNIT_TYPE_XVALUE or PSUNIT_TYPE_LIST are cleared as if reg/clr was called on them. See reg_clr (5).

When the error handler code is called, register PERR is set to point to the error type. The error handler may use error/clr to clear the error condition, or error/now (with no arguments) to cause the error to be passed up to the next handler.

The following demonstrates the use of error traps and error handlers.

.main   % Set-up a default error handler (group 0) % and a separate handler for OutOfMemory errors error/jmp &[.error0] error/jmp &[.error_nomem], ![.prose.error.sys.OutOfMemory] .some_code   % Then comes some code ... .new_scope   % And now to catch a specific error within its own scope % For this we use group 1 instead of group 0 error/jmp #1, &[.error1], ![.prose.error.sys.AccessDenied] .more_code   % Some more code, which may trigger AccessDenied ... .end_scope   % Now we’re not interested in AccessDenied anymore error/jmp #1 func/rtn .error1   % AccessDenied error has occurred % PERR will point to .prose.error.sys.AccessDenied reg/dump PERR error/clr func/rtn .error_nomem   % OutOfMemory error has occurred % PERR will point to .prose.error.sys.OutOfMemory reg/dump PERR error/clr func/rtn .error0   % This is the default error handler % PERR will point to the error type % % If it’s an error you really can’t handle, % pass it up the stack like this... error/now

pal_commands(5), pal_indices(5), ps_errortypes(5), error_def(5), error_now(5), reg_clr(5),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2011 Mark R. Bannister <cambridge@users.sourceforge.net>.

This is free software and can be downloaded from prose.sourceforge.net; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.