SAMPLE: OPTARG: Optional Parameters with Automation

ID: Q131052

The information in this article applies to:

Microsoft OLE Libraries for Windows and Win32s, version 2.03

Microsoft OLE libraries included with:

    - Microsoft Windows NT version 3.5
    - Microsoft Windows 95

SUMMARY

OPTARG is an OLE Automation server application that demonstrates automation methods with optional parameters and variable number of parameters. It implements an Add method that takes optional parameters and a Multiply method that takes a variable number of parameters.

See the README.TXT included with the sample for details to compile and run.

MORE INFORMATION

The following file is available for download from the Microsoft Software Library:

 ~ OPTARG.EXE (size: 35703 bytes)

For more information about downloading files from the Microsoft Software Library, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q119591
   TITLE     : How to Obtain Microsoft Support Files from
               Online Services

Optional parameters are implemented by marking the parameter with the optional attribute and by using VARIANT as the type of the parameter. If the controller omits a parameter, the method will be passed a VARIANT with VARIANT.vt = VT_ERROR and VARIANT.scode = DISP_E_PARAMNOTFOUND.

Variable parameters are implemented by marking the method with the vararg attribute and by providing a parameter of type SAFEARRAY(variant). This array will contain the variable number of parameters passed by the controller.

Note that vararg methods do not have the upper limit of parameters that methods with optional parameters do.

Because of a problem in the OLE dlls, invoking the Multiply method will cause an exception in the 32-bit OLE that shipped with Windows NT 3.5 and a GP fault in 16-bit OLE 2.02 and 2.03. This problem has been fixed in NT 3.51 and Windows 95.

The problem occurs if a vararg method has a retval parameter. For example, the following will fail:

        [vararg]
        HRESULT Multiply([in] short RequiredInteger,
                      [in] SAFEARRAY(variant) VariableNumberOfIntegers,
                      [out, retval] long* retval);

The problem does not occur if the vararg method doesn't have a retval parameter. For example, the following will currently work:

        [vararg]
        HRESULT Multiply([in] short RequiredInteger,
                      [in] SAFEARRAY(variant) VariableNumberOfIntegers);

        [vararg]
       long Multiply([in] short RequiredInteger,
                      [in] SAFEARRAY(variant) VariableNumberOfIntegers);

Additional query words: arguments 3.50 4.00 kbfile

Version           : 2.03 4.00 | 3.50
Platform          : NT WINDOWS

Last Reviewed: December 8, 1998