Chapter 11: E to F

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.

Else

Purpose

All statements between Else and Endif are executed when the If expression is False. See If.

Syntax

Else

ElseIfPlatform

Purpose

Works with IfPlatform and EndIfPlatform statements, similar to the Else statement in an If-Else-Endif control statement except that a new platform ID may be specified.

Syntax

ElseIfPlatform ([{<PlatformID> enumeration}])

Parameters

enumeration (optional, repeating) List of platform IDs to test. If the ID of the current platform is specified, only the statements up to the next ElseIfPlatform statement are included in the macro (all others are ignored). If missing, the current “ignore” state is reversed (ignored statements are compiled up to the next ElseIfPlatform statement). Statements that would have been compiled are ignored; statements that would have been ignored are compiled.

EndApp

Purpose

Identify, for the compiler, an application that is no longer used in a macro (see Application).

EndApp is a non-executable statement that can occur anywhere in a macro. After EndApp, a product command to the application specified by EndApp creates a compile-time syntax error.

Example

Appendix A: 8058

Syntax

EndApp (<ProductPrefix> identifier)

Parameters

identifier A unique identifier that must match the ProductPrefix parameter of an Application statement, or the prefix of an OLE object variable. This command is a compile time only statement, and removes a product or object prefix from the product name list maintained by the macro compiler. If the prefix of the current default object or product is removed, the previous default prefix becomes the new default prefix.

EndFor

Purpose

Close a For control loop. See For.

Syntax

EndFor

EndFunc

Purpose

Close a Function statement (synonym for EndFunction). See Function.

Syntax

EndFunc

EndFunction

Purpose

Close a Function statement (synonym for EndFunc). See Function.

Syntax

EndFunction

EndIf

Purpose

Close an If control statement. See If.

Syntax

EndIf

EndIfPlatform

Purpose

Close an IfPlatform conditional compile statement. See IfPlatform.

The parameter is optional and ignored. Its only purpose is to document what it goes with.

Syntax

EndIfPlatform ([{<PlatformID> enumeration}])

EndProc

Purpose

Close a Procedure statement (synonym for EndProcedure). See Procedure.

Syntax

EndProc

EndProcedure

Purpose

Close a Procedure statement (synonym for EndProc). See Procedure.

Syntax

EndProcedure

EndPrompt

Purpose

Terminate the current Prompt. See Prompt.

Syntax

EndPrompt

EndSwitch

Purpose

Close a Switch control statement. See Switch.

Syntax

EndSwitch

EndWhile

Purpose

Close a While control loop. See While.

Syntax

EndWhile

EndWith

Purpose

Close a With statement. See With.

Syntax

EndWith

EnvVariableGet

Purpose

Return the value of an environment variable.

Return Value

Environment variable value.

Syntax

string := EnvVariableGet ([EnvVariableName: string]; [EnvType: enumeration])

Parameters

EnvVariableName

string (optional) The environment variable name. If not used, a list of all environment variables is returned.

EnvType

enumeration (optional) The type of variable. If mising, DOS! is used.

DOS!

EnvVariableSet

Purpose

Set the value of an environment variable, or delete it.

Syntax

EnvVariableSet (EnvVariableName: string; [Value: string]; [EnvType: enumeration])

Parameters

EnvVariableName

string The environment variable name.

Value

string (optional) The value to assign to the variable. If missing, the environment variable is deleted.

EnvType

enumeration (optional) The type of variable. Default: DOS!

DOS!

Error

Purpose

Determine how a macro responds to an Error condition. Create an Error condition with Assert(ErrorCondition!).

Example

Appendix A: 8020

Return Value

Off!

Previous state was Off!

On!

Previous state was On!

Syntax

enumeration := Error ([State: enumeration])

Parameters

State

enumeration (optional) Specify the Error state. The default is Error(On!). If missing, the current state is returned without changing it.

Off!

Ignore an Error condition.

On!

