Chapter 11

See Graphic

Corel® PerfectScript™ Programming Commands




Corel® PerfectScript™ 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.
 
Examples 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! 3 ... 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
 
Examples 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).

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.

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)
{<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)) (LPDWord)
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 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.
 
Examples 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.
 
Examples 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.
 
Examples 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.
 
Examples 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)