API and Command Error Handling

<< Click to Display Table of Contents >>

Navigation:  NxLib API > HowTo's >

API and Command Error Handling

API and Command Errors

When using NxLib you can encounter two different types of errors:

•API errors: these happen when a read or write operation to a tree item fails. This might happen when you try to modify a read-only item (like the camera's serial number of status node), or you try to read a value from an inexistent item (i.e. the path specified in the read operation does not correspond to a node in the tree).
API errors are reported directly via return codes or exceptions, depending on which of the overloaded read/write functions you use.

•Command execution errors: the execution of commands via the Execute node at the tree root level is a concept that is built on top the tree read/write functionality. A command is executed after writing its name into the Command node. A separate thread takes care of the command execution and clears the Command node (sets it to the JSON value Null) after the command has finished executing. If the command execution thread encounters problems during the command it will create a node /Execute/Result/ErrorSymbol and /Execute/Result/ErrorText. ErorrSymbol serves as a unique, constant identifier for the error type and ErrorText contains an English human readable explanation of what happened. The user should therefore check for the existence of the ErrorSymbol node after each command execution to determine if the command suceeded. When using the NxLibCommand classes to execute commands the existence of ErrorSymbol is checked automatically and an exception with the error code NxLibExecutionFailed is generated.

Error Handling with Exceptions

Using our C++ or C# classes error handling can conveniently done with exceptions by encapsulating code blocks like this:

hmtoggle_plus1C++

try {
   // Code block using NxLib's C++ classes NxLibItem and NxLibCommand. These might throw and 
   // exception of type NxLibException.
   ...
} catch (NxLibException& e) {
   // Errors related to accessing the parameter tree are directly contained as return codes. 
   // NxLibCommand can return the special return code 'NxLibExecutionFailed' to indicate that 
   // the executed command returned more error information in the ErrorSymbol and ErrorText nodes.
   
   // Create an item referencing the result node
   NxLibItem result = NxLibItem()[itmExecute][itmResult];
   if (e.getErrorCode() == NxLibExecutionFailed) {
      // A command has failed to execute successfully. Print all information to identify what happened.
      printf("The execution of a command failed with error %s. Message: %s.\n", 
         result[itmErrorSymbol].asString().c_str(), 
         result[itmErrorText].asString().c_str());
      printf("The full command and all parameters in JSON format of the failed command were:\n%s\n", 
         result[itmExecute].asJson(true).c_str());
   } else {
      // Access to some tree node failed. Print the error code and corresponding text.
      printf("An NxLib API error %s occurred when accessing the item %s. Message: %s.\n", 
         e.getErrorCode().c_str(), 
         e.getItemPath().c_str(),
         e.getErrorText().c_str());
   }
}
hmtoggle_plus1Halcon/HDevelop

open_framegrabber ('Ensenso-NxLib', 0, 0, 0, 0, 0, 0, 'default', 0, 'Raw', -1, 'false', 'Item', '/', 0, 0, RootHandle)
 
try
    * Code block using Ensenso-NxLib framegrabber functions
catch (Exception)
    * Errors related to accessing the parameter tree are directly contained as return codes. 
    * NxLibCommand can return the special return code 'NxLibExecutionFailed' to indicate that 
    * the executed command returned more error information in the ErrorSymbol and ErrorText nodes.
    
    get_framegrabber_param (RootHandle, 'error_code', ErrorCode)
    if (ErrorCode == 17)
       * A command has failed to execute successfully. Print all information to identify what happened.
       get_framegrabber_param (RootHandle, 'Execute/Result/ErrorSymbol', ErrorSymbol)
       get_framegrabber_param (RootHandle, 'Execute/Result/ErrorText', ErrorText)
       throw ('The execution of a command failed with error ' + ErrorSymbol + '. Message: ' + ErrorText)
    else
       * Access to some tree node failed. Print the error code and corresponding text.
       get_framegrabber_param (RootHandle, 'error_item', ErrorItem)
       get_framegrabber_param (RootHandle, 'error_text', ErrorText)
       throw ('An NxLib API error ' + ErrorCode + ' occurred when accessing the item ' + ErrorItem + '. Message: ' + ErrorText)
    endif
endtry

Error Handling with Return Codes

It is also possible to handle errors by checking return codes of each NxLib function call.

A list of return codes of the read/write functions can be found in the API Return Codes topic.

Reading/Writing Tree Nodes

For the case of reading or writing a tree error handling could look like this:

hmtoggle_plus1C/C++

// Read a parameter on a camera with serial number "1234"
 
int result;
char const* cameraStatus = nxLibGetString(&result, "/Cameras/BySerialNo/1234/Status");
 
if (result == NxLibOperationSucceeded) {
   printf("The camera status is %s\n.", cameraStatus);
} else {
   char const* errorText = nxLibTranslateReturnCode(result);
   printf("Could not read status node due to error %d. Message %s\n.", result, errorText);
}

Command Execution

hmtoggle_plus1C/C++

// Execute the Capture command on the camera with serial number "1234" and check for errors
 
int result;
nxLibSetString(&result, "/Execute/Parameters/Cameras", "1234");
// Check 'result' of write operation as under 'Reading/Writing Tree Nodes' above
...
 
nxLibSetString(&result, "/Execute/Command", "Capture");
// Check 'result' of write operation as under 'Reading/Writing Tree Nodes' above
...
 
// The command "Capture" is now executing. When it's finished the /Execute/Command node will be cleared and set to 'null'.
 
// Wait for the command to finish (i.e. wait for the Command node to become 'null' again
nxLibWaitForType(&result, "/Execute/Command", NxLibItemTypeNull, true);
// Check 'result' of wait operation as under 'Reading/Writing Tree Nodes' above
...
 
// Now we must check if the command returned an error by looking at the /Execute/Result/ErrorSymbol node:
// if it exists, we can use the ErrorSymbol and ErrorText nodes to identify what happended,
// otherwise the command execution was successful
 
int type = nxLibGetType(&result, "/Execute/Result/ErrorSymbol");
// If the command execution succeeded the ErrorSymbol node should not exists and nxLibGetType should return the api error
// 'NxLibItemInexistent' and type should be NxLibItemTypeInvalid. When the ErrorSymbol exists the type should be NxLibItemTypeString.
if (result == NxLibItemInexistent && type == NxLibItemTypeInvalid) {
   printf("The capture command succeeded\n.");
} else {
   NXLIBSTR errorSymbol = nxLibGetString(&result, "/Execute/Result/ErrorSymbol");
   NXLIBSTR errorText   = nxLibGetString(&result, "/Execute/Result/ErrorText");
   NXLIBSTR failedCommandInfo = nxLibGetJson(&result, "/Execute/Result/Execute", true, 6, false);
   if (errorSymbol && errorText && failedCommandInfo) {
      printf("Image capture failed with error %s. Message %s\n. Failed command with parameters:\n%s\n", errorSymbol, errorText, failedCommandInfo);
   } else {
      printf("Something went wrong. We could not read out ErrorSymbol, ErrorText or the failing command info from /Execute/Result.\n");
   }
}