Progress
External Program
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 7–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 "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 "COM Object Data Type Mapping."
You can locate data type information that is stored in Type Libraries on-line using the Progress 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 Progress 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 "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 7–2:
Using Data-type Specifiers For Method Parameters
For a method parameter, you can also use a data-type specifier from Table 7–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:
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:
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 Progress 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):
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 © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |