Handling RMCLink COM Component Errors

Each method in the RMCLink and RMCLinkServer classes internally returns an error code. When the error code indicates that there was an error, the RMCLink COM component also registers error information for the calling program to have access to. It is then up to the language hosting the RMCLink COM component to decide how this error information be conveyed to the programmer. Each section below describes how RMCLink errors will be handled in various languages.

Visual Basic 5.0/6.0, VBA, and VBScript Error Handling

The entire Visual Basic family hides the error return value. Instead, the interpreter evaluates the error code returned itself and if it indicates failure, invokes the current error handler. The error handler is controlled using the On Error statement. There are three possible values, On Error GoTo 0, OnError Resume Next, and On Error GoToLabel. In Visual Basic 5.0/6.0 and VBA, the On Error statement applies to the current method. In VBScript, it applies from that time forward in the file.

On Error GoTo 0 - This is the default error handler. When an exception is thrown, the application crashes. This is typically not an acceptable way to handle communication errors, but works fine for catching programming errors during development.
On Error Resume Next - With this option, the program always continues with the statement after the method call, even if an exception was thrown. However, notice that an Err object is updated when an exception is thrown. Therefore, you can programmatically check to see if an error was thrown.
On Error GoTo Label - With this option, the program jumps to the requested label. The code at that label can then access the Err object and process it accordingly.

The example below uses On Error GoTo Label for Visual Basic and VBA and On Error Resume Next for VBScript.

As mentioned above, the Err object can be used to determine the type of the error. Two important members of this object are the Number and Description properties. The Number property will hold a value from the RMCLinkError enumeration after an RMCLink method throws an exception. The Description property will give a text description of the failure.

JScript Error Handling

JScript hides the error return value. Instead, the interpreter evaluates the error code itself and if it indicates failure, throws an exception. This exception can be caught by using a try-catch block. The Number property of the exception object in the catch block will give the value of the error return code from the method. However, notice that the value is the real value returned and it not adjusted like it is in Visual Basic. This means that the values of Error.Number will be 2,146,828,288 less than the RMCLinkError enumeration values. For example, the out of memory condition (rmcEOutOfMemory) is defined as 5. Under JScript Error.Number will be rmcEOutOfMemory minus 2,146,828,288 or -2,146,828,283.

LabVIEW Error Handling

Each method will return any errors in the error out terminal. However, notice that the values will not match the RMCLinkError enumeration, but will have the value 2,146,828,288 subtracted from it. That is, instead of the value 5 (rmcEOutOfMemory) for an out of memory condition, the error out will be -2,146,828,283 (rmcEOutOfMemory - 2,146,828,288).

COM Error Handling in Other Languages

If none of the above languages match your COM component hosting method, then you will need to refer to your host documentation for details on how COM errors/exceptions are handled. In order to help you determine how RMCLink errors will appear in your language, the following information describes the underlying error information available to the language.

Each RMCLink and RMCLinkServer method internally returns the COM data type HRESULT. This data type is a 32-bit integer, which communicates not only if the method failed or succeeded, but also, on failure, it will give a code that indicates the cause. In addition to this error code, when any of the methods in the RMCLink and RMCLinkServer classes returns an error, it will also register an IErrorInfo object for access by the host language.

There are two main decisions that a host language has to make with regards to how COM errors are handled. First, it must decide whether the method syntax will return the HRESULTs or if they will hide this implicit return value. Notice that this documentation does not show the implied HRESULT return value, and instead parameters flagged as [retval] show up as the actual return value. This is the approach taken by all of Visual Basic 5.0/6.0, Visual Basic for Applications (VBA), VBScript, and JScript. When the language chooses to hide the HRESULT return value, it must handle the error in another way. Typically an exception is called (JScript) or the current error handler is invoked (VB5, VB6, VBA, VBScript).

The next decision that the host language must make is how to convey the error number itself. As stated above, the real return type from each method is of type HRESULT, which is a 32-bit number. All error values have bit 31 set, and therefore, the numbers are very large. They make sense when viewed as hexadecimal, but many high-level languages did not want to require users to look at hexadecimal. Therefore, the Visual Basic series (VB5, VB6, VBA, VBScript) all decided to subtract off 0x800A0000 from all errors returned in the range of 0x800A0000-0x800AFFFF. The resulting numbers are what is enumerated in RMCLinkError. However, other languages (e.g. JScript) return the error numbers as is.

Example

The following code example illustrates the proper use of COM exceptions.

Visual Basic 6 / VBA

Option Explicit
 
Public Sub Sample()
    ' Declare and create the RMCLinkServer COM object.
    Dim srv As New RMCLinkServer
 
    ' Use our RMCLinkServer to create the correct type of RMCLink object.
    Dim rmc As RMCLink
    Set rmc = srv.CreateEthernetLink(dtRMC70, "192.168.0.22")
 
    ' Request that we jump to CommError (below) to handle errors.
    On Error GoTo CommError
 
    ' Establish the connection.
    rmc.Connect
 
    ' Read F8:8 and F8:9 (Axis 0 Actual Position and Velocity)
    Dim data As Variant
    data = rmc.ReadFFile(fn70StatusAxis0, 8, 2)
    resultText = "Actual Position = " & data(0) & ", Actual Velocity = " & data(1)
 
    ' Close the connection.
    rmc.Disconnect
    Exit Sub
 
CommError:
    resultText = "Error #" & Err.Number & ": " & Err.Description
End Sub

VBScript

Option Explicit
On Error Resume Next  ' Indicate that we will handle errors.
Dim srv, rmc, data
  
' First we need to create the RMCLinkServer COM object.
Set srv = CreateObject("RMCLink.RMCLinkServer")
 
' Use our RMCLinkServer to create the correct type of RMCLink object.
' NOTE: VBScript does not support enumerations, so we use the literal value (dtRMC70=2).
Set rmc = srv.CreateEthernetLink(2, "192.168.0.22")
 
' Establish the connection.
rmc.Connect
 
' Skip trying to read if the connection could not be established.
If Err = 0 Then
    ' Read F8:8 and F8:9 (Axis 0 Actual Position and Velocity)
    data = rmc.ReadFFile_Script(8,8,2)
 
    ' Only display the results if the read succeeded.
    If Err = 0 Then
        WScript.Echo "Actual Position = " & data(0) & ", Actual Velocity = " & data(1)
    End If
 
    ' Close the connection.
    rmc.Disconnect
End If
 
If Err.Number <> 0 Then
    WScript.Echo "Error #" & Err.Number & ": " & Err.Description
End If

JScript

try
{
    // First we need to create the RMCLinkServer COM object.
    var srv = new ActiveXObject("RMCLink.RMCLinkServer");
 
    // Use our RMCLinkServer to create the correct type of RMCLink object.
    // NOTE: JScript does not support enumerations, so we use the literal value (dtRMC70=2).
    var rmc = srv.CreateEthernetLink(2, "192.168.0.22");
 
    // Establish the connection.
    rmc.Connect();
 
    // Read F8:8 and F8:9 (Axis 0 Actual Position and Velocity)
    var data = rmc.ReadFFile_Script(8,8,2).toArray();
    WScript.echo("Actual Position = " + data[0] + ", Actual Velocity = " + data[1]);
 
    // Close the connection.
    rmc.Disconnect();
}
catch (e)
{
    WScript.echo("Error #" + e.number + ": " + e.description);
}