Error checking and validation

For many methods and properties of the Rational® ClearQuest® API, you must check the return value to validate whether or not the call returns an error.

For calls to functions that return an object, you need to check for the condition if the specified object does not exist. For example, if you call the Item method of a collection object, if the object that you specify is not in the collection, the return value is:
- For Perl, an undefined object. You can use
```
if (!defined($result)) { ... }; 
```
  to detect this condition.
- For VBScript, an error (E_INVALIDARG) that can be handled by the On Error statement.
For calls to functions that have an error String return value, the value is empty if there is no error, or a String containing the description of the error. You can check the result of calling the method and if the value is not empty, you can retrieve the error in a variable, as a String value.
For example the Entity object SetFieldValue method is defined as returning a String value. It returns an empty String if changes to the field are permitted and the operation is successful; otherwise, if the operation fails, this method returns a String containing an explanation of the error.

To trap the error, your code must check the return value. For example:
```
strRetVal = SetfieldValue ("Invalid_field", "Invalid value")

If "" <> strRetVal Then

    REM handle the error

End If
```
If an incorrect field is specified, an error is returned. For example:
```
The Defect SAMPL00000123 does not have a field named "Invalid_field".
```

You should also write code to handle potential exception failures. Trap exceptions by executing API methods within an eval{} statement for Perl. For example,

# trap exceptions and error message strings
# ...
    eval { $RetVal = ${$CQEntity}->Validate(); };
    # EXCEPTION information is in $@
    # RetVal is either an empty string or contains a failure message string
    if ($@){
	print "Exception: '$@'\n";
	# other exception handling goes here...
	   }
    if ($RetVal eq "")
         {# success...
         }
    else {
	  # failure...
	  # return the message string  here...
	 }

For VBScript, use an On Error statement to trap exceptions. For more information, see VBScript error handling and Perl error handling. The Action commit hook example provides examples of error and exception handling when calling the Commit method.