Stop a macro unless preceded by OnError, which directs macro execution to a specified Label.

ErrorNumber

Purpose

Return the error value of a Cancel, Error, Not Found, or user-defined condition.

Notes

ErrorNumber is a macro system variable that returns an enumeration, which can be referred to by name. The enumerations have the same numeric values as in previous versions. The value of ErrorNumber is cleared before every command. After the command is excuted, ErrorNumber returns a value that indicates if an error occured. If a handler condition is disabled, the macro continues when the specified condition occurs. You can test ErrorNumber manually for ErrorNumber.Success!. Commands that do not reset Error

Number are MacroInfo(ErrorNumber!) calls, ErrorNumber itself, and compound statements, such as If- Endif, Switch-EndSwitch, Repeat-Until, While- EndWhile, For-EndFor, and so on. Copy the value returned by ErrorNumber into a variable if the value is needed after executing other macro commands, such as PROMPT, which reset ErrorNumber.

Return Value

Success!

Formerly value 0.

CancelConditionAsserted!

Cancel condition was asserted. Former value 1.

ErrorConditionAsserted!

An Error condition was asserted. Former value 2.

NotFoundConditionAsserted!

A Not Found condition was asserted. Former value 7.

UserDefinedCondition!

This value defines the base value for assertions of user defined conditions. See the Assert command for more information about the value of user defined condition codes.

Syntax

enumeration := ErrorNumber

Exists

Purpose

Determine if a variable exists.

To exist, a variable must be declared and initialized. Given that variable w is declared and not initialized, and that Local x is initialized to 5, Global y to 10, and Persist z to 15, the following statements are valid:

vNoInit := Exists(w)

Result: vNoInit equals Exists.NotFound!

vLocal := Exists(x)

Result: vLocal equals Exists.Local!

vGlobal := Exists(y)

Result: vGlobal equals Exists.Global!

vPersist := Exists(z)

Result: vPersist = Exists.Persistent!

If(Exists(vLocal))

Beep

EndIf

Explanation: Computer beeps because Exists returns a value other than Exists.NotFound!.

If(Exists(vLocal) = Exists.Persistent!)

Beep

EndIf

Explanation: The computer does not beep because Exists returns Exists.Local!. (vLocal is a Local variable, not a Persist variable.)

Example

Appendix A: 8022

Return Value

If Pool is left off, the values are:

NotFound!

Variable does not exist.

Local!

Variable exists in local pool.

Global!

Variable exists in global pool.

Persistent!

Variable exists in persistent pool.

If Pool is specified, the return value is True (exists in the pool specified by the Pool parameter) or False (does not exist).

Syntax

enumeration or boolean:= Exists (VariableName: variable; [Pool: enumeration])

Parameters

VariableName

variable A variable declared as Local, Global, or Persistent. Variables begin with a letter and can include any other combination of letters or numbers.

Pool

enumeration (optional) If missing, the command returns the Pool the variable is in. If provided, the command returns boolean True or False indicating whether the variable is in the specified Pool.

Local!

See if the variable exists in the local variable pool.

Global!

See if the variable exists in the global variable pool.

Persistent!

See if the variable exists in the persistent variable pool.

ExitHandlerState

Purpose

Determine how a macro responds to an Exit condition.

Create an Exit condition with Assert(ExitCondition!).

Unlike Error, Cancel, and NotFound, ExitHandlerState does not prevent or enable a condition from occurring. It enables or disables calling the exit handler when an exit condition occurs.

Example

Appendix A: 8022

Return Value

Off!

Previous state was Off!

On!

Previous state was On!

Syntax

enumeration := ExitHandlerState ([State: enumeration])

Parameters

State

enumeration (optional) Specify the Exit state. If missing, the current state is returned without changing it. Default: Exit(On!).

Off!

Disable exit handler condition calling.

On!

Enable exit handler condition calling.

ExponentPart

Purpose

Return the exponent portion of a numeric value.

For example, the exponent of 3.2e18 is 18.

Return Value

Exponent portion of a numeric value.

Syntax

numeric := ExponentPart (Value: numeric)

Parameters

Value

numeric A fractional number (return exponent part of).

Factorial

Purpose

Return the Nth factorial, which is the product of all numbers in a series (1, 1, 2, 5, 24,...) less than or equal to a specified value.

Return Value

Nth factorial.

Syntax

numeric := Factorial (Nth: numeric)

Parameters

Nth

numeric Compute the Nth term in the series.

False

Purpose

The constant boolean value FALSE.

Syntax

boolean := False

Fibonacci

Purpose

Return the Nth term in a Fibonacci sequence (0, 1, 1, 2, 3,...). The Fibonacci is the sum of the preceding two terms in the series.

Return Value

Nth term in a Fibonacci sequence.

Syntax

numeric := Fibonacci (Nth: numeric)

Parameters

Nth

numeric Term of the Fibonacci sequence to return.

FileConvert

Purpose

Converts a file of one type to a file of another type. The available file types depends on the converters installed by the user. Not all conversions are available on all systems.

A file can only be converted to a similar file type (documents to documents, graphics to graphics, and so on).

Return Value

The common return values follow. Any value not equal to Success! is an error. Other error values are returned as numeric values.

Success!

Successful conversion.

InAndOutSame!

Input and output filenames were the same (they must be different).

NoDriver!

Conversion driver not available for requested conversion. It may need to be installed.

UnknownType!

File type unknown.

UnknownGraphic!

Graphic file type cannot be converted.

InvalidSource!

Invalid source filename.

InvalidDestination!

Invalid destination filename.

Incompatible!

Destination file type is incompatible with the source file type.

Syntax

enumeration or numeric := FileConvert (SourceFilename: string; [SourceFileType: enumeration or numeric]; DestinationFilename: string; DestinationFileType: enumeration or numeric)

Parameters

SourceFilename

string Name of file to convert.

SourceFileType

enumeration or numeric (optional) Type of source file to convert. If missing, AutoDetect! is used. Many of the file types returned by the FileType command are valid source file types. Types not listed may be specified as numeric values.

AutoDetect!

Automatically detects the file type using the FileType command.

WordPerfect42!

WordPerfect50!

WordPerfect51!

WordPerfect678!

WordPerfectCompound!

WPMac31!

WordStar70!

MSWord55!

Word60!

Word97!

RichTextFormat!

AsciiText!

AsciiFormatted!

AsciiDelimited!

AsciiCRLFtoSRT!

AsciiGenericWP!

AnsiText

AnsiDelimited!

AnsiCRLFtoSRT!

AnsiGenericWP!

AmiPro30!

WindowsWrite!

HTML!

WPG1!

WPG2!

TIFF!

WMF!

BMP!

GIF!

JPG!

CorelDRAW7!

Excel70!

Excel97!

Lotus123v4!

PresentationsMaster!

PresentationsMaster3!

DestinationFilename

string Name of the output file.

DestinationFileType

enumeration or numeric Type of file to convert to. These values may change between major releases of PerfectScript. The common file types follow. Types not listed may be specified as numeric values.

WordPerfect42!

WordPerfect50!

WordPerfect51!

WordPerfect678!

WordPerfectCompound!

WPMac31!

WordStar70!

MSWord55!

Word60!

Word97!

RichTextFormat!

AsciiText!

AsciiDelimited!

AsciiGenericWP!

AnsiText

AnsiDelimited!

AnsiGenericWP!

AmiPro30!

WindowsWrite!

HTML!

WPG1!

WPG2!

TIFF!

WMF!

BMP!

GIF!

JPG!

CorelDRAW7!

PresentationsMaster!

PresentationsMaster3!

FileConvertError

Purpose

Returns the name of a file conversion error.

Return Value

Printable name of the error returned by the FileType command.

Syntax

string := FileConvertError (ErrorCode: enumeration or numeric)

Parameters

ErrorCode

enumeration or numeric Error code for which to return a name, returned by the FileType command. The more common values follow. Specify other error values as numeric values.

InAndOutSame!

Input and output filenames were the same (they must be different).

NoDriver!

Conversion driver not available for requested conversion. It may need to be installed.

UnknownType!

File type unknown.

UnknownGraphic!

Graphic file type cannot be converted.

InvalidSource!

Invalid source filename.

InvalidDestination!

Invalid destination filename.

Incompatible!

Destination file type is incompatible with the source file type.

FileError

Purpose

Return the error associated with the last file command.

Example

Appendix A: 8090

Return Value

A number greater than 0 (last file error), -1 (unknown error), or 0 (no error). Error numbers have loword and hiword values. The loword contains an error code generated by Corel WordPerfect’s I/O routines, described in the Corel WordPerfect for Windows SDK (WError.H file). The hiword contains a Windows specific error value, described in the Microsoft Windows SDK.

Syntax

numeric := FileError

FileFind

Purpose

Find a file that matches user-defined search criteria (filename and DOS attributes).

Example

Appendix A: 8090

Return Value

A filename, or an empty filename if no match is found.

Syntax

string := FileFind ([Filename: string]; [Attributes: enumeration]; [Context: numeric])

Parameters

Filename

string (optional) Include the full path. If missing, the next matching file is found (see Context below).

Attributes

enumeration (optional) Default: Normal!

Normal!

ReadOnly!

Hidden!

System!

Label!

Directory!

In addition to files, directories are also returned. This does not return directories only.

Archived!

Context

numeric (optional) A user-defined number which identifies the search. Default: 0. To find the next file to match the search criteria, call FileFind with an empty filename. For example,

vFilename = FileFind (Filename: "*.WPD"; Attributes: Normal!; Context: 1)

finds the first occurrence of a file with a WPD extension. The following statement finds the next file to match the same search criteria:

vFilename = FileFind (Filename: ""; Context: 1)

Use different Context values to perform multiple searches simultaneously. If you perform more than one search before the macro ends, you can continue any search by using the appropriate Context value. The subsequent search begins where it left off.

FileIsEOF

Purpose

Return True if the insertion point is at the end of a file, False if not.

The access mode must be Read! (see OpenFile).

Example

Appendix A: 8088

Return Value

True/False.

Syntax

boolean := FileIsEOF (FileID: numeric)

Parameters

FileID

numeric See OpenFile.

FileNameDialog

Purpose

Display the Open or Save As dialog.

Return Value

The name of the file to open or save, or "" if Cancel is pressed.

Syntax

string := FileNameDialog (StyleOptions: enumeration; [CaptionText: string]; [ButtonText: string]; [InitialFolder: string]; [InitialFileName: string]; [FileTemplate: string]; [RecentFiles: string])

Parameters

StyleOptions

enumeration Specifies the type of dialog to open and the options associated with the dialog. Type | between enumerations to combine styles. For example: OpenDialog! | FileMustExist!.

OpenDialog!

Display the Open dialog.

SaveAsDialog!

Display the Save As dialog.

FileMustExist!

Use with OpenDialog!. The file selected for Open must exist.

PromptOnReplace!

Use with SaveAsDialog!. If the file already exists, a prompt is displayed asking whether the file should be replaced.

CaptionText

string (optional) Text displayed in the caption bar. If missing or "", Open or Save As is displayed.

ButtonText

string (optional) Text displayed on the Open button. If missing or "", Open is displayed.

InitialFolder

string (optional) Initial folder to display. If missing or "", the current folder is displayed.

InitialFileName

string (optional) Initial filename to display. If missing or "", FileTemplate is displayed.

FileTemplate

string (optional) Template for the files to display. If missing or "", *.* files are displayed.

RecentFiles

string (optional) Name of registry subkey where the recent files list is maintained. For example, "HKEY_CURRENT_USER\Software\..." The list can contain up to fifteen filenames. If missing, no history is given. Include the full Registry path where the recent file list is maintained.

FilePosition

Purpose

Return the current marker position or set a new position.

A user can pre-allocate file size by setting the position marker past the end-of-file marker.

Example

Appendix A: 8088

Return Value

The position of the old position marker, or a negative number if an error occurs.

Syntax

numeric := FilePosition (FileID: numeric; [NewPosition: numeric]; [PositionFrom: enumeration])

Parameters

FileID

numeric See OpenFile.

NewPosition

numeric (optional) The number of bytes to move the position marker. Default: 0.

PositionFrom

enumeration (optional) Move the position marker relative to one of the following positions. Default: FromBeginning!

FromBeginning!

FromCurrentPosition!

FromEnd!

FileRead

Purpose

Read text data from an open file.

Example

Appendix A: 8088

Return Value

The number of bytes read, or a negative number if an error occurs.

Syntax

numeric := FileRead (FileID: numeric; Data: variable)

Parameters

FileID

numeric See OpenFile.

Data

variable Starting from the position marker, one line of data is converted to a WP character string and returned in this variable.

FileSize

Purpose

Return a file’s size in bytes.

Example

Appendix A: 8088

Return Value

The file size in bytes, or a negative number if an error occurs.

Syntax

numeric := FileSize (Filename: string)

Parameters

Filename

string Include the full path.

FileTruncate

Purpose

Remove all text data after the position marker (see FilePosition).

Example

Appendix A: 8089

Return Value

The truncated file size (bytes) if successful, or a negative number if an error occurs.

Syntax

numeric := FileTruncate (FileID: numeric)

Parameters

FileID

numeric See OpenFile.

FileType

Purpose

Return a file’s file type.

Return Value

Detected file type (get errors from the FileError command). The more common file types are listed below. Since over 200 file types are recognized, those not listed are returned as numeric values. The values returned may change in future releases of PerfectScript.

Unknown!

File doesn’t exist, or the file type is unknown.

WordPerfect42!

WordPerfect50!

WordPerfect51!

WordPerfect678!

WordPerfectCompound!

WPMac31!

COJava!

WordStar70!

MSWord55!

Word60!

Word97!

RichTextFormat!

AsciiText!

AnsiText!

AmiPro30!

WindowsWrite!

HTML!

SGML!

WPG1!

WPG2!

TIFF!

WMF!

BMP!

GIF!

JPG!

CorelDRAW7!

Excel70!

Excel97!

Lotus123v4!

Show!

SDIF!

Syntax

enumeration or numeric := FileType (Filename: string)

Parameters

Filename

string Name of file to detect.

FileTypeExtension

Purpose

Return the default filename extension of a file type returned by the FileType command.

Return Value

The default filename extension of FileType (usually two or three characters). If FileType does not have an extension, or if you specify an invalid file type, an empty string is returned.

Syntax

string := FileTypeExtension (Filetype: enumeration or numeric)

Parameters

Filetype

Eumeration or numeric Type of file for which to return the default filename extension. This value is returned by the FileType command. The following list contains some of the possible values for FileType. Types not listed can be specified as numeric values.

WordPerfect42!

WordPerfect50!

WordPerfect51!

WordPerfect678!

WordPerfectCompound!

WPMac31!

COJava!

WordStar70!

MSWord55!

Word60!

Word97!

RichTextFormat!

AsciiText!

AnsiText!

AmiPro30!

WindowsWrite!

HTML!

SGML!

WPG1!

WPG2!

TIFF!

WMF!

BMP!

GIF!

JPG!

CorelDRAW7!

Excel70!

Excel97!

Lotus123v4!

Show!

SDIF!

FileTypeList

Purpose

Return an array (list) of detected file types.

Return Value

An array of file types (the same types returned by the FileType command). Associated names are obtained by passing the file types to the FileTypeName command.

Syntax

array := FileTypeList (FileType: enumeration)

Parameters

ListType

enumeration Type of list to obtain.

Detect!

Detected file types.

Source!

File types that are recognized as source file types when calling the FileConvert command.

Destination!

File types that can be destinations when calling the FileConvert command.

FileTypeName

Purpose

Returns the name of a file type.

Return Value

Printable name of the file type returned by the FileType command.

Syntax

string := FileTypeName (FileType: enumeration or numeric)

Parameters

FileType

enumeration or numeric Type of file for which to return a printable name. This value is returned by the FileType command. The following list contains some of the possible values for FileType. Types not listed can be specified as numeric values.

WordPerfect42!

WordPerfect50!

WordPerfect51!

WordPerfect678!

WordPerfectCompound!

WPMac31!

COJava!

WordStar70!

MSWord55!

Word60!

Word97!

RichTextFormat!

AsciiText!

AnsiText!

AmiPro30!

WindowsWrite!

HTML!

SGML!

WPG1!

WPG2!

TIFF!

WMF!

BMP!

GIF!

JPG!

CorelDRAW7!

Excel70!

Excel97!

Lotus123v4!

Show!

SDIF!

FileWrite

Purpose

Write text data to a file.

Example

Appendix A: 8088

Return Value

The number of bytes written, or a negative number if an error occurs.

Syntax

numeric := FileWrite (FileID: numeric; Data: string; [NewLine: enumeration]; {[ParameterData: string]})

Parameters

FileID

numeric See OpenFile.

Data

string Text data is converted to the type specified when the file is opened. A caret (^) followed by a number is replaced by the corresponding character string in the ParameterData parameter. To write a caret, use two carets (^^).

NewLine

enumeration (optional)

Default

NoNewLine!

NoNewLine!

Inserts an end-of-line marker.

NewLine!

ParameterData

string (optional)

The text data inserted in the data string (see Data parameter). Up to 10 strings separated by semicolons are allowed. Numbering begins with 0. For example,

FileWrite (FileID; Data: "My friend ^0 is ^1 years old."; NewLine: NewLine!; ParameterData: {"Dan"; "41"})

writes “My friend Dan is 41 years old.” followed by an end-of-line marker.

Floor

Purpose

Return the largest integer that is less than or equal to a specified value (the floor of a number).

Return Value

Integer.

Syntax

numeric := Floor (Value: numeric)

Parameters

Value

numeric Return the floor of this number.

For

Purpose

A control statement (loop) that executes a specified number of times (see Loop Statements in Chapter 5: Conditional, Loop, and Calling Statements).

The loop executes only if TerminateExp is true, and continues to execute until ControlVariable’s value makes TerminateExp false. EndFor closes a For statement.

The general form of a For statement is:

For (<ControlVariable>; <InitialValue>;<TerminateExp>; <IncrementExp>)

...statement block...

EndFor

For example, the following statement initializes vTest to one, repeats the statement block while vTest is less than ten, and increments vTest by two after each loop.

For(vTest; 1; vTest 10; vTest + 2)

...statement block...

EndFor

Example

Appendix A: 8022

Syntax

For (<ControlVariable> variable; <InitialValue> any; <TerminateExp> boolean; <IncrementExp> any)

Parameters

ControlVariable

variable The control variable.

InitialValue

any The value assigned to ControlVariable at the start of a loop.

TerminateExp

boolean The loop executes while TerminateExp is true.

IncrementExp

any The value to increment ControlVariable after each loop.

ForEach

Purpose

A loop statement that executes a number of times equal to the number of specified expressions (see Loop Statements in Chapter 5: Conditional, Loop, and Calling Statements).

ControlVariable is assigned the first value before the first loop; the second value before the second loop; the third value before the third loop; and so forth. The statement block uses the value of ControlVariable to direct macro execution. EndFor closes a ForEach statement.

The general form of a ForEach statement is:

ForEach (ControlVariable; {ValueList; ...})

...statement block...

EndFor

