Working with result objects



About result objects

The Execute and ExecuteAsync methods of the IGeoProcessor2 interface return IGeoProcessorResult. IGeoProcessorResult can be used to chain more than one process by extracting values returned by the executed tool. The IGeoProcessor interface has methods to get messages. With IGeoProcessorResult, additional information is available, such as the inputs and outputs of the previous tool and status of job execution as well as messages. The following table lists commonly used methods and properties of the IGeoProcessorResult interface:
Method or property
Description
GetMessage
Returns the message description by index. For more information, see How to get returned messages.
GetMessages
Returns all the message descriptions.
MaxSeverity
Returns the maximum severity of the message.
MessageCount
Returns the number of messages.
GetInput
Returns the input by index.
InputCount
Returns the number of inputs.
GetOutput
Returns the output, an IGPValue, by index.
OutputCount
Returns the number of outputs.
ResultID
Gets the job ID.
ReturnValue
Gets the return value of the geoprocessor. For more information, see Tool return values.
Status
Gets the job status.
Cancel
Cancels the job.
The IGeoProcessorResult2 interface has the following additional properties:
Property
Description
IsAsync
Returns whether the process is asynchronous.
IsCanceled
Indicates whether the Cancel method is called.
Process
Sets the geoprocessor process value.
The result object is more useful in a server context. When a geoprocessing service is executed, it always returns a valid result object. However, a geoprocessing tool running locally returns a valid result object when the execution succeeds but throws an exception when it fails.

Getting results from a geoprocessing service

As with geoprocessing tools, geoprocessing services have a fixed set of parameters that provide the tool (the service) with the information it needs for execution. Unlike other tools (core, model, and script), when using geoprocessing services in .NET, the output must be deliberately retrieved by the user instead of automatically by execution of the service. The Execute method returns IGeoProcessorResult, which manages the results. The result object is necessary to support geoprocessing with ArcGIS for Server. This result object will have the return value of a tool when executed; it returns the result ID and the status of a job on the server as well as the geoprocessing messages.
For more information, see the following:

The code example in this section shows how to do the following:
  • Execute a server tool, get the status and messages, and retrieve the feature result. The result is a feature set.
[C#]
public void SampleGeneratingGeoprocessingResults()
{
    // Initialize the geoprocessor.
    Geoprocessor GP = new Geoprocessor();
    // Add the BestPath toolbox.
    GP.AddToolbox(@"http://flame7/arcgis/services;GP/Bestpathtoolbox");
    // Input values are layers on the server.
    IVariantArray parameters = new VarArrayClass();
    parameters.Add(@"source");
    parameters.Add(@"destination");
    // Execute the server tool.
    IGeoProcessorResult2 result;
    result = (IGeoProcessorResult2)GP.Execute("CalculateBestPath", parameters, null);
    // Check the job status.
    while (result.Status != esriJobStatus.esriJobSucceeded)
    {
        Console.WriteLine(result.Status.ToString());
        System.Threading.Thread.Sleep(100);
    }
    // If the job succeeded, retrieve the feature result. 
    if (result.Status == esriJobStatus.esriJobSucceeded)
    {
        IGPValue outVal = result.GetOutput(0);
        parameters.RemoveAll();
        parameters.Add(outVal);
        parameters.Add(@"C:\Data\GPTest.gdb\bestpath");
        GP.Execute("CopyFeatures", parameters, null);
    }
    // Print the resulting messages.  
    for (int Count = 0; Count <= result.MessageCount - 1; Count++)
    {
        Console.WriteLine(result.GetMessage(Count));
    }

}
[VB.NET]
Public Sub SampleGeneratingGeoprocessingResults()
    
    ' Initialize the geoprocessor.
    Dim GP As Geoprocessor = New Geoprocessor()
    
    ' Add the BestPath toolbox.
    GP.AddToolbox("http://flame7/arcgis/services;GP/Bestpathtoolbox")
    
    ' Input values are layers on the server.
    Dim parameters As IVariantArray = New VarArrayClass()
    parameters.Add("source")
    parameters.Add("destination")
    
    ' Execute the server tool.
    Dim result As ESRI.ArcGIS.Geoprocessing.IGeoProcessorResult2
    result = CType(GP.Execute("CalculateBestPath", parameters, Nothing), ESRI.ArcGIS.Geoprocessing.IGeoProcessorResult2)
    
    ' Check the status.
    Do While result.Status <> esriJobStatus.esriJobSucceeded
        Console.WriteLine(result.Status.ToString())
    Loop
    
    ' If the job succeeded, retrieve the feature result.
    If result.Status = esriJobStatus.esriJobSucceeded Then
        Dim outVal As IGPValue = result.GetOutput(0)
        parameters.RemoveAll()
        parameters.Add(outVal)
        parameters.Add("C:\Data\GPTest.gdb\bestpath")
        GP.Execute("CopyFeatures", parameters, Nothing)
    End If
    
    ' Print the resulting messages.
    For Count As Integer = 0 To result.MessageCount - 1
        Console.WriteLine(result.GetMessage(Count))
    Next Count
    
End Sub
Cast the returned result object to IGeoProcessorResult2 to access the IsAsync, IsCanceled, and Process properties.

Getting results from tool execution

When a tool is executed locally, a result object is returned only if the tool runs successfully (that is, if no error is returned from the tool). Caution must be taken when you run a tool locally and attempt to use the result object, because an exception is thrown if the tool fails; and you cannot use the result object, because the flow of control goes to catch block. The workflow is complicated, as shown in the following code example:
[C#]
try
{
    // Copy features.
    // Create a variant array and populate parameters.
    IGeoProcessorResult2 result;
    result = (IGeoProcessorResult2)gp.Execute("CopyFeatures_management", parameters,
        null);
    if (result != null)
    {
        // Use the result object's methods or properties.
        // Use the geoprocessing tool or result object to get messages.
    }
    else
    {
        // The control of code flow may not come into the else block.
        // ...
    }
}

catch (Exception ex)
{
    //
    // Get the geoprocessor error messages.
    // 
}
[VB.NET]
Try
' Execute the Copy Features tool.
' Create a variant array and populate parameters.
Dim parameters As IVariantArray = New VarArray
Dim result As IGeoProcessorResult2
result = CType(gp.Execute("CopyFeatures_management", parameters, Nothing)
If Not result Is Nothing Then
    'Use the result object's methods or properties.
    'Use the geoprocessing tool or result object to get messages.
Else
    'The control of code flow may not come into the else block.
End If
Catch ex As Exception
'
'Get the geoprocessor error messages.
'
End Try
Using Try Catch blocks will catch errors that occur when your code is executed. Read the Errors and exception handling in geoprocessing (link below) for details.


See Also:

Errors and exception handling in geoprocessing
How to run a geoprocessing tool




To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):