Release 10.1A: OpenEdge Development:
Programming Interfaces

> ## Specifying options for properties and method parameters

> Progress allows you to specify a variety of data-type specifier and mode options for passing COM object method parameters and setting COM object properties (see the "Property and method syntax" section). Data-type specifier options specify a data type mapping between COM data types and Progress data types; mode options specify how a method parameter is passed (whether for input or output). Thus:

> - The data-type specifier options in Table 14–2 dictate COM data type conversions for passing method input parameters and setting properties that are different than the defaults. (For more information on COM data-type conversion, see Appendix A "COM Object Data Type Mapping.")

> - The type options `BY-POINTER` and `BY-VARIANT-POINTER` specify additional information for passing method parameters.

> - The mode options `OUTPUT` and `INPUT-OUTPUT` specify how the method parameter is used.

> One of the essential criteria that determines when and how you might have to use data-type specifier and mode options is the Type Library provided with a COM object implementation.

> ##### Understanding a COM object type library

> A Type Library contains definitions for a COM object’s methods and properties. When a COM object provides a Type Library, Progress references it before dispatching the method or property in an attempt to convert each method parameter or property value to the required COM data type. If a Type Library is available, Progress tries to match the number and types of any parameters being passed into a method before dispatching the method to the COM object for execution.

> If both data-type specifier options and Type Library definitions are provided, the data-type specifier options take precedence. For more information on how Progress matches Progress data items to COM object properties and method parameters, see Appendix A "COM Object Data Type Mapping."

> You can locate data type information that is stored in Type Libraries on-line using the OpenEdge COM Object Viewer. For more information on Type Libraries and how to view their components, see the "Locating COM object information on your system" section.

> ##### Using data-type specifier options

> Data-type specifier options allow you to be more specific about how to convert information from the OpenEdge application into the data type expected by the COM object. These data-type specifiers override Progress default data type conversions for COM object properties and method parameters that have no Type Library support. For information on Progress default data conversions and how they are affected by data-type specifiers and Type Library support, see Appendix A "COM Object Data Type Mapping."

> ##### Using data-type specifiers for properties

> You can include a data-type specifier option in a property reference on the left side of an assignment statement, when you set the property. You can use any data-type specifier from Table 14–2:

>     myObject:Money AS CURRENCY = 1000.9999.

> ##### Using data-type specifiers for method parameters

> For a method parameter, you can also use a data-type specifier from Table 14–2. For COM objects that do not have Type Library definitions and yet require that the data type of the parameter be passed properly, you must specify the data type for the method call to succeed:

>     myObject:SaveMoney(1000.9999 AS CURRENCY).

> In addition, you can use the `BY-POINTER` or `BY-VARIANT-POINTER` type option to indicate that the parameter is to be passed as a pointer:

>     myObject:SaveMoneyPtr(1000.9999 AS CURRENCY BY-POINTER).

> A pointer is a value that contains the memory location of the data item you are referencing. `BY-POINTER` specifies a pointer to the data item value. `BY-VARIANT-POINTER` specifies a Variant that contains a pointer to another Variant that stores the actual value.

> Note: A Variant is a self-describing COM data type. It contains both the data and an indication of its effective data type.

> Both the `BY-POINTER` and `BY-VARIANT-POINTER` options have no affect on the value of the parameter. They only affect how the data is packaged when the method is dispatched to the COM object. The type option to use, if any, is determined by the method implementation. You can determine the type options required for each parameter from the OpenEdge COM Object Viewer (see the "Locating COM object information on your system" section).

> ##### Using mode options for method parameters

> The default mode for a method parameter is input. An input parameter passes a value to the method but does not return a value from the method. Thus, an input parameter can be a database field, an expression, or a variable.

> Caution: Do not use the `INPUT` keyword as a mode option because, for a parameter, Progress might interpret this as the screen value of a widget.

> The mode option `OUTPUT` or `INPUT-OUTPUT` specifies a parameter that returns a value from the method. (An `INPUT-OUTPUT` parameter also passes a value to the method.) This means that the value of any passed variable can change after the method call returns. You can only specify the `OUTPUT` or `INPUT-OUTPUT` options with a variable as the parameter (as opposed to a database field or an expression):

>     DEFINE VARIABLE MyWallet AS DECIMAL.
>     myObject:WithdrawMoneyPtr(OUTPUT MyWallet AS CURRENCY).

> Note: The `OUTPUT` or `INPUT-OUTPUT` option forces the parameter to be passed as a pointer and explicitly specifies that a value be returned to your application. Thus, if you use a mode option, you do not need to use the `BY-POINTER` type option because the type option is redundant. However, the `BY-POINTER` type option, by itself, does not return a value to your program. You must use a mode option or Progress does not allow the method to return a value in the parameter.

> Note that Progress does not use Type Library information to determine the parameter mode. This prevents the COM object from updating a variable that you do not expect or want to change. Thus, if the COM object ordinarily changes the value of a particular parameter, you can prevent any variable you pass from having its value changed by omitting any mode option on the parameter.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095