Functions

Parent page: EnableBasic

In Enable Basic, there are two main types of language elements:

• Functions - these elements perform an action and then return a value.
• Procedures - these perform actions but do not have any return value.

This section of the Enable Basic Reference details the functions and procedures supported by the Enable Basic scripting language.
 

Using Functions and Procedures

An Enable Basic macro script must define at least one procedure that defines the main program code. However, other procedures and functions can be defined that can be called by the code. Procedures that are called by other procedures or functions are called subprocedures.

The essentials:

• As with the main program code, subprocedures are defined within a Sub...End Sub statement block.
• Functions are defined within a Function...End Function statement block.
• Any subprocedures or functions used in a macro script must be defined after the main program procedure definition.
• To use (known as "calling") a function or subprocedure, include the name of the function or procedure in a statement in the same way that the built-in Enable Basic functions and procedures are used. If the function or procedure requires parameters, then these must be included in the calling statement.
• Both functions and subprocedures can be defined to accept parameters, but only functions can be defined to return a value to the calling statement.
• When calling a function, the statement containing the function call must be able to handle the return value. This is usually done by assigning the return value to a variable, or by using the return value in a calculated expression.
• Any name may be assigned when defining functions and procedures, as long as it conforms to the standard Enable Basic naming conventions.

Defining parameterized Functions and Procedures

Both the functions and subprocedures defined in a macro script can be declared to accept parameters. Additionally, functions are defined to return a value.

To define a parameterized function or subprocedure, list the variable names to be used to store the parameters as part of a Sub or Function statement. For example, the following code fragment defines a subprocedure that accepts two parameters, storing them in variables Param1 and Param2 respectively:

Sub mySub(Param1, Param2)

To call this subprocedure, the statement form woul be:

mySub Var1, Var2
...where Var1 and Var2 are to be passed to the subprocedure mySub.

Optionally in a Sub or Function, the data type of the parameters can be specified by including the As type clause in the parameter list. For example:

Sub mySub(Param1 As Integer, Param2 As String)

A valid call to this function would be:

mySub 5, "Hello"

As well as defining the data type of the parameters to be passed, how the parameters will be passed to the subroutine or function can be nominated. Enable Basic provides two methods of passing parameters to subprocedures or functions:

1. ByRef - passes a reference to the variable passed and allows the subprocedure or function to make changes to the actual variables that are passed in as parameters. This is the default method of passing parameters and is used if the method is not explicitly declared.
2. ByVal - passes the value of the variable only. The subprocedure or function can use this value, but the original variable passed is not altered.

For more information on using the ByRef and ByVal keywords, see the following section, Passing Parameters to Enable Basic Functions and Procedures.

Passing Parameters to functions and procedures

When a function or subprocedure that can accept parameters is defined in a script, variables can be passed to the function or subprocedure in two ways: by reference or by value.

To declare the method that parameters are passed, use the ByRef or ByVal keywords in the parameter list when defining the function or subprocedure in a Sub or Function statement. For example, the following code fragment defines a subprocedure that accepts two parameters. The first is passed by value and the second by reference:

Sub Test (ByVal Param1 As Integer , ByRef B As String)

The difference between the two methods is how the passed variable is handled:

• ByRef passes a reference to the variable, and allows the subprocedure or function to make changes to the actual variables that are passed in as parameters — this is the default method of passing parameters and is used if the method is not explicitly declared.
• ByVal passes the value of the variable only. The subprocedure or function can use this value, but the original variable passed is not altered.

The following examples illustrate the differences between methods. The main procedure is as follows:

 Sub Main  Dim X As Integer, Y As String  X = 45 : Y = "Number"  Test X, Y      ' Call to a subprocedure called Test.  Print X, Y End Sub 

The above procedure includes a call to subprocedure Test. If the subprocedure is defined as follows:

 Sub Test (ByRef A As Integer , ByRef B As String)  B = B & " = " & A : A = 10*A End Sub 

...then the variables X and Y in the main procedure are then referenced directly by the subprocedure. The result is that the values of X and Y are altered by the subprocedure, so that after Test is executed X = 450 and Y = "Number = 45".

If, however, the subprocedure is defined as follows:

 Sub Test (ByVal A As Integer , ByVal B As String)  B = B & " = " & A : A = 10*A End Sub 

...then after Test is executed X = 45 and Y = "Number" — that is, they remain unchanged.

Alternatively, if the subprocedure is defines as follows:

 Sub Test (ByRef A As Integer , ByVal B As String)  B = B & " = " & A : A = 10*A End Sub 

...then after Test is executed, X = 450 and Y = "Number". Because Y was passed by value, it remains unchanged.

The ByRef setting of a function or subprocedure can be overridden by putting parentheses around a variable name in the calling statement. Calling Test with the following statement:

Test (X), Y

...would pass the variable X by value, regardless of the method defined for that parameter in the procedure definition.

Calling Procedures in external DLLs

A function or procedure that is in an external dynamic linked library (DLL) can be called from an Enable Basic script by first defining the function or procedure using the Declare statement.

The Declare statement must by placed outside the main procedure in the Global Declarations section of the file. All declarations of external functions and procedures are Global. and accessible by all procedures and functions. If the call to the DLL returns a value it should be declared as a function, or otherwise declared as a subprocedure.

The following code segment declares a function called GetPrivateProfileString which resides in Kernel32.dll, which is part of the Windows system. The function takes six parameters and returns an integer value.

 Declare Function GetPrivateProfileString Lib "Kernel32" _  (ByVal lpApplicationName As String, ByVal lpKeyName As _  String, ByVal lpDefault As String, ByVal lpReturnedString _  As String, ByVal nSize As Integer, ByVal lpFileName As String)_  As Integer

The following code segment declares a subprocedure called InvertRect which is in User.dll — also part of the Windows system. The procedure takes two parameters, and being a subprocedure, it does not return any values.

Declare Sub InvertRect Lib "User" (ByVal hDC As Integer, _ aRect As Rectangle)

Once an external function or procedure is declared, it can be called in the same way as any other internal or user-defined function or procedure.

It is important to note that the Enable Basic interpreter cannot verify that an external DLL function or procedure has been declared using the correct name or parameters. Nor can it determine if the correct values have been passed to the external DLL. Before declaring and using an external function or subprocedure, it's important to understand the workings of the external function/procedure.
 

Enable Basic Functions

The following section details the Functions supported by Enable Basic, organized by application categories.

Dates and Times

Date

Description
This function returns a Date data type that contains the current date in the system short date format.
Syntax
Date
Parameters
No parameters.
Example
This example displays the current date in two formats.

 Sub Main  Dim Msg, NL, d1, d2  NL = Chr(10)       ' Define newline.  d1 = Date  d2 = Format (Date, "d-mmmm-yy")  Msg = "Date 1 is " & d1 & NL  Msg = Msg & "Date 2 is " & d2 & NL  MsgBox Msg End Sub 

Day

Description
This function returns an integer between 1 and 365, inclusive, that represents the day of the month given in DateVar$. To check that a string or string expression can be resolved to a valid date, use the IsDate function.
Syntax
Day(DateVar$)
Parameters
DateVar$ - a string or string expression that can be resolved to a valid date.
Example
The following example displays the current day, month and year is succession.

 Sub Main  MsgBox "The current day of the month is " & Day(Date)  MsgBox "The current month is " & Month(Date)  MsgBox "The current year is " & Year(Date) End Sub 

Hour

Description
This function returns an integer between 0 and 23 that is the hour of the day, indicated in the parameter TimeVar$. TimeVar$ must be able to be resolved into a valid time, for example "08:04:23 PM" or "20:04:23". The function returns an Integer data type.
Syntax
Hour(TimeVar$)
Parameters
TimeVar$ - a string expression that represents a valid time.
Example
This example displays the hours, minutes and seconds derived from a time string.

 Sub Main  MyTime = "08:04:23 PM"  MsgBox Second( MyTime ) & " Seconds" ' returns 23  MsgBox Minute( MyTime ) & " Minutes" ' returns 4  MsgBox Hour( MyTime ) & " Hours" ' returns 8 End Sub

IsDate

Description
Returns a value that indicates whether a variant parameter can be converted to a date. The function returns a Boolean TRUE if expression can be resolved to a valid date, or FALSE if it cannot.
Syntax
IsDate(expression)
Parameters
An expression to be validated.

Minute

Description
This function returns an integer between 0 and 59 representing the minute of the hour given in TimeVar$.TimeVar$ must be able to be resolved into a valid time, for example "08:04:23 PM" or "20:04:23".
Syntax
Minute(TimeVar$)
Parameters
TimeVar$ - a string expression that represents a valid time.
Example
This example displays the hours, minutes and seconds derived from a time string.

 Sub Main  MyTime = "08:04:23 PM"  MsgBox Second( MyTime ) & " Seconds" ' returns 23  MsgBox Minute( MyTime ) & " Minutes" ' returns 4  MsgBox Hour( MyTime ) & " Hours"     ' returns 8 End Sub 

Month

Description
This function returns an integer between 1 and 12 inclusive, representing the month of the year given in DateVar$. To check that a string or string expression can be resolved to a valid date, use the IsDate function.
Syntax
Month(DateVar$)
Parameters
DateVar$ - a string expression that can be resolved to a valid date.
Example
The following example displays the current day, month and year in succession.

 Sub Main  MsgBox "The current day of the month is " & Day(Date)  MsgBox "The current month is " & Month(Date)  MsgBox "The current year is " & Year(Date) End Sub 

Now

Description
This function returns a Date data type, which includes both the current date and time values.
Syntax
Now
Parameters
None

Second

Description
Returns an integer between 0 and 59 representing the seconds portion of the time given in TimeVar$. TimeVar$ must be able to be resolved into a valid time, for example "08:04:23 PM" or "20:04:23".
Syntax
Second(TimeVar$)
Parameters
TimeVar$ - a string or string expression that represents a valid time.
Example
This example displays the hours, minutes and seconds derived from a time string.

 Sub Main  MyTime = "08:04:23 PM"  MsgBox Second( MyTime ) & " Seconds" ' returns 23  MsgBox Minute( MyTime ) & " Minutes" ' returns 4  MsgBox Hour( MyTime ) & " Hours"     ' returns 8 End Sub 

Time

Description
The function returns the current system time in the default system short time format.
Syntax
Time
Parameters
None
Example
The following example gets the current system time and formats it for display in the Long Time format.

 Sub Main ' Returns current system time in the long time format.  MsgBox Format(Time, "Long Time") End Sub 

Year

