Handle Exception
(AI Studio Core)
Synopsis
This is a nested operator that is used for exception handling. This operator executes the operators in its Try subprocess and returns its results if there is no error. If there is an error in the Try subprocess, the Catch subprocess is executed instead and its results are returned.Description
The Handle Exception operator is a nested operator i.e. it has two subprocesses: Try and Catch. This operator first tries to execute the Try subprocess. If there is no error i.e. the execution is successful, then this operator returns the results of the Try subprocess. In case there is any error the process is not stopped. Instead, the Catch subprocess is executed and its results are delivered by this operator. The error message can be saved using the exception macro parameter. This Try/Catch concept is like the exception handling construct used in many programming languages. You need to have a basic understanding of macros if you want to save the error message using the exception macro. Please study the documentation of the Extract Macro operator for basic understanding of macros. For more information regarding subprocesses please study the Subprocess operator. Please use this operator with care since it will also cover unexpected errors.
Input
in (IOObject)This operator can have multiple inputs. When one input is connected, another in port becomes available which is ready to accept another input (if any). The order of inputs remains the same. The Object supplied at the first in port of this operator is available at the first in port of the nested chain (inside the subprocess). Do not forget to connect all inputs in the correct order. Make sure that you have connected the right number of ports at the subprocess level.
Output
- out (IOObject)
This operator can have multiple out ports. When one output is connected, another out port becomes available which is ready to deliver another output (if any). The order of outputs remains the same. The Object delivered at the first out port of the subprocess is delivered at the first out port of the outer process. Don't forget to connect all outputs in the correct order. Make sure that you have connected the right number of ports at all levels of the chain.
Parameters
- exception_macroThis parameter specifies the name of the macro which will store the error message (if any). This macro can be accessed by other operators by using '%{macro_name}' syntax. Range: string
- add_details_to_logIndicates if the stack trace and details of the handled exception should be also added to the log files in addition to a simple warning message. Range: boolean
Tutorial Processes
Using Try/Catch for exception handling
The goal of this Example Process is to deliver the 'Iris' data set after renaming its attributes. In case there is an error, the original 'Iris' data set should be delivered along with the error message.
The 'Iris' data set is loaded using the Retrieve operator. A breakpoint is inserted here so that you can have a look at the ExampleSet. You can see that there are four regular attributes a1, a2, a3 and a4. The Handle Exception operator is applied next. Have a look at the subprocesses of this operator. The Rename operator is applied in the Try subprocess for renaming the attributes. The from attribute and to attribute parameters of the Rename operator are deliberately left empty which is an error because these are mandatory parameters. The Catch subprocess takes the original ExampleSet and applies the Log operator and delivers the ExampleSet without modifications to the output. The Log operator is used for recording the error message in case there is an error.
Execute the process and switch to the Results Workspace. You can see that the attributes of the ExampleSet have not been renamed. This is because there was an error in the Try subprocess, therefore it was not executed. The error message can be seen in the log which says that values for mandatory parameters of the Rename operator were not provided. The original ExampleSet can be seen in the Results Workspace because when the Handle Exception operator encountered an error in the Try subprocess, it stopped its execution and executed the Catch subprocess instead and delivered its results.
Now set the from attribute and to attribute parameters of the Rename operator to 'From' and 'To' respectively and run the process again. This time you can see that the attributes have been renamed and there is no error message. This is so because the Handle Exception operator first tried to execute the Try subprocess. Since there was no error in it, its results were delivered and the Catch subprocess was not executed.
