standard basic language

Standard BASIC ReferenceElements belonging to the standard BASIC language are referred to as keywords. This chapter describes theBASIC keywords. To find a keyword:

By function, see BASIC Command Overview In alphabetical order, see A to Z Reference

BASIC Command Overview

The BASIC commands are listed in the following function groups:

Operators Constants and special keywords Math and numerical operators Array handling System Miscellaneous Program control Variable control Character and string manipulation File handling Date and time Business calculations Dynamic Data Exchange (DDE), Windows platforms only

Operators

Keyword Used To

& Concatenate two strings

* Multiply two values

+ Add two numeric values or concatenate two strings.

- Subtract one value from another.

/ Divide one value by another.

< Determine if one value or string is less than another.

Determine if one value or string is greater than another.

>= Determine if one value or string is greater than or equal to another.

\ Perform integer division on two values.

Constants and special keywords

Math and numerical operators

^ Raise a value to a power.

And Perform a logical or bitwise AND.

Eqv Perform a logical or bitwise equivalence.

Imp Perform a logical or bitwise implication.

Is Determine if two object variables refer to the same object.

Like Compare a string with a pattern.

Mod Calculate a remainder.

Not Reverse the logical value or perform a bitwise NOT.

Or Perform a logical or bitwise OR.

Xor Perform a logical or bitwise exclusive OR.

Keyword Used To

' Denote a comment (makes the interpreter skip the rest of the line.)

_ Continue a line.

False (constant) Represent the value of zero or an untrue situation.

PI (constant) Represent the value of pi, 3.14159...

REM (statement) Make the interpreter skip the entire line.

True (constant) Represent the value of one or a valid situation.

Keyword Used to

Abs (function) Calculate the absolute value of a number.

Atn (function) Calculate the arctangent of a value.

CDbl (function) Calculate the double-precision equivalent of an expression.

CInt (function) Convert an expression to an integer.

CLng (function) Calculate the long version of a value.

Cos (function) Calculate the cosine of an angle.

CSng (function) Calculate the single-precision version of a value.

Array handling

System

Exp (function) Raise e to the power of a value.

Fix (function) Calculate the integer portion of a value.

Int (function) Calculate the integer portion of a value. Int also truncates numbers in a negativedirection.

Log (function) Calculate the natural logarithm of a value.

Random (function) Generate a random number within the range of two values.

Randomize(statement) Initialize the random number generator with a new seed.

Rnd (function) Generate a random number between 0 to 1.

Sgn (function) Determine if a number is less than, equal to, or greater than zero.

Sin (function) Calculate the sine of an angle.

Sqr (function) Calculate the square root of a value.

Tan (function) Calculate the tangent of an angle.

Keyword Used to

ArrayDims (function) Return the number of dimensions in an array.

ArraySort (statement) Sort a single-dimensional array.

Erase (statement) Eliminate the members of an array.

LBound (function) Determine the lower bound for a dimension of an array.

Option Base(statement) Set the default lower bound for all array declarations.

ReDim (statement) Redimension an array, specifying new upper & lower bounds for eachdimension.

UBound (function) Determine the upper bound for a dimension of an array.

Keyword Used to

Basic.Capability% (method) Determine the capabilities of the host machine.

Basic.Eoln$ (property) Determine the EOL character sequence of the host machine.

Miscellaneous

Program control

Basic.FreeMemory (property) Determine available memory in BASIC's data space.

Basic.OS (property) Determine the host machine operating environment.

Basic.PathSeparator$(property) Determine the file system path separator used by the host machine.

Err (function) Obtain the value of the run-time error.

Err (statement) Set the value of the current run-time error (for use with the Errorstatement.)

Error (statement) Induce a particular run-time error.

Error$ (function) Obtain the text corresponding to a run-time error.

Keyword Used to

Beep (statement) Cause the system to beep once.

Erl (function) Return 0 (for compatibility with other versions of BASIC).

Print (statement) Print text to an output device.

Sleep (statement) Pause for a specified length of time.

Spc (function) Print a specified number of spaces to an output device.

Tab (function) Print the number of spaces necessary to reach a specified column.

Keyword Used to

Call (statement) Transfer program control to a subroutine.

Declare (statement) Create a prototype for a routine that occurs later in the source module.

Do...Loop (statement) Repeat a block of statements while or until a condition is true.

End (statement) Terminate execution of the current macro.

Exit Do (statement) Terminate a Do...Loop statement.

Exit For (statement) Terminate a For...Next statement.

Exit Function (statement) Terminate execution of a function.

Exit Sub (statement) Terminate execution of a subroutine.

For...Next (statement) Repeat a block of statements a specific number of times.

Variable control

Character and string manipulation

Function...End Function(statement) Define a user function.

GoSub (statement) Transfer program control to a specific point with the intent to return to thestatement following.

Goto (statement) Unconditionally transfer program control to a specific point.

If...Then...Else (statement) Conditionally execute a block of statements.

Main (statement) Define the subroutine that initially receives control when macro executioncommences.

On Error (statement) Define the action taken when a run-time error occurs.

Resume (statement) End the current error handler and continue execution.

Return (statement) Transfer program control to the statement following the most recentGoSub.

Select...Case (statement) Execute a block of statements based on the value of an expression.

Stop (statement) Suspend execution of the macro and break into the debugger.

Sub...End Sub (statement) Define a user subroutine.

While...Wend (statement) Repeat a block of statements while a condition is true.

Keyword Used to

Command$(function)

Obtain a string containing the arguments passed to the macro from the command linewhen the macro was started.

Const (statement) Declare a constant.

DEF... (statement) Establish default variable types.

Dim (statement) Declare a list of local variables and their corresponding types and sizes.

Environ$(function) Obtain the value of an environment variable.

Global (statement) Declare global or public variables.

Let (statement) Assign the result of an expression to a variable.

Private (statement) Declare private variables.

Public (statement) Declare public or global variables.

Set (statement) Assign a value to an object variable.

Type (statement) Define a structure that can be subsequently used by the Dim statement to declare avariable of that type.

Keyword Used to

Asc (function) Obtain the numeric code for a character.

Chr$ (function) Obtain the character for a numeric code.

CStr (function) Convert an expression into a string without leaving white space.

Format$ (function) Format a string.

Hex$ (function) Convert a numeric value into a hexadecimal string.

InStr (function) Obtain the position of a string within another string.

Item$ (function) Obtain items from within a formatted list.

ItemCount (function) Determine how many items are in a formatted list.

LCase$ (function) Convert a string to lower case.

Left$ (function) Obtain a specified number of characters from the left end of a string.

Len (function) Determine the length of a string or the number of bytes in a nonstringvariable.

Line$ (function) Obtain one or more lines from a text buffer.

LineCount (function) Determine the number of lines in a text buffer.

LSet (statement) Copy a string padding with spaces at the end or copy a structure.

LTrim$ (function) Remove leading spaces from a string.

Mid$ (function) Obtain a substring from a string.

Mid$ (statement) Replace a substring of a string.

Null (function) A string that contains no characters and requires no storage.

Oct$ (function) Convert a numeric value into an octal string.

Option Compare(statement) Establish whether string comparisons are to be case sensitive or not.

Right$ (function) Obtain a specified number of characters from the right end of a string.

RSet (statement) Copy a string padding with spaces at the beginning.

RTrim$ (function) Remove trailing spaces from a string.

Space$ (function) Create a string containing a specified number of spaces.

Str$ (function) Convert an expression into a string.

StrComp (function) Compare two strings.

String$ (function) Create a string containing a specified number of a specific character.

Trim$ (function) Remove both leading and trailing spaces from a string.

UCase$ (function) Convert a string to upper case.

File handling

Val (function) Convert a string into a number.

Word$ (function) Obtain one or more complete words from a string.

WordCount (function) Count the number of words in a string.

Keyword Used to

Close (statement) Close opened files.

Dir$ (function) Obtain a list of the files in a directory.

ebArchive (constant) Archived file attribute.

ebDirectory (constant) Directory attribute.

ebHidden (constant) Hidden file attribute.

ebNone (constant) Select files with no attributes.

ebNormal (constant) Select Normal files -- archive, volume, read only, or no attribute.

ebReadOnly (constant) Read only file attribute.

ebSystem (constant) System file attribute.

ebVolume (constant) Volume attribute.

Eof (function) Determine if the end of a file has been reached.

FileAttr (function) Obtain the file mode or file handle.

FileCopy (statement) Copy a file.

FileDateTime (function) Obtain a file's date and time.

FileDirs (statement) Fill an array with directory names from disk.

FileExists (function) Determine if a file exists.

FileLen (function) Determine the length of a file in bytes.

FileList (statement) Fill an array with filenames from disk.

FileParse$ (function) Extract a portion of a filename from a filename string.

FreeFile (function) Obtain the next available file number for use with the Open command.

Get (statement) Retrieve data from a random or binary file.

GetAttr (function) Obtain a file's attributes.

Input # (statement) Retrieve formatted text from a file.

Input$ (function) Retrieve text from a sequential file.

Kill (statement) Delete file(s).

Date and time

Line Input # (statement) Retrieve an entire line of text from a file.

Loc (function) Determine the position of a file's file pointer.

Lock (statement) Prevent a section of a file from being accessed by other processes.

Lof (function) Determine the length of a file.

MkDir (statement) Create a new directory on the disk.

Name (statement) Rename a file.

Open (function) Open a file for read and/or write operations.

Print# (statement) Write text to a sequential file.