Description
The function returns an integer that represents the year given in DateVar$. To check that a string or string expression can be resolved to a valid date, use the IsDate function.
Syntax
Year(DateVar$)
Parameters
DateVar$ - a string expression that can be resolved to a valid date.
Example
The following example displays the current day, month and year is succession.

 Sub Main  MsgBox "The current day of the month is " & Day(Date)  MsgBox "The current month is " & Month(Date)  MsgBox "The current year is " & Year(Date) End Sub 

IO

ChDir

Description
Changes the current default directory.
Syntax
ChDir PathName$
Parameters
PathName$ - a string or string expression, limited to fewer then 128 characters, identifying the path to target directory. If the drive letter is omitted from Pathname$, the function operates on the current drive.
Notes
To return the current default directory, use the CurDir and CurDrive functions.
Example
This example changes to the root directory and then back to the original directory.

 Sub Main ()  Dim Answer, Msg, NL       ' Declare variables.  NL = Chr(10)              ' Define newline.  CurPath = CurDir()        ' Get current path.  ChDir "\"                 ' Change to root directory  Msg = "The current directory has been changed to "  Msg = Msg & CurDir() & NL & NL & "Change back."  Answer = MsgBox(Msg)      ' Get user response.  ChDir CurPath             ' Change back to user default.  Msg = "Directory changed back to " & CurPath & "."  MsgBox Msg                ' Display results. End Sub 

ChDrive

Description
Changes the current default drive.
Syntax
ChDrive Drivename$
Parameters
DriveName$ - a string or string expression that references a valid drive.
Notes
Only a single letter is used by the ChDrive procedure to identify a target drive. If more than a single character is supplied as an argument, the procedure ignores all but the first character. Therefore the statements ChDrive("D:") and ChDrive("D") are equivalent. Both will change to the D: drive, however the colon in the first statement is ignored and is not necessary.
Example
This example changes to G: drive and back.

 Sub Main ()  Dim Msg, NL        ' Declare variables.  NL = Chr(10)       ' Define newline.  CurPath = CurDir() ' Get current path.  ChDrive "G"       ' Change to drive G:  Msg = "The current directory has been changed to "  Msg = Msg & CurDir() & NL & NL & "Change back."  MsgBox Msg         ' Get user response.  ChDir CurPath      ' Change back to user default.  Msg = "Directory changed back to " & CurPath & "."  MsgBox Msg ' Display results. End Sub 

Chr

Description
Converts an integer representing an ASCII character code into the corresponding character.
Syntax
Chr(int)
Parameters
int - an integer expression which represents an ASCII character code.
Notes
The function returns a string containing a single character whose character code is the int argument. To convert a single character string to an ASCII code, use the Asc function.
Example
This example prints all the letters of the alphabet into a message dialog.

 Sub ChrExample ()  Dim X, Msg  For X = Asc("A") To Asc("Z")   Msg = Msg & Chr(X)  Next X  MsgBox Msg End Sub 

Close #

Description
Closes all active input/output files.
Syntax
Close
Parameters
This procedure takes no parameters
Notes
Whenever a file is opened with the Open procedure, a Close statement must be issued after performing all file operations. This ensures the files are properly released by the program.
Example
This example creates three files, writes some text to these files and the closes the files.

 Sub Make3Files ()  Dim I, FNum, Fname    ' Declare variables.  For I = 1 To 3   FNum = FreeFile      ' Determine next file number.   FName = "TEST" & FNum   Open FName For Output As Fnum  ' Open file.   Print #I, "This is test #" & I ' Write string.   Print #I, "Here is another ";  "line";  I   Next I  Close                 ' Close all files. End Sub 

CurDir

Description
Returns the full path including drive name to the current directory.
Syntax
CurDir
Parameters
This function takes no parameters.
Notes
The function returns a String data type. The function is read only — to change the current drive and directory use the ChDrive and ChDir functions.
Example
The following example displays the current directory in a message box.

 Sub Form_Click ()  Dim Msg, NL        ' Declare variables.   NL = Chr(10)       ' Define newline.  Msg = "The current directory is: "  Msg = Msg & NL & CurDir  MsgBox Msg         ' Display message. End Sub 

EOF

Description
Returns a value (0 = false, -1 = true) during file input that indicates whether the end of the file has been reached.
Syntax
EOF(FileNumber)
Parameters
FileNumber - an integer that is the file number of an open input file.
Notes
The function returns a -1 value if the end of the file has been reached, otherwise it returns 0.
Example
This example uses the Input function to read 10 characters at a time from a file and display them in a message dialog. This example assumes that TESTFILE is a text file with a few lines of sample data.

 Sub Main  Open "TESTFILE" For Input As #1  Do While Not EOF(1)         ' Loop until end of file.   MyStr = Input(10, #1)     ' Get ten characters.   MsgBox MyStr  Loop  Close #1                    ' Close file. End Sub 

Erase

