Understanding message types and severity
During execution of a tool, messages are written that can be retrieved with geoprocessing functions, such as GetMessages(). These messages include such information as the following:
- When the operation started and ended
- The parameter values used
- General information about the operation's progress (information message)
- Warnings of potential problems (warning message)
- Errors that cause the tool to stop execution (error message)
All communication between tools and users is done with messages. Depending on where you are running the tools from, messages appear in the Results window, the Python window, and the progress dialog box. From Python, you can fetch these messages within your script, interrogate them, print them, or write them to a file. All messages have a severity property, either informative, warning, or error. The severity is an integer where 0 = informative, 1 = warning, and 2 = error.
|
Severity | |
|---|---|
|
Informative message (severity = 0) |
An informative message is just that—information about execution. It is never used to indicate problems. Only general information, such as a tool's progress, what time a tool started or completed, output data characteristics, or tool results, is found in informative messages. |
|
Warning message (severity = 1) |
Warning messages are generated when a tool experiences a situation that may cause a problem during its execution or when the result may not be what you expect. For example, defining a coordinate system for a dataset that already has a coordinate system defined generates a warning. You can take action when a warning is returned, such as canceling the tool's execution or making another parameter choice. |
|
Error message (severity = 2) |
Error messages indicate a critical event that prevented a tool from executing. Errors are generated when one or more parameters have invalid values or when a critical execution process or routine has failed. |
Both warning and error messages are accompanied by a six-digit ID code. These ID codes have been documented to provide additional information on their causes and how they can be dealt with. When error or warning codes are shown in the tool or progress dialog box, Python window, or Result window, they have a link that allows you to go directly to the additional help for that message.
Getting messages
Messages from the last tool executed are maintained by ArcPy and can be retrieved using the GetMessages function. This function returns a single string containing all the messages from the tool that was last executed. The returned messages can be filtered to include only those with a certain severity using the severity option. When using ArcPy, the first message gives the tool executed, and the last message gives the ending and elapsed time for the tool's execution. The tool's second and last messages always give the start and end time, respectively, for the tool's execution.
Getting geoprocessing messages
import arcpy
# Execute the GetCount tool
#
arcpy.GetCount_management("c:/base/data.gdb/roads")
# Get the resulting messages and print them
#
print arcpy.GetMessages()
# The returned messages would look similar to the following:
# Executing: GetCount c:/base/data.gdb/roads
# Start Time: Wed Apr 07 11:28:21 2010
# Row Count = 373
# Succeeded at Wed April 07 11:28:21 2010 (Elapsed Time: 0.00 seconds)
Individual messages can be retrieved using the GetMessage function. This function has one parameter, which is the index position of the message. The GetMessageCount function returns the number of messages from the last tool executed. The example below shows how to print information about which tool was executed along with ending and elapsed times for the tool.
import arcpy
arcpy.env.workspace = "D:/base/data.gdb"
arcpy.Clip_analysis("roads", "urban_area", "urban_roads")
# Print the first message - tool executed
#
print arcpy.GetMessage(0)
# Print the last message - ending and elapsed times for tool
#
print arcpy.GetMessage(arcpy.GetMessageCount - 1)
Getting messages from a result object
Messages can also be accessed from a tool using a Result object. Unlike getting messages from ArcPy, messages on a Result object can be maintained even after running multiple tools. The Result object supports several of the same functions used to get and interpret geoprocessing tool messages.
|
Properties and methods |
Explanation |
|---|---|
inputCount | Returns the number of inputs. |
|
outputCount |
Returns the number of outputs. |
|
messageCount |
Returns the number of messages. |
|
maxSeverity |
Returns the maximum severity. The returned severity can be 0 (no errors/warnings raised), 1 (warnings raised), or 2 (errors raised). |
|
resultID |
Returns the unique result ID. If the tool is not a geoprocessing service, the resultID will be "". |
|
status |
Returns the status of the job on the server.
|
|
cancel() |
Cancels the job on the server. |
|
getInput(index) |
Returns a given input. If a record set or raster data object, a RecordSet or RasterData object is returned. |
|
getMapImageURL(ParameterList, Height, Width, Resolution) |
Get map service image for a given output. |
|
getMessage(index) |
Returns a specific message. |
|
getMessages(severity) |
The type of messages to be returned: 0=message, 1=warning, 2=error. Not specifying a value returns all message types. |
|
getOutput(index) |
Returns a given output. If a record set or raster data object, a RecordSet or RasterData object is returned. |
|
getSeverity(index) |
Returns the severity of a specific message. |
The following sample runs two geoprocessing tools but waits until the tools are executed before reviewing the messages.
import arcpy
arcpy.env.workspace = "D:/base/data.gdb"
# Execute the Clip and GetCount tools
#
clipResult = arcpy.Clip_analysis("roads", "urban_area", "urban_roads")
countResult = arcpy.GetCount_management("urban_roads")
# Get the resulting messages and print them
#
print clipResult.getMessages()
print countResult.getMessages()
As with geoprocessing tools, server tool messages are classified as either information, a warning, or an error. A message's type is indicated by its severity property, which is a numeric value. The following sample shows how to get the messages from a server tool after it has completed.
import arcpy
import time
# Add the server toolbox
#
arcpy.ImportToolbox("http://lab13/arcgis/services;BufferByVal", "mytools")
featset = arcpy.FeatureSet()
featset.load("//flames/gpqa/coredata/global/redlands/control.shp")
# Run a server tool named BufferPoints
#
result = arcpy.BufferPoints_mytools(featset, "1000 feet")
# Wait until the tool completes
#
while result.status < 4:
time.sleep(0.2)
# Print all messages from the result object
#
print result.getMessages()