Put (statement) Write data to a random or binary file.

Reset (statement) Close all open files.

RmDir (statement) Delete a directory.

Seek (function) Obtain the position of the file pointer.

Seek (statement) Set the position of the file pointer.

SetAttr (statement) Change a file's attributes.

UnLock (statement) Restore access by other processes to a locked portion of a file.

Width# (statement) Specify the line width for a sequential file.

Write # (statement) Write formatted text to a sequential file.

Keyword Used to

Date$ (function) Obtain the current system date as a 10-character string.

Date$ (statement) Set the system date.

DateAdd (function) Add a time interval to a date.

DateDiff (function) Determines the number of time intervals between two dates.

DatePart (function) Obtain a portion of a date/time expression.

DateSerial (function) Convert a specific date to "days since December 30, 1899" format.

DateValue (function) Convert a date from a string to a double-precision value.

Day (function) Obtain the day of the month from a date value.

Hour (function) Obtain the hour of the day (24 hour format) from a time value.

Minute (function) Obtain the minute of the hour from a time value.

Month (function) Obtain the month of the year from a date value.

Business calculations

Dynamic Data Exchange (DDE), Windows platforms only

Now (function) Obtain the current date and time in "days since December 30, 1899" format.

Second (function) Obtain the second of the minute from a time value.

Time$ (function) Obtain the current time as an 8-character string.

Time$ (statement) Set the system time.

Timer (function) Obtain the number of seconds since midnight.

TimeSerial (function) Convert a specific time to "days since December 30, 1899" format.

TimeValue (function) Convert a time from a string to a value.

Weekday (function) Obtain the day of the week, from a date value.

Year (function) Obtain the year from a date value.

Keyword Used to

DDB (function) Calculate the depreciation of an asset using the double-declining balance method.

Fv (function) Calculate the future value of an annuity.

IPmt (function) Calculate the interest payments for an annuity.

IRR (function) Calculate the internal rate of return for a series of payments and receipts.

MIRR (function) Calculate the modified internal rate of return for a series of payments and receipts.

NPer (function) Calculate the number of periods of an annuity.

Npv (function) Calculate the net present value of an annuity.

Pmt (function) Calculate the payments for an annuity.

PPmt (function) Calculate the principal payment for a given period of an annuity.

Pv (function) Calculate the present value of an annuity.

Rate (function) Calculate the rate of interest for each period of an annuity.

Sln (function) Calculate the straight-line depreciation of an asset.

SYD (function) Calculate the sum of year's digits depreciation of an asset.

Keyword Used to

DDEExecute Send an execute message to another application.

A to Z Reference

This section contains a complete, alphabetical reference to all commands in the standard BASIC language.When syntax is described, the following notations are used:

&

string_expression1 & string_expression2

Descr. Returns the concatenation of string_expression1 and string_expression2.

Adds string_expression2 to the end of string_expression1 and returns a string with a length that is the sumof the lengths of string_expression1 and string_expression2. This operator can be used interchangeablywith the plus (+) operator when used with string operands and is provided for clarity of code.

Example:

DDEInitiate Initialize a DDE link to another application.

DDEPoke Set the value of a data item in another application.

DDERequest Get a string value associated with a data item.

DDESend Initiate a conversation with a DDE server application.

DDETerminate Close a DDE channel.

DDETerminateAll Close all DDE channels.

DDETimeOut Set the timeout for DDE command completion.

Notation Description

keyword Elements belonging to the standard BASIC language, referred to in this manual askeywords, appear in the typeface shown to the left.

variable Items that are to be replaced with information that you supply appear in italics. The typeof replacement is indicated in the following description.

text$ The presence of a type-declaration character following a parameter signifies that theparameter must be a variable of that type or an expression that evaluates to that type.

rnd#

A function's return type is indicated by a type-declaration character. This is strictlyinformative and does not mean that the function must be accompanied by that type-declaration character.Functions that return strings are an exception to this rule. In their case, the $ character isrequired.

[parameter%] Square brackets indicate that the enclosed items are optional.

{Input |Binary}

Braces indicate that you must choose one of the enclosed items, which are separated by avertical bar.

start% Toend%

Words that must appear as part of a statement's syntax are shown without type-declaration characters (for example, To).

Sub Main()

'Assign a concatenated string to variable s$ and a string to s2$,'then concatenate the two variables and display in a dialog box.s$ = "This string" & " is concatenated"s2$ = " with the & operator"MbeMessageBox s$ & s2$

End Sub

'

'text

Descr. Causes the compiler to skip all characters between this character and the end of the current line. Thisis very useful for commenting your code to make it more readable.

Example:

Const crlf = Chr$(13) + Chr$(10)

Sub Main()'This whole line is treated as a comment.i$ = "Strings" 'This is a valid assignment with a comment.This line will cause an error (the apostrophe is missing).

End Sub

*

expression1 * expression2

Descr. Returns the product of expression1 and expression2. The operands can be expressions of any numericdata type.

Example:

Sub Main()

'This example assigns values to two variables and their product to'a third variable, then displays the product of S * T.S# = 123.55T# = 2.55U# = S * TMbeMessageBox Str$(S * T)

End Sub

+

expression1 + expression2

Descr. If expression1 and expression2 are both numeric, then this operator returns the sum of expression1and expression2. If both expressions are strings, then this operator returns a new string representing theconcatenation of expression1 and expression2. Mixed string and numeric operands are invalid. For string

operands, the plus (+) is interchangeable with the & operator. (See & [operator].)

Example:

Sub Main()

'This example assigns string and numeric variable values and'then uses the + operator to concatenate the strings and form the'sums of numeric variables.i$ = "Strings" + " can be concatenated"j% = 120 + 5 'addition of numeric literalsk# = j% + 2.7 'addition of numeric variableMbeMessageBox i$ + Str$(j%) + Str$(k#)

End Sub

-

expression1 - expression2

Descr. Returns the difference between expression1 and expression2.

Example:

Sub Main()

'This example assigns values to two numeric variables and their'difference to a third variable, then displays the result.I% = 100J# = 22.55K# = I - JMbeMessageBox "The difference is: " + Str$(K#)

End Sub

/

expression1 / expression2

Descr. Returns the quotient of expression1 and expression2.

Example:

Sub Main()

'This example assigns values to two variables and their quotient to a'third variable, then displays the result.I% = 100J# = 22.55K# = I / JMbeMessageBox "The quotient of I/J is: " + Str$(K#)

End Sub

expression1 < expression2

Descr. Returns TRUE if expression1 is less than expression2; otherwise, returns FALSE. If both expressionsare strings, the < operator performs a case-sensitive comparison between the two string expressions,returning TRUE if expression1 is less than expression2.

Lowercase characters in a string sort higher than uppercase characters, so a comparison of à' and À'would indicate that À' is less than à'.

Example:

Sub Main()

'Test two literals and display the result.If 5 < 2 Then

MbeMessageBox "Five is less than Two"Else

MbeMessageBox "Five is not less than Two"End If'Test two strings and display the result.If "This string expression" < "That string" Then

MbeMessageBox "This is less than That"Else

MbeMessageBox "That is less than This"End If

End Sub

expression1 expression2

Descr. Returns TRUE if expression1 is not equal to expression2; otherwise returns FALSE. If the twoexpressions are strings, the operator performs a case-sensitive comparison between the two expressions,returning TRUE if expression1 is not equal to expression2.

Lowercase characters in a string sort higher than uppercase characters, so a comparison of à' and À'would indicate that À' is less than à'.

Example:

Sub Main()

'Test two literals and display the result.If 5 2 Then

MbeMessageBox "Five is not equal to Two"Else

MbeMessageBox "Five is equal to Two"End If'Test two strings and display the result.If "This string" "That string" Then

MbeMessageBox "This is not equal to That"Else

MbeMessageBox "The strings are equal"End If

End Sub

=

expression1 = expression2

Descr. Returns TRUE if expression1 is equal to expression2; otherwise returns FALSE. If the two expressionsare strings, the = operator performs a case-sensitive comparison between the two expressions, returningTRUE if expression1 is equal to expression2. Strings of different lengths are never equal to one another.

This operator is also used for assignment of values to variables. It operates as a logical equivalency operatoronly in a logical comparison context.

Example:

Sub Main()

'Assignment of values: the variable S is assigned a value of 100.22.S# = 100.22'Logical equivalence: the value of S is compared to 150.99.If S = 150.99 Then

MbeMessageBox "The value of S is 150.99"Else

MbeMessageBox "The value of S is not 150.99"End If

End Sub

>

expression1 > expression2

Descr. Returns TRUE if expression1 is greater than expression2; otherwise returns FALSE. If the twoexpressions are strings, the > operator performs a case-sensitive comparison between the two expressions,returning TRUE if expression1 is greater than expression2.

Example:

Sub Main()

'Test two literals and display the result.If 5 > 2 Then

MbeMessageBox "Five is greater than Two"Else

MbeMessageBox "Five is less than or equal to Two"End If'Test two strings and display the result.If "This string" > "That string" Then

MbeMessageBox "This is greater than That"Else

MbeMessageBox "That is less than or equal to This"End If

End Sub

>=

expression1 >= expression2

Descr. Returns TRUE if expression1 is greater than or equal to expression2; otherwise returns FALSE. If thetwo expressions are strings, the >= operator performs a case-sensitive comparison between the twoexpressions, returning TRUE if expression1 is greater than or equal to expression2.

Example:

Sub Main()

'Test two literals and display the result.If 5 >= 2 Then

