AUTOMATION

PLBCMP GUI Only

The AUTOMATION instruction defines an automation object variable. The AUTOMATION object is implemented as an ActiveX Automation Client interface that allows PL/B to programmatically control any object/program that conforms to the Automation interface. To define an AUTOMATION object, use the following statement format:

Where:

label

Optional. A Data Label.

value

Optional. A string literal that uniquely identifies an interface for a program executing as an Automation Server.

^

Optional. Denotes the item as being a POINTER.

Flags Affected: NONE

Note the following:

1. If the CLASS keyword is not specified with the AUTOMATION declaration, it must be specified on the CREATE statement for the object. The size of the {value} literal is truncated to thirty-nine (39) characters.

2. The properties for an AUTOMATION object are available as two groups:

• The first group is defined by the normal PL/B property set. These properties are under direct control of the runtime and are defined in the list above.

• The second group of properties is provided only via the Automation interface defined for the CLASS identifier. The user must refer to vendor-supplied documentation for specific properties.

3. The properties available through the Automation interface use the following syntax:
   
   *{name}={value}
   or
   @{svar}={value}
   
   Where:

label

is a string variable containing the property name. Property names are not case sensitive.

value

is a character variable, numeric variable, VARIANT or AUTOMATION object that is assigned to the property.

 

4. As a rule, Automation Server applications do not make events available. However, the PL/B implementation will allow such events if they are available. The user should reference the Automation Server documentation.

5. When an Automation object method is used, the method name identifier is determined by referencing the vendor documentation. The method names are not case sensitive. The method can be specified as a keyword form or as a character variable with a leading '@' character. The acceptable syntax forms are as follows:
   
   {object}.methodname GIVING {result} USING {param}
   or
   {object}.@{svar} GIVING {result} USING {param]

 

6. The {result} is the expected return value for the method. The variable types for {result} can be a string variable, numeric variable, VARIANT object, or AUTOMATION object. Please reference Automation vendor documentation for expected return values.

7. The object method parameters identify the expected values required for the {method}. The keyword name of a given {param} can be determined from the automation vendor documentation. The {param} keyword names may or may not be used. If the {param} name is not specified, the parameter must be placed into the {param} list at a valid position as documented for the method. The {param} can have one of the following syntax forms:
   
   {value}
   or
   *{name}={value}
   or
   @{svar}={value}
   
   Where:

value

is a character variable, numeric variable, VARIANT, or AUTOMATION object that is assigned to the property.

name

is the property name. Property names are not case sensitive.

svar

is a string variable containing the property name. Property names are not case sensitive.

 

8. When an AUTOMATION object COLLECTION is being accessed, the 'Item' keyword accesses the collection items using the COM property interface. However, if an AUTOMATION collection class has implement the 'Item' as a method, a runtime conflict can exist resulting in an unexpected O145 error. When an AUTOMATION object COLLECTION has implemented the 'Item' method, the PLB runtime supports a syntax format using the specialized method name of '_Item_' which forces the true method named 'Item' be executed using the COM method interface.

Example:

WinObjCol AUTOMATION ;Windows Object Collection

WinObj AUTOMATION ;Window Object

.

.Perform operations to create WinObjCol collection

.

              .....

. This syntax works for AUTOMATION collections when

. the 'Item' is not implemented as a method for an

. AUTOMATION class.

.

              WinObjCol.Item GIVING WinObj USING 1

             .....

 This syntax can be used when the AUTOMATION collection

. has implemented a 'Item' method to access the collection.

. The '_Item_' format forces the runtime to use the

. COM method interface to access an AUTOMATION collection.

.

              WinObjCol._Item_ GIVING WinObj USING 1

.

9. When an AUTOMATION object is created on the server side using a Application Server, no PL/B application events are supported.

10. This object is not available when using the PL/B Web Server

See Also: Object Definitions, Object Output Instructions