Description
Reinitializes the elements of a fixed array.
Syntax
Erase arrayname
Parameters
arrayname - the name of an array variable. Specify the array name only, without any subscripts or parentheses.
Notes
Reinitializing an array sets all elements in the array to 0 for numeric arrays, or a null string for string arrays.
Example
This example defines two arrays, one integer and one string and assigns values to them. The Erase procedure is then used to reinitialize the arrays.

 Sub Main  Dim IntArray(2) As Integer, StrArray(2) As String  Dim I As Integer  ' Initialize the arrays  For I = 0 to 2   IntArray(I) = I+1  Next I  StrArray(0) = "Goodbye"  StrArray(1) = "cruel"  StrArray(2) = "world\!"  ' Display the arrays  Print IntArray(0), IntArray(1), IntArray(2)  Print StrArray(0), StrArray(1), StrArray(2)  ' Reinitialize the arrays  Erase IntArray  Erase StrArray  ' Redisplay the arrays  Print IntArray(0), IntArray(1), IntArray(2)  Print StrArray(0), StrArray(1), StrArray(2) End Sub 

FileLen

Description
Returns a long integer that is the length of the file in bytes. This function returns a Long data type. If the file does not exist, the function returns -1.
Syntax
FileLen(FileName$)
Parameters
FileName$ - a string or string expression that contains the filename and path of the file to be tested.
Example
The following example displays the size of a config.sys file.

 Sub Main()  Dim myFile$, Size&  myFile$ = "C:\config.sys"  Size& = FileLen(myFile$)  If Size& = \-1 Then        ' Test that file was found   MsgBox "Could not find file."  Else   MsgBox "Config file is " & Size& & " bytes"  End If End Sub 

FileCopy

Description
Copies a file from source to destination.
Syntax
FileCopy SourceFile$, DestinationFile$
Parameters
SourceFile$ - a string expression containing the file name, including full path if not in the current directory, of the file to copy.
DestinationFile$ - a string expression containing the path and file name for the copied file.
Notes
For both SourceFile$ and DestinationFile$ you must specify a name for the file, even if the destination file is to be of the same name as the original. If the source or destination is not the current directory, you must specify the path as part of the SourceFile$ and/or DestinationFile$ strings.
Note that it's important to independently determine if the source file exists, as the FileCopy function does not test for this. If SourceFile$ does not exist, the statement will create a zero length file of the name, at the location given by DestinationFile$. If DestinationFile$ already exists, it will not be overwritten. If the path specified in DestinationFile$ does not exist, it will not be created.
Example
The following example copies the file test.txt from the temp1 directory on C: drive to the temp2 directory. The copied file is given the name newname.txt. The below example assumes C:\temp1\test.txt exists and that the directory
C:\temp2 has been created.

 Sub ExpExample ()  Dim mySource, myDestination As String  mySource = "C:\temp1\test.txt"  myDestination = "C:\temp2\newname.txt"  FileCopy mySource, MyDestination End Sub 

Input #

