This tutorial illustrates how
to use the exception data type to
create and throw exceptions. It also shows how to use the try-catch
statements to capture exceptions and process them. Exceptions are used
to create, throw, and capture errors, warnings, failures, and other
types of special messages (including user-defined messages).
To begin this tutorial, open and save an ASCII text file as described
in the Hello World tutorial. Name
the script 'Exceptions.psc'.
The tutorial starts with the creation of an 'exception' variable. This
variable will be used throughout the tutorial.
| Example
Code |
Line |
Code |
1
2
3
4
5
|
#
This tutorial illustrates the usage of
# exceptions and try/catch
#
Declare an exception data type
exception ex; |
Next, a try-catch statement is set up. All statements in the try portion
of the try-catch will be executed normally. If an error, warning, or
other exception occurs (no OK exceptions), execution will immediately
move to the catch portion of the try-catch. The catch portion receives
the caught exception as its parameter (in this case 'exception e').
Using this parameter, the catch statement can get information about
the exception, including the exception type and the message in the exception.
The statements in the catch portion can ignore the exception (as in
this case), re-throw the exception so it is processed normally, or perform
any other task.
In this case, the exception variable created earlier is used to create
an error (using SetError) with
a user defined message. The exception is thrown (using the 'throw'
method) manually so that it is caught in the catch section. This is
simply to illustrate that an exception thrown manually through the use
of an exception variable is caught and processed in a try-catch statement.
For this tutorial, the exception is ignored, after printing the exception
message to the screen (via disp and
the exception GetMessage method).
| Example
Code |
Line |
Code |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
|
# This
tutorial illustrates the usage of
# exceptions and try/catch
# Declare an exception
data type
exception ex;
# Will set up a try/catch to handle the
# exception when thrown
try{
# Define the exception as an error
ex.SetError("Sample Error");
# Throw the exception. It will be
# handled in the catch section.
ex.throw();
}catch (exception e){
# See what the message was of the caught
# exception
disp("Message: " + ex.GetMessage());
} |
This next part of the script is similar to the first try-catch statement,
with the only difference being instead of using a user-generated exception
(via the exception variable), an internally created error will be
generated and caught in the catch statement. The function call to
'NonFunction' tries to call a function that does not exist. This would
normally generate an error in Phantom and halt script execution. However,
in a try-catch statement, the error can be processed. Again, in this
case the error will simply be ignored, after printing its message
to the screen. In a normal script, the processing could be used to
clean up a testcase by closing windows and applications or perform
other operations.
| Example
Code |
Line |
Code |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
|
# This
tutorial illustrates the usage of
# exceptions and try/catch
# Declare an exception
data type
exception ex;
# Will set up a try/catch to handle the
# exception when thrown
try{
# Define the exception as an error
ex.SetError("Sample Error");
# Throw the exception. It will be
# handled in the catch section.
ex.throw();
}catch (exception e){
# See what the message was of the caught
# exception
disp("Message: " + ex.GetMessage());
}
# Now, an internally generated Phantom
# error will be processed by a try/catch
try{
disp("Creating an error");
# This is a non-existing function:
NonFunction();
}catch (exception e){
# View the exception message
disp("Message: " + e.GetMessage());
} |
The next section will create a user defined warning (using the SetWarning
member). The warning is thrown without a try-catch statement to illustrate
how Phantom responds to un-caught warnings. For a warning, a message
is displayed by Phantom, but the script does not terminate.
| Example
Code |
Line |
Code |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
|
# This
tutorial illustrates the usage of
# exceptions and try/catch
# Declare an exception
data type
exception ex;
# Will set up a try/catch to handle the
# exception when thrown
try{
# Define the exception as an error
ex.SetError("Sample Error");
# Throw the exception. It will be
# handled in the catch section.
ex.throw();
}catch (exception e){
# See what the message was of the caught
# exception
disp("Message: " + ex.GetMessage());
}
# Now, an internally generated Phantom
# error will be processed by a try/catch
try{
disp("Creating an error");
# This is a non-existing function:
NonFunction();
}catch (exception e){
# View the exception message
disp("Message: " + e.GetMessage());
}
# Create a warning. This will not
# terminate the script.
ex.SetWarning("Sample Warning");
ex.throw(); |
Finally, an error exception is generated (via SetError)
and thrown without a try-catch. Phantom will display an error message
to the screen and terminate the script. Any statements after the error
is thrown will not be processed.
| Example
Code |
Line |
Code |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
|
# This
tutorial illustrates the usage of
# exceptions and try/catch
# Declare an exception data type
exception ex;
# Will set up a try/catch to handle the
# exception when thrown
try{
# Define the exception as an error
ex.SetError("Sample Error");
# Throw the exception. It will be
# handled in the catch section.
ex.throw();
}catch (exception e){
# See what the message was of the caught
# exception
disp("Message: " + ex.GetMessage());
}
# Now, an internally generated Phantom
# error will be processed by a try/catch
try{
disp("Creating an error");
# This is a non-existing function:
NonFunction();
}catch (exception e){
# View the exception message
disp("Message: " + e.GetMessage());
}
# Create a warning. This will not
# terminate the script.
ex.SetWarning("Sample Warning");
ex.throw();
# If an error exception is created and
# thrown, or if one occurs internally,
# and is not processed in a try/catch
# then the script will terminate.
ex.SetError("Terminating Error");
ex.throw();
# The script will now have exited because
# the error was not processed. |
Save this script and run it as described in the Hello World tutorial.
The output should look like the following:
| Output |
Message:
Sample Error
Creating an error
Message: Unrecognized statement 'NonFunction'. (2020)
** WARNING: (1) from 'Exceptions.psc' on line 38 - Sample Warning
** ERROR: (1) from 'Exceptions.psc' on line 45 - Terminating Error |
The next tutorial goes through
a simple automation and verification case.
