Automation in PxPlus

Once a reference to an object has been obtained, the next step would be to manipulate or control the object. To obtain a listing of all the exposed properties and methods, the tick asterisk ('*) internal property can be evaluated:

PRINT obj_ID '*

This statement returns a comma-separated list of all exposed properties and methods, with method names having trailing parentheses. This list is merely an overview of the object and does not include data type or parameter information.

Note:
Some objects return a listing that only contains the PxPlus extended properties and methods (see Extended Properties and Methods). This occurs when the object does not expose run-time type information.

Proper object documentation is very important. Without proper documentation, it will be impossible to tell:

• What parameters are to be passed to methods.
• What return values can be expected from properties or methods.
• What parameters are considered by reference versus those that are by value.
• What method parameters are optional.
• What properties are indexed, and what data types are used for the indexes.

PVX Plus Technologies Ltd. only provides support for the PxPlus object interface. Specific interface information for an object must be obtained from the respective vendor.

Retrieving Property Values

To retrieve a property value, place the object variable and property name on the right-hand side of the equation:

     variable = object'property[$]

Automation is case insensitive; therefore, a property name can be written in upper, lower, mixed, or proper case. If the property is to return a string data type, then a $ symbol should be placed at the end of the property name. Properties may also be collections or arrays, which would require a slightly different syntax when assigning values:

     variable = object'property .get [$](index [$], …)

The .get that is appended to the property name indicates to PxPlus that this is a property and not a method call. For string type properties, the $ symbol should be placed at the end of the .get and before the open parentheses. The index parameter indicates the property element to retrieve. Unlike PxPlus arrays, the index for the property might not be a numeric data type (check the object documentation).

Example:

     STYLE=DOCUMENT'Styles.get("Normal")

Where:

     Styles is a property and "Normal" indicates the indexed value to retrieve.

Note:
Some objects allow indexed property access without specifying .get notation.

Assigning Property Values

To assign a property value, place the object variable and property name on the left-hand side of the equation:

     object'property[$]=variable

Automation is case insensitive; therefore, a property name can be written in upper, lower, mixed, or proper case. If the property is to return a string data type, then a $ symbol should be placed at the end of the property name. Properties may also be collections or arrays, which would require a slightly different syntax when assigning values:

     result =object'property.put(index[$],…,data[$])

This syntax is identical to a method call, but with a few exceptions. The result of the property assignment is always zero, and it can be disregarded. The .put indicates to PxPlus that this is a property and not a method call. And finally, the data to be assigned to the property is passed in as the last parameter between the parentheses.

This syntax style is also required when assigning an object to a non-index/non-array property. The reason for this is due to a syntax conflict in PxPlus, where the following would be invalid:

     object'property =* other_object

The correct syntax for the above example would be:

     result =object'property .put (*other_object)

Note:
When assigning or passing an object, it is required that an asterisk ( * ) appear before the object reference. This allows PxPlus to differentiate between a variable holding a numeric value and one that holds an object reference.

There may also be cases where the property assignment is expecting to be set by reference. A common example occurs when an object property is changed to refer to a new object. For most properties that are object types, the .put syntax will work correctly. If an error does occur, then the following syntax should be tried:

     result = object'property .putref (*otherobject)

Calling Methods

To call a method, place the object variable, method name, and parameter list on the right-hand side of the equation:

     result = object'method [$] (param1, param2 [, …])

Automation is case insensitive; therefore, a method name can be written in upper, lower, mixed, or proper case. If the method is to return a string data type, then a $ symbol should be placed at the end of the method name. Some methods are written to accept optional parameters. When choosing not to pass an optional parameter, a * should be passed in the place of the parameter:

     result = object'method [$] (*,param2, param3)

The preceding example passes two parameters in, skipping the first optional parameter. The one exception to this is that PxPlus will not allow the passing of * as the last parameter. When the last parameter is optional and should be skipped, simply close the parenthesis after the last actual argument.

Example:

The following example shows incorrect syntax for skipping the last two optional parameters of a method call:

     result = object'method [$] (param1, *, *)

The correct coding would be:

     result =object'method [$] (param1)

Note:
Documentation or a type library viewer should be used when trying to determine if a method uses optional parameters.