Traps

See also:

Testing which traps have been set - sys.Traps
Traps in report programs

Several Sculptor commands may be assigned traps. Using a trap allows the programmer to override the default action taken by Sculptor if a particular condition occurs when the command is executed.

Syntax

statement trap = label [trap = label] …

If the command results in the condition specified by the trap, control passes to the line specified by label. A trap clause forms part of the command to which it relates. Several traps may be attached to a single command. The traps permitted for a command are specified in the syntax description of that command. Attempts to attach a trap to a command that may not take that trap are rejected by the compiler.

The available traps are summarised below, together with the commands with which they can be used:

Trap

Commands

Meaning

bs

input

User has backspaced from the first control specified in the input command.

cancel

dialog

The CANCEL key or the button defined as the cancel button has been pressed.

eoi

input

User has pressed the END OF INPUT key during this input statement.

err

open #, get #, put #, seek #

Sequential file access error.

fe

openfile , open #

The file to be newly created already exists.

ni

input

The input command caused no change to be made to any of the controls in its input list.

nrs

delete, write, check

No record was selected in the record buffer specified.

nsf

openfile , open #

No such file exists.

nsr

find[u], match[u], next[u], nextkey, prev[u], prevkey, read, readkey, testkey

No such record exists.

re

insert, write

Record already exists with the specified key.

riu

find, insert, match, next, prev, read, readlock, writelock

Record in use (locked).

traps

all

Any trap not more specifically trapped. .

ue

delete, write

Update error on ODBC database.

EXAMPLES

insert Contacts re = REC_EXISTS

Cust.NameRef = tmp.NameRef
testkey Cust nsr = NO_REF

ConfigFile.Key = "*"
read ConfigFile nsr = GC_NORECORD riu = GC_LOCKED

Special labels

The IGNORE label

Any trap clause may specify the special label IGNORE . This prevents the default action for the condition specified by the trap, without offering an alternative course of action. Control simply passes to the next statement.

If a trappable condition has occurred but no action has been taken because of the IGNORE label, the event has still been noted by the setting of the relevant bits in the special system variable sys.Traps. This variable may be tested by the program to determine the result of the trappable operation.

See The traps = clause below.

EXAMPLE:

read Names nsr = IGNORE riu = E20

The BREAK label

The special BREAK label may be used in a trap clause to terminate a for, while or do loop, or the case section of a switch statement. Control is passed to the statement following the closing brace if the trapped condition occurs. The label is functionally equivalent to the break command.

The BREAKIF label

The BREAKIF label is used in a trap clause to break out of a block of statements controlled by the if or else clause of an if construct. The label is functionally equivalent to the breakif command.

The CONTINUE label

The CONTINUE label may be used in a trap clause to terminate the current iteration of for, while or do loop. The loop continues with the next iteration only if the condition controlling the loop evaluates as true. The label is functionally equivalent to the continue command.

The traps = clause

The special clause

traps = label

clause may be used with any command which supports traps. It provides a label for all those traps supported by the command that have not been explicitly trapped. The label may be IGNORE, BREAK, BREAKIF or CONTINUE, or any labelled line within the program.

Note that there is a subtle difference between specifying

traps = IGNORE

for a command, and specifying IGNORE for each trap individually. If a new trap condition is added to the command in a future version of Sculptor, it will still be ignored if traps = IGNORE is used. But if the traps are listed individually, then the new condition will be untrapped and will cause the default action to be executed.

EXAMPLE

read Names traps = IGNORE

Untrapped conditions

If a condition that may be trapped occurs but is not trapped, i.e.:

read Names

the default action is executed. The default action is determined as follows:

1

If a report is running, i.e. a run report is being executed, an untrapped nsr causes a null record to be returned. Other untrapped errors apart from riu are ignored. An untrapped riu causes the program to wait until the required record becomes available. See Traps in report sections.

2

Otherwise, if the untrapped condition is riu, the message Waiting… is displayed, and the command is retried every three seconds until successful.

3

Otherwise, if there is an active menu, an untrapped error causes the current dialog or input to be terminated and control passed to the menu.

4

If there is no active menu, the program exits.

It is strongly recommended that all errors are trapped. If no action is to be taken when an error occurs, correct practice is to use the IGNORE label:

trap_condition = IGNORE
traps = IGNORE

See Special labels.