Error Return Functoid

 

Use the Error Return functoid ( ) to capture error information, such as database connection failures, that occur during run time.

Input

Parameter 1: A link from a Database Lookup functoid.

Output

Output 1: The error string, if any, returned by Open Database Connectivity (ODBC) when using the functoid.

Remarks

Use this functoid in conjunction with the Database Lookup and Value Extractor functoids to capture and map error information. Some of the scenarios this might be useful include:

• When your map has a Database Lookup or Value Extractor functoid that is not behaving as expected. To see the error message, temporarily map the functoid to a field in the output schema.

• If your application expects different message content when database operations fail. You can use the Error Return functoid to detect an error and map the error message to an alternate structure so that downstream applications can react in a controlled manner.

To avoid errors that are only detected at run time, make sure that the parameter 1 to the Error Return functoid is the output of a Database Lookup functoid and not the output of any other functoid in the Database category.

Sample

In the following mapping, a Database Lookup functoid is used to retrieve the last name of a person based on their first name. If no error is encountered and a last name exists, the Value Extractor functoid copies it to the destination schema. Any error thrown by the Database Lookup functoid during the query will be caught by the Error Return functoid and copied to the error message field in the destination schema.

Error Return Sample Map

To test, configure the Database Lookup functoid with an invalid table as shown below.

Invalid Table Name for Database Lookup Functoid

The value for Input[1] is “Provider=SQLNCLI10;Server=localhost;Database=Contoso; Trusted_Connection=yes;

If the lookup table name is incorrect, the output message would be similar to the one below. If “authors” is an invalid table name, an error message is encountered which is stored in the “ErrorMessage” node.

<ns0:SampleSource xmlns:ns0="http://Sample">  
    <Person>  
        <FirstName>FirstName_0</FirstName>  
        <LastName />  
        <ErrorMessage>Invalid object name 'authors'.</ErrorMessage>  
    </Person>  
</ns0:SampleSource>  

This is one example of an error message. There are many different types of possible error messages including connection failures, stored procedure problems, environment issues, SQL exceptions, etc. Downstream processes could monitor the ErrorMessage field and process or route the message appropriately.

See Also

Database Functoids Reference
Database Functoids
How to Add Basic Functoids to a Map