MbeMessageBox "Five is greater than or equal to Two"Else

MbeMessageBox "Five is less than Two"End If'Test two strings and display the result.If "This string" >= "That string" Then

MbeMessageBox "This is greater than or equal to That"Else

MbeMessageBox "That is less than This"End If

End Sub

\

expression1 \ expression2

Descr. Returns the integer division of expression1 and expression2.

This operator operates by rounding expression1 and expression2 prior to division. The integer part of theresult is then returned as a nonfractional number.

Example:

Sub Main()

'Assign the quotient of two literals to a variable and display the'result.s% = 100.99 \ 2.6MbeMessageBox "Integer divide of 100.99 \ 2.6 is: " & Str$(s)

End Sub

^

expression1 ^ expression2

Descr. Returns expression1 raised to the power specified in expression2. Fractional and negative exponentsare allowed.

The following are special cases:

It is important to note that raising a number to a negative exponent produces a fractional result (either aDouble or a Single). In the statement a% = b%^c%, the variables b and c are first promoted to Doubles,then the power operation is applied, and finally the result converted to an Integer (rounding, if necessary)and stored in a.

Example:

Sub Main()

s# = 2 ^ 5 'Returns 2 to the 5th power.r# = 16 ^ .5 'Returns the square root of 16.MbeMessageBox "Two to the 5th power is: " & Str$(s)

End Sub

_

s$ = "This is a very long line that I want to split " + _"onto two lines"

Descr. The `_' character is the line-continuation character.

This character allows you to split a single BASIC statement onto more than one line.

Special Case Value

n^0 1

0^-n undefined

0^+n 0

1^n 1

The line-continuation character cannot be used within strings and must be preceded by white space (either aspace or a tab).

Example:


Sub Main()'The line-continuation operator is useful when concatenating long'strings.Msg$ = "This line is a line of text that" + crlf + "extends beyond " _

+ "borders of the editor" + crlf + "so it is split into " _+ "multiple lines"

'It is also useful for separating and continuing long calculation'lines:b# = .124a# = .223S# = ( (((Sin(b) ^ 2) + (Cos(a) ^ 2)) ^ .5) / _

(((Sin(a) ^ 2) + (Cos(b) ^ 2)) ^ .5) ) * 2.00MbeMessageBox Msg + crlf + "The value of S is: " + Str$(S)

End Sub

Abs

Abs%(number%)Abs&(number&)Abs!(number!)Abs#(number#)

Descr. Returns the absolute value of a given number.

When Integer variables are assigned the absolute value of real numbers, the real number is rounded first,and the absolute value of the rounded number is returned.

Example:

Sub Main()

'Assign absolute values to variables of 4 types and display the result.S1% = Abs(- 10.55)S2& = Abs(- 10.55)S3! = Abs(- 10.55)S4# = Abs(- 10.55)MbeMessageBox Str$(S1) + Str$(S2) + Str$(S3) + Str$(S4)

End Sub

And

expression1 And expression2

Descr. Returns TRUE if both expression1 and expression2 are TRUE. If either expression is FALSE, then theAnd operator returns FALSE.

If the two expressions are numeric, then the result is the bitwise And of the two arguments.

If either of the two operands is a floating-point number, then the two operands are first converted to Longs,then a bitwise And is performed.

Example:

Sub Main()

N1 = 1001N2 = 1000B1 = TrueB2 = False'Perform a numeric bitwise And operation and store the result in N3.N3 = N1 And N2'Perform a logical And comparing B1 and B2 and display the result.If B1 And B2 Then

MbeMessageBox "B1 and B2 is True; N3 is: " + Str$(N3)Else

MbeMessageBox "B1 and B2 is False; N3 is: " + Str$(N3)End If

End Sub

ArrayDims

ArrayDims%(arrayvariable)

Descr. Returns the number of dimensions of a given array.

This function can be used to determine whether a given array contains any elements if the array is initiallydimensioned with null dimensions and then redimensioned by another function, such as the FileListfunction, as shown in the following example.

Example:

Sub Main()

'Allocate an empty (null-dimensioned)'array; fill the array with a list of'filenames, which resizes the array; then test the array dimension and'display an appropriate message.Dim f$()FileList f$,"C:\*.BAT"If ArrayDims(f$) = 0 Then

MbeMessageBox "The array is empty"Else

MbeMessageBox "The array size is: " + Str$(ArrayDims(F$))End If

End Sub

ArraySort

ArraySort s$()ArraySort a%()ArraySort a&()ArraySort a!()ArraySort a#()

Descr. Sorts a single-dimensioned array. If a string array is specified, then the routine sorts alphabetically inascending order (using case-sensitive string comparisons). If a numeric array is specified, the ArraySortstatement sorts smaller numbers to the lowest array index locations.

A run-time error is generated if you specify an array with more than one dimension.

Example:

Sub Main()

'Dimension an array and fill it with filenames using FileList,'then sort the array and display it.Dim F$()FileList f$,"C:\*.*"ArraySort f$result = MbeSelectBox% ("Choose a file", f$)

End Sub

Asc

Asc%(text$)

Descr. Returns the numeric code for the first character of the given string.

The return value is an Integer between 0 and 255.

Example:

Sub Main()

s$ = "ABC"Dim a%(3)'Fill the array with the ASCII values of the string s components and'display the result.For i = 1 To 3

a%(i) = Asc(Mid$(s$,i,1))Next iMbeMessageBox Str$(a%(1)) + Str$(a%(2)) + Str$(a%(3))

End Sub

Atn

atn#(number#)

Descr. Returns the angle (in radians) whose tangent is number.

Pi (3.1415926536) radians = 180 degrees.

One radian = 57.2957795131 degrees.

One degree = .0174532925 radians.

Example:

Sub Main()

'Find the angle whose tangent is 1 (45 degrees) and display the result.a# = Atn(1.00)MbeMessageBox "1.00 is the tangent of " + Str$(a#) +

" radians (45 degrees)"End Sub

Basic.Capability%

Basic.Capability%(which%)

Descr. This method returns TRUE if the specified capability exists on the host operating environment;otherwise, this function returns FALSE.

The which parameter specifies which capability to test for. It can be any of the following values:

Example:

Sub Main()

'Test to see whether your current environment supports disk drives and'hidden file attributes and display the result.Msg$ = "This OS "If Basic.Capability(1) Then

Msg = Msg + "supports disk drives."else

Msg = Msg + "does not support disk drives."End IfMbeMessageBox Msg

End Sub

Basic.Eoln$

Basic.Eoln$

Descr. Returns a string containing the end-of-line character sequence appropriate to the host operatingenvironment.

This string will be either a carriage-return, a carriage-return line-feed, or a line-feed.

Value Returns TRUE if the platform supports

1 Disk drives

2 System file attribute (ebSystem)

3 Hidden file attribute (ebHidden)

4 Volume label file attribute (ebVolume)

5 Archive file attribute (ebArchive)

6 Denormalized floating-point math

Example:

Sub Main()

'This example writes two lines of text in a message box.MbeMessageBox "This is the first line of text " + Basic.Eoln$ + _"The second line"

End Sub

Basic.FreeMemory

Basic.FreeMemory&

Descr. Returns the number of bytes of free memory in BASIC's data space.

This function returns the size of the largest free block in BASIC's data space. Before this number isreturned, the data space is compacted, consolidating free space into a single contiguous free block.

BASIC's data space contains strings and dynamic arrays.

Example:

Sub Main()

'Display free memory in a dialog box.MbeMessageBox "The free memory space is: " + Str$(Basic.FreeMemory)

End Sub

Basic.OS

Basic.OS

Descr. Returns a number indicating the host operating environment.

Example:

Value Constant Platform

2 ebWin32 Microsoft Win32 ('95, NT, Win32s)

3 ebSolaris Sun Solaris 2.x

4 ebSunOS SunOS

5 ebHPUX HP/UX

7 ebIrix Silicon Graphics IRIX

8 ebAIX IBM AIX

10 ebMacintosh Apple Macintosh

12 ebDOS32 MS-DOS

13 ebClix Intergraph Clix

Sub Main()

'Determine the OS this version was created for and display the'appropriate message.o% = Basic.OSSelect Case o%

Case 2S$ = "Win32"

Case 12S$ = "DOS"

Case ElseS$ = "Neither Win32 nor DOS"

End SelectMbeMessageBox "The current version was created for " + S$

End Sub

Basic.PathSeparator$

Basic.PathSeparator$

Descr. Returns a string containing the path separator appropriate for the host operating environment.

The returned string will be a slash `/', a backslash `\', or a colon `:'.

Example:

Sub Main()

MbeMessageBox "The path separator for this environment is: " + _Basic.PathSeparator$

End Sub

Beep

Beep

Descr. Makes a single system beep.

Example:

Sub Main()

'Beep five times and display a reminder message.For i = 1 To 5

BeepSleep(500)

Next iMbeMessageBox "Do you have an upcoming appointment?"

End Sub

Call

Call subroutine_name [(arguments)]

Descr. Transfers control to the given subroutine, optionally passing the specified arguments.

Using this statement is equivalent to:

subroutine_name [arguments]

Use of the Call statement is optional. The subroutine to which control is transferred by Call must bedeclared outside of the Main procedure, as shown in the following example.

Example:

Sub Example_Call (S$)

'This subroutine is declared externally to Main and displays the text'passed in the parameter S$.MbeMessageBox "Example CALL: " + S$

End SubSub Main()

