IDISPINFO pseudo-object

Purpose

Sets and returns additional information about certain Dispatch Status Codes for the OBJRESULT function.

Syntax

info& = IDISPINFO.CODE
info&
= IDISPINFO.CONTEXT
info$
= IDISPINFO.DESC$
info$
= IDISPINFO.HELP$
info$
= IDISPINFO.SOURCE$
IDISPINFO.CLEAR
IDISPINFO.SET code& [, source$, desc$, help$, context&]

Remarks

GET Properties

IDISPINFO.CODE

When OBJRESULT is %DISP_E_EXCEPTION, this Get Property returns a long integer value which represents a more specific error code.  If the value is less than 65536, it is known as a WCODE, which is usually defined by the application when found in 32-bit or 64-bit Windows. Much more common are the larger values known as an SCODE.  These are usually defined by Windows, although application defined values are allowed.  The most common are:

        %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&

IDISPINFO.CONTEXT

When OBJRESULT is %DISP_E_EXCEPTION, this Get Property returns a long integer value which is the context of the topic within the help file (IDISPINFO.HELP$).  This property is only valid if IDISPINFO.HELP returns a valid string.

IDISPINFO.DESC$

When OBJRESULT is %DISP_E_EXCEPTION, this Get Property returns a string containing a textual, human-readable description of the status.  It is intended to be read by the customer.  If no description is available, a null, zero-length string is returned.

IDISPINFO.HELP$

When OBJRESULT is %DISP_E_EXCEPTION, this Get Property returns a string containing drive, path, and filename of a Help File with more information about this particular status code.  If no help is available, a null, zero-length string is returned.

IDISPINFO.PARAM

When OBJRESULT is either %DISP_E_PARAMNOTFOUND or %DISP_E_TYPEMISMATCH, this Get Property returns a long integer value which represents the parameter number of the first parameter which failed to match the requirements needed.  The value is indexed to zero, which is the standard numbering convention for Dispatch parameters.  The first parameter is 0, the second is 1, and so on.

IDISPINFO.SOURCE$

When OBJRESULT is %DISP_E_EXCEPTION, this Get Property returns a string containing a textual, human-readable description of the source of the exception.  Typically, this will be the application name.  If no source is available, a null, zero-length string is returned.

SET Properties

IDISPINFO.CLEAR

Clears all properties which may have been set by prior execution of IDISPINFO.SET in this thread.

IDISPINFO.SET

This statement may be executed in a METHOD or PROPERTY on a Dual Interface, so that the calling code can obtain additional information about Dispatch exception conditions.  These five data items are passed back to the caller in the EXCEPINFO structure, so that they can be retrieved with IDISPINFO GET Properties, or other functions in other programming languages.  This data is only available when using the Dispatch interface.  It is unavailable to Direct Methods.  The first parameter (code&) is required, and must be identical to the value which you return with METHOD OBJRESULT or PROPERTY OBJRESULT.  The actual OBJRESULT will then be changed to %DISP_E_EXCEPTION, so that the caller will know that this data must also be retrieved.  Note that the last four parameters are optional.

Restrictions

You should only execute the GET PROPERTY methods listed above when OBJRESULT returns the specified status code.  In any other case, IDISPINFO Get Properties will return zero or a null string.

See also

OBJECT, OBJRESULT, OBJRESULT$, What is an object, anyway?, What is DISPATCH?

Example

IDISPINFO.SET &H80004040, "MyApp", "Valve stem error","C:\Help.chm", 1773