Dragon NaturallySpeaking Version 9 System ... - Image Management

1
Copyright © 2006 Nuance Communications, Inc. All rights reserved.
Note: For the latest System Administration information, see
http://support.nuance.com/downloads/
Dragon NaturallySpeaking
Version 9
System Administration Guide

Contents
Dragon NaturallySpeaking System Administration Guide ...........................................................10
Overview ........................................................................................................................................ 10
Installation and Upgrade .......................................................................................................11
Recommended System Requirements for Dragon NaturallySpeaking ...................................................... 11
Coexistence with Dragon NaturallySpeaking SDK Client Edition.............................................................. 11
Upgrading from a previous version..................................................................................................... 12
Dragon NaturallySpeaking Installation ................................................................................................ 12
Modifying settings for all users .......................................................................................................... 14
MSI Installation Options.................................................................................................................... 14
Windows Installer (MSI) options ........................................................................................................ 15
MSI options specific to NaturallySpeaking ........................................................................................... 16
InstallShield (setup.exe) options........................................................................................................ 23
Sample Command line...................................................................................................................... 24
Using the User Upgrade Wizard to upgrade multiple users..................................................................... 25
Upgrading Users with Custom Vocabularies ......................................................................................... 28
Version 9 File Structure .................................................................................................................... 29
Cleaning up after uninstalling Dragon NaturallySpeaking....................................................................... 30
Command line interface .................................................................................................................... 31
Setting up Roaming Users .....................................................................................................32
About the Roaming User feature ........................................................................................................ 32
Setting up the Roaming User feature.................................................................................................. 33
Roaming User Network Location......................................................................................................... 37
Internet Roaming User Guidelines ...................................................................................................... 38
Creating a Roaming User .................................................................................................................. 40
Using multiple dictation sources with a single user ............................................................................... 42
Running the Acoustic and Language Model Optimizer for Roaming Users................................................. 43
Dragon NaturallySpeaking Data Distribution Tool .....................................................................43
Overview ........................................................................................................................................ 43
Using the Data Distribution Tool ........................................................................................................ 44
Data Distribution Tool : Add and removing custom words ..................................................................... 45
Data Distribution Tool : Adding and removing vocabularies ................................................................... 46
Data Distribution Tool: Adding and removing custom commands ........................................................... 47
Nsadmin command line..................................................................................................................... 48
Using nsadmin................................................................................................................................. 49
nsadmin: Adding custom words ......................................................................................................... 50
nsadmin: Adding and Deleting Custom Vocabularies............................................................................. 51
nsadmin: Adding Custom Commands .................................................................................................53
Vocabulary Tool ...................................................................................................................54
Dragon Vocabulary Tool (Voctool) ...................................................................................................... 54
Dragon Vocabulary Tool: Overview..................................................................................................... 54
Dragon Vocabulary Tool: Choosing Documents .................................................................................... 55
Dragon Vocabulary Tool: Choosing Word Lists .....................................................................................56
Dragon Vocabulary Tool: Analyzing Settings........................................................................................ 57
Dragon Vocabulary Tool: Analyzing Files ............................................................................................. 58
Dragon Vocabulary Tool: Previewing New Words.................................................................................. 58
Dragon Vocabulary Tool: Training Added Words................................................................................... 59
Dragon Vocabulary Tool: Language Model Building............................................................................... 60
Dragon Vocabulary Tool: Summary Screen ......................................................................................... 61
Using Dragon NaturallySpeaking with Citrix .............................................................................62
Using Dragon NaturallySpeaking in a Citrix environment (overview)....................................................... 62
Installing and publishing Dragon NaturallySpeaking on the Citrix server ................................................. 62
Creating Policies for Dragon NaturallySpeaking on the Citrix server........................................................ 64
Making Published Applications Work together ...................................................................................... 65
2

Setting Up the Program Neighborhood on Citrix clients ......................................................................... 66
Starting Dragon NaturallySpeaking from a Citrix client ......................................................................... 67
The Convert XML to DAT tool .................................................................................................69
Using the Convert XML to DAT tool..................................................................................................... 69
Advanced Scripting Commands ..............................................................................................70
The MyCommands Editor: Advanced Scripting dialog box...................................................................... 70
Using ActiveX Components................................................................................................................ 72
The Script editing window ................................................................................................................. 73
The Advanced Scripting menu ........................................................................................................... 74
The Advanced Scripting Editor toolbar ................................................................................................ 75
The Immediate window..................................................................................................................... 76
The Watch window ........................................................................................................................... 77
The Stack window ............................................................................................................................ 79
Object and Proc lists......................................................................................................................... 80
The Break bar.................................................................................................................................. 80
The Edit area................................................................................................................................... 81
The Status bar................................................................................................................................. 82
The Object Browser.......................................................................................................................... 82
The References dialog box ................................................................................................................ 83
The UserDialog Editor dialog box........................................................................................................ 84
Advanced Scripting Basic Language.................................................................................................... 86
Objects Overview............................................................................................................................. 86
Operators ....................................................................................................................................... 87
All Functions by Groups .................................................................................................................... 88
Assignment Group............................................................................................................................ 89
Constant Group ............................................................................................................................... 90
Conversion Group ............................................................................................................................ 90
Data Type Group ............................................................................................................................. 90
DDE Group...................................................................................................................................... 90
Declaration Group ............................................................................................................................ 90
Dialog Function Group ...................................................................................................................... 90
Error Handling Group........................................................................................................................ 90
File Group ....................................................................................................................................... 91
Flow Control Group .......................................................................................................................... 91
Math Group ..................................................................................................................................... 91
Miscellaneous Group......................................................................................................................... 91
Object Group................................................................................................................................... 91
Operator Group ............................................................................................................................... 91
Settings Group ................................................................................................................................ 91
String Group ................................................................................................................................... 92
Time/Date Group ............................................................................................................................. 92
User Dialog Group............................................................................................................................ 92
User Input Group ............................................................................................................................. 92
Variable Info Group .......................................................................................................................... 92
Class Module ................................................................................................................................... 92
Code Module ................................................................................................................................... 94
Object Module ................................................................................................................................. 94
Any Data Type................................................................................................................................. 95
Boolean Data Type ........................................................................................................................... 95
Byte Data Type................................................................................................................................ 96
Currency Data Type ......................................................................................................................... 96
Date Data Type ............................................................................................................................... 96
Decimal Data Type........................................................................................................................... 96
Double Data Type ............................................................................................................................ 97
Integer Data Type............................................................................................................................ 97
Long Data Type ............................................................................................................................... 97
Object Data Type ............................................................................................................................. 97
PortInt Data Type ............................................................................................................................ 98
Single Data Type ............................................................................................................................. 98
3

4
String Data Type.............................................................................................................................. 98
String*n Data Type .......................................................................................................................... 99
UserDialog Data Type ....................................................................................................................... 99
Variant Data Type ............................................................................................................................ 99
Usertype definition........................................................................................................................... 99
Empty Keyword ............................................................................................................................... 99
False Keyword ............................................................................................................................... 100
Nothing Keyword ........................................................................................................................... 100
Null Keyword................................................................................................................................. 100
True Keyword ................................................................................................................................ 101
Win16 Keyword ............................................................................................................................. 101
Win32 Keyword ............................................................................................................................. 101
Friend Keyword ............................................................................................................................. 101
Main Sub ...................................................................................................................................... 102
Object_Initialize Sub ...................................................................................................................... 102
Object_Terminate Sub .................................................................................................................... 102
Set Instruction .............................................................................................................................. 103
Private Keyword ............................................................................................................................ 103
Public Keyword .............................................................................................................................. 104
AboutWinWrapBasic Instruction ....................................................................................................... 104
Abs Function ................................................................................................................................. 104
AppActivate Instruction .................................................................................................................. 105
arglist definition............................................................................................................................. 105
Array Function............................................................................................................................... 106
Array variable definition.................................................................................................................. 106
As [New] type definition ................................................................................................................. 106
Asc Function.................................................................................................................................. 106
As type definition........................................................................................................................... 107
Atn Function.................................................................................................................................. 107
Attribute definition ......................................................................................................................... 108
Attribute Definition/Statement......................................................................................................... 108
Beep Instruction ............................................................................................................................ 109
Begin Dialog Definition ................................................................................................................... 109
Big-endian definition ...................................................................................................................... 110
Call Instruction .............................................................................................................................. 111
CallByName Instruction .................................................................................................................. 111
CallersLine Function ....................................................................................................................... 112
CancelButton Dialog Item Definition ................................................................................................. 112
CBool Function .............................................................................................................................. 113
CByte Function .............................................................................................................................. 114
CCur Function................................................................................................................................ 114
CDate Function .............................................................................................................................. 114
CDbl Function................................................................................................................................ 115
CDec Function ............................................................................................................................... 115
charlist definition ........................................................................................................................... 116
ChDir Instruction ........................................................................................................................... 116
ChDrive Instruction ........................................................................................................................ 117
CheckBox Dialog Item Definition ...................................................................................................... 117
Choose Function ............................................................................................................................ 118
Chr$ Function................................................................................................................................ 119
Chr$ Function................................................................................................................................ 119
Chr$ Function................................................................................................................................ 120
CInt Function ................................................................................................................................ 120
Class_Initialize Sub ........................................................................................................................ 121
Class_Terminate Sub...................................................................................................................... 121
Class Module ................................................................................................................................. 121
Clipboard Instruction/Function......................................................................................................... 123
CLng Function ............................................................................................................................... 123
Close Instruction............................................................................................................................ 124

5
ComboBox Dialog Item Definition..................................................................................................... 124
Command$ Function ...................................................................................................................... 125
condexpr definition ........................................................................................................................ 126
Const Definition ............................................................................................................................. 126
Cos Function ................................................................................................................................. 126
CreateObject Function .................................................................................................................... 127
CSng Function ............................................................................................................................... 127
CStr Function ................................................................................................................................ 128
CurDir$ Function............................................................................................................................ 128
CVar Function................................................................................................................................ 129
CVErr Function .............................................................................................................................. 129
Date Function................................................................................................................................ 130
DateAdd Function .......................................................................................................................... 130
DateDiff Function ........................................................................................................................... 131
dateexpr definition ......................................................................................................................... 132
DatePart Function .......................................................................................................................... 132
DateSerial Function ........................................................................................................................ 132
DateValue Function ........................................................................................................................ 133
Day Function ................................................................................................................................. 133
DDEExecute Instruction .................................................................................................................. 134
DDEInitiate Function ...................................................................................................................... 135
DDEPoke Instruction ...................................................................................................................... 135
DDERequest$ Function ................................................................................................................... 136
DDETerminate Instruction ............................................................................................................... 136
DDETerminateAll Instruction ........................................................................................................... 137
Debug Object ................................................................................................................................ 137
Declare Definition .......................................................................................................................... 138
Def Definition ................................................................................................................................ 139
DeleteSetting Instruction ................................................................................................................ 140
dialogfunc definition ....................................................................................................................... 141
DialogFunc Prototype...................................................................................................................... 141
Dialog Instruction/Function ............................................................................................................. 142
Dim definition................................................................................................................................ 143
Dim Definition ............................................................................................................................... 143
Dir$ Function................................................................................................................................. 144
DlgControlId Function..................................................................................................................... 145
DlgCount Function.......................................................................................................................... 146
DlgEnd Instruction ......................................................................................................................... 146
DlgEnable Instruction/Function ........................................................................................................ 147
DlgFocus Instruction/Function ......................................................................................................... 148
DlgListBoxArray Instruction/Function................................................................................................ 149
DlgName Function.......................................................................................................................... 150
DlgNumber Function....................................................................................................................... 151
DlgSetPicture Instruction ................................................................................................................ 152
DlgText Instruction/Function ........................................................................................................... 153
DlgType Function ........................................................................................................................... 154
DlgValue Instruction/Function.......................................................................................................... 154
dlgvar definition............................................................................................................................. 156
DlgVisible Instruction/Function ........................................................................................................ 156
Do Statement................................................................................................................................ 157
DoEvents Instruction ...................................................................................................................... 158
DropListBox Dialog Item Definition................................................................................................... 158
End Instruction .............................................................................................................................. 159
Enum Definition ............................................................................................................................. 160
Environ Instruction/Function ........................................................................................................... 160
EOF Function ................................................................................................................................. 161
Erase Instruction ........................................................................................................................... 161
Err Object ..................................................................................................................................... 162
Error Instruction/Function ............................................................................................................... 163

6
Eval Function................................................................................................................................. 164
Exit Instruction.............................................................................................................................. 164
Exp Function ................................................................................................................................. 165
Expr definition ............................................................................................................................... 166
Field definition............................................................................................................................... 166
FileAttr Function ............................................................................................................................ 166
FileCopy Instruction ....................................................................................................................... 167
FileDateTime Function .................................................................................................................... 167
FileLen Function............................................................................................................................. 168
Fix Function .................................................................................................................................. 168
For Statement ............................................................................................................................... 169
For Each Statement........................................................................................................................ 169
Format$ Function........................................................................................................................... 170
FreeFile Function............................................................................................................................ 171
Friend Keyword ............................................................................................................................. 171
Function Definition ......................................................................................................................... 171
Get Instruction .............................................................................................................................. 172
GetAllSettings Function................................................................................................................... 173
GetAttr Function ............................................................................................................................ 174
GetFilePath$ Function..................................................................................................................... 174
GetObject Function ........................................................................................................................ 175
GetSetting Function........................................................................................................................ 175
Goto Instruction ............................................................................................................................ 176
GroupBox Dialog Item Definition...................................................................................................... 176
Hex$ Function ............................................................................................................................... 177
Hour Function................................................................................................................................ 178
If Statement.................................................................................................................................. 178
IIf Function ................................................................................................................................... 179
Input Instruction............................................................................................................................ 180
Input$ Function ............................................................................................................................. 180
InputBox$ Function ........................................................................................................................ 181
InStr Function ............................................................................................................................... 181
InStr Function ............................................................................................................................... 182
InStrRev Function .......................................................................................................................... 182
Instruction definition ...................................................................................................................... 183
Int Function .................................................................................................................................. 183
Is Operator ................................................................................................................................... 184
IsArray Function ............................................................................................................................ 184
IsDate Function ............................................................................................................................. 185
IsEmpty Function ........................................................................................................................... 185
IsError Function............................................................................................................................. 186
IsMissing Function.......................................................................................................................... 186
IsNumeric Function ........................................................................................................................ 187
IsNull Function .............................................................................................................................. 188
IsObject Function........................................................................................................................... 188
KeyName Function ......................................................................................................................... 189
Kill Instruction ............................................................................................................................... 189
Label definition .............................................................................................................................. 190
LBound Function ............................................................................................................................ 190
LCase$ Function ............................................................................................................................ 191
Left$ Function ............................................................................................................................... 191
Left$ Function ............................................................................................................................... 192
Len Function ................................................................................................................................. 192
Len Function ................................................................................................................................. 193
Let Instruction............................................................................................................................... 193
Like Operator ................................................................................................................................ 194
Line Input Instruction ..................................................................................................................... 194
Line Input Instruction ..................................................................................................................... 195
ListBox Dialog Item Definition ......................................................................................................... 195

7
Little-endian definition.................................................................................................................... 196
Loc Function.................................................................................................................................. 197
Lock Instruction............................................................................................................................. 197
LOF Function ................................................................................................................................. 198
Log Function ................................................................................................................................. 198
LSet Instruction ............................................................................................................................. 199
LTrim$ Function............................................................................................................................. 200
Macro definition ............................................................................................................................. 200
MacroDir$ Function ........................................................................................................................ 200
MacroRun Instruction ..................................................................................................................... 201
MacroRunThis Instruction................................................................................................................ 201
Me Object ..................................................................................................................................... 202
Method definition ........................................................................................................................... 202
Mid$ Function/Assignment .............................................................................................................. 202
Mid$ Function/Assignment .............................................................................................................. 203
Minute Function ............................................................................................................................. 204
MkDir Instruction ........................................................................................................................... 205
Module definition ........................................................................................................................... 205
Month Function.............................................................................................................................. 205
MonthName Function...................................................................................................................... 206
MsgBox Instruction/Function ........................................................................................................... 206
MultiListBox Dialog Item Definition................................................................................................... 208
Name definition ............................................................................................................................. 209
Name Instruction ........................................................................................................................... 209
Now Function ................................................................................................................................ 209
Num definition............................................................................................................................... 210
Numvar definition .......................................................................................................................... 210
Objexpr definition .......................................................................................................................... 210
Objtype definition .......................................................................................................................... 210
Objvar definition ............................................................................................................................ 210
Oct$ Function ................................................................................................................................ 211
OKButton Dialog Item Definition ...................................................................................................... 211
On Error Instruction ....................................................................................................................... 212
Open Instruction............................................................................................................................ 213
Option Definition............................................................................................................................ 213
OptionButton Dialog Item Definition ................................................................................................. 214
OptionGroup Dialog Item Definition.................................................................................................. 215
Param definition ............................................................................................................................ 216
Picture Dialog Item Definition .......................................................................................................... 216
Precedence definition ..................................................................................................................... 217
Print Instruction............................................................................................................................. 217
Private Definition ........................................................................................................................... 218
Procedure definition ....................................................................................................................... 219
Property definition ......................................................................................................................... 219
Property Definition ......................................................................................................................... 219
Public Definition............................................................................................................................. 220
PushButton Dialog Item Definition.................................................................................................... 221
Put Instruction............................................................................................................................... 221
QBColor Function ........................................................................................................................... 222
Randomize Instruction.................................................................................................................... 223
ReDim Instruction .......................................................................................................................... 223
Reference Comment....................................................................................................................... 224
Rem Instruction............................................................................................................................. 225
Replace$ Function.......................................................................................................................... 225
Reset Instruction ........................................................................................................................... 226
Resume Instruction ........................................................................................................................ 226
RGB Function ................................................................................................................................ 227
Right$ Function ............................................................................................................................. 227
Right$ Function ............................................................................................................................. 228

8
RmDir Instruction .......................................................................................................................... 228
Rnd Function ................................................................................................................................. 229
Round Function.............................................................................................................................. 229
RSet Instruction............................................................................................................................. 230
RTrim$ Function ............................................................................................................................ 230
SaveSetting Instruction .................................................................................................................. 231
Second Function ............................................................................................................................ 231
Seek Function................................................................................................................................ 232
Seek Instruction ............................................................................................................................ 232
Select Case Statement ................................................................................................................... 233
Select Case Statement ................................................................................................................... 234
SendKeys Instruction ..................................................................................................................... 235
Set Instruction .............................................................................................................................. 237
SetAttr Instruction ......................................................................................................................... 237
Sgn Function ................................................................................................................................. 238
Shell Function................................................................................................................................ 238
ShowPopupMenu Function............................................................................................................... 239
Sin Function .................................................................................................................................. 240
Space$ Function ............................................................................................................................ 240
Sqr Function.................................................................................................................................. 241
Statement definition....................................................................................................................... 241
Static Definition ............................................................................................................................. 241
Stop Instruction............................................................................................................................. 242
Str definition ................................................................................................................................. 242
Str$ Function ................................................................................................................................ 243
Strarray definition.......................................................................................................................... 243
StrConv$ Function ......................................................................................................................... 243
String$ Function ............................................................................................................................ 244
StrReverse$ Function ..................................................................................................................... 245
Strvar definition............................................................................................................................. 245
Sub Definition................................................................................................................................ 245
Tan Function ................................................................................................................................. 246
Text Dialog Item Definition ............................................................................................................. 246
TextBox Dialog Item Definition ........................................................................................................ 247
Text Dialog Item Definition ............................................................................................................. 248
Time Function................................................................................................................................ 249
Timer Function .............................................................................................................................. 249
TimeSerial Function........................................................................................................................ 250
TimeValue Function........................................................................................................................ 250
Trim$ Function .............................................................................................................................. 251
Type definition............................................................................................................................... 251
Type Definition .............................................................................................................................. 252
TypeName Function........................................................................................................................ 252
UBound Function............................................................................................................................ 253
UCase$ Function ............................................................................................................................ 254
Unlock Instruction.......................................................................................................................... 254
Userenum definition ....................................................................................................................... 255
Usertypevar definition .................................................................................................................... 255
Uses Comment .............................................................................................................................. 256
Val Function .................................................................................................................................. 256
Var definition................................................................................................................................. 257
Variantvar definition....................................................................................................................... 257
VarType Function ........................................................................................................................... 257
Wait Instruction............................................................................................................................. 258
Weekday Function.......................................................................................................................... 259
WeekdayName Function.................................................................................................................. 259
While Statement ............................................................................................................................ 260
With Statement ............................................................................................................................. 260
WithEvents Definition ..................................................................................................................... 261

Write Instruction............................................................................................................................ 261
Year Function ................................................................................................................................ 262
Objects Overview........................................................................................................................... 262
Format Predefined Date .................................................................................................................. 263
Format Predefined Number ............................................................................................................. 263
Format User Defined Date............................................................................................................... 264
Format User Defined Number .......................................................................................................... 265
Format User Defined Text ............................................................................................................... 266
Error List ...................................................................................................................................... 266
Dragon NaturallySpeaking scripting language extensions quick reference.............................................. 268
Guidelines for writing scripts ........................................................................................................... 269
List Variables................................................................................................................................. 269
ActiveControlPick ........................................................................................................................... 270
ActiveMenuPick.............................................................................................................................. 271
AppBringUp................................................................................................................................... 272
AppSwapWith ................................................................................................................................ 273
Beep ............................................................................................................................................ 274
ButtonClick ................................................................................................................................... 274
ClearDesktop................................................................................................................................. 275
ControlPick.................................................................................................................................... 275
DdeExecute................................................................................................................................... 276
DdePoke ....................................................................................................................................... 276
DllCall .......................................................................................................................................... 277
DragToPoint .................................................................................................................................. 278
GetState ....................................................................................................................................... 279
GoToSleep .................................................................................................................................... 279
HeardWord.................................................................................................................................... 279
HTMLHelp ..................................................................................................................................... 280
MenuCancel................................................................................................................................... 282
MenuPick ...................................................................................................................................... 282
MouseGrid..................................................................................................................................... 282
MsgBoxConfirm ............................................................................................................................. 283
MyCommandsActiveState................................................................................................................ 284
PlaySound..................................................................................................................................... 285
PromptValue Function..................................................................................................................... 285
RememberPoint ............................................................................................................................. 286
RunScriptFile ................................................................................................................................. 287
SendDragonKeys ........................................................................................................................... 287
SendSystemKeys ........................................................................................................................... 288
SetMicrophone............................................................................................................................... 289
SetMousePosition........................................................................................................................... 289
SetNaturalText .............................................................................................................................. 290
SetState ....................................................................................................................................... 291
ShellExecute ................................................................................................................................. 291
TTSPlayString................................................................................................................................ 292
Wait ............................................................................................................................................. 293
WaitForWindow.............................................................................................................................. 293
WakeUp........................................................................................................................................ 294
WinHelp........................................................................................................................................ 295
Key names for SendDragonKeys ...................................................................................................... 295
Windows shortcut keys ................................................................................................................... 297
Error messages for scripts............................................................................................................... 297
Structured Commands ........................................................................................................ 298
About Structured Commands........................................................................................................... 298
Structured Commands Samples ....................................................................................................... 298
Importing Structured Commands ..................................................................................................... 300
9

Dragon NaturallySpeaking System Administration Guide
Overview
Note: For the latest System Administration information,
see
http://support.nuance.com/downloads/
The Dragon NaturallySpeaking System Administration Guide contains the following information:
10
• Installation and upgrade
o System Requirements
o Coexistence with Dragon NaturallySpeaking SDK Client Edition
o Upgrading from a previous version
o Dragon NaturallySpeaking Installation
o Modifying settings for all users
o MSI Installation Options
o Using the User Upgrade Wizard to upgrade multiple users
o Upgrading Users with Custom Vocabularies
o Version 9 File Structure
o Cleaning up after uninstalling Dragon NaturallySpeaking
o Command line interface
• Setting up Roaming Users
o About the Roaming User feature
o Setting up the Roaming User feature
o Roaming User Network Location
o Internet Roaming User Guidelines
o Creating a Roaming User
o Using multiple dictation sources with a single user
o Running the Acoustic and Language Model Optimizer for Roaming Users
• Using the Dragon NaturallySpeaking Data Distribution Tool
• Using the Nsadmin Wizard
• Using the Vocabulary Tool

11
• Using Dragon NaturallySpeaking with Citrix
o Using Dragon NaturallySpeaking in a Citrix environment
o Installing and publishing Dragon NaturallySpeaking on the Citrix server
o Creating Policies for Dragon NaturallySpeaking on the Citrix server
o Making Published Applications Work together
o Setting Up the Program Neighborhood on Citrix clients
o Starting Dragon NaturallySpeaking from a Citrix client
• Using the Convert XML to DAT tool
Installation and Upgrade
Recommended System Requirements for Dragon NaturallySpeaking
� CPU speed 1GHz or greater. Recommended: 2.4 GHz
� 1GB RAM (512 MB free minimum)
� Minimum of 500MB of free hard disk space for a custom Installation where you install only the program files
and 1 set of speech files. Installations can range from 800 MB (US English Standard) to 2.5 GB (US English
Medical).
� Windows 2000 Service Pack 4 or higher, Windows Server 2003, Windows XP Pro or Windows XP Home (SP1 or
SP2).
� Creative Labs® Sound Blaster® 16 or equivalent sound card supporting 16-bit recording
� Microsoft® Internet Explorer 5 or higher (free download available at www.microsoft.com)
� An internet connection for product activation.
� CD-ROM drive (required for installation)
� Nuance-approved noise-canceling headset microphone
� Speakers (required for playback of recorded speech and text-to-speech features)
Coexistence with Dragon NaturallySpeaking SDK Client Edition
You can install Dragon NaturallySpeaking SDK Client Edition 9 on the same machine where Dragon
NaturallySpeaking 9 is installed.
In addition, Dragon NaturallySpeaking 9 and Dragon NaturallySpeaking SDK Client Edition 9 can share
vocabularies and users.
You can only run one product at the same time. For example, if you are running Dragon NaturallySpeaking you
cannot run any of the SDK Client tools or samples.

Notes:
Coexistence with Dragon NaturallySpeaking SDK Client Edition Version 8 is not supported.
Upgrading from a previous version
12
You can upgrade from Dragon NaturallySpeaking Versions 7 and 8.
During an upgrade, the V9 upgrade procedure will ask you to:
� Remove the previous Dragon NaturallySpeaking installation. If you choose not to remove the previous
installation, you cannot continue to upgrade. Removing Version 7 or 8 will not remove your V7 or 8 speech
files and vocabularies.
� Migrate your existing user files and vocabularies to Version 9. If you choose not to upgrade your user files and
vocabularies during the upgrade, you can do so at a later time by running the Version 9 Upgrade Tool.
Once V9 is installed, your previous version will no longer be functional.
Note: The user files from previous versions remain untouched in case you decide to later reinstall the previous
version.
Edition considerations
You must upgrade to the same edition or higher and to the same language.
For example, if you started with Version 8 German/English and you upgrade to Version 9 English only, your
Version 8 German users will not be upgraded. Upgrading to Version 9 German/English will upgrade both your
German and English users. After upgrading, you can install other Version 9 languages.
Directory Changes
For information on changes to the directory structure when upgrading from Version 7 or 8, see Version 9 File
Structure.
Dragon NaturallySpeaking Installation
This topic describes the basics steps for installing Dragon NaturallySpeaking on a single machine.
For complete a complete description of installing Dragon NaturallySpeaking on a single machine., please see
the Dragon NaturallySpeaking User's Guide.
Note
� You must have Administrator rights to install or uninstall Dragon NaturallySpeaking on Windows 2000 and
Windows XP.

13
For Windows 2000 and Windows XP Professional systems with limited user accounts (users with restricted
privileges), if the administrator wants to create a Dragon NaturallySpeaking user for a limited user, the
administrator must log on as the limited user. If an administrator creates a Dragon NaturallySpeaking user for
a limited user account from an administrator account, the limited user account will not be able to access that
user. Administrator rights are not required to create a user or use the software after installation. These
restrictions also apply for an upgrade installation.
� If you decide not to install some Dragon NaturallySpeaking components by selecting Custom installation, you
can install them later by running the Setup program again and choosing Modify.
Installing Dragon NaturallySpeaking on a single machine
To install Dragon NaturallySpeaking:
1. Insert the first Dragon NaturallySpeaking CD into your CD-ROM drive.
If the installation does not start automatically, use the Windows Explorer to find and double-click setup.exe
on the CD.
2. Provide your customer information, including the serial number supplied with your Dragon
NaturallySpeaking installation.
3. Choose your installation directory. If there are no previous versions of Dragon NaturallySpeaking on your
system, the default directory is:
C:\Program Files\Nuance\NaturallySpeaking9
4. Choose your Setup Type (Preferred and higher editions)
� Typical/Complete: Installs all options and speech files and requires the most disk space.
� Custom: Lets you select which options and speech files to install. Customizing your installation options
can greatly reduce the disk space required for installation.
For the Professional edition, you can modify the following settings during a custom installation. These
settings are applied to all users created with this installation of Dragon NaturallySpeaking, including
users created from Windows XP limited accounts:
� "Modify the application's settings for all users" displays the Options dialog box at the end of the
installation. The Options dialog box lets you change Dragon NaturallySpeaking’s standard behavior,
including specifying hot keys, customizing how text is formatted, initial microphone settings, and
setting the how often your user files are backed up.
� “Modify the administrative settings” displays the Administrative settings dialog box at the end of
the installation. The Administrative settings dialog box lets you set up the Roaming User feature as
well as well as set the backup location of your user files and restrict users from modifying
commands and vocabularies.
5. Enable the Dragon NaturallySpeaking QuickStart option. (Optional)
6. If you are upgrading from Version 7 or 8, you can select to upgrade your users as part of the Version 9
installation by checking “Upgrade existing speech files to work with this installation.”
7. Continue following the on-screen instructions. The setup program will install the files for Dragon
NaturallySpeaking to your computer.
Activating Dragon NaturallySpeaking
The first time you start Dragon NaturallySpeaking, you will be prompted to activate your copy of Dragon
NaturallySpeaking. If you do not activate the software, Dragon NaturallySpeaking will stop working after
starting the product fives times.
For more information on activation, please see the Dragon NaturallySpeaking User's Guide.

Modifying settings for all users
14
For the Professional, you can modify the following settings during an installation:
� "Modify the application's settings for all users" displays the Options dialog box at the end of the installation.
The Options dialog box lets you change Dragon NaturallySpeaking’s standard behavior, including specifying
hot keys, customizing how text is formatted, initial microphone settings, and setting the how often your user
files are backed up.
� “Modify the administrative settings” displays the Administrative settings dialog box at the end of the
installation. The Administrative settings dialog box lets you set up the Roaming User feature as well as well as
set the backup location of your user files and restrict users from modifying commands and vocabularies.
These settings are applied to all users created with this installation of Dragon NaturallySpeaking, including
users created from Windows XP limited accounts.
Modifying settings for all users
During an installation on a single computer, you can choose the Setup type :
� Typical/Complete: Installs all options and speech files and requires the most disk space.
� Custom: Lets you select which options and speech files to install.
Choose custom to select the "Modify the application's settings for all users" and “Modify the administrative
settings” options.
MSI Installation Options
Dragon NaturallySpeaking include a native Windows Installer (MSI) that lets you customize your installations as
well as install across a network to multiple client machines. In addition, you use this service to modify, repair, or
remove an existing NaturallySpeaking installations.
This section describes:
• Command line options specific to the Microsoft Installer Service (msiexec.exe).
• Command line options specific to NaturallySpeaking setup using msiexec.exe
• Command line options specific to how InstallShield Setup (setup.exe) calls msiexec.exe.
• Command line samples
MSI Installer location
The compiled .MSI file is located on your installation CD. The files are named:
• Dragon NaturallySpeaking (all editions): Dragon NaturallySpeaking 9.msi
• SDK Client Edition (DSC): Dragon SDK Client Edition 9.msi

15
• SDK Server Edition (DSS): Dragon SDK Server Edition 9.msi
Installation notes:
Unless otherwise noted
• All command line options are case insensitive and may be combined
• No options require special values based on the values of other options.
In the examples below, user-supplied information is displayed between angle brackets. Do not use angle brackets
() as part of the command line.
Do not use quotation marks except when specifying a full path name with the -path command.
Windows Installer (MSI) options
The executable program that interprets packages and installs products is the Microsoft Installer Service
(msiexec.exe) or MSI.
All native MSI command line options are supported. All options are documented in the Microsoft MSI
documentation, which can be found on:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/command_line_options.asp
All Msiexec.exe command-line options must be prefaced with a forward slash (/) only.
The following are the most useful MSI options for installing the Dragon NaturallySpeaking:
Option Description
/q or /qn Quiet (or silent) mode installation.
/L [i|w|e|a|r|u|c|m|o|p|v|x|+|!|*]
Logfile
Specifies the location of an installation logfile and specifies the
nature of the information to be logged:
i - Status messages.
w - Nonfatal warnings.
e - All error messages.
a - Start up of actions.
r - Action-specific records.
u - User requests.
c - Initial UI parameters.
m - Out-of-memory or fatal exit information.
o - Out-of-disk-space messages.

16
p - Terminal properties.
v - Verbose output.
x - Extra debugging information. Only available on Windows Server
2003.
+ - Append to existing file.
! - Flush each line to the log.
"*" - Wildcard, log all information except for the v and x options. To
include the v and x options, specify "/L*vx".
PROPERTY=VALUE Overrides default public property value. For example, setting
"XYZ=ABC" will replace the default property value of XYZ to ABC.
MSI options specific to NaturallySpeaking
This section described the msiexec.exe options specific to Dragon NaturallySpeaking.
The NaturallySpeaking command line options do not need to be prefaced hyphens or slashs.
Note: Launching automatically sets the property
"XYZ" to the value of "ABC" internally and continues the installation. However, installation through setup.exe will
still require the "/v" command line option in order to pass the property override value on to the MSI service.
The following table documents the supported global property overrides. Unless noted otherwise, all property
values are in UPPERCASE.
ADDLOCAL=Feature1,Feature2,...
or
ADDLOCAL=ALL
Option Description
The value of the ADDLOCAL property is a list of features that
are delimited by commas, and are to be installed locally.
To install all features locally (including the speech files), use
ADDLOCAL=ALL on the command line.
ADVERTISE=Feature1,Feature1,... The value of the ADVERTISE property is a list of features
delimited by commas that are to be advertised.
To install all features as advertised, use ADVERTISE=ALL on
the command line.
The ADVERTISE option overrides the ADDLOCAL option.
The best method for specifying a custom installation is to set
the ADDLOCAL property to ALL and then specify the
ADVERTISE property to match those features you don't want
installed locally. A list of the features that may be set for
installation is listed below.
DEFAULTSINI="c:\xyz.ini" Specifies a "default settings" file, which will allow an installer
to change the default behavior of the product for all users.

17
The specified file contains settings that will be merged into
the nsdefaults.ini file at installation time. Note that this file
must be in an ".ini" file format. In other words, any settings
you want to merge must also have the section notated as well
as the value and data. If only values and data are set in this
file (without the section name encased in brackets), the
settings will not be merged.
For a default installation, the nsdefaults.ini is located in:
C:\Documents and Settings\All Users\Application
Data\Nuance\NaturallySpeaking9
SERIALNUMBER=abcde-fgh-ijkl-mnop-qr The serial number, in the form of "abcde-fgh-ijkl-mnop-qr".
A serial number is required for all installations. If one is not
already built into the ereg.ini file, then a valid one must be
specified on the command line.
Note: Specifying a serial number on the command line does
not bypass the serial number checking within setup.
INSTALLDIR="c:\xyz" The default installation directory.
Long path names need to have their quote strings "escaped"
(\"). If you do not use this option, DSC is installed to the
defualt directory: [PROGRAMFILES]\Nuance\Dragon SDK
Client Edition
If you are upgrading from a previous version, you must set
INSTALLDIR to that versions installation directory.
PRODUCTUPDATEFLAG=0 (or 1 or -1) Sets the default state of the checkbox at the end of
installation to determine if installation will automatically
check the web for product updates.
A value of 0 (zero) will turn the checkbox off by default. A
value of 1 (one) will turn it on by default.
To disable the option entirely (turn the option off and
suppress the display of the checkbox
altogether), set the value to -1.
The default setting is "1" (enable the checkbox and check for
product updates by default).
NOTYPICAL=1 Sets the default choice on the SetupType dialog to "Custom",
rather than "Typical/Complete".
RebootYesNo=No Stops Windows from rebooting, even if the installation will not
be complete until Windows is restarted.
This option will also suppress the prevention of installation
when a reboot is necessary.
Note case: This should not be uppercased.
NOMINIMUM=1 Will override the enforcement of minimum memory/speed
requirements for installation.

QUICKSTART=0 (or 1) Set the default state of "Enable QuickStart Mode" checkbox to
enable QuickStart and to create shortcut for "Dragon
NaturallySpeaking"
in the Windows Startup folder.
18
A value of 0/1 will turn checkbox off/on accordingly.
REINSTALL=Feature1,Feature2,... (or ALL) The value of the REINSTALL property is a list of features
delimited by commas that are to be reinstalled. To reinstall all
features use REINSTALL=ALL on the command line.
REINSTALLMODE={specifying the type of
reinstallation to perform}
If the REINSTALL property is set, the REINSTALLMODE
property should also be set, to indicate the type of reinstall to
be performed. If the REINSTALLMODE property is not set,
then by default all files that are currently installed are
reinstalled, IF the currently installed file is a lesser version (or
is not present). By default, no registry entries are rewritten.
Note that even if REINSTALL is set to ALL, only those features
that were already installed previously are reinstalled. Thus, if
REINSTALL is set for a product that is yet to be installed, no
installation action will take place at all.
For more information, see:
http://msdn.microsoft.com/library/default.asp?url=/library/
en-us/msi/setup/reinstall.asp
The REINSTALLMODE property is a string that contains letters
specifying the type of reinstall to perform. Options are
case-insensitive and order-independent. This property should
normally always be used in conjunction with the REINSTALL
property. However, this property can also be used during
installation, not just reinstall.
If the REINSTALLMODE property is defined without also
defining the REINSTALL property, then the specified
"detection" modes still apply and specify the "overwrite"
mode for a normal installation. The REINSTALLMODE
property only affects those features that are selected
normally for installation. The presence of the
REINSTALLMODE property does not reinstall features. The
reinstallation of features requires the presence of the
REINSTALL property.
For example, to launch a minor upgrade without using
setup.exe, you must set the following properties through the
command line:
REINSTALL=ALL
REINSTALLMODE=vemus
Therefore, to install a minor upgrade through the .msi file,
you'll need to issue the following command line:
msiexec /i "

19
For more information on REINSTALLMODE and the reinstall
option codes, see:
http://msdn.microsoft.com/library/default.asp?url=/library/
en-us/msi/setup/reinstallmode.asp
ROAMINGUSERINI="c:\xyz.ini Specifies a "roaming user ini file", which contains settings to
be merged into nssystem.ini at installation time. These are
the same settings as displayed in the Roaming User section of
the Administrative Settings dialog box.
Long path names need to have their quote strings "escaped"
(\").
The default is empty (no .ini file will be used).
For more information on the roaming user ini file
ROAMINGUSEROPTIONS="c:\xyz.ini" Specifies a "roaming user options file", which contains
settings to be merged into nssystem.ini at installation time.
Long path names need to have their quote strings "escaped"
(\").
The default is empty (no .ini file to be merged).
Note that this file must be in an ".ini" file format. In other
words, any settings you want to merge must also have the
section notated as well as the value and data. If only values
and data are set in this file (without the section name encased
in brackets), the settings will not be merged.
SETDEFAULTS=0 (or 1) Sets the default state of "Modify the application's settings for
all users" checkbox to display the Options dialog box at the
end of the installation. The Options dialog box lets you change
Dragon NaturallySpeaking’s standard behavior, including
specifying hot keys, customizing how text is formatted, initial
microphone settings, and setting the how often your user files
are backed up.
A value of 0/1 will turn checkbox off/on accordingly.
SETADMINS=0 (or 1) Set the default state of "Modify the administrative settings"
checkbox to display the Administrative settings dialog box at
the end of the installation. The Administrative settings dialog
box lets you set up the Roaming User feature as well as well
as set the backup location of your user files and restrict users
from modifying commands and vocabularies.
A value of 0/1 will turn checkbox off/on accordingly.
WEBREGISTRATION=1 (or 0) Determines whether or not to launch the on-line product
registration form.
0 disables the product registration.
The default is 1 (enabled).
Feature variables that may set on the command line through the ADDLOCAL or ADVERTISE
property

Note the following when specifying features on the command line:
20
• If a feature doesn't exist in a particular edition or language, overriding it's default property has no effect.
• Some features (For example, the Speech feature) have subfeatures. Setting these features on the
command line will automatically turn on the properties of all subfeatures, unless those subfeatures have an
additional override also specified.
Subfeatures are indented from their parent features, and any information in parentheses is not included in
the feature name.
The following features can be specified from the command line:
Feature Sub-feature Sub-feature Sub-feature
NatSpeak
Note: Must be
included in
ADDLOCAL,
otherwise
installation will
fail
Samples (Sample
Commands files)
TTS
(Text-to-Speech)
TTSDEU (German
Text-to-Speech)
TTSENX (English
Text-to-Speech)
TTSESP (Spanish
Text-to-Speech)
TTSFRA (French
Text-to-Speech)
TTSITA (Italian
Text-to-Speech)
TTSNLD (Dutch
Text-to-Speech)
Tutorial TutDEU (German
Tutorial)
TutENX (English
Tutorial)
TutESP (Spanish
Tutorial)
TutFRA (French
Tutorial)
TutITA (Italian Tutorial)
TutNLD (Dutch Tutorial)
Speech DEU (German) DEUGeneral (German
General)
DEULegal (German
Legal)
ENX (English) AUS (Australian
English)
Sub-features for ENU (US English):

21
ITA (Italian)
NLD (Dutch)
FRA (French)
The Roaming User .ini file
ENG (UK English)
IND (Indian English)
SEA (SouthEast Asian
English)
ENU (US English)
ESP (Spanish) ESC (Castilian
Pronunciations)
ESL (Latin American
Pronunciations)
General (US English General)
Teens (US English Teens)
Legal (US English Legal)
Cardiology (US English Medical
Cardiology)
Emergency (US English Medical
Emergency)
Gastroenterology (US English Medical
Gastroenterology)
GeneralPractice (US English Medical
GeneralPractice)
Medical (US English Medical No Specialty)
MentalHealth (US English Medical
MentalHealth)
Neurology (US English Medical
Neurology)
ObGyn (US English Medical ObGyn)
Oncology (US English Medical Oncology)
Orthopaedic (US English Medical
Orthopaedic)
Pathology (US English Medical Pathology)
Pediatrics (US English Medical Pediatrics)
Radiology (US English Medical Radiology)
Surgery (US English Medical Surgery)
You can create a "roaming user ini file" to change the roaming user settings at installation time. These options are
the same settings that can be set as set with displayed in the RoamingUserOption
DgnEngineControl::RoamingUserOption using the DgnRoamingUserOptionConstants. For more information on the
DgnRoamingUserOptionConstants, see the API Reference Help file.
Option Description
Roaming User On=0 (or 1)
Roaming User Master
Directory="existing
directory"
Roaming User Local Cache
Directory="existing
directory"
Turns on the Roaming User feature.
Default 0 = Off
The location of the master roaming user you want to open.
This directory must exist.
The location of the local copy of the roaming user.
The default location is: Documents and Settings\All Users\Application

Roaming User Restrict
Local User Access=1 (or 0)
Roaming User Copy
Dragon Log=0 (or 1)
Roaming User Limited
Network Traffic=0 (or 1)
Roaming User Always
Break Lock=0 (or 1)
Roaming User Max
Container Size=500MB
ASW Override=0 (or 1)
Roaming User Do Not Copy
Dra Files=0 (or 1)
Example .ini file:
[Settings]
Roaming User On=1
22
Data\Nuance\Dragon SDK Client Edition\Roaming User\.
Permits non-roaming user to be opened when the roaming user feature is active.
Defaults to "1" which restricts access to roaming user only and prevents dictating
with a non-roaming (local) user by accident.
Copies the Dragon.log file from the local roaming user location to the master
roaming user location at the same time that the program synchronizes the local and
the master roaming user.
Default 0= Off
Transfers local user changes to the Options dialog box to the master roaming user
when the program synchronizes the local and the master roaming user.
Default 0= Off
Ask before breaking the locks on network users (recommended).
A network lock prevents the opening of a roaming user while that user is already
open. While this process does not take a long time, network problems can cause a
lock to become "stuck" and not release when the open process is completed. When
this happens, the next time anyone tries to open that user, they will see a message
informing them of the lock and give them the option of overriding it.
Default 0 = ask before breaking lock
Controls the maximum size for each container directory in the master user directory.
Defaults to 500 MB, max of 10000 MB
Runs a Volume Check and the Microphone Quality Check each time you open a
roaming user.
Turn this option on if your users experience reduced accuracy because of differences
in the microphone, sound card, and ambient sound levels of each roaming user
location.
Default 0 = off
Roaming User Master Directory=G:\TEMP\user1
Roaming User Restrict Local User Access=0
Prevents making the files that contain the acoustic data from the latest dictation
session available to the Acoustic Optimizer when the program synchronizes the local
and the master roaming user.
This prevents the Acoustic Optimizer from running on a local roaming user. If you do
not wish to retain this information, you can use this option to prevent the transfer.

Roaming User Copy Dragon Log=1
Roaming User Limited Network Traffic=1
Roaming User Local Cache Directory=D:\roam
InstallShield (setup.exe) options
Like the Microsoft Installer Service (msiexec.exe), the InstallShield Setup program (setup.exe) can accept a
number of command line options and can pass options through setup.exe to the included .msi file.
All setup.exe command-line options must be prefaced with a forward slash (/) only.
All options are documented in the InstallShield documentation:
http://helpnet.installshield.com/robo/projects/helplibdevstudio9/IHelpSetup_EXECmdLine.htm
The following are the most useful command line options for installing DSC:
/v
/s
23
Option Description
/L (followed by the
Windows Language
Code)
Passes command line and public properties options to the Windows Installer
(msiexec.exe) installation.
If you run setup.exe (rather than msiexec.exe) to install DSC, you can specify any
Windows Installer command line options using the "/v" option.
For example, for MSI quiet mode, you'll need to run setup.exe /v/qn. To set the public
property of XYZ to "ABC", you would run setup.exe /v"XYZ=ABC".
Formerly "noui"
Runs setup in a "silent" mode, suppressing the initialization window. However, unless
the MSI installation is also specified as silent, the MSI installation will run normally.
In order to run both setup.exe and msiexec.exe silently, you will need to combine the /s
and the /v options. Use the following command line: setup.exe /s /v/qn.
Using these options, no dialogs of any kind will be displayed during installation or
uninstallation. All messages are suppressed or, if a log file is also specified, sent to the
MSI log file in the user-specified temp directory.
The "noui" command line flag is no longer supported.
For Multi-lingual installations, specifies the language to use for installation and bypassed
the "Choose Installation Language" dialog box.
For example to launch the installation in French, the command line would be setup.exe
/l1036.
Extracting msi files from single-file installation executables (setup.exe files)
The following options are designed to extract .msi/.mst files from Windows Installer-oriented setup.exe
distribuitions. These options will not install any files; they will only extract an installable set of files into a specified

directory.
/a
/v
24
Option Description
/l
(followed by the Windows
Language Code)
EXTRACTFILES="c:\xyz"
Sample Command line
Administrative installation option. This instructs setup.exe to perform an
administrative installation instead of a normal installation. This option is required
when trying to extract the .msi files.
Passed arguments to Windows Installer. See above for details. This option is
required when trying to extract the .msi files.
Specifies the language to use for installing Dragon NaturallySpeaking . For
example, to launch the installation in French, the command line would be
. The following language codes are supported for installing
Dragon NaturallySpeaking:
1031=German
1033=English
1034=Spanish
1036=French
1040=Italian
1043=Dutch
This option creates an MST file for the language that is specified, for example,
1036.MST.
The directory to which the .msi/.mst files will be extracted. Long path names need
to have their quote strings "escaped" (\"). The property must be set when trying to
extract the .msi files. If the specified directory doesn't exist, it will be created.
Therefore, a sample extraction of msi files from a single file executable might look
like this: setup.exe /a /s /v"EXTRACTFILES=c:\temp\msifiles"
The following example silently installs NaturallySpeaking locally with a specified set of vocabularies:
setup /s /v /qn INSTALLDIR=\"c:\\ns8\" SERIALNUMBER=abcde-fgh-ijkl-mnop-qr ADDLOCAL=ALL
ADVERTISE=Cardiology,Emergency,Gastroenterology,GeneralPractice,MentalHealth,Neurolog
y,ObGyn,Oncology,Orthopaedic,Pathology,Pediatrics,General,Teens /Liwmo!e c:\\Setup.log
The table below describes each option:
/s
Option description
Runs setup in a "silent" mode, suppressing the
initialization window.

v
25
Passes command line and public properties options to the
Windows Installer (msiexec.exe) installation.
In order to run both setup.exe and msiexec.exe silently,
you will need to combine the /s and the /v options. Use the
following command line: setup.exe /s /v/qn.
Using these options, no dialogs of any kind will be
displayed during installation or uninstallation. All
messages are suppressed or, if a log file is also specified,
sent to the MSI log file in the user-specified temp
directory.
/qn Quiet (or silent) mode installation.
INSTALLDIR=\"c:\\ns8\" Sets the installation directory to C:\ns8
SERIALNUMBER=abcde-fgh-hij-klmo-pq
The serial number. A serial number is required for all
installations.
ADDLOCAL=ALL ADDLOCAL=ALL installs all features locally.
ADVERTISE=Cardiology,Emergency,Gastroentero
logy,
GeneralPractice,MentalHealth,Neurology,ObGyn,
Oncology,Orthopaedic,Pathology,Pediatrics,Gene
ral,Teens
/Liwmo!e c:\\Setup.log
Installs the specified vocabularies.
The best method for specifying a custom installation is to
set the ADDLOCAL=ALL and then specify the ADVERTISE
property to match those features you don't want installed
locally.
/L specifies the location of an installation logfile and
specifies the nature of the information to be logged:
i - Status messages.
w - Nonfatal warnings.
m - Out-of-memory or fatal exit information.
o - Out-of-disk-space messages.
! - Flush each line to the log.
e - All error messages.
c:\\Setup.log - writes out the log file to c:\setup.log
Using the User Upgrade Wizard to upgrade multiple users
Migrate your existing user files and vocabularies to Version 9.
If you choose not to upgrade your user files and vocabularies during the upgrade, you can do so at a later time
by running the Version 9 Upgrade Tool.
Use the Select Users to Upgrade screen to create a list of users that you want to upgrade. The wizard starts by
including all the users in the current folder as candidates to upgrade. You add users to the list by clicking the
Add button and browsing for additional users in other locations. You remove users from the list by selecting
them and clicking the Remove button. Once you have adjusted the list of user files to only the ones you want
to upgrade, click Next.
Edition considerations

26
You must upgrade to the same edition or higher and to the same language.
For example, if you started with Version 8 German/English and you upgrade to Version 9 English only, your
Version 8 German users will not be upgraded. Upgrading to Version 9 German/English will upgrade both your
German and English users. After upgrading, you can install other Version 9 languages.
User files to upgrade
Lists the location and name of all the users that the wizard will upgrade.
Note: The current location of the user files is called "Old Location" in this screen.
Number of users to upgrade
Displays the total number of users the wizard will upgrade.
Add
Opens a Browse for Folder window in which you can locate additional users for the wizard to upgrade.
Remove
Deletes a selected user from the User Upgrade wizard.
User Upgrade Wizard: Choose Users to Upgrade
The User Upgrade Wizard guides you through the process of upgrading user files created in Dragon
NaturallySpeaking version 6 and version 7. The wizard cannot upgrade user files created by versions of Dragon
NaturallySpeaking prior to version 6. Use the Choose Users to Upgrade screen to select the user or users that
you want to upgrade from among the following choices:
User only
Select this option to upgrade the user you selected on the Open User dialog box.
All user files in the same location as (recommended)
Select this option to upgrade all the users that the wizard finds in the location of the selected user at the same
time.
Custom: choose which users to upgrade:
Opens the Select Users to Upgrade screen where you can further refine the list of users to upgrade.
Once you have made a selection, click Next.
User Upgrade Wizard: Choose Destination

At the same time that the User Upgrade Wizard modifies your user files to work with Dragon NaturallySpeaking
version 8, it can move a copy of the upgraded user to another location while keeping the old files untouched.
This allows you to return to the old user files in case you need them again, and it makes the files compatible
with operating systems, like Windows XP, that store all user data in the Documents and Settings folder.
Destination for upgraded user files
Click the Browse button or select a new destination from the list if you want to choose a destination other than
the suggested destination.
Advanced
Click the Advanced button to open the Advanced Options screen where you can alter the way that the wizard
upgrades the user.
User Upgrade Wizard: Advanced Options
The Advanced Options screen allows you to make a finer adjustment to how the wizard upgrades the user than
you are normally can make on the Choose Destination screen. The Advanced Options screen contains the
following information and allows you to make the following changes:
User to upgrade
27
This box contains the following information about each user at the current location:
Old Location
User
Location of the current (not yet upgraded) user files.
The name of the user.
Vocabulary
The original vocabulary from which the user was created.
New Base Vocabulary
The new new vocabulary that the User Upgrade Wizard will use for the upgraded user if the old vocbulary is
no longer supported by Dragon NaturallySpeaking. If the current vocabulary is supported, the message
appears.
New Location
The location that the wizard recommended or that you chose on the Choose destination screen.
New Base Vocabulary

28
If a different base vocabulary is available for upgrading the user, you can use this list to select it.
New Location
If you want to choose a new location for the user, you can use this list to select it.
Upgrading Users with Custom Vocabularies
If you have custom vocabularies, upgrading your V8 users will maintain the customized vocabularies associated
with those users but will modify the vocabulary name. If you want to further modify and re-distribute that
customized vocabulary to your V9 users, use the procedure outlined below.
When you upgrade a user based on the custom vocabulary, all your customizations will be maintained but the
vocabulary's base type will be changed. For example, V8 users who used US English | Large | Nuance vocabulary
with a topic ID of 9005 will be upgraded to use the General - Large vocabulary; that upgraded user's vocabulary
will contain all customizations in the original V8 vocabulary.
Once the user is upgraded, you can continue to modify the vocabulary using the Voctool.
Step 1: Export any custom words added to the custom vocabulary
If you added any additional custom words to the custom vocabulary, you must first export those words. To export
custom words:
1. Click Words>Export... from the DragonBar. This displays the The Export Custom Words dialog box.
2. Enter the path and name of the file containing the custom words in your vocabulary that you want to create,
or use the Save in list to find a location for the file you want to create.
Step 2: Upgrade a user with a customized vocabulary
To upgrade V8 users with a customized vocabulary:
1. Run the User Upgrade Wizard. To run the wizard, select Dragon NaturallySpeaking 9.0>Dragon
NaturallySpeaking Tools>Upgrade Users.
2. In the User Upgrade Wizard, select a V8 user that uses a customized vocabulary.
3. Click Next and follow the on-screen prompts.
The User Upgrade Wizard will display the original vocabulary from which the user was created and let you choose
a V9 base vocabulary that the User Upgrade Wizard will use for the upgraded user.
Step 3: Import custom words to the upgraded user
If you exported words in Step 1, you know must import those words. To import a word list:
1. Click Words>Import... from the DragonBar. This displays the The Add Words from Word Lists wizard.
2. Click Next to add the file you created in Step 1.

Step 4: Export the customized vocabulary
You can share vocabularies among different users by first exporting a vocabulary from one user and then importing
it to a new user. Use the following procedure to export a vocabulary. To export a vocabulary:
Notes
29
1. Create a folder in which to save the exported vocabulary files.
2. Open the upgraded V8 user that uses the customized vocabulary.
3. On the NaturallySpeaking menu of the DragonBar, click or say "Manage Vocabularies."
4. On the Manage Vocabularies dialog box, select the vocabulary you want to export and then export it.
5. Locate and open the target folder, enter a name for the exported vocabulary in the File Name box, and then
save it.
6. Click or say "Close" on the Manage Vocabularies dialog box to save and close it.
• Exporting a vocabulary creates a copy of the four files that make up the vocabulary in the new location.
These files can be accessed by the Data Distribution Tool and nsadmin to create new custom base
vocabularies.
Step 5: Use nsadmin or the Data Distribution tool to copy the exported vocabulary
Using the nsadmin command line or the Data Distribution Tool, you can import the vocabulary your created in Step
2 as a base vocabulary on any Dragon NaturallySpeaking installation.
By adding a base vocabulary to a Dragon NaturallySpeaking installation, you can then
You can then use the new vocabulary to create new users or add a new a new vocabulary to the an existing user.
When you run nsadmin or the Data Distribution Tool to import the the exported vocabulary to your Dragon
NaturallySpeaking installation, make sure to give the new vocabulary the same name and topic ID as the V8
customized vocabulary.
For example, if your V8 customized vocabulary was named US English | Large | Nuance topic ID 9005, you would
use nsadmin or the Data Distribution Tool to create a new base vocabulary named US English | Large | Nuance with
a topic ID of 9005.
Version 9 File Structure
Upgrading from Dragon NaturallySpeaking V7 or V8 to V9 will automatically relocate some NaturallySpeaking
directories and files.
Note: The following directory structures and file locations assume an installation to a default location.
V7.0 Directory structure for all supported Windows operating systems
The V7.0 directory structure before upgrading to V9:

C:\Program Files\ScanSoft\NaturallySpeaking
\Custom
\Data
\Help
\Program
\Results
\Training
\Tutorial (optional installation)
\Users
Note: The \Custom directory is present only if you use nsadmin to create custom words, commands, or
vocabularies. The Dragon NaturallySpeaking V7.3 directory structure is the same as V8.
V8 Windows 2000/XP Pro/XP Home directory structure
30
The V8 directory structure before upgrading to V9:
C:\Program Files\ScanSoft\NaturallySpeaking
\Help
\Program
\Tutorial (optional)
C:\Documents and Settings\All Users\Application Data\ScanSoft\NaturallySpeaking\
\Custom
\Data
\Data\Training
\Users
C:\Documents and Settings\\Application Data\ScanSoft\NaturallySpeaking\
\Results
9 Windows 2000/XP Pro/XP Home/Windows Server 2003 directory structure
The Directory structure after installing V9 on Windows 2000/XP Pro/XP Home/Windows 2000 Advanced
Server/Windows Server 2003:
C:\Program Files\Nuance\NaturallySpeaking9
\Help
\Program
\Tutorial (optional)
C:\Documents and Settings\All Users\Application Data\Nuance\NaturallySpeaking9\
\Custom
\Data
\Data\Training
\Users
C:\Documents and Settings\\Application Data\Nuance\NaturallySpeaking9\
\Results
Cleaning up after uninstalling Dragon NaturallySpeaking
The following files will remain on your machine after you uninstall Dragon NaturallySpeaking:

31
� C:\Windows\Speech
� VText.dll
� Vdict.dll
� WrapSAPI.dll
� XTel.Dll
� Xcommand.dll
� Xlisten.dll
� Xvoice.dll
� spchtel.dll
� speech.cnt
� speech.dll
� vcauto.tlb
� vcmd.exe
� vcmshl.dll
� vtxtauto.tlb
Dragon NaturallySpeaking installed these files for Microsoft SAPI4 support. If you do not have other speech
applications that require SAPI4, you can safely remove these files manually. If have installed other speech
applications that require SAPI4 support, you may need to re-install those applications if you remove the files.
Command line interface
You can use command line options to modify the way in which Dragon NaturallySpeaking starts up. These
switches are used in the following syntax:
natspeak /switch
Where /switch is the switch from the following table:
Switch Function
/diagnose Runs Dragon NaturallySpeaking in diagnostic mode. Outputs
information into the Dragon.log file and exits.
/user Automatically loads the user specified by
/topic Automatically loads the topic specified by (Professional edition
only)
/quick Runs Dragon NaturallySpeaking in quick mode. QuickStart mode starts
Dragon NaturallySpeaking without loading a user or any speech models
when you start your computer. Only the Dragon NaturallySpeaking tray
icon is visible. When you click on the Dragon NaturallySpeaking desktop
icon, the Open User dialog box immediately appears. When you exit

32
Dragon NaturallySpeaking the program returns to the QuickStart mode
and remains in memory with a reduced footprint (approximately 10 MB).
/SetDefaultOptions Displays the Options dialog box at the end of the installation. The
Options dialog box lets you change Dragon NaturallySpeaking’s
standard behavior, including specifying hot keys, customizing how text
is formatted, initial microphone settings, and setting the how often your
user files are backed up.
/SetDefaultAdministrativeOptions Displays the Administrative settings dialog box at the end of the
installation. The Administrative settings dialog box lets you set up the
Roaming User feature as well as well as set the backup location of your
user files and restrict users from modifying commands and vocabularies.
Setting up Roaming Users
About the Roaming User feature
The Roaming User feature lets users dictate with Dragon NaturallySpeaking from different network locations
using a variety of computing devices without having to create and train individual user files at each location.
Some situations that the Roaming User feature makes possible:
� A doctor may need to dictate reports in a medical office building using a desktop computer, in a hospital
room using a Tablet PC, or at home using a laptop computer. The Roaming User feature allows the doctor
to use the same set of user files containing the same vocabulary words with the acoustic information from
each location.
� You have a user who uses the same laptop at multiple offices and at home. Before leaving the office, your
user loads a user from a central location on the network to his laptop. Once home, the user dictates and
corrects as they normally would. When they return to the office, the user reconnects the laptop to the
network and the Roaming User feature synchronizes the updated user files on the laptop with those at the
network’s central location the next time you load that user.
Master Roaming User and Local Roaming User
With the Roaming User feature, each Dragon NaturallySpeaking user has a single Master Roaming User that
can be opened from multiple networked machines running Dragon NaturallySpeaking. The Master Roaming
User is stored on a network location accessible to your users.
When a Master Roaming User is opened from that central network location, Dragon NaturallySpeaking
transfers a copy of that user to the local machine. That local copy is called the Local Roaming User.
The Local Roaming User is a copy of the user data taken from the Master Roaming User but modified locally by
corrections and acoustic data gathered during a dictation session.
For example, you can set a central storage device to contain all your Master Roaming User files. By loading a
Dragon NaturallySpeaking user from the central network location, your users can dictate at any computer
where Dragon NaturallySpeaking is installed. When users exit Dragon NaturallySpeaking and save the changes
to their user files, these changes are saved in that central location. The next time the user runs Dragon
NaturallySpeaking, all the changes they saved are available regardless of which computer on the network they

33
use for dictation.
For more information
For more information, see:
� Setting up the Roaming User Feature
� Creating and opening a Roaming User
� Using multiple dictation sources with a single user
� Synchronizing Master and Local Roaming Users
� Running the Acoustic and Language Model Optimizer for roaming users
Setting up the Roaming User feature
You must set up the Roaming User feature on each computer where you want users to dictate with a Roaming
User.
Step 1: Set up and create a network storage location for the Master Roaming
User files
Before setting up the Roaming User feature on individual machines, you must set up the network location for
the Master Roaming Users. The location you pick must be accessible to all computers where users will dictate
using a Roaming User. You can create multiple network storage locations.
The Roaming User feature supports the following types of locations:
� Mapped Drives - used to connect to a shared network folder that has a drive letter assigned to it.
� UNC Paths - used to connect to a shared network folder using the Universal Naming Convention (UNC) to
locate a user. The format is: \\servername\sharename\path\filename.
� HTTP (http:) - used to connect to machine on the internet or your local intranet. The format is:
http://myserver.com/webdav
Make sure your server has Web-based Distributed Authoring and Versioning (WebDAV) turned on.
Note: Additional installation of a third-party web server application called WebDAV is required. WebDAV software
is required in order to access and secure DNS user profiles on the Internet location. The WebDAV application is
available free of charge at www.webdav.org.
Step 2: Close any open users.
Before you can enable the Roaming User feature, you must first close any open users:
� If the Open User dialog box appears when you start Dragon NaturallySpeaking, click Cancel.
� If a user opens automatically (Dragon NaturallySpeaking will do this if there is only one user available), click
Close User on the DragonBar NaturallySpeaking menu.
Step 3: Turn on the Roaming User feature

34
After closing any open users:
1. Click Administrative Settings on the DragonBar Tools menu. This displays the Administrative Settings
dialog box.
2. On the Roaming tab, select Enable.
Step 4: Specify the location of the Master Roaming User
On each computer where you plan to have users dictating as a Roaming Users, you must tell that installation
of Dragon NaturallySpeaking where the Master Roaming user is located, and if necessary, create that location.
After selecting Enable on the Roaming tab:
1. Click the Add button. This displays the Roaming User Network Location dialog box. You use the Roaming User
Network Location dialog box to define the network location of the master roaming users. The location you
pick must be accessible to all computers on the network that you want available for dictation with Dragon
NaturallySpeaking.
2. Set the Display Name and the Network Location. The Roaming User feature supports the following types of
locations:
� Mapped Drive - the format is: \. For example, y:\roaming.
� UNC Path - the format is: \\servername\sharename\path\filename.
� HTTP (http:) - the format is: http://myserver.com/webdav.
3. For HTTP locations, click the HTTP Settings button to set information specific to your HTTP connection like
Authentication, Firewall, and Proxy Server information.
After specifying the HTTP Settings, use the Test Connection button to make sure your settings are correct.
Note: Additional installation of a third-party web server application called WebDAV is required. WebDAV software
is required in order to access and secure DNS user profiles on the Internet location. The WebDAV application is
available free of charge at www.webdav.org.
For more information on setting the location of the master roaming user, see Roaming User Network Location.
Step 5: Specify the location of a Local Roaming User
When a user opens a Master Roaming User, Dragon NaturallySpeaking transfers a copy of that user to the local
machine. That local copy is called the Local Roaming User.
You can set this location, called , from the the Administrative Settings dialog box.
To accept the default location, click OK on the Administrative Settings dialog box. You will
be prompted to create the default directory if it does not already exists.
The default location of is:
Documents and Settings\All Users\Application
Data\Nuance\NaturallySpeaking9\RoamingUsers\\
The is the name you defined for the Master Roaming User location. You can have multiple

35
multiple network storage locations for your Master Roaming User files.
The are the names of the individual Master Roaming Users.
Changing the default location
1. Use the Browse for Folder dialog box to open a location where you want to store the master roaming user.
This is the location on the computer where changes made during a dictation session, such as corrections or
new acoustic data are stored before they are synchronized with the master roaming user.
2. If the directory does not currently exist, click Make New Folder and type a name for the new folder. The
new directory can have any name, but calling it something meaningful, such as Local Roaming User, will
make the folder easier to find in the future.
3. Click OK.
Step 6: Set the Roaming User options
The Administrative Settings dialog box also contains several options that affect how the Roaming User feature
works. You can select from among the following options to modify the behavior of a roaming user for each
Roaming User location:
Allow non-Roaming Users to be opened
Select this box to permit the user to open non-Roaming (local) users. Clear this option to prevent anyone
from dictating with a non-Roaming (local) user by accident.
Access network at user open/close only
Select this box to synchronize changes made during a Dragon NaturallySpeaking session from the Local
Roaming User to the Master Roaming User only when Dragon NaturallySpeaking opens or closes. Otherwise,
synchronization will occur each the user switches users, closes a user, or saves a user. For more information,
see Synchronizing Master and Local Roaming Users. If you experience excessive network slowdowns,
checking this option may solve the problem by limiting the times the Local and Master Roaming users are
synchronized.
Ask before breaking locks on network users (recommended for UNC and mapped drives)
Select this box to keep the option of maintaining or breaking a network lock when opening a Roaming User.
Normally, network locks prevent anyone from opening a Roaming User at the same time someone else is
opening that user. While this process does not take a long time, network problems can cause a lock to
become "stuck" and not release when the open process is completed. When this happens, the next time
anyone tries to open that user, they will see a message informing them of the lock and giving them the
option of overriding it. If you do not wish anyone to be bothered by this message and always want to break
a network lock in this situation, you can clear this option to prevent the message from appearing. Because
the presence of a lock can indicate a problem that needs to be addressed, Nuance recommends that you
enable this option.
Note: This option is valid for users connecting to the Master Roaming User location using a mapped drive or
UNC drive. This option is not supported for users connecting over HTTP.
Set audio levels on each machine (recommended)
Select this box to run the "Check your audio settings" option from the Accuracy Assistant window before
each dictation session with a Roaming User. This includes the Volume Check and the microphone Quality

36
Check. Check this option if your users are users are using different machines or use a single machine, like
a laptop, in many different locations. When a user changes machines or locations, the audio setup data can
vary depending on differences in the microphone and sound card, as well as differences in ambient sound
levels of each Roaming User location. In situations where Dragon NaturallySpeaking detects a significant
difference between operating systems, sound cards, microphones, or other hardware, the program will
prompt you to run "Check your audio settings" even if you do not have this option selected.
Copy Dragon Log to Network
Select this box to copy the file, Dragon.log from the local Roaming User location to the master Roaming
User location at the same time that the program synchronizes the local and the master Roaming User.
Dragon.log contains information that can help to diagnose problems that you might encounter using Dragon
NaturallySpeaking.
Note: If you set the "Disk space reserved for network archive" option, the Dragon.log file will not be
copied once the maximum size is reached.
Always copy acoustic information to network
Select this box to copy the user's acoustic information to the Master Roaming User location. The Local
Roaming User acoustic information is stored in:
Documents and Settings\All Users\Application
Data\Nuance\NaturallySpeaking9\RoamingUsers\\\current\voice
The is the name you defined for the Master Roaming User location. You can have multiple
multiple network storage locations for your Master Roaming User files.
The are the names of the individual Master Roaming Users.
If you chose not to copy the user's acoustic information to the network, corrections you make on one
machine will not be available on other machines used by that particular Roaming User until you run the
Acoustic and Language Model Optimizer on the Master Roaming User location and the Local and Master
Roaming user synchronize. Always copying the acoustic information to the Master Roaming User location
means that these corrections are always available and will by automatically synchronized when the Master
Roaming User is opened from another location.
The transfer of acoustic information is not limited by setting the "Disk space reserved for network archive"
option.
Conserve archive size on network
Select this box to prevent the copying .DRA files (files which contain the acoustic data from the latest
dictation session) to the Master Roaming User location when the program synchronizes the Local and Master
Roaming users. Leaving this box unchecked allows the local .DRA files to synchronize with the Master
Roaming User. This makes the .DRA files available to the Acoustic and Language Model Optimizer when it is
run on the Master Roaming User locations and means increased accuracy.
However, .DRA files can be large. If you experience excessive network slowdowns, checking this option may
solve the problem by eliminating the copying of this files each time the Master and Local Roaming users
synchronize. You can still run the Acoustic and Language Model Optimizer on the Master Roaming User, but

37
since it will be less efficient since it will not have the .DRA files to process.
Note: If you set the "Disk space reserved for network archive" option, the .DRA files will not be copied once
the maximum size is reached.
Disk space reserved for network archive
Notes:
Use this option to specify the maximum size of the directory containing the acoustic data available to the
Acoustic Optimizer. By default the archive size is 500MB. To conserve space, you can reduce the default size
and select the "Conserve archive size on network" option. For this option to work, the machine you are
setting it for must be connected from the network.
� To enable Roaming Users and set the Roaming User options, you must start Dragon NaturallySpeaking from
an account with Windows Administrator privileges.
� Once you set up an installation of Dragon NaturallySpeaking to use the Roaming User feature, users on that
machine can only open Roaming Users; they cannot open any locally created users.
� If you use variety of microphones or input devices with your roaming user, see Using multiple dictation
sources with a single user for more information .
� If you are dictating with a Roaming User, the Acoustic and Language Model Optimizer Scheduler is disabled on
the local user's machine. You must run the Acoustic and Language Model Optimizer on the machine where
your Master Roaming User files are located. For more information, see Running the Acoustic and Language
Optimizer with a Roaming User.
Roaming User Network Location
You use the Roaming User Network Location dialog box to define the network location of the master roaming
users.
The location you pick must be accessible to all computers where users will dictate using a Roaming User.
Display Name
Sets the directory name displayed in the following locations:
� The Roaming tab of the Admistrative Settings dialog box
� The "Location of user files" field on the Open User.
Note: With the Roaming User enabled, the Open User dialog box displays only users in the Roaming User
locations. To let the users open both local (non-roaming) and Roaming users, select the "Allow
non-roaming users to be opened" option on the Administrative Settings dialog box. Clearing this option
prevents users from dictating with a non-roaming (local) user by accident. For more information, see
Setting Up the Roaming User feature..
� The "Location of user files" field on the Manage Users dialog boxes.
Network Location
On each computer where you plan to have users dictating as a Roaming Users, you must tell that installation

38
of Dragon NaturallySpeaking where the Master Roaming user is located.
The Roaming User feature supports the following types of locations:
Mapped Drives and UNC Paths
Mapped drives connect to a shared network folder that has a drive letter assigned to it.
UNC paths connect to a shared network folder using the Universal Naming Convention (UNC) to locate a user.
The UNC is a way to identify a shared file on a computer or network without having to know the storage device
it is on. The UNC path format is: \\servername\sharename\path\filename.
To use a mapped drive or UNC path:
1. Under Network Location, enter the address of the mapped drive or UNC path.
You can click Browse to browse for the location of the mapped drive or UNC path. This displays the Browse
for Folder dialog box. You can also create a new directory on the mapped drive or UNC path by clicking the
Make New Folder button.
2. Click OK when you are done.
Intranet/Internet connections
1. Under Network Location, enter the URL address of your HTTP server where your roaming user master files
are located.
2. Click the HTTP Settings... button to display the HTTP Settings dialog box.
From the HTTP Settings dialog box, you can set information specific to your HTTP connection like
Authentication, Firewall, and Proxy Server information. You can also test your connection to the HTTP
server from HTTP Settings dialog box. For more information, see HTTP Settings.
After specifying the HTTP Settings, use the Test Connection button to make sure your settings are correct.
For more information
About the Roaming User feature
Setting up the Roaming User feature
Creating and opening a roaming user
Internet Roaming User Guidelines
On each computer where you plan to have users dictating as a Roaming Users, you must tell that installation
of Dragon NaturallySpeaking where the Master Roaming user is located.
Dragon NaturallySpeaking lets you store you Master Roaming Users on an HTTP server; allowing you to access
your Master Roaming Users over the internet.

39
To connect to an HTTP server, you must suppy the following information:
� The network location: You use the Roaming User Network Location dialog box to define the network location
of the master roaming users. You must supply the URL address of your HTTP server where your roaming user
master files are located. For more information, see Roaming User Network Location.
� HTTP settings: From the HTTP Settings dialog box, you can set information specific to your HTTP connection
like Authentication, Firewall, and Proxy Server information. For more information, see HTTP Settings.
Supported Servers
Internet Roaming is supported on:
� Microsoft Internet Information Services (IIS) 6.0
� Apache HTTP Server 2.0.54 and higher
Testing the HTTP connection
Once you have supplied all the necessary information needed to connect to your HTTP server, press the Test
Connection button. The Test Connection button tests the connection to your HTTP server bases in the
information you supplied in the Roaming User Network Location HTTP Settings dialog box.
Troubleshooting test connections
The following table lists the possible messages you can recieve after pressing the Test Connection button.
Message Solution
Connection test successful! None - test successful.
Could not connect to the network location. � Check spelling and syntx of the HTTP address in the HTTP
Settings dialog.
� Check your local network for problems.
Could not copy a file to the network location � Check create and write privileges on the server
Could not create a directory on the network
location
Could not delete a file from the network
location
Could not delete a directory from the
network location
Could not copy files into a directory created
on the network location
� Server not installed or active.
� Check the create directory privileges on the server for the
Master Roaming directory.
� Check the the privileges for creating sub-directories under the
Master Roaming directory.
� Check permissions on the Master Roaming directory. The user
must have read, write, and modify privileges
� Check that privileges are inherited in the subdirectories.
� Check permissions on the Master Roaming directory. The user
must have read, write, and modify privileges
� Check that privileges are inherited in the subdirectories.
� Check permissions on the Master Roaming directory. The user
must have read, write, and modify privileges.
� Check for authentication time-out on your server.
� Check your local network for problems.

Could not list the contents of a directory
created on the network location
Contents of newly created directory
TempDir were incorrect
Could not copy a file from the network
location
Could not get the size of a newly created
directory on the network location.
Could not rename a file on the network
location
Could not rename a directory on the network
location
Could not copy a directory within the
network location
Creating a Roaming User
40
There are three ways to create a Roaming User:
� Train a new Roaming User
� Convert a non-roaming local user into a Roaming User
� Check permissions on the Master Roaming directory. The user
must have read, write, and modify privileges
� Check that privileges are inherited in the subdirectories.
Caused by an incomlete directory listing. Try again. If the
problem persists, check the condition of your network.
� Check permissions on the Local Master Roaming directory.
� Check that the Local Master Roaming directory exists.
Apache: Make sure DavDepthInfinity directive is set to "on" for
Master Roaming directory.
� Check permissions on the Master Roaming directory. The user
must have read, write, and modify privileges
� Check that privileges are inherited in the subdirectories.
� Check permissions on the Master Roaming directory. The user
must have read, write, and modify privileges
� Check that privileges are inherited in the subdirectories.
� Check permissions on the Master Roaming directory. The user
must have read, write, and modify privileges
� Check that privileges are inherited in the subdirectories.
� Copy an non-roaming local users to the Master Roaming User location.
To open or create Roaming User, your local installation of Dragon NaturallySpeaking must be configured for
Roaming Users. For more information, see Setting up the Roaming User Feature.
To create and train a new Roaming User
1. Make sure that no local user is open. Click NaturallySpeaking>Close User on the DragonBar if one is open.
2. Select NaturallySpeaking>Open Users on the DragonBar. This displays the Open User dialog box. If you do
not see the user you are looking for, hit F5 to refresh the list of users.
Note: When the Roaming User feature is enabled, you can only create Roaming Users. The "Location of
user files" field only display the Roaming User locations you defined in the Administrative Settings dialog
box. To let the users create both local (non-roaming) and Roaming Users, select the "Allow non-Roaming
Users to be opened" option on the Administrative Settings dialog box. Clearing this option prevents users
from dictating with a non-roaming local user by accident. For more information, see Setting up the
Roaming User Feature.

41
If you allow users to select both non-roaming local and Roaming Users, make sure they select the correct
location from the "Location of user files" field.
3. Click New and begin training the user as you would any other user. When you are finished training the user,
the program copies the user files into the master Roaming User location specified in the "Location of user
files" field.
To convert a non-roaming local user into a Roaming User
You can convert an existing non-roaming local user to a Roaming User from the Manage Users dialog box.
Converting a non-roaming local user copies that user to the specified Master Roaming User location.
1. Make sure that no local user is open. Click NaturallySpeaking>Close User on the DragonBar if one is open.
2. Select NaturallySpeaking>Manage Users from the DragonBar. This displays the Manager User Dialog box.
3. Select the non-roaming local location of your user files from the "Location of user files" field. This should
display the list of non-roaming local users that you can convert to Master Roaming Users.
4. Select the non-roaming local user you want to convert to a Master Roaming User.
5. Click the Advanced button and then click Save to Roaming. This displays the Save to Roaming dialog box.
6. Select the appropriate Master Roaming User location and click OK. A Master Roaming User location
appears in this list only if it is currently connected to the local machine.
7. Repeat the process for any other non-roaming local users you want to convert to Master Roaming Users.
To copy a user into the master user location
You can also copy a non-roaming local user into the network directory of the Master Roaming User. This has the
advantage of allowing you to turn a number of non-roaming local users into master Roaming Users with a single
operation.
Notes:
1. Navigate to the location of the non-roaming local user files you want to convert to Master Roaming Users.
2. Select the files non-roaming local users you want to copy.
3. Copy the selected non-roaming local users to the Master Roaming User network directory.
• By default, non-roaming local users are located in:
C:\Documents and Settings\All Users\Application Data\Nuance\NaturallySpeaking9\Users
• Each non-roaming local user has it's own directory structure. Make sure to copy the entire user directory
structure to the Master Roaming User network directory.
To open a Roaming User
1. Make sure that no local user is open. Click NaturallySpeaking>Close User on the DragonBar if one is open.
2. Select NaturallySpeaking>Open Users on the DragonBar. This displays the Open User dialog box. If you do
not see the user you are looking for, hit F5 to refresh the list of users.
If you allow users to select both non-roaming local and Roaming Users, make sure they select the correct

Notes
42
location from the "Location of user files" field.
Notes:
o When the Roaming User feature is enabled, you can only open Roaming Users. The "Location of
user files" field only display the Roaming User location you defined in the Administrative Settings
dialog box. To let the users open both local (non-roaming) and Roaming Users, select the "Allow
non-Roaming Users to be opened" option on the Administrative Settings dialog box. Clearing this
option prevents users from dictating with a non-roaming local user by accident. For more
information, see Setting up the Roaming User Feature.
o If you connect to your Roaming User Master Directory over HTTP, and you find that not all your
users are listed in the Open User dialog box, make sure that:
� The .INI extention is registered in MIME types (ini.png) list of your IIS server
� The user's topics.ini file is not locked, password protected, or otherwise restricted for
access by your server permissions.
3. Select a user and click Open.
� If you use variety of microphones or input devices with your Roaming User, see the topic: Using multiple
dictation sources with a single user.
� When you export a user to a new location, any custom words that you have added to a local Roaming User will
not accompany the user files unless you first run Add Words from Document wizard from the Accuracy Center.
As an alternative to running the Add Words from Document wizard, you can turn the Roaming User feature off
on the Administrative Settings dialog box, save the user, and then turn the feature back on.
� If you modify a master Roaming User while you have a local Roaming User open on a computer that is not
currently connected to the network (for example, a laptop at a remote location), the changes to the master
Roaming User will overwrite any changes you make to the local Roaming User when you synchronize the local
and master Roaming Users.
� When a Roaming User exits Dragon NaturallySpeaking, switches users, closes a user, or saves a user, Dragon
NaturallySpeaking saves changes to the Local Roaming User and then synchronizes these changes with the
Master Roaming User on the network. For more information, see Synchronizing Master and Local Roaming
Users
Using multiple dictation sources with a single user
It is possible to use a variety of dictation sources with a single set of user files such as different microphones
or portable recording devices. This ability is especially useful with a Roaming User. By allowing multiple
dictation sources, you can still have the same user files for each location regardless of the microphone type or
differences in ambient noise.
You can add dictation sources to a user in the following way:
To add a new dictation source to a user
1. On the Open User dialog box, select the User for which you want to create a new dictation source.

43
2. Click the Source button and then click New. This displays the the New Dictation Source dialog box.
3. Select a new input device for your dictation from the list on the New Dictation Source dialog box. For example,
you can choose from among different microphone or recorder types.
4. Click OK. You return to the Open User dialog box.
5. Select the user you just created and click Open. If you have not previously trained the user with the new
dictation source, the New User wizard appears and you can begin training.
Running the Acoustic and Language Model Optimizer for Roaming Users
When a Local Roaming User is open, that user cannot run the Acoustic and Language Model Optimizer or the
Acoustic and Language Model Optimizer Scheduler. The Acoustic and Language Model Optimizer can only be
run on the Master Roaming User. In this way, any optimizations done by the Acoustic and Language Model
Optimizer are copied to with each Local Roaming User when synchronization occurs.
The system administrator is responsible for running the Acoustic and Language Model Optimizer on the
network location of the Master Roaming Users. The administrator can install Dragon NaturallySpeaking on the
machine where the Master Roaming User files are located or an any machine that has network access to the
Master Roaming User files and run the Scheduler for the Acoustic and Language Model Optimizer.
Note: You must have Windows Administrator privileges on the machine where you are running the Scheduler
for the Acoustic and Language Model Optimizer.
To run the Acoustic and Language Model Optimizer to optimize Roaming Users
1. Be sure that a copy of Dragon NaturallySpeaking is installed on the computer where you plan to run the
Acoustic and Language Model Optimizer.
2. On the Windows Start menu, select Programs>Dragon NaturallySpeaking 9.0>Dragon NaturallySpeaking
Tools>Scheduler for Acoustic and Language Model Optimizer to start the Acoustic and Language Model
Optimizer Scheduler.
3. Access the master directory of the Roaming Users you want to optimize. To do this, click Set Speaker
Directory on the File menu of the Acoustic and Language Model Optimizer Scheduler window. On the Set
User Profile Directory dialog box, either enter the path of the directory or click the Browse button. If the
users you want to optimize are located in multiple directories, you can change directories to locate the
additional users.
4. Select the user or users you want to optimize and set a schedule for running the Acoustic and Language
Model Optimizer. Consult the Help for Using the Acoustic and Language Model Optimizer Scheduler for
specific instructions.
Dragon NaturallySpeaking Data Distribution Tool
Overview
You use the Dragon NaturallySpeaking Data Distribution Tool when you want to interactively make new words,
customized vocabularies or new commands available to all user profiles on a particular Dragon NaturallySpeaking
installation. You run the Data Distribution Tool on each Dragon NaturallySpeaking installation where you want the

new words or vocabularies to be available to your Dragon NaturallySpeaking users.
This section describes:
44
• Using the Data Distribution Tool
• Adding Custom Words
• Adding and Deleting Custom Vocabularies
• Adding Custom Commands
You can also run nsadmin from the command line. For more information, see Nsadmin command line.
Note: The Dragon NaturallySpeaking Data Distribution Tool only runs on Dragon NaturallySpeaking Professional
and higher editions.
Using the Data Distribution Tool
You use Data Distribution Tool when you want to interactively make new words, customized vocabularies or new
commands available to all user profiles on a particular Dragon NaturallySpeaking installation.
You run the Data Distribution Tool on each Dragon NaturallySpeaking installation where you want the new words
or vocabularies to be available to your Dragon NaturallySpeaking users.
Note: Both mapped drives and UNC paths are supported.
Starting the Data Distribution Tool
To start Data Distribution Tool , select Start > All Programs > Dragon NaturallySpeaking > Tools > Data
Distribution Tool
This displays the first screen of the nsadmin wizard. From this screen, you can:
• Add or remove base vocabularies
• Add or remove shared commands
• Add or remove word to share across vocabularies
Select an operation and click Next,
Advanced
Click the Advanced button to set the location where the local installation of Dragon NaturallySpeaking stores
cutomized words and commands.
For a default installation, custom commands for existing DNS users are located in:
\Documents and Settings\All Users\Application Data\Nuance\Dragon
NaturallySpeaking\Custom\

Data Distribution Tool : Add and removing custom words
You can use the Data Distribution Tool to make new words available to all user profiles on a particular installation.
To distribute a set of custom words (for example, a list of new drug names) to a particular installation, you must
first either:
Notes
45
• Create a text (.txt) file and enter each word or phrase you want to add to the vocabulary on a separate line.
Make sure words are spelled correctly. Each word, phrase or name that you add must be on a separate line.
To add a multiple-word phrase, such as "Mayberry Tribune," enter it on one line.
To include a spoken form for a word, type the word followed by a backslash (\) and the spoken form. For
example, to have "Robert F. Kennedy" entered when you say "RFK" type Robert F. Kennedy\RFK.
• If you have Dragon NaturallySpeaking available on another machine, you can use it to create those words
and export the words to a .txt file. For more information, see your DNS documentation.
• After you have have imported the custom words using nsadmin, you must close your users, then re-open
and save them for the changes to become available.
• Paths can be entered as complete local paths, relative paths, mapped network drives, a UNC path, or the
path to removable media, such as a CD-ROM or ZIP drive. Pathnames that include spaces must be
enclosed in quotation marks.
Before adding the custom words
Once you have created a .txt file (newwords.txt in the following examples) containing the custom words:
1. Copy the .txt file to a shared location accessible to all the client computers where you want to add the
words.
2. On each client computer, map a network drive to the shared location you created or reference the network
UNC address of the location in the nsadmin program.
Adding custom words
To add custom words:
1. Select "Add or remove words to share across vocabularies" from the Data Distribution Tool and click Next.
2. Select the languages of the user profiles that will have the custom words added and click Next.
3. Use the Import button to select the .TXT files containing the custom words you want to add.
You can use the View button to view the files that you added. You can modify the list by using the Remove
and Remove All buttons.
Click Next to continue.
4. The Data Distribution Tool displays a log of all operations it performed.
5. Click Finish when to re-display the Data Distribution Tool main screen; click Cancel to exit..
The NewWords.txt file will be copied to the following directory on each machine where it is run:
\Documents and Settings\All Users\Application Data\Nuance\Dragon
NaturallySpeaking9\Custom\enx\NewWords.txt

Data Distribution Tool : Adding and removing vocabularies
You can use Data Distribution Tool to make a customized vocabulary available to all user profiles on a particular
Dragon NaturallySpeaking installation.
For example, say you have extensively customized a vocabulary using the Voctool. Using the Data Distribution
Tool , you can copy the user's vocabulary to be used as a base vocabulary on any Dragon NaturallySpeaking
installation. By adding a base vocabulary to a Dragon NaturallySpeaking installation, any user profiles created
after adding that vocabulary can use that vocabulary.
Notes
46
• For a default installation, vocabularies for existing Dragon NaturallySpeaking users are located in:
\Documents and Settings\All Users\Application Data\Nuance\Dragon
NaturallySpeaking9\users\\current
• Vocabulary files end with the *.voc extension.
Before adding a vocabulary
Before adding the new vocabulary with the Data Distribution Tool :
• Copy the vocabulary to a shared location accessible to all the client computers where you want to add the
vocabulary.
• On each client computer where you plan to add the vocabulary, map a network drive to the shared location
you created or reference the network UNC address of the location in the nsadmin command.
Adding a vocabulary
To add a new base vocabulary:
1. Select "Add or remove base vocabulary" from the Data Distribution Tool and click Next.
2. On the screen click "Add". This displays the Add Base Vocabulary dialog.
3. On the Add Base Vocabulary dialog box:
o Give the vocabulary a name. The name should describe the content of the vocabulary, such as
"Astronomy" or "Marketing."
o Select the location of the vocabulary. This can be either a mapped drive or UNC address
o Give the vocabulary an unique numeric ID. Use a value greater than 9000 for the topic ID
parameter.
4. Click OK when you are done.
Adding exported vocabularies
If you used a separate installation of Dragon NaturallySpeaking to create a vocabulary, you can use the Data
Distribution Tool to distribute that vocabulary.
An exported Dragon NaturallySpeaking vocabulary is saved as a group of files.

One of the exported files has a .top file extension, the other files have .to* file extensions, where * is an integer.
To add an exported vocabulary to NaturallySpeaking with the Data Distribution Tool , provide the path to the file
with the .top file extension as an argument on the nsadmin command line.
For information on exporting a Dragon NaturallySpeaking vocabulary, see open_voc_dialog.htm
Deleting a vocabulary
To delete a base vocabulary:
47
1. Select "Add or remove base vocabulary" from the Data Distribution Tool and click Next.
2. The screen displays the existing base vocabularies by ID and username.
3. Select the vocabulary to delete.
4. Click Remove and then click Next. The Data Distribution Tool displays message when the vocabulary is
deleted.
5. Click Finish to close the Data Distribution Tool or back to re-display the screen.
Data Distribution Tool: Adding and removing custom commands
You can use the Data Distribution Tool to make a set of custom commands available to all user profiles on a
particular DNS installation.
Note the following when adding a custom commands:
• For a default installation, custom commands for existing DNS users are located in:
\Documents and Settings\All Users\Application Data\Nuance\Dragon
NaturallySpeaking\Custom\
• Once you have imported the custom commands to NaturallySpeaking installation, you must close your
users, then re-open and save them for the changes to become available to those users.
Before adding the commands
Custom commands are voice commands that you can create and modify to enter text, insert graphics, or activate
menu and keystroke commands in any application. You can create these commands with the MyCommands editor
or modify commands using the Command Browser.
When creating commands for export:
1. Create custom commands in Dragon NaturallySpeaking.
2. Export the commands to a .dat file using the Command Browser.
3. Copy the .dat file to a shared location accessible to all the client computers where you want to add the
commands.
Adding custom commands
To add custom commands:

48
1. Select "Add or remove shared commands " from the Data Distribution Tool and click Next.
2. Select the languages of the user profiles that will have the custom words added and click Next.
3. Use the Import button to select the .DAT files containing the custom commands you want to add.
You can modify the list by using the Remove and Remove All buttons.
Click Next to continue.
4. The Data Distribution Tool displays a log of all operations it performed.
5. Click Finish when to re-display the Data Distribution Tool main screen; click Cancel to exit..
Removing shared commands
To remove shared commands:
Paths
3. Select "Add or remove shared commands " from the Data Distribution Tool and click Next.
4. Select the languages of the user profiles that will have the custom words added and click Next.
5. Select the command to remove from the "Existing shared commands" list and click Remove.
6. Click Next. The Data Distribution Tool displays a log of all operations it performed.
7. Click Finish when to re-display the Data Distribution Tool main screen; click Cancel to exit..
Paths can be entered as complete local paths, relative paths, mapped network drives, a UNC path, or the path to
removable media, such as a CD-ROM or ZIP drive. Pathnames that include spaces must be enclosed in quotation
marks.
For example, if the .dat file is named NewCommands.dat, The NewCommands.dat file will be copied to::
\Documents and Settings\All Users\Application Data\Nuance\Dragon
NaturallySpeaking9\Custom\enx\NewCommands.dat
Nsadmin command line
You use nsadmin command line when you want to make new words, customized vocabularies or new commands
available to all user profiles on a particular Dragon NaturallySpeaking installation.
The nsadmin command line only performs one operation at a time, but you can write your own batch file or script
to execute multiple nsadmin operations on each computer.
This section describes:
• Using the nsadmin command line
• Adding Custom Words
• Adding and Deleting Custon Vocabularies

49
• Adding Custom Commands
You can also run nsadmin interactively. For more information, see Using the Data Distribution Tool.
Note: The nsadmin command line utility only runs on Dragon NaturallySpeaking Professional and higher editions.
Using nsadmin
You run the nsadmin utility on each computer containing Dragon NaturallySpeaking where you want the new words,
vocabularies, or commands to be available.
The nsadmin program only performs one operation at a time, but you can write your own batch file or script to
execute multiple nsadmin operations on each computer.
Starting nsadmin
To start nsadmin, select Start > All Programs > Dragon NaturallySpeaking > Tools > Nsadmin
Nsadmin starts in a DOS window, listing the nsadmin syntax. To re-display the nsadmin syntax, enter the
following:
>nsadmin /?
The nsadmin.exe program is located in the \Program directory beneath the directory where NaturuallySpeaking is
installed. For example, in a default installation:
C:\Program Files\Nuance\Dragon NaturallySpeaking9\Program>
Command line syntax
The nsadmin.exe program uses the following syntax.
nsadmin [options]
Available commands and options:
Commands and parameters Description
/commands Adds a command file to the local installation
/words Adds a list of new words to the local installation
/vocabulary " | |
"
Adds a vocabulary contained in or an exported .top
file to the NaturallySpeaking using the specified , and
/vocabulary delete Deletes the base vocabulary specified by
Options
/language enx | fra | deu | ita | esp | nld
Name of an installed NaturallySpeaking language to which you want
to add words, commands, or a vocabulary. The default value is "enx."

overwrite yes | no | ask
/? Display the command syntax
Notes:
50
Specifies overwrite rules if a file exists with the same name as the file
you are attempting to add. The default value is "ask."
• Command line arguments that contain spaces must be enclosed in quotation marks.
• If you are running nsadmin from other than the DNS Tools, you must specify the full path to the
nsadmin.exe program on the command line.
• You may want to write a batch file or script that executes nsadmin. When you have new words or
vocabularies to distribute, you can place them at the network location defined in the script and run the
script from the client machines to copy the new functionality to those machines.
• Both mapped drives and UNC paths are supported.
nsadmin: Adding custom words
You can use nsadmin to make new words available to all user profiles on a particular installation.
To distribute a set of custom words (for example, a list of new drug names) to a particular installation, you must
first either:
Notes
• Create a text (.txt) file and enter each word or phrase you want to add to the vocabulary on a separate line.
Make sure words are spelled correctly. Each word, phrase or name that you add must be on a separate line.
To add a multiple-word phrase, such as "Mayberry Tribune," enter it on one line.
To include a spoken form for a word, type the word followed by a backslash (\) and the spoken form. For
example, to have "Robert F. Kennedy" entered when you say "RFK" type Robert F. Kennedy\RFK.
• If you have Dragon NaturallySpeaking available on another machine, you can use it to create those words
and export the words to a .txt file. For more information, see your DNS documentation.
• After you have have imported the custom words using nsadmin, you must close your users, then re-open
and save them for the changes to become available.
• Paths can be entered as complete local paths, relative paths, mapped network drives, a UNC path, or the
path to removable media, such as a CD-ROM or ZIP drive. Pathnames that include spaces must be
enclosed in quotation marks.
Adding custom words
Once you have created a .txt file (newwords.txt in the following examples) containing the custom words:
1. Copy the .txt file to a shared location accessible to all the client computers where you want to add the
words.
2. On each client computer, map a network drive to the shared location you created or reference the network

51
UNC address of the location in the nsadmin program.
3. On each client computer, use the following command to add the custom words contained in the .txt file.
\nsadmin /words G:\NsAdmin\NewWords.txt
The NewWords.txt file will be copied to the following directory on each machine where it is run:
\Documents and Settings\All Users\Application Data\Nuance\Dragon
NaturallySpeaking9\Custom\enx\NewWords.txt
Example: Overwriting a custom words file
To overwrite a custom words file with the same name as the file you are adding, use the /overwrite option:
\nsadmin /words G:\NsAdmin\NewWords.txt /overwrite=yes
If the NewWords.txt file already exists in the \Documents and Settings\All Users\Application
Data\Nuance\Dragon NaturallySpeaking9\Custom\enx directory, the new file will overwrite the existing
file without prompting you.
nsadmin: Adding and Deleting Custom Vocabularies
You can use nsadmin to make a customized vocabulary available to all user profiles on a particular DNS installation.
For example, say you have extensively customized a vocabulary using the Voctool. Using nsadmin, you can copy
the user's vocabulary to be used as a base vocabulary on any DNS installation. By adding a base vocabulary to a
DNS installation, any user profiles created after adding that vocabulary can use that vocabulary.
Note the following when adding a custom vocabulary:
• For a default installation, vocabularies for existing DNS users are located in:
\Documents and Settings\All Users\Application Data\Nuance\Dragon
NaturallySpeaking9\users\\current
• Copy the directory containing the vocabulary to a shared location accessible to all the client computers
where you want to add the vocabulary.
Adding vocabularies
Notes
1. Copy the vocabulary to a shared location accessible to all the client computers where you want to add the
words.
2. On each client computer, map a network drive to the shared location you created or reference the network
UNC address of the location in the nsadmin command.
3. On each client computer, use the following command syntax to add the vocabulary:
\nsadmin /vocabulary " | |
"
• Use the parameter to link a vocabulary to a language.

52
For example, "US English" or "UK English" for an English install. The language or dialect you enter must be
present in the version of NaturallySpeaking installed on the computer. The represents the
size of the vocabulary you are importing.
• The value you specify for the parameter should describe the content of the vocabulary, such
as "Astronomy" or "Marketing."
• Use a value greater than 9000 for the topic ID parameter.
Example
\nsadmin /vocabulary G:\NsAdmin\myvoc "US English | Large | Nuance" 9005
The contents of the myvoc directory will be copied to:
\Documents and Settings\All Users\Application Data\Nuance\Dragon
NaturallySpeaking9\Custom\enx\Custom9005\
The model name, category, and ID will be added to the models.ini file.
To overwrite a vocabulary with the same name as the vocabulary you are adding, use the
/overwrite option:
\nsadmin /vocabulary G:\NsAdmin\myvoc "US English | Large | Nuance" 9005
/overwrite=yes
If the vocabulary file already exists in \Documents and Settings\All Users\Application
Data\Nuance\Dragon NaturallySpeaking9\Custom\enx\Custom9005\, it will be overwritten without
prompting you.
Adding exported vocabularies
If you used a separate installation of Dragon NaturallySpeaking to create a vocabulary, you can use nsadmin to
distribute that vocabulary.
An exported Dragon NaturallySpeaking vocabulary is saved as a group of files.
One of the exported files has a .top file extension, the other files have .to* file extensions, where * is an integer.
To add an exported vocabulary to NaturallySpeaking with nsadmin, provide the path to the file with the .top file
extension as an argument on the nsadmin command line. Do NOT include the .top file extension on the command
line.
The following command adds the "myvoc" exported topic (myvoc.top) as a new base vocabulary.
\nsadmin /vocabulary D:\MyDocuments\myvoc "US English | Large | Nuance" 9005
Deleting a base vocabulary
On each client computer, use the following command syntax to delete the vocabulary and the corresponding entry
in models.ini:
\nsadmin /vocabulary delete
\nsadmin /vocabulary delete 9005
After a base vocabulary is deleted, no user's vocabularies based on that base vocabulary can be used.

nsadmin: Adding Custom Commands
You can use nsadmin to make a set of custom commands available to all user profiles on a particular DNS
installation.
Note the following when adding a custom commands:
53
• For a default installation, custom commands for existing DNS users are located in:
\Documents and Settings\All Users\Application Data\Nuance\Dragon
NaturallySpeaking\Custom\
• Once you have imported the custom commands to NaturallySpeaking installation, you must close your
users, then re-open and save them for the changes to become available to those users.
Adding custom commands
1. Create custom commands in Dragon NaturallySpeaking.
2. Export the commands to a .dat file. In this example, NewCommands.dat.
3. Copy the .dat file to a shared location accessible to all the client computers where you want to add the
commands.
4. On each client computer, map a network drive to the shared location you created or reference the network
UNC address of the location with nsadmin.
5. On each client computer, use the following command syntax to add the custom commands contained in
the .dat file.
Example
\nsadmin /commands G:\NsAdmin\NewCommands.dat
Paths
Paths can be entered as complete local paths, relative paths, mapped network drives, a UNC path, or the path to
removable media, such as a CD-ROM or ZIP drive. Pathnames that include spaces must be enclosed in quotation
marks.
To use a UNC address, format the command as in the following example:
\nsadmin /commands \\HostComputer\NsAdmin\NewCommands.dat
The NewCommands.dat file will be copied to::
\Documents and Settings\All Users\Application Data\Nuance\Dragon
NaturallySpeaking9\Custom\enx\NewCommands.dat
To add the commands to a language other than English, use the /language option:
\nsadmin /commands G:\NsAdmin\NewCommands.dat /language=fra
The NewCommands.dat file will be copied to:
\Documents and Settings\All Users\Application Data\Nuance\Dragon
NaturallySpeaking9\Custom\fra\NewCommands.dat
To overwrite a commands file with the same name as the file you are adding, use the
/overwrite option:

\nsadmin /commands G:\NsAdmin\NewCommands.dat /overwrite=yes
If the NewCommands.dat file already exists in the
\Documents and Settings\All Users\Application Data\Nuance\Dragon NaturallySpeaking9\Custom\enx
directory, the new file will overwrite the existing file without prompting you.
Vocabulary Tool
Dragon Vocabulary Tool (Voctool)
You use the Dragon Vocabulary Tool to customize a vocabulary by adding new words and by optimizing the
language model. This section includes:
54
• Vocabulary Tool Overview
• Choosing Documents
• Choosing Word Lists
• Analyzing Settings
• Analyzing Files
• Previewing New Words
• Training Added Words
• Language Model Building
• Summary Screen
Dragon Vocabulary Tool: Overview
The Dragon Vocabulary Tool allows you to customize a vocabulary by adding new words and by optimizing the
language model.
The following information is available and can be modified on the introduction screen of this wizard.
User
The name of the user that the Dragon Vocabulary Tool will modify.
Vocabulary
The vocabulary type from which the user was created.
Change User/Vocabulary
Click this button to open the Select Speaker dialog box. Use this dialog box to choose a different user from among
the ones that are available.

Add new words from documents and adapt to writing style
This option instructs the Dragon Vocabulary Tool to examine documents you specify in the Choose Documents
screen that appears when you click Next. In general, you should select documents that reflect the preferred writing
style and vocabulary of the person who will use the modified user files for dictation.
Add new words from word list files
This option instructs the Dragon Vocabulary Tool to examine files containing lists of words that you specify in the
Choose Word Lists screen that appears when you click Next. Choosing this option means that the Vocabulary Tool
will only add words and will not analyse word frequency or otherwise adapt the vocabulary to a particular writing
style.
Notes
55
• Do not change the current user or the vocabulary while you are running the Dragon Vocabulary Tool. If you
do try to change the user or vocabulary, the Dragon Vocabulary Tool will stop running and discard any
changes.
• You can run the Dragon Vocabulary Tool using MS-DOS commands. To view a list of command-line
switches for running the Dragon Vocabulary Tool, type "voctool.exe /?" at the prompt inside a
command-prompt window.
Dragon Vocabulary Tool: Choosing Documents
In this step you select documents for the Vocabulary Tool to analyse. The Vocabulary Tool determines which words
in the documents are not in the current vocabulary and analyses the frequency and order in which words appear
in the samples to better understand the writing style of the author.
The following information and buttons appear on this screen:
Documents
The list of documents that you can have the Vocabulary Tool analyse. The buttons to the right of this list allow you
to add to and delete from the contents of the list.
Add Folder
Click this button to open the Browse for Folder dialog box, which you can use to select a folder of documents to
display in the documents list. Continue to click the Add Folder button and select different folders to add additional
documents to the list.
Add Document
Click this button to open the Add Documents dialog box, which you can use to select documents from a folder to
display in the documents list. You can hold down the CTRL key and click individual document names to select
multiple documents one at a time, or you can hold down the SHIFT key and click the first and last document names
to select a range of documents. Continue to click the Add Documents button and select different folders to add
additional documents to the list.
Remove Document

Click this button to remove selected document names from the document list. You can hold down the CTRL key and
click individual document names to select multiple documents one at a time, or you can hold down the SHIFT key
and click the first and last document names to select a range of documents.
View Document
Click this button to open a selected document in the application in which the document was created. For example,
if the document has a .doc extension, it will open in Microsoft Word. If the document has a .txt extension, it will
open in Notepad. The application must be available on your computer for you to be able to view a document.
Save List
Click this button to open the Save Document List as File dialog box, which you can use to save the current list of
documents in a separate file in the Folder of your choice. The files contains a .txt extension.
Load List
Click this button to open the Load Document List from File dialog box, which you can use to locate and load a file
containing a list of documents from among those that have been previously saved. If the file you try to load is not
an appropriate file list, an error message alerting you of this fact will appear and the contents of the file will not
appear in the document list.
Notes
56
• The Dragon Vocabulary Tool can process documents created in the following formats:
o Microsoft Word (*.DOC)
o Corel WordPerfect (*.WPD)
o ASCII Text (*.TXT)
o Rich Text Format (*.RTF)
o HyperText (*.HTM, *.HTML, *.SHTM, and *.SHTML)
If your computer does not have access to an application that can open a particular format, then the Dragon
Vocabulary Tool will not be able to process that document.
• If you try to process documents that contain invalid characters or text that doesn't reflect the writing style
of the person for whom the user was created, you may either damage the vocabulary by filling it with
improper words or decrease recognition accuracy by building a Language Model from example that don't
reflect the user's dictation style.
Dragon Vocabulary Tool: Choosing Word Lists
In this step you select word lists for the Vocabulary Tool to analyse. The Vocabulary Tool determines which words
in the lists are not in the current vocabulary.
A word list is an ASCII text document containing words or shorts phrases you want to add to the vocabulary. Each
word or phrase should be on an individual line and may contain a spoken form separate from the written form by
a backslash (\). For example, "& Co.\and Company".
The following information and buttons appear on this screen:

Word Lists
The names of files containing word lists that you can have the Vocabulary Tool analyse. The buttons to the right of
this list allow you to add to and delete file names.
Add Word List
Click this button to open the Add Word List Files dialog box, which you can use to select file names to display in the
documents list. You can hold down the CTRL key and click individual file names to select multiple files one at a time,
or you can hold down the SHIFT key and click the first and last file names to select a range of files. Continue to click
the Add Word List button and select different folders from which to add additional file names to the documents list.
Remove Word List
Click this button to remove selected file names from the documents list. You can hold down the CTRL key and click
individual file names to select multiple documents one at a time, or you can hold down the SHIFT key and click the
first and last file names to select a range of files.
Notes
57
• Be careful to process word lists that contain only valid words or phrases. Otherwise you may fill the
vocabulary with improper words or decrease recognition accuracy by building a Language Model from
examples that don't reflect the user's normal dictation vocabulary.
• You can create word list files from a current Dragon NaturallySpeaking user with the Export Words dialog
box on the Tools menu of the DragonBar.
Dragon Vocabulary Tool: Analyzing Settings
In this step you specify how the Dragon Vocabulary Tool will analyze the documents and word list files you chose
on the previous screen (Choose Documents or Choose Word Lists).
You can change the following settings:
Find unknown words
Select this option to have the Vocabulary Tool find words that are not already in the vocabulary. Note: This option
is only available if the Vocabulary Tool is analyzing documents and not word lists.
Find known words with unknown capitalization
Select this option to have the Vocabulary Tool find words that are already in the vocabulary but with a different
capitalization.
Preview the list of unknown words
Select this option to have the Vocabulary Tool open the Preview New Words screen, which displays the unknown
words and/or the known words with unique capitalization. You can use the Preview New Words to modify the list
select specific words that the Vocabulary Tool found.
Add all unknown words without previewing them

Select this option to have the Vocabulary Tool skip the Preview New Words screen. The Vocabulary Tool will add all
the unknown words and/or the known words with unique capitalization to the vocabulary without the option of
modifying the list.
Note
Use the Find known words with unknown capitalization option only with word lists that you are sure you want to
add to the vocabulary. Otherwise you might add words to the vocabulary unintentionally.
Dragon Vocabulary Tool: Analyzing Files
In this the Dragon Vocabulary Tool analyses the documents and word list files you choose in the Choose
Documents step or the Choose Word Lists step.
This screen shows the following information and contains the following button:
File list
The file list is a scrolling list of the files or documents that the Vocabulary Tool is processing. A check mark next to
the file name indicates that Vocabulary Tool has completed analyzing that file. An "X" mark indicates that the
Vocabulary Tool has not successfully completed analyzing the file, either because the analysis was interrupted by
the Stop button, or because an error occured while reading the contents of the file. An hourglass symbol appears
next to the name of the file that Vocabulary Tool is currently analyzing.
Stop/Resume
Click Stop to end the analysis. Click Resume to restart the analysis.
Progress bar
The progress bar indicates how much of the current file has been analyzed.
Dragon Vocabulary Tool: Previewing New Words
In this step you can view the list of words that the Vocabulary Tool identified as either not being in the current
vocabulary or as having a unique capitalization.
The following information and buttons appear on this screen:
Word
You can scroll the Word list and use the check box to the left of the word to choose whether or not to add the word
to the vocabulary. A check mark indicates that the word will be added. Removing the check mark indicates that the
word will not be added.
Frequency
58

Frequency indicates how many times the word appears in the analyzed documents. This information appears only
if you selected the "Add new words from documents and adapt to writing style" option on the Introduction screen
of the wizard.
Check All
Click this button to check all the words in the Word list.
Clear All
Click this button to clear all the words in the Word list.
Edit
Click this button to open the Edit Word dialog box for a word you have selected. In this dialog box you can change
both the written and enter a different spoken form of the selected word. The Edit Word dialog box also displays the
context and frequency with which the word appears in the analyzed document.
Save
Click this button to open the Windows Save As dialog box so you can save the contents of the Word list as a file.
Use the dialog box to specify a name and a location for this file. You can use this file with the Vocabulary Tool at a
later time to modify the vocabulary of other users.
Train added words
Select this option to open the Train Added Words screen of the Vocabulary Tool where you can train selected words
so that Dragon NaturallySpeaking can better recognize your pronunciation.
The Train added words feature is available only when you run the Dragon Vocabulary Tool as part of a normal
installation of Dragon NaturallySpeaking. You cannot train words using the Vocabulary Tool if you are running the
Dragon DSS SDK version.
Dragon Vocabulary Tool: Training Added Words
In this step you can train Dragon NaturallySpeaking so that the program can better recognize your pronunciation.
This feature is available only when you run the Dragon Vocabulary Tool as part of a normal installation of Dragon
NaturallySpeaking. You cannot train words using the Vocabulary Tool if you are running the Dragon
NaturallySpeaking SDK Server Edition (DSS) .
The following information and buttons appear on this screen:
Word
The Word list contains the words you selected on the Preview New Words screen. Select the words you want to
train from this list. A check mark in the box to the left of the word indicates that you want to train that word.
Check All
Click this button to select all the words in the Word list.
59

Clear All
Click this button to deselect all the words in the Word list.
Train
Click this button to open the Train dialog box where you can train Dragon NaturallySpeaking to recognize your
pronunciation of the words you selected. If you have selected more than one word to train, the Train dialog box
shows them to you in the order that they appear in the list.
Note
Only the person who will be dictating with the user you are modifying can perform the training. If that person is
unavailable for this Vocabulary Tool session, then training can also occur during a Dragon NaturallySpeaking
session by clicking Train from the Words menu on the DragonBar.
Dragon Vocabulary Tool: Language Model Building
In this step you tell the Vocabulary Tool to build a new language model with the information that it has gathered
in the preceding steps and specify the location and maximum size of the new vocabulary.
You can specify the following settings:
Build language model
If this option is selected the Vocabulary Tool will build a new language model containing the words and other
information it has gathered in preceding steps.
Language Model locator
If you are building a language model for a Solution Series version of Dragon NaturallySpeaking you can select
either the Middle or the User slot as a location. If you are building a language model for a Preferred version of
Dragon NaturallySpeaking you can select only the User slot as a location.
Language model size limit (Solution Series or SDK Server Edition only)
If you build the Language Model into the Middle slot, you can also limit the size of the model. You can specify a limit
between 0.5 megabytes to 5 megabytes. If you don't want to set a limit select Unspecified from the list.
Existing Model built by:
The version of the Dragon Vocabulary Builder that created the previous Language Model. This information only
appears if the user you are building a language model for has an existing language model.
Preserve existing model
This option appears only if the user for which you are building a language model has an existing language model.
Selecting Yes merges the new language model with the current one. Selecting No builds a new language model to
replace the existing one. Normally, you should accept the recommended value, which varies by the language
model location and the version of Dragon NaturallySpeaking for which you are creating the language model. The
recommendations for the Solution Series and Preferred editions are:
60
• For Dragon NaturallySpeaking Solution Series, middle slot, the recommendation is No.

61
• For Dragon NaturallySpeaking Solution Series, user slot, the recommendation is Yes.
• For Dragon NaturallySpeaking Preferred, user slot, the recommendation is Yes.
You cannot build a language model in the middle slot of Dragon NaturallySpeaking Preferred.
Dragon Vocabulary Tool: Summary Screen
The Summary screen for the Vocabulary Tool displays information about the newly built language model.
Details
The details box contains following information:
User
The name of the user that Vocabulary Tool modified.
Vocabulary
The vocabulary type of the user.
Language
The language of the vocabulary, including any specific variation of that language, such as United States
English or Southeast Asian English.
Additional information
The following information may also appear:
o The names of the documents or word lists that were processed
o The number of unknown words that were found
o The number of added words
o Whether or not the the Vocabulary Tool saved the previous language model or built a new
language model, and if it did, which language model location was used.
o Any warnings or any non-critical errors that might have occured during processing
Save speech files
Select this option to save the new speech file so that it is available for future Dragon NaturallySpeaking sessions.

Using Dragon NaturallySpeaking with Citrix
Using Dragon NaturallySpeaking in a Citrix environment (overview)
Dragon NaturallySpeaking includes support for deploying and running Dragon NaturallySpeaking in a Citrix
environment.
This section includes the following:
62
• Installing and publishing Dragon NaturallySpeaking on the Citrix server
• Creating Policies for Dragon NaturallySpeaking on the Citrix server
• Making Published Applications Work together
• Setting Up the Program Neighborhood on Citrix clients
• Starting Dragon NaturallySpeaking from a Citrix client
Sizing and performance information
For sizing and performance information for running Dragon NaturallySpeaking in a Citrix environment, please see:
http://www.nuance.com/naturallyspeaking/citrix
Installing and publishing Dragon NaturallySpeaking on the Citrix server
Dragon NaturallySpeaking includes support for deploying and running Dragon NaturallySpeaking in a Citrix
environment.
Dragon NaturallySpeaking can be run through the Citrix Webclient, Program Neighborhood Agent, and/or the
Program Neighborhood.
Requirements
Server:
Citrix Presentation Server 3.0 or 4.0
Please check www.citrix.com to download the latest patches.
Client:
Citrix ICA clients 8.x or 9.x
Installing and publishing Dragon NaturallySpeaking on the Citrix server
1. Install Dragon NaturallySpeaking as you normally would other applications that you make available on the
Citrix server, noting the installation directory.

63
2. Publish Dragon NaturallySpeaking:
o If you installed Dragon NaturallySpeaking, you must publish it as an Application:
When publishing Dragon NaturallySpeaking from the Presentation Server Console, use
natspeak.exe as the Dragon NaturallySpeaking executable. By default the Dragon
NaturallySpeaking applications are installed to:
\Program Files\Nuance\NaturallySpeaking9\Program
For example:
o If you installed the Dragon SDK Client Edition, you must publish the SDK as a Desktop from the
Citrix Presentation Server Console in order to view and run the sample programs from a client.
3. On the Specify Client Requirements dialog box, check the Enable legacy audio setting. For example, if you
are using the Program Neighborhood:
4. Publish the Dragon NaturallySpeaking Citrix Client Update as Content:

64
When publishing the Citrix Client Update from the Presentation Server Console, use vddnspatch.exe as the
Citrix Client Update executable. For example:
Note: You must install this Client Update directly on each client computer. For more information, see
Setting Up the Program Neighborhood on Citrix clients and Starting Dragon NaturallySpeaking from a
Citrix client.
Create a list of applications on the Citrix Server
For Dragon NaturallySpeaking to work correctly with the other applications published on your Citrix servers, you
must do the following:
Creating Policies for Dragon NaturallySpeaking on the Citrix server
You must create two policies for Dragon NaturallySpeaking before users can access Dragon NaturallySpeaking
from their desktops.
Create the AudioIn policy
1. From the Presentation Server Console, select Policies and click the Create Policy button (or
Actions>Policy>Create Policy from the menu) to create a policy named AudioIn.
2. 2. Select the AudioIn policy and then click the Properties button (or Actions>Properties) to set the
properties. Use the Properties dialog to enable Microphones so the client’s microphones can be used for
audio input. For example:
3. Select the AudioIn policy and then click the Apply this policy to button (or Actions>Policy>Apply this
policy…) to specify which users can use the AudioIn policy (in other words, all users who will use Dragon
NaturallySpeaking). This displays the Policy Filters for the AudioIn Policy – select Users and grant access
to the appropriate users.

Create the AudioOut policy
65
1. From the Management Console, select Policies and click the Create Policy… button (or
Actions>Policy>Create Policy from the menu) to create a second policy named AudioOut.
2. Select the AudioOut policy and then click the Properties button to set the properties to enable the Sound
Quality and set the client audio quality to “High sound quality; lowest performance”. For example:
3. Select the AudioOut policy and then click the Apply this policy to button (or Actions>Policy>Apply this
policy…) to specify which users can use the AudioOut policy (in other words, all users who need access to
Dragon NaturallySpeaking). This displays the Policy Filters for the AudioOut Policy – select Users and grant
access to the appropriate users.
Making Published Applications Work together
To be able to use a published Dragon NaturallySpeaking with another published application like Microsoft Word,
both applications must be running in a single Citrix client session.
Use the following guidelines to make sure all published applications work together.
For the Administrator
Give users access to applications
There are two ways to give users access to applications:
1. Publish the desktop and let users start applications from the published desktop.
2. Publish all needed applications with identical settings. If the settings are not identical, Dragon
NaturallySpeaking may not operate correctly in other published applications. For example, if Microsoft
Word is published with different settings than the published NaturallySpeaking, the microphone hotkey will
not work in Word.
For the Client
If you published separate applications and not a Desktop, use the following guidelines:

Notes
66
1. All applications must be started in Seamless mode.
2. Don’t change Application Set settings when a published application is running.
3. When using the Smooth Roaming feature with published applications on multiple computers, the user must
either:
o Close all published applications before moving to a new location.
o Start the same published applications in the same order on all the machines that are used. If a user
left a running published application on one machine and moved to another one, the user should
start the same published application on the next machine. In this case, the user will connect to the
already running application. For example, if the use left published Word running on one computer,
moved to another computer, started published Dragon NaturallySpeaking and then Word,
dictation in Word won't work because Dragon NaturallySpeaking is running in a new session. In
this particular case, the user should first start Word and then Dragon NaturallySpeaking.
• Citrix starts two published applications in separate sessions for single user when:
1. The applications are published with different settings (Colors, Enable Legacy Audio, Encryption).
Citrix places applications into isolated Windows sessions if the color settings are different. Using
different color settings may cause problems with dictation. If you have problems with applications
with different color settings, use the same color settings for all applications.
2. Any single application is published as a Desktop.
3. The client does not start the application in Seamless mode.
4. A client launches one application, changes Application Set settings, and then launches another
application.
5. A user starts different applications from different machines. If the user starts the same application
from a different machine, it connects to the same session and disconnects the previous session, as
in Smooth Roaming feature
Setting Up the Program Neighborhood on Citrix clients
After publishing Dragon NaturallySpeaking and the Citrix Client Update, the Citrix ICA clients should see both
programs in their Citrix Program Neighborhood (or Web Client interface). For example:

Before starting Dragon NaturallySpeaking as a published application, you must enable sound on the client for the
application set for Dragon NaturallySpeaking on each Citrix client.
67
1. From the Citrix Program Neighborhood, select the Application Set that contains Dragon NaturallySpeaking
and the Citrix Client Update.
2. From this Application Set click the Settings button .
This displays the Settings dialog for the selected application set.
3. Select the Default Options tab and unselect User server default and select Enable Sound. In the
dropdown list select High Sound Quality. For example:
Starting Dragon NaturallySpeaking from a Citrix client
If you intend to dictate from the Citrix client, you must run the Citrix Client Update before you run Dragon
NaturallySpeaking for the first time.
Installing the Citrix Client Update
4. Double-click the Citrix Client Update icon in the Program Neighborhood

68
This starts the Citrix Client Update installer wizard.
5. When prompted, click Next and then Patch. Clicking Patch starts the installation.
6. Click Finish when the installation completes.
After installing the Citrix Client Update, you can start Dragon NaturallySpeaking to create your users.
Notes
• In order to run the Citrix Client Update, each client machine must be joined to the network domain of the
Citrix server. In other words, the Citrix server must be able to recognize the client’s Windows logon
credentials. If the client is not joined to network domain of the Citrix server, you will see the following error
when trying to run the Citrix Client Update:
If this is a problem, you can still use network resources by entering your domain user name and password.
Before running the Citrix Client Update:
1. From the Windows Explorer, click on the Tools menu and then click Map Network Drive.
2. In Drive, type or select the drive letter to map to the shared resource.
3. In Folder, type the server and optionally, the share name of the resource, in the form of \\server
name\share name. You can also click Browse to locate the resource.
4. Click Finish.
5. In the User name and password dialog box, type your user name in the form of domain\user name.
6. In Password, type your domain password.
• If during the installation of Citrix Client Update you see the following error message:
" Unable to set High Sound Quality in your Citrix client. It is recommended that you do this manually"

69
Please double-check that the Audio settings on your client are set to high. For more information, see
Setting up Citrix Clients.
• If you are using a Phillips SpeechMike, set up your system so that sound playback is through a different
device and not the SpeechMike. To do this, select Sound and Audio Devices from the Windows control
panel and use the Audio tab to set your Sound playback and Sound recording devices.
• There must be sound system installed on the client. For example, if your client has disabled USB audio, you
cannot create a DNS user. If you disable USB audio, enable it and re-connect to the Citrix server.
The Convert XML to DAT tool
Using the Convert XML to DAT tool
This tool (mycmdsxml2dat.exe) extracts user-defined NaturallySpeaking commands from a .XML file. The tool
writes out the commands to a .DAT file. NaturallySpeaking uses .DAT files to store commands. To make these
commands available to other NaturallySpeaking users, use the nsadmin tool or the Data Distribution Tool to
copy the created .DAT files to those other users.
Note: If you are using the Dragon NaturallySpeaking SDK Client Edition, you can programmatically import
NaturallySpeaking commands stored in .XML or .DAT files into a NaturallySpeaking user profile by using the
DgnEngingControl::ImportMyCommands method.
Starting Convert XML to DAT (mycmdsxml2dat.exe)
To start Convert XML to DAT (mycmdsxml2dat.exe) select:
� For Dragon NaturallySpeaking:
Start>All Programs>Dragon NaturallySpeaking 9>Dragon NaturallySpeaking
Tools>Convert XML to DAT
� For Dragon NaturallySpeaking SDK Client Edition:
Start>All Programs>Dragon SDK Client Edition 9>Dragon SDK Client Tools>Convert XML
to DAT
The Convert XML to DAT tool starts in a DOS window, listing the tool's syntax. To re-display the syntax, enter
the following:
>mycmdsxml2dat
The mycmdsxml2dat.exe program is located in the \Program directory beneath the directory where DSC is
installed. For example, in a default installation:
C:\Program Files\Nuance\NaturallySpeaking9\Program>

Convert XML to DAT (mycmdsxml2dat.exe) syntax
70
Convert XML to DAT (mycmdsxml2dat.exe) uses the following syntax:
mycmdsxml2dat.exe [options]
Required parameters : Description
The full path to the local copy of the current user's .DAT file
The full path to the .XML file
Optional parameters :
-v Validates the specified .xml file over the Internet with a Nuance DTD (Document
Type Definition) file. Disabled by default
Using the XML to DAT tool
To make a set of commands in an XML file available to other users:
1. Create the XML file containing the commands to be used in Dragon NaturallySpeaking.
2. Execute the command line tool, mycmdsXML2DAT.exe, to convert the XML file .dat format.
3. Use the nsadmin tool, to import the .dat file into Dragon NaturallySpeaking for all users.
After using nsadmin or the Data Distribution Tool to copy the .DAT file to a user, that user will have the new
commands available the next time they start Dragon NaturallySpeaking.
For more information, see:
� Adding custom commands (nsadmin)
� Adding and removing custom commands (Data Distribution Tool)
Advanced Scripting Commands
The MyCommands Editor: Advanced Scripting dialog box
Use the MyCommands Editor: Advanced Scripting dialog box to create complex scripts and sequences to perform
virtually any function on the computer using voice commands. Creating these commands requires familiarity with
the Visual Basic programming language.
MyCommand Name
The name of the command. This is what you will say to execute the command. You can click the Train button to
teach Dragon NaturallySpeaking how you pronounce this name. If you enter an angle bracket (

Description
A short description of what the command does (optional).
Group
A list containing the categories in which you can place the command. You use these groups to locate the command
in the Command Browser. By default, the groups Dragon and User-defined are available. To create your own group,
select User-defined and type over it with a group name of your choosing.
Availability
Where the command will be available.
71
Global: The command will be available in every application.
Application-specific: The command will be available in the application you specify. When you select this
option, the applications currently open appear in a list. If the application you want is not open, use the
Browse button to locate the application on your computer.
Window-specific: The command will be available in the window you specify. When you select this option,
the Application and Window lists appear. If the application or window you want is not in the list, you must
close the MyCommands Editor: Advanced Scripting dialog box, open the application or window you want,
and reopen the MyCommands Editor: Advanced Scripting dialog box to see the window listed.
When you select either the Application-specific or Window-specific option, the Recognizable in states list appears.
You can either select from the list or enter the name of a new state. A command with this option will be available
in the state you specify within the window or application you specify.
Command Type
The command type, in this case, Advanced Scripting. There are three other types of commands:
Text and Graphics commands
Step-by-Step commands
Macro Recorder commands
Name Editor
Click this button to open the MyCommands Name Editor dialog box. Use this dialog box to assign variables to your
command such as a name for the command you want to create. Refer to the Help topic on the MyCommands Name
Editor dialog box for more information.
Script
The Script editing window is the location where you create commands. Click the following buttons for an
introduction to either the Advanced Scripting Basic Language or the Dragon Scripting Language.
Advanced Scripting Basic Language
Dragon NaturallySpeaking Scripting Language Extensions
Changes to a line of code are automatically capitalized and highlighted when a different line is selected. This
autoformatting helps you catch typing errors.
Break points can be toggled on/off. A dot at the front of the line indicates a break point.
Toolbar
The Script editing area contains tools to help you create, edit, and test scripts. Click the following button to read a
description of these tools.
The Scripting toolbar

Object:
Select the object type from the list of available objects. The "(General)" object groups all of the procedures, which
are not part of any specific object.
Proc:
The Proc list shows all the procedures for the current object. Use it to select the procedure type from the list of
available procedures. A procedure that is not bold inserts the proper procedure definition for that procedure.
Save
Click Save to save the advanced scripting command. Note that you must give the command a name before this
button is active.
Cancel
Click Cancel to close the Advanced Scripting dialog box without saving any changes you have made since you last
clicked Save.
Create New
Click Create New to open the Advanced Scripting dialog box with a duplicate of the current command. You can
rename and edit the command to create a new command.
Note that this button is active only when you open the editor from the Script mode of the Command Browser by
selecting a command and clicking Edit.
Notes
72
If the Visual Basic code in an Advanced Scripting command contains some runtime errors, a message will
appear describing the error and prompting you to correct it.
Multiple Advanced Scripting commands cannot execute simultaneously. If one Advanced Scripting command
is running, you cannot start another Advanced Scripting command until the first one is finished.
Using ActiveX Components
You can use ActiveX® components in your scripts. Use the following procedure to create commands with ActiveX
components.
To create commands with ActiveX Components
On the Tools menu of the DragonBar, click Add New Command to open the MyCommands dialog box.
By default, the MyCommands Text and Graphics dialog box opens. Select Advanced Scripting from the
Command Type list to open the MyCommands Advanced Scripting dialog box.
In the MyCommand name box, enter what you will say to start the command. Choose a phrase that is easy to
remember but not likely to be used in normal dictation.
In the Description box, enter a description that will help you identify the command.
In the Group list, specify whether this command will be a Dragon command or a User-defined command. If it
is User-defined, you can type over "User-defined" with a group name of your choosing. The new group
name will appear in the list the next time you create a command.
Specify whether the command will work everywhere (Global), in a specific application that you name, or in a
specific window.

73
Click the Browse Object tool to open the ActiveX Automation Members dialog box. Use this dialog box to
build your script with ActiveX variables. If you would like more information about a specific variable, select
it in the Methods/Properties box and click the question mark button to the left of the Help String box.
When you are finished, close the ActiveX Automation Members dialog box and click Save on the MyCommands
Advanced Scripting dialog box.
The Script editing window
You use the Script editing window in the MyCommands Editor: Advanced Scripting dialog box to edit and test your
scripts.
The Script editing window contains the following menu, windows, screens, tabs, and miscellaneous components.
The Advanced Scripting menu
The Script Editor toolbar
The Object and Proc lists
The Break Bar
The Edit area
The Status Bar
The Object Browser
The References dialog box
The UserDialog Editor dialog box
The Immediate, Watch, and Stack windows
When you run a script, the Script editing window appears with three tabs below the toolbar. These are the
Immediate, Watch, and Stack windows.

Item Description
Immediate Evaluates expressions, assigns variables, or calls subroutines.
Watch Displays the variables, expressions, and functions in the current script.
Stack Displays the lines of code that called the current statement.
These three tabs appear when you run your script.
The Advanced Scripting menu
You open the Advanced Scripting menu by pointing to the Script area of the MyCommands Advanced Scripting
dialog box and right-clicking or by pressing Shift+F10. The menu has the following commands:
Item Description
Cut Moves the selected text to the Clipboard.
Copy Copies the selected text to the Clipboard.
Paste Pastes the Clipboard text over the selected text.
Run Runs the script to completion. (If the macro is not active, start it.)
Pause Stops the script. Execution can be resumed.
End Terminates the script. Execution cannot be continued.
Step Into Executes the current line. If the current line is a subroutine or function call, stop
on the first line of that subroutine or function. (If the script is not active, start it.)
Step to Cursor Executes until the line the cursor is on is the current line. (If the script is not
active, start it.)
Toggle Break Toggles a break point on the current line.
74

Clear All Breaks Clears all break points.
Quick Watch Shows the value of the expression under the insertion point in the immediate
window.
Browse Shows the methods of the expression under of the cursor. (see The Object
Browser)
Show Next
Statement
75
Shows the next statement to be executed.
References Opens the References dialog box, which shows the current script/module's
references.
The Advanced Scripting Editor toolbar
The toolbar that appears in the Script editing window contains the following tools:
Tool Description
Cut Deletes the selected text.
Copy Makes a copy of the selected text on the clipboard.
Paste Inserts the contents of the clipboard at the insertion point.
Undo Removes the previous action and restores the contents to their state before
you performed the previous action.
Redo Performs the previously undone action.
Browse Object Opens the ActiveX Automation Members dialog box.
Start/Resume Runs or resumes running the current script.
Pause Stops execution of the current command at the current point in the script. You
can restart the command at this point by clicking the Start/Resume icon.
End Stops execution of the current command.
Toggle Break Enables or disables a breakpoint at the current location.
Evaluate Expression Displays the value of the currently selected variable.
Shows Current
Statement
Displays the value of the currently selected statement.
Step Into Moves program execution into the next statement or module to be run.
Step Over Skips over the next statement or module to be run.
Step Out Skips the remaining statements in the currently running script or subroutine
and goes to the next subroutine or scripts.
Edit UserDialog Displays the Edit UserDialog window where you can graphically create or
modify a UserDialog.
Edit Module
Properties
Disabled in this release of Dragon NaturallySpeaking.
As a result of clicking the Step Into and Step Over buttons, the Immediate, Watch, and Stack windows may appear
in the Script Editor. Click the following buttons to learn more about these windows.
The Immediate Window

The Watch Window
The Stack Window
The Immediate window
The Immediate window of the MyCommands Advanced Scripting dialog box allows you to evaluate an expression,
assign a variable, or call a subroutine.
76
Type "?expr" to show the value of "expr".

77
Type "var = expr" to change the value of "var".
Type "Set var = expr" to change the reference of "var".
Type "subname args" to call a subroutine or built-in instruction.
Type "Trace" to toggle trace mode. Trace mode prints each statement in the Immediate window
when a script is running.
The Watch window
The Watch window allows you to list the variables, functions, and expressions that are calculated and displayed,
and see their current value.

You have to enter the name of a variable, function, or expression in the Watch window. Then, the Watch window
will update the value of that variable, function, or expression.
78
The value of each line in the window is updated each time the execution pauses.

79
You can change the expression to the left of arrow ( ).
Press Enter to update all the values immediately.
Press Ctrl-Y to delete the line.
The Stack window
The Stack window lists the lines that called the current statement.

80
The first line is the current statement. The second line is the statement that called the first line, etc.
Click on a line to bring that script into a sheet and highlight the line in the Script editing window.
Object and Proc lists
The Object list shows all the objects for the current module. The Proc list shows all the procedures for the current
object.
The "(General)" object groups all of the procedures, which are not part of any specific object.
Selecting a procedure that is not bold inserts the proper procedure definition for that procedure.
The Break bar
The Break bar shows which lines have break points. It also shows which line is next to execute.

Click on the Break bar to toggle a break point for that line.
The Edit area
Use the Edit area to view or edit the current script.
81
You can only edit scripts that are not currently loaded.
Changes to a line are automatically capitalized and highlighted when a different line is selected.
Break points can be toggled on/off. A dot at the front of the line indicates a break point.

The Status bar
The Status bar displays status information.
In this example, the status is paused.
The Object Browser
The Object Browser shows information about all the special data types that are available.
Click the Browse Object tool on the MyCommands Advanced Scripting dialog box toolbar to display the
ActiveX Automation Members window.
82

Item Description
Library list Lists all the type libraries.
DataType list Lists all the special data types.
Methods/Properties
list
83
Lists all the methods and/or properties for the current data type.
Info area Displays the method/property name, result or value and the dispatch id. (A
Methods/Properties item must be selected for this to be visible.)
Help area Displays a description of the method or property. The question mark (?)
button is enabled if the object's method/property has help file information.
The "Help String" shows a short description of the method/property.
Parameters list Lists all the parameters for the current method/property. (A
Methods/Properties item must be selected for this to be visible.)
Back button Returns to the previous path shown.
Path edit box Displays the object browser's current path. (A Methods/Properties item must
be selected for this to be visible.)
Paste button Pastes the current method/property into the edit or immediate window.
Close button Closes the object browser window.
The References dialog box
The References dialog box shows the current script or module's references. You can add or remove references to
type libraries from the current script. You can also change the relative priority of a reference. Checked references
are available to the current script. For example, if your script refers to Microsoft Word objects, the Word object

library must be checked. Each checked reference is searched in order from top to bottom. If the desired library
does not appear in the Available References list, click Browse to locate it on your computer.
To open the References dialog box, point to the Script area of the MyCommands Advanced Scripting dialog box and
right-click or press Shift+F10. On the shortcut menu that appears, click References.
Item Description
Available
References list
84
Lists all the registered type libraries. Check the box in front of a reference to
add it. Uncheck the box to remove it.
Priority Up button Moves the current reference towards the top of the list.
Priority Down
button
Moves the current reference towards the bottom of the list.
OK button Changes the current macro or module's references.
Cancel button Closes the references dialog without changing the current macro or module's
references.
Browse button Opens a dialog box with which you can search for and select libraries. These
are files with the extensions .OLB, .TLB, and .DLL.
Info area Displays the selected reference's language and where it is located.
The UserDialog Editor dialog box
The UserDialog Editor dialog box allows you to create and modify dialog boxes.
Click the Edit UserDialog tool on the MyCommands Advanced Scripting dialog box toolbar to display the
UserDialog Editor dialog box.

In the code, a UserDialog is described by a Begin Dialog...End Dialog block. To graphically edit a UserDialog, place
the current selection in a UserDialog block and click on the Edit UserDialog tool.
The top row of icons in the UserDialog window has the following components, which you can use to edit the
contents of a dialog box:
Item Description
Edit Item Properties Edits the selected item's properties. Hot key: Enter
Delete Deletes the selected item. Hot key: Del
Cut Moves the selected item to the Clipboard. Hot key: Ctrl+X
Copy Copies the selected item to the Clipboard. Hot key: Ctrl+C
Paste Pastes the Clipboard item in front of the selected item. Hot
key: Ctrl+Z
Move In Front (towards End
Dialog)
Move Behind (towards Begin
Dialog)
Select Behind (towards Begin
Dialog)
Select In Front (towards End
Dialog)
85
Moves the selected item in front. Hot key: Ctrl+Up
Moves the selected item behind). Hot key: Ctrl+Down
Selects the item behind the selected item.
Selects the item in front of the selected item.
Set Grid Changes the grid settings. Hot key: Ctrl+G
Save and Exit Saves the UserDialog and exits the UserDialog editor.
The gallery on the left has the following options, listed from left to right and top to bottom. To add a control to your
UserDialog, click this control's item in the gallery, then "draw" the control on the UserDialog grid.
Item Description
Select Selects, moves, or edits item mode.

Add GroupBox Adds a GroupBox item.
Add Text Adds a Text item.
Add TextBox Adds a TextBox item.
Add CheckBox Adds a CheckBox item.
Add OptionButton Adds an OptionButton item.
Add ComboBox Adds a ComboBox item.
Add ListBox Adds a ListBox item.
Add DropListBox Adds a DropListBox item.
Add Picture Adds a Picture item.
Add OKButton Adds an OKButton item.
Add CancelButton Adds a CancelButton item.
Add PushButton Adds a PushButton item.
Advanced Scripting Basic Language
The Advanced Scripting Basic Language provides the core language definition. It is Visual Basic for Applications
compatible.
Language reference by group:
86
Declaration, Data Type, Assignment
Flow Control, Error Handling
Conversion, Variable Info
Constant
Math, String, Object, Time/Date
File
User Input, User Dialog, Dialog Function
DDE
Settings
Miscellaneous
Operator
Objects Overview
ActiveX Automation provides access to objects in other applications. Each object supports a particular set of
methods and properties. Each method/property has zero or more parameters. Parameters may be optional, in
which case the parameter can be specified by using name := value.
objexpr.method [expr][, ...] [param := expr][,...]
Call method for objexpr.

objexpr.method[([expr][, ...] [param := expr][,...])]
Return the value of method for objexpr.
objexpr.property[([expr][, ...] [param := expr][,...])]
Return the value of property for objexpr.
objexpr[([expr][, ...] [param := expr][,...])]
Return the default value for the objexpr.
objexpr.property[([expr][, ...])] = expr
Assign the value of property for objexpr.
objexpr[([expr][, ...])] = expr
Assign the default value for the objexpr.
Set objexpr.property[([expr][, ...])] = objexpr
Set the object reference of property for objexpr.
Note: objexpr!name is shorthand for objexpr.defaultproperty("name"). Use objexpr![name] if name contains any
characters that are not allowed in an identifier.
Operators
Syntax
^ Not * / \ Mod + - & < >= = Is And Or Xor Eqv Imp
Description
These operators are available for numbers n1 and n2 or strings s1 and s2. If any value in an expression is Null then
the expression's value is Null. The order of operator evaluation is controlled by operator precedence.
Operator Description
- n1 Negate n1.
n1 ^ n2 Raise n1 to the power of n2.
n1 * n2 Multiply n1 by n2.
n1 / n2 Divide n1 by n2.
n1 \ n2 Divide the integer value of n1 by the integer value of n2.
n1 Mod n2 Remainder of the integer value of n1 after dividing by the integer value of n2.
n1 + n2 Add n1 to n2.
s1 + s2 Concatenate s1 with s2.
n1 - n2 Difference of n1 and n2.
s1 & s2 Concatenate s1 with s2.
n1 < n2 Return True if n1 is less than n2.
n1 n2 Return True if n1 is greater than n2.
n1 >= n2 Return True if n1 is greater than or equal to n2.
n1 = n2 Return True if n1 is equal to n2.
n1 n2 Return True if n1 is not equal to n2.
s1 < s2 Return True if s1 is less than s2.
s1 s2 Return True if s1 is greater than s2.
s1 >= s2 Return True if s1 is greater than or equal to s2.
s1 = s2 Return True if s1 is equal to s2.
s1 s2 Return True if s1 is not equal to s2.
Not n1 Bitwise invert the integer value of n1. Only Not True is False.
n1 And n2 Bitwise and the integer value of n1 with the integer value n2.
n1 Or n2 Bitwise or the integer value of n1 with the integer value n2.
87

n1 Xor n2 Bitwise exclusive-or the integer value of n1 with the integer value n2.
n1 Eqv n2 Bitwise equivalence the integer value of n1 with the integer value n2 (same as Not (n1
Xor n2)).
n1 Imp n2 Bitwise implicate the integer value of n1 with the integer value n2 (same as (Not n1)
Or n2).
Example
Sub Main
N1 = 10
N2 = 3
S1$ = "asdfg"
S2$ = "hjkl"
Debug.Print -N1 '-10
Debug.Print N1 ^ N2 ' 1000
Debug.Print Not N1 '-11
Debug.Print N1 * N2 ' 30
Debug.Print N1 / N2 ' 3.3333333333333
Debug.Print N1 \ N2 ' 3
Debug.Print N1 Mod N2 ' 1
Debug.Print N1 + N2 ' 13
Debug.Print S1$ + S2$ '"asdfghjkl"
Debug.Print N1 - N2 ' 7
Debug.Print N1 & N2 '"103"
Debug.Print N1 < N2 'False
Debug.Print N1 = N2 'True
Debug.Print N1 = N2 'False
Debug.Print N1 N2 'True
Debug.Print S1$ < S2$ 'True
Debug.Print S1$ = S2$ 'False
Debug.Print S1$ = S2$ 'False
Debug.Print S1$ S2$ 'True
Debug.Print N1 And N2 ' 2
Debug.Print N1 Or N2 ' 11
Debug.Print N1 Xor N2 ' 9
Debug.Print N1 Eqv N2 ' -10
Debug.Print N1 Imp N2 ' -9
End Sub
All Functions by Groups
Declaration:
#Reference, #Uses, Attribute, Class Module, Code Module, Const, Declare, Deftype, Dim, Enum...End Enum,
Function...End Function, Object Module, Option, Private, Property...End Property, Public, ReDim, Static, Sub...End
Sub, Type...End Type. WithEvents
Data Type:
Any, Boolean, Byte, Currency, Date, Decimal, Double, Integer, Long, Object, PortInt, Single, String, String*n,
Variant, obj type, user enum, user type.
Assignment:
Erase, Let, LSet, RSet, Set.
88

Flow Control:
Call, CallByName, Do...Loop, End, Exit, For...Next, For Each...Next, GoTo, If...ElseIf...Else...End If, MacroRun,
MacroRunThis, Select Case...End Select, Stop, While...Wend.
Error Handling:
Err, Error, On Error, Resume.
Conversion:
Array, CBool, CByte, CCur, CDate, CDec, CDbl, CInt, CLng, CSng, CStr, CVar, CVDate, CVErr, Val.
Variable Info:
IsArray, IsDate, IsEmpty, IsError, IsMissing, IsNull, IsNumeric, IsObject, LBound, TypeName, UBound, VarType.
Constant:
Empty, False, Nothing, Null, True, Win16, Win32.
Math:
Abs, Atn, Cos, Exp, Fix, Int, Log, Randomize, Rnd, Round, Sgn, Sin, Sqr, Tan.
String:
Asc, AscB, AscW, Chr, ChrB, ChrW, Format, Hex, InStr, InStrB, InStrRev, LCase, Left, LeftB, Len, LenB, LTrim, Mid,
MidB, Oct, Replace, Right, RightB, RTrim, Space, String, Str, StrComp, StrConv, StrReverse, Trim, UCase.
Object:
CreateObject, GetObject, Me, With...End With.
Time/Date:
Date, DateAdd, DateDiff, DatePart, DateSerial, DateValue, Day, Hour, Minute, Month, MonthName, Now, Second,
Time, Timer, TimeSerial, TimeValue, Weekday, WeekdayName, Year.
File:
ChDir, ChDrive, Close, CurDir, Dir, EOF, FileAttr, FileCopy, FileDateTime, FileLen, FreeFile, Get, GetAttr, Input,
Input, Kill, Line Input, Loc, Lock, LOF, MkDir, Name, Open, Print, Put, Reset, RmDir, Seek, Seek, SetAttr, Unlock,
Write.
User Input:
Dialog, GetFilePath, InputBox, MsgBox. ShowPopupMenu
User Dialog:
Begin Dialog...End Dialog, CancelButton, CheckBox, ComboBox, DropListBox, GroupBox, ListBox, OKButton,
OptionButton, OptionGroup, Picture, PushButton, Text, TextBox.
Dialog Function:
Dialog Func, DlgControlId, DlgCount, DlgEnable, DlgEnd, DlgFocus, DlgListBoxArray, DlgName, DlgNumber,
DlgSetPicture, DlgText, DlgType, DlgValue, DlgVisible.
DDE:
DDEExecute, DDEInitiate, DDEPoke, DDERequest, DDETerminate, DDETerminateAll.
Settings:
DeleteSetting, GetAllSettings, GetSetting, SaveSetting
Miscellaneous:
AboutWinWrapBasic, AppActivate, Attribute, Beep, CallersLine, Choose, Clipboard, Command, Debug.Print,
DoEvents, Environ, Eval, IIf, KeyName, MacroDir, QBColor, Rem, RGB, SendKeys, Shell, Wait.
Operator:
Operators: +, -, ^, *, /, \, Mod, +, -, &, =, , , =, Like. Not, And, Or, Xor, Eqv, Imp, Is.
Assignment Group
Erase, Let, LSet, RSet, Set.
89

Constant Group
Empty, False, Nothing, Null, True, Win16, Win32.
Conversion Group
Array, CBool, CByte, CCur, CDate, CDec, CDbl, CInt, CLng, CSng, CStr, CVar, CVDate, CVErr, Val.
Data Type Group
Any, Boolean, Byte, Currency, Date, Decimal, Double, Integer, Long, Object, PortInt, Single, String, String*n,
Variant, obj type, user enum, user type.
DDE Group
DDEExecute, DDEInitiate, DDEPoke, DDERequest, DDETerminate, DDETerminateAll.
Declaration Group
#Reference, #Uses, Attribute, Class Module, Code Module, Const, Declare, Deftype, Dim, Enum...End Enum,
Function...End Function, Object Module, Option, Private, Property...End Property, Public, ReDim, Static, Sub...End
Sub, Type...End Type. WithEvents
Dialog Function Group
Dialog Func, DlgControlId, DlgCount, DlgEnable, DlgEnd, DlgFocus, DlgListBoxArray, DlgName, DlgNumber,
DlgSetPicture, DlgText, DlgType, DlgValue, DlgVisible.
Error Handling Group
Err, Error, On Error, Resume.
90

File Group
ChDir, ChDrive, Close, CurDir, Dir, EOF, FileAttr, FileCopy, FileDateTime, FileLen, FreeFile, Get, GetAttr, Input,
Input, Kill, Line Input, Loc, Lock, LOF, MkDir, Name, Open, Print, Put, Reset, RmDir, Seek, Seek, SetAttr, Unlock,
Write.
Flow Control Group
Call, CallByName, Do...Loop, End, Exit, For...Next, For Each...Next, GoTo, If...ElseIf...Else...End If, MacroRun,
MacroRunThis, Select Case...End Select, Stop, While...Wend.
Math Group
Abs, Atn, Cos, Exp, Fix, Int, Log, Randomize, Rnd, Round, Sgn, Sin, Sqr, Tan.
Miscellaneous Group
AboutWinWrapBasic, AppActivate, Attribute, Beep, CallersLine, Choose, Clipboard, Command, Debug.Print,
DoEvents, Environ, Eval, IIf, KeyName, MacroDir, QBColor, Rem, RGB, SendKeys, Shell, Wait.
Object Group
CreateObject, GetObject, Me, With...End With.
Operator Group
Operators: +, -, ^, *, /, \, Mod, +, -, &, =, , , =, Like. Not, And, Or, Xor, Eqv, Imp, Is.
Settings Group
DeleteSetting, GetAllSettings, GetSetting, SaveSetting
91

String Group
Asc, AscB, AscW, Chr, ChrB, ChrW, Format, Hex, InStr, InStrB, InStrRev, LCase, Left, LeftB, Len, LenB, LTrim, Mid,
MidB, Oct, Replace, Right, RightB, RTrim, Space, String, Str, StrComp, StrConv, StrReverse, Trim, UCase.
Time/Date Group
Date, DateAdd, DateDiff, DatePart, DateSerial, DateValue, Day, Hour, Minute, Month, MonthName, Now, Second,
Time, Timer, TimeSerial, TimeValue, Weekday, WeekdayName, Year.
User Dialog Group
Begin Dialog...End Dialog, CancelButton, CheckBox, ComboBox, DropListBox, GroupBox, ListBox, MultiListBox,
OKButton, OptionButton, OptionGroup, Picture, PushButton, Text, TextBox.
User Input Group
Dialog, GetFilePath, InputBox, MsgBox. ShowPopupMenu
Variable Info Group
IsArray, IsDate, IsEmpty, IsError, IsMissing, IsNull, IsNumeric, IsObject, LBound, TypeName, UBound, VarType.
Class Module
Group
Declaration
Description
A class module implements an ActiveX Automation object.
Has a set of Public procedures accessible from other macros and modules.
These public symbols are accessed via an object variable.
Public Consts, Types, arrays, fixed length strings are not allowed.
A class module is similar to a object module except that no instance is automatically created.
To create an instance use:
92

93
C:\ABCTemp\vbs\Dim_Definition00000109.htm
Dim Obj As classname
Set Obj = New classname
Can optionally contain Attributes one of which must be VB_Name.
See Also: Attribute Definition/Statement, Code Module, Object Module, Uses.
Example
'MyCommands macro
'#Uses "File.CLS"
Sub Main
Dim File As New File
File.Attach "C:\AUTOEXEC.BAT"
Debug.Print File.ReadLine
End Sub
'File.CLS class file
VERSION 1.0 CLASS
BEGIN
MultiUse = -1 'True
END
Attribute VB_Name = "File"
Option Explicit
Dim FN As Integer
Public Sub Attach(FileName As String)
FN = FreeFile
Open FileName For Input As #FN
End Sub
Public Sub Detach()
If FN 0 Then Close #FN
FN = 0
End Sub
Public Function ReadLine() As String
Line Input #FN,ReadLine
End Function
Private Sub Class_Initialize()
Debug.Print "Class_Initialize"
End Sub
Private Sub Class_Terminate()
Debug.Print "Class_Terminate"
Detach
End Sub

Code Module
Group
Declaration
Description
A Code module implements a code library.
Has a set of Public procedures accessible from other macros and modules.
The public symbols are accessed directly.
Can optionally contain Attributes
See Also: Attribute Definition/Statement, Class Module, Object Module, Uses.
Example
'MyCommands macro
'#Uses "Module1.BAS"
Sub Main
Debug.Print Value '"Hello"
End Sub
'Module1.BAS code file
Attribute VB_Name = "Module1"
Option Explicit
Private mValue As String
Property Get Value() As String
Value = mValue
End Property
'this sub is called when the module is first loaded
Private Sub Main
mValue = "Hello"
End Sub
Object Module
Group
Declaration
Description
An object module implements an ActiveX Automation object.
It has a set of Public procedures accessible from other macros and modules.
These public symbols are accessed via the name of the object module or an object variable.
94

Public Consts, Types, arrays, fixed length strings are not allowed.
An object module is similar to a class module except that one instance is automatically created. That instance
has the same name as the object module's name.
To create additional instances use:
C:\ABCTemp\vbs\Dim_Definition00000109.htm
Dim Obj As objectname
Set Obj = New objectname
It can optionally contain Attributes one of which must be VB_Name.
See Also: Attribute Definition/Statement, Class Module, Code Module, Uses.
Example
'MyCommands macro
'#Uses "Sample.OBM"
Sub Main
Debug.Print Sample.Name
End Sub
'Sample.OBM object file
VERSION 1.0 OBJECT
BEGIN
MultiUse = -1 'True
END
Attribute VB_Name = "Sample"
Option Explicit
Public Function Name() As String
Name = "Sample Object Module"
End Function
Any Data Type
Group
Data Type
Description
Any variable expression (Declare only).
Boolean Data Type
Group
Data Type
95

Description
A True or False value.
Byte Data Type
Group
Data Type
Description
An 8 bit unsigned integer value.
Currency Data Type
Group
Data Type
Description
A 64 bit fixed point real. (A twos complement binary value scaled by 10000.)
Date Data Type
Group
Data Type
Description
A 64 bit real value. The whole part represents the date, while the fractional part is the time of day. (December 30,
1899 = 0.) Use #date# as a literal date value in an expression.
Decimal Data Type
Group
Data Type
Description
96

Win32 only. A 96 bit scaled real value. Decimal is not a valid variable type, but Variant variables can contain
decimal values (see CDec). A decimal number is of the form: s*m*10^-p where
s - sign (+1 or -1)
m - mantissa, unsigned binary value of 96 bits (0 to 79,228,162,514,264,337,593,543,950,335)
p - scaling power (0 to +28)
Double Data Type
Group
Data Type
Description
A 64 bit real value.
Integer Data Type
Group
Data Type
Description
A 16 bit integer value.
Long Data Type
Group
Data Type
Description
A 32 bit integer value.
Object Data Type
Group
Data Type
97

Description
An object reference value. (see Objects)
PortInt Data Type
Group
Data Type
Description
A portable integer value.
For Win16: A 16 bit integer value.
For Win32: A 32 bit integer value.
Single Data Type
Group
Data Type
Description
A 32 bit real value.
String Data Type
Group
Data Type
Description
An arbitrary length string value. Some useful string constants are predefined:
vbNullChar - same as Chr(0)
vbCrLf - same as Chr(13) & Chr(10)
vbCr - same as Chr(13)
vbLf - same as Chr(10)
vbBack - same as Chr(8)
vbFormFeed - same as Chr(12)
vbTab - same as Chr(9)
98

vbVerticalTab - same as Chr(11)
String*n Data Type
Group
Data Type
Description
A fixed length (n) string value.
UserDialog Data Type
Group
Data Type
Description
A usertype defined by Begin Dialog UserDialog.
Variant Data Type
Group
Data Type
Description
An empty, numeric, currency, date, string, object, error code, null or array value.
Usertype definition
User defined types are defined with Type.
Empty Keyword
Group
99

Constant
Description
A variantvar that does not have any value.
False Keyword
Group
Constant
Description
A condexpr is false when its value is zero. A function that returns False returns the value 0.
Nothing Keyword
Group
Constant
Description
An objexpr that does not refer to any object.
Null Keyword
Group
Constant
Description
A variant expression that is null. A null value propagates through an expression causing the entire expression to be
Null. Attempting to use a Null value as a string or numeric argument causes a run-time error. A Null value prints
as "#NULL#".
Example
Sub Main
X = Null
Debug.Print X = Null '#NULL#
Debug.Print IsNull(X) 'True
End Sub
100

True Keyword
Group
Constant
Description
A conditional expression is True when its value is non-zero. A function that returns True returns the value -1.
Win16 Keyword
Group
Constant
Description
True if running in 16 bits. False if running in 32 bits.
Win32 Keyword
Group
Constant
Description
True if running in 32 bits. False if running in 16 bits.
Friend Keyword
Group
Declaration
Description
Friend Functions, Propertys and Subs in a module are available in all other macros/modules that access it. Friends
are not accessible via Object variables.
101

Main Sub
Syntax
Sub Main()
...
End Sub
-or-
Private Sub Main()
...
End Sub
Group
Declaration
Description
Form 1: Each macro must define Sub Main. A macro is a "program". Running a macro starts the Sub Main and
continues to execute until the subroutine finishes.
Form 2: A code module may define a Private Sub Main. This Sub Main is the code module initialization subroutine.
If Main is not defined then no special initialization occurs.
See Also: Code Module.
Object_Initialize Sub
Syntax
Private Sub Object_Initialize()
...
End Sub
Group
Declaration
Description
Object module initialization subroutine. Each time a new instance is created for a Object module the
Object_Initialize sub is called. If Object_Initialize is not defined then no special initialization occurs.
Note: Object_Initialize is also called for the instance that is automatically created.
See Also: Object Module, Object_Terminate.
Object_Terminate Sub
Syntax
102

Private Sub Object_Terminate()
...
End Sub
Group
Declaration
Description
Object module termination subroutine. Each time an instance is destroyed for a Object module the
Object_Terminate sub is called. If Object_Terminate is not defined then no special termination occurs.
See Also: Object Module, Object_Initialize.
Set Instruction
Syntax
Set objvar = objexpr
-or-
Set objvar = New objtype
Group
Assignment
Description
Form 1: Set objvar's object reference to the object reference of objexpr.
Form 2: Set objvar's object reference to the a new instance of objtype.
The Set instruction is how object references are assigned.
Example
Sub Main
Dim App As Object
Set App = CreateObject("WinWrap.CppDemoApplication")
App.Move 20,30 ' move icon to 20,30
Set App = Nothing
App.Quit ' run-time error (no object)
End Sub
Private Keyword
Group
Declaration
Description:
103

Private Consts, Declares, Functions, Propertys, Subs and Types are only available in the current macro/module.
Public Keyword
Group
Declaration
Description
Public Consts, Declares, Functions, Propertys, Subs and Types in a module are available in all other
macros/modules that access it.
AboutWinWrapBasic Instruction
Syntax
AboutWinWrapBasic [Timeout]
Group
Miscellaneous
Description
Show the WinWrap Basic about box.
Parameter Description
Timeout This numeric value is the maximum number of seconds to show the about box. A
value less than or equal to zero displays the about box until the user closes it. If this
value is omitted then a three second timeout is used.
Example
Sub Main
AboutWinWrapBasic
End Sub
Abs Function
Syntax
Abs(Num)
Group
Math
104

Description
Return the absolute value.
Parameter Description
Num Return the absolute value of this numeric value. If this value is Null then Null is
returned.
Example
Sub Main
Debug.Print Abs(9) ' 9
Debug.Print Abs(0) ' 0
Debug.Print Abs(-9) ' 9
End Sub
AppActivate Instruction
Syntax
AppActivate Title$
-or-
AppActivate TaskID
Group
Miscellaneous
Description
Form 1: Activate the application top-level window titled Title$. If no window by that title exists then the first
window with at title that starts with Title$ is activated. If no window matches then an error occurs.
Form 2: Activate the application top-level window for task TaskID. If no window for that task exists then an error
occurs.
Parameter Description
Title$ The name shown in the title bar of the window.
TaskID This numeric value is the task identifier.
See Also: SendKeys, Shell( ).
Example
Sub Main
' make ProgMan the active application
AppActivate "Program Manager"
End Sub
arglist definition
[ | expr | param:=expr ][, ...]
A list of zero or more exprs that are assigned to the parameters of the procedure.
105

106
A positional parameter may be skipped by omitting the expression. Only optional parameters may be
skipped.
Positional parameter assignment is done with expr. Each parameter is assigned in turn. By name parameter
assignment may follow.
By name parameter assignment is done with param:=expr. All following parameters must be assigned by
name.
Array Function
Syntax
Array([expr[, ...]])
Group
Conversion
Description
Return a variant value array containing the exprs.
Example
Sub Main
X = Array(0,1,4,9)
Debug.Print X(2) ' 4
End Sub
Array variable definition
A variable that holds an array of values. A Variant variable can hold an array. Dynamic arrays can be
ReDimensioned.
As [New] type definition
Dim, Private, Public and Static statements may declare variable types using As type or As New objtype. A variable
declared using As New objtype is automatically created prior to use, if the variable is Nothing.
Asc Function
Syntax
Asc(S$)

Group
String
Description
Return the ASCII value.
Note: A similar function, AscB, returns the first byte in S$. Another similar function, AscW, returns the Unicode
number.
Parameter Description
S$ Return the ASCII value of the first char in this string value.
See Also: Chr$( ).
Example
Sub Main
Debug.Print Asc("A") ' 65
End Sub
As type definition
Variable and parameter types, as well as, function and property results may be specified using As type: Boolean,
Byte, Currency, Date, Double, Integer, Long, Object, PortInt, Single, String, String*n, UserDialog, Variant, objtype,
userenum, usertype.
Atn Function
Syntax
Atn(Num)
Group
Math
Description
Return the arc tangent.
Parameter Description
Num Return the arc tangent of this numeric value. This is the number of radians. There are
2*Pi radians in a full circle.
Example
Sub Main
Debug.Print Atn(1)*4 ' 3.1415926535898
End Sub
107

Attribute definition
A file attribute is zero or more of the following values added together.
Attribute Value
vbNormal 0 Normal file.
vbReadOnly 1 Read-only file.
vbHidden 2 Hidden file.
vbSystem 4 System file.
vbVolume 8 Volume label.
vbDirectory 16 MS-DOS directory.
vbArchive 32 File has changes since last backup.
Attribute Definition/Statement
Syntax
Attribute attributename = value
Attribute varname.attributename = value
Attribute procname.attributename = value
Group
Declaration
Description
All attribute definitions and statements are ignored except for:
108
Form 1: Module level attribute
Attribute VB_Name = "name"
Attribute VB_GlobalNameSpace = bool
Attribute VB_Creatable = bool
Attribute VB_PredeclaredId = bool
Attribute VB_Exposed = bool
Attribute VB_HelpID = int
Attribute VB_Description = "text"
VB_Name - Declares the name of the class module or object module.
VB_GlobalNameSpace - Declares the class module as a global class. (ignored)
VB_Creatable - Declares the module as creatable (True), non-creatable (False). (ignored)
VB_PredeclaredId - Declares the module as a predeclared identifier (True). (ignored)
VB_Exposed - Declares the module as public (True). (ignored)
VB_HelpID - Declares the module's help context displayed by the object browser.
VB_Description - Declares the module's help text displayed by the object browser.
Form 2: Macro/Module level variable attribute
Public varname As Type
Attribute varname.VB_VarUserMemId = 0
Attribute varname.VB_VarHelpID = int
Attribute varname.VB_VarDescription = "text"

109
VB_VarUserMemID - Declares Public varname as the default property for a class module or object module.
VB_VarHelpID - Declares the variable's help context displayed by the object browser.
VB_VarDescription - Declares the variable's help text displayed by the object browser.
Form 3: User defined procedure attribute
[Sub | Function | Property [Get|Let|Set] procname ...
Attribute procname.VB_UserMemId = 0
Attribute procname.VB_HelpID = int
Attribute procname.VB_Description = "text"
...
End [Sub | Function | Property]
VB_UserMemID - Declares Property procname as the default property for a class module or object module.
VB_HelpID - Declares the procedure's help context displayed by the object browser.
VB_Description - Declares the procedure's help text displayed by the object browser.
HelpFile:
Each macro/module can define the HelpFile for the object browser:
'#HelpFile "helpfile"
where "helpfile" is a full path to the help file associated with the help text and help context.
Beep Instruction
Syntax
Beep
Group
Miscellaneous
Description
Sound the bell.
Example
Sub Main
Beep ' beep the bell
End Sub
Begin Dialog Definition
Syntax
Begin Dialog UserDialog [X, Y,] DX, DY[, Title$] _
[, .dialogfunc]
User Dialog Item

[User Dialog Item]...
End Dialog
Group
User Dialog
Description
Define a UserDialog type to be used later in a Dim As UserDialog statement.
Parameter Description
X This numeric value is the distance from the left edge of the screen to the left edge of
the dialog box. It is measured in 1/8ths of the average character width for the
dialog's font. If this is omitted then the dialog will be centered.
Y This numeric value is the distance from the top edge of the screen to the top edge of
the dialog box. It is measured in 1/12ths of the average character width for the
dialog's font. If this is omitted then the dialog will be centered.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
Title$ This string value is the title of the user dialog. If this is omitted then there is no title.
dialogfunc This is the function name that implements the DialogFunc for this UserDialog. If this
is omitted then the UserDialog doesn't have a dialogfunc.
User Dialog Item
One of: CancelButton, CheckBox, ComboBox, DropListBox, GroupBox, ListBox, MultiListBox, OKButton,
OptionButton, OptionGroup, PushButton, Text, TextBox.
See Also: Dim As UserDialog.
Example
Sub Main
Begin Dialog UserDialog 200,120
Text 10,10,180,15,"Please push the OK button"
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
Dialog dlg ' show dialog (wait for ok)
End Sub
Big-endian definition
Multiple byte data values (not strings) are stored with the highest order byte first. For example, the long integer
&H01020304 is stored as this sequence of four bytes: &H01, &H02, &H03 and &H04. A Binary or Random file
written using Put uses little-endian format so that it can be read using Get on any machine. (Big-endian machines,
like the Power-PC, reverse the bytes as they are read by Get or written by Put.)
See Also: Dir( ), GetAttr( ), SetAttr( ).
110

Call Instruction
Syntax
Call name[(arglist)]
-or-
name [arglist]
Group
Flow Control
Description
Evaluate the arglist and call subroutine (or function) name with those values. Sub (or function) name must be
previously defined by either a Sub, Function or Property definition. If name is a function then the result is discarded.
If Call is omitted then name must be a subroutine and the arglist is not enclosed in parens.
See Also: Declare, Sub.
Example
Sub Show(Title$,Value)
Debug.Print Title$;"=";Value
End Sub
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
Call Show("2000/9",2000/9) ' 222.2222222222
Show "1

vbSet 8 Set the property's reference
Example
Sub Main
On Error Resume Next
CallByName Err, "Raise", vbMethod, 1
Debug.Print CallByName(Err, "Number", vbGet) ' 1
End Sub
CallersLine Function
Syntax
CallersLine[(Depth)]
Group
Miscellaneous
Description
Return the caller's line as a text string.
The text format is: "[macroname|subname#linenum] linetext".
Parameter Description
Depth This integer value indicates how deep into the stack to get the caller's line. If Depth
= -1 then return the current line. If Depth = 0 then return the calling subroutine's
current line, etc.. If Depth is greater than or equal to the call stack depth then a null
string is returned. If this value is omitted then the depth is 0.
Example
Sub Main
A
End Sub
Sub A
Debug.Print CallersLine '"[(untitled 1)|Main# 2] A"
End Sub
CancelButton Dialog Item Definition
Syntax
CancelButton X, Y, DX, DY[, .Field]
Group
User Dialog
Description
112

Define a cancel button item. Pressing the Cancel button from a Dialog instruction causes a run-time error.
(Dialog( ) function call returns 0.)
Parameter Description
X This numeric value is the distance from the left edge of the screen to the left edge of
the dialog box. It is measured in 1/8ths of the average character width for the
dialog's font.
Y This numeric value is the distance from the top edge of the screen to the top edge of
the dialog box. It is measured in 1/12ths of the average character width for the
dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
Field This identifier is the name of the field. The dialogfunc receives this name as string. If
this is omitted then the field name is "Cancel".
See Also: Begin Dialog, Dim As UserDialog.
Example
Sub Main
Begin Dialog UserDialog 200,120
Text 10,10,180,30,"Please push the Cancel button"
OKButton 40,90,40,20
CancelButton 110,90,60,20
End Dialog
Dim dlg As UserDialog
Dialog dlg ' show dialog (wait for cancel)
Debug.Print "Cancel was not pressed"
End Sub
CBool Function
Syntax
CBool(Num|$)
Group
Conversion
Description
Convert to a boolean value. Zero converts to False, while all other values convert to True.
Parameter Description
Num|$ Convert a number or string value to a boolean value.
Example
Sub Main
Debug.Print CBool(-1) 'True
Debug.Print CBool(0) 'False
Debug.Print CBool(1) 'True
End Sub
113

CByte Function
Syntax
CByte(Num|$)
Group
Conversion
Description
Convert to a byte value.
Parameter Description
Num|$ Convert a number or string value to a byte value.
Example
Sub Main
Debug.Print CByte(1.6) ' 2
End Sub
CCur Function
Syntax
CCur(Num|$)
Group
Conversion
Description
Convert to a currency value.
Parameter Description
Num|$ Convert a number or string value to a currency value.
Example
Sub Main
Debug.Print CCur("1E6") ' 1000000
End Sub
CDate Function
Syntax
114

CDate(Num|$)
-or-
CVDate(Num|$)
Group
Conversion
Description
Convert to a date value.
Parameter Description
Num|$ Convert a number or string value to a date value.
Example
Sub Main
Debug.Print CDate(2) ' 1/1/00
End Sub
CDbl Function
Syntax
CDbl(Num|$)
Group
Conversion
Description
Convert to a double precision real.
Parameter Description
Num|$ Convert a number or string value to a double precision real.
Example
Sub Main
Debug.Print CDbl("1E6") ' 1000000
End Sub
CDec Function
Syntax
CDec(Num|$)
Group
Conversion
115

Description
Win32 only. Convert to a decimal (96 bit scaled real).
Parameter Description
Num|$ Convert a number or string value to a 96 bit scaled real.
Example
Sub Main
Debug.Print CDec("1E16")+0.1 ' 10000000000000000.1
End Sub
charlist definition
A group of one or more characters enclosed by [ ] as part of Like operator's right string expression.
This list contains single characters and/or character ranges which describe the characters in the list.
A range of characters is indicated with a hyphen (-) between two characters. The first character must be
ordinally less than or equal to the second character.
Special pattern characters like ?, *, # and [ can be matched as literal characters.
The ] character can not be part of charlist, but it can be part of the pattern outside the charlist.
ChDir Instruction
Syntax
ChDir Dir$
Group
File
Description
Change the current directory to Dir$.
Parameter Description
Dir$ This string value is the path and name of the directory.
See Also: ChDrive, CurDir$( ).
Example
Sub Main
ChDir "C:\"
Debug.Print CurDir$() '"C:\"
End Sub
116

ChDrive Instruction
Syntax
ChDrive Drive$
Group
File
Description
Change the current drive to Drive$.
Parameter Description
Drive$ This string value is the drive letter.
See Also: ChDir, CurDir$( ).
Example
Sub Main
ChDrive "B"
Debug.Print CurDir$() '"B:\"
End Sub
CheckBox Dialog Item Definition
Syntax
CheckBox X, Y, DX, DY, Title$, .Field[, Options]
Group
User Dialog
Description
Define a checkbox item.
Parameter Description
X This number value is the distance from the left edge of the dialog box. It is measured
in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is measured
in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
Field The value of the check box is accessed via this field. Unchecked is 0, checked is 1 and
grayed is 2.
Options This numeric value controls the type of check box. Choose one value from following
table. (If this numeric value omitted then zero is used.)
Option Description
0 Check box is either checked or unchecked.
117

1 Check box is either checked, unchecked or grayed, and it switches between checked and
unchecked when clicked.
2 Check box is either checked, unchecked or grayed, and it cycles through all three states
as the button is clicked.
See Also: Begin Dialog, Dim As UserDialog.
Example
Sub Main
Begin Dialog UserDialog 200,120
Text 10,10,180,15,"Please push the OK button"
CheckBox 10,25,180,15,"&Check box",.Check
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
dlg.Check = 1
Dialog dlg ' show dialog (wait for ok)
Debug.Print dlg.Check
End Sub
Choose Function
Syntax
Choose(Index, expr[, ...])
Group
Flow Control
Description
Return the value of the expr indicated by Index.
Parameter Description
Index The numeric value indicates which expr to return. If this value is less than one
or greater than the number of exprs then Null is returned.
expr
All expressions are evaluated.
See Also: If, Select Case, IIf( ).
Example
Sub Main
Debug.Print Choose(2,"Hi","there") '"there"
End Sub
118

Chr$ Function
Syntax
Chr[$](Num)
Group
String
Description
Return a one char string for the ASCII value.
Note: A similar function, ChrB, returns a single byte ASCII string. Another similar function, ChrW, returns a single
char Unicode string.
Parameter Description
Num Return one char string for this ASCII numeric value.
See Also: Asc( ).
Example
Sub Main
Debug.Print Chr$(48) '"0"
End Sub
Chr$ Function
Syntax
Chr[$](Num)
Group
String
Description
Return a one char string for the ASCII value.
Note: A similar function, ChrB, returns a single byte ASCII string. Another similar function, ChrW, returns a single
char Unicode string.
Parameter Description
Num Return one char string for this ASCII numeric value.
See Also: Asc( ).
Example
Sub Main
Debug.Print Chr$(48) '"0"
End Sub
119

Chr$ Function
Syntax
Chr[$](Num)
Group
String
Description
Return a one char string for the ASCII value.
Note: A similar function, ChrB, returns a single byte ASCII string. Another similar function, ChrW, returns a single
char Unicode string.
Parameter Description
Num Return one char string for this ASCII numeric value.
See Also: Asc( ).
Example
Sub Main
Debug.Print Chr$(48) '"0"
End Sub
CInt Function
Syntax
CInt(Num|$)
Group
Conversion
Description
Convert to a 16 bit integer. If Num|$ is too big (or too small) to fit then an overflow error occurs.
Parameter Description
Num|$ Convert a number or string value to a 16 bit integer.
Example
Sub Main
Debug.Print CInt(1.6) ' 2
End Sub
120

Class_Initialize Sub
Syntax
Private Sub Class_Initialize()
...
End Sub
Group
Declaration
Description
Class module initialization subroutine. Each time a new instance is created for a class module, the Class_Initialize
sub is called. If Class_Initialize is not defined, then no special initialization occurs.
See Also: Code Module, Class_Terminate.
Class_Terminate Sub
Syntax
Private Sub Class_Terminate()
...
End Sub
Group
Declaration
Description
Class module termination subroutine. Each time an instance is destroyed for a class module the Class_Terminate
sub is called. If Class_Terminate is not defined then no special termination occurs.
See Also: Code Module, Class_Initialize.
Class Module
Group
Declaration
Description
A class module implements an ActiveX Automation object.
Has a set of Public procedures accessible from other macros and modules.
These public symbols are accessed via an object variable.
121

Public Consts, Types, arrays, fixed length strings are not allowed.
A class module is similar to a object module except that no instance is automatically created.
To create an instance use:
C:\ABCTemp\vbs\Dim_Definition00000109.htm
Dim Obj As classname
Set Obj = New classname
Can optionally contain Attributes one of which must be VB_Name.
See Also: Attribute Definition/Statement, Code Module, Object Module, Uses.
Example
'MyCommands macro
'#Uses "File.CLS"
Sub Main
Dim File As New File
File.Attach "C:\AUTOEXEC.BAT"
Debug.Print File.ReadLine
End Sub
'File.CLS class file
VERSION 1.0 CLASS
BEGIN
MultiUse = -1 'True
END
Attribute VB_Name = "File"
Option Explicit
Dim FN As Integer
Public Sub Attach(FileName As String)
FN = FreeFile
Open FileName For Input As #FN
End Sub
Public Sub Detach()
If FN 0 Then Close #FN
FN = 0
End Sub
Public Function ReadLine() As String
Line Input #FN,ReadLine
End Function
Private Sub Class_Initialize()
Debug.Print "Class_Initialize"
End Sub
Private Sub Class_Terminate()
Debug.Print "Class_Terminate"
Detach
End Sub
122

Clipboard Instruction/Function
Syntax
Clipboard Text$
-or-
Clipboard[$][( )]
Group
Miscellaneous
Description
Form 1: Set the clipboard to Text$. This is similar to the Edit|Copy menu command.
Form 2: Return the text in the clipboard.
Parameter Description
Text$ Put this string value into the clipboard.
Example
Sub Main
Debug.Print Clipboard$()
Clipboard "Hello"
Debug.Print Clipboard$() '"Hello"
End Sub
CLng Function
Syntax
CLng(Num|$)
Group
Conversion
Description
Convert to a 32 bit long integer. If Num|$ is too big (or too small) to fit then an overflow error occurs.
Parameter Description
Num|$ Convert a number or string value to a 32 bit integer.
Example
Sub Main
Debug.Print CLng(1.6) ' 2
End Sub
123

Close Instruction
Syntax
Close [[#]StreamNum][, ...]
Group
File
Description
Close StreamNums.
Parameter Description
StreamNum Streams 1 through 255 are private to each macro. Streams 256 through 511 are
shared by all macros. If this is omitted then all open streams for the current
macro/module are closed.
See Also: Open, Reset.
Example
Sub Main
' read the first line of XXX and print it
Open "XXX" For Input As #1
Line Input #1,L$
Debug.Print L$
Close #1
End Sub
ComboBox Dialog Item Definition
Syntax
ComboBox X, Y, DX, DY, StrArray$( ), .Field$[, Options]
Group
User Dialog
Description
Define a combobox item. Combo boxes combine the functionality of an edit box and a list box.
Parameter Description
X This number value is the distance from the left edge of the dialog box. It is measured
in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is measured
in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
124

StrArray$( ) This one-dimensional array of strings establishes the list of choices. All the non-null
elements of the array are used.
Field$ The value of the combo box is accessed via this field. This is the text in the edit box.
Options This numeric value controls the type of combo box. Choose one value from following
table. (If this numeric value omitted then zero is used.)
Option Description
0 List is not sorted.
2 List is sorted.
See Also: Begin Dialog, Dim As UserDialog.
Example
Sub Main
Dim combos$(3)
combos$(0) = "Combo 0"
combos$(1) = "Combo 1"
combos$(2) = "Combo 2"
combos$(3) = "Combo 3"
Begin Dialog UserDialog 200,120
Text 10,10,180,15,"Please push the OK button"
ComboBox 10,25,180,60,combos$(),.combo$
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
dlg.combo$ = "none"
Dialog dlg ' show dialog (wait for ok)
Debug.Print dlg.combo$
End Sub
Command$ Function
Syntax
Command[$]
Group
Miscellaneous
Description
Contains the value of the MacroRun parameters.
See Also: MacroRun.
Example
Sub Main
Debug.Print "Command line parameter is: """;
Debug.Print Command$;
Debug.Print """"
End Sub
125

condexpr definition
An expression that returns a numeric result. If the result is zero then the conditional is False. If the result is
non-zero then the conditional is True.
0 'false
-1 'true
X > 20 'true if X is greater than 20
S$ = "hello" 'true if S$ equals "hello"
Const Definition
Syntax
[ | Private | Public ] _
Const name[type] [As Type] = expr[, ...]
Group
Declaration
Description
Define name as the value of expr. The expr can refer to other constants or built-in functions. If the type of the
constants is not specified, the type of expr is used. Constants defined outside a Sub, Function or Property block are
available in the entire macro/module.
C:\ABCTemp\vbs\Private_Keyword.htm
Private is assumed if neither Private or Public is specified.
Note: Const statement in a Sub, Function or Property block may not use Private or Public.
Example
Sub Main
Const Pi = 4*Atn(1), e = Exp(1)
Debug.Print Pi ' 3.14159265358979
Debug.Print e ' 2.71828182845905
End Sub
Cos Function
Syntax
Cos(Num)
Group
Math
126

Description
Return the cosine.
Parameter Description
Num Return the cosine of this numeric value. This is the number of radians. There are 2*Pi
radians in a full circle.
Example
Sub Main
Debug.Print Cos(1) ' 0.54030230586814
End Sub
CreateObject Function
Syntax
CreateObject(Class$)
Group
Object
Description
Create a new object of type Class$. Use Set to assign the returned object to an object variable.
Parameter Description
Class$ This string value is the application's registered class name. If this application is not
currently active it will be started.
See Also: Objects.
Example
Sub Main
Dim App As Object
Set App = CreateObject("WinWrap.CppDemoApplication")
App.Move 20,30 ' move icon to 20,30
Set App = Nothing
App.Quit ' run-time error (no object)
End Sub
CSng Function
Syntax
CSng(Num|$)
Group
Conversion
127

Description
Convert to a single precision real. If Num|$ is too big (or too small) to fit then an overflow error occurs.
Parameter Description
Num|$ Convert a number or string value to a single precision real.
Example
Sub Main
Debug.Print CSng(Sqr(2)) ' 1.4142135381699
End Sub
CStr Function
Syntax
CStr(Num|$)
Group
Conversion
Description
Convert to a string.
Parameter Description
Num|$ Convert a number or string value to a string value.
Example
Sub Main
Debug.Print CStr(Sqr(2)) '"1.4142135623731"
End Sub
CurDir$ Function
Syntax
CurDir[$]([Drive$])
Group
File
Description
Return the current directory for Drive$.
Parameter Description
Drive$ This string value is the drive letter. If this is omitted or null then return the current
directory for the current drive.
128

See Also: ChDir, ChDrive.
Example
Sub Main
Debug.Print CurDir$()
End Sub
CVar Function
Syntax
CVar(Num|$)
Group
Conversion
Description
Convert to a variant value.
Parameter Description
Num|$ Convert a number or string value (or object reference) to a variant value.
Example
Sub Main
Debug.Print CVar(Sqr(2)) ' 1.4142135623731
End Sub
CVErr Function
Syntax
CVErr(Num|$)
Group
Conversion
Description
Convert to a variant that contains an error code. An error code can't be used in expressions.
Parameter Description
Num|$ Convert a number or string value to an error code.
See Also: IsError.
Example
Sub Main
129

Debug.Print CVErr(1) ' Error 1
End Sub
Date Function
Syntax
Date[$]
Group
Time/Date
Description
Return today's date as a date value.
See Also: Now, Time, Timer.
Example
Sub Main
Debug.Print Date ' example: 1/1/1995
End Sub
DateAdd Function
Syntax
DateAdd(interval, number, dateexpr)
Group
Time/Date
Description
Return a date value a number of intervals from another date.
Parameter Description
interval This string value indicates which kind of interval to add.
number Add this many intervals. Use a negative value to get an earlier date.
dateexpr Calculate the new date relative to this date value. If this value is Null then Null is
returned.
Interval Description
yyyy Year
q Quarter
m Month
y Day of year
d Day
w Weekday
130

ww Week
h Hour
n Minute
s Second
See Also: DateDiff, DatePart.
Example
Sub Main
Debug.Print DateAdd("yyyy",1,#1/1/2000#) '1/1/2001
End Sub
DateDiff Function
Syntax
DateDiff(interval, dateexpr1, dateexpr2)
Group
Time/Date
Description
Return the number of intervals between two dates.
Parameter Description
interval This string value indicates which kind of interval to subtract.
dateexpr1 Calculate the from this date value to dateexpr2. If this value is Null then Null is
returned.
dateexpr2 Calculate the from dateexpr1 to this date value. If this value is Null then Null is
returned.
Interval Description
yyyy Year
q Quarter
m Month
y Day of year
d Day
w Weekday
ww Week
h Hour
n Minute
s Second
See Also: DateAdd, DatePart.
Example
Sub Main
Debug.Print DateDiff("yyyy",#1/1/1990#,#1/1/2000#) ' 10
End Sub
131

dateexpr definition
An expression that returns a date result. Use #literal-date# to express a date value.
#1/1/2000# ' Jan 1, 2000
Now+7 ' seven days from now
DateSerial(Year(Now)+1,Month(Now),Day(Now))
' one year from now
DatePart Function
Syntax
DatePart(interval, dateexpr)
Group
Time/Date
Description
Return the number from the date corresponding to the interval.
Parameter Description
interval This string value indicates which kind of interval to extract.
dateexpr Get the interval from this date value. If this value is Null then Null is returned.
Parameter Description
yyyy Year (100-9999) Quarter (1-4)
m Month (1-12)
y Day of year (1-366)
d Day (1-31)
w Weekday (1-7)
ww Week (1-53)
h Hour (0-23)
n Minute (0-59)
s Second (0-59)
See Also: DateAdd, DateDiff.
Example
Sub Main
Debug.Print DatePart("yyyy",#1/1/2000#) ' 2000
End Sub
DateSerial Function
Syntax
DateSerial(Year, Month, Day)
132

Group
Time/Date
Description
Return a date value.
Parameter Description
Year This numeric value is the year (0 to 9999). (0 to 99 are interpreted by the operating
system.)
Month This numeric value is the month (1 to 12).
Day This numeric value is the day (1 to 31).
See Also: DateValue, TimeSerial, TimeValue.
Example
Sub Main
Debug.Print DateSerial(2000,7,4) '7/4/2000
End Sub
DateValue Function
Syntax
DateValue(Date$)
Group
Time/Date
Description
Return the day part of the date encoded as a string.
Parameter Description
Date$ Convert this string value to the day part of date it represents.
See Also: DateSerial, TimeSerial, TimeValue.
Example
Sub Main
Debug.Print DateValue("1/1/2000 12:00:01 AM")
'1/1/2000
End Sub
Day Function
Syntax
Day(dateexpr)
133

Group
Time/Date
Description
Return the day of the month (1 to 31).
Parameter Description
dateexpr Return the day of the month for this date value. If this value is Null then Null is
returned.
See Also: Date( ), Month( ), Weekday( ), Year( ).
Example
Sub Main
Debug.Print Day(#1/1/1900#) ' 1
Debug.Print Day(#1/2/1900#) ' 2
End Sub
DDEExecute Instruction
Syntax
DDEExecute ChanNum, Command$[, Timeout]
Group
DDE
Description
Send the DDE Execute Command$ string via DDE ChanNum.
Parameter Description
ChanNum This is the channel number returned by the DDEInitiate function. Up to 10 channels
may be used at one time.
Command$ Send this command value to the server application. The interpretation of this value is
defined by the server application.
Timeout The command will generate an error if the number of seconds specified by the
timeout is exceeded before the command has completed. The default is five seconds.
Example
Sub Main
ChanNum = DDEInitiate("PROGMAN","PROGMAN")
DDEExecute ChanNum,"[CreateGroup(XXX)]"
DDETerminate ChanNum
End Sub
134

DDEInitiate Function
Syntax
DDEInitiate(App$, Topic$)
Group
DDE
Description
Initiate a DDE conversation with App$ using Topic$. If the conversation is successfully started then the return
value is a channel number that can be used with other DDE instructions and functions.
Parameter Description
App$ Locate this server application.
Topic$ This is the server application's topic. The interpretation of this value is defined by the
server application.
Example
Sub Main
ChanNum = DDEInitiate("PROGMAN","PROGMAN")
DDEExecute ChanNum,"[CreateGroup(XXX)]"
DDETerminate ChanNum
End Sub
DDEPoke Instruction
Syntax
DDEPoke ChanNum, Item$, Data$[, Timeout]
Group
DDE
Description
Poke Data$ to the Item$ via DDE ChanNum.
Parameter Description
ChanNum This is the channel number returned by the DDEInitiate function. Up to 10 channels
may be used at one time.
Item$ This is the server application's item. The interpretation of this value is defined by the
server application.
Data$ Send this data value to the server application. The interpretation of this value is
defined by the server application.
Timeout The command will generate an error if the number of seconds specified by the
timeout is exceeded before the command has completed. The default is five seconds.
Example
Sub Main
ChanNum = DDEInitiate("PROGMAN","PROGMAN")
135

DDEPoke ChanNum,"Group","XXX"
DDETerminate ChanNum
End Sub
DDERequest$ Function
Syntax
DDERequest[$](ChanNum, Item$[, Timeout])
Group
DDE
Description
Request information for Item$. If the request is not satisfied then the return value will be a null string.
Parameter Description
ChanNum This is the channel number returned by the DDEInitiate function. Up to 10 channels
may be used at one time.
Item$ This is the server application's item. The interpretation of this value is defined by the
server application.
Timeout The command will generate an error if the number of seconds specified by the
timeout is exceeded before the command has completed. The default is five seconds.
Example
Sub Main
ChanNum = DDEInitiate("PROGMAN","PROGMAN")
Debug.Print DDERequest$(ChanNum,"Groups")
DDETerminate ChanNum
End Sub
DDETerminate Instruction
Syntax
DDETerminate ChanNum
Group
DDE
Description
Terminate DDE ChanNum.
Parameter Description
ChanNum This is the channel number returned by the DDEInitiate function. Up to 10 channels
may be used at one time.
136

Example
Sub Main
ChanNum = DDEInitiate("PROGMAN","PROGMAN")
DDEExecute ChanNum,"[CreateGroup(XXX)]"
DDETerminate ChanNum
End Sub
DDETerminateAll Instruction
Syntax
DDETerminateAll
Group
DDE
Description
Terminate all open DDE channels.
Example
Sub Main
ChanNum = DDEInitiate("PROGMAN","PROGMAN")
DDEExecute ChanNum,"[CreateGroup(XXX)]"
DDETerminateAll
End Sub
Debug Object
Syntax
Debug.Clear
-or-
Debug.Print [expr[; ...][;]]
Group
Miscellaneous
Description
Form 1: Clear the output window.
Form 2: Print the expr(s) to the output window. Use semi-colons (;) to separate expressions. A num is
automatically converted to a string before printing (just like Str$( )). If the instruction does not end with a
semicolon, then a new line is printed at the end.
Example
137

Sub Main
X = 4
Debug.Print "X/2=";X/2 ' 2
Debug.Print "Start..."; ' don't print a new line
Debug.Print "Finish" ' print a new line
End Sub
Declare Definition
Syntax
[ | Private | Public ] _
Declare Sub name Lib "dll name" _
[Alias "module name"] [([param[, ...]])]
-or-
[ | Private | Public ] _
Declare Function name[type] Lib "dll name" _
[Alias "module name"] [([param[, ...]])] [As type[()]]
Group
Declaration
Description
Interface to a DLL defined subroutine or function. The values of the calling arglist are assigned to the params.
Declare defaults to Public if neither Private or Public is specified.
WARNING! Be very careful when declaring DLL subroutines or functions. If you make a mistake and declare the
parameters or result incorrectly then Windows might halt. Save any open documents before testing new DLL
declarations.
C:\ABCTemp\vbs\Err_Object.htm
Err.LastDLLError returns the error code for that last DLL call (Windows 32 bit versions only).
Parameter Description
name This is the name of the subroutine or function being defined. If Alias "module name"
is omitted then this is the module name, too.
"dll name" This is the DLL file where the module's code is.
params A list of zero or more params that are used by the DLL subroutine or function. (Note:
"module
name"
138
A ByVal string's value may be modified by the DLL.)
This is the name of the module in the DLL file. If this is #number then it is the ordinal
number of the module. If it is omitted then name is the module name.
The DLL is searched for the specified module name. If this module exists, it is used.
All As String parameters are converted from Unicode to ASCII prior to calling the
DLL and from ASCII to Unicode afterwards. (Use "Unicode:module name" to prevent
ASCII to Unicode conversion.)
If the module does not exist, one or two other module names are tried:
1) For Windows NT only: The module name with a "W" appended is tried. All As
String parameters are passed as Unicode to calling the DLL.
2) For Windows NT only: The module name with an "A" appended is tried. All As
String parameters are converted from Unicode to ASCII prior to calling the DLL and
from ASCII to Unicode afterwards.
If none of these module names is found a run-time error occurs.
See Also: Function, Sub, Call.

Example
Declare Function GetForegroundWindow& Lib "user32" ()
Declare Function GetWindowTextLengthA& Lib "user32"(ByVal hwnd&)
Declare Sub GetWindowTextA Lib "user32"(ByVal hwnd&, ByVal lpsz$, ByVal cbMax&)
Function ActiveWindowTitle$()
ActiveWindowTitle$ = vbCr
ActiveWindow = GetForegroundWindow()
TitleLen = GetWindowTextLengthA(ActiveWindow)
If TitleLen > 0 Then
TitleLen = TitleLen + 1
Title$ = Space$(TitleLen)
GetWindowTextA ActiveWindow,Title$,TitleLen
ActiveWindowTitle$ = Title$
End If
End Function
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
Clipboard ActiveWindowTitle$
End Sub
Def Definition
Syntax
Def{Bool|Cur|Date|Dbl|Int|Lng|Obj|Sng|Str|Var} _
letterrange[, ...]
Group
Declaration
Description
Define untyped variables as:
DefBool - Boolean
DefByte - Byte
DefCur - Currency
DefDate - Date
DefDbl - Double
DefInt - Integer
DefLng - Long
DefObj - Object
DefSng - Single
DefStr - String
DefVar - Variant
Parameter Description
letterrange letter, or A letter is one of A to Z. When letter-letter is used, the first letter must be
139

letter-letter alphabetically before the second letter. Variable names that begin with a
letter in this range default to declared type.
See Also: Option.
Example
140
If a variable name begins with a letter not specific in any letterrange then the
variable is a Variant. The letterranges are not allowed to overlap.
DefInt A,C-W,Y' integer
DefBool B ' boolean
DefStr X ' string
' all others are variant
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
B = 1 ' B is an boolean
Debug.Print B ' True
X = "A" ' X is a string
Debug.Print X '"A"
Z = 1 ' Z is a variant (anything)
Debug.Print Z ' 1
Z = "Z"
Debug.Print Z '"Z"
End Sub
DeleteSetting Instruction
Syntax
DeleteSetting AppName$, Section$[, Key$]
Group
Settings
Description
Delete the settings for Key in Section in project AppName. Win16 and Win32s store settings in a .ini file named
AppName. Win32 stores settings in the registration database.
Parameter Description
AppName$ This string value is the name of the project which has this Section and Key.
Section$ This string value is the name of the section of the project settings.
Key$ This string value is the name of the key in the section of the project settings. If this
is omitted then delete the entire section.
Example
Sub Main
SaveSetting "MyApp","Font","Size",10
DeleteSetting "MyApp","Font","Size"
End Sub

dialogfunc definition
A dialog function executes while a UserDialog is visible.
DialogFunc Prototype
Syntax
Function dialogfunc(DlgItem$, Action%, SuppValue%) _
As Boolean
Select Case Action%
Case 1 ' Dialog box initialization
...
Case 2 ' Value changing or button pressed
...
Case 3 ' TextBox or ComboBox text changed
...
Case 4 ' Focus changed
...
Case 5 ' Idle
...
Case 6 ' Function key
...
End Select
End Function
Group
Dialog Function
Description
A dialogfunc implements the dynamic dialog capabilities.
Parameter Description
DlgItem This string value is the name of the user dialog item's field.
Action This numeric value indicates what action the dialog function is being asked to do.
SuppValue This numeric value provides additional information for some actions.
Action/Description
141
Dialog box initialization. DlgItem is a null string. SuppValue is the dialog's window handle. Set dialogfunc =
True to terminate the dialog.
CheckBox, DropListBox, ListBox, MultiListBox, or OptionGroup: DlgItem's value has changed. SuppValue is
the new value.
CancelButton, OKButton or PushButton: DlgItem's button was pushed. SuppValue is meaningless. Set
dialogfunc = True to prevent the dialog from closing.
ComboBox or TextBox: DlgItem's text changed and losing focus. SuppValue is the number of characters.
Item DlgItem is gaining focus. SuppValue is the item that is losing focus. (The first item is 0, second is 1,
etc.)
Idle processing. DlgItem is a null string. SuppValue is zero. Set dialogfunc = True to continue receiving idle
actions.
Function key (F1-F24) was pressed. DlgItem has the focus. SuppValue is the function key number and the

142
shift/control/alt key state.
Regular function keys range from 1 to 24.
Shift function keys have &H100 added.
Control function keys have &H200 added.
Alt function keys have &H400 added.
(Alt-F4 closes the dialog and is never passed to the Dialog Function.)
See Also: Begin Dialog.
Example
Sub Main
Begin Dialog UserDialog 200,120,.DialogFunc
Text 10,10,180,15,"Please push the OK button"
TextBox 10,40,180,15,.Text
OKButton 30,90,60,20
PushButton 110,90,60,20,"&Hello"
End Dialog
Dim dlg As UserDialog
Debug.Print Dialog(dlg)
End Sub
C:\ABCTemp\vbs\Function_Definition.htm
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Debug.Print "Action=";Action%
Debug.Print DlgItem$;"=""";DlgText$(DlgItem$);""""
Debug.Print "SuppValue=";SuppValue%
Select Case Action%
Case 1 ' Dialog box initialization
Beep
Case 2 ' Value changing or button pressed
If DlgItem$ = "Hello" Then
MsgBox "Hello"
DialogFunc% = True 'do not exit the dialog
End If
Case 4 ' Focus changed
Debug.Print "DlgFocus=""";DlgFocus();""""
Case 6 ' Function key
If SuppValue And &H100 Then Debug.Print "Shift-";
If SuppValue And &H200 Then Debug.Print "Ctrl-";
If SuppValue And &H400 Then Debug.Print "Alt-";
Debug.Print "F" & (SuppValue And &HFF)
End Select
End Function
Dialog Instruction/Function
Syntax
Dialog dialogvar[, default]
-or-
Dialog(dialogvar[, default])
Group
User Input

Description
Display the dialog associated with dialogvar. The initial values of the dialog fields are provided by dialogvar. If the
OK button or any push button is pressed then the fields in dialog are copied to the dialogvar. The Dialog( ) function
returns a value indicating which button was pressed. (See the result table below.)
Parameter Description
dlgvar This variable that holds the values of the fields in a dialog. Use field to access
individual fields in a dialog variable.
default This numeric value indicates which button is the default button. (Pressing the Enter
key on a non-button pushes the default button.) Use -2 to indicate that there is no
default button. Other possible values are shown the result table below. If this value
is omitted then the first PushButton, OKButton or CancelButton is the default button.
Result Description
-1 OK button was pressed.
0 Cancel button was pressed.
>0 Nth push button was pressed.
See Also: Begin Dialog, Dim As UserDialog.
Example
Sub Main
Begin Dialog UserDialog 200,120
Text 10,10,180,15,"Please push the OK button"
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
Dialog dlg ' show dialog (wait for ok)
End Sub
Dim definition
[lower To] upper
Array dimension. If lower is omitted then the lower bound is zero or one depending on the Option Base setting.
(The lower bound of an array element in a Type definition is not affected by the Option Base setting.) upper must
be at least as big as lower.
Dim A(100 To 200) '101 values
Note: For ReDim the lower and upper may be any valid expression. Otherwise, lower and upper must be constant
expressions.
Dim Definition
Syntax
Dim [WithEvents] name[type][([dim[, ...]])][As [New] type][, ...]
Group
Declaration
143

Description
Dimension var array(s) using the dims to establish the minimum and maximum index value for each dimension. If
the dims are omitted then a scalar (single value) variable is defined. A dynamic array is declared using ( ) without
any dims. It must be ReDimensioned before it can be used.
See Also: Begin Dialog, Dialog, Option Base, Private, Public, ReDim, Static, WithEvents.
Example
Sub DoIt(Size)
Dim C0,C1(),C2(2,3)
ReDim C1(Size) ' dynamic array
C0 = 1
C1(0) = 2
C2(0,0) = 3
Debug.Print C0;C1(0);C2(0,0) ' 1 2 3
End Sub
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
DoIt 1
End Sub
Dir$ Function
Syntax
Dir[$]([Pattern$][, AttribMask])
Group
File
Description
Scan a directory for the first file matching Pattern$.
Parameter Description
Pattern$ This string value is the path and name of the file search pattern. If this is omitted
then continue scanning with the previous pattern. Each macro has its own
independent search. A path relative to the current directory can be used.
AttribMask This numeric value controls which files are found. A file with an attribute that
matches will be found.
See Also: GetAttr( ).
Example
Sub Main
F$ = Dir$("*.*")
While F$ ""
Debug.Print F$
F$ = Dir$()
Wend
End Sub
144

DlgControlId Function
Syntax
DlgControlId(DlgItem|$)
Group
Dialog Function
Description
Return the field's window id.
This instruction/function must be called directly or indirectly from a dialogfunc.
Parameter Description
DlgItem|$ If this is a numeric value then it is the dialog item number. The first item is 0, second
is 1, etc. If this is a string value then it is the dialog item's field name.
Example
Sub Main
Begin Dialog UserDialog 200,120,.DialogFunc
Text 10,10,180,15,"Please push the OK button"
TextBox 10,40,180,15,.Text
OKButton 30,90,60,20
PushButton 110,90,60,20,"&Hello"
End Dialog
Dim dlg As UserDialog
Debug.Print Dialog(dlg)
End Sub
C:\ABCTemp\vbs\Function_Definition.htm
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Debug.Print "Action=";Action%
Select Case Action%
Case 1 ' Dialog box initialization
Beep
Case 2 ' Value changing or button pressed
If DlgItem$ = "Hello" Then
DialogFunc% = True 'do not exit the dialog
End If
Case 4 ' Focus changed
Debug.Print "DlgFocus=""";DlgFocus();""""
Debug.Print "DlgControlId(";DlgItem$;")=";
Debug.Print DlgControlId(DlgItem$)
End Select
End Function
145

DlgCount Function
Syntax
DlgCount()
Group
Dialog Function
Description
Return the number of dialog items in the dialog.
This instruction/function must be called directly or indirectly from a dialogfunc.
Example
Sub Main
Begin Dialog UserDialog 200,120,.DialogFunc
Text 10,10,180,15,"Please push the OK button"
TextBox 10,40,180,15,.Text
OKButton 30,90,60,20
End Dialog
Dim dlg As UserDialog
Dialog dlg
End Sub
C:\ABCTemp\vbs\Function_Definition.htm
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Debug.Print "Action=";Action%
Select Case Action%
Case 1 ' Dialog box initialization
Beep
Debug.Print "DlgCount=";DlgCount() ' 3
End Select
End Function
DlgEnd Instruction
Syntax
DlgEnd ReturnCode
Group
Dialog Function
Description
Set the return code for the Dialog Function and close the user dialog.
This instruction/function must be called directly or indirectly from a dialogfunc.
ReturnCode Return this numeric value.
146

Example
Sub Main
Begin Dialog UserDialog 210,120,.DialogFunc
Text 10,10,190,15,"Please push the Close button"
OKButton 30,90,60,20
CheckBox 120,90,60,20,"&Close",.CheckBox1
End Dialog
Dim dlg As UserDialog
Debug.Print Dialog(dlg)
End Sub
C:\ABCTemp\vbs\Function_Definition.htm
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Debug.Print "Action=";Action%
Select Case Action%
Case 1 ' Dialog box initialization
Beep
Case 2 ' Value changing or button pressed
Select Case DlgItem$
Case "CheckBox1"
DlgEnd 1000
End Select
End Select
End Function
DlgEnable Instruction/Function
Syntax
DlgEnable DlgItem|$[, Enable]
-or-
DlgEnable(DlgItem|$)
Group
Dialog Function
Description
Instruction: Enable or disable DlgItem|$.
Function: Return True if DlgItem|$ is enabled.
This instruction/function must be called directly or indirectly from a dialogfunc.
Parameter Description
DlgItem|$ If this is a numeric value then it is the dialog item number. The first item is 0, second
is 1, etc. If this is a string value then it is the dialog item's field name.
Note: Use -1 to enable or disable all the dialog items at once.
Enable It this numeric value is True then enable DlgItem|$. Otherwise, disable it. If this
omitted then toggle it.
Example
147

Sub Main
Begin Dialog UserDialog 210,120,.DialogFunc
Text 10,10,190,15,"Please push the OKButton"
OKButton 30,90,60,20
PushButton 110,90,60,20,"&Disable"
End Dialog
Dim dlg As UserDialog
Debug.Print Dialog(dlg)
End Sub
C:\ABCTemp\vbs\Function_Definition.htm
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Debug.Print "Action=";Action%
Select Case Action%
Case 1 ' Dialog box initialization
Beep
Case 2 ' Value changing or button pressed
Select Case DlgItem$
Case "Disable"
DlgEnable "Text",False
DialogFunc% = True 'do not exit the dialog
Case "Enable"
DlgText DlgItem$,"&Disable"
DlgEnable "Text",True
DialogFunc% = True 'do not exit the dialog
End Select
End Select
End Function
DlgFocus Instruction/Function
Syntax
DlgFocus DlgItem|$
-or-
DlgFocus[$]()
Group
Dialog Function
Description
Instruction: Move the focus to this DlgItem|$.
Function: Return the field name which has the focus as a string.
This instruction/function must be called directly or indirectly from a dialogfunc.
Parameter Description
DlgItem|$ If this is a numeric value then it is the dialog item number. The first item is 0, second
is 1, etc. If this is a string value then it is the dialog item's field name.
Example
Sub Main
148

Begin Dialog UserDialog 200,120,.DialogFunc
Text 10,10,180,15,"Please push the OK button"
TextBox 10,40,180,15,.Text
OKButton 30,90,60,20
PushButton 110,90,60,20,"&Hello"
End Dialog
Dim dlg As UserDialog
Debug.Print Dialog(dlg)
End Sub
C:\ABCTemp\vbs\Function_Definition.htm
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Debug.Print "Action=";Action%
Select Case Action%
Case 1 ' Dialog box initialization
Beep
Case 2 ' Value changing or button pressed
If DlgItem$ = "Hello" Then
MsgBox "Hello"
DialogFunc% = True 'do not exit the dialog
End If
Case 4 ' Focus changed
Debug.Print "DlgFocus=""";DlgFocus();""""
End Select
End Function
DlgListBoxArray Instruction/Function
Syntax
DlgListBoxArray DlgItem|$, StrArray$( )
-or-
DlgListBoxArray(DlgItem|$[, StrArray$( )])
Group
Dialog Function
Description
Instruction: Set the list entries for DlgItem|$.
Function: Return the number entries in DlgItem|$'s list.
This instruction/function must be called directly or indirectly from a dialogfunc. The DlgItem|$ should refer to a
ComboBox, DropListBox, ListBox, or MultiListBox.
Parameter Description
DlgItem|$ If this is a numeric value then it is the dialog item number. The first item is 0, second
is 1, etc. If this is a string value then it is the dialog item's field name.
StrArray$( ) Set the list entries of DlgItem|$. This one-dimensional array of strings establishes
the list of choices. All the non-null elements of the array are used.
Example
Dim lists$()
149

C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
ReDim lists$(0)
lists$(0) = "List 0"
Begin Dialog UserDialog 200,119,.DialogFunc
Text 10,7,180,14,"Please push the OK button"
ListBox 10,21,180,63,lists(),.list
OKButton 30,91,40,21
PushButton 110,91,60,21,"&Change"
End Dialog
Dim dlg As UserDialog
dlg.list = 2
Dialog dlg ' show dialog (wait for ok)
Debug.Print dlg.list
End Sub
C:\ABCTemp\vbs\Function_Definition.htm
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Select Case Action%
Case 2 ' Value changing or button pressed
If DlgItem$ = "Change" Then
Dim N As Integer
N = UBound(lists$)+1
ReDim Preserve lists$(N)
lists$(N) = "List " & N
DlgListBoxArray "list",lists$()
DialogFunc% = True 'do not exit the dialog
End If
End Select
End Function
DlgName Function
Syntax
DlgName[$](DlgItem)
Group
Dialog Function
Description
Return the field name of the DlgItem number.
This instruction/function must be called directly or indirectly from a dialogfunc.
Parameter Description
DlgItem This numeric value is the dialog item number. The first item is 0, second is 1, etc.
Example
Sub Main
Begin Dialog UserDialog 200,120,.DialogFunc
Text 10,10,180,15,"Please push the OK button"
TextBox 10,40,180,15,.Text
150

OKButton 30,90,60,20
End Dialog
Dim dlg As UserDialog
Dialog dlg
End Sub
C:\ABCTemp\vbs\Function_Definition.htm
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Debug.Print "Action=";Action%
Select Case Action%
Case 1 ' Dialog box initialization
Beep
For I = 0 To DlgCount()-1
Debug.Print I;DlgName(I)
Next I
End Select
End Function
DlgNumber Function
Syntax
DlgNumber(DlgItem$)
Group
Dialog Function
Description
Return the number of the DlgItem$. The first item is 0, second is 1, etc.
This instruction/function must be called directly or indirectly from a dialogfunc.
Parameter Description
DlgItem$ This string value is the dialog item's field name.
Example
Sub Main
Begin Dialog UserDialog 200,120,.DialogFunc
Text 10,10,180,15,"Please push the OK button"
TextBox 10,40,180,15,.Text
OKButton 30,90,60,20
End Dialog
Dim dlg As UserDialog
Dialog dlg
End Sub
C:\ABCTemp\vbs\Function_Definition.htm
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Debug.Print "Action=";Action%
Select Case Action%
Case 1 ' Dialog box initialization
Beep
Case 4 ' Focus changed
Debug.Print DlgItem$;"=";DlgNumber(DlgItem$)
151

End Select
End Function
DlgSetPicture Instruction
Syntax
DlgSetPicture DlgItem|$, FileName, Type
Group
Dialog Function
Description
Instruction: Set the file name for DlgItem|$.
This instruction/function must be called directly or indirectly from a dialogfunc.
Parameter Description
DlgItem|$ If this is a numeric value then it is the dialog item number. The first item is 0, second
is 1, etc. If this is a string value then it is the dialog item's field name.
FileName Set the file name of DlgItem|$ to this string value.
Type This numeric value indicates the type of bitmap used. See below.
Type Effect
0 FileName is the name of the bitmap file. If the file does not exist then "(missing picture)" is
displayed.
3 The clipboard's bitmap is displayed. Not supported.
+16 Instead of displaying "(missing picture)" a run-time error occurs.
Example
Sub Main
Begin Dialog UserDialog 200,120,.DialogFunc
Picture 10,10,180,75,"",0,.Picture
OKButton 30,90,60,20
PushButton 110,90,60,20,"&View"
End Dialog
Dim dlg As UserDialog
Debug.Print Dialog(dlg)
End Sub
C:\ABCTemp\vbs\Function_Definition.htm
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Debug.Print "Action=";Action%
Select Case Action%
Case 1 ' Dialog box initialization
Beep
Case 2 ' Value changing or button pressed
Select Case DlgItem$
Case "View"
FileName = GetFilePath("Bitmap","BMP")
DlgSetPicture "Picture",FileName,0
DialogFunc% = True 'do not exit the dialog
End Select
152

End Select
End Function
DlgText Instruction/Function
Syntax
DlgText DlgItem|$, Text
-or-
DlgText[$](DlgItem|$)
Group
Dialog Function
Description
Instruction: Set the text for DlgItem|$.
Function: Return the text from DlgItem|$.
This instruction/function must be called directly or indirectly from a dialogfunc.
Parameter Description
DlgItem|$ If this is a numeric value then it is the dialog item number. The first item is 0, second
is 1, etc. If this is a string value then it is the dialog item's field name. Note: Use -1
to access the dialog's title.
Text Set the text of DlgItem|$ to this string value.
Example
Sub Main
Begin Dialog UserDialog 200,120,.DialogFunc
Text 10,10,180,15,"Please push the OK button"
TextBox 10,40,180,15,.Text
OKButton 30,90,60,20
PushButton 110,90,60,20,"&Now"
End Dialog
Dim dlg As UserDialog
Debug.Print Dialog(dlg)
End Sub
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Debug.Print "Action=";Action%
Select Case Action%
Case 1 ' Dialog box initialization
Beep
Case 2 ' Value changing or button pressed
Select Case DlgItem$
Case "Now"
DlgText "Text",CStr(Now)
DialogFunc% = True 'do not exit the dialog
End Select
End Select
End Function
153

DlgType Function
Syntax
DlgType[$](DlgItem|$)
Group
Dialog Function
Description
Return a string value indicating the type of the DlgItem|$. One of: "CancelButton", "CheckBox", "ComboBox",
"DropListBox", "GroupBox", "ListBox", "MultiListBox", "OKButton", "OptionButton", "OptionGroup", "PushButton",
"Text", "TextBox".
This instruction/function must be called directly or indirectly from a dialogfunc.
Parameter Description
DlgItem|$ If this is a numeric value then it is the dialog item number. The first item is 0, second
is 1, etc. If this is a string value then it is the dialog item's field name.
Example
Sub Main
Begin Dialog UserDialog 200,120,.DialogFunc
Text 10,10,180,15,"Please push the OK button"
TextBox 10,40,180,15,.Text
OKButton 30,90,60,20
End Dialog
Dim dlg As UserDialog
Dialog dlg
End Sub
C:\ABCTemp\vbs\Function_Definition.htm
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Debug.Print "Action=";Action%
Select Case Action%
Case 1 ' Dialog box initialization
Beep
For I = 0 To DlgCount()-1
Debug.Print I;DlgType(I)
Next I
End Select
End Function
DlgValue Instruction/Function
Syntax
DlgValue DlgItem|$, Value
-or-
DlgValue(DlgItem|$)
154

Group
Dialog Function
Description
Instruction: Set the numeric value DlgItem|$.
Function: Return the numeric value for DlgItem|$. (A MultiListBox user dialog item returns an array.)
This instruction/function must be called directly or indirectly from a dialogfunc. The DlgItem|$ should refer to a
CheckBox, ComboBox, DropListBox, ListBox, MultiListBox, or OptionGroup.
Parameter Description
DlgItem|$ If this is a numeric value then it is the dialog item number. The first item is 0, second
is 1, etc. If this is a string value then it is the dialog item's field name.
Value Set the text of DlgItem|$ to this numeric value. (A MultiListBox user dialog item uses
an array.)
Example
Sub Main
Begin Dialog UserDialog 150,147,.DialogFunc
GroupBox 10,7,130,77,"Direction",.Field1
PushButton 100,28,30,21,"&Up"
PushButton 100,56,30,21,"&Dn"
OptionGroup .Direction
OptionButton 20,21,80,14,"&North",.North
OptionButton 20,35,80,14,"&South",.South
OptionButton 20,49,80,14,"&East",.East
OptionButton 20,63,80,14,"&West",.West
OKButton 10,91,130,21
CancelButton 10,119,130,21
End Dialog
Dim dlg As UserDialog
Dialog dlg
MsgBox "Direction=" & dlg.Direction
End Sub
C:\ABCTemp\vbs\Function_Definition.htm
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Select Case Action%
Case 1 ' Dialog box initialization
Beep
Case 2 ' Value changing or button pressed
Select Case DlgItem$
Case "Up"
DlgValue "Direction",0
DialogFunc% = True 'do not exit the dialog
Case "Dn"
DlgValue "Direction",1
DialogFunc% = True 'do not exit the dialog
End Select
End Select
End Function
155

dlgvar definition
A dialog variable holds values for fields in the dialog. Dialog variables are declared using Dim dlgvar As UserDialog.
DlgVisible Instruction/Function
Syntax
DlgVisible DlgItem|$[, Visible]
-or-
DlgVisible(DlgItem|$)
Group
Dialog Function
Description
Instruction: Show or hide DlgItem|$.
Function: Return True if DlgItem|$ is visible.
This instruction/function must be called directly or indirectly from a dialogfunc.
Parameter Description
DlgItem|$ If this is a numeric value then it is the dialog item number. The first item is 0, second
is 1, etc. If this is a string value then it is the dialog item's field name.
Enable It this numeric value is True then show DlgItem|$. Otherwise, hide it. If this omitted
then toggle it.
Example
Sub Main
Begin Dialog UserDialog 200,120,.DialogFunc
Text 10,10,180,15,"Please push the OK button"
TextBox 10,40,180,15,.Text
OKButton 30,90,60,20
PushButton 110,90,60,20,"&Hide"
End Dialog
Dim dlg As UserDialog
Debug.Print Dialog(dlg)
End Sub
C:\ABCTemp\vbs\Function_Definition.htm
Function DialogFunc%(DlgItem$, Action%, SuppValue%)
Debug.Print "Action=";Action%
Select Case Action%
Case 1 ' Dialog box initialization
Beep
Case 2 ' Value changing or button pressed
Select Case DlgItem$
Case "Hide"
DlgText DlgItem$,"&Show"
DlgVisible "Text",False
DialogFunc% = True 'do not exit the dialog
Case "Show"
156

DlgText DlgItem$,"&Hide"
DlgVisible "Text",True
DialogFunc% = True 'do not exit the dialog
End Select
End Select
End Function
Do Statement
Syntax
Do
statements
Loop
-or-
Do {Until|While} condexpr
statements
Loop
-or-
Do
statements
Loop {Until|While} condexpr
Group
Flow Control
Description
Form 1: Do statements forever. The loop can be exited by using Exit or Goto.
Form 2: Check for loop termination before executing the loop the first time.
Form 3: Execute the loop once and then check for loop termination.
Loop Termination:
Until condexpr: Do statements until condexpr is True.
While condexpr: Do statements while condexpr is True.
See Also: For, For Each, Exit Do, While.
Example
Sub Main
I = 2
Do
I = I*2
Loop Until I > 10
Debug.Print I ' 16
End Sub
157

DoEvents Instruction
Syntax
DoEvents
Group
Miscellaneous
Description
This instruction allows other applications to process events.
Example
Sub Main
DoEvents ' let other apps work
End Sub
DropListBox Dialog Item Definition
Syntax
DropListBox X, Y, DX, DY, StrArray$( ), .Field[, Options]
Group
User Dialog
Description
Define a drop-down listbox item.
Parameter Description
X This number value is the distance from the left edge of the dialog box. It is measured
in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is measured
in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
StrArray$( ) This one-dimensional array of strings establishes the list of choices. All the non-null
elements of the array are used.
Field The value of the drop-down list box is accessed via this field. It is the index of the
StrArray$( ) var.
Options This numeric value controls the type of drop-down list box. Choose one value from
following table. (If this numeric value omitted then zero is used.)
Option Description
0 Text box is not editable and list is not sorted.
1 Text box is editable and list is not sorted.
2 Text box is not editable and list is sorted.
3 Text box is editable and list is sorted.
158

See Also: Begin Dialog, Dim As UserDialog.
Example
Sub Main
Dim lists$(3)
lists$(0) = "List 0"
lists$(1) = "List 1"
lists$(2) = "List 2"
lists$(3) = "List 3"
Begin Dialog UserDialog 200,120
Text 10,10,180,15,"Please push the OK button"
DropListBox 10,25,180,60,lists$(),.list1
DropListBox 10,50,180,60,lists$(),.list2,1
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
dlg.list1 = 2 ' list1 is a numeric field
dlg.list2 = "xxx" ' list2 is a string field
Dialog dlg ' show dialog (wait for ok)
Debug.Print lists$(dlg.list1)
Debug.Print dlg.list2
End Sub
End Instruction
Syntax
End
Group
Flow Control
Description
The end instruction causes the macro to terminate immediately. If the macro was run by another macro using the
MacroRun instruction then that macro continues on the instruction following the MacroRun.
Example
Sub DoSub
L$ = UCase$(InputBox$("Enter End:"))
If L$ = "END" Then End
Debug.Print "End was not entered."
End Sub
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
Debug.Print "Before DoSub"
DoSub
Debug.Print "After DoSub"
End Sub
159

Enum Definition
Syntax
[ | Private | Public ] _
Enum name
elem [ = value]
[...]
End Enum
Group
Declaration
Description
Define a new userenum. Each elem defines an element of the enum. If value is given then that is the element's
value. The value can be any constant integer expression. If value is omitted then the element's value is one more
than the previous element's value. If there is no previous element then zero is used.
Enum defaults to Public if neither Private or Public is specified.
Example
Enum Days
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday
End Enum
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
Dim D As Days
For D = Monday To Friday
Debug.Print D ' 0 through 4
Next D
End Sub
Environ Instruction/Function
Syntax
Environ[$](Index)
-or-
Environ[$](Name)
Group
Miscellaneous
Description
160

Return an environment string.
Parameter Description
Index Return this environment string's value. If there is no environment string at this index
a null string is returned. Indexes start at one.
Name Return this environment string's value. If the environment string can't be found a
null string is returned.
Example
Sub Main
Debug.Print Environ("Path")
End Sub
EOF Function
Syntax
EOF(StreamNum)
Group
File
Description
Return True if StreamNum is at the end of the file.
Parameter Description
StreamNum Streams 1 through 255 are private to each macro. Streams 256 through 511 are
shared by all macros.
Example
Sub Main
Open "XXX" For Input As #1
While Not EOF(1)
Line Input #1,L$
Debug.Print L$
Wend
Close #1
End Sub
Erase Instruction
Syntax
Erase arrayvar[, ...]
-or-
Erase usertypevar.elem[, ...]
Group
161

Assignment
Description
Reset arrayvar or user defined type array element to zero. (Dynamic arrays are reset to undimensioned arrays.)
String arrays values are set to a null string. arrayvar must be declared as an array.
Declare with Dim, Private, Public or Static.
Declare as a parameter of Sub, Function or Property definition.
Example
Sub Main
Dim X%(2)
X%(1) = 1
Erase X%
Debug.Print X%(1) ' 0
End Sub
Err Object
Syntax
Err
Group
Error Handling
Description
Set Err to zero to clear the last error event. Err in an expression returns the last error code. Add vbObjectError to
your error number in ActiveX Automation objects. Use Err.Raise or Error to trigger an error event.
Err[.Number]
This is the error code for the last error event. Set it to zero (or use Err.Clear) to clear the last error condition. Use
Error or Err.Raise to trigger an error event. This is the default property.
Err.Description
This string is the description of the last error event.
Err.Source
This string is the error source file name of the last error event.
Err.HelpFile
This string is the help file name of the last error event.
Err.HelpContext
This number is the help context id of the last error event.
Err.Clear
Clear the last error event.
Err.Raise [Number:=]errorcode _
[, [Source:=]source] _
162

[, [Description:=]errordesc] _
[, [HelpFile:=]helpfile] _
[, [HelpContext:=]context]
Raise an error event.
Err.LastDLLError
For 32 bit windows this returns the error code for the last DLL call (see Declare). For 16 bit windows this always
returns 0.
Example
Sub Main
On Error GoTo Problem
Err = 1 ' set to error #1 (handler not triggered)
Exit Sub
Problem: ' error handler
Error Err ' halt macro with message
End Sub
Error Instruction/Function
Syntax
Error ErrorCode
-or-
Error[$]([ErrorCode])
Group
Error Handling
Description
Instruction: Signal error ErrorCode. This triggers error handling just like a real error. The current procedure's error
handler is activated, unless it is already active or there isn't one. In that case the calling procedure's error handler
is tried. (Use Err.Raise to provide complete error information.)
Function: The Error( ) function returns the error text string.
Parameter Description
ErrorCode This is the error number.
Example
Sub Main
On Error GoTo Problem
Err.Raise 1 ' simulate error #1
Exit Sub
Problem: ' error handler
Debug.Print "Error$=";Error$
Resume Next
End Sub
163

Eval Function
Syntax
Eval(Expr[, Depth])
Group
Miscellaneous
Description
Return the value of the string expression as evaluated.
Parameter Description
Expr Evaluate this string value.
Depth This integer value indicates how deep into the stack to locate the local variables. If
Depth = 0 then use the current procedure. If this value is omitted then the depth is
0.
Example
Sub Main
Dim X As String
X = "Hello"
Debug.Print Eval("X") 'Hello
A
End Sub
Sub A
Dim X As String
X = "Bye"
Debug.Print Eval("X") 'Bye
Debug.Print Eval("X",1) 'Hello
End Sub
Exit Instruction
Syntax
Exit {All|Do|For|Function|Property|Sub|While}
Group
Flow Control
Description
The exit instruction causes the macro to continue with out doing some or all of the remaining instructions.
Exit Description
All Exit all macros.
Do Exit the Do loop.
For Exit the For of For Each loop.
164

Function Exit the Function block. Note: This instruction clears the Err and sets Error$ to null.
Property Exit the Property block. Note: This instruction clears the Err and sets Error$ to null.
Sub Exit the Sub block. Note: This instruction clears the Err and sets Error$ to null.
While Exit the While loop.
Example
Sub Main
L$ = InputBox$("Enter Do, For, While, Sub or All:")
Debug.Print "Before DoSub"
DoSub UCase$(L$)
Debug.Print "After DoSub"
End Sub
C:\ABCTemp\vbs\Sub_Definition.htm
Sub DoSub(L$)
Do
If L$ = "DO" Then Exit Do
I = I+1
Loop While I < 10
If I = 0 Then Debug.Print "Do was entered"
C:\ABCTemp\vbs\For_Statement.htm
For I = 1 To 10
If L$ = "FOR" Then Exit For
Next I
If I = 1 Then Debug.Print "For was entered"
I = 10
While I > 0
If L$ = "WHILE" Then Exit While
I = I-1
Wend
If I = 10 Then Debug.Print "While was entered"
C:\ABCTemp\vbs\If_Statement.htm
If L$ = "SUB" Then Exit Sub
Debug.Print "Sub was not entered."
If L$ = "ALL" Then Exit All
Debug.Print "All was not entered."
End Sub
Exp Function
Syntax
Exp(Num)
Group
Math
Description
Return the exponential.
Parameter Description
Num Return e raised to the power of this numeric value. The value e is approximately
165

Example
166
2.718282.
Sub Main
Debug.Print Exp(1) ' 2.718281828459
End Sub
Expr definition
An expression that returns the appropriate result.
Field definition
Use .field to access individual fields in a dialog variable.
dlg.Name$
dlg.ZipCode
FileAttr Function
Syntax
FileAttr(StreamNum, ReturnValue)
Group
File
Description
Return StreamNum's open mode or file handle.
Parameter Description
StreamNum Streams 1 through 255 are private to each macro. Streams 256 through 511 are
shared by all macros.
ReturnValue 1 - return the mode used to open the file: 1=Input, 2=Output, 4=Random,
8=Append, 32=Binary
2 - return the file handle
See Also: Open.
Example
Sub Main
Open "XXX" For Output As #1
Debug.Print FileAttr(1,1) ' 2
Close #1
End Sub

FileCopy Instruction
Syntax
FileCopy FromName$, ToName$
Group
File
Description
Copy a file.
Parameter Description
FromName$ This string value is the path and name of the source file. A path relative to the
current directory can be used.
ToName$ This string value is the path and name of the destination file. A path relative to the
current directory can be used.
Example
Sub Main
FileCopy "C:\AUTOEXEC.BAT","C:\AUTOEXEC.BAK"
End Sub
FileDateTime Function
Syntax
FileDateTime(Name$)
Group
File
Description
Return the date and time file Name$ was last changed as a date value. If the file does not exist then a run-time
error occurs.
Parameter Description
Name$ This string value is the path and name of the file. A path relative to the current
directory can be used.
Example
Sub Main
F$ = Dir$("*.*")
While F$ ""
Debug.Print F$;" ";FileDateTime(F$)
F$ = Dir$()
167

Wend
End Sub
FileLen Function
Syntax
FileLen(Name$)
Group
File
Description
Return the length of file Name$. If the file does not exist then a run-time error occurs.
Parameter Description
Name$ This string value is the path and name of the file. A path relative to the current
directory can be used.
Example
Sub Main
F$ = Dir$("*.*")
While F$ ""
Debug.Print F$;" ";FileLen(F$)
F$ = Dir$()
Wend
End Sub
Fix Function
Syntax
Fix(Num)
Group
Math
Description
Return the integer value.
Parameter Description
Num Return the integer portion of this numeric value. The number is truncated. Positive
numbers return the next lower integer. Negative numbers return the next higher
integer. If this value is Null then Null is returned.
Example
Sub Main
168

Debug.Print Fix(9.9) ' 9
Debug.Print Fix(0) ' 0
Debug.Print Fix(-9.9) '-9
End Sub
For Statement
Syntax
For Num = First To Last [Step Inc]
statements
Next [Num]
Group
Flow Control
Description
Execute statements while Num is in the range First to Last.
Parameter Description
Num This is the iteration variable.
First Set Num to this value initially.
Last Continue looping while Num is in the range. See Step below.
Step If this numeric value is greater than zero then the for loop continues as long as Num
is less than or equal to Last. If this numeric value is less than zero then the for loop
continues as long as Num is greater than or equal to Last. If this is omitted then one
is used.
See Also: Do, For Each, Exit For, While.
Example
Sub Main
For I = 1 To 2000 Step 100
Debug.Print I;I+I;I*I
Next I
End Sub
For Each Statement
Syntax
For Each var In items
statements
Next [var]
Group
Flow Control
169

Description
Execute statements for each item in items.
Parameter Description
ar This is the iteration variable.
items This is the collection of items to be done.
See Also: Do, For, Exit For, While.
Example
Sub Main
Dim Document As Object
For Each Document In App.Documents
Debug.Print Document.Title
Next Document
End Sub
Format$ Function
Syntax
Format[$](expr[, form$], [firstday], _
[firstweek])
Group
String
Description
Return the formatted string representation of expr.
Parameter Description
expr Return the formatted string representation of this numeric value.
form Format expr using to this string value. If this is omitted then return the expr as a
string.
firstday Format using this day as the first day of the week. If this is omitted then the
vbSunday is used. (Only supported for Win32.)
firstweek Format using this week as the first week of the year. If this is omitted then the
vbFirstJan1 is used. (Only supported for Win32.)
firstday Value Description
vbUseSystemFirstDay 0 Use the systems first day of the week.
vbSunday 1 Sunday (default)
vbMonday 2 Monday
vbTuesday 3 Tuesday
vbWednesday 4 Wednesday
vbThursday 5 Thursday
vbFriday 6 Friday
vbSaturday 7 Saturday
firstweek Value Description
vbUseSystem 0 Use the systems first week of the year
vbFirstJan1 1 The week that January 1 occurs in. This is the default value.
170

vbFirstFourDays 2 The first week that has at least four days in the year.
vbFirstFullWeek 3 The first week that entirely in the year.
See Also: Predefined Date Format, Predefined Number Format, User defined Date Format, User defined Number
Format, User defined Text Format.
FreeFile Function
Syntax
FreeFile[( )]
Group
File
Description
Return the next unused shared stream number (greater than or equal to 256). Streams 1 through 255 are private
to each macro. Streams 256 through 511 are shared by all macros.
Example
Sub Main
Debug.Print FreeFile ' 256
FN = FreeFile
Open "XXX" For Output As #FN
Debug.Print FreeFile ' 257
Close #FN
Debug.Print FreeFile ' 256
End Sub
Friend Keyword
Group
Declaration
Description
Friend Functions, Propertys and Subs in a module are available in all other macros/modules that access it. Friends
are not accessible via Object variables.
Function Definition
Syntax
171

[ | Private | Public | Friend ] _
Function name[type][([param[, ...]])] [As type[()]]
statements
End Function
Group
Declaration
Description
User defined function. The function defines a set of statements to be executed when it is called. The values of the
calling arglist are assigned to the params. Assigning to name[type] sets the value of the function result.
Function defaults to Public if Private, Public or Friend are not is specified.
See Also: Declare, Property, Sub.
Example
Function Power(X,Y)
P = 1
For I = 1 To Y
P = P*X
Next I
Power = P
End Function
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
Debug.Print Power(2,8) ' 256
End Sub
Get Instruction
Syntax
Get StreamNum, [RecordNum], var
Group
File
Description
Get a variable's value from StreamNum.
Parameter Description
StreamNum Streams 1 through 255 are private to each macro. Streams 256 through 511 are
shared by all macros.
RecordNum For Random mode files this is the record number. The first record is 1. Otherwise, it
is the byte position. The first byte is 1. If this is omitted then the current position (or
record number) is used.
ar This variable value is read from the file. For a fixed length variable (like Long) the
number of bytes required to restore the variable are read. For a Variant variable two
bytes are read which describe its type and then the variable value is read
accordingly. For a usertype variable each field is read in sequence. For an array
172

See Also: Open, Put.
Example
173
variable each element is read in sequence. For a dynamic array variable the number
of dimensions and range of each dimension is read prior to reading the array values.
All binary data values are read from the file in little-endian format.
Note: When reading a string (or a dynamic array) from a Binary mode file the length
(or array dimension) information is not read. The current string length determines
how much string data is read. The current array dimension determines how may
array elements are read.
Sub Main
Dim V As Variant
Open "SAVE_V.DAT" For Binary Access Read As #1
Get #1, , V
Close #1
End Sub
GetAllSettings Function
Syntax
GetAllSettings(AppName$, Section$, Key$)
Group
Settings
Description
Get all of Section's settings in project AppName. Settings are returned in a Variant. Empty is returned if there are
no keys in the section. Otherwise, the Variant contains a two dimension array: (I,0) is the key and (I,1) is the
setting. Win16 and Win32s store settings in a .ini file named AppName. Win32 stores settings in the registration
database.
Parameter Description
AppName$ This string value is the name of the project which has this Section and Key.
Section$ This string value is the name of the section of the project settings.
Example
Sub Main
SaveSetting "MyApp","Font","Size",10
SaveSetting "MyApp","Font","Name","Courier"
Settings = GetAllSettings("MyApp","Font")
For I = LBound(Settings) To UBound(Settings)
Debug.Print Settings(I,0); "="; Settings(I,1)
Next I
DeleteSetting "MyApp","Font"
End Sub

GetAttr Function
Syntax
GetAttr(Name$)
Group
File
Description
Return the attributes for file Name$. If the file does not exist then a run-time error occurs.
Parameter Description
Name$ This string value is the path and name of the file. A path relative to the current
directory can be used.
Example
Sub Main
F$ = Dir$("*.*")
While F$ ""
Debug.Print F$;" ";GetAttr(F$)
F$ = Dir$()
Wend
End Sub
GetFilePath$ Function
Syntax
GetFilePath[$]([DefName$], [DefExt$], [DefDir$], _
[Title$], [Option])
Group
User Input
Description
Put up a dialog box and get a file path from the user. The returned string is a complete path and file name. If the
cancel button is pressed then a null string is returned.
Parameter Description
DefName$ Set the initial File Name in the to this string value. If this is omitted then *.DefExt$ is
used.
DefExt$ Initially show files whose extension matches this string value. (Multiple extensions
can be specified by using ";" as the separator.) If this is omitted then * is used.
DefDir$ This string value is the initial directory. If this is omitted then the current directory is
used.
Title$ This string value is the title of the dialog. If this is omitted then ''Open" is used.
Option This numeric value determines the file selection options. If this is omitted then zero
is used. See table below.
Option Effect
174

0 Only allow the user to select a file that exists.
1 Confirm creation when the user selects a file that does not exist.
2 Allow the user to select any file whether it exists or not.
3 Confirm overwrite when the user selects a file that exists.
+4 Selecting a different directory changes the application's current directory.
Example
Sub Main
Debug.Print GetFilePath$()
End Sub
GetObject Function
Syntax
GetObject([File$][, Class$])
Group
Object
Description
Get an existing object of type Class$ from File$. Use Set to assign the returned object to an object variable.
Parameter Description
File$ This is the file where the object resides. If this is omitted then the currently active
object for Class$ is returned.
Class$ This string value is the application's registered class name. If this application is not
currently active it will be started. If this is omitted then the application associated
with the file's extension will be started.
Example
Sub Main
Dim App As Object
Set App = GetObject(,"WinWrap.CppDemoApplication")
App.Move 20,30 ' move icon to 20,30
Set App = Nothing
App.Quit ' run-time error (no object)
End Sub
GetSetting Function
Syntax
GetSetting[$](AppName$, Section$, Key$[, Default$])
Group
175

Settings
Description
Get the setting for Key in Section in project AppName. Win16 and Win32s store settings in a .ini file named
AppName. Win32 stores settings in the registration database.
Parameter Description
AppName$ This string value is the name of the project which has this Section and Key.
Section$ This string value is the name of the section of the project settings.
Key$ This string value is the name of the key in the section of the project settings.
Default$ Return this string value if no setting has been saved. If this is omitted then a null
string is used.
Example
Sub Main
SaveSetting "MyApp","Font","Size",10
Debug.Print GetSetting("MyApp","Font","Size") ' 10
End Sub
Goto Instruction
Syntax
GoTo label
Group
Flow Control
Description
Go to the label and continue execution from there. Only labels in the current user defined procedure are accessible.
Example
Sub Main
X = 2
Loop:
X = X*X
If X < 100 Then GoTo Loop
Debug.Print X ' 256
End Sub
GroupBox Dialog Item Definition
Syntax
GroupBox X, Y, DX, DY, Title$[, .Field]
Group
176

User Dialog
Description
Define a groupbox item.
Parameter Description
X This number value is the distance from the left edge of the dialog box. It is measured
in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is measured
in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
Title$ This string value is the title of the group box.
Field This identifier is the name of the field. The dialogfunc receives this name as string. If
this identifer is omitted then the first two words of the title are used.
See Also: Begin Dialog, Dim As UserDialog.
Example
Sub Main
Begin Dialog UserDialog 200,120
Text 10,10,180,15,"Please push the OK button"
GroupBox 10,25,180,60,"Group box"
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
Dialog dlg ' show dialog (wait for ok)
End Sub
Hex$ Function
Syntax
Hex[$](Num)
Group
String
Description
Return a hex string.
Parameter Description
Num Return a hex encoded string for this numeric value.
See Also: Oct$( ), Str$( ), Val( ).
Example
Sub Main
Debug.Print Hex$(15) 'F
End Sub
177

Hour Function
Syntax
Hour(dateexpr)
Group
Time/Date
Description
Return the hour of the day (0 to 23).
Parameter Description
dateexpr Return the hour of the day for this date value. If this value is Null then Null is
returned.
See Also: Minute( ), Second( ), Time( ).
Example
Sub Main
Debug.Print Hour(#12:00:01 AM#) ' 0
End Sub
If Statement
Syntax
If condexpr Then [instruction] [Else instruction]
-or-
If condexpr Then
statements
[ElseIf condexpr Then
statements]...
[Else
statements]
End If
-or-
If TypeOf objexpr Is objtype Then ...
Group
Flow Control
Description
Form 1: Single line if statement. Execute the instruction following the Then if condexpr is True. Otherwise, execute
the instruction following the Else. The Else portion is optional.
Form 2: The multiple line if is useful for complex ifs. Each if condexpr is checked in turn. The first True one causes
178

the following statements to be executed. If all are False then the Else's statements are executed. The ElseIf and
Else portions are optional.
Form 3: If objexpr's type is the same type or a type descended from objtype the Then portion is executed.
See Also: Select Case, Choose( ), IIf( ).
Example
Sub Main
S = InputBox("Enter hello, goodbye, dinner or sleep:")
S = UCase(S)
If S = "HELLO" Then Debug.Print "come in"
If S = "GOODBYE" Then Debug.Print "see you later"
If S = "DINNER" Then
Debug.Print "Please come in."
Debug.Print "Dinner will be ready soon."
ElseIf S = "SLEEP" Then
Debug.Print "Sorry."
Debug.Print "We are full for the night"
End If
End Sub
IIf Function
Syntax
IIf(condexpr, TruePart, FalsePart)
Group
Miscellaneous
Description
Return the value of the parameter indicated by condexpr. Both TruePart and FalsePart are evaluated.
Parameter Description
condexpr If this value is True then return TruePart. Otherwise, return FalsePart.
TruePart Return this value if condexpr is True.
FalsePart Return this value if condexpr is False.
See Also: If, Select Case, Choose( ).
Example
Sub Main
Debug.Print IIf(1 > 0,"True","False") '"True"
End Sub
179

Input Instruction
Syntax
Input [#]StreamNum, var[, ...]
Group
File
Description
Get input from StreamNum and assign it to vars. Input values are comma delimited. Leading and trailing spaces
are ignored. If the first char (following the leading spaces) is a quote (") then the string is terminated by an ending
quote. Special values #NULL#, #FALSE#, #TRUE#, #date# and #ERROR number# are converted to their
appropriate value and data type.
See Also: Line Input, Print, Write.
Example
Sub Main
Open "XXX" For Input As #1
Input #1,A,B,C$
Debug.Print A;B;C$
Close #1
End Sub
Input$ Function
Syntax
Input[$](N, StreamNum)
Group
File
Description
Return N chars from StreamNum.
Parameter Description
N Read this many chars. If fewer than that many chars are left before the end of file
then a run-time error occurs.
StreamNum Streams 1 through 255 are private to each macro. Streams 256 through 511 are
shared by all macros.
Example
Sub Main
Open "XXX" For Input As #1
L = LOF(1)
T$ = Input$(L,1)
Close #1
Debug.Print T$;
180

End Sub
InputBox$ Function
Syntax
InputBox[$](Prompt$[, Title$][, Default$][, XPos, YPos])
Group
User Input
Description
Display an input box where the user can enter a line of text. Pressing the OK button returns the string entered.
Pressing the Cancel button returns a null string.
Parameter Description
Prompt$ Use this string value as the prompt in the input box.
Title$ Use this string value as the title of the input box. If this is omitted then the input box
does not have a title.
Default$ Use this string value as the initial value in the input box. If this is omitted then the
initial value is blank.
XPos When the dialog is put up the left edge will be at this screen position. If this is omitted
then the dialog will be centered.
YPos When the dialog is put up the top edge will be at this screen position. If this is omitted
then the dialog will be centered.
Example
Sub Main
L$ = InputBox$("Enter some text:", _
"Input Box Example","asdf")
Debug.Print L$
End Sub
InStr Function
Syntax
InStr([Index, ]S1$, S2$)
Group
String
Description
Return the index where S2$ first matches S1$. If no match is found return 0.
Note: A similar function, InStrB, returns the byte index instead.
Parameter Description
181

Index Start searching for S2$ at this index in S1$. If this is omitted then start searching
from the beginning of S1$.
S1$ Search for S2$ in this string value. If this value is Null then Null is returned.
S2$ Search S1$ for this string value. If this value is Null then Null is returned.
See Also: InStrRev( ), Left$( ), Len( ), Mid$( ), Replace$( ), Right$( ).
Example
Sub Main
Debug.Print InStr("Hello","l") ' 3
End Sub
InStr Function
Syntax
InStr([Index, ]S1$, S2$)
Group
String
Description
Return the index where S2$ first matches S1$. If no match is found return 0.
Note: A similar function, InStrB, returns the byte index instead.
Parameter Description
Index Start searching for S2$ at this index in S1$. If this is omitted then start searching
from the beginning of S1$.
S1$ Search for S2$ in this string value. If this value is Null then Null is returned.
S2$ Search S1$ for this string value. If this value is Null then Null is returned.
See Also: InStrRev( ), Left$( ), Len( ), Mid$( ), Replace$( ), Right$( ).
Example
Sub Main
Debug.Print InStr("Hello","l") ' 3
End Sub
InStrRev Function
Syntax
InStrRev(S1$, S2$[, Index])
Group
String
182

Description
Return the index where S2$ last matches S1$. If no match is found return 0.
Parameter Description
S1$ Search for S2$ in this string value. If this value is Null then Null is returned.
S2$ Search S1$ for this string value. If this value is Null then Null is returned.
Index Start searching for S2$ ending at this index in S1$. If this is omitted then start
searching from the end of S1$.
See Also: Left$( ), Len( ), Mid$( ), Replace$( ), Right$( ).
Example
Sub Main
Debug.Print InStrRev("Hello","l") ' 4
End Sub
Instruction definition
A single command.
Beep
Debug.Print "Hello"
Today = Date
Multiple instructions may be used instead of a single instruction by separating the single instructions with colons.
X = 1:Debug.Print X
If X = 1 Then Debug.Print "X=";X:Stop
Beep ' must resume from Stop to get to here
Int Function
Syntax
Int(Num)
Group
Math
Description
Return the integer value.
Parameter Description
Num Return the largest integer which is less than or equal to this numeric value. If this
value is Null then Null is returned.
Example
Sub Main
Debug.Print Int(9.9) ' 9
Debug.Print Int(0) ' 0
183

Debug.Print Int(-9.9) '-10
End Sub
Is Operator
Syntax
expr Is expr
Group
Operator
Description
Return the True if both exprs refer to the same object.
See Also: Objects.
Example
Sub Main
Dim X As Object
Dim Y As Object
Debug.Print X Is Y ' True
End Sub
IsArray Function
Syntax
IsArray(var)
Group
Variable Info
Description
Return the True if var is an array of values.
Parameter Description
var A array variable or a variant var can contain multiple of values.
See Also: TypeName, VarType.
Example
Sub Main
Dim X As Variant, Y(2) As Integer
Debug.Print IsArray(X) 'False
X = Array(1,4,9)
Debug.Print IsArray(X) 'True
184

X = Y
Debug.Print IsArray(X) 'True
End Sub
IsDate Function
Syntax
IsDate(expr)
Group
Variable Info
Description
Return the True if expr is a valid date.
Parameter Description
expr A variant expression to test for a valid date.
See Also: TypeName, VarType.
Example
Sub Main
Dim X As Variant
X = 1
Debug.Print IsDate(X) 'False
X = Now
Debug.Print IsDate(X) 'True
End Sub
IsEmpty Function
Syntax
IsEmpty(variantvar)
Group
Variable Info
Description
Return the True if variantvar is Empty.
Parameter Description
variantvar A variant var is Empty if it has never been assigned a value.
See Also: TypeName, VarType.
Example
185

Sub Main
Dim X As Variant
Debug.Print IsEmpty(X) 'True
X = 0
Debug.Print IsEmpty(X) 'False
X = Empty
Debug.Print IsEmpty(X) 'True
End Sub
IsError Function
Syntax
IsError(expr)
Group
Variable Info
Description
Return the True if expr is an error code.
Parameter Description
expr A variant expression to test for an error code value.
See Also: TypeName, VarType.
Example
Sub Main
Dim X As Variant
Debug.Print IsError(X) 'False
X = CVErr(1)
Debug.Print IsError(X) 'True
End Sub
IsMissing Function
Syntax
IsMissing(variantvar)
Group
Variable Info
Description
Return the True if Optional parameter variantvar does not have a default value and it did not get a value. An
Optional parameter may be omitted in the Sub, Function or Property call.
Parameter Description
186

variantvar Return True if this variant parameter's argument expression was not specified in the
Sub, Function or Property call.
Example
Sub Main
Opt 'IsMissing(A)=True
Opt "Hi" 'IsMissing(A)=False
Many 'No args
Many 1,"Hello" 'A(0)=1 A(1)=Hello
OptBye '"Bye"
OptBye "No" '"No"
End Sub
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Opt(Optional A)
Debug.Print "IsMissing(A)=";IsMissing(A)
End Sub
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Many(ParamArray A())
If LBound(A) > UBound(A) Then
Debug.Print "No args"
Else
For I = LBound(A) To UBound(A)
Debug.Print "A(" & I & ")=" & A(I) & " ";
Next I
Debug.Print
End If
End Sub
C:\ABCTemp\vbs\Sub_Definition.htm
Sub OptBye(Optional A As String = "Bye")
Debug.Print A
End Sub
IsNumeric Function
Syntax
IsNumeric(expr)
Group
Variable Info
Description
Return the True if expr is a numeric value.
Parameter Description
expr A variant expression is a numeric value if it is numeric or string value that represents
a number.
See Also: TypeName, VarType.
Example
187

Sub Main
Dim X As Variant
X = 1
Debug.Print IsNumeric(X) 'True
X = "1"
Debug.Print IsNumeric(X) 'True
X = "A"
Debug.Print IsNumeric(X) 'False
End Sub
IsNull Function
Syntax
IsNull(expr)
Group
Variable Info
Description
Return the True if expr is Null.
Parameter Description
expr A variant expression to test for Null.
See Also: TypeName, VarType.
Example
Sub Main
Dim X As Variant
Debug.Print IsEmpty(X) 'True
Debug.Print IsNull(X) 'False
X = 1
Debug.Print IsNull(X) 'False
X = "1"
Debug.Print IsNull(X) 'False
X = Null
Debug.Print IsNull(X) 'True
X = X*2
Debug.Print IsNull(X) 'True
End Sub
IsObject Function
Syntax
IsObject(var)
Group
188

Variable Info
Description
Return the True if var contains an object reference.
Parameter Description
var A var contains an object reference if it is objexpr reference.
See Also: TypeName, VarType.
Example
Sub Main
Dim X As Variant
X = 1
Debug.Print IsObject(X) 'False
X = "1"
Debug.Print IsObject(X) 'False
Set X = Nothing
Debug.Print IsObject(X) 'True
End Sub
KeyName Function
Syntax
KeyName(Key)
Group
Miscellaneous
Description
Return the key name for a key number. This is the name used by SendKeys.
Parameter Description
Key Key number.
See Also: SendKeys.
Example
Sub Main
Debug.Print KeyName(&H270) '"^{F1}"
End Sub
Kill Instruction
Syntax
Kill Name$
189

Group
File
Description
Delete the file named by Name$.
Parameter Description
Name$ This string value is the path and name of the file. A path relative to the current
directory can be used.
Example
Sub Main
Kill "XXX"
End Sub
Label definition
An identifier that names a statement. Identifiers start with a letter. Following chars may be a letter, an underscore
or a digit.
LBound Function
Syntax
LBound(arrayvar[, dimension])
Group
Variable Info
Description
Return the lowest index.
Parameter Description
arrayvar Return the lowest index for this array variable.
dimension Return the lowest index for this dimension of arrayvar. If this is omitted then return
the lowest index for the first dimension.
See Also: UBound( ).
Example
Sub Main
Dim A(-1 To 3,2 To 6)
Debug.Print LBound(A) '-1
Debug.Print LBound(A,1) '-1
Debug.Print LBound(A,2) ' 2
End Sub
190

LCase$ Function
Syntax
LCase[$](S$)
Group
String
Description
Return a string from S$ where all the uppercase letters have been lowercased.
Parameter Description
S$ Return the string value of this after all chars have been converted to lowercase. If
this value is Null then Null is returned.
See Also: StrComp( ), StrConv$( ), UCase$( ).
Example
Sub Main
Debug.Print LCase$("Hello") '"hello"
End Sub
Left$ Function
Syntax
Left[$](S$, Len)
Group
String
Description
Return a string from S$ with only the Len chars.
Note: A similar function, LeftB, returns the first Len bytes.
Parameter Description
S$ Return the left portion of this string value. If this value is Null then Null is returned.
Len Return this many chars. If S$ is shorter than that then just return S$.
See Also: InStr( ), InStrRev( ), Len( ), Mid$( ), Replace$( ), Right$( ).
Example
Sub Main
Debug.Print Left$("Hello",2) '"He"
End Sub
191

Left$ Function
Syntax
Left[$](S$, Len)
Group
String
Description
Return a string from S$ with only the Len chars.
Note: A similar function, LeftB, returns the first Len bytes.
Parameter Description
S$ Return the left portion of this string value. If this value is Null then Null is returned.
Len Return this many chars. If S$ is shorter than that then just return S$.
See Also: InStr( ), InStrRev( ), Len( ), Mid$( ), Replace$( ), Right$( ).
Example
Sub Main
Debug.Print Left$("Hello",2) '"He"
End Sub
Len Function
Syntax
Len(S$)
-or-
Len(usertypevar)
Group
String
Description
Return the number of characters in S$.
Note: A similar function, LenB, returns the number of bytes in the string. For a usertypevar, LenB returns the
number of bytes of memory occupied by the variable's data.
Parameter Description
S$ Return the number of chars in this string value. If this value is Null then Null is
returned.
usertypevar Return the number of bytes required to store this user type variable. If the user type
has any dynamic String and Variant elements the length returned may not be as big
as the actual number of bytes required.
See Also: InStr( ), InStrRev( ), Left$( ), Mid$( ), Replace$( ), Right$( ).
192

Example
Sub Main
Debug.Print Len("Hello") ' 5
End Sub
Len Function
Syntax
Len(S$)
-or-
Len(usertypevar)
Group
String
Description
Return the number of characters in S$.
Note: A similar function, LenB, returns the number of bytes in the string. For a usertypevar, LenB returns the
number of bytes of memory occupied by the variable's data.
Parameter Description
S$ Return the number of chars in this string value. If this value is Null then Null is
returned.
usertypevar Return the number of bytes required to store this user type variable. If the user type
has any dynamic String and Variant elements the length returned may not be as big
as the actual number of bytes required.
See Also: InStr( ), InStrRev( ), Left$( ), Mid$( ), Replace$( ), Right$( ).
Example
Sub Main
Debug.Print Len("Hello") ' 5
End Sub
Let Instruction
Syntax
[Let] var = expr
Group
Assignment
Description
193

Assign the value of expr to var. The keyword Let is optional.
Example
Sub Main
Let X = 1
X = X*2
Debug.Print X ' 2
End Sub
Like Operator
Syntax
str1 Like str2
Group
Operator
Description
Return the True if str1 matches pattern str2. The pattern in str2 is one or more of the special character sequences
shown in the following table.
Char(s) Description
? Match any single character
* Match zero or more characters
# Match a single digit (0-9)
[charlist] Match any char in the list
[!charlist] Match any char not in the list
Example
Sub Main
Debug.Print "abcdfgcdefg" Like "" ' False
Debug.Print "abcdfgcdefg" Like "a*g" ' True
Debug.Print "abcdfgcdefg" Like "a*cde*g" ' True
Debug.Print "abcdfgcdefg" Like "a*cd*cd*g" ' True
Debug.Print "abcdfgcdefg" Like "a*cd*cd*g" ' True
Debug.Print "00aa" Like "####" ' False
Debug.Print "00aa" Like "????" ' True
Debug.Print "00aa" Like "##??" ' True
Debug.Print "00aa" Like "*##*" ' True
Debug.Print "hk" Like "hk*" ' True
End Sub
Line Input Instruction
Syntax
Line Input [#]StreamNum, S$
194

Group
File
Description
Get a line of input from StreamNum and assign it to S$.
See Also: Input, Print, Write.
Example
Sub Main
Open "XXX" For Input As #1
Line Input #1,S$
Debug.Print S$
Close #1
End Sub
Line Input Instruction
Syntax
Line Input [#]StreamNum, S$
Group
File
Description
Get a line of input from StreamNum and assign it to S$.
See Also: Input, Print, Write.
Example
Sub Main
Open "XXX" For Input As #1
Line Input #1,S$
Debug.Print S$
Close #1
End Sub
ListBox Dialog Item Definition
Syntax
ListBox X, Y, DX, DY, StrArray$( ), .Field[, Options]
Group
195

User Dialog
Description
Define a listbox item.
Parameter Description
X This number value is the distance from the left edge of the dialog box. It is measured
in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is measured
in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
StrArray$( ) This one-dimensional array of strings establishes the list of choices. All the non-null
elements of the array are used.
Field The value of the list box is accessed via this field. It is the index of the StrArray$( )
var.
Options This numeric value controls the type of list box. Choose one value from following
table. (If this numeric value omitted then zero is used.)
Parameter Description
0 List is not sorted.
2 List is sorted.
See Also: Begin Dialog, Dim As UserDialog.
Example
Sub Main
Dim lists$(3)
lists$(0) = "List 0"
lists$(1) = "List 1"
lists$(2) = "List 2"
lists$(3) = "List 3"
Begin Dialog UserDialog 200,120
Text 10,10,180,15,"Please push the OK button"
ListBox 10,25,180,60,lists$(),.list
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
dlg.list = 2
Dialog dlg ' show dialog (wait for ok)
Debug.Print dlg.list
End Sub
Little-endian definition
Multiple byte data values (not strings) are stored with the lowest order byte first. For example, the long integer
&H01020304 is stored as this sequence of four bytes: &H04, &H03, &H02 and &H01. A Binary or Random file
written using Put uses little-endian format so that it can be read using Get on any machine. (Big-endian machines,
like the Power-PC, reverse the bytes as they are read by Get or written by Put.)
196

Loc Function
Syntax
Loc(StreamNum)
Group
File
Description
Return StreamNum file position. For Random mode files this is the current record number minus one. For Binary
mode files it is the current byte position minus one. Otherwise, it is the current byte position minus one divided by
128. The first position in the file is 0.
Parameter Description
StreamNum Streams 1 through 255 are private to each macro. Streams 256 through 511 are
shared by all macros.
Example
Sub Main
Open "XXX" For Input As #1
L = Loc(1)
Close #1
Debug.Print L ' 0
End Sub
Lock Instruction
Syntax
Lock StreamNum
-or-
Lock StreamNum, RecordNum
-or-
Lock StreamNum, [start] To end
Group
File
Description
Form 1: Lock all of StreamNum.
Form 2: Lock a record (or byte) of StreamNum.
Form 3: Lock a range of records (or bytes) of StreamNum. If start is omitted then lock starting at the first record
(or byte).
Note: Be sure to Unlock for each Lock instruction.
Note: For sequential files (Input, Output and Append) lock always affects the entire file.
Parameter Description
197

StreamNum Streams 1 through 255 are private to each macro. Streams 256 through 511 are
shared by all macros.
RecordNum For Random mode files this is the record number. The first record is 1. Otherwise, it
is the byte position. The first byte is 1.
start First record (or byte) in the range.
end Last record (or byte) in the range.
See Also: Open, Unlock.
Example
Sub Main
Dim V As Variant
Open "SAVE_V.DAT" For Binary As #1
Lock #1
Get #1, 1, V
V = "Hello"
Put #1, 1, V
Unlock #1
Close #1
End Sub
LOF Function
Syntax
LOF(StreamNum)
Group
File
Description
Return StreamNum file length (in bytes).
Parameter Description
StreamNum Streams 1 through 255 are private to each macro. Streams 256 through 511 are
shared by all macros.
Example
Sub Main
Open "XXX" For Input As #1
L = LOF(1)
Close #1
Debug.Print L
End Sub
Log Function
Syntax
198

Log(Num)
Group
Math
Description
Return the natural logarithm.
Parameter Description
Num Return the natural logarithm of this numeric value. The value e is approximately
2.718282.
Example
Sub Main
Debug.Print Log(1) ' 0
End Sub
LSet Instruction
Syntax
LSet strvar = str
-or-
LSet usertypevar1 = usertypevar2
Group
Assignment
Description
Form 1: Assign the value of str to strvar. Shorten str by removing trailing chars (or extend with blanks). The
previous length strvar is maintained.
Form 2: Assign the value of usertypevar2 to usertypevar1. If usertypevar2 is longer than usertypevar1 then only
copy as much as usertypevar1 can handle.
See Also: RSet.
Example
Sub Main
S$ = "123"
LSet S$ = "A"
Debug.Print ".";S$;"." '".A ."
End Sub
199

LTrim$ Function
Syntax
LTrim[$](S$)
Group
String
Description
Return the string with S$'s leading spaces removed.
Parameter Description
S$ Copy this string without the leading spaces. If this value is Null then Null is returned.
See Also: RTrim$( ), Trim$( ).
Example
Sub Main
Debug.Print ".";LTrim$(" x ");"." '".x ."
End Sub
Macro definition
A macro is like an application. Execution starts at the macro's Sub Main.
MacroDir$ Function
Syntax
MacroDir[$]
Group
Flow Control
Description
Return the directory of the current macro. A run-time error occurs if the current macro has never been saved.
See Also: MacroRun.
Example
Sub Main
' open the file called Data that is in the
' same directory as the macro
Open MacroDir & "\Data" For Input As #1
Line Input #1, S$
200

Debug.Print S$
Close #1
End Sub
MacroRun Instruction
Syntax
MacroRun MacroName$[, Command$]
Group
Flow Control
Description
Play a macro. Execution will continue at the following statement after the macro has completed.
Parameter Description
MacroName$ Run the macro named by this string value.
Command$ Pass this string value as the macro's Command$ value.
See Also: Command$, MacroDir$, MacroRunThis.
Example
Sub Main
Debug.Print "Before Demo"
MacroRun "Demo"
Debug.Print "After Demo"
End Sub
MacroRunThis Instruction
Syntax
MacroRunThis MacroCode$
Group
Flow Control
Description
Play the macro code. Execution will continue at the following statement after the macro code has completed. The
macro code can be either a single line or a complete macro.
Parameter Description
MacroName$ Run the macro named by this string value.
See Also: Command$, MacroDir$, MacroRun.
Example
201

Sub Main
Debug.Print "Before Demo"
MacroRunThis "MsgBox ""Hello"""
Debug.Print "After Demo"
End Sub
Me Object
Syntax
Me
Group
Object
Description
Me references the current macro/module. It can be used like any other object variable, except that it's reference
can't be changed.
See Also: Set.
Example
Sub Main
DoIt
Me.DoIt ' calls the same sub
End Sub
Sub DoIt
MsgBox "Hello"
End Sub
Method definition
An object provides methods and properties. Methods can be called as subs (the return value is ignored), or used
as functions (the return value is used).
If the method name contains characters that are not legal in a name, surround the method name with [].
App.[Title$]
Mid$ Function/Assignment
Syntax
Mid[$](S$, Index[, Len])
-or-
202

Mid[$](strvar, Index[, Len]) = S$
Group
String
Description
Function: Return the substring of S$ starting at Index for Len chars.
Instruction: Assign S$ to the substring in strvar starting at Index for Len chars.
Note: A similar function, MidB, returns the Len bytes starting a byte Index.
Parameter Description (Mid Function)
S$ Copy chars from this string value. If this value is Null then Null is returned.
Index Start copying chars starting at this index value. If the string is not that long then
return a null string.
Len Copy this many chars. If the S$ does not have that many chars starting at Index then
copy the remainder of S$.
Parameter Description (Mid Assignment)
strvar Change part of this string.
Index Change strvar starting at this index value. If the string is not that long then it is not
changed.
Len The number of chars copied is smallest of: the value of Len, the length of S$ and the
remaining length of strvar. (If this value is omitted then the number of chars copied
is the smallest of: the length of S$ and the remaining length of strvar.)
S$ Copy chars from this string value.
See Also: InStr( ), Left$( ), Len( ), Replace$( ), Right$( ).
Example
Sub Main
S$ = "Hello There"
Mid$(S$,7) = "?????????"
Debug.Print S$ '"Hello ?????"
Debug.Print Mid$("Hello",2,1) '"e"
End Sub
Mid$ Function/Assignment
Syntax
Mid[$](S$, Index[, Len])
-or-
Mid[$](strvar, Index[, Len]) = S$
Group
String
Description
Function: Return the substring of S$ starting at Index for Len chars.
203

Instruction: Assign S$ to the substring in strvar starting at Index for Len chars.
Note: A similar function, MidB, returns the Len bytes starting a byte Index.
Parameter Description (Mid Function)
S$ Copy chars from this string value. If this value is Null then Null is returned.
Index Start copying chars starting at this index value. If the string is not that long then
return a null string.
Len Copy this many chars. If the S$ does not have that many chars starting at Index then
copy the remainder of S$.
Parameter Description (Mid Assignment)
strvar Change part of this string.
Index Change strvar starting at this index value. If the string is not that long then it is not
changed.
Len The number of chars copied is smallest of: the value of Len, the length of S$ and the
remaining length of strvar. (If this value is omitted then the number of chars copied
is the smallest of: the length of S$ and the remaining length of strvar.)
S$ Copy chars from this string value.
See Also: InStr( ), Left$( ), Len( ), Replace$( ), Right$( ).
Example
Sub Main
S$ = "Hello There"
Mid$(S$,7) = "?????????"
Debug.Print S$ '"Hello ?????"
Debug.Print Mid$("Hello",2,1) '"e"
End Sub
Minute Function
Syntax
Minute(dateexpr)
Group
Time/Date
Description
Return the minute of the hour (0 to 59).
Parameter Description
dateexpr Return the minute of the hour for this date value. If this value is Null then Null is
returned.
See Also: Hour( ), Second( ), Time( ).
Example
Sub Main
Debug.Print Minute(#12:00:01 AM#) ' 0
End Sub
204

MkDir Instruction
Syntax
MkDir Name$
Group
File
Description
Make directory Name$.
Parameter Description
Name$ This string value is the path and name of the directory. A path relative to the current
directory can be used.
See Also: RmDir.
Example
Sub Main
MkDir "C:\WWTEMP"
End Sub
Module definition
A file with public symbols that are accessible by other modules/macros via the #Uses comment.
A module is loaded on demand.
A code module is a code library.
An object module or class module implements an ActiveX Automation object.
A module may also access other modules with its own #Uses comments.
Month Function
Syntax
Month(dateexpr)
Group
Time/Date
Description
Return the month of the year (1 to 12).
205

Parameter Description
dateexpr Return the month of the year for this date value. If this value is Null then Null is
returned.
See Also: Date( ), Day( ), MonthName( ), Weekday( ), Year( ).
Example
Sub Main
Debug.Print Month(#1/1/1900#) ' 1
Debug.Print Month(#2/1/1900#) ' 2
End Sub
MonthName Function
Syntax
MonthName(NumZ{month}[, CondZ{abbrev}])
Group
Time/Date
Description
Return the localized name of the month.
Parameter Description
month Return the localized name of this month. (1-12)
abbrev If this conditional value is True then return the abbreviated form of the month name.
See Also: Month( ).
Example
Sub Main
Debug.Print MonthName(1) 'January
Debug.Print MonthName(Month(Now))
End Sub
MsgBox Instruction/Function
Syntax
MsgBox Message$[, Type][, Title$]
-or-
MsgBox(Message$[, Type][, Title$])
Group
User Input
206

Description
Show a message box titled Title$. Type controls what the message box looks like (choose one value from each
category). Use MsgBox( ) if you need to know what button was pressed. The result indicates which button was
pressed.
Result Value Button Pressed
vbOK 1 OK button
vbCancel 2 Cancel button
vbAbort 3 Abort button
vbRetry 4 Retry button
vbIgnore 5 Ignore button
vbYes 6 Yes button
vbNo 7 No button
Parameter Description
Message$ This string value is the text that is shown in the message box.
Type This numeric value controls the type of message box. Choose one value from each of
the following tables.
Title$ This string value is the title of the message box.
Button Value Effect
vbOkOnly 0 OK button
vbOkCancel 1 OK and Cancel buttons
vbAbortRetryIgnore 2 Abort, Retry, Ignore buttons
vbYesNoCancel 3 Yes, No, Cancel buttons
vbYesNo 4 Yes and No buttons
vbRetryCancel 5 Retry and Cancel buttons
Icon Value Effect
0 No icon
vbCritical 16 Stop icon
vbQuestion 32 Question icon
vbExclamation 48 Attention icon
vbInformation 64 Information icon
Default Value Effect
vbDefaultButton1 0 First button
vbDefaultButton2 256 Second button
vbDefaultButton3 512 Third button
Mode Value Effect
vbApplicationModal 0 Application modal
vbSystemModal 1000 System modal
Example
Sub Main
MsgBox "Please press OK button"
If MsgBox("Please press OK button",vbOkCancel) = vbOK Then
Debug.Print "OK was pressed"
Else
Debug.Print "Cancel was pressed"
End If
End Sub
207

MultiListBox Dialog Item Definition
Syntax
MultiListBox X, Y, DX, DY, StrArray$( ), .Field[, Options]
Group
User Dialog
Description
Define a multiple selection listbox item.
Parameter Description
X This number value is the distance from the left edge of the dialog box. It is measured
in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is measured
in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
StrArray$( ) This one-dimensional array of strings establishes the list of choices. All the non-null
elements of the array are used.
Field The value of the list box is accessed via this field. It is the index of the StrArray$( )
var.
Options This numeric value controls the type of list box. Choose one value from following
table. (If this numeric value omitted then zero is used.)
Parameter Description
0 List is not sorted.
1 List is not sorted and horizontally scrollable.
2 List is sorted.
3 List is sorted and horizontally scrollable.
See Also: Begin Dialog, Dim As UserDialog, ListBox.
Example
Sub Main
Dim lists$(3)
lists$(0) = "List 0"
lists$(1) = "List 1"
lists$(2) = "List 2"
lists$(3) = "List 3"
Begin Dialog UserDialog 200,120
Text 10,10,180,15,"Please push the OK button"
MultiListBox 10,25,180,60,lists$(),.list
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
dlg.list = Array (2)
Dialog dlg ' show dialog (wait for ok)
For i = LBound(dlg.list) To UBound(dlg.list)
Debug.Print lists$(dlg.list(i));
Next i
Debug.Print
End Sub
208

Name definition
An identifier that names a variable or a user defined procedure. Identifiers start with a letter. Following chars may
be a letter, an underscore or a digit.
Count
DaysTill2000
Get_Data
Name Instruction
Syntax
Name OldName$ As NewName$
Group
File
Description
Rename file OldName$ as NewName$.
Parameter Description
OldName$ This string value is the path and name of the file. A path relative to the current
directory can be used.
NewName$ This is the new file name (and path). A path relative to the current directory can be
used.
Example
Sub Main
Name "AUTOEXEC.BAK" As "AUTOEXEC.SAV"
End Sub
Now Function
Syntax
Now
Group
Time/Date
Description
Return the current date and time as a date value.
209

See Also: Date, Time, Timer.
Example
Sub Main
Debug.Print Now ' example: 1/1/1995 10:05:32 AM
End Sub
Num definition
An expression that returns a numeric result. Use &O to express an octal number. Use &H to express a hex number.
Numvar definition
A variable that holds one numeric value. The name of a numeric variable may be followed by the appropriate type
char.
Objexpr definition
A expression that returns a reference to an object or module.
CreateObject("WinWrap.CDemoApplication")
Objtype definition
A specific ActiveX Automation type defined by your application, another application or by an object module or class
module.
See Also: Objects, CreateObject( ), GetObject( ).
Objvar definition
A variable that holds a objexpr which references an object. Object variables are declared using As Object in a Dim,
Private or Public statement.
See Also: Objects.
210

Oct$ Function
Syntax
Oct[$](Num)
Group
String
Description
Return a octal string.
Parameter Description
Num Return an octal encoded string for this numeric value.
See Also: Hex$( ), Str$( ), Val( ).
Example
Sub Main
Debug.Print Oct$(15) '17
End Sub
OKButton Dialog Item Definition
Syntax
OKButton X, Y, DX, DY[, .Field]
Group
User Dialog
Description
Define an OK button item. Pressing the OK button updates the dlgvar field values and closes the dialog. (Dialog( )
function call returns -1.)
Parameter Description
X This number value is the distance from the left edge of the dialog box. It is measured
in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is measured
in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
Field This identifier is the name of the field. The dialogfunc receives this name as string. If
this is omitted then the field name is "OK".
See Also: Begin Dialog, Dim As UserDialog.
Example
Sub Main
211

Begin Dialog UserDialog 200,120
Text 10,10,180,30,"Please push the OK button"
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
Dialog dlg ' show dialog (wait for ok)
End Sub
On Error Instruction
Syntax
On Error GoTo 0
-or-
On Error GoTo label
-or-
On Error Resume Next
Group
Error Handling
Description
Form 1: Disable the error handler (default).
Form 2: Send error conditions to an error handler.
Form 3: Error conditions continue execution at the next statement.
On Error sets or disables the error handler. Each user defined procedure has its own error handler. The default is
to terminate the macro on any error. The Err object's properties are set whenever an error occurs. Once an error
has occurred and the error handler is executing any further errors will terminate the macro, unless the Err object
has been cleared.
Note: This instruction clears the Err and sets Error$ to null.
Example
Sub Main
On Error Resume Next
Err.Raise 1
Debug.Print "RESUMING, Err=";Err
On Error GoTo X
Err.Raise 1
Exit Sub
X: Debug.Print "Err=";Err
Err.Clear
Debug.Print "Err=";Err
Resume Next
End Sub
212

Open Instruction
Syntax
Open Name$ For mode [Access access] [lock] As _
[#]StreamNum [Len = RecordLen]
Group
File
Description
Open file Name$ for mode as StreamNum.
Parameter Description
Name$ This string value is the path and name of the file. A path relative to the current
directory can be used.
mode May be Input, Output, Append, Binary or Random.
access May be Read, Write or Read Write.
lock May be Shared, Lock Read, Lock Write or Lock Read Write.
StreamNum Streams 1 through 255 are private to each macro. Streams 256 through 511 are
shared by all macros.
RecordLen This numeric value is the record length for Random mode files. Other file modes
ignore this value.
See Also: Close, FileAttr, FreeFile, Reset.
Example
Sub Main
Open "XXX" For Output As #1
Print #1,"1,2,""Hello"""
Close #1
End Sub
Option Definition
Syntax
Option Base [0|1]
-or-
Option Explicit
-or-
Option Private Module
Group
Declaration
Description
Form 1: Set the default base index for array declarations. Affects Dim, Static, Private, Public and ReDim. Does not
affect Array, ParamArray or arrays declare in a Type. Option Base 0 is the default.
213

Form 2: Require all variables to be declared prior to use. Variables are declared using Dim, Private, Public, Static
or as a parameter of Sub, Function or Property blocks.
Form 3: Public symbols defined by the module are only accessible from the same project.
See Also: Dim, Private, Public, ReDim, Static.
Example
Option Base 1
Option Explicit
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
Dim A
Dim C(2) ' same as Dim C(1 To 2)
Dim D(0 To 2)
A = 1
B = 2 ' B has not been declared
End Sub
OptionButton Dialog Item Definition
Syntax
OptionButton X, Y, DX, DY, Title$[, .Field]
Group
User Dialog
Description
Define an option button item.
Parameter Description
X This number value is the distance from the left edge of the dialog box. It is measured
in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is measured
in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
Title$ The value of this string is the title of the option button.
See Also: Begin Dialog, Dim As UserDialog, OptionGroup.
Example
Sub Main
Begin Dialog UserDialog 200,120
Text 10,10,180,15,"Please push the OK button"
OptionGroup .options
OptionButton 10,30,180,15,"Option &0"
OptionButton 10,45,180,15,"Option &1"
OptionButton 10,60,180,15,"Option &2"
214

OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
dlg.options = 2
Dialog dlg ' show dialog (wait for ok)
Debug.Print dlg.options
End Sub
OptionGroup Dialog Item Definition
Syntax
OptionGroup .Field
OptionButton X, Y, DX, DY, Title$[, .Field]
OptionButton X, Y, DX, DY, Title$[, .Field]
...
Group
User Dialog
Description
Define a optiongroup and option button items.
Parameter Description
Field The value of the option group is accessed via this field. This first option button is 0,
the second is 1, etc.
X This number value is the distance from the left edge of the dialog box. It is measured
in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is measured
in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
Title$ The value of this string is the title of the option button.
See Also: Begin Dialog, Dim As UserDialog, OptionButton.
Example
Sub Main
Begin Dialog UserDialog 200,120
Text 10,10,180,15,"Please push the OK button"
OptionGroup .options
OptionButton 10,30,180,15,"Option &0"
OptionButton 10,45,180,15,"Option &1"
OptionButton 10,60,180,15,"Option &2"
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
dlg.options = 2
Dialog dlg ' show dialog (wait for ok)
Debug.Print dlg.options
End Sub
215

Param definition
[ [Optional] [ | ByVal | ByRef ] | ParamArray ] param[type][( )] [As type] [ = defaultvalue ]
The param receives the value of the associated expression in the Declare, Sub, Function or Property call. (See
arglist.)
An Optional param may be omitted from the call. It may also have a defaultvalue. The parameter receives the
default value if a value is not specified by the call. If the default value is omitted, the parameter is a Variant
and no value is specified in the call then IsMissing will return True.
All parameters following an Optional parameter must also be Optional.
ParamArray may be used on the final param. It must be an array of Variant type. It must not follow any Optional
parameters. The ParamArray receives all the expressions at the end of the call as an array. If
LBound(param) > UBound(param) then the ParamArray didn't receive any expressions.
If the param is not ByVal and the expression is merely a variable then the param is a reference to that variable
(ByRef). (Changing param changes the variable.) Otherwise, the parameter variable is local to the
procedure, so changing its value does not affect the caller.
Use param( ) to specify an array parameter. An array parameter must be referenced and can not be passed by
value. The bounds of the parameter array are available via LBound( ) and UBound( ).
Picture Dialog Item Definition
Syntax
Picture X, Y, DX, DY, FileName$, Type[, .Field]
Group
User Dialog
Description
Define a picture item. The bitmap is automatically sized to fit the item's entire area.
Parameter Description
X This number value is the distance from the left edge of the dialog box. It is measured
in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is measured
in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
FileName$ The value of this string is the .BMP file shown in the picture control.
Type This numeric value indicates the type of bitmap used. See below.
Field This identifier is the name of the field. The dialogfunc receives this name as string. If
this identifer is omitted then the first two words of the title are used.
Type Effect
216

0 FileName is the name of the bitmap file. If the file does not exist then "(missing picture)" is
displayed.
3 The clipboard's bitmap is displayed. Not supported.
+16 Instead of displaying "(missing picture)" a run-time error occurs.
See Also: Begin Dialog, Dim As UserDialog.
Example
Sub Main
Begin Dialog UserDialog 200,120
Picture 10,10,180,75,"SAMPLE.BMP",0
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
Dialog dlg ' show dialog (wait for ok)
End Sub
Precedence definition
When several operators are used in an expression, each operator is evaluated in a predetermined order. Operators
are evaluated in this order:
^ (power)
- (negate)
* (multiply), / (divide)
\ (integer divide)
Mod (integer remainder)
+ (add), - (difference)
& (string concatenate)
= (equal), (not equal), < (less than) > (greater than), = (greater than or equal
to), Like, (string similarity) Is (object equivalence)
Not (logical bitwise invert)
And (logical bitwise and)
Or (logical or bitwise or)
Xor (logical or bitwise exclusive-or)
Eqv (logical or bitwise equivalence)
Imp (logical or bitwise implication)
Operators shown on the same line are evaluated from left to right.
Print Instruction
Syntax
217

Print #StreamNum, [expr[; ...][;]]
Group
File
Description
Print the expr(s) to StreamNum. Use ; to separate expressions. A num is it automatically converted to a string
before printing (just like Str$( )). If the instruction does not end with a semicolon, then a new line is printed at the
end.
See Also: Input, Line Input, Write.
Example
Sub Main
A = 1
B = 2
C$ = "Hello"
Open "XXX" For Output As #1
Print #1,A;",";B;",""";C$;""""
Close #1
End Sub
Private Definition
Syntax
Private [WithEvents] name[type][([dim[, ...]])] [As [New] type][, ...]
Group
Declaration
Description
Create arrays (or simple variables) which are available to the entire macro/module, but not other macros/modules.
Dimension var array(s) using the dims to establish the minimum and maximum index value for each dimension. If
the dims are omitted then a scalar (single value) variable is defined. A dynamic array is declared using ( ) without
any dims. It must be ReDimensioned before it can be used. The Private statement must be placed outside of Sub,
Function or Property blocks.
See Also: Dim, Option Base, Public, ReDim, Static, WithEvents.
Example
Private A0,A1(1),A2(1,1)
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Init
A0 = 1
A1(0) = 2
A2(0,0) = 3
End Sub
C:\ABCTemp\vbs\Sub_Definition.htm
218

Sub Main
Init
Debug.Print A0;A1(0);A2(0,0) ' 1 2 3
End Sub
Procedure definition
A subroutine, function or property.
Property definition
An object provides methods and properties. Properties may be used as values (like a function call) or changed
(using assignment syntax).
If the property name contains characters that are not legal in a name, surround the property name with [].
App.[Title$]
See Also: Objects.
Property Definition
Syntax
[ | Private | Public | Friend ] _
Property Get name[type][([param[, ...]])] [As type[()]]
statements
End Property
-or-
[ | Private | Public | Friend ] _
Property [Let|Set] name[([param[, ...]])]
statements
End Property
Group
Declaration
Description
User defined property. The property defines a set of statements to be executed when its value is used or changed.
A property acts like a variable, except that getting its value calls Property Get and changing its value calls Property
Let (or Property Set). Property Get and Property Let with the same name define a property that holds a value.
Property Get and Property Set with the same name define a property that holds an object reference. The values of
the calling arglist are assigned to the params. (For Property Let and Property Set the last parameter is the value
on the right hand side of the assignment operator.)
Property defaults to Public if Private, Public or Friend are not is specified.
219

See Also: Function, Sub.
Example
Dim X_Value
Property Get X()
X = X_Value
End Property
Property Let X(NewValue)
If Not IsNull(NewValue) Then X_Value = NewValue
End Property
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
X = "Hello"
Debug.Print X
X = Null
Debug.Print X
End Sub
Public Definition
Syntax
Public [WithEvents] name[type][([dim[, ...]])] [As [New] type][, ...]
Group
Declaration
Description
Create arrays (or simple variables) which are available to the entire macro/module and other macros/modules.
Dimension var array(s) using the dims to establish the minimum and maximum index value for each dimension. If
the dims are omitted then a scalar (single value) variable is defined. A dynamic array is declared using ( ) without
any dims. It must be ReDimensioned before it can be used. The Public statement must be placed outside of Sub,
Function or Property blocks.
See Also: Dim, Option Base, Private, ReDim, Static, WithEvents.
Example
Public A0,A1(1),A2(1,1)
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Init
A0 = 1
A1(0) = 2
A2(0,0) = 3
End Sub
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
Init
Debug.Print A0;A1(0);A2(0,0) ' 1 2 3
End Sub
220

PushButton Dialog Item Definition
Syntax
PushButton X, Y, DX, DY, Title$[, .Field]
Group
User Dialog
Description
Define a push button item. Pressing the push button updates the dlgvar field values and closes the dialog.
(Dialog( ) function call returns the push button's ordinal number in the dialog. The first push button returns 1.)
Parameter Description
X This number value is the distance from the left edge of the dialog box. It is measured
in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is measured
in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
Title$ The value of this string is the title of the push button control.
Field This identifier is the name of the field. The dialogfunc receives this name as string. If
this identifer is omitted then the first two words of the title are used.
See Also: Begin Dialog, Dim As UserDialog.
Example
Sub Main
Begin Dialog UserDialog 200,120
Text 10,10,180,30,"Please push the DoIt button"
OKButton 40,90,40,20
PushButton 110,90,60,20,"&Do It"
End Dialog
Dim dlg As UserDialog
Debug.Print Dialog(dlg)
End Sub
Put Instruction
Syntax
Put StreamNum, [RecordNum], var
Group
File
221

Description
Write a variable's value to StreamNum.
Parameter Description
StreamNum Streams 1 through 255 are private to each macro. Streams 256 through 511 are
shared by all macros.
RecordNum For Random mode files this is the record number. The first record is 1. Otherwise, it
is the byte position. The first byte is 1. If this is omitted then the current position (or
record number) is used.
var This variable value is written to the file. For a fixed length variable (like Long) the
number of bytes required to store the variable are written. For a Variant variable two
bytes which describe its type are written and then the variable value is written
accordingly. For a usertype variable each field is written in sequence. For an array
variable each element is written in sequence. For a dynamic array variable the
number of dimensions and range of each dimension is written prior to writing the
array values. All binary data values are written to the file in little-endian format.
See Also: Get, Open.
Example
222
Note: When a writing string (or a dynamic array) to a Binary mode file the string
length (or array dimension) information is not written. Only the string data or array
elements are written.
Sub Main
Dim V As Variant
Open "SAVE_V.DAT" For Binary Access Write As #1
Put #1, , V
Close #1
End Sub
QBColor Function
Syntax
QBColor(num)
Group
Miscellaneous
Description
Return the appropriate color defined by Quick Basic.
num color
0 black
1 blue
2 green
3 cyan
4 red
5 magenta
6 yellow
7 white
8 gray

9 light blue
10 light green
11 light cyan
12 light red
13 light magenta
14 light yellow
15 bright white
See Also: RGB( ).
Example
Sub Main
Debug.Print Hex(QBColor(1)) '"800000"
Debug.Print Hex(QBColor(7)) '"C0C0C0"
Debug.Print Hex(QBColor(8)) '"808080"
Debug.Print Hex(QBColor(9)) '"FF0000"
Debug.Print Hex(QBColor(10)) '"FF00"
Debug.Print Hex(QBColor(12)) '"FF"
Debug.Print Hex(QBColor(15)) '"FFFFFF"
End Sub
Randomize Instruction
Syntax
Randomize [Seed]
Group
Math
Description
Randomize the random number generator.
Parameter Description
Seed This numeric value sets the initial seed for the random number generator. If this
value is omitted then the current time is used as the seed.
See Also: Rnd( ).
Example
Sub Main
Randomize
Debug.Print Rnd ' 0.??????????????
End Sub
ReDim Instruction
Syntax
223

ReDim [Preserve] name[type][([dim[, ...]])] [As type][, ...]
-or-
ReDim [Preserve] usertypevar.elem[type][([dim[, ...]])] [As type][, ...]
Group
Declaration
Description
Redimension a dynamic arrayvar or user defined type array element. Use Preserve to keep the array values.
Otherwise, the array values will all be reset. When using preserve only the last index of the array may change, but
the number of indexes may not. (A one-dimensional array can't be redimensioned as a two-dimensional array.)
See Also: Dim, Option Base, Private, Public, Static.
Example
Sub Main
Dim X()
ReDim X(3)
Debug.Print UBound(X) ' 3
ReDim X(200)
Debug.Print UBound(X) ' 200
End Sub
Reference Comment
Syntax
'#Reference {uuid}#vermajor.verminor#lcid#[path[#name]]
Description
The Reference comment indicates that the current macro/module references the type library identified. Reference
comment lines must be the first lines in the macro/module (following the global Attributes). Reference comments
are in reverse priority (from lowest to highest). The IDE does not display the reference comments.
Parameter Description
uuid Type library's universally unique identifier.
vermajor Type library's major version number.
verminor Type library's minor version number.
lcid Type library's locale identifier.
path Type library's path.
name Type library's name.
Example
'#Reference {00025E01-0000-0000-C000-000000000046}#4.0#0#C:\PROGRAM FILES\COMMON
FILES\MICROSOFT SHARED\DAO\DAO350.DLL#Microsoft DAO 3.5 Object Library
224

Rem Instruction
Syntax
Rem ...
-or-
'...
Group
Miscellaneous
Description
Both forms are comments. The Rem form is an instruction. The ' form can be used at the end of any line. All text
from either ' or Rem to the end of the line is part of the comment. That text is not executed.
Example
Sub Main
Debug.Print "Hello" ' prints to the output window
Rem the macro terminates at Main's End Sub
End Sub
Replace$ Function
Syntax
Replace[$](S$, Pat$, Rep$, [Index], [Count])
Group
String
Description
Replace Pat$ with Rep$ in S$.
Parameter Description
S$ This string value is searched. Replacements are made in the string returned by
Replace.
Pat$ This string value is the pattern to look for.
Rep$ This string value is the replacement.
Index This numeric value is the starting index in S$. Replace(S,Pat,Rep,N) is equivalent to
Replace(Mid(S,N),Pat,Rep). If this is omitted use 1.
Count This numeric value is the maximum number of replacements that will be done. If this
is omitted use -1 (which means replace all occurrences).
See Also: InStr( ), InStrRev( ), Left$( ), Len( ), Mid$( ), Right$( ).
Example
Sub Main
Debug.Print Replace$("abcabc","b","B") '"aBcaBc"
Debug.Print Replace$("abcabc","b","B",,1) '"aBcabc"
Debug.Print Replace$("abcabc","b","B",3) '"caBc"
225

Debug.Print Replace$("abcabc","b","B",9) '""
End Sub
Reset Instruction
Syntax
Reset
Group
File
Description
Close all open streams for the current macro/module.
See Also: Close, Open.
Example
Sub Main
' read the first line of XXX and print it
Open "XXX" For Input As #1
Line Input #1,L$
Debug.Print L$
Reset
End Sub
Resume Instruction
Syntax
Resume label
-or-
Resume Next
Group
Error Handling
Description
Form 1: Resume execution at label.
Form 2: Resume execution at the next statement.
Once an error has occurred, the error handler can use Resume to continue execution. The error handler must use
Resume or Exit at the end.
Note: This instruction clears the Err and sets Error$ to null.
226

Example
Sub Main
On Error GoTo X
Err.Raise 1
Debug.Print "RESUMING"
Exit Sub
X: Debug.Print "Err=";Err
Resume Next
End Sub
RGB Function
Syntax
RGB(red, green, blue)
Group
Miscellaneous
Description
Return a color.
See Also: QBColor( ).
Example
Sub Main
Debug.Print Hex(RGB(255,0,0)) '"FF0000"
End Sub
Right$ Function
Syntax
Right[$](S$, Len)
Group
String
Description
Return the last Len chars of S$.
Note: A similar function, RightB, returns the last Len bytes.
Parameter Description
S$ Return the right portion of this string value. If this value is Null then Null is returned.
227

Len Return this many chars. If S$ is shorter than that then just return S$.
See Also: InStr( ), InStrRev( ), Left$( ), Len( ), Mid$( ), Replace$( ).
Example
Sub Main
Debug.Print Right$("Hello",3) '"llo"
End Sub
Right$ Function
Syntax
Right[$](S$, Len)
Group
String
Description
Return the last Len chars of S$.
Note: A similar function, RightB, returns the last Len bytes.
Parameter Description
S$ Return the right portion of this string value. If this value is Null then Null is returned.
Len Return this many chars. If S$ is shorter than that then just return S$.
See Also: InStr( ), InStrRev( ), Left$( ), Len( ), Mid$( ), Replace$( ).
Example
Sub Main
Debug.Print Right$("Hello",3) '"llo"
End Sub
RmDir Instruction
Syntax
RmDir Name$
Group
File
Description
Remove directory Name$.
Parameter Description
Name$ This string value is the path and name of the directory. A path relative to the current
228

See Also: MkDir.
Example
Sub Main
RmDir "C:\WWTEMP"
End Sub
Rnd Function
Syntax
Rnd([Num])
Group
Math
Description
229
directory can be used.
Return a random number greater than or equal to zero and less than one.
Parameter Description
Num See table below.
Num Description
0 Return the next random number in the sequence.
0 Return the most recently generated number.
omitted Return the next random number in the sequence.
See Also: Randomize.
Example
Sub Main
Debug.Print Rnd() ' 0.??????????????
End Sub
Round Function
Syntax
Round([Num][, Places])
Group
Math
Description
Return the number rounded to the specified number of decimal places.

Parameter Description
Num Round this numeric value. If this value is Null then Null is returned.
Places Round to this number of decimal places. If this is omitted then round to the nearest
integer value.
Example
Sub Main
Debug.Print Round(.5) ' 0
Debug.Print Round(.500001) ' 1
Debug.Print Round(1.499999) ' 1
Debug.Print Round(1.5) ' 2
Debug.Print Round(11.11) ' 11
Debug.Print Round(11.11,1) ' 11.1
End Sub
RSet Instruction
Syntax
RSet strvar = str
Group
Assignment
Description
Assign the value of str to strvar. Shorten str by removing trailing chars (or extend with leading blanks). The
previous length strvar is maintained.
See Also: LSet.
Example
Sub Main
S$ = "123"
RSet S$ = "A"
Debug.Print ".";S$;"." '". A."
End Sub
RTrim$ Function
Syntax
RTrim[$](S$)
Group
String
230

Description
Return the string with S$'s trailing spaces removed.
Parameter Description
S$ Copy this string without the trailing spaces. If this value is Null then Null is returned.
See Also: LTrim$( ), Trim$( ).
Example
Sub Main
Debug.Print ".";RTrim$(" x ");"." '". x."
End Sub
SaveSetting Instruction
Syntax
SaveSetting AppName$, Section$, Key$, Setting
Group
Settings
Description
Save the Setting for Key in Section in project AppName. Win16 and Win32s store settings in a .ini file named
AppName. Win32 stores settings in the registration database.
Parameter Description
AppName$ This string value is the name of the project which has this Section and Key.
Section$ This string value is the name of the section of the project settings.
Key$ This string value is the name of the key in the section of the project settings.
Setting Set the key to this value. (The value is stored as a string.)
Example
Sub Main
SaveSetting "MyApp","Font","Size",10
End Sub
Second Function
Syntax
Second(dateexpr)
Group
Time/Date
Description
231

Return the second of the minute (0 to 59).
Parameter Description
dateexpr Return the second of the minute for this date value. If this value is Null then Null is
returned.
See Also: Hour( ), Minute( ), Time( ).
Example
Sub Main
Debug.Print Second(#12:00:01 AM#) ' 1
End Sub
Seek Function
Syntax
Seek(StreamNum)
Group
File
Description
Return StreamNum current position. For Random mode files this is the record number. The first record is 1.
Otherwise, it is the byte position. The first byte is 1.
Parameter Description
StreamNum Streams 1 through 255 are private to each macro. Streams 256 through 511 are
shared by all macros.
See Also: Seek.
Example
Sub Main
Open "XXX" For Input As #1
Debug.Print Seek(1) ' 1
Line Input #1,L$
Debug.Print Seek(1)
Close #1
End Sub
Seek Instruction
Syntax
Seek [#]StreamNum, Count
Group
File
232

Description
Position StreamNum for input Count.
Parameter Description
StreamNum Streams 1 through 255 are private to each macro. Streams 256 through 511 are
shared by all macros.
Count For Random mode files this is the record number. The first record is 1. Otherwise, it
is the byte position. The first byte is 1.
See Also: Seek( ).
Example
Sub Main
Open "XXX" For Input As #1
Line Input #1,L$
Seek #1,1 ' rewind to start of file
Input #1,A
Close #1
Debug.Print A
End Sub
Select Case Statement
Syntax
Select Case expr
[Case caseexpr[, ...]
statements]...
[Case Else
statements]
End Select
Group
Flow Control
Description
Select the appropriate case by comparing the expr with each of the caseexprs. Select the Case Else part if no
caseexpr matches. (If the Case Else is omitted then skip the entire Select...End Select block.)
caseexpr Description
expr Execute if equal.
Is < expr Execute if less than.
Is expr Execute if greater than.
Is >= expr Execute if greater than or equal to.
Is expr Execute if not equal to.
expr1 To expr2 Execute if greater than or equal to expr1 and less than or equal to expr2.
See Also: If, Choose( ), IIf( ).
Example
Sub Main
S = InputBox("Enter hello, goodbye, dinner or sleep:")
233

Select Case UCase(S)
Case "HELLO"
Debug.Print "come in"
Case "GOODBYE"
Debug.Print "see you later"
Case "DINNER"
Debug.Print "Please come in."
Debug.Print "Dinner will be ready soon."
Case "SLEEP"
Debug.Print "Sorry."
Debug.Print "We are full for the night"
Case Else
Debug.Print "What?"
End Select
End Sub
Select Case Statement
Syntax
Select Case expr
[Case caseexpr[, ...]
statements]...
[Case Else
statements]
End Select
Group
Flow Control
Description
Select the appropriate case by comparing the expr with each of the caseexprs. Select the Case Else part if no
caseexpr matches. (If the Case Else is omitted then skip the entire Select...End Select block.)
caseexpr Description
expr Execute if equal.
Is < expr Execute if less than.
Is expr Execute if greater than.
Is >= expr Execute if greater than or equal to.
Is expr Execute if not equal to.
expr1 To expr2 Execute if greater than or equal to expr1 and less than or equal to expr2.
See Also: If, Choose( ), IIf( ).
Example
Sub Main
S = InputBox("Enter hello, goodbye, dinner or sleep:")
Select Case UCase(S)
Case "HELLO"
Debug.Print "come in"
Case "GOODBYE"
Debug.Print "see you later"
234

Case "DINNER"
Debug.Print "Please come in."
Debug.Print "Dinner will be ready soon."
Case "SLEEP"
Debug.Print "Sorry."
Debug.Print "We are full for the night"
Case Else
Debug.Print "What?"
End Select
End Sub
SendKeys Instruction
Syntax
SendKeys Keys$[, Wait]
Group
Miscellaneous
Description
Send Keys$ to Windows.
Parameter Description
Keys$ Send the keys in this string value to Windows. (Refer to table below.)
Wait If this is not zero then the keys are sent before executing the next instruction. If this
is omitted or zero then the keys are sent during the following instructions.
Key Description
+ Shift modifier key: the following key is a shifted key
^ Ctrl modifier key: the following key is a control key
% Alt modifier key: the following key is an alt key
(keys) Modifiers apply to all keys
~ Send Enter key
k Send k Key (k is any single char)
K Send Shift k Key (K is any capital letter)
{special n} special key (n is an optional repeat count)
{mouse x,y} mouse key (x,y is an optional screen position)
{k} Send k Key (any single char)
{K} Send Shift k Key (any single char)
{Cancel} Send Break Key
{Esc} Send Escape Key
{Escape} Send Escape Key
{Enter} Send Enter Key
{Menu} Send Menu Key (Alt)
{Help} Send Help Key (?)
{Prtsc} Send Print Screen Key
{Print} Send
{Execute} Send ?
{Tab} Send
{Pause} Send Pause Key
{Tab} Send Tab Key
{BS} Send Back Space Key
{BkSp} Send Back Space Key
235

{BackSpace} Send Back Space Key
{Del} Send Delete Key
{Delete} Send Delete Key
{Ins} Send Insert Key
{Insert} Send Insert Key
{Left} Send Left Arrow Key
{Right} Send Right Arrow Key
{Up} Send Up Arrow Key
{Down} Send Down Arrow Key
{PgUp} Send Page Up Key
{PgDn} Send Page Down Key
{Home} Send Home Key
{End} Send End Key
{Select} Send ?
{Clear} Send Num Pad 5 Key
{Pad0..9} Send Num Pad 0-9 Keys
{Pad*} Send Num Pad * Key
{Pad+} Send Pad + Key
{PadEnter} Send Num Pad Enter
{Pad.} Send Num Pad . Key
{Pad-} Send Num Pad - Key
{Pad/} Send Num Pad / Key
{F1..24} Send F1 to F24 Keys
Mouse
Mouse movement and button clicks:
• {Move x,y} - move the mouse to (x,y)
• {ClickLeft x,y} - move the mouse to (x,y) and click the left button. (This is the same as {DownLeft
x,y}{UpLeft}.)
• {DoubleClickLeft x,y} - move the mouse to (x,y) and click the left button. (This is NOT the same as {ClickLeft
x,y}{ClickLeft}.)
• {DownLeft x,y} - move the mouse to (x,y) and push the left button down.
• {UpLeft x,y} - move the mouse to (x,y) and release the left button.
• similarly named keys for the middle and right mouse buttons.
The x,y values are screen pixel location (0,0) is in the upper-right. In all cases the x,y is optional. If omitted the
previous mouse position is used.
See Also: AppActivate, KeyName, Shell( ).
Example
Sub Main
SendKeys "%S" ' send Alt-S (Search)
SendKeys "GoTo~~" ' send G o T o {Enter} {Enter}
End Sub
Note
In general, SendKeys cannot be used with characters higher than ASCII 127. Use SendDragonKeys instead.
SendDragonKeys supports some characters that SendKeys does not support. For a table listing the names of
nonprinting keys and the codes to use in SendDragonKeys see the topic: Key names for SendDragonKeys.
236

Set Instruction
Syntax
Set objvar = objexpr
-or-
Set objvar = New objtype
Group
Assignment
Description
Form 1: Set objvar's object reference to the object reference of objexpr.
Form 2: Set objvar's object reference to the a new instance of objtype.
The Set instruction is how object references are assigned.
Example
Sub Main
Dim App As Object
Set App = CreateObject("WinWrap.CppDemoApplication")
App.Move 20,30 ' move icon to 20,30
Set App = Nothing
App.Quit ' run-time error (no object)
End Sub
SetAttr Instruction
Syntax
SetAttr Name$, Attrib
Group
File
Description
Set the attributes for file Name$. If the file does not exist then a run-time error occurs.
Parameter Description
Name$ This string value is the path and name of the file. A path relative to the current
directory can be used.
Attrib Set the file's attributes to this numeric value.
Example
Sub Main
Attrib = GetAttr("XXX")
SetAttr "XXX",1 ' readonly
Debug.Print GetAttr("XXX") ' 1
237

SetAttr "XXX",Attrib
End Sub
Sgn Function
Syntax
Sgn(Num)
Group
Math
Description
Return the sign.
Parameter Description
Num Return the sign of this numeric value. Return -1 for negative. Return 0 for zero.
Return 1 for positive.
Example
Sub Main
Debug.Print Sgn(9) ' 1
Debug.Print Sgn(0) ' 0
Debug.Print Sgn(-9) '-1
End Sub
Shell Function
Syntax
Shell(Name$[, WindowType])
Group
Miscellaneous
Description
Execute program Name$. This is the same as using File|Run from the Program Manager. This instruction can
run .COM, .EXE, .BAT and .PIF files. If successful, return the task ID.
Parameter Description
Name$ This string value is the path and name of the program to run. Command line
arguments follow the program name. (A long file name containing a space must be
surrounded by literal double quotes.)
WindowType This controls how the application's main window is shown. See the table below.
WindowType Value Effect
vbHide 0 Hide Window
vbNormalFocus 1, 5, 9 Normal Window
238

vbMinimizedFocus 2 Minimized Window (default)
vbMaximizedFocus 3 Maximized Window
vbNormalNoFocus 4, 8 Normal Deactivated Window
vbMinimizedNoFocus 6, 7 Minimized Deactivated Window
See Also: AppActivate, SendKeys.
Example
Sub Main
X = Shell("Calc") ' run the calc program
AppActivate X
SendKeys "% R" ' restore calc's main window
SendKeys "30*2{+}10=",1 '70
End Sub
ShowPopupMenu Function
Syntax
ShowPopupMenu(StrArray$( )[, PopupStyle][, XPos, YPos])
Group
User Input
Description
Show a popup menu and return the number of the item selected. The item number is the index of the StrArray
selected minus LBound(StrArray). The value -1 is returned in no menu item is selected.
Parameter Description
StrArray$( ) This one-dimensional array of strings establishes the list of choices. All the
non-null elements of the array are used.
PopupMenuStyle This controls how the popup menu is aligned. Any combination of styles may
used together. See the table below.
XPos When the menu is put up the alignment will be at this window position. If this is
omitted then the current mouse position is used.
YPos When the menu is put up the alignment will be at this window position. If this is
omitted then the current mouse position is used.
PopupStyle Value Effect
vbPopupLeftTopAlign 0 Align menu left edge at XPos and top at YPos. (default)
vbPopupUseLeftButton 1 User can select menu choices with the left mouse button only.
vbPopupUseRightButton 2 User can select menu choices with the left or right mouse
button.
vbPopupRightAlign 4 Align menu with right edge at the XPos.
vbPopupCenterAlign 8 Align menu center at the XPos.
vbPopupVCenterAlign 16 Align menu center at the YPos.
vbPopupBottomAlign 32 Align menu bottom at the YPos.
Example
Sub Main
Dim Items(0 To 2) As String
Items(0) = "Item &1"
239

Items(1) = "Item &2"
Items(2) = "Item &3"
X = ShowPopupMenu(Items) ' show popup menu
Debug.Print X ' item selected
End Sub
Sin Function
Syntax
Sin(Num)
Group
Math
Description
Return the sine.
Parameter Description
Num Return the sine of this numeric value. This is the number of radians. There are 2*Pi
radians in a full circle.
Example
Sub Main
Debug.Print Sin(1) ' 0.8414709848079
End Sub
Space$ Function
Syntax
Space[$](Len)
Group
String
Description
Return the string Len spaces long.
Parameter Description
Len Create a string this many spaces long.
See Also: String$( ).
Example
Sub Main
Debug.Print ".";Space$(3);"." '". ."
240

End Sub
Sqr Function
Syntax
Sqr(Num)
Group
Math
Description
Return the square root.
Parameter Description
Num Return the square root of this numeric value.
Example
Sub Main
Debug.Print Sqr(9) ' 3
End Sub
Statement definition
Zero or more instructions. A statement is at least one line long. Begin Dialog, Do, For, If (multiline), Select Case,
While and With statements are always more than one line long. A single line statement continues on the next line
if it ends a line with a space and an underscore ' _'.
S$ = "This long string is easier to read, " + _
"if it is broken across two lines."
Debug.Print S$
Static Definition
Syntax
Static name[type][([dim[, ...]])][As [New] type][, ...]
Group
Declaration
Description
A static variable retains it value between procedure calls. Dimension var array(s) using the dims to establish the
minimum and maximum index value for each dimension. If the dims are omitted then a scalar (single value)
241

variable is defined. A dynamic array is declared using ( ) without any dims. It must be ReDimensioned before it can
be used.
See Also: Dim, Option Base, Private, Public, ReDim.
Example
Sub A
Static X
Debug.Print X
X = "Hello"
End Sub
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
A
A ' prints "Hello"
End Sub
Stop Instruction
Syntax
Stop
Group
Flow Control
Description
Pause execution. If execution is resumed then it starts at the next instruction. Use End to terminate the macro
completely.
Example
Sub Main
For I = 1 To 10
Debug.Print I
If I = 3 Then Stop
Next I
End Sub
Str definition
An expression that returns a string result.
"Hello"
S$
S$ + " Goodbye"
S$ & " Goodbye"
Mid$(S$,2)
242

Str$ Function
Syntax
Str[$](Num)
Group
String
Description
Return the string representation of Num.
Parameter Description
Len Return the string representation of this numeric value. Positive values begin with a
blank. Negative values begin with a dash '-'.
See Also: CStr( ), Hex$( ), Oct$( ), Val( ).
Example
Sub Main
Debug.Print Str$(9*9) ' 81
End Sub
Strarray definition
A variable that holds an array of string values. The name of a string variable may be followed by a $.
StrConv$ Function
Syntax
StrConv[$](Str,Conv)
Group
String
Description
Convert the string.
Parameter Description
Str Convert this string value. If this value is Null then Null is returned.
Conv This numeric value indicates the type of conversion. See conversion table below.
Conv Value Effect
243

vbUpperCase 1 Convert to upper case.
vbLowerCase 2 Convert to lower case.
vbProperCase 3 Convert to proper case. (Not supported.)
vbWide 4 Convert to wide. (Only supported for Win32 in eastern locales.)
vbNarrow 8 Convert to narrow. (Only supported for Win32 in eastern locales.)
vbKatakana 16 Convert to Katakana. (Only supported for Win32 in Japanese locales.)
vbHiragana 32 Convert to Hiragana. (Only supported for Win32 in Japanese locales.)
vbUnicode 64 Convert to Unicode. (Only supported for Win32.)
vbFromUnicode 128 Convert from Unicode. (Only supported for Win32.)
See Also: LCase$( ), StrComp( ), UCase$( ).
Example
Sub Main
Dim B(1 To 3) As Byte
B(1) = 65
B(2) = 66
B(3) = 67
Debug.Print StrConv$(B,vbUnicode) '"ABC"
End Sub
String$ Function
Syntax
String[$](Len, Char|$)
Group
String
Description
Return the string Len long filled with Char or the first char of Char$.
Parameter Description
Len Create a string this many chars long.
Char|$ Fill the string with this char value. If this is a numeric value then use the ASCII char
equivalent. If this is a string value use the first char of that string. If this value is Null
then Null is returned.
See Also: Space$( ).
Example
Sub Main
Debug.Print String$(4,65) '"AAAA"
Debug.Print String$(4,"ABC") '"AAAA"
End Sub
244

StrReverse$ Function
Syntax
StrReverse[$](S)
Group
String
Description
Return the string with the characters in reverse order.
Parameter Description
S Return this string with the characters in reverse order.
Example
Sub Main
Debug.Print StrReverse$("ABC") 'CBA
End Sub
Strvar definition
A variable that holds one string value. The name of a string variable may be followed by a $.
FirstName$
Sub Definition
Syntax
[ | Private | Public | Friend ] _
Sub name[([param[, ...]])]
statements
End Sub
Group
Declaration
Description
User defined subroutine. The subroutine defines a set of statements to be executed when it is called. The values of
the calling arglist are assigned to the params. A subroutine does not return a result.
Sub defaults to Public if Private, Public or Friend are not is specified.
See Also: Declare, Function, Property.
Example
245

Sub IdentityArray(A()) ' A() is an array of numbers
For I = LBound(A) To UBound(A)
A(I) = I
Next I
End Sub
Sub CalcArray(A(),B,C) ' A() is an array of numbers
For I = LBound(A) To UBound(A)
A(I) = A(I)*B+C
Next I
End Sub
Sub ShowArray(A()) ' A() is an array of numbers
For I = LBound(A) To UBound(A)
Debug.Print "(";I;")=";A(I)
Next I
End Sub
Sub Main
Dim X(1 To 4)
IdentityArray X() ' X(1)=1, X(2)=2, X(3)=3, X(4)=4
CalcArray X(),2,3 ' X(1)=5, X(2)=7, X(3)=9, X(4)=11
ShowArray X() ' print X(1), X(2), X(3), X(4)
End Sub
Tan Function
Syntax
Tan(Num)
Group
Math
Description
Return the tangent.
Parameter Description
Num Return the tangent of this numeric value.
Example
Sub Main
Debug.Print Tan(1) ' 1.5574077246549
End Sub
Text Dialog Item Definition
Syntax
246

Text X, Y, DX, DY, Title$[, .Field][, Options]
Group
User Dialog
Description
Define a text item.
Parameter Description
X This number value is the distance from the left edge of the dialog box. It is measured
in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is measured
in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
the dialog's font.
Title$ The value of this string is the title of the text control.
Field This identifier is the name of the field. The dialogfunc receives this name as string. If
this identifer is omitted then the first two words of the title are used.
Options This numeric value controls the alignment of the text. Choose one value from
following table. (If this numeric value omitted then zero is used.)
Option Description
0 Text is left aligned.
1 Text is right aligned.
2 Text is centered.
See Also: Begin Dialog, Dim As UserDialog.
Example
Sub Main
Begin Dialog UserDialog 200,120
Text 10,10,180,15,"Please push the OK button"
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
Dialog dlg ' show dialog (wait for ok)
End Sub
TextBox Dialog Item Definition
Syntax
TextBox X, Y, DX, DY, .Field$[, Options]
Group
User Dialog
Description
Define a textbox item.
247

Parameter Description
X This number value is the distance from the left edge of the dialog box. It is
measured in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is
measured in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height
for the dialog's font.
Field The value of the text box is accessed via this field.
Options This numeric value controls the type of text box. Choose one value from following
table. (If this numeric value omitted then zero is used.)
Option Description
0 Text box allows a single line of text to be entered.
1 Text box allows multiple lines of text can be entered.
-1 Text box allows a hidden password can be entered.
See Also: Begin Dialog, Dim As UserDialog.
Example
Sub Main
Begin Dialog UserDialog 200,120
Text 10,10,180,15,"Please push the OK button"
TextBox 10,25,180,20,.Text$
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
dlg.Text$ = "none"
Dialog dlg ' show dialog (wait for ok)
Debug.Print dlg.Text$
End Sub
Text Dialog Item Definition
Syntax
Text X, Y, DX, DY, Title$[, .Field][, Options]
Group
User Dialog
Description
Define a text item.
Parameter Description
X This number value is the distance from the left edge of the dialog box. It is measured
in 1/8ths of the average character width for the dialog's font.
Y This number value is the distance from the top edge of the dialog box. It is measured
in 1/12ths of the character height for the dialog's font.
DX This number value is the width. It is measured in 1/8ths of the average character
width for the dialog's font.
DY This number value is the height. It is measured in 1/12ths of the character height for
248

the dialog's font.
Title$ The value of this string is the title of the text control.
Field This identifier is the name of the field. The dialogfunc receives this name as string. If
this identifer is omitted then the first two words of the title are used.
Options This numeric value controls the alignment of the text. Choose one value from
following table. (If this numeric value omitted then zero is used.)
Option Description
0 Text is left aligned.
1 Text is right aligned.
2 Text is centered.
See Also: Begin Dialog, Dim As UserDialog.
Example
Sub Main
Begin Dialog UserDialog 200,120
Text 10,10,180,15,"Please push the OK button"
OKButton 80,90,40,20
End Dialog
Dim dlg As UserDialog
Dialog dlg ' show dialog (wait for ok)
End Sub
Time Function
Syntax
Time[$]
Group
Time/Date
Description
Return the current time as a date value.
See Also: Date, Now, Timer.
Example
Sub Main
Debug.Print Time ' example: 09:45:00 am
End Sub
Timer Function
Syntax
Timer
249

Group
Time/Date
Description
Return the number of seconds past midnight. (This is a real number, accurate to about 1/18th of a second.)
See Also: Date, Now, Time.
Example
Sub Main
Debug.Print Timer ' example: 45188.13
End Sub
TimeSerial Function
Syntax
TimeSerial(Hour, Minute, Second)
Group
Time/Date
Description
Return a date value.
Parameter Description
Hour This numeric value is the hour (0 to 23).
Minute This numeric value is the minute (0 to 59).
Second This numeric value is the second (0 to 59).
See Also: DateSerial, DateValue, TimeValue.
Example
Sub Main
Debug.Print TimeSerial(13,30,0) '1:30:00 PM
End Sub
TimeValue Function
Syntax
TimeValue(Date$)
Group
Time/Date
250

Description
Return the time part of date encoded as a string value.
Parameter Description
Date$ Convert this string value to the time part of date it represents.
See Also: DateSerial, DateValue, TimeSerial.
Example
Sub Main
Debug.Print TimeValue("1/1/2000 12:00:01 AM")
'12:00:01 AM
End Sub
Trim$ Function
Syntax
Trim[$](S$)
Group
String
Description
Return the string with S$'s leading and trailing spaces removed.
Parameter Description
S$ Copy this string without the leading or trailing spaces. If this value is Null then Null is
returned.
See Also: LTrim$( ), RTrim$( ).
Example
Sub Main
Debug.Print ".";Trim$(" x ");"." '".x."
End Sub
Type definition
Variable and parameter types, as well as, function and property results may be specified using a type character as
the last character in their name.
Type char As Type
% Integer
? PortInt
& Long
! Single
# Double
@ Currency
$ String
251

Type Definition
Syntax
[ | Private | Public ] _
Type name
elem [([dim[, ...]])] As [New] type
[...]
End Type
Group
Declaration
Description
Define a new usertype. Each elem defines an element of the type for storing data. As [New] type defines the type
of data that can be stored. A user defined type variable has a value for each elem. Use .elem to access individual
element values.
Type defaults to Public if neither Private or Public is specified.
Example
Type Employee
FirstName As String
LastName As String
Title As String
Salary As Double
End Type
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
Dim e As Employee
e.FirstName = "John"
e.LastName = "Doe"
e.Title = "President"
e.Salary = 100000
Debug.Print e.FirstName '"John"
Debug.Print e.LastName '"Doe"
Debug.Print e.Title '"President"
Debug.Print e.Salary ' 100000
End Sub
TypeName Function
Syntax
TypeName[$](var)
252

Group
Variable Info
Description
Return a string indicating the type of value stored in var.
Parameter Description
var Return a string indicating the type of value stored in this variable.
Result Description
Empty Variant variable is empty. It has never been assigned a value.
Null Variant variable is null.
Integer Variable contains an integer value.
Long Variable contains a long value.
Single Variable contains a single value.
Double Variable contains a double value.
Currency Variable contains a currency value.
Date Variable contains a date value.
String Variable contains a string value.
Object Variable contains an object reference that is not Nothing. (An object may return a type
name specific to that type of object.)
Nothing Variable contains an object reference that is Nothing.
Error Variable contains a error code value.
Boolean Variable contains a boolean value.
Variant Variable contains a variant value. (Only used for arrays of variants.)
Unknown Variable contains a non-ActiveX Automation object reference.
Byte Variable contains a byte value.
( ) Variable contains an array value. The TypeName of the element followed by ( ).
See Also: VarType.
Example
Sub Main
Dim X As Variant
Debug.Print TypeName(X) '"Empty"
X = 1
Debug.Print TypeName(X) '"Integer"
X = 100000
Debug.Print TypeName(X) '"Long"
X = 1.1
Debug.Print TypeName(X) '"Double"
X = "A"
Debug.Print TypeName(X) '"String"
Set X = CreateObject("Word.Basic")
Debug.Print TypeName(X) '"Object"
X = Array(0,1,2)
Debug.Print TypeName(X) '"Variant()"
End Sub
UBound Function
Syntax
UBound(arrayvar[, dimension])
253

Group
Variable Info
Description
Return the highest index.
Parameter Description
arrayvar Return the highest index for this array variable.
dimension Return the highest index for this dimension of arrayvar. If this is omitted then return
the highest index for the first dimension.
See Also: LBound( ).
Example
Sub Main
Dim A(3,6)
Debug.Print UBound(A) ' 3
Debug.Print UBound(A,1) ' 3
Debug.Print UBound(A,2) ' 6
End Sub
UCase$ Function
Syntax
UCase[$](S$)
Group
String
Description
Return a string from S$ where all the lowercase letters have been uppercased.
Parameter Description
S$ Return the string value of this after all chars have been converted to lowercase. If
this value is Null then Null is returned.
See Also: LCase$( ), StrComp( ), StrConv$( ).
Example
Sub Main
Debug.Print UCase$("Hello") '"HELLO"
End Sub
Unlock Instruction
Syntax
254

Unlock StreamNum
-or-
Unlock StreamNum, RecordNum
-or-
Unlock StreamNum, [start] To end
Group
File
Description
Form 1: Unlock all of StreamNum.
Form 2: Unlock a record (or byte) of StreamNum.
Form 3: Unlock a range of records (or bytes) of StreamNum. If start is omitted then unlock starting at the first
record (or byte).
Note: For sequential files (Input, Output and Append) unlock always affects the entire file.
Parameter Description
StreamNum Streams 1 through 255 are private to each macro. Streams 256 through 511 are
shared by all macros.
RecordNum For Random mode files this is the record number. The first record is 1. Otherwise, it
is the byte position. The first byte is 1.
start First record (or byte) in the range.
end Last record (or byte) in the range.
See Also: Lock, Open.
Example
Sub Main
Dim V As Variant
Open "SAVE_V.DAT" For Binary As #1
Lock #1
Get #1, 1, V
V = "Hello"
Put #1, 1, V
Unlock #1
Close #1
End Sub
Userenum definition
User defined enums are defined with Enum.
Usertypevar definition
A user defined type variable holds values for elements of the user defined type. User defined types are defined
using Type.
255

Declare with Dim, Private, Public or Static.
Declare as a parameter of Sub, Function or Property definition.
Uses Comment
Syntax
'#Uses "module" [Only:[Win16|Win32]] ...
-or-
'$Include: "module"
Description
The Uses comment indicates that the current macro/module uses public and friend symbols from the module. The
Only option indicates that the module is only loaded for that Windows platform.
Parameter Description
module Public and Friend symbols from this module are accessible. If the module name is a
relative path then the path is relative to the macro/module containing the Uses
comment. For example, if module "A:\B\C\D.BAS" has this uses comment:
'#Uses "E.BAS"
then it uses "A:\B\C\E.BAS".
See Also: Class Module, Code Module, Object Module.
Example
'Macro A.WWB
'#Uses "B.WWB"
Sub Main
Debug.Print BFunc$("Hello") '"HELLO"
End Sub
'Module B.WWB
Public Function BFunc$(S$)
BFunc$ = UCase(S$)
End Sub
Val Function
Syntax
Val(S$)
Group
String
Description
Return the value of the S$.
Parameter Description
256

S$ Return the numeric value for this string value. A string value begins with &O is an
octal number. A string value begins with &H is a hex number. Otherwise it is decimal
number.
Example
Sub Main
Debug.Print Val("-1000") '-1000
End Sub
Var definition
A variable holds either a string, a numeric value or an array of values depending on its type.
Variantvar definition
A variant variable can hold any type of value (except String*n or usertypevar). or it can hold an array.
VarType Function
Syntax
VarType(var)
Group
Variable Info
Description
Return a number indicating the type of value stored in var.
Parameter Description
var Return a number indicating the type of value stored in this variable.
Result Value Description
vbEmpty 0 Variant variable is empty. It has never been assigned a value.
vbNull 1 Variant variable is null.
vbInteger 2 Variable contains an integer value.
vbLong 3 Variable contains a long value.
vbSingle 4 Variable contains a single value.
vbDouble 5 Variable contains a double value.
vbCurrency 6 Variable contains a currency value.
vbDate 7 Variable contains a date value.
vbString 8 Variable contains a string value.
vbObject 9 Variable contains an object reference.
vbError 10 Variable contains a error code value.
vbBoolean 11 Variable contains a boolean value.
257

vbVariant 12 Variable contains a variant value. (Only used for arrays of variants.)
vbDataObject 13 Variable contains a non-ActiveX Automation object reference.
vbDecimal 14 Variable contains a 96 bit scaled real.
vbByte 17 Variable contains a byte value.
vbUserDefinedType 36 Variable contains a User Defined Type value.
+vbArray 8192 Variable contains an array value. Use VarType( ) And 255 to get the
type of element stored in the array.
See Also: TypeName.
Example
Sub Main
Dim X As Variant
Debug.Print VarType(X) ' 0
X = 1
Debug.Print VarType(X) ' 2
X = 100000
Debug.Print VarType(X) ' 3
X = 1.1
Debug.Print VarType(X) ' 5
X = "A"
Debug.Print VarType(X) ' 8
Set X = CreateObject("Word.Basic")
Debug.Print VarType(X) ' 9
X = Array(0,1,2)
Debug.Print VarType(X) ' 8204 (8192+12)
End Sub
Wait Instruction
Syntax
Wait Delay
Group
Miscellaneous
Description
Wait for Delay seconds.
Examples
Sub Main
Wait 5 ' wait for 5 seconds
End Sub
Sub Main
Wait 0.5 ' wait for ½ second
End Sub
258

Weekday Function
Syntax
Weekday(dateexpr)
Group
Time/Date
Description
Return the weekday.
vbSunday (1) - Sunday
vbMonday (2) - Monday
vbTuesday (3) - Tuesday
vbWednesday (4) - Wednesday
vbThursday (5) - Thursday
vbFriday (6) - Friday
vbSaturday (7) - Saturday
Parameter Description
dateexpr Return the weekday for this date value. If this value is Null then Null is returned.
See Also: Date( ), Day( ), Month( ), WeekdayName( ), Year( ).
Example
Sub Main
Debug.Print Weekday(#1/1/1900#) ' 2
Debug.Print Weekday(#1/1/2000#) ' 7
End Sub
WeekdayName Function
Syntax
WeekdayName(NumZ{day}[, CondZ{abbrev}])
Group
Time/Date
Description
Return the localized name of the weekday.
Parameter Description
day Return the localized name of this weekday. (1-7)
abbrev If this conditional value is True then return the abbreviated form of the weekday
name.
See Also: Weekday( ).
259

Example
Sub Main
Debug.Print WeekdayName(1) 'Sunday
Debug.Print WeekdayName(Weekday(Now))
End Sub
While Statement
Syntax
While condexpr
statements
Wend
Group
Flow Control
Description
Execute statements while condexpr is True.
See Also: Do, For, For Each, Exit While.
Example
Sub Main
I = 2
While I < 10
I = I*2
Wend
Debug.Print I ' 16
End Sub
With Statement
Syntax
With objexpr
statements
End With
Group
Object
Description
Method and property references may be abbreviated inside a With block. Use .method or .property to access the
object specified by the With objexpr.
260

Example
Sub Main
Dim App As Object
Set App = CreateObject("WinWrap.CppDemoApplication")
With App
.Move 20,30 ' move icon to 20,30
End With
End Sub
WithEvents Definition
Syntax
[Dim | Private | Public] _
WithEvents name As objtype[, ...]
Group
Declaration
Description
Dimensioning a module level variable WithEvents allows the macro to implement event handling Subs. The
variable's As type must be a type from a referenced type library (or language extension) which implements events.
See Also: Dim, Private, Public.
Example
Dim WithEvents X As Thing
C:\ABCTemp\vbs\Sub_Definition.htm
Sub Main
Set X = New Thing
X.DoIt ' DoIt method raises DoingIt event
End Sub
C:\ABCTemp\vbs\Private_Keyword.htm
Private Sub X_DoingIt
Debug.Print "X.DoingIt event"
End Sub
Write Instruction
Syntax
Write #StreamNum, expr[, ...]
Group
File
261

Description
Write's expr(s) to StreamNum. String values are quoted. Null values are written as #NULL#. Boolean values are
written as #FALSE# or #TRUE#. Date values are written as #date#. Error codes are written as #ERROR number#.
See Also: Input, Line Input, Print.
Example
Sub Main
A = 1
B = 2
C$ = "Hello"
Open "XXX" For Output As #1
Write #1,A,B,C$
Close #1
End Sub
Year Function
Syntax
Year(dateexpr)
Group
Time/Date
Description
Return the year.
Parameter Description
dateexpr Return the year for this date value. If this value is Null then Null is returned.
See Also: Date( ), Day( ), Month( ), Weekday( ).
Example
Sub Main
Debug.Print Year(#1/1/1900#) ' 1900
Debug.Print Year(#1/1/2000#) ' 2000
End Sub
Objects Overview
ActiveX Automation provides access to objects in other applications. Each object supports a particular set of
methods and properties. Each method/property has zero or more parameters. Parameters may be optional, in
which case the parameter can be specified by using name := value.
objexpr.method [expr][, ...] [param := expr][,...]
Call method for objexpr.
objexpr.method[([expr][, ...] [param := expr][,...])]
262

263
Return the value of method for objexpr.
objexpr.property[([expr][, ...] [param := expr][,...])]
Return the value of property for objexpr.
objexpr[([expr][, ...] [param := expr][,...])]
Return the default value for the objexpr.
objexpr.property[([expr][, ...])] = expr
Assign the value of property for objexpr.
objexpr[([expr][, ...])] = expr
Assign the default value for the objexpr.
Set objexpr.property[([expr][, ...])] = objexpr
Set the object reference of property for objexpr.
Note: objexpr!name is shorthand for objexpr.defaultproperty("name"). Use objexpr![name] if name contains any
characters that are not allowed in an identifier.
Format Predefined Date
Description
The following predefined date formats may be used with the Format function. Predefined formats may not be
combined with user defined formats or other predefined formats.
Form Description
General Date Same as user defined date format "c"
Long Date Same as user defined date format "dddddd"
Medium Date Not supported at this time.
Short Date Same as user defined date format "ddddd"
Long Time Same as user defined date format "ttttt"
Medium Time Same as user defined date format "hh:mm AMPM"
Short Time Same as user defined date format "hh:mm"
Format Predefined Number
Description
The following predefined number formats may be used with the Format function. Predefined formats may not be
combined with user defined formats or other predefined formats.
Form Description
General Number Return number as is.
Currency Same as user defined number format "$#,##0.00;($#,##0.00)"
Not locale dependent at this time.
Fixed Same as user defined number format "0.00".
Standard Same as user defined number format "#,##0.00".
Percent Same as user defined number format "0.00%".
Scientific Same as user defined number format "0.00E+00".
Yes/No Return "No" if zero, else return "Yes".
True/False Return "True" if zero, else return "False".

On/Off Return "On" if zero, else return "Off".
Example
Sub Main
Debug.Print Format$(2.145,"Standard") ' 2.15
End Sub
Format User Defined Date
Description
The following date formats may be used with the Format function. Date formats may be combined to create the
user defined date format. User defined date formats may not be combined with other user defined formats or
predefined formats.
Parameter Description
: insert localized time separator
/ insert localized date separator
c insert ddddd ttttt, insert date only if t=0, insert time only if d=0
d insert day number without leading zero
dd insert day number with leading zero
ddd insert abbreviated day name
dddd insert full day name
ddddd insert date according to Short Date format
dddddd insert date according to Long Date format
w insert day of week number
ww insert week of year number
m insert month number without leading zero
insert minute number without leading zero (if follows h or hh)
mm insert month number with leading zero
insert minute number with leading zero (if follows h or hh)
mmm insert abbreviated month name
mmmm insert full month name
q insert quarter number
y insert day of year number
yy insert year number (two digits)
yyyy insert year number (four digits, no leading zeros)
h insert hour number without leading zero
hh insert hour number with leading zero
n insert minute number without leading zero
nn insert minute number with leading zero
s insert second number without leading zero
ss insert second number with leading zero
ttttt insert time according to time format
AM/PM use 12 hour clock and insert AM (hours 0 to 11) and PM (12 to 23)
am/pm use 12 hour clock and insert am (hours 0 to 11) and pm (12 to 23)
A/P use 12 hour clock and insert A (hours 0 to 11) and P (12 to 23)
a/p use 12 hour clock and insert a (hours 0 to 11) and p (12 to 23)
AMPM use 12 hour clock and insert localized AM/PM strings
\c insert character c
"text" insert literal text
264

Format User Defined Number
Description
The following number formats may be used with the Format function. Number formats may be combined to create
the user defined number format. User defined number formats may not be combined with other user defined
formats or predefined formats.
User defined number formats can contain up to four sections separated by ';':
265
form - format for non-negative expr, '-'format for negative expr, empty and null expr return ""
form;negform - negform: format for negative expr
form;negform;zeroform - zeroform: format for zero expr
form;negform;zeroform;nullform - nullform: format for null expr
Parameter Description
# digit, don't include leading/trailing zero digits (all the digits left of decimal point
are returned)
eg. Format(19,"###") returns "19"
eg. Format(19,"#") returns "19"
0 digit, include leading/trailing zero digits
eg. Format(19,"000") returns "019"
eg. Format(19,"0") returns "19"
. decimal, insert localized decimal point
eg. Format(19.9,"###.00") returns "19.90"
eg. Format(19.9,"###.##") returns "19.9"
, thousands, insert localized thousand separator every 3 digits
"xxx," or "xxx,." mean divide expr by 1000 prior to formatting
two adjacent commas ",," means divide expr by 1000 again
eg. Format(1900000,"0,,") returns "2"
eg. Format(1900000,"0,,.0") returns "1.9"
% percent, insert %, multiply expr by 100 prior to formatting
: insert localized time separator
/ insert localized date separator
E+ e+ E- e- use exponential notation, insert E (or e) and the signed exponent
eg. Format(1000,"0.00E+00") returns "1.00E+03"
eg. Format(.001,"0.00E+00") returns "1.00E-03"
- + $ ( ) space insert literal char
eg. Format(10,"$#") returns "$10"
\c insert character c
eg. Format(19,"\####\#") returns "#19#"
"text" insert literal text
eg. Format(19,"""##""###""##""") returns "##19##"
Example
Sub Main
Debug.Print Format$(2.145,"#.00") ' 2.15
End Sub

Format User Defined Text
Description
The following text formats may be used with the Format function. Text formats may be combined to create the user
defined text format. User defined text formats may not be combined with other user defined formats or predefined
formats.
User defined text formats can contain one or two sections separated by ';':
266
form - format for all strings
form;nullform - nullform: format for empty and null strings
Parameter Description
@ char placeholder, insert char or space
& char placeholder, insert char or nothing
< all chars lowercase
> all chars uppercase
! fill placeholder from left-to-right (default is right-to-left)
\c insert character c
"text" insert literal text
Example
Sub Main
Debug.Print Format("123","ab@c") '" ab1c23"
Debug.Print Format("123","!ab@c") '" ab3c"
End Sub
Error List
The following table lists all error codes with the associated error text.
Error Description
10000 Execution interrupted.
10001 Out of memory.
10008 Invalid '#Uses "module" comment.
10009 Invalid '#Uses module dependency.
10010 Macro is already running.
10011 Can't allocate memory to macro/module.
10012 Macro/module has syntax errors.
10013 Macro/module does not exist.
10014 Another macro is paused and can't continue at this time.
10017 No macro is currently active.
10018 Sub/Function does not exist.
10019 Wrong number of parameters.
10021 Can't allocate large array.
10022 Array is not dimensioned.
10023 Array index out of range.
10024 Array lower bound is larger than upper bound.
10025 Array has a different number of indexes.
10030 User dialog has not been defined.
10031 User pressed cancel.
10032 User dialog item id is out of range.
10033 No UserDialog is currently displayed.

10034 Current UserDialog is inaccessible.
10035 Wrong with, don't GoTo into or out of With blocks.
10040 Module could not be loaded.
10041 Function not found in module.
10048 File not opened with read access.
10049 File not opened with write access.
10050 Record length exceeded.
10051 Could not open file.
10052 File is not open.
10053 Attempt to read past end-of-file.
10054 Expecting a stream number in the range 1 to 511.
10055 Input does not match var type.
10056 Expecting a length in the range 1 to 32767.
10057 Stream number is already open.
10058 File opened in the wrong mode for this operation.
10059 Error occurred during file operation.
10060 Expression has an invalid floating point operation.
10061 Divide by zero.
10062 Overflow.
10063 Expression underflowed minimum representation.
10064 Expression loss of precision in representation.
10069 String value is not a valid number.
10071 Resume can only be used in an On Error handler.
10075 Null value can't be used here.
10080 Type mismatch.
10081 Type mismatch for parameter #1.
10082 Type mismatch for parameter #2.
10083 Type mismatch for parameter #3.
10084 Type mismatch for parameter #4.
10085 Type mismatch for parameter #5.
10086 Type mismatch for parameter #6.
10087 Type mismatch for parameter #7.
10088 Type mismatch for parameter #8.
10089 Type mismatch for parameter #9.
10090 OLE Automation error.
10091 OLE Automation: no such property or method.
10092 OLE Automation: server cannot create object.
10093 OLE Automation: server cannot load file.
10094 OLE Automation: Object var is 'Nothing'.
10095 OLE Automation: server could not be found.
10096 OLE Automation: no object currently active.
10097 OLE Automation: wrong number of parameters.
10098 OLE Automation: bad index.
10099 OLE Automation: no such named parameter.
10100 Directory could not be found.
10101 File could not be killed.
10102 Directory could not be created.
10103 File could not be renamed.
10104 Directory could not be removed.
10105 Drive not found.
10106 Source file could not be opened.
10107 Destination file could not be created.
10108 Source file could not be completely read.
10109 Destination file could not be completely written.
10110 Missing close brace '}'.
10111 Invalid key name.
10112 Missing close paren ')'.
10113 Missing close bracket ']'.
10114 Missing comma ','.
267

10115 Missing semi-colon ';'.
10116 SendKeys couldn't install the Windows journal playback hook.
10119 String too long (too many keys).
10120 Window could not be found.
10130 DDE is not available.
10131 Too many simultaneous DDE conversations.
10132 Invalid channel number.
10133 DDE operation did not complete in time.
10134 DDE server died.
10135 DDE operation failed.
10140 Can't access the clipboard.
10150 Window style must be in the range from 1 to 9.
10151 Shell failed.
10160 Declare is not implemented.
10200 Basic is halted due to an unrecoverable error condition.
10201 Basic is busy and can't provide the requested service.
10202 Basic call failed.
10203 Handler property: prototype specification is invalid.
10204 Handler is already in use.
Dragon NaturallySpeaking scripting language extensions quick reference
The Dragon NaturallySpeaking scripting language extensions provide a set of tools for creating Dragon
NaturallySpeaking voice commands. See the topics guidelines for writing scripts and voice command list variables
for more information on using the following:
Dragon NaturallySpeaking scripting language extensions
A
ActiveControlPick ActiveMenuPick AppBringUp AppSwapWith
B
Beep ButtonClick
C
ClearDesktop ControlPick
D
DdeExecute DdePoke DllCall DragToPoint
G
GetState GoToSleep
H
HeardWord HTMLHelp
M
MenuCancel MenuPick MouseGrid MsgBoxConfirm MyCommandsActiveState
P
PlaySound PromptValue Function
268

R
RememberPoint RunScriptFile
S
SendDragonKeys SendSystemKeys SetMicrophone SetMousePosition SetNaturalText SetState
ShellExecute
T
TTSPlayString
W
Wait WaitForWindow WakeUp WinHelp
Reference
Key names Windows shortcut keys Error messages
Guidelines for writing scripts
Scripting commands have two parts: a command name and a set of arguments.
Syntax
CommandName "argument," [, argument]
Rules
Note
269
Command names are case-sensitive.
Arguments in brackets ([ ]) are optional. Do not, however, include the brackets in scripts.
Arguments must appear in the order shown, separated by commas. Spaces are optional.
Enclose literal values (strings), including key sequences, in quotation marks. Do not enclose numeric values
in quotation marks. To send a quotation mark as a literal, enclose it in quotations marks. For example,
type: ""."
Scripts can contain comments (text that is ignored when the script runs). Precede comments with a single
quote (') character.
Scripts cannot be used to activate or disable dictation words and voice commands. Dragon NaturallySpeaking does
not support these distinct modes.
List Variables
A list is a variable part of a voice command name that is replaced by an actual item from a list of pre-defined
variables.
Move Cursor to is an example of a command that contains a list. The list, , can be replaced
by one of a list of predefined values, including Top, Bottom, Beginning, and End.

Adding a list variable to a command name
To add a list variable to a command name, type the list name with angle brackets. For example, type "Send Email
to ", where Employee is the name of a new list.
A command with a list can:
270
• Perform different actions depending on the particular list value that is used. For example, the command
Move Cursor to performs a different action depending on the list value (Top, Bottom,
Beginning, and End) used for .
• Perform the same action but have different spoken forms. For example, the commands "Move to End of
Line" and "Go to End of Line" are forms of the same command. The command includes the list ,
which has two synonymous values: "Move to" and "Go to".
You can use lists that are already defined or create your own. To include a list, type its name (enclosed in angle
brackets) in the Command Name box. In the next step, you will be prompted to enter (or edit) the values for any
lists you include.
Notes
• If the command will perform a different action depending on the list value used, the command can be
implemented only with a script.
• You can access the values of the lists from the script by means of the ListVarX() function, where X is of 1..20
range. Once created, it appears in the Lists Already Defined box.
• To refer to the value of a list variable, use the UtilityProvider object. UtilityProvider.ContextValue(n) returns
a string containing the value of the nth list variable, where the variables are numbered starting with 0. (In
debug mode, this same function returns the name of the variable, though you can change it to debug your
script, see Debugging section below.) UtilityProvider.ContextValueCount returns the number of lists in the
command name. For an example of a script using list variables, see the example custom command called
"sample script ," which is in the user-defined global commands.
Debugging
In debug mode, ListVarX() and UtilityProvider.ContextValue(n) functions return the name of the corresponding
variable. If you want these functions to return more meaningful values while debugging your script, you can use
UtilityProvider.SetContextValue(n,value) function to set the necessary value. And to determine whether your
script is being executed under the debugger you can query UtilityProvider.IsDebugMode boolean property. The
following example will set the first list value to "5" and the second list value to "snakes", but only if the script is
executed under debugger in MyCommands Editor.
Sub Main
If UtilityProvider.IsDebugMode Then
UtilityProvider.SetContextValue(0,"5")
UtilityProvider.SetContextValue(1,"snakes")
End If
MsgBox UtilityProvider.ContextValue(0) + " " + UtilityProvider.ContextValue(1)
End Sub
At runtime when the appropriate command gets recognized and the script is executed the
UtilityProvider.IsDebugMode returns false and the list variables will be set to their appropriate values uttered by
the speaker.
ActiveControlPick
Selects a control in an application that supports Microsoft Active Accessibility. Command buttons, option buttons,

check boxes, group boxes, list boxes, and text fields are examples of controls. Only controls within the currently
active window are available.
Some programs require Active Accessibility to select controls. Most applications do not require Active Accessibility
and some system environments do not support it. Therefore, you should only use the ActiveControlPick command
for applications that require Active Accessibility for control selection. For all other programs, use the ControlPick
command or use the SendKeys command to press the control's accelerator key.
Note
This command works only for legacy Dragon NaturallySpeaking version 5 commands that have been imported into
version 9. It will not work in commands that you create using the MyCommands editor.
Syntax
ActiveControlPick "menuItem"
Argument Description
menuItem Specifies the identifier assigned to the control to be selected. This value is typically
the control's text label, and is case sensitive. Do not use a control's accelerator keys
for this value. If the label includes an ampersand (&) prefixing an access key, do not
include it.
Example
This example presses the OK button in the active window.
Notes
271
ActiveControlPick "OK"
• Generally, toolbar buttons, property sheet tabs, and taskbar buttons cannot be selected using
ActiveControlPick.
• A static text field, such as a text box label, can be selected only if it has an access key (underlined letter).
ActiveMenuPick
Selects the specified menu or menu item, visible in the active window, by executing the menu's access keys. This
command works only in applications that support Microsoft Active Accessibility.
Some programs require Active Accessibility to select menus. Most applications do not require Active Accessibility
and some system environments do not support it. Therefore, you should only use the ActiveMenuPick command for
applications that require Active Accessibility for menu selection. For all other programs, use the MenuPick
command or use the SendKeys command to press an accelerator key.
Note
This command works only for legacy Dragon NaturallySpeaking version 5 commands that have been imported into
version 9. It will not work in commands that you create using the MyCommands editor.
Syntax
ActiveMenuPick "menuItem"

Argument Description
MenuItem The name (as displayed in the menu) of the menu or menu item to open. This value
is case-sensitive.
Example
This example displays the File menu and then selects the Save As menu item.
Notes
272
ActiveMenuPick "File"
ActiveMenuPick "Save As"
• If the menu name contains an ellipsis, do not include it in the menuItem value.
• You may need to insert a Wait command between consecutive MenuPick commands to ensure that the first
menu appears before selecting one of its entries.
• A static text field, such as a text box label, can be selected only if it has an access key (underlined letter).
AppBringUp
Starts the specified application, or reactivates it if it is already running.
Syntax
AppBringUp "appName" [, "cmndLine" [,style[, "dir"]]]
Argument Description
appName A name you assign to the application to be started. This value can be used
again in subsequent AppBringUp instructions to reactivate a running
application. The value has meaning only to Dragon NaturallySpeaking; it has
no effect on the application.
If no other arguments are included, and the appName value has not been used
in a previous AppBringUp or AppSwapWith command, AppBringUp looks for an
executable file named appName in the Dragon NaturallySpeaking Program
folder and in the directores that Windows searches when starting a program.
cmndLine Specifies the application path and any command line switches, such as the
name of a file to open. Long file names are not supported. For program names
it is not necessary to include the extension .EXE.
If the value contains a file name, Dragon NaturallySpeaking starts the
application specified (or, if no application is specified, the program associated
with the file type) and opens the file.
If this argument does not include a full file path, the file must be in the Dragon
NatuallySpeaking Program folder or in a directory that is searched when
Windows starts a program.
style A value indicating the window state in which to open the application. If the
application is already running, this value has no effect.

273
1 (default) Default window size; active
2 Minimized window; active
3 Maximized window; active
4 Default window size; not active
6 Minimized window; not active
dir Specifies the default working directory for the application. The default value is
the directory containing the program's executable file.
Example 1
This example starts or reactivates WordPad, opens the MyApp Readme file in a maximized window.
AppBringUp "Readme", "Notepad C:\Program Files\Myapp\Readme.txt", 3
This second instruction reactivates the specified application (it must be running) and file by using the same
appName value.
AppBringUp "Readme"
Example 2
This example copies text from the active application to the specified application when you say "Copy All to Word"
or "Copy All to WordPad". In this example, the command name is "Copy All to " and the
list consists of the words "Word" and "WordPad".
Note
SendKeys "^a^c"
if _arg1 = "Word" then AppBringUp "WinWord"
if _arg1 = "WordPad" then AppBringUp "WordPad"
SendKeys "^v"
SendSystemKeys "{Alt+Tab}"
Scripting commands from Dragon NaturallySpeaking version 5 that use the Dragon List Variables will only function
when the .dvc file is imported. You cannot create new commands using these old Dragon List Variables.
AppSwapWith
Switches the active application with the specified application. Starts the specified application if it is not already
running.
Syntax
AppSwapWith "appName"
Argument Description
appName A name you assign to the application to switch to. If the specified application is
not running, it is started.
The value has meaning only to Dragon NaturallySpeaking; it has no effect on the
application.

Beep
274
If the appName value has not been used in a previous AppBringUp or
AppSwapWith command and the program is not running, an executable file
named appName must be in the Dragon NaturallySpeaking Program folder or in
a directory that is searched when Windows starts a program.
Generates the Windows default beep sound by calling the Windows API MessageBeep() function. The exact result
of this call depends on the hardware and system software configuration. On some systems with half-duplex sound
systems, you must turn off the microphone before using this command for users to hear the beep.
Syntax
Beep
This command does not have any arguments.
Example
The following script turns off the microphone, plays the beep sound, waits for five seconds to ensure that the sound
finishes playing, and turns the microphone back on
SetMicrophone 0
Beep
Wait 5
SetMicrophone 1
ButtonClick
Generates a single or double click with the specified mouse button.
Syntax
ButtonClick [button[, count]]
Argument Description
button A value indicating which button is to be clicked. To click multiple mouse buttons
simultaneously, add the values for each button to be clicked.
1 (default) left button (button 1)
2 right button (button 2)
4 third (middle) button
count A value indicating the number of clicks.
1 (default) single click
2 double click

Example
This example generates a double-click with the left mouse button.
Note
275
ButtonClick 1,2
Use a series of ButtonClick commands to generate triple- or quadruple-clicks.
ClearDesktop
Minimizes all open applications.
Syntax
ClearDesktop
This command does not have any arguments.
ControlPick
Selects a specified control in an active secondary window. Command buttons, option buttons, check boxes, group
boxes, list boxes, and text fields are examples of controls. Generally, toolbar buttons, property sheet tabs, and
taskbar buttons cannot be selected by using ControlPick.
Syntax
ControlPick "menuItem"
Argument Description
menuItem Specifies the identifier assigned to the control to be selected. This value is
typically the control's text label, and is case sensitive. Do not use a control's
accelerator keys for this value. If the label includes an ampersand (&) prefixing
an access key, do not include it.
Example
This example presses the OK button in the active window.
Notes
ControlPick "OK"
ControlPick does not work for nonstandard controls, such as an option with a bitmapped text label. You may
be able to select a nonstandard control by using SendKeys to send a TAB sequence.
A static text field, such as a text box label, can be selected only if it has an access key (underlined letter).

DdeExecute
Sends a command or series of commands to a dynamic-data exchange (DDE) application.
Syntax
DdeExecute "appName", "topic", "command"[, async]
Argument Description
appName The name of the DDE application receiving the command. The appName value is
usually the name of the application's .EXE file without the file name extension.
The application must be running.
topic The name of a topic recognized by the application. Many DDE applications
recognize a topic named "System", which is always available. Each open
document may also be a separate topic.
command A command or series of commands recognized by the DDE application. Most
applications require that each command received through a DDE channel be
enclosed in square brackets. See Examples. Do not include spaces between
bracketed commands.
async If 0 or omitted, this call is synchronous and waits until the DDE application
acknowledges completion or a timeout occurs. If 1, this call is asynchronous and
returns immediately.
Example 1
This example opens a channel to Microsoft Excel and the System topic, and then sends a command to open
EXPENSES.XLS. The document name must be enclosed in two sets of quotation marks.
276
DdeExecute "Excel", "System", "[OPEN(""Expenses.xls"")]"
Example 2
This example tells Microsoft Word to decrease the font size of selected text.
Notes
DdeExecute "WinWord", "System", "[ShrinkFont]"
Use a DdeExecute instruction instead of SendKeys if you cannot be sure a key sequence always produces the
same result. A key sequence can have different results depending on whether it is received by the
application window or an open dialog box.
Set async to 1 if you are calling a DDE command that does not return immediately. Otherwise, if the DDE
command does not return quickly, DdeExecute fails with a timeout error and Dragon NaturallySpeaking
displays an error message.
DdePoke
Uses an open dynamic-data exchange (DDE) channel to send data to an application.
Syntax

DdePoke "appName", "topic", "item", "value"
Argument Description
appName The name of the DDE application receiving the command. The application must be
running.
topic The name of the topic receiving the command.
item An item within the specified DDE topic.
value A string containing the data to send to the specified item.
Example
This example sends the string "Total: $1,216" to the second row and third column of the Expenses worksheet in
Microsoft Excel.
277
DDEPoke "Excel", "Expenses", "R2C3", "Total: $1,216"
DllCall
Calls a function in an application's dynamic-link library (DLL). There are three forms of this command. The first
does not return a value. The second is a function that returns an integer (LONG/DWORD) value. The third is a
function that returns a string value.
In the first two forms, the DLL function must be a PASCAL function that takes a single LPCSTR (long pointer to a
constant string) argument. In the third form, the DLL function must take three arguments, an LPCSTR, a pointer
to a BYTE buffer, and an integer.
C or C++ DLL functions called by the first form of DllCall must have prototypes equivalent to:
extern "C" __declspec(dllexport) void __stdcall fn(LPCTSTR szParam );
C or C++ DLL functions called by the second form of DllCall must have prototypes equivalent to:
extern "C" __declspec(dllexport) dword __stdcall fn(LPCTSTR szParam );
C or C++ DLL functions called by the third form of DllCall must have prototypes equivalent to:
extern "C" __declspec(dllexport) void __stdcall fn(LPCTSTR szParam , BYTE *pBuffer,
int cMax);
Syntax
DllCall "libName", "function", "argString"
integerVariable& = DllCall ("libName", "function", "argString")
stringVariable$ = DllCall$ ("libName", "function", "argString", "maxStringLength")
Argument Description
libName The name of the .DLL file to be called. The DllCall command works even if the
dynamic-link file does not have a .DLL extension. The value can be an
expression.

function The name or number of the .DLL file function to call. If a number is used, do
not enclose the value in quotation marks. The value cannot be an expression.
argString The string containing the data to be passed to the dynamic-link function. The
value can be an expression. This argument is passed as the first (or only)
argument to the DLL function.
maxStringLengt
h
Return Value Description
integerVariable
&
278
Maximum length of the string that the DLL can return as stringVariable.
Dragon NaturallySpeaking uses this argument to reserve space for the string
returned by the DLL call and passes it as the third argument to the DLL
function. The value can be an expression.
The Dll function must return an integer. DllCall sets integerVariable& to this
value.
stringVariable$ The Dll function must return a string by reference. DllCall sets
stringVariable$ to the string value.
Notes
Improper use of the DllCall command can cause applications to hang and under some circumstances may
require you to restart the computer. In particular, you should make sure that the form of the call and the
argument string match the DLL function that you are calling.
You can use the DllCall command to add application extensions to the Dragon NaturallySpeaking scripting
language.
As a general rule, do not call Windows system .DLL files. However, you can write a DLL with functions that
convert the contents of the stringArg from a single string into the appropriate arguments for a Windows
DLL call and then make the required Windows calls.
This command loads and releases the DLL each time you use it. If you make frequent DLLCalls to the same
DLL, you can have another process load the DLL (and not unload it) to ensure that the DLL stays in
memory.
DragToPoint
Positions the pointer in the last RememberPoint position, and then holds the mouse button and moves the mouse
to the current pointer position.
Syntax
DragToPoint [buttons]
Argument Description
buttons A value indicating which button is to be pressed. To press multiple mouse buttons
simultaneously, add the values for each button to be pressed.
1 (default) left button (button 1)
2 right button (button 2)

Example
279
4 third (middle) button
This instruction positions the mouse pointer in the last RememberPoint location, presses the right mouse button,
and then drags the pointer to the current pointer position.
Notes
DragToPoint 2
DragtoPoint will have no effect if the RememberPoint command has not been used earlier in the script.
This command does not work if you hold down any modifier keys (SHIFT, CTRL, ALT) when you run it.
The DragToPoint command works only in applications that support dragging.
GetState
Returns the name of the active Structured State. The state of the commands are specified during their creation, so
that at runtime, the groups of commands may be activated or deactivated using the SetState scripting command
or the ActiveState property of the DgnEngineControl object in the MyCommands Advanced Scripting editor.
Syntax
GetState() As String
The GetState function returns the string containing the name of the active state. If there is no state active, the
returned value is an empty string.
GoToSleep
Activates sleep mode and the voice commands available for this state. The sleep mode vocabulary typically
includes only the Wake Up command.
Syntax
GoToSleep
Arguments
This command does not have any arguments.
HeardWord
Causes Dragon NaturallySpeaking to behave as if the specified word, word sequence, or voice command were
received by the recognizer. You can use HeardWord to create a command that executes a series of other
commands or that has the same function as an existing command but a different name.

Syntax
HeardWord "word1" [, "word2", . . .]
Argument Description
word A single word in the active vocabulary or a single item in a command list. A list
item can contain multiple words. This argument is case-sensitive.
Example 1
280
Up to eight word values can be specified, separated by commas. A series of word
values is recognized as a single continuous phrase.
This example types a closing remark, in bold type, at the end of a Dragon NaturallySpeaking document.
HeardWord "go", "to", "bottom"
HeardWord "set", "font", "bold"
Wait 1
SendDragonKeys "{Enter 2}" + "This document was dictated using Dragon
NaturallySpeaking."
Example 2
This example automates the task of copying text between windows.
Notes
HeardWord "copy", "all", "to", "clipboard"
HeardWord "switch", "to", "previous", "window"
HeardWord "paste", "that"
• If a word has different written and spoken forms, use the written form for the word value. If a word in a list
has different written and spoken forms, use the entire list entry.
• Use a single backslash before dictation commands that do not have a written form. For example, use
HeardWord "\No-Caps". To see the words that need this treatment, open the Vocabulary Editor and scroll to
the top.
• If a dictation vocabulary word (such as "Academy Awards") consists of more than one dictionary word, put
the vocabulary word in a single argument.
HTMLHelp
Calls the Microsoft HTML Help API. This command enables you to display HTML Help and close HTML Help windows.
For more information on the HTML Help API, see the Microsoft HTML Help documentation.
Syntax
The following sections provide the syntax for each supported HTML Help API commands and describe the
command's function. They use the following common parameter names:
Parameter Description
helpFile The name of the complied HTML Help file to open, for example, dragon_enx.chm. If
you do not specify a full path, Dragon NaturallySpeaking looks in the currently

281
active Dragon NaturallySpeaking Help folder. If the file is not found there, the
normal HTML Help file search rules apply.
topic The specific HTML topic to display. If the compiled help uses subdirectories, this
parameter must include the subdirectory. For example, this topic is
scrptref/htmlhelp.htm. Note that the identifier uses a forward slash (/).
window The name of the window in which to display the HTML Help, for example, main. This
parameter is always optional.
HH_DISPLAY_TOPIC
HTMLHelp "helpFile[>window]", "HH_DISPLAY_TOPIC", "topic"
Opens the specified topic.
HH_DISPLAY_TOC
HTMLHelp "helpFile[::/topic][>window]", "HH_DISPLAY_TOC"
Displays the Table of Contents navigation pane and opens the specified topic, if any.
HH_DISPLAY_INDEX
HTMLHelp "helpFile[::/topic][>window]", "HH_DISPLAY_INDEX", "[indexSearchText]"
Displays the Index navigation pane and enters the indexSearchText string, if any, in the keyword field.
HH_HELP_CONTEXT
HTMLHelp "helpFile[>window]", "HH_HELP_CONTEXT", "ContextId"
Displays the Help topic for the specified contextId in the specified window. The contextId must be the numeric ID
in the [MAP] section of the Help project (.hhp) file for the topic to display.
HH_CLOSE_ALL
HTMLHelp "", "HH_CLOSE_ALL"
Closes all HTML Help Windows opened by this program. The first argument must be an empty pair of double
quotes.
Examples
HH_DISPLAY_TOC
This instruction opens dragon_enx.chm in the default window, displays the Contents tab in the navigation pane,
and displays the htmlhelp.htm topic (this topic) in the topic pane.
HTMLHelp "dragon_enx.chm::/scrptref/htmlhelp.htm, "HH_DISPLAY_TOC"
HH_HELP_CONTEXT
This instruction opens MyProg.chm in a Help window named "HiddenNav" and displays the topic with the context
ID 133096 (Hex 207E8).
Notes
HTMLHelp "C:\\MyProg\Help\MyProg.chm>HiddenNav", "HH_HELP_CONTEXT", "133096"
• Dragon NaturallySpeaking does not get error returns from the HTML Help engine. As a result, it cannot
display any messages when an HTML Help error occurs.
• If the HTML Help file name does not use an absolute path, The HTMLHelp command first checks in the Dragon
NaturallySpeaking Help directory for the requested help file. If the file is not found, the he normal HTML Help
file search rules apply.

MenuCancel
Cancels the active menu and any parent menus.
Syntax
MenuCancel
Arguments
This command does not have any arguments.
Note
The MenuCancel command is seldom needed in an application-specific command. Application-specific commands
are not recognized when Windows is in a special mode such as when a menu is active or while a window is being
moved or sized.
MenuPick
Selects the specified menu or menu item, visible in the active window, by executing the menu's access keys.
Syntax
MenuPick "menuItem"
Argument Description
menuItem The name (as displayed in the menu) of the menu or menu item to open. This value
is case-sensitive.
Example
This example displays the File menu and then selects the Save As menu item.
Notes
282
MenuPick "File"
Wait 1
MenuPick "Save As"
If the menu name contains an ellipsis, do not include it in the menuItem value.
You may need to insert a Wait command between consecutive MenuPick commands to ensure that the first
menu appears before selecting one of its entries.
MouseGrid
Opens or resizes MouseGrid, a utility for positioning the mouse pointer.
Syntax

MouseGrid [state[, gridbox]]
Argument Description
state A value indicating whether MouseGrid is sized relative to the screen or the active
window.
283
1
(default)
Open MouseGrid relative to the screen or resize an open MouseGrid. If
no gridbox value is specified, restore MouseGrid it to its previous size
or to fit the screen.
2 Open MouseGrid relative to the active window or resize an open
MouseGrid. If no gridbox value is specified, restore MouseGrid it to its
previous size or to fit the screen.
0 Turn MouseGrid off (or leave it off).
gridbox A value indicating the numbered area of the screen, window, or open MouseGrid
to which MouseGrid is to be sized, as follows: (The value 0 undoes the last
MouseGrid action.)
Example
1 2 3
4 5 6
7 8 9
This example opens or resizes MouseGrid to fit in the upper-left corner of the active window.
Note
MouseGrid 2,1
If MouseGrid reaches a point in which it would become unreadable if further resized, it moves, rather than resizes
to, the specified gridbox value.
MsgBoxConfirm
Displays a standard Windows message box with the specified attributes.
Syntax
MsgBoxConfirm "msg", type, "title"
Argument Description
msg The text to be displayed in the message box. Up to 1024 characters can be
displayed. Text wraps automatically.
type A value indicating which buttons and which symbol appear in the message box,
and which button is the default. The value is the sum of selected values from the
following three groups:

284
16 critical symbol (stop sign)
32 warning query symbol (question mark). The Microsoft Windows Interface
Guidelines for Software Design discourages using this icon.
48 warning symbol (exclamation mark)
64 information symbol (lowercase i)
+
0 OK button
1 OK and Cancel buttons
4 Yes and No buttons
5 Retry and Cancel buttons
+
0 first button is the default
256 second button is the default
title The text to be displayed in the message box title bar.
Example
This instruction displays a message box with a warning symbol and Yes and No buttons. The first button, "Yes", is
the default. (48 + 4 + 0 = 52)
Notes
MsgBoxConfirm "Do you want to save changes?", 52, "Warning"
• The script automatically terminates if the user selects the Cancel or No button in the message box.
• Dragon NaturallySpeaking editions through 3.01 do not support using the second button as a default.
MyCommandsActiveState
Syntax
Visual Basic
DgnEngineControl.MyCommandsActiveState As String
C++
HRESULT DgnEngineControl::get_MyCommandsActiveState( BSTR * StateName );
HRESULT DgnEngineControl::put_MyCommandsActiveState( BSTR StateName );
Description
Returns or sets active Structured State for the MyCommands, so that you can dynamically activate or deactivate
a set of commands, specific to a particular state in a window or application.

Parameters
Argument Description
StateName The name of the active MyCommands Structured State.
PlaySound
Plays the specified sound file. This command turns the microphone off while the sound plays. The next command
in the script executes when the sound file stops playing.
Syntax
PlaySound "fileName.wav"
Argument Description
fileName.wa
v
Example
285
The name of the sound file to play and, optionally, its path. If no path is specified,
the file must be in the Dragon NatuallySpeaking Program folder or in a directory
that is searched when Windows starts a program. The .wav extension is not
needed.
This example plays the standard Windows chimes sound.
PlaySound "C:\Windows\Media\Chimes.wav"
PromptValue Function
Syntax
Visual Basic
DgnEngineControl.PromptValue( Values As String, Description As String, Optional X As Long = -1,
Optional Y As Long = -1 ) As String
C++
HRESULT IDgnEngineControl::PromptValue (SAFEARRAY (BSTR)* Values, BSTR Descrription, int X, int
Y, BSTR * ChosenValue);
Description
Displays a Prompt box with a list of values from which the user can select an option. This allows you to create
scripting commands with behavior that is dependent on the user's response. While the Prompt box is active, the
user can select a value via mouse or voice.

Argument Description
Values The array of values that will be shown to the user. In order to group values, you
can use an empty string. This string appears as a separator element in the
array. The values can optionally contain a word's spoken form, separated by
backslash symbol (see example below).
Description The caption that appears on the prompt box.
X, Y Optional. Screen coordinates of the Prompt-box. If you do not supply these
parameters, the Prompt-box will try to determine the most appropriate
coordinates, basing on the current caret position.
ChosenValue The return value; this is either the value selected by the user, or an empty
string if the user dismissed the prompt box without making a selection.
To access PromptValue, use the EngineControl object. EngineControl.PromptValue returns a string that contains
the value chosen by the user, or an empty string if the Prompt-box was dismissed.
Example
....
Dim Values(7) As String
'Build a list of commands to display in the prompt dialog
Values (0) = "milk"
Values (1) = "cream"
Values (2) = "eggs"
Values (3) = "butter"
Values (4) = "yogurt"
Values (5) = "cheese"
Values (6) = "chicken pot pie ingredients"
Values (7) = "next"
'set state to null before displaying prompt dialog
SetState ""
PROMPT_LIST:
Dim item As String
item = EngineControl.PromptValue (Values(), "Available Dairy")
....
RememberPoint
Records the current mouse pointer position. You must use this command to record a starting point position before
you can use a DragToPoint command.
Syntax
RememberPoint
Arguments
This command does not have any arguments.
286

RunScriptFile
Runs a Dragon NaturallySpeaking script contained in the specified file. The script file can contain only valid Dragon
NaturallySpeaking scripting commands.
Syntax
RunScriptFile "fileName"
Argument Description
fileName The name of the file containing the Dragon NaturallySpeaking script to be run. The
file must be in ANSI text format.
Example
287
If no path is specified, the file must be in the Dragon NatuallySpeaking Program
folder or in a directory that is searched when Windows starts a program.
This example runs a script contained in a file named Automate.txt.
RunScriptFile "Automate.txt"
SendDragonKeys
Sends keystrokes to the active window. If SendDragonKeys fails to send the specified keystrokes, try using
SendSystemKeys.
Syntax
SendDragonKeys "type this"
Argument Description
type this The keystrokes to be sent to the active window. Enclose the names of nonprinting
keys in braces ({ }). To specify a shift-key combination, enclose the modifier key
name (such as Alt), a plus sign (+), and the shifted key in braces. To repeat a
keystroke or key combination, enclose the key name, a space, and the number of
repetiitions in braces.
Example 1
This instruction sends three CTRL+RIGHT keystrokes to the active window.
SendDragonKeys "{Ctrl+Right 3}"
Example 2
This example carries out the Set Font command by sending the Font dialog box access keys and the value
of the list variable ListVAR1 (the keystrokes that set the font to the spoken face). Plus signs are used to
concatenate the keystroke strings and the variable.
SendDragonKeys "{Alt+o}f{Alt+f}"+ListVAR1+"{Enter}"

Notes
• Scripting commands from Dragon NaturallySpeaking version 5 that use the Dragon List Variables will only
function when the .dvc file is imported. You cannot create new commands using these old Dragon List
Variables.
• Sending uppercase characters is equivalent to sending SHIFT plus the character. For example, A and
{Shift+a} are equivalent.
• Do not include spaces between the names of simultaneously pressed keys, such as Alt+Tab.
• Any modifier keys (SHIFT, CTRL, ALT) pressed while the SendDragonKeys command executes do not affect
the command action.
• You should test the use of SendDragonKeys under varying conditions to avoid unpredictable results.
• Use a DdeExecute instruction, rather than SendDragonKeys, if you cannot be sure a key sequence always
produces the same result.
• You can use 0 to indicate zero repetitions of a key. This feature is useful for scripts where a keystroke may
be used 0 or more times, depending upon a variable value.
SendSystemKeys
Sends keystrokes to the Windows operating system. Use this command only when SendKeys fails to perform. You
can use SendSystemKeys to send key combinations such as {Ctrl+Esc}, {Alt+Esc}, and {Alt+Tab}.
Syntax
SendSystemKeys "keystroke text" [, speed]
Argument Description
keystroke
text
288
The keystrokes to be sent to the Windows operating system. Enclose the names of
nonprinting keys in braces ({ }).
speed A value between 1 and 32767 indicating the keystroke speed. The default value is
100; 200 is twice as fast as the default.
Example
This instruction executes the "Switch to Next Window" command.
Notes
SendSystemKeys "{Alt+Esc}"
• Do not include spaces between the names of simultaneously-pressed keys, such as Alt+Tab.
• Any modifier keys (SHIFT, CTRL, ALT) pressed while the SendSystemKeys command executes affect the
command action.
• The SendSystemKeys command sends keystrokes more slowly than the SendKeys command. Also, if the
system responds slowly long strings can overflow the system keyboard buffer.

SetMicrophone
Turns the microphone on or off.
Syntax
SetMicrophone [onOff]
Argument Description
onOff A value indicating the microphone state. If no value is specified, the microphone
switches to the opposite state.
Example
289
0 off
1 on
This example turns the microphone on.
Note
SetMicrophone 1
SetMicrophone is used in the Microphone Off command.
SetMousePosition
Positions the mouse pointer by using absolute or relative coordinates. You can use SetMousePosition to position
the mouse for selecting objects that do not have accelerator keys and that do not change position.
Syntax
SetMousePosition relativeTo, x[, y]
Argument Description
relativeTo A value indicating the reference point for the specified mouse pointer position.
0 Coordinates are relative to the upper-left corner of the screen.
1 Coordinates are relative to the upper-left corner of the active window.
2 Coordinates are relative to the current pointer position.
5 Coordinates are relative to the upper-left corner of the window interior (area
within the window borders).
3 The x-coordinate is one of nine mapped positions relative to the screen.
4 The x-coordinate is one of nine mapped positions relative to the active
window.
6 The x-coordinate is one of nine mapped positions relative to the window

290
interior (area within the window borders).
x A value indicating the x-coordinate for the mouse position. Value must be an
integer. If relativeTo is 1, 2, or 5, x is in pixels and positive values move the
pointer right. If relativeTo is 3, 4 or 6, x must be a number between 0 and 8
corresponding to one of nine mapped positions as follows:
8 1 5
4 0 2
7 3 6
y A value indicating the y-coordinate for the mouse position, in pixels. Value must
be an integer. Positive values move the pointer down. If the value of relativeTo is
3, 4 or 6, do not include a value for y.
Example
This instruction positions the mouse pointer relative to the upper-left corner of the active window, 300 pixels to the
right and 200 down.
Notes
SetMousePosition 1, 300, 200
• To select objects, use SetMousePosition followed by a ButtonClick command.
• Target only objects that are always in the same position.
• If the specified coordinate values would place the pointer off the screen, Dragon NaturallySpeaking displays
an error message or positions the pointer as close as possible to the targeted position.
SetNaturalText
Turns general dictation (NaturalText), on or off. This command turns on and off the ability to dictate into text
applications and fields that are not specifically supported by Dragon NaturallySpeaking. You can always dictate into
supported applications including DragonPad, Microsoft Word, Lotus Notes, and so on.
Syntax
SetNaturalText [onOff]
Argument Description
onOff A value indicating the general dictation state. If no value is specified, the ability to
dictate in all applications switches to the opposite state.
Example
0 off
1 on
This example turns general dictation on.

291
SetNaturalText 1
SetState
Activates the specified Structured State and the commands associated with it as long as their availability also
matches the foreground window. The states of the commands are specified during their creation, so that at runtime,
the groups of commands can be activated or deactivated using the SetState scripting command or the ActiveState
property of the DgnEngineControl object in the MyCommands Advanced Scripting editor.
Syntax
SetState( NewState As String )
Argument Description
NewState The name of the state to activate. If an empty string is specified, any current
active state will be deactivated.
Any previous Structured State will be deactivated together with associated commands.
ShellExecute
Loads an application. If a copy of the application is already running, it loads a new instance of the application.
Syntax
ShellExecute "commandLine"[, windowStyle[, "directory" ["applicationName"]]]
Argument Description
commandLine Specifies the executable file to run and any command line arguments. You do
not have to include the application's .exe extension. If commandLine does not
specify a full file path, the application must be in the the Dragon
NatuallySpeaking Program folder or in a directory that is searched when
Windows starts a program. You cannot use long file names or include spaces in
the executable path.
windowStyle Controls how the window appears when you activate the application. Must be
one of the following:
1, 5, or 9 default window size; active (default)
2 minimized window; active
3 maximized window; active
4 or 8 default window size; not active
6 or 7 minimized window; not active
directory Assigns a working directory for the application. The default is the directory

applicationNam
e
Example
292
that contains the executable file.
Lets you name the application. This name is used by the AppBringUp and
AppSwapWith commands. The application name must be unique. ShellExecute
reports an error if the name is already in use.
This instruction starts an instance of WordPad with its window maximized and sets the working directory to
C:\DOCS. This instance of WordPad has the name "letter", and you can now use the AppBringUp and AppSwapWith
scripting commands with the argument "letter" to activate the window while it is open.
ShellExecute "WordPad", 3, "c:\docs", "letter"
TTSPlayString
Sends an instruction to the text-to-speech utility. The microphone is turned off while the command executes. The
user can stop output by pressing the ESC key or turning on the microphone.
Syntax
TTSPlayString ["text" [, "switches"]]
Argument Description
text The text string to be read back by using the text-to-speech utility. If no text is
included, or an empty string ("") is sent, the command reads the contents of the
Clipboard.
switches A series of values specifying the speed and volume of text-to-speech output.
Example 1
Switches are optional and may override text-to-speech preferences set by the
user. Switches can be used in any order.
/s A number between 0 and 255 indicating the playback speed. The default
value is 127.
/l A number between 0 and 255 indicating the playback volume relative to the
current volume control setting. The default value, 255, reads text at a
volume equal to this volume setting.
This instruction reads the specified text at a moderate speed and at a volume equal to the current output volume.
TTSPlayString "Click the microphone button to start", "/s80 /l255"
Example 2
This instruction reads a word-processor document by copying it to the Clipboard and sending a TTSPlayString
command. Playback is at a slow speed.
HeardWord "copy", "all", "to", "clipboard"
TTSPlayString "", "/s90"

Wait
Causes the script to pause for the specified number of milliseconds before executing the next command.
Note
This command works only for legacy Dragon NaturallySpeaking version 5 commands that have been imported into
version 8. It will not work in commands that you create using the MyCommands editor. If you are creating a
command from the MyCommands editor, use the Wait Instruction command.
Syntax
Wait milliseconds
Argument Description
millisecond
s
Example
293
A value from 0 to 32,767 indicating the number of milliseconds to wait.
This example causes the script to pause for 100 milliseconds (one tenth of a second) before continuing.
Notes
Wait 100
• You can use the Wait command to ensure that an application has enough time to load before the script
continues.
• To pause a script for longer than 32,767 milliseconds (32 seconds), use a loop to repeat the Wait command.
• In many cases, this command stops recognition. However, recognition does continue where it is appropriate,
for example, when the previous command is a MsgBoxConfirm command (to allow spoken responses to the
message box).
WaitForWindow
The WaitFor Window command suspends execution of the script until a desired window appears in the foreground.
Note
This command works only for legacy Dragon NaturallySpeaking version 5 commands that have been imported into
version 8. It will not work in commands that you create using the MyCommands editor.
Syntax
WaitForWindow caption [, windowClass [, timeout ] ]
Argument Description
caption A text string to match against the window caption. The string may (and often will)
include the asterisk (*) character as a wild-card to match against variable parts of

windowClas
s
294
the window caption. If parts of the actual window caption are guaranteed to be
unpredictable, you MUST use an * wild-card to get a successful match.
The caption may also be an empty string "", to indicate that the caption does not
matter.
A text string which, when not empty (""), must exactly match (case-sensitive) the
window class name of the window you are looking for. The window class name is
usually obtainable only through programmer utilities like "Spy".
timeout The length of time, in milliseconds, to wait for the window to appear. If no
matching window appears by then, a timeout error is displayed, and the script
stops without executing any subsequent commands following WaitForWindow. If
not specified, defaults to 10 seconds.
Examples
In the following example the * in the caption is an instruction to ignore "Document1".
AppBringUp "(correct path here)winword.exe"
WaitForWindow "*Microsoft Word"
SendKeys "this text will appear in the Word document, not the splash screen"
The following example waits for Word's main window by class name.
AppBringUp "(correct path here)winword.exe"
WaitForWindow "", "OpusApp"
SendKeys "this text will appear in the Word document, not the splash screen"
The following example starts Outlook, waits as long as 30 seconds in case the network is slow, and then types
Alt+n to create a new E-mail.
AppBringUp "(correct path)outlook.exe"
WaitForWindow "*Microsoft Outlook", "", 30000
SendSystemKeys "{Alt+n}"
WakeUp
Exits sleep mode and activates the microphone.
Syntax
WakeUp
Arguments
This command does not have any arguments.
Note
WakeUp is used in the Wake Up command.

WinHelp
Activates the Windows Help application and specified Help (.HLP) file, and then displays the specified window or
topic.
Syntax
WinHelp "helpFile", cmd, data
Argument Description
helpFile The name of the Help (.HLP) file to activate. If no path is specified, Dragon
NaturallySpeaking looks for the file in the Dragon NaturallySpeaking Help folder.
If the file is not found there, the normal Windows Help file search rules apply. The
Help file name can be followed by the name of the Help system window in which to
display the help, in the form ">WindowName".
cmd A value identifying the Help topic to display.
295
1 Display the Help topic identified by the data argument.
2 Close the Windows Help application.
3 Display the default Help Contents topic. This topic is defined either in the
Help project (.hpj) file or by a previous WinHelp command with a cmd value
of 5. If there is no Contents topic, WinHelp displays the first topic in the Help
file.
4 Display Help for Windows Help.
5 Set the topic specified in the data argument as the Help Contents topic. Does
not display the Help file.
8 Display in a popup window the Help topic identified by the data argument.
9 Switch to the specified Help file. Open it with the first topic if the file is not
already open. (Useful if another Help file has the focus.)
11 Display the Help Topics dialog box. The tab used most recently is displayed.
data Identifies the Help topic to open. This value must be the decimal number value of
a Help context identifier assigned to a topic ID in the [MAP] section of the .hpj file.
This value is required if the cmd value is 1, 5, or 8.
Example
This instruction opens Myapp.hlp in a Help window named "main" and displays the topic with the context ID
133096 (Hex 207E8).
WinHelp "C:\Program Files\Myapp\Myapp.hlp>main", 1, 133096
Key names for SendDragonKeys
This table lists the names of nonprinting keys and the codes to use in these Advanced Scripting commands:
SendDragonKeys and SendSystemKeys.

Key Key Code
ALT {Alt}
BACKSPACE {BackSpace}
BREAK {Break}
CAPS LOCK {CapsLock}
CENTER {Center}
CONTROL {Ctrl}
DEL {Del}
DOWN ARROW {Down}
END {End}
ENTER {Enter}
ESC {Esc}
HELP {F1}
HOME {Home}
INS {Ins}
LEFT ARROW {Left}
NUM LOCK {NumLock} (extended keyboards only)
PAGE DOWN {PgDn}
PAGE UP {PgUp}
PAUSE {Pause}
PRINT SCREEN {Prtsc}
RIGHT ARROW {Right}
SCROLL LOCK {ScrollLock}
SHIFT {Shift}
SPACE {Space}
SYS REQ {SysReq}
TAB {Tab}
UP ARROW {Up}
F1, F2,
F3,...F16
Numeric keypad
296
{F1}, {F2}, {F3},...{F16}
{NumKey/}, {NumKey*}, {NumKey-}{NumKey+}
{NumKey0},...{NumKey9}
{NumKey.}, {NumKeyEnter}
(These codes are handled as if NUM LOCK were on)

Extended Keys
These keystrokes are generated by the extended keypad keys that are available on most keyboards. Most
applications treat them the same as the corresponding keystrokes that do not have the Ext prefix (listed in the
preceding table).
{ExtDel} {ExtDown} {ExtEnd} {ExtHome} {ExtIns} {ExtLeft} {ExtPgDn} {ExtPgUp} {ExtRight} {ExtUp}
Notes
• Always precede the BREAK key with the CONTROL key.
• CENTER is the non-NUM LOCK version of NUM KEY 5.
• If you need to specify one of two ALT, CTRL, or SHIFT keys, use {LeftAlt} or {RightAlt}, {LeftCtrl} or
{RightCtrl}, and {LeftShift} or {RightShift}.
Windows shortcut keys
This table lists some standard Windows shortcut keys you can use in keystroke commands and script commands.
Keystrokes Action
{Ctrl+Tab} or {Ctrl+PgDn} Switch to the next tab in a dialog box.
{Ctrl+Shift+Tab} or
{Ctrl+PgUp}
Switch to the previous tab in a dialog box.
{Tab} Move to the next option or group of option buttons.
{Shift+Tab} Move to the previous option or group of option buttons.
Arrow keys Move within the active list box or group of option buttons.
{Space} Select the active command button or check box.
Letter keys Move to the next item beginning with that letter in an active list
box.
{Alt+letter key} Select the item with that underlined letter.
{Alt+Down} Display a drop-down list box.
{Esc} Close a drop-down list box.
{Enter} Choose the default command button.
{Esc} Cancel the command and close the dialog box.
Error messages for scripts
Scripts may not run properly in every situation. Some scripts depend on certain options and settings. If a script
cannot run, it displays an error message.
If a command you have created produces an error or does nothing, open the command by using the Command
Browser and check the following information:
• If the command is application-specific, is the correct window or dialog box active when you say the
command? If yes, does the title of the active window match the title specified?
• If the command includes a list, do the list values match what you said?
• If the command includes keystrokes, are braces included around keystrokes? Are the correct key codes
used?
• If the command runs a script, do the script commands follow proper syntax? Are quotation marks used to
enclose strings, including keystroke strings?
297

• If the command name contains punctuation (for example, "What Time Is It?"), did you verbalize the
punctuation?
Structured Commands
About Structured Commands
Dragon NaturallySpeaking Professional, Medical and Legal include an extension to text and graphics commands
that let you to set the values of variables in text blocks based on voice input.
You can create simple text and graphics commands with variables in the My Commands Editor dialog box without
having to do extensive programming in Microsoft® VBA.
Application states
Structured commands let you control the action of a command based on the existence of a state in the application.
For example, when you assign a state to each field in a form, the same command can perform different actions
depending on which field is activated.
You can use Advanced Scripting methods to control the states within structured commands or to set the initial state
from a non-structured command. You can also create structured commands that prompt the user to select values
from a predefined list.
When the user speaks a command, the user is presented with a list of pre-defined values for the command. Once
the user selects a value, the value is inserted into the correct location in the macro.
Samples
Dragon NaturallySpeaking includes several sample text and graphics commands with variables and sample
structured commands. You can import the samples into Dragon NaturallySpeaking to use them as templates for
your own commands. The sample commands are fully commented.
For more information, see:
Structured Commands Samples
298
Importing Sample Commands
Methods
For more information on the methods used by the sample commands, refer to the following:
Global Methods
SetState
GetState
EngineControl Methods
MyCommandsActiveState
PromptValue
Structured Commands Samples
Dragon NaturallySpeaking includes several sample text and graphics commands with variables and sample
structured commands. You can import the samples into Dragon NaturallySpeaking to use them as templates for

your own commands. The sample commands are fully commented.
Sample location
The sample commands are installed in:
\Documents and Settings\All Users\Application
Data\Nuance\NaturallySpeaking9\Data\Enx\samplecommands
A shortcut to this directory is available on the Windows Start menu. To open this directory, click Start, point to
Programs, then point to Dragon NaturallySpeaking 8, and click Sample Commands.
Importing Sample Commands
You can import the samples into Dragon NaturallySpeaking to use them as templates for your own commands. For
information, see Importing Sample Commands
Samples
The following samples are included with Dragon NaturallySpeaking:
299
GroceryListSample_DragonPad
GroceryListSample_DragonPad.xml contains Advanced Scripting commands that simulate an on-line grocery
order form in DragonPad. It demonstrates how to set and change command states, activating and deactivating
various state structured commands, and how to use the command prompt. The voice command "Prepare
Grocery List" causes the first section of a grocery list to display in DragonPad and sets a command state. Each
section of the grocery list is designed to have a separate state. The voice command "What's Available" will
prompt the user with a set of grocery list commands that are active in the given section.
GroceryListSample_WordPad
GroceryListSample_WordPad.xml contains Advanced Scripting commands similar to those of
GroceryListSample_DragonPad.xml. It demonstrates how to set and change command states and to use the
command prompt in WordPad and uses a different coding style. The same voice command "Prepare Grocery
List" will start the grocery list in WordPad, activate the initial grocery list state, and prompt the user with a set
of grocery list commands that are active in the given state. To read more about this sample and its commands,
refer to the code comments in the XML file.
SampleBoilerPlate_ColonCancer
SampleBoilerPlate_ColonCancer.xml contains Advanced Scripting commands that demonstrate how to use
structured commands and the command prompt for boilerplate text. This sample is modeled after a colon
cancer checklist and is designed to work in Microsoft Word 2003. The voice command "Colon Cancer Checklist"
causes the boilerplate text to display and takes the user, field by field, through the checklist.
SampleBoilerPlate_EndoBiopsy
SampleBoilerPlate_EndoBiopsy.xml contains a single Advanced Scripting macro that demonstrates how to set
up boilerplate text and use the command prompt to guide users in filling the boilerplate text without using states.
This sample is modeled after an endoscopic biopsy report and is designed to work in Microsoft Word 2003. The
voice command "Prepare Endoscopic Biopsy Gross Template" causes the boilerplate text to display and takes
the user, field by field, through the report.
SampleTGV_Restaurant
SampleTGV_Restaurant.xml contains Text and Graphics and Advanced Scripting commands that are used in
DragonPad to simulate an ordering system for a Chinese and Japanese restaurant. This sample demonstrates
how to set states for structured commands as well as how the same commands can be used to produce different
results in different states. The voice command "Chinese Restaurant" or "Japanese Restaurant" starts the
ordering system and activates the structured commands created for the given state. The voice command "Exit
Ordering System" ends the ordering session.

300
SetStateSample
SetStateSample.xml contains simple Text and Graphics commands that demonstrate how to use variables and
text formats and Advanced Scripting commands to set and unset a command state. This sample is designed to
work in DragonPad with the initial command "Sample Set State". When the command executes, a command
state is set for DragonPad and a simple exchange of greetings is simulated between the user and the system.
The user speaks the greeting, e.g. "Good Morning", and the system responds in bold red text. When the user
says "Good-bye", the exchange is terminated and the command state is unset.
SampleInjuryReport
SampleInjuryReport.xml together with SampleInjuryReport.dot demonstrates how structured commands and
Microsoft Word templates can be used together to create a voice-enabled form filling environment. The
template is a mock injury report with several text and checkbox fields can be filled using the commands included
in the XML file. You start a form filling session with the voice command "Edit Report" spoken in a new document
based on the sample template. Both the template and the commands are designed to work in Microsoft Word
2003.
Importing Structured Commands
You can import existing structured commands, such as the Structured Commands Samples, into Dragon
NaturallySpeaking to use as templates for your own commands. Use the following procedure to import the sample
structured commands that are supplied with Dragon NaturallySpeaking:
To import the sample structured commands:
1. On the DragonBar Tools menu, click Command Browser to open the Command Browser window.
2. Click the Manage button on the Command Browser toolbar.
3. In the Manage area, click the Import button, and in the Import Commands window choose MyCommands
XML files from the Files of type list.
4. Use the Import Commands window to browse to the Documents and Settings\All Users\Application
Data\Nuance\NaturallySpeaking9\Data\Enx\samplecommands directory.
5. Select one of the sample .XML files (for example, sampletgv_restaurant.xml) and click Open.
6. Click OK on the Import Commands validation dialog box and then click Import on the Import Commands
window to import the commands contained in the file.
Note: The syntax of XML command files is defined by a document type definition (DTD) file that resides on the
Nuance web site. When you import an XML command file, the application gives you the option of validating the
syntax of the XML file against the DTD. The validation step is useful if you receive a XML command file from
another person and want to check it for syntax errors prior to importing it.
Click OK on the success message and return to the Manage area of the Command Browser.
To examine the sample code
Open the Command Browser and click the Manage button.
Expand and select the appropriate item (for example, “ Menu”)
Click the To Script button and then click the Edit button.
The My Commands Editor dialog box opens with the command you selected entered into it. You can examine and
modify the command with the My Commands Editor.