Phantom Documentation

[Help Home] [Phantom Home]
Exceptions Tutorial

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.


Copyright 2000-2011 Phantom Automated Solutions