RCI errors and warnings

RCI responses may contain RCI errors or warnings to indicate that a requested command did not complete normally.

Message type	Description
<error>	An error occurred and the operation failed.
<warning>	An RCI command was executed, but a warning was issued. Changes were made, but not all requested changes were successful.

More than one error or warning may be present in a reply. The location of the <error> or <warning> tag implies the scope of the error. The parent element of <error> or <warning> is the source of the error/warning. For example, in this RCI code, a <set_setting> command experienced an error and the command failed to execute. The caller can assume that none of the requested <set_setting> changes occurred.

<rci_reply version=”1.1”>
  <set_setting>
    <error id=”1”>
      <desc>Operation unavailable</desc>
    </error>
  </set_setting>
</rci_reply>

The following example shows that an error occurred while setting the <serial> group. An error under <serial> implies that no changes were made to the <serial> group, even if baud is the only invalid field; that is, group level sets are treated atomically. Note also that the <system/> element was returned without an error, so the <system> set was successfully applied.

<rci_reply version=”1.1”>
 <set_setting>
   <serial>
    <error id=”2”>
      <desc>Invalid baud”</desc>
      <hint>baud</hint>
    </error>
   </serial>
   <system/>
 </set_setting>
</rci_reply>

This example shows the same situation, except a <warning> is returned instead of an error. This indicates to the caller that the <serial> group was changed as requested, but a problem was encountered and the changes may not be as expected. Again, the requested <system> set was successful.

<rci_reply version=”1.1”>
 <set_setting>
  <serial>
   <warning id=”2”> 
     <desc>Invalid baud</desc> 
     <hint>baud</hint>
   </warning>
  </serial>
  <system/>
 </set_setting>
</rci_reply>

This example shows a similar error, except that the <error> is more precisely placed as a child of the <baud> field. Note, however, that since the <baud> field encountered an error, the entire serial group does not get saved. Generally, if an error occurs inside a setting group, the entire group is not saved. The <set_setting> command is special in this way. Usually, if an <error> occurs as a child of a command (or any descendent) the command fails and changes do not take place.

<rci_reply version=”1.1”>
 <set_setting>
  <serial>
   <baud>
     <error id=”2”>
       <desc>Invalid baud</desc>
     </error>
   </baud>
  </serial>
  <system/>
 </set_setting>
</rci_reply>