Chapter 11
Corel® PerfectScript® 8 Programming Commands
Three new macro commands have been added: MacroCompile, MacroIsCompiled, and MacroPlay. See online Help for information about these commands. Also, the following commands have been changed: DialogAddControl, DialogDelete, FileFind, FileNameDialog, GetFileAttributes, MacroInfo, OLEAutomation, and SetFileAttributes. See online Help for information about these commands.
Dimensions
Purpose
Return dimension information about an array variable.
Example
Appendix A: 8064
Return Value
Return the number of dimensions or elements, or the index range (see the IndexOption parameter).
Syntax
Numeric := Dimensions (VariableName: variable; [IndexOption: enumeration])
Parameters
VariableName
variable Array variable name. Return dimension information about this variable.
IndexOption
enumeration (optional) Type of dimension information to return. If missing, DimensionCount! is used. Use 0 to return the total number of array elements. Use a dimension number to return the number of elements in that dimension (the numeric value 2 is equivalent to IndexLimit2!).
DimensionCount!
Return the total number of dimensions in the array.
ElementCount!
Return the total number of elements in the array.
IndexLimit1!
Return the upper limit of the array’s first index.
IndexLimit2!
... 9! Return the upper limit of a specified index (2 through 9).
IndexLimit10!
Return the upper limit of the array’s tenth index.
Given the following declaration,
Declare array[4; 2; 5]
Dimensions returns the following values:
3 Dimension (array[ ]; DimensionCount!) // number of dimensions
40 Dimension (array[ ]; ElementCount!) // total elements
4 Dimension (array[ ]; IndexLimit1!) // elements in dimension 1
2 Dimension (array[ ]; IndexLimit2!) // elements in dimension 2
5 Dimension (array[ ]; IndexLimit3!) // elements in dimension 3
0 Dimension (array[ ]; IndexLimit4!) // out of range
0 Dimension (c) // not an array
0 Dimension (b[ ]) // does not exist
Discard
Purpose
Remove Local, Global, or Persist variables from memory, in that order.
Discard does not specify a variable table. If a variable by the same name exists in all three tables, call Discard three times.
While(Exists(VariableName))
Discard(VariableName)
EndWhile
Example
Appendix A: 8022
Syntax
Discard ({VariableName: variable})
Parameters
VariableName
variable (repeating) Variable(s) to discard. Variables begin with a letter and can include any other combination of letters or numbers. Separate multiple variables with a semicolon.
DIV
Purpose
Operator. Precedence level 3. See Arithmetic Operators in Chapter 4: Expressions.
Return Value
Return the integer quotient of two numbers.
Syntax
numeric := numeric DIV numeric
DLLCall
Purpose
Call a function in a Dynamic Link Library (DLL).
Note
Do not use this command unless you are familiar with Windows programming. Incorrect DLL calls can damage files and/or reset your computer. Macros using DLLCalls written for Windows 3.x must be rewritten for Windows 95.
Syntax
DLLCall (<ModuleInstance> numeric; <FunctionName> string; [<ReturnVariable> variable]; <ReturnType> enumeration; {[<Parameter> any]})
Parameters
<ModuleInstance>
numeric A DLL handle. DLLLoad returns the handle in a variable.
<FunctionName>
string A function name. See DLL documentation for function names.
<ReturnVariable>
variable (optional) The DLL function may return a value in this variable. The ReturnType parameter defines the expected data type.
<ReturnType>
enumeration The data type to return (see ReturnVariable parameter).
Data types and descriptions:
AnsiString!
(Windows type LPSTR)
Bool!
(Windows type BOOL)
DWord!
(Windows type DWord)
Integer!
(Windows type LONG)
OemString!
(Windows type LPSTR)
Real!
(Microsoft C type double)
String!
(Windows type LPSTR)
Word!
(Windows type WORD)
WPString!
(Corel WordPerfect wordstring)
Void!
(Nothing)
ReturnType must match the data type returned in ReturnVariable (see DLL function documentation for return types). If it does not, an Unrecoverable Application Error or system crash may result.
{<Parameter>}
any (optional) Parameter information passed to a DLL function, enclosed in braces and separated by a semicolon. The type of information depends on the function being called (see DLL function documentation for parameter values to pass).
Data types and descriptions:
integer (LONG or Dword)
string (FAR pointer to an ANSI string)
boolean (BOOL)
real (Microsoft c-type double)
AnsiString(string) (FAR pointer to an ANSI string)
OemString(string) (FAR pointer to an OEM string)
WPString(string) (FAR pointer to a WP 6.0 word string)
ADDRESS(integer) (LPDWord)
ADDRESS(DWord(integer))
ADDRESS(boolean) (BOOL FAR*)
ADDRESS(string) (FAR pointer to an ANSI string)
ADDRESS(AnsiString(string)) (FAR pointer to an ANSI string)
ADDRESS(OemString(string)) (FAR pointer to OEM string)
ADDRESS(WPString(string)) (FAR pointer to a WP 6.0 word string.)
ADDRESS(real) (FAR pointer to a Microsoft C- type double)
ADDRESS(Real(real)) (FAR pointer to a Microsoft C-type double)
DLLCall Prototype
Purpose
Define the calling format of a DLL routine (see example).
DLLCall Prototype must occur before calling a DLL function. The DLL library is loaded and freed each time the DLL function is called.
DLLCall Prototype makes a macro easier to read and provides safer DLL calls (routines can be called only as defined).
Note
Do not use this command unless you are familiar with Windows programming. Incorrect DLL calls can damage files and/or reset your computer.
DLLCall is a compile-time only command that allows a variable name (simple variables only, no array elements are allowed), specified as the DllLibraryFile parameter as well as the literal character string that it supports. When a variable name is specified (see ModuleFileName parameter), the contents of the variable specified in the DLLCall Prototype statement is used, which must contain the name of the DLL library file. If the specified variable does not exist when the DLL routine is called, an undefined
variable error occurs at runtime. This occurs when the DLL filename or instance handle is loaded in a local variable in a user-defined routine or macro file, and the DLL routine is called from a different file or different user-defined routine in which the variable does not exist. Define the variable containing the DLL name or instance handle as a Global macro variable, which makes it visible throughout the execution of the macro.
Syntax
DLLCall Prototype <Name> label (<ModuleFileName> string or variable; [<FunctionName> string]; <ReturnType> enumeration; {[<Parameter> any}])
Parameters
<Name>
label Name used to call the DLL function.
<ModuleFileName>
string or variable DLL library file containing the DLL function, defined as a literal string, or as a variable that must contain the DLL library module name at runtime. If the variable contains an integer value, this value is assumed to be the instance handle of a DLL that was loaded using the DLLLoad command.
<FunctionName>
string (optional) A function name. See DLL documentation for function names. If not used, the Name parameter is used.
<ReturnType>
enumeration The data type returned by the DLL function. See DLLCall.
AnsiString!
Bool!
DWord!
Integer!
OemString!
Real!
String!
Word!
WPString!
Void!
<Parameter>
any (optional) Parameter information passed to a DLL function, enclosed in braces and separated by a semicolon. The type of information depends on the function being called (see DLL function documentation for parameter values to pass). See DLLCall.
DLLFree
Purpose
Remove a dynamic link library (DLL) from memory.
Note
Do not use this command unless you are familiar with Windows programming. Incorrect DLL calls can damage files and/or reset your computer.
Syntax
DLLFree (ModuleInstance: numeric)
Parameters
ModuleInstance
numeric A DLL handle. DLLLoad returns the handle in a variable.
DLLLoad
Purpose
Load a dynamic link library (DLL) into memory.
You should respond to error values with code similar to the following (see ModuleInstance parameter):
Result := DLLLoad(filename)
Switch(vResult)
CaseOF 0: ...statement block...
CaseOF 2: ...statement block...
EndSwitch
Note
Do not use this command unless you are familiar with Windows programming. Incorrect DLL calls can damage files and/or reset your computer.
Return Value
A DLL handle if the DLL successfully loads, or an error value. For example, 31 means a General Failure occurred; 1157 means the DLL was not found.
See your Windows 95 documentation for more information.
Syntax
numeric := DLLLoad (Filename: string)
Parameters
Filename
string DLL path and filename.
DoesDialogExist
Purpose
Look for a dialog in the current macro, then look through the Use file list for the current macro. See Use.
Example
Appendix A: 8099
Return Value
True if the dialog is found, False if not.
Syntax
boolean := DoesDialogExist (Dialog: string)
Parameters
Dialog
string The name or number of a dialog box (see DialogDefine).
DoesDirectoryExist
Purpose
Return True if a directory exists, False if not.
Example
Appendix A: 8078
Return Value
True/False.
Syntax
boolean := DoesDirectoryExist (DirectoryName: string)
Parameters
DirectoryName
string Include the full path.
DoesFileExist
Purpose
Return True if a file exists, False if not.
Example
Appendix A: 8078
Return Value
True/False.
Syntax
boolean := DoesFileExist (Filename: string)
Parameters
Filename
string Include the full path.
DoesRegionExist
Purpose
Return whether a named region exists.
Example
Appendix A: 8078
Return Value
True if the named region exists, False if not.
Syntax
boolean := DoesRegionExist (NamedRgn: string)
Parameters
NamedRgn
string Dialog ID and control ID, or Dialog ID and name of a named region. Enclose IDs in double quotation marks, separated by a period.
DWord
Purpose
Pass a value as a DWord (DLL call in-line parameter function). DWord or double word is an unsigned long integer. See DLLCall.
Syntax
numeric := DWord (<Value> numeric)