For example, the following statement repeats three times. The variable vTest is initialized to "Apples" before the first loop, to "Oranges" before the second, and to "Bananas" before the third.

ForEach(vTest; {"Apples"; "Oranges"; "Bananas"})

... statement block ...

EndFor

Example

Appendix A: 8003

Syntax

ForEach (<ControlVariable> variable; {<ValueList> any})

Parameters

variable The control variable.

any Variables, arrays, constants, or expressions, enclosed in braces and separated by a semicolon.

ForNext

Purpose

A loop statement that executes a specified number of times (see Loop Statements in Chapter 5: Conditional, Loop, and Calling Statements).

The loop executes if ControlVariable is less than or equal to FinalValue, and executes until ControlVariable is greater than FinalValue. If you use a negative value in IncrementValue, the loop executes until ControlVariable is less than FinalValue. EndFor closes a ForNext statement.

The general form of a ForNext statement is,

ForNext (ForNext (<ControlVariable>; <InitialValue>; <FinalValue>; <IncrementValue>)

...statement block...

EndFor

The following statement initializes vTest to one, repeats the statement block while vTest is less than or equal to five, and increments vTest by two after each loop.

ForNext(vTest; 1; 5; 2)

...statement block...

EndFor

Example

Appendix A: 8001

Syntax

ForNext (<ControlVariable> variable; <InitialValue> any; <FinalValue> any; [<IncrementValue> any])

Parameters

ControlVariable

variable The control variable.

InitialValue

any The value assigned to ControlVariable at the start of a loop.

FinalValue

any A variable, constant, or expression. The loop executes while FinalValue is greater than ControlVariable, or less than ControlVariable if IncrementValue is a negative value.

IncrementValue

any (optional) The value to increment ControlVariable after each loop. Default is 1.

Fraction

Purpose

Return the fractional portion of a real number.

Example

Appendix A: 8023

Return Value

A fraction.

vFraction := Fraction(1.5)

Result: vFraction equals 0.5

vResult := Fraction(1.77 * 2)

Result: vResult = 0.54

Syntax

numeric := Fraction (Value: numeric)

Parameters

Value

numeric A real number.

FractionalPart

Purpose

Return the fractional portion of a numeric value.

vFrac := FractionalPart (3.2)

Result: vFrac = 0.2

Return Value

Fractional portion of a numeric value.

Syntax

numeric := FractionalPart (Value: numeric)

Parameters

Value

numeric A fractional number.

FractionStr

Purpose

Return a fraction string representing a value.

vStr := FractionStr (4.5; 0; MixedFraction!)

Result: vStr = "4 1/2"

vStr := FractionStr (4.5; 8; MixedFraction!)

Result: vStr = "4 4/8"

Return Value

Fraction string.

Syntax

string := FractionStr (Value: numeric; [Denominator: numeric]; [Option: enumeration])

Parameters

Value

numeric The numerical value to be converted.

Denominator

numeric (optional) The denominator (the nearest fraction using this denominator is returned). If missing, or less than or equal to zero, the nearest denominator is used.

Option

enumeration (optional) Specify the fraction form used for values greater than 1. Default: ImproperFraction!

ImproperFraction!

Numerator is larger than the denominator.

MixedFraction!

A whole number, followed by a proper fraction (numerator is smaller than the denominator).

Function

Purpose

Identify a macro subroutine that can receive one or more values from a calling statement (see Calling Statements in Chapter 5: Conditional, Loop, and Calling Statements). Function also returns a value to the calling statement (caller).

Functions contain one or more statements that execute when the function is called. Unlike Label statements, functions do not execute unless called. A calling statement consists of the function’s name, and can have one or more parameters that pass values to the function. Return, EndFunc, or EndFunction direct macro execution to the statement that follows the function’s caller. Return also returns the result of a function operation, or 0 if no result is specified. For example,

y := 5

x := Add(y) // calling statement

Function Add(z)

z := z + 5

Return(z)

EndFunc

assigns the value 10 to variable x. Add is the name of the function, and y contains a value to pass. Variable z has no value until the function is called, when the value of z is function statement assigns 10 to variable z. The next statement returns the value of z to the calling statement, which is then assigned to variable x. If the function did not contain a Return statement, or if Return did not return a value, x would be equal to 0.

Address Mode

In the above example, the value of y does not change. The function returns the value of z in variable x. To change the value of a variable passed to a function, precede the calling statement parameter and its corresponding function parameter with an ampersand (&). For example,

y := 5

x := Add(&y)

Function Add(&z)

z = z + 5

Return(z)

EndFunc

assigns the value 10 to both x and y. The ampersand before variable x means the variable’s address (location in memory) is passed to the function, not the variable’s value. Changes made at the address of x are made to the contents of x.

Arrays

You pass arrays to functions the same way you pass variables. If you are passing the entire array, every array element must be assigned a value. If not, a run-time error identifies a reference to the undefined element. For example,

Declare w[10]

ForNext(x; 1; 9; 1) // assign only 9 elements

w[x] = x

EndFor

Function Test(z[ ])

ForNext(x; 1; 10; 1)

x[z] = x * 10

EndFor

Return(z[ ]) // the value of 10 elements returned

EndFunc

y[ ] = Test(w[ ]) // 10 elements returned in array y[ ]

Type(y[10]) // y[10] equals 100

Type(w[10]) // Run-time error: Undefined variable "W[10]"

In the previous example, if you precede the calling statement parameter and the corresponding function parameter with an ampersand (&), 100 is returned in w[10]. No run-time error occurs. You are passing the address of array w[ ], not its value. The value is assigned inside the function (see Address Mode above). The two statements look like this:

Function Test(&z[ ])

and

y[ ] = Test(&w[ ])

Pass the value of an array element, the same way you pass a variable. For example,

Declare w[10]

ForNext(x; 1; 10; 1)

w[x] = x

EndFor

Function Test(z)

z := z * 10

Return(z)

EndFunc

y = Test(w[1])

Type(y + " - ")

Type(w[1])

The value of y equals 10. The value of w[1] equals 1. If you precede the calling statement parameter and the corresponding function parameter with an ampersand (&), the value of y equals 10 and the value of w[1] equals 10. Passing the address of w[1] causes its value to change inside the function. The two statements look like this:

Function Test(&z)

and

y = Test(&w[1])

The general form of a Function statement is:

Function <Name> (<Parameter>; <Parameter>; ... <Parameter>)

...statement block...

EndFunc

The syntax accepts EndFunc or EndFunction.

Example

Appendix A: 8024

Syntax

Function <Name> label ({[<Parameter> any]})

Parameters

<Name>

label The name of a function. It begins with a letter and consists of one or more letters or numbers.

{<Parameter>}

any (optional) Receives a value from a calling statement (see Calling Statements in Chapter 5: Conditional, Loop, and Calling Statements). If an ampersand precedes the calling statement variable, an ampersand must precede the corresponding function variable (see Address Mode above). Multiple variables are separated by a semicolon.

Function Prototype

Purpose

Verify the syntax of a Function statement (see Function).

If the syntax of a function contained in a Use macro file is incorrect and the function is called from the main macro, you get a run-time error but not a compile-time error (see Compiler Errors in Chapter 3: Creating Macros). Using Function Prototype at the start of a main macro ensures that you get a compile- time error.

Example

Appendix A: 8024

Syntax

Function Prototype <Name> label ({[<Parameter> any]})

Parameters

<Name>

label The name of the function. It begins with a letter and consists of one or more letters or numbers.

{<Parameter>}

any (optional) Receive a value from a calling statement (see Calling Statements in Chapter 5: Conditional, Loop, and Calling Statements). If an ampersand precedes the calling statement variable, an ampersand must precede the corresponding function variable (see Address Mode under Function). Multiple variables are separated by a semicolon.