'Assign a string variable to display, then call subroutine'Example_Call, passing parameter S$ to be displayed in a'message box within the subroutine.S$ = "Display this text"Example_Call "Display this text"Call Example_Call ("Second form of Call statement")

End Sub

CDbl

CDbl#(number#)

Descr. Returns the double-precision equivalent of the passed numeric expression (number).

This function has the same effect as assigning the numeric expression number to a double-precisionvariable.

Example:

Sub Main()

i% = 100j! = 123.44MbeMessageBox Str$(CDbl(i * j))MbeMessageBox Str$(CDbl(i) * j)MbeMessageBox Str$(CDbl(i) * CDbl(j))

End Sub

Chr$

Chr$(Code%)

Descr. Returns the character whose value is Code.

Code must be an integer between 0 and 255. In addition, Code cannot be an expression.

The Chr$ function can be used within constant declarations, as in the following example:

Example:

Const crlf$ = Chr$(13) + Chr$(10)

Sub Main()'Concatenate carriage return (13) and line feed (10) to clf$,'then display a multiple-line message using clf$ to separate lines.CLF$ = Chr$(13) + Chr$(10)MbeMessageBox ("First line" + CLF + "Second line")'Fill an array with the ASCII characters for ABC and display their'corresponding characters.Dim a%(3)For i = 1 To 3

a%(i) = (64 + i)Next iMbeMessageBox Chr$(a(1)) + Chr$(a(2)) + Chr$(a(3))

End Sub

CInt

