After a prefix variable is defined, the prefix is used to identify all object method (command) calls and properties (values). Before methods and properties can be accessed, an object instance must be assigned to this variable by the CreateObject or GetObject commands.
Parameters 1
ObjectVariable: variable Name of the object variable that is used in a macro.
ObjectType: string (optional) OLE object class name for this object. If missing, this is a generic object.
Options: enumeration (optional) Options for defining this object. If missing, no options are used.
Default! All non-prefixed commands are assumed to belong to this object.
Syntax 2
(<Value>: OLEObject)
Description 2
Object lets you specify the type and format of a parameter. You can use Object to pass parameters in calls to OLE automation methods or properties. Object generates a compile-time error if used outside an OLE automation call. Object is similar to the inline parameter functions for DLLCall.
Return Value 2
Object returns an OLE Object.
Parameter 2
<Value>: OLE Object The value to be converted and passed as a parameter
Note
This command is not available for use on a Linux operating system.
OLEObject := Object
Syntax
(<Value>: OLEObject)
Description
Object lets you specify the type and format of a parameter. You can use Object to pass parameters in calls to OLE automation methods or properties. Object generates a compile-time error if used outside an OLE automation call. Object is similar to the inline parameter functions for DLLCall.
Return Value
Object returns an OLE Object.
Parameter
<Value>: OLE Object The value to be converted and passed as a parameter
Note
This command is not available for use on a Linux operating system.
After a prefix variable is defined, the prefix is used to identify all object method (command) calls and properties (values). Before methods and properties can be accessed, an object instance must be assigned to this variable by the CreateObject or GetObject commands.
Parameters
ObjectVariable: variable Name of the object variable that is used in a macro.
ObjectType: string (optional) OLE object class name for this object. If missing, this is a generic object.
Options: enumeration (optional) Options for defining this object. If missing, no options are used.
Default! All non-prefixed commands are assumed to belong to this object.
Note
This command is not available for use on a Linux operating system.
any := ObjectInfo
Syntax
(ObjectVariable: any; [InfoItem: enumeration])
Description
Return information about an OLE object.
Return Value
Specified item. If the variable specified is not an object variable, False is returned.
Parameters
ObjectVariable: any Get information about this OLE object.
InfoItem: enumeration (optional) Information item to obtain. If missing, IsObject! is used.
IsObject! boolean Return whether the specified variable is an OLE object variable.
IsConnected! boolean Return whether the OLE object is connected to the OLE server.
ClassName! string Return the class name associated with this OLE object.
Note
This command is not available for use on a Linux operating system.
string := OemString
Syntax
(<Value> string)
Description
Pass a variable address (DLL call in-line parameter and OLE type casting function). See DLLCall and OLE Automation.
Parameter
<Value> string Value of the OEM string
Note
This command is not available for use on a Linux operating system.
OLE Automation
PerfectScript can send commands to WordPerfect, Corel Presentations and Corel QuattroPro. Through a Windows standard interface known as OLE Automation, PerfectScript can also send commands to programs such as Microsoft Excel and Microsoft Word. These programs are called OLE Automation servers. PerfectScript is an OLE Automation controller. OLE Automation is not limited to these programs. PerfectScript can send commands and control any OLE Automation server.
OLE Automation servers define objects. These object have names that are registered with Windows (refer to a program's documentation for the names of objects they define).
OLE objects can have methods and properties. A method is a command or function that performs an action on that object. A property is a value that the object has (like system variables in WordPerfect). This value can be retrieved and set. An example of a method for the "Excel.Application" object is,
Worksheets ().Activate
A property of the "Excel.Application" object is,
ActiveSheet.Name
Methods, like product commands, can require parameters, and may or may not return values. Unlike system variables in WordPerfect, properties can be set by placing the property name on the left hand side of an assignment statement. Properties can also take parameters when being retrieved or when being set. This makes the retrieval of a property very similar to a method call.
Object Support
Support for OLE Automation objects is provided through the following commands:
Object
CreateObject
GetObject
With
EndWith
ObjectInfo
Before using an OLE object in PerfectScript, the Object statement must be used. The Object statement is similar to the Application statement for products. This statement defines an object prefix variable that is used to call methods, and to retrieve and set object properties. The name of the object is also specified, and whether this prefix is to be used as the default object for non-prefixed method calls and properties.
The object prefix variable specified in the Object statement identifies a variable that will contain an instance handle to the object at run time. As a variable, it can be used in many places where other macro variables can be used, but not all. For example, the macro language operators "+" and "-" cannot be used with object variables, and automatic type conversions are not defined for object variables. Object variables can be assigned to other object variables of the same type, and can be passed as parameters to user defined macro routines.
As with other macro variables, object variables exist at run time in a specific macro variable pool. Specify this pool with Declare, Local, Global and Persist statements. If the pool is not specified, it exists in the local variable pool (unless PersistAll is in effect, and then the object variable exists in the persistent variable pool).
Before making a call to an object's methods, and before an object's properties can be retrieved or set, an instance handle to a specific object must be obtained through the CreateObject or GetObject statement. These statements return an instance handle to a specific instance of an object. Because many OLE Automation servers support multiple instances of the objects they define, an instance handle to a specific object must be obtained to distinguish instances of the same object. Multiple object variables can be created, and multiple instances can be obtained if the OLE Automation server supports multiple instances.
After getting an instance handle, an object variable is said to be connected to the OLE Automation server. Like other variables, the Exists statement can be used on object variables to find out if an object variable exists, and which variable pool it exists in. Even though an object variable exists, it may not be currently connected to the OLE Automation server. This information may be obtained from the ObjectInfo command.
When an instance of an OLE object is no longer needed, the connection can be terminated with the Discard statement. Like other variables, OLE object variables are automatically discarded when the macro terminates, or when the user defined routine ends in which the variable is defined. If connected, this automatically disconnects the object from an OLE Automation server.
After an object is connected to its OLE Automation server, the methods and properties of that object can be accessed. This is done by prefixing the method or property name with the OLE object prefix variable name and a ".". If the OLE object variable is the default object variable (specified by Default! in the Object statement, or specified in a With statement), the object prefix variable can be omitted. It replaced by two leading periods (".."). Leading periods are necessary to inform the macro compiler that the method name being called is not the name of a user defined macro routine, but the method name (or property) of the current default OLE object.
To establish a new default object for a localized block of code, use the With/EndWith compound statement. The object prefix variable is specified in the With statement, and all statements to access methods and properties preceded by ".." until the EndWith statement are assumed to be references to that object.
The NewDefault statement can be used to establish a new default object variable prefix for the remainder of the macro (or until the macro encounters another NewDefault statement).
The following functions allow the specification of a parameter's specific type and format. They can only be used to pass parameters in calls to OLE automation methods or properties. These functions generate a compile-time error if used outside an OLE automation call. They are similar to the inline parameter functions for DLLCall.
The return value from these functions is a value of the specified type.
<Value> or <VariableName> is the value or variable to be converted and passed as a parameter.
unsigned 1 byte numeric := Byte (<Value>numeric)
boolean := Bool (<Value>boolean)
boolean := Boolean (<Value>boolean)
signed 2 byte numeric := Integer (<Value>numeric)
signed 4 byte numeric := Long (<Value>numeric)
numeric := Currency (<Value>numeric)
numeric := Date (<Value>numeric)
4 byte floating point numeric := Single (<Value>numeric)
8 byte floating point numeric := Double (<Value>numeric)
OLEObject := Object (<Value>OLEObject)
any := Variant (<Value>any)
ansi string := String (<Value>string)
ansi string := AnsiString (<Value>string)
ansi string := OEMString (<Value>string)
ansi string := WPString (<Value>string)
unsigned 2 byte numeric := Word (<Value>numeric)
unsigned 4 byte numeric := DWord (<Value>numeric)
variable := Address (<VariableName>variable)
variable := &<VariableName>variable
Note
This command is not available for use on a Linux operating system.
label := OnCancel
Example
Syntax
([Label: label])
Description
Specify a Label or routine (function or procedure) to execute when a Cancel condition occurs.
A macro with more than one OnCancel executes the last OnCancel before a Cancel condition occurs. A Cancel condition stops a macro unless preceded by OnCancel.
Return Value
The previous Label set to execute by the OnCancel command. If there is no label, "" is returned.
Parameter
Label: label (optional) A Label to execute when a Cancel condition occurs. If a label is not specified, the macro halts when a Cancel condition occurs. For example: OnCancel().
label := OnCancel Call
Example
Syntax
([Label: label])
Description
Specify a Label-Return statement or routine (function or procedure) to execute when a Cancel condition occurs.
Return directs macro execution to the first statement after the Cancel condition.
A macro with more than one OnCancel Call executes the last OnCancel Call before a Cancel condition occurs. A Cancel condition stops a macro unless preceded by OnCancel Call.
Return Value
The previous Label set to execute by the OnCancel Call command. If there is no label, "" is returned.
Parameter
Label: label (optional) A Label to call when a Cancel condition occurs.
label := OnCondition
Syntax
(Conditon: enumeration or numeric; [Label: label])
Description
Specify a Label or routine (function or procedure) to execute when a Cancel, Error, NotFound, or user-defined condition occurs.
A macro with more than one OnCondition executes the last Condition command before a Cancel, Error, NotFound, or user-defined condition occurs. One of these conditions stops a macro unless preceded by OnCondition.
A user-defined condition number must be greater than or equal to 100. It is expressed as UserDefinedCondition! + numeric, or as a numeric. For example, UserDefinedCondition! + 1 is equal to the numeric value 101. Use Assert to cause the user-defined condition.
Return Value
The previous Label set to execute by the OnCondition command. If there is no label, "" is returned.
Parameters
Condition: enumeration or numeric Associate a condition with label. Use one of the enumerations below, or any numeric value greater than or equal to 100 (user-defined condition). See Note above.
CancelCondition!
ErrorCondition!
NotFoundCondition!
ExitCondition! Equivalent to OnExit(label).
VarErrChkCondition! Lets you specify the label to jump to or call if an undefined variable is accessed.
UserDefinedCondition! Adds 100 to a user-defined condition value (see Note above). For example, OnCondition (UserDefinedCondtion! + 1; Label101), sends macro execution to a label named Label101 on Assert (101).
Label: label (optional) A Label to execute when the specified condition occurs. If a Label is not specified, the macro halts on the associated condition. For example: label := OnCondition (CancelCondition!).
label := OnCondition Call
Syntax
(Conditon: enumeration or numeric; [Label: label])
Description
Specify a Label-Return statement or routine (function or procedure) to execute when a specified condition occurs. See Condition.
Return directs macro execution to the first statement after the specified condition.
A macro with more than one OnCondition Call executes the last Condition command before a Cancel, Error, NotFound, or user-defined condition occurs. One of these conditions stops a macro unless preceded by OnCondition Call.
A user-defined condition number must be greater than or equal to 100. It is expressed as UserDefinedCondition! + numeric, or as a numeric. For example, UserDefinedCondition! + 1 is equal to the numeric value 101. Use Assert to cause the user-defined condition.
Return Value
The previous Label set to execute by the OnCancel Call command. If there is no label, "" is returned.
Parameters
Condition: enumeration or numeric Associate a condition with label. Use one of the enumerations below, or any numeric value greater than or equal to 100 (user-defined condition). See Note above.
CancelCondition!
ErrorCondition!
NotFoundCondition!
ExitCondition! Equivalent to OnExit(label).
VarErrChkCondition! Lets you specify the label to jump to or call if an undefined variable is accessed.
UserDefinedCondition! Adds 100 to a user-defined condition value (see Note above). For example, OnCondition Call (UserDefinedCondtion! + 1; Label101), sends macro execution to a label named Label101 on Assert (101).
Label: label (optional) A Label to execute when the specified condition occurs. If a Label is not specified, the macro halts on the associated condition. For example: label := OnCondition Call (ErrorCondition!).
Establish a link with an application and test for changes in the value of the DDERequest ItemName parameter.
Return Value
One of the following enumerations:
Success!
AdvActTimeout!
Busy!
DataAckTimeout!
DllNotInitialized!
DllUsage!
ExeAckTimeout!
InvalidParameter!
LowMemory!
MemoryError!
NotProcessed!
NoConvEstablished!
PokeAckTimeout!
PostMsgFailed!
Reentrancy!
ServerDied!
SysError!
UnAdvAckTimeout!
UnfoundQueueId!
Refer to a Microsoft SDK (DdeGetLastError function) for detailed information on each enumeration.
Parameters
ConversationID: numeric The value of the DDERequest ConversationID parameter.
ItemName: string The value of the DDERequest ItemName parameter.
Label: label The Label to call when the value of ItemName changes.
label := OnError
Example
Syntax
([Label: label])
Description
Specify a Label or routine (function or procedure) to execute when an Error condition occurs.
A macro with more than one OnError statement executes the last OnError before an Error condition occurs. An Error condition stops a macro unless preceded by OnError.
Return Value
The previous Label set to execute by the OnError command. If there is no label, "" is returned.
Parameter
Label: label (optional) A Label to execute when an Error condition occurs. If a label is not specified, the macro halts when an Error condition occurs. For example: OnError().
label := OnError Call
Example
Syntax
([Label: label])
Description
Specify a Label-Return statement or routine (function or procedure) to execute when an Error condition occurs.
Return directs macro execution to the first statement after the Error condition.
A macro with more than one OnError Call statement executes the last OnError Call before an Error condition occurs. An Error condition stops a macro unless preceded by OnError Call.
Return Value
The previous Label set to execute by the OnError Call command. If there is no label, "" is returned.
Parameter
Label: label (optional) A Label to call when an Error condition occurs.
label = OnExit
Syntax
([Label: label])
Description
Specifies a label or routine (function or procedure) to execute when an Exit condition occurs.
A macro calls this label when it encounters one of the following exit conditions: Quit command, Return command from the main body of a macro, all macro statements have been executed (macro ends), Exitcondition! asserted (see Assert).
Return Value
Previous exit handler label. If one does not exist, an empty string ("") is returned.
Parameter
Label: label (optional) Exit handler label. If missing, the exit handler is cleared.
label := OnNotFound
Example
Syntax
([Label: label])
Description
Specify a Label or routine (function or procedure) to execute when a Not Found condition occurs.
A macro with more than one OnNotFound statement executes the last OnNotFound before a Not Found condition occurs. A Not Found condition stops a macro unless preceded by OnNotFound.
Return Value
The previous Label set to execute by the OnNotFound command. If there is no label, "" is returned.
Parameter
Label: label (optional) A Label to execute when a Not Found condition occurs. If a label is not specified, the macro halts when a Not Found condition occurs. For example: OnNotFound().
label := OnNotFound Call
Example
Syntax
([Label: label])
Description
Specify a Label-Return statement or routine (function or procedure) to call when a Not Found condition occurs.
Return directs macro execution to the first statement after the Not Found condition.
A macro with more than one OnNotFound Call statement calls the last OnNotFound Call before a Not Found condition occurs. A Not Found condition stops a macro unless preceded by OnNotFound Call.
Return Value
The previous Label set to execute by the OnNotFound Call command. If there is no label, "" is returned.
Parameter
Label: label (optional) A Label to call when a Not Found condition occurs.
label: := OnVarErrChk
Example
Syntax
([Label: label])
Description
Lets you specify a Label or routine to execute when a Cancel condition occurs.
Return Value
The previous Label set to execute by the OnVarErrChk command. If there is no label, "" is returned.
Parameter
Label: label (optional) A label to execute when a Cancel condition occurs. If a label is not specified, the macro halts when a Cancel condition occurs. For example: OnVarErrChk ().
label := OnVarErrChk Call
Example
Syntax
([Label: label])
Description
Lets you specify a Label or routine to execute when a Cancel condition occurs.
Return Value
The previous Label set to execute by the OnVarErrChk command. If there is no label, "" is returned.
Parameter
Label: label (optional) A label to execute when a Cancel condition occurs. If a label is not specified, the macro halts when a Cancel condition occurs. For example: OnVarErrChk ().
Close the file when it is no longer needed, or system resources will be lost. The file is closed automatically when the macro ends. See CloseFile.
Return Value
The file ID, or a negative number if an error occurs. The following file I/O (input/output) commands require a file ID:
CloseFile
FileIsEOF
FilePosition
FileRead
FileTruncate
FileWrite
Parameters
Name: string Include the full path. If the path is not included, the file is searched for in the following directories: the shared PerfectFit directory, current, Windows system, Windows, DOS PATH, network (mapped).
AccessMode: enumeration (optional) Default: Read!
Read!
ReadWrite!
Write! Override existing data if the position marker is not at the end of the file (see FilePosition).
WriteNew! Delete existing data and create a new file.
Append!
Exists! Open and close the file to test if the file exists.
If file does not exist: Read! and ReadWrite! cause macro to fail; Write!, WriteNew!, and Append! create a new file.
ShareMode: enumeration (optional) Default: None!
None!
Compatibility! Allow one or more macros to open a file any number of times.
Exclusive! Deny read and write access to more than one macro.
DenyNone! Does not deny other macros read and write access.
