Mci (function)
Syntax
Mci(command$,result$ [,error$])
Description
Executes an Mci command, returning an Integer indicating whether the command was successful.
Comments
The Mci function takes the following parameters:
Parameter
command$
result$
Description
String containing the command to be executed.
String variable into which the result is placed. If the command doesn’t return
anything, then a zero-length string is returned.To ignore the returned string,
pass a zero-length string: r% = Mci(“open chimes.wav type
waveaudio”,””)
error$
Optional String variable into which an error string will be placed. A zero-length
string will be returned if the function is successful.
The Mci function returns 0 if successul. Otherwise, an non-zero Integer is returned indicating the
error.
Examples
‘This first example plays a wave file. The wave file is
‘played to completion before execution can continue.
Sub Main()
Dim result As String
Dim ErrorMessage As String
Dim Filename As String
Dim rc As Integer
‘Establish name of file in the Windows directory.
Filename = FileParse$(System.WindowsDirectory$ + “\” + _
“chimes.wav”)
‘Open the file and driver.
rc = Mci(“open “ & Filename & _
“ type waveaudio alias CoolSound”,””,ErrorMessage)
If (rc) Then
‘Error occurred—display error message to user.
MsgBox ErrorMessage
Exit Sub
End If
rc = Mci(“play CoolSound wait”,””,””)
‘Wait for sound
‘to finish.
rc = Mci(“close CoolSound”,””,””) ‘Close driver and file.
End Sub
325
‘This next example shows how to query an Mci device and play an
‘MIDI file in the background.
Sub Main()
Dim result As String
Dim ErrMsg As String
Dim Filename As String
Dim rc As Integer
‘Check to see whether MIDI device can play for us.
rc = Mci(“capability sequencer can play”,result,ErrorMessage)
‘Check for error.
If rc Then
MsgBox ErrorMessage
Exit Sub
End If
‘Can it play?
If result <> “true” Then
MsgBox “MIDI device is not capable of playing.”
Exit Sub
End If
‘Assemble a filename from the Windows directory.
Filename = FileParse$(System.WindowsDirectory$ & “\” & _
“canyon.mid”)
‘Open the driver and file.
rc = Mci(“open “ & Filename & _
“ type sequencer alias song”,result$,ErrMsg)
If rc Then
MsgBox ErrMsg
Exit Sub
End If
rc = Mci(“play song”,””,””)
‘Play in the background.
MsgBox “Press OK to stop the music.”,ebOKOnly
rc = Mci(“close song”,””,””)
End Sub
See Also
Beep (statement).
Platform Notes: Windows
The Mci function accepts any Mci command as defined in the Multimedia Programmers Reference in the Windows 3.1 SDK.
326
Menu (statement)
Syntax
Menu MenuItem$
Description
Issues the specified menu command from the active window of the active application.
Comments
The MenuItem$ parameter specifies the complete menu item name, with each menu level being
separated by a period. For example, the “Open” command on the “File” menu is represented by
“File.Open”. Cascading menu items may have multiple periods, one for each pop-up menu, such as
“File.Layout.Vertical”. Menu items can also be specified using numeric index values. For example,
to select the third menu item from the File menu, use “File.#3”. To select the fourth item from the
third menu, use “#3.#4”.
Items from an application’s system menu can be selected by beginning the menu item specification with a period, such as “.Restore” or “.Minimize”.
A runtime error will result if the menu item specification does not specify a menu item. For example, “File” specifies a menu pop-up rather than a menu item, and “File.Blah Blah” is not a valid
menu item.
When comparing menu item names, this statement removes periods (.), spaces, and the ampersand. Furthermore, all characters after a backspace or tab are removed. Thus, the menu item
“&Open...\aCtrl+F12” translates simply to “Open”.
A runtime error is generated if the menu item cannot be found or is not enabled at the time that this
statement is encountered.
Examples
Sub Main()
Menu “File.Open”
Menu “Format.Character.Bold”
Menu “.Restore”
‘Command from system menu
Menu “File.#2”
End Sub
See Also
MenuItemChecked (function); MenuItemEnabled (function); MenuItemExists (function).
327
MenuItemChecked (function)
Syntax
MenuItemChecked(MenuItemName$)
Description
Returns True if the given menu item exists and is checked; returns False otherwise.
Comments
The MenuItemName$ parameter specifies a complete menu item or menu item pop-up following
the same format as that used by the Menu statement.
Example
‘This example turns the ruler off if it is on.
Sub Main()
If MenuItemChecked(“View.Ruler”) Then Menu “View.Ruler”
End Sub
See Also
Menu (statement); MenuItemEnabled (function); MenuItemExists (function).
MenuItemEnabled (function)
Syntax
MenuItemEnabled(MenuItemName$)
Description
Returns True if the given menu item exists and is enabled; returns False otherwise.
Comments
The MenuItemName$ parameter specifies a complete menu item or menu item pop-up following
the same format as that used by the Menu statement.
Example
‘This example only pastes if there is something in the Clipboard.
Sub Main()
If MenuItemEnabled(“Edit.Paste”) Then
Menu “Edit.Paste”
Else
MsgBox “There is nothing in the Clipboard.”,ebOKOnly
End If
End Sub
See Also
Menu (statement); MenuItemChecked (function); MenuItemExists (function).
328
MenuItemExists (function)
Syntax
MenuItemExists(MenuItemName$)
Description
Returns True if the given menu item exists; returns False otherwise.
Comments
The MenuItemName$ parameter specifies a complete menu item or menu item pop-up following
the same format as that used by the Menu statement.
Examples
Sub Main()
If MenuItemExists(“File.Open”) Then Beep
If MenuItemExists(“File”) Then MsgBox _
“There is a File menu.”
End Sub
See Also
Menu (statement); MenuItemChecked (function); MenuItemEnabled (function).
329
Mid, Mid$, MidB, MidB$ (functions)
Syntax
Mid[$](string, start [,length])
MidB[$](string, start [,length])
Description
Returns a substring of the specified string, beginning with start, for length characters (for Mid and
Mid$) or bytes (for MidB and MidB$).
Comments
The Mid and Mid$ functions return a substring starting at character position start and will be
length characters long. The MidB and MidB functions return a substring starting at byte position
start and will be length bytes long.
The Mid$ and MidB$ functions return a String, whereas the Mid and MidB functions return a
String variant.
These functions take the following named parameters:
Named Parameter
string
start
length
Description
Any String expression containing the text from which data are returned.
Integer specifying the position where the substring begins. If start is
greater than the length of string, then a zero-length string is returned.
Integer specifying the number of characters or bytes to return. If this
parameter is omitted, then the entire string is returned, starting at start.
The Mid function will return Null if string is Null.
The MidB and MidB$ functions are used to return a substring of bytes from a string containing
byte data.
Example
‘This example displays a substring from the middle of a
‘string variable using the Mid$ function and replaces the
‘first four characters with “NEW “ using the Mid$ statement.
Const crlf = Chr$(13) + Chr$(10)
Sub Main()
a$ = “This is the Main string containing text.”
b$ = Mid$(a$,13,Len(a$))
Mid$ (b$,1) = NEW “
MsgBox a$ & crlf & b$
End Sub
See Also
InStr, InStrB (functions); Option Compare (statement); Mid, Mid$, MidB, MidB$ (statements).
330
Mid, Mid$, MidB, MidB$ (statements)
Syntax
Mid[$](variable,start[,length]) = newvalue
MidB[$](variable,start[,length]) = newvalue
Description
Replaces one part of a string with another.
Comments
The Mid/Mid$ statements take the following parameters:
Parameter
variable
start
length
newvalue
Description
String or Variant variable to be changed.
Integer specifying the character position (for Mid and Mid$) or byte position
(for MidB and MidB$) within variable where replacement begins. If start is
greater than the length of variable, then variable remains unchanged.
Integer specifying the number of characters or bytes to change. If this parameter is omitted, then the entire string is changed, starting at start.
Expression used as the replacement. This expression must be convertible to
a String.
The resultant string is never longer than the original length of variable.
With Mid and MidB, variable must be a Variant variable convertible to a String, and newvalue is
any expression convertible to a string. A runtime error is generated if either variant is Null.
The MidB and MidB$ statements are used to replace a substring of bytes, whereas Mid and Mid$
are used to replace a substring of characters.
Example
‘This example displays a substring from the middle of a
‘string variable using the Mid$ function, replacing the
‘first four characters with “NEW “ using the Mid$ statement.
Const crlf = Chr$(13) + Chr$(10)
Sub Main()
a$ = “This is the Main string containing text.”
b$ = Mid$(a$,13,Len(a$))
Mid$(b$,1) = “NEW “
MsgBox a$ & crlf & b$
End Sub
See Also
Mid, Mid$, MidB, MidB$ (functions); Option Compare (statement).
331
Minute (function)
Syntax
Minute(time)
Description
Returns the minute of the day encoded in the specified time parameter.
Comments
The value returned is as an Integer between 0 and 59 inclusive.
The time parameter is any expression that converts to a Date.
Example
‘This example takes the current time; extracts the hour,
‘minute, and second; and displays them as the current time.
Sub Main()
xt# = TimeValue(Time$())
xh# = Hour(xt#)
xm# = Minute(xt#)
xs# = Second(xt#)
MsgBox “The current time is: “ & xh# & “:” & xm# & “:” & xs#
End Sub
See Also
Day (function); Second (function); Month (function); Year (function); Hour (function); Weekday
(function); DatePart (function).
332
MkDir (statement)
Syntax
MkDir path
Description
Creates a new directory as specified by path.
Example
‘This example creates a new directory on the default drive.
‘If this causes an error, then the error is displayed and
‘the program terminates. If no error is generated, the
‘directory is removed with the RmDir statement.
Sub Main()
On Error Resume Next
MkDir “TestDir”
If Err <> 0 Then
MsgBox “The following error occurred: “ & Error(Err)
Else
MsgBox “Directory was created and is about to be removed.”
RmDir “TestDir”
End If
End Sub
See Also
ChDir (statement); ChDrive (statement); CurDir, CurDir$ (functions); Dir, Dir$ (functions); RmDir
(statement).
333
Mod (operator)
Syntax
expression1 Mod expression2
Description
Returns the remainder of expression1 / expression2 as a whole number.
Comments
If both expressions are integers, then the result is an integer. Otherwise, each expression is
converted to a Long before performing the operation, returning a Long.
A runtime error occurs if the result overflows the range of a Long.
If either expression is Null, then Null is returned. Empty is treated as 0.
Example
‘This example uses the Mod operator to determine the value
‘of a randomly selected card where card 1 is the ace (1) of
‘clubs and card 52 is the king (13) of spades. Since the
‘values recur in a sequence of 13 cards within 4 suits, we
‘can use the Mod function to determine the value of any
‘given card number.
Const crlf = Chr$(13) + Chr$(10)
Sub Main()
cval$ = “ACE,TWO,THREE,FOUR,FIVE,SIX,SEVEN,EIGHT,”
cval$ = cval$+”NINE,TEN,JACK,QUEEN,KING”
Randomize
card% = Random(1,52)
value = card% Mod 13
If value = 0 Then value = 13
CardNum$ = Item$(cval,value)
If card% < 53 Then suit$ = “spades”
If card% < 40 Then suit$ = “hearts”
If card% < 27 Then suit$ = “diamonds”
If card% < 14 Then suit$ = “clubs”
msg = “Card number “ & card% & “ is the “
msg = msg & CardNum & “ of “ & suit$
MsgBox msg
End Sub
See Also
/ (operator); \ (operator).
334
Month (function)
Syntax
Month(date)
Description
Returns the month of the date encoded in the specified date parameter.
Comments
The value returned is as an Integer between 1 and 12 inclusive.
The date parameter is any expression that converts to a Date.
Example
‘This example returns the current month in a dialog box.
Sub Main()
mons$ = “Jan., Feb., Mar., Apr., May, Jun., Jul., “
mons$ = mons$ + “Aug., Sep., Oct., Nov., Dec.”
tdate$ = Date$
tmonth! = Month(DateValue(tdate$))
MsgBox “The current month is: “ & Item$(mons$,tmonth!)
End Sub
See Also
Day (function); Minute (function); Second (function); Year (function); Hour (function); Weekday
(function); DatePart (function).
335
Msg.Close (method)
Syntax
Msg.Close
Description
Closes the modeless message dialog box.
Comments
Nothing will happen if there is no open message dialog box.
Example
Sub Main()
Msg.Open “Printing. Please wait...”,0,True,True
Sleep 3000
Msg.Close
End Sub
See Also
Msg.Open (method); Msg.Thermometer (property); Msg.Text (property).
Msg.Open (method)
Syntax
Msg.Open prompt,timeout,cancel,thermometer [,XPos,YPos]
Description
Displays a message in a dialog box with an optional Cancel button and thermometer.
Comments
The Msg.Open method takes the following named parameters:
Parameter
prompt
timeout
cancel
336
Description
String containing the text to be displayed.The text can be changed using the
Msg.Text property.
Integer specifying the number of seconds before the dialog box is automatically removed. The timeout parameter has no effect if its value is 0.
Boolean controlling whether or not a Cancel button appears within the dialog
box beneath the displayed message. If this parameter is True, then a Cancel
button appears. If it is not specified or False, then no Cancel button is
created.If a user chooses the Cancel button at runtime, a trappable runtime
error is generated (error number 18). In this manner, a message dialog box
can be displayed and processing can continue as normal, aborting only when
the user cancels the process by choosing the Cancel button.
thermometer
XPos, YPos
Boolean controlling whether the dialog box contains a thermometer. If this
parameter is True, then a thermometer is created between the text and the
optional Cancel button. The thermometer initially indicates 0% complete and
can be changed using the Msg.Thermometer property.
Integer coordinates specifying the location of the upper left corner of the
message box, in twips (twentieths of a point). If these parameters are not
specified, then the window is centered on top of the application.
Unlike other dialog boxes, a message dialog box remains open until the user selects Cancel, the
timeout has expired, or the Msg.Close method is executed (this is sometimes referred to as
modeless).
Only a single message window can be opened at any one time. The message window is removed
automatically when a script terminates.
The Cancel button, if present, can be selected using either the mouse or keyboard. However, these
events will never reach the message dialog unless you periodically call DoEvents from within your
script.
Example
‘This example displays several types of message boxes.
Sub Main()
Msg.Open “Printing. Please wait...”,0,True,False
Sleep 3000
Msg.Close
Msg.Open “Printing. Please wait...”,0,True,True
For x = 1 to 100
Msg.Thermometer = x
Next x
Sleep 1000
Msg.Close
End Sub
See Also
Msg.Close (method); Msg.Thermometer (property); Msg.Text (property).
337
Msg.Text (property)
Syntax
Msg.Text [= newtext$]
Description
Changes the text within an open message dialog box (one that was previously opened with the
Msg.Open method).
Comments
The message dialog box is not resized to accommodate the new text.
A runtime error will result if a message dialog box is not currently open (using Msg.Open).
Example
‘This example creates a modeless message box, leaving room
‘in the message text for the record number. This box
‘contains a Cancel button.
Sub Main()
Msg.Open “Reading Record”,0,True,False
For i = 1 To 100
‘Read a record here.
‘Update the modeless message box.
Sleep 100
Msg.Text =”Reading record “ & i
Next i
Msg.Close
End Sub
See Also
Msg.Close (method); Msg.Open (method); Msg.Thermometer (property).
338
Msg.Thermometer (property)
Syntax
Msg.Thermometer [= percentage]
Description
Changes the percentage filled indicated within the thermometer of a message dialog box (one that
was previously opened with the Msg.Open method).
Comments
A runtime error will result if a message box is not currently open (using Msg.Open) or if the value
of percentage is not between 0 and 100 inclusive.
Example
‘This example create a modeless message box with a
‘thermometer and a Cancel button. This example also shows
‘how to process the clicking of the Cancel button.
Sub Main()
On Error Goto ErrorTrap
Msg.Open “Reading records from file...”,0,True,True
For i = 1 To 100
‘Read a record here.
‘Update the modeless message box.
Msg.Thermometer = i
DoEvents
Sleep 50
Next i
Msg.Close
On Error Goto 0
‘Turn error trap off.
Exit Sub
ErrorTrap:
If Err = 809 Then
MsgBox “Cancel was pressed!”
Exit Sub
‘Reset error handler.
End If
End Sub
See Also
Msg.Close (method); Msg.Open (method); Msg.Text (property).
339
MsgBox (function)
Syntax
MsgBox(prompt [, [ buttons] [,[title] [ ,helpfile,context]]])
Description
Displays a message in a dialog box with a set of predefined buttons, returning an Integer representing which button was selected.
Comments
The MsgBox function takes the following named parameters:
Named Parameter
prompt
buttons
title
helpfile
context
Description
Message to be displayed—any expression convertible to a String.
End-of-lines can be used to separate lines (either a carriage return,
line feed, or both). If a given line is too long, it will be word-wrapped.
If prompt contains character 0, then only the characters up to the
character 0 will be displayed.
The width and height of the dialog box are sized to hold the entire
contents of prompt. A runtime error is generated if prompt is Null.
Integer specifying the type of dialog box (see below).
Caption of the dialog box. This parameter is any expression convertible to a String. If it is omitted, then “BasicScript” is used. A runtime
error is generated if title is Null.
Name of the file containing context-sensitive help for this dialog. If this
parameter is specified, then context must also be specified.
Number specifying the ID of the topic within helpfile for this dialog’s
help. If this parameter is specified, then helpfile must also be
specified.
The MsgBox function returns one of the following values:
Constant
ebOK
ebCancel
ebAbort
ebRetry
ebIgnore
ebYes
ebNo
340
Value
1
2
3
4
5
6
7
Description
OK was pressed.
Cancel was pressed.
Abort was pressed.
Retry was pressed.
Ignore was pressed.
Yes was pressed.
No was pressed.
The buttons parameter is the sum of any of the following values:
Constant
ebOKOnly
ebOKCancel
ebAbortRetryIgnore
ebYesNoCancel
ebYesNo
ebRetryCancel
ebCritical
ebQuestion
ebExclamation
ebInformation
ebDefaultButton1
ebDefaultButton2
ebDefaultButton3
ebApplicationModal
Value
0
1
2
3
4
5
16
32
48
64
0
256
512
0
ebSystemModal
4096
Description
Displays OK button only.
Displays OK and Cancel buttons.
Displays Abort, Retry, and Ignore buttons.
Displays Yes, No, and Cancel buttons.
Displays Yes and No buttons.
Displays Retry and Cancel buttons.
Displays “stop” icon.
Displays “question mark” icon.
Displays “exclamation point” icon.
Displays “information” icon.
First button is the default button.
Second button is the default button.
Third button is the default button.
Application modal—the current application is suspended until
the dialog box is closed.
System modal—all applications are suspended until the
dialog box is closed.
The default value for buttons is 0 (display only the OK button, making it the default).
If both the helpfile and context parameters are specified, then context-sensitive help can be
invoked using the help key (F1 on most platforms). Invoking help does not remove the dialog.
Breaking Text across Lines
The prompt parameter can contain end-of-line characters, forcing the text that follows to start on a
new line. The following example shows how to display a string on two lines:
MsgBox “This is on” + Chr(13) + Chr(10) + “two lines.”
The carriage-return or line-feed characters can be used by themselves to designate an end-of-line.
341
Example
Sub Main
MsgBox “This is a simple message box.”
MsgBox “This is a message box with a title and an icon.”, _
ebExclamation,”Simple”
MsgBox “This message box has OK and Cancel buttons.”, _
ebOkCancel,”MsgBox”
MsgBox “This message box has Abort, Retry, and Ignore buttons.”, _
ebAbortRetryIgnore,”MsgBox”
MsgBox “This message box has Yes, No, and Cancel buttons.”, _
ebYesNoCancel Or ebDefaultButton2,”MsgBox”
MsgBox “This message box has Yes and No buttons.”,ebYesNo,”MsgBox”
MsgBox “This message box has Retry and Cancel buttons.” , _
ebRetryCancel,”MsgBox”
MsgBox “This message box is system modal!”,ebSystemModal
End Sub
See Also
AskBox, AskBox$ (functions); AskPassword, AskPassword$ (functions); InputBox, InputBox$
(functions); OpenFileName$ (function); SaveFileName$ (function); SelectBox (function);
AnswerBox (function).
Platform Notes:
The appearance of the MsgBox dialog box and its icons differs slightly depending on the platform.
MsgBox (statement)
Syntax
MsgBox prompt [, [ buttons] [,[title] [, helpfile, context]]]
Description
This command is the same as the MsgBox function, except that the statement form does not
return a value. See MsgBox (function).
Example
Sub Main()
MsgBox “This is text displayed in a message box.”
‘Display
‘text.
MsgBox “The result is: “ & (10 * 45) ‘Display a number.
End Sub
See Also
AskBox, AskBox$ (functions); AskPassword, AskPassword$ (functions); InputBox, InputBox$
(functions); OpenFileName$ (function); SaveFileName$ (function); SelectBox (function);
AnswerBox (function).
342