CInt%(number#)

Descr. Returns the integer portion of the given expression.

The passed numeric expression must be within the following range:

-32768

CLng&(number#)

Descr. Returns a Long representing the result of the given numeric expression.

The passed numeric expression must be within the following range:

-2147483648

'Get the command line and parameters, check to see whether the string' "/s" is present, and display the result.CMD$ = Command$If (InStr(Cmd,"/s")) 0 Then

MbeMessageBox "Macro started with /s switch"Else

MbeMessageBox "Macro started without /s switch"End IfMbeMessageBox "Startup line was: " + CMD$

End Sub

Const

const name = expression [,name = expression]...

Descr. Declares a constant for use within the current macro.

name is only valid within the current BASIC macro.

expression must be assembled from literals or other constants. Calls to functions are not allowed exceptcalls to the Chr$ function when used in the declarations part of the code or outside the Sub Main...EndSub.

- The constants are declared before the Sub Main declaration.

Example:

Const CRLF = Chr$(13) + Chr$(10)

Const T$ = "This is a constant"Sub Main()

'Display the declared constants in a dialog box (CRLF produces a new'line in the dialog box).MbeMessageBox T + CRLF + "The constants are shown above"

End Sub

Cos

Cos#(angle#)

Descr. Returns the cosine of a given angle.

The angle parameter is given in radians.

Example:

Sub Main()

'Assign the cosine of PI/4 radians (45 degrees) to C# and display its'value.C# = Cos(3.14159 / 4)MbeMessageBox "The cosine of 45 degrees is: " + Str$(C)

End Sub

CSng

CSng!(number#)

Descr. Returns a single representing the result of the given numeric expression number.

This function has the same effect as assigning a numeric expression to a single variable.

Example:

Sub Main()

'Assign variables of different types and display their CSng'conversions.S1# = CSng(150.61010101)S2& = CSng(150.62020202)S3% = CSng(150.63030303)S4! = CSng(150.64040404)MbeMessageBox Str$(S1) + Str$(S2) + Str$(S3) + Str$(S4)

End Sub

CStr

CStr(number#)

Descr. Returns a string representing the result of the given expression. The result is returned in floatingpoint `E' notation, if the result is very small or very large. Unlike Str$, the string returned by CStr will notcontain a leading space if the expression is positive.

Example:


Sub Main()'Assign two variables and display them using CStr conversions.A# = 123.456B# = -123.456MbeMessageBox CStr(A) + crlf + CStr(B)

End Sub

Date$

Date$[()]Date$ = newdate$

Descr. The Date$ function returns the current system date as a 10-character string. The statement form ofDate$ sets the system date to the specified date.

The format for the date used by Date$ is MM-DD-YYYY.

Example:


Sub Main()' This example saves the current date to Cdate$, then changes` the date and displays the result. It then changes the date back' to the saved date and displays the result.Cdate$ = Date$()Date$ = "01/01/94"MbeMessageBox("Saved date is: " + Cdate + crlf + "Changed date is: " + _

Date$())Date$ = CdateMbeMessageBox("Restored date to: " + Cdate)

End Sub

DateAdd

DateAdd#(interval$, increment&, date1$ | date1#)

Descr. The DateAdd function returns a double-precision number representing the sum of date1 and aspecified number (increment) of a specified time interval (interval$).

DateAdd adds a specified number (increment) of time intervals (interval$) to the specified date (date1).The following table describes the parameters to the DateAdd function:

The interval$ parameter specifies what unit of time is to be added to the given date. It can be any of thefollowing:

Parameter Description

interval$ a string expression that indicates the time interval used in the addition.

increment a double-precision number that indicates the number of time intervals you wish to add.Positive values result in dates in the future; negative values result in dates in the past.

date1 a double-precision number or a valid date/time. String expression. An example of a validdate/time string would be "January 1, 1993."

Time Interval

"y" Day of the year

"yyyy" Year

"d" Day

"m" Month

"q" Quarter

"ww" Week

"h" Hour

"n" Minute

"s" Second

"w" Weekday

To add days to a date, you may use either day, day of the year, or weekday, as they are all equivalent ("d","y", "w").

DateAdd will never return an invalid date/time expression. The following example adds two months toDecember 31, 1992:

s# = DateAdd("m", 2, "December 31, 1992")

In this example, s is returned as the double-precision number equal to "February 28, 1993", not"February 31, 1993".

A run-time error is generated if you attempt to subtract a time interval that is larger than the time value ofthe date.

Example:

Sub Main()

'This example gets today's date using the Date$ function; adds one'year, two months, one week, and two days to it; and then displays the'result in a dialog box.Dim dDate#Dim sDate$sDate$ = Date$NewDate# = DateAdd("yyyy", 3, sDate)NewDate = DateAdd("mm", 2, NewDate)NewDate = DateAdd("ww", 1, NewDate)NewDate = DateAdd("dd", 2, NewDate)s$ = "One year, two months, one week, and two days from now will be: "s$ = s$ + format$(NewDate, "long date")MbeMessageBox s$

End Sub

DateDiff

DateDiff&(interval$, date1$ | date1#, date2$ | date2#)

Descr. Returns a double-precision number representing the number of given time intervals between date1and date2.

The DateDiff function will return the number of days or the number of whole weeks between two dates. Thefollowing table describes the parameters:

The following table lists the valid time interval strings and the meanings of each. The Format$ functionuses the same expressions.


interval$ a string expression that indicates the specific time interval you wish to find the differencebetween.

date1 a double-precision number or a valid date/time string expression. An example of a validdate/time string would be "January 1, 1993".

date2 a double-precision number or a valid date/time string expression. An example of a validdate/time string would be "January 1, 1993".

To find the number of days between two dates, you may use either day or day of the year, as they are bothequivalent ("d", "y").

The time interval weekday ("w") will return the number of weekdays occurring between date1 and date2,counting the first occurrence but not the last. However, if the time interval is week ("ww"), the function willreturn the number of calendar weeks between date1 and date2, counting the number of Sundays. If date1falls on a Sunday, then that day is counted, but if date2 falls on a Sunday, it is not counted.

DateDiff will return a negative date/time value if date1 occurs later in time than date2.

Example:

Sub Main()

'This example gets today's date and adds 10 days to it. It then'calculates the difference between the two dates in days and weeks'and displays the result.Today$ = Date$TodayR# = DateValue(Date$)

NextWeek# = DateAdd("d", 10, Today)Difdays# = DateDiff("d", Today, NextWeek)Difweek# = DateDiff("ww", Today, NextWeek)S$ = "The difference between " + Str$(Today) + " and " + Str$(NextWeek)S$ = S$ + " is: " + Str$(Difdays) + " days or " + Str$(DifWeek) + _

" weeks"MbeMessageBox S$

End Sub

DatePart

DatePart%(interval$, date1$ | date1#)

Descr. Returns a number representing a specified part of a valid date/time expression.

The DatePart function decomposes the given date and returns a given date/time element. The followingtable describes the parameters:

Time Interval

"y" Day of the year

"yyyy" Year

"d" Day

"m" Month

"q" Quarter

"ww" Week

"h" Hour

"n" Minute

"s" Second

"w" Weekday

The following table lists the valid time interval strings and the meanings of each. The Format$ functionuses the same expressions.

The weekday expression starts with Sunday as 1 and ends with Saturday as 7.

Example:

const crlf = chr$(13) + chr$(10)

Sub Main()'This example displays the parts of the current dateToday$ = Date$Qtr = DatePart("q",Today)Yr = DatePart("yyyy",Today)Mo = DatePart("m",Today)Wk = DatePart("ww",Today)Da = DatePart("d",Today)S$ = "Quarter: " + Str$(Qtr) + crlfS$ = S$ + "Year : " + Str$(Yr) + crlfS$ = S$ + "Month : " + Str$(Mo) + crlfS$ = S$ + "Week : " + Str$(Wk) + crlfS$ = S$ + "Day : " + Str$(Da) + crlfMbeMessageBox S$

End Sub

DateSerial

DateSerial#(year%, month%, day%)

Descr. The DateSerial function returns a double-precision number representing the specified date. Thenumber is returned in days, where Dec 30, 1899 is 0.

Example:

Sub Main()


interval$ a string expression that indicates the specific time interval you wish to identify within thegiven date.

date1 either a double-precision number or a valid date/time string expression. An example of avalid date/time string would be "January 1, 1993".

Time Interval

"y" Day of the year

"yyyy" Year

"d" Day

"m" Month

"q" Quarter

"ww" Week

'This example converts a date to a real number representing the'serial date in days since Dec 30, 1899 (which is day 0).Tdate# = DateSerial(1990,08,22)MbeMessageBox "DateSerial value for Aug 22, 1990, is: " + Str$(Tdate)

End Sub

DateValue

DateValue#(date_string$)

Descr. Returns a double-precision number representing the date contained in the specified string argument.

Example:

Sub Main()

'This example returns the day of the month for today's date.Dim TDay as LongTdate$ = Date$TDay = DateValue(Tdate)MbeMessageBox Tdate + "The date value is: " + Str$(Tday)

End Sub

Day

Day%(serial#)

Descr. Returns the day of the date encoded in the specified serial parameter. The value returned is between1 and 31 inclusive.

Example:

Sub Main()

'This example returns the day of the month for today's date.Dim TDay as LongTdate$ = Date$TDay! = Day(DateValue(Tdate))MbeMessageBox ("The day part of " + Tdate + " is: " + Str$(TDay))

End Sub

DDB

DDB#(Cost#, Salvage#, Life#, Period#)

Descr. This function calculates the depreciation of an asset for a specified Period of time using the double-declining balance method.

The double-declining balance method calculates the depreciation of an asset at an accelerated rate. Thedepreciation is at its highest in the first period and becomes progressively lower in each additional period.DDB uses the following formula to calculate the depreciation:

DDB =((Cost - Total_depreciation_from_all_other_periods) * 2)/Life

DDB uses the following parameters:

Life and Period must be expressed using the same units. If Life is expressed in months, then Period mustalso be expressed in months.

Example:


Sub Main()'This example calculates the depreciation for capital equipment'that cost $10,000, has a service life of 10 years, and is worth'$2,000 as scrap. The dialog box displays the depreciation for each'of the first 4 years.S$ = "Depreciation Table" + crlf + crlfFor yy = 1 To 4

CurDep# = DDB(10000.0, 2000.0, 10, yy)S$ = S$ + "Year " + Str$(yy) + " : " + Str$(CurDep) + crlf

Next yyMbeMessageBox S$

End Sub

DDEExecute

DDEExecute channel%, command$

Descr. Sends an execute message to another application.

The channel must first be initiated using DDEInitiate. An error will result if channel is invalid.

If the receiving application does not execute the instructions, BASIC generates a run-time error.

The format of command$ depends on the receiving application.

Win32 is the platform that applies to DDEExecute. The DDEML library is required for DDE support. Thislibrary is loaded when the first DDEInitiate statement is encountered and remains loaded until the BASICsystem is terminated. Thus, the DDEML library is required only if DDE statements are used within a macro.

Example:

Sub Main()

Dim ch As Integerq$ = Chr$(34)


Cost a double-precision number that represents the initial cost of the asset

Salvage a double-precision number that represents the estimated value of the asset at the end of itspredicted useful life

Life a number that represents the predicted length of the asset's useful life

Period a number that represents the period for which you wish to calculate the depreciation

ch = DDEInitiate("Excel", "C:\SHEETS\TEST.XLS")CMD$ = "[SELECT(" + q$ + "R1C1:R8C1" + q$ + ")]"DDEExecute ch,cmd$DDETerminate ch

End Sub

DDEInitiate

DDEInitiate%(app$, topic$)

Descr. Initializes a DDE link to another application and returns a unique number subsequently used to referto the open DDE channel.

The function returns 0 if BASIC cannot establish the link. This will occur under any of the followingcircumstances:

1. The specified application is not running.2. The topic was invalid for that application.3. Memory or system resources are insufficient to establish the DDE link.

app$ specifies the name of the application (the server) with which a DDE conversion will be established.topic$ specifies the name of the topic for the conversation. The possible values for this parameter aredescribed in the documentation for the server application.

Win32 is the platform that applies to DDEInitiate. The DDEML library is required for DDE support. Thislibrary is loaded when the first DDEInitiate statement is encountered and remains loaded until the BASICsystem is terminated. Thus, the DDEML library is required only if DDE statements are used within a macro.

Example:

Sub Main()

Dim ch As Integerq$ = Chr$(34)ch = DDEInitiate("Excel", "C:\SHEETS\TEST.XLS")CMD$ = "[SELECT(" + q$ + "R1C1:R8C1" + q$ + ")]"DDEExecute ch, cmd$DDETerminate ch

End Sub

DDEPoke

DDEPoke channel%, dataItem$, value$

Descr. Sets the value of a data item in the receiving application associated with an open DDE link.


The format for dataItem$ and value$ depends on the receiving application.

Win32 is the platform that applies to DDEPoke. The DDEML library is required for DDE support. Thislibrary is loaded when the first DDEInitiate statement is encountered and remains loaded until the BASICsystem is terminated. Thus, the DDEML library is required only if DDE statements are used within a macro.

Example:

Sub Main()

ch = DDEInitiate("Excel", "C:\SHEETS\TEST.XLS")DDEPoke ch, "R1C1", "980"DDETerminate ch

End Sub

DDERequest

DDERequest$ (channel%, dataItem$)

Descr. Returns a string representing the value of the given data item in the receiving application associatedwith the open DDE channel.


The formats for dataItem$ and the returned value depend on the receiving application.

Win32 is the platform that applies to DDERequest. The DDEML library is required for DDE support. Thislibrary is loaded when the first DDEInitiate statement is encountered and remains loaded until the BASICsystem is terminated. Thus, the DDEML library is required only if DDE statements are used within a macro.

Example:

Sub Main()

ch = DDEInitiate("Excel", "C:\SHEETS\TEST.XLS")s$ = DDERequest$(ch, "R1C1")DDETerminate chMbeMsgBox s$

End Sub

DDESend

DDESend application$, topic$, item$, data$

Descr. Initiates a DDE conversation with the server as specified by application$ and topic$ and sends thatserver a new value for the specified item.

The DDESend statement performs the equivalent of the following statements:

ch% = DDEInitiate(application$, topic$)DDEPoke ch$, item$, data$DDETerminate ch%

Win32 is the platform that applies to DDESend. The DDEML library is required for DDE support. Thislibrary is loaded when the first DDEInitiate statement is encountered and remains loaded until the BASICsystem is terminated. Thus, the DDEML library is required only if DDE statements are used within a macro.

Example:

` The following code fragment sets the content of the first cell in an

` Excel spreadsheet.On Error Goto Trap1DDESend "Excel", "C:\EXCEL\TEST.XLS", "R1C1", "Hello, world."On Error Goto 0` Add more lines here ...

Trap1:MbeMsgBox "Error sending data to Excel."Exit Sub `Reset error handler

DDETerminate

DDETerminate channel%

Descr. Closes the specified DDE channel.


All open DDE channels are automatically terminated when the macro ends.

Win32 is the platform that applies to DDETerminate. The DDEML library is required for DDE support.This library is loaded when the first DDEInitiate statement is encountered and remains loaded until theBASIC system is terminated. Thus, the DDEML library is required only if DDE statements are used withina macro.

Example:

Sub Main()

Dim ch As Integerq$ = Chr$(34)ch = DDEInitiate("Excel", "C:\SHEETS\TEST.XLS")CMD$ = "[SELECT(" + q$ + "R1C1:R8C1" + q$ + ")]"DDEExecute ch, cmd$DDETerminate ch

End Sub

DDETerminateAll

DDETerminateAll

Descr. Closes all open DDE channels.

All open DDE channels are automatically terminated when the macro ends.

Win32 is the platform that applies to DDETerminateAll. The DDEML library is required for DDE support.This library is loaded when the first DDEInitiate statement is encountered and remains loaded until theBASIC system is terminated. Thus, the DDEML library is required only if DDE statements are used withina macro.

Example:

Sub Main()

Dim ch As Integer

q$ = Chr$(34)ch = DDEInitiate("Excel", "C:\SHEETS\TEST.XLS")CMD$ = "[SELECT(" + q$ + "R1C1:R8C1" + q$ + ")]"DDEExecute ch, cmd$DDETerminateAll

End Sub

DDETimeOut

DDETimeOut milliseconds&

Descr. This statement sets the number of milliseconds that must elapse before a DDE command times out.The default is 10,000 (10 seconds).

Win32 is the platform that applies to DDETimeOut. The DDEML library is required for DDE support. Thislibrary is loaded when the first DDEInitiate statement is encountered and remains loaded until the BASICsystem is terminated. Thus, the DDEML library is required only if DDE statements are used within a macro.

Example:

Sub Main()

Dim ch As Integerq$ = Chr$(34)ch = DDEInitiate("Excel", "C:\SHEETS\TEST.XLS")DDETimeOut (20000)CMD$ = "[SELECT(" + q$ + "R1C1:R8C1" + q$ + ")]"DDEExecute ch, cmd$DDETerminate ch

End Sub

Declare

Declare Sub name [([argumentlist])]Declare Function name [([argumentlist])] [As type]

Descr. You can use the Declare statement to create a prototype for a BASIC routine that occurs later in thesource module.

The name parameter is any valid BASIC name. When you declare functions, you can include a type-declaration character to indicate the return type.

The optional argumentlist specifies the arguments received by the routine. By default, arguments arepassed by reference. When a routine requires a value rather than a reference, include the ByVal keyword.For example, the following subroutine:

Sub MessageBeep (ByVal numBeeps%, message#)

would be declared as follows:

Declare Sub MessageBeep (ByVal numBeeps%, message#)

For function declarations, the return type can be specified using a type-declaration character (i.e., $, % or &)or by specifying the [As type] clause. The valid types are Integer, Long and String.

Declare statements must appear outside of any Sub or Function declaration. Declare statements are onlyvalid during the life of that macro.

DEF...

DEFInt letterrangeDEFLng letterrangeDEFStr letterrangeDEFsng letterrangeDEFdbl letterrange

Descr. Establishes the default type assigned to undeclared or untyped variables.

The DEF... statement controls automatic type declaration of variables. Normally, if a variable isencountered that hasn't yet been declared with the Dim statement or does not appear with an explicit type-declaration character, then that variable is declared implicitly as an integer (DEFInt A-Z). This can bechanged using the DEF... statement to specify starting letter ranges for type other than integer. Theletterrange parameter is used to specify starting letters. Thus, any variable that begins with a specifiedcharacter will be declared using the specified type.

The syntax for letterrange is:

letter [-letter] [,letter [-letter]]...

DEF... variable types are superseded by an explicit type declaration--using either a type-declarationcharacter or the Dim statement.

DEF... only affects how macros are compiled and has no effect at run time. DEF... can only appear outsideall Sub and Function declarations.

Example:

DEFStr a-l

DEFLng m-rDEFSng s-uDEFDbl v-wDEFInt x-zSub Main()

a = "This stuff"m = 100.52s = 100.52v = 100.55x = 100.52MbeMessageBox a & Str$(m) & Str$(s) & Str$(v) & Str$(x)

End Sub

Dim

Dim name [()] [As [New] type] [,name [()] _[As [New] type]]...

Descr. Declares a list of local variables and their corresponding types and sizes.

If a type-declaration character is used when specifying name (such as %, &, $ or !), the optional [As type]expression is not allowed. For example, the following are allowed:

Example:

Dim Temperature As Integer

Dim Temperature%

The subscripts parameter allows the declaration of dynamic and fixed arrays. subscripts uses the followingsyntax:

[lower to] upper [,[lower to] upper]...

The lower and upper parameters are Integers specifying the lower and upper bounds of the array. If loweris not specified, then the lower bound as specified by Option Base is used (or 0 if no Option Basestatement has been encountered). BASIC supports a maximum of 60 array dimensions.

The total size of an array (not counting space for strings) is limited to 64K.

Dynamic arrays are declared by not specifying any bounds:

Example:

Dim a()

The type parameter specifies the type of the data item being declared. It can be any of the following datatypes: String, Integer, Long, Single, Double, Object, application-defined object, application-defineddata type, or any user-defined data type.

A Dim statement within a subroutine or function declares variables local to that subroutine or function. Ifthe Dim statement appears outside of any subroutine or function declaration, then that variable has the samescope as variables declared with the Private statement.

Implicit Variable Declaration

If BASIC encounters a variable that has not been explicitly declared with Dim, then the variable will beimplicitly declared using the specified type-declaration character (%, $ or &). If the variable appears withouta type-declaration character, then the first letter is matched against any pending DEF... statements, using thespecified type if found. If no DEF... statement has been encountered corresponding to the first letter of thevariable name, then Integer is used.

Creating New Objects

The optional [New] keyword is used to declare a new instance of the specified application-defined object.This keyword can only be used with application-defined object data types. Furthermore, this keywordcannot be used when declaring arrays.

At run time, the application or extension that defines that object type is notified that a new object is beingdefined. The application should respond by creating a new physical object (within the appropriate context)and returning a reference to that object, which is immediately assigned to the variable being declared.

When that variable goes out of scope (i.e., the Sub or Function procedure in which the variable is declaredends), the application is notified. The application can choose any appropriate actions, such as destroying thephysical object.

Example:

Sub Main()

'The following are examples using the Dim statement to declare various'variable types.Dim a As integerDim a%Dim b As longDim b&Dim c As stringDim c$Dim MyArray(10) As integerDim MyStrings$(2,10)Dim FileNames$(5 to 10)Dim Values(1 to 10, 100 to 200)

End Sub

Dir$

Dir$[(filespec$ [,attributes])]

Descr. If filespec$ is specified, then the Dir$ function returns the first file matching that filespec$. Iffilespec$ is not specified, then Dir$ returns the next file matching the initial filespec$ as shown in theexample.

The filespec$ argument can include wild cards, such as * and ?. The * character matches any sequence ofzero or more characters, whereas the ? character matches any single character. Multiple *'s and ?'s canappear within the expression to form complete searching patterns. The following table shows someexamples:

An error is generated if Dir$ is called without first calling it with a valid filespec$.

If there is no matching filespec$, then an empty string is returned.

If no path is specified on filespec$, then the current directory is used.

You can control which files are included in the search by specifying the optional attributes parameter. Thisparameter contains any OR'ed combination of the following attributes:

This pattern Matches these files Doesn't match these files

*S*.TXTSAMPLE.TXTGOOSE.TXTSAMS.TXT

SAMPLESAMPLE.DAT

C*T.TXT CAT.TXTACATS.TXT CAP.TXT

C*T CATCAP.TXT CAT.DOC

C?TCATCUTCT

CAT.TXTCAPIT

* (All files)

Example:


Sub Main()'This example dimensions a null array and fills it with directory'entries. The result is displayed in a dialog box.Dim a$(10)a(1) = Dir$("*.*")i% = 1While (a(i) "") And (i < 10)

i = i+1a(i) = Dir$

WendMbeMessageBox a(1) + crlf + a(2) + crlf + a(3) + crlf + a(4)

End Sub

Do...Loop

Do {While | Until} condition statements LoopDo

statementsLoop {While | Until} conditionDo

statementsLoop

Descr. Repeats a block of BASIC statements while a condition is TRUE or until a condition is TRUE. If the{While | Until} conditional clause is not specified, then the loop repeats the statements forever (or untilBASIC encounters an Exit Do statement).

The condition parameter specifies any Boolean expression.

Example:


Sub Main()'The first example uses the Do...While statement, which performs the'iteration, then checks the condition, and repeats if the condition'is True.Dim a$(100)i% = 0Do

i = i+1If i = 1 Then

a(i) = Dir$("*.*")Else

Constant Value Includes

ebNormal 0 Clear the read-only and archive attributes

ebReadOnly 1 Set read-only attribute

ebHidden 2 Set hidden attribute

ebSystem 4 Set system file attribute

ebArchive 32 Set archive attribute

a(i) = Dir$End If

Loop While (a(i) "")Msg$ = "There are " + Str$(i) + " files found" + crlfMbeMessageBox Msg + a(1) + crlf + a(2) + crlf + a(3) + crlf + a(10)'The second example uses the Do While...Loop, which checks the'condition and then repeats if the condition is True.Dim a$(100)i% = 1a(i) = Dir$("*.*")Do While a(i) ""

i = i+1a(i) = Dir$

LoopMsg$ = "There are " + Str$(i) + " files found" + crlfMbeMessageBox Msg + a(1) + crlf + a(2) + crlf + a(3) + crlf + a(10)'The third example uses the Do Until...Loop, which does the iteration'and then checks the condition and repeats if the condition is True.Dim a$(100)i% = 1a(i) = Dir$("*.*")Do Until a(i) = ""

i = i+1a(i) = Dir$

LoopMsg$ = "There are " + Str$(i) + " files found" + crlfMbeMessageBox Msg + a(1) + crlf + a(2) + crlf + a(3) + crlf + a(10)'The last example uses the Do...Until Loop, which performs the'iteration first, checks the condition, and repeats if the condition'is True.Dim a$(100)i% = 0Do



a(i) = Dir$End If

Loop Until (a(i) = "")Msg$ = "There are " + Str$(i) + " files found" + crlfMbeMessageBox Msg + a(1) + crlf + a(2) + crlf + a(3) + crlf + a(10)

End Sub

ebArchive

Descr. 32-bit position of a file attribute indicating that a file hasn't been backed up.

Example:

Sub Main()

'Dimension an array and fill it with filenames with Archive bit set.Dim s$()FileList(s$), "*.*", ebArchivea% = SelectBox("Archived Files", "Choose one", s$)If a >= 0 Then 'If a% is -1, then user pressed Cancel.

MbeMessageBox "You selected ARCHIVE file " + s$(a)Else

MbeMessageBox "No selection made"End If

End Sub

ebDirectory

Descr. 16-bit position of a file attribute indicating that a file is a directory entry.

Example:

Sub Main()

'Dimension an array and fill it with directory names using the'ebDirectory constant.Dim s$()FileList(s$), "*.*", ebDirectorya% = MbeSelectBox("Choose One", s(), "Directories")If a >= 0 Then

MbeMessageBox "You selected directory " + S$(a)Else


End Sub

ebHidden

Descr. 2-bit position of a file attribute indicating that a file is hidden.

Example:

Sub Main()

'Dimension an array and fill it with filenames using`the ebHidden attribute.Dim s$()FileList(S$), "*.*", ebHiddena% = SelectBox("Hidden Files","Choose one", S$)If a >= 0 Then

MbeMessageBox "You selected hidden file " + S$(a)Else


End Sub

ebNone

Descr. 64-bit value used to select files with no other attributes. This value can be used with the Dir$ andFileList commands. These functions will return only files with no attributes set when used with thisconstant.

Example:

Sub Main()

'Dimension an array and fill it with filenames with no attributes set.Dim s$()FileList(S$), "*.*", ebNone

a% = SelectBox("No Attributes", "Choose one", S$)If a >= 0 Then

MbeMessageBox "You selected file " + S$(a)Else


End Sub

ebNormal

Descr. 0

Value used to search for "normal" files. This value can be used with the Dir$ and FileList commands andwill return files with the Archive, Volume, ReadOnly or no attributes set. It will not match files withHidden, System or Directory attributes.

Example:

Sub Main()

'Dimension an array and fill it with filenames with Normal attributes.Dim s$()FileList(S$),"*.*", ebNormala% = SelectBox("Normal Files", "Choose one", S$)If a >= 0 Then



End Sub

ebReadOnly

Descr. Bit[1] position of a file attribute indicating that a file is read-only.

Example:

Sub Main()

'Dimension an array & fill it with filenames with ReadOnly attributes.Dim s$()FileList(S$), "*.*", ebReadOnlya% = SelectBox("ReadOnly", "Choose one", S$)If a >= 0 Then



End Sub

ebSystem

Descr. Bit[4] position of a file attribute indicating that a file is a system file.

Example:

Sub Main()

'Dimension an array and fill it with filenames with System attributes.Dim s$()FileList(S$), "*.*", ebSystema% = SelectBox("System Files", "Choose one", S$)If a >= 0 Then



End Sub

ebVolume

Descr. Bit[8] position of a file attribute indicating that a file is the volume label.

Example:

Sub Main()

'Dimension an array and fill it with filenames with Volume attributes.Dim s$()FileList(S$), "*.*", ebVolumeIf ArrayDims(a) > 0 Then

MbeMessageBox "The volume name is: " + a(1)Else

MbeMessageBox "No volumes found"End If

End Sub

End

End

Descr. Terminates execution of the current macro. All open files are closed.

Example:

Sub Main()

MbeMessageBox "The next line will terminate the script"End

End Sub

Environ$

Environ$(variable$)Environ$(VariableNumber%)

Descr. Returns the value of the specified environment variable.

If variable$ is specified, then this function looks for that variable$ in the environment. If variable$ cannotbe found, an empty string is returned.

If VariableNumber is specified, then this function looks for the nth variable within the environment (thefirst variable being number 1). If there is no such environment variable, then an empty string is returned.Otherwise, the entire entry from the environment is returned in the following format:

variable = value

Example:

Sub Main()

'This example looks for the DOS Comspec variable and displays the'value in a dialog box.Dim a$(1)a(1) = Environ$("COMSPEC")MbeMessageBox a(1)

End Sub

To retrieve and set the values of MicroStation configuration variables, use the MicroStation BASICextensions: MbeGetConfigVar (page8144) and MbeDefineConfigVar.

See also MbeGetConfigVar, MbeSetConfigVar.

Eof

Eof%(filenumber%)

Descr. Returns TRUE if the end of file has been reached for the given file; otherwise returns FALSE.

The filenumber parameter is a number that is used to refer to the open file--the number passed to the Openstatement.

With sequential files, Eof returns TRUE when the end of the file has been reached (i.e., the next file readcommand will result in a run-time error).

With Random or Binary files, Eof returns TRUE after an attempt has been made to read beyond the end of thefile. Thus, Eof will only return TRUE when Get was unable to read the entire record.

Example:

Sub Main()

'This example opens the Autoexec.Bat file and reads lines from the'file until the end of file is reached.Dim S$Open "C:\AUTOEXEC.BAT" For Input As 1Do While Not Eof(1)

Input #1,SLoopCloseMbeMessageBox "The last line was" + crlf + S

End Sub

Eqv

expression1 Eqv expression2

Descr. If both operands are relational, then Eqv returns the logical equivalence of expression1 andexpression2. Eqv returns TRUE if expression1 and expression2 are the same (i.e., either both TRUE or bothFALSE); otherwise Eqv returns FALSE.

If both operands are numeric, then the result is the bitwise Eqv of the arguments.

If either of the two operands is a floating-point number, the two operands are converted to Longs, then abitwise Eqv is performed.

For numeric operands, bitwise Eqv works as follows:

Example:

Sub Main()

'This example assigns False to A, performs some equivalent operations,'and displays a dialog box with the result. Since A is equivalent to'False, and False is equivalent to 0, and by definition, A = 0, then'the dialog box will display "A is False".A = FalseIf ((A Eqv False) And (False Eqv 0) And (A = 0)) Then

MbeMessageBox "A is False"Else

MbeMessageBox "A is True"End If

End Sub

Erase

Erase array1 [,array2]...

Descr. The Erase statement erases the elements of the specified arrays.

For dynamic arrays, the elements are erased and the array is redimensioned to have no dimensions (andtherefore no elements). For fixed arrays, only the elements are erased; the array dimensions are not changed.

After a dynamic array is erased, the array will contain no elements and no dimensions. Thus, before thearray can be used by your program, the dimensions must be reestablished using the Redim statement.

Up to 32 parameters can be specified with the Erase statement.

The meaning of erasing an array element depends on the type of element being erased:

Bit in expression1 Bit in expression2 Bit in result

1 1 1

0 1 0

1 0 0

0 0 1

Example:

Sub Main()

Dim a$(1)a(1) = Dir$("*.*")MbeMessageBox aErase aMbeMessageBox a(1)

End Sub

Erl

Erl%[()]

Descr. Returns 0 (BASIC does not support line numbers).

Example:

Sub Main()

'Since the Erl function normally specifies a line number, it will'always return 0 within this product, as shown below.a = ErlIf a = 0 Then

MbeMessageBox "Returned 0"Else

MbeMessageBox "Returned non-0" + Str$(a)End If

End Sub

Err (function)

Err%[()]

Descr. The Err function returns an Integer representing the run time error that caused the current errortrap.

Err can only be used while within an error trap.

Element type What Erase does to that element

Integer Sets the element to 0.

Long Sets the element to 0.

Double Sets the element to 0.0.

Single Sets the element to 0.0.

String Frees the string, then sets the element to an empty string.

Object Decrements the reference count and sets the element to Nothing.

User-defined types Sets each structure element as a separate variable.

When a function or statement ends, the value returned by Err is reset to 0.

Example:

Sub Main()

'This example forces error 10, with a subsequent transfer to'the TestError label. TestError tests the error and, if not'error 55, resets Err to 999 (user-defined error) and returns to'the Main subroutine.On Error Goto TestErrorError 10MbeMessageBox("The returned error is: " + Str$(Err()) + " : " + Error$)Exit Sub

TestError:If Err = 55 Then 'File already open.

MbeMessageBox "Cannot copy an open file. Close it and try again."Else

MbeMessageBox "Error " + Str$(Err) + " has occurred"Err = 999

End IfResume Next

End Sub

Err (statement)

Err = value%

Descr. The statement form of Err sets the value returned by the Err function to a specific value.

Only positive values less than 32767 are valid.

Setting value to -1 has the side effect of resetting the error state. This allows you to perform error trappingwithin an error handler.

Example:

Sub Main()





End IfResume Next

End Sub

Error

Error errornumber%

Descr. This function simulates the occurrence of the given run-time error.

The errornumber parameter can be a built-in error number or a user-defined error number. Err can be usedwithin the error trap handler to determine the value of the error.

Example:

Sub Main()





End IfResume Next

End Sub

Error$

Error$ [(errornumber%)]

Descr. Returns the text corresponding to the given error number or the most recent error.

If errornumber is omitted, then the function returns the text corresponding to the most recent run-timeerror. If no run-time error has occurred, then an empty string ("") is returned.

If the Error statement was used to generate a user-defined run-time error, then this function will return anempty string ("").

Example:

Sub Main()





End IfResume Next

End Sub

Exit Do

Exit Do

Descr. This statement can only appear within a Do...Loop statement. It causes execution to continue on thenext statement after the Loop clause.

Example:

Sub Main()

'This example will load an array with directory entries unless there'are more than three entries, in which case, the Exit Do terminates'the loop.'If fewer than 3 entries are found, a dialog box displays the count;'otherwise, a dialog box displays "More than three entries found."Dim a$(5)i% = 0Do



a(i) = Dir$End If

If i >= 3 Then Exit DoLoop While (a(i) "")If i 3 Then

MbeMessageBox "There are " + Str$(i) + " files found"Else

MbeMessageBox "Exited on i = 3"End IfMbeMessageBox a(1) + crlf + a(2) + crlf + a(3) + crlf + a(10)

End Sub

Exit For

Exit For

Descr. This statement ends the For...Next block in which it appears. Execution will continue on the lineimmediately after the Next statement.

This statement can only appear within a For...Next block.

Example:


Sub Main()'This example will fill an array with directory entries`until a null entry is encountered or 100 entries have been

`processed. The dialog box displays a count of files found and`then some entries from the array.Dim a$(100)Dim i%For i% = 1 To 100

If i = 1 Thena(i) = Dir$("*.*")

Elsea(i) = Dir$

End IfIf (a(i) = "") Or (i >= 100) Then Exit For

Next iMsg$ = "There are " + Str$(i) + " files found" + crlfMbeMessageBox Msg + a(1) + crlf + a(2) + crlf + a(3) + crlf + a(10)

End Sub

Exit Function

Exit Function

Descr. This statement ends execution of the function in which it appears. Execution will continue on thestatement or function following the call to this function.

This statement can only appear within a function.

Example:

Function Test_Exit () As Integer

'This function displays a message & then terminates with Exit Function.MbeMessageBox("Testing function exit: returning to Main")Test_Exit = 0Exit FunctionMbeMessageBox("This line should never execute")

End FunctionSub Main()

a% = Test_Exit()MbeMessageBox "This is the last line of Main"

End Sub

Exit Sub

Exit Sub

Descr. This statement ends the current subroutine. Execution is transferred to the statement following thecall to the current subroutine.

This statement can appear anywhere within a subroutine. It cannot appear within a function.

Example:

Sub Main()

'This example displays a dialog box & then exits. The last line should'never execute because of the Exit Sub statement.MbeMessageBox("Terminating Main")

Exit SubMbeMessageBox("Still here in Main")

End Sub

Exp

Exp#(value#)

Descr. Returns the value of e raised to the power of value.

Range of value: 0

The filenumber parameter is a number that is used to refer to the open file--the number passed to the Openstatement.

Example:

Sub Main()

'This example opens a file for input, reads the file attributes, and'determines the file mode for which it was opened. The result is'displayed in a dialog box.Open "C:\AUTOEXEC.BAT" For Input As 1a% = FileAttr(1,1)Select Case a

Case 1MbeMessageBox "Opened for input"

Case 2MbeMessageBox "Opened for output"

Case 3MbeMessageBox "Opened for random"

Case 4MbeMessageBox "Opened for append"

Case 32MbeMessageBox "Opened for binary"

Case ElseMbeMessageBox "Unknown file mode"

End Selecta = FileAttr(1,2)MbeMessageBox "File handle is: " + Str$(a)Close

End Sub

FileCopy

FileCopy source$, destination$

Descr. The FileCopy command copies a source$ file to a destination$ file.

The source$ parameter must specify a single file. It cannot contain wild cards (? or *) but may contain pathinformation.

The destination$ specifies a single, unique destination file and may contain drive and path specifiers. Thefile will be copied and renamed if the source$ and destination$ filenames are not the same. Note that someplatforms do not support drive letters and may not support dots to indicate current and parent directories.

Example:

Sub Main()

'This example copies the Autoexec.Bat file to "AUTOEXEC.SAV", then

1 Input

2 Output

4 Random

8 Append

32 Binary

'opens the copied file and tries to copy it again, generating an error.On Error Goto ErrHandlerFileCopy "C:\AUTOEXEC.BAT", "C:\AUTOEXEC.SAV"Open "C:\AUTOEXEC.SAV" For Input As # 1FileCopy "C:\AUTOEXEC.SAV", "C:\AUTOEXEC.SV2"CloseExit Sub

ErrHandler:If Err = 55 Then 'File already open.


MbeMessageBox "An unspecified file copy error has occurred"End IfResume Next

End Sub

FileDateTime

FileDateTime#(filename$)

Descr. The FileDateTime function returns a double-precision number representing the date and time of thegiven file. The number is returned in days, where Dec 30, 1899 is 0.

FileDateTime retrieves the date and time of the file specified by filename$. A run-time error results if thefile does not exist. The value returned can be used with the date/time functions (i.e., Year, Month, Day,Weekday, Minute, Second, Hour) to extract the individual elements.

Example:

Sub Main()

'This example gets the file date/time of the Autoexec.Bat file and'displays it in a dialog box.If FileExists "C:\Autoexec.Bat" Then

A# = FileDateTime("C:\AUTOEXEC.BAT")MbeMessageBox Str$(Year(A)) + Str$(Month(A)) + Str$(Day(A))

ElseMbeMessageBox "The file does not exist"

End IfEnd Sub

FileDirs

FileDirs array$() [,dirspec$]

Descr. This statement fills an array$ with directory names from disk.

array$() is any previously declared string array. The FileDirs function reallocates this array to exactly holdall the directory names matching a given specification.

array$ must specify either a 0- or a 1-dimensioned dynamic array or a single-dimensioned fixed array. Ifthe array is dynamic, then it will be redimensioned to exactly hold the new number of elements. If the arrayis fixed, each array element is first erased, then the new elements are placed into the array. If there are fewerelements than will fit in the array, then the remaining elements are unused. A run-time error results if thearray is too small to hold the new elements.

The dirspec$ parameter specifies the file search mask, such as:

T*. C:\*.*

If dirspec$ is not specified, then * is used, which fills the array with all the subdirectory names within thecurrent directory.

Example:

Sub Main()

'This example fills an array with directory entries and displays the'first one.Dim A$()FileDirs A,"C:\*.*"

MbeMessageBox A(1)End Sub

FileExists

FileExists%(filename$)

Descr. TRUE if the filename$ is a valid file; FALSE otherwise.

FileExists determines whether a given filename$ is valid. FileExists will return FALSE if filename$specifies a subdirectory.

Example:

Sub Main()

'This example checks to see whether there is an Autoexec.Bat file in'the root directory of the C drive, then displays either its date and'time of creation or the fact that it does not exist.If FileExists("C:\AUTOEXEC.BAT") Then

a# = FileDateTime("C:\AUTOEXEC.BAT")MbeMessageBox Str$(Year(A#)) + Str$(Month(A#)) + Str$(Day(A#))

ElseMbeMessageBox "File does not exist"

End IfEnd Sub

FileLen

FileLen&(filename$)

Descr. Returns the length of the given filename$ in bytes.

This function is used in place of Lof to retrieve the length of a file without first opening the file. A run-timeerror results if the file does not exist.

Example:

Sub Main()

'This example checks to see whether there is a C:\AUTOEXEC.BAT file'and, if there is, displays the length of the file.If (FileExists("C:\AUTOEXEC.BAT") And _

(FileLen("C:\AUTOEXEC.BAT") 0)) Thenb% = FileLen("C:\AUTOEXEC.BAT")MbeMessageBox "The length of Autoexec.Bat is: " + Str$(B)

ElseMbeMessageBox "File does not exist"

End IfEnd Sub

FileList

FileList array$() [,filespec$ [,include_attr% [,exclude_attr]]]

Descr. This statement fills an array with filenames from disk. The filenames must conform to an eightcharacter filename handle and three character filename extension (8.3 DOS format), or an MDL abort willoccur.

The array$() is any previously declared string array. The FileList function reallocates this array to exactlyhold all the files matching a given filespec$.

The filespec$ argument can include wild cards, such as * and ?. The * character matches any sequence ofzero or more characters, whereas the ? character matches any single character. Multiple *s and ?s can appearwithin the expression to form complete searching patterns. The following table shows some examples:

Thus, if filespec$ is not specified, * is used.

include_attr is a number indicating what types of files you want included in the list. Similarly, exclude_attrspecifies attributes of files you want excluded from the list. These numbers can be any combination of thefollowing:

This pattern Matches these files Doesn't match these files

*S*.TXTSAMPLE.TXTGOOSE.TXTSAMS.TXT

SAMPLESAMPLE.DAT

C*T.TXT CAT.TXTACATS.TXT CAP.TXT

C*T CATCAP.TXT CAT.DOC

C?TCATCUTCT

CAT.TXTCAPIT

* (All files)

Constant Value Includes

ebNormal 0 Read-only, archive, subdir, none

ebReadOnly 1 Read-only files

ebHidden 2 Hidden files

If include_attr is not specified, then the value 97 is used (ebReadOnly Or ebArchive Or ebNone). Ifexclude_attr is not specified, then hidden files and subdirectories are excluded from the list (18).

Example:


Sub Main()'This example fills an array a with the directory of the current drive'for all files that have normal or no attributes and excludes those'with system attributes. The dialog box displays four filenames from'the array.Dim a$()FileList a,"*.*", (ebNormal + ebNone), ebSystemIf ArrayDims(a) > 0 Then

MbeMessageBox a(1) + crlf + a(2) + crlf + a(3) + crlf + a(4)Else

MbeMessageBox "No files found"End If

End Sub

FileParse$

FileParse$(filename$[, operation])

Descr. This statement takes a filename and extracts a given portion of the filename from it.

filename$ can specify any valid filename (it does not have to exist). For example:

..\test.datC:\sheets\test.dattest.dat

The optional operation parameter specifies which portion of the filename$ to extract. It can be any of thefollowing values.

ebSystem 4 System files

ebVolume 8 Volume label

ebDirectory 16 DOS subdirectories

ebArchive 32 Files that have changed since the last backup

ebNone 64 Files with no attributes

0 Full name c:\sheets\test.dat

1 Drive c

2 Path c:\sheets

3 Name test.dat

4 Root test

5 Extension dat

If operation is not specified, then the full name is returned. A run-time error will result if operation is notone of the above values.

A runtime error results if filename$ is empty.

Example:


Sub Main()'This example parses the file string "C:\TestSub\Autoexec.Bat" into its'component parts and displays them in a dialog box.Dim a$(6)Dim i%For i = 1 To 5

a(i) = FileParse$("C:\TestSub\Autoexec.Bat",i-1)Next iMbeMessageBox a(1)+ crlf + a(2) + crlf + a(3) + crlf + a(4) + crlf + a(5)

End Sub

Fix

Fix%(number#)

Descr. Returns the integer part of number.

This function returns the integer part of the given value by removing the fractional part. The sign ispreserved

standard basic language

Documents