Copyright: Actuate Software Corporation


  Actuate Basic Language Reference

The Actuate Basic language reference consists of a language summary, a set of grouped lists of functions and statements, AB data types, AB keywords, AB operators, and an alphabetical listing of all the Actuate Basic functions and statements.

Language summary. This section provides grouped lists of functions and statements that are frequently used together to perform specific programming tasks.

Statements and functions. This section contains an alphabetical reference for all functions and statements.

Data types. Actuate Basic data types. This section contains information about data types supported by Actuate Basic.

Keywords This section contains information about Actuate Basic keywords.

Operators This section contains information about Actuate Basic operators.

See also

Using the code examples


Language summary

This reference provides grouped lists of functions and statements that are frequently used together to perform specific programming tasks. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	Arrays

•	Classes and instances

•	Controlling program flow

•	Converting

•	Date and time

•	Environment

•	Error trapping

•	File input and output

•	Finances

•	Graphics and printing

•	Math

•	Operators

•	Procedures

•	Strings

•	Variables and constants


Arrays

Programming task	Function/Statement
Change default lower limit	Option Base statement
Declare and initialize	Dim statement, Global statement, ReDim statement, Static statement
Test the limits	LBound function, UBound function
Reinitialize	Erase statement, ReDim statement


Classes and instances

Programming task	Function/Statement
Declare classes	Class statement
Create an instance of a class	NewInstance function, NewPersistentInstance function, IsPersistent function
Access class variables	GetClassID function, GetClassName function, GetValue function, GetVariableCount function, GetVariableName function, IsKindOf function, SetBinding function
Copy class variable values	CopyInstance statement


Controlling program flow

Programming task	Function/Statement
Branch	GoTo statement, On Error statement
Exit or pause the program	End statement, Stop statement
Loop	Do...Loop statement, For...Next statement, While...Wend statement
Make decisions	If...Then...Else statement, IIf function, Select Case statement


Converting

Programming task	Function/Statement
ANSI value to string	Chr, Chr$ functions
Binary image file to string	ConvertBFileToString function
Date to serial number	DateSerial function, DateValue function
Decimal numbers to others	Hex, Hex$ functions,  Oct, Oct$ functions
Number to string	Format, Format$ functions, Str, Str$ functions
One data type to another data type	CCur function, CDate function, CDbl function, CInt function, CLng function, CSng function, CStr function, CVar function, CVDate function, Fix function, Int function
Serial number to date	Day function, Month function, Weekday function, Year function
Serial number to time	Hour function, Minute function, Second function
String to ANSI value	Asc function
String to binary image file	ConvertStringToBFile function
String to HTML as literal	ConvertToHtml function
String to number	Val function
Time to serial number	TimeSerial function, TimeValue function


Date and time

Programming task	Function/Statement
Convert date to serial number	DateSerial function, DateValue function
Convert serial number to date	CVDate function, Day function, Month function, Weekday function, Year function
Convert serial number to time	Hour function, Minute function, Second function
Convert time to serial number	TimeSerial function, TimeValue function
Convert to date data type	CDate function, CVDate function
Get current date or time	Date, Date$ functions, Now function, Time, Time$ functions, IsDate function
Manipulate date or time	DateAdd function, DateDiff function, DatePart function
Time process	Timer function


Environment

Programming task	Function/Statement
Clear Clipboard	ClearClipboard function
Find environment variables	Environ, Environ$ functions
Get Clipboard text	GetClipboardText function
Get command-line arguments	Command, Command$ functions
Get login name of user logged into the report server	GetServerUserName function
Get machine name of user logged into the report server	GetServerName function
Get name of Actuate application currently running	GetAppContext function
Get operating system (login) name of the user	GetOSUserName function
Get version number of the AFC library	GetAFCROXVersion function
Get version number of the Factory the ROX is using	GetFactoryVersion function
Get version number of ROX file	GetROXVersion function
OLE	CreateObject function
Run other programs	Shell function
Set Clipboard text	SetClipboardText function
Sound beep	Beep statement


Error trapping

Programming task	Function/Statement
Get error messages	Error, Error$ functions
Get error status	Err function, Erl function
Insert explanatory remarks	Rem statement
Prevent division-by-zero error	SafeDivide function
Prevent logic error by predetermining whether a condition is true	Assert statement
Set Err function to a given value	Err function
Simulate run-time errors	Error, Error$ functions
Trap errors while program is running	Assert statement, On Error statement, Resume statement


File input and output

Programming task	Function/Statement
Access or create files	Open statement
Close files	Close statement, Reset statement
Control output appearance	Space, Space$ functions, Tab function, Width # statement
Copy one file to another	FileCopy statement
Display dialog boxes	InputBox, InputBox$ functions, MsgBox statement
Get information on files	EOF function, FileAttr function, FileDateTime function,FileExists function,FileLen function, FreeFile function, Loc function, LOF function, Seek statement, Seek2 function
Manage disk drives and directories	ChDir statement, ChDrive statement, CurDir, CurDir$ functions, MkDir statement, RmDir statement
Manage files	Kill statement, Lock...Unlock statement, Name statement
Read from file	Get statement, Input # statement, Input, Input$ functions, InputB, InputB$ functions, Line Input # statement
Retrieve strings from resource files	StrLoad, StrLoad$ functions
Set or get file attributes	GetAttr function, SetAttr statement
Set read-write position in file	Seek statement
Write to file	Print # statement, Put statement, Write # statement


Finances

Programming task	Function/Statement
Depreciation of assets	DDB function, SLN function, SYD function
Get annuity information	FV function, IPmt function, NPer function, Pmt function, PPmt function, PV function, Rate function
Get net present value and rate of return	IRR function, NPV function, MIRR function


Graphics and printing

Programming task	Function/Statement
Decode string into binary image file	ConvertStringToBFile function
Encode binary image file into string	ConvertBFileToString function
Dynamically adjust the height of a container to accomodate a large amount of text	GetDisplayHeight function (Windows only)
Print Text	Print # statement, Write # statement
Work with colors	QBColor function, RGB function


Math

Programming task	Function/Statement
General calculation	Exp function, Log function, Sqr function
Generate random numbers	Randomize statement, Rnd function
Get absolute value	Abs function
Get the sign of expressions	Sgn function
Numeric conversions	Fix function, Int function
Trigonometry	Atn function, Cos function, Sin function, Tan function


Operators

Programming task	Function/Statement
Arithmetic	* operator, + operator, - operator, \ operator, / operator, ^ operator, Mod operator
Comparison	<, =<, >, >=, =, <>Comparison operators, Is operator
Concatenation	& operator
Logical expressions	And operator, BAnd operator, Eqv operator, Imp operator, Not operator, BNot operator, Or operator, BOr operator, XOr operator
Pattern matching	Like operator


Procedures

Programming task	Function/Statement
Call Sub procedure	Call statement
Declare references to external procedures	Declare statement
Define procedures	Function...End Function statement, Sub...End Sub statement
Exit from procedures	Exit statement, Function...End Function statement, Sub...End Sub statement


Strings

Programming task	Function/Statement
Assign value	Let statement
Compare two strings	StrComp function
Convert to lowercase or uppercase letters	LCase, LCase$ functions, UCase, UCase$ functions
Copy to and from Clipboard	SetClipboardText function, GetClipboardText function
Create strings of repeating characters	Space, Space$ functions, String, String$ functions
Find the length of an expression in bytes	LenB function
Find the length of a string	Len function
Format strings	Format, Format$ functions
Justify strings	LSet statement, RSet statement
Manipulate strings	InStr function, Left, Left$ functions, LTrim, LTrim$ functions Mid, Mid$ functions, Right, Right$ functions, RTrim, RTrim$ functions, Trim, Trim$ functions
Manipulate bytes	InStrB function, LeftB, LeftB$ functions, RightB, RightB$ functions, MidB, MidB$ functions
Set string comparison rules	Option Compare statement
Translate from one language to another	Encode, Encode$ functions, Decode, Decode$ functions
Work with ASCII and ANSI values	Asc function, Chr, Chr$ functions


Variables and constants

Programming task	Function/Statement
Declare variables and constants	Const statement, Dim statement, Global statement, Static statement
Assign object references to variables	Set statement
Declare user-defined variables or record structures	Type...End Type statement
Declare aliases for existing object types	Type...As statement
Get information about Variant variables	IsDate function, IsEmpty function, IsNull function, IsNumeric function, VarType function


Using the code examples

Example

The easiest way to use the Actuate Basic code examples is to copy the code from the Code Example window in online help into the Method Editor window in the Developer Workbench.

To open an example in the online help:

1	Choose Help→Contents

2	In the Table of Contents window, scroll to Actuate Basic Reference, "Using the code examples."

3	Click on the green link, "Example." This link lies under the topic title.

It displays the code example in a secondary window.

To use a code example in a Developer Workbench report design, do the following:

1	Choose File→Open New Basic File.

2	Select the default file name Source1.BAS.

3	Move your cursor back to the Code Example window of the online help.

4	Select the piece of code described under step a of the code example.

5	Use the copy and paste options to paste the part of the example you wish to use into the Source1.BAS file.

6	Save the .BAS file.

Note: Not all examples will have a Declaration section. If the example you are using does not include a Declare,...End Declare statement, you do not have to paste anything in the .BAS file.

Next, in the Developer Workbench application, do this:

1	Use the Drawing/Graphics Rectangle tool to draw an object in the report.

2	Double-click the object to open the Component Editor window.

3	Select the Methods tab.

4	Scroll down the list to Function OnLButtonDblClk.

5	Click Override. If you are modifying an existing object, click Edit.

6	In the Method Editor window, paste the selected code from the example from step b. Place it just under the line that says 'Insert your code here.

7	Click Update to save your changes.

To compile and run your report, do the following:

1	Choose Report→Build/Run/View.

2	Click OK in the Requester window.

Your report displays.

To run your AB function:

1	Double-click on the object in your report.

The function runs and the message box displays several prompts.

2	Answer the prompts.

The function displays the final result.


Example

The following example demonstrates the FV function. The example shows you where exactly to paste the different parts of a code example. To use this example, follow steps a through d below.

a	Paste the following code into your Actuate Basic source code (.BAS) file.

Declare

Global Const ENDPERIOD = 0

Global Const BEGINPERIOD = 1

End Declare

b	Paste the following code into the OnLButtonDblClk() method of a label or other control, where it says 'Insert your code here.

Dim EachPmt As Double, APR As Double

Dim TotalPmts As Single, PayWhen As Integer

Dim PresentVal As Double, FutureVal As Double

Dim Msg as String, Fmt As String

' Specify money format

Fmt = "$###,###,##0.00"

' Get user input

Msg = 	"How much will you save each month?"

EachPmt = InputBox(Msg)

Msg = "What is the annual percentage rate for the interest?"

APR = InputBox(Msg)

' Ensure proper form as %

If APR > 1 Then

APR = APR / 100

End If

Msg = "For how many months will you save?"

TotalPmts = InputBox(Msg)

Msg = "Will you make payments at month's end?"

PayWhen = MsgBox(Msg, MB_YESNO)

If PayWhen = IDNO Then

PayWhen = BEGINPERIOD

Else

PayWhen = ENDPERIOD

End If

Msg = "What amount is in this savings account now?"

PresentVal = InputBox(Msg)

' Now do the real work

FutureVal = FV(APR / 12, TotalPmts, -EachPmt, -PresentVal, PayWhen)

' Format the resulting information for the user

Msg = "Starting with " & Format(PresentVal, Fmt) & " "

Msg = Msg & " and saving " & Format(EachPmt, Fmt) & " every month at"

Msg = Msg & " an interest rate of " & Format(APR, "##.0%")

Msg = Msg & " for a period of " & TotalPmts

Msg = Msg & " months will give you " & Format(FutureVal, Fmt) & "."

MsgBox Msg

c	Build, run, and view your report.

d	Double-click on the label or control and follow the prompts.


Statements and functions

This reference lists the statements and functions for the Actuate Basic Language. To view the topics in order use the Browse button (>>) in the Help windows toolbar.


Abs function

Example   See also

Returns the absolute value for a number or expression.

Syntax

Abs(<number expression>)

<number expression>

Number, numeric expression, or Variant of VarType 8 (String) that specifies the number for which you want to find the absolute value.

Return value

Number, numeric expression, or Variant of VarType 8 (String)

Rule: If <number> evaluates to Null, Abs returns a Null.


Example

The following example demonstrates the return value of Abs.

Function OnLButtonDblClk ( )

' Returns 25

MsgBox Abs(25)

' Returns 25

MsgBox Abs(-25)

End Function

For information about using the code examples, see Using the code examples.


See also

Sgn function


Asc function

Example   See also

Returns the ANSI code that corresponds to the given character.

Syntax

Asc(<string expression>)

<string expression>

Any string expression that represents a character Asc translates to a corresponding code in the ANSI character set.

Rules:

•	If <string expression> is longer than one character, Asc translates only the first character.

•	If <string expression> evaluates to Null, Asc returns a Null.

•	<string expression> must not be zero-length.

Example:

The following statements are equivalent. Each returns the numeric value 90.

Function OnLButtonDblClk ( )

MsgBox Asc("Z")

MsgBox Asc(Mid$("XYZ",3,1))

MsgBox Asc(UCase$("zebra"))

End Function

Return value

Integer

Tip

To translate from an ANSI code number to its corresponding character, use Chr$.


Example

The following example takes each letter in your name and shows you its corresponding ANSI value.

Function OnLButtonDblClk ( )

Dim I, Msg, NL, UserName

NL = Chr$(10)

UserName = InputBox$("Please type your name.")

For I = 1 To Len(UserName)

Msg = Msg & Mid$(UserName, I, 1) & " ---> "

Msg = Msg & Asc(Mid$(UserName, I, 1)) & NL

Next I

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Chr, Chr$ functions


Assert statement

Example   See also

Halts the program and displays an error message when a given condition is False.

Syntax

Assert(<condition>)

<condition>

Any numeric or string expression that can be evaluated. When <condition> evaluates to zero or Null, the condition is False, otherwise <condition> is True.

Description

When <condition> is True, Assert does nothing. When False, Assert halts the program and displays an error message.

Tip

Use Assert to trap errors.


Example

The following example uses Assert to halt a program before a function attempts to divide a number by zero. This prevents the program from even attempting to perform the illegal operation.

Function PercentOf(num As Integer, denom As Integer) As Integer

Assert(denom <> 0)

PercentOf = num * 100 / denom

End Function

For information about using the code examples, see Using the code examples.


See also

Erl function

Err function

Error statement

Error, Error$ functions

On Error statement


Atn function

Example   See also

Gives the arctangent of a number.

Syntax

Atn(<number>)

<number >

Number, numeric expression, or Variant of VarType 8 (String) that specifies in radians the ratio for which you want to find the arctangent. The ratio is the length of the side opposite the angle divided by the length of the side adjacent to the angle.

Return value

Double

Rule: If <number> evaluates to Null, Atn returns a Null.

Tip

To convert between radians and degrees, use: radians = degrees * Pi/180.


Example

The following example displays 0.46364761 and 1.2490.

Function OnLButtonDblClk ( )

MsgBox Atn(0.5)

MsgBox Atn(3)

End Function

For information about using the code examples, see Using the code examples.


See also

Cos function

Sin function

Tan function


Beep statement

Example

Sounds a short tone through the computer's speaker.

Syntax

Beep

Rules

•	You cannot control the tone or the duration of the sound using Beep.

•	Sound must be turned on in the sounds section of the Windows Control Panel.


Example

The following example prompts the user for a number. If the number falls outside a certain range recognized as valid, the computer beeps and displays a message.

Function OnLButtonDblClk ( )

Dim UserAns, Msg

Do

UserAns = InputBox("Please enter a value from 1 to 5.")

' Validate range

If UserAns >= 1 And UserAns <= 5 Then

Exit Do

Else

' Beep if not in range

Beep

MsgBox "Sorry, that number is out of range!"

End If

Loop

MsgBox "Thank you!"

End Function

For information about using the code examples, see Using the code examples.


Call statement

Example   See also

Transfers program control to an Actuate Basic Sub procedure or to a Windows dynamic-link library (DLL) procedure.

Syntax

[Call] <procedure name> [(<argument list>)]

Call

Optional keyword that indicates that Actuate Basic is to transfer program control to another procedure.

<procedure name>

Specifies the name of the procedure to which the program is to transfer control.

<argument list>

List of variables, arrays, or expressions to pass to the procedure as arguments.

Default: Arguments in list are passed by reference.

Tip: To pass an entire array, use its name followed by empty parentheses.

Examples:

The following statement transfers control to a Sub procedure called ManyBeeps and passes the value 15 to it as an argument.

Call ManyBeeps (15)

The following statement transfers control to a Sub procedure called ManyBeeps and passes the value 15 to it as an argument, but without using the Call keyword.

ManyBeeps (15)

The following statement transfers control to a Sub procedure called MySortArray, and passes the integer array NewColors% to it.

Call MySortArray (NewColors%( ))

Description

•	You are never required to use the Call keyword when you call a procedure.

•	You pass variable arguments to <procedure name> in two ways: "by reference" or "by value."

•	When you pass variables by reference, Actuate Basic assigns their contents (values) actual addresses. The called procedure can alter the variables.

•	When you pass variables by value, Actuate Basic assigns their contents (values) temporary addresses. The called procedure cannot alter the contents of the variables.

Rule

If you use the Call keyword to call a procedure that requires arguments, <argument list> must be enclosed in parentheses.

Tip

If you are having trouble passing arguments to DLL procedures, use the ByVal keyword to pass them by value. In many cases, external DLL routines may not support all Actuate Basic data types, and using ByVal to call such a DLL routine will allow the routine to convert the arguments so that it can accept them.


Example

The example shows two ways you can call the MessageBeep procedure in USER.EXE, a Microsoft Windows DLL. First, you must declare the procedure MessageBeep from the Windows dynamic link library at or near the beginning of your Actuate Basic source code (.BAS) file.

Declare Sub MessageBeep Lib "User32" (ByVal N As Integer)

Then type this example in the Method Editor:

Function OnLButtonDblClk ( )

Dim I As Integer

' Call Windows procedure

Call MessageBeep(0)

' Insert delay between calls

For I = 1 To 500: Next I

' Call again without Call keyword

MessageBeep (0)

End Function

For information about using the code examples, see Using the code examples.


See also

Declare statement


CCur function

Example   See also

Converts a numeric expression to the Currency data type.

Syntax

CCur(<numeric expression>)

<numeric expression>

Numeric expression to convert to the Currency data type from the Date, Integer, Long, Single, Double, String, or Variant data type.

Rules:

•	If <numeric expression> is Null, CCur returns Null.

•	If String or Variant, <numeric expression> must be interpretable as a number.

Examples:

Each of the following statements returns the value 123. In the second statement, the string "123" enclosed in double quotes is considered a numeric expression because it can be interpreted as a number.

CCur(123)

CCur("123")

The following statement generates an error. The string"123four" is not considered a numeric expression because 'four' cannot be interpreted as a number.

CCur("123four")

The following statement first converts the string"123four" using Val to convert the number 123. Val ignores the string component ("four").

CCur(Val("123four"))

Return value

Currency

•	One of eight Actuate Basic data type conversion functions.

•	If <numeric expression> lies outside the acceptable range for Currency, an overflow error occurs.

Tips

•	To convert an expression to currency without explicitly using CCur, assign the expression to a variable that is the Currency data type.

•	To declare the data type of a variable, use Dim with the As clause.

•	To declare the data type of a variable dynamically--without using Dim or one of these conversion functions--append the data type declaration character to the variable's name. For example, if you want a variable "Income" to contain only Currency data, refer to it as "Income@". If you want it to contain only Integer data, refer to it as "Income%".

•	To round a number to precisely the number of decimal places you want and discard anything residual, use Format$.

•	To be sure you pass the correct data type to a Sub procedure or to a Windows Dynamic Link Library (DLL), use data type conversion functions.


Example

The following example prompts you for a number, converts it using each of the conversion functions in turn, and displays the result.

Function OnLButtonDblClk()

Dim Orig As String, Msg As String, NL As String

NL = Chr$(10)

Orig = InputBox$("Please enter a number.")

Msg = "Your number is: " & Orig & NL & NL

Msg = Msg & "CCur(Orig) yields ----> " & CCur(Orig) & NL

Msg = Msg & "CDate(Orig) yields ----> " & CDate(Orig)  & NL

Msg = Msg & "CDbl(Orig) yields ----> " & CDbl(Orig) & NL

Msg = Msg & "CInt(Orig) yields ----> "  & CInt(Orig) & NL

Msg = Msg & "CLng(Orig) yields ----> " & CLng(Orig) & NL

Msg = Msg & "CSng(Orig) yields ----> " & CSng(Orig) & NL

Msg = Msg & "CStr(Orig) yields ----> "  & CStr(Orig) & NL

Msg = Msg & "CVar(Orig) yields ----> "  & CVar(Orig) & NL

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

CDate function

CDbl function

CInt function

CLng function

CSng function

CStr function

CVar function

CVDate function

Format, Format$ functions


CDate function

Example   See also

Converts an expression to a Variant of VarType 7 (Date).

Syntax

CDate(<date expression>)

<date expression>

Date expression, or any numeric or string expression that can be interpreted as a date, as a time, or as both a date and a time.

•	Can be a String such as "November 12, 1982 8:30 PM", "12 Nov, 1982 08:30 PM", "11/12/82", "08:30PM", or any other String that can be interpreted as a date, time, or date/time in the valid range.

•	Can be a date serial number such as 30267.854 (which corresponds to November 12, 1982 at 8:30 PM), or any other number that can be mapped to a date, time, or date/time in the valid range.

•	For date serial numbers, the Integer component represents the date itself while the decimal component represents the time of day on that date, where January 1, 1900 at precisely noon has the date serial number 2.5, and negative numbers represent dates prior to December 30, 1899 (0).

Default date if none specified: 0 (Dec 30, 1899)

Default time if none specified: 00:00:00 (midnight)

Rules:

•	If a time of day is included, it must be a valid time, even if CDate is not being used to return anything having to do with a time of day. A valid time is one that is in the range 0:00:00 (12:00:00 AM) through 23:59:59 (11:59:59 PM). Either the 12- or 24-hour clock can be used.

•	If a numeric expression, the numeric expression must be in the range -657434 to +2958465, inclusive.

•	For abridged date expressions ending in 00 through 29 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 2000. For example, while Year(4/30/1910) returns 1910, the abridged expression Year(4/30/10) returns 2010 (10 + 2000).

•	For abridged date expressions ending in 30 through 99 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 1900. For example, while Year(11/12/2082) returns 2082, the abridged expression Year(11/12/82) returns 1982 (82 + 1900).

Note that there are arguably "abridged" dates like Nov 12, 1982 (versus November 12, 1982) that do specify the century. Note also that both abridged and unabridged dates are dates ending in 00 through 99.

Examples:

The following statements are equivalent. Each assigns 11/12/82 8:30:00 PM (with its underlying serial number) to the variable BDate.

BDate = CDate("11/12/82 8:30 pm")

BDate = CDate("12 Nov 1982 20:30")

BDate = CDate("November 12, 1982 8:30PM")

BDate = CDate(30267.854167)

Return value

Date

•	If <date expression> is Null, CDate returns a Null.

•	If <date string> contains only numbers separated by valid date separators, CDate recognizes the order for month, day, and year according to the Short Date setting in the International section of the Windows Control Panel.

Rules

•	<date expression> must not be empty or zero-length.

•	Do not use CDate to convert a long date format that also contains the day-of-the-week string, like "Friday, Nov 12, 1982". The function will not recognize such strings as dates.

•	Avoid supplying CDate with a date in a format other than formats available in the Windows Control Panel.

Tip

To determine if either a numeric or string expression that looks like a date can actually be converted to a date, use IsDate. However, IsDate cannot determine whether a string that looks like a number can be converted to a date, even if the number is in the correct range for date serial numbers.


Example

The following example prompts the user for a date, a date and time, a time, or a date serial number. For any valid entry, it displays both a date and a date serial number.

Function OnLButtonDblClk()

Dim NL As String, DateMeme As String, ConvDateMeme As Date

Dim Msg As String

NL = Chr$(10)

Msg = "Please type a date, a date and time, "

Msg = Msg & "a time, or a date serial number."

DateMeme = InputBox(Msg)

ConvDateMeme = CDate(DateMeme)

MsgBox "The date you gave me was: " & ConvDateMeme & NL

MsgBox "The serial number for that date is: " & CDbl(ConvDateMeme)

End Function

For information about using the code examples, see Using the code examples.


See also

CCur function

CDbl function

CInt function

CLng function

CSng function

CStr function

CVar function

CVDate function

Format, Format$ functions

IsDate function


CDbl function

Example   See also

Converts a numeric expression to the Double data type.

Syntax

CDbl(<numeric expression>)

<numeric expression>

Numeric expression to be converted to the Double data type from the Currency, Date, Integer, Long, Single, String or Variant data type.

Rules for (<numeric expression>):

•	If <numeric expression> is Null, CDbl returns Null.

•	If <numeric expression> is of the data type String or Variant, <numeric expression> must be interpretable as a number.

Examples for (<numeric expression>):

Each of the following statements returns the value 123. In the second statement, the string"123" enclosed in double quotes is considered a numeric expression because it can be interpreted as a number.

CDbl(123)

CDbl("123")

The following statement generates an error. The string "123four" is not considered a numeric expression because 'four' cannot be interpreted as a number.

CDbl("123four")

The following statement uses Val to convert the string "123four" to the number 123. Val ignores the string component ("four").

CDbl(Val("123four"))

Returns

Double

•	One of nine data type conversion functions.

•	If <numeric expression> lies outside the acceptable range for a Double data type, an overflow error occurs.

Tips

•	To convert an expression to double without explicitly using CDbl, assign the expression to a variable that is the Double data type.

•	To declare the data type of a variable, use Dim with the As clause.

•	To declare the data type of a variable dynamically--without using Dim or one of these conversion functions--append the data type declaration character to the variable's name. For example, if you want a variable called "Income" to contain only Currency data, refer to it as "Income@". If you want it to contain only Double type data, refer to it as "Income#".

•	To round a number to precisely the number of decimal places you want and discard anything residual, use Format$.

•	To be sure you pass the correct data type to a sub procedure or to a Windows Dynamic Link Library (DLL), use data type conversion functions.


Example

The following example prompts you for a number, converts it using each of the conversion functions in turn, and displays the result.

Function OnLButtonDblClk()

Dim Orig As String, Msg As String, NL As String

NL = Chr$(10)

Orig = InputBox$("Please enter a number.")

Msg = "Your number is: " & Orig & NL & NL

Msg = Msg & "CCur(Orig) yields ----> " & CCur(Orig) & NL

Msg = Msg & "CDate(Orig) yields ----> " & CDate(Orig)  & NL

Msg = Msg & "CDbl(Orig) yields ----> " & CDbl(Orig) & NL

Msg = Msg & "CInt(Orig) yields ----> "  & CInt(Orig) & NL

Msg = Msg & "CLng(Orig) yields ----> " & CLng(Orig) & NL

Msg = Msg & "CSng(Orig) yields ----> " & CSng(Orig) & NL

Msg = Msg & "CStr(Orig) yields ----> "  & CStr(Orig) & NL

Msg = Msg & "CVar(Orig) yields ----> "  & CVar(Orig) & NL

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

CCur function

CDate function

CInt function

CLng function

CSng function

CStr function

CVar function

CVDate function

Fix function

Format, Format$ functions

Int function

Dim statement


ChDir statement

Example   See also

Changes the current working directory on the specified or current drive.

Syntax

ChDir <path name>

<path name>

String expression that specifies the name of the target directory.

Rule:

•	<path name> must contain fewer than 259 characters.

•	<path name> must be a valid directory.

<path name> has the following syntax:

[<drive:>] [\] [<directory>\<directory>]... (Windows)

[/] [<directory>/<directory>]... (UNIX)

<drive:>

Character, followed by a colon, that specifies the drive (Windows only.)

<directory>

String expression of the name of the directory or subdirectory to make the current directory.

Examples:

The following statement changes the current working directory on drive D: to "MYDOCS", even if the current drive is C:, but does not change the current drive to D.

ChDir "D:\MYDOCS"

Together, the following two statements change the current directory on the current drive to "\MYFILES\MAILBOX".

DirName$ = "\MYFILES\MAILBOX"

ChDir DirName$

Description

•	If you do not specify <drive:>, ChDir uses the current drive.

•	If you specify a drive other the than current one, Actuate Basic only changes the current directory on that drive; it does not change the current drive to <drive:>.

Tips

•	To make sure you have set the correct working directory before you issue commands that do not specify full path names, use ChDir.

•	To change the current drive, use ChDrive.

•	ChDir affects the operation of file-related commands like Open and Kill, which use the current working, or default, drive and directory unless you specify a full path name.


Example

The following example changes the current directory to the root, then changes it back to whatever it was originally.

Function OnLButtonDblClk()

Dim UserAns As Integer, Msg As String, NL As String, UsersPath As String

' Define newline

NL = Chr$(10)

' Save the current path

UsersPath = CurDir

' Reset to a new path

ChDir "\"

Msg = "The current directory has been changed to "

Msg = Msg & CurDir & NL & NL

Msg = Msg & "Press OK to change back "

Msg = Msg & "to the previous current directory."

' Get user response

UserAns = MsgBox(Msg)

' Change back to user default directory

ChDir UsersPath

Msg = "The current directory has been reset to " & UsersPath & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

CurDir, CurDir$ functions

ChDrive statement

MkDir statement

RmDir statement


ChDrive statement

Example   See also

Changes the current default drive.

Syntax

ChDrive <drive letter>

<drive letter>

String expression, consisting of a single letter that specifies the drive that is to become the default drive (Windows only).

Rule:

•	<drive letter> must correspond to the letter of a valid drive.

•	<drive letter> must be in the range A to <lastdrive>, where <lastdrive> is the maximum drive letter in your computer.

Examples:

The following statement changes the current working (default) drive to A.

ChDrive "A"

Together, the following two statements change the current drive to C.

DriveSpec$ = "C"

ChDrive DriveSpec$

Tips

•	To ensure that you have set the correct working directory before you issue commands that do not specify full path names, use ChDir.

•	To change the current directory, use ChDir.

•	To determine the current drive and directory, use CurDir.

•	ChDir and ChDrive affect the operation of file-related commands like Open and Kill, which use the current working, or default, drive and directory unless you specify a full path name.

•	ChDrive is ignored when the Basic program is running on UNIX.


Example

The following example changes the default directory to whichever drive the user specifies. If it cannot change the directory, it responds with an error message.

Function OnLButtonDblClk()

On Error Resume Next

Dim CurrPath As String, Drive As String

Dim HasColon As Integer, Msg As String

Dim NewDrive As String, NL As String

' Define new line

NL = Chr$(10)

' Get current path

CurrPath = CurDir

' If current drive

If Err = 68 Then

' is invalid

Drive = "Invalid"

' Reset error to 0

Err = 0

Else

' Get drive letter

Drive = Left(CurrPath, 2)

End If

Msg = "Your current drive is "& Drive & ". "

Msg = Msg & "Please type the letter of another drive "

Msg = "to make it the current drive."

' Prompt for new drive

NewDrive= InputBox(Msg)

' Check for colon

HasColon = InStr(1, NewDrive, ":")

' If there is no colon, append one

If Not HasColon Then

NewDrive = Left$(NewDrive, 1) & ":"

End If

' Change drive

ChDrive NewDrive

Select Case Err

' Device unavailable error

Case 44

Msg = "Sorry, that drive is not available. "

Msg = Msg & "No drive change was made."

' Disk not ready error

Case 71

Msg = "Please close the door on your drive and try again"

' Illegal function call

Case 10

Msg = "Sorry, you probably did not type a drive letter. "

Msg = Msg & "No drive change was made."

Case Else

Msg = "Drive changed to " & UCase$(NewDrive)

End Select

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

CurDir, CurDir$ functions

ChDir statement

MkDir statement

RmDir statement


Chr, Chr$ functions

Example   See also

Returns the character that corresponds to the given character code.

Syntax

Chr(<character code>)

Chr$(<character code>)

<character code>

A numeric expression that represents the character code you want Chr[$] to translate to a character.

Rules:

•	If <character code> is not an Integer, Chr[$] rounds it to the nearest Integer before returning the character. In the United States, <character code> usually refers to ANSI codes.

•	<character code> must be between 1 and 255.

Example:

The following statements are equivalent. Each returns "Z".

Chr$(90)

Chr$(Sqr(4) * 45)

Chr$(90.11)

The following statement prints or displays the copyright symbol (©).

Chr$(169)

Return value

Chr: Variant

Chr$: String

•	Chr$ returns nonprintable as well as printable characters.

•	Character codes from 0 to 31, inclusive, are the same as the standard, nonprintable ASCII codes.

•	Character codes 8, 9, 10, and 13 convert, respectively, to backspace, tab, linefeed, and carriage return characters. You cannot see them graphically. Depending on the application, they can affect the visual display of text.

Tips

•	To force a message either to start or to continue to print on a new line, use Chr$(10), which inserts the linefeed character.

•	To insert double quotes ("). inside a message, use Chr$(34).

•	To send special control codes to your printer or to some other device, use Chr$ with a print statement directed to that device.

•	To translate from a character to its character code number, use Asc.


Example

The following example returns the character corresponding to the number the user types. It also shows the use of the nonprintable newline character represented by Chr$(10). The example displays the user-selected character, if it can be displayed at all, on a new line by itself.

Function OnLButtonDblClk()

Dim AnsiNum As Integer, NL As String, Msg As String

' Define newline

NL = Chr$(10)

AnsiNum = InputBox("Please type a number between 0 and 255.")

Msg = "The character that corresponds to " & AnsiNum & " is this:"

' Insert newline

Msg = Msg & NL

' Show character by itself

Msg = Msg & Chr$(AnsiNum)

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Asc function


CInt function

Example   See also

Converts a numeric expression to the Integer data type.

Syntax

CInt(<numeric expression>)

<numeric expression>

Numeric expression that converts to the Integer data type from the Currency, Date, Double, Long, Single, String, or Variant data type.

Rules for (<numeric expression>):

•	If <numeric expression> is Null, CInt returns a Null.

•	If String or Variant, <numeric expression> must be interpretable as a number.

Examples for (<numeric expression>):

Each of the following statements returns the value 123. In the second statement, the string "123" enclosed in double quotes is considered a numeric expression because it can be interpreted as a number.

CInt(123)

CInt("123")

The following statement generates an error. The string "123four" is not considered a numeric expression because 'four' cannot be interpreted as a number.

CInt("123four")

The following statement first converts the string "123four" using Val to convert the number 123. Val ignores the string component ("four").

CInt(Val("123four"))

Return value

Integer

•	One of eight Actuate Basic data type conversion functions.

•	CInt rounds the fractional part of <numeric expression>, while Fix and Int truncate it.

•	If the fractional part of <numeric expression> is exactly 0.5, CInt rounds to the nearest even number.

CInt(1.5) = 2

CInt(2.5) = 2

CInt(0.5) = 0

•	If <numeric expression> lies outside the acceptable range for an Integer, an overflow error occurs.

Tips

•	To convert an expression to an Integer without using CInt, assign the expression to a variable that is the Integer data type.

•	To declare the data type of a variable, use Dim with the As clause.

•	To declare the data type of a variable dynamically--without using Dim or one of these conversion functions--append the data type declaration character to the variable's name. For example, if you want a variable called "Income" to contain only Currency data, refer to it as "Income@". If you want it to contain only Integer data, call it "Income%".

•	To round a number to precisely the number of decimal places you want and discard anything residual, use Format$.

•	To be sure you pass the correct data type to a sub procedure or to a Windows Dynamic Link Library (DLL), use data type conversion functions.


Example

The following example prompts you for a number, converts it using each of the conversion functions in turn, and displays the result.

Function OnLButtonDblClk()

Dim Orig As String, Msg As String, NL As String

NL = Chr$(10)

Orig = InputBox$("Please enter a number.")

Msg = "Your number is: " & Orig & NL & NL

Msg = Msg & "CCur(Orig) yields ----> " & CCur(Orig) & NL

Msg = Msg & "CDate(Orig) yields ----> " & CDate(Orig)  & NL

Msg = Msg & "CDbl(Orig) yields ----> " & CDbl(Orig) & NL

Msg = Msg & "CInt(Orig) yields ----> "  & CInt(Orig) & NL

Msg = Msg & "CLng(Orig) yields ----> " & CLng(Orig) & NL

Msg = Msg & "CSng(Orig) yields ----> " & CSng(Orig) & NL

Msg = Msg & "CStr(Orig) yields ----> "  & CStr(Orig) & NL

Msg = Msg & "CVar(Orig) yields ----> "  & CVar(Orig) & NL

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

CCur function

CDate function

CDbl function

CLng function

CSng function

CStr function

CVar function

CVDate function

Fix function

Format, Format$ functions

Int function

Dim statement


Class statement

See also

Declares and defines a class in Actuate Basic.

Syntax

Class <name of class> [Subclass Of <name of superclass>]...[,<name of superclass>...]]

<variable(s)>

<nested class(es)>

<method(s)>

End Class

<name of class>

The name you assign to the class.

Rule: You must supply a class name.

<Subclass Of <name of superclass>>

Specifies a superclass from which this class can be derived.

<variable(s)>

Variable belonging to the class. A class can contain any number of variables using one of the following declarations styles.

Dim <variable> [([<subscripts>])] [As <data type>]

Defines an instance variable. Each instance of your class has a copy of each instance variable.

Static <variable> [([<subscripts>])] [As <data type>]

Defines a static variable. All instances of this class and all instances of derived classes share a single copy of the variable.

<variable>

Name of the variable to declare.

As <data type>

Clause that declares the data type of <variable>.

Rule: <data type> can specify any valid Actuate Basic data type, user-defined data type, or class name.

Dim SalesTax Customer As String, Amount As Currency

<nested class(es)>

Any number of other class definitions. Actuate automatically creates nested classes for controls within frames, and for sections and frames within the report object.

<method(s)>

Procedure that performs actions on the objects of the class. Your class can contain any number of methods. Each method is defined using the Sub or Function statements.

Tip

Class statements can be recursive; they can call themselves repeatedly to perform a task.


See also

Dim statement

Function...End Function statement

Static statement

Sub...End Sub statement


ClearClipboard function

Example   See also

Clears the contents of the operating environment Clipboard.

Syntax

ClearClipboard( )

Return

Integer

•	Returns 1 (True) if the Clipboard was successfully cleared.

•	Returns 0 (False) if the Clipboard could not be cleared.


Example

The following example places the current date on the Clipboard and then displays the contents of the Clipboard.

Function OnLButtonDblClk ( )

Dim Msg As String, UserContent, DoMore

On Error Resume Next

Msg = "The Clipboard currently contains:  " & GetClipboardText()

MsgBox Msg

Msg = "Choose OK to load today's date onto the Clipboard."

MsgBox Msg

ClearClipboard()

SetClipboardText(Format$(Date, "dddd, mm/dd/yyyy"))

Msg = "Today's date is on the Clipboard.  Choose OK to get the "

Msg = Msg & "date back from the Clipboard and put it in a message."

MsgBox Msg

Msg = GetClipboardText()

MsgBox "The Clipboard currently contains:  " & Msg

DoMore = MsgBox("Put something else on the clipboard?", MB_YESNO)

If DoMore = IDNO Then

MsgBox "The date is still on the Clipboard."

Else

UserContent = InputBox("Put what?")

SetClipboardText(UserContent)

End If

MsgBox "The Clipboard currently contains:  " & GetClipboardText()

End Function

For information about using the code examples, see Using the code examples.


See also

GetClipboardText function

SetClipboardText function


CLng function

Example   See also

Converts a numeric expression to the Long data type.

Syntax

CLng(<numeric expression>)

<numeric expression>

Numeric expression to convert to the Long (Long integer) data type from the Currency, Date, Double, Integer, Single, String, or Variant data type.

Rules for (<numeric expression>):

•	If <numeric expression> is Null, CLng returns a Null.

•	If String or Variant, <numeric expression> must be interpretable as a number.

Examples for (<numeric expression>):

Each of the following statements returns the value 123. In the second statement, the string "123" enclosed in double quotes is considered a numeric expression because it can be interpreted as a number.

CLng(123)

CLng("123")

The following statement generates an error. The string "123four" is not considered a numeric expression because 'four' cannot be interpreted as a number.

CLng("123four")

The following statement first converts the string "123four" using Val to convert the number 123. Val ignores the string component ("four").

CLng(Val("123four"))

Return value

Long

•	One of eight Actuate Basic data type conversion functions.

•	If <numeric expression> lies outside the acceptable range for a Long data type, an overflow error occurs.

Tips

•	To convert an expression to long without using CLng, assign the expression to a variable that is the Long data type.

•	To declare the data type of a variable, use Dim with the As clause.

•	To declare the data type of a variable dynamically--without using Dim or one of these conversion functions -- append the data type declaration character to the variable's name. For example, if you want a variable called "Income" to contain only currency data, refer to it as "Income@". If you want it to contain only Long data, refer to it as "Income&".

•	To round a number to precisely the number of decimal places you want and discard anything residual, use Format$.

•	To be sure you pass the correct data type to a sub procedure or to a Windows Dynamic Link Library (DLL), use data type conversion functions.


Example

The following example prompts you for a number, converts it using each of the conversion functions in turn, and displays the result.

Function OnLButtonDblClk()

Dim Orig As String, Msg As String, NL As String

NL = Chr$(10)

Orig = InputBox$("Please enter a number.")

Msg = "Your number is: " & Orig & NL & NL

Msg = Msg & "CCur(Orig) yields ----> " & CCur(Orig) & NL

Msg = Msg & "CDate(Orig) yields ----> " & CDate(Orig)  & NL

Msg = Msg & "CDbl(Orig) yields ----> " & CDbl(Orig) & NL

Msg = Msg & "CInt(Orig) yields ----> "  & CInt(Orig) & NL

Msg = Msg & "CLng(Orig) yields ----> " & CLng(Orig) & NL

Msg = Msg & "CSng(Orig) yields ----> " & CSng(Orig) & NL

Msg = Msg & "CStr(Orig) yields ----> "  & CStr(Orig) & NL

Msg = Msg & "CVar(Orig) yields ----> "  & CVar(Orig) & NL

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

CCur function

CDate function

CDbl function

CInt function

CSng function

CStr function

CVar function

CVDate function

Format, Format$ functions

Dim statement


Close statement

Example   See also

Concludes input/output to a file.

Syntax

Close [ [#] <open file number> ] ... [, [#] <open file number> ] . . .

<open file number>

Numeric expression for the number you used in a previously issued Open statement that opened the target file to be closed.

Default: All open files are closed.

Examples:

The following statement closes the file previously "Open"ed as #1:

Close #1

The following statement closes the files opened as 1, 5, and 7:

Close 1, 5, 7

The following statement closes all open files:

Close

Description

•	If you use Close for a file that was opened for Output or Append, Actuate Basic flushes the buffers associated with the file and writes any remaining data in them to disk.

•	The association of a file with <open file number> ends when Close is executed. You can then reopen the file using the same or a different file number, or you can reuse the file number to open a different file.

•	Once a file has been closed, the file number cannot be referenced by any other file-related statements (such as Get or Put) until you issue another Open with that file number.

•	If <open file number> does not refer to a currently open file, Actuate Basic ignores the Close statement and continues with the next command.

•	Close with no arguments closes all open files.

•	Actuate Basic automatically closes all open files at program termination, whether or not you use Close.

Tip

You should close each open file before ending your program.


Example

The following example generates three test files on disk by opening the test files, writing to the test files, and closing the test files. In this example OnLButtonDblClk( ) is overridden to generate the three test files and prompt the user to delete the test files. The procedure Make3Files( ) should be typed after the End Function of the OnLButtonDblClk( ) procedure or saved in an Actuate Basic source code (.BAS) file.

Function OnLButtonDblClk()

Dim Msg As String

' Create test files

Make3Files

Msg = "Three test files have been created on your disk. "

Msg = Msg & "Choose OK to delete them."

MsgBox Msg

' Remove files from disk.

Kill "TESTFIL?"

End Function

'

' The following procedure creates the sample data files.

Sub Make3Files()

Dim I As Integer, FreeNum As Integer, TestFileName As String

MsgBox "We are now in the Make3Files sub."

For I = 1 to 3

' Get next free file handle

FreeNum = FreeFile

TestFileName = "TESTFIL" & FreeNum

' Opening the file automatically creates it

Open TestFileName For Output As FreeNum

' Print one line of text in the file

Print # FreeNum, "This is a test file."

Next I

' Close all files

Close

End Sub

For information about using the code examples, see Using the code examples.


See also

Open statement

Reset statement

Stop statement


Command, Command$ functions

Example

Returns the argument component of the command line of DESIGNER.EXE or VIEWER.EXE.

Syntax

Command

Command$

In the following example, "commandargs" represents what Command returns if you launched Actuate Basic with the following command.

DESIGNER.EXE /CMD commandargs

VIEWER.EXE /CMD commandargs

The function returns "commandargs Secondcomm 32" (the launch argument)--assuming you launched the application with the following command.

Viewer commandargs Secondcomm 32

Returns

Command: Variant

Command$: String

Actuate Basic Compiler does not generate an .EXE file. Instead, it generates a .ROX file which runs in the ROX compiler (the Factory) built in the Developer Workbench and the End User Desktop, or through a Report Server.


Example

The following example displays the command-line arguments of Viewer or Designer you are currently using.

Function OnLButtonDblClk()

Dim Msg As String

If Command = "" Then

Msg = "Sorry, no command-line arguments were "

Msg = Msg & "used to launch this program."

Else

Msg = "The command-line string you passed to this "

Msg = Msg & "program when you launched it is "

Msg = Msg & Command

End If

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


Const statement

Example   See also

Declares symbolic constants to be used in place of literal values.

Syntax

Global Const <const name> = <exprs> [, <const name> = <exprs>]...

[Global]

Keyword indicating that the <const name>s can be accessed by all procedures in the program.

<const name>

Name of the constant to which the value of <exprs> is assigned.

Rule:

Must follow standard variable naming conventions.

<exprs>

Expression assigned to <const name>. Can consist of literals, other constants, or any arithmetic or logical operators.

Rules:

•	Cannot contain or use any of the following:

•	Variables

•	User-defined functions

•	Intrinsic Actuate Basic functions such as Chr[$]

Description

•	Unlike a variable, a constant cannot be changed while your program is running.

•	You can use a constant anywhere you might use an expression.

•	The data type of <const name> is based on <exprs> if there is no type declaration postfix specified. A string <exprs> always yields a String <const name>, but a numeric <exprs> yields the simplest data type that can represent it once it has been evaluated.

•	A constant declared in a sub or function procedure is local to that procedure.

Rules

•	Const must be in a Declare section.

•	Any <const name> you use must be defined by Const before you can refer to it.

•	A constant cannot be a Variant, and its data type cannot change.

Tips

•	To simplify maintenance and debugging, put Global Const definitions in a single module.

•	To make constants easier to recognize when debugging, use all uppercase letters for your constant names.

•	To declare the data type of a constant, use a type declaration postfix like %, &, !, #, @, or $.


Example

The following example defines the constant PI, prompts the user for a radius, then uses PI to computer the circumference and area of a circle. To use this example, paste this portion at or near the beginning of your Actuate Basic source code (.BAS) file.

Declare

' Define constant

Global Const PI = 3.141592654

End Declare

Then, enter this function into the Method Editor.

Function OnLButtonDblClk()

Dim Area, Circum, Msg, Radius

Msg = "Please type the radius of a circle in centimeters."

Radius = InputBox(Msg)

' Compute circumference

Circum = 2 * PI * Radius

' Compute area

Area = PI * (Radius ^ 2)

Msg = "The circumference of the circle is "

Msg = Msg & Circum & " cm. Its area is "

Msg = Msg & Area & " cm."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Dim statement

Global statement

Let statement

Static statement


ConvertBFileToString function

See also

Encodes a binary image file into a string.

Syntax

ConvertBFileToString(<filename>)

<filename>

String expression that specifies the binary file to convert. Can include optional drive and path information.

Default path: Current default drive and directory.

Rules for <filename>:

•	Cannot include wildcard characters.

•	Must refer to an existing file.

Example for <filename>:

ConvertBFileToString("image1.bmp")

ConvertBFileToString(ROIimage1)

Return value

String

Description

Use ConvertStringToBFile to conditionally embed different images in your report instances--based upon different data or runtime parameters.

Use ConvertStringToBFile, and the complementary function ConvertBFileToString, to send the same report design to two different customers, A and B, and include image A in the report to A, and image B in the report to B. Instead of embedding either image in a given report, or creating two slightly different reports, you write conditional code in a single report. The instances of your report will display different images at runtime as required.

Rule

ConvertBFileToString should be used only in conjunction with its complementary function, ConvertStringToBFile.


See also

ConvertStringToBFile function

Roiimage example in the Developer Workbench Examples\Roiimage directory


ConvertStringToBFile function

See also

Decodes a string from Actuate's internal representation back into a binary file.

Syntax

ConvertStringToBFile(<stringval>)

<stringval>

String expression that specifies the string to convert into a binary file, usually an image file.

Return value

String

Description

Use ConvertStringToBFile to conditionally embed different images in your report instances--based upon different data or runtime parameters.

Use ConvertStringToBFile, and the complementary function ConvertBFileToString, to send the same report design to two different customers, A and B, and include image A in the report to A, and image B in the report to B. Instead of embedding either image in a given report, or creating two slightly different reports, you write conditional code in a single report. The instances of your report will display different images at runtime as required.

Rules

•	ConvertStringToBFile should be used only in conjunction with its complementary function, ConvertBFileToString.

•	The parameter you pass in (<stringval>) must be the return from the complimentary function ConvertBFileToString.

•	The returned file name is the name of the temporary file. This temporary file needs to be removed after it is no longer needed.

Tip

ConvertStringToBFile will create a temporary file. Be sure to include code that will clean up the temporary file after it is no longer needed.


See also

ConvertBFileToString function

Roiimage example in the Developer Workbench examples\roiimage directory


ConvertToHtml function

Example

Converts a string to its HTML equivalent, ensuring that the string will appear in the browser literally as given.

Syntax

ConvertToHtml(<ShowUserThis>)

<ShowUserThis>

String you want the browser to display exactly as shown.

In HTML, certain characters are interpreted as instructions to the browser rather than as characters to be displayed. ConvertToHtml ensures that the characters in <ShowUserThis> will not be interpreted as instructions, but instead will display in the browser exactly as you typed them.

Example:

Suppose you want the browser to display the following to the user:

Look --- >> Picks & Pans

Then use ConvertToHtml as follows:

ConvertToHtml("Look --- >> Picks & Pans")

The function will return the following HTML source code:

Look --- &gt;&gt; Picks &amp; Pans

Return values

String

If the character to display in the browser is:	ConvertToHtml returns:
<	&lt;
>	&gt;
&	&amp;
(any ASCII nnn > 128)	&#nnn;
All other characters remain the same.


Example

The following statement is true:

ConvertToHtml("<first name> & <last name>") = "&lt;first name&gt; &amp; &lt;last name&gt;"

For information about using the code examples, see Using the code examples.


CopyInstance statement

See also

Copies the values of the variables from one instance to another instance, even when the classes of the two instances are unrelated.

Syntax

CopyInstance(<source>, <destination>)

<source>

Any instance (object). The instance that contains the variables from which you want to copy values.

<destination>

Any instance (object). The instance that contains the variables to which you want to copy the values from <source>.

The classes of the two instances do not need to be related.

CopyInstance matches variables on name and data type.

For example, in the case of a variable in <source> named "Amount" with type Currency, CopyInstance will copy the variable's value from <source> to <destination> only if <destination> has a variable with the same name and type.

CopyInstance ignores or skips variables that do not match on both name and data type.

Rule

Both the names and data types of the variables in <source> must match the names and data types of the corresponding variables in <destination>.

Tip

CopyInstance is useful when you work with multi-input filters. CopyInstance simplifies writing complex data streams, for example, when creating a union.


See also

SetBinding function


Cos function

Example   See also

Returns the cosine of an angle.

Syntax

Cos(<angle>)

<angle>

Number, numeric expression, or Variant of VarType 8 (String) that specifies in radians the ratio for which you want to find the cosine.

Return value

Double

Rule: If <angle> evaluates to Null, Cos returns a Null.

Tip

To convert between radians and degrees, use: radians = degrees * Pi/180.


Example

In the following example the user is prompted to enter an angle expressed in radians. The code then returns the cosine of the angle.

Function OnLButtonDblClk ( )

Dim UserAns

UserAns = InputBox("Type a number representing an angle in radians.")

MsgBox "The cosine of " & UserAns & " is: " & Cos(UserAns)

End Function

For information about using the code examples, see Using the code examples.


See also

Atn function

Sin function

Tan function


CreateObject function

Creates an OLE Automation object.

Syntax

CreateObject ("<application name>.<object type>")

<application name>.<object type>

String expression that specifies the name of the application providing the object as established in the registry.

Returns

An instance of an OLE object.

Every application that supports OLE Automation provides at least one type of object. For example, a word-processing application might provide an application object, a document object, and a toolbar object.

Example:

In the following example, the variable MyObject is dimensioned as a type Object on the first line. On the second line, CreateObject is used to create the OLE Automation object that is assigned to MyObject.

Dim MyObject As Object

Set MyObject = CreateObject("WordProc.Document")

When you run this code, if the application that created the object (WordProc.EXE in this example) is not already running, Actuate Basic launches it and creates an object of the specified type.

Unlike what happens with a linked or embedded object using the OLE control, Actuate Basic does not display the object's image anywhere, nor does it maintain its data.

Once you create an OLE object, reference it in Actuate Basic code using the object variable to which you assigned it. In the following example, the properties and methods of the new object are accessed using the object variable MyObject.

MyObject.Bold

MyObject.Insert "Hello, world."

MyObject.Print

MyObject.SaveAs "C:\WORDPROC\DOCS\TEST.DOC"

Tip

To get a list of OLE Automation objects supported by an application, consult that application's documentation.


CSng function

Example   See also

Converts a numeric expression to the Single data type.

Syntax

CSng(<numeric expression>)

<numeric expression>

Numeric expression to convert to the Single (or single precision floating-point) data type from the Currency, Date, Double, Integer, Long, String, or Variant data type.

Rules:

•	If <numeric expression> is Null, CSng returns a Null.

•	If <numeric expression> is a String or Variant, <numeric expression> must be interpretable as a number.

Examples:

Each of the following statements returns the value 123. In the second statement, the string "123" enclosed in double quotes is considered a numeric expression because it can be interpreted as a number.

CSng(123)

CSng("123")

The following statement generates an error. The string "123four" is not considered a numeric expression because 'four' cannot be interpreted as a number.

CSng("123four")

The following statement first converts the string"123four" using Val to convert the number 123. Val ignores the string component ("four").

CSng(Val("123four"))

Return value

Single

•	One of eight Actuate Basic data type conversion functions.

•	If <numeric expression> lies outside the acceptable range for a Single data type, an overflow error occurs.

Tips

•	To convert an expression to single without using CSng, assign the expression to a variable that is the Single data type.

•	To declare the data type of a variable, use Dim with the As clause.

•	To declare the data type of a variable dynamically--without using Dim or one of these conversion functions--append the data type declaration character to the variable's name. For example, if you want a variable called "Income" to contain only Currency data, refer to it as "Income@". If you want it to contain only Single data, refer to it as "Income!".

•	To round a number to precisely the number of decimal places you want and discard anything residual, use Format[$].

•	To be sure you pass the correct data type to a sub procedure or to a Windows Dynamic Link Library (DLL), use data type conversion functions.


Example

The following example prompts you for a number, converts it using each of the conversion functions in turn, and displays the result.

Function OnLButtonDblClk()

Dim Orig As String, Msg As String, NL As String

NL = Chr$(10)

Orig = InputBox$("Please enter a number.")

Msg = "Your number is: " & Orig & NL & NL

Msg = Msg & "CCur(Orig) yields ----> " & CCur(Orig) & NL

Msg = Msg & "CDate(Orig) yields ----> " & CDate(Orig)  & NL

Msg = Msg & "CDbl(Orig) yields ----> " & CDbl(Orig) & NL

Msg = Msg & "CInt(Orig) yields ----> "  & CInt(Orig) & NL

Msg = Msg & "CLng(Orig) yields ----> " & CLng(Orig) & NL

Msg = Msg & "CSng(Orig) yields ----> " & CSng(Orig) & NL

Msg = Msg & "CStr(Orig) yields ----> "  & CStr(Orig) & NL

Msg = Msg & "CVar(Orig) yields ----> "  & CVar(Orig) & NL

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

CCur function

CDate function

CDbl function

CInt function

CLng function

CStr function

CVar function

CVDate function

Format, Format$ functions

Dim statement


CStr function

Example   See also

Converts an expression to the String data type.

Syntax

CStr(<valid expression>)

<valid expression>

Expression to convert to the String data type from the Currency, Date, Double, Integer, Long, Single, or Variant data type.

Rule: If <valid expression> is Null, CStr returns a Null.

Examples:

The following statement returns the string value "123four".

CStr(123) & "four"

The following statement generates an error, because it mixes string and numeric data types.

CStr(123) + 5

Return value

String

Rule: One of eight Actuate Basic data type conversion functions.

Tips

•	To declare the data type of a variable, use Dim with the As clause.

•	To declare the data type of a variable dynamically--without using Dim or one of these conversion functions--append the data type declaration character to the variable's name. For example, if you want a variable called "MyVar" to contain only Currency data, refer to it as "MyVar@". If you want it to contain only String type data, refer to it as "MyVar$".

•	To be sure you pass the correct data type to a sub procedure or to a Windows Dynamic Link Library (DLL), use data type conversion functions.


Example

The following example prompts you for a number, converts it using each of the conversion functions in turn, and displays the result.

Function OnLButtonDblClk()

Dim Orig As String, Msg As String, NL As String

NL = Chr$(10)

Orig = InputBox$("Please enter a number.")

Msg = "Your number is: " & Orig & NL & NL

Msg = Msg & "CCur(Orig) yields ----> " & CCur(Orig) & NL

Msg = Msg & "CDate(Orig) yields ----> " & CDate(Orig)  & NL

Msg = Msg & "CDbl(Orig) yields ----> " & CDbl(Orig) & NL

Msg = Msg & "CInt(Orig) yields ----> "  & CInt(Orig) & NL

Msg = Msg & "CLng(Orig) yields ----> " & CLng(Orig) & NL

Msg = Msg & "CSng(Orig) yields ----> " & CSng(Orig) & NL

Msg = Msg & "CStr(Orig) yields ----> "  & CStr(Orig) & NL

Msg = Msg & "CVar(Orig) yields ----> "  & CVar(Orig) & NL

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

CCur function

CDbl function

CInt function

CLng function

CSng function

CVar function

CVDate function

Format, Format$ functions

Dim statement


CurDir, CurDir$ functions

Example   See also

Returns the current default directory for the specified drive, or for the current drive.

Syntax

CurDir[(<drive:>)]

CurDir$[(<drive:>)]

<drive:>

String expression, consisting of a single character followed by a colon that specifies the drive for which you want to determine the current directory.

Default: The current drive.

Rules:

•	First character of <drive:> must correspond to the letter of a valid DOS drive.

•	First character of <drive:> must be in the range A to <lastdrive>, where <lastdrive> is the maximum drive letter you set in your CONFIG.SYS file.

Example:

The following statement assigns to the variable DefaultVar a string containing the current directory path on the default drive.

DefaultVar = CurDir

The following statement assigns to the variable B$ a string containing the current directory path on drive A.

B$ = CurDir("A")

The following statement assigns to the variable PlaceMark a string containing the current directory path on drive C.

PlaceMark = CurDir$("C:")

Return value

CurDir: Variant

CurDir$: String

While DOS, Windows 95, or Windows NT always maintains a distinct current directory for each drive in the system, UNIX only keeps only the current directory under the current drive. The current directory is the one the system searches first for a file name whenever you start such a search without specifying a path name.

Tips

•	Since the path CurDir[$] returns includes the drive letter, it also determines which drive is currently the current drive.

•	To be sure you have set the correct working directory before you issue commands that do not specify full path names, use CurDir[$], ChDrive, and ChDir.

•	<drive> is ignored when the Basic program is running on a UNIX server.


Example

The following example displays a message box indicating the current directory on the current drive.

Function OnLButtonDblClk()

Dim Msg As String, NL As String

' Define newline

NL = Chr$(10)

Msg = "The current directory is: "

' Get current directory

Msg = Msg & NL & CurDir

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

ChDir statement

ChDrive statement

MkDir statement

RmDir statement


CVar function

Example   See also

Converts a numeric expression to the Variant data type.

Syntax

CVar(<valid expression>)

<valid expression>

Expression to convert to the Variant data type from the Currency, Date, Double, Integer, Long, Single, or String data type.

Rule: If <valid expression> is Null, CVar returns a Null.

Examples:

The following statements return True (nonzero).

CVar(123) & "four" = "123four"

CVar(123) + 5 = 128

CVar(123) + 5 & "append" = "128append"

Return value

Variant

•	One of eight data type conversion functions.

•	If <any valid expression> lies outside the acceptable range for a Variant data type, an overflow error occurs.

Tips

•	To convert an expression to variant without explicitly using CVar, assign the expression to a variable that is the Variant data type.

•	To declare the data type of a variable, use Dim with the As clause.

•	To be sure you pass the correct data type to a sub procedure or to a Windows Dynamic Link Library (DLL), use data type conversion functions.


Example

The following example prompts you for a number, converts it using each of the conversion functions in turn, and displays the result.

Function OnLButtonDblClk()

Dim Orig As String, Msg As String, NL As String

NL = Chr$(10)

Orig = InputBox$("Please enter a number.")

Msg = "Your number is: " & Orig & NL & NL

Msg = Msg & "CCur(Orig) yields ----> " & CCur(Orig) & NL

Msg = Msg & "CDate(Orig) yields ----> " & CDate(Orig)  & NL

Msg = Msg & "CDbl(Orig) yields ----> " & CDbl(Orig) & NL

Msg = Msg & "CInt(Orig) yields ----> "  & CInt(Orig) & NL

Msg = Msg & "CLng(Orig) yields ----> " & CLng(Orig) & NL

Msg = Msg & "CSng(Orig) yields ----> " & CSng(Orig) & NL

Msg = Msg & "CStr(Orig) yields ----> "  & CStr(Orig) & NL

Msg = Msg & "CVar(Orig) yields ----> "  & CVar(Orig) & NL

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

CCur function

CDate function

CDbl function

CInt function

CLng function

CSng function

CStr function

CVDate function

Dim statement


CVDate function

Example   See also

Converts an expression to a Date.

Syntax

CVDate(<date expression>)

<date expression>

Date expression, or any numeric or string expression that can be interpreted as a date, as a time, or as both a date and a time.

•	Can be a string such as "November 12, 1982 8:30 PM", "12 Nov, 1982 08:30 PM", "11/12/82", "08:30PM", or any other string that can be interpreted as a date, time, or date/time in the valid range.

•	Can be a date serial number such as 30267.854 (which corresponds to November 12, 1982 at 8:30 PM), or any other number that can be mapped to a date, time, or date/time in the valid range.

•	For date serial numbers, the integer component represents the date itself while the decimal component represents the time of day on that date, where January 1, 1900 at precisely noon has the date serial number 2.5, and negative numbers represent dates prior to December 30, 1899 (0).

Default date if none specified: 0 (Dec 30, 1899)

Default time if none specified: 00:00:00 (midnight)

Rules:

•	If <date expression> includes a time of day, it must be a valid time, even if CVDate is not being used to return anything having to do with a time of day. A valid time is one that is in the range 0:00:00 (12:00:00 AM) through 23:59:59 (11:59:59 PM). Either the 12- or 24-hour clock can be used.

•	If <date expression> is a numeric expression, it must be in the range -657434 to +2958465, inclusive.

•	For abridged date expressions ending in 00 through 29 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 2000. For example, while Year(4/30/1910) returns 1910, the abridged expression Year(4/30/10) returns 2010 (10 + 2000).

•	For abridged date expressions ending in 30 through 99 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 1900. For example, while Year(11/12/2082) returns 2082, the abridged expression Year(11/12/82) returns 1982 (82 + 1900).

Note that there are arguably "abridged" dates like Nov 12, 1982 (versus November 12, 1982) that do specify the century. Note also that both abridged and unabridged dates are dates ending in 00 through 99.

Examples:

The following statements are equivalent. Each assigns 11/12/82 8:30:00 PM (with its underlying serial number) to the variable BDate.

BDate = CVDate("11/12/82 8:30 pm")

BDate = CVDate("12 Nov 1982 20:30")

BDate = CVDate("November 12, 1982 8:30PM")

BDate = CVDate(30267.854167)

Returns

Date

•	If <date expression> is Null, CVDate returns a Null.

•	If <date string> contains only numbers separated by valid date separators, CVDate recognizes the order for month, day, and year according to the Short Date setting in the International section of the Windows Control Panel.

Rules

•	<date expression> must not be empty or zero-length.

•	Do not use CVDate to convert a long date format that also contains a day-of-the-week string, like "Friday, Nov. 12, 1982"; the function does not recognize such strings as dates.

•	Avoid supplying CVDate with a date in a format other than the format specified by Windows in the Control Panel.

Tip

To determine if either a numeric or string expression that looks like a date can be converted to a date, use IsDate. However, IsDate cannot determine whether a string that looks like a number can be converted to a date, even if the number is in the correct range for date serial numbers.


Example

The following example prompts the user for a date, date and time, a time, or a date serial number. For any valid entry, it displays both a date and a date serial number.

Function OnLButtonDblClk()

Dim NL As String, DateMeme As String, ConvDateMeme As Date

Dim Msg As String

NL = Chr$(10)

Msg = "Please type a date, a date and time, "

Msg = Msg & "a time, or a date serial number."

DateMeme = InputBox(Msg)

ConvDateMeme = CVDate(DateMeme)

MsgBox "The date you gave me was: " & ConvDateMeme & NL

MsgBox "The serial number for that date is: " & CDbl(ConvDateMeme)

End Function

For information about using the code examples, see Using the code examples.


See also

CCur function

CDate function

CDbl function

CInt function

CLng function

CSng function

CStr function

CVar function

IsDate function


Date, Date$ functions

Example   See also

Returns the current system date.

Syntax

Date

Date$

Example:

The following statement assigns the current system date to a variable:

CurrDate = Date

Return value

Date: Variant

Date$: String

•	Date returns a Variant of VarType 7 (Date) that contains a date stored internally as a Double.

•	Date[$] returns a 10-character string in the form mm-dd-yyyy, where mm represents the current month (01-12), dd the day (01-31), and yyyy the year (1980-2099).

•	If the date is defined in this format in Windows, the return value of Date[$] is equivalent to the following statement:

Format$(Now, "mm-dd-yyyy")

•	The actual format of date and time is set using the Windows Control Panel.


Example

The following example looks at the system date and determines how many business days are left in the current week, not counting today.

Function OnLButtonDblClk()

' Dimension CurrentDay and BusDaysLeft as Variants so we can

' perform arithmetic operations on them

Dim CurrentDay, BusDaysLeft

Dim Verb As String, DayNoun As String, Msg As String

' Weekday returns an Integer

CurrentDay = Weekday(Date)

BusDaysLeft = 6 - CurrentDay

If BusDaysLeft < 0 or BusDaysLeft > 5 Then BusDaysLeft = 0

Select Case BusDaysLeft

Case Is = 1

Verb = "is "

DayNoun = "day "

Case Else

Verb = "are "

DayNoun = "days "

End Select

Msg = "Today is " & Format$(Date, "dddd") & "."

Msg = Msg & "There " & Verb & BusDaysLeft & " business " & DayNoun

Msg = Msg & "left in the current week, not counting today."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

CVDate function

Format, Format$ functions

Now function

Time, Time$ functions


DateAdd function

Example   See also

Returns a date to which a specified time interval has been added.

Syntax

DateAdd(<interval code>, <number of intervals>, <date expression>)

<interval code>

String expression that specifies the interval of time (quarter, month, second, and so on) to add.

Rule: You cannot use more than one <interval code> at a time.

The following table lists each valid time period and the <interval code> that corresponds to it.

Time period	<interval code>
Year	yyyy
Quarter	q
Month	m
Day of the Year	y
Day of the Month	d
Day of the Week	w
Week of the Year	ww
Hour	h
Minute	n
Second	s
<number of intervals>

Numeric expression that specifies the number of intervals to add. Use a positive number to get future dates and a negative number to get past dates.

<date expression>

String expression that specifies the date to add to, or a variant expression that contains a valid date.

Return value

Variant

•	If you subtract more years than are in <date expression>, an error occurs.

•	If <number of intervals> is not a Long value, DateAdd follows the rules for Fix function and rounds <number of intervals> to the nearest whole number.

•	The actual display format of date and time is set according the Windows Control Panel.

•	For abridged date expressions ending in 00 through 29 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 2000. For example, while Year(4/30/1910) returns 1910, the abridged expression Year(4/30/10) returns 2010 (10 + 2000).

•	For abridged date expressions ending in 30 through 99 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 1900. For example, while Year(11/12/2082) returns 2082, the abridged expression Year(11/12/82) returns 1982 (82 + 1900).

Note that there are arguably "abridged" dates like Nov 12, 1982 (versus November 12, 1982) that do specify the century. Note also that both abridged and unabridged dates are dates ending in 00 through 99.

Tips

•	Use DateAdd to add a specified time interval to a date. For example, you can use DateAdd to calculate a date 30 days from a transaction date to display a Send Late Payment Notice field.

•	To calculate the difference between two dates, use DateDiff.


Example

The following example adds 30 days to the value of a date entered by the user and displays the result.

Function OnLButtonDblClk ( )

Dim TransactionDate, Msg

TransactionDate = InputBox("Type a date in the pattern 1/1/82.")

Msg = DateAdd("d", 30, TransactionDate)

MsgBox Msg & " is 30 days after the date " & TransactionDate

End Function

For information about using the code examples, see Using the code examples.


See also

DateDiff function


DateDiff function

Example   See also

Calculates and returns the time difference between two specified dates.

Syntax

DateDiff(<interval >, <date to subtract>, <date to subtract from>)

<interval>

String expression that specifies the interval of time (quarter, month, second, and so on) to use in calculating the difference between two specified dates.

Rule for <interval>: You cannot use more than one <interval> at a time.

The following table lists valid values for <interval> and describes how DateDiff uses each in calculations.

Interval	Time period	Description
yyyy	Year	DateDiff uses the year portion in calculation.
q	Quarter	DateDiff uses the following quarters: 1/1 - 3/31, 4/1 - 6/30, 7/1- 9/30, and 10/1- 12/31. DateDiff calculates the difference by determining the quarter into which each date falls, then subtracting the quarters.
m	Month	DateDiff uses the month portion of dates in calculation.
y	Day of the Year	DateDiff counts number of days in the specified years.
d	Day of the Month	DateDiff counts number of days in the specified months.
w	Day of the Week	DateDiff counts number of Mondays.
ww	Week of the Year	DateDiff counts number of Sundays.
h	Hour	Hour
n	Minute	Minute
s	Second	Second
<date to subtract>

String expression that specifies the date to subtract, or the name of a variant expression containing the valid date.

<date to subtract from>

String expression that specifies the date to subtract from, or the name of a variant expression containing the valid date.

Rules:

•	For abridged date expressions ending in 00 through 29 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 2000. For example, while Year(4/30/1910) returns 1910, the abridged expression Year(4/30/10) returns 2010 (10 + 2000).

•	For abridged date expressions ending in 30 through 99 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 1900. For example, while Year(11/12/2082) returns 2082, the abridged expression Year(11/12/82) returns 1982 (82 + 1900).

Note that there are arguably "abridged" dates like Nov 12, 1982 (versus November 12, 1982) that do specify the century. Note also that both abridged and unabridged dates are dates ending in 00 through 99.

Return value

Variant

•	If <date to subtract> refers to a later point in time than <date to subtract from>, DateDiff returns a negative number.

•	If <interval> is "w" (weekday), DateDiff returns the number of weeks by counting the number of Mondays between the two dates. If <date to subtract from> falls on a Monday, DateDiff does not include that Monday in the calculation. In the following example, both specified dates fall on a Monday. The result DateDiff returns is 2.

DateDiff("w", "6/26/95", "7/10/95")

•	If <interval> is "ww" (week), DateDiff returns the number of weeks by counting the number of Sundays between the two dates. If <date to subtract from> falls on a Sunday, DateDiff does not include that Sunday in the calculation. In the following example, both specified dates fall on a Sunday. The result DateDiff returns is 2.

DateDiff("ww", "6/25/95", "7/9/95")

•	Because DateDiff uses the year portion of dates in calculation, DateDiff returns 1 in the following example, although the dates are one day apart.

DateDiff ("yyyy", "12/31/95", "1/1/96")

•	Because DateDiff uses the month portion of dates in calculation, DateDiff returns 1 in the following example, although the dates are one day apart.

DateDiff ("m", "12/31/95", "1/1/96")

•	Because DateDiff calculates the difference by checking which quarters the specified dates fall in, DateDiff returns 1 in the following example, although the dates are one day apart.

DateDiff ("q", "12/31/95", "1/1/96")

•	The actual display format of date and time is set using the Windows Control Panel.

Tips

•	Use DateDiff to calculate the difference between two dates to display in a calculated field. For example, you can use DateDiff to calculate the number of days between a pre-sales date and a transaction date to display in a Sales Response field.

•	If you are calculating the number of weeks between two dates, you can use either weekday ("w") or week ("ww") as the interval. Because each starts the calculations from a different day, the results can be different.

•	To add a specified time interval to a date, use DateAdd.


Example

The following example uses two valid date expressions called PreSalesDate and TransactionDate. DateDiff finds the difference, in days, between PreSalesDate and TransactionDate, and displays the result.

Function OnLButtonDblClk ( )

Dim PreSalesDate, TransactionDate, DDiff, Msg

PreSalesDate = InputBox("Type the pre-sales date in the pattern 1/1/82.")

TransactionDate = InputBox("Type the transaction date.")

DDiff = DateDiff("d", PreSalesDate, TransactionDate)

Msg = "The pre-sales date is "

Msg = Msg & DDiff & " days before the transaction date."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

DateAdd function


DatePart function

Example   See also

Returns a specified component of a given date.

Syntax

DatePart(<interval code>, <date exprs>)

<interval code>

String expression that specifies the interval of time (quarter, month, second, and so on) you want to determine.

Rule for <interval code>: You cannot use more than one <interval code> at a time.

The following table lists valid time periods for <interval code>.

Time period	<interval code>	Range of return value
Year	yyyy	100 - 9999
Quarter	q	1 - 4
Month	m	1 - 12
Day of the Year	y	1 - 366
Day of the Month	d	1 - 31
Day of the Week	w	1 - 7
Week of the Year	ww	1 - 53
Hour	h	0 - 23
Minute	n	0 - 59
Second	s	0 - 59
<date exprs>

Date expression, or any numeric or string expression that can be interpreted as a date, as a time, or as both a date and a time.

•	Can be a string expression such as "November 12, 1982 8:30 PM", "Nov 12, 1982 08:30 PM", "11/12/82 8:30pm", "20:30", or any other string that can be interpreted as a date, time, or date/time in the valid range.

•	Can be a date serial number such as 30267.854 (which corresponds to November 12, 1982 at 8:30 PM), or any other number that can be mapped to a date, time, or date/time in the valid range.

•	For date serial numbers, the integer component represents the date itself while the decimal component represents the time of day on that date, where January 1, 1900 at precisely noon has the date serial number 2.5, and negative numbers represent dates prior to December 30, 1899 (0).

Default time of day if none specified: 00:00:00 (Midnight)

Default date if none specified: December 30, 1899

Rules for <date exprs>:

•	Must be in the range January 1, 100 through December 31, 9999, inclusive.

•	If a numeric expression, it must be in the range -657434 to +2958465, inclusive.

•	If a variable containing a date serial number, the variable must have been explicitly declared as one of the numeric types.

•	If a time of day is included, it must be a valid time, even when you are not using DatePart to return anything having to do with time of day. A valid time is one that is in the range 00:00:00 (12:00:00 AM) through 23:59:59 (11:59:59 PM). Either the 12- or 24-hour clock format may be used.

•	The actual display format of date and time is set using the Windows Control Panel.

•	For abridged date expressions ending in 00 through 29 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 2000. For example, while Year(4/30/1910) returns 1910, the abridged expression Year(4/30/10) returns 2010 (10 + 2000).

•	For abridged date expressions ending in 30 through 99 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 1900. For example, while Year(11/12/2082) returns 2082, the abridged expression Year(11/12/82) returns 1982 (82 + 1900).

Note that there are arguably "abridged" dates like Nov 12, 1982 (versus November 12, 1982) that do specify the century. Note also that both abridged and unabridged dates are dates ending in 00 through 99.

Examples:

Each of the following statements will return 1 (True):

Print 11 = DatePart("m", "11/12/82 8:30:01 pm")

Print 12 = DatePart("d", "11/12/82 8:30:01 pm")

Print 316 = DatePart("y", "11/12/82 8:30:01 pm")

Return value

Integer

•	If <date expression> is Null, DatePart returns a Null.

•	If DatePart("w", <date exprs>) returns 1, the day of the week for <date exprs> is Sunday; if 2, Monday, and so on.

Tip

To return more than one interval at a time and to exercise more control over output, use Format instead of DatePart.


Example

The following example prompts the user for a date or date/time, then displays all ten values DatePart can return for it:

Function OnLButtonDblClk()

Dim UserDate As String, NL As String

Dim InputMsg As String, Msg As String

' Define newline

NL = Chr$(10)

' Set a string for msgbox

InputMsg = "Please type a date or date/time"

InputMsg = InputMsg & " like Nov 12, 1982 8:32pm."

' Get user input

UserDate = InputBox(InputMsg)

Msg = "The year is: " & DatePart("yyyy", UserDate) & NL

Msg = Msg & "The quarter is: " & DatePart("q", UserDate) & NL

Msg = Msg & "The month is: " & DatePart("m", UserDate) & NL

Msg = Msg & "The day of the year is: " & DatePart("y", UserDate) & NL

Msg = Msg & "The day of the month is: " & DatePart("d", UserDate) & NL

Msg = Msg & "The day of the week is: " & DatePart("w", UserDate) & NL

Msg = Msg & "The week of the year is: " & DatePart("ww", UserDate) & NL

Msg = Msg & "The hour is: " & DatePart("h", UserDate) & NL

Msg = Msg & "The minute is: " & DatePart("n", UserDate) & NL

Msg = Msg & "The second is: " & DatePart("s", UserDate) & NL

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

DateAdd function

DateDiff function

Day function

Fix function

Format, Format$ functions

Now function

Weekday function

Year function


DateSerial function

Example   See also

Returns a date variant based on the supplied year, month, day, hour, minute, and second.

Syntax

DateSerial(<year>, <month>, <day>)

DateSerial(<year>, <month>, <day>, <hour>, <minute>, <second>)

<year>

Numeric expression that specifies the year of a date. The values 0 through 99 represent the years 1900-1999.

Rules for <year>:

•	Must be in the range 100 through 9999, inclusive.

•	To represent a year outside the range 1900-1999, you must use all four of its digits.

<month>

Numeric expression that specifies the month of a date.

Rule for <month>: Must be in the range 1 through 12, inclusive.

<day>

Numeric expression that specifies the day of a date.

Rule for <day>: Must be in the range 1 through 31, inclusive.

<hour>

Numeric expression that specifies the hour of a day.

Rule for <hour>: Must be in the range 0-23, inclusive.

<minute>

Numeric expression that specifies the minute of a hour.

Rule for <minute>: Must be in the range 0-59, inclusive.

<second>

Numeric expression that specifies the second of a minute.

Rule for <second>: Must be in the range 0-59, inclusive.

Examples:

The following statements are equivalent. If the default Short Date format for the operating environment is mm/dd/yy, each stores "11/12/82" into the variable DateVar.

DateVar = DateSerial(82, 11, 12)

DateVar = DateSerial(1982, 11, 12)

Each of the following statements stores the underlying date serial number for November 12, 1982 (which is 30267) into the double-precision variable DateVar#.

DateVar# = CDbl(DateSerial(82, 11, 12))

DateVar# = DateSerial(82, 11, 12) * 1

Return value

Date

•	The value returned by DateSerial usually looks like a date but is stored internally as a double-precision number known as a date serial number, which is a number that represents a date and/or time from midnight January 1, 100 through December 31, 9999, inclusive.

•	The integer component of any date serial number represents the date (day, month, and year) itself while the decimal or fractional component represents the time of day on that date as a proportion of a whole day-- where January 1, 1900 at precisely noon has the date serial number 2.5, and where negative numbers represent dates prior to December 30, 1899.

•	The actual display format of date and time is set using the Windows Control Panel.

Tip

DateSerial can return a new date based on calculations done on a given date. In the following example, DateSerial returns a date that is thirty days before November 12, 1982--that is, 10/13/82--and assigns it to the variable DateNew.

DateNew = DateSerial(1982, 11, 12)-30


Example

The following example displays the day of the week for any date supplied by the user.

Function OnLButtonDblClk()

Dim Msg As String, UserDate As Double

Dim DateGiven As String, Verb As String

Dim ValidFlag As Integer

Dim DD As Integer, MM As Integer, YY As Integer

Dim DayOfWeek As String

Msg = "Please type a date in the format mm/dd/yyyy."

Do

' Assume the best

 	ValidFlag = True

' Get user input

DateGiven = InputBox(Msg)

If Len(DateGiven) <> 10 Then DateGiven = Format(Now, "mm/dd/yyyy")

' Extract month number

MM = Left(DateGiven, 2)

If MM <1 Or MM > 12 Then ValidFlag = False

' Extract day number

DD = Mid(DateGiven, 4, 2)

If DD <1 Or DD > 31 Then ValidFlag = False

' Extract year number

YY = Right(DateGiven, 4)

If YY < 1753 Or YY > 2078 Then ValidFlag = False

Loop While ValidFlag = False

' Determine date serial

UserDate = DateSerial(YY, MM, DD)

' Find correct verb

Select Case UserDate

' Now is the date serial for the current moment. We need only the

' integer component of it to compare with what the user entered to

' determine if date entered was before today, today, or in the future

Case Is < Int(Now): Verb = " was a "

Case Is > Int(Now): Verb = " will be a "

Case Else: Verb = " is a "

End Select

' Returns a day of week

DayOfWeek = Format(UserDate, "dddd")

Msg = DateGiven & Verb & DayOfWeek & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

DateValue function

Day function

Month function

Now function

TimeSerial function

TimeValue function

Weekday function

Year function


DateValue function

Example   See also

Returns a date variant that represents the date of the supplied string.

Syntax

DateValue(<date string>)

<date string>

String expression that specifies a date. Can be any string that can be interpreted as a date.

Rules:

•	Must be in the range January 1, 100 through December 31, 9999, inclusive.

•	If a time is appended to the date it must be a valid time, even though DateValue does not return a time.

•	For abridged date expressions ending in 00 through 29 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 2000. For example, while Year(4/30/1910) returns 1910, the abridged expression Year(4/30/10) returns 2010 (10 + 2000).

•	For abridged date expressions ending in 30 through 99 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 1900. For example, while Year(11/12/2082) returns 2082, the abridged expression Year(11/12/82) returns 1982 (82 + 1900).

Note that there are arguably "abridged" dates like Nov 12, 1982 (versus November 12, 1982) that do specify the century. Note also that both abridged and unabridged dates are dates ending in 00 through 99.

Examples:

The following statements are equivalent. If the default Short Date format for the operating environment is mm/dd/yy, each stores "11/12/82" into the variable DateVar.

DateVar = DateValue("November 12, 1982")

DateVar = DateValue("Nov 12, 1982")

DateVar = DateValue("Nov 7, 1982") + 5

DateVar = DateValue("11/12/82")

DateVar = DateValue("11-12-1982")

Each of the following statements stores the underlying date serial number for November 12, 1982 (which is 30267) into the double-precision variable DateVar#.

DateVar# = DateValue("Nov 12, 1982")

DateVar# = DateValue("Nov 12, 1982") * 1

Return value

Date

•	If <date string> contains only numbers separated by valid date separators, DateValue recognizes the order for month, day, and year according to the Short Date setting in the Windows Control Panel.

•	The value DateValue returns usually looks like a date but is stored internally as a double-precision number known as a date serial number--that is, a number that represents a date and/or time from midnight January 1, 100 through December 31, 9999, inclusive.

•	The integer component of any date serial number represents the date (day, month, and year) itself while the decimal or fractional component represents the time of day on that date as a proportion of a whole day, where January 1, 1900, at precisely noon has the date serial number 2.5, and negative numbers represent dates prior to December 30, 1899.

•	The actual format of date and time is set for the Windows environment through the Control Panel.


Example

The following example displays the day of the week for any date supplied by the user.

Function OnLButtonDblClk()

Dim Msg As String, UserDate As Double

Dim DateGiven As String, Verb As String

Dim ValidFlag As Integer

Dim DD As String, MM As String, YY As String

Dim DayOfWeek As String

Msg = "Please type a date in the format mm/dd/yyyy"

Do

' Assume the best

 	ValidFlag = True

' Get user input

DateGiven = InputBox(Msg)

If Len(DateGiven) <> 10 Then DateGiven = Format(Now, "mm/dd/yyyy")

' Extract month number

MM = Left(DateGiven, 2)

If MM < "01" Or MM > "12" Then ValidFlag = False

' Extract day number

DD = Mid(DateGiven, 4, 2)

If DD < "01" Or DD > "31" Then ValidFlag = False

' Extract year number

YY = Right(DateGiven, 4)

If YY < "1753" Or YY > "2078" Then ValidFlag = False

Loop While ValidFlag = False

' Determine date value

UserDate = DateValue(DateGiven)

' Find correct verb

Select Case UserDate

' Now is the date serial for the current moment. We need only the

' integer component of it to compare with what the user entered to

' determine if date entered was before today, today, or in the future

Case Is < Int(Now): Verb = " was a "

Case Is > Int(Now): Verb = " will be a "

Case Else: Verb = " is a "

End Select

' Returns a day of week

DayOfWeek = Format(UserDate, "dddd")

Msg = DateGiven & Verb & DayOfWeek & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

DateSerial function

Day function

Month function

Now function

TimeSerial function

TimeValue function

Weekday function

Year function


Day function

Example   See also

Returns an Integer between 1 and 31, inclusive, that represents the day of the month for a supplied date argument.

Syntax

Day(<date exprs>)

<date exprs>

Date expression, or any numeric or string expression that can evaluate to a date. Specifies a date and/or time.

•	Can be a string such as "November 12, 1982", "Nov 12, 1982", "11/12/82", or "11-12-82", or any other string that can be interpreted as a date in the valid range.

•	Can be a date serial number such as 30267.854 (which corresponds to November 12, 1982 at 8:30 PM), or any other number that can be mapped to a date in the valid range.

•	For date serial numbers, the integer component represents the date itself while the decimal component represents the time of day on that date, where January 1, 1900 at precisely noon has the date serial number 2.5, and negative numbers represent dates prior to December 30, 1899 (0).

Rules:

•	If a string expression, must specify a date in the range January 1, 100 through December 31, 9999, inclusive.

•	If a numeric expression, must be in the range -657434 to +2958465, inclusive.

•	If a variable contains a date serial number, the variable must be explicitly declared as one of the numeric types.

Examples:

The following statements are equivalent. Each assigns 7 to the variable UserDay.

UserDay = Day("6/7/64")

UserDay = Day("June 7, 1964 2:35 PM")

UserDay = Day("Jun 7, 1964")

UserDay = Day(23535)

UserDay = Day(4707*5)

Return value

Integer

Rule: If <date exprs> is Null, Day returns a Null.


Example

The following example uses various interrelated date functions to display the year, the month, the day and the weekday for a date entered by the user. Finally, it gives the date's serial number. The code for the function "Suffix" should be pasted after the End Function statement for the event.

Function OnLButtonDblClk ( )

Dim UserEntry As String, UserYear As Integer, UserMonth As Integer

Dim UserDay As Integer, UserDOW As Integer, DOWName As String

Dim Msg As String, NL As String, LeapYear As String

' Define newline

NL = Chr$(10)

' Get user input

UserEntry = InputBox("Please type a date.")	UserEntry = CDate(UserEntry)

' Calculate year

UserYear = Year(UserEntry)

' Calculate month

UserMonth = Month(UserEntry)

' Calculate day

UserDay = Day(UserEntry)

' Calculate day of week

UserDOW = Weekday(UserEntry)

' Convert to name of day

DOWName = Format$ (UserEntry, "dddd")

' Determine if the year is a leap year or a centesimal

If UserYear Mod 4 = 0 And UserYear Mod 100 = 0 Then

' Evenly divisible by 400?

If UserYear Mod 400 = 0 Then

LeapYear = "is a leap year."

' Not evenly divisible

Else

LeapYear = "is a centesimal but not a leap year."

End If

ElseIf UserYear Mod 4 = 0 Then

LeapYear = "is a leap year."

Else

LeapYear = "is not a leap year."

End If

' Display results for the user after the pattern:

' The given year 1982 is not a leap year. The weekday number for

' the 12th day of the 11th month in 1982 is 3, which means that

' day was a Tuesday.

'

' The date serial number for 11/12/82 is: 30267

'

MsgBox "The given year, " & UserYear & ", " & LeapYear

Msg = "The weekday number for the "

Msg = Msg & UserDay & Suffix(UserDay) & " day "

Msg = Msg & "of the " & UserMonth & Suffix(UserMonth) & " month "

Msg = Msg & "in " & UserYear & " is " & UserDOW

Msg = Msg & ", which means that day is a " & DOWName & "." & NL & NL

Msg = Msg & "The date serial number for " & UserEntry & " is:  "

Msg = Msg & CDbl(DateSerial(UserYear, UserMonth, UserDay))

MsgBox Msg

End Function

' The following function called in the previous procedure tells us what

' suffix (1st, 2nd, 3rd) to use with a number

Function Suffix (DateNum) As String

Select Case DateNum

Case 1

Suffix = "st"

Case 2

Suffix = "nd"

Case 3

Suffix = "rd"

Case Else

Suffix = "th"

End Select

End Function

For information about using the code examples, see Using the code examples.


See also

Date, Date$ functions

Hour function

Minute function

Month function

Now function

Second function

Weekday function

Year function


DDB function

Example   See also

Returns the depreciation of an asset for a given, single period using the double-declining balance method.

Syntax

DDB(<initial cost>, <salvage value>, <asset lifespan>, <single period>)

<initial cost>

Numeric expression that specifies the initial cost of the asset.

<salvage value>

Numeric expression that specifies the value of the asset at the end of its useful life.

<asset lifespan>

Numeric expression that specifies the length of the useful life of the asset.

Rule for <asset lifespan>: Must be given in the same units of measure as <single period>. For example, if <single period> represents a month, then <asset lifespan> must be expressed in months.

<single period>

Numeric expression that specifies the period for which you want DDB to calculate the depreciation.

Rule for <single period>: Must be given in the same units of measure as <asset lifespan>. For example, if <asset lifespan> is expressed in months, then <single period> must represent a period of one month.

Example:

The following example calculates the depreciation for the first year under the double-declining balance method for a new machine purchased at $1400, with a salvage value of $200, and a useful life estimated at 10 years. The result ($280) is assigned to the variable Year1Deprec.

Year1Deprec = DDB(1400, 200, 10, 1)

Return value

Double

Double-declining balance depreciation is an accelerated method of depreciation that results in higher depreciation charges and greater tax savings in the earlier years of the useful life of a fixed asset than are given by the straight-line depreciation method (SLN), where charges are uniform throughout.

The method uses the following formula:

Depreciation over <single period> = ((<initial cost> - total depreciation from prior periods) * 2) / <asset lifespan>.

Rules

•	<asset lifespan> and <single period> must both be expressed in terms of the same units of time.

•	All parameters must be positive numbers.


Example

The following example prompts the user for various particulars about an asset, then returns the asset's double-declining balance depreciation for any single period.

Function OnLButtonDblClk()

Dim Fmt As String, InitCost As Double, SalvageVal As Double

Dim MonthLife As Double, LifeSpan As Double, DepYear As Double

Dim PeriodDepr As Double, Msg As String, YearMonths

YearMonths = 12

' Define money format

Fmt = "###,##0.00"

' Get user input

InitCost = InputBox("What is the initial cost of the asset?")

SalvageVal = InputBox("What is the asset's value at the end of its life?")

MonthLife = InputBox("What is the asset's useful life in months?")

' Ensure period is >= 1 year

Do While MonthLife < YearMonths

MsgBox "Asset life must be a year or more."

MonthLife = InputBox("What is the asset's useful life in months?")

Loop

' Convert months to years

LifeSpan = MonthLife / YearMonths

If LifeSpan <> Int(MonthLife / YearMonths) Then

'Round up to nearest year

LifeSpan = Int(LifeSpan + 1)

End If

DepYear = CInt(InputBox("For which year do you want depreciation?"))

Do While DepYear < 1 Or DepYear > LifeSpan

MsgBox "You must type at least 1 but not more than " & LifeSpan

DepYear = CInt(InputBox("For which year do you want depreciation?"))

Loop

PeriodDepr = DDB(InitCost, SalvageVal, LifeSpan, DepYear)

Msg = "The depreciation for year " & DepYear & " is "

Msg = Msg & Format(PeriodDepr, Fmt) & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

SLN function

SYD function


Declare statement

Example   See also

Informs Actuate Basic that you are using, and how you are using, an external procedure in a Dynamic Link Library (DLL). A procedure that returns a value is declared as a Function; a procedure that does not return a value is declared as a Sub.

Syntax

Declare Sub <proc> Lib <lib name> [Alias <alias name>] [([<arg list>])]

Declare Function <proc> Lib <lib name> [Alias <alias name> ] [([<arg list>])] [As <function data type>]

Sub

Keyword indicating that the procedure does not return a value.

Function

Keyword indicating that the procedure returns a value and therefore can be used in an expression.

<proc>

The name of the sub or function you are declaring as it is named in the DLL where it is defined. For function procedures, the data type of the procedure determines the data type it returns. Unless you use an As clause, <proc> can include a type-declaration character indicating the data type returned by the procedure.

Rules for <proc>:

•	Must follow standard variable naming conventions.

•	Cannot be the name of any other procedure.

•	Cannot include a type-declaration character if you use the As clause.

Lib

Keyword before the name of the DLL, <lib name>, that contains the procedure being declared.

<lib name>

String literal of the DOS filename of the DLL that contains <proc> or <alias name>.

Rule for <lib name>: If not in the current directory on the current drive, <lib name> must specify the full path name.

Alias

Keyword indicating the sub or function as it is named in the DLL.

Rules for Alias:

•	Must be used when the DLL procedure name is the same as an Actuate Basic reserved word.

•	Must be used when a DLL procedure has the same name as a global variable, constant, or any other procedure in the same scope.

•	Must be used if any characters in the DLL procedure name are not allowed in Actuate Basic names.

<alias name>

String literal for the alternative name of <proc> as it appears within <lib name>.

<arg list>

List of variables representing arguments that are passed to the sub or function procedure when it is called. <arg list> has the following syntax:

[ByVal] <arg variable> [ As <arg data type>] [,[ByVal] <arg variable>
[ As <arg data type>] ] . . .

Arguments may be passed by value (using the keyword ByVal) or by reference.

ByVal

Keyword indicating that the argument is passed by value rather than by reference. The following table summarizes the behavior of ByVal.

<arg variable>	Behavior of ByVal
Numeric expression	Converts <arg variable> to the data type indicated by its type-declaration character, if any, or else by its associated As clause. Passes the converted value to the DLL procedure.
Null-terminated string	Passes the address of the string data to the DLL procedure
Default: String descriptor is sent to the called DLL procedure.

Rule for ByVal: Cannot be used with an array, user-defined type, or class variable.

<arg variable>

Any valid Actuate Basic variable name.

Rules for <arg variable>:

•	Must conform to standard variable naming conventions.

•	If it includes a type-declaration character, you cannot use the As <arg data type> clause.

As <arg data type>

Clause that declares the data type of <arg variable> as Any, CPointer, Currency, Date, Double, Integer, Long, Single, String, Variant, a user-defined type, or any class.

Rules for As <arg data type>:

•	If you use this clause, do not use a type-declaration character as part of <arg variable>.

•	Use the Any data type in an As clause only to override type checking for that argument.

Default: Variant

As <function data type>

Clause that declares the data type of the value returned by a function procedure, and not valid with declarations of sub procedures. The argument <function data type> can be Integer, Long, Single, Double, Currency, String (variable-length only), or Variant.

Description

Use Declare to declare external procedures--procedures contained in a DLL. Declare needs to appear at or near the beginning of the Actuate Basic source code (.BAS) file. DLL procedures declared in any module are available to all procedures in all modules.

Empty parentheses indicate that the sub or function procedure has no arguments and that arguments should be checked to ensure that none are passed. In the following example, the sub First takes no arguments.

Declare Sub First Lib "MyLIB"()

If you use arguments in a call to First, an error occurs. The following example code would return an error for a sub First that takes no arguments.

Declare Sub First Lib "MyLIB" (arg%)

When an argument list appears, the number and type of arguments are checked each time the procedure is called. In the following example, the sub procedure Second takes one Long argument.

Declare Sub Second Lib "MyLIB" (X&)

Rule

If the name of the procedure in the DLL does not conform to Actuate Basic naming conventions, you must use an Alias clause to specify it as it appears in the DLL. From that point on, <alias name> is the name it uses in Actuate Basic.


Example

The following example shows a Declare statement that substitutes a shorter name (WinDir) for the full name of a Windows function that retrieves the Windows directory (GetWindowsDirectory). The function takes two arguments which are declared here by value and returns an integer.

Declare Function WinDir Lib "Kernel" Alias "GetWindowsDirectory" (ByVal

{XXxde} lpBuffer As String, ByVal nSize As Integer) As Integer

For information about using the code examples, see Using the code examples.


See also

Call statement


Declare...End Declare statement

Example   See also

Declares global constants, global variables, and user-defined variable types.

Syntax

Declare

<declaration statements>

End Declare

<declaration statements>

Any number of valid Actuate Basic global variable, global constant, or user-defined data type declaration statements.

Rule

To declare global constants, global variables, and user-defined variable types in Actuate Basic, you must bookend your declarations with Declare and End Declare, as shown in the Example section that follow the Tips.

Tips

•	Do not confuse this multi-line Declare... End Declare statement with the single-line Declare statement that allows you to access functions in external dynamic link library files (DLLs).

•	You can use as few or as many Declare... End Declare blocks as you need. It is good programming practice, however, to position all such statements in one group at or near the beginning of your code.


Example

The following code in a user Basic file contains several different types of declarations within a single Declare... End Declare block.

Declare

' Global dynamic array:

Global CarModelsCount( )

' Global fixed array with 366 elements:

Global Birthdays(366)

' Global Integer variable:

Global PrintFlag as Integer

' Global constant:

Global Const PI = 3.14159265359

' User-defined (non-intrinsic) variable type:

Type FullName

FirstName As String
MiddleName As String

Lastname As String

ExactAge As Double

End Type

' A declaration based on the new non-instrinsic type above. Like an alias:
Type PenName As FullName

' Two similar user-defined variable types, but based on intrinsic types this time:

Type CustomerCount As Integer

Type LiquidMeasure As Double

End Declare

For information about using the code examples, see Using the code examples.


See also

Const statement

Declare statement

Global statement

Type...As statement

Type...End Type statement


Decode, Decode$ functions

See also

Converts a value previously encoded using Encode from the internal encoding, and returns the string in the encoding format you specify.

Syntax

Decode(<value>, <encoding format>)

Decode$(<value>, <encoding format>)

<value>

String expression encoded in the internal encoding format.

Rule: If <value> is Null, Decode[$] returns Null.

<encoding format>

String expression that specifies the name of the encoding format you want the value to be encoded into, such as "ASCII".

Examples:

The following are names of possible encoding formats used by United States locals.

"ISO 8859-1", "USASCII", "ASCII"

Return value

Decode: Variant

Decode$: String


See also

Encode, Encode$ functions


Dim statement

See also

Declares variables and allocates memory. Dim is an abbreviation for the Basic term dimension.

Syntax

Dim <varname> [([<subscripts>])] [As [{Volatile|Transient|Persistent}] <type>] [, <varname> [([<subscripts>])] [As [{Volatile|Transient|Persistent}] <type>]]...

<varname>

A name you create for the new variable.

<subscripts>

Describes array dimensions according to the following syntax:

[<lower> To] <upper>[,[<lower> To]<upper>]...

Rules for <subscripts>:

•	If you do not supply subscript values between parentheses, Actuate Basic declares a dynamic array.

•	Range from <lower> to <upper> can be from -2147483648 to 2147483647, inclusive.

Examples of <subscripts>:

The following statements are equivalent if you do not use Option Base.

Dim P(7,5)

Dim P(0 TO 7, 0 TO 5)

Dim P(7, 0 TO 5)

The following example declares a dynamic array.

Dim TestArray( )

[{Volatile|Transient|Persistent}]

These keywords are optional. When omitted, the variable is Persistent by default.

You probably will not want to use these keywords in your own code, and Actuate does not support their use in the Variables dialog box. They are documented here to help you understand AFC source code more thoroughly.

Persistent--The variable is to be written to the .ROI file subject to standard ROI compression.

Transient--The variable is used only in the Factory and will not be written to the .ROI file. When the object is read from the ROI file, Transient variables are set to their default values. Marking variables as Transient results in a smaller .ROI file, and improves object locality.

Volatile--Like a Persistent variable, the variable is written to the .ROI file. However, unlike Persistent, Volatile variables are not subject to .ROI compression. Marking variables as Volatile improves object locality for objects with variables that change frequently during a report run, at the cost of taking additional space in the .ROI file.

As <type>

Specifies a data type or class for the variable. If you specify a class, <varname> can hold a reference to an instance of that class or descendant classes; otherwise, if you do not specify As <type>, <varname> is of type Variant.

Description

When you dimension variables with Dim, they are initialized as follows:

Type	Initialized as:
Numeric	0
Variant	Empty
Variable-length strings	Zero-length strings
CPointer	Null
User-defined	Separate variables
Object reference	Nothing (before Set)
Rules

•	To declare variables that are available to all procedures within the module, use Global.

•	To declare variables that are available only in the procedure, use Dim at the procedure level.

•	You cannot redimension an array variable with ReDim if you explicitly specified its size using Dim.

Tips

•	To avoid assigning incorrect variable types, use the As clause to declare variable types.

•	To declare dynamic arrays, use Dim with empty parentheses after the variable name. Later, to define the number of dimensions and elements in the array, use ReDim.

Dim TestArray( )

•	To set the value of an instance handle to an instance of a class, use Set.


See also

ReDim statement

Set statement


Do...Loop statement

Example   See also

Repeats a block of instructions while a specified condition is True or until a specified condition becomes True.

Syntax

Syntax 1

Do [{While | Until } <expression to reevaluate>]

<statements>

[Exit Do]

<statements>

Loop

Syntax 2

Do

<statements>

[Exit Do]

<statements>

Loop [{While | Until } <expression to reevaluate>]

While

Keyword indicating that every time Actuate Basic begins or repeats the instructions between Do and Loop, Actuate Basic must determine whether <expression to reevaluate> is True or False.

Rules:

•	If <expression to reevaluate> is True, the program executes the loop.

•	If <expression to reevaluate> is False, or has become False during the last trip through the loop, Actuate Basic skips the intervening statements and passes control to the statement following Loop.

Until

Keyword indicating that every time Actuate Basic begins or repeats the instructions between Do and Loop, Actuate Basic must determine whether <expression to reevaluate> is True or False.

Rules:

•	If <expression to reevaluate> is False, the program executes the loop.

•	If <expression to reevaluate> is True, or has become True during the last trip through the loop, Actuate Basic skips the intervening statements and passes control to the statement following Loop.

Example:

The following example assumes Counter starts at 1 and increments by 1 each time through the loop, the following statement fragments are equivalent. In either case, the associated loop is executed nine times.

Do While Counter < 10

Loop Until Counter = 10

If Counter is instead incremented by 2 each time, the first associated loop is executed five (1, 3, 5, 7, 9) times. The second loop, however, never stops executing because Counter increments from 9 to 11 and so never exactly equals 10. A minor correction can address this issue. In the following example, Counter is incremented by 2 each time and the loop executes only five times.

Do Until Counter >= 10

Exit Do

A keyword indicating that the program must immediately interrupt the loop at the point at which the keyword occurs, and pass control to the statement following Loop.

<expression to reevaluate>

Any valid numeric or string expression that evaluates to True or False.

<statements>

Zero or more valid Actuate Basic statements.

Description

If the condition to evaluate is placed at the bottom of the loop (after Loop), the loop will execute at least once; if the condition to evaluate is placed after Do, the loop will not execute at all if the condition is initially false.

Tips

•	To stop a loop from continuing based upon whether a given expression is True or False, use Exit Do within a conditional structure like If Then.

•	Exit Do does not automatically exit all nested loops. When Do...Loop statements are nested, an Exit Do in a loop transfers control to the loop that is logically nested one level above the current one. For example, if you want to provide users with a way to back out of a complicated structure, map out a logical backtracking path in the form of several Exit Do statements, one at each level to which they are backtracking.

•	It is good programming practice to evaluate Boolean variables -- not by inspecting their content for a nonzero (True) or zero (False) numeric value -- but by using the keywords True or False.


Example

The following example asks the user whether to display Demo 1 or Demo 2 first. In Demo 1, the program prompts the user to type a number within a certain range. If the number typed falls outside the range, the Demo repeats the prompt. In Demo 2, the program prints the numbers from 1 to 11.

Function OnLButtonDblClk()

Dim DemoNum As Integer, Counter As Integer

Dim NL As String, FirstShown As Integer

Dim SecondShown As Integer, BothShown As Integer

Dim UserTyped As Integer, Msg As String

' Get user input

DemoNum = InputBox("Choose whether to start with Demo 1 or 2.")

' Initialize flags and counters before the top of the loop

' Initially set Counter to 1

Counter = 1

' Define newline

NL = Chr$(10)

' Assume Demo 1 has not been shown

FirstShown = False

' Assume Demo 2 has not been shown

SecondShown = False

' Assume neither have been shown

BothShown = False

' The outer loop will execute until the exit condition BothShown is true

Do Until BothShown

' First inner loop is executed if the user typed 1

Do While DemoNum = 1

' This is the first demo

UserTyped = InputBox("Please type a number between 1 and 9.")

If UserTyped >= 1 And UserTyped <= 9 Then

' Remember Demo 1 has been shown

DemoNum = 2

' User is ready for Demo 2

FirstShown = True

' Exit first inner loop

Exit Do

End If

Loop

' The second inner loop is executed when the user type 2

' but only if user hasn't seen the second demo (SecondShown is false)

Do While DemoNum = 2 And Not SecondShown

' This nested loop will execute 11 times and return to 2nd inner loop

Do Until Counter = 12

Msg = Msg & Counter & NL

Counter = Counter + 1

Loop

DemoNum = 1

' Exit condition for second inner loop

SecondShown = True

MsgBox Msg

Loop

' Set up final exit condition from outer loop

If FirstShown and SecondShown then BothShown = True

Loop

MsgBox "Both demos have been shown. Goodbye!"

End Function

For information about using the code examples, see Using the code examples.


See also

Exit statement

If...Then...Else statement

While...Wend statement


Encode, Encode$ functions

See also

Converts an internally encoded value into the encoding format you specify and returns the string in the new encoding format.

Syntax

Encode(<value>, <encoding format>)

Encode$(<value>, <encoding format>)

<value>

String expression encoded in the internal encoding format.

Rule: If <value> is Null, Encode[$] returns Null.

<encoding format>

String expression that specifies the name of the encoding format you want the value to be encoded into, such as "ASCII".

Examples:

The following are names of possible encoding formats used by United States locals.

"ISO 8859-1", "USASCII", "ASCII"

Return value

Encode: Variant

Encode$: String


See also

Decode, Decode$ functions


End statement

Example   See also

Signals the completion of a multiline If...Then...Else statement, a Select Case statement, a block of Function or Sub statements, a Declare section, a Type or Class definition, or terminates the entire program.

Syntax

End [{ Class | Declare | Function | If | Select | Sub | Type }]

End

Keyword that terminates the entire program.

End Class

Keyword that signifies the completion of a Class statement.

Rule: End Class must terminate every Class statement.

End Declare

Keyword that completes a multiple-line Declare statement.

Rule: End Declare must terminate a Declare statement that is in a multiline or block format.

End Function

Keyword that completes a Function definition.

Rule: End Function must terminate every Function statement. Actuate Basic automatically supplies End Function when you type a Function statement.

End If

Keyword that completes a multiple-line If...Then...Else statement.

Rule: End If must terminate every If...Then...Else statement that is in multiline or block format.

End Select

Keyword that completes a Select Case statement.

Rule: End Select must terminate every Select Case statement.

End Sub

Keyword that completes a Sub procedure.

Rule: End Sub must terminate every Sub statement. Actuate Basic automatically supplies End Sub when you type a Sub statement.

End Type

Keyword that completes a Type statement.

Rule: End Type must terminate every Type statement.


Example

The following example uses a Select Case block to return the name of the day of the week for the current day. To try this example, remove the End statement and run the example. It generates an error message that says "Select Case without End Select".

Function OnLButtonDblClk()

Dim DayNumber As Integer, DayName As String

DayNumber = Weekday(Date)

Select Case DayNumber

Case 1

DayName = "Sunday"

Case 2

DayName = "Monday"

Case 3

DayName = "Tuesday"

Case 4

DayName = "Wednesday"

Case 5

DayName = "Thursday"

Case 6

DayName = "Friday"

Case 7

DayName = "Saturday"

End Select

MsgBox DayName

End Function

For information about using the code examples, see Using the code examples.


See also

Class statement

Declare statement

Function...End Function statement

If...Then...Else statement

Select Case statement

Stop statement

Sub...End Sub statement

Type...End Type statement


Environ, Environ$ functions

Example   See also

Returns the setting of a specified environment variable.

Syntax

Environ$(<environment variable name>)

Environ[$](<environment variable name>)

- or -

Environ$(<table entry number>)

Environ[$](<table entry number>)

<environment variable name>

String expression that specifies the name of an environment variable about which you want to know the settings. An environment variable is an Internal variable an operating system uses to hold information about the computer system in which your program is running. These variables contain information about the current drive and path, and special information needed by various programs. Although each computer system has a different set of environment variables with different values, there are a few that are common, such as PATH.

Rule: Must not contain a space.

<table entry number>

Numeric expression that specifies the variable's entry number. This number corresponds to its position in the environment table, where the first line in the table is line 1.

Rule: Must be greater than zero.

Example:

PathToJavaClasses = Environ("CLASSPATH")

Return value

Environ: Variant

Environ$: String

•	If <table entry number> is greater than the number of lines in the table, Environ[$] returns a Empty string.

•	If you call Environ[$] using <environment variable name>, the function returns only the content of the variable, not its name.

•	If you call Environ[$] using <table entry number>, the function returns both the content of the variable in that position and its name.


Example

The following Windows-based code looks for the PATH environment variable in the user's system. If it finds the variable, it then displays its entry number and the length of the string it contains.

Function OnLButtonDblClk ( )

Dim EnvString As String, LineNumber As Integer

Dim Msg As String, Pathlen As Integer

' Initialize line index to 1

LineNumber = 1

Do

' Get environment variable

EnvString = Environ(LineNumber)

' Is it the PATH entry?

If Left(EnvString, 5) = "PATH=" Then

' If so, get its length

Pathlen = Len(Environ("PATH"))

Msg = "The PATH entry occurs at position " & LineNumber & ".  "

Msg = Msg & "Its length is " & Pathlen & "."

Exit Do

Else

' Not the PATH entry, so ...increment line counter

LineNumber = LineNumber + 1

End If

Loop Until EnvString = ""

If Pathlen > 0 Then

MsgBox Msg

Else

MsgBox "This system is not using a PATH environment variable."

End If

End Function

For information about using the code examples, see Using the code examples.


See also

Command, Command$ functions


EOF function

Example   See also

Returns a value that indicates whether the end of a file being input has been reached.

Syntax

EOF(<open file number>)

<open file number>

Numeric expression that is the file descriptor used in the previously issued Open statement to open the target file.

Rules:

•	Must be the number of a currently open file.

•	Must refer to a disk file.

Examples:

The following code opens an existing disk file and then uses EOF repeatedly to test whether or not the end of the file has yet been reached.

Open "c:\vb\tests\test.fil" For Input As #1

Do While Not EOF(1)	'Test for end of file.

        Input #1, FileData  	'Read line of data.

Loop

Return value

Integer (0 for False or 1 for True)

EOF behaves differently depending upon the mode of access you use for the file.

•	For Sequential files, EOF returns 1 (True) if the end of the file has been reached; otherwise, it returns 0 (False).

•	For Random or Binary files, EOF returns 1 (True) if the last executed Get statement was unable to read an entire record; otherwise, it returns 0 (False).

Tip

Use EOF when you handle sequential files to avoid an error generated when you try to access a file's contents past the end of a file.


Example

The following example creates a test file on disk that contains random numbers. The procedure opens the test file, reports the last value in the test file, and deletes the sample file from the disk. In this example OnLButtonDblClk( ) is overridden to generate the test file, report the value, and prompt the user to delete the test file. The procedure MakeDataFile( ) should be typed after the End Function of the OnLButtonDblClk( ) procedure or saved in an Actuate code module (.BAS file).

Function OnLButtonDblClk()

Dim NL As String, TempVar As Integer, Msg As String

' Define newline

NL = Chr$(10)

' Generate sample file

MakeDataFile

' Open sample for input

Open "TEST.FIL" For Input As #1

' Check for end of file

Do While Not EOF(1)

' Read data

Input #1, TempVar

Loop

' Close test file

Close #1

Msg = "The last value in the test file was "

Msg = Msg & TempVar & "." & NL

Msg = Msg & NL & "Select OK to delete the created test file."

MsgBox Msg

' Delete test file

Kill "TEST.FIL"

End Function

'

'Here is the procedure that generates the test file

'

Sub MakeDataFile ( )

Dim I As Integer

' Open file for output

Open "TEST.FIL" For Output As #1

' Generate random values

For I = 0 To 250

Print #1, Int(711 * Rnd)

Next I

' Close test file

Close #1

End Sub

For information about using the code examples, see Using the code examples.


See also

Loc function

LOF function

Open statement


Erase statement

Example   See also

Deallocates memory reserved for dynamic arrays, or reinitializes the elements in a fixed array.

Syntax

Erase <array name>... [, <array name> ]

<array name>

Any valid array name.

Example:

Erase BigArray

Description

Erase behaves differently depending upon whether <array name> refers to a fixed or to a dynamic array.

•	When Erase refers to a fixed array, Erase reinitializes the contents of the array but does not free up memory.

•	When Erase refers to a dynamic array, Erase recovers the memory previously allocated to the array.

Erase reinitializes fixed arrays as follows:

Type of fixed array	Array element set to
Numeric	0 (Zero)
String (variable-length)	Empty
Variant	Empty
User-Defined	The value as shown here for each component type, taken separately
Object	Nothing
CPointer	Null
Tips

•	If you erase a dynamic array, you can use Dim or ReDim to create a new dynamic array with the same name as the old one.

•	You do not need to erase a dynamic array before you redimension it with ReDim.


Example

The following example creates an array, fills it with values, and then erases it.

Static Function OnLButtonDblClk()

' Declare variables

Dim I As Integer, J As Integer, Total As Long, Msg

' Create 2-D integer array

Dim Matrix(50, 50) As Integer

For I = 1 To 50

For J = 1 To 50

' Put some values into array

Matrix(I, J) = J

Next J

Next I

' Erase array

Erase Matrix

' Initialize total counter

Total = 0

For I = 1 To 50

For J = 1 To 50

' Sum elements after Erase

Total = Total + Matrix(I, J)

' to make sure all are set to zero

Next J

Next I

Msg = "An array has been created, filled, and erased. When the "

Msg = Msg & "Erase statement was executed, zeros replaced the "

Msg = Msg & "previous contents of each element.  The total of "

Msg = Msg & "all elements is now " & Total & ", "

Msg = Msg & "demonstrating that all elements have been cleared."

' Display message

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Dim statement

ReDim statement


Erl function

Example   See also

Returns the line number for the most recent run-time error.

Syntax

Erl

Return value

Integer

•	When it runs an application, Actuate Basic uses Erl to report the number of the line at which the most recent error occurred, or of the line most closely preceding it.

•	When Erl is 0, it means one of three things:

•	No run-time error has occurred

•	An error could have occurred, but there was no line number just before the point at which the error occurred, or your program contains no line numbers.

•	Actuate Basic has reset Erl to 0 because it executed Resume or On Error, or because it executed Exit Sub or Exit Function from within an error handling routine.

•	Erl returns only a line number, not a line label.

Tips

•	To preserve the value of Erl before it gets reset to 0, immediately assign it to a variable.

•	To set the value of Erl indirectly, simulate an error condition using an Error statement.


Example

In the following example, the program generates an error because it attempts to divide a number by zero. It then displays a message to the user indicating the line number of the error.

Function OnLButtonDblClk ( )

Dim XVar, YVar, ZVar

' Set up error handler

On Error GoTo ErrorHandler

YVar = 1

' Now cause division by zero error:

 XVar = YVar / ZVar

Exit Function

' Error handler starts here

ErrorHandler:

MsgBox "Error occurred at program line " & Erl

Resume Next

End Function

For information about using the code examples, see Using the code examples.


See also

Err statement

Error statement

On Error statement

Resume statement


Err function

Example   See also

Returns the code number for the most recent run-time error.

Syntax

Err

Return value

Integer

•	Returns an Integer between 0 and 2,147,483,647.

•	When it runs an application, Actuate Basic uses Err to report the occurrence of a run-time error and its error code.

•	When Err is 0, it means no run-time error has occurred.

•	Actuate Basic sets or resets Err to 0 whenever it executes Resume or On Error, or whenever it executes Exit Sub or Exit Function from within an error handling routine.

Tips

•	To preserve the value of Err before it gets reset to 0, immediately assign it to a variable.

•	To set the value of Err directly, use an Err statement. To set it indirectly, simulate an error condition using an Error statement.


Example

In the following example, the program generates an error because it attempts to divide a number by zero. It then displays the code number of the error.

Function OnLButtonDblClk()

Dim XVar, YVar, ZVar

' Set up error handler

On Error GoTo ErrorHandler

YVar = 1

' Now cause division by zero error:

XVar = YVar / ZVar

Exit Function

'

' Error handler starts here

ErrorHandler:

MsgBox "Error number " & Err & " occurred"

Resume Next

End Function

For information about using the code examples, see Using the code examples.


See also

Erl function

Err statement

Error statement

On Error statement

Resume statementResume statement

Error, Error$ functions

Error statement


Err statement

Example   See also

Sets Err to a given value.

Syntax

Err = <error code>

<error code>

Numeric expression between 0 and 2,147,483,647 indicating the code of the most recent run-time error.

Description

•	When it runs an application, Actuate Basic uses Err to record the occurrence of a run-time error and its error code.

•	When Err is 0, it means no run-time error has occurred.

•	Actuate Basic sets or resets Err to 0 whenever it executes Resume or On Error, or whenever it executes Exit Sub or Exit Function from within an error handling routine.

Tips

•	To define and use your own error code, use a value for <error code> that is greater than any of the standard Actuate Basic error codes.  You can work down from error code 2,147,483,647 to find an available user-defined error number.  Write a routine that assigns that number to Err whenever certain error conditions that you define are true.  Also write an error handling routine that translates the error number into an understandable message for the user.

•	You will find many "user-defined" codes among the standard ones.

•	The Error statement can set Err to any value, because it simulates any run-time error.

•	To preserve the value of Err before it gets reset to 0, immediately assign it to a variable.


Example

The following example prompts the user for a filename, attempts to open the file to verify its existence, then handles a range of errors that may result.

Function OnLButtonDblClk ( )

Dim FileName As String

' Set up error handler

On Error Resume Next

FileName = InputBox("Please type a file name: ")

Do

' Clear any error

Err = 0

' Attempt to open file

Open FileName For Input As #1

' Handle error, if any

Select Case Err

' No error = success!

Case 0

MsgBox UCase$(FileName) & " was found."

' I/O errors

Case 14

FileName = InputBox("File not found. Please try again.")

' Handle all other cases

Case Else

MsgBox "Error:  Sorry!  Cannot continue!"

' Don't try again = failed!

Exit Do

End Select

Loop Until Err = 0

' Clean up

Close #1

End Function

For information about using the code examples, see Using the code examples.


See also

Erl function

Err function

Error, Error$ functions

Error statement


Error, Error$ functions

Example   See also

Returns the error message for the most recent run-time error, or for a specified error number.

Syntax

Error[(<error code>)]

Error$[(<error code>)]

<error code>

Numeric expression between 1 and 2,147,483,647 that is the error number to be displayed as a message string by Error[$].

Rule: If <error code> is not defined by Actuate Basic, Error[$] returns the following message string: "User-defined error".

Default: The message string for the most recent run-time error, if an error has occurred, or a zero-length string, if no error has occurred.

Rule: <error code> must be between 1 and 2,147,483,647, inclusive.

Return value

Error: Variant

Error$: String

•	With <error code>, the Error[$] function returns the message for the specified error number. In cases where context-sensitive information is inserted in the message at run-time, the context-sensitive string is replaced with a space character. For example, in the following message, a space is inserted where the array element index number would normally appear:

Control array element '  ' doesn't exist.

•	Without <error code>, the Error[$] function returns the message for the most recent run-time error. If no error has occurred, the Error[$] function returns an empty string.


Example

The following example shows error messages for user input number errors.

Function OnLButtonDblClk ( )

' Demo of Error$ function and Error statement

Dim Msg, NL, UserError, TempUser

' Set up error handler

On Error GoTo ErrorHandler

' Define newline

NL = Chr$(10)

TempUser = InputBox("Please type the number of an error to simulate.")

' Convert response to integer

UserError = Int(TempUser)

' Simulate given error

Error UserError

Exit Function

' Error handler starts here

ErrorHandler:

Msg = "The message for error number "

Msg = Msg & Err & " is:" & NL & NL

Msg = Msg & Error(Err)

MsgBox Msg

Resume Next

End Function

For information about using the code examples, see Using the code examples.


See also

Erl function

Err function

Error statement


Error statement

Example   See also

Simulates the occurrence of an error. Also, generates a user-defined error.

Syntax

Error <error code>[ ,<message> [ ,<message>....]]

<error code>

Integer between 1 and 2,147,483,647 that is the error you wish to artificially generate.

Example:

The following statement will cause Actuate Basic to stop your program and display the message "Division by zero," whether or not your program has actually attempted to divide anything by zero.

Error 8

<message>

You can pass any number of arguments in order to replace standard error messages. All extra messages are converted to strings and concatenated together. Then, the concatenated message is displayed instead of the standard error message.

Description

•	By setting the value of Err to <error code>, this statement simulates the occurrence of a specified error. It then passes control to whatever error-handling routine you have enabled, if any, so that in a debugging session you can verify whether or not that error-handler works.

•	If you have not enabled an error-handler when your program executes this statement, Actuate Basic stops your program and displays its own internal error message if it has one corresponding to <error code>, or "User-defined error" if it does not.

Tips

•	To define your own error code, use a value for <error code> that is greater than any of the standard Actuate Basic error codes. You can work down from error code 2,147,483,647 to find an available user-defined error number.

•	You will find many "user-defined" codes among the standard error codes Actuate Basic uses.


Example

The following example prompts the user for an error number, simulates the appropriate error, and passes control to an error handler, which then retrieves the corresponding message.

Function OnLButtonDblClk ( )

' Demo of Error$ function and Error statement

Dim Msg, NL, UserError, TempUser

' Set up error handler

On Error GoTo ErrorHandler

' Define newline

NL = Chr$(10)

TempUser = InputBox("Please type the number of an error to simulate.")

' Convert response to integer

UserError = Int(TempUser)

' Simulate given error

Error UserError

Exit Function

' Error handler starts here

ErrorHandler:

Msg = "The message for error number "

Msg = Msg & Err & " is:" & NL & NL

Msg = Msg & Error(Err)

MsgBox Msg

Resume Next

End Function

For information about using the code examples, see Using the code examples.


See also

Erl function

Err function

Err statement

On Error statement

Resume statement


Exit statement

Example   See also

Terminates execution of the instructions specified in a Do Loop or For Next structure, or in a Function or Sub procedure.

Syntax

Exit { Do | For | Function | Sub }

Exit Do

Keyword used to terminate a Do...Loop statement.

Rules for Exit Do:

•	When it encounters Exit Do, Actuate Basic transfers control to the statement following the Loop keyword.

•	If it encounters Exit Do within a nested loop, the program transfers control to the loop that is nested one level above the one in which it occurs.

•	Use Exit Do only within a Do Loop statement.

Exit For

Keyword used to terminate a For...Next statement.

Rules for Exit For:

•	When it encounters Exit For, Actuate Basic transfers control to the statement following the Next keyword.

•	If it encounters Exit For within a nested loop, the program transfers control to the loop that is nested one level above the one in which it occurs.

•	Use Exit For only within a For Next statement.

Exit Function

Keyword used to terminate a Function statement.

Rule for Exit Function: When it encounters Exit Function, Actuate Basic transfers control to the statement following the one that called the current Function statement.

Exit Sub

Keyword used to terminate a Sub statement.

Rule: When it encounters Exit Sub, Actuate Basic transfers control to the statement following the one that called the current Sub statement.

Tips

•	To stop a loop from continuing or repeating based upon whether or not a given expression is true, use Exit Do within a conditional structure like an If...Then...Else statement.

•	Do not confuse Exit with End. Use End to define the completion of a structure.


Example

The following example shows how to use nested statements with Exit. When a random number generated matches one of those specified in the first Case clause, Actuate Basic exits the For...Next statement and the Do...Loop statement in two separate steps via both Exit For and Exit Do. When the random number matches one of those in the second Case clause, Actuate Basic exits the both statements in only one step, using Exit Do alone. A message reports in which Case clause the loops were terminated.

Function OnLButtonDblClk()

Dim I As Integer, Num As Integer, Msg As String

Dim NL As String, BumpOut As Integer

' Define newline and carriage return

NL = Chr$(10)

' Set a flag for ultimate exit

BumpOut = False

' Generate random numbers

Randomize Timer

' Set up an infinite loop

Do

' If we exited FOR, let's also exit DO

If BumpOut Then Exit Do

For I = 1 To 1000

' Generate random number

Num = Int(Rnd * 100)

Select Case Num

Case 7, 11, 13, 25

' This case causes an immediate exit from the For loop and

' will cause an exit from the Do loop on the next iteration

' Set flag for exit from Do next time

BumpOut = True

Exit For

Case 29, 35, 87

' This case causes an immediate exit from both loops but leaves

' BumpOut set to false so we can tell where the exit occurred

' Directly exit in one step

Exit Do

 End Select

Next I

Loop

' We exited in the first Case clause

If BumpOut Then

Msg = "Exited because of " & Num & " (1st case:  Two-step exit)."

Else

Msg = "Exited because of " & Num & " (2nd case:  One-step exit)."

End If

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Do...Loop statement

End statement

For...Next statement

Function...End Function statement

Sub...End Sub statement


Exp function

Example   See also

Raises e to the specified power.

Syntax

Exp(<power>)

<power>

Number, numeric expression, or Variant of VarType 8 (String) that specifies the exponent.

Rules:

•	<power> cannot be greater than 709.782712893.

•	If <power> evaluates to Null, Exp returns a Null.

Return value

Double

Tip

Exp is the inverse of Log.


Example

The following prints 1  2.71828183  1.79769313E308

Print #1, Exp(0), Exp(1), Exp(710)

For information about using the code examples, see Using the code examples.


See also

Log function


FileAttr function

Example   See also

Returns the mode of an open file or its DOS file handle.

Syntax

FileAttr(<file number>, <info type>)

<file number>

Numeric expression that is the number you used as a file descriptor when you opened the target file.

Rule: Must evaluate to the number of a currently open file.

<info type>

Numeric expression that specifies whether to return the open mode of the file (1), or the DOS file handle (2).

Rule: Must evaluate or round to 1 or 2

Example:

In the following code, Actuate Basic opens a file, then stores values returned by FileAttr in corresponding variables.

Open "TEST" For Input As #1

OpenMode = FileAttr(1,1)

DOSHandle = FileAttr(1,2)

Return value

Integer

•	When <info type> is 1, FileAttr returns a number that defines the mode under which the file was opened. The following table lists possible values for FileAttr when <info type> is 1, and the corresponding modes.

Return value	Mode for which file was opened
1	Input
2	Output
4	Random
8	Append
32	Binary
•	When <info type> is 2, FileAttr returns the file handle that DOS has assigned to the open file.


Example

In the following example, Actuate Basic creates a test file by opening it for Append. Then it displays a message indicating the DOS handle and open mode of the file.

Function OnLButtonDblClk( )

Dim FileNum As Integer, DOSHandle As Long

Dim OpenMode As String, Msg As String

' Get next available file number

FileNum = FreeFile

' Create sample file

Open "TESTFILE" For Append As FileNum

' Get file DOS handle

DOSHandle = FileAttr(FileNum, 2)

' Determine OpenMode

Select Case FileAttr(FileNum, 1)

Case 1: 	OpenMode = "Input"

Case 2: 	OpenMode = "Output"

Case 4: 	OpenMode = "Random"

Case 8: 	OpenMode = "Append"

Case 32: 	OpenMode = "Binary"

End Select

' Close test file

Close FileNum

Msg = "The file assigned DOS file handle " & DOSHandle

Msg = Msg & " was opened for " & OpenMode & "."

MsgBox Msg

' Delete test file

Kill "TESTFILE"

End Function

For information about using the code examples, see Using the code examples.


See also

GetAttr function

Open statement

SetAttr statement


FileCopy statement

Example   See also

Copies a file. Similar to the DOS command Copy.

Syntax

FileCopy <source>, <destination>

<source>

String expression that specifies the file to copy. Can include optional drive and path information.

Default path: Current default drive and directory.

Rules for <source>:

•	Cannot include wildcard characters.

•	Must refer to an existing file.

<destination>

String expression that specifies where <source> is to be copied. Can include optional drive and path information.

Default path: Current default drive and directory.

Rules for <destination>:

•	Must conform to platform's file naming conventions. Platform can be Windows 3.1, Windows NT, Windows 95, and UNIX.

•	Cannot include wildcard characters.

<source> or <destination> can optionally specify full path information, in which case either has the following syntax:

[<drive:>] [ \ ]<directory>[\<directory>]...(Windows)

[ / ]<directory>[/<directory>]...(UNIX)

<drive:>

Character, followed by a colon. Specifies the drive (Windows only).

<directory>

String expression that specifies the name of a directory or subdirectory.

Example:

Assuming a file name TEMP.FIL exists on a Windows system, and that it is located on the current drive and in the current directory, the following code copies it, places the new copy on drive D: in the subdirectory \FILES\ARCHIVES, and names that copy TEMP.ARC (while leaving TEMP.FIL alone where it is).

NewName = "D:\FILES\ARCHIVES\TEMP.ARC"

FileCopy "TEMP.FIL", NewName


Example

In the following example, Actuate Basic prompts the user for the names of a source and destination file, then copies the source to the destination.

Function OnLButtonDblClk ( )

Dim SourceFile As String, DestFile As String, Msg As String

On Error GoTo ErrHandler

SourceFile = InputBox("Copy what file?")

DestFile = InputBox("To where?")

' Copy file to destination

FileCopy SourceFile, DestFile

Exit Function

ErrHandler:

Select Case Err

' Path not found

Case 48

MsgBox "Sorry! Path not found."

Case 40

MsgBox "Sorry! Permission denied, or drive not available."

End Select

Msg = "An error occurred. Try specifying the full path "

Msg = Msg & "name of the source file, of the destination file, "

Msg = Msg & "or of both. If referring to a floppy drive, be sure "

Msg = Msg & "the correct disk is in the drive."

MsgBox Msg

Resume Next

End Function

For information about using the code examples, see Using the code examples.


See also

Kill statement

Name statement


FileDateTime function

Example   See also

Returns a string that indicates the date and time a specified file was created or last modified.

Syntax

FileDateTime(<file spec>)

<file spec>

String expression that specifies the name of a valid file. Can include optional drive and path information.

Default path: Current default drive and directory.

Rules:

•	Must be an unambiguous specification. Wildcards are not allowed.

•	Indicated file or files must exist.

•	Path, if specified, must exist.

<file spec> can optionally specify full path information, in which case it has the following syntax:

[<drive:>] [ \ ]<directory>[\<directory>]... (Windows)

[ / ]<directory>[/<directory>]... (UNIX)

<drive:>

Character, followed by a colon that specifies the drive on which the file is located (Windows only).

<directory>

String expression that specifies the name of a directory or subdirectory that constitutes a branch in the full path specification of <file spec>.

Example:

The following statement determines when the file MYDATA.MDB on a Windows system in the subdirectory C:\ACCESS was last modified, and converts the returned string to a date variant.

LastSaved = CVDate(FileDateTime("C:\ACCESS\MYDATA.MDB"))

Return value

String


Example

The following example prompts the user for the name of a file, then displays the date and time the file was last created or modified, and its size in bytes.

Function OnLButtonDblClk ( )

Dim Msg As String, TimeStamp As String, UserFile As String

On Error Goto ErrHandler

' Get file name

UserFile = InputBox("Please type a file name.")

' Get file date/time

TimeStamp = FileDateTime(UserFile)

Msg = UCase$(UserFile) & " was created or last modified on "

Msg = Msg & Format(TimeStamp, "dddd, mmmm dd, yyyy") & " at "

Msg = Msg & Format(TimeStamp, "h:nn AM/PM") & ".  Its size is "

' Get file size

Msg = Msg & FileLen(UserFile) & " bytes."

MsgBox Msg

Exit Function

ErrHandler:

MsgBox "Sorry! An error occurred. Please check the file name."

End Function

For information about using the code examples, see Using the code examples.


See also

FileLen function

GetAttr function


FileExists function

Example   See also

Determines whether or not a given file or directory exists.

Syntax

FileExists(<filename or dirname> [As String]) [As Boolean]

<filename or dirname>

String expression enclosed in double quotes that is the name of the file, directory, or subdirectory the existence of which you wish to determine.

Default path: Current drive and directory.

<filename or dirname> can optionally specify a full path, in which case it has the following syntax:

[<drive:>][\]<directory>[\<directory>]...(Windows)

[/]<directory>[/<directory>]...(UNIX)

<drive:>

Character, followed by a colon, that specifies the drive (Windows only).

<directory>

String expression that specifies the name of a directory or subdirectory.

Return value

Boolean

True if the file or directory exists, False if not.

Tip

It is good programming practice to evaluate Boolean variables -- not by inspecting their content for a nonzero (True) or zero (False) numeric value -- but by using the keywords True or False.


Example

Assuming a file called "readme.txt" exists in the current directory, the following statement assigns the value True to the variable FileAlreadyInstalled.

FileAlreadyInstalled = FileExists("readme.txt")

For information about using the code examples, see Using the code examples.


See also

FileDateTime function

GetAttr function

Kill statement

Name statement

Open statement


FileLen function

Example   See also

Returns the length of a given file in bytes.

Syntax

FileLen(<file spec>)

<file spec>

String expression that specifies the name of a valid file. Can include optional drive and path information.

Default path: Current default drive and directory.

Rules:

•	Must be an unambiguous specification. Wildcards are not allowed.

•	Indicated file or files must exist.

•	Path, if specified, must exist.

<file spec> can optionally specify full path information, in which case it has the following syntax:

[<drive:>] [ \ ]<directory>[\<directory>]... (Windows)

[ / ]<directory>[/<directory>]... (UNIX)

<drive:>

Character, followed by a colon that specifies the drive on which the file is located (Windows only).

<directory>

String expression that specifies the name of a directory or subdirectory that constitutes a branch in the full path specification of <file spec>.

Example:

The following statement determines the length of the file MYDATA.MDB on a Windows system in the subdirectory C:\ACCESS, and assigns the value to a variable.

SizeOfFile = FileLen("C:\ACCESS\MYDATA.MDB")

Return value

Integer

Rule: If the file specified in <file spec> is open when you call FileLen, the value FileLen returns represents the length of the file before it was opened.


Example

The following example prompts the user for the name of a file, then displays the date and time the file was last created or modified, and its size in bytes.

Function OnLButtonDblClk ( )

Dim Msg As String, TimeStamp As String, UserFile As String

On Error Goto ErrHandler

' Get file name

UserFile = InputBox("Please type a file name.")

' Get file date/time

TimeStamp = FileDateTime(UserFile)

Msg = UCase$(UserFile) & " was created or last modified on "

Msg = Msg & Format(TimeStamp, "dddd, mmmm dd, yyyy") & " at "

Msg = Msg & Format(TimeStamp, "h:nn AM/PM") & ".  Its size is "

' Get file size

Msg = Msg & FileLen(UserFile) & " bytes."

MsgBox Msg

Exit Function

ErrHandler:

MsgBox "Sorry! An error occurred. Please check the file name."

End Function

For information about using the code examples, see Using the code examples.


See also

FileDateTime function

GetAttr function

LOF function


Fix function

Example   See also

Removes the fractional part of a numeric expression and returns whatever integer remains.

Syntax

Fix(<number to truncate>)

<number to truncate>

A numeric expression from which the fractional part is removed so that only the integer component is returned.

Return value

Data type of <number to truncate>	Data type returned
Variant of VarType 8 (String) that can convert to a number	Variant of VarType 5 (Double)
Any other data type	Same data type as <number to round>
Null	Null
•	Int and Fix are functionally similar but not identical. For negative values, Int returns the first negative integer less than or equal to <number to round>; Fix returns the first negative integer greater than or equal to <number to round>. CInt is also similar, but not identical, to both Int and Fix.

•	Using some sample values as arguments, the following table shows the differences between Int, Fix, and CInt.

Value	Int (Value)	Fix (Value)	CInt(Value)
3.7	3	3	4
3.2	3	3	3
3	3	3	3
-3	-3	-3	-3
-3.2	-4	-3	-3
-3.7	-4	-3	-4
Tip

Fix is equivalent to Sgn (<number to round>) * Int (Abs (<number to round>)).


Example

The following example prompts for a number and displays the return values from Int, Fix, and Cint.

Function OnLButtonDblClk()

Dim Num As Double, Msg As String, NL As String

' Define newline

NL = Chr$(10)

' Get user input and strip off any surrounding spaces

Num = InputBox("Please type a number.")

Msg = "Int(" & Num & ") = " & Int(Num) & NL

Msg = Msg & "Fix(" & Num & ") = " & Fix(Num) & NL

Msg = Msg & "CInt(" & Num & ") = " & CInt(Num) & NL

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

CInt function

Int function


Format, Format$ functions

See also

Formats a numeric expression, date variant or string according to a specified pattern.

Syntax

Format(<exprs to format>, <format pattern>)

Format$(<exprs to format>, <format pattern>)

<exprs to format>

Expression to be displayed according to the <format pattern> you specify.

<format pattern>

A keyword that has been predefined in Actuate Basic or a string of format characters that specifies how the expression is to be displayed.

Rules for <format pattern>:

•	Do not mix different type format expressions (numeric, date/time or string) in a single <format pattern> argument.

•	Enclose <format pattern> within quotes.

Format[$] works differently depending on whether <expression to format> is numeric, date, or string data.

Return value

Format: Variant

Format$: String

Rule: If <format pattern> is omitted or is zero-length, and <exprs to format> is a numeric expression, Format[$] does the same thing as Str$. Positive numbers converted to strings using Format[$] lack a leading space, whereas those converted using Str$ retain a leading space.


Using Format[$] with numeric data

Format numeric data using one of the following methods:

•	Use the format keywords that have been predefined in Actuate Basic.

•	Create your own user-defined formats using standard characters or symbols that have special functional meanings when used in a Format[$] expression.

The following table shows the predefined numeric format keywords you can use, and Format[$] examples and their results.

Keyword and Description	Example/Result
"General number" Returns as is, without rounding or applying any formats.	Format(3434.2899, "General number") Returns 3434.2899
"Currency" Returns as a string with thousands separators and rounded to the nearest hundredth if needed. Two digits to the right of the decimal separator. Encloses negative numbers in parentheses. Currency format depends on settings in Control Panel.	Format(3434.2899, "Currency") Returns $3,434.29
"Fixed" Returns at least one digit to the left and two digits to the right of the decimal separator. Rounds to the nearest hundredth.	Format(3434.2899, "Fixed") Returns 3434.29 Format(.3122, "Fixed") Returns 0.31
"Standard" Returns with thousands separators and rounded to the nearest hundredth, if needed. At least two digits to the right of the decimal.	Format(3434.2899, "Standard") Returns 3,434.29
"Percent" Returns * 100 with a percent sign to the right. Two digits to the right of the decimal separator. Rounds to the nearest hundredth	Format(0.2899, "Percent") Returns 28.99% Format(0.28999, "Percent") Returns 29.00%
"Scientific" Returns in standard scientific notation, appropriately rounded.	Format(3434.2899, "Scientific") Returns 3.43E+03
"Yes/No" Returns No if zero, Yes otherwise	Format(3434.2899, "Yes/No") Returns Yes
"True/False" Returns False if zero, True otherwise	Format(3434.2899, "True/False") Returns True
"On/Off" Returns Off if zero, On otherwise	Format(3434.2899, "On/Off") Returns On


User-defined numeric formats

The following table shows the symbols or characters you can use to create your own user-defined formats, and the effect of each symbol on the resulting format string.

Symbol and Description	Examples/Results
"0" Zero-digit placeholder. If <exprs to format> has fewer digits than <format pattern>, the empty digits are filled with zeros. If <exprs to format> has more digits to the right of the decimal than <format pattern>, the result is rounded to the number of places in <format pattern>; if it has more digits to the left of the decimal, the extra digits are displayed without modification.	Format(3434.2899, "000.000") Returns 3434.290 Format(129.557, "0000.00") Returns 0129.56
"#" Null digit placeholder. If <exprs to format> has fewer digits than the format pattern, empty digits become Null, not filled with blanks.  Therefore, the resulting string can be shorter than the original format pattern.	Format(3434.2899, "#,###,##0.0") Returns 3,434.3 Format(3434.2899, "000###0.00") Returns 0003434.29
"%" Percentage placeholder. Multiplies <exprs to format> by 100 and appends a "%" character.	Format(.75, "##%") Returns 75% Format(.75, "0##.000%") Returns 075.000%
"." Decimal placeholder indicates where to place the decimal point.	Format(3434.28, "0.0") Returns 3434.3 Format(3434.28, "0.00") Returns 3434.28
"," Thousands separator.	Format(3434.2899, "#,##0.00") Returns 3,434.29
"E-" or "e-" Returns <exprs to format> in scientific notation. You must place a digit placeholder (0 or #) to the immediate left of the symbol.  Place an appropriate number of digit placeholders to the right of the symbol to display the exponent.  A minus sign is displayed if the result has a negative exponent.	Format(1500000, "0.0E-") Returns 1.5E6 Format(1500000, "#0.0E-") Returns 15.0E5
"E+" or "e+" Same as "E-". The plus sign causes the polarity of the exponent to display whether positive (+) or negative (-).	Format(1500000, "0.0E+") Returns 1.5E+6 Format(1500000, "#0.0e+") Returns 15.e+5
"-", "(", ")", [space], "$", "+" Literal characters that do not affect the format of the expression. [space] is Chr$(32).	Format$(5551212, "##0-0000") Returns 555-1212 Format$(1111111111, "(###) ##0-0000") Returns (111) 111-1111 Format$(150, "$##0") Returns $150 Format$(150,"+##0") Returns +150


Format[$] with Format sections

Unless <format pattern> specifies one of the predefined format keywords, a format expression for numbers can have up to four sections, separated by semicolons. If you use semicolons with nothing between them, the missing section is printed using the format of the positive value.

The following examples assume settings in the user's Control Panel are for the United States.

Use and description	Example/Result
1 section only <format pattern> applies to all values.	Format$(4.15, "$#,##0.00") Returns $4.15 Format$(-4.15, "$#,##0.00") Returns -$4.15
2 sections (1) Applies to positive values and zero. (2) Applies to negative values.	Format$(-7, "$#,##0.00;$(#,##0.00)") Returns $(7.00) Format$(-7, "$#,##0.00;\L\o\s\s: #,##0.00") Returns Loss: 7.00
3 sections (1) Applies to positive values. (2) Applies to negative values. (3) Applies to zero.	Format$(0, "#,###;(#,###);\Z\e\r\o!") Returns Zero!
4 sections (1) Applies to positive values. (2) Applies to negative values. (3) Applies to zero. (4) Applies to Null.	Format$(-25, "#;(#);\Z\e\r\o;\N\i\l") Returns (25) Format$(25-25, "#;(#);\Z\e\r\o;\N\i\l") Returns Zero Format$(Null, "#;(#);\Z\e\r\o;\N\i\l") Returns Nil


Using Format[$] for date data

Numbers can also be used to represent date and time information. You can format date and time serial numbers using either date and time formats or numeric formats because date/time serial numbers are stored as floating-point values.

To format date and time, use one of the following methods:

•	Use the format keywords that have been predefined in Actuate Basic.

•	Create your own user-defined formats using standard characters or symbols that have special functional meanings when used in a format expression.

The following table shows the predefined date and time format keywords you can use and the effects of each on the resulting format pattern.

Keyword and description	Example/Result
"General date" Returns a date or time.  For real numbers, if there is no fractional component, returns only a date.  If there is no integer component, returns only a time.	Format$(30267.83681, "General date") Returns 11/12/82 8:05:00 PM Format$(30267.0, "General date") Returns 11/12/82 Format$(0.83681, "General date") Returns 8:05:00 PM
"Long date" Returns a Long Date as defined in the user's Control Panel.	Format$(30267.83681, "Long date") Returns Friday, November 12, 1982
"Medium date" Returns a date with the month name abbreviated to 3 letters.	Format$(30267.83681, "Medium date") Returns 12-Nov-82
"Short date" Returns a Short Date as defined in the user's Control Panel.	Format$(30267.83681, "Short date") Returns 11-12-82
"Long time" Returns a Long Time as defined in the user's Control Panel. Includes hours, minutes, and seconds.	Format$(0.83681, "Long time") Returns 8:05:00 PM
"Medium time" Returns hours and minutes in 12-hour format, including the AM/PM designation.	Format$(0.83681, "Medium time") Returns 8:05 PM
"Short time" Returns hours and minutes in 24-hour format	Format$(0.83681, "Short time") Returns 20:05


User-Defined date formats

The following table shows the symbols or characters you can use to create your own user-defined date formats, and the effect of each symbol on the resulting format string.

In all cases, assume DateVar = CVDate("11/12/82") or DateVar = CVDate("9/9/82") (to demonstrate use of leading zeros), unless noted. The format of the results is the United States format. The order of month, day, and year depends on the date format defined in the user's Control Panel. Note that the symbol for minute is "n," not "m," which is the symbol for "month."

Symbol and description	Example/Result
"/", "-" Date separator.	Format$(DateVar, "mm/dd/yy") Returns 11/12/82 Format$(DateVar, "mm-dd-yy") Returns 09-09-82
"d" Day of the month without leading zero (1-31).	Format$(DateVar, "/d/") Returns /12/ Format$(DateVar, "/d/") Returns /9/
"dd" Day of the month with leading zero if needed (01-31).	Format$(DateVar, "/dd/") Returns /12/ Format$(DateVar, "/dd/") Returns /09/
"ddd" Three-letter abbreviation for day of the week.	Format$(DateVar, "ddd") Returns Fri
"dddd" Full name of day of the week.	Format$(DateVar, "dddd, mm/dd") Returns Friday, 11/12
"ddddd" Short Date string, as defined in the user's Control Panel.	Format$(DateVar, "ddddd") Returns 11/12/82
"dddddd" Long Date string, as defined in the user's Control Panel.	Format$(DateVar, "dddddd") Returns November 12, 1982
"w" Day of the week as a number (Sunday = 1, Saturday = 7).	Format$(DateVar, "w") Returns 6
"ww" Week of the year as a number (1-53).	Format$(DateVar, "ww") Returns 46
"m" Number of the month without leading zero (1-12).	Format$(DateVar, "m") Returns 11
"mm" Number of the month with leading zero (01-12).	Format$(DateVar, "mm") Returns 11 Format$(DateVar, "mm") Returns 09
"mmm" Three-letter abbreviation for month name.	Format$(DateVar, "mmm") Returns Nov
"mmmm" Full name of the month.	Format$(DateVar, "mmmm") Returns November
"q" Number of the quarter (1-4).	Format$(DateVar, "q") Returns 4 "Quarter" & Format$(DateVar, "q") Returns Quarter 4
"y" Number of the day of the year (1-366).	Format$(DateVar, "y") Returns 316 Val(Format$(DateVar, "y") + 19) Returns 335
"yy" Last two digits of the year (00-99).	Format$(DateVar, "yy") Returns 82
"yyyy" All four digits of the year (100-9999).	Format$(DateVar, "yyyy") Returns 1982
"c" Date variant as ddddd ttttt	Format$(DateVar, "c") Returns 11/12/82


Using Format[$] with time data

The fractional part of a number that represents a date represents a time of day on that date.

For example, the CVDate function converts numbers to date variants. CVDate(30632) is 11/12/83. No time of day is returned because 30632 has no fractional part. By contrast, CVDate(30632.83) returns 11/12/83 7:55:12 PM, because 30632.83 does have a fractional part, and the fractional part (.83) corresponds to about 7:55 PM (0.83 hours * 24 = 19.92 hours from midnight, or 7:55:12 PM).

The following table assumes DateVar = "11/12/82 20:05:07". Times returned by Format[$] are in 24-hour format unless you use one of the AM/PM format symbols. Note that the symbol for minute is "n," not "m," which is the symbol for month.

Symbol and description	Example/Result
":" Time separator.	Format$(DateVar, "hh:nn:ss") Returns 20:05:00
"h" Hour without leading zero (0-23).	Format$(DateVar, "h:nn AM/PM") Returns 8:05 PM
"hh" Hour with leading zero (00-23).	Format$(DateVar, "hh:nn AM/PM") Returns 08:05 PM
"n" Minute without leading zero (0-59).	Format$(DateVar, "h:n AM/PM") Returns 8:5 PM
"nn" Minute with leading zero (00-59).	Format$(DateVar, "hh:nn AM/PM") Returns 08:05 PM
"s" Second without leading zero (0-59).	Format$(DateVar, "h:n:s AM/PM") Returns 8:5:7 PM
"ss" Second with leading zero (00-59).	Format$(DateVar, "h:nn:ss AM/PM") Returns 8:05:07 PM
"AM/PM" or "am/pm" Designation AM/am for any hour before noon and PM/pm for any hour after. Case-sensitive.	Format$(DateVar, "hh:nn:ss am/pm") Returns 08:05:07 pm
"A/P" or "a/p" Designation A/a for any hour before noon and P/p for any hour after. Case-sensitive.	Format$(DateVar, "hh:nn:ss A/P") Returns 08:05:07 P
"AMPM" Uses formats set by "s1159" and "s2359" as defined in the user's Control Panel. Default is AM/PM.	Format$(DateVar, "hh:nn AMPM") Returns 08:05 PM
"ttttt" Uses format set by "sTime" as defined in the user's Control Panel. Default is h:nn:ss.	Format$(DateVar, "h:nn ttttt") Returns 8:05 PM


Using Format[$] with string data

You can also format strings with Format[$].

The following table shows the symbols or characters you can use to create your own user-defined formats, and the effect of each symbol on the resulting format string.

Symbol and description	Example/Result
"@", "&" Character placeholders. Returns a character, or a space if there is no character in the corresponding position.  Placeholders are filled from right to left unless <format pattern> uses a "!" character.	Format$("1111212111","(@@@) @@@-@@@@") Returns (111) 121-2111 Format$("6789999","(&&&) &&&-&&&&") Returns (   ) 678-9999
"<" Lowercase conversion. Converts <exprs to format> to lowercase.	Format$("Smith, John","<") Returns smith, john
">" Uppercase conversion. Converts <exprs to format> to uppercase.	Format$("Smith, John",">") Returns SMITH, JOHN
"!" Placeholder that specifies that placeholders are to be filled from left to right.	Format$("5551212","(&&&) &&&-&&&&") Returns (   ) 555-1212 Format$("5551212","(!!!) !!!-!!!!") Returns (555) 121-2


See also

CVDate function

DateValue function

Str, Str$ functions


For...Next statement

Example   See also

Repeats a block of instructions a specified number of times.

Syntax

For <counter variable> = <start> To <end> [ Step <step size> ]

[<statement block>]

[Exit For]

[<statement block>]

Next [<counter variable >]

<counter variable>

Numeric variable that keeps track of the number of times the set of statements between For and Next has been executed.

<start>

Numeric expression indicating the first number at which <counter variable> is to begin counting; the initial value of <counter variable>.

<end>

Numeric expression indicating the number at which <counter variable> is to stop counting; the final value of <counter variable>. As soon as <counter variable> stops execution, Actuate Basic skips everything between the For and Next keywords, and transfers control to the statement following Next.

Step

Keyword that specifies what number to add to <counter variable> every time after the loop finishes executing. The sum of <counter variable> and <step size> returns the next, new value for <counter variable>.

<step size>

The number the program adds to <counter variable>, at the end of every trip through the loop, in order to determine the next value of <counter variable>.

Default: 1	(start < end)
Default: -1	(start > end)

<statement block>

Any valid Actuate Basic statements.

Exit For

Keyword that causes Actuate Basic to terminate the loop immediately, and to transfer control to the statement following Next. Exit For statement can be placed anywhere in the loop any number of times, although only one will be executed.

Next

Keyword that defines the completion of a For...Next statement, and causes the program to add <step size> to <counter variable>.

Default: If you omit <counter variable> on the Next line, Actuate Basic adds the value of <step size> to the <counter variable> associated with the most recent For statement.

Description

•	First, Actuate Basic sets <counter variable> to <start>.

•	The following table summarizes what Actuate Basic does next, which depends upon the sign of <step size>.

<step size>	Loop executes when . . .	Stops execution when....
Positive or 0	<counter variable> <= <end>	<counter variable> > <end>
Negative	<counter variable> >= <end>	<counter variable> < <end>
•	If Actuate Basic executes the loop, it adds <step size> to <counter variable> at the line starting with Next.

•	Then Actuate Basic compares this new value of <counter variable> to <end>.

•	If the conditions described in the table are satisfied, Actuate Basic executes the loop again.

•	Otherwise, Actuate Basic skips everything between the For and Next keywords and transfers control to the statement immediately following Next.

Rule

If we say that a For...Next loop is "opened" by its For clause and "closed" by its corresponding Next clause, nested loops must be closed in the reverse order in which they were opened.

Example:

Loop 1

For I = 1 To 10

For J = 1 To 10

For K = 1 To 10

L = I + J + K

Next K

Next J

Next I

When you nest For...Next statements, you must use a different counter variable for each block. Traditionally, the letters I, J, K, etc., declared as Integers are used as counter variables.

Tips

•	To avoid confusion when you debug, do not change the value of <counter variable> from inside the loop.

•	To make your program more efficient, dimension <counter variable> as an Integer.

•	To evaluate a certain condition and then determine whether or not a loop continues, use Exit For within a conditional structure like If...Then...Else.

•	To ascertain or set the contents of a multidimensional array, use nested For...Next loops.


Example

The following example uses two nested loops to put seven lines of the uppercase alphabet into a message box.

Function OnLButtonDblClk()

Dim I As Integer, Msg As String, NL As String, Rep As Integer

' Define new line

NL = Chr$(10)

' Perform seven repetitions

For Rep = 7 To 1 Step -1

' Convert alpha to numeric values

For I = Asc("A") To Asc("Z")

' Convert back, append letters to string

Msg = Msg & Chr$(I)

Next I

' Add newline after each repetition

Msg = Msg & NL

Next Rep

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Do...Loop statement

Exit statement

While...Wend statement


FreeFile function

Example   See also

Returns the next unused system file number.

Syntax

FreeFile

Example:

In the following statements, the return value of FreeFile is assigned to the variable FileNum%, then FileNum is used to open the file TEST.DAT.

FileNum% = FreeFile

Open "TEST.DAT" for Output As FileNum%

Return value

Integer

Whenever you open a file, you must supply a number by which to reference it throughout the program. This number must not already be in use by another currently open file. FreeFile eliminates the need for you to keep track of which file numbers are currently in use by finding the next available number.

Tip

The number that FreeFile returns does not change until you actually open a file with it. So to be sure FreeFile is always current, immediately open a file with the number it gives you, instead of waiting until later to do so.


Example

In the following example, a test file is created and opened to determine an unused file number.

Function OnLButtonDblClk()

Dim NL As String, FileNumber As Integer, Msg As String

' Define newline

NL = Chr$(10)

' Open a file

Open "TEST1.FIL" For Output As #1

' Get unused file number

FileNumber = FreeFile

' Create a test file

Open "TEST2.FIL" For Output As FileNumber

' Close all files

Close

Msg = "The file number FreeFile returned was:  "

Msg = Msg & FileNumber & "." & NL & NL

Msg = Msg & "Choose OK to delete the  test files."

MsgBox Msg

 ' Delete files from disk

Kill "TEST1.FIL"

Kill "TEST2.FIL"

End Function

For information about using the code examples, see Using the code examples.


See also

Open statement


Function...End Function statement

Example   See also

Declares and defines the name, code, and arguments that constitute an Actuate Basic function, and returns a value to the calling expression or statement.

Syntax

[Static] Function <name of function> [(<list of arguments>)] [As <data type>]

[<statements>]

[Exit Function]

[<statements>]

<name of function> = <return value>

End Function

Static

Keyword that instructs Actuate Basic to preserve the values of the procedure's local variables between calls.

Rules:

•	You cannot use Static to affect variables declared outside the procedure.

•	You should avoid using Static in recursive procedures.

<name of function>

The name you assign to the procedure.

Rules for <name of function>:

•	Subject to the same constraints as variable names, as well as to the following additional constraints:

•	Can include a type declaration character.

•	Cannot be the same as any other name recognized at the global or module level, such as that of:

•	-	A procedure in a declared dynamic-link library (DLL).

•	-	A variable.

•	-	A constant.

•	Can be overloaded. That is, you can define another function and/or procedure that has the same name, as long as the respective arguments are unique. For example, the following are BOTH permissible in the same program.

Sub Potato(intTomato As Integer)

..

End Sub

Sub Potato(intTomato As Double)

..

End Sub

<list of arguments>

The variable name or names that the function uses internally to store and manipulate the values (arguments) that you pass to it from the calling statement.

Each of the <variable name> components of the <list of arguments> corresponds to a value or variable that is in the same relative position in the calling statement. It does not matter what you call the variable that is passed to the function; the function will process the value it receives as an argument. The <statements> in the procedure process arguments it receives to produce the single value that is returned to the calling procedure.

In the following example, the function Square ( ) expects to be supplied with a single argument (a numeric expression), which it squares.

Function Square(X)

Square = X ^ 2

End Function

The following statements will pass the value 4 to the function Square ( ) and receive back the value 16 after Square ( ) has completed. The statement will then continue; it will multiply the value it received from the function Square ( ) times 2 and print the resulting value.

MyNumber = 4

Print #1, Square(MyNumber) * 2

Here are the steps in the process:

1	First, the value 4 is assigned to the variable MyNumber.

2	The value of MyNumber is passed to the function Square ( ). Square ( ) assigns the value it receives from the calling statement to the variable X.

3	Square ( ) processes X and assigns the resulting value to the name of the function itself--Square--and returns control to the statement that called it.

4	The calling statement continues processing the new value of MyNumber (16); it multiplies it by 2, and prints the result (32).

<statements>

One or more valid Actuate Basic statements. These statements constitute the body of the function procedure.

<return value>

The value the function returns to the calling statement after the function has completed. Usually, <return value> is a variable that contains the final result of all the changes the argument or arguments underwent in the course of the execution of the <statements>.

Exit Function

Keyword that signals Actuate Basic to terminate the function procedure and transfer control to the statement following the one that called the procedure. You can use multiple Exit Function statements, anywhere in a function procedure, but only one is executed.

<list of arguments> has the following syntax:

[ByVal] <variable name> [As <data type>] [,[ByVal] <variable name>
[As <data type>]...

ByVal

Keyword that instructs Actuate Basic to pass the argument to the procedure by value rather than by reference, so that whatever change the function makes to the argument variable has no affect on its original value in the calling procedure.

Rule for ByVal: Cannot be used with a variable of user-defined type, object type, or with an array variable.

<variable name>

Name of the variable to pass as an argument. If the function changes the value of <variable name> internally, then it also changes its value externally.

Rules for <variable name>:

•	You must use ByVal if you do not want the function's changes to an argument variable to affect the variable's value in the calling statement. Example:

Function SquareRoot (ByVal UserNum)

•	For array variables, use the parentheses but omit the number of dimensions. Example:

Function SalesTax MyArray( )

•	If <variable name> is undeclared within the function but has the same name as another procedure, a Global or module-level constant or variable, or an object, Actuate Basic assumes your function refers to that external name. This can cause name conflicts. To avoid such conflicts, explicitly declare each <variable name> within the function.

As <data type>

Clause that declares the data type of <variable name>. You can also specify the data type of <returned value> by appending this clause after the <list of arguments>.

Rule for As <data type>: <data type> can specify any valid Actuate Basic or user-defined data type except fixed-length String.

Examples:

Function SalesTax(Customer As String, Amount As Currency)

Function SalesTax(ByVal Customer As String, Amount)

Description

Like a Sub statement, a Function can take arguments, execute a series of statements, and change the values of its arguments. However, unlike a Sub statement, a Function can also return a value directly and can be used in an expression.

You can use the same name for two or more different procedures, as long as you make sure the procedures take a different number of arguments, or that the arguments are of different data types. For example, you can write two different square root functions - one that operates on integers, and another that operates on doubles. Their respective first lines might look like the following:

Function SquareRoot(intParam As Integer) As Integer

Function SquareRoot(dblParam As Double) As Double

Actuate Basic will know which procedure you mean by the type of value you pass when you call the procedure. For instance, if you write a call to SquareRoot(5), the compiler will choose the first SquareRoot function. But if you call SquareRoot(5.1234567), or SquareRoot(5.000), it will execute the second one.

Rules

•	You cannot define a Function statement from within another Function statement.

•	You cannot use GoTo to enter or exit a Function statement.

Tips

•	Functions can be recursive.

•	To avoid possible name conflicts between <variable name> and the names of other variables, constants, procedures, or objects, explicitly declare all variables within the function with Dim, ReDim, or Static. That way, you can feel free to use a common variable name like SaleDate within a function procedure, even if there happens to be a global variable named SaleDate. Name conflicts can arise only when you use a variable in a procedure that you did not explicitly declare within it.

•	To evaluate a condition and then determine whether or not the function procedure should continue, use Exit Function within a conditional structure like If...Then...Else.

•	To guard against the wrong data type being passed to or returned from a function, use As <data type> clauses.


Example

The following example prompts the user to type a number, then calls a user-defined function that returns the number's square root. The function SquareRoot should be typed after the End Function of the procedure or saved in your Actuate code module (.BAS file).

Function OnLButtonDblClk()

Dim Msg As String, NumRoot

Dim UserNum As Double

UserNum = InputBox("Please type a number.")

' Call the SquareRoot function here to process UserNum

NumRoot = SquareRoot(UserNum)

' NumRoot has now been set to the square root of UserNum

Msg = "The square root of " & UserNum

Select Case NumRoot

Case 0: 	Msg = Msg & " is zero."

Case -1: 	Msg = Msg & " is an imaginary number."

Case Else: 	Msg = Msg & " is " & NumRoot

End Select

MsgBox Msg

End Function

'

' This function finds the square root of a number. It takes one input argument

' X (data type Double) and returns a value that is also data type Double.

'

Function SquareRoot (X As Double) As Double

' Sgn returns 1 if a number is positive, -1 if it's negative, and 0 if it's zero

' Important here since we only want to operate on a number greater

' than zero

' Evaluate sign of argument

Select Case Sgn(X)

Case 1

SquareRoot = Sqr(X)

' OK if positive, so exit

Exit Function

Case 0

SquareRoot = 0

Case -1

SquareRoot = -1

End Select

End Function

For information about using the code examples, see Using the code examples.


See also

Dim statement

Static statement

Sub...End Sub statement


FV function

Example   See also

Returns the future value of an annuity based on periodic, constant payments, and on an unvarying interest rate.

Syntax

FV(<rate per period>,<number pay periods>,<each pmt>,<present value>, <when due>)

<rate per period>

Numeric expression that specifies the interest rate that accrues per period.

Rule for <rate per period>: Must be given in the same units of measure as <number pay periods>. For instance, if <number pay periods> is expressed in months, then <rate per period> must be expressed as a monthly rate.

<number pay periods>

Numeric expression that specifies the total number of payment periods in the annuity.

Rule for <number pay periods>: Must be given in the same units of measure as <rate per period>. For instance, if <rate per period> is expressed as a monthly rate, then <number pay periods> must be expressed in months.

<each pmt>

Numeric expression that specifies the amount of each payment.

Rule for <each pmt>: Must be given in the same units of measure as <rate per period>. For instance, if <rate per period> is expressed in months, then <each pmt> must be expressed as a monthly payment.

<present value>

Numeric expression that specifies the value today of a future payment, or stream of payments.

Example for <present value>: If you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you end up with about $100. The present value of $100 is approximately $23.94.

<when due>

Numeric expression that specifies whether each payment is made at the beginning (1), or at the end (0) of each period.

Default: 0

Rule for <when due>: Must be 0 or 1

Examples:

The following example assumes you deposit $10,000 in a savings account for your daughter when she is born. If the account pays 5.7% compounded daily, how much will she have for college in 18 years? The answer ($27,896.60) is assigned to the variable TotalValue.

TotalValue = FV(0.057/365, 18*365, 0, -10000, 1)

The following example is almost the same as the previous one. In this one, however, assume that the interest is compounded monthly instead of daily, and that you have decided to make an additional monthly deposit of $55 into the account. The future value assigned to TotalValue in this case is $48,575.82.

TotalValue = FV(0.057/12, 18*12, -55, -10000, 1)

Return value

Double

An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment (such as a monthly savings plan) or a loan (such as a home mortgage). The future value of an annuity is the cash balance you want after you have made your final payment.

Examples:

•	You set up a savings plan with a goal of having $75,000 in 18 years to pay for your child's education. For this plan, the future value is $75,000.

•	You take out a loan for $11,000. The future value is $0.00, as it is for any typical loan.

Rules

•	<rate per period>, <number pay periods>, and <each pmt> must all be expressed in terms of the same units (weekly/weeks, monthly/months, yearly/years, and so on).

•	You must express cash paid out (such as deposits to savings) using negative numbers, and cash received (such as dividend checks) using positive numbers.


Example

The following example prompts the user to supply an amount to save or invest each month, the annual percentage rate (APR) of the interest, the total number of payments, and when during the month payments will be made. Then it tells the user what the future value of such a savings plan or investment will be.

To use this example, paste the first portion at or near the beginning of your Actuate Basic source code (.BAS) file.

Declare

Global Const ENDPERIOD = 0

Global Const BEGINPERIOD = 1

End Declare

'

Function OnLButtonDblClk()

Dim EachPmt As Double, APR As Double

Dim TotalPmts As Single, PayWhen As Integer

Dim PresentVal As Double, FutureVal As Double

Dim Msg as String, Fmt As String

' Specify money format

Fmt = "$###,###,##0.00"

' Get user input

Msg = 	"How much will you save each month?"

EachPmt = InputBox(Msg)

Msg = "What is the annual percentage rate for the interest?"

APR = InputBox(Msg)

' Ensure proper form as %

If APR > 1 Then

APR = APR / 100

End If

Msg = "For how many months will you save?"

TotalPmts = InputBox(Msg)

Msg = "Will you make payments at month's end?"

PayWhen = MsgBox(Msg, MB_YESNO)

If PayWhen = IDNO Then

PayWhen = BEGINPERIOD

Else

PayWhen = ENDPERIOD

End If

Msg = "What amount is in this savings account now?"

PresentVal = InputBox(Msg)

' Now do the real work

FutureVal = FV(APR / 12, TotalPmts, -EachPmt, -PresentVal, PayWhen)

' Format the resulting information for the user

Msg = "Starting with " & Format(PresentVal, Fmt) & " "

Msg = Msg & " and saving " & Format(EachPmt, Fmt) & " every month at"

Msg = Msg & " an interest rate of " & Format(APR, "##.0%")

Msg = Msg & " for a period of " & TotalPmts

Msg = Msg & " months will give you " & Format(FutureVal, Fmt) & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

IPmt function

NPer function

Pmt function

PPmt function

PV function

Rate function


Get statement

Example   See also

Reads data from a disk file into a variable.

Syntax

Get [#] <open file number>, [<record number>], <receiving variable>

<open file number>

Numeric expression that is the number you assigned as a descriptor for the target file when you Opened it.

<record number>

Numeric expression between 1 and 2,147,483,647.

•	For files opened in Random mode, <record number> is the number of the record to be read.

•	For files opened in Binary mode, it is the byte position at which reading starts, where the first byte in a file is at position 1, the second byte at position 2, and so on.

Default: The next record or byte--that is, the one following the last Get or Put statement, or the one pointed to by the last Seek function.

Rule for <record number>: If you omit <record number> you must still include the delimiting commas that would have been on either side of it had you included it.

<receiving variable>

String expression that specifies the variable that is to receive input from the open file.

Rules for <receiving variable>:

•	Cannot be an object variable.

•	Cannot be an array variable that refers to an entire array, although you can use a variable that denotes a single element of an array.

Description

The behavior of Get varies depending upon the mode in which the file was opened.

For Files Opened in Random mode

If the length of the data you read is less than the length specified in the Len clause of the Open statement, the next Get skips the data you did not read and reads subsequent records starting at the (Len-specified) record-length boundary.

Example:

The first Get stores bytes 1-4 of the disk file "MYFILE.TXT" into the variable HoldingVar1. The second Get skips to the record-length boundary (20) and starts counting from there, which means it stores bytes 21-25 into HoldingVar2. The intervening bytes (5-20) are ignored.

Dim HoldingVar1 As String

Dim HoldingVar2 As String

HoldingVar1 = "1234"

HoldingVar2 = "1234"

Open "MYFILE.TXT" for Random As #1 Len = 20

Get #1, , HoldingVar1

Get #1, , HoldingVar2

The following table summarizes how Get behaves depending on the data type of <receiving variable>. "Open" here refers to the particular statement that opened the file in question.

<receiving variable>	Get reads, in order	Rules
Variable-length string	1 2-byte descriptor containing string length 2 Data that goes into <receiving variable>	Record length specified in the Len clause of Open must be at least 2 bytes greater than the actual length of the string.
Numeric Variant  (Variant Types 0-7)	1 2-byte descriptor identifying VarType of the Variant 2 the data that goes into <receiving variable>	Len clause length must be at least 2 bytes greater than the actual number of bytes required to store the variable.
String Variant (Variant Type 8)	1 2-byte VarType descriptor 2 2 bytes indicating the string length 3 Data that goes into <receiving variable>	Len clause length must be at least 4 bytes greater than the actual length of the string.
Any other type of variable	1 Data that goes into <receiving variable>	Len clause length must be greater than or equal to the length of the data.
User-defined type	1 As though each element were being read individually	Len clause length must be greater than or equal to the sum of all bytes for the individual elements
For Files Opened in Binary mode

All the Random descriptions and rules above apply except that the Len clause in the Open statement has no effect.

Example:

The first statement stores the first 4 bytes of the disk file "MYFILE.TXT" into the variable HoldingVar1. The second stores the next 5 bytes into HoldingVar2. No data is ignored.

Dim HoldingVar1 As String

Dim HoldingVar2 As String

Open "MYFILE.TXT" for Binary As #1

Get #1, , HoldingVar1

Get #1, , HoldingVar2

For variable-length strings that are not elements of user-defined types, Get does not expect a 2-byte descriptor to tell it how many bytes to read; it reads the number of bytes equal to the number of characters already in the string.

Example:

The following statements reads 12 bytes from file #1:

VariLen$ = String$(12, "*")

Get #1, , VariLen$

Tip

To avoid corrupting or misreading data, be sure your record lengths and/or variable lengths match the lengths of the data you want to read or write.


Example

The following example prompts the user to type three customer names. It writes each name to a test file and then reads the names back.

Function OnLButtonDblClk()

Dim CustName As String

Dim I As Integer, Max As Integer, Msg As String

' Create a sample data file

Open "TESTFILE.DAT" For Random As #1 Len = 50

' Ask user to type a few records

For I = 1 to 3

CustName = InputBox("Please type a customer name: ")

' Put record into file on disk

Put #1, I, CustName

Next I

Close #1

' Close the file we've written into and open again for reading

Open "TESTFILE.DAT" For Random As #1 Len = 50

' Calc total # of records

Max = LOF(1) / 50

Max = Max + 1

' Read file backwards

For I = Max To 1 Step -1

' Seek statement used

Seek #1, I

' Get record at that position

Get #1, , CustName

Msg = "Record #" & (Seek2(1) - 1) & " contains: "

Msg = Msg & CustName

MsgBox Msg

Next I

' Close test file

Close #1

Msg = "Choose OK to remove the test file."

MsgBox Msg

' Delete file from disk

Kill "TESTFILE.DAT"

End Function

For information about using the code examples, see Using the code examples.


See also

Open statement

Put statement

Seek statement

Type...End Type statement


GetAFCROXVersion function

Example   See also

Returns either the integer or the decimal component of the version number of the AFC library (afcnnnnn.rox).

Syntax

GetAFCROXVersion(<numpart>)

<numpart>

Number or numeric expression that tells GetAFCROXVersion whether you want to know the integer part of the version number, or the decimal part.

Rule: Must be either 0 or 1

Return value

Integer

If <numpart> is 0, GetAFCROXVersion returns the integer (major) component of the version number.

If <numpart> is 1, GetAFCROXVersion returns the decimal (minor) component of the version number.


Example

The code in the example determines both parts of the version number of the AFC library, and puts the parts together, interpolating the decimal point where it belongs.

Dim AFCMajor As Integer, AFCMinor As Integer, AFCTotal as String

AFCMajor = GetAFCROXVersion(0)

AFCMinor = GetAFCROXVersion(1)

'Now put the two parts together and prepend some identifying text:

AFCTotal = "AFC Version: " & (AFCMajor) & "." & (AFCMinor)

For information about using the code examples, see Using the code examples.


See also

GetAppContext function

GetFactoryVersion function

GetOSUserName function

GetROXVersion function

GetServerName function

GetServerUserName function


GetAppContext function

Example   See also

Indicates which Actuate application is currently running.

Syntax

GetAppContext

Return value

AppContext

How you interpret the GetAppContext's return value depends upon whether at runtime GetAppContext is called from a client or a server machine.

On a client, GetAppContext returns the context of the Actuate application being used -- for example the Administrator Desktop, End User Desktop, or the Developer Workbench.

On a server, GetAppContext returns the context of Server, and not the context of the Administrator, End User Desktop, or Developer Workbench.

The following table maps the return value from GetAppContext to the corresponding Actuate application:

GetAppContext value	Application
ServerContext	Server
LRXContext	Live Report Extension (Plug-in)
ViewerContext	Viewer
ADTContext	Administrator Desktop (ADT)
EUDTContext	End User Desktop (EUDT)
DWBContext	Developer Workbench (DWB)


Example

The following code illustrates how you might use GetAppContext to determine which Actuate application is running at the time you call the function.

Dim ApplicationContext As AppContext, MyValue As String

MyValue = "Application Context = "

ApplicationContext =  GetAppContext

Select Case ApplicationContext

Case ServerContext

MyValue = MyValue & "Server"

Case LRXContext

MyValue = MyValue & "Live Report Extension (Plugin)"

Case ViewerContext

MyValue = MyValue & "Viewer"

Case ADTContext

MyValue = MyValue & "Administrator Desktop"

Case EUDTContext

MyValue = MyValue & "End User Desktop"

Case DWBContext

MyValue = MyValue & "Developer WorkBench"

End Select

For information about using the code examples, see Using the code examples.


See also

GetAFCROXVersion function

GetFactoryVersion function

GetOSUserName function

GetROXVersion function

GetServerName function

GetServerUserName function


GetAttr function

Example   See also

Determines the attributes of a file, directory, or volume.

Syntax

GetAttr(<file dir or vol name>)

<file dir or vol name>

String expression that specifies the file, directory, or volume for which you wish to determine what attributes are set.

Default path: Current drive and directory.

Rules:

•	Must refer to a valid file, directory, or volume.

•	Reference must be unambiguous.

<file dir or vol name> can optionally specify a full path, in which case it has the following syntax:

[<drive:>][ \ ]<directory>[\<directory>]...(Windows)

[ /]<directory>[/<directory>]...(UNIX)

<drive:>

Character, followed by a colon, that specifies the drive (Windows only).

<directory>

String expression that specifies the name of a directory or subdirectory.

Example:

Assuming TESTFILE.DAT has both the system and read-only attributes set, the following statement assigns the value 5 (4 + 1) to the variable ATTRIBS.

ATTRIBS = GetAttr("TESTFILE.DAT")

Return value

Integer

•	The operating system assigns one or more attributes to each file, directory, and volume. These attributes indicate whether the item is a normal, read-only, hidden, or system file; a volume label; a directory; whether it has been modified since the last backup; or some combination of these.

•	If the file has multiple attributes, the return value will be the bit-wise AND of all the values that apply. For example, a return value of 3 indicates a file is both read-only and hidden (1 + 2).

•	The following table shows certain Constant names that are defined in HEADER.BAS, and their corresponding return values and attributes. The return value of GetAttr is the sum of one or more return values. The return values not supported under UNIX will be 0.

Return value	Constant name	File attribute	Operating system
0	ATTR_NORMAL	Normal	Windows, UNIX
1	ATTR_READONLY	Read-only	Windows, UNIX
2 or 0	ATTR_HIDDEN	Hidden	Windows
4 or 0	ATTR_SYSTEM	System file	Windows
8 or 0	ATTR_VOLUME	Volume label	Windows
16	ATTR_DIRECTORY	Directory label	Windows, UNIX
32 or 0	ATTR_ARCHIVE	Changed since last backup	Windows
Tip

To determine--without having to do any arithmetic--whether a file has a particular, single attribute, use the BAnd operator to perform a bitwise test. If this statement evaluates to nonzero you know that, whatever other attributes it has, the file is Read-only.

GetAttr("TESTFILE.DAT") BAnd ATTR_READONLY


Example

In the following Windows example, Actuate Basic prompts the user to type a file name, then displays a message indicating the attributes of the given file.

Function OnLButtonDblClk()

Dim Attr As Integer, FName As String, Msg As String

On Error Goto ErrorHandler

' Get a file name from the user

FName = InputBox("Please type the name of a file.")

' Determine the file's attributes

Attr = GetAttr(FName)

MsgBox "The value returned by GetAttr is:  " & Attr

' Disregard the Archive attribute

If Attr > 7 And Attr <> 16 Then

If Attr BAnd ATTR_ARCHIVE Then

Attr = Attr BAnd BNot ATTR_ARCHIVE

Else

Attr = Attr BOr ATTR_ARCHIVE

End If

End If

' Correlate some attribute codes and code sums to messages

Select Case Attr

Case ATTR_NORMAL

Msg = "Normal"

Case ATTR_READONLY

Msg = "Read-only"

Case ATTR_HIDDEN

Msg = "Hidden"

Case ATTR_HIDDEN + ATTR_READONLY

Msg = "Hidden and Read-only"

Case ATTR_SYSTEM

Msg = "System"

Case ATTR_READONLY + ATTR_SYSTEM

Msg = "Read-only and System"

Case ATTR_HIDDEN + ATTR_SYSTEM

Msg = "Hidden and System"

Case ATTR_READONLY + ATTR_HIDDEN + ATTR_SYSTEM

Msg = "Read-only, Hidden, and System"

Case ATTR_DIRECTORY

Msg = "Directory"

End Select

MsgBox UCase$(FName) & " is a " & Msg & " file."

Exit Function

ErrorHandler:

Msg = "Sorry, an error occurred. Please check the name or path "

Msg = Msg & "of the file and try again."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

FileDateTime function

FileLen function

SetAttr statement


GetClassID function

Example   See also

Returns the identification number that Actuate assigns automatically to all classes. Objects of the same class have the same ID number.

Syntax

GetClassID(<object reference>)

<object reference>

The name of the variable that refers to the object for which you want the ID.

Return value

Integer that is the class ID.

Tips

•	Use GetClassID when you want to check if an object is of a given type without the overhead of a string compare.

•	To find out an object's class, use GetClassName.

•	To find out if an object is an instance of a specified class or is an instance of a subclass of a specified class, use IsKindOf.


Example

The following procedure displays the Class Name and Class ID of the current component, creates two new label components, and displays the Class Name and Class ID of each of the new components.

' Create a new label in the Design Editor and override its

' OnLButtonDblClk method.  Paste the following code at

' the point where it says: Insert your code here.

Dim ClassIDVar, ClassNameVar

Dim MyLabel1 As AcLabelControl, MyLabel2 As AcLabelControl

Dim NL As String, Msg As String

' Set newline

NL = Chr$(10)

ClassIDVar = GetClassID(Me)

ClassNameVar = GetClassName(Me)

Msg = "My Class ID is: " & ClassIDVar & NL

Msg = Msg & "My Class Name is: " & ClassNameVar

MsgBox Msg

Set MyLabel1 = New AcLabelControl

Set MyLabel2 = New AcLabelControl

Msg = "The Class Name for MyLabel1 is: "

Msg = Msg & GetClassName(MyLabel1) & NL

Msg = Msg & "Its Class ID is: "

Msg = Msg & GetClassID(MyLabel1) & NL & NL

Msg = Msg & "The Class Name for MyLabel2 is: "

Msg = Msg & GetClassName(MyLabel2) & NL

Msg = Msg & "Its Class ID is: " & GetClassID(MyLabel2)

MsgBox Msg

For information about using the code examples, see Using the code examples.


See also

GetClassName function

IsKindOf function


GetClassName function

Example   See also

Returns the name of the object's class.

Syntax

GetClassName(<object reference>)

< object reference >

The name of the variable that refers to the object for which you want the class name.

Return value

String

The name of the class. If the class is nested, the name is the fully qualified name, for example, MyReport::MyFrame::MyControl.

Tips

•	Use GetClassName to test for a specific class before performing an action.

•	To find out if an object is an instance of a specified class or is an instance of a subclass of a specified class, use IsKindOf.


Example

The following procedure displays the Class Name and Class ID of the current component, creates two new label components, and displays the Class Name and Class ID of each of the new components.

' Create a new label in the Design Editor and override its

' OnLButtonDblClk method.  Paste the following code at

' the point where it says: Insert your code here.

Dim ClassIDVar, ClassNameVar

Dim MyLabel1 As AcLabelControl, MyLabel2 As AcLabelControl

Dim NL As String, Msg As String

' Set newline

NL = Chr$(10)

ClassIDVar = GetClassID(Me)

ClassNameVar = GetClassName(Me)

Msg = "My Class ID is: " & ClassIDVar & NL

Msg = Msg & "My Class Name is: " & ClassNameVar

MsgBox Msg

Set MyLabel1 = New AcLabelControl

Set MyLabel2 = New AcLabelControl

Msg = "The Class Name for MyLabel1 is: "

Msg = Msg & GetClassName(MyLabel1) & NL

Msg = Msg & "Its Class ID is: "

Msg = Msg & GetClassID(MyLabel1) & NL & NL

Msg = Msg & "The Class Name for MyLabel2 is: "

Msg = Msg & GetClassName(MyLabel2) & NL

Msg = Msg & "Its Class ID is: " & GetClassID(MyLabel2)

MsgBox Msg

For information about using the code examples, see Using the code examples.


See also

GetClassID function

IsKindOf function


GetClipboardText function

Example   See also

Returns a text string from the operating environment Clipboard.

Syntax

GetClipboardText(<format>)

<format>

One of the following Clipboard formats recognized by Actuate Basic.

Symbolic constant	Value	Clipboard format
CF_LINK	&HBF00	DDE conversation information
CF_TEXT	1	Text
If <format> is omitted, CF_TEXT is assumed.

Return value

String

If there is no text string on the Clipboard that matches the expected format, a zero-length string ("") is returned.


Example

The following example places the current date on the Clipboard and then displays the contents of the Clipboard.

Function OnLButtonDblClk ( )

Dim Msg As String, UserContent, DoMore

On Error Resume Next

Msg = "The Clipboard currently contains:  " & GetClipboardText()

MsgBox Msg

Msg = "Choose OK to load today's date onto the Clipboard."

MsgBox Msg

ClearClipboard()

SetClipboardText(Format$(Date, "dddd, mm/dd/yyyy"))

Msg = "Today's date is on the Clipboard.  Choose OK to get the "

Msg = Msg & "date back from the Clipboard and put it in a message."

MsgBox Msg

Msg = GetClipboardText()

MsgBox "The Clipboard currently contains:  " & Msg

DoMore = MsgBox("Put something else on the clipboard?", MB_YESNO)

If DoMore = IDNO Then

MsgBox "The date is still on the Clipboard."

Else

UserContent = InputBox("Put what?")

SetClipboardText(UserContent)

End If

MsgBox "The Clipboard currently contains:  " & GetClipboardText()

End Function

For information about using the code examples, see Using the code examples.


See also

ClearClipboard function

SetClipboardText function


GetDisplayHeight function (Windows only)

Returns the height, in twips, that you will require in order to display a given text string without truncating it.

Can be used to dynamically adjust the height of a container when you have a large amount of text that might otherwise overflow.

Syntax

GetDisplayHeight (<context>, <width>, <theText>, <theFont>, <format>)

<context>

String expression. Specifies whether to return the height either for your display, or for your default printer.

Rule:  Must be either "display" or "default_printer".

<width>

Integer expression. Specifies the width in twips of the control that will display the text. <width> is used to determine the height of the control to display all the text for this control. p-GetDisplayHeight assumes that at least one character fits on each line.

Rule:  Must be a positive integer.

<theText>

String expression. The text whose height you want to determine.

Rule:  Must not be empty.

<theFont>

AcFont data type.

<format>

AcTextPlacement data type.

Return value

Integer

•	The height of the formatted text in twips for the specified device.

•	When negative, an error has occurred. The following table shows the meaning of the error codes

	Error code	Description of errors
	-1	Not running Windows
	-2	Wrong number of parameters passed
	-3	<context> is not a string, or represents a nonsupported context
	-4	<width> is not a positive integer
	-5	<theText> is not a string, or it is an empty string
	-6	<AcFont.FaceName> is an empty string
	-7	<AcFont.Size> is not a positive integer
	-8	<AcFont.Bold> internal error
	-9	<AcFont.Italic> internal error
	-10	<AcFont.Underline> internal error
	-11	<AcFont.StrikeThrough> internal error
	-12	<AcTextPlacement.MultiLine> internal error
	-13	<AcTextPlacement.WordWrap> is not 0, 2, or 3
	-14	Default printer is selected, but no default printer has been set
	-15	Implementation failed to get information on the device
	-16	Operation caused an exception
Description

Different devices display or print fonts differently. These differences are small, but they can sometimes become significant. This means, for example, that a visual box filled with text may look good on your screen, but bad on your printed report, because some of the text it encloses may be truncated by the target device, in this case, your printer.

GetDisplayHeight lets you calculate exactly how tall your formatted text will be when a given display or printer device renders it.

Rule

GetDisplayHeight does not work under UNIX.

Tip

Because GetDisplayHeight works only under Windows, be sure to write error-handling code that checks whether the function returns -1 when the report is run in a non-Windows environment.

When GetDisplayHeight does return -1, the report is not running under Windows, it is probably running under UNIX, and you will have to change your code accordingly.


GetFactoryVersion function

Example   See also

Returns either the integer or the decimal component of the version number of the Factory the ROX is using.

Syntax

GetFactoryVersion(<numpart>)

<numpart>

Number or numeric expression that tells GetFactoryVersion whether you want to know the integer part of the Factory's version number, or the decimal part.

Rule: Must be either 0 or 1

Return value

Integer

If <numpart> is 0, GetFactoryVersion returns the integer (major) component of the Factory's version number.

If <numpart> is 1, GetFactoryVersion returns the decimal (minor) component of the Factory's version number.


Example

The code in this example determines both parts of the version number of the Factory your ROX is using, and it puts the parts together, interpolating the decimal point where it belongs.

Dim FactVerMajor As Integer, FactVerMinor As Integer

Dim FactVerTotal As String

FactVerMajor = GetFactoryVersion(0)

FactVerMinor = GetFactoryVersion(1)

'Now put the two parts together and prepend some identifying text:

FactVerTotal = "Factory Version: " & (FactVerMajor) & "." & (FactVerMinor)

For information about using the code examples, see Using the code examples.


See also

GetAppContext function

GetAFCROXVersion function

GetOSUserName function

GetROXVersion function

GetServerName function

GetServerUserName function


GetHeadline function

See also

Returns the headline associated with the completed request for a report.

Syntax

GetHeadline

Return value

String

The current text of the headline.

Description

Headlines are associated with the completed request for a report, and are visible only in the Web Agent when viewing channels.

By default, the headline is set to the value of the Headline parameter that appears in the Output Options section of the Requester. Use GetHeadline to programmatically determine the headline text.

Rules

•	GetHeadline and SetHeadline do not work in the Viewer.

•	To change the headline, do not change the Headline parameter itself. Instead, use SetHeadline.


See also

SetHeadline statement


GetOSUserName function

Example   See also

Returns the operating system (login) name of the user. For server, returns the login name of the account running the server.

Syntax

GetOSUserName

Return value

String

The login name of the user, or the login name of the account running the server.

Rule

You cannot use GetOSUserName in a 16-bit environment.


Example

The following code gets the login name of the user and puts it in a variable along with some identifying text.

Dim OSUserName As String

OSUserName = "OS User Name is: " & (GetOSUserName)

For information about using the code examples, see Using the code examples.


See also

GetAppContext function

GetAFCROXVersion function

GetFactoryVersion function

GetROXVersion function

GetServerName function

GetServerUserName function


GetROXVersion function

Example   See also

Returns either the integer or the decimal component of the version number of the report ROX file.

Syntax

GetROXVersion(<numpart>)

<numpart>

Number or numeric expression that tells GetROXVersion whether you want to know the integer part of the version number, or the decimal part.

Rule: Must be either 0 or 1

Return value

Integer

If <numpart> is 0, GetROXVersion returns the integer (major) component of the version number.

If <numpart> is 1, GetROXVersion returns the decimal (minor) component of the version number.


Example

The code determines both parts of the version number of the ROX, and puts the parts together, interpolating the decimal point where it belongs.

Dim ROXMajor As Integer, ROXMinor As Integer, ROXTotal As Srting

ROXMajor = GetROXVersion(0)

ROXMinor = GetROXVersion(1)

'Now put the two parts together and prepend some identifying text:

ROXTotal = "ROX Version: " & (ROXMajor) & "." & (ROXMinor)

For information about using the code examples, see Using the code examples.


See also

GetAFCROXVersion function

GetAppContext function

GetFactoryVersion function

GetOSUserName function

GetServerName function

GetServerUserName function


GetServerName function

Example   See also

Returns the name of the machine the report server is running on.

Syntax

GetServerName

Return value

String


Example

The following code illustrates how you might use GetServerName to display the user's login name in a control.

Dim ServerName as String

ServerName = "Server Name: " & (GetServerName)

For information about using the code examples, see Using the code examples.


See also

GetAFCROXVersion function

GetAppContext function

GetFactoryVersion function

GetOSUserName function

GetROXVersion function

GetServerUserName function


GetServerUserName function

Example   See also

Returns the login name of the user logged into the report server.

Syntax

GetServerUserName

Return value

String


Example

The following code illustrates how you might use GetServerUserName to display the user's login name in a control.

Dim ServerUserName as String

ServerUserName = "Server User Name: " & (GetServerUserName)

For information about using the code examples, see Using the code examples.


See also

GetAFCROXVersion function

GetAppContext function

GetFactoryVersion function

GetOSUserName function

GetROXVersion function

GetServerName function


GetValue function

Example   See also

Returns the variable in an object even if you do not know the object's data type.

Syntax

GetValue(<object reference>, <column name>|<index>)

<object reference>

Any class expression. An object variable that refers to the object that has the variable you want to find.

<column name>

String expression that specifies the name of the variable to find.

Sometimes, you know the name of the variable to access, but do not know the name of the class that contains that variable, even though you do know its base class. The GetValue method of AcDataRow calls the global GetValue function. Use GetValue at run-time, not at compile-time, to check whether the object contains the variable. If the variable name does not exist, GetValue returns a run-time error.

Sub SetValue (row as AcDataRow)

MyValue = GetValue(row, "CustomerName")

End Sub

When using data rows, you can assign one or more aliases to each variable in the data row. For example, you can assign "customer.name", and "name" as aliases for a data row variable called "CustomerName". Then you can reference values using familiar database terms. This column-to-variable mapping is established when you use the Actuate Query Builder to build a data stream and its data row.

Use GetValue to look up the value of a variable given its database column alias. If GetValue finds no alias of the name, it looks for a variable of that name. The proper mapping must already be set using SetBinding.

Sub SetValue (row as AcDataRow)

MyValue = GetValue(row, "customer.name")

End Sub

<index>

Integer that specifies the index of a variable instead of its name or alias.

Indexing starts at 1. The index order puts all superclass variables before those defined in a subclass. For a data row, variable 1 is the standard RowNumber variable defined in AcDataRow.

Within a given class, the index order of variables is the order in which the variables are defined in the Actuate Basic source. If the DWB generates the Basic source (as is standard for a data row), then the DWB lists the variables in alphabetical order.

Return value

Variant

Tip

GetValue cannot provide compile error checking, but instead checks errors at run-time. If no variable exists with that name, GetValue sends an error message. Use GetValue when you don't know the name of the class that contains the variable or the data row's variable name.

Otherwise, use the following method to provides compile time error checking. You can access the variables in a class by declaring an object variable reference that points to an instance of that class, and then accesses the variables through that object reference variable. Sometimes you are given an object reference variable that points to a base class, such as AcDataRow, but you are interested in a derived class, such as CustomerRow. You can declare a temporary object reference variable of the derived class and set it equal to the reference to the base class.

Sub SetValue (row as AcDataRow)

Dim cust As CustomerRow

Set cust = row

MyValue = row.CustomerName

End Sub


Example

If you have the following classes:

Class MyBaseRow As AcDataRow

    Dim AVar As Integer

    Dim BVar As Integer

End Class

Class MyRow Subclass Of MyBaseRow

    Dim CVar As Integer

    Dim DVar As Integer

End Class

And you declare a row as follows:

    Dim row As MyRow

Then, you can call AVar with any of the following statements:

    x = row.AVar

    x = row.GetValue( "AVar" )

    x = row.GetValue( 2 )

The ordering sequence is now:

1 = AcDataRow::RowNumber

2 = MyBaseRow::AVar

3 = MyBaseRow::BVar

4 = MyRow::CVar

5 = MyRow::DVar


See also

SetBinding function


GetVariableCount function

Example   See also

Returns the number of variables in an instance. Used in conjunction with GetVariableName.

Syntax

GetVariableCount(<object reference>)

<object reference>

Any class expression. An object variable that refers to the object that has the variables you want to count.

Indexing of variables starts at 1. The index order puts all superclass variables before those defined in a subclass. For a data row, variable 1 is the standard RowNumber variable defined in AcDataRow.

Within a given class, the index order of variables is the order in which the variables are defined in the Actuate Basic source. If Actuate generates the Basic source, as is standard for a data row, then Actuate lists the variables in alphabetical order.

Return value

Integer

Tip

Use GetVariableName and GetVariableCount to loop over all the variables in an instance, and get both the variables' names and values. You van write highly customizable reports, or general purpose libraries using these functions.


Example

The following example shows how GetVariableName and GetVariableCount relate to each other.

Suppose you have the following classes:

Class MyBaseRow As AcDataRow

    Dim AVar As Integer

    Dim BVar As Integer

End Class

Class MyRow Subclass Of MyBaseRow

    Dim CVar As Integer

    Dim DVar As Integer

End Class

And suppose you declare a row as follows:

    Dim row As MyRow

You can get at AVar with any of the following:

x = row.GetValue( "AVar" )

x = row.GetValue( 2 )

In the ordering sequence, we have:

1 = AcDataRow::RowNumber

2 = MyBaseRow::AVar

3 = MyBaseRow::BVar

4 = MyRow::CVar

5 = MyRow::DVar

The following returns "AVar", the name of the variable at index 2:

GetVariableName( row, 2 )

The following returns the integer 5:

   GetVariableCount(row)


See also

GetVariableName function


GetVariableName function

Example   See also

Returns the name of the variable at a given index.

Syntax

GetVariableName(<object reference>, <index>)

<object reference>

Any class expression. An object variable that refers to the object that has the variable whose name you want to find.

<index>

Integer that specifies the index of a variable.

Indexing starts at 1. The index order puts all superclass variables before those defined in a subclass. For a data row, variable 1 is the standard RowNumber variable defined in AcDataRow.

Within a given class, the index order of variables is the order in which the variables are defined in the Actuate Basic source. If Actuate generates the Basic source, as is standard for a data row, then Actuate lists the variables in alphabetical order.

Return value

String

Tip

Use GetVariableName and GetVariableCount to loop over all the variables in an instance, and get both the variables' names and values. You van write highly customizable reports, or general purpose libraries using these functions.


Example

If you have the following classes:

Class MyBaseRow As AcDataRow

    Dim AVar As Integer

    Dim BVar As Integer

End Class

Class MyRow Subclass Of MyBaseRow

    Dim CVar As Integer

    Dim DVar As Integer

End Class

And you declare a row as follows:

    Dim row As MyRow

Then, you can call AVar with any of the following statements:

    x = row.AVar

    x = row.GetValue( "AVar" )

    x = row.GetValue( 2 )

The ordering sequence is now as follows:

1 = AcDataRow::RowNumber

2 = MyBaseRow::AVar

3 = MyBaseRow::BVar

4 = MyRow::CVar

5 = MyRow::DVar

The following statement returns "AVar", the name of the variable at index 2:

GetVariableName( row, 2 )

The following returns the integer 5:

   GetVariableCount(row)


See also

GetValue function

GetVariableCount function


Global statement

Example   See also

Declares and allocates memory for variables, and declares the variables to be available to all procedures in all modules.

Syntax

Global <variable name> [([<subscripts>])] [As <type>] [, <variable name> [([<subscripts>])] [As <type>]]...

<variable name>

A name you create for the new variable.

<subscripts>

Each <subscripts> argument specifies the number of elements in a dimension. The number of <subscripts> arguments specifies the number of dimensions in the array.

Array dimensions using the following syntax:

[<lower>] To <upper>],[<lower>] To <upper>]...

Rules for <subscripts>:

•	If you do not specify <subscripts> between parentheses, Actuate Basic declares a dynamic array

•	<lower> and <upper> can range from -32,768 to 32,767 inclusive.

•	<lower> must always be less than <upper>.

•	Use no more than 60 dimensions in a Global statement.

•	Do not later use ReDim to declare more than 8 dimensions for a dynamic array you declared with Global.

Examples:

The statements within the following Declare...End Declare block are equivalent if you do not use Option Base.

Declare

Global P(7,5)

Global P(0 to 7, 0 to 5)

Global P(7, 0 to 5)

End Declare

The following example declares a dynamic array:

Global TestArray( )

As <type>

Specifies a data type or class for the variable. If you specify a class, the variable can hold a reference to an instance of that class or descendant classes.

Rule for As <type>: If you do not specify As <type>, Actuate Basic uses the data type you declared with Dim or defaults to a Variant.

Rule

Use Global within a Declare...End Declare block in your .BAS source file.

Tips

•	To avoid assigning incorrect variable types, use the As clause to declare variables.

•	To create a dynamic array with more than eight dimensions, declare it with ReDim, not Global or Dim.

•	Use Global variables sparingly; declare variables in local scope if at all possible. Global variables are most useful when values must be shared or accessed by several tasks. Adding a lot of Global variables makes debugging more complicated; in addition, variables with Global scope must be kept in memory while the application is running.

•	To avoid debugging problems, note that variables declared with Global are automatically initialized as follows:

	Type	Initialized as
	Numeric	0
	Variant	Empty
	Variable-length strings	Zero-length String
	CPointer	Null
	User-defined	Separate variables
	Object or Class	Nothing (before Set)
To initialize one or more of your global variables to some default value (other than zero), write a procedure that initializes the variables, then call that procedure from the OnStartViewer( ) method of the report.


Example

The following Declare statement uses Global to declare two variables. The first is a global dynamic array variable called TestArray. The second is a global integer variable called PrintFlag, which is checked by several parts of the application to determine whether a print action has been completed.

Paste the following lines (Declare block and Sub block) at or near the beginning of your Actuate Basic code module (.BAS) file.

Declare

' Global dynamic array

Global TestArray( )

' Global integer variable

Global PrintFlag as Integer

End Declare

Sub LoadGlobalArray ( )

Dim I As Integer, Size As Integer, Msg As String, NL As String

NL = Chr$(10)

' First check if the global array has already been printed.

If PrintFlag Then

Msg = "That information has already been printed."

MsgBox Msg

Else

' Otherwise, set up TestArray for printing

Size = Int(10 * Rnd + 1)

ReDim TestArray(Size)

For I = 1 to Size

TestArray(I) = Int(10 * Rnd + 1)

Msg = Msg & TestArray(I) & NL

Next I

MsgBox Msg

' Finally set the print flag to true to notify the whole application

PrintFlag = True

End If

End Sub

Paste the following line into the OnLButtonDblClick( ) method of a label or other component in the Method Editor where noted "Insert your code here." After compiling, double-click the component.

LoadGlobalArray

For information about using the code examples, see Using the code examples.


See also

Const statement

Dim statement

GetAFCROXVersion function

GetAppContext function

GetFactoryVersion function

GetOSUserName function

GetROXVersion function

GetServerUserName function

Option Base statement

ReDim statement

Static statement

Type...End Type statement


GoTo statement

Example   See also

Branches to a specified line within a procedure unconditionally and without returning to the calling statement.

Syntax

GoTo { <line label> | <line number> }

<line label>

The name of any existing program label that marks the statement to execute next.

Rules for setting up <line label>:

•	Must begin with an alphabetic character and end with a colon.

•	Must not be an Actuate Basic keyword.

•	Must be unique to the module in which it appears.

•	Must be the first non-blank characters on the line.

•	Is not case-sensitive.

Example:

Function OnLButtonDblClk ( )

' Using Goto with a line label

On Error Goto MyErrorHandler

...

Exit Function

' The line label

MyErrorHandler:

...

End Sub

<line number>

The number of any program line that marks the statement to execute next.

Rules for setting up <line number>:

•	Must consist entirely of decimal digits (0 through 9).

•	Must not end with a colon.

•	Must be unique to the module in which it appears.

•	Must not be greater than 2,147,483,647 if you intend to use the Erl function.

•	Can begin in any column, but must be the first non-blank character on the line.

Example:

Function OnLButtonDblClk ( )

500 Dim X, Y, Z

' Set up error handler

510 On Error GoTo 550

520 Y = 1

'Now cause division by zero error:

530 X = Y / Z

540 Exit Function

' Error handler

550	 MsgBox "Error occurred at program line " & Erl

560 Resume Next

End Sub

Rule

GoTo can branch only to lines that exist within the procedure in which it appears.

Tips

•	Using GoTo in your code makes it difficult to understand and debug. To avoid confusion, use GoTo rarely. Instead, use more structured control statements, such as Do...Loop, For...Next, If...Then...Else, and Select Case, or define Function and Sub procedures.

•	It is good programming practice to evaluate Boolean variables -- not by inspecting their content for a nonzero (True) or zero (False) numeric value -- but by using the keywords True or False.


Example

The following example uses GoTo to branch around a subroutine.

Function OnLButtonDblClk()

Dim UserNum as Integer, HalfNum As Double

HalfNum = 0

UserNum = InputBox("Please type a number.")

' Branch around subroutine

GoTo ThisPlusColon

MsgBox "This message never appears."

Routine:

' GoTo detours around this subroutine

HalfNum = UserNum / 2

ThisPlusColon:

MsgBox "UserNum is: " & UserNum & ". HalfNum is still: " & HalfNum

End Function

For information about using the code examples, see Using the code examples.


See also

Erl function

Do...Loop statement

For...Next statement

Function...End Function statement

If...Then...Else statement

Select Case statement

Sub...End Sub statement


Hex, Hex$ functions

Example   See also

Converts a numeric expression from decimal to hexadecimal notation, and from numeric to string.

Syntax

Hex <numeric expression>)

Hex$ (<numeric expression>)

<numeric expression>

Numeric expression to be converted from decimal to hexadecimal notation.

Rule: If <numeric expression> evaluates to Null, Hex[$] returns a Null.

Examples:

The following statements are equivalent. Each returns "&H010", which is the full form of the hexadecimal equivalent of decimal number 16.

"&H" & Hex$(16)

"&H" & Hex$(2*8)

Of the next two statements, the first returns decimal value 32, and the second returns decimal value 37.

("&H" & Hex$(16)) * 2

Hex$(16) * 2 + 17

Return value

Hex: Variant

Hex$: String

•	Hex[$] rounds <numeric expression> to the nearest whole number before evaluating it.

•	If the data type of <numeric expression> is Integer, Variant of VarType 2 (Integer), or Variant of VarType 0 (Empty), Hex[$] returns up to four hexadecimal characters.

•	If <numeric expression> is of any other numeric or Variant data type, Hex[$] returns up to eight hexadecimal characters.

Tips

•	To represent a hexadecimal number directly, precede a number in the correct range with the radical prefix "&H". The valid range for hex numbers is &H0 to &HFFFFFFFF. For example, you can use &H010 * 2 to generate the decimal value 32; &H010 is hexadecimal notation for decimal value 16.

•	To generate the full hexadecimal representation of <numeric expression>, you will need to supply the radical prefix "&H", because Hex[$] does not return that component.

•	To ensure correct results when you assign the output of Hex to a variable, be sure the variable is of type Variant.


Example

The following example prompts you for a decimal number, then uses Hex[$] to convert it to hexadecimal notation.

Function OnLButtonDblClk()

Dim Msg, Num

' Get user input

Num = InputBox("Please type a number to convert.")

Msg = Num & " in decimal notation is &H"

Msg = Msg & Hex$(Num) & " in hexadecimal notation."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Oct, Oct$ functions

Val function


Hour function

Example   See also

Returns the hour of the day as an integer from 0 (Midnight) to 23 (11:00 PM), inclusive, based on a supplied date expression.

Syntax

Hour(<date expression>)

<date expression>

Date expression, or any numeric or string expression that can be interpreted as a date, a time, or as both a date and a time.

•	Can be a string expression such as "November 12, 1982 8:30 PM", "Nov 12, 1982 08:30 PM", "11/12/82 8:30pm", or "08:30pm", or any other string that can be interpreted as a date or date/time in the valid range.

•	Can be a date serial number such as 30267.854 (which corresponds to November 12, 1982 at 8:30 PM), or any other number that can be mapped to a date or date/time in the valid range.

•	For date serial numbers, the integer component to the left of the decimal represents the date itself while the fractional component to the right of the decimal represents the time of day on that date, where January 1, 1900, at precisely noon has the date serial number 2.5, and negative numbers represent dates prior to December 30, 1899 (0).

Default if no time specified: 0

Rules:

•	If a date is included, it must be a valid date, even though Hour does not return a date. A valid date is any date in the range January 1, 100, through December 31, 9999, inclusive, expressed in one of the standard date formats.

•	If a time is included, it must be in the range 00:00:00 (12:00:00 AM) through 23:59:59 (11:59:59 PM), in either 12- or 24-hour notation.

•	If a numeric expression, it must be in the range -657,434 to +2,958,465, inclusive.

•	If a variable containing a date serial number, the variable must have been explicitly declared as one of the numeric types.

Examples:

The following statements are equivalent. Each assigns 14 to the variable UserHour.

UserHour = Hour("6/7/64  2:35pm")

UserHour = Hour("14:35")

UserHour = Hour("June 7, 1964 2:35 PM")

UserHour = Hour("Jun 7, 1964") + 14

UserHour = Hour(23535.6076)

UserHour = Hour(0.6076)

Return value

Integer

Rule: If <date expression> is Null, Hour returns a Null.


Example

The following example displays the number of hours, minutes, and seconds to midnight.

Function OnLButtonDblClk()

Dim HrDiff As Integer, MinDiff As Integer, SecDiff As Integer

Dim RightNow As Double, Midnight As Double, TotalDiff As Double

Dim TotalMinDiff As Double, TotalSecDiff As Double
Dim Msg As String

'

Midnight = TimeValue("23:59:59")

' Get current time

RightNow = Now

' Get diffs re midnight

HrDiff = Hour(Midnight) - Hour(RightNow)

MinDiff = Minute(Midnight) - Minute(RightNow)

SecDiff = Second(Midnight) - Second(RightNow) + 1

' Restate seconds and minutes if necessary

If SecDiff = 60 Then

' Add 1 to minute

MinDiff = MinDiff + 1

' And set 0 seconds

SecDiff = 0

End If

If MinDiff = 60 Then

' Add 1 to hour

HrDiff = HrDiff + 1

' And set 0 minutes

MinDiff = 0

End If

' Now get totals

TotalMinDiff = (HrDiff * 60) + MinDiff

TotalSecDiff = (TotalMinDiff * 60) + SecDiff

TotalDiff = TimeSerial(HrDiff, MinDiff, SecDiff)

' Prepare msg for display

Msg = "There are a total of " & Format(TotalSecDiff, "#,##0")

Msg = Msg & " seconds until midnight.  That translates to "

Msg = Msg & HrDiff & " hours, "

Msg = Msg & MinDiff & " minutes, and "

Msg = Msg & SecDiff & " seconds. "

Msg = Msg & "Expressed in standard time notation, it becomes "

' Remember not to use "mm" for minutes! m is for month.

Msg = Msg & Format(TotalDiff, "hh:nn:ss") & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Day function

Minute function

Month function

Now function

Second function

Time, Time$ functions

Weekday function

Year function


If...Then...Else statement

Example   See also

Executes an instruction or block of instructions based on a condition or series of conditions.

Syntax

Single-line If...Then...Else statement

If <condition> Then <then-statement> Else <else-statement>

Block, multiple-line If...Then...Else statement

If <condition> Then

<then-statement>

[[ElseIf <condition> Then

<then-statement>]]

[Else

[<else-statement>]]]

End If

<condition>

A numeric or string expression that can be evaluated, and that determines whether to execute the associated <statements>. When <condition> evaluates to zero or Null, the condition is False. <condition> is True otherwise.

<then-statement>, <else-statement>

One or more Actuate Basic expressions which can include nested If...Then...Else statements. The <then-statement> executes if the preceding <condition> is true. The <else-statement> executes if all previous <conditions> are False. Only one block of <statements> is executed in an If...Then...Else statement: the block of statements following the first <condition> found to be true, or (if no <condition> is found to be true) the <else-statement> block.

If

Keyword that begins every If...Then...Else statement and precedes the first <condition> to be tested.

Then

Keyword that separates <condition> from <then-statement> in an If...Then...Else statement. When <condition> evaluates to True, the <then-statement> is executed. When <condition> evaluates to False, the <then-statement> is ignored, and the program execution tests the next <condition> that it finds.

Else

A keyword that tells the program what to do when all previous conditions are False.

ElseIf

Keyword that begins an alternative <condition> to be evaluated when the previous <condition> is false. You can use multiple ElseIf clauses. (Tip: if you have several ElseIf clauses, consider using a Select Case statement instead). Actuate Basic evaluates each ElseIf <condition> in turn, but only until the first true one is encountered. When an ElseIf <condition> evaluates to true, its <then-statements> are executed and control resumes after End If.

End If

Keyword that signals the end of an If...Then...Else statement. A multi-line block If...Then...Else statement must be closed with End If. It is not required for a single-line If...Then...Else statement.

Rule: If, Else, ElseIf, and End If must be the first statement on a line. Else, ElseIf, and End If can be preceded by a line number or a line label.

Tip

It is good programming practice to evaluate Boolean variables -- not by inspecting their content for a nonzero (True) or zero (False) numeric value -- but by using the keywords True or False.


Example

The following example prompts the user for a number between 0 and 10000. Then it returns the number of digits in the number.

Function OnLButtonDblClk()

Dim UserNum As Integer, NumDigits As Integer

Dim Msg As String, Unit As String

UserNum = InputBox("Type an integer greater than 0 and less than 10000.")

If UserNum < 10 Then

' 1 digit

NumDigits = 1

ElseIf UserNum < 100 Then

' 2 digits

NumDigits = 2

ElseIf UserNum < 1000 Then

' 3 digits

NumDigits = 3

ElseIf UserNum < 10000 Then

' 4 digits

NumDigits = 4

Else

' Prepare the msg for display if none of our conditions was met

Msg = "Sorry, the number you typed was too high."

End If

' Prepare a msg for display if at least one condition was met

If UserNum < 10000 Then

If NumDigits > 1 Then

Unit = " digits."

Else

Unit = " digit."

End If

Msg = "The number you typed has " & NumDigits & Unit

End If

' Display message

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

End statement

Exit statement

Select Case statement


IIf function

Example   See also

Evaluates an expression and returns one of two supplied values; if the expression that is the first argument is true, IIf returns the second argument, if false, IIf returns the third.

Syntax

IIf(<condition>, <value if true>, <value if false>)

<condition>

Numeric or string expression to be evaluated.

<value if true>

Numeric or string expression that specifies the value or expression to return if <condition> is true.

<value if false>

Numeric or string expression that specifies the value or expression to return if <condition> is false.

Example:

The following statement assigns the double-precision value 112.335577 to the variable ValidMsg if the variable UserAns contains a value less than 5. It assigns the string expression "Sorry, invalid response" if the value of UserAns is greater than or equal to 5.

ValidMsg = IIf(UserAns < 5, 112.335577, "Sorry, invalid response")

Return value

Same type as that of <value if true> or <value if false>, depending on which is returned.

Rule

All three arguments must be valid. That is, none can generate an error since all three are always evaluated whether <condition> is true or false.


Example

The following example asks the user to type a number less than 5. It then validates the response and displays an appropriate message.

Function OnLButtonDblClk ( )

Dim UserAns As Double, ValidMsg As String

UserAns = InputBox("Please type a number smaller than 5.")

ValidMsg = IIf(UserAns < 5, "You typed:  " & UserAns, "Invalid response")

MsgBox ValidMsg

End Function

For information about using the code examples, see Using the code examples.


See also

If...Then...Else statement

Select Case statement


Input # statement

Example   See also

Reads data from a sequential file and assigns the data to variables.

Syntax

Input #<open file number>, <variable list>

<open file number>

Numeric expression that is the file number assigned by Open statement when the target file was opened.

Rules for <open file number>:

•	The number sign ("#") preceding the file number is required.

•	The file must be open.

<variable list>

Comma-delimited list of the variables that act as containers for values read from the file.

Rules for <variable list>:

•	Cannot contain array variables, but can contain variables that reference an element of an array. For instance, "MyArray( )" refers to an entire array and is therefore not allowed; but "MyArray(23)" refers to a specific element in the array and is therefore a valid variable.

•	Cannot be an object variable, user-defined data type structure, handle to a class, CPointer, or OLE object.

Example:

The following code fragment opens an existing file named TEST.FIL, assigns data from it to a variable called FileData, and constructs a message.

Open "TEST.FIL" for Input As #1

Do While Not EOF(1)

Input #1, FileData

Msg = Msg & FileData & Chr$(10)

Loop

Close #1

MsgBox Msg

Kill "TEST.FIL"

Description

The Input # statement places each data item in the file into one or more of the variables in <variable list>. Data items in the file must appear in the same order as the variables in <variable list> and each variable in <variable list> must be of the same data type as the target data item.

The Input # statement reads each data item and assigns it to its corresponding variable according to its data type. The following two tables summarize the behavior of Input #:

Variable in <variable list>	Behavior of Input #
Numeric	Assumes first nonspace character it encounters to be the start of a number. Assumes the first space, comma, or end-of-line it encounters to be the end of a number. Inputs blank lines and data of an invalid data type as zero.
String	Assumes the first nonspace character it encounters to be the start of a character string. If that character is a double quote ("), it ignores the mark itself and inputs all the succeeding characters until it encounters the next double quote, including spaces and commas. If string data are not delimited by double quotes, it assumes the first line, space, or end-of-line character to be the end of the string. Inputs blank lines as zero-length strings.
The following table summarizes how Input # decides what Variant type to assign to Variants in <variable list>:

Input data	Variant type assigned
Valid number	An appropriate numeric Variant (types 2 through 6)
No data, but only a delimiting comma, or a blank line	VarType 0 (Empty)
The literal Null	VarType 1 (Null)
Date literal (that is, a date of the form "yyyy-mm-dd hh:nn:ss")	VarType 7 (Date). Tip: When either the date or time portion is present, the other portion is optional.
None of the above	VarType 8 (String)
Rules

•	Input # generates an error if it reaches the end of file while it is inputting a data item.

•	Data items in a file should appear in the same order as the variables in <variable list> to which they correspond.

Tips

•	To prevent Input # from encountering the end-of-file before it is finished processing data, use it within a loop that tests for the end-of-file condition. For details, see EOF.

•	Match data in the file with variables of the proper data type, that is:

•	Assign string data to string or Variant variables.

•	Assign numeric data to numeric or Variant variables.

•	Assign date data to date or Variant variables.

•	Assign uniquely Variant data--like Empty and Null values--only to Variant variables.


Example

The following example creates a test file and reads nonnumeric values from the test file into a variable. In this example OnLButtonDblClk( ) is overridden to generate the test file. The procedure MakeSomeData( ) should be typed after the End Function of the OnLButtonDblClk( ) procedure or saved in an Actuate code module (.BAS file).

Function OnLButtonDblClk( )

Dim FileData As String, Msg As String, NL As String

' Define newline

NL = Chr$(10)

' Create test file

MakeSomeData

' Open to read test file

Open "TEST.FIL" For Input As #1

Do While Not EOF(1)

' Read a line of data

Input #1, FileData

' Construct message

Msg = Msg & FileData & NL

Loop

'

' Close file

Close #1

MsgBox Msg

' Delete test file

Kill "TEST.FIL"

End Function

Sub MakeSomeData()

' This procedure creates the test file used in OnLButtonDblClk

'

' Open to write test file

Open "TEST.FIL" For Output As #1

' Write sample data

Write #1, "This is the first line of the file."

Write #1, "This is the second line."

' Close test file

Close #1

End Sub

For information about using the code examples, see Using the code examples.


See also

Input, Input$ functions

Write # statement


Input, Input$ functions

Example   See also

Returns a specified number of characters from a sequential file.

Syntax

Input(<number of chars>,<file number>)

Input$(<number of chars>, <file number>)

<number of chars>

Numeric expression for the number of characters to read from the file.

Rule for <number of chars>: Must be between 1 and 2,147,483,647.

Example:

The following code fragment opens a file in the current directory named MYFILE.TXT, reads 51 characters from that file into a variable called ReadChunk, then closes the file.

Open "MYFILE.TXT" for Input As #1

ReadChunk = Input$(51, #1)

Close #1

<file number>

Integer that is the file number assigned by Open statement when the target file was opened.

Rule for <file number>: File must be open.

Return value

Input: Variant

Input$: String

Returns all the characters it reads, including commas, carriage returns, linefeeds, quotation marks, and leading spaces.

Rules

Can be used only with files opened in Input or Binary mode.


Example

The following procedure reads a single character at a time from a file. When it encounters an ANSI character code 10 (linefeed), however, it displays the entire line of text in a message box.

Function OnLButtonDblClk ( )

Dim Collector, UsersFile, DisplayMe

' Request file name

UsersFile = InputBox("Please type a filename.")

If Len(UsersFile) Then

' Open specified file

Open UsersFile For Input As #1

Do While Not EOF(1)

' Obtain 1 character

Collector = Input$(1, 1)

' If not a linefeed, then collect it

If Collector <> Chr(10) Then

DisplayMe = DisplayMe & Collector

' If it is a linefeed, then display it

Else

MsgBox DisplayMe

' Clear the line

DisplayMe = ""

End If

' Loop if not EOF

Loop

' Close the file

Close #1

End If

End Function

For information about using the code examples, see Using the code examples.


See also

Input # statement

InputB, InputB$ functions


InputB, InputB$ functions

Example   See also

Returns a specified number of bytes from a sequential file.

Syntax

InputB(<number of bytes>,<file number>)

InputB$(<number of bytes>, <file number>)

<number of bytes>

Numeric expression for the number of bytes to read from the file.

Rule for <number of chars>: Must be between 1 and 2,147,483,647.

Example:

The following code fragment opens a file in the current directory named "MYFILE.TXT", reads 51 bytes from that file into a variable called ReadChunk, then closes the file.

Open "MYFILE.TXT" for Input As #1

ReadChunk = InputB$(51, #1)

Close #1

<file number>

Integer that is the file number assigned by Open statement when the target file was opened.

Rule: File must be open

Return value

InputB: Variant

InputB$: String

Returns all the bytes it reads, including commas, carriage returns, linefeeds, quotation marks, and leading spaces.

Rules

Can be used only with files opened in Input or Binary mode.


Example

The following procedure reads a single byte at a time from a file. When it encounters an ANSI character code 10 (linefeed), however, it displays the entire line of text in a message box.

Function OnLButtonDblClk ( )

Dim Collector, UsersFile, DisplayMe

' Request file name

UsersFile = InputBox("Please type a filename.")

If Len(UsersFile) Then

' Open specified file

Open UsersFile For Input As #1

Do While Not EOF(1)

' Obtain 1 byte

Collector = InputB$(1, 1)

' If not a linefeed, then collect it

If Collector <> Chr(10) Then

DisplayMe = DisplayMe & Collector

' If it is a linefeed, then display it

Else

MsgBox DisplayMe

' Clear the line

DisplayMe = ""

End If

' Loop if not EOF

Loop

' Close the file

Close #1

End If

End Function

For information about using the code examples, see Using the code examples.


See also

Input # statement

Input, Input$ functions


InputBox, InputBox$ functions

Example   See also

Displays a prompt in a dialog box, waits for the user to type text or select a button, and returns the contents of the text box.

Syntax

InputBox[$](<user prompt> [,<box title> ][,<default entry> ])

<user prompt>

String expression that specifies an instruction, message, or prompt to display to the user.

Rule for <user prompt>: Cannot be longer than approximately 255 characters, depending on character width.

<box title>

String expression that specifies the text you want to display in the title bar of the dialog box. The default is no text displayed in the title bar.

<default entry>

String expression that is the default response if the user supplies no other input. It is placed in the dialog's text box and is selected (highlighted), which means that any new entry replaces it. If desired, the most frequently given response can be displayed here. The default is no text displayed in the text box.

Example:

The following statement presents a dialog box with "Date Entry" in the title bar. It prompts the user with "Type a date" and suggests today's date as the default. The dialog box appears in the upper left corner of the screen. The user's response is assigned to the variable UDate. If the user types nothing in the text box but selects the OK button (or presses Enter), today's date is assigned to the variable by default.

UDate = InputBox("Type a date.", "Date Entry", Format$(Now, "mm/dd/yy"))

Return value

InputBox: Variant

InputBox$: String

InputBox[$] displays a dialog box that contains an OK button and a Cancel button, a text box for user input, and the text specified in <user prompt>.

•	If the user selects OK or Enter, InputBox[$] returns whatever is in the
text box.

•	If the user selects Cancel, InputBox[$] returns a zero-length string ("").

Rule

You must explicitly type InputBox input variables as numeric if you're expecting numeric input from the user.

Tips

•	Use InputBox[$] when you want a quick way to get data from the user.

•	If the string in <user prompt> is too long to fit on one line in the dialog box, the text automatically wraps around to the next line. You can, however, force a new line by inserting a line feed (Chr$(10)) in <user prompt>.


Example

The following example prompts the user to type a date, and suggests today's date as the default. Whenever the user fails to type a valid date, it repeats the dialog box. Finally, it displays the day of the week for the supplied date.

Sub InputBoxExample()

Dim UserPrompt As String, BoxTitle As String, DefEntry As String

Dim UserDate, Msg As String

'

UserPrompt = "Please type a date in the form mm/dd/yy."

BoxTitle = "Date Entry Screen"

DefEntry = Format$(Now, "mm/dd/yy")

'

Do

UserDate = InputBox(UserPrompt, BoxTitle, DefEntry)

Loop Until IsDate(UserDate)

'

Msg = "That date, " & UserDate

Msg = Msg & ", was a " & Format$(UserDate, "dddd") & "."

MsgBox Msg

End Sub

For information about using the code examples, see Using the code examples.


See also

MsgBox function

MsgBox statement


InStr function

Example   See also

Returns the starting position of the occurrence of one string within another.

Syntax

Syntax 1

InStr(<string being searched>, <string to find>)

Syntax 2

InStr(<start>, <string being searched>, <string to find>)

<start>

Position (number of characters) within <string being searched> at which to begin searching.

Rules for <start>:

•	If you do not supply a <start> position, Actuate Basic begins searching at 1 (the first character).

•	Must be a number or numeric expression.

•	Must be between 1 and 2,147,483,647, inclusive.

<string being searched>

String you are inspecting in order to locate <string to find>.

Rule for <string being searched>: Must be a variable string, a literal string, a string constant, the return value of any function that returns a string, or a variant that can evaluate to a string.

<string to find>

String you are seeking within <string being searched>.

Rule for <string to find>: Must be a variable string, a literal string, a string constant, the return value of any function that returns a string, or a variant that can evaluate to a string.

Return value

Integer

•	If <string to find> is found within <string being searched>, InStr returns the position of the first character at which the match was found.

•	If <string to find> is not found within <string being searched>, InStr returns 0.

•	If <string to find> is zero-length, InStr returns the value of <start>.

•	If <string being searched> is zero-length, InStr returns 0.

•	If <start> is greater than <string being searched>, InStr returns 0.


Example

The following example returns the starting position of a some characters within a string.

Function OnLButtonDblClk()

Dim MonthList As String, Position As Integer

Dim Msg As String, UserInput As String

    MonthList = "JANFEBMARAPRMAYJUNJULAUGSEPOCTNOVDEC"

    Msg = "Please type the 3-letter abbreviation for a month."

' Get user input

    UserInput = UCase(InputBox(Msg))

' Check user input

    If Len(UserInput)Then

' Get the position

Position = InStr(MonthList, UserInput)

If Position <> 0 and Len(UserInput)= 3 and ((Position - 1) Mod 3 = 0) Then

Msg = "That month starts at position " & Position & " in the list."

Else

Msg = "You did not enter a 3-letter abbreviation for a month!"

End If

Else

Msg = "You did not enter anything at all."

End If

    MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Left, Left$ functions

Len function

Mid, Mid$ functions

Right, Right$ functions


InStrB function

Example   See also

Returns the starting byte of the occurrence of one string within another.

Syntax

Syntax 1

InStrB(<string being searched>, <string to find>)

Syntax 2

InStrB(<start>, <string being searched>, <string to find>)

<start>

Position (byte count) within <string being searched> at which to begin searching.

Rules for <start>:

•	If you do not supply a <start> position, Actuate Basic begins searching at 1 (the first byte).

•	Must be a number or numeric expression.

•	Must be between 1 and 2,147,483,647, inclusive.

<string being searched>

String you are inspecting in order to locate <string to find>.

Rule for <string being searched>: Must be a variable string, a literal string, a string constant, the return value of any function that returns a string, or a variant that can evaluate to a string.

<string to find>

String you are seeking within <string being searched>.

Rule for <string to find>: Must be a variable string, a literal string, a string constant, the return value of any function that returns a string, or a variant that can evaluate to a string.

Return value

Integer

•	If <string to find> is found within <string being searched>, InStrB returns the position of the first byte at which the match was found.

•	If <string to find> is not found within <string being searched>, InStrB returns 0.

•	If <string to find> is zero-length, InStrB returns the value of <start>.

•	If <string being searched> is zero-length, InStrB returns 0.

•	If <start> is greater than <string being searched>, InStrB returns 0.


Example

In the following example, InStrB returns the starting position of a some bytes within a string.

Function OnLButtonDblClk()

Dim MonthList As String, Position As Integer

Dim Msg As String, UserInput As String

MonthList = "JANFEBMARAPRMAYJUNJULAUGSEPOCTNOVDEC"

Msg = "Please type the 3-letter abbreviation for a month."

' Get user input

UserInput = UCase(InputBox(Msg))

' Check user input

If Len(UserInput)Then

' Get the position

Position = InStrB(MonthList, UserInput)

If Position <> 0 and Len(UserInput)= 3 and ((Position - 1) Mod 3 = 0) Then

Msg = "That month starts at position " & Position & " in the list."

Else

Msg = "You did not enter a 3-letter abbreviation for a month!"

End If

Else

Msg = "You did not enter anything at all."

End If

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

LeftB, LeftB$ functions

LenB function

MidB, MidB$ functions

RightB, RightB$ functions


Int function

Example   See also

Returns the largest integer that is less than or equal to a given numeric expression.

Syntax

Int(<number to round>)

<number to round>

Numeric expression from which the fractional part is removed so that an integer value is returned.

Return value

Data type or value of <number to round>	Int returns
Variant of type 8 (String) that can convert to a number	Variant of type 5 (Double)
Any other data type	Same data type as <number to round>
Null	Null
•	Int and Fix are similar but not identical. For negative values, Int returns the first negative integer less than or equal to <number to round> while Fix returns the first negative integer greater than or equal to <number to round>. CInt is also similar to Int and Fix.

•	Using some sample values as arguments, the following table shows the differences between Int, Fix and CInt.

Value	Int(Value)	Fix(Value)	CInt(Value)
3.7	3	3	4
3.2	3	3	3
3	3	3	3
-3	-3	-3	-3
-3.2	-4	-3	-3
-3.7	-4	-3	-4
Tip

Fix is equivalent to Sgn(<number to round>) * Int(Abs(<number to round>)).


Example

The following example prompts you for a number and displays the return values from Int, Fix and CInt.

Function OnLButtonDblClk()

Dim Number, Msg As String, NL As String

' Define newline

NL = Chr$(10)

' Get user input

Number = InputBox("Please type a number.")

' Strip off any surrounding spaces

Number = Trim(Number)

Msg = "Int(" & Number & ") = " & Int(Number) & NL

Msg = Msg & "Fix(" & Number & ") = " & Fix(Number) & NL

Msg = Msg & "CInt(" & Number & ") = " & CInt(Number) & NL

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

CInt function

Fix function


IPmt function

Example   See also

Returns the interest payment for a given period of an annuity, based on periodic, constant payments, and on an unvarying interest rate.

Syntax

IPmt(<rate per period>,<single period>, <number pay periods>, <present value>, <future value>, <when due>)

<rate per period>

Numeric expression that specifies the interest rate that accrues per period.

Rule for <rate per period>: Must be given in the same units of measure as <number pay periods>. For instance, if <number pay periods> is expressed in months, then <rate per period> must be expressed as a monthly rate.

<single period>

Numeric expression that specifies the particular period for which you want to determine how much of the payment for that period represents interest.

Rule for <single period>: Must be in the range 1 through <number pay periods>.

<number pay periods>

Numeric expression that specifies the total number of payment periods in the annuity.

Rule for <number pay periods>: Must be given in the same units of measure as <rate per period>. For instance, if <rate per period> is expressed as a monthly rate, then <number pay periods> must be expressed in months.

<present value>

Numeric expression that specifies the value today of a future payment or stream of payments.

Example: If you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you end up with about $100. In this case, the present value of $100 is approximately $23.94.

<future value>

Numeric expression that specifies the cash balance you want after you have made your final payment.

Examples:

•	You set up a savings plan with a goal of having $75,000 in 18 years to pay for your child's education. For this plan, the future value is $75,000.

•	You take out a loan for $11,000. The future value is $0.00, as it is for any typical loan.

<when due>

Numeric expression that specifies whether each payment is made at the beginning (1) or at the end (0) of each period.

Default: 0, end of period.

Rule for <when due>: Must be 0 or 1.

Example:

The following example assumes you are making monthly payments the first of each month on a loan of $20,000, over 36 months, at an APR of 11.5%. How much of your 5th payment represents interest? The answer ($171.83) is assigned to Interest5.

Interest5 = IPmt(.115/12, 5, 36, -20000, 0, 1)

Return value

Double

An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment (such as a monthly savings plan) or a loan (such as a home mortgage). Each payment consists of two components: principal and interest. IPmt returns the interest component of the payment.

Rules

•	<rate per period> and <number pay periods> must be expressed in terms of the same units (weekly/weeks, monthly/months, yearly/years).

•	You must express cash paid out (such as deposits to savings) using negative numbers, and cash received (such as dividend checks) using positive numbers.


Example

The following example prompts the user to supply various particulars about a loan. It then returns the total amount of interest that will be paid on it. To use this example, paste the first portion at or near the beginning of your Actuate Basic source code (.BAS) file. Then copy the procedure into the Method Window for a clickable component.

Declare

Global Const ENDPERIOD = 0

Global Const BEGINPERIOD = 1

End Declare

'

Function OnLButtonDblClk()

Dim FutVal As Double, PresVal As Double

Dim APR As Double, TotPmts As Integer

Dim PayWhen As Integer, Period As Integer, IntPmt As Double

Dim SumInt As Double, Fmt As String, Payment As Double

Dim Msg as String

'

' Specify money format

Fmt = "$###,###,##0.00"

' Normally 0 for a loan

FutVal = 0

' Get user input

Msg = "How much will you borrow?"

PresVal = InputBox(Msg)

Msg = "What is the annual percentage rate (APR) for your loan?"

APR = InputBox(Msg)

' Ensure proper form as %

If APR > 1 Then

APR = APR / 100

End If

Msg = "How many monthly payments will you make?"

TotPmts = InputBox(Msg)

Msg = "Will you make payments at month end.?"

PayWhen = MsgBox(Msg, MB_YESNO)

If PayWhen = IDNO Then

PayWhen = BEGINPERIOD

Else

PayWhen = ENDPERIOD

End If

' Do the computational work

For Period = 1 To TotPmts

IntPmt = IPmt(APR / 12, Period, TotPmts, -PresVal, FutVal, PayWhen)

SumInt = SumInt + IntPmt

Next Period

' Set up display for the user

Msg = "You will pay a cumulative total of " & Format(SumInt, Fmt)

Msg = Msg & " in interest for this loan, which represents about "

Msg = Msg & Format(SumInt / PresVal, "##.0%") & " of the "

Msg = Msg & Format(PresVal, Fmt) & " you are borrowing."

MsgBox Msg

Payment = Pmt(APR / 12, TotPmts, -PresVal, FutVal, PayWhen)

MsgBox "Your payments will be " & Format(Payment, Fmt) & " per month."

End Function

For information about using the code examples, see Using the code examples.


See also

FV function

NPer function

Pmt function

PPmt function

PV function

Rate function


IRR function

Example   See also

Returns the internal rate of return for a series of periodic cash flows (payments and receipts) in an existing array.

Syntax

IRR(<casharray>(),<starting guess>)

<casharray>()

Specifies the name of an existing array of Doubles representing cash flow values.

Rule for <casharray>: Array must contain at least one positive value (receipt) and one negative value (payment).

<starting guess>

Numeric expression. Specifies the value you estimate IRR will return. In most cases, this is 0.1 (10 percent).

Example:

The following example assumes you have filled the array MyArray() with a series of cash flow values. The internal rate of return is assigned to the variable IRRValue.

IRRValue = IRR(MyArray(), .1)

Return value

Double

The internal rate of return is the interest rate for an investment consisting of payments and receipts that occur at regular intervals. The cash flow for each period does not need to be constant, as it does for an annuity.

IRR is closely related to the net present value function, NPV, because the rate of return calculated by IRR is the interest rate corresponding to a net present value of zero. IRR calculates by iteration. Starting with the value of <starting guess>, it repeats the calculation until the result is accurate to within 0.00001 percent. If it cannot determine a result after 20 iterations, the function fails.

Rules

•	You must express cash paid out (such as deposits to savings) using negative numbers, and cash received (such as dividend checks) using positive numbers.

•	<casharray>() must contain at least one negative and one positive number.

•	In cases where you have both a positive cash flow (income) and a negative one (payment) for the same period, use the net flow for that period.

•	If no cash flow or net cash flow occurs for a particular period, you must type 0 (zero) as the value for that period.

Tips

•	Because IRR uses the order of values within the array to interpret the order of payments and receipts, be sure to type your payment and receipt values in the correct sequence.

•	If IRR fails, try a different value for <starting guess>.


Example

The following example returns the internal rate of return for a series of five cash flows contained in the array CashValues(). The first array element is a negative cash flow that represents business start-up costs. The remaining four cash flows represent positive cash flows for the subsequent four years. The variable Guess holds the estimated internal rate of return. Option Base is assumed to be set to zero.

Function OnLButtonDblClk ( )

' Set up the array

Static CashValues(5) As Double

Dim Guess As Double, Fmt As String

Dim ReturnRate As Double, Msg As String

' Start guess at 10%

Guess = .1

' Define % format

Fmt = "#0.00"

' Business start-up costs

CashValues(0) = -80000

' Now type positive cash flows reflecting

' income for four successive years:

CashValues(1) = 23000: CashValues(2) = 27000

CashValues(3) = 31000: CashValues(4) = 35000

' Calc internal rate

ReturnRate = IRR(CashValues, Guess) * 100

Msg = "The internal rate of return for these 5 cash flows is:  "

Msg = Msg & Format(ReturnRate, Fmt) & " percent."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

MIRR function

NPV function

Rate function

Option Base statement


IsDate function

Example   See also

Determines whether the given argument can be converted to a date.

Syntax

IsDate(<exprs>)

<exprs>

Variant expression to test to determine whether it is a date, can be evaluated as a date, or can be converted into a date.

Rule: Range of valid dates is January 1, 100, through December 31, 9999, inclusive.

Examples:

The following are equivalent. They all return 1 (True).

IsDate("11/12/82")

IsDate("November 12, 1982")

IsDate("Nov 12, 1982")

IsDate("N" & "ov " & "12, " & (1980 + 2))

Return value

Integer

Returns 1 (True) if <exprs> can be converted to a date. Otherwise, returns 0 (False).

Tip

To convert any number between -657,434 and 2,958,465 into a date, use CVDate. For example, use CVDate(34040.34) to return 3/12/93 7:55:12 AM.


Example

The following example accepts a string or a number and, if possible, converts it to a date.

Function OnLButtonDblClk ( )

Dim UsrStr As String, NL As String, Msg As String

' Define newline

NL = Chr$(10)

UsrStr = InputBox("Please type a string to display as a date.")

' Test the string

If IsDate(UsrStr) Then

MsgBox "The date is: " & Format(CVDate(UsrStr), "dddddd")

Else

If IsNumeric(UsrStr) Then

If Val(UsrStr) >= -657434 And Val(UsrStr) <= 2958465 Then

Msg = "You typed a number that is not in "

Msg = Msg & "date format.  However, it will "

Msg = Msg & "be interpreted as the following date:" & NL & NL

Msg = Msg & Format(CVDate(UsrStr), "dddddd")

MsgBox Msg

Else

MsgBox "Sorry, what you typed cannot be converted to a date."

End If

End if

End If

End Function

For information about using the code examples, see Using the code examples.


See also

CVDate function

IsEmpty function

IsNull function

IsNumeric function

VarType function


IsEmpty function

Example   See also

Reports whether the given variable has been initialized.

Syntax

IsEmpty(<exprs>)

<exprs>

Variant expression to test whether it has ever been assigned a value.

Return value

Integer

•	Returns 1 (True) if <exprs> contains the Empty value. Otherwise, returns 0 (False).

•	Returns 0 (False) if <exprs> contains more than one Variant.

Tip

Empty and Null are different. A variable can contain the Null value only if you explicitly assign Null to the variable.


Example

The following example tests a variable to determine whether it has ever held any value. If not, it reports that the variable has not been initialized, and asks the user whether to do so or not.

Function OnLButtonDblClk ( )

Dim InitYesNo As Integer, MyVar, Msg As String

MsgBox "The value of IsEmpty(MyVar) is now: " & IsEmpty(MyVar)

'Test MyVar

If IsEmpty(MyVar) Then

Msg = "MyVar is uninitialized.  Should we initialize it now?"

InitYesNo = MsgBox(Msg, MB_YESNO + MB_ICONQUESTION)

' If user answers Yes

If InitYesNo = IDYES Then

' Initialize MyVar

MyVar = 32.5

MsgBox "MyVar initialized to " & MyVar

MsgBox "The value of IsEmpty(MyVar) is now:" & IsEmpty(MyVar)

Else

MsgBox "The value of IsEmpty(MyVar) is still:" & IsEmpty(MyVar)

End If

End If

End Function

For information about using the code examples, see Using the code examples.


See also

IsDate function

IsNull function

IsNumeric function

VarType function


IsKindOf function

Example   See also

Determines whether a specified object is an instance of a specified class.

Syntax

IsKindOf(<object>, <class>)

<object>

The variable name that refers to the object about which you want information.

<class>

The class to test for the membership of an instance of <object>.

Return value

Integer

•	Returns 1 (True) if <object> is a member of <class>.

•	Returns 0 (False) if <object> is not a member of <class>.

Tips

•	Use IsKindOf to test if an object is an instance, or an instance of a subclass, of a specified class.

•	To find out an object's class, use GetClassName.


Example

The following example tests whether an object is either an instance of MyLabel or an instance of a subclass of MyLabel. If True, the example sets the object's background color to red.

Function OnLButtonDblClk ( )

Dim MyLabel As AcLabelControl, Msg As String

Set MyLabel = New AcLabelControl

If IsKindOf(MyLabel, "AcLabelControl") Then

Msg = "Yes, MyLabel is an AcLabelControl.  "

Msg = Msg & "We will now set its background color to red."

MsgBox Msg

MyLabel.BackgroundColor = Red

End If

End Function

For information about using the code examples, see Using the code examples.


See also

GetClassID function

GetClassName function


IsNull function

Example   See also

Reports whether the given Variant or Variant expression contains the Null value.

Syntax

IsNull(<exprs>)

<exprs>

Variant expression to test. Any expression that contains a Null is itself Null and therefore False. That is why both the following expressions evaluate to False, no matter what value MyVar contains.

If MyVar = Null
If MyVar <> Null

Examples:

Assuming you have assigned the Null value to MyVar, the following statements are equivalent. Each returns 1 (True).

IsNull(MyVar)

IsNull(MyVar = Null)

IsNull(MyVar <> Null)

IsNull(MyVar + 5000)

Return value

Integer

•	Returns 1 (True) if <exprs> contains the Null value. Otherwise, returns 0 (False).

•	The only way to determine whether a variable contains Null is to use IsNull.

Tip

Empty and Null are different. If a variable contains the Empty value, it means it has never yet been assigned any value. A variable can contain the Null value only if you have explicitly assigned Null to it.


Example

The following example tests MyVar to determine whether it contains the Null value. The variable MyVar is first initialized to Null but the first time though the loop it is changed to a zero-length string. The second time through the loop, MyVar is again set to Null and the loop exits.

Function OnLButtonDblClk()

Dim MyVar

' Initialize variable as Null

MyVar = Null

Do

' Evaluate variable

If IsNull(MyVar) Then

' Report if Null

MsgBox "MyVar is Null."

' Assign zero-length string

MyVar = ""

Else

' Report if not Null

MsgBox "MyVar is not Null."

' Assign Null to variable

MyVar = Null

End If

' Loop until MyVar is Null

Loop Until IsNull(MyVar)

End Function

For information about using the code examples, see Using the code examples.


See also

IsDate function

IsEmpty function

IsNumeric function

VarType function


IsNumeric function

Example   See also

Tests whether the type of a variable is or can be converted to Integer, Long, Single, Double, or Currency.

Syntax

IsNumeric(<exprs>)

<exprs>

Variant expression to test to be determined whether it is, can be evaluated as, or can be converted to a numeric data type. For example, the following are equivalent. Each returns 1 (True).

IsNumeric("34040")

IsNumeric(34040)

IsNumeric(Val("343Haydn"))

Return value

Integer

•	Returns 1 (True) if <exprs> can be converted to a number. Otherwise, returns 0 (False).

•	Returns 1 (True) if <exprs> is Empty.

•	Returns 0 (False) for any <exprs> assigned to InputBox no matter what type of data the user supplies in response to the InputBox prompt.

Tip

To extract a numeric value from a string that starts with numbers but also contains non-numeric characters, use Val.


Example

The following example inspects each of four elements in an array of mixed types and reports whether or not the content of the variable is numeric.

Function OnLButtonDblClk()

Dim UserVar(4), Msg, Slot As Integer

UserVar(1) = 12

UserVar(2) = "twelve"

UserVar(3) = "123four"

UserVar(4) = Val("123four")

For Slot = 1 to 4

If IsNumeric(UserVar(Slot)) Then

Msg = UserVar(Slot) & "is Numeric."

Else

Msg = UserVar(Slot) & "is not Numeric."

End If

MsgBox Msg

Next Slot

End Function

For information about using the code examples, see Using the code examples.


See also

IsDate function

IsEmpty function

IsNull function

Val function

VarType function


IsPersistent function

See also

Reports whether an instance of an object is persistent or transient.

Syntax

IsPersistent(<object>)

<object>

The variable name that refers to the object about which you want information.

Return value

Integer

•	Returns 1 (True) if <object> is persistent.

•	Returns 0 (False) if <object> is transient.


See also

NewInstance function

NewPersistentInstance function


Kill statement

Example   See also

Deletes a specified file or files from a disk.

Syntax

Kill <file spec>

<file spec>

String expression that specifies the name or names of the file or files to be deleted. Wildcard characters can be used. Can include optional drive and path information.

Default path: Current default drive and directory.

Rules:

•	Indicated file or files must exist.

•	Path, if specified, must exist.

•	Indicated file must not currently be open by Actuate Basic.

<file spec> may optionally specify full path information, in which case it has the following syntax:

[<drive:>] [ \ ]<directory>[\<directory>]...<file spec> (Windows)

[/]<directory>[/<directory>]...<file spec> (UNIX)

<drive:>

Character, followed by a colon, that specifies the drive where <file spec> is located (Windows only).

<directory>

String expression that specifies the name of a directory or subdirectory where <file spec> is located.

Example:

The following statement will delete all files in the Windows directory C:\DISCARD that have an extension of DOC.

Kill C:\DISCARD\*.DOC

Description

Kill is similar to the operating system commands ERASE and DEL.

Tips

•	Be careful in how you use Kill, especially if you include wildcard characters in <file spec>. It is easy to delete files unintentionally, and Kill is irreversible.

•	To delete directories, use RmDir.


Example

The following example prompts the user for a file or files to delete, verifies the delete request, then performs the operation if it can; if it cannot, it issues an error message.

Function OnLButtonDblClk()

Dim MakeSure As Integer, ChuckFile As String, Msg As String

' Set up error handler

On Error GoTo Errhandler55

' Get user input

Msg = "Type the full pathname of the file you want to delete."

ChuckFile = UCase$(InputBox(Msg))

' Verify file to delete -- if the user has changed mind, immediately exit

If Len(ChuckFile) <= 0 Then

Msg = "You did not enter a file name."

MsgBox Msg

Exit Function

Else

Msg = "Sure you want to delete " & ChuckFile & "?"

MakeSure = MsgBox(Msg, MB_YESNO)

' User chose Yes

If MakeSure = IDYES Then

Msg = "Deleting " & ChuckFile & " from your disk."

' Delete file

Kill ChuckFile

Else

Msg = ChuckFile & " was not deleted."

End If

End If

MsgBox Msg

Exit Function

Errhandler55:

MsgBox "Error number " & Err & " occurred. " & Error$(Err)

' "Path not Found"

If Err = 48 Then

Msg = "Sorry, the file you named could not be found."

Else

Msg = "Sorry, unable to delete file.  May be open."

End If

Resume Next

End Function

For information about using the code examples, see Using the code examples.


See also

Name statement


LBound function

Example   See also

Returns the smallest available subscript for the given dimension of an array.

Syntax

LBound(<array name>[,<dimension>])

<array name>

Name of an array variable.

<dimension>

Numeric expression that specifies the array dimension for which you want to determine the lower bound.

Rules:

•	If you do not supply a <dimension>, Actuate Basic defaults to 1.

•	Use 1 for the first dimension, 2 for the second, and so on.

•	Must not be larger than the total number of dimensions in <array name>.

•	Must not be zero, negative, or Null.

For example, the table below shows the values LBound returns for an array with these dimensions:

Dim MyArray(1 To 55, 0 To 27, -3 To 42)

Statement	Returned value
LBound(MyArray, 1)	1
LBound(MyArray, 2)	0
LBound(MyArray, 3)	-3
Return value

Integer

Rule: If <dimension> is not an Integer, LBound rounds <dimension> to the nearest Integer before evaluating it.

Tips

•	To determine the upper bound of an array, use UBound.

•	To determine the total number of elements in a given dynamic array dimension, take the value returned from UBound, subtract the value returned from LBound, and then add 1.


Example

The following example determines the lower bounds of an array of 3 dimensions. The use of Rnd simulates changes in lower bounds that the user can make at runtime.

Function OnLButtonDblClk()

Dim First As Integer, Sec As Integer, Third As Integer

Dim Msg As String, NL As String, TabChar As String

' Declare array

Dim MyArray()

' Define newline, tab

NL = Chr(10): TabChar = Chr(9)

' Generate random dimensions between 3 and 16 for array size.

' First dimension

First = Int(14 * Rnd + 3)

' Second dimension

Sec = Int(14 * Rnd + 3)

' Third dimension

Third = Int(14 * Rnd + 3)

' Set dimensions

ReDim MyArray(First To 30, Sec To 30 , Third To 30)

Msg = "MyArray has the following lower bounds: " & NL

Msg = Msg & TabChar & "Dimension 1 ---> " & LBound(MyArray, 1) & NL

Msg = Msg & TabChar & "Dimension 2 ---> " & LBound(MyArray, 2) & NL

Msg = Msg & TabChar & "Dimension 3 ---> " & LBound(MyArray, 3)

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

UBound function

Dim statement


LCase, LCase$ functions

Example   See also

Converts all uppercase alphabetic characters in a string to lowercase.

Syntax

LCase(<string exprs>)

LCase$(<string exprs>)

<string exprs>

String expression to convert to lowercase characters.

For example, the following statements are equivalent. Each returns "6 jane street, 2nd fl".

LCase$("6 JANE STREET, 2ND FL")

LCase$("6 Jane Street, 2nd Fl")

LCase$("6 jAn" & "E sTreeT, 2nD fL")

Return value

LCase: Variant

LCase$: String

•	If <string exprs> contains no uppercase alphabetic characters, LCase[$] returns <string exprs> unchanged.

•	LCase[$] has no effect on non-alphabetic characters in <string exprs>.

Tips

•	To ensure uniformity in the data you get from the user so that name strings like "MacManus," "Macmanus," or "macMaNus" are always sorted, or compared, or otherwise treated in the same way, first convert strings using LCase[$] or UCase[$].

•	To convert alphabetic characters in <string exprs> to uppercase, use UCase[$].


Example

The following example renders a customer's name in lowercase.

Function OnLButtonDblClk ( )

Dim LowerCase As String, UserInput As String, Msg As String

UserInput = InputBox("Please type a customer's name.")

' Convert to lowercase

LowerCase = LCase$(UserInput)

Msg = "LCase$ converts """ & UserInput & """ to """

Msg = Msg & LowerCase & """."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

UCase, UCase$ functions


Left, Left$ functions

Example   See also

Returns a segment of a Variant or String, starting at the leftmost character.

Syntax

Left(<string exprs>, <length>)

Left$(<string exprs>, <length>)

<string exprs>

Source string. It can be a variable string, a literal string, a string constant, the return value of any function that returns a String, or a Variant that can evaluate to a String.

<length>

Numeric expression that specifies how many characters to copy from the left of <string exprs>.

Rules:

•	Must be an Integer or expression of type Long.

•	Must be between 0 and 2,147,483,647.

The following statements are equivalent. Both return "Widget".

Left$("Widget",6)

Left$("Widget",99)

Return value

Left: Variant

Left$: String

•	If <length> = 0, returns a zero-length string.

•	If <length> is greater than or equal to the length of <string exprs>, returns an exact copy of <string exprs>.

Tips

•	Use Len to find the number of characters in <string exprs>.

•	Use InStr to find the position of a specified character in <string exprs>.


Example

The following example asks the user to input a customer's first and last names, then returns the first name.

Function OnLButtonDblClk()

Dim FName As String, Msg As String, LName As String

Dim SpacePos As Integer, UserInput As String

Msg = "Enter a client's first and last name, separated by a space."

' Get user's input

UserInput = InputBox(Msg)

' Find the space

SpacePos = InStr(1, UserInput, " ")

If SpacePos Then

' Get first and last name

FName = Left$(UserInput, SpacePos - 1)

LName = Right$(UserInput, Len(UserInput) - SpacePos)

Msg = "The first name is """ & FName & "." & """"

Msg = Msg & " The last name is """

Msg = Msg & LName & "." & """"

Else

Msg = "You did not enter a first and last name!"

End If

' Display the message

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

InStr function

Len function

Mid, Mid$ functions

Right, Right$ functions


LeftB, LeftB$ functions

Example   See also

Returns a segment of a Variant or String, starting at the leftmost byte.

Syntax

Left (<string exprs>, <length>)

Left$(<string exprs>, <length>)

<string exprs>

Source string. It can be a variable string, a literal string, a string constant, the return value of any function that returns a String, or a Variant that can evaluate to a String.

<length>

Numeric expression that specifies how many bytes to copy from the left of <string exprs>.

Rules:

•	Must be an Integer or expression of type Long.

•	Must be between 0 and 2,147,483,647.

In the following example, the statements are equivalent. Both simply return "Widget".

LeftB$("Widget",6)

LeftB$("Widget",99)

Return value

LeftB: Variant

LeftB$: String

•	If <length> = 0, returns zero-length string.

•	If <length> is greater than or equal to the length of <string exprs>, returns an exact copy of <string exprs>.

Tip

•	Use LenB to find the number of bytes in <string exprs>.

•	Use InStrB to find the position of a specified byte in <string exprs>.


Example

The following example asks the user to input a customer's first and last names, then returns the first name.

Function OnLButtonDblClk ( )

Dim FName As String, Message As String, LName As String

Dim SpacePos As Integer, UserInput As String

Message = "Type a client's first and last names separated by a space."

' Get user's input

UserInput = InputBox(Message)

' Find the space

SpacePos = InStr(1, UserInput, " ")

If SpacePos Then

' Get first and last name

FName = LeftB$(UserInput, SpacePos - 1)

LName = RightB$(UserInput, LenB(UserInput) - SpacePos)

Message = "The first name is """ & FName

Message = Message & "." & """" & " The last name is """

Message = Message & LName & "." & """"

Else

Message = "You did not type first and last names!"

End If

' Display the message

MsgBox Message

End Function

For information about using the code examples, see Using the code examples.


See also

InStrB function

LenB function

MidB, MidB$ functions

RightB, RightB$ functions


Len function

Example   See also

Returns the number of characters in a string expression.

Syntax

Len(<string exprs>)

Len(<variable name>)

<string exprs>

String expression to test for character length.

<variable name>

Variable to test for character length.

Examples:

The following example returns 11.

Len("Smith, John")

The following example, which tests "MyVar" (a 4-byte Integer), returns 4.

Len(MyVar)

Return value

Integer

•	No matter what its value, if <variable name> is of any numeric data type except Variant, Len returns the number of characters required to store any variable of that data type.

•	No matter what its Variant type, if <variable name> is a Variant, Len returns the number of characters required to store it as a String.

•	If <string exprs> or <variable name> is Null, Len returns Null.

Tip

Use Len to determine record size when you perform file input/output with random-access files using user-defined variable types. Please note that Actuate Basic does not notice a type mismatch if you dimension a variable (such as "UserInput") as a String, and then later test it as an Integer (such as "If UserInput = 0).


Example

The following example returns the length of the user's name.

Function OnLButtonDblClk()

Dim UserInput As String, Msg as String

' Get user input

UserInput = InputBox("Please type your name.")

' Test the user input and continue only if it's not empty

If Len(UserInput) <= 0 then

Msg = "Maybe another time!"

MsgBox Msg

Exit Function

End if

Msg = "Your name is " & Len(UserInput) & " characters long, "

Msg = Msg & "including the space(s)."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

LenB function

VarType function

Type...End Type statement


LenB function

Example   See also

Returns the number of bytes in a string expression.

Syntax

LenB(<string exprs>)

LenB(<variable name>)

<string exprs>

String expression to test for byte length.

<variable name>

Variable to test for byte length.

Examples:

The following example returns 11.

LenB("Smith, John")

The following example, which tests "MyVar" (a 4-byte Integer), returns 4.

LenB(MyVar)

Return value

Integer

•	No matter what its value, if <variable name> is of any numeric data type except Variant, LenB returns the number of bytes required to store any variable of any value that is of the same data type.

•	No matter what its Variant type, if <variable name> is Variant, LenB returns the number of bytes required to store it as a String.

•	If <string exprs> or <variable name> is Null, LenB returns Null.

Tip

To determine record size when you perform file input/output with random-access files using user-defined variable types, use LenB.


Example

The following example returns the number of bytes needed to store each of the fundamental data types. Note that whatever integer you input, none of these values change except the last two.

Sub LenBFuncUser()

Dim IntVar%, LongVar&

Dim SingleVar!, DoubleVar#

Dim CurrVar@, DynamicVar, UserNum, Mercurial

Dim Msg, NL

NL = Chr(10)	'Define newline.

UserNum = InputBox("Please, enter an integer less than 10000 please. ")

IntVar% = UserNum	'Integer

LongVar& = IntVar%  ' Long integer

SingleVar! = LongVar&	'Single-precision, floating

DoubleVar# = SingleVar!	'Double-precision, floating

CurrVar@ = DoubleVar#	'Currency

Mercurial = CurrVar@	'Variant

Msg = "Integer values are stored using " & LenB(IntVar%) & " bytes."

Msg = Msg & NL & "Long integer values are stored using "

Msg = Msg & LenB(LongVar&) & " bytes." & NL

Msg = Msg & "Single-precision values are stored using "

Msg = Msg & LenB(SingleVar!) & " bytes." & NL

Msg = Msg & "Double-precision values are stored using "

Msg = Msg & LenB(DoubleVar#) & " bytes." & NL

Msg = Msg & "Currency values are stored using "

Msg = Msg & LenB(CurrVar@) & " bytes." & NL

Msg = Msg & "This Variant requires "

Msg = Msg & LenB(Mercurial) & " bytes to store it as a string." & NL

Msg = Msg & "This message contains more than "

Msg = Msg & LenB(Msg) & " characters."

MsgBox Msg

End Sub

For information about using the code examples, see Using the code examples.


See also

Len function

VarType function

Type...End Type statement


Let statement

Example   See also

Assigns a value to a variable.

Syntax

[Let] <variable> = <exprs>

<variable>

The name of any variable to store <exprs>.

<exprs>

String or numeric expression to assign to <variable>.

Rules:

•	If <exprs> is Variant, and <variable> is numeric, Actuate Basic converts <exprs> to a number, if possible, before assigning it to <variable>.

•	If <exprs> is numeric, its value must fall into the range of the data type of <variable>.

Examples:

The following statements are equivalent.

Let N = 50

N = 50

The following example generates an error, because 2,147,483,647 is the upper limit of the range of the Integer data type variable to which it is being assigned.

N% = 2147483648

Description

In some older versions of BASIC, the Let keyword is required to begin a statement that assigns a value to a variable. In Actuate Basic, the use of Let is optional.

Rules

•	If <variable> is a user-defined type declared with Type, <exprs> must be of the same user-defined type.

•	The data types of <variable> and <exprs> must be compatible.

•	In addition to the data type compatibilities listed in the table below, you can assign Null to numeric, String, Variant, or CPointer variables.

	Data type of <variable>	Valid data types for <exprs>
	Numeric	Numeric  Variant that will convert to a numeric data type
	String	String  Non-Null Variant
	Variant	String Numeric Variant
	CPointer	CPointer
Tips

•	Use IsNumeric to determine if a Variant variable converts to numeric.

•	To make assignments between variables of different user-defined types that have been defined by Type...End Type, use LSet or the = operator. Using the = operator to assign an <exprs> of one data type to a <variable> of a different type converts the value of <exprs> into the data type of <variable>.


Example

The following example uses Let to assign a value to Pi.

Function OnLButtonDblClk()

Dim Msg As String, Pi As Double

' Assign a value to Pi with the Let statement

Let Pi = 4 * Atn(1)

' Assign a value to Msg without Let statement

Msg = "The area of a circle of radius 3 inches is "

Msg = Msg & (Pi * (3^2)) & " inches."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

IsNumeric function

Const statement

LSet statement


Line Input # statement

Example   See also

Reads from a sequential file until it reaches a carriage-return-linefeed (CRLF) pair or the end of the file (EOF), and assigns the information to a variable.

Syntax

Line Input #<file number>, <receiving variable>

<file number>

Numeric expression that is the file number assigned to the target file when it was Opened in the Input mode.

<receiving variable>

String or variant expression to which Line Input # assigns the data it reads from the target file.

Example:

The following example reads one line of data from "NOTES.TXT" into the variable A$.

Open "NOTES.TXT" for Input As #2

Line Input #2, A$

The following example reads the first line of "POEM.TXT" into the variable A$, the second line into B$, and the third into C$.

Open "POEM.TXT" for Input As #1

Line Input #1, A$

Line Input #1, B$

Line Input #1, C$

Description

Line Input # reads data from a sequential file one line at a time.

Unlike Input #, Line Input # treats commas, spaces, and quotes no differently than it does any other characters. It is useful for reading plain ASCII files. Line Input # stops reading into <receiving variable> when it encounters a carriage-return-linefeed character-pair (CRLF). It skips the carriage-return-linefeed character-pair itself and--assuming it is called again--continues reading from the first character after the CRLF until it reaches another CRLF or the end of the file (EOF).

Rules

•	<file number> must match the number of a currently open file.

•	The number sign (#) preceding <file number> is required.

•	The file corresponding to <file number> must be open under the Input mode.

•	You must have write access to the open file. That is, the file must not have been opened using a Lock Read or Lock Read Write clause.


Example

The following example reads and displays the first five lines of the user's CONFIG.SYS file.

Function OnLButtonDblClk()

Dim Msg As String, NL As String, Lyne As String, N As Integer

' Define newline

NL = Chr$(10)

Msg = "The first 5 lines of your CONFIG.DOS are: " & NL

Open "C:\CONFIG.DOS" For Input As #1

For N = 1 To 5

' Get the Nth line

Line Input #1, Lyne

' Save the line

Msg = Msg & Lyne & NL

Next N

' Close file

Close #1

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Input # statement

Open statement

Print # statement


Loc function

Example   See also

Returns the current position in an open file.

Syntax

Loc(<file number>)

<file number>

Numeric expression that is the file number used to open the file with Open statement.

Rule: File must be open.

Return value

Integer

•	For Sequential files: Returns the current byte position in the file divided by 128.

•	For Random files: Returns the number of the last variable read from or written to the file.

•	For Binary mode files: Returns the position of the last byte read or written.

Tip

You can open sequential files with a buffer of a different size if you use the Len parameter in Open. However, this does not change the result of Loc, which always divides by 128 when applied to sequential files.


Example

In the following example, the program opens a test file and asks the user how much of it to read. Then it reports the current position in the file.

Function OnLButtonDblClk ( )

Dim CountVar As Integer, UserMsg As String

Dim NL As String, NowLoc As Integer, TempVar, MaxNum

' Define newline

NL = Chr$(10)

Randomize Timer

' Open file for output

Open "TESTDATA.FIL" For Output As #1

' Generate rnd values

For CountVar = 1 To 300

' Put data in file

Print #1, CountVar

Next CountVar

' Close test file

Close #1

'

' Open file just created

Open "TESTDATA.FIL" For Input As #1

MaxNum = InputBox("How many items to read?  Type a # from 1 to 299.")

For CountVar = 1 To MaxNum

' Read some data from it

Input #1, TempVar

Next CountVar

' Find location in file

NowLoc = Loc(1)

' Close file

Close #1

UserMsg = MaxNum & " data elements have been read from a file of 300. "

UserMsg = UserMsg & "The current location in the TESTDATA.FIL file is:  "

UserMsg = UserMsg & NowLoc & "." & NL & NL

UserMsg = UserMsg & "Choose OK to delete the sample file."

MsgBox UserMsg

' Delete file from disk

Kill "TESTDATA.FIL"

End Function

For information about using the code examples, see Using the code examples.


See also

EOF function

LOF function

Open statement


Lock...Unlock statement

Example   See also

Prohibits access by other users or processes to all or part of an open file.

Syntax

Lock [#]<open file number> [,{<record> | [<start>] To <end>} ]

[<data process statements>]

Unlock [#]<open file number> [,{<record> | [<start>] To <end>} ]

<open file number>

Numeric expression that is the file number you used to Open the target file.

Rules for <open file number>:

•	Must be the number of a currently open file.

•	The number sign (#) before <open file number> is required.

<record>

Numeric expression that specifies the number of the record or byte to lock.

Rules for <record>:

•	Must be between 1 and 2,147,483,647.

•	Record length cannot exceed 65,535 bytes.

<start>

Numeric expression that specifies the number of the first record or byte to lock.

Default: 1

To

Keyword that separates <start> from <end> in the clause that specifies a range of records or bytes to lock.

<end>

Numeric expression that specifies the number of the last record or byte to lock.

The terms <record>, or <start> and <end> specify different things according to the mode under which the target file was opened. The following table summarizes these differences.

File mode	<record>, or <start> and <end> refer to
Binary	The number of a byte relative to the beginning of the open file. The first byte in a file is byte 1.
Random	The number of a record relative to the beginning of the open file. The first record is record 1.
Sequential Input or Output	The entire file, no matter what range you specify with <start> To <end>.
<data process statements>

One or more valid Actuate Basic statements that direct the operations your program performs on the open file while others are temporarily locked out.

Examples:

In the following example, Lock restricts other users or processes from accessing any part at all of the file previously opened as #1. When processing of the file is done, Unlock lifts those restrictions.

Lock #1

[<data process statements>]

Unlock #1

The following Lock...Unlock statement block prohibits and then permits others' access to just a single record, namely the 112th in the random access file MAILLIST.DAT

Open "MAILLIST.DAT" for Random As #1 Len = 32

Lock #1, 112

[<data process statements>]

Unlock #1, 112

The following Lock...Unlock statement block locks and then unlocks others' access to byte positions 11 through 25, inclusive, of the binary file TESTFILE.DAT.

Open "TESTFILE.DAT" For Binary As #1

Lock #1, 11 TO 25

[<data process statements>]

Unlock #1, 11 TO 25

The following Lock...Unlock statement block locks and then unlocks byte positions 1 through 229, inclusive, of the binary file TESTFILE.DAT.

Open "TESTFILE.DAT" For Binary As #1

Lock #1, TO 229

[<data process statements>]

Unlock #1, TO 229

Description

•	Lock restricts multiuser access to a specified area of a file. When you lock part of the file or the whole file, no other user on a network can access it until you Unlock the file or file segment.

•	Lock and Unlock apply only to files opened with Open by Actuate Basic. They do not apply to Access databases.

Rules

•	The parameters for Lock and Unlock in a Lock...Unlock statement must match exactly.

•	If you use Lock to restrict access to a file, you must Unlock the file before you close that file or terminate your program.

•	You cannot use Lock...Unlock with versions of MS-DOS earlier than 3.1.

•	If you do use MS-DOS, and SHARE.EXE is not already loaded, you must exit Actuate Basic and run SHARE.EXE under DOS to enable locking operations before you can use Lock...Unlock.

Tips

•	Use Lock...Unlock in networked environments, in which several users or processes might need access to the same file.

•	Use Lock...Unlock to ensure that two users simultaneously updating a database record do not accidentally save old data on top of new.


Example

The following example creates a sample data file, and accesses a single record (RecNum) which is locked to other users while the record is being updated. Access is permitted again when the update is complete. In this example OnLButtonDblClk( ) is overridden to create the sample data file and later prompt the user to delete the test file. To use this example, paste the Declare statement and the procedure MakeDataFile1216( )at or near the beginning of your Actuate Basic source code (.BAS) file. Make sure the Declare statement is pasted at or near the beginning of the .BAS file.

Declare

Type AcctRecord

Payer As String

Address As String

City As String

Owe As Currency

End Type

End Declare

'

Sub MakeDataFile1216()

Dim CustRecord As AcctRecord

Open "TESTFILE" For Random Shared As #1 Len = 60

' Put information in each field of the record

CustRecord.Payer = "Emilio Enbilliam"

CustRecord.Address = "6 Jane Street"

CustRecord.City = "New York, NY"

' Initialize amount owed

CustRecord.Owe = 12

'Put record in file

Put #1, 1, CustRecord

' Close the file

Close #1

End Sub

Function OnLButtonDblClk ( )

Dim CustRecord As AcctRecord

Dim Change As String, Msg As String, NL As String, RecNum As Integer

' Define newline

NL = Chr$(10)

' Set up error handler

On Error GoTo ErrorHandler

' Create sample data file

MakeDataFile1216

Open "TESTFILE" For Random Shared As #1 Len = 60

Do

' There is only one record, lock the current record

RecNum = 1

Lock #1, RecNum

' Read a record

Get #1, RecNum, CustRecord

Msg = "Customer " & CustRecord.Payer

Msg = Msg & " currently owes: "

Msg = Msg & Format(CustRecord.Owe, "$#,##0.00") & NL & NL

Msg = Msg & "Please type the net change (+ or - )"

' Show data and get change

Change = InputBox(Msg)

If Len(Change) = 0 Then Change = 0

CustRecord.Owe = CustRecord.Owe + Change

' Update record

Put #1, RecNum, CustRecord

' Unlock the record

Unlock #1, RecNum

Loop Until Change = 0

' Close the file

Close #1

Cleanup:

Msg = "Transaction complete. Choose OK to delete the sample "

Msg = Msg & "data file."

MsgBox Msg

' Remove file from disk

Kill "TESTFILE"

Exit Function

ErrorHandler:

' Permission denied error

If Err = 70 Then

Msg = "Sorry, you must run SHARE.EXE before running this example. Exit "

Msg = Msg & "Actuate Basic, Exit Windows, run SHARE.EXE, and "

Msg = Msg & "reenter Actuate Basic to run this example. Do not "

Msg = Msg & "shell to DOS and run SHARE.EXE or you may not be "

Msg = Msg & "able to run other programs until you reboot."

' Some other error occurred

Else

Msg = "Error " & Err & " occurred."

End If

' Display error message

MsgBox Msg

' Close files, flush buffers

Reset

' Do an orderly exit

Resume Cleanup

End Function

For information about using the code examples, see Using the code examples.


See also

Get statement

Open statement

Put statement


LOF function

Example   See also

Returns the size of an open file in bytes.

Syntax

LOF(<open file number>)

<open file number>

Numeric expression that is the file number you used to Open to open the target file.

Rules for <open file number>:

•	Must be the number of a currently open file.

•	Must refer to a disk file.

Examples:

The following example opens an existing disk file named TEST.FIL and then uses LOF to determine its size in bytes.

Open "TEST.FIL" FOR Input As #1

SizeOfFile = LOF(1)

Return value

Integer

Tip

To determine the length of a file that is not open, use FileLen.


Example

The following example creates a test file on disk that contains some random numbers. The procedure then reopens the test file and reports its length. In this example OnLButtonDblClk( ) is overridden to generate the test file and prompt the user to delete the test file. The procedure MakeDataFile0314( ) should be typed after the End Function of the OnLButtonDblClk( ) procedure or pasted into your Actuate Basic source code (.BAS) file.

Function OnLButtonDblClk ( )

Dim Msg As String, NL As String, FileLength

' Define newline

NL = Chr$(10)

' Create sample data file

MakeDataFile0327

' Open newly created file

Open "TEST.FIL" For Input As #1

' Get length of file

FileLength = LOF(1)

' Close test file

Close #1

Msg = "The length of the TEST.FIL file just created is "

Msg = Msg & FileLength & " bytes." & NL & NL

Msg = Msg & "Choose OK to delete the sample data file."

MsgBox Msg

' Delete test file

Kill "TEST.FIL"

End Function

Sub MakeDataFile0327()

Dim I As Integer

' Open file for output

Open "TEST.FIL" For Output As #1

' Generate values 0-250

For I = 0 To 250

Print #1, I

Next I

' Close test file

Close #1

End Sub

For information about using the code examples, see Using the code examples.


See also

EOF function

FileLen function

Loc function

Open statement


Log function

Example   See also

Gives the natural logarithm for a number.

Syntax

Log(<number>)

<number>

Numeric expression or Variant of VarType 8 (String) for which you want to find the logarithm.

Rule for <number>: <number> must be greater than 1.

Return value

Double

Rule: If <number> evaluates to Null, Log returns a Null.

Tips

•	To calculate logarithms in a base other than e, use Log(<number> divided by Log(<base>), where <base> is the number of the desired base other than e.

•	Log is the inverse of Exp.


Example

The following prompts the user for a number, and returns the natural logarithm for that number.

Function OnLButtonDblClick ( )

On Error Goto ErrorHandler

Dim UserNum, Msg As String

UserNum = InputBox("Please type a number.")

Msg= "The log (base e), or Log(" & UserNum & ") is "

Msg= Msg & Log(UserNum)

MsgBox Msg

Exit Function

ErrorHandler:

MsgBox "Actuate Basic error:  " & Err & " -- " & Error$(Err)

MsgBox "Sorry!  An error occurred.  Please try again."

Resume Next

End Function

For information about using the code examples, see Using the code examples.


See also

Exp function


LSet statement

Example   See also

Left-aligns a string within the space of a string variable.

Syntax

LSet <string variable> = <string exprs>

<string variable>

Name of a string variable in which LSet stores the left-aligned <string exprs>.

<string exprs>

String expression that you want LSet to left-align within <string variable>.

The behavior of LSet depends upon whether <string exprs> is shorter or longer than <string variable>.

<string exprs>	Behavior of LSet
Shorter than <string variable>	Left-aligns <string exprs> within <string variable>. Replaces any leftover characters in <string variable> with spaces.
Longer than <string variable>	Places only the leftmost characters, up to the length of the <string variable>, in <string variable>. Truncates characters beyond the length of <string variable> from the right.
Description

Used for left-aligning a string expression within a variable.


Example

The code in the following example left-aligns text within a 20-character String variable.

Function OnLButtonDblClk ( )

Dim Msg, NL, TmpStr As String

' Define newline

NL = Chr(10)

' Create 20-character string

TmpStr = String(20, "*")

Msg = "The following two strings that have been right"

Msg = Msg & NL & "and left justified in a " & Len(TmpStr)

Msg = Msg & "-character string." & NL & TmpStr & NL

' Right justify

RSet TmpStr = "Right->"

Msg = Msg & TmpStr & NL

' Left justify

LSet TmpStr = "<-Left"

Msg = Msg & TmpStr & NL

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

RSet statement


LTrim, LTrim$ functions

Example   See also

Returns a copy of a string expression after removing leading spaces.

Syntax

LTrim(<string exprs>)

LTrim$(<string exprs>)

<string exprs>

String from which LTrim[$] strips leading spaces. Leading spaces are any spaces that occur before the first non-space character in a string. <string exprs> must be a variable string, a literal string, a string constant, the return value of any function that returns a string, or a Variant that can evaluate to a String.

Return value

LTrim: Variant

LTrim$: String

A copy of <string exprs> with leading spaces removed. If there are no leading spaces, LTrim$ simply returns <string exprs>.

Tips

•	Use Trim$ to simultaneously strip both leading and trailing spaces in a string.

•	Use InStr to find spaces in the middle of a string.


Example

The following example uses LTrim$ to strip leading spaces from a string variable, while RTrim$ is used to strip trailing spaces.

Function OnLButtonDblClk ( )

Dim Msg As String, NL As String

Dim CustName As String, CustName1 As String

' Define newline

NL = Chr(10)

CustName = "  Harold Pinter  "

' Strip spaces

CustName1 = LTrim$(RTrim$(CustName))

Msg = "The original customer name " & NL & "'"

Msg = Msg & CustName & "'" & NL & " ...was "

Msg = Msg & Len(CustName) & " characters long. There were two "

Msg = Msg & "leading spaces and two trailing spaces." & NL & NL

Msg = Msg & "The name returned after stripping the spaces "

Msg = Msg & "is:" & NL & "'" & CustName1

Msg = Msg & "'" & NL & "...and it contains only "

Msg = Msg & Len(CustName1) & " characters."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

InStr function

RTrim, RTrim$ functions


Mid, Mid$ functions

Example   See also

Returns specified portion of a string expression.

Syntax

Mid(<string exprs>, <start>[,<length>])

Mid$(<string exprs>, <start>[,<length>])

<string exprs>

Source string from which you are copying a portion. It can be a variable string, a literal string, a string constant, the return value of any function that returns a string, or a Variant that can evaluate to a String.

<start>

Integer that specifies the position within a <string exprs> where copy begins.

Rule: Must be between 1 and 2,147,483,647, inclusive.

<length>

Integer indicating how many characters to copy.

Rules for <length>:

•	If <length> is omitted, Actuate Basic uses all characters from <start> to the end of <string exprs>.

•	Must be between 0 and 2,147,483,647.

Examples:

•	The following examples are equivalent.

Mid$("Widget",4,3)

Mid$("Widget",4)

•	The following example returns "Widget".

Mid$("Widget",1,99)

Return value

Mid: Variant

Mid$: String

•	If <start> is greater than length of <string exprs>, returns zero-length string.

•	If <length> = 0, returns zero-length string.

•	If <length> is greater than length of <string exprs>, returns only the characters up to the length of <string exprs>.

Tip

Use Len to find the number of characters in <string exprs>.


Example

In the following example, Mid[$] returns the middle word from a variable containing three words.

Function OnLButtonDblClk ( )

Dim MiddleWord, Msg, TestStr

Dim SpacePos1, SpacePos2, WordLen

' Create text string

TestStr = "Mid function Example"

' Find first space

SpacePos1 = InStr(1, TestStr, " ")

' Find next space

SpacePos2 = InStr(SpacePos1 + 1, TestStr, " ")

' Calc 2nd word length

WordLen = (SpacePos2 - SpacePos1) - 1

' Find the middle word

MiddleWord = Mid(TestStr, SpacePos1 + 1, WordLen)

Msg = "The word in the middle of TestStr is """ & MiddleWord & """"

MsgBox Msg, 0, TestStr

End Function

For information about using the code examples, see Using the code examples.


See also

Left, Left$ functions

Len function

Right, Right$ functions


Mid, Mid$ statements

Example   See also

Replaces a segment of a string with another string.

Syntax

Mid(<string variable>,<start>[,<length>]) = <string exprs>

Mid$(<string variable>,<start>[,<length>]) = <string exprs>

<string variable>

String expression or Variant variable to modify.

Rule for <string variable>: Cannot be a literal, function, or other expression.

<start>

Position in <string variable> at which replacement text begins. The position of the first character is 1.

Rule for <start>: Must be between 1 and 2,147,483,647, inclusive.

<length>

Number of characters from <string exprs> to use.

Default: Unchanged <string exprs>.

Rules for <length>:

•	Must be between 1 and 2,147,483,647, inclusive.

•	No matter how large you specify <length> to be, the resulting string is never longer than <string variable>.

<string exprs>

String expression that replaces segment of <string variable>. It can be a variable-length string, a literal string, a string constant, the return value of any function that returns a string, or a Variant that can evaluate to a String.

Rule for <string exprs>: Cannot entirely replace <string variable> with a shorter <string exprs>.


Example

The following example replaces part of the string "FREUDIAN" with all or part of "Jung" in the variable "Hillman".

Function OnLButtonDblClk()

Dim Hillman As String

Hillman = "FREUDIAN"

' now Hillman = "JungDIAN"

Mid$(Hillman,1,5) = "Jung"

MsgBox Hillman

Hillman = "FREUDIAN"

' same result, "JungDIAN"

Mid(Hillman,1,4) = "Jung"

MsgBox Hillman

Hillman = "FREUDIAN"

' now Hillman = "JunUDIAN"

Mid$(Hillman,1,3) = "Jung"

MsgBox Hillman

Hillman = "FREUDIAN"

' now Hillman = "FREUJung"

Mid(Hillman,5) = "Jung"

MsgBox Hillman

End Function

For information about using the code examples, see Using the code examples.


See also

Left, Left$ functions

Mid, Mid$ functions

Right, Right$ functions


MidB, MidB$ functions

Example   See also

Returns specified portion of a string expression.

Syntax

MidB(<string exprs>, <start>[,<length>])

MidB$(<string exprs>, <start>[,<length>])

<string exprs>

String expression from which you are copying a byte or a series of contiguous bytes. It can be a variable string, a literal string, a string constant, the return value of any function that returns a string, or a Variant that can evaluate to a String.

<start>

Integer that specifies the position within a <string exprs> where copy begins.

Rule for <start>: Must be between 1 and 2,147,483,647, inclusive.

<length>

Integer indicating how many characters to copy.

Rules:

•	If <length> is omitted, Actuate Basic uses all characters from <start> to the end of <string exprs>.

•	Must be between 0 and 2,147,483,647.

Examples:

•	The following examples are equivalent.

MidB$("Widget",4,3)

MidB$("Widget",4)

•	The following example simply returns "Widget".

MidB$("Widget",1,99)

Return value

MidB: Variant

MidB$: String

•	If <start> is greater than length of <string exprs>, returns zero-length string.

•	If <length> = 0, returns zero-length string.

•	If <length> is greater than length of <string exprs>, returns only the characters up to the length of <string exprs>.

Tip

•	Use LenB[$] to find the number of bytes in <string exprs>.

•	Use InStrB[$] to find the position of a specified byte in <string exprs>.


Example

In the following example, MidB returns the middle word from a variable containing three words.

Function OnLButtonDblClk ( )

Dim MiddleWord, Msg, TestStr

Dim SpacePos1, SpacePos2, WordLen

' Create text string

TestStr = "MidB function Example"

' Find first space

SpacePos1 = InStr(1, TestStr, " ")

' Find next space

SpacePos2 = InStr(SpacePos1 + 1, TestStr, " ")

' Calc 2nd word length

WordLen = (SpacePos2 - SpacePos1) - 1

' Find the middle word

MiddleWord = MidB(TestStr, SpacePos1 + 1, WordLen)

Msg = "The word in the middle of TestStr is """ & MiddleWord & """"

MsgBox Msg, 0, TestStr

End Function

For information about using the code examples, see Using the code examples.


See also

InStrB function

LeftB, LeftB$ functions

LenB function

RightB, RightB$ functions


MidB, MidB$ statements

Example   See also

Replaces a segment of a string with another string.

Syntax

MidB(<string variable>,<start>[,<length>]) = <string exprs>

MidB$(<string variable>,<start>[,<length>]) = <string exprs>

<string variable>

String expression or Variant to modify.

Rule for <string variable>: Must be a variable, not a literal, function, or other expression.

<start>

Position in <string variable> at which replacement text begins. The position of the first byte is 1.

Rule for <start>: Must be between 1 and 2,147,483,647, inclusive.

<length>

Number of bytes from <string exprs> to use.

Default: Unchanged <string exprs>.

Rules for <length>:

•	Must be between 1 and2,147,483,647, inclusive.

•	No matter how large you specify <length> to be, the resulting string is never longer than <string variable>.

<string exprs>

String expression that replaces segment of <string variable>. It can be a variable string, a literal string, a string constant, the return value of any function that returns a string, or a Variant that can evaluate to a String.

Rule for <string exprs>: Cannot entirely replace <string variable> with a shorter <string exprs>.


Example

The following example replaces part of the string "FREUDIAN" with all or part of "Jung" in the variable Hillman.

Function OnLButtonDblClk()

Dim Hillman As String

Hillman = "FREUDIAN"

' now Hillman = "JungDIAN"

MidB(Hillman,1,5) = "Jung"

MsgBox Hillman

Hillman = "FREUDIAN"

' same result, "JungDIAN"

MidB(Hillman,1,4) = "Jung"

MsgBox Hillman

Hillman = "FREUDIAN"

' now Hillman = "JunUDIAN"

MidB$(Hillman,1,3) = "Jung"

MsgBox Hillman

Hillman = "FREUDIAN"

' now Hillman = "FREUJung"

MidB$(Hillman,5) = "Jung"

MsgBox Hillman

End Function

For information about using the code examples, see Using the code examples.


See also

LeftB, LeftB$ functions

MidB, MidB$ functions

RightB, RightB$ functions


Minute function

Example   See also

Returns an Integer from 0 to 59, inclusive, that represents the minute of the hour specified by a supplied date expression.

Syntax

Minute(<date exprs>)

<date exprs>

Date expression, or any numeric or string expression that can be interpreted as a date, a time, or as both a date and a time.

•	Can be a string such as "November 12, 1982 8:30 PM", "Nov 12, 1982 08:30 PM", "11/12/82 8:30pm", or "08:30pm", or any other string that can be interpreted as a date, time, or date/time in the valid range.

•	Can be a date serial number such as 30267.854 (which corresponds to November 12, 1982 at 8:30 PM), or any other number that can be mapped to a date, a time, or to a date/time in the valid range.

•	For date serial numbers, the integer component represents the date itself while the fractional component represents the time of day on that date, where January 1, 1900, at precisely noon has the date serial number 2.5, and negative numbers represent dates prior to December 30, 1899 (0).

Default: 0.

Rules:

•	If a date is included, it must be a valid date, even though Minute cannot return a date. A valid date is any date in the range January 1, 100, through December 31, 9999, expressed in one of the standard date formats.

•	If a time is included, it must be in the range 00:00:00 (12:00:00 AM) through 23:59:59 (11:59:59 PM), in either the 12- or 24-hour format.

•	If a numeric expression, it must be in the range -657434.0 to +2958465.9999, inclusive.

•	If a variable containing a date serial number, the variable must have been explicitly declared as one of the numeric types.

Example:

The following statements are equivalent. Each assigns 35 to the variable UserMinute.

UserMinute = Minute("6/7/64  2:35pm")

UserMinute = Minute("5:35 pm")

UserMinute = Minute("June 7, 1964 2:35 PM")

UserMinute = Minute("Jun 7, 1964") + 35

UserMinute = Minute(23535.6077)

UserMinute = Minute(0.6077)

Return value

Integer

Rule: If <date exprs> is Null, Minute returns a Null.


Example

The following example displays the number of hours, minutes, and seconds to midnight.

Function OnLButtonDblClk()

Dim HrDiff As Integer, MinDiff As Integer, SecDiff As Integer

Dim RightNow As Double, Midnight As Double, TotalDiff As Double

Dim TotalMinDiff As Double, TotalSecDiff As Double
Dim Msg As String

'

Midnight = TimeValue("23:59:59")

' Get current time

RightNow = Now

' Get diffs re midnight

HrDiff = Hour(Midnight) - Hour(RightNow)

MinDiff = Minute(Midnight) - Minute(RightNow)

SecDiff = Second(Midnight) - Second(RightNow) + 1

' Restate seconds and minutes if necessary

If SecDiff = 60 Then

' Add 1 to minute

MinDiff = MinDiff + 1

' And set 0 seconds

SecDiff = 0

End If

If MinDiff = 60 Then

' Add 1 to hour

HrDiff = HrDiff + 1

' And set 0 minutes

MinDiff = 0

End If

' Now get totals

TotalMinDiff = (HrDiff * 60) + MinDiff

TotalSecDiff = (TotalMinDiff * 60) + SecDiff

TotalDiff = TimeSerial(HrDiff, MinDiff, SecDiff)

' Prepare msg for display

Msg = "There are a total of " & Format(TotalSecDiff, "#,##0")

Msg = Msg & " seconds until midnight.  That translates to "

Msg = Msg & HrDiff & " hours, "

Msg = Msg & MinDiff & " minutes, and "

Msg = Msg & SecDiff & " seconds. "

Msg = Msg & "Expressed in standard time notation, it becomes "

' Remember not to use "mm" for minutes! m is for month.

Msg = Msg & Format(TotalDiff, "hh:nn:ss") & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Day function

Hour function

Month function

Now function

Second function

Time, Time$ functions

Weekday function

Year function


MIRR function

Example   See also

Returns the modified internal rate of return for a series of periodic cash flows (payments and receipts) in an existing array.

Syntax

MIRR(<casharray>( ),<finance rate>, <reinvestment rate>)

<casharray>()

Array of Doubles that specifies the name of an existing array of cash flow values.

Rule for <casharray>: Array must contain at least one positive value (receipt) and one negative value (payment).

<finance rate>

Numeric expression that specifies the interest rate paid as the cost of financing.

Rule for <finance rate>: Must be a decimal value that represents a percentage.

<reinvestment rate>

Numeric expression that specifies the interest rate received on gains from cash reinvestment.

Rule for <reinvestment rate>: Must be a decimal value that represents a percentage.

Example:

The following example assumes you have filled the array MyArray() with a series of cash flow values. If the interest rate you pay for financing is 12%, and the rate your earn on income is 11.5%, what is the modified internal rate of return? The answer is assigned to the variable MIRRValue.

MIRRValue = MIRR(MyArray( ), 0.12, 0.115)

Return value

Double

The modified internal rate of return is the internal rate of return (IRR) when payments and receipts are financed at different rates. MIRR takes into account both the cost of the investment (<finance rate>) and the interest rate received on the reinvestment of cash (<reinvestment rate>).

Rules

•	You must express cash paid out (such as deposits to savings) using negative numbers, and cash received (such as dividend checks) using positive numbers.

•	<casharray>() must contain at least one negative and one positive number.

•	In cases where you have both a positive cash flow (income) and a negative one (payment) for the same period, use the net flow for that period.

•	If no cash flow or net cash flow occurs for a particular period, you must type 0 (zero) as the value for that period.

Tip

Because MIRR uses the order of values within the array to interpret the order of payments and receipts, be sure to type your payment and receipt values in the correct sequence.


Example

The following example returns the modified internal rate of return for a series of cash flows contained in the array CashValues(). LoanAPR represents the financing interest, and InvAPR represents the interest rate received on reinvested cash. Option Base is assumed to be set to zero.

Function OnLButtonDblClk( )

 ' Set up array

Static CashValues(5) As Double

Dim LoanAPR As Double, InvAPR As Double, NL As String

Dim Fmt As String, ReturnRate As Double, Msg As String

NL = Chr$(10)

' Loan rate

LoanAPR = .1

' Reinvestment rate

InvAPR = .12

' Define money format

Fmt = "#0.00"

' Business start-up costs

CashValues(0) = -80000

'Now type positive cash flows reflecting income for four successive years:

CashValues(1) = 23000: CashValues(2) = 27000

CashValues(3) = 31000: CashValues(4) = 35000

' Calc internal rate

ReturnRate = MIRR(CashValues, LoanAPR, InvAPR)

Msg = "The modified internal rate of return for these five cash flows is:  "

Msg = Msg & Format(Abs(ReturnRate) * 100, Fmt) & "%."

MsgBox Msg

Msg = CashValues(1) & NL & CashValues(2) & NL

Msg = Msg & CashValues(3) & NL & CashValues(4)

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

IRR function

Rate function


MkDir statement

Example   See also

Creates a new directory or subdirectory on the specified or current drive.

Syntax

MkDir <path name>

<path name>

String expression that is the name of the directory to be created.

Rules for <path name>:

•	Must contain fewer than 259 characters.

•	Cannot be the name of a directory that already exists.

<path name> has the following syntax:

[<drive:>] [ \ ]<directory>[\<directory>]...(Windows)

[ /]<directory>[/<directory>]...(UNIX)

<drive:>

Character, followed by a colon, that is the name of the drive (Windows only).

<directory>

String expression that is the name of the directory or subdirectory to create.

Examples:

The following example creates the subdirectory "DOCS" under the current directory on the default drive.

MkDir "DOCS"

The following example creates the subdirectory "DOCS" under the root directory of the current drive.

DirName$ = "\DOCS"

MkDir DirName$

On a Windows system, the following example creates the subdirectory "DOCS" under the root directory of drive D.

MkDir "D:\DOCS"

Description

If you do not specify the full path name, MkDir creates the new subdirectory on the current drive under the current directory.

Tips

•	MkDir is similar to the operating system MkDir. Unlike the DOS command, however, it cannot be abbreviated.

•	If you use one or more embedded spaces in <path name> when you create a directory, use Actuate Basic's RmDir to remove the directory.

•	To determine the current directory, use CurDir.


Example

The following example determines whether a \TMP subdirectory exists on the current drive. If it does not, it creates it, prompts the user to retain or remove it, and responds accordingly.

Function OnLButtonDblClk ( )

Dim UserAns As Integer, ThisDrive As String

Dim Msg As String, TempDir As String

' Set up error handler

On Error Resume Next

' Get current drive letter

ThisDrive = Left$(CurDir, 2)

' Construct full path spec

TempDir = UCase$(ThisDrive & "\TMPERASE")

' Make the new directory

MkDir TempDir

' Does it exist?

If Err = 41Then

Msg = "Sorry, " & TempDir & " directory already exists."

Else

Msg = TempDir & " directory was created.  "

End If

Msg = Msg & "Would you like to remove it?"

UserAns = MsgBox(Msg, MB_YESNOCANCEL)

If UserAns = IDYES Then

RmDir TempDir

End If

End Function

For information about using the code examples, see Using the code examples.


See also

CurDir, CurDir$ functions

ChDir statement

RmDir statement


Month function

Example   See also

Returns an Integer between 1 and 12, inclusive, that represents the month of the year for a supplied date argument.

Syntax

Month(<date exprs>)

<date exprs>

Date expression, or any numeric or string expression that can evaluate to a date or a date and a time.

•	Can be a string such as "November 12, 1982", "Nov 12, 1982", "11/12/82", or "11-12-82", or any other string that can be interpreted as a date in the valid range.

•	Can be a date serial number such as 30267.854 (which corresponds to November 12, 1982 at 8:30 PM), or any other number that can be mapped to a date in the valid range.

•	For date serial numbers, the integer component represents the date itself while the fractional component represents the time of day on that date, where January 1, 1900, at precisely noon has the date serial number 2.5, and negative numbers represent dates prior to December 30, 1899 (0).

Rules:

•	If <date exprs> a string expression, must specify a date in the range January 1, 100, through December 31, 9999, inclusive.

•	If a numeric expression, must be in the range -657434 to +2958465, inclusive.

•	If a variable containing a date serial number, the variable must have been explicitly declared as one of the numeric types.

Examples:

The following statements are equivalent. Each assigns 6 to the variable UserMonth.

UserMonth = Month("6/7/64")

UserMonth = Month("June 7, 1964 2:35 PM")

UserMonth = Month("Jun 7, 1964")

UserMonth = Month(23535)

UserMonth = Month(4707*5)

Return value

Integer

Rule: If <date exprs> is Null, Month returns a Null.


Example

The following example prompts the user to type a date. Then it uses various interrelated date functions to display the year, the month, the day and the weekday for the given date. Finally, it gives the date's serial number.

To use this example, paste the function (Function Suffix) into your Actuate Basic source code (.BAS) file. Then paste the subroutine code into a clickable control, compile, and run.

Function OnLButtonDblClk ( )

Dim UserEntry, UserYear As Integer, UserMonth As Integer

Dim UserDay As Integer, UserDOW As Integer, DOWName As String

Dim Msg As String, NL As String, LeapYear As String

' Define newline

NL = Chr$(10)

' Get user input

UserEntry = InputBox("Please type a date.")	UserEntry = CDate(UserEntry)

' Calculate year

UserYear = Year(UserEntry)

' Calculate month

UserMonth = Month(UserEntry)

' Calculate day

UserDay = Day(UserEntry)

' Calculate day of week

UserDOW = Weekday(UserEntry)

' Convert to name of day

DOWName = Format$ (UserEntry, "dddd")

' Determine if the year is a leap year or a centesimal

If UserYear Mod 4 = 0 And UserYear Mod 100 = 0 Then

' Evenly divisible by 400?

If UserYear Mod 400 = 0 Then

LeapYear = "is a leap year."

' Not evenly divisible

Else

LeapYear = "is a centesimal but not a leap year."

End If

ElseIf UserYear Mod 4 = 0 Then

LeapYear = "is a leap year."

Else

LeapYear = "is not a leap year."

End If

' Display results for the user after the pattern:

' The given year 1982 is not a leap year. The weekday number for

' the 12th day of the 11th month in 1982 is 3, which means that

' day was a Tuesday.

'

' The date serial number for 11/12/82 is: 30267

'

MsgBox "The given year, " & UserYear & ", " & LeapYear

Msg = "The weekday number for the "

Msg = Msg & UserDay & Suffix(UserDay) & " day "

Msg = Msg & "of the " & UserMonth & Suffix(UserMonth) & " month "

Msg = Msg & "in " & UserYear & " is " & UserDOW

Msg = Msg & ", which means that day is a " & DOWName & "." & NL & NL

Msg = Msg & "The date serial number for " & UserEntry & " is:  "

Msg = Msg & CDbl(DateSerial(UserYear, UserMonth, UserDay))

MsgBox Msg

End Function

' The following function called in the previous procedure tells us what

' suffix (1st, 2nd, 3rd) to use with a number. Paste this in your .BAS file.

Function Suffix (DateNum) As String

Select Case DateNum

Case 1

Suffix = "st"

Case 2

Suffix = "nd"

Case 3

Suffix = "rd"

Case Else

Suffix = "th"

End Select

End Function

For information about using the code examples, see Using the code examples.


See also

Date, Date$ functions

Day function

Hour function

Minute function

Now function

Second function

Weekday function

Year function


MsgBox function

Example   See also

Displays a user-defined message in a window with a specified set of response buttons, waits for the user to choose a button, and returns a value indicating which button the user selected.

Syntax

MsgBox(<message text> [, [<configuration>][, <window title>] ])

<message text>

String expression that is the message to be displayed in the dialog box. Lines break automatically at the right edge of the dialog box.

Rule for <messages text>: If the <message text> for an application modal message box is longer than 1024 characters, the message is truncated.

<configuration>

Numeric expression that is the bit-wise sum of up to four separate values:

•	Number and type of buttons.

•	Icon style.

•	Default button.

•	Modality.

The following table summarizes values for <configuration> and their corresponding meanings.

	Symbolic constant	Value	Meaning
Button group	MB_OK	0	Display OK button
	MB_OKCANCEL	1	Display OK and Cancel buttons
	MB_ABORTRETRYIGNORE	2	Display Abort, Retry, and Ignore buttons
	MB_YESNOCANCEL	3	Display Yes, No, and Cancel buttons
	MB_YESNO	4	Display Yes and No buttons
	MB_RETRYCANCEL	5	Display Retry and Cancel buttons
Icon style group	MB_ICONSTOP	16	Display Stop  icon
	MB_ICONQUESTION	32	Display Question Mark icon
	MB_ICONEXCLAMATION	48	Display Exclamation Point icon
	MB_ICONINFORMATION	64	Display Information icon
Default button group	MB_DEFBUTTON1	0	First button is default
	MB_DEFBUTTON2	256	Second button is default
	MB_DEFBUTTON3	516	Third button is default
Modality group	MB_APPLMODAL	0	Application modal. User must respond to message box before continuing in current application.
	MB_SYSTEMMODAL	4096	System modal. User must respond to message box before continuing with any application.
Add these numbers or constants together to specify the corresponding attributes of the message box.

Default: 0

Rule: You can use only one number from each group.

Example:

Each displays a message box with the Question Mark icon, the message "Are you sure you want to overwrite the file?" and the Yes, No and Cancel buttons. In each case, the No button is the default. The user's response is assigned to the variable UserAns.

UserAns = MsgBox("Are you sure you want to overwrite the file? ", 3+32+256)

UserAns = MsgBox("Are you sure you want to overwrite the file? ", 291)

UserAns = MsgBox("Are you sure you want to overwrite the file? ", 	    MB_YESNOCANCEL + MB_ICONQUESTION + MB_DEFBUTTON2)

<window title>

String expression that is the text displayed in the title bar of the dialog box.

Default: No title in the title bar.

Return value

Integer

The value that MsgBox function returns tells you which button the user selected.

The following table summarizes the possible user selections and their corresponding return values.

Selection at run-time	MsgBox returns	Symbolic Constant is
OK button	1	IDOK
Cancel button	2	IDCANCEL
Abort button	3	IDABORT
Retry button	4	IDRETRY
Ignore button	5	IDIGNORE
Yes button	6	IDYES
No button	7	IDNO
Tip

To set line breaks yourself, place a linefeed (ANSI character 10) before the first character of the text that is to begin each new line. This does not apply to Microsoft Windows 3.0.


Example

The following example displays a different message box based on whether the user selected the Yes button or No button in a dialog box.

Function OnLButtonDblClk ( )

Dim Title As String, MsgTxt As String

Dim DialogDef As Integer, UserResponse As Integer

Title = "Demonstration of MsgBox Function"

MsgTxt = "This demonstrates the display of a critical-error message."

MsgTxt = MsgTxt & " Do you want to continue?"

DialogDef = MB_YESNO + MB_ICONSTOP + MB_DEFBUTTON2

UserResponse = MsgBox(MsgTxt, DialogDef, Title)

If UserResponse = IDYES Then

MsgTxt = "You selected Yes."

Else

MsgTxt = "You selected No or pressed Enter."

End If

MsgBox MsgTxt

End Function

For information about using the code examples, see Using the code examples.


See also

InputBox, InputBox$ functions

MsgBox statement


MsgBox statement

Example   See also

Displays a user-defined message in a window with a specified set of response buttons, and waits for the user to choose a button. MsgBox statement does not return a value indicating which button the user has clicked.

Syntax

MsgBox <message text> [, [<configuration>][, <window title>] ]

<message text>

String expression that is the message displayed in the dialog box. Lines break automatically at the right edge of the dialog box.

Rule for <message text>: For application modal message boxes, must not be longer than 1024 characters, or are truncated.

<configuration>

Numeric expression that is the bit-wise sum of up to four separate values:

•	Number and type of buttons.

•	Icon style.

•	Default button.

•	Modality.

The following table summarizes values for <configuration> and their corresponding meanings.

	Symbolic constant	Value	Meaning
Button group	MB_OK	0	Display OK button
	MB_OKCANCEL	1	Display OK and Cancel buttons
	MB_ABORTRETRYIGNORE	2	Display Abort, Retry, and Ignore buttons
	MB_YESNOCANCEL	3	Display Yes, No, and Cancel buttons
	MB_YESNO	4	Display Yes and No buttons
	MB_RETRYCANCEL	5	Display Retry and Cancel buttons
Icon style group	MB_ICONSTOP	16	Display Stop  icon
	MB_ICONQUESTION	32	Display Question Mark icon
	MB_ICONEXCLAMATION	48	Display Exclamation Point icon
	MB_ICONINFORMATION	64	Display Information icon
Default button group	MB_DEFBUTTON1	0	First button is default
	MB_DEFBUTTON2	256	Second button is default
	MB_DEFBUTTON3	516	Third button is default
Modality group	MB_APPLMODAL	0	Application modal. User must respond to message box before continuing in current application.
	MB_SYSTEMMODAL	4096	System modal. User must respond to message box before continuing with any application.
Add these numbers or constants together to specify the corresponding attributes of the message box.

Default: 0.

Rule: You may use only one number from each group.

Example:

Each of the following displays a message box with the Exclamation Point icon, the message "Sorry, insufficient disk space" and the OK button. In each case, the No button is the default button.

MsgBox "Sorry, insufficient disk space", 0+48

MsgBox "Sorry, insufficient disk space", 48

MsgBox "Sorry, insufficient disk space", (MB_OK + MB_ICONEXCLAMATION)

<window title>

String expression that specifies the words to appear in the title bar of the message window.

Default: No title in title bar.

Tip

To set line breaks yourself, place a linefeed (ANSI character 10) before the first character of the text that is to begin each new line. This does not apply to Microsoft Windows 3.0.


Example

The following example displays three message boxes consecutively.

Function OnLButtonDblClk ( )

' Define the dialog box

MsgBox "The dialog box shows a Yes and a No button.", MB_YESNO

MsgBox "The dialog box shows only an OK button."

MsgBox "The dialog box shows an OK button, a Cancel button,

{XXxde}and an info icon.", MB_OKCANCEL + 64.

End Function

For information about using the code examples, see Using the code examples.


See also

InputBox, InputBox$ functions

MsgBox function


Name statement

Example   See also

Renames a file or directory. Also, moves a file from one directory to another.

Syntax

Name <old name> As <new name or path>

As

Keyword that separates the name of the original file or directory from the name of the target file or directory.

<old name>

String expression that specifies an existing file or directory to rename.

Default path: Current default drive and directory.

Rules for <old name>:

•	Indicated file or directory must exist.

•	Drive letter, if specified, must be the same as that specified in <new name or path>.

•	Indicated file must not currently be open by Actuate Basic.

<new name or path>

String expression that specifies the new file or directory name.

Default path: Current drive and directory.

Rules for <new name>:

•	Indicated file must not already exist if its path is the same as the path in <old name>.

•	Indicated path must already exist if it is not the same as the path in <old name>.

•	Drive letter, if specified, must be the same as that specified in <old name>.

•	Indicated file must not currently be open by Actuate Basic.

<old name> or <new name or path> can optionally specify a full path, in which case use the following syntax.

[<drive:>] [ \ ]<directory>[\<directory>][\<file name>] (Windows)

[ / ]<directory>[/<directory>][<file name>] (UNIX)

<drive:>

Character, followed by a colon that specifies the drive on which the directory to be renamed, or file to be renamed/moved is located (WIndows only).

Rule for <drive:>: Both <old name> and <new name or path> must refer to the same drive.

<directory>

String expression that specifies the name of a directory or subdirectory in the full path specification of <old name> or of <new name or path>.

Rule: You can use Name to change the name of a directory, but you cannot move directories.

Examples:

The following example changes the name of the file TEST1.FIL in the current directory to TEST2.FIL.

Name "TEST1.FIL" As "TEST2.FIL"

The following example moves the file TEST1.FIL from the C:\TEMP subdirectory to the root directory.

Name "C:\TEMP\TEST1.FIL" As "C:\TEST1.FIL"

Description

Name is similar to the operating system's Rename command. Name, however, can change the name of a directory as well as that of a file.


Example

The following example moves a file from one directory to another and renames it at the same time.

Function OnLButtonDblClk ( )

Dim FileName1 As String, FileName2 As String

Dim Msg As String, NL As String, TestDir As String

' Define newline

NL = Chr$(10)

' Define filenames

FileName1 = "NAMEAAAA.DAT"

FileName2 = "NAMEBBBB.DAT"

' Test directory name

TestDir = "\TEST.DIR"

' Create test file

Open FileName1 For Output As #1

' Put sample data in file

Print #1, "This is a test."

Close #1

' Make test directory.

MkDir TestDir

' Move and rename

Name FileName1 As TestDir & "\" & FileName2

Msg = "A new file, " & FileName1 & " was created "

Msg = Msg & "in " & CurDir$ & ". After being created, it was "

Msg = Msg & "moved to " & TestDir & " and renamed "

Msg = Msg & FileName2 & "." & NL & NL

Msg = Msg & "Choose OK to delete the test data file and "

Msg = Msg & "directory."

MsgBox Msg

' Delete file from disk

Kill TestDir & "\" & FileName2

' Delete test directory

RmDir TestDir

End Function

For information about using the code examples, see Using the code examples.


See also

Kill statement


NewInstance function

Example   See also

Dynamically creates an instance of a class given the name of that class as a String. Use NewInstance to choose at runtime which class to instantiate.

Syntax

NewInstance (<class name>)

<class name>

String expression that specifies the fully qualified name of the class to instantiate.

Rule: The class name must be valid or a runtime error is sent.

Return value

The reference to the new object instance.


Example

In this example, two methods for instantiating an object are demonstrated.

Function OnLButtonDblClk ( )

Dim Obj1 As AcLabelControl

Dim Obj2 As AcLabelControl, Msg As String

' Standard instantiation

Set Obj1 = New AcLabelControl

' Dynamic instantiation

Set Obj2 = NewInstance ("AcLabelControl")

Obj2.BackgroundColor = Red

Msg = "The numeric value for the background color "

Msg = Msg & "of Obj2 is:  " & Obj2.BackgroundColor

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

IsPersistent function

NewPersistentInstance function


NewPersistentInstance function

Example   See also

Dynamically creates a persistent instance of a class given the name of that class as a String. Use NewPersistentInstance to choose at run time which class to instantiate.

Syntax

NewPersistentInstance (<class name>, <file number>)

<class name>

String expression that specifies the name of the class to instantiate.

Rule: Must be valid or a runtime error is sent.

<file number>

Numeric expression that specifies the number of the open .ROI file.

Rules:

•	If no file number is specified, the object is persistent in the current default ROI file.

•	If two or more .ROI files are open, you must specify the file number.

Return value

String

The reference to the new object instance.


Example

In this example, a persistent instance of an AcLabelControl object is created dynamically.

Function OnLButtonDblClk ( )

Dim Obj As AcLabelControl, Msg As String

Set Obj = NewPersistentInstance ("AcLabelControl", 1)
Obj.BackgroundColor = Red

Msg = "The numeric value for the background color "

Msg = Msg & "of Obj is:  " & Obj.BackgroundColor

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

IsPersistent function

NewInstance function


Now function

Example   See also

Returns a date that represents the current date and time according to the user's operating system.

Syntax

Now

Examples:

The following example assigns the current year to the variable ThisYear.

ThisYear = Year(Now)

The following example assigns the current date and time to the variable ThisInstant.

ThisInstant = Now

The following example assigns the full date serial number representing the present moment to the double-precision variable FreezeFrame.

FreezeFrame# = Now

Return value

Date

The value that Now returns usually looks like a date and/or time but is stored internally as a Double-precision floating-point number--a date serial number--that represents a date between midnight January 1, 100, and December 31, 9999, inclusive, and/or a time between 00:00:00 and 23:59:59, or 12:00:00 AM and 11:59:59 PM, inclusive.

The integer component of a date serial number represents the date (day, month, and year) itself, while its decimal or fractional component represents the time of day on that date as a proportion of a whole day, where January 1, 1900, at noon has the date serial number 2.5, and where negative numbers represent dates prior to December 30, 1899 (0).


Example

In the following example, Now returns the current date and Format displays it as a long date that includes the day and date.

Function OnLButtonDblClk()

Dim Today As Double

Today = Now

MsgBox "Today is " & Format(Today, "dddd, mmmm dd, yyyy") & "."

End Function

For information about using the code examples, see Using the code examples.


See also

Date, Date$ functions

Day function

Hour function

Minute function

Month function

Second function

Time, Time$ functions

Weekday function

Year function


NPer function

Example   See also

Returns the number of periods for an annuity based on periodic, constant payments, and on an unvarying interest rate.

Syntax

NPer(<rate per period>, <each pmt>, <present value>, <future value>, <when due>)

<rate per period>

Numeric expression that specifies the interest rate that accrues per period.

Rule for <rate per period>: Must be given in the same units of measure as <each pmt>. For instance, if <each pmt> is expressed as a monthly payment, then <rate per period> must be expressed as the monthly interest rate.

<each pmt>

Numeric expression that specifies the amount of each payment.

Rule for <each pmt>: Must be given in the same units of measure as <rate per period>. For instance, if <rate per period> is expressed in months, then <each pmt> must be expressed as a monthly payment.

<present value>

Numeric expression that specifies the value today of a future payment or of a stream of payments.

Example: If you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you will end up with about $100. In this case, the present value of $100 is approximately $23.94.

<future value>

Numeric expression that specifies the cash balance you want after you have made your final payment.

Examples:

•	You set up a savings plan with a goal of having $75,000 in 18 years to pay for your child's education. For this plan, the future value is $75,000.

•	You take out a loan for $11,000. The future value is $0.00, as it is for any typical loan.

<when due>

Numeric expression that specifies whether each payment is made at the beginning (1), or at the end (0) of each period.

Default: 0.

Rule for <when due>: Must be 0 or 1.

Example:

The following example assumes you are making monthly payments at the first of each month on a loan of $20,000, at an APR of 11.5%. If each payment is $653.26, how many payments will you have to make to finish paying off the loan? The answer (36) is assigned to the variable NumPeriods.

NumPeriods = NPer(.115/12, -653.26, 20000, 0, 1)

Return value

Double

An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment (such as a monthly savings plan) or a loan (such as a home mortgage).

Rules

•	<rate per period> and <each pmt> must be expressed in terms of the same units (weekly/monthly/yearly, and so on).

•	You must express cash paid out (such as deposits to savings) using negative numbers, and cash received (such as dividend checks) using positive numbers.


Example

The following example prompts the user to supply various particulars about a loan. It then returns the number of payments the user must make to pay it off. To use this example, paste the first section at or near the beginning of your Actuate Basic source code (.BAS) file and copy the procedure into the code window for a clickable component like a label.

Declare

Global Const ENDPERIOD = 0

' When payments are made

Global Const BEGINPERIOD = 1

End Declare

'

Function OnLButtonDblClk()

Dim FutureVal As Double, PresVal As Double, APR  As Double

Dim Payment As Double, PayWhen As Integer, TotalPmts As Integer

'

' Usually 0 for a loan

FutureVal = 0

' Get user input

PresVal = InputBox("How much will you borrow?")

APR = InputBox("What is the annual percentage rate of this loan?")

If APR > 1 Then

' Ensure proper form

APR = APR / 100

End If

Payment = InputBox("How much do you want to pay each month?")

PayWhen = MsgBox("Do you make payments at month end?", MB_YESNO)

If PayWhen = IDNO Then

PayWhen = BEGINPERIOD

Else

PayWhen = ENDPERIOD

End If

' Do computation

TotalPmts = NPer(APR / 12, -Payment, PresVal, FutureVal, PayWhen)

If Int(TotalPmts) <> TotalPmts Then

TotalPmts = Int(TotalPmts) + 1

End If

MsgBox "It will take " & TotalPmts & " months to pay off your loan."

End Function

For information about using the code examples, see Using the code examples.


See also

FV function

IPmt function

Pmt function

PPmt function

PV function

Rate function


NPV function

Example   See also

Returns the net present value of a varying series of periodic cash flows (both positive and negative) at a given interest rate.

Syntax

NPV(<rate>,<casharray>( ))

<rate>

Numeric expression that specifies the discount rate over the length of the period.

Rule for <rate>: Must be expressed as a decimal.

<casharray>( )

Array of Doubles that specifies the name of an existing array of cash flow values.

Rule for <casharray>: Array must contain at least one positive value (receipt) and one negative value (payment).

Example:

The following example assumes you have filled the array MyArray with a series of cash flow values, and that the interest rate is 11%. What is the net present value? The answer is assigned to the variable NetPValue.

NetPValue = NPV(.11,MyArray( ))

Return value

Double

While PV determines the present value of a series of constant payments, NPV does the same for a series of varying payments. Net present value is the value in today's dollars of all future cash flows associated with an investment minus any initial cost. In other words, it is that lump sum of money that would return the same profit or loss as the series of cash flows in question, if the lump sum were deposited in a bank today and left untouched to accrue interest at the rate given by <rate> for the same period of time contemplated by the cash flow stream.

Rules

•	The NPV investment begins one period before the date of the first cash flow value and ends with the last cash flow value in the array.

•	If your first cash flow occurs at the beginning of the first period, its value must be added to the value returned by NPV and must not be included in the cash flow values of <casharray>( ).

•	You must express cash paid out (such as deposits to savings) using negative numbers, and cash received (such as dividend checks) using positive numbers.

•	<casharray>( ) must contain at least one negative and one positive number.

•	In cases where you have both a positive cash flow (income) and a negative one (payment) for the same period, use the net flow for that period.

•	If no cash flow or net cash flow occurs for a particular period, you must enter 0 (zero) as the value for that period.

Tip

Because NPV uses the order of values within the array to interpret the order of payments and receipts, be sure to enter your payment and receipt values in the correct sequence.


Example

The following example assumes Option Base is set to zero, and returns the net present value for a series of cash flows contained in an array. The variable ReturnRate represents the fixed internal rate of return.

Function OnLButtonDblClk()

' Set up the array

Static CashFlows(6) As Double

Dim Fmt As String, ReturnRate As Double

Dim Msg As String, NetPVal As Double

' Money display format

Fmt = "$###,##0.00"

' Set fixed internal rate

ReturnRate = .12

' Business start-up expense

CashFlows(0) = -100000

' Now enter positive cash flows reflecting income for four successive years:

CashFlows(1) = 20000: CashFlows(2) = 40000

CashFlows(3) = 80000: CashFlows(4) = 0: CashFlows(5) = 10000

' Calc net present value

NetPVal = NPV(ReturnRate, CashFlows)

Msg = "The net present value of these cash flows is:  "

Msg = Msg & Format(NetPVal, Fmt) & ". "

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

FV function

IRR function

PV function


Oct, Oct$ functions

Example   See also

Converts a numeric expression from decimal to octal notation, and from numeric to string.

Syntax

Oct(<numeric exprs>)

Oct$(<numeric exprs>)

<numeric exprs>

Numeric expression to be converted from decimal to octal notation.

Rule: If <numeric exprs> evaluates to Null, Oct[$] returns a Null.

In the following example, the two statements are equivalent. Each returns "&O010", which is the full form of the octal notation equivalent of decimal number 8.

"&O" & Oct$(8)

"&O" & Oct$(2*4)

In the following example, the first returns decimal value 16, but the second generates an error because the return value of Oct[$] is not preceded by the octal prefix, "&O".

("&O" & Oct$(8)) * 2

Oct$(8) * 2

Return value

Oct: Variant

Oct$: String

•	Oct[$] rounds <numeric exprs> to the nearest whole number before evaluating it.

•	If <numeric exprs> is Integer, Variant of type 2 (Integer), Variant of type 0 (Empty) or any other numeric or Variant data type, Oct[$] returns up to 11 octal characters.

Tips

•	To represent an octal number directly, precede a number in the correct range with &O. An octal number's correct range is from 0 to O7777777777. For example, you can use &O010 * 2 to return decimal value 16, because &O010 is octal notation for 8.

•	To generate the full octal representation of <numeric exprs>, you need to supply the radical prefix "&O", because Oct[$] does not return that component.


Example

The following example prompts you for a decimal number, then uses Oct[$] to convert it to octal notation.

Function OnLButtonDblClk ( )

Dim Msg, Num

' Get user input

Num = InputBox("Please enter a number to convert.")

Msg = Num & " in decimal notation is &O"

Msg = Msg & Oct(Num) & " in octal notation."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Hex, Hex$ functions

Val function


On Error statement

Example   See also

Tells the program what to do if an error occurs at run-time.

Syntax

On Error { GoTo <line | line label> | Resume Next | GoTo 0 }

GoTo

Clause that enables the error-handling routine that starts at <line > (or, more commonly, <line label>). Enabling the routine means that if a run-time error occurs, program control branches to <line>. The error-handler at <line> remains active until a Resume, Exit Sub, or Exit Function is executed.

<line> or <line label>

The line number or line label to which the program branches when a run-time error occurs.

Rule for <line>: Must be in the same procedure as On Error.

Example:

The following statement tells Actuate Basic to branch to the label "ErrorTrap" when an error occurs.

On Error GoTo ErrorTrap

Resume Next

Clause specifying that when a run-time error occurs, control passes to the statement immediately following that in which the error occurred. That is, directs Actuate Basic to continue executing code even though an error has occurred.

GoTo 0

Clause that disables any enabled error handler in the current procedure.

Rule for <GoTo 0>: Cannot be used to specify line number 0 as the start of the error-handling code.

Description

•	Unless you use On Error, any run-time error that occurs is fatal. Actuate Basic generates an error message and stops executing the program.

•	If another error occurs while an error handler is active, Actuate Basic passes control back through any previous calling procedure or procedures until it finds an inactive error handler, which it then activates. If it cannot find such an inactive error handler, the error is fatal.

•	Each time control passes back to a calling procedure, that procedure becomes the current one. Once an error handler in any procedure succeeds in handling an error, program execution resumes in the current procedure at the point designated by its own error handler's Resume statement--which may not be the error handler or the Resume you perhaps intended to execute a few levels down the calling hierarchy.

•	An error-handler is automatically disabled when you exit its procedure.

Rules

•	The error handler indicated by <line> or <line label> cannot be a sub or function procedure. It must be a block of code marked by a line label or line number.

•	To prevent error-handling code from becoming part of the normal program flow even when there is no error--that is, from inadvertently executing when it should not--place an Exit Sub or Exit Function immediately before the label of the error handler.

Tips

•	An error-handling routine should be exited only by using some form of Resume.

•	You can use Err to obtain the error number of a run-time error.

•	Your error-handling routine should test or save the value of Err before any other error can occur, or before it calls any procedure that could cause an error.

•	You can use Error[$] function to return the error message associated with any given run-time error returned by Err.


Example

The following example generates an error, then it displays the error's number and description.

Function OnLButtonDblClk ( )

Dim Drive As String, Msg As String

' Set up error handler

On Error GoTo ErrorHandler7

' Attempt to open file

Open Drive & ":\TEST\X.DAT" For Input As #1

Close #1

' Exit before entering the error  handler

Exit Function

' Error handler line label

ErrorHandler7:

Msg = "Error " & Err & " occurred, which is: " & Error$(Err)

MsgBox Msg

' Resume procedure

Resume Next

End Function

For information about using the code examples, see Using the code examples.


See also

Erl function

Err function

Error, Error$ functions

Resume statement


Open statement

Example   See also

Enables reading and writing--input and output (I/O)--to a file.

Syntax

Open <file name> [For <mode>] [Access <permissions>] [<lock>] As [#]<file number> [Len = <record or buffer size>]

<file name>

String expression enclosed in double quotes that is the name of the target file. If the file does not exist when it is opened for Append, Binary, Output, or Random modes, it is created and then opened.

Example:

Open "C:\WINDOWS\MYNOTES.FIL" As #1

For <mode>

Clause that specifies the file mode. Indicates whether and how to read from or write to the file. <mode> may be Append, Binary, Input, Output, or Random.

Example:

Open "C:\WINDOWS\MYNOTES.FIL" For Input As #1

Access <permissions>

Clause that specifies what operations this process is permitted to perform on <file name>. Another process can be more or less restricted than this one is. The <permissions> keyword can consist of any one of the following: Read, Write, or Read Write.

Rules for Access <permissions>:

•	If another process already opened the file and made <permissions> unavailable to others, the Open operation fails and a "Permission denied" error occurs.

•	Windows 3.1 users: To enable locking operations and use this clause, you must first run SHARE.EXE before you run your Actuate Basic program.

Example:

Open "C:\WINDOWS\MYNOTES.FIL" For Input Access Read As #1

<lock>

Keyword or set of keywords that specifies what operations other processes are permitted to perform on <file name>. In a multiuser environment or multiprocessing environment, <lock> restricts access by other processes or users. The <lock> keyword can consist of any one of the following: Shared, Lock Read, Lock Write, or Lock Read Write.

Example:

Open "C:\WINDOWS\MYNOTES.FIL" For Binary As #1 Shared

As <file number>

Clause that assigns a number to the open file.

<file number>

Integer that specifies the number that is associated with the file as long as it remains open. Other I/O statements can then use <file number> to refer to the file.

Rule for <file number>: Must be between 1 and 255, inclusive.

Len = <record or buffer size>

Clause specifying how much information to take from the file into the buffer.

The following table summarizes the behavior of the Len = <record or buffer size> clause, which depends on the setting of <mode>:

Mode	Len = <record or buffer size>
Random	Specifies the record length (the number of characters in a record). Default for <record or buffer size> in bytes is 128.
Input Output Append	Specifies the number of characters to be placed in the buffer. Default for <record or buffer size> in bytes is 512.
Binary	Ignored
<record or buffer size>

Integer expression that indicates either the record length or buffer size depending on <mode>.

Rules:

•	Must be positive.

•	Must be less than or equal to 32,767 bytes.

Example:

Open "C:\WINDOWS\NOTES\MYNOTES.FIL" For Input As #1 Len = 512

Default mode: Random.

Options for <mode>

Random

Keyword that specifies random-access file mode. Instructs Actuate Basic to make three attempts to open the file with these permissions, and in this order.

•	Read and write.

•	Write-only.

•	Read-only.

Binary

Keyword that specifies binary file mode so you can read and write information to any byte position in the file. If you do not supply an Access clause, instructs Actuate Basic to make three attempts to open the file, following the same order as for Random files.

Rule for Binary mode: If <file name> does not exist, it is created, then opened.

Tip: Use Get and Put to write to any byte position in a Binary file.

Input

Keyword that specifies sequential input mode.

Rule for Input mode: <file name> must exist.

Output

Keyword that specifies sequential output mode.

Rule for Output mode: If <file name> does not exist, it is created, then opened.

Append

Keyword that specifies sequential output mode, and sets the file pointer to the end of the file. If <file name> does not exist it is created, then opened.

Tip: Use Print # or Write# to append to the file.

Example:

Open "C:\WINDOWS\MYNOTES.FIL" For APPEND As #1

Options for Access

Read

Keyword instructing Actuate Basic to open the file for a reading process only.

Write

Keyword that instructs Actuate Basic to open the file for a writing process only.

Read Write

Keyword that instructs Actuate Basic to open the file for both reading and writing processes.

Rule for Read Write access: Valid only if <mode> is Random, Binary, or Append.

Options for <lock>

Shared

Keyword indicating that any process on any machine has permission to read from or write to <file name> while this Open is in effect.

Lock Read

Keyword indicating that no other process has permission to read <file name> while this Open is in effect.

Rule for Lock Read: Applied only if no other process has a previous read access to the file.

Lock Write

Keyword indicating that no other process has permission to write to <file name> while this Open is in effect.

Rule for Lock Write: Applied effect only if no other process has a previous write access to the file.

Lock Read Write

Keyword indicating that no other process has permission to read from or write to <file name> while this Open is in effect.

Lock Read Write can only occur if

•	No other process has already been granted read or write access.

•	A Lock Read or Lock Write is not already in effect.

Default for <lock>: Lock Read Write.

Description

You must open a file before any I/O operation can be performed on it. Open allocates a buffer to the file for I/O, and determines the mode of access used with the buffer.

In Actuate Basic there are three types of file access, Random, Sequential and Binary. The type you use in Open causes Actuate Basic to assume that <file name> has certain characteristics. These assumptions are summarized in the following table.

Access	Mode	Actuate Basic assume <file name>
Random	Random	Consists of a series of records of identical length, and all of the same data type.
Sequential	Input Output Append	Is a text file, or consists of a series of text characters and/or of text formatting characters such as newlines.
Binary	Binary	Can consist of data of any type, with records of any length, or even of variable lengths.
Rules

•	In Binary, Input, and Random modes, you do not need to first close an open file before you open it with a different <file number>.

•	In Append and Output modes, you must first close an open file before you open it with a different <file number>.

Tips

•	Use Random access files when you want easy access to individual records. Do not use them when you want to conserve storage space.

•	Use Sequential access files when you want to process files consisting only of text. Do not use them for other types of information.

•	Use Binary access files when you want to save storage space by varying your record lengths, sizing them only as needed to fit the data they contain. Do not use them if you do not want to keep track of the differently sized records.


Example

The following example opens six files for sequential output and puts some test data into them.

Function OnLButtonDblClk ( )

Dim FileName As String, FileNum As Integer, I As Integer

Dim UserMsg As String, SampleTxt As String

' Create test string

SampleTxt = "Here is some sample text."

For I = 1 To 6

' Determine file number

FileNum = FreeFile

FileName = "TEST" & FileNum & ".DAT"

' Open for sequential output

Open FileName For Output As #FileNum

' Write test data to file

Print #FileNum, SampleTxt

Next I

' Close all open files

Close

UserMsg = "Six test files have been created on your disk. "

UserMsg = UserMsg & "Choose OK to delete them."

MsgBox UserMsg

' Delete the test files

Kill "TEST?.DAT"

End Function

For information about using the code examples, see Using the code examples.


See also

Close statement

FreeFile function

Get statement

Print # statement

Put statement

Write # statement


Option Base statement

Example   See also

Declares the default lower bound for array subscripts.

Syntax

Option Base {0 | 1}

0

Specifies that the lowest subscript for arrays in the current module is 0.

1

Specifies that the lowest subscript for arrays in the current module is 1.

Default: 0.

Rule: Must be 0 or 1.

Example:

The following statement declares that the lowest subscript for any arrays you create is 1.

Option Base 1

Description

•	Affects only arrays in the same module.

•	Has no effect on arrays within user-defined types. The lower bound for all such arrays is always 0.

Rules

•	Can appear only once in a module.

•	Can occur only in the Declare... End Declare section.

•	Must be used before you declare the dimensions of any array.

Tips

•	The To clause in Dim, ReDim, and Static provides a more flexible way to control the range of an array's subscripts.

•	If you do not explicitly set the lower bound with a To clause, you can use Option Base to change the default lower bound to 1.


Example

The code in the following example uses Option Base to override the default base array subscript value of 0. The first portion of the example should be pasted at or near the beginning of your Actuate Basic source code (.BAS) file.

Declare

' Module level statement

Option Base 1

End Declare

'

Function OnLButtonDblClk ( )

Dim MyArray1(), Msg, NL

' Define newline

NL = Chr(10)

' Create an array

ReDim MyArray1(25)

Msg = "The lower bound of MyArray1 array is " & LBound(MyArray1) & "."

Msg = Msg & NL & "The upper bound is " & UBound(MyArray1) & "."

MsgBox Msg

End Function

After you compile and run this example once, delete the Option Basic statement lines from your Actuate Basic source code file and compile and test the example again. The lower bound will revert to zero, the default.

For information about using the code examples, see Using the code examples.


See also

Dim statement

LBound function

ReDim statement

Static statement


Option Compare statement

Example   See also

Declares default comparison mode used when comparing string data.

Syntax

Option Compare { Binary | Text }

Binary

String comparisons in the module are case-sensitive by default. For example, if you use Option Compare Binary, then by default "McManus" does not match "MCMANUS" or "mcmanus".

Text

String comparisons in the module are not case-sensitive by default. If you use Option Compare Text, then by default "McManus" matches "MCMANUS" or "mcmanus".

Rules

•	Use Option Compare within a Declare... End Declare section.

•	If used, Option Compare must appear before any statements that declare variables or define constants.


Example

The following example shows the difference between using Option Compare Text and Option Compare Binary. When you run the Option Compare Text example the first time, the uppercase and lowercase versions of your customer's name match. Then remove the Option Compare Text statement and run the Option Compare Binary again to demonstrate that the strings no longer match. To use this example, paste the first portion at or near the beginning of your Actuate Basic source code (.BAS) file, and paste the subroutine into the code window of a clickable control.

Declare

Option Compare Text

End Declare

'

Function OnLButtonDblClk ( )

Dim NameStr As String, UName As String, LName As String

Dim Msg As String

NameStr = InputBox ("Enter customer name.")

UName = UCase(NameStr)

LName = LCase(NameStr)

If UName Like LName Then

   	Msg = UName & " matches " & LName

Else

   	Msg = UName & " does NOT match " & LName

End If

MsgBox Msg

End Function

When you compile your report and try the example, note that the uppercase and lowercase version of the customer's name match. Then delete the Options Compare Text statement from your Actuate Basic source code and compile the example again. The uppercase and lowercase versions of the customer's name will not match because without any Option Compare statement, Option Compare Binary is in effect by default.

For information about using the code examples, see Using the code examples.


See also

InStr function

StrComp function


Pmt function

Example   See also

Returns the payment for an annuity, based on periodic, constant payments, and on an unvarying interest rate.

Syntax

Pmt(<rate per period>, <number pay periods>, <present value>, <future value>, <when due>)

<rate per period>

Numeric expression that specifies the interest rate that accrues per period.

Rule for <rate per period>: Must be given in the same units of measure as <number pay periods>. For instance, if <number pay periods> is expressed in months, then <rate per period> must be expressed as a monthly rate.

<number pay periods>

Numeric expression that specifies the total number of payment periods in the annuity.

Rule for <number pay periods>: Must be given in the same units of measure as <rate per period>. For instance, if <rate per period> is expressed as a monthly rate, then <number pay periods> must be expressed in months.

<present value>

Numeric expression that specifies the value in today's dollars of a future payment, or stream of payments.

Example:

If you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you end up with about $100. In this case, the present value of $100 is approximately $23.94.

<future value>

Numeric expression that specifies the cash balance you want after you have made your final payment.

Examples:

•	You set up a savings plan with a goal of having $75,000 in 18 years to pay for your child's education. For this plan, the future value is $75,000.

•	You take out a loan for $11,000. The future value is $0.00, as it is for any typical loan.

<when due>

Numeric expression that specifies whether each payment is made at the beginning (1), or at the end (0) of each period.

Default: The end of the period (0).

Rule for <when due>: Must be 0 or 1.

Example:

The following example assumes you are making monthly payments the first of each month on a loan of $20,000, over 36 months, at an APR of 11.5%. How much will each of your payments be? The answer ($653.26) is assigned to PaymentAmt.

PaymentAmt = Pmt(.115/12, 36, -20000, 0, 1)

Return value

Double

An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment (such as a monthly savings plan) or a loan (such as a home mortgage).

Rules

•	<rate per period> and <number pay periods> must be expressed in terms of the same units (weekly/weeks, monthly/months, yearly/years).

•	You must express cash paid out (such as deposits to savings) using negative numbers, and cash received (such as dividend checks) using positive numbers.


Example

The following example prompts the user to supply various particulars about a loan. It then returns the amount of the payments.

To use this example, paste the first portion at or near the beginning of your Actuate Basic source code (.BAS) file.

Declare

Global Const ENDPERIOD = 0

' When payments are made

Global Const BEGINPERIOD = 1

End Declare

Function OnLButtonDblClk ( )

Dim Fmt As String, FutureVal As Double, PresVal As Double

Dim APR As Double, TotPmts As Integer, PayWhen As Integer

Dim Period As Integer, InterestPmt As Double, PrincipPmt As Double

Dim Payment As Double, Msg As String

' Specify money format

Fmt = "$###,###,##0.00"

' Normally 0 for a loan

FutureVal = 0

PresVal = InputBox("How much do you want to borrow?")

APR = InputBox("What is the annual percentage rate (APR) for your loan?")

' Ensure proper form as %

If APR > 1	 Then

APR = APR / 100

End If

TotPmts = InputBox("How many monthly payments will you make?")

PayWhen = MsgBox("Payments at the end of month?", MB_YESNO)

If PayWhen = IDNO Then

PayWhen = BEGINPERIOD

Else

PayWhen = ENDPERIOD

End If

Payment = Pmt(APR / 12, TotPmts, -PresVal, FutureVal, PayWhen)

Msg = "Your payments are " & Format(Payment, Fmt) & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

FV function

IPmt function

NPer function

PPmt function

PV function

Rate function


PPmt function

Example   See also

Returns the principal payment for a given period of an annuity, based on periodic, constant payments, and on an unvarying interest rate.

Syntax

PPmt(<rate per period>,<single period>, <number pay periods>, <present value>, <future value>, <when due>)

<rate per period>

Numeric expression that specifies the interest rate that accrues per period.

Rule for <rate per period>: Must be given in the same units of measure as <number pay periods>. For instance, if <number pay periods> is expressed in months, then <rate per period> must be expressed as a monthly rate.

<single period>

Numeric expression that specifies the particular period for which you want to determine how much of the payment for that period represents interest.

Rule for <single period>: Must be in the range 1 through <number pay periods>.

<number pay periods>

Numeric expression that specifies the total number of payment periods in the annuity.

Rule for <number pay periods>: Must be given in the same units of measure as <rate per period>. For instance, if <rate per period> is expressed as a monthly rate, then <number pay periods> must be expressed in months.

<present value>

Numeric expression that specifies the value today of a future payment, or stream of payments.

Example: If you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you end up with about $100. In this case, the present value of $100 is approximately $23.94.

<future value>

Numeric expression that specifies the cash balance you want after you have made your final payment.

Examples:

•	You set up a savings plan with a goal of having $75,000 in 18 years to pay for your child's education. For this plan, the future value is $75,000.

•	You take out a loan for $11,000. The future value is $0.00, as it is for any typical loan.

<when due>

Numeric expression that specifies whether each payment is made at the beginning (1), or at the end (0) of each period.

Default: 0.

Rule for <when due>: Must be 0 or 1.

Example:

The following example assumes you are making monthly payments at the first of each month on a loan of $20,000, over 36 months, at an APR of 11.5%. How much of your 5th payment represents principal? The answer ($481.43) is assigned to Principal5.

Principal5 = PPmt(.115/12, 5, 36, -20000, 0, 1)

Return value

Double

An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment (such as a monthly savings plan) or a loan (such as a home mortgage).

Each payment in an annuity consists of two components: principal and interest. PPmt returns the principal component of the payment.

Rules

•	<rate per period> and <number pay periods> must be expressed in terms of the same units (weekly/weeks, monthly/months, yearly/years).

•	You must express cash paid out (such as deposits to savings) using negative numbers, and cash received (such as dividend checks) using positive numbers.


Example

The following example prompts the user to supply various particulars about a loan. It then returns, for a single payment period the user specifies, the portion of that payment that represents principal, and the portion that represents interest.

To use this example, paste the first portion at or near the beginning of your Actuate Basic source code (.BAS) file.

Declare

Global Const ENDPERIOD = 0

' When payments are made

Global Const BEGINPERIOD = 1

End Declare

'

Function OnLButtonDblClk ( )

Dim Fmt As String, FutureVal As Double, PresVal As Double

Dim APR As Double, TotPmts As Integer, PayWhen As Integer

Dim Period As Integer, IntPmt As Double, PrinPmt As Double

Dim Payment As Double, Msg As String

'

' Specify money format

Fmt = "$###,###,##0.00"

' Normally 0 for a loan

FutureVal = 0

PresVal = InputBox("How much do you want to borrow?")

APR = InputBox("What is the annual percentage rate (APR) for your loan?")

' Ensure proper form as %

If APR > 1 Then

APR = APR / 100

End If

TotPmts = InputBox("How many monthly payments will you make?")

PayWhen = MsgBox("Payments at month end?", MB_YESNO)

If PayWhen = IDNO Then

PayWhen = BEGINPERIOD

Else

PayWhen = ENDPERIOD

End If

Msg = "Which payment period are you interested in?  "

Msg = Msg & "Please type a number from 1 to " & TotPmts

Period = InputBox(Msg)

IntPmt = IPmt(APR / 12, Period, TotPmts, -PresVal, FutureVal, PayWhen)

PrinPmt = PPmt(APR / 12, Period, TotPmts, -PresVal, FutureVal, PayWhen)

Payment = Pmt(APR / 12, TotPmts, -PresVal, FutureVal, PayWhen)

Msg = "At period " & Period & " you will pay a total "

Msg = Msg & " of " & Format(Payment, Fmt) & ", representing "

Msg = Msg & Format(PrinPmt, Fmt) & " principal and "

Msg = Msg & Format(IntPmt, Fmt) & " interest.  "

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

FV function

IPmt function

NPer function

Pmt function

PV function

Rate function


Print # statement

Example   See also

Writes unformatted data to a sequential file.

Syntax

Print #<file number>, [ [{ Spc(<number of blanks>) | Tab(<tab column>) } ] [ <expression list> ] [ { ; | , } ]... ]

<file number>

Numeric expression that is the file number used to Open a sequential file to which Print # writes data.

Example:

The following example writes "Hello, world!" to the file opened under file number 1, and appends a carriage-return-linefeed character-pair (CRLF) to the file, so that whatever is next written to the file appears on the next line.

Print #1, "Hello, world!"

The following example shows three statements that work together, although they can be separated from one another by any number of lines of code. The first statement opens a file called "MYNOTES.FIL", the second one writes to that file, and the third, by closing it, turns the file over to the operating system to complete the process of writing it to the disk.

Open "C:\MYFILES\MYNOTES.FIL" For Output As #2

Print #2, "This datum.", "This datum, too. "

Close #2

Spc(<number of blanks>)

Clause that inserts spaces into the output. May be repeated; separated by commas or semicolons.

<number of blanks>

Numeric expression that specifies the number of spaces Spc inserts.

Example:

Print #2, "This datum.", Spc(10), "This datum, too.", Spc(5), "And this."

Tab(<tab column>)

Clause that tabs to the specified column before the program prints <expression list>. May be repeated; separated by commas or semicolons.

<tab column>

Numeric expression that specifies the column to which the program jumps before it prints the <expression list>.

Example:

Print #2, "This datum."; Tab(5); "This datum, too."; Tab(7); "And this."

<expression list>

Numeric and/or string expressions that specify the data that Print # writes to the file. There can be any number of these.

Default: Blank line, if comma is used.

; (semicolon)

Character (semicolon) that determines the position of the next character printed. Instructs Actuate Basic to print the next character immediately after the last one.

, (comma)

Character (comma) that determines the position of the next character printed. Instructs Actuate Basic to print the next character at the start of the next print zone. Print zones begin every 14 columns.

Default position for next character: Next line.

Example:

The following example writes the number 250, and the content of P$ to the file. The comma after the number 250 causes P$ to be written at the next print zone. The semicolon after P$ causes Actuate Basic to suppress the printing of the carriage-return-linefeed character-pair, so that whatever is next written to the file occurs immediately after the text in P$.

Print #1, 250, P$;

Description

Print # usually writes Variant data to a file the same way it writes any other Actuate Basic data type. However, there are some exceptions:

Data type	Print # writes this to the file
Variant of VarType 0 (Empty)	Nothing at all
Variant of VarType 1 (Null)	The literal value Null
Variant of VarType 7 (Date)	The date, using whatever Short Date format is defined in the Control Panel
Variant of VarType 7 (Date), but with either the date or time component missing or zero	Only the part of the date provided
Rules

•	<file number> must match the number of a currently open file.

•	The file corresponding to <file number> must be open under either the Output or Append mode.

•	You must have write access to the open file. That is, the file must not have been opened using a Lock Write or Lock Read Write clause.

•	The data cannot be an object variable, user-defined data type structure, handle to a class, CPointer, or OLE object.

Tips

•	To ensure integrity of separate data fields, use Write # instead of Print #. Write # delimits data properly and ensures that the data can be read correctly in any locale.

•	Use Print # with ASCII text files.

•	Spacing of data displayed on a text screen with monospaced characters may not work well when the data is redisplayed in a graphical environment using proportionally spaced characters.


Example

The following example creates a file called TESTFILE.TXT, writes some data in it, then closes it. It then reopens the file in order to read the data just written. Finally, after displaying a message, it closes the file and deletes it.

Function OnLButtonDblClk ( )

Dim TestData As String, UserMsg As String, NL As String

' Define newline

NL = Chr$(10)

' Open to write file

Open "TESTFILE.TXT" For Output As #1

Print #1, "Test of the Print # statement."

' Print extra blank line to file

Print #1,

' Print in two print zones

Print #1, "Zone 1", "Zone 2"

' Print two strings together

Print #1, "With no space between"; "these"

Close #1

' Open to read file

Open "TESTFILE.TXT" For Input As #1

' Read entire file

Do While Not EOF(1)

' Read a line

Line Input #1, TestData

' Construct message

UserMsg = UserMsg & TestData & NL

Loop

Close #1

MsgBox UserMsg

' Delete file from disk

Kill "TESTFILE.TXT"

End Function

For information about using the code examples, see Using the code examples.


See also

Open statement

Write # statement


Put statement

Example   See also

Writes data from a variable to a disk file.

Syntax

Put [#] <open file number>, [<record number>], <variable to write>

<open file number>

Numeric expression that specifies the number you used in the previously issued Open that opened the file to which you now want to write using Put.

<record number>

Numeric expression.

•	For files opened in Random mode, <record number> is the number of the record to be written.

•	For files opened in Binary mode, it is the byte position at which writing starts, where the first byte in a file is at position 1, the second byte at position 2, and so on.

Default: The next record or byte--that is, the one following the last Get or Put statement, or the one pointed to by the last Seek2 function.

Rules for <record number>:

•	If you omit <record number> you must still include the delimiting commas that would have been on either side of it had you included it. For example,

Put #1, , HoldingVar1

•	Must be between 1 and 2,147,483,647.

<variable to write>

String expression that specifies the variable to write to the open file.

Rules for <variable to write>:

•	Cannot be an object variable, user-defined data type structure, handle to a class, CPointer, or OLE object.

•	Cannot be an array variable that refers to an entire array, although you can use one that describes a single element of an array.

Description

For Files Opened in Random Mode:

•	If the length of the data you write is less than the length specified in the Len clause of the Open statement, Put still writes subsequent records on record-length boundaries. The space between the end of one record and the beginning of the next is padded with the existing contents of the file buffer.

Example:

In the following example, the first Put writes the 4 bytes of the variable HoldingVar1 to the disk file "myfile.txt" at byte positions 1-4. Any data that was there is overwritten. The second Put, however, does not pick up where the last one left off but instead skips to the record-length boundary (20) and starts counting from there, which means it writes the 5 bytes of HoldingVar2 to byte positions 21-25. The intervening bytes (5-20) remain what they were, but now represent padding between records.

Dim HoldingVar1 As String * 4

Dim HoldingVar2 As String * 5

Open "myfile.txt" For Random As #1 Len = 20

HoldingVar1 = "1234"

HoldingVar2 = "12345"

Put #1, , HoldingVar1

Put #1, , HoldingVar2

•	The following table summarizes how Put behaves depending on the data type of <variable to write>. "Open" here refers to the particular statement that opened the file in question

<variable to write>	Put writes, in order	Rules
Variable-length  string	1 2-byte descriptor containing string length 2 Data in the variable	Record length specified in the Len clause of Open must be at least 2 bytes greater than the actual length of the string.
Numeric Variant  (Variant Types 0-7)	1 2-byte descriptor that identifies the type of the Variant 2 Data in the variable	Len clause length must be at least 2 bytes greater than the actual number of bytes required to store the variable.
String Variant (Variant Type 8)	1 2-byte Variant Type descriptor 2 2 bytes indicating the string length 3 Data in the variable	Len clause length must be at least 4 bytes greater than the actual length of the string.
Any other type of variable	1 Data in the variable	Len clause length must be greater than or equal to the length of the data.
For Files opened in Binary mode:

All the Random descriptions and rules above apply except that the Len clause in Open has no effect. Put writes all variables to disk contiguously, that is, with no padding between records.

Example:

In the following example, the first Put writes the 4 bytes of the variable HoldingVar1 to the disk file "myfile.txt" at byte positions 1-4. The second Put writes the 5 bytes of HoldingVar2 to byte positions 5-10. No data shows between them as padding.

Dim HoldingVar1 As String * 4

Dim HoldingVar2 As String * 5

Open "myfile.txt" For Binary As #1 Len = 20

HoldingVar1 = "1234"

HoldingVar2 = "12345"

Put #1, , HoldingVar1

Put #1, , HoldingVar2

For variable-length strings, Put does not write a 2-byte descriptor; it writes the number of bytes equal to the number of characters already in the string.

Example:

The following example writes 12 bytes to file number 1:

VariLen$ = String$(12, "*")

Put #1, , VariLen$

Tip

To avoid corrupting or misreading data, be sure your record lengths and/or variable lengths match the lengths of the data you want to read or write.


Example

The following example prompts the user to type three customer names. It write each name in turn to a test file and then reads the names back.

Function OnLButtonDblClk ( )

Dim CustName As String

Dim Indx As Integer, Max As Integer, Msg As String, NL As String

NL = Chr$(10)

CustName = String(20, " ")

'Generate sample random-access file using PUT:

Msg = "Please type a name." & NL & NL

Msg = Msg & "When finished, press 'Enter' with no name."

Open "testfil3.txt" For Random As #1 Len = Len(CustName)

' Get user input

CustName = InputBox(Msg)

Do While CustName <> " " And CustName <> ""

' Write to file

Put #1, , CustName

' Get user input

CustName = InputBox(Msg)

Loop

'Read the sample random-access file using GET:

Max = Loc(1)

' Check if records exist

If Max = 0 Then

Msg = "Sorry, your file contains no names." & NL

Else

Msg = "Your file contains the following names:" & NL & NL

End If

For Indx = 1 To Max

' Read from test file

Get #1, Indx, CustName

Msg = Msg & CustName & NL

Next Indx

' Close file

Close #1

Msg = Msg & NL & "Please press OK to delete the test file."

MsgBox Msg

' Delete test file

Kill "testfil3.txt"

End Function

For information about using the code examples, see Using the code examples.


See also

Get statement

Open statement

Type...End Type statement


PV function

Example   See also

Returns the present value of an annuity based on periodic, constant payments to be paid in the future, and on an unvarying interest rate.

Syntax

PV(<rate per period>,<number pay periods>,<each pmt>, <future value>, <when due>)

<rate per period>

Numeric expression that specifies the interest rate that accrues per period.

Rule for <rate per period>: Must be given in the same units of measure as <number pay periods>. For instance, if <number pay periods> is expressed in months, then <rate per period> must be expressed as a monthly rate.

<number pay periods>

Numeric expression that specifies the total number of payment periods in the annuity.

Rule for <number pay periods>: Must be given in the same units of measure as <rate per period>. For instance, if <rate per period> is expressed as a monthly rate, then <number pay periods> must be expressed in months.

<each pmt>

Numeric expression that specifies the amount of each payment.

Rule for <each pmt>: Must be given in the same units of measure as <rate per period>. For instance, if <rate per period> is expressed in months, then <each pmt> must be expressed as a monthly payment.

<future value>

Numeric expression. Specifies the cash balance you want after you have made your final payment.

Examples:

•	You set up a savings plan with a goal of having $75,000 in 18 years to pay for your child's education. For this plan, the future value is $75,000.

•	You take out a loan for $11,000. The future value is $0.00, as it is for any typical loan.

<when due>

Numeric expression that specifies whether each payment is made at the beginning (1), or at the end (0) of each period.

Default: 0.

Rule: Must be 0 or 1.

Examples:

The following example assumes you are considering the purchase of a corporate bond with a $1000 face value. The bond pays an annual coupon of $100, matures in 15 years, and the next coupon is paid at the end of one year. The yield to maturity on similar bonds is 12.5%. What is a fair price for this bond (its present value)? The answer ($834.18) is assigned to the variable PresentValue.

PresentValue = PV(.125, 15, 100, 1000, 0)

The following examples assumes you have won the lottery. The jackpot is $10 million, which you receive in yearly installments of $500,000 per year for 20 years, beginning one year from today. If the interest rate is 9.5% compounded annually, how much is the lottery worth today? The answer ($4,406,191.06) is assigned to PresentValue.

PresentValue = PV(.095, 20, 50000,10000000, 0)

The following example assumes you want to save $11,000 over the course of 3 years. If the APR is 10.5% and you plan to save $325 monthly, and if you make your payments at the beginning of each month, how much would you need to start off with in your account to achieve your goal? The answer ($2,048.06) is assigned to StartValue. Note that <each pmt> is expressed as a negative number because it represents cash paid out.

StartValue = PV(.105/12, 3*12, -325, 11000, 1)

Return value

Double

An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment (such as a monthly savings plan) or a loan (such as a home mortgage). The present value is the value today of a future payment, or of a stream of payments structured as an annuity.

Example: If you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you end up with about $100. So, the present value of $100 is approximately $23.94.

Rules

•	<rate per period> and <number pay periods> must be expressed in terms of the same units (if weekly/then weeks, monthly/months, yearly/years, and so on).

•	You must express cash paid out (such as deposits to savings) using negative numbers, and cash received (such as dividend checks) using positive numbers.


Example

The following example prompts the user to supply the amount to save or invest each month, the annual percentage rate (APR) of the interest, the total number of payments, a target amount, and when during the month payments are made. Then it interprets the present value as the amount the user would have to start with in order to achieve the goal.

To use this example, copy the first portion at or near the beginning of your Actuate Basic source code (.BAS) file.

Declare

Global Const ENDPERIOD = 0

Global Const BEGINPERIOD = 1

End Declare

'

Function OnLButtonDblClk ( )

Dim EachPmt As Double, APR As Double, Fmt As String, Msg As String

Dim TotalPmts As Single, PayWhen As Integer

Dim PresentVal As Double, FutureVal As Double

' Specify money format

Fmt = "$###,###,##0.00"

EachPmt = InputBox("How much do you save each month?")

APR = InputBox("What is the annual percentage rate for the interest?")

' Ensure proper form as %

If APR > 1 Then

APR = APR / 100

End If

TotalPmts = InputBox("For how many months are you saving?")

PayWhen = MsgBox("Payments at month's end?", MB_YESNO)

If PayWhen = IDNO Then

PayWhen = BEGINPERIOD

Else

PayWhen = ENDPERIOD

End If

FutureVal = InputBox("What amount is your goal?")

PresentVal = PV(APR / 12, TotalPmts, -EachPmt, FutureVal, PayWhen)

Msg = "Starting with " & Format(-PresentVal, Fmt) & " "

Msg = Msg & " and saving " & Format(EachPmt, Fmt) & " every month at "

Msg = Msg & "an interest rate of " & Format(APR, "##.0%") & " for a period "

Msg = Msg & "of " & TotalPmts & " months brings you to your goal of "

Msg = Msg & Format(FutureVal, Fmt) & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

FV function

IPmt function

NPer function

Pmt function

PPmt function

Rate function


QBColor function

Example   See also

Translates the numeric representations for colors from older BASIC languages such as Quick Basic to those used by Actuate Basic.

Syntax

QBColor(<number to translate>)

<number to translate>

Integer that specifies the number of a color, specifically one of the 16 standard Windows colors.

Rules:

•	Must be between 00 and 15, inclusive.

•	If <number to translate> evaluates to a Null, QBColor returns a Null.

Return value

Long

The following table shows the 16 color codes QBColor accepts, their names, and their equivalents in Actuate Basic--that is, the values returned by QBColor.

Older BASIC Code Number	Color Name	Actuate Code Number
00	Black	00
01	Blue	8388608
02	Green	32768
03	Cyan	8421376
04	Red	128
05	Magenta	8388736
06	Yellow	32896
07	White	12632256
08	Gray	8421504
09	Bright Blue	16711680
10	Bright Green	65280
11	Bright Cyan	16776960
12	Bright Red	255
13	Bright Magenta	16711935
14	Bright Yellow	65535
15	Bright White	16777215
Tips

There are at least four ways to represent a color in Actuate Basic. You can:

•	Specify the relative mix of red, green, and blue in a color by using RGB with decimal numbers.

•	Directly specify, without using RGB or any function, the relative mix using hexadecimal numbers in a certain format.

•	Use one of the 16 standard Windows colors by supplying the appropriate integer to QBColor.

•	Use one of the appropriate color name constants from HEADER.BAS.


Example

The following example displays a variety of color shades on a component.

Function OnLButtonDblClk( )

Dim UserAns, Msg

Msg = "The 16 standard Windows colors are specified by "

Msg = Msg & "integers from 0 to 15.  Please type an integer "

Msg = Msg & "from 0 to 15 to see its equivalent in "

Msg = Msg & "Actuate Basic."

UserAns = InputBox(Msg)

MsgBox "The Actuate Basic code for that color is:  " & QBColor(UserAns)

End Function

For information about using the code examples, see Using the code examples.


See also

RGB function


Randomize statement

Example   See also

Initializes the random number generator so it can generate a new sequence of apparently random numbers.

Syntax

Randomize [<seed number>]

<seed number>

Numeric expression that specifies the number that initializes the random number generator by supplying it with a new seed value.

Rule: Must be between -2,147,483,648 and 2,147,483,647.

Examples:

Randomize

Randomize 34

Description

Actuate Basic supplies you with Randomize and Rnd as tools for generating random numbers.

Randomize generates a sequence of pseudo-random numbers by starting with a seed value. The randomizing function then takes that initial seed value and uses it to generate the first number in the pseudo-random sequence. Then it uses that number in turn to produce the second one, and so on. The result is a series of numbers that vary well enough to seem to have no pattern, or in other words, to be random.

Rules

•	If you do not use Randomize, Rnd returns the same sequence of numbers every time the program is run.

•	Use Randomize before Rnd, or it will have no effect.

Tips

•	To generate numbers that seem truly random, use Randomize--with no argument--at the beginning of your program. In that case, Actuate Basic uses a randomizing seed based on the current running system time, which is almost certain to vary randomly whenever you run the program.

•	Although, you can use Randomize several times throughout a program, it works best if you use it only once, at the beginning.

•	To help you debug certain programs, use Randomize with a specific <seed number>. That way, the same "random" numbers repeat every time you run the program.


Example

The following example simulates rolling a die twice by generating random values between 1 and 6 for each roll.

Function OnLButtonDblClk ( )

Dim DieRoll1, DieRoll2, UserMsg

' Seed random num generator

Randomize

' First roll

DieRoll1 = Int(6 * Rnd + 1)

' Second roll

DieRoll2 = Int(6 * Rnd + 1)

UserMsg = "You rolled a " & DieRoll1

UserMsg = UserMsg & " and a " & DieRoll2

UserMsg = UserMsg & " giving a total of "

UserMsg = UserMsg & (DieRoll1 + DieRoll2) & "."

MsgBox UserMsg

End Function

For information about using the code examples, see Using the code examples.


See also

Rnd function


Rate function

Example   See also

Returns the interest rate per period for an annuity.

Syntax

Rate(<number pay periods>,<each pmt>, <present value>, <future value>, <when due>, <starting guess>)

<number pay periods>

Numeric expression that specifies the total number of payment periods in the annuity.

Rule for <number pay periods>: Must be given in the same units of measure as <each pmt>. For instance, if <each pmt> is expressed as a monthly payment, then <number pay periods> must be expressed in months.

<each pmt>

Numeric expression that specifies the amount of each payment.

Rule for <each pmt>: Must be given in the same units of measure as <number pay periods>. For instance, if <number pay periods> is expressed in months, then <each pmt> must be expressed as a monthly payment.

<present value>

Numeric expression that specifies the value today of a future payment, or of a stream of payments.

Example: If you put $23.94 in the bank today and leave it there for 15 years at an interest rate of 10% compounded annually, you will end up with about $100. So in this case, the present value of $100 is approximately $23.94.

<future value>

Numeric expression that specifies the cash balance you want after you have made your final payment.

Examples:

•	You set up a savings plan with a goal of having $75,000 in 18 years to pay for your child's education. For this plan, the future value is $75,000.

•	You take out a loan for $11,000. The future value is $0.00, as it is for any typical loan.

<when due>

Numeric expression that specifies whether each payment is made at the beginning (1), or at the end (0) of each period.

Default: 0.

Rule: Must be 0 or 1.

<starting guess>

Numeric expression that specifies the value you estimate Rate will return. In most cases, this is 0.1 (10 percent).

Example:

The following example assumes you have taken out a loan for $20,000, that you are paying off over the course of 3 years. If your payments are $653.26 per month, and you make them at the beginning of each month, what interest rate (APR) are you paying? The answer (.115 or 11.5%) is assigned to the variable InterestRate. Note that the return value of Rate must be multiplied by 12 in order to yield an annual rate.

InterestRate = Rate(3*12, -653.26, 20000, 0, 1, .1) * 12

Return value

Double

An annuity is a series of cash payments, constant in value, made over a period of time. An annuity can be an investment (such as a monthly savings plan) or a loan (such as a home mortgage).

Rate calculates the interest rate on an annuity iteratively. Starting with the value of <starting guess>, it repeats the calculation until the result is accurate to within 0.00001 percent. If it cannot determine a result after 20 iterations, the function fails.

Rules

•	<number pay periods>, and <each pmt> must be expressed in terms of the same units (weekly/weeks, monthly/months, yearly/years, and so on).

•	You must express cash paid out (such as deposits to savings) using negative numbers, and cash received (such as dividend checks) using positive numbers.

Tips

•	Because Rate uses the order of values within the array to interpret the order of payments and receipts, be sure to enter your payment and receipt values in the correct sequence.

•	If Rate fails, try a different value for <starting guess>.


Example

The following example prompts the user for particulars about a loan, then returns the interest rate. To use this example, paste the first portion at or near the beginning of your Actuate Basic source code (.BAS) file. Then copy the procedure into the Method Window for a clickable component.

Declare

Global Const ENDPERIOD = 0

' When payments are made

Global Const BEGINPERIOD = 1

End Declare

'

Function OnLButtonDblClk ( )

Dim Fmt As String, FutVal As Double, Guess As Double

Dim PresVal As Double, Pymt As Double, TotalPmts As Integer

Dim PayWhen As Integer, APR As Double

' Define percentage format

Fmt = "##0.00"

' Usually 0 for a loan

FutVal = 0

' Guess of 10 percent

Guess = .1

PresVal = InputBox("What is the loan amount?")

Pymt = InputBox("What is the monthly payment?")

TotalPmts = InputBox("How many monthly payments are needed?")

PayWhen = MsgBox("Payments at month end?", MB_YESNO)

If PayWhen = IDNO Then

PayWhen = BEGINPERIOD

Else

PayWhen = ENDPERIOD

End If

APR = (Rate(TotalPmts, -Pymt, PresVal, FutVal, PayWhen, Guess) * 12)* 100

MsgBox "Your interest rate is " & Format(APR, Fmt) & " percent."

End Function

For information about using the code examples, see Using the code examples.


See also

FV function

IPmt function

NPer function

Pmt function

PPmt function

PV function


ReDim statement

Example   See also

Declares a new dynamic array variable or changes the size of an existing dynamic array variable, and reallocates memory if needed.

Syntax

ReDim [Preserve] <array variable name>(<subscripts>) [As <type>], <array variable name>(<subscripts>) [As <type>]. . .

Preserve

Retains the data in an existing array when you resize the last dimension. With Preserve, if you decrease the size of any dimension, you will lose some of the data in that dimension although the data in the others will be retained.

<array variable name>

Name you create for the array.

<subscripts>

Each <subscripts> argument specifies the number of elements in a dimension. The number of <subscripts> arguments specifies the number of dimensions in the array.

Array dimensions using the following syntax:

[<lower> To]<upper>[,[<lower> To]<upper>]...

Rules for <subscripts>:

•	<lower> and <upper> can range from -2,147,483,647 to 2,147,483,647 inclusive.

•	<lower> must always be less than <upper>.

•	Each ReDim can specify up to 60 dimensions.

•	When working with an existing array, you cannot add dimensions. That is, the number of <subscripts> arguments must not exceed the number given when the array was originally declared.

•	When working with an existing array, you cannot add dimensions. The number of [<lower>To] <upper> pairs must not exceed the number given when the array was originally declared.

In the following example, the statements are equivalent if you do not use Option Base:

ReDim P(7,5)

ReDim P(0 TO 7, 0 TO 5)

ReDim P(7, 0 TO 5)

As <type>

Specifies a data type or class for the variable. If you specify a class, the variable can hold a reference to an instance of that class or descendant classes. You must use As <type> to declare the variable that you use to specify the dimensions of an array. If you do not specify a data type in Actuate Basic, the data type for a variable defaults to the Variant data type, which cannot be used as a parameter for sizing an array with the ReDim statement.

Rules

•	Use ReDim only at the procedure level.

•	Use ReDim to change the number of elements in an array, not the number of dimensions.

•	You cannot use ReDim to resize a fixed-size array.

•	You cannot change the data type of an existing array.

Tips

•	To work with large arrays, use ReDim, which dynamically allocates memory as needed.

•	To create a dynamic array with more than eight dimensions, declare it with ReDim, not Dim.

•	To clear the values in an array, use ReDim without Preserve.

To avoid debugging problems, note that variables declared with Dim are automatically initialized as follows

Type	Initialized As
Numeric	0
Variant	Empty
Variable-length strings	Empty string("")
User-defined type	Separate variables
Object or class	Nothing (before Set)
CPointer	Null


Example

The following example dynamically resizes an array while a procedure is running.

Function OnLButtonDblClk ( )

Dim Customer1 As Integer, Customer2 As Integer, Msg As String

Dim NL As String, I As Integer

NL = Chr$(10)

Customer1 = 5

Customer2 = 10

ReDim MyArray(Customer1)

For I = 1 To Customer1

MyArray(I) = I ^ 2

Msg = Msg & I & ": " & MyArray(I) & NL

Next I

MsgBox Msg

ReDim MyArray(Customer2)

For I = 1 To Customer2

MyArray(I) = I ^ 2

Msg = Msg & I & ": " & MyArray(I) & NL

Next I

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Dim statement


Rem statement

Example   See also

Inserts comments or explanatory remarks in a program.

Syntax

{Rem | :Rem | ' }<comment>

<comment>

Any characters or numbers, including spaces or punctuation. <comment> is a remark that explains what is happening in the program.

Description

•	All text to the right of Rem is ignored by the compiler.

•	<comment> appears exactly as you entered it when the program is listed.

•	If you branch from a GoTo statement to a line that contains Rem, program execution continues with the first executable statement that follows Rem.

To place a comment on the same line as a code instruction, precede the comment either with the apostrophe identifier or with :Rem.

For A = 1 To 20	 'This code steps through the 20 items

For A = 1 To 20	 : REM This code steps through the 20 items

To place a comment on a line by itself, precede the comment with any one of the three identifiers.

Rem The third line after this steps through the 20 items of the array.

: Rem The second line after this steps through the 20 items of the array.

' The next line steps through the 20 items of the array.

For A = 1 To 20

Tips

•	Use comments liberally throughout your program to explain how the code works.

•	To disable a line of code when debugging, precede it with one of the three Rem identifiers. Temporarily "commenting out" the line lets you see what happens when that line is left out of the program.


Example

The following example shows various ways in which you can use Rem.

Function OnLButtonDblClk ( )

Dim Message1, Message2, Message3, NL, AllMessages

' Define newline

NL = Chr(10)

Rem The compiler will ignore this entire line.

' This line will also be ignored.

Message1 = "First message line." 	:Rem Colon needed before REM here

Message2 = "Second message line."	' But this one needs no colon

: Rem This line has a colon, but really does not need it.

Message3 = "This example shows different ways to use REM."

AllMessages = Message1 & NL & Message2 & NL & Message3

MsgBox AllMessages

End Function

For information about using the code examples, see Using the code examples.


See also

Format, Format$ functions

Str, Str$ functions


Reset statement

Example   See also

Writes all data in open file buffers to the appropriate disk files, then closes all open disk files.

Syntax

Reset

Description

Performs the same task as Close with no parameters.


Example

The following example creates and opens two test files, closes them using Reset, then reopens them and reads back the data. Finally, it deletes the test files.

Function OnLButtonDblClk ( )

Dim FirstVar, SecondVar

Open "testalpha.fil" for Output As #1

Open "testbeta.fil" for Output As #2

Print #1, "This line is in the first test file."

Print #2, "This line is in the second test file."

Reset

Open "testalpha.fil" for Input As #1

Open "testbeta.fil" for Input As #2

Line Input #1, FirstVar

Line Input #2, SecondVar

Reset

MsgBox FirstVar & "  " & SecondVar

Reset

MsgBox "Press okay to delete the test files."

Kill "testalpha.fil"

Kill "testbeta.fil"

End Function

For information about using the code examples, see Using the code examples.


See also

Close statement

End statement


Resume statement

Example   See also

Releases control from an error-handling routine and resumes program execution at a specified place.

Syntax

Resume { [0] | Next | <line> | <line label> }

[0]

Keyword (an optional zero) indicating that Actuate Basic is to resume program execution with the statement that caused the error, or with the statement that last called out of the procedure containing the error handler.

Examples:

The following two statements are equivalent:

Resume

Resume 0

Next

Keyword indicating that Actuate Basic is to resume program execution with the statement following the one that caused the error, or with the statement following the one that last called out of the procedure containing the error handler.

Example:

Resume Next

<line> or <line label>

Keyword indicating the line number or line label at which Actuate Basic is to resume execution.

Rule: Must be in the same procedure as the error handler.

Example:

The following example instructs Actuate Basic to continue execution at the label "Continuation".

Resume Continuation

Description

Where Actuate Basic resumes execution depends on the location of the error handler in the which the error is trapped, not necessarily on the location of the error itself. The following table summarizes where a program resumes execution when either the Resume [0] or Resume Next statement is used.

Error occurred	Resume [0]	Resume Next
In the same procedure as the error handler	The statement that caused the error	The statement after the one that caused the error
In a different procedure from the error handler	The statement that last called out of the procedure containing the error handler	The statement after the one that last called out of the procedure containing the error handler
Rules

•	You can only use Resume in an error-handling routine.

•	You can only exit an error-handling routine by using Resume, not by using End Sub or End Function.


Example

The code in the following example generates two errors in succession and does something different in each case. In the first case, the error routine displays the error number and description and then uses Resume to resume execution of the code at the line following the line that caused the error. In the second case, the error routine displays a simple message and uses Resume to branch to a specified routine. This branch causes the flow of program execution to skip the line following the one that caused the error.

Function OnLButtonDblClk()

On Error GoTo ErrorHandler

Dim Zilch, Zero, DivisionByZero, Nada

Zilch = 0

Zero = 0

DivisionByZero = Zilch/Nada

MsgBox "This is the next line after the divide-by-zero error."

Open "z:\zzzzzz.zzz" for Input As #1

MsgBox "This is the next line after the file error. It is skipped."

Badfile:

MsgBox "This line is in the Badfile routine."

Exit Function

ErrorHandler:

If Err = 8 Then

MsgBox "Sorry!  Error number: " & Err & " occurred: " & Error$(Err)

Resume Next

Else

MsgBox "A file error!  Rerouting to the Badfile label."

Resume Badfile

End If

End Function

For information about using the code examples, see Using the code examples.


See also

On Error statement


RGB function

Example   See also

Returns a number representing the RGB color value for a given mix of red, green and blue values.

Syntax

RGB(<red>, <green>, <blue>)

<red>

Integer indicating the red value of the color.

Rules for <red>:

•	If <red> is greater than 255, <red> defaults to 255.

•	If <red> is empty, <red> defaults to 0.

•	<red> must be greater than 0.

•	<red> must not be Null.

<green>

Integer indicating the green value of the color.

Rules for <green>:

•	If <green> is greater than 255, <green> defaults to 255.

•	If <green> is empty, <green> defaults to 0.

•	<green> must be greater than 0.

•	<green> must not be Null.

<blue>

Integer indicating the blue value of the color.

Rules for <blue>:

•	If <blue> is greater than 255, <blue> defaults to 255.

•	If <blue> is empty, <blue> defaults to 0.

•	<blue> must be greater than 0.

•	<blue> must not be Null.

Return value

Long

•	Returns a number between 0 and 16,777,215, inclusive.   This single number represents the relative intensities of red, green, and blue that make up a particular color.

•	The following table shows some standard colors. For each color, you see the decimal values returned by RGB, the hexadecimal equivalent, the corresponding QBColor number, and the mix of red, green and blue decimal values that make up the color.

Color	RGB Value (Dec)	RGB Value (Hex)	QBColor	Red Value	Green Value	Blue Value
Black	0	&H00	0	0	0	0
Blue	16711680	&HFF0000	1	0	0	255
Green	65280	&HFF00	2	0	255	0
Cyan	16776960	&HFFFF00	3	0	255	255
Red	255	&HFF	4	255	0	0
Magenta	16711935	&HFF00FF	5	255	0	255
Yellow	65535	&HFFFF	6	255	255	0
White	16777215	&HFFFFFF	15	255	255	255
Gray	8421504	&H808080	8	128	128	128
Tips

There are four ways in which you can precisely represent a color in Actuate Basic.

•	Specify the relative mix of red, green and blue in a color by using RGB with decimal numbers, as described here.

•	Directly specify, without using RGB or any function, the relative mix using hexadecimal numbers in a certain format

•	Use one of the 16 standard Windows colors by supplying the appropriate integer to QBColor.

•	Use one of the built-in color constant names, such as BLUE.


Example

The following example returns the RGB value for a mix of red, green, and blue values specified by the user.

Function OnLButtonDblClk ( )

Dim NL As String, RedPart As Integer, GreenPart As Integer

Dim BluePart As Integer

Dim HexVersion, Msg As String, RGBNumber

NL = Chr$(10)

RedPart = InputBox("How much red?")

GreenPart = InputBox("How much green?")

BluePart = InputBox("How much blue?")

RGBNumber = RGB(RedPart, GreenPart, BluePart)

HexVersion = Hex(RGBNumber)

Msg = "Red component: " & RedPart & NL

Msg = Msg & "Green component: " & GreenPart & NL

Msg = Msg & "Blue component: " & BluePart & NL

Msg = Msg & "The decimal representation of that mix of "

Msg = Msg & "red, green, and blue is: "

Msg = Msg & RGBNumber & "." & NL

Msg = Msg & "The hex representation of it is: "

Msg = Msg & HexVersion

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

QBColor function


Right, Right$ functions

Example   See also

Returns a segment of a Variant or String, starting at the rightmost character and working to the left.

Syntax

Right(<string exprs>, <length>)

Right$(<string exprs>, <length>)

<string exprs>

Source string from which you are copying a rightmost portion. It can be a variable string, a literal string, a string constant, the return value of any function that returns a string, or a Variant that can evaluate to a String.

<length>

Long that specifies how many characters to copy from the right of <string exprs>.

•	<length> must be an Integer or expression between 0 and 2,147,483,647.

•	In the following example, the statements are equivalent. Both simply return "Widget".

Right$("Widget",6)

Right$("Widget",99)

Return values

Right: Variant

Right$: String

•	If <length> = 0, returns zero-length string.

•	If <length> is greater than or equal to the length of <string exprs>, returns an exact copy of <string exprs>.

Tip

•	Use Len to find the number of characters in <string exprs>.

•	Use InStr to find the position of a specified character in <string exprs>.


Example

The following example asks the user to input a customer's first and last names, then returns the last name.

Function OnLButtonDblClk ( )

Dim FName As String, Msg As String, Message As String

Dim LName As String, SpacePos As Integer, UserInput As String

Msg = "Please enter a customer's first and last names, "

Msg = Msg & " separated by a space."

' Get user's input

UserInput = InputBox(Msg)

' Find the space

SpacePos = InStr(1, UserInput, " ")

If SpacePos Then

' Get first & last names

FName = Left$(UserInput, SpacePos - 1)

LName = Right$(UserInput, Len(UserInput) - SpacePos)

Message = "The first name is """ & FName

Message = Message & "." & """" & " The last name is """

Message = Message & LName & "." & """"

Else

Message = "You did not enter a first and last name."

End If

' Display the message

MsgBox Message

End Function

For information about using the code examples, see Using the code examples.


See also

InStr function

Left, Left$ functions

Len function

Mid, Mid$ functions


RightB, RightB$ functions

Example   See also

Returns a segment of a Variant or String, starting at the rightmost byte and working to the left.

Syntax

RightB(<string exprs>, <length>)

RightB$(<string exprs>, <length>)

<string exprs>

Source string from which you are copying a rightmost portion. It can be a variable string, a literal string, a string constant, the return value of any function that returns a string, or a Variant that can evaluate to a String.

<length>

Long that specifies how many bytes to copy from the right of <string exprs>.

•	<length> must be an Integer or expression between 0 and 2,147,483,647.

•	In the following example, the statements are equivalent. Both simply return "Widget".

RightB$("Widget",6)

RightB$("Widget",99)

Return values

RightB: Variant

RightB$: String

•	If <length> = 0, returns zero-length string.

•	If <length> is greater than or equal to the length of <string exprs>, returns an exact copy of <string exprs>.

Tip

•	Use LenB to find the number of bytes in <string exprs>.

•	Use InStrB to find the position of a specified bytes in <string exprs>.


Example

The following example asks the user to input a customer's first and last names, then returns the last name.

Function OnLButtonDblClk ( )

Dim FName As String, Msg As String, LName As String

Dim SpacePos As Integer, UserInput As String, Message As String

Msg = "Please enter a customer's first and last names, "

Msg = Msg & " separated by a space."

' Get user's input

UserInput = InputBox(Msg)

' Find the space

SpacePos = InStrB(1, UserInput, " ")

If SpacePos Then

' Get first & last names

FName = LeftB$(UserInput, SpacePos - 1)

LName = RightB$(UserInput, Len(UserInput) - SpacePos)

Message = "The first name is """ & FName

Message = Message & "." & """" & " The last name is """

Message = Message & LName & "." & """"

Else

Message = "You did not enter a first and last name."

End If

' Display the message

MsgBox Message

End Function

For information about using the code examples, see Using the code examples.


See also

InStrB function

LeftB, LeftB$ functions

LenB function

MidB, MidB$ functions


RmDir statement

Example   See also

Removes a subdirectory from a disk.

Syntax

RmDir <directory name>

<directory name>

String expression that is the name of the directory or subdirectory to be deleted.

Default: Current drive and directory.

Rules:

•	Must specify a valid directory.

•	Target directory must contain no child subdirectories.

•	Target directory must be empty.

<directory name> has the following syntax:

[<drive:>] [ \ ]<directory>[\<directory>]...(Windows)

[ / ]<directory>[/<directory>]...(UNIX)

<drive:>

Character, followed by a colon, that specifies the drive (Windows only).

<directory>

String expression that is the name of the directory or subdirectory to remove.

Examples:

The following statement removes the subdirectory "Test" under the current directory on the current drive.

RmDir "TEST"

The following removes the subdirectory "Test" under the root directory of the current drive.

RmDir "\TEST"

The following removes the subdirectory "Test" under the root directory of drive D:

RmDir "D:\TEST"

Description

RmDir works like the DOS command of the same name. Unlike the DOS command, however, it cannot be abbreviated.

Tips

•	If a directory name contains embedded spaces, you cannot use the DOS RmDir command to remove it. Instead, use RmDir.

•	To determine the current directory, use CurDir.


Example

The following example determines whether a \TMPZZZ subdirectory exists on the current drive. If it does not, it creates it, prompts the user to retain or remove it, and responds accordingly.

Function OnLButtonDblClk ( )

Dim UserAns As Integer, ThisDrive As String

Dim Msg As String, TempDir As String

' Set up error handler

On Error Resume Next

' Get current drive letter

ThisDrive = Left$(CurDir, 2)

' Construct full path spec

TempDir = UCase$(ThisDrive + "\tmpzzz")

' Make the new directory

MkDir TempDir

' Does it exist?

If Err = 41 Then

Msg = "Sorry, " & TempDir & " directory already exists. "

Else

Msg = TempDir & " directory was just created. "

End If

Msg = Msg & "Would you like to remove it?"

UserAns = MsgBox(Msg, MB_YESNOCANCEL)

If UserAns = IDYES Then

RmDir TempDir

End If

End Function

For information about using the code examples, see Using the code examples.


See also

CurDir, CurDir$ functions

MkDir statement


Rnd function

Example   See also

Returns a random number.

Syntax

Rnd[(<sequencing code>)]

<sequencing code>

Numeric expression for the code number that identifies the value to return from the pseudo-random sequence. The pseudo-random sequence is the fixed sequence of numbers you generate if you have not used Randomize and you call Rnd repeatedly without any argument.

Rule: If <sequencing code> is omitted, Actuate Basic moves to the next number in the pseudo-random sequence.

The following table shows the possible values of <sequencing code>, and the corresponding values Rnd returns from the pseudo-random sequence.

<sequencing code>	Rnd returns
Less than 0	The same number every time. The specific value varies as a function of  <sequencing code>.
Greater than 0	The next random number in the pseudo-random sequence.
Equal to 0	The number most recently generated.
Example:

The following expressions are all true, but only if (A) you evaluate them in the order shown, and (B) you do not use a Randomize statement before them. If you do use a Randomize statement, the last of these expressions will always be different.

Rnd(-5) = 0.298564536496997

Rnd(0) = .298564536496997

Rnd(1) = .223996873013675

Rnd = .0928899832069874

Return value

Single

•	Rnd returns a value less than 1 but greater than or equal to 0.

•	Unless you use Randomize beforehand, Rnd generates the same random-number sequence every time the program is run.

•	As long as <sequencing code> is omitted or is greater than zero, each successive call to Rnd uses the previous random number as the seed for the next one.

Tips

•	To generate a more apparently random sequence every time the program is run, use Randomize without an argument before you use Rnd.

•	To produce random integers in a given range, use the following formula:

Int((<high number> - <low number> + 1) * Rnd + <low number>)

In this formula, <high number> represents the highest number in the range, and <low number> the lowest.


Example

The following example simulates rolling a die twice by generating random values between 1 and 6 for each roll.

Function OnLButtonDblClk( )

Dim DieRoll1, DieRoll2, UserMsg

' Seed random num generator

Randomize

' First roll

DieRoll1 = Int(6 * Rnd + 1)

' Second roll

DieRoll2 = Int(6 * Rnd + 1)

UserMsg = "You rolled a " & DieRoll1

UserMsg = UserMsg & " and a " & DieRoll2

UserMsg = UserMsg & " giving a total of "

UserMsg = UserMsg & (DieRoll1 + DieRoll2) & "."

MsgBox UserMsg

End Function

For information about using the code examples, see Using the code examples.


See also

Time, Time$ functions

Randomize statement


RSet statement

Example   See also

Right-aligns a string within the space of a string variable.

Syntax

RSet <string variable> = <string exprs>

<string variable>

Name of a string variable in which RSet stores the right-aligned <string exprs>.

<string exprs>

String expression that you want RSet to right-align within <string variable>.

<string exprs>	Behavior of RSet
Shorter than <string variable>	Right-aligns <string exprs> within <string variable>. Replaces any leftover characters in <string variable> with spaces.
Longer than <string variable>	Places only the right most characters, up to the length of the <string variable>, in <string variable>. Truncates characters beyond the length of <string variable> from the left.
Description

RSet right-aligns a string expression within a variable.


Example

The code in the following example right-aligns text within a 20-character String variable.

Function OnLButtonDblClk ( )

Dim Msg, NL, TmpStr

' Define newline

NL = Chr(10)

' Create 20-character string

TmpStr = String(20, "*")

Msg = "The following two strings that have been right"

Msg = Msg & NL & "and left justified in a " & Len(TmpStr)

Msg = Msg & "-character string." & NL & TmpStr & NL

' Right justify

RSet TmpStr = "Right->"

Msg = Msg & TmpStr & NL

' Left justify

LSet TmpStr = "<-Left"

Msg = Msg & TmpStr & NL

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

LSet statement


RTrim, RTrim$ functions

Example   See also

Returns a copy of a string after removing the trailing spaces from it.

Syntax

RTrim(<string exprs>)

RTrim$(<string exprs>)

<string exprs>

String expression from which RTrim$ strips trailing spaces. Trailing spaces are any spaces that occur after the last non-space character in a string. The <string exprs> must be a variable string, a literal string, a string constant, the return value of any function that returns a string, or a Variant that can evaluate to a String.

Return value

RTrim: Variant

RTrim$: String

Rule: If there are no trailing spaces, RTrim[$] returns the original <string exprs>.

Tips

•	Use Trim[$] to simultaneously strip both leading and trailing spaces in a string.

•	Use InStr to find other spaces in the middle of a string.


Example

The following example strips trailing spaces from a string variable, while LTrim[$] strips leading spaces.

Function OnLButtonDblClk( )

Dim Msg As String, NL As String

Dim CustName As String, CustName1 As String

' Define newline

NL = Chr$(10)

CustName = "  Harold Pinter  "

' Strip left and right spaces

CustName1 = LTRIM$(RTRIM$(CustName))

Msg = "The original client name " & NL & "'" & CustName & "'" & " was "

Msg = Msg & Len(CustName) & " characters long. There were two "

Msg = Msg & "leading spaces and two trailing spaces." & NL & NL

Msg = Msg & "The name returned after stripping the spaces "

Msg = Msg & "is:" & NL & "'" & CustName1 & "'"

Msg = Msg & NL & "...and it contains only "

Msg = Msg & Len(CustName1) & " characters."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

InStr function

LTrim, LTrim$ functions

Trim, Trim$ functions


SafeDivide function

Example   See also

Divides two given numbers, but prevents division by zero. Returns a specified value if division by zero might otherwise have occurred.

Syntax

SafeDivide(<num> As Variant, <denom> As Variant, <ifZero> As Variant) As Variant

<num>

Any number, or valid numeric expression. The numerator of a fraction or ratio.

<denom>

Any number, or valid numeric expression. The denominator of a fraction or ratio.

<ifZero>

Value to return when <denom> is zero.

Return value

Variant

If <denom> = 0, SafeDivide returns <ifZero>

Otherwise, SafeDivide returns <num>/<denom>


Example

The following statement averages amounts in a number of records. But if there are no records at all, the statement does not generate a division-by-zero error. Instead, it simply returns zero.

AverageAmtVar = SafeDivide(Sum(Amount)), Count(), 0)

For information about using the code examples, see Using the code examples.


See also

Err function

Error, Error$ functions

On Error statement


Second function

Example   See also

Returns an Integer from 0 to 59, inclusive, that represents the second of the minute specified by a supplied date expression.

Syntax

Second(<date expression>)

<date expression>

Date expression, or any numeric or string expression that can be interpreted as a date, as a time, or as both a date and a time.

•	Can be a string such as "November 12, 1982 8:30 PM", "Nov 12, 1982 08:30 PM", "11/12/82 8:30pm", or "08:30pm", or any other string that can be interpreted as a date, time, or date/time in the valid range.

•	Can be a date serial number such as 30267.854 (which corresponds to November 12, 1982 at 8:30 PM), or any other number that can be mapped to a date, a time, or to a date/time in the valid range.

•	For date serial numbers, the integer component represents the date itself while the decimal component represents the time of day on that date, where January 1, 1900, at noon has the date serial number 2.5, and negative numbers represent dates prior to December 30, 1899 (0).

Default if no time specified: 0

Rules:

•	If a date is included, it must be a valid date, even though Second does not return a date. A valid date is any date in the range January 1, 100, through December 31, 9999, expressed in one of the standard date formats.

•	If a time is included, it must be in the range 00:00:00 (12:00:00 AM) through 23:59:59 (11:59:59 PM), in either 12- or 24-hour format.

•	If a numeric expression, it must be in the range -657434.0 to +2958465.9999, inclusive.

•	If a variable containing a date serial number, the variable must have been explicitly declared as one of the numeric types.

Examples:

The following statements are equivalent. Each assigns 22 to the variable UserSecond:

UserSecond = Second("6/7/64  2:35:22pm")

UserSecond = Second("5:35:22 pm")

UserSecond = Second("June 7, 1964 2:35:22 PM")

UserSecond = Second("Jun 7, 1964") + 22

UserSecond = Second(23535.60789)

UserSecond = Second(0.60789)

Return value

Integer

Rule: If <date expression> is Null, Second returns a Null.


Example

The following example displays the number of hours, minutes, and seconds to midnight.

Function OnLButtonDblClk()

Dim HrDiff As Integer, MinDiff As Integer, SecDiff As Integer

Dim RightNow As Double, Midnight As Double, TotalDiff As Double

Dim TotalMinDiff As Double, TotalSecDiff As Double
Dim Msg As String

'

Midnight = TimeValue("23:59:59")

' Get current time

RightNow = Now

' Get diffs re midnight

HrDiff = Hour(Midnight) - Hour(RightNow)

MinDiff = Minute(Midnight) - Minute(RightNow)

SecDiff = Second(Midnight) - Second(RightNow) + 1

' Restate seconds and minutes if necessary

If SecDiff = 60 Then

' Add 1 to minute

MinDiff = MinDiff + 1

' And set 0 seconds

SecDiff = 0

End If

If MinDiff = 60 Then

' Add 1 to hour

HrDiff = HrDiff + 1

' And set 0 minutes

MinDiff = 0

End If

' Now get totals

TotalMinDiff = (HrDiff * 60) + MinDiff

TotalSecDiff = (TotalMinDiff * 60) + SecDiff

TotalDiff = TimeSerial(HrDiff, MinDiff, SecDiff)

' Prepare msg for display

Msg = "There are a total of " & Format(TotalSecDiff, "#,##0")

Msg = Msg & " seconds until midnight.  That translates to "

Msg = Msg & HrDiff & " hours, "

Msg = Msg & MinDiff & " minutes, and "

Msg = Msg & SecDiff & " seconds. "

Msg = Msg & "Expressed in standard time notation, it becomes "

' Remember to use "nn" for minutes! m is for month.

Msg = Msg & Format(TotalDiff, "hh:nn:ss") & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Day function

Hour function

Minute function

Month function

Now function

Time, Time$ functions

Weekday function

Year function


Seek statement

Example   See also

Sets the position in a file for the next read or write. The Seek statement should not be confused with the Seek2 function.

Syntax

Seek #<open file number>, <next position>

<open file number>

Numeric expression is the file number for a file that is Open.

Rules for <open file number>:

•	Must be the number of a currently open file.

•	The pound sign (#) preceding the file number is required.

<next position>

Numeric expression that specifies the number that indicates where in <open file number> the next read or write should occur.

Rule: Must be in the range 1 to 2,147,483,647, inclusive.

<next position> means or refers to different things depending on the mode under which the file corresponding to <open file number> is open. The following table summarizes these different meanings.

Mode	<next position> refers to
Random	The number of a record in the open file. The first record is record 1.
Binary Input Output Append	The byte position relative to the beginning of the file. The first byte is byte 1.
Examples:

In the following code fragment, we open a file called "TEST.DAT" for random access and use Get to read record number 52 from it; this action positions the pointer at record 53. Then we use the Seek2 function to save this new position to the variable CurrentRec. Finally, we use the Seek statement to reposition the file pointer to record number 100:

Open "TEST.DAT" For Random As #1  Len = 32

Get #1, 52, TestRecord

CurrentRec = Seek2(1)

Seek #1, 100

Rule

•	If <next position> is beyond the end of a file, Seek extends the file.

•	Record numbers in Get and Put override Seek file positioning.


Example

The following example prompts the user to type three customer names. After writing the names to a test file, the Seek statement repositions the pointer three times successively and then displays the names in reverse order; then the Seek2 function identifies the record numbers.

Function OnLButtonDblClk ( )

Dim CustName As String

Dim I As Integer, Max As Integer, Msg As String

' Create a sample data file:

Open "TESTFILE.DAT" For Random As #1 Len =50

' Ask user to type a few records:

For I = 1 To 3

CustName = InputBox("Please type a customer name: ")

' Put record into file

Put #1, I, CustName

Next I

' Close data file

Close #1

' Open data file

Open "TESTFILE.DAT" For Random As #1 Len = 50

' Calc total # of records

Max = LOF(1) \ 50

Max = Max+ 1

' Read file backwards

For I = Max To 1 Step -1

' Seek STATEMENT

Seek #1, I

' Get record at that position

Get #1, , CustName

' Seek2 FUNCTION

Msg = "Record #" & (Seek2(1) - 1) & " contains: "

Msg = Msg & CustName

MsgBox Msg

Next I

' Close test file

Close #1

Msg = "Choose OK to remove the test file."

MsgBox Msg

' Delete file from disk

Kill "TESTFILE.DAT"

End Function

For information about using the code examples, see Using the code examples.


See also

Seek2 function

Get statement

Open statement

Put statement


Seek2 function

Example   See also

Returns the current position in an open file. This function should not be confused with the Seek statement.

Syntax

Seek2(<open file number>)

<open file number>

Numeric expression that represents the file number of a file that is Open.

Rule: Must be the number of a currently open file.

Examples:

In the following code fragments, we open a file called "TEST.DAT" for random access and use Get to read record number 52 from it; this action positions the pointer at record 53. Then we use the Seek2 function to save this new position to the variable CurrentRec. Finally, we use the Seek statement to reposition the file pointer to record number 100:

Open "TEST.DAT" For Random As #1  Len = 32

Get #1, 52, TestRecord

CurrentRec = Seek2(1)

Seek #1, 100

Returns

Integer

•	Returns a value between 1 and 2,147,483,647.

•	The value Seek2 returns means, or refers to, different things depending on the mode under which the file corresponding to <open file number> is open. The following table summarizes these different meanings.

	Mode	Seek2 refers to:
	Random	The number of the next record to be read or written to.
	Binary Input Output Append	The byte position at which the next operation is to take place.


Example

The following example prompts the user to type three customer names. After writing the names to a test file, the Seek statement repositions the pointer three times successively and then displays the names in reverse order; then thee Seek2 function to identifies the record numbers.

Function OnLButtonDblClk ( )

Dim CustName As String

Dim I As Integer, Max As Integer, Msg As String

' Create a sample data file:

Open "TESTFILE.DAT" For Random As #1 Len =50

' Ask user to type a few records:

For I = 1 To 3

CustName = InputBox("Please type a customer name: ")

' Put record into file

Put #1, I, CustName

Next I

' Close data file

Close #1

' Open data file

Open "TESTFILE.DAT" For Random As #1 Len = 50

' Calc total # of records

Max = LOF(1) \ 50

Max = Max + 1

' Read file backwards

For I = Max To 1 Step - 1

' Seek STATEMENT

Seek #1, I

' Get record at that position

Get #1, , CustName

' Seek2 FUNCTION

Msg = "Record #" & (Seek2(1) - 1) & " contains: "

Msg = Msg & CustName

MsgBox Msg

Next I

' Close test file

Close #1

Msg = "Choose OK to remove the test file."

MsgBox Msg

' Delete file from disk

Kill "TESTFILE.DAT"

End Function

For information about using the code examples, see Using the code examples.


See also

Get statement

Open statement

Put statement

Seek statement


Select Case statement

Example   See also

Executes the first of several blocks of instructions for which an associated expression matches a given one.

Syntax

Select Case <compare to this>

[Case <value to compare> [, <value to compare>]...

[<statement block 1>]]

[Case <value to compare> [, <value to compare>]...

[<statement block 2>]]

...

[Case Else

[<statement block n>]]

End Select

<compare to this>

Any valid numeric or string expression.

Case

Keyword that begins a statement block of a Select Case statement. Case is always followed by a value to compare, and a statement to execute if <value to compare> is the same as <compare to this>. Case may be repeated.

<value to compare>

Any valid numeric or string expression. In addition to the form previously shown in the Syntax section, <value to compare> can also take either of the following forms, or it can take any combination of all three forms.

Range Form

<lower value > To <higher value >

For <value to compare>, specifies a range of values between <lower value> and <higher value>, inclusively. If <compare to this> falls within the range, the case evaluates as True.

To

Keyword used to specify a range of values.

<lower value>, <higher value>

Numeric or string expressions.

Rule: The lower value must always precede the higher one.

Example:

Case 65, 19 To 25, 34 To 49

Case "ZACHARY", "ADAMS" To "JEFFERSON"

Comparison Operator Form

[Is] <comparison operator> <value to compare>

Is

An optional keyword preceding <comparison operator> <value to compare>.

<comparison operator>

Any valid comparison operator except Like.

Example:

Case Is <= 25 , 34 To 49, Is = 65

Case Else

Keyword indicating the statement block Actuate Basic executes if it finds no match between <compare to this> and any of the <value to compare> expressions. If there is more than one Case Else clause, only the first is executed.

Description

For the purposes of this discussion, one expression is said to "match" a second expression when they are equivalent, or when the first falls within a range specified by the second.

Actuate Basic compares <compare to this> against each <value to compare> until it finds a match. For the first--and only the first--of these matches, if there is one, Actuate Basic:

•	Executes the instructions in the <statement block> that immediately follows the matching <value to compare>.

•	Skips any other intervening lines.

•	Passes control to the statement that follows End Select.

If no <value to compare> at all matches <compare to this>, Actuate Basic looks for a Case Else clause. If it finds one it:

•	Executes any statements that immediately follow it.

•	Passes control to the statement immediately following End Select.

If it does not find a Case Else clause, it passes control to the statement immediately following End Select.

Rules

The data type of <value to compare> must be compatible with the data type of <compare to this>. The following table summarizes data type compatibilities in Actuate Basic.

<compare to this>	<value to compare>
Numeric expression	Numeric Variant that converts to Numeric
String expression	String  non-Null Variant
Tips

•	To handle any unforeseen <compare to this> values, always use a Case Else clause in your Select Case statements.

•	The Is comparison operator is different from the Is keyword in this statement.

•	To be sure that string data the user supplies always matches <value to compare> strings consistently, use UCase$ on the user data before you use Select Case.

•	To specify whether string comparisons are or are not case sensitive, use Option Compare.

•	It is good programming practice to evaluate Boolean variables -- not by inspecting their content for a nonzero (True) or zero (False) numeric value -- but by using the keywords True or False.


Example

The following example shows one way to use logical operators with a Select Case statement.

Function OnLButtonDblClk( )

Dim UTyp As String, Insect As Integer, Light As Integer

Dim Tester As Integer, Msg As String

UTyp = InputBox("Please type 'BUG', 'LIGHTNING BUG', or a number.")

UTyp = UCase$(UTyp)

'If the user types either 'lightning bug' or 'bug' then the

'variable Insect will have a value of 1 (True)

Insect = (InStr(UTyp, "LIGHTNING BUG") <> 0) Or (InStr(UTyp, "BUG") <> 0)

'If the user types 'lightning' but NOT 'bug' then the

'variable Light will have a value of 1 (True)

Light = (InStr(UTyp, "LIGHTNING") <> 0) And Not (InStr(UTyp, "BUG") <> 0)

'Set Tester to True, just to get started

Tester = 1

Select Case Tester

Case Insect

Msg = "That is an insect, or refers to one."

Case Light

Msg = "That is definitely not an insect."

Case Else

'The following nested Select Case structure helps sort out

'numeric input in cases where the user typed a number

Select Case Val(UTyp)

Case 1 To 9

Msg = "That is, or starts with, a number from 1 to 9."

Case Is > 9

Msg = "That is, or starts with, a number greater than 9."

Case Else

Msg = "I don't know anything about that."

End Select

End Select

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

GoTo statement

If...Then...Else statement

Option Compare statement


Set statement

Example   See also

Assigns an object reference to a variable.

Syntax

Set <object variable> = {<object reference> | New <class> | Nothing}

<object variable>

Expression that specifies the name of the variable to which you are assigning an object reference.

Rules:

•	Must be of a class consistent with that of <object reference>.

•	Must have been explicitly declared unless declared for you by Actuate Basic.

<object reference>

Expression that specifies the name of an object, of another declared variable of the same class, or of a function or method that returns an object.

New

Reserved word used to create a new instance of a specific class

Rule: Cannot be used to create new variables of any of the fundamental data types.

<class>

The name of a specific class.

Nothing

Reserved word that discontinues association of <object variable> with any specific object. Assigning Nothing to <object variable> releases all resources associated with the previously referenced object, as long as no other variable refers to it.

Description

When you use Set to assign an object reference to a variable, Actuate Basic generally creates not a copy of the object but a reference to it. More than one object variable can refer to the same object. Because these variables are references and not copies, as the object changes, so do they.

When you use the New reserved word with Set, you create a new instance of the referenced type.


Example

The following example uses the Set statement with New to create a new instance of AcLabelControl.

Function OnLButtonDblClk ( )

Dim MyLabel As AcLabelControl, Msg As String

Set MyLabel = New AcLabelControl

If IsKindOf(MyLabel, "AcLabelControl") Then

Msg = "Yes, MyLabel is an AcLabelControl.  "

Msg = Msg & "We will now set its background color to red."

MsgBox Msg

MyLabel.BackgroundColor = Red

End If

End Function

For information about using the code examples, see Using the code examples.


See also

Dim statement

ReDim statement

Static statement


SetAttr statement

Example   See also

Sets attribute information for files.

Syntax

SetAttr(<file name>, <attributes>)

<file name>

String expression that specifies the file for which to set one or more attributes.

Default path: Current drive and current directory.

Rules:

•	Cannot include wildcard characters.

•	Must refer to a valid file.

<attributes>

Numeric expression that specifies the sum of one or more of the values in the following table, which shows what attribute each value indicates along with its HEADER.BAS constant name. The return values not supported under UNIX will be 0.

Return value	Constant name	File type	Operating system
0	ATTR_NORMAL	Normal	Windows, UNIX
1	ATTR_READONLY	Read-only	Windows, UNIX
2 or 0	ATTR_HIDDEN	Hidden	Windows
4 or 0	ATTR_SYSTEM	System file	Windows
32 or 0	ATTR_ARCHIVE	Changed since last backup	Windows
<file name> can optionally specify a full path, in which case it has the following syntax:

[[<drive:>] [ \ ]<directory>[\<directory>]...<file name> (Windows)

[ /]<directory>[/<directory>]...<file name> (UNIX)

<drive:>

Character, followed by a colon, that specifies the drive (Windows only).

<directory>

String expression that specifies the name of a directory or subdirectory.

Example:

The following statement sets the System and Read-only (4 + 1) attributes for a file in the current directory called TESTFILE.DAT.

SetAttr("TESTFILE.DAT", 5)

Description

The operating system assigns one or more attributes to each file. These attributes indicate whether the file is a normal, read-only, hidden, or system file; whether it has been modified since the last backup; or whether some combination of these is the case. SetAttr lets you modify these attributes.

Rule

<file name> can be open for read-only access, but must not be opened for write access.

Tips

•	To determine whether, or in what mode, a file is open, use FileAttr.

•	To determine what attributes of a file, directory, or volume have already been set, use GetAttr.


Example

The following example prompts the user for the name of a file. If the Archive attribute for that file is already set, it displays a message; if not, it sets the attribute.

Function OnLButtonDblClk( )

Dim FileName As String, Msg As String

On Error GoTo ErrorHandler

FileName = InputBox("Please type a file name.")

'Check for Archive attribute

If GetAttr(FileName) BAnd ATTR_ARCHIVE Then

MsgBox "Sorry, " & FileName & " already has the Archive attribute."

Else

' Set Archive attribute

SetAttr FileName, ATTR_ARCHIVE

MsgBox FileName & " now has the Archive attribute."

End If

Exit Function

ErrorHandler:

Msg = "Sorry! An error occurred. Please "

Msg = Msg & "check the file name or path and "

Msg = Msg & "try again."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

FileAttr function

GetAttr function


SetBinding function

Example   See also

Establishes an alias for an instance variable of a class. SetBinding is used primarily to set up a mapping from database column names to the names of variables in a data row class.

Syntax

SetBinding(<instance handle>, <column name>, <variable name>)

<instance handle>

The instance handle to one instance of the class for which to set up the binding.

<column name>

The name, usually a column name, to map to a variable.

<variable name>

The name of the variable or constant to associate with the column name.

Tip

The column name mapped to the column name within a class lets you access variables through their column aliases using GetValue. SetBinding is called automatically for data rows created through the Actuate Query Builder, and you can call SetBinding through custom code for data rows you create manually. When you call SetBinding for a manually created data row, you can insert the calls to SetBinding in the data row's BuildBinding method. For any other class for which you want to set up bindings, you must call SetBinding at the beginning of your code.


Example

The following example assumes you have a database column called Customer.Name. Note the declaration for SetBinding.

Declare Sub SetBinding Lib "Factory" (handle As AnyClass, rname As String, vname As String)

'Using string variables

SetBinding(me, myStr1, myStr2 )

'Using string constants

SetBinding(me, "Customer.Name", "Customer_Name")

For information about using the code examples, see Using the code examples.


See also

GetValue function


SetClipboardText function

Example   See also

Places a string expression in the operating environment Clipboard using the specified Clipboard format.

Syntax

SetClipboardText(<data>[, <format>])

<data>

String data to be placed on the Clipboard.

<format>

One of the following Clipboard formats. If <format> is omitted, CF_TEXT is assumed.

Symbolic constant	Value	Clipboard format
CF_LINK	&HBF00	DDE conversation information
CF_TEXT	1	Text
The symbolic constants and their values should be declared in your Actuate Basic code module (.BAS file).

Return

Integer

•	Returns 1 (True) if Clipboard text is successfully set.

•	Returns 0 (False) if Clipboard text cannot be set.


Example

The following example places the current date on the Clipboard and then displays the contents of the Clipboard.

Function OnLButtonDblClk ( )

Dim Msg As String, UserContent, DoMore, Success As Integer

On Error Resume Next

Msg = "The Clipboard currently contains:  " & GetClipboardText()

MsgBox Msg

Msg = "Choose OK to load today's date onto the Clipboard."

MsgBox Msg

ClearClipboard()

SetClipboardText(Format$(Date, "dddd, mm/dd/yyyy"))

Msg = "Today's date is on the Clipboard.  Choose OK to get the "

Msg = Msg & "date back from the Clipboard and put it in a message."

MsgBox Msg

Msg = GetClipboardText()

MsgBox "The Clipboard currently contains:  " & Msg

DoMore = MsgBox("Put something else on the clipboard?", MB_YESNO)

If DoMore = IDNO Then

MsgBox "The date is still on the Clipboard."

Else

UserContent = InputBox("Put what?")

SetClipboardText(UserContent)

End If

MsgBox "The Clipboard currently contains:  " & GetClipboardText( )

End Function

For information about using the code examples, see Using the code examples.


See also

ClearClipboard function

GetClipboardText function


SetHeadline statement

See also

Sets to a given value the headline associated with the completed request for a report.

Syntax

SetHeadline(<newHeadline> [As String])

<newHeadline>

String expression. The text you want the headline to display.

Description

Headlines are associated with the completed request for a report, and are visible only in the Web Agent when viewing channels.

By default, the headline is set to the value of the Headline parameter that appears in the Output Options section of the Requester. Use SetHeadline to programmatically change the headline to contain some other text.

Rules

•	GetHeadline and SetHeadline do not work in the Viewer.

•	To change the headline, do not change the Headline parameter itself. Instead, use SetHeadline.

Tip

To determine the current headline setting, use GetHeadline.


See also

GetHeadline function


Sgn function

Example   See also

Indicates whether a number is positive, negative, or zero.

Syntax

Sgn(<number>)

<number>

Number, numeric expression, or Variant of VarType 8 (String) that specifies the number for which you want to determine the sign.

Return value

Same data type as <number>. If <number> is a Variant of type 8 (String), returns Variant of type 5 (Double). Returns one of the following numbers indicating whether <number> is positive, negative, or zero.

Return value	Description
1	Positive number
-1	Negative number
0	Zero


Example

The following example tells whether a given number is positive, negative, or zero.

Function OnLButtonDblClk( )

Dim Number As Double, Msg As String

Number = InputBox("Please type a number.")

Select Case Sgn(Number)

Case 0

Msg = "That is zero."

Case 1

Msg = "That is a positive number."

Case -1

Msg = "That is a negative number."

End Select

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Abs function


Shell function

Example

Runs a specified executable program.

Syntax

Shell(<program name and parameters> [, <window style>] )

<program name and parameters>

String expression containing a valid executable name. Name of the program to execute, with its required arguments or command line switches, if there are any.

Default file extension under Windows: .EXE.

Rules:

•	Must have an extension of EXE, COM, BAT, or PIF (Windows).

•	Must have execute permission set (UNIX).

•	Must be enclosed within quotes.

•	If the executable is not located in the default directory:

•	Program name must include the full path.

•	Program must be located in a directory specified in the PATH environment variable.

Example:

Each of the following examples runs the Windows calculator and then immediately executes the next statement in the program, whether or not CALC.EXE has terminated:

DummyVar = Shell("calc.exe")

X = Shell("C:\WINDOWS\CALC.EXE")

<window style> (ignored under UNIX)

Integer that specifies the number for the style of the window to use for the new program, and whether or not to give it the focus. The following table identifies each possible value for <window style> and the resulting style and focus of the window.

Value	Window style	Focus
1, 5, 9	Normal	New program receives
2	Minimized	New program receives
3	Maximized	New program receives
4, 8	Normal	Current program retains
6, 7	Minimized	Current program retains
Default if omitted: 2.

Example:

The following example calls Word for Windows, maximizes its window, and gives it focus.

Z = Shell("C:\WORD\WINWORD.EXE", 3)

Return value

Integer

•	Shell loads an executable file into the Windows environment, and returns the unique task ID number that Windows assigns to each running program as its identifier (Windows).

•	Shell runs programs asynchronously. You cannot be certain whether or not a program you start with Shell will finish executing before the code following the Shell function in your Actuate Basic application is executed.

•	If Shell cannot start the named program, it generates an error.

Rule

You cannot use Shell on Windows NT Server to run a Windows application unless:

•	Your program has been allowed to interact with the desktop, AND

•	Your program invokes Shell from the System account.

Tips

•	To shell to DOS--in other words, to run the DOS command processor--specify the program name "COMMAND.COM" with Shell (Windows).

•	To enjoy greater flexibility and exercise better control over the behavior of external programs, use an OLE technique rather than Shell (Windows).


Example

In the following Windows example, Shell runs the Windows calculator. The next statement in the program is then executed immediately, whether or not CALC.EXE has terminated.

Function OnLButtonDblClk( )

Dim DummyVar

DummyVar = Shell("C:\WINDOWS\CALC.EXE", 6)

MsgBox "Calculator opened and minimized, without focus."

End Function

For information about using the code examples, see Using the code examples.


ShowFactoryStatus statement

Example

Instructs the Workbench to display a comment in the status line of the Factory dialog box when you generate a report.

Syntax

ShowFactoryStatus(<StatusMsg>)

<StatusMsg>

String you want to display in the status line of the Factory dialog box.

Example:

ShowFactoryStatus("Preparing the statement.")


Example

The following code shows how you might use ShowFactoryStatus.

To try this example, override the DataStream's OpenCursor() method, and paste the following code in the Method Editor window:

Sub OpenCursor( stmtText As String )

Dim stmt	As AcDBStatement

Assert( Cursor Is Nothing )

' Prepare the statement

Set stmt = New AcDBStatement( GetDBConnection( ) )

ShowFactoryStatus("Got a handle for the statement.")

If Not stmt.Prepare( stmtText ) Then

GetDBConnection( ).RaiseError( )

End If

ShowFactoryStatus("Preparing the statement.")

' Create a cursor for the statement.

Set Cursor = New AcDBCursor( stmt )

ShowFactoryStatus("Got a handle for the cursor.")

' Now we must bind any static parameters which may be present

BindStaticParameters( Cursor )

ShowFactoryStatus("Binding static parameters")

' Open the Cursor

If Not Cursor.OpenCursor( )	Then

GetDBConnection( ).RaiseError( )

Set Cursor = Nothing

End If

ShowFactoryStatus("opening the cursor")

' Bind the data row class variables to the output row  of the cursor

BindDataRow( Cursor )

ShowFactoryStatus("Binding datarow.")

End Sub

For information about using the code examples, see Using the code examples.


Sin function

Example   See also

Gives the sine of an angle.

Syntax

Sin(<angle>)

<angle>

Number, numeric expression, or Variant of type 8 (String) that specifies, in radians, the angle for which you want to find the sine.

Return value

Double

Rule: If <number> evaluates to Null, Sin returns a Null.


Example

In the following example the user is prompted to enter an angle expressed in radians. The code then returns the sine of the angle.

Function OnLButtonDblClk( )

Dim UserTyped

UserTyped = InputBox("Type a number representing an angle in radians.")

MsgBox "The sine of " & UserTyped & " is: " & Sin(UserTyped)

End Function

For information about using the code examples, see Using the code examples.


See also

Atn function

Cos function

Tan function


SLN function

Example   See also

Returns the straight-line depreciation of an asset for a single period.

Syntax

SLN(<initial cost>, <salvage value>, <asset lifespan>)

<initial cost>

Numeric expression that specifies the initial cost of the asset.

<salvage value>

Numeric expression that specifies the value of the asset at the end of its useful life. You can type a salvage value to view the straight line depreciation offset by the salvage value, or return straight line depreciation without salvage value by entering 0 in salvage value.

<asset lifespan>

Numeric expression that specifies the length of the useful life of the asset.

Rule for <asset lifespan>: Must be given in the same units of measure you want the function to return. For example, if you want SLN to determine the annual depreciation of the asset, <asset lifespan> must be given in years.

Examples:

The following example calculates the depreciation under the straight-line method for a new machine purchased at $1400, with a salvage value of $200, and a useful life estimated at 10 years. The result ($120 annually) is assigned to AnnualDeprec.

AnnualDeprec = SLN(1400, 200, 10)

Return value

Double

Straight-line depreciation is the oldest and simplest method of depreciating a fixed asset. It uses the book value of the asset less its estimated residual value, and allocates the difference equally to each period of the asset's life. Such procedures are used to arrive at a uniform annual depreciation expense that is charged against income before calculating income taxes.

Rule

All arguments must be positive numbers.


Example

The code in the following example prompts the user for various particulars about an asset, then returns the asset's straight-line depreciation for any single period. To use this example, paste the first portion at or near the beginning of your Actuate Basic source code (.BAS) file; then paste the procedure into the OnLButtonDblClk( ) method for a clickable component like a label.

Declare

' Number of months in a year

Global Const YEARMONTHS = 12

End Declare

'

 Function OnLButtonDblClk ( )

Dim Fmt As String, InitCost As Double, SalvageVal As Double

Dim MonthLife As Double, LifeSpan As Double, PerDepr As Double

' Define money format

Fmt = "$###,##0.00"

InitCost = InputBox("What is the initial cost of the asset?")

SalvageVal = InputBox("What is the asset's value at useful life end?")

MonthLife = InputBox("What is the asset's useful life in months?")

' Ensure period is >= 1 year

Do While MonthLife < YEARMONTHS

MsgBox "Sorry, asset life must be a year or more."

MonthLife = InputBox("What is the asset's useful life in months?")

Loop

' Convert months to years

LifeSpan = MonthLife / YEARMONTHS

If LifeSpan <> Int(MonthLife / YEARMONTHS) Then

' Round up to nearest year

LifeSpan = Int(LifeSpan + 1)

End If

PerDepr = SLN(InitCost, SalvageVal, LifeSpan)

MsgBox "The depreciation is " & Format(PerDepr, Fmt) & " per year."

End Function

For information about using the code examples, see Using the code examples.


See also

DDB function

SYD function


Space, Space$ functions

Example   See also

Returns a string consisting of the specified number of spaces.

Syntax

Space(<number of spaces>)

Space$(<number of spaces>)

<number of spaces>

Numeric expression indicating the length of the returned string of spaces.

Rules:

•	Must be between 0 and 2,147,483,647 or memory limit.

•	The <number of spaces> is rounded to Long no matter what numeric data type it is.

Return value

Space: Variant

Space$: String

Tip

To generate a string of characters other than spaces, use String[$].


Example

The following example creates a variable containing 10 spaces.

Function OnLButtonDblClk ( )

Dim NL, Msg, Pad, UserFname, UserLname

NL = Chr(10)

UserFname = InputBox("Please type your first name.")

UserLname = InputBox("Please type your last name.")

' Create 10-space pad

Pad = Space(10)

Msg = "Notice the 10-space pad between your first "

Msg = Msg & "and last names.  " & NL & NL

Msg = Msg & UserFname & Pad & UserLname

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

String, String$ functions


Sqr function

Example

Gives the square root of a number.

Syntax

Sqr(<number>)

<number>

Number, numeric expression, or Variant of type 8 (String) indicating the number for which you want to determine the square root.

Return value

Double

Rule: If <number> evaluates to Null, Sqr returns a Null.


Example

The code in this example returns the square root of a number specified by the user.

Function OnLButtonDblClk( )

On Error GoTo ErrorHandler

Dim UserTyped, Msg

UserTyped = InputBox("Please type a number.")

MsgBox "The square root of " & UserTyped & " is:  " & Sqr(UserTyped)

Exit Function

ErrorHandler:

Msg = "Sorry!  An error occurred.  Please try again."

MsgBox Msg

Resume Next

End Function

For information about using the code examples, see Using the code examples.


Static statement

Example   See also

Declares a static variable or static procedure.

Syntax

Static <variable name> [([<subscripts>])] [As <type>] [, <variable name> [([<subscripts>])] [As <type>]]...

- or -

Static <procedure name>

<variable name>

Name you create for the new variable.

<procedure name>

Name you create for the new procedure. When you use the syntax Static <procedure name>, all the variables in <procedure name> are declared to be static.

<subscripts>

The dimensions of an array variable.

Subscript syntax

[<lower> To] <upper>[,[<lower> To] <upper>]...

Rule: <lower> and <upper> can range from -2,147,483,648 to 2,147,483,647, inclusive.

Examples:

The following two statements have the same effect. Both declare a two-dimensional array that contains 11 elements in its first dimension, and 6 elements in its second.

Static MEM(10, 5)

Static MEM(0 TO 10, 0 TO 5)

As <type>

Clause in which you specify a data type for the new variable.

Default: Variant or the data type specified by the type declaration character appended to <variable name>, if there is one.

Description

Static variables retain their values as long as the program is running, unlike local variables, which are cleared when the procedure ends. This does not mean, however, that you can access them from outside the procedure. Every time you execute the procedure in which the static variables are declared, the procedure can make use of and update the most recent values of those variables. Whatever changes it makes are preserved until the next time you call the procedure.

Rules

•	To declare a fixed-size array in a nonstatic procedure, you must use Static.

•	Use Static at the procedure level.

Tip

To retain the values of all the variables in a procedure, you do not have to declare each one individually as Static, or list each one on a Static declaration line. Instead, use Static <procedure name> to declare the procedure itself.

Example:

Static Sub MyProcedure


Example

In the following example, the value of the variable Accumulate is preserved between calls to the Sub procedure. Each time the procedure is called, it prompts the user to add to the Accumulate variable. Then it displays the accumulated value.

Function OnLButtonDblClk ( )

Static Accumulate As Double

Accumulate = Accumulate + InputBox("Add what number? ")

MsgBox "The static variable now has the following value:  " & Accumulate

End Function

For information about using the code examples, see Using the code examples.


See also

Dim statement

Function...End Function statement

Sub...End Sub statement


Stop statement

Example   See also

Suspends execution of the running Actuate Basic code.

Syntax

Stop

Description

•	Unlike End, Stop does not close files or clear variables.

•	To continue a program suspended by Stop, choose DebugÆContinue, or press F5.

Tip

You can place Stop anywhere in procedures to suspend program execution. It is useful as a debugging aid.


Example

In the following example, for each step through the For...Next loop, Stop suspends execution. To resume program execution, choose DebugÆContinue.

Function OnLButtonDblClk ( )

Dim I As Integer

' Begin For...Next loop

For I = 1 To 10

' Show I

MsgBox I

' Stop each time through loop

Stop

Next I

End Function

For information about using the code examples, see Using the code examples.


See also

End statement


Str, Str$ functions

Example   See also

Converts a numeric expression to a String.

Syntax

Str(<numeric expression>)

Str$(<numeric expression>)

<numeric expression>

Numeric expression to be converted into a String.

Examples:

The following examples are equivalent. Each returns "Customer 55".

"Customer" & Str$(55)

"Customer" & Str$(110/2)

Return value

Str: Variant

Str$: String

•	If <numeric expression> is positive, Str[$] precedes the string representation of the number with a leading space.

•	If < numeric expression> is negative, Str[$] precedes the string representation of the number with a minus sign instead of a leading space.

Tip

•	To put the results of a calculation into a message for the user and avoid generating a "Data Type Mismatch" error, use Str[$].

•	To convert numeric values you want rendered in currency, date, time, or user-defined formats, use Format[$] instead of Str[$].

•	To convert a String to a number, use Val.


Example

The following example returns a string representation of the values contained in two variables. Because the numbers are positive, a space precedes the first string character in each case.

Function OnLButtonDblClk ( )

Dim Dice1, Dice2, Msg

' Seed random num generator

Randomize

' Generate first value

Dice1 = Int(6 * Rnd + 1)

' Generate second value

Dice2 = Int(6 * Rnd + 1)

Msg = "You first rolled a " & Str$(Dice1)

Msg = Msg & " and then a " & Str$(Dice2)

Msg = Msg & " for a total of "

Msg = Msg & Str$(Dice1 + Dice2) & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Format, Format$ functions

Val function


StrComp function

Example   See also

Compares two strings and returns a Variant indicating the result.

Syntax

StrComp(<string exprs 1>, <string exprs 2>[,<compare method>])

<string exprs 1>, <string exprs 2>

Any string expression. Whether the underlying data type is Variant or String, each expression is first converted to a Variant before the arguments are compared.

<compare method>

Numeric expression that indicates whether <compare method> is case sensitive or insensitive.

Value	String comparison	Similar to
0	Case-sensitive	Option Compare Binary
1	Case-insensitive	Option Compare Text
Default: 0, unless you used Option Compare Text in the module.

Rule: Must be 0 or 1.

Example:

•	When <compare method> is case-sensitive (0), "McManus" does not match "MCMANUS" or "McMANUS"

•	When <compare method> is case-insensitive (1) "McManus" matches "MCMANUS" or "McMANUS".

Return value

Variant

StrComp returns a Variant that reports the relationship between the two string expressions. The following table illustrates each possible return value and the relationship or condition it signifies:

Return value	Relationship or condition
-1	<string exprs 1> is less than <string exprs 2>
0	<string exprs 1> = <string exprs 2>
1	<string exprs 1> is greater than <string exprs 2>
Null	<string exprs 1> = Null or <string exprs 2> = Null


Example

The following example prompts for two strings and for the comparison method to use when comparing them. Then it returns the result of the comparison along with a short explanation.

Function OnLButtonDblClk()

Dim Comp, CompMethod, Msg As String

Dim String1 As String, String2 As String, Desc As String

String1 = InputBox("Type a customer's name.")

String2 = InputBox("Type the same name, or a different one if you like.")

CompMethod = InputBox("Use which comparison method?  Type 0 or 1.")

If CompMethod <> 0 And CompMethod <> 1 Then

MsgBox "You did not type 0 or 1 so CompMethod is case sensitive."

CompMethod = 0

End If

Select Case CompMethod

Case 0

Desc = "case sensitive."

Case 1

Desc = "NOT case sensitive."

End Select

Comp = StrComp(String1, String2, CompMethod)

Select Case Comp

Case -1

Msg = String1 & " is less than " & String2

Msg = Msg & " for compare method " & CompMethod

Msg = Msg & ", which is " & Desc

Case 0

Msg = String1 & " is equal to " & String2

Msg = Msg & " for compare method " & CompMethod

Msg = Msg & ", which is " & Desc

Case 1

Msg = String1 & " is greater than " & String2

Msg = Msg & " for compare method " & CompMethod

Msg = Msg & ", which is " & Desc

End Select

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Option Compare statement


String, String$ functions

Example   See also

Returns a string consisting of a specified character repeated a specified number of times.

Syntax

String(<number of characters>,<char to repeat>)

-or -

String$(<number of characters>,<character code number>)

<number of characters>

Numeric expression that indicates the length of the returned string.

Rule: Must be between 0 and 2,147,483,647.

<char to repeat>

String expression that specifies the character to be duplicated.

Rules:

•	If <char to repeat> is longer than one character, only the first character is used as the repeated character.

•	If <char to repeat> or <character code number> is a Variant of any numeric type, String[$] interprets the numeric value as the ANSI code for the repeated character.

Default: If longer than one character, first character only is used.

<character code number>

Numeric expression that specifies the ANSI code for the repeated character.

Rule: Must not be Null.

Examples:

The following statements are equivalent. Each returns "##########".

String$(10,"# ")

String$(10,35)

String$(10,291)

Return value

String: String

String$: Variant

Tip

To generate a string of spaces, use Space[$].


Example

The example returns a string consisting of 12 number signs followed by a sample check amount. The ANSI code of the number sign character is 35.

Function OnLButtonDblClk ( )

Dim Msg As String, NL As String

' Define newline

NL = Chr(10)

Msg = "This generates two strings of 12 number signs, " & NL

Msg = Msg & "followed by a sample check amount. " & NL & NL

Msg = Msg & "Both forms of String$ syntax are illustrated.  " & NL

Msg = Msg & NL & "First Form: " & String$(12, "#") & "$100.00" & NL

Msg = Msg & "Second Form: " & String$(12, 35) & "$100.00" & NL & NL

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Space, Space$ functions


StrLoad, StrLoad$ functions

Retrieves the String specified by the <id>.

Syntax

StrLoad(<id>)

StrLoad$(<id>)

<id>

Numeric expression to associated with a string. The string is in a resource file attached to the executable file.

Return value

StrLoad: Variant

StrLoad$: String

Rule: If <id> evaluates to Null, StrLoad[$] returns a Null.


Sub...End Sub statement

Example   See also

Declares and defines the name, code, and any arguments that constitute an Actuate Basic Sub procedure.

Syntax

[Static] Sub <name of procedure> [(<list of arguments>)]

[<statements>]

[Exit Sub]

[<statements>]

End Sub

Static

Keyword that instructs Actuate Basic to preserve the values of the procedure's local variables between calls.

Rules:

•	Cannot use Static to affect variables declared outside the procedure.

•	Avoid using Static in recursive Sub procedures.

<name of procedure>

The name you assign to the procedure.

Rules for <name of procedure>:

•	Subject to the same constraints as variable names, as well as to the following additional constraints:

•	Cannot include a type declaration character.

•	Cannot be the same as any other globally recognized name such as that of:

•	-	Procedure in a declared dynamic-link library (DLL).

•	-	Any Global variable.

•	-	Any Global constant.

•	Can be overloaded. That is, you can define another function and/or procedure that has the same name, as long as the respective arguments are unique. For example, the following are both permissible in the same program.

Sub Potato(intTomato As Integer)

..

End Sub

Sub Potato(intTomato As Double)

..

End Sub

<list of arguments>

The list of variables that Actuate Basic passes as arguments from the calling procedure to the Sub procedure.

<statements>

One or more valid Actuate Basic statements. These statements constitute the body of the Sub procedure.

Exit Sub

Statement that signals Actuate Basic to terminate the Sub procedure and transfer control to the statement following the one that called the procedure. You may use as many Exit Sub statements as you wish, anywhere in a Sub procedure.

<list of arguments> has the following syntax:

[ByVal] <variable name>[( )] [As <data type>] [,[ByVal] <variable name>[( )] [As <data type>]...

ByVal

Keyword that instructs Actuate Basic to pass the argument to the procedure by value rather than by reference--which means that whatever changes the Sub makes to the argument variable will have no affect on its value in the calling procedure.

Rule: Cannot be used with a variable of user-defined type, class, or with an array variable.

<variable name>

Name of the variable to pass as an argument.

If the Sub procedure changes the value of <variable name> internally, then it also changes its value externally--that is, in the procedure that called the Sub.

Rules:

•	You must use the ByVal keyword if you do not want the Sub's changes to an argument variable to affect the variable's value in the calling procedure.

•	For array variables, use the parentheses but omit the number of dimensions.

Example:

The following statement calls a Sub procedure named SalesTax and passes to it as its argument an array variable previously declared as MyArray(50,72):

SalesTax MyArray( )

As <data type>

Clause that declares the data type of <variable name>.

Rule: <data type> can specify any valid Actuate Basic or user-defined data type except a fixed-length string

Example:

SalesTax Customer As String, Amount As Currency

Description

Like a Function procedure, a Sub procedure can take arguments, execute a series of statements, and change the values of its arguments. However, unlike a Function procedure, a Sub procedure does not return a value directly and cannot be used in an expression.

You can use the same name for two or more different procedures, as long as you make sure the procedures take a different number of arguments, or that the arguments are of different data types. For example, you can write two different square root functions - one that operates on integers, and another that operates on doubles. Their respective first lines might look like the following:

Function SquareRoot(intParam As Integer) As Integer

Function SquareRoot(dblParam As Double) As Double

Actuate Basic will know which procedure you mean by the type of value you pass when you call the procedure. For instance, if you write a call to SquareRoot(5), the compiler will choose the first SquareRoot function. But if you call SquareRoot(5.1234567), or SquareRoot(5.000), it will execute the second one.

Rules

•	You cannot define a Sub procedure from within another Sub procedure.

•	You cannot use a Sub procedure in an expression, as you can a Function procedure.

•	You cannot use GoTo to enter or exit a Sub procedure.

Tips

•	Sub procedures can be recursive; that is, they can call themselves repeatedly in order to perform a given task.

•	To evaluate a certain condition and then determine whether or not the Sub procedure should continue, use Exit Sub within a conditional structure like If Then.

•	See Call for further information on how to call Sub procedures.


Example

The following example declares two Sub procedures. The first one calls the second. In this example OnLButtonDblClk( ) is overridden to prompt the user to enter the data. The procedure SalesTax( ) should be typed after the End Function of the OnLButtonDblClk( ) procedure or saved in an Actuate Basic source code (.BAS) file.

Function OnLButtonDblClk ( )

Dim PassThisArg1 As Double, PassThisArg2 As Double

PassThisArg1 = InputBox("What is the amount of the sale?")

PassThisArg2 = InputBox("What is the tax rate,expressed as a decimal?")

SalesTax(PassThisArg1, PassThisArg2)

End Function

Sub SalesTax (Arg1, Arg2)

Dim LocalVar

LocalVar = Arg1 * Arg2

MsgBox "The sales tax is:  " & Format$(LocalVar, "$#,###.00")

End Sub

For information about using the code examples, see Using the code examples.


See also

Call statement

Dim statement

Function...End Function statement

Static statement


SYD function

Example   See also

Returns sum-of-years'-digits depreciation of an asset for a specified period.

Syntax

SYD(<initial cost>, <salvage value>, <asset lifespan>, <single period>)

<initial cost>

Numeric expression that specifies the initial cost of the asset.

<salvage value>

Numeric expression that specifies the value of the asset at the end of its useful life.

<asset lifespan>

Numeric expression that specifies the length of the useful life of the asset.

Rule for <asset lifespan>: Must be given in the same units of measure as <single period>. For example, if <single period> represents a month, then <asset lifespan> must be expressed in months.

<single period>

Numeric expression that specifies the period for which you want SYD to calculate the depreciation.

Rule for <single period>: Must be given in the same units of measure as <asset lifespan>. For example, if <asset lifespan> is expressed in months, then <single period> must represent a period of one month.

Examples:

The following example calculates the depreciation for the first year under the sum-of-years'-digits method for a new machine purchased at $1400, with a salvage value of $200, and a useful life estimated at 10 years. The result ($218.18) is assigned to Year1Deprec. You may wish to note (a) that this result is equivalent to 10/55 * $1,200; (b) that 55 = 10 + 9 + 8 + 7 + 6 + 5 + 4 + 3 + 2 + 1; and (c) that 10 is the 1st (Year 1) term in this series of digits.

Year1Deprec = SYD(1400, 200, 10, 1)

The following example calculates the depreciation of the same asset for the second year of its useful life. The result ($196.36) is assigned to Year2Deprec. You may wish to note (a) that this result is equivalent to 9/55 * $1,200; (b) that 55 = 10 + 9 + 8 + 7 + 6 + 5 + 4 + 3 + 2 + 1; and (c) that 9 is the 2nd (Year 2) term in this series of digits.

Year2Deprec = SYD(1400, 200, 10, 2)

Returns

Double

Sum-of-years'-digits is an accelerated method of depreciation that results in higher depreciation charges and greater tax savings in the earlier years of the useful life of a fixed asset than are given by the straight-line depreciation method (SLN), where charges are uniform throughout.

The method bases depreciation on an inverted scale of the total of digits for the years of useful life. For instance, if the asset's useful life is 4 years, the digits 4, 3, 2 and 1 are added together to produce 10. SYD for the first year then becomes 4/10ths of the depreciable cost of the asset (cost less salvage value); the rate for the second year becomes 3/10ths, and so on.

Rules

•	<asset lifespan> and <single period> must both be expressed in terms of the same units of time.

•	All arguments must be positive numbers.


Example

The following example prompts the user for various particulars about an asset, then returns the asset's sum-of-years'-digits depreciation for any single period. To use this example, paste the first portion at or near the beginning of your Actuate Basic source code (.BAS) file. Then paste the procedure into the OnLButtonDblClk( ) method for a clickable component like a label.

Declare

' Number of months in a year

Global Const YEARMONTHS = 12

End Declare

'

Function OnLButtonDblClk ( )

Dim Fmt As String, InitCost As Double, SalvageVal As Double

Dim MonthLife As Double, LifeSpan As Double, DepYear As Double

Dim PeriodDepr As Double, Msg As String

' Define money format

Fmt = "###,##0.00"

InitCost = InputBox("What is the initial cost of the asset?")

SalvageVal = InputBox("What is the asset's value at the end of its life?")

MonthLife = InputBox("What is the asset's useful life in months?")

' Ensure period is >= 1 year

Do While MonthLife < YEARMONTHS

MsgBox "Asset life must be a year or more."

MonthLife = InputBox("What is the asset's useful life in months?")

Loop

' Convert months to years

LifeSpan = MonthLife / YEARMONTHS

If LifeSpan <> Int(MonthLife / YEARMONTHS) Then

' Round up to nearest year

LifeSpan = Int(LifeSpan + 1)

End If

DepYear = CInt(InputBox("For which year do you want depreciation?"))

Do While DepYear < 1 Or DepYear > LifeSpan

MsgBox "You must enter at least one but not more than " & LifeSpan

DepYear = CInt(InputBox("For what year do you want depreciation?"))

Loop

PeriodDepr = SYD(InitCost, SalvageVal, LifeSpan, DepYear)

Msg = "The depreciation for year " & DepYear & " is "

Msg = Msg & Format(PeriodDepr, Fmt) & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

DDB function

SLN function


Tab function

Example   See also

Specifies the columnar position at which the next character is to print.

Syntax

Tab(<column>)

<column>

Integer expression. Specifies the column at which printing is to continue.

Example:

The following statements open a file and use Tab to move the print position to column 40 in an output data file.

Open "TEST.FIL" For Output As #1

Print #1, "Here is a test of the "; Tab(40); "Tab function."

Close #1

Description

•	The leftmost print position on an output line is always 1.

•	When you use Print # to print to files, the rightmost print position is the current width of the output file, which you can set using Width #.

•	When you use Tabs without separators, the semicolon (;) separator is assumed by default.

•	There is no simple correlation between the number of characters printed and the number of fixed-width columns they occupy. For example, the uppercase letter W occupies more than one fixed-width column.

•	Tab behaves as follows:

If:	Then Tab:
The current print position on the current line is greater than <column>	Skips to <column> on the next output line and continues printing there
<column> is greater than the output-line width (set by Width #)	Calculates <print position> =  <column> Mod <width>
<column> is less than the current print position	Continues printing on the next line at the calculated print position
<column> is less than 1	Moves the print position to column 1
The calculated print position is greater than the current print position	Continues printing at the calculated print position on the same line, as expected
Rule

You can use Tab only with the Print # statement.

Tips

•	To accommodate wider letters, make sure your tabular columns are wide enough.

•	To set the width of the output file, use Width #.


Example

The following example uses the Tab function to move the print position to column 40 in an output data file.

Function OnLButtonDblClk ( )

Dim Msg

'Create sample file

Open "TEST.FIL" For Output As #1

Print #1, "This is a test of the "; Tab(40); "Tab function."

'Close file

Close #1

'Reopen test file for input

Open "TEST.FIL" For Input As #1

'Read test data

Input #1, Msg

'Close file

Close #1

MsgBox Msg

'Delete test file

Kill "TEST.FIL"

End Function

For information about using the code examples, see Using the code examples.


See also

Print # statement


Tan function

Example   See also

Returns the tangent of an angle.

Syntax

Tan(<angle>)

<angle>

Number, numeric expression, or Variant of type 8 (String) that specifies, in radians, the angle for which you want to find the tangent.

Return value

Double

Rule: If <angle> evaluates to Null, Tan returns a Null.

Tips

•	To find the cotangent of an angle, use: Cotangent = 1/Tan.

•	To convert between radians and degrees, use: radians = degrees * Pi/180.


Example

In the following example, the user is prompted to enter an angle expressed in radians. The code then returns the tangent of the angle.

Function OnLButtonDblClk( )

Dim UserTyped

UserTyped = InputBox ("Type a number representing an angle in radians.")

MsgBox "The tangent of " & UserTyped & " is: " & Tan(UserTyped)

End Function

For information about using the code examples, see Using the code examples.


See also

Atn function

Cos function

Sin function


Time, Time$ functions

Example   See also

Returns the current system time.

Syntax

Time[()]

Time$[()]

Example:

The following statement assigns the current system time to a variable:

CurrTime = Time

Return value

Time: Variant

Time$: String

•	Time returns a Variant of type 7 (Date) that contains a time stored internally as the fractional part of a double-precision number.

•	Time$ returns an 8-character string of the form hh:nn:ss, where hh represents the hour (00-23), nn the minute (00-59), and ss the second (00-59). The function uses a 24-hour clock, so 8:00 PM appears as 20:00:00.

•	The return value of Time$ is equivalent to that of the following statement:

Format$(Now, "hh:nn:ss")


Example

The following example selects a "lucky number" for the user that is based on the exact time the user calls the routine. This number ranges from 1 to 48:

Function OnLButtonDblClk( )

Dim CurrTime, Msg, UserUniv, PowerUp, Choice

CurrTime = Time

UserUniv = 48

PowerUp = CurrTime * 10000000

Choice = (PowerUp Mod UserUniv) + 1

Msg = "Your lucky number, based on the "

Msg = Msg & "exact time of day is: " & Choice

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

CVDate function

Date, Date$ functions

Format, Format$ functions

Now function


Timer function

Example   See also

Returns the number of seconds that have elapsed since midnight of the current day.

Syntax

Timer

Example:

The following statements use the Timer function to determine how long it takes the procedure TestRoutine to execute.

StartTime = Timer

Call TestRoutine

EndTime = Timer

TimeElapsed = EndTime - StartTime

Returns

Double

Tips

•	Timer is automatically used with Randomize to generate a seed for the Rnd (random-number) function.

•	You can also use Timer to time programs or parts of programs.


Example

The code in the following example prompts the user to type a number (500000 is suggested as the default). The computer then "counts" up to that number using a simple FOR NEXT loop. Actuate Basic times this counting process and reports the total number of seconds elapsed to the user.

Function OnLButtonDblClk( )

Dim UserNum, StartTime, I, EndTime, TimeElapsed, Msg

UserNum = InputBox("Please type a number to count up to.", , "500000")

StartTime = Timer

For I = 1 To UserNum

Next I

EndTime = Timer

TimeElapsed = EndTime - StartTime

Msg = "The time it took your computer to count to "

Msg = Msg & UserNum & " was:  " & TimeElapsed

Msg = Msg & " seconds."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Randomize statement


TimeSerial function

Example   See also

Returns a date variant based on supplied integer hour, minute, and second arguments.

Syntax

TimeSerial(<hour>, <minute>, <second>)

<hour>

Numeric expression that specifies a particular hour of the day.

Rule for <hour>: Must be in the range 0 (12:00 AM) through 23 (11:00 PM), inclusive.

<minute>

Numeric expression that specifies a particular minute after <hour>.

Rule for <minute>: Must be in the range 0 through 59, inclusive.

<second>

Numeric expression that specifies a particular second.

Rule for <second>: Must be in the range 0 through 59, inclusive.

Examples:

The following statements are equivalent. Each stores "05:03:46" to the variable TimeVar:

TimeVar = TimeSerial(05, 03, 46)

TimeVar = TimeSerial(5, 3, 46)

Each of the following statements stores the underlying serial number for "05:03:46" (which is about .210949) to the double-precision variable TimeVar#:

TimeVar# = CDbl(TimeSerial(5, 3, 46))

TimeVar# = TimeSerial(5, 3, 46) * 1

Return value

Date

The value TimeSerial returns usually looks like a time but is stored internally as a double-precision fractional number between 0 and .99999. This number represents a time between 00:00:00 and 23:59:59, or 12:00:00 AM and 11:59:59 PM, inclusive.

In other contexts, this fractional number becomes part of what is known as a date serial number--a number that represents a date and/or time from midnight January 1, 100, through December 31, 9999, inclusive.

The integer component of any date serial number represents the date (day, month, and year) while the decimal or fractional component represents the time of day on that date as a proportion of a whole day--where January 1, 1900, at noon has the date serial number 2.5, and where negative numbers represent dates prior to December 30, 1899 (0).

Tip

TimeSerial can return a new time based on calculations done on a given time. In the following example, TimeSerial returns a time that is thirty minutes before 11:45:00 am and assigns it to the variable T:

T = TimeSerial(11, 45, 00) -((30/60)/24)


Example

The following example displays the number of hours, minutes, and seconds to midnight.

Function OnLButtonDblClk()

Dim HrDiff As Integer, MinDiff As Integer, SecDiff As Integer

Dim RightNow As Double, Midnight As Double, TotalDiff As Double

Dim TotalMinDiff As Double, TotalSecDiff As Double
Dim Msg As String

'

Midnight = TimeValue("23:59:59")

' Get current time

RightNow = Now

' Get diffs re midnight

HrDiff = Hour(Midnight) - Hour(RightNow)

MinDiff = Minute(Midnight) - Minute(RightNow)

SecDiff = Second(Midnight) - Second(RightNow) + 1

' Restate seconds and minutes if necessary

If SecDiff = 60 Then

' Add 1 to minute

MinDiff = MinDiff + 1

' And set 0 seconds

SecDiff = 0

End If

If MinDiff = 60 Then

' Add 1 to hour

HrDiff = HrDiff + 1

' And set 0 minutes

MinDiff = 0

End If

' Now get totals

TotalMinDiff = (HrDiff * 60) + MinDiff

TotalSecDiff = (TotalMinDiff * 60) + SecDiff

TotalDiff = TimeSerial(HrDiff, MinDiff, SecDiff)

' Prepare msg for display

Msg = "There are a total of " & Format(TotalSecDiff, "#,##0")

Msg = Msg & " seconds until midnight.  That translates to "

Msg = Msg & HrDiff & " hours, "

Msg = Msg & MinDiff & " minutes, and "

Msg = Msg & SecDiff & " seconds. "

Msg = Msg & "Expressed in standard time notation, it becomes "

' Remember to use "nn" for minutes! m is for month.

Msg = Msg & Format(TotalDiff, "hh:nn:ss") & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

DateSerial function

DateValue function

Hour function

Minute function

Now function

Second function

TimeValue function


TimeValue function

Example   See also

Returns a Date variant representing a time of day, based on a supplied string.

Syntax

TimeValue(<time string>)

<time string>

String expression that specifies a time. Can be any string that can be interpreted as a time of day. You can enter valid times using a 12- or 24-hour clock.

Rules:

•	Must be in the range 00:00:00 (12:00:00 AM) through 23:59:59 (11:59:59 PM).

•	If a date is included in <time string>, it must be a valid one, even though TimeValue will not return a date.

Examples:

The following examples are equivalent. Each stores 1:25:00 PM to the variable TimeVar:

TimeVar = TimeValue("1:25PM")

TimeVar = TimeValue("1:25 PM")

TimeVar = TimeValue("01:25 pm")

TimeVar = TimeValue("13:25")

Each of the following examples stores the underlying serial number for 1:25:00 PM (which is about .559028) to the double-precision variable TimeVar#:

TimeVar# = CDbl(TimeValue("1:25PM"))

TimeVar# = TimeValue("1:25PM") * 1

Return value

Date

TimeValue returns looks like a time but is stored internally as a double-precision fractional number between 0 and .99999. This number represents a time between 00:00:00 and 23:59:59, or 12:00:00 AM and 11:59:59 PM, inclusive.

In other contexts, this fractional number becomes part of what is known as a date serial number--a number that represents a date and/or time from midnight January 1, 100, through December 31, 9999, inclusive.

The integer component of any date serial number represents the date (day, month, and year) while the decimal or fractional component represents the time of day on that date as a proportion of a whole day--where January 1, 1900, at noon has the date serial number 2.5, and where negative numbers represent dates prior to December 30, 1899 (0).


Example

The following example displays the number of hours, minutes, and seconds to midnight.

Function OnLButtonDblClk()

Dim HrDiff As Integer, MinDiff As Integer, SecDiff As Integer

Dim RightNow As Double, Midnight As Double, TotalDiff As Double

Dim TotalMinDiff As Double, TotalSecDiff As Double
Dim Msg As String

'

Midnight = TimeValue("23:59:59")

' Get current time

RightNow = Now

' Get diffs re midnight

HrDiff = Hour(Midnight) - Hour(RightNow)

MinDiff = Minute(Midnight) - Minute(RightNow)

SecDiff = Second(Midnight) - Second(RightNow) + 1

' Restate seconds and minutes if necessary

If SecDiff = 60 Then

' Add 1 to minute

MinDiff = MinDiff + 1

' And set 0 seconds

SecDiff = 0

End If

If MinDiff = 60 Then

' Add 1 to hour

HrDiff = HrDiff + 1

' And set 0 minutes

MinDiff = 0

End If

' Now get totals

TotalMinDiff = (HrDiff * 60) + MinDiff

TotalSecDiff = (TotalMinDiff * 60) + SecDiff

TotalDiff = TimeSerial(HrDiff, MinDiff, SecDiff)

' Prepare msg for display

Msg = "There are a total of " & Format(TotalSecDiff, "#,##0")

Msg = Msg & " seconds until midnight.  That translates to "

Msg = Msg & HrDiff & " hours, "

Msg = Msg & MinDiff & " minutes, and "

Msg = Msg & SecDiff & " seconds. "

Msg = Msg & "Expressed in standard time notation, it becomes "

' Remember to use "nn" for minutes! m is for month.

Msg = Msg & Format(TotalDiff, "hh:nn:ss") & "."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

DateSerial function

DateValue function

Hour function

Minute function

Now function

Second function

TimeSerial function


Trim, Trim$ functions

Example   See also

Returns a copy of a string after removing leading and trailing spaces.

Syntax

Trim(<string expression>)

Trim$ (<string expression>)

<string expression>

String expression from which Trim[$] strips leading and trailing spaces. Leading spaces are any spaces that occur before the first non-space character in a string (leftmost spaces). Trailing spaces are any spaces that occur after the last non-space character in a string (rightmost spaces).

Returns

Trim: Variant

Trim$: String

•	If there are no leading or trailing spaces, Trim[$] returns the original <string expression>.

•	Trim[$] has no effect on spaces in the middle of a string.

Tips

•	To strip extraneous spaces a user added in response to a prompt, use Trim[$].

•	To find other spaces in the middle of a string, use InStr.


Example

The following example strips leading and trailing spaces from a string variable. It shows a typical situation in which you would use Trim[$] to remove extraneous spaces a user might have entered in response to a prompt.

Function OnLButtonDblClk()

Dim Msg, NL, CustName, CustName1, LeftSpcs, RightSpcs, Instruct

' Define newline

NL = Chr(10)

Instruct = "Type a customer name.  Put "

Instruct = Instruct & "a few extra spaces before and "

Instruct = Instruct & "after it, to simulate something "

Instruct = Instruct & "a user might do unintentionally."

CustName = InputBox(Instruct)

' Number of leading spaces

LeftSpcs = Len(CustName) - Len(LTrim$(CustName))

' Number of trailing spaces

RightSpcs = Len(CustName) - Len(RTrim$(CustName))

' Strip left and right spaces

CustName1 = Trim$(CustName)

Msg = "The original name " & NL & "'" & CustName & "'" & NL & " was "

Msg = Msg & Len(CustName) & " characters long. There were " & LeftSpcs

Msg = Msg & " leading spaces and " & RightSpcs & " trailing spaces." & NL

Msg = Msg & "The name returned after stripping the spaces "

Msg = Msg & "is:" & NL & "'" & CustName1 & "'" & NL & " which is only "

Msg = Msg & Len(CustName1) & " characters."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

InStr function

LTrim, LTrim$ functions

RTrim, RTrim$ functions


Type...End Type statement

Example   See also

Declares a user-defined variable or record structure.

Syntax

Type <user-defined variable type>

<component variable> [(<subscripts>)] As <data type>

[ <component variable> [(<subscripts>)] As <data type>]

. . .

End Type

<user-defined variable type>

The name of a user-defined data type.

Rule for <user-defined variable type>: Must follow standard variable-naming conventions.

<component variable>

The name of an element of the user-defined data type.

Rule for <component variable>: Must follow standard variable-naming conventions.

<subscripts>

The dimensions of an array element. Each <subscripts> argument specifies the number of elements in a single dimension. The number of <subscripts> arguments for an array variable specifies the number of dimensions in the array.

The syntax of <subscripts> is as follows:

 [<lower> To]<upper>[,[<lower> To]<upper>]...

Rules for <subscripts>:

•	<lower> and <upper> can range from -2,147,483,648 to +2,147,483,647 inclusive.

•	<lower> must always be less than <upper>.

•	<lower> and <upper> cannot be the names of variables. They must be literal numeric constants.

•	Each <subscripts> clause can specify up to 60 dimensions.

You cannot use Type to declare dynamic arrays. However, you can declare the dimensions for an existing dynamic array within Type.

<data type>

The name of a valid data type.

Rules for <data type>:

•	Can be any valid Actuate Basic data type except an object type, including String (for variable-length strings).

•	Can be another user-defined type.

Examples:

The following three arrays are equivalent if you do not use Option Base:

MyArray(7,5)

MyArray(0 TO 7, 0 TO 5)

MyArray(7, 0 TO 5)

The following shows the use of array variables in the context of Type.

Declare

Type CustomerData

CustName As String

CustAddress As String

ArrayPhones(5) As String

ArrayOther(5 To 10, 31) As Double

End Type

End Declare

Rules

•	You cannot use line numbers or line labels in Type.

•	When declaring a static array within Type, you must use literal numeric constants rather than variables to declare its dimensions.

Tip

To more easily manipulate data records that consist of a number of related elements of different data types, use Type to define your own custom data types.


Example

The following example creates a user-defined type with three elements. Then it declares a new variable of the user-defined type, and prompts the user to assign data to each element. To use this example, first create a user-defined type and call it SampleRec. Paste the code for SampleRec in your Actuate Basic source code (.BAS) file. Paste the rest of the code into the OnLButtonDblClk( ) method of a clickable component like a label.

Declare

Type SampleRec

ClientNum As Long

ClientName As String

ClientPurchase As String

End Type

End Declare

'

Function OnLButtonDblClk ( )

Dim UserAns, FileNum, IDTracker, Msg, NL, TB

' Declare new variable to be of user-defined type SampleRec

Static ClientEntry As SampleRec

' Define newline and tab

NL = Chr$(10): TB = Chr$(9)

' Get an unused file number

FileNum = FreeFile

Open "SAMPLE.FIL" For Random As FileNum

' Track record numbers

IDTracker = 1

' Now get data from user to fill the elements of data records:

Do

ClientEntry.ClientNum = IDTracker

Msg = "Please type client name. Type 'END' when finished."

ClientEntry.ClientName = InputBox(Msg)

If UCase$(Trim(ClientEntry.ClientName)) = "END" Then Exit Do

Msg = "Please type the amount of the purchase:"

ClientEntry.ClientPurchase = InputBox(Msg)

Msg = "Client #"

Msg = Msg & ClientEntry.ClientNum & NL

Msg = Msg & ClientEntry.ClientName & NL

Msg = Msg & ClientEntry.ClientPurchase & NL

Msg = Msg & NL & "Is this data correct?"

' Display current rec, confirm

UserAns = MsgBox(Msg, MB_YESNOCANCEL)

' If Yes

If UserAns = IDYES Then

Put FileNum, IDTracker, ClientEntry

' Increment record counter

IDTracker = IDTracker + 1

End If

Loop

Close FileNum

Msg = "The records you typed were written to a test file.  "

Msg = Msg & "Choose OK to delete the test file from your disk."

MsgBox Msg

' Delete test file

Kill "SAMPLE.FIL"

End Function

For information about using the code examples, see Using the code examples.


See also

Class statement

Declare statement

Type...As statement


Type...As statement

Example   See also

Declares an alias for an existing data type.

Syntax

Type <alias data type name> As <existing data type name>

<alias data type name>

The name you assign as an alias for an existing data type.

Rule for <alias data type name>: Must follow standard naming conventions.

<existing data type name>

The name of an existing, valid data type.

Rule for <existing data type name>: Must follow standard naming conventions.


Example

The following example illustrates the use of Type As. To use this example, paste the first portion at or near the beginning of your Actuate Basic source code (.BAS) file. Then copy the second portion into the OnLButtonDblClk() method of a clickable component like a label.

Declare

Type SampleRec

ClientNum As Long

ClientName As String

ClientPurchase As Currency

End Type

Type OtherName As SampleRec

Type LogicalVar As Boolean

End Declare

Function OnLButtonDblClk( )

Dim UserVar1 As OtherName, IsValid As LogicalVar

Dim Msg As String, UserAns, NL

NL = Chr$(10)

UserVar1.ClientName = InputBox("Please type a client's name.")

Msg = "You typed:  " & UserVar1.ClientName & NL & NL

Msg = Msg & "Is this correct?"

' Display current name, confirm

UserAns = MsgBox(Msg, 4)

If UserAns = 6 Then 	' If Yes

' Set Boolean to True

IsValid = 1

Else

' If No, set to False

IsValid = 0

End If

MsgBox "The value of the IsValid variable is:  " & IsValid

If IsValid Then

Msg = "In other words, IsValid is True."

Else

Msg = "In other words, IsValid is False."

End If

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Class statement

Declare statement

Type...End Type statement


UBound function

Example   See also

Returns the largest available subscript for the given dimension of an array.

Syntax

UBound(<array name>[,<dimension>])

<array name>

Name of an array variable.

<dimension>

Numeric expression that specifies the array dimension for which you want to determine the upper bound.

Default: 1.

Rules:

•	Use 1 for the first dimension, 2 for the second, and so on.

•	Must not be larger than the total number of dimensions in <array name>.

•	Must not be zero, negative, or Null.

Examples:

The following example shows the values UBound returns for an array with these dimensions:

Dim MyArray(1 To 55, 0 To 27, -3 To 42)

UBound(MyArray, 1) = 55

UBound(MyArray, 2) = 27

UBound(MyArray, 3) = 42

Return value

Integer

Rule: If <dimension> is not an Integer, UBound rounds it to the nearest Integer before evaluating it.

Tips

•	To determine the lower bound of an array, use LBound.

•	To determine the total number of elements in a given dynamic array dimension, take the value returned from UBound, subtract the value returned from LBound, then add 1.


Example

The following example uses UBound to determine the upper bounds of an array of 3 dimensions. The use of Rnd simulates changes in upper bounds that may have been made by the user at runtime in response to your program.

Function OnLButtonDblClk( )

Dim First As Integer, Sec As Integer, Third As Integer

Dim Msg As String, NL As String, TabChar As String

' Declare array variable

Dim MyArray()

' Define newline, tab

NL = Chr(10): TabChar = Chr(9)

' Seed rnd generator

Randomize

' First dimension

First = Int(14 * Rnd + 3)

' Second dimension

Sec = Int(14 * Rnd + 3)

' Third dimension

Third = Int(14 * Rnd + 3)

' Set dimensions

ReDim MyArray(First, Sec, Third)

Msg = "MyArray has the following upper bounds: " & NL

Msg = Msg & TabChar & "Dimension 1 ---> " & UBound(MyArray, 1) & NL

Msg = Msg & TabChar & "Dimension 2 ---> " & UBound(MyArray, 2) & NL

Msg = Msg & TabChar & "Dimension 3 ---> " & UBound(MyArray, 3)

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

LBound function

Rnd function

Dim statement


UCase, UCase$ functions

Example   See also

Converts all lowercase alphabetic characters in a string to uppercase.

Syntax

UCase(<string exprs>)

UCase$(<string exprs>)

<string exprs>

String expression that contains the characters to change to uppercase.

Examples:

The following statements are equivalent. Each returns "6 JANE STREET, 2ND FL".

UCase$("6 jane street, 2nd fl")

UCase$("6 Jane Street, 2nd Fl")

UCase$("6 jAn" & "E sTreeT, 2nD fL")

Return value

UCase: Variant

UCase$: String

•	If <string exprs> contains no lowercase alphabetic characters, UCase[$] returns the original <string exprs>.

•	UCase[$] has no effect on non-alphabetic characters in <string exprs>.

Tips

•	To ensure uniformity in the data you get from the user--so that, for instance, strings like "MacManus," "Macmanus," and "macMaNus" are always sorted, or compared, or otherwise treated in the same way, use UCase[$] in your reports to convert the data before you go ahead and use it.

•	To convert alphabetic characters in <string exprs> to all-lowercase characters, use LCase[$].


Example

The following example uses UCase[$] to render the all-uppercase version of a customer's name.

Function OnLButtonDblClk( )

Dim AnyCase, Uppercase, Msg

AnyCase = InputBox("Please type a customer's name.")

' Convert to uppercase

Uppercase = UCase$(AnyCase)

Msg = "UCase$ converts """ & AnyCase & """ to """

Msg = Msg & Uppercase & """."

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

LCase, LCase$ functions


Val function

Example   See also

Returns the numeric value of a string expression.

Syntax

Val(<string exprs>)

<string exprs>

String expression from which to extract a numeric value.

Examples:

The following are equivalent. They both return the value 118.

Val("      118 36th Street")

Val("      118 36th Street, #55")

The following returns the value 11836.

Val("&H2E3C")

Because the first character is non-numeric, the following returns 0.

Val("$1,275,332.52")

Return value

Double

•	Starts translating a string into a number by starting at the left of the string and proceeding toward the right.

•	Stops translating the string as soon as it encounters a non-numeric character or the end of the string, whichever comes first.

•	Interprets the prefixes &O and &H as numeric characters representing octal and hexadecimal numbers, respectively.

•	Interprets dollar sign and commas as non-numeric.

•	Ignores spaces, tabs, and line feeds.

•	Interprets the first period or dot it encounters as a decimal point, but stops translating at the appearance of the second period or dot.

•	Returns zero if it stopped before it encounters a numeric character.

Tip

•	To convert a number to a String use Str$.

•	To avoid having to use Val, use the Variant data type for variables when it is necessary to convert between strings and numbers.


Example

The following example returns the value of a string you enter.

Function OnLButtonDblClk ( )

Dim Msg, Number

Number = Val(InputBox$("Type a string containing some numbers."))

Msg = "VAL extracted this value from your input:  " & Number

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Format, Format$ functions

Str, Str$ functions


VarType function

Example   See also

Returns a value that indicates how a Variant is stored internally by Actuate Basic.

Syntax

VarType(<variant variable>)

<variant variable>

String expression that specifies a variant of the Variant data type.

Returns

Integer

The following table shows the values returned by VarType, the Variant data types they indicate, and the names of the corresponding symbolic constants stored in HEADER.BAS.

VarType returns	Data type of <variant variable>	Symbolic constant
0	Empty	V_EMPTY
1	Null	V_NULL
2	Integer	V_INTEGER
3	Long	V_LONG
4	Single	V_SINGLE
5	Double	V_DOUBLE
6	Currency	V_CURRENCY
7	Date	V_DATE
8	String	V_STRING


Example

The following example prompts the user to type a date, number, or string. It then displays the Variant data type for the user's response. Numeric data in this example always returns Variant type 5 (Double). Date and string data return Variant types 7 and 8, respectively. If the user types nothing, the sample code returns a zero-length string (Variant type 8).

Function OnLButtonDblClk( )

Dim UserTyped

UserTyped = InputBox("Please type a date, number, or string.")

If IsNumeric(UserTyped) Then

MsgBox "That's numeric."

UserTyped = CDbl(UserTyped)

End If

If IsDate(UserTyped) Then

MsgBox "That's a date."

UserTyped = CVDate(UserTyped)

End If

MsgBox "That is of VarType:  " & VarType(UserTyped)

End Function

For information about using the code examples, see Using the code examples.


See also

IsDate function

IsEmpty function

IsNull function

IsNumeric function


Weekday function

Example   See also

Returns an Integer between 1 (for Sunday) and 7 (for Saturday) that represents the day of the week for a supplied date argument.

Syntax

Weekday(<date exprs>)

<date exprs>

Date expression, or any numeric or string expression that can be interpreted as a date, or as both a date and a time.

•	Can be a string such as "November 12, 1982 8:30 PM", "Nov 12, 1982 08:30 PM", "11/12/82 8:30pm", or any other String that can be interpreted as a date or date/time in the valid range.

•	Can be a date serial number such as 30267.854 (which corresponds to November 12, 1982 at 8:30 PM), or any other number that can be mapped to a date or date/time in the valid range.

•	For date serial numbers, the integer component represents the date itself while the fractional component represents the time of day on that date, where January 1, 1900, at noon has the date serial number 2.5, and negative numbers represent dates prior to December 30, 1899 (0).

Rules:

•	If a time is included, it must be a valid time, even though Weekday will not return a time. A valid time is one that is in the range 00:00:00 (12:00:00 AM) through 23:59:59 (11:59:59 PM), in either 12- or 24-hour format.

•	If a numeric expression, it must be in the range -657434 to +2958465, inclusive.

•	If a variable containing a date serial number, the variable must have been explicitly declared as one of the numeric types.

•	For abridged date expressions ending in 00 through 29 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 2000. For example, while Year(4/30/1910) returns 1910, the abridged expression Year(4/30/10) returns 2010 (10 + 2000).

•	For abridged date expressions ending in 30 through 99 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 1900. For example, while Year(11/12/2082) returns 2082, the abridged expression Year(11/12/82) returns 1982 (82 + 1900).

Note that there are arguably "abridged" dates like Nov 12, 1982 (versus November 12, 1982) that do specify the century. Note also that both abridged and unabridged dates are dates ending in 00 through 99.

Examples:

The following statements are equivalent. Each assigns 1 (which maps to Sunday) to the variable DayOfWeek:

DayOfWeek = Weekday("6/7/64  2:35pm")

DayOfWeek = Weekday("June 7, 1964 2:35 PM")

DayOfWeek = Weekday("Jun " & 5+2 & ", 1964")

DayOfWeek = Weekday(23535.6076)

DayOfWeek = Weekday(0.6076) - 6

Return value

Integer

•	If <date exprs> is Null, Weekday returns a Null.

•	If Weekday returns 1, the day of the week for <date exprs> is Sunday; if 2, Monday, and so on.


Example

The following example displays a message indicating whether today is a weekend day or a weekday.

Function OnLButtonDblClk( )

Dim DayNum As Integer, Msg As String, FullDesc as String

' Get current day of week

DayNum = Weekday(Now)

FullDesc = Format(Now, "dddd, mmmm dd, yyyy")

' Is it a weekend day?

If DayNum = 1 Or DayNum = 7 Then

Msg = "Today is " & FullDesc & ". It is a weekend day."

'... or is it a weekday?

Else

Msg = "Today is " & FullDesc & ".  It is a weekday."

End If

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Date, Date$ functions

Day function

Hour function

Minute function

Month function

Now function

Second function

Year function


While...Wend statement

Example   See also

Repeats a block of instructions each time a specified condition is True.

Syntax

While <expression to reevaluate>

<statements to repeat>

Wend

<expression to reevaluate>

Any valid numeric or string expression that evaluates to True (1) or False (0 or Null).

<statements to repeat>

One or more valid Actuate Basic statements; the statements that, collectively taken, are referred to as "the loop."

Example:

Assuming the variable Counter starts at 1 and is incremented by 1 each time through the loop, the following statement will cause its associated loop to be executed nine times.

While Counter < 10

Description

First, <expression to reevaluate> is tested. If it is True, the <statements to repeat> in the body of the loop are executed. Then <expression to reevaluate> is tested again. If it is still True, <statements to repeat> are executed again. This process repeats until <expression to reevaluate> is False. In that case, Actuate Basic skips all intervening <statements to repeat> and passes control to the statement immediately following Wend.

Rule

Do not branch into the middle of a While...Wend statement. Execute the entire statement instead, starting at the line with the While keyword.

Tips

•	To take advantage of its greater flexibility, use Do...Loop instead of While Wend.

•	To be sure the loop executes at least once, explicitly set <expression to reevaluate> to True in a statement that closely or immediately precedes the While...Wend statement.

•	It is good programming practice to evaluate Boolean variables -- not by inspecting their content for a nonzero (True) or zero (False) numeric value -- but by using the keywords True or False.


Example

The following example sorts an array.

Function OnLButtonDblClk()

Dim SwapThese, Position As Integer, Msg, NL, TempVar

' Declare an array

Static Cities(5)

' Define newline

NL = Chr$(10)

'Now assign array data out of alphabetical order

'so we can see sort illustrated.

Cities(1) = "New York"

Cities(2) = "San Francisco"

Cities(3) = "Paris"

Cities(4) = "Boston"

Cities(5) = "Seattle"

' Make sure we loop at least once

SwapThese = True

' Sort while there still are elements we need to swap

While SwapThese

' Now compare array elements by pairs. When two are swapped,

' ensure another pass thru loop by setting SwapThese to TRUE:

SwapThese = False

For Position = 2 To 5

If Cities(Position - 1) > Cities(Position) Then

SwapThese = True

' Now do the swap:

TempVar = Cities(Position)

Cities(Position) = Cities(Position - 1)

Cities(Position - 1) = TempVar

End If

Next Position

Wend

Msg = "New, sorted order: " & NL & NL

For Position = 1 To 5

Msg = Msg & Cities(Position) & NL

Next Position

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Do...Loop statement

If...Then...Else statement


Width # statement

Example   See also

Defines the width of the output line of a sequential file.

Syntax

Width #<open file number>, <new line width>

<open file number>

Numeric expression that is the file number for a file opened with the Open statement.

Rule: The file number must refer to a file that is currently open.

<new line width>

Numeric expression that is the new width for the line. Width is measured as the number of characters Actuate Basic will print on a line before it begins a new line. If <new line width> is specified as 0, there is no limit to the length of the line.

Default: 0

Rule: Must be in the range of 0-255, inclusive.

Example:

The following statement sets the output line width to 75 columns for open file #1.

Width #1, 75

Description

When you print to an ASCII text file, you may need to define a maximum output length for each line. Use the Width # statement for this operation.


Example

In the following example, the code first creates a test file and writes some ASCII characters to it using the default output width (unlimited). Then the width is changed, and the same ASCII characters are appended to the file. Finally, the entire file is read back and displayed with both sets of ASCII characters, then deleted.

Function OnLButtonDblClk( )

Dim I As Integer, Msg As String, NL As String, TextLines As String

' Define newline

NL = Chr$(10)

' Create a sample text file

Open "TESTFILE.TXT" For Output As #1

' Print ASCII characters . . . 0-9 all on same line

Width #1, 10

Print #1, "Width 10:"

For I = 0 To 9

Print #1, Chr$(48 + I)

Next I

' Start a new line

Print #1,

' Change the line width to 4

Width #1, 4

' Print ASCII characters . . . 4 characters to a line

For I = 0 To 9

Print #1, Chr$(48 + I)

Next I

Close #1

Msg = "The effect of WIDTH # is as displayed: " & NL

' Reopen test file for input

Open "TESTFILE.TXT" For Input As #1

Do While Not EOF(1)

' Get contents of each line

Input #1, TextLines

Msg = Msg & NL & TextLines

Loop

Close #1

Msg = Msg & NL & "Please select OK to delete the text file."

' Display results

MsgBox Msg

Kill "TESTFILE.TXT"

End Function

For information about using the code examples, see Using the code examples.


See also

Space, Space$ functions

Tab function

Open statement

Print # statement


Write # statement

Example   See also

Formats and writes data to a sequential file.

Syntax

Write #<file number> [, <exprs 1>] [, <exprs 2>] [, <exprs 3>]...

<file number>

Numeric expression that is the file number of a sequential file that is Open for Output or Append.

Example:

The following statements work together, although they can be separated from one another by lines of code. The first statement opens a file called "MYNOTES.FIL", the second one writes the contents of four variables to that file, and the third, by closing it, turns the file over to the operating system to complete the process of writing it to the disk.

Open "C:\MYFILES\MYNOTES.FIL" FOR OUTPUT AS #2

Write #2, A$, B%, C!, D#

Close #2

The following statement writes the specified variables to the file opened by a previous Open statement under number 1. Actuate Basic places double quotes around the value in StringVar$, and it inserts commas between all the variables in order to delimit them. Finally, after the value in DoubleVar#, it writes a newline character.

Write #1, StringVar$, IntVar%, SingleVar!, DoubleVar#

<exprs n>

Numeric and/or string expression that specifies the data that Write # places in the file. There can be any number of these.

Default: Newline character only.

Description

When Write # writes to the file it inserts commas between items and places quotation marks around strings. You don't need to put explicit delimiters in the list. Write # also inserts a newline character after it writes the final <exprs> to the file.

Write # usually writes Variant data to a file the same way it writes data of any other Actuate Basic data type. The following table, however, notes certain exceptions.

Data	Write # writes to the file
One Variant of type 0 (Empty)	Nothing at all
More than one Variant of type 0 (Empty)	Delimiting commas
Variant of type 1 (Null)	Literal #NULL#
Variant of type 7 (Date)	The date, using the fixed date format: #yyyy-mm-dd hh:nn:ss#
Variant of type 7 (Date), but with either the date or time component missing or zero	Only the part of the date provided
Rules

•	<file number> must match the number of a currently open file.

•	The file corresponding to <file number> must be open under either the Output or Append mode.

•	You must have write access to the open file. That is, the file must not have been opened using a Lock Write or Lock Read Write clause.

•	The data cannot be an object variable, user-defined data type structure, handle to a class, CPointer, or OLE object.

Tip

Many database programs let you import data when the data is structured in the way that Write # structures it. Such programs interpret each newline character as delimiting the end of a complete record, and treat each comma on a line as delimiting the end of a field within that record. This means you can use Write # to export information from Actuate Basic to almost any database program.


Example

The following example prompts the user for their name and age. It then writes this information to a test file, reads the file back, places the data in a message, and finally, displays the message to the user. After the user responds, it deletes the file from the disk.

Function OnLButtonDblClk( )

Dim Msg, NL, UsersAge, UsersName

' Define newline

NL = Chr$(10)

' Now create a sample data file:

' Open the file for output

Open "TEST.FIL" For Output As #1

Msg = "Please enter your name."

UsersName = InputBox(Msg)

Msg = "Enter your age."

UsersAge = InputBox(Msg)

' Write data to test file

Write #1, UsersName, UsersAge

' Close file

Close #1

' Now read back the sample data file:

' Open test file for input

Open "TEST.FIL" For Input As #1

' Read the data in it

Input #1, UsersName, UsersAge

' Close file

Close #1

Msg = "The name '" & UsersName & "' was read from the test file. "

Msg = Msg & "'" & UsersAge & "' is your age."

Msg = Msg & NL & NL & "Choose OK to delete the test file."

MsgBox Msg

' Delete file from disk

Kill "TEST.FIL"

End Function

For information about using the code examples, see Using the code examples.


See also

Open statement

Print # statement


Year function

Example   See also

Returns an Integer between 100 and 9999, inclusive, that represents the year of a supplied date argument.

Syntax

Year(<date exprs>)

<date exprs>

Date expression, or any numeric or string expression that can evaluate to a date. Specifies a date and/or time.

•	Can be a string such as "November 12, 1982", "Nov 12, 1982", "11/12/82", or "11-12-82", or any other string that can be interpreted as a date in the valid range.

•	Can be a date serial number such as 30267.854 (which corresponds to November 12, 1982 at 8:30 PM), or any other number that can be mapped to a date in the valid range.

•	For date serial numbers, the integer component represents the date itself while the fractional component represents the time of day on that date, where January 1, 1900, at noon has the date serial number 2.5, and negative numbers represent dates prior to December 30, 1899 (0).

Rules:

•	If a string expression, must specify a date in the range January 1, 100, through December 31, 9999, inclusive.

•	If a numeric expression, must be in the range -657434 to +2958465, inclusive.

•	If a variable containing a date serial number, the variable must have been explicitly declared as one of the numeric types.

•	For abridged date expressions ending in 00 through 29 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 2000. For example, while Year(4/30/1910) returns 1910, the abridged expression Year(4/30/10) returns 2010 (10 + 2000).

•	For abridged date expressions ending in 30 through 99 that do not specify the century, relevant date functions "guess" at the unabridged year by adding 1900. For example, while Year(11/12/2082) returns 2082, the abridged expression Year(11/12/82) returns 1982 (82 + 1900).

Note that there are arguably "abridged" dates like Nov 12, 1982 (versus November 12, 1982) that do specify the century. Note also that both abridged and unabridged dates are dates ending in 00 through 99.

Examples:

The following statements are equivalent. Each assigns 1964 to the variable UserYear:

UserYear = Year("6/7/64")

UserYear = Year("June 7, 1964 2:35 PM")

UserYear = Year("Jun 7, 1964")

UserYear = Year(23535)

UserYear = Year(4707*5)

Returns

Integer

Rule: If <date exprs> is Null, Year returns a Null.


Example

The following example prompts the user to enter a date. Then it uses various interrelated date functions to display the year, the month, the day and the weekday for the given date. Finally, it gives the date's serial number. To use this example, paste the first portion into your Actuate Basic source code (.BAS) file. Then paste the second portion into the OnLButtonDblClk( ) method of a clickable component like a label.

' This  function tells us what suffix (1st, 2nd, 3rd) to use with a number

Function Suffix (DateNum) As String

Select Case DateNum

Case 1

Suffix = "st"

Case 2

Suffix = "nd"

Case 3

Suffix = "rd"

Case Else

Suffix = "th"

End Select

End Function

'

Function OnLButtonDblClk( )

Dim UserEntry As String, UserYear As Integer, UserMonth As Integer

Dim UserDay As Integer, UserDOW As Integer, DOWName As String

Dim Msg As String, NL As String, LeapYear

' Define newline

NL = Chr$(10)

' Get user input

UserEntry = InputBox("Please type a date.")

' Calculate year

UserYear = Year(UserEntry)

' Calculate month

UserMonth = Month(UserEntry)

' Calculate day

UserDay = Day(UserEntry)

' Calculate day of week

UserDOW = Weekday(UserEntry)

' Convert to name of day

DOWName = Format$ (UserEntry, "dddd")

' Determine if the year is a leap year or a centesimal

If UserYear Mod 4 = 0 And UserYear Mod 100 = 0 Then

' Evenly divisible by 400?

If UserYear Mod 400 = 0 Then

LeapYear = "is a leap year."

' Not evenly divisible

Else

LeapYear = "is a centesimal but not a leap year."

End If

ElseIf UserYear Mod 4 = 0 Then

LeapYear = "is a leap year."

Else

LeapYear = "is not a leap year."

End If

' Display results for the user after the pattern:

' The given year 1982 is not a leap year. The weekday number for

' the 12th day of the 11th month in 1982 is 6, which means that

' day was a Friday.

'

' The date serial number for 11/12/82 is: 30267

'

MsgBox "The given year, " & UserYear & ", " & LeapYear

Msg = "The weekday number for the "

Msg = Msg & UserDay & Suffix(UserDay) & " day "

Msg = Msg & "of the " & UserMonth & Suffix(UserMonth) & " month "

Msg = Msg & "in " & UserYear & " is " & UserDOW

Msg = Msg & ", which means that day is a " & DOWName & "." & NL & NL

Msg = Msg & "The date serial number for " & UserEntry & " is:  "

Msg = Msg & CDbl(DateSerial(UserYear, UserMonth, UserDay))

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

Date, Date$ functions

Day function

Hour function

Minute function

Month function

Now function

Second function

Weekday function


Actuate Basic data types

The following elementary data types are supported by Actuate Basic.

Data type	Suffix	Data size	Range
Integer	%	4 bytes 32 bits	-2,147,483,648 to +2,147,483,647
Long integer	&	4 bytes 32 bits	-2,147,483,648 to +2,147,483,647
Single-precision floating-point	!	8 bytes 64 bits	-1.797693134862315E308 to -4.94066E-324 for negative values; 4.94066E-324 to 1.797693134862315E308 for positive values.
Date-precision floating-point	None	8 bytes 64 bits	1 January 100 to 31 December 9999
Double-precision floating-point	#	8 bytes 64 bits	-1.797693134862315E308 to -4.94066E-324 for negative values; 4.94066E-324 to 1.797693134862315E308 for positive values.
Currency (scaled integer)	@	12 bytes 96 bits	-39,614,081,257,132,168,796.771975167 to +39,614,081,257,132,168,796.771975168
String	$	1 byte per character	0 to approximately 2,147,483,648 bytes or memory limit.
CPointer	None	4 bytes 32 bits
User-defined data (using Type)	None	Number of bytes  defined by elements	The range of each element depends on its fundamental type.
Any	None		Used to suppress type-checking of arguments passed to DLL procedures.
Variant	None		The range of each element depends on its fundamental type


Any data type

The Any data type is used only to suppress type checking of arguments passed to dynamic-link library (DLL) procedures.


CPointer data type

The CPointer data type is used to hold a pointer to data allocated in a C function you have created


Currency data type

Currency variables are stored as 96-bit numbers (12 bytes) in a two's complement integer format, and are scaled by 1,000,000,000 to give a fixed point number with 20 digits to the left of the decimal point and 9 digits to the right. This representation provides a range of -39,614,081,257,132,168,796.771975167 to +39,614,081,257,132,168,796.771975168. The type-declaration character for a Currency variable is @ (ANSI character 64).

The Currency data type is useful for calculations involving money and for fixed-point calculations in which accuracy is particularly important.


Date data type

Date variables are stored as 64-bit (8 byte) floating-point numbers that represent dates ranging from 1 January 100 to 31 December 9999 and times from 0:00:00 to 23:59:59. Date variables display dates and times based on the formats specified by your computer.

The Date data type is useful for performing calculations on date/time values.  Adding and subtracting Integers operates on the date.  Adding or subtracting fractions operates on the time.


Double data type

Double (double-precision floating-point) variables are stored as 64-bit numbers (8 bytes) ranging in value from -1.797693134862315E308 to -4.94066E-324 for negative values and from 4.94066E-324 to 1.797693134862315E308 for positive values. The type-declaration character for a Double is # (ANSI character 35).

Note  Double-precision floating-point numbers are stored in memory using IEEE 64-bit floating-point format. Each floating-point value consists of three parts: the sign, the exponent, and the mantissa. In a double-precision number, the sign takes I bit, the exponent takes 11 bits, and the mantissa uses the remaining 52 bits plus an additional implied bit.


Integer data type

Integer variables are stored as signed 32-bit numbers (4 bytes) ranging in value from -2,147,483,648 to 2,147,483,647. The type-declaration character for an Integer is % (ANSI character 37).

In addition to representing numbers in this range, Integers can represent Boolean values (values that can have only one of two states). For Boolean values, 1 represents true and 0 represents false. You can also use the Actuate Basic reserved words True and False, which return 1 and 0, respectively.

You can also use Integers to represent enumerated values. An enumerated value can contain a finite set of unique whole numbers, each of which has special meaning in the context in which it is used. Enumerated values provide a convenient way to select among a known number of choices.


Long data type

Long (long integer) variables are stored as signed 32-bit numbers (4 bytes) ranging in value from -2,147,483,648 to 2,147,483,647. The type-declaration character for a Long is & (ANSI character 38).


Single data type

Single (single-precision floating-point) has the same precision and range as Double in Actuate Basic.


String data type

Variable-length strings can contain up to approximately 2,147,283,647 characters or up to your computer's memory limit. Because some storage overhead is required, a string can't actually be 2,147,283,647 characters long.

The type-declaration character for a String is $ (ANSI character 36). The codes for String characters range from 0 to 255. String characters used by all applications designed for Microsoft Windows consist of ANSI characters. The first 128 characters (0-127) correspond to the letters and symbols on a standard U.S. keyboard. These first 128 characters are the same as defined by the ASCII character set. The second 128 characters (128-255) represent special characters, such as letters in international alphabets, accents, currency symbols, and fractions.

Unlike Visual Basic, Actuate Basic's InputBox function by default treats numbers supplied by the user as string data. When you assign a Variant variable to the value returned by InputBox, you will not be able to use this value in an arithmetic expression. For example:

Dim Alpha, Beta, Gamma

Alpha = InputBox("What is Alpha?")

Beta = InputBox("What is Beta?")

'The following expression will cause a runtime error

Gamma = Alpha * Beta

MsgBox Gamma

Some functions, like PV, will treat a string from the InputBox, with a Variant variable assigned to it, as zero. This zero will not cause an error but instead will return an incorrect value.


User-defined data type

Any data type that you define using the Type reserved word. User-defined data types can contain one or more elements of any fundamental Actuate Basic data type.


Variant data type

The Variant data type is the default for Actuate Basic--the data type that all variables become if they are not explicitly declared to be of some other type (using Dim, Global, or Static). The Variant data type has no type-declaration character.

The Variant is a special data type that can contain numeric, string, or date data as well as the special values empty and Null. You can determine how the data in a Variant is treated by using the VarType function. The following table illustrates the return value of the VarType function and the corresponding interpretation of the contents of the Variant:

Return value	Interpretation of Variant
0	Empty (uninitialized)
1	Null (no valid data)
2	Integer
3	Long (long integer)
4	Single (single-precision floating-point)
5	Double (double-precision floating-point)
6	Currency (scaled integer)
7	Date
8	String
9	CPointer
Numeric data can be any Integer or real number value ranging from -1.797693134862315E308 to -4.94066E-324 for negative values and from 4.94066E-324 to 1.797693134862315E308 for positive values. Generally, numeric Variant data is maintained in its original fundamental data type within the Variant. For example, if you assign an Integer to a Variant, subsequent operations treat the Variant as if it were an Integer. However, if an arithmetic operation is performed on a Variant containing an Integer, a Long, or a Single, and the result exceeds the normal range for the original data type, the result is promoted within the Variant to the next larger data type. An Overflow error occurs when Variant variables containing Currency and Double values exceed their respective ranges.

Always use the Variant data type when the data could contain date information, Empty, or a Null. You can also use the Variant data type in place of any fundamental data type to work with data in a more flexible way. If the contents of a Variant variable are digits, they may either be the string representation of the digits or the actual value, depending on the context. For example:

Dim MyVar As Variant

MyVar = 98052

In the preceding example, Myvar contains a numeric representation of the actual value 98052. Arithmetic operators work as expected on Variant variables that contain numeric values or string data that can be interpreted as numbers. If you use the + operator to add MyVar to another Variant containing a number or to a variable of a numeric data type, the result is an arithmetic sum.

The value Empty denotes a Variant variable that hasn't been initialized. A Variant containing Empty is 0 if it is used in a numeric context and a zero-length string if it is used in a string context. Don't confuse Empty with Null. Null indicates that the Variant variable intentionally contains no valid data.


Keywords

The words in the following list are keywords in Actuate Basic: data types, operators, statements, and certain other words that are recognized by the Actuate compiler. Although Actuate Basic, unlike Visual Basic, lets you use names that are the same as function names, it is good programming practice to avoid using these names.

Alias	And	Any
AnyClass	Append	As
Assert	BAnd	Base
Beep	Binary	BNot
BOr	ByVal	Call
Case	ChDir	ChDrive
Class	Clipboard	Close
Compare	Const	CPointer
Currency	Date	Debug
Declare	DefCur	DefDbl
DefInt	DefLng	DefSng
DefStr	Dim	Do
Double	Else	ElseIf
End	Eqv	Err
Error	Exit	Explicit
False	FileCopy	For
FreeLocks	Function	Get
Global	GoTo	If
Imp	Input	Integer
Internal	Is	Kill
Let	Lib	Like
Line	Line Input	Load
Local	Lock	Long
Loop	LSet	Mid
MidB	MkDir	Mod
MsgBox	Name	New
Next	Not	Nothing
Null	Object	Of
On	On Error	Open
Option	Option Base	Option Compare
Option Explicit	Or	Output
Persistent	Preserve	Print
Put	Random	Randomize
Read	ReDim	Rem
Reset	Resume	Return
RmDir	RSet	Seek
Select	Select Case	Set
SetAttr	Shared	Single
Static	Step	Stop
String	Sub	Subclass
Text	Then	Time
To True	Transient	Type
Unload	Unlock	Until
Variant	VarType	Verify
Volatile	Wend	While
Write	XOr


Operators

This section contains information about operators supported by Actuate Basic.

When several operations occur in an expression, each part is evaluated and resolved in a predetermined order, known as operator precedence. Parentheses can be used to override the order of precedence and force parts of an expression to be evaluated before others. Operations within parentheses are always performed before those outside. Within parentheses, normal operator precedence is maintained.

When expressions contain operators from more than one category, arithmetic operators are evaluated first, comparison operators are evaluated next, and logical operators are evaluated last. Within individual categories, operators are evaluated in the following order.

Arithmetic	Comparison	Logical	Bitwise
Exponentiation(^)	Equality(=)	Not	BNot
Negation(-)	Inequality(<>)	And	BAnd
Multiplication and Division(* and /)	Less than(<)	Or	BOr
Integer division(\)	Greater than(>)	XOr
Modulo arithmetic (Mod)	Less than or  Equal to(<=)	Eqv
Addition and  Subtraction (+and -)	Greater than or  Equal to(>=)	Imp
String concatenation(&)	Like	Is
All comparison operators have equal precedence, that is, they are evaluated in the left-to-right order in which they appear.

When multiplication and division or addition and subtraction occur together in an expression, each operation is evaluated as it occurs from left to right.

In precedence, the string concatenation operator (&) falls after all arithmetic operators and before all comparison operators. The Like operator, while equal in precedence to all comparison operators, is actually a pattern-matching operator.


* operator

Example   See also

Multiplies two numbers.

Syntax

<result> = <operand1> * <operand2>

Description

The operands can be any numeric expression.

The data type of <result> is usually the same as that of the most precise operand. The order of precision, from least to most precise, is Integer, Long, Single, Double, Currency. The following are exceptions to this order:

•	When multiplication involves a Single and a Long, the data type of <result> is converted to a Double.

•	When the data type of <result> is a Variant of type 3 (Long), type 4 (Single), or type 7 (Date) that overflows its legal range, <result> is converted to a Variant of type 5 (Double)

•	When the data type of <result> is a Variant of type 2 (Integer) that overflows its legal range, <result> is converted to a Variant of type 3 (Long).

If one or both operands are Null expressions, <result> is a Null. Any operand that is empty (VarType0) is treated as 0.


Example

The following example determines tax on a user-supplied value using the * operator to multiply the user-supplied value by the tax rate of 15%.

Function OnLButtonDblClick ( )

' Declare variables

Dim N As Double, Tax As Double

' Get tax rate

N = InputBox("Enter a number.")

' Calculate tax

Tax = .15 * N

' Display results

MsgBox "Tax is" & Tax

End Function

For information about using the code examples, see Using the code examples.


See also

VarType function


+ operator

Example   Example   See also

Sums two numbers.

Syntax

<result> = <operand1> + <operand 2>

Description

Use the & operator for concatenation to eliminate ambiguity and provide self-documenting code.

When you use the + operator, you may not be able to determine whether addition or string concatenation is to occur. If at least one operand is not a Variant, the following rules apply:

Condition	Result
Both expressions are numeric data types (Integer, Long, Single, Double, or Currency)	Add
Both expressions are strings	Concatenate
One expression is a numeric data type and the other is a Variant (other than a Null)	Add
One expression is a String and the other is a Variant (other than a Null)	Concatenate
One expression is a Variant containing Empty	Return the remaining operand unchanged as <result>
One expression is a numeric data type and the other is a String	A Type Mismatch error occurs
If either operand is a Null (Variant type 1), <result> is a Null.

If both operands are Variant expressions, the VarType of the operands determines the behavior of the + operator in the following way:

Condition	Result
Both Variant expressions are of type 2-7 (numeric data types)	Add
Both Variant expressions are of type 8 (String)	Concatenate
One Variant expression is of type 2-7 (a numeric data type) and the other is of type 8 (String)	Add
For simple arithmetic addition involving only operands of numeric data types, the data type of <result> is usually the same as the most precise operand.

The order of precision, from least to most precise, is Integer, Long, Single, Double, Currency. The following exceptions are to this order:

•	When a Single and a Long are added together, the data type of <result> is converted to a Double.

•	When the data type of <result> is a Variant of type 3 (Long), type 4 (Single), or type 7 (Date) that overflows its legal range, <result> is converted to a Variant of type 5 (Double).

If one or both of the expressions are Null expressions, <result> is a Null. If both operands are Empty, <result> is an Integer. However, if only one operand is Empty, the other operand is returned unchanged as <result>.


Example 1

The following example  adds a user-supplied number to itself and displays the result.

Function OnLButtonDblCLk( )

' Declare variables

Dim N As Double, Result As Double

' Get a number

N = InputBox ("Enter a number.")

'Add numbers

Result = N + N

' Display result

MsgBox N & " plus " & N & " is " & (N+N)

End Function


Example 2

The following example  uses the + operator to concatenate strings.

Function OnLButtonDblClk( )

' Display result

MsgBox "Actuate " + "Developer " + "Workbench "

End Function

For information about using the code examples, see Using the code examples.


See also

VarType function


- operator

Example   Example   See also

Finds the difference between two numbers or indicates the negative value of an operand.

Syntax 1

<result> = <operand1> - <operand2>

Syntax 2

-number

Description

In Syntax 1, the - operator is the arithmetic subtraction operator used to find the difference between two numbers. The operands can be any numeric expression.

The data type of <result> is usually the same as the most precise operand. The order of precision, from least to most precise, is Integer, Long, Single, Double, Currency. The following exceptions are to this order:

•	When subtraction involves a String and a Long, the data type of <result> is converted to a Double.

•	When the data type of <result> is a Variant of type 3 (Long), type 4 (Single), or type 7 (Date) that overflows its legal range, <result> is converted to a Variant of type 5 (Double).

If one or both operands are Null expressions, <result> is a Null. If an operand is Empty (VarType 0), it is treated as if it were 0.


Example 1

The following example  subtracts a user-supplied number from 1000 and displays the result.

Function OnLButtonDblClk( )

' Declare variables

Dim N As Double, Result As Double

' Get a number

N = InputBox ("Enter a number.")

Result = 1000 - N

' Display result

MsgBox "1000 minus " & N & " is " & Result

End Function

For information about using the code examples, see Using the code examples.


Example 2

The following example  uses the - operator to indicate a negative value of a number.

Function OnLButtonDblClk( )

' Declare variables

Dim N As Double, MinusN As Double

' Get a number

N = InputBox("Enter a number")

' Use negation operator

MinusN = -N

' Display result

MsgBox "Negative " & N & " is " & MinusN

End Function

For information about using the code examples, see Using the code examples.


See also

VarType function


/ operator

Example   See also

Divides two numbers and returns a floating-point result.

Syntax

<result> =  <operand1> / <operand2>

Description

The operands can be any numeric expression.

The data type of <result> is always a Double or a Variant of type 5 (Double).

If one or both operands are Null expressions, <result> is a Null. If an operand is Empty (Variant type 0), it is treated as if it were 0.


Example

The following example  divides 100,000 by 7 and returns 14,285.7142857143.

Function OnLButtonDblClk( )

' Declare variable

Dim Result As Double

' Divide numbers

Result = 100000 / 7

' Display results

MsgBox "100000 divided by 7 is " & Result

End Function

For information about using the code examples, see Using the code examples.


See also

VarType function


\ operator

Example

Divides two numbers and returns an integer result.

Syntax

<result> = <operand1> \ <operand2>

Description

The operands can be any numeric expression.

Before division is performed, the operands are rounded to Integer or Long expressions.

The data type <result> is an Integer.  Any fractional portion is truncated. However, if any operand is a Null, <result> is also a Null. Any operand that is Empty (Variant type 0) is treated as 0.


Example

The following example  divides 100,000 by 7 using integer division and returns 14,285.

Function OnLButtonDblClk( )

' Declare variables

Dim Result As Double

' Divide numbers

Result = 100000 \ 7

' Display results

MsgBox "100000 divided by 7 is " & Result

End Function

For information about using the code examples, see Using the code examples.


^ operator

Example   See also

Raises a number to the power of an exponent.

Syntax

<result> = <number> ^ <exponent>

Description

The <number> and <exponent> operands can be any numeric expression. However, the <number> operand can be negative only if <exponent> is an integer value. When more than one exponentiation is performed in a single expression, the ^ operator is evaluated as it is encountered from left to right.

Usually, the data type of <result> is a Double or a Variant (type 5). However, if either <number> or <exponent> is a Null expression, <result> is also a Null.


Example

The following example  squares (n^2) a user-supplied number.

Function OnLButtonDblClk( )

' Declare variables

Dim N As Double, Result As Double

' Get number

N = InputBox("Enter a number.")

' Square number

Result = N ^ 2

' Display result

MsgBox N & " squared is " & Result

End Function

For information about using the code examples, see Using the code examples.


See also

VarType function


Mod operator

Example   See also

Divides two numbers and returns only the remainder.

Syntax

<result> = <operand1> Mod <operand2>

Description

The modulus, or remainder, operator divides <operand1> by <operand2> (rounding floating-point numbers to integers) and returns only the remainder as the <result>. For example, in the expression A = 19 Mod 6.7, A (which is <result>) equals 5. The operands can be any numeric expression.

Usually the data type of <result> is an Integer.  However, <result> is a Null (Variant type 1) if one or both operands are Null expressions. Any operand that is Empty (Variant type 0) is treated as 0.


Example

The following example  uses the Mod operator to determine if a 4-digit year is a leap year.

Sub Form Click ( )

' Declare variables

Dim TestYr, LeapStatus

TestYr = InputBox("Enter a 4-digit year.")

' Divisible by 4?

If TestYr Mod 4 = 0 And TestYr Mod 100 = 0 Then

' Divisible by 400?

If TestYr Mod 400 = 0 Then

LeapStatus = " is a leap year."

Else

LeapStatus = " is a centesimal year, but not a leap year."

End If

ElseIf TestYr Mod 4 = 0 Then

LeapStatus = " is a leap year."

Else

LeapStatus = " is not a leap year."

End If

' Display results

MsgBox TestYr & LeapStatus

End Sub

For information about using the code examples, see Using the code examples.


See also

VarType function


Comparison operators

Example   See also

Compares two expressions.

Syntax

<result> = <expr1> <operator> <expr2>

Description

Comparison operators, also known as relational operators, compare two expressions. The following table contains a list of the comparison operators and the conditions that determine whether <result> is True, False, or Null.

	Meaning	True if	False if	Null if
<	Less than	expr1 < expr2	expr1 >= expr2	expr1 or expr2= Null
<=	Less than or equal to	expr1 <= expr2	expr1 > expr2	expr1 or expr2= Null
>	Greater than	expr1 > expr2	expr1 <= expr2	expr1 or expr2= Null
>=	Greater than or equal to	expr1 >= expr2	expr1 < expr 2	expr1 or expr2= Null
=	Equal to	expr1 = expr2	expr1 <> expr 2	expr1 or expr2= Null
<>	Not equal to	expr1 <> expr2	expr1 = expr2	expr1 or expr2= Null
When comparing two expressions, you may not be able to easily determine whether the expressions are being compared as numbers or as strings. The following table shows how the expressions are compared or what results when either expression is not a Variant.

If	Then
Both expressions are numeric data types (Integer, Long, Single, Double, or Currency)	Perform a numeric comparison
Both expressions are String	Perform a string comparison
One expression is a numeric data type and the other is a Variant of type 2-7 (a numeric data type) or type 8 (String) that can be converted to a number	Perform a numeric comparison
One expression is a numeric data type and the other is a Variant of type 8 (String) that can't be converted to a number	A Type Mismatch error occurs
One expression is a String and the other is a Variant of any type except Null	Perform a string comparison
One expression is Empty and the other is a numeric data type	Perform a numeric comparison, using 0 as the Empty expression
One expression is Empty and the other is a String	Perform a string comparison, using a zero-length string as the Empty expression
One expression is Empty and the other is a Variant of type 8 (String)	A Type Mismatch error occurs
If <expr1> and <expr2> are both Variant expressions, their type determines how they are compared. The following table shows how the expressions are compared or what results from the comparison, depending on the type of the Variant.

If	Then
Both Variant expressions are of type 2-7 (numeric data types)	Perform a numeric comparison
Both Variant expressions are of type 8 (String)	Perform a string comparison
One Variant expression is of type 2-7 (a numeric data type) and the other is of type 8 (String)	The numeric expression is less than the String expression
One Variant expression is Empty and the other is of type 2-7 (a numeric data type)	Perform a numeric comparison, using 0 as the Empty expression
One Variant expression is Empty and the other is of type 8 (String)	Perform a string comparison, using a zero-length string as the Empty expression
Both Variant expressions are Empty	The expressions are equal
Note

If a Currency is compared with a Single or Double, the Single or Double is converted to a Currency. This causes any fractional part of the Single or Double value less than 0.000000001 to be lost and may cause two values to compare as equal when they are not. Such a conversion can also cause an Overflow error if the magnitude of the Single or Double is too large.


Example

The following example  shows a typical use of a comparison operator to evaluate the relationship between variables A and B. An appropriate massage is displayed depending on whether A < B, A = B, or A > B. The other comparison operators can be used in a similar way.

Function OnLButtonDblClk( )

' Declare variables

Dim A, B, Msg

' Get first variable

A = InputBox("Enter a value for A.")

' Get second variable

B = InputBox("Enter a value for B.")

' Evaluate relationship

If A < B Then

' Create correct message

Msg = "A is less than B."

ElseIf A = B Then

Msg = "A is equal to B."

Else

Msg = "A is greater than B."

End If

' Display results

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


See also

VarType function


& operator

Example

Forces string concatenation of two operands.

Syntax

<result> = <operand1> & <operand2>

Description

Whenever an operand is a number, it is converted to a Variant of type 8 (String). The data type of <result> is String if both operands are String expressions; otherwise, <result> is a Variant of type 8 (String). If both operand are Null (type 1), <result> is also Null. However, if only one operand is Null, that operand is treated as a zero-length string when concatenated with the other operand. Any operand that is Empty (type 0) is also treated as a zero-length string.


Example

The following example  uses the & operator to concatenate a numeric variable (Var1), a string literal containing a space, and a string variable (Var2) that contains "trombones".

Function OnLButtonDblClk( )

' Declare variables

Dim Var1, Var2

Var1 = 76

Var2 = "trombones"

' Concatenate and display

MsgBox 76 & " " & Var2

End Function

For information about using the code examples, see Using the code examples.


And operator

Example

Performs logical conjunction on two expressions.

Syntax

<result> = <expr1> And <expr2>

Description

If, and only if, both expressions evaluate True, <result> is True. If either expression evaluates False, <result> is False. The following table illustrates how <result> is determined.

<expr1>	And <expr2>	<result>
True	True	True
True	False	False
True	Null	Null
False	True	False
False	False	False
False	Null	False
Null	True	Null
Null	False	False
Null	Null	Null


Example

The following example  displays a message that depends on the value of variables A, B, and C, assuming that no variable is a Null. If A = 10, B = 8, and C = 6, both expressions evaluate True. Because both expressions are True, the And expression is also True.

Function OnLButtonDblClk( )

' Declare variables

Dim A, B, C, Msg

' Assign values

A = 10: B = 8: C = 6

' Evaluate expressions

If A > B And B > C Then

Msg = "Both expressions are True."

Else

Msg = "One or both expressions are False."

End If

' Display results

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


BAnd operator

Example

Performs a bitwise comparison of identically positioned bits in two numeric expressions.

Syntax

<result> = <expr1> BAnd <expr2>

Description

If, and only if, both expressions evaluate True, <result> is True. If either expression evaluates False, <result> is False. The BAnd operator sets the corresponding bit in <result> according to the following truth table.

Bit in <expr1> is	Bit in <expr2> is	<result>
0	0	0
0	1	0
1	0	0
1	1	1


Example

The following example  displays a message that depends on the value of variables A, B, and C, assuming that no variable is a Null. If A = 10, B = 8, and C = 6, both expressions evaluate True. Because both expressions are True, the BAnd expression is also True.

Function OnLButtonDblClk( )

' Declare variables

Dim A, B, C, Msg

' Assign values

A = 10: B = 8: C = 6

' Evaluate expressions

If A > B BAnd B > C Then

Msg = "Both expressions are True."

Else

Msg = "One or both expressions are False."

End If

' Display results

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


Eqv operator

Example

Performs a logical equivalence on both expressions.

Syntax

<result> = <expr2> Eqv <expr2>

Description

If either expression is a Null, <result> is also Null. When neither expression is a Null, result is determined according to the following table.

<expr1>	<expr2>	<result>
True	True	True
True	False	False
False	True	False
False	False	True


Example

The following example  displays a message that depends on the value of variables A, B, and C, assuming that no variable is a Null. If A = 10, B = 8, and C= 6, both expressions evaluate True. As a result, the Eqv expression also evaluates True.

Function OnLButtonDblClk( )

' Declare variables

Dim A, B, C, Msg

' Assign values

A = 10: B = 8: C = 6

' Evaluate expressions

If A > B Eqv B > C Then

Msg = "Both expressions are True or both are False."

Else

Msg ="One expression is True and one is False."

End If

' Display results

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


Imp operator

Example

Performs a logical implication on two expressions.

Syntax

<result> = <expr1> Imp <expr2>

Description

The following table illustrates how <result> is determined.

<expr1>	<expr2>	<result>
True	True	True
True	False	False
True	Null	Null
False	True	True
False	False	True
False	Null	True
Null	True	True
Null	False	Null
Null	Null	Null


Example

The following example  displays a message that depends on the value of variables A, B, and C, assuming that no variable is a Null. If A = 10, B = 8, and C= 6, both expressions evaluate True. Because both are True, the Imp expression is also True.

Function OnLButtonDblClk( )

' Declare variables

Dim A, B, C, Msg

' Assign values

A = 10: B = 8: C = 6

If A > B Imp B > C Then

Msg = "The left expression implies the right expression."

Else

Msg = "The left expression doesn't imply the right expression."

End If

' Display results

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


Not operator

Example

Performs logical negation on an expression.

Syntax

<result> = Not <expr>

Description

The following table illustrates how <result> is determined.

<expr>	<result>
True	False
False	True
Null	Null
In addition, the Not operator inverts the bit values of any variable and sets the corresponding bit in <result> according to the following truth table.

Bit in <expr>	Bit in <result>
0	1
1	0
If an integer variable has the value 0 (False), the variable becomes 1 (True); if it has the value of 1 it becomes 0.


Example

The following example  displays a message that depends on the value of variables A, B, and C, assuming that no variable is a Null. If A = 10, B = 8, and C= 6, the Not expression evaluates True because A is not equal to B.

Function OnLButtonDblClk( )

' Declare variables

Dim A, B, Msg

' Assign values

A = 10: B = 8

' Evaluate expression

If Not A = B Then

Msg = "A and B aren't equal."

Else

Msg = "A and B are equal."

End If

' Display results

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


BNot operator

Example

Inverts the bit values of any variable.

Syntax

<result> = BNot <expr>

Description

The BNot operator sets the corresponding bit in <result> according to the following truth table.

Bit in <expr>	Bit in <result>
0	1
1	0
If an integer variable has the value 0 (False), the variable becomes 1 (True); if it has the value of 1, it becomes 0.


Example

The following example displays a message that depends on the value of variables A, B, and C, assuming that no variable is a Null. If A = 10, B = 8, and C= 6, the BNot expression evaluates True because A is not equal to B.

Function OnLButtonDblClk( )

' Declare variables

Dim A, B, Msg

' Assign values

A = 10: B = 8

' Evaluate expression

If BNot A = B Then

Msg = "A and B aren't equal."

Else

Msg = "A and B are equal."

End If

' Display results

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


Or operator

Example

Performs a logical disjunction on two expressions.

Syntax

<result> = <expr1> Or <expr2>

Description

If either or both expressions evaluate True, <result> is True. The following table illustrates how <result> is determined.

<expr1>	<expr2>	<result>
True	True	True
True	False	True
True	Null	True
False	True	True
False	False	False
False	Null	Null
Null	True	True
Null	False	Null
Null	Null	Null
The Or operator performs a bit-wise comparison of identically positioned bits in two numeric expressions and sets the corresponding bit in <result> according to the following truth table.

Bit in <expr1>	Bit in <expr2>	<result>
0	0	0
0	1	1
1	0	1
1	1	1


Example

The following example  displays a message that depends on the value of variables A, B, and C, assuming that no variable is a Null. If A = 10, B = 8, and C= 6, the left expression is True and the right expression is False. Because at least one comparison expression is True, the Or expression evaluates True.

Function OnLButtonDblClk( )

 'Declare variables

Dim A, B, C, Msg

' Assign values

A = 10: B = 8: C = 11

' Evaluate expression

If A > B Or B > C Then

Msg = "One or both comparison expressions are True."

Else

Msg = "Both comparison expressions are False."

End If

' Display results

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


BOr operator

Example

Performs a bitwise comparison of identically positioned bits in two numeric expressions.

Syntax

<result> = <expr1> BOr <expr2>

Description

The BOr operator sets the corresponding bit in <result> according to the following truth table

Bit in <expr1>	Bit in <expr2>	<result>
0	0	0
0	1	1
1	0	1
1	1	1


Example

The following example  displays a message that depends on the value of variables A, B, and C, assuming that no variable is a Null. If A = 10, B = 8, and C= 6, the left expression is True and the right expression is False. Because at least one comparison expression is True, the BOr expression evaluates True.

Function OnLButtonDblClk( )

' Declare variables

Dim A, B, C, Msg

' Assign values

A = 10: B = 8: C = 11

' Evaluate expression

If A > B BOr B > C Then

Msg = "One or both comparison expressions are True."

Else

Msg = "Both comparison expressions are False."

End If

' Display results

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


XOr operator

Example

Performs a logical exclusion on two expressions.

Syntax

<result> = <expr1> Xor <expr2>

Description

If only one of the expressions evaluates True, <result> is True. If either expression is a Null <result> is also a Null. When neither expression is a Null, <result> is determined according to the following table.

<expr1>	<expr2>	<result>
True	True	False
True	False	True
False	True	True
False	False	False


Example

The following example  displays a message that depends on the value of variables A, B, and C, assuming that no variable is a Null. If A = 6, B = 8, and C= 10, both expressions evaluate False. Because both are False, the Xor expression is also False.

Function OnLButtonDblClk( )

' Declare variables

Dim A, B, C, Msg

' Assign values

A= 6: B = 8: C = 10

' Evaluate expression

If A > B Xor B = C Then

Msg = "Only one comparison expression is True, not Both."

Else

Msg = "Both comparison expressions are True or both are False."

End If

' Display results

MsgBox Msg

End Function

For information about using the code examples, see Using the code examples.


Is operator

Example   See also

Compares two object reference variables.

Syntax

<result> = <objref1> Is <objref2>

Description

If <objref1> and <objref2> both refer to the same object, <result> is True; if they do not, <result> is False. Two variables can be made to refer to the same object in several ways:

In the following example, A has been set to refer to the same object as B.

Set A = B

The following example makes A and B refer to the same object as C:

Set A = C

Set B = C


Example

The following example uses the Is operator to evaluate whether two object reference values refer to the same control.

Function OnLButtonDblClk( )

Dim MLabel1 As AcLabelControl

Dim MLabel2 As AcLabelControl

Dim Msg As String, LoopCount As Integer

'Instantiate two new, separate objects

Set MLabel1 = New AcLabelControl

Set MLabel2 = New AcLabelControl

'Loop twice through the Is evaluation

For LoopCount = 1 to 2

If MLabel1 Is MLabel2 Then

MsgBox "Now MLabel1 and MLabel2 DO refer to the same object."

Else

MsgBox "MLabel1 and MLabel2 do NOT yet refer to the same object."

'Before the next Is evaluation loop, force identity.

Set MLabel1 = MLabel2

End If

Next LoopCount

End Function

For information about using the code examples, see Using the code examples.


See also

Set statement


Like operator

Example   See also

Compares two string expressions.

Syntax

<result> = <exprs> Like <pattern>

Description

If <exprs> matches <pattern>, <result> is True; if there is no match, <result> is False; and if either <exprs> or <pattern> is a Null, <result> is also a Null. The case sensitivity and character sort order of the Like operator depend on the setting of the Option Compare statement.

Unless other wise specified, the default string-comparison method for each module is Option Compare Binary; that is, string comparisons are case sensitive.

Built-in pattern matching provides a versatile tool for string comparisons. The pattern-matching feature allows you to use wildcard characters, such as those recognized by the operating system, to match strings. The wildcard characters and what they match are shown in the following table.

Character(s) in <pattern>	Matches in <exprs>
?	Any single character
*	Zero or more characters
#	Any single digit (0-9)
[character list]	Any single character in <character list>
[!character list]	Any single character not in <character list>
A group of one or more characters <character list> enclosed in brackets ([ ]) can be used to match any single character in <exprs> and can include almost any characters in the ANSI character set, including digits. In fact, the special characters left bracket ([ ), question mark (?), number sign (#), and asterisk (*) can be used to match themselves directly only by enclosing them in brackets. The right bracket ( ]) cannot be used within a group to match itself, but it can be used outside a group as an individual character.

In addition to a simple list of characters enclosed in brackets, <character list> can specify a range of characters by using a hyphen (-) to separate the upper and lower bounds of the range. For example, [A-Z] in <pattern> results in a match if the corresponding character position in <exprs> contains any of the uppercase letters in the range A through Z. Multiple ranges are included within the brackets without any delimiting. For example, [a-zA-Z0-9] matches any alphanumeric character.

Other important rules for pattern matching include the following:

•	An exclamation point (!) at the beginning of <character list> means that a made if any character except the ones in <character list> are found in <exprs>. When used outside brackets, the exclamation point matches itself.

•	The hyphen (-) can appear either at the beginning (after an exclamation mark if one is used) or at the end of <character list> to match itself. In any other location, the hyphen is used to identify a range of ANSI characters.

•	When a range of characters is specified, they must appear in ascending order (low to high).

•	The character sequence [ ] is ignored; it is evaluated as a zero-length string.


Example

The following example shows what happens when you mix and match various wildcard characters in conjunction with the Like operator.

Function OnLButtonDblClk( )

'Returns True (1)

MsgBox "PB123" Like "P[A-F]###"

'Returns False (0)

MsgBox "PG123" Like "P[A-F]###"

'Returns True

MsgBox "PG123" Like "P[!A-F]###"

'Returns False

MsgBox "PB12x" Like "P[A-F]###"

'Returns True

MsgBox "PB123" Like "?B???"

'Returns False

MsgBox "PB123" Like "?B??"

'Returns True

MsgBox "PB123" Like "P*"

'Returns False

MsgBox "PB123" Like "*P"

'Returns True

MsgBox "PB123" Like "*P*"

'Returns False

MsgBox "F" Like "[!A-Z]"

'Returns True

MsgBox "F" Like "[A-Z]"

'Returns False

MsgBox "aMxb" Like "a[L-P]#[!c-e]"

'Returns True

MsgBox "aM5b" Like "a[L-P]#[!c-e]"

'Returns False

MsgBox "aM5b" Like "a[L-P][!c-e]"

'Returns True

MsgBox "abracadabra12Z%$a" Like "a*a"

'Returns False

MsgBox "CAT123khg" Like "B?T*"

End Function

For information about using the code examples, see Using the code examples.


See also

InStr function

StrComp function

Option Compare statement


Trigonometric identities

This section contains information about trigonometric formulas supported by Actuate Basic. Actuate Basic supports only a few built-in trigonometric functions: Sin, Cos, Tan and Atn. To use trigonometric functions other than these, you need to derive and write the functions yourself. To do so, use the following table, which shows the most commonly used trigonometric identities.

Name of formula	Formula
Secant	Sec(X) = 1 / Cos(X)
Cosecant	Cosec(X) = 1 / Sin(X)
Cotangent	Cotan(X) = 1 / Tan(X)
Inverse Sine	Arcsin(X) = Atn(X / Sqr(-X * X + 1))
Inverse Cosine	Arccos(X) = Atn(-X / Sqr(-X * X + 1)) + 2 * Atn(1)
Inverse Cotangent	Arccotan(X) = -Atn(X) + 2 * Atn(1)
Hyperbolic Sine	HSin(X) = (Exp(X) - Exp(-X)) / 2
Hyperbolic Cosine	HCos(X) = (Exp(X) + Exp(-X)) / 2
Hyperbolic Tangent	HTan(X) = (Exp(X) - Exp(-X)) / (Exp(X) + Exp(-X))
Hyperbolic Secant	HSec(X) = 2 / (Exp(X) + Exp(-X))
Hyperbolic Cosecant	HCosec(X) = 2 / (Exp(X) - Exp(-X))
Hyperbolic Cotangent	HCotan(X) = (Exp(X) + Exp(-X)) / (Exp(X) - Exp(-X))
Inverse Hyperbolic Sine	HArcsin(X) = Log(X + Sqr(X * X + 1))
Inverse Hyperbolic Cosine	HArccos(X) = Log(X + Sqr(X * X - 1))
Inverse Hyperbolic Tangent	HArctan(X) = Log((1 + X) / (1 - X)) / 2
Inverse Hyperbolic Secant	HArcsec(X) = Log((Sqr(-X * X + 1) + 1) / X)
Inverse Hyperbolic Cosecant	HArccosec(X) = Log((Sgn(X) * Sqr(X * X + 1) +1) / X)
Inverse Hyperbolic Cotangent	HArccotan(X) = Log((X + 1) / (X - 1)) / 2
Logarithm to base N	LogN(X) = Log(X) / Log(N)