Error Handling

The API uses a generic COM error object to handle errors. Depending on the programming environment, languages have their own protocols to retrieve errors from the generic error object. For example, C++ and Visual Basic .NET use exception handling to handle errors. To ensure a stable application, it is recommended that API clients use error handling to trap potential errors such as attempting to access an object that was deleted, or attempting to access an empty collection.

Example 30

The following example illustrates error handling using C++. It assumes that there is a Model Object object from Example 9:

long GetObjectProperties(ISCModelObjectPtr & scObjPtr)
{    
     // Get the collection of Properties
     ISCModelPropertyCollectionPtr scPropColPtr;
     try
     {
         scPropColPtr = scObjPtr->GetProperties();
         if (!scPropColPtr.GetInterfacePtr())
         {
              AfxMessageBox("Unable to Get Properties Collection");
              return FALSE;
         }
         // …
     }
     catch(_com_error &error)
     {
          AfxMessageBox(error.Description());
     }
}

The following example illustrates error handling using Visual Basic .NET. It assumes that there is a Model Object object from Example 9:

Public Sub GetObject(ByRef scSession As SCAPI.Session, ByRef objID As String)
     Dim scObjCol as SCAPI.ModelObjects
     Dim scObj as SCAPI.ModelObject
     
     Try
         scObjCol = scSession.ModelObjects
         scObj = scObjCol.Item(objID)  ' retrieves object with given object ID
     Catch ex As Exception
         ' Failed
         Console.WriteLine(" API Failed With Error message :" + ex.Message())
     End Try
End Sub

In addition to the generic error object, the API provides an extended error handling mechanism with the Application Environment Message log. The message log can handle a sequence of messages that is useful in a context of complex operations like transactions.

More information about the Application Environment Message log organization is located in the Property Bag for Application Environment section.