OBJRESULT function

Purpose

Returns a status code (hResult) to describe the success or failure of the most recent METHOD or PROPERTY procedure.

Syntax

lResult& = OBJRESULT

Remarks

An Automation procedure is a METHOD or PROPERTY on an IAUTOMATION, IDISPATCH, or DUAL interface.  By definition, an Automation procedure always returns a hidden result code which is cryptically called an hResult.  OBJRESULT the most recent hResult generated by the program, and can be used to identify the success or failure of an operation.

If an Automation procedure fails with a severe error, the ERR system variable is set to an appropriate PowerBASIC error code.  This is usually Error 99 ("Object error").  In such cases, you can use the OBJRESULT function to return the result (hResult&) of the last run-time OBJECT statement or direct METHOD/PROPERTY reference.

Numeric equates for most OBJRESULT errors can be found in the WIN32API.INC file, and are mostly prefixed with %E_, %CO_, %OLE_, and %DISP_.  The following list includes the most common codes that may be returned by a direct call of a Method or Property:

%S_OK                    = &H0
%S_FALSE                 = &H1
%E_UNEXPECTED            = &H8000FFFF&
%E_NOTIMPL               = &H80004001&
%E_NOINTERFACE           = &H80004002&
%E_POINTER               = &H80004003&
%E_ABORT                 = &H80004004&
%E_FAIL                  = &H80004005&
%E_ACCESSDENIED          = &H80070005&
%E_HANDLE                = &H80070006&
%E_OUTOFMEMORY           = &H8007000E&
%E_INVALIDARG            = &H80070057&

This list tells the most common status codes which may be returned by a DISPATCH call using the OBJECT statement:

%S_OK                    = &H0
%DISP_E_ARRAYISLOCKED    = &H8002000D
%DISP_E_BADINDEX:        = &H8002000B
%DISP_E_BADPARAMCOUNT    = &H8002000E
%DISP_E_BADVARTYPE       = &H80020008
%DISP_E_EXCEPTION        = &H80020009
%DISP_E_MEMBERNOTFOUND   = &H80020003
%DISP_E_NONAMEDARGS      = &H80020007
%DISP_E_OVERFLOW         = &H8002000A
%DISP_E_PARAMNOTFOUND    = &H80020004
%DISP_E_TYPEMISMATCH     = &H80020005
%DISP_E_UNKNOWNINTERFACE = &H80020001
%DISP_E_UNKNOWNLCID      = &H8002000C
%DISP_E_UNKNOWNNAME      = &H80020006
%DISP_E_PARAMNOTOPTIONAL = &H8002000F

If the status code %DISP_E_EXCEPTION is returned, you can use the IDISPINFO object to secure much additional information about the status. This includes a more specific error code, a description, help file information, etc.  If the status code %DISP_E_PARAMNOTFOUND or %DISP_E_TYPEMISMATCH, you can use IDISPINFO.PARAM to determine which parameter actually caused the problem.  Please refer to the IDISPINFO section for more details.

As can be seen from the above lists, a large numeric status code can be cryptic.  However, you can translate the OBJRESULT code into a descriptive message using the OBJRESULT$ function. This can be most helpful, especially during application development and debugging.

Restrictions

Methods and Properties on a custom interface (a direct interface based upon IUnknown rather than IDispatch) do not support OLE Automation, and do not return an OBJRESULT (hResult).

See also

DIM, CLASS, CLSID$, IDISPINFO, GUID$, GUIDTXT$, INTERFACE (Direct), INTERFACE (IDBind), ISINTERFACE, ISNOTHING, ISOBJECT, LET (with Objects), METHOD, PROPERTY, OBJECT, OBJACTIVE, OBJEQUAL, OBJPTR, OBJRESULT$, PROGID$, What is an hResult?, What is an object, anyway?