Description
Input returns a defined number of characters from a sequential file.
Syntax
Input(numBytes , [#]FileNumber)
Parameters
numBytes - numeric expression representing the number of bytes to be read from the file.
FileNumber - the file number used in the Open statement to open the file.
Notes
The file referenced by FileNumber must be opened for input using an Open statement before it can be used by the Input function. The function returns a String data type.
Example
This example assumes that a file called TESTFILE exists in the current directory.

 Sub Main  Open "TESTFILE" For Input As #1   ' Open file.  Do While Not EOF(1)               ' Loop until end of file.   MyStr = Input(10, #1)        ' Get ten characters.   MsgBox MyStr  Loop  Close #1                           ' Close file. End Sub 

Kill

Description
This procedure is used to delete a file from a disk.
Syntax
Kill FileName$
Parameters
FileName$ - a string expression that contains the full filename and path of a file to delete.
Notes
This procedure is only used to remove files. To remove a directory, use the RmDir procedure.
Example
The following example creates three test files in the current directory, and then deletes them.

 Const NumberOfFiles = 3  Sub Main ()  Dim Msg, J  Msg = "Creating test files in the "  Msg = Msg & CurDir & " directory."  Msg = Msg & Chr(10) & "Files will be deleted after use."  If MsgBox(Msg, 1, "Test") = 1 Then     Call MakeFiles()          ' Create data files.     Msg = "Three test files have been created on your disk "     Msg = Msg & "in " & CurDir & Chr(10)     Msg = Msg & "Choose OK to remove these files."     If MsgBox(Msg, 1, "Remove files?") = 1 Then        For J = 1 To NumberOfFiles            Kill "TEST" & J       ' Remove data files from disk.        Next J     MsgBox "Files have been removed."     End If  End If End Sub ' Function to generate test files Sub MakeFiles ()  Dim I, FNum, FName  For I = 1 To NumberOfFiles      FNum = FreeFile       ' Determine next file number.      FName = "TEST" & I      Open FName For Output As FNum      ' Open file.      Print #FNum, "This is test #" & I      Print #FNum, "Here is another ";  "line";  I  Next I  Close                     ' Close all files. End Sub 

Line Input #

Description
Reads a line from a sequential file into a String or Variant variable.
Syntax
Line Input #FileNumber, VarName
Parameters
FileNumber - the number used in an Open statement to open the file.
VarName - the name of a string or variant variable to hold the line of text.
Notes
The file referred to by FileNumber must be opened for input using an Open statement prior to using this function.
Example
This example assumes a file called TESTFILE exists in the current directory.

 Sub Main  Open "TESTFILE" For Input As #1   ' Open file.  Do While Not EOF(1)               ' Loop until end of file.   Line Input #1, TextLine          ' Read line into variable.   Print TextLine                   ' Print to Debug window.  Loop  Close #1                          ' Close file. End Sub 

MkDir

Description
Creates a new directory within an existing directory.
Syntax
MkDir Path$
Parameters
Path$ - a string expression of less than 128 characters that represents the path and name of the directory to create.
Notes
You can only use MkDir to create a new directory within a directory that already exists. You cannot create multiple directories in a hierarchy with a single MkDir statement. For example, if the directory C:\TEST does not exist, then the statement MkDir "C:\TEST\SUBTEST" would not perform any action. The directory C:\TEST and then C:\TEST\SUBTEST would need to be created sequentially.
If Path$ already exists, the procedure performs no action.
Example
This example creates a directory on C: drive called NewDir1 and then creates a subdirectory under this called NewDir2. The macro then removes the newly created directories.

 Sub Main    Dim DST As String     DST = "C:\NewDir1"    If MsgBox("OK to create test directories?", 1, "New Dir") = 1 Then     MkDir DST     MsgBox "New directory has been created on C:"     MkDir "C:\NewDir1\NewDir2"     MsgBox "A new subdirectory has been created."     If MsgBox("OK to delete test directories?", 1, "Del Dir") = 1 Then      RmDir "C:\NewDir1\NewDir2"      RmDir DST      MsgBox "Test directories removed."     End If    End If End Sub 

Open #

Description
Opens a file for sequential input and output operations.
Syntax
Open FileName$ [For mode] [Access access] As [#]FileNumber
Parameters
FileName$ - a string expression that contains the filename and path.
mode - keyword that specifies the file mode: Append, Input, Output
access - keyword that specifies which operations are permitted on the file: Read, Write, Read Write.
FileNumber - integer expression with a value between 1 and 255, inclusive. When an Open statement is executed, filenumber is associated with the file as long as it is open. Other I/O statements can use the number to refer to the file.
Notes
A file must be open before any I/O operation can be performed on it. If FileName$ doesn't exist, it is created when a file is opened for Append or Output modes. If the file is already opened by another process and the specified type of access is not allowed, the Open operation fails with a permission denied error.

mode =
Input - Sequential input mode. Data can be read from the file.
Output - Sequential output mode. Data can be written to the file.
Append - Append sets the file pointer to the end of the file. A Print # or Write # statement then adds to (appends to) the file.

access =
Read - Opens the file for reading only.
Write - Opens the file for writing only.
Read Write - Opens the file for both reading and writing. This mode is valid only for files opened for Append mode.

Example
The following example creates a file called TESTFILE in the current directory, gets input from the user, and writes this to the file. The program then reads the data in the file and displays it.

 Sub Main () ' Create a test file and write some date to it  Open "TESTFILE" For Output As #1 ' Open to write file.  userData1$ = InputBox ("Enter your own text here")  userData2$ = InputBox ("Enter more of your own text here")  Write #1, "This is a test file."  Write #1, userData1$  Write #1, userData2$  Close #1 ' Read the data back from the test file  Open "TESTFILE" For Input As #2 ' Open to read file.  Msg$ = ""  Do While Not EOF(2)   Line Input #2, FileData ' Read a line of data.   Msg$ = Msg$ & FileData & Chr(10) ' Construct message.  Loop  Close #2  ' Close all open files.  MsgBox Msg$ ' Display file contents  Kill "TESTFILE" ' Remove file from disk. End Sub 

Print #

Description
Writes data to a sequential file.
Syntax
Print #FileNumber, [OutputList]
Parameters
FileNumber - the file number associated with the file to print to.
OutputList - list of expressions to print (see below)

The OutputList argument takes the following format:
[{Spc(n) | Tab[(n)]}] [expression] [charpos]
...where;
Spc(n) - Used to insert space characters in the output, where n is the number of space characters to insert.
Tab(n) - Used to position the insertion point to an absolute column number, where n is the column number. Use Tab with no argument to position the insertion point at the beginning of the next print zone.
Expression - Numeric expressions or string expressions to print.
charpos - Specifies the insertion point for the next character. Use a semicolon to position the insertion point immediately after the last character displayed. Use Tab(n) to position the insertion point to an absolute column number. Use Tab with no argument to position the insertion point at the beginning of the next print zone. If charpos is omitted, the next character is printed on the next line.

Notes
If you omit OutputList and include only a list separator after FileNumber, a blank line is printed to the file. Multiple expressions can be separated with either a space or a semicolon. A space has the same effect as a semicolon.
The Print # statement usually writes a Variant data type to a file the same way it writes any other data type. However, there are some exceptions:
If the data being written is a Variant of VarType 0 (Empty), Print # writes nothing to the file for that data item.
If the data being written is a Variant of VarType 1 (Null), Print # writes the literal #NULL# to the file.
If the data being written is a Variant of VarType 7 (Date), Print # writes the date to the file using the system Short Date format. When either the date or the time component is missing or zero, Print # writes only the part provided to the file.
Example
The following example prints lines of date to a sequential file:

 Sub Main   Dim I, FNum, FName ' Declare variables.  For I = 1 To 3   FNum = FreeFile ' Determine next file number.   FName = "TEST" & FNum   Open FName For Output As FNum ' Open file.   Print #I, "This is test #" & I ' Write string to file.   Print #I, "Here is another ";  "line";  I  Next I  Close ' Close all files. End Sub 

RmDir

Description
Removes an existing empty directory.
Syntax
RmDir DirName$
Parameters
DirName$ - a string expression that contains the name and path to the directory to be removed.
Notes
If the directory listed in DirName$ does not exist, the procedure takes no action. If the directory referred to in DirName$ contains files, then no action is taken. To remove a directory it must first be empty.
Example
This example creates a directory on C: drive called NewDir1 and then creates a subdirectory under this called NewDir2. The macro then removes the newly created directories.

 Sub Main    Dim DST As String     DST = "C:\NewDir1"    If MsgBox("OK to create test directories?", 1, "New Dir") = 1 Then     MkDir DST     MsgBox "New directory has been created on C:"     MkDir "C:\NewDir1\NewDir2"     MsgBox "A new subdirectory has been created."     If MsgBox("OK to delete test directories?", 1, "Del Dir") = 1 Then      RmDir "C:\NewDir1\NewDir2"      RmDir DST      MsgBox "Test directories removed."     End If    End If End Sub 

Seek #

Description
The function form of Seek returns the byte position of the file pointer in an open file. This marks the current read/write position in the file.
The procedure form of Seek sets the read/write position of an open file.
Syntax
Seek([#]FileNumber)
Seek [#]FileNumber, Position
Parameters
FileNumber - a numeric expression that represents a number used in the Open # statement.
Position - a numeric expression representing the byte position relative to the beginning of the file.
Notes
The function form of Seek returns a Long data type. The FileNumber parameter must reference a currently open file.
Example
The following examples assume that a file called TESTFILE containing several lines of data exists in the current directory. This example uses the function form of Seek to print the current byte position.

 Sub SeekFunction   Open "TESTFILE" For Input As #1 ' Open file for reading.   Do While Not EOF(1)             ' Loop until end of file.    MyChar = Input(1, #1)          ' Read next character of data.    Print Seek(1)                  ' Print byte position.   Loop   Close #1                        ' Close file. End Sub  This example uses the procedure form of Seek to move through the data. Sub SeekProcedure   Open "TESTFILE" For Input As #1 ' Open file for reading.   For i = 1 To 24 Step 3          ' Loop until end of file.    Seek #1, I                     ' Seek to byte position     MyChar = Input(1, #1)          ' Read next character of data.    Print MyChar                   ' Print character of data.   Next i    Close #1                        ' Close file. End Sub 

Write #

Description
Writes and formats data to a sequential file that has been opened in Output or Append mode.
Syntax
Write #FileNumber [, paramrlist ]
Parameters
FileNumber - a valid file number that references a file opened with the Open # statement.
paramlist - a comma-delimited list of numeric or string expressions to write to the file.
Notes
A comma delimited list of the supplied parameters is written to the indicated file. If no parameters are present, the newline character is all that will be written to the file.
Example
The following example creates a file called TESTFILE in the current directory and then gets input from the user and writes this to the file. The program then reads the data in the file and displays it.

 Sub Main () ' Create a test file and write some date to it  Open "TESTFILE" For Output As #1 ' Open to write file.  userData1$ = InputBox ("Enter your own text here")  userData2$ = InputBox ("Enter more of your own text here")  Write #1, "This is a test file."  Write #1, userData1$  Write #1, userData2$  Close #1 ' Read the data back from the test file  Open "TESTFILE" For Input As #2 ' Open to read file.  Msg$ = ""  Do While Not EOF(2)   Line Input #2, FileData ' Read a line of data.   Msg$ = Msg$ & FileData & Chr(10) ' Construct message.  Loop  Close #2  ' Close all open files.  MsgBox Msg$ ' Display file contents  Kill "TESTFILE" ' Remove file from disk. End Sub 

Maths

Cos

Description
Returns the cosine of an angle. The argument must be expressed in radians and must be a valid numeric expression. The function returns a Double data type.
Syntax
Cos (number)
Parameters
number - a numeric variable, constant or expression.
Example
The example displays the cosine of 1, 2, 3 radians.

 Sub Main()  Dim I As Single            'Declare variables.  For I =1 To 3   Msg = Msg & "Cos(" & I & ")="   Msg = Msg & Cos(I) & " " 'Cos function call  Next I  MsgBox Msg                 ' Display results. End Sub 

Exp

Description
Returns the base of the natural log raised to a power (e^ num).
Syntax
Exp(num)
Parameters
num - number or numeric expression.
Notes
The value of the constant e is approximately 2.71828. This function returns a Double data type.
Example
This example calculates the value of the constant e.

 Sub ExpExample ()   ' Exp(x) is e ^x so Exp(1) is e ^1 or e.   Dim Msg, ValueOfE      ' Declare variables.   ValueOfE = Exp(1)      ' Calculate value of e.   Msg = "The value of e is " & ValueOfE   MsgBox Msg End Sub 

Log

Description
Returns the natural log of a number.
Syntax
Log(num)
Parameters
num - a numerical expression. The number must greater than zero.
Notes
The base for the natural log is the constant e, which is approximately 2.71828. This function returns a Double data type.

Not

Description
Returns the Boolean opposite of expression.
Syntax
Not(expression)
Parameters
expression - an expression that resolves to a Boolean TRUE or FALSE.
Notes
The expression parameter must be able to be resolved to a TRUE or FALSE value. A numeric 0 value is the equivalent of a Boolean FALSE. Any non-zero numeric value resolves to a Boolean TRUE.

Oct

Description
Returns the octal value of the decimal parameter. The function returns a String data type which is the octal representation of the argument.
Syntax
Oct(num)
Parameters
num - a numeric expression.

Rnd

Description
Returns a random number between 0 and 1. The function returns a Double data type whose value is randomized between 0 and 1.
Syntax
Rnd
Parameters
None
Example
The example uses the Rnd function to simulate rolling a pair of dice by generating random values from 1 to 6.

 Sub Main ()  Dim Dice1, Dice2, Msg, Again  Again = True  While Again   MsgBox "Press OK to roll the dice"   Dice1 = CInt(5 * Rnd) + 1    ' Generate first die value.   Dice2 = CInt(5 * Rnd) + 1    ' Generate second die value.   Msg = "You rolled a " & Dice1   Msg = Msg & " and a " & Dice2   Msg = Msg & " for a total of "   Msg = Msg & Str(Dice1 + Dice2) & "." & Chr(10)   Msg = Msg & Chr(10) & "Roll again?"   If MsgBox(Msg, 36, "Roll dice") = 7 Then    Again = False   End If  Wend End Sub 

Sin

Description
Returns the sine of an angle. The argument must be expressed in radians and must be a valid numeric expression. The function returns a Double data type.
Syntax
Sin(number)
Parameters
number - a numeric variable, constant or expression.
Example

 Sub Main ()  pi = 4 * Atn(1)  rad = 90 * (pi/180)  x = Sin(rad)  Print x End Sub 

Sqr

Description
Returns the square root of a number.
Syntax
Sqr(num)
Parameters
num - a positive number or numeric expression. The parameter num must be a valid number greater than or equal to zero.
Notes
The function returns a Double data type representing the square root of num.

Tan

Description
Returns the tangent of an angle.
Syntax
Tan(number)
Parameters
number - a numeric expression.
Notes
The argument must be expressed in radians and must be a valid numeric expression. The function returns a Double data type.
Example
The following example calculates the tangent of Pi/4 radians.

 Sub Main  Dim Msg, Pi  Pi = 4 * Atn(1)     ' Calculate Pi.  Msg = "Pi is equal to " & Pi  MsgBox Msg  x = Tan(Pi/4)  MsgBox  x & " is the tangent of Pi/4" End Sub 

Strings

LCase

Description
Returns a string in which all letters of the string$ parameter have been converted to lower case.
Syntax
LCase(string$)
Parameters
string$ - a string or string expression.
Notes
The function returns a String data type.

Len

Description
Returns the number of characters in a string.
Syntax
Len(string$)
Parameters
string$ - a string expression.
Notes
The function returns an Integer data type representing the length of the string.

Left

Description
Returns the left most number of characters of a string parameter.
Syntax
Left(string$, chars)
Parameters
string$ - a string expression.
chars - the number of characters to return.
Notes
The function returns a String data type. If chars is greater than the number of characters in the string, then the whole string is returned.
Example
This example shows the use of the Left and Right string functions.

 Sub Main ()  myString = "Hello out there"  MsgBox Left(myString, 5)    ' Returns "Hello"  MsgBox Mid(myString, 7, 3)  ' Returns "out"  MsgBox Right(myString, 5)   ' Returns "there" End Sub 

Mid

Description
Returns a substring within a string.
Syntax
Mid(String$, StartPos, NumChar)
Parameters
String$ - a string expression.
StartPos - a numeric expression that gives the start position within Str$ for the return substring. StartPos is the number of characters from the start of Str$.
NumChar - a numeric expression that represents the number of characters to return.
Notes
The function returns a String data type. If StartPos is greater than the length of String$, a null string is returned. If NumChar extends beyond the end of String$, all characters from StartPos to the end of String$ are returned.
Example
This example shows the use of the Left and Right string functions.

 Sub Main ()  myString = "Hello out there"  MsgBox Left(myString, 5)    ' Returns "Hello"  MsgBox Mid(myString, 7, 3)  ' Returns "out"  MsgBox Right(myString, 5)   ' Returns "there" End Sub 

Right

Description
Returns a number of characters from the end of the string parameter.
Syntax
Right(string$, chars )
Parameters
string$ - a string or string expression.
chars - an integer expression defining the number of characters to return.
Notes
The function returns a String data type which is the right-most chars characters of string$. If chars is greater than the length of string$, then the return value is string$.
Example
This example shows the use of the Left and Right string functions.

 Sub Main ()  myString = "Hello out there"  MsgBox Left(myString, 5)    ' Returns "Hello"  MsgBox Mid(myString, 7, 3)  ' Returns "out"  MsgBox Right(myString, 5)   ' Returns "there" End Sub 

Str

Description
Returns the value of a numeric expression as a string.
Syntax
Str(number)
Parameters
number - a number or numeric expression.
Notes
The function returns a String data type.
Example
The following example determines the position of a particular digit in a number by converting the number to a string and then using the InStr search function.

 Sub main ()  Dim a As Long  Dim x As Integer  Dim aStr As String  a = 16374859  aStr = Str(a)            ' Convert a to a string.  x = InStr(1, aStr, "7")  ' Search for a particular digit.  MsgBox "7 is digit number " & x & " in " & aStr End Sub 

Trim, LTrim, RTrim

Description
LTrim, RTrim and Trim all return a copy of a string with leading, trailing or both leading and trailing spaces removed.
Syntax
[L | R]Trim (String$ )
Parameters
String$ - a string or string expression.
Notes
Ltrim removes leading spaces. Rtrim removes trailing spaces. Trim removes leading and trailing spaces. All functions return a String data type.
Example
This example uses the LTrim and RTrim functions to strip leading and trailing spaces, respectively, from a string variable. It also uses the Trim function alone to strip both types of spaces.

 Sub Main  MyString = "    <-Trim->    "  ' Initialize string.  TrimString = LTrim(MyString)  MsgBox "\|" & TrimString & "\|"  TrimString = RTrim(MyString)  MsgBox "\|" & TrimString & "\|"  TrimString = LTrim(RTrim(MyString))  MsgBox "\|" & TrimString & "\|" ' Using the Trim function alone achieves the same result ' as the previous statement.  TrimString = Trim(MyString)  MsgBox "\|" & TrimString & "\|" End Sub 

UCase

Description
Returns a string in which all letters of the string$ parameter have been converted to upper case.
Syntax
UCase(string$)
Parameters
string$ - a string expression.
Notes
The function returns a String data type.

Enable Basic Extensions

AltKeyDown

Description
Returns a value that indicates the state of the ALT key.
Syntax
AltKeyDown
Parameters
This function takes no parameters.
Notes
The function returns 1 if the ALT key is down, otherwise it returns 0. Use the CBool function to convert the return value to a TRUE or FALSE.

ConfirmNoYes

Description
Displays a message dialog with a YES button and NO button. The title of the message box is "Confirm".
Syntax
ConfirmNoYes Message$, IntVar
Parameters
Message$ - a string expression to be used as the displayed message.
IntVar - a valid integer variable name which is used to store the value of the key pressed.
Notes
When the user exists the message box, the variable IntVar is set to 1 if the YES button was clicked, or 0 if the NO button was clicked.
The variable IntVar must be declared as an Integer data type before calling the function.
Example
The following example displays an Altium Designer confirmation dialog. If the user clicks the YES button, a message is displayed.

 Sub Main  Dim myVal As Integer  ConfirmNoYes "Do you want to display a message?", myVal  If myVal = 1 Then            ' If the user presses YES   MsgBox "You pressed the YES button"  End If End Sub 

ConfirmNoYesCancel

Description
Displays a message dialog with a YES button, NO button, CANCEL button and question mark icon.
Syntax
ConfirmNoYesCancel Message$, IntVar
Parameters
Message$ - a string expression to be used as the displayed message.
IntVar - a valid integer variable name which is used to store the value of the key pressed.
Notes
When the user exits the message box, the variable IntVar is set to 6 if the YES button was clicked, 7 if the NO button was clicked, or 2 if the CANCEL button was clicked.
The variable IntVar must be declared as an Integer data type before calling the function.
Example
The following example displays an Altium Designer confirmation dialog and displays a message if the YES or NO buttons are pressed.

 Sub Main  Dim myVal As Integer  ConfirmNoYesCancel "Click YES or NO to display a message?", myVal  Select Case myVal   Case 6   ' YES button pressed    MsgBox "You pressed the YES button"   Case 7   ' NO button pressed    MsgBox "You pressed the NO button"  End Select End Sub 

GetCurrentWindowHandle

Description
Returns an integer representing the system ID handle of the currently active window.
Syntax
GetCurrentWindowHandle IntVar
Parameters
IntVar a previously declared variable of Integer data type in which to store the ID handle.
Notes
Whenever the Windows operating system creates a display window, it creates a unique ID number for the window. This extension allows you to determine the Windows ID number for the active window.
The number returned by this extension is not used directly by any other Enable Basic function, procedure or extension. It may be useful, however, if you are declaring functions within the Windows system DLLs for use with your macro.

ResetCursor

Description
Changes the cursor to the default arrow cursor.
Syntax
ResetCursor
Parameters
This extension takes no parameters.

RunApplication

Description
Runs an application program.
Syntax
RunApplication AppName$
Parameters
AppName$ - a string expression containing the name and path of an executable program file.
Notes
This extension uses the RunApplication process to run an executable file. This extension has the same function as the Shell procedure.
Example
This example runs the Notepad application.

 Sub Main  RunApplication "NOTEPAD.EXE" End Sub 

SetCursorBusy

Description
Changes the cursor to the default busy cursor.
Syntax
SetCursorBusy
Parameters
This extension takes no parameters
Notes
Use ResetCursor to reset the cursor to its default arrow icon.

ShiftKeyDown

Description
Returns a value that indicates the state of the SHIFT key.
Syntax
ShiftKeyDown
Parameters
None
Notes
The function returns 1 if the SHIFT key is down, otherwise it returns 0. Use the CBool function to convert the return value to a TRUE or FALSE.

ShowError

Description
Displays a warning dialog containing an OK button and the warning icon.
Syntax
ShowError Message$
Parameters
Message$ - a string expression containing the message to display in the warning box.
Notes
This extension displays a warning message. It does not cause an error to be generated.
This extension is identical to the ShowWarning extension.

ShowInfo

Description
Displays an information dialog containing an OK button and the information icon.
Syntax
ShowInfo Message$
Parameters
Message$ - a string expression containing the message to display in the information box.

ShowWarning

Description
Displays a warning dialog containing an OK button and the warning icon.
Syntax
ShowWarning Message$
Parameters
Message$ - a string expression containing the message to display in the warning box.
Notes
This extension is identical to the ShowError extension.