Progress
External Program
Interfaces


Property and Method Syntax

The syntax to access properties and methods is similar to the syntax to access widget attributes and methods. However, where widget references use widget handles, COM object references use component handles. Component handles support an extended syntax that allows you to:

The following syntax diagrams describe the syntax for method and property references. These diagrams are equivalent to the syntax presented in the Progress Language Reference , but describe method and property references in a more top-down fashion. (See the information on attributes and methods in the Progress Language Reference .)

NOTE: All COM object errors are translated to Progress errors. To suppress any error messages generated by a COM object method or property reference, you can specify the NO-ERROR option in any statement that includes the method or property reference.

Method Reference

This is the syntax for a COM object method reference:

SYNTAX
[ NO-RETURN-VALUE ]
    COMhdl-expression:Method-Name-Reference 

NO-RETURN-VALUE

Required for some methods that do not have a return value.

NO-RETURN-VALUE prevents Progress from expecting a possible return value. This option is appropriate only if the method does not have a return value. Whether a method call requires this option depends on the COM object. Some COM objects require that the caller knows there is no return value. In this case, you must specify the option. Many more robust COM objects do not require this option.

If the method requires NO-RETURN-VALUE and you don’t specify it, the COM object generally returns an error. For example, Word for Windows 95 Version 7.0 returns an error similar to “Non-function called as function.”

NOTE: If the method has a return value, you must not invoke it in a statement with the NO-RETURN-VALUE option. In this case, ignore the return value without specifying this option, as in the second call to the SetDate( ) method.

COMhdl-expression

An expression that returns a component handle to the COM object that owns the method specified by Method-Name-Reference.

Method-Name-Reference

Specifies a single COM object method that might return a value.

Property Reference

This is the syntax for a COM object property reference:

SYNTAX
COMhdl-expression:Property-Name-Reference 

COMhdl-expression

An expression that returns a component handle to the COM object that owns the property specified by Property-Name-Reference.

Property-Name-Reference

Specifies a single COM object property.

Component Handle Expression

Every method or property reference must begin with a component handle expression that returns a component handle value. This is the syntax to specify a component handle expression:

SYNTAX
COMhandle [ : Method-Name-Reference | Property-Name-Reference ] ... 

COMhandle

A component handle variable. (Note that the first element in a component handle expression must be a COM-HANDLE variable.)

Method-Name-Reference

Specifies a single COM object method or property that returns a component handle value. A component handle expression can chain as many method and property references as required to return the handle to a particular COM object.

Property-Name-Reference

Specifies a single COM object method or property that returns a component handle value. A component handle expression can chain as many method and property references as required to return the handle to a particular COM object.

NOTE: For the most efficient dispatch of multiple references to a particular COM object, assign the initial component handle expression for the COM object to a COM-HANDLE variable. Each reference to a given component handle expression incurs additional run-time overhead for each method or property referenced in the expression.

Method Name Reference

This is the syntax to specify a single COM object method:

SYNTAX
Method-Name
  (
    {     [ OUTPUT | INPUT-OUTPUT ]
              expression [ AS datatype ]
              [ BY-POINTER | BY-VARIANT-POINTER ]
       |  null-parameter
    }
    [ ,     [ OUTPUT | INPUT-OUTPUT ]
                expression [ AS datatype ]
                [ BY-POINTER | BY-VARIANT-POINTER ]
         |  null-parameter
    ] ...
  ) 

Method-name

The name of the COM object method. This name is not case sensitive. But by convention, Progress documentation shows COM object method names in mixed case.

expression

Any valid Progress expression that you can pass as a parameter to the method.

datatype

One of several data-type specifiers that the associated parameter might require. For more information on datatype, see Table 7–2. The remaining keyword options specify additional type and mode information for each parameter. The COM object defines the data types and numbers of parameters for a method.

null-parameter

Any amount of white space, indicating an optional parameter that you choose to omit. You can also pass variable numbers of parameters if the method supports it. For more information on specifying method parameter options, see the "Specifying Options For Properties and Method Parameters" section.

You can invoke a method in two ways:

Property Name Reference

This is the syntax to specify a single COM object property:

SYNTAX
Property-Name [ ( index [ , index ] ... ) ]
  [ AS datatype-specifier ] 

Property-Name

The name of the COM object property. This name is not case sensitive. But by convention, Progress documentation shows COM object property names in mixed case.

index

Any expression that legally indexes the property and for the required number of dimensions. If necessary and if possible, Progress converts the data type of index to the COM data type expected by the property. Essentially, the syntax is the same as for a method reference with input parameters.

datatype-specifier

One of several data-type specifiers that the associated property might require when you set its value. For more information on datatype, see Table 7–2. For more information on specifying the AS datatype option and data type conversion for properties, see the "Specifying Options For Properties and Method Parameters" section.

You can reference a property in two ways:

Data-type Specifier

Progress supports a protocol to provide default mappings between native COM object method parameter and property values and the corresponding Progress data values. This mapping protocol supports many COM data types. You can override the default mapping by using a type specifier, as shown in Table 7–2. For more information on mapping data types shown in Table 7–2, see "COM Object Data Type Mapping."

Table 7–2: Data-type Specifiers For COM Object Methods and Properties 
Data-type Specifier To Override
the Default Mapping
Progress Data Type
CURRENCY
DECIMAL
ERROR-CODE
INTEGER
IUNKNOWN
COM-HANDLE
FLOAT
DECIMAL
SHORT
INTEGER
UNSIGNED-BYTE
INTEGER

Each of these data-type specifiers represents one of the base COM data types available for a method parameter or property. Each Progress data type represents the typical Progress data type that corresponds to the specified COM data type.

Data-type specifier options are necessary only for some method input parameters and property settings. Whether or not you must specify the AS datatype or any of the other type options (BY-POINTER or BY-VARIANT-POINTER) depends on the COM object method or property and the implementation of the COM object. You can also specify how a method parameter of any data type is passed using the mode options OUTPUT or INPUT-OUTPUT. Whether you use a mode option depends (in part) on how you plan to use the method parameter in your application. For more information on using data-type specifiers and mode options, see the "Specifying Options For Properties and Method Parameters" section and "COM Object Data Type Mapping."


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